Invitations

New collaborators join a vault via a single-use, signed invitation token. You generate one with zetl invite (or the web UI), send the resulting link by whatever out-of-band channel you prefer, and the recipient uses it exactly once to register a passkey and pick a display name.

Generating an invite from the CLI

The minimal form takes your own username (the inviter) and the role the invitee will have:

zetl invite --as Alice --role editor

This creates the token and copies the full invitation URL to the clipboard. Paste it into Signal, email, a sticky note — whatever gets it to the recipient without a third party logging it along the way.

Three roles are available:

Role	What they can do
`reader`	View pages; no editing, no invitations.
`editor`	View and edit pages; cannot invite new users or change access.
`admin`	Full control, including issuing invitations and managing passkeys.

Scoping an invite to specific pages

By default an invite gives the recipient access to the whole vault at their role. For a contractor who should only touch one project, or a reviewer who only needs to see a single folder, use --pages with a glob:

# A reader who only sees pages under projects/website/
zetl invite --as Alice --role reader --pages "projects/website/*"

# An editor scoped to a specific topic
zetl invite --as Alice --role editor --pages "research/biology/**"

Globs match on the vault-relative path. projects/* matches direct children; projects/** matches everything underneath, recursively. For more expressive rules — “editor on everything except billing/**”, or “editor only between 9–5” — see SPL-based deontic rules in Access Control.

Custom expiry

Invitation links expire. The default is 72 hours, which is long enough for someone to find the email but short enough that a forgotten link doesn’t become a permanent back door:

# One-day window for a meeting-day onboarding
zetl invite --as Alice --role editor --expires 24h

# A week for someone who travels
zetl invite --as Alice --role reader --expires 7d

Accepted units are h (hours) and d (days). After expiry the token refuses to redeem even if it hasn’t been used.

Using the web UI instead

If the CLI isn’t handy, /_admin/invite does the same thing with a form. Admins can also see a list of outstanding invites, revoke un-redeemed ones, and check which tokens have been used. This is the easier surface for day-to-day invitations; the CLI is better for scripting and one-liners.

What’s in the token

Each invite is an Ed25519-signed blob containing the role, optional page scope, expiry, and a single-use nonce. The server refuses to redeem a token whose nonce it has already seen, so a link can’t be replayed even if someone intercepts it.

The server key that signs these tokens is the same key derived from your --server-key-seed mnemonic — see Passkeys and Accounts. If you rotate the seed, all outstanding invites become invalid.

Accepting an invite

The recipient opens the link, enters a display name, registers a passkey, and is dropped into the vault at their scoped role. They don’t need their own 12-word phrase at this point — zetl generates one and shows it to them during onboarding, to save for recovery. (They should save it. See Passkeys and Accounts.)

Revoking access

To remove a collaborator entirely, an admin deletes the user from /_admin/users. To narrow scope, issue a new, more restrictive invite and revoke the old role. There’s no separate “suspend” state in v0.5; access is either on or off.

Backlinks

Linked Pages

Capability URLs

Capability mode is zetl’s answer to: “I want to share my wiki with a dozen friends, read-only, without running a server, but I don’t want the whole internet reading it.” The output is a plain static site — hostable on any CDN, any S3 bucket, any sftp’d directory — where access is gated by a secret in the URL fragment. No accounts, no server-side auth, nothing to rotate but the URLs themselves.

If you want multi-user editing, you want Running a Team Server. Capability mode is for publishing.

The idea in one paragraph

Each page is encrypted at build time with a cohort-specific key. Invite URLs look like https://wiki.example.com/welcome.html#k=<base64-secret>. The #fragment — by design of the HTTP spec — is never sent to the server. The reader’s browser, executing a small JavaScript shim, pulls the key out of the fragment, decrypts the page locally, and verifies a vault-level Ed25519 signature so nobody can serve them a forged page. Revocation is per-cohort: you rotate the cohort’s salt and re-deploy, old URLs stop decrypting.

Formal spec: see docs/capability-mode.md in the zetl repo.

Setting up a capability site

1. Generate the keys

zetl cap genkey

This prints two secrets to stdout, exactly once:

ZETL_CAP_SECRET — the 48-byte content-encryption secret.
ZETL_CAP_SIGNING_KEY — the Ed25519 vault-signing private key.

Capture them somewhere safe (a secret store, a password manager, a sealed envelope). You’ll need ZETL_CAP_SECRET on every build and ZETL_CAP_SIGNING_KEY whenever you rotate the signing key.

Co-editing

When two people open the same page in a --collab vault, their edits merge without conflicts. Under the hood zetl uses a Peritext CRDT engine over WebSocket: every keystroke is a small op that both clients apply in the same causal order, so the document converges no matter who’s typing where. Think Google Docs, but local-first and committed to git.

What you see as a user

Open a page in the web UI. If someone else is editing it, you see their cursor as a coloured caret with their display name floating above it. Your edits and theirs interleave in real time. There’s no “save” button — everything is continuously streamed to the server.

A small idle period (a few seconds of quiet, or navigating away) triggers an auto-commit: zetl writes the page to disk and runs git commit with the author set to the person whose session made the last edits. If Alice and Bob were both editing, the commit message notes both contributors.

This means your vault’s git log is an authentic editing history. You can git blame a line and find out who wrote it. You can revert a page with git revert. The CRDT layer is an editing affordance; the source of truth is still Markdown on disk, tracked by git.

Crash recovery

Between auto-commits, in-flight edits live in a write-ahead log at .zetl/collab/wal/. If the server dies mid-edit — process killed, power cut, container restarted — the WAL is replayed on next startup so nothing is lost. You shouldn’t ever need to think about this, but it’s why zetl serve --collab can take an extra second to come up after a hard crash.

If you deploy in an ephemeral container where .zetl/collab/wal/ vanishes on redeploy, your CRDT merge state is gone. Auto-commit frequency is your backstop: most “in-flight” edits are short-lived, and anything older than a few seconds is in git already. For long-lived containers you can persist the WAL directory on a volume.

External edits still work

The server polls git every 30 seconds (tunable via --git-poll-interval on serve) for commits that landed outside the UI — a git pull in a terminal, a push from another machine, a hook that rewrote a page. Those changes show up in the editor without anyone refreshing. If you’re actively editing when an external change lands on the same page, zetl merges at the CRDT layer just as it would for a second live user.

Authorship and git

Access Control

zetl’s access model has two layers. The built-in layer — three roles plus glob-based page scoping — covers the 90% case: readers, editors, admins, optionally confined to a folder. The optional layer — SPL-based deontic rules — lets you express richer policies (“editor everywhere except billing/**”, “read access only between 9:00 and 17:00”) using the same reasoning engine that powers What is defeasible reasoning.

The three roles

Role	View	Edit	Invite	Admin UI
`reader`	yes	no	no	no
`editor`	yes	yes	no	no
`admin`	yes	yes	yes	yes

A user’s role is set on the invitation that brought them in (see Invitations) and can be changed later from /_admin/users. There’s no implicit hierarchy beyond this table — an editor isn’t a superset of admin, they’re just different.

Page scoping with globs

When you issue an invitation you can restrict which pages the recipient reaches at all:

zetl invite --as Alice --role editor --pages "research/**"

The scope is a glob against vault-relative paths. projects/* matches direct children of projects/. projects/** matches everything recursively. You can pass only one --pages at invite time; for more intricate patterns, use deontic rules below.

Pages outside the scope are invisible — not just uneditable. An out-of-scope page won’t appear in search, won’t show up in the graph, and returns 404 if requested by URL. This is a deliberate minimum-surface choice: users don’t learn about documents they can’t touch.

Deontic rules with SPL

Requires --features reason at install time. See Installation.

Passkeys and Accounts

zetl doesn’t do passwords. Instead, every collab account is backed by one or more WebAuthn passkeys — Touch ID, Face ID, Windows Hello, a YubiKey, or any FIDO2 authenticator. A 12-word BIP39 recovery phrase is the break-glass fallback, and the same phrase deterministically derives the collab server’s signing key and a git SSH key.

Why passkeys

Passwords get phished, reused, and leaked. Passkeys are bound to the origin (so a phishing site can’t steal them), require a local user gesture (touch, face, PIN), and never leave your device in usable form. For a small team vault, this is the right default: lower operational burden than password-plus-2FA, and nothing to leak in a database breach.

Registering on first login

The first time you open a collab server, you log in by display name (e.g. Alice) and then register a passkey. The browser prompts whatever authenticator is available — Touch ID on a Mac, Windows Hello on a PC, a hardware key, or a phone acting as a security key.

Subsequent logins are one tap. No username/password fields.

You can register multiple passkeys on one account — laptop Touch ID, phone Face ID, a YubiKey in a drawer. If one device dies, the others still work. Manage them from /_admin/passkeys in the web UI.

Recovery

If you lose access to every passkey — laptop stolen, phone dead, YubiKey at the bottom of a river — you recover using your 12-word phrase:

Open /auth/recovery on the server.
Enter your display name and the 12 words.
zetl issues a fresh session and deletes all your existing passkeys.
Register a new passkey on whatever device you’re on now.

Write the phrase down when you first see it. Don’t type it into a browser extension. Don’t email it to yourself. Paper in a drawer, or a line in your password manager, is the sweet spot for a small team.

Running a Team Server

zetl’s --collab flag turns zetl serve into a multi-user editing server: passkey login, real-time CRDT co-editing, per-user git commits, and scoped invitations. Everything is in-tree — there’s no feature flag to enable at install time. If you can run zetl serve, you can run a team server.

The shape of a collab vault

A collab vault is a normal Markdown vault plus a .zetl/collab/ directory:

.zetl/collab/server.key — the server’s Ed25519 signing key (for session cookies and invitations).
.zetl/collab/users.db — SQLite store for passkeys, sessions, and invitation nonces.
.zetl/collab/wal/ — write-ahead log for the CRDT engine. Survives crashes.

These files are created on first run. You never edit them by hand.

First run: bootstrap the owner

The very first time you start a collab server, you need to bootstrap an owner account. --init-owner creates one, prints a 12-word recovery phrase, and exits into the normal serve loop:

zetl -d ~/notes serve --collab --init-owner --owner-name Alice

The terminal will print something like:

Owner created: Alice
Recovery phrase (write this down — you will not see it again):

  palm  tornado  ladder  oyster  casual  umbrella
  desert  finger  enlist  brave  coconut  strong

Server listening on http://localhost:3000

Save that phrase. It’s your only way back into the account if you lose your passkey, and zetl will not show it to you a second time. Paper, password manager, encrypted notes file — pick one and commit.