Design rationale

Keel is opinionated. Every opinion below was argued out before the first line of code, and each one closes off a class of failure that plagues long manuscripts. This chapter preserves the why — so that when a rule gets in your way, you can weigh the reason before working around it.

Why strict RCS, and no git at all

Git is optimistic: everyone edits freely and conflicts are merged afterwards. RCS is pessimistic: take the lock and conflicts never happen. Layering one on the other fights itself — a lock means nothing when anyone can commit locally, and branches have no purpose when nothing ever diverges. So Keel keeps the half that matters for prose and drops the rest: every editable thing is an object with an exclusive lock, revisions are immutable and monotonic, and reads are always free.

Two subsystems got simpler the day git left: review stopped being a branch and became a status column, and retroactive edits stopped being branches and became changesets — named sets of pending revisions that land atomically or not at all. And offline got better, not worse: the lock is your offline token. Check out before you fly; nobody can touch the leaf until you return.

Why the write gate

No leaf exists outside the spine. A leaf can only be created on a beat that is specified or better — there is no command that makes a floating scene, so orphan prose is unrepresentable rather than merely discouraged. The second rule keeps the first from being tyrannical: a leaf's status can never exceed its beat's, which means you can draft freely against a pending beat — the prose simply cannot outrun the structure it serves. When the prose fights the beat (and it will), you amend the beat. That friction is the feature: the structural change becomes explicit and blast-radius-checked instead of the manuscript drifting silently away from its outline. That drift is the exact failure this tool exists to prevent.

Why "leaf"

The writing unit was called a scene until the obvious word arrived. A leaf is the terminal node of the keel — the tree ends and the words begin — and it is also the bookbinder's word for a sheet of the book. The leaves of the spine become the leaves of the book. Ids stay s-#### on the wire so nothing old breaks; the language is leaf everywhere a person reads it.

Why two clocks

Allowing flashbacks forces apart two questions a linear book conflates: is this fact true right now? (story time) and does the reader know it yet? (narrative order). Keel keeps both orderings and never substitutes one for the other — true_at answers the first, known_at the second. The payoff: a memory scene set forty years earlier can state a fact the reader has not met without the continuity machinery screaming, while the do-not-reveal list still knows that fact is spent for everything downstream in reading order. In a flashback, that list is the only thing keeping the scene from leaking the future.

Why the Yard holds objects, not reasoning

Every deterministic rule — the spine graph, the ledger, blast radius, allocation, diffing — lives in the binary and runs locally. The Yard stores objects, revisions, and locks, and does what needs a secret key. It reasons about nothing. This is why the same schema sits behind SQLite locally and Postgres hosted, why the TUI cannot tell the difference, and why both surfaces can edit the same spine with divergence impossible by construction. It is also why revisions being immutable makes the hosted cache trivially correct: content by (object, revision) can be cached forever; only "what is head?" ever needs the network.

Why one binary, local-first

keel.exe is a copy-paste install: no runtime, no interpreter, no package manager on the writing machine. The whole system — TUI, Yard, Postgres — builds and runs locally under docker compose before anything touches a host. For a tool meant to hold a decade of work, the ability to run every part of it on one unplugged laptop is not a convenience; it is the durability story. The same instinct puts working copies on disk as plain text: anything checked out survives any outage of anything.

Why proofread marks are per-revision

A proofread that survives edits is a lie waiting to be printed. The mark records which revision was proofread; touch the leaf and the mark is gone, visibly. Enforcement is deliberate too — tracked and warned at render, never blocking a drafting session. The gate hardens only where mistakes become expensive: at the book.