inkhaven 1.3.21

Inkhaven — TUI literary work editor for Typst books
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

# Tutorial 68 — The Editorial Pass: one revision worklist

*Inkhaven 1.3.6+*

By the time a draft is done, Inkhaven has a dozen detectors looking at it —
echo repetition, pacing collapse, continuity drift, numeric contradictions,
naming near-misses, dropped characters, stalled threads, the Planning
Board's structural findings, the Facts-scan contradictions. The problem was
never detection. It was that you had to run each one separately
(`doctor --scan`, `plan check`, `facts scan`, …) and hold the results in your
head.

The **Editorial Pass** collapses all of it into **one ranked, walkable
worklist**: every finding, errors first, each one you can jump to, defer, or
skip. It's the pre-submission sweep.

## The worklist

```sh
inkhaven edit
```

```
EDITORIAL PASS · 14 finding(s)  (2 error · 9 warn · 3 info)

  ✗ continuity  ch.7         Mara's eyes change green → brown across chapters
  ⚠ pacing      ch.3         chapter runs 3.1× the local average length
  ⚠ structure   —            drift: `Midpoint` lands at 64% (target 50%, +14%)
  ⚠ tension     —            tension: `Midpoint` is flat — actual 33% vs expected 65%
  ⚠ fact        ch.9         "a three-day ride" contradicts: the capital is 200 miles off
  ⚠ scene       ch.4         scene `The locked study` states a goal but never turns
  · echo        ch.3         `suddenly` appears 4× within ¶2–4
  ...
```

Every finding carries a **category**, a **severity** (error → warn → info),
a **location**, and the message. They come from four places, unified:

- the editorial **`doctor`** classes (echo, pacing, continuity, naming,
  dropped-character, stalled-thread, numeric-contradiction, …),
- the Planning Board's **`plan check`** structural findings (gaps, drift,
  pacing, flat tension, weak scenes / sequels),
- the **Facts-scan** sidecar (contradictions against your world facts),
- the **prose-style** detectors, per paragraph — **show-don't-tell** (telling
  phrases), **filter-word** (intensifier crutches + hedges, at `info`), and
  **anachronism** (terms that postdate the setting `year`).

The pass is **deterministic** — it reads what's already computed, runs no
AI, and so works offline and in CI:

```sh
inkhaven edit --json | jq '.errors'      # gate a build on zero errors
inkhaven edit --only structure,tension   # one category at a time
```

`edit` vs `doctor`: **`doctor`** is *project integrity* (zero-byte files,
orphan rows, storage drift). **`edit`** is *manuscript readiness*. They share
the author-judgment classes; they're not the same surface.

## The cockpit

In the editor, **`Ctrl+V Shift+R`** (R for **R**evision) opens the same
worklist as a walkable modal:

- `↑↓` move; the selected finding's full message + hint expand below.
- `[` / `]` cycle the category filter (all → echo → pacing → …).
- **`Enter`** jumps straight to the finding's location — the chapter /
  paragraph opens in the editor, cursor placed. A `→` marks the jumpable
  ones. (Book-level structural findings have no single location.)

Most editorial findings are *author judgment* — there's no auto-rewrite for
"the midpoint sags"; the fix is you editing at the jumped-to spot.

### Let the AI fix it: `f`

The prose-level findings *can* be fixed for you. A **`✎`** marks the
rewritable ones:

- **echo** (vary the over-repeated word) and **pacing** (tighten an overlong
  paragraph) rewrite the **whole paragraph**;
- **show-don't-tell** (rewrite a telling passage to show) and **filter-word**
  (cut the crutch) rewrite **only the flagged phrase** and splice it back —
  *span-scoped* (1.3.9), so the good prose around it is left untouched.

Press **`f`** on one:

```
EDITORIAL · ch.2 · show-don't-tell
finding: "she was furious" — telling

  f → AI rewrite (streams into the AI pane):
  "Her knuckles whitened on the rail; she didn't
   trust her own voice."

  [a]ccept (snapshots first) · [r]eject
```

`f` opens the finding's paragraph, streams the rewrite, and pops the **diff
review** — the same one the sentence-rhythm rewrite uses; the diff always
shows the whole paragraph for context even when only a phrase changed.
**`a`** snapshots the paragraph (so the original is one `F6` away) then
replaces it; **`r`** discards. The prompt resolves through the usual three
tiers (a `editorial-fix-<category>` entry in your Prompts book →
`prompts.hjson` → built-in), so the rewriting voice is yours to tune.

### Fix the whole category: `F`

When a category is clean enough to trust the rewriter, **`F`** (Shift+F)
**batch fix-all**: it walks every rewritable finding in the current `[` `]`
filter through that *same* per-item diff review — one at a time, never
blind-applied. `a` accepts (and advances), `r` skips to the next, and **`Esc`
stops** the run, leaving the rest untouched. The status line tracks progress
(`editorial batch 3/7 …`) and the close reports `N applied, M skipped`. Filter
to one category first (`]` until the header reads `show-tell`) to scope the
sweep. This is the loop: see it, `f` (or `F` the lot), accept — or jump and
write it yourself.

### Clearing the list: skip and defer

- **`s`** skips a finding for this session (it's back next time).
- **`d`** **defers** it — persisted. A deferred finding stays hidden until
  its prose *changes*: the fingerprint is the finding's text, so editing the
  passage renews it and it resurfaces, but a deliberate choice you've
  accepted stays gone.
- **`D`** clears every deferral and re-scans.

From the CLI, deferred findings are hidden too (with a count); `inkhaven edit
--show-deferred` includes them.

## The deep tier

The default pass reads the AI sidecars but never *runs* the AI. To refresh
them first — re-run the Facts scan, the tension scan, and the continuity
extract, then aggregate — use:

```sh
inkhaven edit --deep                 # needs an LLM provider
inkhaven edit --deep --provider ollama
```

Each scan prints its progress; one that can't run (no provider, an empty
Facts book) is skipped and the pass falls back to deterministic-only rather
than aborting. `--deep` can't combine with `--json` (the scans print); for a
CI gate, run the scans separately and then `inkhaven edit --json`.

## Where to go next

- The structure findings come from [Tutorial 67](67-planning-board.md).
- The Facts contradictions: `inkhaven facts scan` (Tutorial 63).
- Anachronisms also underline **live** in the editor once you set a setting
  `year` (theme key `style_warning_anachronism_fg`) —
  [Tutorial 69](69-world-consistency.md).
- Every chord: [`../KEYBINDING.md`](../KEYBINDING.md).
- The design: [EDITORIAL-1 plan](../PROPOSALS/EDITORIAL-1_PLAN.md) ·
  [EDITORIAL-3 plan](../PROPOSALS/EDITORIAL-3_PLAN.md).