# Inkhaven 1.4.8 — Terminology governance

_The quiet trust-killer in long nonfiction and technical writing is terminology drift: "access
token" in chapter one, "auth token" in chapter seven, "authentication token" in the appendix.
TERMS-1 adds a **Glossary** system book of canonical terms + their **banned synonyms**, and wires
those synonyms into the editor as a **red-underline overlay**, a project-wide scan, an LLM
canonicaliser, and a Bund API. **Self-gating** — with an empty Glossary, nothing changes. **No new
dependencies, no new storage tables.**_

_Plan: [TERMS-1_PLAN.md](../PROPOSALS/TERMS-1_PLAN.md)_

## A Glossary of canonical terms

A new **Glossary** system book holds entries as HJSON paragraphs — a canonical `term`, a
`definition`, and the banned `synonyms` you want to stamp out. Press **`P`** under the Glossary
book and the title becomes the term:

```hjson
{
  term: access token
  definition: A short-lived credential the client sends with each request.
  synonyms: [
    auth token
    authentication token
  ]
  // scope: global   // or a book slug to enforce only in that book
}
```

## See drift as you write

In the editor, banned synonyms are **red-underlined** the moment you type them — "auth token"
lights up while the canonical "access token" stays clean (the inverse of a normal highlight: the
*wrong* form is flagged, not the right one). Put the cursor on a flag and the footer shows the fix:

```
terms: "auth token" → use "access token"
```

**`Ctrl+V z`** toggles the overlay; the colour is the theme key `style_warning_banned_synonym_fg`
(default red). Synonyms can be 1–3 words; matching is Unicode-aware (works in en/ru/…) and catches
hyphenated forms (`auth-token`).

## Sometimes you mean it

Not every variant is a mistake. With the cursor on a flag, **`Ctrl+V Shift+Z`** declares that term a
**deliberate variant** — an intent in the shared ledger that stops the overlay and the scan from
flagging it. The "I meant to write it this way" escape hatch.

## Scan the whole project

```sh
$ inkhaven terms check
terms check: 2 banned-synonym occurrence(s) in 1 paragraph(s):
  guide/03-tokens/01-intro line 2: "auth token" → use "access token"
  guide/03-tokens/01-intro line 5: "auth token" → use "access token"
```

It **exits non-zero** on findings, so it slots into a pre-build / CI step. `--book <slug>` scopes
it (honouring per-book term scope); `--json` emits a machine-readable report.

## Let the model find the drift

No glossary yet? **`inkhaven terms suggest --book <slug>`** clusters words appearing in multiple
surface forms and asks the LLM to propose Glossary entries for the genuine terminology drift
(skipping plurals and stylistic variation). Add `--auto-create` to drop the proposals into the
Glossary book as drafts.

## From a script

`ink.terms.{list,get,check}` (read-only) inspect the glossary and findings; `ink.terms.declare_intent`
(store_write) declares a deliberate variant. The Glossary's canonical terms also appear in the
**story bible** (`Ctrl+V Shift+L`).

## Notes

- **Self-gating, zero-cost when unused:** an empty Glossary yields an empty detector, so every line
  scan short-circuits — projects that don't use TERMS-1 pay nothing.
- Built on the existing style-warning + intent-ledger machinery — **no external app/binary deps, no
  new runtime crates, no new DuckDB tables** (one additive `Glossary` system book + one
  `IntentKind`). New tutorial 91; `Ctrl+V z` / `Ctrl+V Shift+Z` in KEYBINDING; a Terminology
  section in CONFIGURATION. Tests 1910 → 1926.
