Finding Orphans and Dead Links

zetl check is the vault-health command. It reports three kinds of problem — dead links, orphan pages, and syntax errors — and optionally a fourth, SPL diagnostics, if you use the reasoning layer. Run it before a big refactor, before a publish, and in CI.

zetl check

Exits non-zero if anything at error level is found. That makes it a drop-in CI step.

The two main health signals

Dead links

A dead link is a [[wikilink]] that points at a page that does not exist. You typed [[Zettelkasten Methog]] and meant [[Zettelkasten Method]]; or you deleted a page without updating the notes that cited it.

zetl check --dead-links

Two ways to fix each one:

Create the page. If the link represents a real idea that deserves a page, the dead link is a prompt: go write the note. This is the positive use of dead links — they are a TODO list generated by your past self.
Rename or delete the link. If the target was a typo, fix the typo. If the idea no longer deserves a page, remove the link or replace it with plain prose.

The zetl similar "Zettelkasten Methog" command (see Similar Pages) pairs naturally with dead-link review: for each dead link, check whether you meant an existing page.

Orphans

An orphan is a page with no inbound links and no outbound links. Nothing points at it; it points at nothing. It is disconnected from the graph.

zetl check --orphans

Two ways to treat each one:

Link it. If the page is real content (a book note, a meeting summary), wire it in. Add a [[link]] from an index page, a project page, or a daily note. This is usually the right move.
Delete it. If the orphan is a stale draft, a duplicate, or a half-thought you abandoned, delete it. Orphans are not neutral; they decay the signal-to-noise ratio of Searching and of your own browsing.

A zero-orphan vault is not a goal. Some orphans are intentional — a daily journal entry, say, that you never expect to link into the graph. Skim the list, act on the fixable ones, leave the rest.

Syntax errors

zetl check --syntax reports malformed wikilinks, malformed frontmatter, and other parse-level problems. These are usually copy-paste accidents. Fix them on sight.

`zetl stats` — the summary view

zetl stats

pages:           4,127
wikilinks:       9,844
dead links:          12
orphans:             31
most-linked:     Zettelkasten Method (84 inbound)
                 2026 Research Plan  (61 inbound)
                 ...

A pre-flight glance. Run it weekly; watch the dead-link and orphan counts trend. An unchanged dead-link count for a month means you are not actually reviewing them. --top N widens the most-linked section (default 10).

CI integration

The --fail-on flag controls exit code behaviour. Default is error; bump to warning if you want a strict CI that fails on anything at all.

# GitHub Actions, Woodpecker, whatever
zetl check --fail-on error

A typical pipeline step:

- name: vault health
  run: |
    zetl index
    zetl check --fail-on error

JSON output is automatic under a pipe, so you can also post results to a dashboard:

zetl check --json \
  | jq '{dead: .dead_links | length, orphans: .orphans | length}'

SPL diagnostics

If you use the reasoning layer (What is SPL), --spl surfaces Spindle-Lisp-specific problems: parse errors, duplicate labels, undefined references, unreachable literals.

zetl check --spl

Requires --features reason. A related flag, --drift, reports SPL blocks whose grounding facts have changed since the last theory build — the “your logic block is stale” warning.

Example: pre-publish pass

You are about to zetl build your public notes vault. A three-minute pass before the build:

zetl index --no-cache            # fresh index
zetl stats                       # eyeball the numbers
zetl check --dead-links          # fix typos, create missing pages
zetl check --orphans             # decide: link, delete, or leave
zetl check --fail-on error       # gate
zetl build

The exit code of the fourth command tells you whether to proceed.

Backlinks

Linked Pages

CLI Overview

Every zetl subcommand at a glance, with the flags writers actually use. This page is the reference — the linked how-to pages give the narrative.

Run zetl <cmd> --help for the authoritative flag list for any command. This guide tracks zetl v0.5.0.

Global flags

Every subcommand honours these, wherever they make sense.

Flag	Env var	Purpose
`-d, --dir <DIR>`	`ZETL_DIR`	Vault root. Default: `.` (current directory).
`-f, --format <FORMAT>`	`ZETL_FORMAT`	`json` / `table` / `auto`. Auto picks table for a TTY, JSON for a pipe.
`--json`	—	Shorthand for `-f json`.
`--no-cache`	`ZETL_NO_CACHE`	Ignore the cached index; force a full rescan.
`--no-color`	`NO_COLOR`	Disable ANSI colour.
`-q, --quiet`	—	Suppress non-essential output.
`-v, --verbose`	—	Increase verbosity. Repeatable (`-vv`).
`--no-input`	—	Disable interactive prompts; fail if input is needed.
`--at <TIME-EXPR>`	—	Query the vault at a historical point. Requires `--features history`. See Time Travel.
`-V, --version`	—	Print zetl version.

Subcommand summary

Command	Description	Feature flag
`index`	Build or refresh the link index	—
`list`	List every page in the vault	—
`stats`	Summary counts and most-linked pages	—
`links`	Forward links from a page	—
`backlinks`	Backlinks to a page	—
`check`	Dead links, orphans, syntax, SPL diagnostics	—
`search`	Full-text search (BM25, optional semantic)	`semantic` for `--semantic`/`--hybrid`
`similar`	SimHash title matches	—
`path`	Shortest link path between two pages	—
`export`	Dump the full link graph	—
`blocks`	List or resolve Merkle blocks	—
`view`	Two-pane terminal reader	—
`serve`	Local web server	—
`build`	Static-site HTML export	—
`watch`	Stream vault changes as NDJSON	—
`diff`	Graph diff against a git ref or snapshot	—
`theme`	List / install / remove / export themes	—
`hook`	Author, test, and inspect hooks	—
`ecosystem`	Probe Pandoc / mdBook / remark runtimes	`ecosystems-v1`
`ast`	Inspect or diff zetl-ext AST	—
`agent`	Run an agent-lifecycle hook	—
`invite`	Multi-user invitation token	collab (built-in)
`agent-token`	Derive a headless API token	collab
`derive-ssh-key`	Derive an SSH ed25519 key from a mnemonic	collab
`cap`	Capability-URL static sharing operations	—
`reason`	SPL queries over the vault	`reason`
`mcp`	Start an MCP server	`mcp`
`delegate`	Issue a delegate JWT	`mcp`
`completions`	Emit a shell completion script	—
`man`	Emit a roff(7) man page	—

zetl index

Scan the vault and write the cached link index to .zetl/index.json. Incremental by default; --no-cache forces a full rescan.

Key flags: --exclude <PATTERN> (repeatable gitignore syntax), --include-hidden (walk .claude/, .obsidian/, etc.).

zetl index
zetl -d ~/notes index --exclude 'drafts/**'

zetl list

Enumerate every page zetl can see. Useful in pipes.

Writing Pages

In a zetl vault, one page is one Markdown file. No databases, no sidecar XML, no magic — if you can write a .md file, you can write a zetl page.

The filename is the title

zetl uses the filename (minus .md) as the page title. Title-case filenames with spaces are the convention:

~/notes/
  Zettelkasten Method.md
  Reading List 2026.md
  Meeting with Priya 2026-04-18.md

When another page writes [[Zettelkasten Method]], zetl resolves the link by matching the filename. Slugification happens at render time — the URL becomes /zettelkasten-method/, but your filesystem stays human-readable. Case doesn’t matter for resolution; [[zettelkasten method]] works too.

There is no restriction on where a file lives. Folders are for your eyes, not zetl’s. See Organising Your Vault.

A minimal page

Every page is CommonMark-compatible Markdown with optional YAML frontmatter at the top:

---
title: Reading List 2026
tags: [reading, journal]
status: open
---

# Reading List 2026

Books I want to read this year, with a running note once I finish each.

- [[Gödel, Escher, Bach]] — started January
- [[The Glass Bead Game]] — queued
- [[Seeing Like a State]] — finished March

## Related

- [[Book Journal]]
- [[Annual Review 2026]]

That’s it. No build step, no registration. Save the file; it’s a page. Run zetl list and you’ll see it.

Markdown flavour

Similar Pages

zetl similar "Query" finds pages whose titles are near-matches for the query string. It uses SimHash over page names, which makes it excellent at three things: recovering from typos, spotting duplicate-ish pages you meant to merge, and suggesting links as you type.

zetl similar "Zetelkasten Method"

Zettelkasten Method        (distance 3)
Zettelkasten Workflow      (distance 7)
Luhmann's Method           (distance 11)

The number is Hamming distance on the hash — smaller is more similar. Zero would be identical.

What SimHash does, briefly

SimHash is a locality-sensitive hash: feed it a string, get back a fixed-length binary fingerprint such that similar strings produce similar fingerprints. Unlike a cryptographic hash (where flipping one letter scrambles the whole output), SimHash changes only a few bits when the input changes slightly. Comparing two hashes by Hamming distance — the count of differing bits — gives you a cheap similarity score without storing the originals.

zetl computes one hash per page name at index time. zetl similar then scans them and returns the closest N. No full-text comparison, no embedding model, no network — just arithmetic over bits. It finishes in under a millisecond for vaults of tens of thousands of pages.

The tradeoff: it only sees names. A page titled Dogs and a page titled Canine Companions are not similar to SimHash, even though they are the same topic. For content similarity, use zetl search --semantic (see Searching).

The three flags

Flag	Default	Use
`--threshold N`	`12`	Max Hamming distance to report. Lower = stricter
`--limit N`	`10`	Max results
`--json`	off	Force JSON output

The default threshold of 12 is tuned to catch typos and near-duplicates without flooding the output. Lower it to 6 if you only want obvious matches; raise it to 20 to see the long tail.

When to use it

Backlinks

zetl backlinks "Page" lists every page that links to Page. It is the quiet workhorse of a wikilink system — more useful, over time, than the links you write yourself.

zetl backlinks "Zettelkasten Method"

Output: the file path, the line of the match, and (with --context N) a snippet of the surrounding prose.

Why backlinks matter

Forward links are a claim you made at the time of writing. A backlink is every claim anyone ever made that referred back to this idea — including you, six months later, with more context. That asymmetry is the whole research payoff:

You read a paper and start a note on it. A year later the note has eight backlinks: three from project docs, two from meeting minutes, one from a book review. You did not plan any of that. The graph assembled it.
You are revisiting an old concept page. Instead of re-reading it in isolation, you walk its backlinks — every context in which you once found it relevant. That is a research tool disguised as a list.

Forward links (see Following Links) answer what does this page talk about? Backlinks answer what talks about this page? The second question is almost always more interesting for notes older than a few weeks.

Multi-hop with `--depth`

By default zetl backlinks returns direct, one-hop references. --depth N walks the reverse graph:

# Direct backlinks only
zetl backlinks "Zettelkasten Method"

# Every page that reaches "Zettelkasten Method" in up to 3 reverse hops
zetl backlinks "Zettelkasten Method" --depth 3

Depth 2–3 is where the transitive structure gets interesting: you find the notes that cite notes that cite this concept. Depth 5+ tends to return most of your vault — the graph is small-world.

What is SPL

Requires --features reason at install time. See Installation.

SPL is Spindle Lisp — a small Lisp-family language for writing rules. zetl extracts SPL from your vault and draws conclusions: “if a project is approved and has an owner, it’s ready to start”. This page is a gentle orientation; see Writing SPL for the syntax reference.

Why a second language at all

Most of your vault is prose — the thing humans are good at reading. But some knowledge is best expressed as a rule, not a paragraph. “Any release candidate must have a green test run and up-to-date docs” is easier to write (and check) as a rule than as a checklist you hope to follow.

SPL lets you write those rules inside your notes, alongside the prose they explain. zetl then reasons over all the SPL in the vault at once — a single combined theory — and tells you what follows.

The shape of SPL

SPL is parenthesised. Facts and rules are S-expressions:

(given docs-updated)
(given tests-pass)

(normally r-ready
  (and docs-updated tests-pass)
  release-candidate)

Reading top to bottom: two facts, then a rule named r-ready that says normally, if both facts hold, conclude release-candidate. Run reasoning and zetl will report +d release-candidate — defeasibly proved.

“Normally” is load-bearing. SPL is a defeasible logic: a conclusion can be drawn by default, and then withdrawn when stronger contrary evidence appears. See What is Defeasible Reasoning for what this means and why it matters for knowledge that isn’t strictly mathematical.

Searching

zetl search scans your vault for a string and prints the matches, with context. It is deliberately small: a fast text finder for when you remember a phrase but not which note it lives in.

zetl search "attention is all you need"

No regex engine, no query DSL. If you want regex, pipe the raw index through rg. What zetl gives you instead is graph-aware narrowing.

The two flags you will actually use

Flag	What it does
`--near "Zettelkasten Method"`	Only match pages within `--depth` hops of that page
`--case-sensitive`	Exact case, no folding

--near is the one most people miss. A keyword search over 4,000 notes gives you noise; a search restricted to “notes that cite Zettelkasten Method or one link away” gives you signal.

# Every note mentioning "CRDT" anywhere in the vault
zetl search "CRDT"

# Every note about CRDTs within two hops of my reading list
zetl search "CRDT" --near "2026 Research Plan" --depth 2

Other useful flags:

--path "journal/**" — glob filter on file paths.
--context 120 — widen the snippet from the default 40 characters.
--limit 200 — default is 50; raise for grep-replace workflows.

See CLI Overview for the full list.

JSON when piped

When stdout is a pipe or redirect, zetl search auto-switches to JSON. This is the contract that lets you chain searches into scripts:

Finding Orphans and Dead Links

The two main health signals

Dead links

Orphans

Syntax errors

zetl stats — the summary view

CI integration

SPL diagnostics

Example: pre-publish pass

Related

Backlinks

`zetl stats` — the summary view