keel.pub yard
Getting started Hierarchy & glossary Sample-novel walkthrough

Hierarchy & glossary

Keel's structure mirrors how planned novels are actually written, not an invented scheme: rough shape far from the pen, full detail only where you are about to write. Four levels, and the top two carry almost nothing.

SERIES VOLUME one book ARC ~3 / volume · holds the spine SCENE contract + prose THE KEEL — the arc's ordered scene list is the spine scenes: s-0005 s-0007 s-0006 the order on the arc card IS the spine — reorder by editing one list; flat s-#### ids never change. a stored scene on no arc's list shows as unlisted — never hidden. Series and Volume are containers: a premise and an intent, one sentence each. Nothing checks them. The arc card carries the ordered scene list; only the scene has a contract and words. What the reader meets (via the Frames): Volume → Part (≈ arc) → Chapter (allocated scenes) → scene breaks between scenes
The chain. The arc card carries the ordered scene list — the Keel; each scene is one document, contract over prose.

The recommended shape of a novel

~3 arcsper volume
3–8 scenesper arc
~2,400 wordsper scene ≈ 8 printed pages
~300 wordsper printed page (novella trim, 60 characters × 35 lines)
You never lay all of this out up front. The spine is deep near the pen and shallow further out: series premise and ending, arcs for volume one, scene contracts in detail only where you are about to write. Arc III can be a one-line premise for a year.

Glossary — the modules

Keel — three things at once: the product, the one binary you run, and the narrative spine itself (each arc's ordered scene list). The keel of a ship is laid first; everything else attaches to it. The modules take keel.x names: keel.helm (the app), keel.pub (this site), keel.yard (the editors' section inside it), keel.davy (the AI layer).

keel.pub — this site, the web surface as a whole: the home page, these docs, logins, published book previews, and the admin.

The yard — keel.yard, the editors' section of keel.pub: your books, the spine tree, card editing, scene comments, book design, and the approval queue. A shipyard is where ships are built and serviced.

loft — the world bible: characters, locations, factions, lore, and the world calendar. In shipbuilding, the loft is where full-size drawings are laid out before any wood is cut.

Frames — the join between the story you build and the book the reader holds: scenes allocated into chapters with page budgets. Allocating a scene that is not yet canon warns, never blocks — allocation is the admin's post-canon step. The ribs on the keel.

planking — the prose layer as a whole: every scene's plank body. The hull boards fastened over the frames.

Scene — where writing happens, and one stored document: a YAML contract between --- fences (id, title, status, input, output, overview — plus pov, story time, and word budget when you want them) over the plank prose body, ~2,400 words. Flat s-#### id; its position lives on the arc card, never in the id.

Pages — @page void markers inside a scene body: drafting subdivisions that render as nothing in the book. While they exist the editor's foot shows page 2/5, and ^PgUp/^PgDn jump between the seams.

plank — the markup language scene bodies are written in: @quote … @end quote, @think{...} style directives plus ordinary markdown emphasis. Structural markup is emitted from the spine, never typed.

ledger — the return loop: facts extracted from canon prose (with story-time validity and reveal positions), promises with due-bys, and quote-anchored references — all anchored to scene ids. What later scenes must not contradict.

davy — keel.davy, the AI writing partner behind ^g: drafts against the scene's contract with a fully inspectable context; nothing lands without your accept.

worldline — the worldline view: every scene as a mark on a horizontal line, in reading order or laid across the five story eras.

the helm — keel.helm: the writing app itself (keelhelm.exe, launched from a shortcut, no arguments) and the hand-built editor at its heart — one name for both. Soft wrap at the printed measure, typewriter scrolling, vim-lite keys, decoration spans, wrapped in the shell layout of head strip, left rail and foot strip.

Lenses vs views — a view (the toolbar chips) fills the center pane; a lens (Tab, or click its tab) picks what the narrow rail glances at. Views hold detail, lenses hold orientation.

Review statuses — every scene carries one: ○ draft → ◐ in-review → ● canon. keel review s-0007 sends a draft into the yard's approval queue; the book admin's Approve lands status: canon.

Genesis — the three cards a book starts from: series, volume, arc. Once they exist, any editor or admin writes immediately — nothing stands in front of prose; review comes after the words, per scene.

The frontier — the last scene in tree order that has prose: where the book runs dry. Marked in the map, warned about — never a block.

Amendment — changing a canon scene's contract is a migration: keel amend computes the blast radius — a changed output means the successor's input must be re-satisfied (⛔), a changed input points back at the predecessor's output (⛔), promises and facts anchored in the scene get a ⚠ — then collects the fixes into a changeset and lands them atomically.

Snapshot — a named pin of every object's revision (keel snapshot draft-one) to diff against later.

Next

See it all in motion: the Salt Ledger walkthrough, or go deep on the spine handbook.