zetl

Bi-directional wikilink graph CLI with defeasible reasoning for personal knowledge management.

zetl parses [[wikilinks]] from Markdown files, builds an in-memory link graph, and exposes query, validation, search, and visualization commands. Optionally, it extracts concepts/Spindle Lisp code blocks from your vault and performs concepts/Defeasible Reasoning — drawing conclusions that can be defeated by stronger evidence.

(given vault-self-documenting)
(given vault-uses-wikilinks)
(given vault-uses-spl)

Vault Map

Getting Started

Install — Rust toolchain, make install, --features reason
Quick Start — five-step tour of zetl’s core commands
Demo Vault — the included demo-vault and how to explore it
Compatibility — Obsidian, Logseq, Foam, and Dendron support

Reference

CLI Reference — global flags, exit codes, JSON-by-default
Index Command, Links Command, Path Command, Search Command
Similar Command, Check Command, Blocks Command, Diff Command
Watch Command, List and Export Commands, Stats Command
TUI, View Command, Serve Command, Build Command
Reason Commands — all eight reasoning subcommands

Architecture

architecture/Scanner — pulldown-cmark, wikilink and SPL extraction
Link Graph — petgraph DiGraph, resolution, query API
architecture/Cache — two-tier invalidation, .zetl/ schemas
architecture/SimHash — trigram hashing, Hamming distance
Merkle Tree — BLAKE3 leaves, section grounding, drift detection
Reasoning Engine — SPL pipeline: extract, parse, merge, reason, annotate
Drift Detection — implicit/explicit grounding, check --drift
architecture/Performance — NFR targets, measured baselines

Concepts

concepts/Wikilinks — syntax reference and formal grammar
concepts/Defeasible Reasoning — rule types, conclusion tags, superiority
concepts/Spindle Lisp — full SPL syntax reference and embedding guide
concepts/Provenance — what is tracked, commands, cross-referencing
concepts/SimHash — conceptual explanation of fuzzy matching
Xanadu Lineage — Ted Nelson’s transclusion vision and zetl view
Local-first Design — five principles: read-only, disposable, no network

Decisions

Specs

Spec Index — all nine specifications with status
SPEC-001 Link Graph CLI, SPEC-002 Full-Text Search
SPEC-003 Agent Ergonomics, SPEC-004 Distributed Sync
SPEC-005 Defeasible Reasoning, SPEC-006 Merkle Tree
SPEC-007 Graph Diff, SPEC-008 Watch Mode, SPEC-009 Xanadu View

Theories

SPL rules that reason across the entire vault:

theories/vault-readiness.spl — derives vault-ready-to-publish
theories/design-principles.spl — design philosophy as defeasible rules
theories/caching.spl — caching theory with intentional conflict
theories/agent-ergonomics.spl — agent-friendliness modelled as rules

; This vault reasons about its own completeness.
; Run: zetl reason explain "vault-ready-to-publish" --format natural
(normally r-self-documenting
  (and vault-self-documenting vault-uses-wikilinks vault-uses-spl)
  vault-is-self-referential)

Backlinks

Demo Vaultline 35
Spec Indexline 42

Linked Pages

SPEC-009 Xanadu View

SPEC-009: Xanadu View

Adds an interactive TUI for reading and navigating the vault with visible connections. See View Command for the CLI and Xanadu Lineage for the conceptual background.

(given spec-009-documented)

Xanadu lineage

Implements Ted Nelson’s vision of parallel pages with visible connections. The left pane shows the current note; the right pane shows context cards for linked notes; a bridge column holds color-coded connectors.

Key requirements

ID	Requirement
REQ-062	View command entry point
REQ-063	Two-pane layout
REQ-064	Wikilink anchor annotations (`[N]`)
REQ-065	Context pane excerpt cards
REQ-066	Bridge column connectors
REQ-067	Dynamic scroll tracking
REQ-068	Selected-link focus mode
REQ-069	Link navigation (Enter)
REQ-070	Backlink mode toggle (b)
REQ-071	Navigation history ([/])
REQ-072	No-index graceful fallback
REQ-073	Page-not-found fuzzy suggestion
REQ-074	Context excerpt length configuration

Architecture decisions

Xanadu View Design (ADR-016, ADR-017, ADR-018)
Uses ratatui + crossterm (same as TUI)
Color-paired anchor numbers as bridge rendering
Supports true-color, 8-color, and no-color terminals

Performance targets

Startup: <= 200ms
Scroll frame time: <= 16ms (60fps)

Layout

┌─ Main Pane ──────────┐ ┌─Bridge─┐ ┌─ Context Cards ─────┐
│ # Scanner             │ │        │ │ ┌─ [1] Link Graph ─┐ │
│                       │ │  1 ──  │ │ │ Builds a directed │ │
│ The scanner [1] is    │ │        │ │ │ graph where nodes  │ │
│ zetl's entry point    │ │  2 ──  │ │ └──────────────────-┘ │
│ for understanding a   │ │        │ │ ┌─ [2] Cache ───────┐ │
│ vault. It uses the    │ │        │ │ │ Two-tier mtime +   │ │
│ cache [2] for...      │ │        │ │ │ hash invalidation  │ │
│                       │ │        │ │ └────────────────────┘ │
└───────────────────────┘ └────────┘ └───────────────────────┘

SPEC-008 Watch Mode

SPEC-008: Watch Mode

Adds persistent file-system monitoring with graph event streaming. See Watch Command for the CLI.

(given spec-008-documented)

Overview

zetl watch starts a persistent process that monitors the vault via OS file system events, incrementally re-indexes changed files, and emits graph-level events as NDJSON on stdout. The event vocabulary mirrors the Diff Command output schema.

Key requirements

ID	Requirement
REQ-053	Watch command entry point
REQ-054	FS event monitoring
REQ-055	Debounced incremental re-index
REQ-056	Merkle tree change detection
REQ-057	NDJSON graph event stream
REQ-058	Event types (page/link/orphan/dead-link added/removed)
REQ-059	`--exec` command invocation
REQ-060	Graceful shutdown
REQ-061	Startup error handling

Design principles

Files are the source of truth
Agent-first (NDJSON on stdout, status on stderr)
Events emitted only on actual graph changes (not every file save)
Fast and disposable

Architecture decisions

ADR-013: Use notify crate for FS events
ADR-014: Inherit SPEC-006 Merkle Tree for change detection
ADR-015: NDJSON on stdout, status on stderr

Performance targets

Event latency: <= 500ms at p95
CPU idle: <= 0.5%
Memory: <= 250 MB

SPEC-007 Graph Diff

SPEC-007: Graph Diff

Adds graph-level diffing against Git history. See Diff Command for the CLI.

(given spec-007-documented)

Overview

zetl diff reconstructs the vault graph at a Git ref by re-parsing only changed files, then computes a structural diff showing what changed in the link graph. This is the only zetl command that requires Git.

Key requirements

ID	Requirement
REQ-046	Git ref baseline (`--from <ref>`)
REQ-047	Since-date baseline (`--since <date>`)
REQ-048	Default baseline (HEAD~1)
REQ-049	Structured diff output
REQ-050	Diff filter by category
REQ-051	Git unavailable error
REQ-052	Efficient reconstruction

Reconstruction algorithm

See ADR-012 Changed Files Reconstruction:

git diff --name-only identifies changed .md files
git show reads old content of each changed file
Old content parsed for wikilinks
Set differences yield the diff

Diff output

Pages added / removed
Links added / removed
Orphans gained / resolved
Dead links added / resolved

Architecture decisions

SPEC-006 Merkle Tree

SPEC-006: Merkle Tree

Introduces content-addressed Merkle trees built during indexing. Enables two-tier cache invalidation, SPL grounding, and Drift Detection. See Merkle Tree for the architecture and Blocks Command for the CLI.

(given spec-006-documented)
(given content-addressed-hashing)

The drift problem

SPL theories embedded in Markdown can drift from surrounding prose. Mtime-based caching cannot detect this — the file changed, but which part? The Merkle Tree solves this by hashing individual content blocks.

Key requirements

ID	Requirement
REQ-037	Merkle tree construction during index
REQ-038	SPL block dual hashing (content + AST)
REQ-039	Two-tier cache invalidation (mtime + content hash)
REQ-040	SPL-specific theory cache invalidation
REQ-041	Implicit section grounding
REQ-042	Explicit grounding via `(meta ... (source ...))`
REQ-043	Drift detection in `zetl check --drift`
REQ-044	Durable provenance with content hashes
REQ-045	Content block discovery (`zetl blocks`)

Content grounding model

Implicit (section-based)

Every SPL block is automatically grounded in its containing section. The grounding hash is computed from non-SPL leaves between the current heading and the next heading.

Explicit

Facts can be explicitly grounded via (meta label (source "ref")) using:

^block-id — same-file block reference
Merkle hash prefix — content-addressed reference
[[Page^block-id]] — cross-file reference

SPEC-005 Defeasible Reasoning

SPEC-005: Defeasible Reasoning

Adds the logical reasoning layer using concepts/Spindle Lisp embedded in Markdown. See Reason Commands for the CLI interface and Reasoning Engine for the architecture.

(given spec-005-documented)

Core insight

Zettelkasten notes make claims that can be formalized. SPL code blocks in Markdown express defeasible rules that zetl extracts, combines into a unified theory, and reasons over using spindle-core.

Key requirements

ID	Requirement
REQ-026	SPL extraction from Markdown
REQ-027	Theory construction with provenance
REQ-028	Vault reasoning (+D/-D/+d/-d conclusions)
REQ-029	Explanation with document provenance
REQ-030	Hypothetical reasoning (what-if)
REQ-031	Failure explanation (why-not)
REQ-032	Knowledge gap detection (require)
REQ-033	Conflict detection
REQ-034	SPL validation in check
REQ-035	Theory export
REQ-036	Cross-reference graph and theory

Eight commands

reason status — current conclusions
reason explain — proof tree with provenance
reason why-not — why something can’t be proved
reason require — abductive reasoning (missing facts)
reason what-if — hypothetical reasoning
reason conflicts — unresolved contradictions
reason export — theory export (JSON or SPL)
reason provenance — cross-referenced source tracing

Architecture decisions

ADR-005: Embed spindle-core as Rust library behind Feature Gates
ADR-006: Theory caching in .zetl/theory.json — see architecture/Cache
ADR-007: Provenance via spindle-core Meta API

Performance targets

Reasoning: <= 500ms for 10,000 rules
Memory: <= 50 MB for reasoning
Incremental extraction from cache

SPEC-004 Distributed Sync

SPEC-004: Distributed Sync

Proposes distributed vault synchronization using a Spritely Goblins sidecar. See Distributed Sync Future for the decision record.

Status: Proposed — not yet implemented.

Core insight

zetl stays pure Rust for local operations. A Guile Scheme Goblins sidecar handles networking, capability-based access control, and sync. Files remain the source of truth.

Architecture

┌─────────┐  JSON-RPC   ┌──────────────┐  OCapN/CapTP  ┌──────────┐
│  zetl   │ ──────────> │   Goblins    │ ────────────> │  Remote  │
│  (Rust) │  Unix sock  │  (Guile)     │   Tor/TCP     │  Peers   │
└─────────┘             └──────────────┘               └──────────┘

Capability model

Access controlled via sturdyrefs (cryptographic capability tokens)
Folder-based scopes: read, write, admin
Capabilities can be created, delegated, attenuated, and revoked

Sync protocol

Delta-based file transfer (not full vault sync)
Conflict detection via vector clocks
Explicit merge — never silent overwrite
Initially: conflict staging (always ask user)

User profiles

SPEC-003 Agent Ergonomics

SPEC-003: Agent Ergonomics

Documents findings from running zetl as an LLM agent would — systematically exercising every command and identifying friction points. See Agent Ergonomics for the decision record.

(given spec-003-documented)
(given agent-ergonomics-audited)

Findings

P0 — Bugs

Finding	Issue	Fix
FINDING-001	Empty search query panic	Return `{"results": []}`
FINDING-002	Plain-text errors in JSON mode	ADR-003 JSON Errors

P1 — Quality

Finding	Issue	Fix
FINDING-004	Duplicate link results	ADR-004 Link Dedup
FINDING-005	Duplicate backlink results	ADR-004 Link Dedup
FINDING-006	UTF-8 context splitting	Character-boundary-aware slicing

P2 — New capabilities

Requirement	Command	Purpose
REQ-019	`zetl list`	Page enumeration for agent discovery
REQ-020	`search --path`	Restrict search to subdirectory
REQ-021	`zetl export`	Full graph adjacency list

Design principles established

Agents consume stdout as JSON — errors must be structured
Non-zero exit codes signal failure
Page enumeration (list) is essential for agent bootstrapping
Deduplication at the output layer keeps the internal graph faithful

Impact

These fixes made zetl significantly more reliable as an agent building block. The JSON by Default philosophy, structured errors, and non-zero exit codes all trace back to this spec.

SPEC-002 Full-Text Search

SPEC-002: Full-Text Search

Adds zetl search for content search across vault Markdown files. See Search Command for usage.

(given spec-002-documented)

Motivation

The Similar Command does page-name matching, not content search. Users need to find where specific text appears in their vault.

Key requirements

ID	Requirement
REQ-013	Full-text content search
REQ-014	Body-text-only search (skip frontmatter/code by default, `--all` override)
REQ-015	Regex mode
REQ-016	Case-sensitive mode

Performance targets

Search <= 2 seconds for 10,000 files
Memory <= 50 MB above baseline

Design decision

ADR-002 Search Without Index — index-free scan chosen over inverted index for simplicity and correctness. The trade-off is acceptable because:

Most vaults have fewer than 10,000 files
Scanning is I/O-bound and fast on SSDs
No index build step or invalidation logic needed

Content filtering

SPEC-001 Link Graph CLI

SPEC-001: Link Graph CLI

The foundational specification for zetl. Defines the scanner, link graph, graph queries, SimHash fuzzy matching, cache, and CLI contracts.

(given spec-001-documented)

Scope

concepts/Wikilinks parsing (all forms: basic, alias, heading, block, embed)
Directed graph construction via Link Graph
Graph queries: forward links, backlinks, shortest path, dead links, orphans
architecture/SimHash fuzzy page name matching
architecture/Cache with mtime-based invalidation
Structured output (JSON default, table optional)

Key requirements

ID	Requirement
REQ-001	Index Markdown files, extract wikilinks
REQ-002	Build directed link graph
REQ-003	Query forward links with depth
REQ-004	Query backlinks with depth
REQ-005	Detect dead links
REQ-006	Detect orphan pages
REQ-007	Syntax validation
REQ-008	SimHash fuzzy page name search
REQ-009	Graph statistics
REQ-010	Shortest path between pages
REQ-011	Persistent cache
REQ-012	Ignore patterns (.gitignore)

Performance targets

Indexing: >= 2,000 files/sec
Query latency: <= 100ms
Memory: <= 200 MB for 50k pages
Binary size: <= 10 MB

Architecture decisions

ADR-001 Rust — language selection
Wikilink syntax follows Obsidian conventions

Design philosophy

Files are the source of truth
Cross-application compatibility (Obsidian convention)
Agent-first structured output (JSON by Default)
Fast, disposable indexing
Zero configuration

Spec Index

zetl’s design is documented in nine specifications, each covering a major feature area.

(given all-specs-documented)

Specifications

Spec	Title	Status	Primary Feature
SPEC-001 Link Graph CLI	Bi-directional Link Graph CLI	Implemented	Wikilinks, graph queries, SimHash, cache
SPEC-002 Full-Text Search	Full-Text Content Search	Implemented	`zetl search`
SPEC-003 Agent Ergonomics	Agent Ergonomics & Robustness	Implemented	JSON errors, dedup, list/export
SPEC-004 Distributed Sync	Distributed Vault Sync	Proposed	Goblins sidecar, OCapN
SPEC-005 Defeasible Reasoning	Defeasible Logic over Markdown	Implemented	`zetl reason` (8 subcommands)
SPEC-006 Merkle Tree	Content-Addressed Merkle Tree	Implemented	BLAKE3 hashing, grounding, drift
SPEC-007 Graph Diff	Git-Backed Graph Diff	Implemented	`zetl diff`
SPEC-008 Watch Mode	Vault Watch with Event Stream	Implemented	`zetl watch`
SPEC-009 Xanadu View	Xanadu-Inspired Transclusion TUI	Implemented	`zetl view`

How specs relate

SPEC-001 (foundation)
  ├── SPEC-002 (search)
  ├── SPEC-003 (agent ergonomics)
  ├── SPEC-004 (future sync)
  ├── SPEC-005 (reasoning) ──── SPEC-006 (merkle/grounding)
  ├── SPEC-007 (diff)
  ├── SPEC-008 (watch)
  └── SPEC-009 (view)

SPEC-001 defines the foundation (scanner, graph, cache, CLI). Each subsequent spec builds on it. SPEC-006 extends SPEC-005 with content-addressed grounding.

Traceability

Each spec includes requirements (REQ-), contracts (CON-), tests (TEST-), and architecture decisions (ADR-). Cross-references between specs maintain traceability.

Context

zetl needed a focused reading mode that shows connections between notes. The design question was how to render Ted Nelson’s Xanadu concept of “parallel pages with visible connections” in a terminal.

See Xanadu Lineage for the conceptual background and SPEC-009 Xanadu View for the full specification.

Key decisions

ADR-016: Use ratatui + crossterm

The TUI framework was already in use for zetl tui. Reusing it for zetl view provides consistent behavior across terminal emulators and avoids a second rendering dependency.

ADR-017: Color-paired anchor numbers

Each wikilink gets a numbered anchor glyph [N] in the main pane. The corresponding context card in the right pane shares the same color. A bridge column between the panes draws connectors linking each anchor to its card.

This is more practical in a terminal than literal connecting lines (which would require pixel-level rendering). The color pairing provides the visual association that Xanadu’s bridge connectors achieve.

ADR-018: Override SPEC-001 TUI scope exclusion

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.

Agent Ergonomics

Status: Accepted

Context

SPEC-003 Agent Ergonomics documents findings from running zetl as an LLM agent would — systematically exercising every command and checking for friction points.

Findings and fixes

P0 — Bugs

Empty search query panic — zetl search "" crashed instead of returning an empty result. Fixed to return {"results": []}.
Plain-text errors — errors were emitted as plain text even in JSON mode. Fixed with ADR-003 JSON Errors.

P1 — Quality

Duplicate results — links and backlinks returned the same page multiple times. Fixed with ADR-004 Link Dedup.
UTF-8 safety — context extraction could split multi-byte characters. Fixed with character-boundary-aware slicing.

P2 — New capabilities

zetl list — page enumeration for agent discovery workflows. See List and Export Commands.
search --path — restrict search to a subdirectory. See Search Command.
zetl export — full graph adjacency list for external consumption. See List and Export Commands.

Design principle

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

Feature Gates

The Reasoning Engine and all Reason Commands are behind a Cargo feature flag: --features reason. This keeps the default binary lean and the dependency tree small.

(given reason-feature-optional)
(given graceful-degradation)

How it works

In Cargo.toml:

[features]
default = []
reason = ["dep:spindle-core", "dep:spindle-parser"]

Building without the flag produces a binary that handles concepts/Wikilinks, graph queries, Search Command, Check Command, and the TUI — everything except reasoning.

Graceful degradation

When a user runs zetl reason on a binary built without the feature, they get a clear error message explaining how to rebuild with --features reason. This is better than a confusing “unknown command” error.

Why not always include it?

spindle-core and spindle-parser add compile time and binary size
Not every user needs concepts/Defeasible Reasoning
concepts/Spindle Lisp is a niche feature — progressive disclosure serves users better

Progressive disclosure

JSON by Default

All zetl commands emit JSON by default. Human-readable output is available via --format table (or --format natural / --format dot for reason explain).

(given json-default-output)

Why agent-first

zetl is designed to work both as a human CLI tool and as a building block for AI agents and scripts. JSON output means:

Agents can parse results without scraping tables
Structured errors include error codes, affected files, and suggested fixes (see ADR-003 JSON Errors)
Non-zero exit codes signal failure to shell scripts and CI pipelines
Output is composable with jq, fx, and other JSON tools

Human output

For interactive use, --format table renders results as aligned tables via comfy-table. The TUI and View Command provide richer interactive experiences.

Both audiences

This dual-output design means a single tool serves both audiences. An agent might run zetl reason status and parse the JSON, while a human runs zetl reason status --format table and reads the output directly.

; Serving both audiences is a design principle
(normally r-dual-audience
  (and json-default-output tui-complete seven-views)
  serves-both-audiences)

ADR-012 Changed Files Reconstruction

ADR-012: Changed-Files-Only Reconstruction

Status: Accepted

Context

When computing a graph diff, should zetl check out the full vault at the baseline ref and build a complete graph, or reconstruct only the changed portions?

Decision

Reconstruct via changed files only:

git diff --name-only identifies changed .md files
git show retrieves old content of each changed file
Old content is parsed for wikilinks
Set differences between old and current graphs yield the diff

Rationale

Scales with the size of the change, not the size of the vault
A 50-file change in a 10,000-file vault processes only those 50 files
No temporary checkout needed — works in the current working directory
Memory usage proportional to the change set, not the vault

Trade-offs

Cannot detect changes in files that were renamed (Git detects renames, but the wikilink graph doesn’t track filename history)
Requires the current index to be up to date

Performance

ADR-011 No Snapshots

ADR-011: No zetl-Managed Snapshots

Status: Accepted

Context

Diff Command needs a baseline to diff against. Should zetl maintain its own snapshot history, or delegate to Git?

Decision

zetl uses Git as the sole history backend. It does not maintain snapshot storage.

Rationale

Most vaults are already in Git repositories
Snapshot management adds significant storage and complexity
Git provides rich baseline selection: refs, tags, dates, HEAD~N
The Merkle Tree provides content-addressed change detection within a single point in time; Git provides the temporal axis

Trade-offs

zetl diff requires Git — it’s the only zetl command with this dependency
Vaults not in Git cannot use diff
Git must be installed and accessible on PATH

Mitigation

When Git is unavailable, zetl diff produces a clear error message explaining the requirement. All other commands continue to work. See SPEC-007 Graph Diff for the full specification.

ADR-004 Link Dedup

ADR-004: Default Link Deduplication

Status: Accepted

Context

A page may contain multiple wikilinks to the same target (e.g., [[Cache]] mentioned three times in a single page). Should zetl links and zetl backlinks report the target once or three times?

Discovered during the agent ergonomics audit — see Agent Ergonomics.

Decision

Deduplicate by default at the output layer. A page appears once in results even if multiple links point to it.

Rationale

Agent workflows typically want “what pages are connected?” not “how many times is this link repeated?”
Deduplication at the output layer keeps the internal Link Graph faithful to the actual link structure
Users who need link counts can use zetl stats or zetl export for the full data

Implementation

Deduplication happens after graph traversal, before JSON/table serialization. The graph itself retains all edges.

ADR-003 JSON Errors

ADR-003: JSON Errors on Stdout

Status: Accepted

Context

When zetl encounters an error (e.g., page not found, empty search query), how should it report it? The initial implementation wrote plain-text errors to stderr, which broke agent parsing of JSON output.

This was discovered during the agent ergonomics audit — see Agent Ergonomics and SPEC-003 Agent Ergonomics.

Decision

When --format json is active (the default), errors are written as structured JSON to stdout. Diagnostic messages (verbose logging, timing) remain on stderr.

(given structured-errors)
(given nonzero-exit-codes)

Error format

{
  "error": "page not found: Nonexistent",
  "suggestion": "did you mean: Nonfiction?"
}

Rationale

Agents parse stdout as JSON; a plain-text error on stdout breaks the parser
Structured errors include actionable fields (suggestions, affected files)
Non-zero exit codes signal failure to shell scripts and CI
stderr remains available for human-readable diagnostics

ADR-002 Search Without Index

ADR-002: Search Without Index

Status: Accepted

Context

zetl needs full-text content search across vault files (see Search Command). The question is whether to build an inverted index (like Lucene/tantivy) or scan files directly on each query.

Decision

Use index-free scanning — read and search files directly on each query.

Rationale

Simplicity — no index build step, no index format to maintain, no index invalidation logic beyond what architecture/Cache already handles
Correctness — results always reflect the current file contents; no stale index entries
Acceptable performance — scanning 10,000 files completes in under 2 seconds on commodity hardware (see Performance)
Consistency — zetl already has an mtime-based cache for the link graph; adding a second indexing system increases complexity disproportionately

Trade-offs

Slower than an inverted index for very large vaults (>50k files)
No ranking or relevance scoring — matches are returned in file order
Regex search performance depends on pattern complexity

Mitigation

The --path filter (from Agent Ergonomics) lets users restrict search to a subdirectory, which reduces scan scope. The --limit flag bounds result size.

ADR-001 Rust

ADR-001: Rust for CLI

Status: Accepted

Context

zetl needs to be fast, safe, and easy to distribute. It processes thousands of Markdown files, builds an in-memory graph, and optionally runs a defeasible reasoning engine — all of which demand reliable memory management and low startup latency.

(given type-safe)
(given single-binary)

Decision

zetl is written in Rust.

Rationale

Type safety — the architecture/Scanner, Link Graph, and Reasoning Engine involve complex data flows. Rust’s type system catches entire classes of bugs at compile time.
Single binary — cargo install produces one executable with no runtime dependencies. Users don’t need Python, Node, or a JVM.
Fast startup — CLI tools that take hundreds of milliseconds to start feel sluggish. Rust’s zero-cost abstractions keep startup instant.
Memory safety — no garbage collector pauses, no null pointer surprises.

Key crates

clap — CLI parsing
petgraph — Link Graph
pulldown-cmark — architecture/Scanner
ratatui + crossterm — TUI and View Command
serde + serde_json — JSON serialization
ignore — .gitignore-aware file walking
blake3 — Merkle Tree hashing
spindle-core + spindle-parser — Reasoning Engine (behind Feature Gates)

Trade-offs

Xanadu Lineage

Ted Nelson’s Project Xanadu envisioned a hypertext system with visible connections between documents — “parallel pages” where you could see the source and destination of every link simultaneously.

The vision

In Xanadu, links aren’t hidden behind underlined text. When you read a document, you see its connections to other documents rendered alongside it. The original and the referenced text appear side by side, connected by visible “bridge” lines.

How zetl implements it

zetl’s View Command is a terminal-native interpretation of Xanadu transclusion:

Left pane — the current note, with numbered [N] anchor glyphs at each wikilink
Bridge column — color-coded connectors pairing anchors to context cards
Right pane — context cards: excerpts from forward-linked pages

The Serve Command and Build Command implement the same design with SVG bridge connectors in the browser.

Why it matters for PKM

In a Zettelkasten, notes are meant to be read in context of their connections. Xanadu-style visible links make those connections tangible:

You see what a page links to without navigating away
Context cards give you enough of the linked page to understand the connection
Bridge connectors make the structure of knowledge visible

Transclusion vs embedding

SimHash

SimHash is the fuzzy matching algorithm behind zetl similar — see Similar Command. For the conceptual explanation, see concepts/SimHash.

Implementation

Tokenize — split the page name into overlapping character trigrams (3-character windows)
Hash — compute a hash for each trigram
Aggregate — for each bit position in the 64-bit fingerprint, sum the trigram hash bits (+1 for 1, -1 for 0). The final bit is 1 if the sum is positive, 0 otherwise.
Compare — Hamming distance between two 64-bit fingerprints counts the differing bits

Hamming distance

Lower distance means more similar names:

Distance	Interpretation
0	Identical (after normalization)
1–5	Very similar (minor typos)
6–12	Somewhat similar (default threshold)
13+	Likely different pages

The default threshold of 12 is tunable via --threshold.

Performance

SimHash comparison is O(1) per pair (a single XOR + popcount). The initial fingerprint computation is O(n) in page name length. For a vault with 10,000 pages, comparing a query against all pages takes microseconds.

Limitations

SimHash works well for page names but is not suitable for content similarity. For content search, use Search Command. For semantic similarity, future work may explore embedding-based approaches.

Provenance

Provenance is the ability to trace a conclusion back to its origins. In zetl, every fact, rule, and conclusion carries metadata recording the source file, line number, and page name where it was defined.

(given provenance-documented)

Why it matters

A reasoning system that says “X is true” is only useful if you can ask “why?” and get a concrete answer. Provenance connects the Reasoning Engine’s abstract logic back to the human-readable documents in your vault.

What is tracked

Element	Provenance
Fact	File path, line number, page name
Rule	File path, line number, page name, rule label
Conclusion	Full proof tree of contributing rules and facts
Grounding	Section hash or explicit source reference (see Drift Detection)

Commands

zetl reason explain <literal> — proof tree with source locations
zetl reason provenance <literal> — cross-referenced with the Link Graph
zetl reason export --format spl — reconstructed concepts/Spindle Lisp with provenance comments

Grounding freshness

Since SPEC-006 Merkle Tree, provenance includes grounding freshness. Each source in a provenance trace reports whether its grounding (section or explicit) is still fresh — i.e., whether the prose that justifies the fact has changed since the theory was built.

Example

Running zetl reason provenance "vault-ready-to-publish" on this vault traces the conclusion through rules in theories/vault-readiness.spl back to facts scattered across the architecture, reference, and concept pages.

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:

Defeasible Reasoning

Defeasible reasoning is a form of logic where conclusions can be drawn tentatively and later retracted when stronger evidence appears. This is how most real-world reasoning works — we act on the best information available, knowing new facts might change our minds.

(given defeasible-reasoning-documented)

Why it fits knowledge management

Decision documents, architecture records, and project plans all contain reasoning that is provisional. A conclusion like “use Redis” might be well-supported now but defeated by a future license audit. concepts/Spindle Lisp lets you express this directly in your notes, and zetl’s Reasoning Engine computes what follows.

Rule types

Type	Syntax	Meaning
Fact	`(given X)`	X is unconditionally true
Strict	`(always label body head)`	If body, then head — no exceptions
Defeasible	`(normally label body head)`	If body, normally head — can be defeated
Defeater	`(except label body head)`	If body, block head — but don’t assert the opposite

Superiority

When two rules conflict, a superiority relation resolves the tie:

(prefer stronger-rule weaker-rule)

Without a declared preference, the conflict remains unresolved — zetl reason conflicts will flag it. See Reason Commands.

Conclusion tags

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

In zetl

Wikilinks

Wikilinks are inline references between pages using [[double bracket]] syntax. They are the primary connective tissue in a zetl vault, forming the edges of the Link Graph.

(given wikilink-syntax-documented)

Syntax

Form	Example	Description
Basic	`[[Cache]]`	Link to a page
Aliased	`[[Cache\|caching layer]]`	Display text differs from target
Heading	`[[Cache#Design tension]]`	Link to a specific heading
Block	`[[Cache^summary]]`	Link to a block ID
Embed	`![[Cache]]`	Embed the target page inline
Self-heading	`[[#Syntax]]`	Link to heading in same page

Formal grammar

wikilink     = "[[" target ("#" fragment)? ("|" alias)? "]]"
embed        = "![[" target "]]"
target       = page-name
fragment     = heading | "^" block-id
heading      = text
block-id     = alphanumeric-with-hyphens
alias        = text
page-name    = text (may include "/" for path-qualified links)

Parsing rules

The architecture/Scanner extracts wikilinks from every Markdown file. Wikilinks inside the following zones are ignored:

Fenced code blocks (```)
Inline code (`)
HTML comments ()
YAML frontmatter (--- fences)

Resolution

Page names are matched case-insensitively. [[cache]] resolves to Cache.md. When ambiguity exists (e.g., concepts/SimHash.md and architecture/SimHash.md), use path-qualified links: [[concepts/SimHash]] or [[architecture/SimHash]].

Cross-referencing with logic

Performance

zetl is designed for large vaults — tens of thousands of notes — without sacrificing startup speed or interactive responsiveness.

(given fast-startup)

Targets

Metric	Target	Measured (10k vault)
Cold-start full scan	< 200 ms	140 ms
Incremental re-index (1 file)	< 50 ms	8 ms
Graph query p99	< 10 ms	4 ms
Search (10k files)	< 2 sec	—
Reasoning (10k rules)	< 500 ms	—
TUI startup	< 200 ms	—
View startup	< 200 ms	—
Scroll frame time	< 16 ms	—
Merkle construction overhead	< 20%	—
Diff (2k pages, 50 changed)	< 500 ms	—
Watch event latency (p95)	< 500 ms	—

Strategies

Incremental parsing

The Scanner only re-parses files whose mtime has advanced since the last run. On typical editing sessions (1–5 changed files), this cuts scan time by 99% compared to a full rebuild. See architecture/Cache.

Merkle-based change detection

BLAKE3 content hashes let zetl skip unchanged files even when mtimes are unreliable (e.g., after git checkout). See Merkle Tree.

Memory layout

The Link Graph is stored as a flat adjacency list rather than a pointer-linked structure. This improves cache-line utilisation during multi-hop traversal.

Index-free search

Drift Detection

Drift occurs when the prose surrounding an SPL block changes but the SPL itself does not. The facts and rules may no longer accurately reflect the arguments in the surrounding text.

The problem

SPL blocks in Markdown are grounded in their surrounding prose. When you write:

## Benchmark Results
Redis achieves 185,000 reads/sec at p99.

```spl
(given redis-fast-enough)


The fact `redis-fast-enough` is grounded in the benchmark paragraph. If someone later edits the benchmark numbers but forgets to update the SPL, the fact drifts from its grounding.

## How zetl detects it

zetl uses the [[Merkle Tree]] to track grounding freshness:

1. During indexing, each SPL block's containing section is identified (heading through next heading)
2. A section grounding hash is computed from the non-SPL leaves in that section
3. When the theory is built, section grounding hashes are stored in the theory cache
4. On subsequent `zetl check --drift`, current grounding hashes are compared against cached values
5. Mismatches are reported as drift warnings

## Implicit vs explicit grounding

### Implicit (section-based)

The default. Every SPL block is grounded in its containing section's prose. No annotation needed.

### Explicit (source metadata)

Facts can be explicitly grounded to specific content:

```spl
(given redis-fast-enough)
(meta redis-fast-enough (source "^benchmark-results"))

Explicit grounding uses ^block-id, Merkle hash prefixes, or cross-file [[Page^block-id]] references. See Blocks Command for hash discovery.

Using drift detection

zetl check --drift                       # report drift warnings
zetl check --drift --fail-on warning     # CI: fail on drift

Drift requires a baseline from a previous theory build. New files have no baseline and are not flagged.

Design decisions

SPL changes are NOT drift (the SPL was updated intentionally)
Section restructuring (inserting a new heading) correctly triggers drift because the section boundaries change
Drift is reported as a warning, not an error, by default

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.

Merkle Tree

zetl builds a content-addressed Merkle tree over each Markdown file during indexing. This enables two-tier cache invalidation, SPL grounding, and Drift Detection.

(given content-addressed-hashing)

Structure

Each file produces a flat list of Merkle leaf nodes, computed from pulldown-cmark AST block-level elements:

Leaf type	Source
Heading	`## Section Title`
Paragraph	Prose text blocks
SplBlock	```spl fenced code blocks
Code	Non-SPL fenced code blocks
Table	Markdown tables
List	Ordered/unordered lists
Blockquote	`>` block quotes
Frontmatter	YAML between `---` fences

BLAKE3 hashing

All leaf hashes use BLAKE3, chosen for speed and cryptographic strength. Content is normalized before hashing (whitespace trimmed, consistent line endings) so that formatting-only changes don’t produce different hashes.

SPL dual hashing

SPL blocks receive two hashes:

content_hash — hash of the raw SPL text (changes on any edit, including comments)
ast_hash — hash of the parsed SPL AST (changes only on logical modifications)

The AST hash drives theory cache invalidation — see architecture/Cache. The content hash detects any change for drift purposes.

File and vault roots

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

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.

Scanner

The scanner is zetl’s entry point for understanding a vault. It walks every Markdown file and standalone .spl file, extracting concepts/Wikilinks and concepts/Spindle Lisp blocks in a single pass.

(given wikilink-extraction)
(given spl-extraction)

Wikilink extraction

The scanner recognises all common wikilink forms:

[[Page]] — basic link
[[Page|alias]] — aliased link
[[Page#heading]] — heading anchor
[[Page^block-id]] — block reference
![[Page]] — embed

Extracted links feed into the Link Graph for query and traversal.

Exclusion zones

The scanner skips wikilink-like patterns that appear inside:

Fenced code blocks (```)
Inline code (`)
HTML comments ()
YAML frontmatter (--- fences)

This prevents false positives from code examples or metadata.

SPL extraction

Reason Commands

zetl reason exposes the Reasoning Engine through eight subcommands. All require --features reason at build time — see Feature Gates.

(given reason-status-done)
(given reason-explain-done)
(given reason-why-not-done)
(given reason-require-done)
(given reason-what-if-done)
(given reason-conflicts-done)
(given reason-export-done)
(given reason-provenance-done)

Commands

`reason status`

What does the vault’s combined concepts/Spindle Lisp theory conclude? Filter by polarity (--positive, --negative), strength (--definite, --defeasible), or literal name (--literal "release*").

`reason explain <literal>`

Why does a conclusion hold? Produces a proof tree tracing the derivation through rules back to facts, with full concepts/Provenance (file, line, page). Output as JSON, table, natural language, or Graphviz dot.

`reason why-not <literal>`

Why can’t something be proved? Identifies missing facts, blocked rules, or active defeaters. This is the inverse of explain — useful for understanding gaps in the vault’s knowledge.

`reason require <literal>`

What facts would make a goal provable? Abductive reasoning — finds the minimal sets of missing facts. Useful for answering “what would it take to make release-candidate true?”

Build Command

zetl build generates a static HTML site from your vault, with the same look and feel as Serve Command minus the edit button and save functionality.

Usage

zetl -d ./my-vault build                  # generates dist/
zetl -d ./my-vault build --out-dir site   # custom output directory

Flags

Flag	Default	Description
`--out-dir <path>`	`dist`	Output directory for the generated site

Output structure

dist/
  index.html              # vault overview with stats and page grid
  page/
    Some Page/index.html   # one page per note
    Another/index.html

Features

Rendered Markdown with syntax highlighting
Backlink lists on each page
Transclusion panels with SVG bridge connectors
Page grid on the index page
Clean URLs (/page/Scanner/ instead of /page/Scanner.html)

Deployment

The output can be uploaded to any static host:

GitHub Pages
Netlify
S3 + CloudFront
Any web server

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.

View Command

zetl view is a Xanadu-inspired two-pane reader for focused page navigation. See Xanadu Lineage for the design philosophy.

Usage

zetl view "Scanner"               # open a specific page
zetl view                         # open the page picker
zetl view "Scanner" --context-lines 10 --main-width 60

Flags

Flag	Default	Description
`--context-lines N`	5	Lines shown per context card (1–20)
`--main-width pct`	58	Percentage of terminal width for the main pane (30–80)

Layout

The screen is divided into three columns:

Left pane — the current note, rendered with numbered [N] anchor glyphs at each wikilink
Bridge column — color-coded connectors pairing anchors to cards
Right pane — context cards: excerpts from forward-linked pages

In narrow terminals (<60 cols), the view falls back to a single-pane layout.

Keybindings

Key	Action
`j` / `k`	Scroll (or cycle links in focus mode)
`Ctrl-d` / `Ctrl-u`	Half-page scroll
`g` / `G`	Top / bottom of note
`Tab`	Toggle between scroll and focus mode
`Enter`	Navigate to focused link
`[` / `]`	Session history back / forward
`b`	Toggle backlink mode
`/`	Open page picker
`?`	Toggle keybindings help
`q`	Quit

Implementation

Built on ratatui and crossterm, like the TUI. Supports true-color, 8-color, and no-color terminals. See Xanadu View Design for design decisions and SPEC-009 Xanadu View for the full specification.

TUI

zetl tui launches an interactive terminal interface for browsing your vault. It is the human-oriented complement to zetl’s JSON by Default output philosophy.

(given tui-complete)
(given seven-views)

Views

View	Description
Dashboard	Vault stats and most-linked pages
Pages	Filterable page list
Links	Forward/back link explorer
Search	Full-text search with context
Diagnostics	Dead links, orphans, syntax issues
Page	Rendered Markdown with inline concepts/Wikilinks navigation
Graph	Local link graph with depth toggle

Navigation

Key	Action
`Tab` / `Shift+Tab`	Cycle views
`Ctrl+K`	Quick switcher
`j` / `k`	Scroll
`Enter`	Follow a wikilink
`Backspace`	Go back
`/`	Search/filter

Implementation

Built on ratatui and crossterm. The TUI reads the same Link Graph and architecture/Cache as the CLI commands — no separate data path. See SPEC-009 Xanadu View for the related two-pane reader.

Relationship to View

The TUI is a multi-view dashboard. For focused reading with visible connections between notes, use View Command instead — it provides a Xanadu-inspired two-pane layout with bridge connectors.

Stats Command

zetl stats prints summary statistics about the vault.

Usage

zetl -d ./my-vault stats
zetl stats --top 20 --format table

Flags

Flag	Default	Description
`--top N`	10	Number of most-linked pages to show

Output

The stats include:

pages — total page count
links — total wikilink count
orphans — pages with no incoming links
most_linked — top N pages by incoming link count
vault_content_hash — BLAKE3 root hash of the entire vault (from Merkle Tree)
spl_blocks — total SPL block count
grounded_spl_blocks — SPL blocks with section or explicit grounding
explicitly_grounded_facts — facts with (meta ... (source ...)) references

The vault content hash provides an integrity checkpoint — agents can use it to verify that the vault state hasn’t changed between operations.

List and Export Commands

Two utility commands for enumerating vault contents.

`zetl list`

Lists all pages in the vault.

zetl -d ./my-vault list

Returns page names and file paths. Useful for agent workflows that need to enumerate available pages before querying them.

Added in response to agent ergonomics findings — see Agent Ergonomics and SPEC-003 Agent Ergonomics.

`zetl export`

Exports the complete Link Graph as JSON — every page and every link.

zetl -d ./my-vault export

The output is a full adjacency list of the vault’s link structure. This enables external tools to consume zetl’s graph data for visualization, analysis, or integration.

Relationship to other commands

Watch Command

zetl watch starts a persistent process that monitors the vault for file changes and emits graph-level events as NDJSON on stdout.

Usage

# Start watching (NDJSON events on stdout)
zetl -d ./my-vault watch

# Custom debounce interval
zetl watch --debounce 500

# Execute a command on each change
zetl watch --exec "zetl check --fail-on error"

Flags

Flag	Default	Description
`--debounce <ms>`	200	Debounce interval for batching rapid changes
`--exec <cmd>`	none	Command to invoke after each re-index

Event types

Events are emitted as NDJSON (one JSON object per line). The event vocabulary mirrors the Diff Command output schema:

Event	Description
`index_ready`	Initial index complete, watching started
`page_added`	New page appeared
`page_removed`	Page deleted
`link_added`	New wikilink appeared
`link_removed`	Wikilink removed
`orphan_gained`	Page became orphaned
`orphan_resolved`	Orphan page got an incoming link
`dead_link_added`	New dead link appeared
`dead_link_resolved`	Dead link target now exists
`index_updated`	Re-index cycle complete (summary)

How it works

zetl uses OS-level file system events (via the notify crate) to detect changes. When a .md file changes, zetl debounces the event, incrementally re-indexes only the affected files using the Merkle Tree change detection from architecture/Cache, and emits events only when the graph actually changes.

Agent integration

The NDJSON stream is designed for consumption by AI agents and automation scripts. Pipe it to tools like jq or feed it into an incremental reasoning loop.

Diff Command

zetl diff computes a graph-level diff against Git history, showing what changed in the link structure between two points in time.

Usage

# Diff against previous commit (default: HEAD~1)
zetl -d ./my-vault diff

# Diff against a specific ref
zetl diff --from main~5

# Diff by date
zetl diff --since "2026-02-01"

# Filter by change category
zetl diff --filter links

Flags

Flag	Default	Description
`--from <ref>`	`HEAD~1`	Git ref to diff against
`--since <datetime>`	none	Find closest commit at or before this date
`--filter <category>`	none	Filter output: `pages`, `links`, `orphans`, `dead_links`

How it works

zetl uses an efficient reconstruction algorithm (see ADR-012 Changed Files Reconstruction):

git diff --name-only identifies changed .md files between the baseline and HEAD
git show retrieves the old content of each changed file
Old content is parsed for wikilinks
Set differences between old and new graphs yield the diff

This scales with the size of the change, not the size of the vault.

Output

The diff reports:

Pages added and removed
Links added and removed
Orphans gained and resolved
Dead links added and resolved

Blocks Command

zetl blocks lists content-addressable Merkle Tree blocks for a page (forward mode) or resolves a block by its BLAKE3 hash prefix (reverse mode).

Usage

# Forward mode: list all blocks for a page
zetl -d ./my-vault blocks "Scanner"

# Filter by type
zetl blocks "Scanner" --type heading

# Reverse mode: resolve a hash to its source
zetl blocks --resolve abc123de

Forward mode

Given a page name, returns all Merkle leaf nodes in document order. Each block includes:

type — Heading, Paragraph, SplBlock, Code, Table, List, Blockquote, Frontmatter
lines — start and end line numbers
hash — BLAKE3 content hash
text — preview of the block content
spl_hashes — for SPL blocks: content_hash and ast_hash (dual hashing)

Block type filter

`--type` value	Matches
`heading`	Heading nodes
`paragraph`	Paragraph nodes
`spl`	SPL code blocks
`code`	Non-SPL code blocks
`table`	Table nodes
`list`	List nodes
`blockquote`	Blockquote nodes
`frontmatter`	YAML frontmatter
`all`	All block types (default)

Reverse mode

Given a hash prefix (minimum 8 hex characters), finds the source location:

zetl blocks --resolve e5f6a7b8

Returns the file, page name, line range, block type, and content. Useful for tracing concepts/Provenance from a hash back to its source.

Check Command

zetl check validates the vault and reports issues across both the Link Graph and concepts/Spindle Lisp content.

(given dead-link-detection)
(given orphan-detection)
(given spl-diagnostics)
(given drift-detection)

Usage

zetl -d ./my-vault check
zetl check --dead-links --fail-on error    # CI mode
zetl check --spl                           # SPL diagnostics only
zetl check --drift                         # detect SPL grounding drift

Issue types

Dead links

A wikilink that points to a page that doesn’t exist. For example, [[Plugin System]] would be a dead link if there’s no Plugin System.md file.

Orphan pages

Pages with no incoming links — nothing in the vault references them. These may be forgotten drafts or entry points that need a wikilink from somewhere.

Syntax errors

Malformed wikilinks like unclosed brackets.

Similar Command

zetl similar finds pages with names similar to a query string, using concepts/SimHash-based fuzzy matching.

Usage

zetl -d ./my-vault similar "zettelkasen"

Flags

Flag	Default	Description
`--threshold N`	12	Max Hamming distance (lower = stricter)
`--limit N`	10	Max results

How it works

zetl computes a SimHash fingerprint for each page name using character trigrams, then compares the query’s fingerprint against all pages using Hamming distance. Pages within the threshold are returned, sorted by similarity.

This is useful for:

Finding pages despite typos
Discovering pages with similar names that might be candidates for merging
Fuzzy lookup when you don’t remember the exact page title

Relationship to search

similar matches page names. Search Command matches page content. Use similar when you know roughly what a page is called; use search when you know something the page contains.

Search Command

zetl search provides full-text content search across all Markdown files in the vault.

(given fulltext-search-done)
(given regex-support)

Usage

# Literal text search
zetl -d . search "defeasible"

# Regex search
zetl -d . search "reason(ing|ed)" --regex

# With surrounding context
zetl -d . search "Cache" --context 100

# Case-sensitive
zetl -d . search "SPL" --case-sensitive

# Restrict to a subdirectory
zetl -d . search "given" --path "theories/*"

Flags

Flag	Default	Description
`--context N`	0	Include N characters of surrounding text
`--limit N`	50	Max results to return
`--regex`	off	Interpret query as a regular expression
`--case-sensitive`	off	Require exact case match
`--all`	off	Search raw content (include frontmatter, code blocks)
`--path <glob>`	none	Restrict results to files matching glob

Content filtering

By default, search skips frontmatter and fenced code blocks to focus on prose. Use --all to search raw file content including concepts/Spindle Lisp blocks and YAML frontmatter.

Design decision

zetl uses index-free scanning rather than an inverted index. This trades query speed on very large vaults for zero build-time indexing cost and simpler architecture. See ADR-002 Search Without Index for the rationale.

Fuzzy page name matching

For finding pages by name rather than content, use Similar Command instead:

Path Command

zetl path finds the shortest chain of concepts/Wikilinks connecting two pages in the Link Graph.

Usage

zetl -d ./my-vault path "Scanner" "Provenance"

Flags

Flag	Default	Description
`--max-depth N`	10	Maximum path length to search

How it works

zetl performs a breadth-first search on the directed link graph from the source page toward the target. The result is the shortest sequence of pages connecting them.

This is useful for discovering how ideas relate through intermediate notes — a form of knowledge exploration that leverages the graph structure built from wikilinks.

Output

JSON output includes the ordered list of pages in the path and the total hop count. Table output shows the path as an arrow-separated chain.

If no path exists within --max-depth hops, zetl reports that the pages are not connected.

Links Command

zetl links and zetl backlinks query the Link Graph for forward and backward connections.

Usage

# Forward links — pages that <page> links to
zetl -d ./my-vault links "Scanner"

# Backlinks — pages that link to <page>
zetl -d ./my-vault backlinks "Cache" --depth 2

Flags

Flag	Default	Description
`--depth N`	1	Traverse N hops (1 = direct only)
`--fuzzy`	off	Enable fuzzy page name matching via concepts/SimHash
`--context N`	0	Include N characters of surrounding text
`--with-conclusions`	off	Show SPL conclusions each linked page contributes

Multi-hop traversal

With --depth 2, zetl follows links from the target page AND from every page the target links to (or is linked by). This reveals indirect relationships in the vault’s knowledge structure.

Deduplication

By default, zetl deduplicates results — a page appears once even if multiple links point to it. This is the output-layer deduplication described in ADR-004 Link Dedup.

Cross-referencing with reasoning

Add --with-conclusions to see what concepts/Spindle Lisp conclusions each linked page contributes. This bridges the structural graph with the logical theory from the Reasoning Engine.

zetl -d . links "Cache" --with-conclusions

Index Command

zetl index builds or refreshes the link index for a vault.

Usage

zetl -d ./my-vault index

What it does

Scans all .md files in the vault directory (recursively)
Parses each file with pulldown-cmark, extracting concepts/Wikilinks and concepts/Spindle Lisp blocks — see architecture/Scanner
Builds the Link Graph — a directed graph of page-to-page links
Computes Merkle Tree hashes for content-addressable blocks
Writes the index to .zetl/index.json — see architecture/Cache

Incremental behavior

On subsequent runs, zetl uses two-tier cache invalidation:

Tier 1 (mtime): If a file’s modification time hasn’t changed, skip it entirely
Tier 2 (hash): If the mtime changed but the content hash matches, skip reprocessing

This makes re-indexing fast even for large vaults. Use --no-cache to force a full rescan.

Verbose output

With -v, zetl reports scan statistics to stderr: files scanned, files skipped, links found, SPL blocks extracted, and timing.

CLI Reference

zetl is a single binary with subcommands. All commands output JSON by default — see JSON by Default.

Global flags

Flag	Short	Description
`--dir <path>`	`-d`	Vault root directory (default: `.`)
`--format <fmt>`	`-f`	Output format: `json` (default) or `table`
`--no-cache`		Force full rescan, ignore cached index
`--no-color`		Disable colored output
`--quiet`	`-q`	Suppress non-essential output
`--verbose`	`-v`	Increase verbosity (repeat for more: `-vv`)

Commands

Wikilink commands

Command	Description	Reference
`index`	Build or refresh the link index	Index Command
`links <page>`	Query forward links from a page	Links Command
`backlinks <page>`	Query backlinks to a page	Links Command
`path <from> <to>`	Shortest link path between pages	Path Command
`search <query>`	Full-text content search	Search Command
`similar <query>`	Fuzzy page name matching (SimHash)	Similar Command
`check`	Validate vault: dead links, orphans, SPL errors	Check Command
`blocks [page]`	List or resolve Merkle content blocks	Blocks Command
`diff`	Git-backed graph diff	Diff Command
`watch`	NDJSON event stream on file changes	Watch Command
`list`	List all pages	List and Export Commands
`export`	Export complete link graph as JSON	List and Export Commands
`stats`	Vault summary statistics	Stats Command
`tui`	Interactive terminal UI	TUI
`view [page]`	Xanadu-style two-pane reader	View Command
`serve`	Local web server	Serve Command
`build`	Static site export	Build Command

Reasoning commands

Require --features reason at build time. See Feature Gates.

Command	Description	Reference
`reason status`	Current conclusions from vault-wide SPL	Reason Commands
`reason explain <literal>`	Proof tree with provenance	Reason Commands
`reason why-not <literal>`	Why a literal isn’t provable	Reason Commands
`reason require <literal>`	Abductive: what facts are needed	Reason Commands
`reason what-if <spl>`	Hypothetical reasoning	Reason Commands
`reason conflicts`	Unresolved logical contradictions	Reason Commands
`reason export`	Export combined theory	Reason Commands
`reason provenance <literal>`	Trace conclusion to source files	Reason Commands

Exit codes

Code	Meaning
0	Success
1	Error (dead links found with `--fail-on error`, conflicts with `--fail-on-conflicts`, etc.)

Structured JSON errors are written to stdout, not stderr. See ADR-003 JSON Errors.

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.

Demo Vault

zetl ships with a demo-vault/ directory — a self-referential knowledge base that documents zetl itself using both concepts/Wikilinks and concepts/Spindle Lisp.

What’s inside

The demo vault contains pages across several categories:

architecture/ — architecture/Scanner, Link Graph, architecture/Cache, Reasoning Engine, architecture/Performance
concepts/ — concepts/Wikilinks, concepts/Defeasible Reasoning, concepts/Spindle Lisp, concepts/Provenance
decisions/ — ADR-001 Rust, Feature Gates, JSON by Default, decisions/Local-first Design
features/ — command documentation for graph queries, search, diagnostics, and reasoning
theories/ — standalone .spl files with cross-cutting rules

SPL showcase

The demo vault embeds SPL facts in prose pages (e.g., (given wikilink-extraction) in the Scanner page) and combines them with rules in theories/release-readiness.spl. Running zetl reason status derives conclusions like release-candidate from facts scattered across the vault.

The theories/caching.spl file includes a deliberate conflict that zetl reason conflicts surfaces — two competing rules about cache reasoning results with no superiority relation.

Try it

zetl -d ./demo-vault index
zetl -d ./demo-vault stats --format table
zetl -d ./demo-vault reason explain "release-candidate" --format natural
zetl -d ./demo-vault reason conflicts --format table
zetl -d ./demo-vault serve

This vault vs the demo vault

This zetl-vault/ is a more comprehensive documentation vault. The demo vault is smaller and focused on showcasing features. Both are self-documenting — they use zetl’s own features to describe zetl.

Quick Start

A five-step tour of zetl’s core capabilities. Assumes you’ve already run Install.

Step 1: Build the index

zetl -d ./demo-vault index

This scans all Markdown files, extracts concepts/Wikilinks and concepts/Spindle Lisp blocks, and builds the link graph. The index is cached in .zetl/ for fast subsequent runs — see architecture/Cache.

Step 2: Explore stats

zetl -d ./demo-vault stats --format table

Shows page count, link count, orphan count, and the most-linked pages. All commands output JSON by default — add --format table for human-readable output. See Stats Command.

Step 3: Validate the vault

zetl -d ./demo-vault check --format table

Reports dead links, orphan pages, syntax errors, and SPL diagnostics. See Check Command.

Step 4: Launch the TUI

Install

zetl requires a Rust toolchain. Install one via rustup if you don’t already have it.

(given single-binary)
(given fast-startup)
(given type-safe)

Basic install (wikilinks only)

make install

This builds a lean binary with wikilink parsing, graph queries, search, TUI, and the web UI — everything except concepts/Defeasible Reasoning.

With reasoning support

cargo install --path . --features reason

The reason feature gate pulls in the concepts/Spindle Lisp runtime (spindle-core). Without it, running zetl reason prints a helpful error instead of failing silently — see Feature Gates for the design rationale.

From source

git clone <repo-url>
cd zetl
make           # fmt + clippy + build + test
make release   # optimized binary