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 Wikilinks, Graph Queries, Search, Vault Diagnostics, and the TUI — but not 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 Defeasible Reasoning
Spindle Lisp is a niche feature — progressive disclosure serves users better

Install with reasoning

cargo install --path . --features reason

See also: Rust for CLI, Reasoning Engine, Reason Commands

Backlinks

Linked Pages

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

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

Rust for CLI

zetl is written in Rust. This was a deliberate choice driven by the requirements of a CLI tool that handles large vaults and complex reasoning.

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

Why Rust

Type safety — the 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 even on large vaults.
Memory safety — no garbage collector pauses, no null pointer surprises. Important when processing thousands of files.

Trade-offs

Slower to iterate during development compared to a scripting language
The Feature Gates mechanism adds build complexity
Compile times are non-trivial

These trade-offs are acceptable for a tool meant to be installed once and used daily.

Dependencies

Key crates: clap (CLI parsing), petgraph (Link Graph), pulldown-cmark (Scanner), ratatui (TUI), spindle-core / spindle-parser (Reasoning Engine).

See also: Feature Gates, JSON by Default, Local-first Design

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

Defeasible Reasoning

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.

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. 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 name body head)`	If body, then head — no exceptions
Defeasible	`(normally name body head)`	If body, normally head — can be defeated
Defeater	`(except name 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.

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

In zetl

The Reasoning Engine implements defeasible reasoning via spindle-core. See Reason Commands for the CLI interface and Provenance for how conclusions trace back to source files.

TUI

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.

Views

(given tui-complete)
(given seven-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 Wikilinks navigation
Graph	Local link graph with depth toggle

Navigation

Tab / Shift+Tab — cycle views
Ctrl+K — quick switcher
j / k — scroll
Enter — follow a wikilink
Backspace — go back

Implementation

Built on ratatui and crossterm. The TUI reads the same Link Graph and Cache as the CLI commands — no separate data path.

See also: Graph Queries, Search, Vault Diagnostics

Vault Diagnostics

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.

Search

Search

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

(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/*"

Content filtering

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

Fuzzy page name matching

For finding pages by name rather than content, use zetl similar:

zetl -d . similar "reasning engine"

This uses SimHash-based similarity to find close matches even with typos.

See also: Graph Queries, TUI, Scanner

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.

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.