@liminis/editor 0.1.0 → 0.2.0

package/docs/decisions/adr-078.md

@@ -86,6 +86,40 @@ that exists but contains no class-bearing source.
 `publishConfig` makes that whole class of problem not arise. The cost is that
 the built path is exercised only in CI — which is what SC-005 mandates anyway.
 
+> **Amended 2026-08-16 — the `publishConfig` mechanism is reversed as of
+> 0.1.1.** It does not work, and it shipped a broken `0.1.0`.
+>
+> `publishConfig` **manifest-field** overrides (`main`, `types`, `exports`) are
+> a pnpm and yarn feature. npm honours `publishConfig` only for *config* values
+> — `access`, `registry`, `tag` — and ignores field overrides entirely.
+> `.github/workflows/publish.yml` publishes with `npm publish`, so the swap to
+> `dist/` never happened: `0.1.0` went to the registry declaring
+> `"main": "./src/index.ts"` while `files` shipped only `dist/`. Every entry
+> point resolved to a file that was not in the tarball, and the package could
+> not be imported at all.
+>
+> This survived a verification pass that was, in itself, correct and thorough.
+> `scripts/verify-package.mjs` asserted that the packed manifest pointed at
+> `dist/` and that each target existed — but it packed with **pnpm** while the
+> release packed with **npm**. It validated a tarball no consumer would ever
+> receive. The lesson is narrower and more useful than "test more": *verify the
+> artifact the release actually produces.*
+>
+> The entry points now live in the checked-in manifest as `dist/` paths, with
+> no pack-time rewriting by anyone, and `verify-package.mjs` packs with npm and
+> additionally asserts the packed entry points are byte-identical to the
+> checked-in ones — so a client that rewrites them fails too.
+>
+> **What this costs is exactly what the decision above was buying.** An
+> in-workspace consumer resolving `@liminis/editor` no longer lands on raw
+> TypeScript, so the Tailwind `@source` directive and the bundler
+> externalization exclusion described above must name the installed package
+> rather than a sibling `src/` tree. That cost is now acceptable because the
+> monorepo copy is being removed in favour of the published package
+> (verveguy/liminis#1009) — the in-workspace consumer this protected is going
+> away. The rest of the decision — the non-bundling `tsc` emit, `sideEffects`,
+> the vendored wiki-link fix — is unaffected.
+
 `private: true` is kept: publishing is out of scope for #940, and `private`
 blocks `publish` without blocking `pack`.
 
@@ -96,8 +130,9 @@ blocks `publish` without blocking `pack`.
 > package is private. The guard is now `prepublishOnly` →
 > `scripts/guard-publish.mjs`, which refuses unless `LIMINIS_ALLOW_PUBLISH=1`
 > is set — a script rather than a flag precisely so that it can be tested, and
-> it is, in `tests/package-manifest-contract.test.ts`. The rest of this ADR is
-> unaffected: `publishConfig` and the non-bundling `tsc` emit stand as decided.
+> it is, in `tests/package-manifest-contract.test.ts`. The non-bundling `tsc`
+> emit stands as decided. (This amendment originally said `publishConfig` stood
+> too. It does not — see the amendment above it, added later the same day.)
 
 ### 3. `mdast-util-wiki-link` is vendored, not merely un-patched.
 

package/docs/decisions/adr-085.md

@@ -0,0 +1,166 @@
+# ADR-085: The Theming Token Reference Is Generated Into `README.md` and Guarded Against Drift
+
+**Date:** 2026-08-17
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #50 (verveguy/liminis-editor)
+
+## Context
+
+The editor exposes its theming surface entirely through CSS custom properties
+— a VS Code-style vocabulary (`--vscode-*`) plus a handful of `--slashmd-*`,
+`--color-*` and `--checkbox-*` tokens. Before this issue, none of it was
+documented: a host wanting to match its own palette had to read all of
+`src/styles.css` (2,477 lines) to find the knobs, and nothing kept a written
+list honest against the code even if one had been hand-authored.
+
+The issue's own acceptance criteria (FR-002/FR-005 in the Plan stage) require
+the reference to be *generated from source*, not transcribed once, and
+(FR-008) require a CI-enforced guard. The spec (FR-003) additionally requires
+each documented property to state what it controls in a short,
+human-readable description — not merely its name and classification. The
+guard therefore asserts three things: that the documented set equals the
+consumed set, that every consumed token resolves without any host
+configuration (a default, or a fallback at every call site), and that every
+consumed token has a description. The resolves-without-host assertion is
+exactly the rule issue #52 broke, where `--vscode-text` (a typo for
+`--vscode-foreground`) had neither and silently dropped its declaration. #52
+was fixed independently and had already merged to `main` by the time this
+issue's implementation began, so this change did not need to bundle that fix
+itself — but the guard's assertion still exists to catch the next occurrence
+of the same bug class.
+
+Three questions needed a specific, reviewable answer rather than being left
+to convention:
+
+1. How does a generated table get **into** a checked-in markdown file, given
+   this repo already has one script (`generate-demo-docs.mjs`) that reads
+   `README.md` but none that writes into it?
+2. How is "structural" (affects layout) distinguished from "cosmetic"
+   (affects appearance only) for a token, given the source has no explicit
+   signal for this beyond the CSS property each token feeds?
+3. Where does the per-token "what it controls" description (FR-003) come
+   from, given the source has no comment or annotation convention that
+   states a token's purpose in prose?
+
+## Decision
+
+**A shared, plain-JS extraction module — one generator, one guard, no second
+list.** `scripts/lib/theming-tokens.mjs` exports pure functions (comment-strip,
+consumed-token scan, defaulted-token scan, resolves-without-host check,
+structural/cosmetic classification, description lookup, table render/parse). Both
+`scripts/generate-theming-docs.mjs` (the CLI that writes `README.md`) and
+`tests/theming-contract.test.ts` (the CI guard) import it. Plain `.mjs`, no
+build step, matches the existing `scripts/lib/install-tarball.mjs` precedent;
+a hand-written `.d.mts` sidecar gives the test file's `tsc --noEmit` pass real
+types without introducing `checkJs` or a TypeScript rewrite of `scripts/`.
+
+**Marker-delimited regeneration, not a one-time transcription.**
+`README.md`'s new `### Theming: CSS custom properties` subsection carries a
+`<!-- theming-tokens:start -->` / `<!-- theming-tokens:end -->` pair; the
+generator rewrites only the text between them, leaving the surrounding prose
+(intro, worked example, the forward note on #51's future rename) untouched.
+The guard's staleness check regenerates the block in memory from current
+`src/` and diffs it against what is actually committed — not "did someone
+run the generator once," but "does the committed table match source right
+now."
+
+**Classification defaults to cosmetic; a small keyword table promotes the
+few that touch layout.** `margin`/`padding`/`width`/`height`/`gap`/
+`line-height`/`font-family`/`font-size` on a token's consumption site marks
+it structural (currently: the five `--slashmd-h{1-5}-indent` tokens and
+`--vscode-font-family`/`--vscode-font-size`); every other token — including
+ones set through a CSS shorthand like `border: 1px solid var(--x)`, where
+only the color segment is templated, and ones reached only through a JS
+variable indirection with no adjacent property name in the source text — is
+cosmetic by default. No hand-maintained override list exists: the two
+ambiguous cases this codebase actually has are caught by the keyword table
+itself (their property names literally appear next to the `var()` call in
+`styles.css`), so a separate override map would have been an unused,
+unexercised second place for this classification to drift.
+
+**Descriptions are a hand-curated map, keyed by token name, checked for
+completeness rather than generated.** `TOKEN_DESCRIPTIONS` in
+`scripts/lib/theming-tokens.mjs` is a plain object mapping each token to one
+sentence of prose, written by inspecting each token's actual consumption
+site(s) in `src/` (e.g. `--vscode-focus-border` and `--vscode-focusBorder`
+are two distinct, unrelated tokens — one styles a focused input border, the
+other a drag-and-drop indicator — that no automatic heuristic on the name
+alone could tell apart). This is deliberately *not* generated the way the
+token set and classification are: FR-003 asks for meaning, which the source
+does not encode anywhere machine-readable. What's generated is the
+*completeness check* — `buildInventory` looks up every consumed token in the
+map and the drift guard fails if any lookup misses, so the map cannot
+silently fall behind the token set the way a truly hand-written README table
+could.
+
+**All three drift-guard assertions are demonstrated by mutation**, not merely
+asserted — `tests/theming-contract.test.ts` writes throwaway fixtures under
+`os.tmpdir()` (never into `src/`) and checks that an undocumented token, an
+unresolvable token, and a token missing from `TOKEN_DESCRIPTIONS` are each
+actually flagged, following the same mutation-testing shape the issue's
+acceptance criteria require and the same fixture-directory convention
+already used by other `scripts/lib/` consumers in this repo.
+
+## Consequences
+
+**Good:**
+
+- The token table can never silently drift from `src/`: adding, removing, or
+  renaming a `var(--x)` reference without running
+  `node scripts/generate-theming-docs.mjs` fails `pnpm test`.
+- A host can theme the editor by reading `README.md` alone — no more reading
+  2,477 lines of `styles.css` to find the knobs. Every row states what the
+  property actually controls (FR-003), not just its name and classification.
+- The classification mechanism needs no maintenance as new tokens are added
+  in the ordinary case (a new color token classifies correctly with zero
+  code changes); it only needs attention if a genuinely new *kind* of
+  layout-affecting token is introduced, at which point the keyword table
+  (not a growing override list) is the one place to extend.
+
+**Bad / accepted:**
+
+- Classification correctness is not itself tested beyond the token *set* —
+  a future token that sets a property this repo's keyword table doesn't
+  recognize would default to "Cosmetic" without failing CI even if it were
+  actually structural. Accepted: worst case is a table cell in the wrong
+  column, not a broken guard, and building a second test for a heuristic
+  this small was judged not worth its own maintenance burden.
+- Hand-editing the generated block between the markers is silently
+  overwritten the next time the generator runs, and produces a CI failure if
+  it isn't. This is deliberate — it is the entire point of the staleness
+  check — but it is a real constraint a future contributor needs to learn
+  once.
+- `TOKEN_DESCRIPTIONS` is hand-written prose, not derived from source, so its
+  *accuracy* (as opposed to its completeness) is not tested — a description
+  could go stale if a token is repurposed for a different UI element without
+  updating its entry, and nothing would catch that. Accepted: the drift
+  guard's completeness check (every consumed token has *an* entry) is what
+  FR-003 actually requires and is what's mechanically enforceable; a
+  description's continued accuracy is a normal code-review concern for
+  future PRs that touch `src/`, the same as any other comment.
+
+**Neutral:**
+
+- The generated table currently lists 59 distinct tokens, not the 60 the
+  issue's own background section estimated. The scan is authoritative over
+  that estimate by construction (FR-002); the discrepancy traces to the
+  issue's manual family-by-family arithmetic (25 `--vscode-*` + 31
+  `--slashmd-*` where the source actually contains 24 and 30 respectively),
+  not to a change in what the code consumes.
+
+## References
+
+- Issue #50 (this decision)
+- Issue #52 (verveguy/liminis-editor) — the `--vscode-text` typo that
+  motivated the guard's "resolves without a host" assertion; fixed
+  independently before this issue's implementation began
+- Issue #51 (verveguy/liminis-editor) — the deferred `--vscode-*` rename this
+  inventory exists to make complete rather than approximate
+- `tests/adr-citations.test.ts`, `tests/package-manifest-contract.test.ts` —
+  the "scan repo, build a `Set`, diff, anti-vacuity-check" test shape this
+  guard follows
+- `docs/decisions/adr-081.md` — prior art for a generated-artifact-with-a-single-
+  owner pattern in this repo, though that artifact is gitignored where this
+  one is checked in and diffable

package/docs/decisions/adr-086.md

@@ -0,0 +1,147 @@
+# ADR-086: The Tailwind Requirement Is Dropped — Utility Classes Are Folded into `styles.css`
+
+**Date:** 2026-08-18
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** ADR-075, ADR-078
+**Issue:** #49 (verveguy/liminis-editor)
+
+## Context
+
+`@liminis/editor`'s styling system is semantic CSS plus custom properties —
+`src/styles.css` carries 2,477 lines, 358 selectors, and 60 `--vscode-*`
+variables, all of it resolved at runtime with no build-time dependency. A
+handful of Tailwind utility classes sat outside that system, at four sites:
+the loading state and error banner in `App.tsx`, the `App` component's
+`className` prop default, and the editor's root wrapper in `Editor.tsx`. Both
+ADR-075 and ADR-078 document what that coupling cost a consumer: Tailwind v4
+must be installed, its automatic source detection must be pointed at
+`node_modules/@liminis/editor` (or the real path under a pnpm workspace's
+`.pnpm/` tree) via an explicit `@source` directive, and — because the failure
+mode is silent, not an error — the resulting generated CSS must be manually
+inspected to confirm the utility actually appears.
+
+verveguy/liminis#1016 measured what that `@source` directive actually
+contributes in `liminis-app`, the one real consumer: two classes. `.ml-5`
+(the editor's left margin — real) and `.list-item` (an inert false positive,
+Tailwind's scanner matching the substring in
+`data-list-item-paragraph-break`). A whole build-time framework requirement,
+a documented footgun, and a silent failure mode, for one margin.
+
+## Decision
+
+**Fold all four Tailwind-utility sites into semantic CSS, so the package's
+styling contract is exactly "import `styles.css`."** Four new classes were
+added to `src/styles.css` — `.editor-loading`, `.editor-error-banner`,
+`.editor-app-root`, `.editor-container` — one per site, following the file's
+existing `editor-*` naming convention. Each reproduces Tailwind v4's
+default-theme resolution of the utility tokens it replaces exactly (e.g.
+`gap-3` → `0.75rem` under v4's `0.25rem` base spacing unit, `bg-red-500` →
+`oklch(63.7% 0.237 25.331)`, matching the file's existing use of `oklch(...)`
+for other colors), so the shipped visual result is unchanged.
+
+`.editor-inner` (`Editor.tsx`'s inner wrapper) keeps its existing name; only
+the redundant Tailwind `relative` utility is dropped from its `className`,
+replaced by `position: relative` added to the CSS rule directly. This
+mattered beyond the comment: `DragHandlePlugin.tsx` positions the drag
+handle, delete button, and drop indicator absolutely, relative to
+`.editor-inner`'s bounding rect, so that element has to stay a positioned
+ancestor.
+
+The `App` component's `className` prop default — `'min-h-screen p-0'` — was
+folded into the same treatment even though the issue's own source-reference
+list didn't name it, because it is a `className` under `src/` carrying
+Tailwind spacing tokens and both FR-005 and the issue's own acceptance
+criterion ("no Tailwind utility class remains in any `className` in `src/`")
+are written broadly enough to already cover it. It became `'editor-app-root'`,
+backed by `min-height: 100vh`; `p-0` was dropped without replacement since
+it's inert on a bare `div`.
+
+No Tailwind dependency removal was needed: `tailwindcss` was never a
+`package.json` dependency of this repository — the requirement was purely a
+documentation-level ask to consumers, satisfied by removing the "If you use
+Tailwind" section from `README.md`.
+
+## Amendments to ADR-075 / ADR-078
+
+Both ADRs' "Negative / costs" and "Consequences" sections describe the
+Tailwind `@source` requirement as an accepted, ongoing cost of the package
+boundary:
+
+- **ADR-075**, "Negative / costs" §1: names the `@source` directive as one of
+  four "build-config landmines" the package extraction introduced, guarded by
+  a test that lives in `liminis-app` (`editor-package-wiring.test.ts`), not
+  here. That landmine no longer exists — there is nothing left for the
+  `@source` directive to select, and the guard test (out of scope for this
+  repo, per the spec's Assumptions) becomes a check for an emptied-out
+  requirement rather than a real one.
+- **ADR-078**, "Consequences" §"Two silent failure modes": documents the
+  `@source` requirement as the second of two silent failure modes a consumer
+  can hit, alongside the missing-`styles.css`-import case. Only the
+  `styles.css`-import failure mode remains after this change; the Tailwind
+  one is eliminated at the source rather than mitigated.
+
+Neither ADR is edited in place — they remain an accurate record of what was
+decided when the package boundary was drawn. This ADR is the up-to-date
+pointer: a contributor who reads ADR-075 or ADR-078 today and needs to know
+whether the `@source` coupling still applies should land here.
+
+## Consequences
+
+**Good:**
+
+- The package's styling contract is exactly one instruction — import
+  `styles.css` — which every consumer already does. No Tailwind version
+  requirement, no `@source` directive, no `.pnpm/` path resolution, no manual
+  verification step.
+- The silent-failure mode ADR-078 warned about for the Tailwind `@source`
+  case is gone, not mitigated — there's nothing left to silently fail to
+  generate.
+- Removing the utility classes touches nothing in the `--vscode-*` /
+  `--slashmd-*` custom-property system (see ADR-085): the loading state's
+  `text-[var(--vscode-foreground)]` already round-tripped through an
+  existing, documented, defaulted token, and moving it into a plain CSS rule
+  adds nothing to and removes nothing from the theming contract's tracked
+  token sets.
+
+**Bad / accepted:**
+
+- Layout constants that a host's own Tailwind config could previously
+  influence (e.g. a customized spacing scale changing what `ml-5` resolved
+  to) are now fixed CSS values, not host-tunable. This is an intended
+  behavior change, not a regression — Tailwind resolves at build time and CSS
+  variables at runtime, so treating Tailwind as the theming surface would
+  have meant forcing a rebuild to retheme, which contradicts the existing
+  runtime `--vscode-*` API. It is why this ships as `0.2.0`, not a patch.
+- `bg-red-500`'s value is pinned to Tailwind v4's `oklch(63.7% 0.237 25.331)`
+  rather than v3's `#ef4444`. The two are visually near-identical but not
+  bit-identical on wide-gamut displays; v4 was chosen because the README
+  required Tailwind v4 up through this change, so v4 is what the shipped
+  color actually was.
+
+**Neutral:**
+
+- Adopting Tailwind as a peer dependency to gain a theming system was
+  explicitly considered and rejected as part of this decision, in favor of
+  the existing runtime CSS-variable API — see issue #50 and ADR-085 for what
+  that theming surface actually needs.
+- Consumer-side follow-ups — removing the now-inert `@source` line from
+  `liminis-app`'s `src/renderer/styles/main.css`, and from Zusammen if it has
+  one — are out of scope for this repository and tracked separately in their
+  own repos.
+
+## References
+
+- Issue #49 (this decision)
+- verveguy/liminis#1016 — measurement of the `@source` directive's actual
+  contribution in `liminis-app` (two classes, one of them a false positive)
+  that motivated this change
+- `docs/decisions/adr-075.md` — "Negative / costs" §1, names the `@source`
+  requirement this ADR removes
+- `docs/decisions/adr-078.md` — "Consequences", documents the `@source`
+  silent-failure mode this ADR eliminates
+- `docs/decisions/adr-085.md` — the runtime `--vscode-*` custom-property
+  theming system this decision leaves untouched, and the alternative to a
+  Tailwind-as-theming-surface approach
+- Issue #50 (verveguy/liminis-editor) — theming follow-up that explicitly
+  considered and rejected Tailwind as a peer dependency

package/docs/decisions/adr-087.md

@@ -0,0 +1,216 @@
+# ADR-087: The Theming Vocabulary Is Renamed to `--liminis-editor-*`, With Old Names Kept Live as Fallbacks
+
+**Date:** 2026-08-18
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** ADR-085
+**Issue:** #51 (verveguy/liminis-editor)
+
+## Context
+
+ADR-085 (#50) inventoried the editor's theming surface and found it was not
+one vocabulary but four, none of them the package's own: 30 `--slashmd-*`
+properties (the name of the upstream project this editor was derived from),
+24 `--vscode-*` properties (the name of the VS Code extension it also came
+from), 4 `--color-*`, and 1 `--checkbox-*`. `--vscode-*` at least reads as a
+recognisable theming convention; `--slashmd-*` — the largest group — implies
+a relationship to a project named "slashmd" that means nothing to an
+adopter and does not exist for them. The defect is the inconsistency itself:
+renaming only one of the four families would leave three, which is strictly
+less coherent than renaming all of them or none. Since this is already a
+breaking change and each consumer migration has a measured cost, splitting
+it into a second pass later would mean paying that cost twice.
+
+An org-wide `--liminis-*` vocabulary — splitting the ~42 tokens that are
+generic design tokens (`foreground`, `border`, `link`, `font-family`, …)
+from the editor-specific rest — was considered and rejected. Not every
+consumer of this package is a Liminis product: Zusammen is a separate
+product, and external adopters are neither. A non-Liminis host would
+otherwise be forced to declare Liminis-branded globals for a component it
+merely depends on. `--liminis-editor-*` keeps the future open in the
+correct direction — if an org-wide `--liminis-*` vocabulary emerges later,
+Liminis apps can map individual tokens
+(`--liminis-editor-foreground: var(--liminis-foreground);`) without
+requiring non-Liminis adopters to do anything, whereas retracting org-wide
+globals once adopters depend on them is not similarly available.
+
+Unresolved CSS custom properties do not error — the declaration is dropped
+and the value falls back to inherited or initial. A clean-break rename
+would therefore strip theming from `liminis-app` and Zusammen (and any
+external adopter) silently: no failing test, no console warning, nothing
+pointing at the cause. The issue's User Story 2 requires that a host
+supplying only the old names keep theming exactly as before, with the
+deprecation communicated in the release notes rather than enforced by
+breakage.
+
+## Decision
+
+**All 59 tokens move to one prefix, `--liminis-editor-*`, no split tier.**
+FR-001 rejects the org-wide/editor-specific split explicitly (see Context);
+every consumed property becomes `--liminis-editor-<suffix>`. One collision
+required a deliberate deviation from pure prefix-stripping:
+`--checkbox-border` and `--vscode-border` both strip to the bare suffix
+`border`. The checkbox token keeps its discriminator —
+`--liminis-editor-checkbox-border` — rather than colliding with
+`--liminis-editor-border`. No other suffix is touched; pre-existing
+inconsistent casing (`--vscode-focusBorder` vs. `--vscode-focus-border`)
+carries over unchanged into `--liminis-editor-focusBorder` /
+`--liminis-editor-focus-border`, since normalizing it is a separate,
+unrequested migration surface.
+
+**Defaults stay declared under the old name; only consumption sites move.**
+This is the one non-obvious part of the design, and it runs opposite to the
+"obviously symmetric" alternative (rename the `:root`/`.dark` declaration
+too, and add a fallback in the `var()` call). That alternative is broken:
+once the package's own `:root` unconditionally declares
+`--liminis-editor-x`, that property is never unset at the point of use, so
+a host overriding only the old name is silently ignored — the two custom
+properties resolve independently, and the browser does not fail over from
+one name to the other based on whether the *other* name was touched by a
+host. The design actually shipped: `styles.css`'s `:root`/`.dark`/
+`@media print` blocks are structurally untouched, still declaring
+`--vscode-foreground` etc. directly; only every `var(...)` **consumption**
+site was rewritten, to
+`var(--liminis-editor-x, var(--old-name-x, ...existing fallback if any))`.
+Concretely, all three host states now resolve correctly:
+
+- Host sets nothing → `--liminis-editor-x` unset → falls to `--old-name-x`
+  → resolves to the package's still-old-named default. Unchanged.
+- Host sets only the new name → resolves directly.
+- Host sets only the old name (today's actual `liminis-app`/Zusammen state)
+  → `--liminis-editor-x` still unset anywhere → falls to `--old-name-x` →
+  the host's override. Unchanged from pre-rename behavior.
+
+One visible side effect: every renamed token's "Has a default" column in
+the generated `README.md` table now reads "No (inline fallback only)",
+including tokens that read "Yes" before this change — the *new* name is
+never declared directly, only ever satisfied through the fallback chain.
+This is not a defect; it is the mechanism that makes the compatibility
+story work, called out here and in `README.md` so a future contributor
+does not "fix" it by giving the new name its own declaration (which would
+silently reintroduce the exact breakage this ADR exists to avoid).
+
+**The extraction script (#50's `scripts/lib/theming-tokens.mjs`) gains a
+primary/nested distinction.** Wrapping all 59 consumption sites in a
+two-level `var()` chain, without changing the extraction logic, would have
+made the flat, nesting-unaware regex scan count the nested old-name
+reference as a second, independently "consumed" token at every one of the
+59 sites — up to 118 entries instead of 59, doubling the README table and
+the `TOKEN_DESCRIPTIONS` maintenance burden, and violating SC-001 ("a
+previous-family name appears only as a fallback, never as the primary
+consumed name"). `consumptionSitesIn` now walks each file with a
+paren-aware scanner tracking `var()` nesting depth; `consumedTokens` keeps
+only depth-0 sites as "consumed," and each depth-0 site records the name of
+whatever `var()` call is nested immediately inside its own fallback (its
+`immediateFallback`) — which, after this rename, is always the token's
+previous name.
+
+**`PREVIOUS_NAME` is an explicit, checked-in table, not derived by
+convention.** In this codebase "strip the old prefix, add
+`--liminis-editor-`" happens to reconstruct the new name from the old one
+(modulo the one collision above), but the drift guard needs the *reverse*
+direction — given a new name, which specific old family did it actually
+come from — and reconstructing that from the new name alone is exactly the
+kind of assumption FR-011 exists to not rely on. `PREVIOUS_NAME` maps all
+59 new names to their real previous names, and a new function,
+`resolvesToPreviousName(name, consumed)`, checks every one of a token's
+consumption sites' `immediateFallback` against it.
+
+**The two pre-existing sites with no `:root`/`.dark` default of their own —
+`--vscode-input-bg` (default was `var(--vscode-code-bg)`) and
+`--vscode-foreground-muted` (default was `var(--vscode-border)`) — get a
+four-level cascade**, e.g.
+`var(--liminis-editor-input-bg, var(--vscode-input-bg, var(--liminis-editor-code-bg, var(--vscode-code-bg))))`.
+No special-casing was needed to produce this: rewriting every occurrence of
+`var(--old-name...)` (including ones already nested inside another token's
+fallback) independently, in a single generic pass per token, composes
+correctly regardless of processing order — the outer wrap's fallback
+argument is whatever text was already there, including an inner match that
+gets wrapped by its own pass. This keeps these two tokens' behavior
+consistent with every other consumption of `--liminis-editor-code-bg` /
+`--liminis-editor-border`: a host overriding only the new name of the
+*inner* token still takes effect, rather than the two sites bypassing the
+new vocabulary as a special case.
+
+**Drift guard extended, not replaced (FR-011).**
+`tests/theming-contract.test.ts` gained a fourth assertion — every consumed
+token for which `PREVIOUS_NAME` has an entry must satisfy
+`resolvesToPreviousName` at every call site — plus a mutation test proving
+it fires for a renamed token consumed with no fallback at all. The three
+pre-existing assertions from ADR-085 (documented-equals-consumed,
+resolves-without-host, has-a-description) are unchanged in shape; one of
+their existing mutation fixtures, which referenced `--checkbox-border`
+directly as a "described" token, was updated to use the new
+`--liminis-editor-checkbox-border` name now that `TOKEN_DESCRIPTIONS` is
+keyed by the new vocabulary.
+
+**Compatibility is documented as deprecation, not silence.** `README.md`
+gained a "Migrating from the old names" section, and `CHANGELOG.md` (new —
+no changelog existed in this repo before) documents, under the shared
+`0.2.0` entry alongside #49, that the four old prefixes are deprecated and
+will be removed in a future major release.
+
+## Consequences
+
+**Good:**
+
+- A host that upgrades and changes nothing keeps its exact theme — the
+  fallback-chain design makes User Story 2's independent test (host
+  supplies only old names, theme resolves unchanged) true by construction,
+  not by accident.
+- The vocabulary an adopter reads about is now singular and package-owned;
+  none of the 59 documented properties names VS Code or an upstream project
+  the adopter has no relationship to.
+- A partial rename — a new `--liminis-editor-*` name introduced without its
+  fallback to the correct previous name — now fails CI (FR-011), rather
+  than merging as a silent, host-breaking regression discoverable only by a
+  human noticing a host's theme went blank.
+- The extraction script's primary/nested distinction is general: it holds
+  for the two pre-existing nested-default sites without any special-casing
+  in the scanner itself, and generalizes to any future token that needs a
+  multi-level fallback.
+
+**Bad / accepted:**
+
+- Every renamed token's "Has a default" column now reads "No (inline
+  fallback only)," even for the ~50 tokens that had a direct `:root`/`.dark`
+  declaration before this change. This is a real reduction in what that
+  column communicates (it no longer distinguishes "has a real default" from
+  "resolves via fallback chain" for the common case) — accepted as the
+  direct, unavoidable consequence of keeping compatibility, and called out
+  explicitly in `README.md` so it reads as intentional rather than a
+  generator bug.
+- Every one of the 59 tokens now carries a permanent, two-name fallback
+  chain in `styles.css` and the five `.tsx` consumption sites, which stays
+  until a future major release removes the old names — a standing
+  verbosity cost in the source, not just the generated docs.
+- `PREVIOUS_NAME` is a second, hand-maintained mapping the drift guard
+  depends on (not derived from `TOKEN_DESCRIPTIONS` or any other single
+  source), so a future contributor who renames a *new* token years from now
+  needs to know it exists.
+
+**Neutral:**
+
+- `--checkbox-border` renaming to `--liminis-editor-checkbox-border`,
+  rather than the "strip the prefix" convention's `--liminis-editor-border`,
+  is the one place the new vocabulary is not a mechanical function of the
+  old one. It is the correct fix for a genuine name collision, not a
+  stylistic choice, and is recorded directly in `PREVIOUS_NAME`'s
+  definition in `scripts/lib/theming-tokens.mjs` so it stays visible.
+- `liminis-app` needed no code change for this issue: it supplies none of
+  the old-prefix overrides today, so its `--color-primary`/
+  `--color-muted-foreground` Tailwind `@theme` tokens (coincidental naming
+  overlap with two of the renamed tokens, not deliberate editor-theming
+  wiring) are unaffected either way.
+
+## References
+
+- Issue #50 / ADR-085 (verveguy/liminis-editor) — the generated inventory
+  and drift guard this rename uses as its worklist and extends
+- Issue #52 (verveguy/liminis-editor) — corrected the consumed-token count
+  from 60 to 59, which this issue's scope decision (all 59, one prefix)
+  builds on
+- Issue #49 / ADR-086 (verveguy/liminis-editor) — the sibling breaking
+  change sharing this `0.2.0` release
+- [verveguy/zusammen#125](https://github.com/verveguy/zusammen/issues/125)
+  — ported this rename into Zusammen's vendored copy of the editor source