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

Backlinks

Wikilinksline 21
Spindle Lispline 87
Reasoning Engineline 11
Reasoning Engineline 7
Cacheline 45
Link Graphline 36
Link Graphline 14
Performanceline 63
Performanceline 30
Local-first Designline 31
Rust for CLIline 32
Rust for CLIline 17
Vault Diagnosticsline 53
Searchline 47

Linked Pages

Reasoning Engine

Reasoning Engine

The reasoning engine takes Spindle Lisp extracted by the Scanner from across the entire vault, merges it into a single theory, and computes conclusions using Defeasible Reasoning. Every conclusion carries full Provenance — you can trace any result back to the exact file and line that contributed to it.

Pipeline

Extract — Scanner finds SPL blocks in Markdown fences and .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
Combine — all rules and facts are merged into a single theory
Validate — check for undefined labels, duplicate definitions
Reason — spindle-core computes conclusions
Annotate — each conclusion is traced back to its proof sources

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

Conclusion types

The engine produces four types of conclusion — see Defeasible Reasoning for details:

Tag	Meaning
`+D`	Definitely provable
`-D`	Definitely not provable
`+d`	Defeasibly provable
`-d`	Defeasibly not provable

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.

See also: Reason Commands, Provenance, Spindle Lisp

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

Cache

Cache

zetl uses mtiame-based incremental caching for both the Link Graph and the Reasoning Engine’s theory. On subsequent runs, only files modified since the last scan are re-parsed.

How it works

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

index.json — serialised link graph
theory.json — serialised reasoning theory and conclusions

Each entry records the file’s last-modified timestamp. When zetl starts, it compares mtimes and only re-scans changed files. Use --no-cache to force a full rebuild.

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

Design tension

There is an unresolved design tension in how aggressively to cache reasoning results:

; Cache the theory for fast startup
(normally r-cache-theory
  mtime-based-cache
  cache-reasoning-results)

; But recomputing ensures results are always fresh
(normally r-recompute-theory
  incremental-rebuild
  (not cache-reasoning-results))

Both arguments have merit. Try zetl reason conflicts on this vault to see how zetl surfaces this kind of tension. A future Plugin System could let users configure the trade-off.

Safety

Local-first Design

Local-first Design

zetl never modifies your files. It is strictly read-only against the vault.

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

Principles

Read-only — zetl only reads Markdown and .spl files. It never writes to, renames, or deletes vault content.
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.
No network — zetl makes no network calls. Everything runs locally.
No lock-in — your vault is plain Markdown with optional Spindle Lisp blocks. Removing zetl leaves your files untouched.

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.

The Cache is the only thing zetl writes, and it lives in a clearly-marked directory that can be gitignored.

Compatibility

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

See also: Cache, Scanner, Rust for CLI

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.

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

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 Spindle Lisp with provenance comments

Example

Running zetl reason provenance "release-candidate" on this vault traces the conclusion through rules in theories/release-readiness.spl back to facts scattered across the architecture and feature pages.

See also: Reasoning Engine, Reason Commands, Defeasible Reasoning

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.