Troubleshooting & roadmap
Keel fails loudly on purpose — every error names the object, the reason, and usually the cure. This page maps the messages you will actually meet to what they mean, then lays out what is coming next.
"object … is checked out by … (since unix …)"
Someone — usually you, in another window or an open TUI session — holds
the exclusive lock. keel status shows every lock with its age;
keel co -l shows yours. If it is your own lock, finish the
thought: keel ci releases it (an unchanged check-in releases
the lock without creating a revision). Breaking someone else's lock is
deliberately absent from the MVP — the admin break arrives with M8 roles,
announced and never silent.
"INTEGRITY VIOLATION … check-in base rev X != head rev Y"
The loud one, and deliberately so: under exclusive locking this state
should be impossible, which is exactly why a silent success here would be
the bug worth catching. It means the object's head moved while you held
what you believed was the lock — in practice: an amendment was abandoned
under you, or something bypassed the store. Do not retry blindly. Inspect
keel log <id>, compare your working file against the head,
and re-checkout. Your text is never lost — the working file in
checked-out/ stays on disk through every refusal.
"the TUI is login-locked and the Yard did not accept your session"
You are signed in, but the Yard is unreachable or rejected the token.
Either start it — docker compose up -d in the repo — or drop
to local dev mode with keel logout. Inside the TUI, the login
screen offers F2 for dev mode directly. The seeded MVP login is
admin / mvp, printed on the admin
login page itself.
A key does nothing (?, F-keys, glyphs look wrong)
Two usual causes. First: you are running a stale binary — after any
update, quit the TUI and relaunch with
start-keel.ps1 -Rebuild (a running keel.exe locks itself and
silently blocks rebuilds). Second: the legacy console — Keel's supported
host is Windows Terminal; conhost mangles function keys
and the tree glyphs. F1 always opens help even where shift-key reporting
is odd.
"could not run typst" / "could not run pandoc"
The book pipeline shells out: Typst typesets the PDF, pandoc builds EPUB/DOCX. Both errors say exactly this; both installs are one line.
Plank refuses a check-in
@quote is never closed, @chapter is structural —
the leaf's markup has errors, and broken markup cannot land. The message
lists each problem with its position; keel plank check s-####
re-runs the diagnosis. Structural directives (@chapter, @part…) are
emitted from the spine at render time and never typed — that refusal is
the two-tier rule doing its job.
Where things live
The index is derived data: deleting it costs nothing,
keel index --rebuild reconstructs it byte-identically. The
store is the book — that is what snapshots, exports, and (hosted) the
Yard's Postgres protect.
The road ahead
M8 — the Yard grows up. Store::Yard lets the TUI open hosted series over HTTP, reading through a local cache that immutable revisions make permanently valid — only head lookups touch the network, so navigating leaves never re-pulls what you have seen. Project setup moves fully into the web admin, joined by the spine planner (tree, card forms, chapter allocation — planning sessions in the browser, write-time spine work stays in the TUI). Roles arrive with admins as de-facto editors, sovereign zones for delegated arcs, and the nightly export job. Version 1.0.0 lands with the local MVP go-live.
Chosen features, order TBD — the owner's kept picks:
- Three-variant DAVY — the spec's N=3 drafts as tabs
- Beat-contract verifier — does the prose deliver enters→exits?
- Reader simulation — a first-read report per chapter
- The Architect — proposed movements/beats against the stated ending
- Entity quick-capture — @ref on an unknown name offers to create it
- Worldline branch — the one permitted branch, rendered
- Styled exports — EPUB cover and CSS, print-ready PDF
- Preview navigator — chapter jump list with live page numbers