git:20261003.d98807a to git:20261007.e971a0c

- description: This skill should be used when the user asks to validate, reindex, repair registries, check links, check continuity, count words, summarize a story project, import an existing manuscript, export a manuscript, build a review copy or print interior, generate a diagram, check pacing, clues, voices, or names, track revision passes, run the story CLI, or perform deterministic maintenance on a Story Skills markdown project.

- Run deterministic maintenance for Story Skills projects. Use the CLI for structure validation, registry rebuilds, word counts, link checks, continuity checks, project reports, next-action reports, pacing, clue, voice, and name checks, revision-pass tracking, Mermaid diagrams, schema migration, entity helpers, manuscript import, and manuscript export and builds. The creative skills still own story decisions; this skill handles mechanical consistency.

- 2. `bun run story -- <command>` - when working from this repository

- 3. `node scripts/story.js <command>` - bundled fallback, resolving `scripts/story.js` relative to this skill folder

- If none of these are available, perform the requested maintenance manually using the conventions in `story-init`.

- story validate .

- story names "Mira" "Kelvos"

- story import draft.md --title "Title"

- story add character "Name"

- story add character "Пётр"

- story add character "李明" --id li-ming

- story add matter "Dedication"

- story add research "Tidal bore timing" --source "Tide tables 2024" --used-in chapter-03

- story add research "Night shift on a cardiac ward" --method interview --accuracy must-be-accurate --confidence medium --risk medical

- story add matter "Acknowledgments" --placement back

- story rename character old-id "New Name"

- story rename character petr "Пётр Иванов"

- story rename character li-ming "李明华" --id li-minghua

- story add clue "The silver locket" --planted chapter-02 --payoff chapter-05

- - `continuity` after drafting or revising a chapter, and whenever the user asks about contradictions, dead characters appearing, unfired setups, or stale state; it deterministically checks `died-in` ordering (and warns when a character `deceased` with no `died-in`, dead before the story, is in a cast; `revived-in` ends the dead window, a `died-in` outline chapter is a planned death, not in force, so the character may keep `status: alive` and a later cast is allowed until that chapter is drafted, a `pov` also in `mentions` is a posthumous narrator rather than an appearance, and chapters dated on both sides compare by story date, not number; a character `status` progression to `deceased` with no `died-in` counts as the death for later casts and learning, and a status progression that contradicts `died-in` or `revived-in` warns), promise/question chapter ordering, Chekhov gaps, POV/cast consistency, `status: cut` characters still listed in a chapter or scene `pov`/`characters`, an arc's `characters`, or a relationship (warnings), and `continuity/state.md` references, plus warnings where `continuity/state.md` disagrees with scene `state-changes` (a `character` + `knowledge` change with no `knowledge-state` entry learned by that chapter, an artifact `owner`/`location` set by a later scene), with deaths (knowledge learned after dying, `character-state` for a dead character), or with casts (a `learned-in` chapter that does not list the learner, a `character-state` location the `current-chapter` never visits). It reuses the promise-ordering machinery for the clue ledger (`continuity/clues/`): payoff before plant is an error (also when the planted chapter is a scheduled `chapter-NN` not written yet), and a completed story with planned or planted clues is an error. The Chekhov warning requires `status: planted`: it fires as soon as a recorded payoff chapter has been drafted, or, with no payoff recorded, once three or more chapter files follow the plant (positions, not chapter numbers). An open question with no `resolved` chapter warns `question-unanswered` once twelve or more drafted chapters follow `introduced`, counted the same way; the finding stays a warning, and an open question is an error only once `story.md` is `complete`. Exempt one question meant to stay open with `code: question-unanswered` and its file, or set that code's `severity` to `off` to silence all of them. `story add clue --planted` (and `story add promise --planted`) records the chapter and sets `status: planted` when that chapter exists; with `--planted` naming a chapter not written yet, or without `--planted`, the status is `planned`, and `--status` overrides either default. A promise or clue with `status: planned` and a `planted` chapter warns ("records planted chapter X but status is still planned") only once chapter X has prose, so `--status planned --planted chapter-NN` schedules a setup ahead. Both warnings read the named chapter's own `status`: an `outline` planted or payoff chapter does not count as drafted, even when later chapters are. A recorded payoff chapter that is not drafted yet suppresses the "no payoff yet" warning. `story links` accepts a scheduled `chapter-NN` that has no chapter file yet in `payoff`, in `planted` while the status is `planned`, and in a research note's `used-in`, unless its number is 0 or belongs to an existing chapter under another id (`chapter-1` beside `chapter-01` is reported as missing); once the status is `planted` or `paid-off` the planted chapter must exist, and once `paid-off` the payoff chapter must too. It also checks prop custody — artifacts with `destroyed` or `lost` status must not be referenced after their destruction chapter (recorded in object-state `since: chapter-NN`; later scenes referencing them in `state-changes` or `mentions` are errors; an entry with no `since` was destroyed or lost before the story, so any scene `state-changes` using it is an error while `mentions` stay allowed; a later entry for the same artifact with another status and a later `since` ends a loss) — and clock/time plausibility when scenes or chapters carry `date: YYYY-MM-DD` / `time: HH:MM` frontmatter (time may be `dawn`, `morning`, `midday`, `afternoon`, `evening`, or `night`; dated units are scenes, or a chapter with no scene records, in reading order, the same units `story timeline` shows; a unit that cannot fall after the latest moment reached warns as running backward and does not reset that moment, with named times read as the same spans as the route check and each chapter `strand` keeping its own clock; scene `travel-hours: N` asserts the minimum time since that moment; a character, by scene `characters` or `pov` (the chapter's `pov` when the scene has none), in two dated scenes on the same chapter `strand` (chapters without one share a strand) at locations linked by location `routes`, with less story time between them than the fastest route, is an error, and so is a character at two different places at the same exact `HH:MM` on one strand whether or not routes join them; a sighting in another strand is not the other end of a journey. The route check reads scene `date`, `time`, and `location` only, not chapter dates; a named time is a span such as `morning` 05:00-11:59, an untimed scene spans its whole day, and only journeys impossible on every reading are reported). Without dates, only malformed dates or times and `travel-hours` on an undated scene are reported. Intentional exceptions go in `continuity/exemptions.md` (frontmatter `type: exemption-log`, entries with a `reason` and the finding's `code` plus its `file` or `chapter`, as `--json` diagnostics give them; `pattern` matches message text and still works); exempted findings are reported as dismissed, not errors

- - `compare` after a revision pass, or when the user asks what changed since a draft: `--ref` reads chapters at a git branch, tag, or commit with `git show` (it never writes to the repository), and `--against` reads another copy of the project. It reports per-chapter word changes, added and removed chapters, and the share of paragraphs unchanged. With `--anchor <label>` (repeatable) it instead maps review-copy paragraph labels from that draft to the current text, one line per label: `ch01-p20 -> ch01-p21 (text unchanged)`, `(edited, NN% similar)`, `not found in the current text ("first words…")`, or `no such label`; use it to resolve reader notes from an older build. See Draft Snapshots in the `revision-continuity` skill for taking the snapshot

- - `similarity` when the user asks whether a passage echoes another text too closely: their earlier books, a previous draft, or a source they worked from. `--against` takes a file, a folder (another story project's chapters, or every `.md`, `.markdown`, and `.txt` file in it), or a git ref. It reports each run of `--min-words` (default 8) or more shared words, compared lowercased without punctuation, as a `similarity-shared-passage` warning with the chapter's review-copy label, the reference's location, and the shared words, then per-chapter and total shares. It is advisory and exits 0. Shared text is not proof of copying, so report what it found and where, never a verdict; see the `editorial-review` skill

- - `progress` when the user asks how far along the book is, whether they will make a deadline, or after a writing session: it reports words against `story.md` `target-words`, days left to `deadline` and words a day needed, chapter `target-words`, and pace from `progress.md`. `--log` records today's total there (`--date YYYY-MM-DD` to backfill); only log when the user keeps a log or asks for it

- - `pacing` when the user asks about pacing, sagging middles, or chapter endings, and after drafting or restructuring chapters: per chapter it shows words, scene and sequel counts, scene `outcome`s (`yes`, `no`, `yes-but`, `no-and`), and the chapter `hook` (`cliffhanger`, `question`, `revelation`, `reversal`, `decision`, `emotional`, `resolution`). It warns about three or more consecutive `yes` outcomes, four or more scene units with no sequel, chapter length outliers (over 2x or under 0.5x the median once three chapters have prose), three or more consecutive chapters ending on `resolution`, and drafted chapters with no `hook`. See the `plot-structure` and `scene-craft` skills

- - `clues` for mysteries and any story with a clue ledger: prints a clue-by-chapter matrix (`P` planted, `R` payoff, `x` both, `.` none; `~` after a clue name marks a red herring) and warns about a payoff with no plant, a late plant (same chapter as the payoff, or the one before), a clue with no `characters`, three or more genuine live clues (not red herrings) with none `significance-delayed`, and a `red-herring: true` clue with no `payoff`. See the `genre-craft` skill

- - `voices` when dialogue voices may blur or during a line pass: attributes quoted lines (straight, curly, or British single quotes) to the character the narration names next to a speech verb (`"...," Mara said`, `said Mara`, `Mara asked`, aliases included; a name before the verb wins), or else to the only character the paragraph names (an action beat). Pronoun tags (`she said`) are never attributed, so a close-third POV character is often under-counted. It reports lines, words, mean sentence length, contraction, question, and exclamation rates, and signature words. It warns when a character says a `voice-avoid` word, when two characters with five or more lines have near-identical fingerprints ("X and Y may sound alike: ..."), and when a `voice-words` entry is never said. See the `voice-style` and `line-editing` skills

- - `--json` when you need to read a result rather than show it to the user: `validate`, `links`, `continuity`, `series`, `report`, `next`, `doctor`, `knowledge`, `context`, `progress`, `timeline`, `prose`, `pacing`, `clues`, `voices`, and `similarity` then print one JSON object on stdout (`apiVersion`, `command`, `ok`, `data`, `diagnostics`, `writes`). `ok` is true exactly when the exit code is 0; each diagnostic has `severity`, `file`, `message`, `code` (the finding's rule, such as `stale-word-count`, the name a `story.md` `severity` entry takes), and `check` (the check that raised it). `report`, `next`, and `doctor` always have `ok: true`, so read their `data.checks` or error diagnostics instead

- - `passes` to track named revision passes in `story.md` `revision-passes` (`{pass, status}`, status `pending`, `in-progress`, or `done`). `--init` writes the default ladder (`structure`, `character`, `theme`, `continuity`, `pacing`, `line`, `copyedit`, `proof`) and keeps existing entries; `--start <pass>` and `--done <pass>` update one; with no flag it prints the checklist and the checks each default pass runs. When the story `status` is `revising`, `next` recommends the next unfinished pass. See the `revision-continuity` skill

- - `names` before naming a character, place, faction, artifact, system, or glossary term: `story names <name...>` checks candidates against every existing name and alias. A candidate's given name (first word that is not a title or article such as `the`, `lord`, or `captain`) is compared with each character's given name, and everything else as a whole name; an exact match with either is a clash, an error (exit 1). Look-alikes (the same first four letters, or the same initial within edit distance 1, or 2 when both words have five letters or more) and a given name sharing an initial with a protagonist, antagonist, deuteragonist, or narrator are warnings. Multi-word names are only checked for exact clashes, so pass a multi-word name's distinctive words separately. Pass `--path <project>` when not in the project root

- - `timeline` when the user asks what happens when, how flashbacks sit against the main line, whose POV dominates, or where a character drops out: it orders dated scenes (and chapters without scene records) by `date` and `time`, marks entries told after later events, lists undated scenes in reading order, totals chapters and words per POV, and reports each character's chapter presence, longest absence, and absence from the final chapters. It is read-only; `continuity` owns clock errors

- - `prose` when the user asks for a prose check or before sharing a draft: per chapter it counts sentence length and spread, filter words and -ly adverbs per 1,000 narration words, plain and said-bookism dialogue tags, echoed words, watch words, and avoided spellings from `style-sheet.md` (`dialect`, `preferred`, `watch-words`, `allow-words`); across the manuscript it lists repeated 4-word phrases and similar character first names. Findings are advisory warnings and the command exits 0 unless `story.md` `severity` promotes one. `--max-filter-words <n>` (default 10), `--max-adverbs <n>` (default 12), and `--max-bookisms <n>` (default 2) change the warning thresholds. See the `voice-style` skill for acting on them

- - `import` when the user has an existing manuscript or chapter drafts and wants a Story Skills project built from them; follow up by creating character and location files from the printed entity candidates, and by setting `form` and `target-words` in `story.md` (import refuses `--form`; without them `story validate` never checks length and `story progress` has no target). Directory sources import in natural file-name order (`chapter-2` before `chapter-10`). `import --force` into an existing directory deletes every `chapter-NN.md` in `chapters/` before writing the imported chapters, so confirm with the user before forcing an import over a project with drafted chapters

- - `doctor` when the user asks what is stale, broken, or inconsistent

- - `add`, `rename`, `move`, and `remove` for deterministic entity file operations when they fit the requested change. `add` takes ids, not names, for reference options (`--planted chapter-01`, `--pov mara-quill`), and `add scene` needs its chapter to exist, so add the chapter first. Ids stay ASCII kebab-case. Cyrillic and Greek names are transliterated (`story add character "Пётр"` writes `characters/petr.md` and keeps `name: Пётр`), but a name in a script with no transliteration table (`李明`) needs the id by hand: `story add character "李明" --id li-ming` writes `characters/li-ming.md`, and `story rename <kind> <id> "<New Name>" --id <new-id>` does the same on a rename. `--id` is refused for chapters and scenes, whose ids come from their numbers. `remove chapter` refuses while scene files point at the chapter, so remove those scenes first; it walks back ledger statuses that relied on the chapter (planted to planned, paid-off to planted or planned, answered or resolved questions to open), so review the ledgers afterwards

- - `move` whenever a chapter's number or a scene's chapter or position changes, never a hand rename: chapter and scene ids encode their numbers. `story move chapter <id> --number <n>` renames the chapter and its scene files, sets `number` and the `# Chapter N:` heading, and rewrites every reference to the old id (scene `chapter`, clue and promise `planted`/`payoff`, question `introduced`/`resolved`, research `used-in`, `died-in`, `continuity/state.md` `since`/`learned-in` and `current-chapter`, markdown links, and bare ids in `plot/timeline.md` and arc bodies). A taken number is refused (`chapter-05 already exists: move it first. To make room, renumber from the highest chapter down`), so to insert a chapter move the later chapters up one, highest first, then `add chapter --number <n>`. `story move scene <id> --chapter <chapter-id>` moves a scene to the next free number in that chapter (`--scene <n>` picks the number, and `--scene` alone reorders within the chapter) and adds its location and characters to the new chapter; give at least one of the two. `move` works only on chapters and scenes (use `rename` for other ids), never edits prose or outline beats that mention a chapter number, and reindexes. References are written before the files move, so rerun an interrupted move. See the `revision-continuity` skill for splits and merges

- - `add matter` when the user wants a dedication, epigraph, copyright page, acknowledgments, author's note, about-the-author, or also-by page. Pages live in `matter/` (indexed in `matter/_index.md` by reindex) with `title`, `placement` (`front` or `back`), `order`, and `heading` (pass `--heading false` for a dedication or epigraph, or edit the scaffolded `heading:` key; never add a second one). Write the page text directly in the file; unwritten pages are left out of builds and `validate` warns about them. Never invent acknowledgments, biographical facts, or copyright details: ask the user for them. Matter pages that quote others' work (an epigraph, song lyrics) may record `permission` (`not-needed`, `pending`, `granted`, `public-domain`), `rights-holder`, and `credit`; `validate` warns when `permission: pending` remains on a complete story and when `granted` has no `rights-holder`. See the `editorial-review` skill

- - `add research` when the story relies on a real-world fact: notes live in `research/` with `status` (`open`, `verified`, `disputed`), whole-citation `sources`, and `used-in` chapter ids, plus optional `--accuracy` (`must-be-accurate`, `blended`, `invented`), `--confidence` (`high`, `medium`, `low`), `--method` (`fact`, `interview`, `site-visit`, `expert-review`, `reading`), and repeatable `--risk` (`legal`, `medical`, `weapons`, `safety`, `cultural`, `defamation`, `technical`). `validate` warns when a final chapter relies on open or disputed research (invented notes never trigger this), and when a note with a `risk` is used in a final or complete chapter with no `reviewed-by`. See the `research` skill

- - `build` when the user asks to build the book artifact; supports markdown, EPUB, DOCX, Shunn, HTML, print, narration, metadata, Fountain, Twee, and ink outputs in `dist/`, with front and back matter. For EPUB, set `cover: path/to/cover.jpg` (inside the project) and `author` in `story.md` to embed a cover image and creator

- - `build --format html` when the user wants a review or reading copy for people who never open a terminal: a single HTML file with a table of contents and a paragraph label on every paragraph, shown faintly in the margin as a link labelled `ch03-p12` (chapter 3, paragraph 12), that reviewers cite in notes. A label is the paragraph's position in that build, so any earlier edit renumbers it; add `--stamp <round or date>` so notes can name the build, and ask reviewers to quote each paragraph's first few words. `--note-url <url>` adds a Note link beside each label, prefilled with `title`, `anchor`, `build`, and `quote` query parameters for the `manuscript-note.yml` issue form. `templates/github/review-copy.yml` publishes it to GitHub Pages; see the `feedback-triage` skill

- - `build --format print` for a print-ready interior: HTML with CSS paged media, trim size from `--trim` (`5x8`, `5.25x8`, `5.5x8.5`, `6x9`, `a5`; default `5.5x8.5`), mirrored margins with gutter, running heads (author on verso, chapter title on recto, blank on chapter openings), page numbers at the foot of chapter and back-matter pages, chapters on recto, a raised initial at each chapter opening, widow and orphan control, and a copyright page. Render it to PDF with a paged-media engine the user installs (Paged.js CLI `pagedjs-cli`, WeasyPrint, or Prince); the CLI does not bundle one. See the `publishing` skill

- - `build --format narration` for an audiobook narration script: a pronunciation guide table from every `pronunciation` field, each chapter with an estimated finished runtime at the language's narration pace (155 words per minute in English), scene breaks as `[pause]`, and a total runtime. See the `adaptation` skill

- - `build --format metadata` for a retailer metadata sheet from `story.md`: title, series, authors, ISBN, publisher, date, language, description with its character count against common limits (KDP 4,000), keywords, BISAC subjects, word count, estimated page count, AI disclosure, and a readiness checklist of missing fields. See the `publishing` skill

- - `build --format twee` for a Twine story (Twee 3) of a branching book: one passage per chapter, named by its id, with a `[[text->chapter-NN]]` link for each entry in the chapter's `choices` frontmatter (`text` and `to`). The first chapter is the start; once any chapter has choices, a chapter without them is an ending, and with none anywhere each chapter links to the next. The IFID comes from `ifid` in `story.md`; without it the build derives one from the story id and warns with the `ifid:` line to add. It refuses to build while a choice is malformed or leads to a missing chapter; `story validate` and `story links` report the same problems, and `links` warns about chapters no choice path reaches. See the `adaptation` skill

- - `build --format ink` for the same branching book as an ink story for Inky and inklecate: one knot per chapter (`chapter-03` becomes `chapter_03`), a sticky `+ [text] -> knot` choice for each entry in `choices`, `-> END` for a chapter without choices, the title, author, and IFID as global tags, and prose escaped so ink reads it as text. It shares the Twee build's rules, checks, and refusals. See the `adaptation` skill

- - `build --format epub` also writes EPUB 3 accessibility metadata, language, semantic chapter and matter markup, and a landmarks nav, and uses the optional `story.md` publishing fields (`cover-alt`, `isbn`, `publisher`, `publication-date`, `description`, `subjects`, `language`, and `copyright`, which generates a copyright page when no copyright matter page exists)

- - `build --format shunn` when the user wants Shunn manuscript-format markdown: title page, contact block, word count, chapter breaks, and double-spaced prose; `story build . --format docx --shunn` applies the same Shunn formatting to the DOCX output

- - `knowledge` when the user asks what a character knew at a given chapter: `story knowledge <character-id> --at <chapter-id>` lists knowledge-state entries the character knows there in story time (by date when both chapters are dated, otherwise by chapter number), plus entries without `learned-in`. Each line is `reader-knowledge` (already on the page, or pre-existing) or `character-knowledge` with `do not reveal` (known from a flashback the reader has not reached). `story context` uses the same rule and the same marks

- - `context` before drafting a chapter or scene: `story context <chapter-or-scene-id> [--budget <tokens>] [--scenes <n>]` prints, as markdown and in priority order until the estimated budget (default 6000 tokens; 4 per 3 words in spaced text, 2 per 3 Han or katakana characters, 1 per 2 hiragana, and 1 per Thai, Lao, Khmer, or Burmese word) runs out, the target's outline and cast, the `story.md` essentials and `style-sheet.md` rules, the POV character's knowledge and state at that point, cards for the characters on the page and the locations, with their progressions applied at the target, open promises, clues, and questions, and summaries of the previous `--scenes` scenes (default 5). POV knowledge follows the same rule as `knowledge`, including a `character-knowledge` line that must not be revealed. Other material from later chapters is left out, progressions included. For a scene, a fact learned in that chapter is included only when an earlier scene's `state-changes` records it for the POV character. Items left out for the budget are listed with the file to read instead

- - `add clue` when the user plants a new clue: `story add clue "Name" --planted chapter-02 --payoff chapter-05` creates the clue ledger entity in `continuity/clues/` with `status: planted` (`planned` when `--planted` is omitted or names a chapter not written yet; pass `--status planned` if the clue is not on the page yet); omit `--payoff` when the payoff is not yet known, and pass `--red-herring` for a clue meant to mislead