Unwritten

Report the notes you never wrote: unexplained link pairs, stub hubs, and decisions with no stated reason.

Unwritten reads your vault's link graph and writes one note — Gap Report.md — listing the places where your notes point at something you never sat down and wrote. It is part of the Second Read suite.

What it is not

It is not a linter, and the report is not a to-do list. It says so at the top of every report:

This is a prompt, not a task list. Nothing here is a finding. These are three structural guesses about where your vault is thinner than your thinking — places where the notes point at something you never sat down and wrote. They are computed from links, word counts and frontmatter alone, so they cannot tell that you already explained a connection in a paragraph, and early on they will be wrong more often than they are right. Read them, ignore most of them, and write the one that makes you wince.

That warning is the honest position, not modesty. These heuristics see structure, not meaning. Every threshold is a setting, because the right ones depend on how you write.

The three heuristics

Unexplained pairs. Two notes keep being linked from the same places — three or more — and no short note links to both. Somebody keeps mentioning A and B in the same breath, and nobody ever wrote the note that connects them.

A note with six links or fewer that points at both counts as that note, and the pair is dropped. A map of content with thirty links does not: it is a shelf, not an explanation. That distinction is the whole heuristic.

Stub hubs. Eight or more notes point at a note that says a hundred and twenty words or fewer. The vault treats it as load-bearing; the text does not.

Decisions with no stated reason. A note with decision: true in its frontmatter (or a #decision tag) that has no ## Rationale / ## Why / ## Because / ## Reasoning heading and no line that says because. The choice is recorded; the reasoning is not.

Use

One command: Generate the gap report. There are no listeners, no background indexing and no editor extension — nothing runs while you type. It reads the metadata cache, writes the report, and goes back to sleep.

Regenerating overwrites the report. If you have edited it, you are asked first, and one of the answers is "save as a new file" — so your notes on the notes are never eaten.

Settings

Everything is tunable: the report's location, the co-occurrence threshold, the bridge size, the index-note cutoff, the hub thresholds, the frontmatter key that marks a decision, the headings that count as a reason, and the folders to exclude.

Privacy

Unwritten does not phone home. It sends no telemetry, and it makes no network request of any kind unless you click Download engine in settings (see below). The license check is offline Ed25519 signature verification — there is no account and no server.

The only thing it writes into your vault is the report note, at the path you choose.

Pro

One key unlocks Pro in all five Second Read add-ons — Note Decay, Standing Questions, Effort Index, Prior Art, and Unwritten. Unwritten's Pro tier adds two sections to the same report:

• Evidence — for each unexplained pair, the passages that are about both halves. Every passage is scored against each half separately and kept only if it clears the bar on both, so a paragraph that is merely about one of them cannot qualify. A pair with no evidence is reported as exactly that: nothing you have written explains this, which is the strongest thing the report can say.
• Latent topics — a subject you keep touching across four or more notes, in passages that say nearly the same thing, with no note at its centre. A topic that already has a note about it is not reported: you wrote it.

Both read your notes by meaning rather than by structure, and that needs a local semantic engine.

Second Read Pro — $29 one-time. One key unlocks Pro in all five Second Read add-ons (Note Decay, Standing Questions, Effort Index, Prior Art, Unwritten). Buy here: https://buymeacoffee.com/vaultspotlight/e/560213 — the key is emailed to you automatically, within seconds (delivery is fully automated), pasted into settings, and verified offline.

The semantic engine (what it is, and what it does to your computer)

This is the disclosure. Read it before you click anything.

• The engine is a separate program (embed-sidecar), published in the open at second-read-engine. It turns passages of your notes into vectors so they can be compared by meaning.
• Nothing is downloaded, unpacked, made executable or run until you click "Download and run" in a modal that first shows you the exact URL, the version, the SHA-256 it must match, and the directory it will be written to. There is no download at startup and no silent update, ever.
• The downloaded bytes are verified against a checksum baked into this add-on at build time before anything is extracted and before any exec bit is set. On a mismatch the file is deleted and nothing runs. A build with no pinned checksum — like this one — refuses to download at all.
• It is installed OUTSIDE your vault, in your system's application-data folder (%LOCALAPPDATA%, ~/Library/Application Support, or $XDG_DATA_HOME), so it is never synced to your other devices. This add-on therefore reads and writes files outside the vault, and that is the only reason it does.
• The engine opens no network connections. It reads only the text this add-on sends it over a pipe, it writes its index next to itself, and it exits when Obsidian closes.
• It is shared with the other Second Read add-ons: one program and one index however many of them you have installed, refcounted so the last one to unload kills it.
• You never have to use it. Point "Path to an existing engine" at a binary you built yourself and nothing is ever downloaded.

Everything outside this section is free, needs no engine, works offline, and works on mobile. When the engine is missing, the Pro sections are not silently omitted from the report: it says they did not run, and why.

Install

Community plugins (recommended): open Settings → Community plugins, search Unwritten, and install it — one click, auto-updates.

To build from source instead:

npm install
npm test
npm run build
VAULT=/path/to/your/vault npm run install:vault

License

MIT. See LICENSE.