Local-first Design

zetl follows five local-first principles that make it safe to use with your knowledge base.

(given read-only-vault-access)
(given no-network-calls)
(given local-first-documented)

Five principles

1. Read-only

zetl only reads Markdown and .spl files. It never writes to, renames, or deletes vault content. The only exception is the inline edit feature in Serve Command, which writes only when the user explicitly saves.

2. Disposable cache

The .zetl/ directory contains only derived data (the Link Graph index and Reasoning Engine theory cache). Deleting it loses nothing — zetl index regenerates it. Add .zetl/ to your .gitignore.

3. No network

zetl makes no network calls. Everything runs locally. The Serve Command listens on localhost only. Future distributed sync (see Distributed Sync Future) would be opt-in via a separate sidecar.

4. No lock-in

Your vault is plain Markdown with optional concepts/Spindle Lisp blocks. Removing zetl leaves your files untouched. The .zetl/ directory can be deleted without consequence.

5. Cross-tool compatibility

zetl works alongside Obsidian, Logseq, Foam, Dendron, or any editor. Multiple tools can read the same vault simultaneously without conflict. See Compatibility.

Why this matters

Users trust zetl with their knowledge base — years of accumulated notes. A tool that might corrupt, reformat, or accidentally delete files would be a non-starter. Read-only access removes that risk entirely.

See also: decisions/Local-first Design, Compatibility, architecture/Cache

Backlinks

Linked Pages

Cache

Cache

zetl uses two-tier incremental caching for both the Link Graph and the Reasoning Engine’s theory.

(given mtime-based-cache)
(given incremental-rebuild)
(given disposable-cache)

How it works

The cache lives in .zetl/ at the vault root:

index.json — serialised link graph with per-file Merkle Tree roots
theory.json — serialised reasoning theory, conclusions, and grounding data

Two-tier invalidation

Tier 1 (mtime): If a file’s modification time hasn’t changed, skip it entirely — no I/O beyond the stat call
Tier 2 (content hash): If the mtime changed but the BLAKE3 content hash matches the cached value, skip reprocessing

This handles the common case where git checkout updates mtimes without changing content.

SPL-specific invalidation

For the theory cache, zetl uses the SPL AST hash (not content hash) to determine if re-reasoning is needed. This means:

Prose edits that don’t touch SPL → no theory rebuild
SPL reformatting (comments, whitespace) → no theory rebuild
SPL logical changes (new facts, modified rules) → theory rebuild

Compatibility

zetl works with any Markdown vault that uses [[wikilink]] syntax. It never modifies your files.

(given obsidian-compatible)
(given logseq-compatible)
(given foam-compatible)
(given dendron-compatible)

Supported tools

Tool	Status	Notes
Obsidian	Full support	Standard `[[wikilink]]` syntax, aliases, headings, block references
Logseq	Full support	Wikilinks in Markdown mode
Foam	Full support	VS Code extension using `[[wikilinks]]`
Dendron	Full support	VS Code extension with Markdown wikilinks

What zetl reads

zetl parses [[target]], [[target|alias]], [[target#heading]], [[target^block-id]], and ![[embeds]]. It identifies pages by filename (case-insensitive, .md extension stripped). See concepts/Wikilinks for the full grammar.

What zetl ignores

Frontmatter (YAML between --- fences) — parsed but not treated as links
Code blocks — wikilinks inside fenced code are ignored
Comments — HTML comments are skipped

SPL is optional

concepts/Spindle Lisp embedding is entirely optional. Vaults work fine with just wikilinks — SPL adds reasoning capabilities on top. If you don’t use SPL, commands like zetl links, zetl check, and zetl tui work identically.

The `.zetl/` directory

The index and theory cache are stored in .zetl/ at the vault root. This directory is disposable — delete it any time, and zetl index rebuilds it. Add .zetl/ to your .gitignore. See architecture/Cache.

Local-first Design

Local-first Design (Decision Record)

Status: Accepted

Context

zetl operates on personal knowledge bases that may contain years of accumulated notes. Users need confidence that the tool won’t damage their data.

Decision

zetl is strictly read-only against vault files. All derived data is stored in a disposable .zetl/ directory. No network calls are made.

(given read-only-vault-access)
(given disposable-cache)

Rationale

Trust — users adopt CLI tools more readily when they can’t cause data loss
Composability — read-only access means zetl works alongside Obsidian, Logseq, Foam, Dendron, or any editor without conflict
Simplicity — no write path means no write bugs, no file locking, no corruption recovery
Disposability — the cache is derived data; losing it costs only a re-index

Implications

The architecture/Cache in .zetl/ can be gitignored and deleted freely
The Serve Command’s inline edit feature is the single exception (writes only on explicit user save)
Future distributed sync (see Distributed Sync Future) would be handled by a separate sidecar process, not by zetl itself

Relationship to concepts page

Spindle Lisp

Spindle Lisp (SPL) is a domain-specific language for expressing concepts/Defeasible Reasoning theories. zetl extracts SPL from fenced code blocks in Markdown and from standalone .spl files.

(given spl-documented)

Syntax reference

Facts

Unconditionally true propositions:

(given bird)
(given (not guilty))

Strict rules

Cannot be defeated. If the body holds, the head must hold:

(always r-penguin-is-bird penguin bird)

Defeasible rules

Can be defeated by stronger evidence. The label is optional:

Distributed Sync Future

Distributed Sync Future

Status: Proposed (not yet implemented)

Context

Users with multiple machines or collaborating teams may want to sync vaults. SPEC-004 Distributed Sync proposes a design using a Spritely Goblins sidecar communicating via OCapN (Object Capability Network).

Design overview

zetl stays pure Rust for all local operations
A Guile Scheme Goblins sidecar handles networking, capability-based access control, and sync
Communication between zetl and the sidecar uses JSON-RPC over Unix domain sockets
Files remain the source of truth — sync is delta-based with explicit merge
Capabilities (not passwords) control access via sturdyrefs

Why a sidecar?

Keeps zetl’s core free of networking dependencies
Goblins provides battle-tested capability security (OCapN/CapTP)
The sidecar is optional — zetl works fully offline without it
Aligns with decisions/Local-first Design: network is opt-in, never required

Current status

This is a future direction. No implementation exists yet. Research spikes are planned for Syrup serialization in Rust, Goblins sidecar prototyping, and conflict detection accuracy.

Deliberate gap

This page has no SPL facts — modeling the zetl reason why-not use case. Running zetl reason why-not "distributed-sync-ready" would show that no facts support this conclusion because the feature doesn’t exist yet.

Serve Command

zetl serve starts a local web server for browsing the vault in a browser.

Usage

zetl -d ./my-vault serve              # http://localhost:3000
zetl -d ./my-vault serve --port 8080

Flags

Flag	Default	Description
`--port N`	3000	Port to listen on

Features

The web UI provides:

Rendered pages — Markdown rendered to HTML with syntax highlighting
Sidebar — page list with search/filter
Backlink list — pages linking to the current page
Transclusion panel — forward-link excerpt cards with SVG bridge connectors, mirroring the View Command design
Inline editing — edit a page in the browser and save; zetl re-indexes on save

Relationship to other viewers

Viewer	Interface	Read-only?
`zetl tui`	Terminal (multi-view dashboard)	Yes
`zetl view`	Terminal (two-pane reader)	Yes
`zetl serve`	Browser (full web UI)	No (inline editing)
`zetl build`	Static HTML (deployable)	Yes

Design

The server uses the same Link Graph and architecture/Cache as all other commands. The transclusion panel implements the same Xanadu-inspired design as View Command, but with SVG bridge connectors instead of terminal graphics. See Xanadu Lineage for the design philosophy.

See also: CLI Reference, Build Command, View Command, TUI

Reasoning Engine

Reasoning Engine

The reasoning engine takes concepts/Spindle Lisp extracted by the Scanner from across the entire vault, merges it into a single theory, and computes conclusions using concepts/Defeasible Reasoning. Every conclusion carries full concepts/Provenance.

(given spindle-core-integrated)
(given four-conclusion-types)

Pipeline

Extract — the Scanner finds SPL blocks in Markdown fences and standalone .spl files
Parse — spindle-parser converts SPL text into rule objects
Provenance — source file, line number, and page name are attached to each rule and fact
Merge — all rules and facts are merged into a single vault-wide theory
Validate — check for undefined labels, duplicate definitions, broken source references
Reason — spindle-core computes conclusions using the defeasible reasoning algorithm
Annotate — each conclusion is traced back to its proof sources with grounding freshness

Conclusion types

Tag	Meaning
`+D`	Definitely provable — strict derivation, no defeating possible
`-D`	Definitely not provable
`+d`	Defeasibly provable — inferred, no active defeaters
`-d`	Defeasibly not provable — blocked or no derivation path

Theory caching

The merged theory and its conclusions are cached in .zetl/theory.json. Invalidation uses the SPL AST hash — prose-only edits don’t trigger a rebuild. See architecture/Cache and Merkle Tree.

Feature gate

The reasoning engine is compiled only when --features reason is enabled — see Feature Gates. Without it, zetl reason prints a clear error rather than failing silently.

Cross-referencing

The --with-conclusions flag on Links Command bridges the structural graph with the logical theory, showing what each linked page contributes to the vault’s conclusions.

Link Graph

zetl builds a directed graph where nodes are pages and edges are concepts/Wikilinks. The graph powers all link-based queries.

(given directed-graph)
(given multi-hop-traversal)

Data model

Node — a Markdown page, identified by its title (filename without .md, case-insensitive)
Edge — a wikilink from one page to another, with optional alias, heading, or block reference

The graph is built by the Scanner and cached by architecture/Cache for incremental re-scans.

Resolution

Page names are resolved case-insensitively. When a wikilink target like [[cache]] appears, zetl matches it to Cache.md regardless of casing. For disambiguation between pages with the same name in different directories, use path-qualified links like [[architecture/Cache]].

Queries

Command	Description
`links`	Forward links from a page, with configurable depth
`backlinks`	Pages linking to a target, with depth traversal
`path`	Shortest link path between any two pages
`export`	Full graph as JSON

These are exposed through Links Command, Path Command, and List and Export Commands. With the --with-conclusions flag, link results are cross-referenced with the Reasoning Engine to show what each linked page contributes to the vault’s logic.

Library

Built on petgraph, a Rust graph data structure library. The graph is stored as a flat adjacency list for cache-line efficiency during multi-hop traversal. See Performance.