# Book Ledger

> 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.

- Skill: `nibzard/book-ledger` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nibzard/book-ledger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nibzard/book-ledger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: nibzard (https://skillmd.com/u/nibzard)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nibzard/book-ledger

---


# 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:

1. identifies the exact `text_version_id`;
2. marks it `state='approved'` and `is_current=1` (and demotes rejected alternatives if instructed);
3. updates the unit node status where appropriate;
4. promotes only the `planned` consequences **established by that version** from `planned` to `canon`, preserving intentional beliefs, rumors, lies, and uncertainty;
5. adds an `approval` entry naming the version and scope;
6. 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:

1. find the old statement and its downstream dependencies;
2. explain the creative and continuity cost and **wait for explicit authorization**;
3. mark the old statement `retconned`;
4. insert the replacement;
5. add a `decision` entry explaining why;
6. identify current manuscript units and open threads that depended on the old statement and create follow-up tasks;
7. 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.