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.

Glob-based scoping can’t express subtraction (“editor on research/** except research/private/**”) or time windows. For those, zetl reads deontic rules from SPL blocks in your vault. SPL expresses permission and prohibition with modal operators — (may X), (must X), (forbidden X) — used as the head of a normally rule:

;; In a page like 'Vault Policies.md'
(normally editor-may-edit-research
  (and (has-role ?user editor)
       (page-matches ?page "research/**")
       (not (page-matches ?page "research/private/**")))
  (may (edit ?user ?page)))

(normally editors-forbidden-billing
  (and (has-role ?user editor)
       (page-matches ?page "billing/**"))
  (forbidden (edit ?user ?page)))

Deontic rules compose with defeasible reasoning: a narrower forbidding rule can defeat a broader permitting one via (prefer editors-forbidden-billing editor-may-edit-research). You write policy as overlapping layers rather than as a flat table. Conflicts show up in zetl reason conflicts just like any other defeasible conflict. See Writing SPL for the full syntax, Running Queries for how to test rules, and the upstream Spindle SPL reference for the complete modal-operator specification.

Time-bounded access is typically encoded via temporal literals or a fact that an external hook asserts at the appropriate time:

;; A separate process (cron / on-save hook) asserts `(given during-business-hours)`
;; between 09:00 and 17:00 and retracts it otherwise.
(normally readers-may-view-internal-hours
  (and (has-role ?user reader)
       (page-matches ?page "internal/**")
       during-business-hours)
  (may (view ?user ?page)))

The `on-access-request` hook

When a user tries to do something zetl’s built-in rules forbid — view a scoped-out page, edit a read-only one — zetl can run an on-access-request hook instead of silently denying. The hook receives the user, the requested action, the target page, and the justification (a free-text field the user filled in) on stdin as JSON. It prints a decision — allow, deny, or defer — and zetl acts on that.

This is how you wire in a custom approval flow without forking zetl:

Slack approval bot: the hook posts to a channel and waits for a thumbs-up.
Auto-approve inside working hours, page an admin otherwise.
Deny but email the admin for an audit trail.

The hook is a normal zetl lifecycle hook — any executable, any language. See Lifecycle Hooks for the hook runtime and payload conventions.

Keeping it grounded

For a small team vault, three roles plus --pages glob scoping is almost always enough. Reach for SPL deontic rules when you have a real policy — HR-sensitive folders, time-bounded contractors, a reviewer who should see A and B but not C — not as a matter of architectural tidiness. Plain roles leave less room to get wrong.

Backlinks

Linked Pages

What is SPL

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

SPL is Spindle Lisp — a small Lisp-family language for writing rules. zetl extracts SPL from your vault and draws conclusions: “if a project is approved and has an owner, it’s ready to start”. This page is a gentle orientation; see Writing SPL for the syntax reference.

Why a second language at all

Most of your vault is prose — the thing humans are good at reading. But some knowledge is best expressed as a rule, not a paragraph. “Any release candidate must have a green test run and up-to-date docs” is easier to write (and check) as a rule than as a checklist you hope to follow.

SPL lets you write those rules inside your notes, alongside the prose they explain. zetl then reasons over all the SPL in the vault at once — a single combined theory — and tells you what follows.

The shape of SPL

SPL is parenthesised. Facts and rules are S-expressions:

(given docs-updated)
(given tests-pass)

(normally r-ready
  (and docs-updated tests-pass)
  release-candidate)

Reading top to bottom: two facts, then a rule named r-ready that says normally, if both facts hold, conclude release-candidate. Run reasoning and zetl will report +d release-candidate — defeasibly proved.

“Normally” is load-bearing. SPL is a defeasible logic: a conclusion can be drawn by default, and then withdrawn when stronger contrary evidence appears. See What is Defeasible Reasoning for what this means and why it matters for knowledge that isn’t strictly mathematical.

Writing SPL

Spindle Lisp (SPL) is the small language zetl reads when you ask it to reason over your vault. This page walks through the syntax by example — no formal grammar, just enough to start writing useful theories.

Requires --features reason at install. See Installation.

Where SPL goes

SPL lives in two places:

Fenced code blocks inside any Markdown file, tagged spl.
Standalone .spl files anywhere in the vault.

# Q2 Release

We're tracking the release of the next minor version here.

```spl
(given core-features-done)
(given docs-drafted)
```

zetl merges every spl block and every .spl file across the vault into one combined theory before reasoning. A fact stated on one page can feed a rule defined on another. This is the point — rules and facts can live next to the prose that motivated them.

Facts

A fact is something you assert to be true. Use (given ...):

(given project-approved)
(given has-owner)
(given budget-signed-off)

Lifecycle Hooks

Git-style scripts that run at defined points during a zetl operation. Drop an executable into .zetl/hooks/ named after a lifecycle point, and zetl invokes it with structured JSON on stdin and a handful of ZETL_* environment variables.

These are separate from the AST-level Render Pipeline Hooks — lifecycle hooks fire around the build, not inside it. Use them to publish an RSS feed after zetl build, notify a chat room on on-save, or run a schema validator on post-check.

Lifecycle points

Hook	Fires	Can abort?
`pre-build`	Before `zetl build` renders pages	Yes
`post-build`	After `zetl build` completes	No (warning on non-zero)
`post-index`	After `zetl index` completes	No
`post-check`	After `zetl check` collects diagnostics	No
`pre-serve`	Before `zetl serve` binds	Yes
`on-save`	After a page is saved via `zetl serve`	No
`on-agent`	When an agent API request arrives	No
`on-access-request`	When a user requests page access (collab mode)	No

“Can abort” means a non-zero exit cancels the parent operation; every other hook just logs a warning and continues.

What a hook receives

stdin — a JSON object with vault metadata, the page list, the link graph, and hook-specific fields (e.g. saved for on-save). If history is enabled, a history object is included.
environment — ZETL_HOOK (the lifecycle name), ZETL_VAULT_ROOT, ZETL_THEME, ZETL_VERSION, plus hook-specific vars: ZETL_OUT_DIR on build hooks, ZETL_PORT on serve hooks.
working directory — the vault root, regardless of where zetl was invoked from.
timeout — 30 seconds wall-clock. A hook that hangs is killed.

Writing a hook

Create an executable file named exactly after the lifecycle point (no extension):

# .zetl/hooks/post-build
#!/bin/bash
# Generate an RSS feed from pages with a `date:` frontmatter field.
set -euo pipefail

jq -r '
  .pages
  | map(select(.frontmatter.date))
  | sort_by(.frontmatter.date) | reverse | .[0:20]
  | map("<item><title>\(.title)</title><pubDate>\(.frontmatter.date)</pubDate></item>")
  | "<rss><channel>\(join(""))</channel></rss>"
' < /dev/stdin > "$ZETL_OUT_DIR/feed.xml"

Then mark it executable:

chmod +x .zetl/hooks/post-build

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.

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

Running Queries

Once your vault contains some SPL, zetl reason is how you ask questions of it. This page walks the everyday command surface: status, conflicts, export, and provenance.

Requires --features reason at install. See Installation.

`reason status` — the default view

zetl reason status prints every conclusion the combined theory produces, tagged with +D, -D, +d, or -d (see What is Defeasible Reasoning for what those mean).

cd ~/notes
zetl reason status

In a TTY you get a table. Piped or redirected, you get JSON — same data, machine-readable.

Filters

Status output gets long fast. A few flags keep it manageable:

Flag	Shows
`--positive`	Only `+D` and `+d` conclusions
`--negative`	Only `-D` and `-d` conclusions
`--definite`	Only `+D` and `-D` (the strict layer)
`--defeasible`	Only `+d` and `-d` (the soft layer)
`--literal "release*"`	Wildcard filter on the literal name (`*` and `?` supported)

Combine them. “What are all the things my Acme project is currently defeasibly committed to?” becomes:

zetl reason status --positive --defeasible --literal "acme*"

Installation

zetl ships prebuilt binaries for Linux, macOS, and Windows. The installer script handles platform detection, download, and wiring up the man page and shell completions. If you prefer to build from source, that path is documented below too.

Prebuilt binaries (recommended)

macOS and Linux:

curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

The script detects your OS and architecture, downloads the right tarball, installs the binary to ~/.local/bin, and generates the man page and shell completions.

Windows:

Download zetl-windows-x86_64.zip from files.anuna.io/zetl/latest, extract zetl.exe, and place it somewhere on your PATH.

Pinning to a specific version

VERSION=0.6.1 curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

Custom install location

INSTALL_DIR=/usr/local/bin curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

What is Defeasible Reasoning

A short primer on the kind of logic zetl uses when you ask it to reason over your notes. No symbols, no formal notation — just an explanation of why this flavour of logic suits knowledge work.

Requires --features reason at install. See Installation.

Classical logic: everything is final

In classical logic, facts combine and the conclusion is permanent. If you write down that every bird flies, and that Tweety is a bird, then Tweety flies. Forever. Adding new information can only produce new conclusions — it can never retract one you already made.

That rule works beautifully inside a maths textbook. It breaks almost immediately when you try to write down the actual state of a research project, a release plan, or a set of beliefs you formed over six months of reading. Real knowledge is provisional. You revise it. You hedge. You say “normally X, but not when Y”.

Defeasible logic: conclusions have strength

Defeasible reasoning lets you write rules that are normally true but can be defeated by stronger evidence. In a project-tracking vault you might write:

Normally, a release candidate is ready if core features are done, docs are written, and tests pass.
Except when there is an outstanding critical bug.

Both rules live in the theory at the same time. When zetl reasons over them, the defeater wins if its conditions hold — the release is blocked. If the bug is later fixed, the block lifts and the conclusion flips. You never rewrote the rules; you just added and removed facts.

This is exactly how thinking about ongoing work feels. “We’re on track — unless the client pushes back on the design.” “The proposal is done — except we still need a legal review.” You already reason this way. zetl just gives you a notation for it.

Access Control

The three roles

Page scoping with globs

Deontic rules with SPL

The on-access-request hook

Keeping it grounded

Related

Backlinks

The `on-access-request` hook