# Tutorials

Each tutorial walks through one concrete writing workflow end to end.
They assume nothing about your prior experience with Inkhaven, AI, or
RAG; they do assume you have already installed the binary per
[`../FIRST_STEPS.md`](../FIRST_STEPS.md).

Read in order if you are new. Skip around once you know what each
covers.

| # | Tutorial | Workflow |
| --- | -------- | -------- |
| 1 | [`01-getting-started.md`](01-getting-started.md) | First five minutes: launch the TUI, build a tiny book, save a paragraph. |
| 2 | [`02-organising-your-manuscript.md`](02-organising-your-manuscript.md) | The hierarchy, system books, folding, reordering, renaming. |
| 3 | [`03-the-editor.md`](03-the-editor.md) | Movement, selection, find / replace, undo / redo, snapshots, split-edit. |
| 4 | [`04-search-and-discovery.md`](04-search-and-discovery.md) | Semantic and full-text search; finding prose you have forgotten the words for. |
| 5 | [`05-ai-writing-assistant.md`](05-ai-writing-assistant.md) | Sending text to the LLM, scopes (F9), inference modes (F10), chat history, prompt picker. |
| 6 | [`06-grammar-check.md`](06-grammar-check.md) | The F7 grammar workflow and the `g`-apply pipeline that preserves Typst markup. |
| 7 | [`07-places-and-characters.md`](07-places-and-characters.md) | Building a lexicon of worldbuilding, using the yellow / cyan overlays, asking the AI via `Ctrl+B P` / `Ctrl+B C`. |
| 8 | [`08-importing-existing-docs.md`](08-importing-existing-docs.md) | `inkhaven import-help`, the F3 file picker, adopting a directory of `.md` / `.typ` files. |
| 9 | [`09-exporting-to-typst-and-pdf.md`](09-exporting-to-typst-and-pdf.md) | `inkhaven export typst` / `export pdf`; what a book-level config paragraph looks like. |
| 10 | [`10-backups-and-recovery.md`](10-backups-and-recovery.md) | Manual backup, restore, the auto-backup-on-exit hook, recovery from drift. |
| 11 | [`11-theming.md`](11-theming.md) | The Catppuccin Mocha defaults and every colour knob in the HJSON. |
| 12 | [`12-configuring-ai-providers.md`](12-configuring-ai-providers.md) | The six bundled provider stanzas (Gemini / Claude / OpenAI / DeepSeek / Grok / Ollama), Ctrl+B L live-switching, model upgrades. |
| 13 | [`13-ai-full-screen-mode.md`](13-ai-full-screen-mode.md) | Ctrl+B K layout, persistent chat history, Ctrl+F search, Ctrl+C selection mode that copies / inserts turns. |
| 14 | [`14-document-status.md`](14-document-status.md) | Ctrl+B R workflow ring, status badges in tree + editor header, Ctrl+B 1..7 scoped filter modal. |
| 15 | [`15-multi-format-export.md`](15-multi-format-export.md) | `inkhaven export markdown / tex / epub`, `--book-name` for multi-book projects, Ctrl+B O extra formats, Ctrl+V markdown extraction. |
| 16 | [`16-similar-paragraphs.md`](16-similar-paragraphs.md) | Ctrl+V S — vector-similarity picker + side-by-side editor with the AI pane replaced by a second editor. |
| 17 | [`17-writing-goals.md`](17-writing-goals.md) | Writing-progress tracking, the `goals:` HJSON stanza, daily-words vs morning-baseline, streak with grace, per-book deadlines, the Ctrl+V G modal. |
| 18 | [`18-bund-pane-and-script-picker.md`](18-bund-pane-and-script-picker.md) | The floating Bund output pane (`ink.pane.*`), the Ctrl+Z ? script picker, the `ink.input` prompt modal. |
| 19 | [`19-wiki-links.md`](19-wiki-links.md) | Metadata-only outgoing / incoming paragraph links, Ctrl+V A / I / L / K chords, AI-inference integration, status-bar count. |
| 20 | [`20-snapshot-diff.md`](20-snapshot-diff.md) | F6 V snapshot diff (snapshot vs current), pre-restore safety snapshot on Enter, recovery flow. |
| 21 | [`21-navigation.md`](21-navigation.md) | Ctrl+V P fuzzy paragraph picker, Ctrl+V B / M bookmarks, AI prompt Up-arrow history, slash-command prefix ranking. |
| 22 | [`22-tree-multiselect.md`](22-tree-multiselect.md) | Tree-pane mark set (Space), T cycles type, O cycles status — both work on single OR multi-selection. |
| 23 | [`23-scrivener-import.md`](23-scrivener-import.md) | `inkhaven import-scrivener` — single-binary `.scriv` ingest with RTF→Typst conversion, dry-run, mapping rules. |
| 24 | [`24-typst-in-process.md`](24-typst-in-process.md) | `typst_compile.engine = "inprocess"` — bundled compiler + fonts + `@preview` packages, parse + semantic diagnostics, Ctrl+V R render preview, Ctrl+V N diagnostic navigation, `inkhaven doctor`. |
| 25 | [`25-tag-workflows.md`](25-tag-workflows.md) | Project-wide tags — `Ctrl+B ]` picker, `Ctrl+B }` search, R rename, `inkhaven export --tag`, tree pips, `ink.tag.*` Bund, Scrivener keyword import. |
| 26 | [`26-story-view.md`](26-story-view.md) | `Ctrl+V Shift+W` book view + `Ctrl+V w` paragraph mini view — radial graph of hierarchy / paragraph links / lexicon mentions; `S` saves PNG; `ink.story.render` Bund word. |
| 27 | [`27-diagnostics.md`](27-diagnostics.md) | Typst diagnostics surface — gutter `●` markers, `F8` list modal, `Ctrl+V N` next-diagnostic, `Ctrl+F12` AI explain, `hook.on_diagnostic`, `ink.editor.set_cursor`. |
| 28 | [`28-ai-critique-and-memory.md`](28-ai-critique-and-memory.md) | `F12` mode-aware critique, opt-in per-paragraph AI memory, diff-review modal on apply (`a`/`r`/`e`), smart marker extraction for grammar replies. |
| 29 | [`29-snapshot-annotations.md`](29-snapshot-annotations.md) | `F5` annotation prompt; `F6` picker rendering with `✎` indent; when to label which snapshots. |
| 30 | [`30-render-preview.md`](30-render-preview.md) | `Ctrl+V R` render preview with `+/-` live zoom (1.2.6+); `S` saves current page, `A` saves all. |
| 31 | [`31-story-timeline.md`](31-story-timeline.md) | The full timeline feature (1.2.6+) — calendars, CLI `event add/list/show`, `Ctrl+V e` picker, `Ctrl+V Shift+T` swim lanes with scope nav, `Ctrl+V Shift+E` new event from any pane, `Ctrl+V Shift+I` edit event timing, AI health critique (y/Y/Ctrl+Y). 1.2.7+ adds tree-style Tab/Enter, Space collapse, span-aware ↑/↓ select, grid stripes, F12 full critique, session persistence, book-slug prefix. |
| 32 | [`32-paragraph-undelete.md`](32-paragraph-undelete.md) | `Ctrl+B U` restores the most recently deleted paragraph — body, tags, status, paragraph links, event data round-trip. Single-slot kill-ring (1.2.7+). |
| 33 | [`33-navigation-history.md`](33-navigation-history.md) | `Alt+←` / `Alt+→` step through visited paragraphs; `Ctrl+V Shift+P` recent-paragraph picker (1.2.7+). Browser-style back/forward across every pane that opens a paragraph. |
| 34 | [`34-mouse-and-external-changes.md`](34-mouse-and-external-changes.md) | `Ctrl+Shift+M` toggles mouse capture so the terminal's native text-select + copy works; passive watcher reloads the open paragraph when the on-disk file changes (CLI / sed / git pull / Bund script). (1.2.7+) |
| 35 | [`35-embedded-shell.md`](35-embedded-shell.md) | Embedded **nushell** pane (1.2.8+) — `Ctrl+Z o` opens a floating shell inside the TUI; `Ctrl+Z h` selection mode lets you `c` copy a command's output to clipboard or `i` insert it into the editor wrapped as a typst raw block. Per-project SQLite history; HJSON-configurable insert template. |
| 36 | [`36-config-editor.md`](36-config-editor.md) | Edit `<project>/inkhaven.hjson` from inside the TUI (1.2.8+) — `Ctrl+B 0` opens a full-screen modal editor with HJSON syntax highlighting. `Ctrl+S` saves; when bytes change a *Restart required* overlay pops up. Mirrors the paragraph editor's chord set. |
| 37 | [`37-help-book-viewer.md`](37-help-book-viewer.md) | The Help book as a rendered-markdown viewer (1.2.8+) — paragraphs render via pulldown-cmark (headings, lists, emphasis, code fences, blockquotes, links) instead of showing source. Read-only; scroll keys + mouse wheel only. |
| 38 | [`38-writing-streak-heatmap.md`](38-writing-streak-heatmap.md) | Ctrl+B Shift+G — GitHub-style 13×7 grid of the last 91 days of word activity; current streak + longest streak + 91-day total + active-day average; bucket colors (1.2.9+). |
| 39 | [`39-scene-break-navigation.md`](39-scene-break-navigation.md) | Ctrl+B < / Ctrl+B > — jump the cursor between typographic scene-break lines (`* * *`, `***`, `---`, `___`, `###`, `~~~`, `§`) inside the open paragraph (1.2.9+). |
| 40 | [`40-concordance.md`](40-concordance.md) | Ctrl+B Shift+L — project-wide concordance modal: every distinct lexical stem with count + KWIC samples; stop-word filtering; Snowball grouping; substring filter; count/alphabetical sort (1.2.9+). |
| 41 | [`41-pov-character-chip.md`](41-pov-character-chip.md) | Ctrl+B Shift+P — status-bar POV / character chip; most-mentioned character surfaces as the heuristic POV, with up to three supporting characters; driven by the existing characters lexicon (1.2.9+). |
| 42 | [`42-sentence-rhythm-gauge.md`](42-sentence-rhythm-gauge.md) | Ctrl+B Shift+H — sentence-rhythm gauge: word-count mean / stdev / CV → verdict (Monotone / Steady / Varied / Choppy); per-sentence bar chart + outlier callouts; the felt rhythm of the prose (1.2.9+). |
| 43 | [`43-show-dont-tell.md`](43-show-dont-tell.md) | Inline overlay (under Ctrl+B Shift+F): copula+emotion-adj 2-grams, manner-of-emotion adverbs, cognition verbs. Plus Ctrl+B Shift+T — AI-driven scan with rewrite suggestions in the AI pane (1.2.9+). |
| 44 | [`44-prompts-editor.md`](44-prompts-editor.md) | `inkhaven prompts-editor` — standalone four-pane workbench for `prompts.hjson`. List + editor + AI response + AI prompt input.  The LLM acts as a prompt-engineering REVIEWER (no template execution).  Ctrl+B G inserts the AI response at the editor cursor; Ctrl+R rolls back to a `.prompts-backups/` snapshot.  Auto-populates from embedded defaults on first launch (1.2.10+). |
| 45 | [`45-config-tui.md`](45-config-tui.md) | `inkhaven config` — standalone schema-aware editor for `inkhaven.hjson`.  Typed widgets (bool / int / float / string / colour with preview / path / enum / list).  Build-time doc-comment extraction so every field has docs.  Comment-preserving surgical save + .config-backups/ rollback + annotations + Ctrl+I comment inspector + map-entry add/delete for `llm.providers` (1.2.10+).  1.2.11+ adds F3 file-picker in the path widget, three new enum entries (`language`, `typst_page.language`, `typst_page.page_numbering`), and an HSL slider mode for the colour widget (toggle with `h`). |
| 46 | [`46-ai-rhythm-rewrite.md`](46-ai-rhythm-rewrite.md) | `Ctrl+B Shift+M` — AI sentence-rhythm rewrite of the open paragraph.  Pairs with the Ctrl+B Shift+H gauge: see MONOTONE → press the chord → review the side-by-side diff → accept commits the rewrite AND creates a snapshot annotated `Sentence rhythm rewrite` for safe rollback (1.2.11+). |
| 47 | [`47-multilingual-prompts.md`](47-multilingual-prompts.md) | Per-language prompts across the seven embedded AI flows.  Three-pass resolver (strict same-language → untagged → any-language with English floor), `lang:<code>` tag convention on Prompts-book paragraphs, optional `language:` field on `prompts.hjson` entries, `Ctrl+B Shift+N` runtime mode toggle (book-defined ↔ paragraph-detected via whatlang), AI pane `lang=` chip, `/` picker sectioning, `inkhaven prompts bootstrap <lang> [--update]` CLI (1.2.11+). |
| 48 | [`48-split-view.md`](48-split-view.md) | `Shift+F4` toggles fullscreen split-view — tree pane on the left, primary editor in the middle, secondary editor on the right.  `Shift+Enter` is the universal "pin to secondary" modifier across every paragraph picker (tree, fuzzy, recent, bookmarks, F6 snapshots). `Ctrl+V Shift+B` is the sibling-book lookup chord designed for translation manuscripts (same slug, other top-level book → pin).  F12 fires the `critique-compare` embedded prompt when both panes hold distinct paragraphs (5-language match, multilingual resolver) (1.2.12+). |
| 49 | [`49-language-book.md`](49-language-book.md) | End-to-end Language-book workflow.  Scaffold a conlang (tree-pane Add Book under `Language` OR `inkhaven language init`), populate `Meta/overview`, add dictionary entries with `language add-word`, see the lexicon overlay + status-bar chip light up invented words in your manuscript, translate INTO the conlang with `Ctrl+B Q` (picker on ambiguity, first-letter jump-and-commit), reverse-translate with `Ctrl+B Shift+Q` for roundtrip testing, `I` in the AI pane lifts only the `<<<TRANSLATION>>>` block, `language doctor` health report (with `--json` for CI), `language list` summary, and `language export --format dictionary-twocol/anki/json` (1.2.13+). |
| 50 | [`50-dictionary-csv-import.md`](50-dictionary-csv-import.md) | Bulk-import a dictionary from CSV via `inkhaven language add-word <lang> --import <path.csv>`.  Format spec (12 columns, RFC 4180 quoting, `;`-separated paradigms, `\|`-separated example lists), additive vs `--new` wipe-and-replace semantics, pre-flight alphabet + phonology validation (`--force` to bypass), CI-pattern recipes, idempotent re-imports.  Ships with a worked Tira-starter sample CSV ([`49-language-book-tira-starter.csv`](49-language-book-tira-starter.csv)) — 12 entries covering noun/verb/particle/pronoun/adjective + ritual register with full inflection paradigms + etymology + cross-references (1.2.13+). |
| 51 | [`51-crash-report-and-recover.md`](51-crash-report-and-recover.md) | Survivability layer (1.2.15+).  Custom panic hook flushes every dirty buffer to `<path>.inkhaven-rescue` companion files atomically; writes `inkhaven-crash-<UTC>.hjson` to cwd with panic context + project state + recent action ring + environment fingerprint.  `inkhaven recover <crash.hjson>` walks the manifest with y/N/diff per buffer; on `y` it snapshots the current on-disk version as `<original>.pre-recover-<UTC>` then atomically applies the rescue.  `--yes` for scripted recovery, `--keep` to retain the report after apply.  Built-in path-traversal rejection so a crafted crash report can't write outside the project root. |
| 52 | [`52-health-and-doctor.md`](52-health-and-doctor.md) | Background health monitor + on-demand doctor (1.2.15+).  Status-bar chip (`✓` clean / `✎` repaired / `⚠` warning / `✗` error) driven by a tokio task that checks project-root reachability (90s), backup freshness (5min), and rescue-orphan accumulation (1h).  Per-class auto-repair opt-in in HJSON.  `inkhaven doctor --scan` + `--autofix` walks the project for zero-byte files / orphan paragraph rows / bdslib-disk drift / corrupt comment sidecars.  `--json` for CI gates (exit 2 on Warning+).  `Ctrl+B Shift+0` opens the same flow as a TUI modal. |
| 53 | [`53-bund-trust-gate.md`](53-bund-trust-gate.md) | Bund script trust gate (1.2.15+).  `scripting.trust_decision: "ask"` (default), `"trust"`, or `"deny"`.  `"ask"` requires `<project>/.inkhaven/trust` with a `trust` marker before script auto-loading runs at project open.  How to enable for your own projects (HJSON vs trust file).  How to audit someone else's project before granting trust — what to look for in `ink.fs.*` / `ink.input` / `ink.key.bind` / `hook.*` calls.  Read alongside `Documentation/SECURITY_WARNING.md`. |
| 54 | [`54-manuscript-intelligence-dashboard.md`](54-manuscript-intelligence-dashboard.md) | Manuscript intelligence dashboard (1.2.16+).  `Ctrl+V Shift+J` opens a synthesis pane unifying every metric inkhaven collects since 1.2.5 — word count today/total + streak + active minutes, structure (books/chapters/paragraphs + chapter-word-count CV + pacing verdict), threads (active/dormant), comments (open/resolved this week/lifetime).  `↑↓` scroll, `e` exports the snapshot to `<project>/journal-<UTC>.md`, `Esc` closes.  J for Journal.  Headline 1.2.16 feature. |
| 55 | [`55-plot-mining-and-worldbuilding.md`](55-plot-mining-and-worldbuilding.md) | Four new doctor-scan classes from 1.2.16 cycle: `dropped-character` (mentioned in first 30% of chapters, absent from last 30%), `pacing-collapse` (chapter > 3× or < 0.3× trailing 5-chapter mean), `stalled-thread` (newest waypoint > 30d old; mirrors `inkhaven thread doctor`), `naming-inconsistency` (near-miss spelling of canonical multi-word names via Levenshtein).  All Info severity, no autofix — author-judgment findings.  Plus the worldbuilding glossary chip (`<N>C·<N>P·<N>A`) in the status bar. |
| 56 | [`56-tts-piper.md`](56-tts-piper.md) | TTS Piper transition (1.2.17+).  Cross-platform neural backend replacing the macOS-only 1.2.9 `say` integration: `engine: auto` prefers Piper if resolvable + falls back to System, voices auto-download into `<project>/.inkhaven/voices/`, voice picker on `Ctrl+B Shift+V`, full headless CLI (`inkhaven tts engine / binary / voice / catalog / test`).  Also covers the known Apple Silicon limitation (Piper's upstream ships x86_64 in the `aarch64` tarball; mac arm64 users need `engine: system`, a source build, or the workaround documented in the tutorial). |
| 57 | [`57-reader-experience-exports.md`](57-reader-experience-exports.md) | Reader-experience exports (1.2.18+).  `inkhaven epub` builds a standards-compliant EPUB 3 directly (no pandoc, zero new deps) — one XHTML per chapter, nav + ncx + stylesheet, in-house typst→XHTML conversion.  `inkhaven audiobook` synthesises a chapter-marked `.m4b` via the TTS engine + ffmpeg.  Both walk a user book's chapters; `--book-name` / `--output` / `--title` / `--author` flags.  Covers the ffmpeg requirement + the roughly-real-time synthesis cost. |
| 58 | [`58-reading-pace.md`](58-reading-pace.md) | Reading pace (1.2.18+).  The `editor.reading_time_chip` status-bar chip (`📖 remaining / total` at `editor.reading_wpm`, default 200) + the `Ctrl+B Shift+E` reader-pace preview teleprompter that advances a word-by-word highlight through the open paragraph at reading speed so pacing problems surface.  Space pause/resume, ←→ step, r restart, Esc close. |
| 59 | [`59-revision-and-continuity.md`](59-revision-and-continuity.md) | Revision & continuity (1.2.19+).  Four multilingual `doctor --scan` detectors: `echo-repetition` (a distinctive word reused close together, stem + window), `numeric-contradiction` (reversed directions / mismatched durations via per-language quantity lexicons — en/fr/es), `continuity-drift` (`inkhaven continuity extract` builds a character fact bible, the scan flags attributes that change across chapters), `unresolved-tension` (`inkhaven tension scan` tags introduced/resolved tensions, the opt-in scan flags the open ones).  All Info, no autofix.  Includes the multilingual-coverage table (which detector works in which language + the graceful-degradation path). |
| 60 | [`60-manuscript-format.md`](60-manuscript-format.md) | Submitting your manuscript (1.2.19+).  `inkhaven manuscript` exports a user book to a submission-ready Shunn standard manuscript format typst document: 12pt Courier double-spaced, title page with contact + rounded word count, running `Surname / KEYWORD / page` header, chapters on fresh pages, scene breaks as `#`.  Self-contained — compiles with `typst compile`.  The agent/editor companion to the `epub` + `audiobook` reader exports. |
| 61 | [`61-echo-overlay-and-long-paragraphs.md`](61-echo-overlay-and-long-paragraphs.md) | Live echo overlay + over-long paragraphs (1.2.20+).  `Ctrl+B Shift+K` underlines, in the open paragraph, words echoing across nearby paragraphs of the chapter — the inline companion to the `echo-repetition` scan, in its own colour (`theme.style_warning_echo_fg`), with the open paragraph read live (unsaved edits included) and no per-keystroke I/O.  Shares the `echo_window` / `echo_min_repeats` / `echo_max_global` tunables; multilingual via the Snowball stemmer.  Plus the `paragraph-too-long` doctor class — flags a paragraph whose read time at `editor.reading_wpm` exceeds `editor.paragraph_long_secs` (Info, no autofix). |
| 62 | [`62-global-config-and-themes.md`](62-global-config-and-themes.md) | Global config + shareable themes (1.2.20+).  User-global overrides that apply to *every* project: `~/.config/inkhaven/config.hjson` + `~/.config/inkhaven/conf/*.hjson` layer on top of each project's `inkhaven.hjson` (global wins; partial overrides; honours `$XDG_CONFIG_HOME`).  Ships `color_styles/` — 15 popular classic / dark / light schemes (Dracula, Nord, Gruvbox, Solarized, Tokyo Night, Monokai, One Dark, Material Ocean, Catppuccin, GitHub Light, Ayu Light, …) as drop-in `theme` overrides. |
| 63 | [`63-facts-and-fact-checking.md`](63-facts-and-fact-checking.md) | The Facts book + AI fact-checking (1.2.21+).  A new **Facts** system book for a world's invariants (climate, geography, seasons, distances, chronology) — free-form prose like Notes.  The F9 **Facts** scope seeds a sticky chat session with every fact loaded as a visible prologue + a fact-analysis system prompt, so you can interrogate your world.  The `Ctrl+B Shift+X` fact-check chord locks the scope to the local paragraph and grounds the check against the Facts book, flagging claims that contradict the world (snow in the tropics, a three-day ride done overnight).  Multilingual (en/ru/de/fr/es). |
| 64 | [`64-project-find-and-replace.md`](64-project-find-and-replace.md) | Project-wide find & replace (1.2.22+).  Rename a character / term across the whole book, safely — lexical (literal / whole-word / opt-in regex, *not* semantic) over a linear scan.  In the editor: `Ctrl+R` → `Ctrl+B` toggles scope to the whole book → a **review modal** shows every match in context, `Space` skips individual ones, `Enter` applies the kept ones — snapshotting each touched paragraph first (`F6` undo).  CLI: `inkhaven replace <pat> <repl>` with `--dry-run` preview + `--yes` apply, `--regex` / `--substring` / `--book` / `--include-system`.  Whole-word + user-books-only by default. |
| 65 | [`65-hand-binding.md`](65-hand-binding.md) | Hand-binding production (1.3.0+).  Turn the reading PDF into a printable, foldable book over a pure-Rust PDF core (no external apps).  **Imposition**: `inkhaven pdf impose --config default\|chapbook` reorders pages into folding signatures with printer marks + creep (shingling); `--dry-run` prints the plan; `Ctrl+B Q` previews it in the TUI; `imposed_pdf` is a `Ctrl+B O` book-take.  **Covers**: `inkhaven pdf cover --pages N` computes the spine from page count + paper stock, with optional front art, back blurb, and a validated EAN-13 `--isbn` barcode (`cover_pdf` book-take; standalone `pdf barcode`).  **Preflight**: `inkhaven pdf preflight` catches the print-only problems — effective image DPI via CTM tracking, non-embedded fonts, inconsistent page size, blanks.  **Finishing**: `pdf grayscale` / `optimize` / `watermark` / `sample`.  All mirrored as `ink.pdf.*` Bund words. |
| 66 | [`66-submission-package.md`](66-submission-package.md) | From draft to submission (1.3.0+ `.docx`, 1.3.1+ package + tracker).  The agent/editor hand-off path.  **`.docx`**: `inkhaven docx [--font times\|courier]` emits a hand-rolled Shunn-format Word document (no `docx` dep, no Word needed); `docx` is a `Ctrl+B O` book-take.  **Package (AI)**: `inkhaven submission digest` caches a compact whole-book context, then `submission query \| synopsis [--long] \| comps \| logline` draft into the **Submissions** system book (synopses spoil the ending; comps are labelled suggestions).  `Ctrl+V q` picks a generator and streams it into the AI pane (3-tier prompt resolution via the Prompts book / `prompts.hjson`).  **Tracker**: `inkhaven submissions add\|list\|status\|add-note\|remove` (the `.inkhaven/submissions.json` log) + the `Ctrl+V u` modal; `add-note` is a timestamped event trail (sent → requested edits → round two).  All mirrored as `ink.export.*` Bund words. |
| 67 | [`67-planning-board.md`](67-planning-board.md) | The Planning Board — diagnose structure (1.3.2+).  Structure is the third axis (Timeline = *when*, Threads = *arc payoff*, Planning = the skeleton).  `inkhaven plan init --framework save_the_cat\|three_act\|story_circle\|hero_journey\|seven_point` scaffolds a framework's beats into the **Planning** system book (HJSON paragraphs; set `mapped_chapter` + `threads` to link a beat).  **`inkhaven plan check`** is the deterministic diagnosis — coverage gaps, per-beat **position drift** (Midpoint lands at 64% vs target 50%), and **act word-share pacing** ("Act 1 is 30% of your words — long"); no AI.  **`Ctrl+V Shift+K`** shows it as a position bar per beat.  **`inkhaven plan analyze`** (and `a` in the outline) maps beats→chapters and names the sag over the 1.3.1 digest.  Thread-links surfaced + validated.  Zero new deps. |
| 68 | [`68-editorial-pass.md`](68-editorial-pass.md) | The Editorial Pass — one revision worklist (1.3.6+).  Unifies every detector (the editorial `doctor` classes + `plan check`'s structural findings + the Facts-scan sidecar) into one ranked list, errors first.  **`inkhaven edit`** prints it; deterministic (reads computed sidecars, no live AI), so `--json` gates a CI build and `--only echo,pacing` narrows it.  **`Ctrl+V Shift+R`** opens the cockpit: `↑↓` navigate, `[`/`]` filter by category, `Enter` jumps to the finding's chapter/paragraph in the editor, `s` skips, `d` defers (persisted — hidden until the prose changes), `D` clears.  **`inkhaven edit --deep`** first re-runs the AI scans (Facts / tension / continuity) then aggregates.  `edit` is *manuscript readiness*; `doctor` stays *project integrity*.  Zero new deps. |
| 69 | [`69-world-consistency.md`](69-world-consistency.md) | World consistency — facts, anachronisms, the story bible (1.3.8+).  Four world-consistency tools.  **`inkhaven facts check`** flags fact pairs that contradict each other *within* the Facts book ("winters are mild" vs "the harbor freezes"); cached, surfaced in `inkhaven edit` (category `world`).  **Anachronism overlay** — set `editor.style_warnings.anachronism.year` and a ~35-term built-in lexicon flags terms that postdate the setting ("wristwatch" in 1840), surfaced in `edit`.  **Story bible** (`Ctrl+V Shift+L`) — a consolidated, navigable view of the world: each Character with the attributes `continuity extract` tracked across chapters, plus Places / Artefacts / Facts; `Enter` jumps to source.  **Series-shared facts** — `facts.shared_path` (a directory of fact files) layers shared canon into `facts check` (local wins on a clash); `inkhaven facts import` copies a snapshot into the Facts book.  Zero new deps. |
| 70 | [`70-semantic-drift.md`](70-semantic-drift.md) | Semantic drift — when a description quietly changes (1.3.10+).  The *soft*-consistency counterpart to Tutorial 69: two descriptions of the same entity that diverge without a hard fact clash (a tavern "cramped and smoky" in ch.2, "airy and bright" in ch.20).  **Embeddings retrieve, the AI adjudicates** — reuses the on-save vector index to pull each entity's description paragraphs, then asks the model which contradict.  **`inkhaven drift scan`** writes `.inkhaven/drift.json` and surfaces in `inkhaven edit` (category `drift`, jump-only to the divergent passage); **`drift list`** previews the retrieved descriptions deterministically.  The **`Ctrl+V Shift+L`** story bible shows a ⚠ drift badge + the chapter-ordered description trail under each flagged entity.  Tunable via the `drift` config block.  Zero new deps. |
| 71 | [`71-world-report.md`](71-world-report.md) | The world report + pronoun-aware drift (1.3.11+).  Two threads.  **Drift depth** — coreference-lite recovers pronoun-only descriptions ("Mara crossed the yard. She was taller…") via a precision-favouring recency heuristic; multilingual built-in pronoun sets (en/ru/fr/de/es) keyed by the project language.  **`inkhaven world`** — one consolidated consistency snapshot (established facts + internal/prose contradictions + drift + continuity coverage + named anachronisms + a health summary), complementing `edit` (walkable worklist) as a world-layer snapshot; `--json` gates CI, `--deep` refreshes the AI scans, `--entity <name>` zooms to one entity.  **Coverage** flags entities defined in the books but never named in the prose (a dangling cast), also an `info` `coverage` finding in `edit`.  The same health line banners the `Ctrl+V Shift+L` story bible.  Zero new deps. |
| 72 | [`72-deep-refresh.md`](72-deep-refresh.md) | The background deep refresh (1.3.12+).  **`Ctrl+V Shift+F`** runs the whole world-layer AI batch (facts check + facts scan + drift + continuity, the `inkhaven world --deep` set, in the manuscript's language) on a **background thread** — the editor stays responsive, a `⟳ deep refresh` chip tracks progress, and the open story bible / Editorial Pass rebuilds itself from the fresh findings when it lands.  It runs in-process on a clone of the editor's DuckDB connection pool (single-writer lock means no second open; tune with `embeddings.pool_size`).  **Advisory by design** — it reads your manuscript and writes findings to `.inkhaven/*.json` sidecars only; it never edits a word of your prose (rewrites stay manual via the Editorial Pass `f`/`F`, snapshot-gated + diff-reviewed).  Re-press `Ctrl+V Shift+F` while it runs to **cancel** (1.3.13).  Zero new deps. |
| 73 | [`73-multilingual.md`](73-multilingual.md) | Writing in any language (1.3.13+).  The style overlays, world-checks, and drift coref key off the project `language`.  **`inkhaven lang status`** prints an honest coverage matrix (stemming / detectors / pronouns / embeddings / AI output + prompts).  Five languages ship fully curated (en/ru/fr/de/es); an uncurated language gets **no false flags** (empty lists, never English) while stemming + embeddings + AI output still work.  **`inkhaven lang bootstrap <lang>`** has the LLM lexicographer produce the full detector vocabulary in lemma form for **any** language and (`--yes`) patches `inkhaven.hjson` safely.  World-check prompts are localized (or English-with-warning); per-language config maps + worked Arabic / Hungarian examples in `custom_languages/`.  Zero new deps. |

## Scripting + chord customisation

Two narrative docs sit outside the numbered tutorial sequence
because they cross-cut every other topic:

| Topic | Doc |
| ----- | --- |
| **Bund — the embedded scripting language** | [`../Bund/BUND_TUTORIAL.md`](../Bund/BUND_TUTORIAL.md) — stack model, lambdas, hooks, `ink.*` stdlib, sandbox. |
| **Reassigning chord keys** | [`../KEYS_REASSIGNMENT.md`](../KEYS_REASSIGNMENT.md) — HJSON `keys.bindings` + `ink.key.*`. Includes the full action table. |

## Conventions used in these tutorials

- Commands you should run are in fenced code blocks. Lines starting
  with `$` indicate a shell prompt; the `$` itself is not part of
  the command.
- Keystrokes are written `Ctrl+S`, `F1`, `Ctrl+B` then `P` (the
  meta prefix needs two keypresses).
- The cursor on the TUI is represented by `│` in plain-text mockups.
- Status-bar messages and Inkhaven output are shown in code blocks
  with no leading `$`.
- When a tutorial references another doc, the link is relative — open
  it in another tab; nothing else here depends on it.

## What if I get lost?

- Inside the TUI, press `Ctrl+B H` for the pane-aware quick reference
  overlay.
- Press `F1` for the help-manual query pane (once you have populated
  the Help book — `inkhaven import-help` ingests a directory).
- Print the [`cheat sheet`](../INKHAVEN_CHEAT_SHEET.typ) (`typst
  compile Documentation/INKHAVEN_CHEAT_SHEET.typ`) — two-column A4
  with every chord, hook, and CLI subcommand.
- See the canonical reference: [`../KEYBINDING.md`](../KEYBINDING.md).
- For database / backup / recovery questions:
  [`../MAINTENANCE.md`](../MAINTENANCE.md).
- For configuration: [`../CONFIGURATION.md`](../CONFIGURATION.md).
