Sample-novel walkthrough
The Salt Ledger is the sample novel that ships with the repo: 24 pages, three characters (Kael, Vess, Immy), one arc, three scenes — every layer of Keel populated. This lesson touches every feature once, in the order you would really use them. Budget: twenty minutes.
1 · In: launch and sign in
Open keelhelm.exe. At the login: your password, Enter.
(Or F2 for dev mode — the lesson works either way.) Pick
the-salt-ledger in the series picker.
2 · The Map — walk the spine
You land on the map, in INTERACTIVE mode (the badge top
right). The rail's tree is two levels: arc rows in bold, scene rows under
them with status glyphs — everything in the sample is ● canon. Press
j and k (or click a row): the selection moves,
the detail box under the tree shows the selected scene's contract,
and the center pane previews its prose.
The ⚠ frontier warning on the tree's border says s-0003 is the last scene with prose — the book runs dry after it. A warning, never a block.
3 · Enter — write in a scene
With a scene selected, press Enter. Keel checks the scene out (you hold its lock now) and opens the editor directly — the thick cyan ✎ border, the badge flips to EDITING, and you are typing immediately. You edit the prose body only: the YAML contract in the frontmatter is held aside and re-attached when you save. The keys are vim-lite:
| i / Esc | insert text / normal mode — Esc again taps out to the app |
| h j k l · w b e | move by character, line, word |
| dd · cw · yy · p · u | delete line, change word, yank, paste, undo |
| ^s | save · the foot shows ●unsaved until you do |
| ^f | focus — dim everything but the current paragraph |
Type a sentence. One sentence per line is the house style — Keel keeps diffs readable that way.
4 · ^m — markup
Press ^m. With no selection you get block directives — pick
break to drop a @break scene break, or
page to drop an @page marker, which subdivides a
long scene into drafting pages (it renders as nothing; the foot shows
page 2/5 and ^PgUp/^PgDn jump the
seams). Select a few words first (v in normal mode) and ^m offers inline
directives instead: think wraps the selection as
@think{...}, interior monologue the typesetter renders in
italics.
5 · ^g — davy
Type what you want, Enter — the draft streams in (the context is
pre-warmed in the background, so davy starts instantly); a
accepts it into the scene, r rejects. Nothing is ever written
without your accept, and accepted spans are logged (the foot's ✎% shows AI
density). Press ^; before generating to inspect the exact
context the DAVY sees — every section pinnable.
ANTHROPIC_API_KEY set in
your environment. Without it you get the honest refusal — "no AI
provider configured" — and everything else in Keel still works.6 · The console — every feature has a command twin
Save (^s), tap out with Esc, and open the
console: ^p, then type :. Any keel verb runs in
place, output in an overlay. Proofread your edited scene:
The proofread mark is per-revision — edit the scene again and the foot's
⚑ returns to unmarked, visibly, in :status and at render time.
Explore the ledger the sample seeded:
Two more habits worth forming here: ^k opens the comment
threads on the open scene — feedback written on the yard's scene edit page,
d marks a thread done — and keel review s-####
sends a ○ draft scene into ◐ in-review, queued for the book admin's Approve
on the yard's activity page. The sample is already ● canon, so nothing to
send today.
7 · Amend a scene — the blast radius
The centerpiece. Change a canon scene's contract and watch Keel
compute what that breaks. Check the scene out from the console, change
output: in its YAML frontmatter in any text editor (the
working file is the whole document under checked-out\ — or use
the yard's scene edit page), then:
Landing is refused while a ⛔ stands. Reconcile the successor into the changeset, then land — everything flips canon in one transaction, and the unreconciled ⚠ becomes tracked debt:
8 · worldline, review, the book
Click review on the toolbar: a-1 is listed as landed.
Click worldline: the three scenes lie on a horizontal
line — c for reading order, t for story time
across the five eras, ↑↓ selects, Enter opens a scene. Then press
F5: the whole book typesets — the real pages appear in the
app (←→ turns them) and the book PDF opens beside it.
Finally, from the console:
You have now touched everything
The spine and its frontier, the editor, markup, davy, proofreading, the ledger, an amendment with a real blast radius, the worldline, and the book itself. Where to go deeper: the writing workflow · the spine handbook · davy · amendments & blast radius · the book pipeline.