Vault Diagnostics

zetl check validates the vault and reports issues. It examines both the Link Graph and Spindle Lisp content.

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

Issue types

Dead links

A wikilink that points to a page that doesn’t exist. For example, [[Plugin System]] in this vault is a dead link — there is no Plugin System.md file.

zetl -d . check --dead-links

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.

zetl -d . check --orphans

Syntax errors

Malformed Wikilinks like unclosed brackets.

SPL diagnostics

Parse errors, duplicate rule labels, undefined references, and unreachable literals in Spindle Lisp blocks. Enabled with --spl:

zetl -d . check --spl

CI integration

Use --fail-on error to exit non-zero when issues are found:

zetl -d ./my-vault check --dead-links --fail-on error

See also: Graph Queries, Reason Commands, Scanner

Backlinks

Link Graphline 36
TUIline 38
Feature Gatesline 24
Graph Queriesline 49

Linked Pages

Scanner

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

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.

SPL extraction

Fenced code blocks tagged ```spl are extracted verbatim, along with their source file and line number. Standalone .spl files anywhere in the vault are also picked up. Both feed into the Reasoning Engine with full Provenance.

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

Implementation

Built on pulldown-cmark for Markdown parsing and ignore for .gitignore-aware file walking. The scanner is deliberately read-only — see Local-first Design.

See also: Cache, Link Graph, Reasoning Engine

Reason Commands

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 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 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.

`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?”

Graph Queries

zetl exposes the Link Graph through several query commands. All output JSON by default — see JSON by Default.

(given forward-links-done)
(given backlinks-done)
(given shortest-path-done)

Commands

`zetl links <page>`

Show all pages that <page> links to. Supports --depth N for multi-hop traversal and --fuzzy for approximate page name matching.

`zetl backlinks <page>`

Show all pages that link to <page>. Same depth and fuzzy options as links.

`zetl path <from> <to>`

Find the shortest chain of Wikilinks connecting two pages. Useful for discovering how ideas relate through intermediate notes.

`zetl export`

Dump the entire Link Graph as JSON — every page and every link.

Spindle Lisp

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

Syntax reference

Facts

(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.

(normally r-birds-fly bird flies)
(normally bird animal)

Defeaters

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.

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

How zetl uses them

The Scanner extracts wikilinks from every Markdown file. The Link Graph stores them as directed edges, enabling:

Forward link queries (zetl links)
Backlink queries (zetl backlinks)
Shortest path computation (zetl path)
Dead link detection (zetl check)

Cross-referencing with logic

When reasoning is enabled, --with-conclusions annotates link results with the Spindle Lisp conclusions that each linked page contributes. This bridges the Link Graph and the Reasoning Engine.

Compatibility

zetl supports the wikilink conventions used by Obsidian, Logseq, Foam, and Dendron. See Local-first Design for the principle that zetl never modifies your files.

Link Graph

zetl builds a directed graph where nodes are pages and edges are Wikilinks. The graph powers all link-based queries: forward links, backlinks, multi-hop traversal, shortest path, and orphan detection.

Data model

Node — a Markdown page, identified by its title (filename without .md)
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 the Cache for incremental re-scans.

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

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 Graph Queries. 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.

See also: Scanner, Graph Queries, Vault Diagnostics