| name | book-ledger |
| description | Natural-language access to book.db — project status, search, memory and context packs, canon, approvals, threads, continuity, tasks, retcons, and database health. Use to answer “where are we”, find what a character knows, locate open promises, approve a version, retcon a fact, or audit continuity. Translates requests into safe parameterized transactions. |
Book Ledger
Be the natural-language interface to book.db. Answer questions, retrieve narrow context, run approvals and retcons, and audit health — all through safe parameterized SQL. Read the relevant current state before acting; use BEGIN IMMEDIATE for material writes and commit only after validation.
This skill inherits every rule in AGENTS.md. It never overrides human creative authority or database safety. Route through $book-guide first for mixed requests.
What “true” means
Distinguish statement modes precisely:
canon — approved objective story truth;planned — provisional truth from an unapproved draft;author_intent — desired effect, not an in-world fact;belief — held by the context node;rumor — uncertain in-world report;lie — knowingly false in-world;hypothesis — analytical possibility;evidence — research/evaluation link;- and the absence of evidence (not the same as false).
Status and search
Use the queries in AGENTS.md (“Search and retrieval”, “First action in every session”). Typical asks: Where are we? What should we work on next? What does Mara know before Chapter 6? Where did the brass key last appear? Which Book 1 promises are still open? Show every version of the opening. Which scenes depend on the old magic rule?
Read only the context needed. The database has no full-text index by design; simple LIKE searches are sufficient for one series.
Approvals
“Approve this version” produces one transaction that:
- identifies the exact
text_version_id;
- marks it
state='approved' and is_current=1 (and demotes rejected alternatives if instructed);
- updates the unit node status where appropriate;
- promotes only the
planned consequences established by that version from planned to canon, preserving intentional beliefs, rumors, lies, and uncertainty;
- adds an
approval entry naming the version and scope;
- runs
PRAGMA foreign_key_check and the continuity audits before commit.
When version metadata is absent, inspect the exact prose to decide which facts that version established. Never promote every statement attached to a scene indiscriminately. Approval of a scene does not automatically approve a book synopsis, a market claim, or a later retcon.
Retcons
Never edit an old canon statement into a new meaning. In one transaction:
- find the old statement and its downstream dependencies;
- explain the creative and continuity cost and wait for explicit authorization;
- mark the old statement
retconned;
- insert the replacement;
- add a
decision entry explaining why;
- identify current manuscript units and open threads that depended on the old statement and create follow-up tasks;
- run continuity checks before commit.
Continuity and health audits
Run before and after large changes (AGENTS.md “Continuity and health audits”): text-parent mismatch; resolved thread without payoff; open thread that already has a resolution; conflicting functional facts ({"functional":true}); reversed validity windows; plus PRAGMA quick_check, PRAGMA foreign_key_check, and SELECT * FROM v_unreachable_nodes.
A database audit cannot judge whether a choice is believable or a payoff is satisfying — report those as editorial judgments, not database errors.
Definition of done
A ledger turn is complete when the author received a correct, narrowly-scoped answer or a safely-committed change, approvals/retcons were scoped exactly to the authorized version, integrity checks passed, and a receipt names the affected node codes and text-version IDs.
