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

Feedback and support

Bug reports, feature requests, and questions all go to the GitHub issue tracker. It is the only place I track them, so an issue will always get further than a review comment.

• Report a bug — please include your Obsidian version, your operating system, and the steps that reproduce it.
• Request a feature — describe the workflow you are trying to make faster; that is more useful than a proposed solution.
• Browse open issues — worth a look first, in case it is already tracked.

More plugins by the same author

Small, local-first Obsidian plugins that each do one job and keep your data in your vault. All of them are in the community directory — search the name under Settings → Community plugins.

Search and views

• Vault Spotlight — keyboard-first command center — fuzzy search, saved workflows, and result actions.
• Bases Power Pack — kanban, calendar, Gantt, and outline views over your notes or a .base file.

Vault health

• Vault Triage — find stale, orphaned, unfinished, and metadata-broken notes, then work through them.
• Attachment Audit — find orphaned, duplicate, oversized, and misplaced attachments, then clean them up safely.
• Patina — score every note's staleness from edits, opens, and inbound links.
• Vault Router — move new notes out of Inbox with fast local routing rules.
• FlowKit Health Dashboard — find which add-on is breaking your vault, and score every one installed.

Writing and research

• Prose Lens — live writing feedback — passive voice, adverbs, hedges, cliches, and a reading grade.
• Prior Art — show similar existing notes while you write, and merge duplicates without losing links.
• Standing Questions — track the open questions in your vault and surface new notes that may answer them.
• Effort Index — measure the editing time behind every note and resurface the expensive ones.

Time and billing

• Task Calendar Bridge — export dated Markdown tasks to standards-based ICS calendar files.
• Invoice Forge — turn #billable notes into numbered invoices, so nothing is missed or billed twice.
• Time Tracker and Invoicing — track billable time against notes and projects, then invoice by client.

License

MIT. See LICENSE.