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.

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`)

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

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

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

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

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

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

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`)

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

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

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

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

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

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)

Spec Index

Specifications

How specs relate

Traceability

Backlinks