remarque-tokens 0.7.0 → 0.9.0

package/AGENT_RULES.md

@@ -26,7 +26,7 @@ Execute in this exact order. Do not skip steps. Do not reorder.
 
 8. **Validate readability on mobile** before adding any visual polish.
 
-9. **Verify every page conforms** to one of the four archetypes (Essay, Project Dossier, Notebook, Landing).
+9. **Verify every page conforms** to one of the seven archetypes (Essay, Project Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery).
 
 **Why this order matters:** Most agents build polished components first and bolt on typography later. That produces the exact aesthetic Remarque exists to prevent. Typography and prose are the foundation. Everything else is furniture.
 
@@ -41,6 +41,7 @@ These are not guidelines. Agents must follow them literally.
 - NEVER change a value in `tokens-core.css` (or its tokens' values anywhere) — core tokens are Remarque's identity; changing them means the project has forked the system
 - Site personalization happens ONLY by overriding `tokens-palette.css` tokens (font slots from the approved pairings, colors, accent, `--content-reading` per the measure table) in a stylesheet loaded after the tokens
 - After ANY palette change, run the audit and fix every failure before shipping — `npm run audit` inside this repo; `npx remarque-audit --palette <file> --src <dir>` in a consumer project (the npm script only exists here)
+- A generated palette override (from `npx remarque-theme <light> --dark <dark>`, see REMARQUE.md "Color Providers") is regenerated, never hand-edited — if it needs to change, change the source theme slugs and re-run `remarque-theme`, don't patch the emitted CSS directly
 
 ### Typography
 
@@ -160,6 +161,8 @@ project/
     └── notes                 # Notebook archetype
 ```
 
+Three further archetypes — Reference/Docs, Changelog, Gallery — are specified in REMARQUE.md but have no reference page in this repo's demo site yet; build them per spec, they follow the same file-structure conventions as the four above (e.g. `docs/[slug]`, `changelog`, `gallery` or `browse`).
+
 ### Implementation Pitfalls (learned from reference implementation)
 
 1. **Tailwind spacing collision:** Never map Remarque's `--space-N` values onto Tailwind's default numeric spacing keys — in v4 `@theme` that means no `--spacing-9`…`--spacing-12`, and in the v3 config no `spacing: { "5"…"12" }` overrides — or `mt-12` produces 192px instead of 48px. Both shipped artifacts namespace instead: the v3 config exposes `mt-remarque-9` etc., the reference v4 `@theme` uses `--spacing-remarque-N`. Use those, or `var(--space-N)` in arbitrary values.
@@ -195,7 +198,7 @@ Before considering any implementation complete, verify:
 - [ ] Accent color appears in ≤2 roles per viewport
 - [ ] No scroll-triggered or entrance animations exist
 - [ ] Every image has a 1px border and mono caption
-- [ ] Every page maps to an archetype (Essay, Dossier, Notebook, Landing)
+- [ ] Every page maps to an archetype (Essay, Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery)
 - [ ] Mobile version is roomy — not a compressed desktop layout
 - [ ] Mobile nav links have ≥44px touch targets
 - [ ] No pure white or pure black backgrounds

package/CHANGELOG.md

@@ -4,6 +4,102 @@ All notable changes to `remarque-tokens` are documented here. Token value
 changes always state the design rationale — downstream sites pin against
 these entries when syncing.
 
+## 0.9.0 — 2026-07-22
+
+Color-provider bridge release (consensus-ratified 7-0, higher_order panel;
+closes #75 — Phase 1 of the color-provider integration; Phase 2/3 tracked
+in #76).
+
+### Added
+- **`remarque-theme` bin** (#75): `npx remarque-theme <light-slug> --dark
+  <dark-slug> [-o out.css]` derives a full 15-slot palette-tier override
+  from an `@williamzujkowski/oklch-terminal-themes` light+dark pair.
+  Terminal themes carry only `background/foreground/cursor/selection` +
+  16 ANSI slots — most of Remarque's semantic slots don't map directly,
+  and most themes fail the AAA `fg-muted` 7:1 line as authored. The bridge
+  derives instead: hue + chroma come from the theme, lightness is solved
+  per slot by binary search against the exact Enforcement Checklist
+  targets (in-gamut chroma clamping inside the solver, round-then-verify
+  to avoid float rounding pushing a borderline value back out of gamut).
+  Output passes `remarque-audit` **by construction** — the script
+  self-verifies the same contrast + gamut checks in-process before it
+  will emit anything.
+- **Security hardening** (#75, panel security review): both slugs are
+  validated against the package's own `index.json` *before* any path is
+  built from them (the actual guard against path traversal, not the slug
+  regex, which is defense-in-depth); every OKLCH triplet read from theme
+  JSON is validated as finite numbers before use; CSS is never built by
+  string-interpolating raw JSON — every emitted number has passed through
+  our own rounding + validation. Light/dark polarity (`isDark`) is
+  enforced against the requested slugs.
+- **`scripts/test-theme.mjs`** (#75): a corpus property test enumerating
+  every light+dark pair in the installed `oklch-terminal-themes` package
+  by name-stem (47 pairs at the pinned 0.1.0 dataset) — every pair must
+  derive AND pass the real `audit.mjs`, not a sample. Also covers unknown
+  slugs, polarity mismatches, traversal-looking slugs, and that the
+  output declares only palette-tier custom properties. Wired into CI
+  alongside `test-audit.mjs`/`test-drift.mjs`.
+- **`@williamzujkowski/oklch-terminal-themes`** pinned exact at `0.1.0` in
+  `devDependencies`, and listed as an optional `^0.1.0` peerDependency —
+  consumers who want `remarque-theme` install it themselves; it is never
+  required to use the rest of the package.
+- REMARQUE.md: new "Color Providers" section positioning the palette tier
+  as theme-suppliable, with `oklch-terminal-themes` as the reference
+  provider and the pairing contract stated explicitly (`--dark` is
+  required; upstream pairing metadata tracked in
+  `oklch-terminal-themes#128`). AGENT_RULES.md: a rule against hand-editing
+  a generated palette — regenerate it instead.
+
+No core-tier token values changed in this release. `tokens-palette.css`
+(the shipped default palette) is also unchanged — `remarque-theme` is an
+opt-in alternate source for the palette tier, not a replacement for it.
+
+## 0.8.0 — 2026-07-21
+
+Archetype-vocabulary and AI-agent-packaging release (design review; closes
+#55, closes #57).
+
+### Added
+- **Three new page archetypes** (#55): Reference/Docs (persistent nav
+  rail, breadcrumb kicker, prev/next footer — reuses Essay's three-column
+  shape), Changelog (mono version/date headline, grouped Added/Changed/
+  Fixed lists — built from Notebook's entry structure), and Gallery
+  (content-wide cover grids, covers exempt from the reading-width cap,
+  border-only hover — formalized from tsundoku's documented reference
+  implementation, cited directly in REMARQUE.md). Seven archetypes total;
+  agents must not invent an eighth.
+- **Plate** (#55): a screenshot-heavy-page subsection of Image Treatment —
+  numbered mono captions, a narrow 2-up exception for terminal captures.
+- **CLI-tool landing guidance** (#55): a scoped, rationale-argued exception
+  to Landing's no-CTA rule for a single mono install command block.
+- **Dataviz Tokens** (#55): chart grid/axis/categorical-ramp mapped onto
+  existing tokens and required to pass the audit — citing tsundoku's
+  orthogonal category-color system as precedent and naming the one gap
+  (never run through `remarque-audit`'s `CHECKS` array) this guidance
+  closes.
+- **`remarque-tokens/agent-rules` and `remarque-tokens/spec` exports**
+  (#57): both files were already in `files`; this ships them as named
+  subpaths so a consumer can `require.resolve('remarque-tokens/agent-rules')`
+  instead of hardcoding a `node_modules` path.
+- **`.claude/skills/remarque/SKILL.md`** (#57): a Claude Code skill
+  triggering on "remarque" / "design system" / new-page work. Loads
+  `AGENT_RULES.md` + `REMARQUE.md` + `tokens.json`, states the token-tier
+  rules, the audit command, and Pitfalls #6/#7 (string-form `@import`;
+  unlayered token import under Tailwind v4) inline — both pass a green
+  build while silently breaking, so they're worth surfacing without a
+  file round-trip.
+- **`/tokens.json` on the demo site** (#57): `site/scripts/copy-tokens-json.mjs`
+  runs as a prebuild step (`npm run build` in `site/`), copying the
+  installed package's `tokens.json` into `public/` so it ships at
+  `https://williamzujkowski.github.io/remarque/tokens.json` — a remote
+  agent can fetch current token values instead of trusting training data.
+  The copy is generated, not a source file (`site/public/tokens.json` is
+  gitignored).
+- Root README's "For AI Agents" section documents all three packaging
+  additions above.
+
+No core-tier token values changed in this release.
+
 ## 0.7.0 — 2026-07-21
 
 Typographic-completeness release (design review, #50/#51/#54): the

package/README.md

@@ -58,6 +58,11 @@ See: REMARQUE.md for specification, AGENT_RULES.md for implementation contract,
 
 The agent rules define build order, non-negotiable rules, disallowed patterns, and a quality checklist. Every decision is specified — agents don't need to guess.
 
+Packaging for agent tooling:
+- **npm exports:** `remarque-tokens/agent-rules` (→ `AGENT_RULES.md`) and `remarque-tokens/spec` (→ `REMARQUE.md`), alongside the existing `remarque-tokens/tokens.json`, so a project can point an agent at `node_modules/remarque-tokens/AGENT_RULES.md` without hardcoding a filename.
+- **Claude Code skill:** [`.claude/skills/remarque/SKILL.md`](.claude/skills/remarque/SKILL.md) — triggers on "remarque" / "design system" / new-page work, loads all three files, and states the tier rules, the audit command, and the two build-time pitfalls (unlayered-token-import, string-form `@import`) that pass a green build while silently breaking.
+- **Live tokens endpoint:** the demo site serves the current `tokens.json` at **https://williamzujkowski.github.io/remarque/tokens.json** — a remote agent can fetch current token values directly instead of trusting training data.
+
 ## Files
 
 | File | Purpose |
@@ -83,14 +88,17 @@ The agent rules define build order, non-negotiable rules, disallowed patterns, a
 
 ## Page Archetypes
 
-Every page conforms to one of four archetypes:
+Every page conforms to one of seven archetypes:
 
 - **Essay** — long-form writing with serif title, mono metadata, narrow reading column
 - **Project Dossier** — structured project page with metadata block and architecture section
 - **Notebook** — short-form notes with mono timestamps, no cards
 - **Landing** — identity statement, content navigation, generous whitespace
+- **Reference/Docs** — persistent nav rail, breadcrumb kicker, prev/next footer (reuses Essay's three-column shape)
+- **Changelog** — mono version/date headlines, grouped Added/Changed/Fixed lists (built from Notebook's entry structure)
+- **Gallery** — cover-grid pages at `--content-wide`, covers exempt from the reading-width cap (formalized from tsundoku's reference implementation)
 
-See the [live demo](https://williamzujkowski.github.io/remarque/) for all four archetypes in action.
+See the [live demo](https://williamzujkowski.github.io/remarque/) for the original four archetypes in action — Reference/Docs, Changelog, and Gallery are specified in REMARQUE.md but don't yet have a demo page in this repo.
 
 ## Design Decisions
 

package/REMARQUE.md

@@ -70,6 +70,24 @@ This makes compliance mechanical: a site that overrides only palette-tier tokens
 
 ---
 
+## Color Providers
+
+The palette tier (all `--color-*` tokens) can be *supplied* rather than hand-authored — Remarque focuses on typography, and a color-provider package can own the personalization surface it already sanctions.
+
+[`@williamzujkowski/oklch-terminal-themes`](https://www.npmjs.com/package/@williamzujkowski/oklch-terminal-themes) is the reference provider: a dataset of terminal color schemes converted to OKLCH. Run it through the bundled bridge:
+
+```
+npx remarque-theme <light-slug> --dark <dark-slug> [-o palette-override.css]
+```
+
+Terminal themes carry only `background/foreground/cursor/selection` + 16 ANSI slots — a few of Remarque's 15 semantic slots map directly, and most themes fail the AAA `fg-muted` 7:1 line as authored. So `remarque-theme` *derives* rather than maps: **hue and chroma carry the theme's personality; lightness is solved per slot** (binary search against the same contrast targets as the Enforcement Checklist below, with in-gamut chroma clamping) so the output passes `remarque-audit` by construction. The accent hue comes from the theme's cursor color if it's chromatic, otherwise the most saturated classic ANSI color, and is kept consistent between the light and dark half of a pair.
+
+The audit remains the gate regardless of provenance — `remarque-theme` self-verifies its own output against the same checks before it will emit anything, but a site that hand-edits a generated palette (or points at a provider with pathological input colors) still runs through `remarque-audit` in CI like any other palette.
+
+**Pairing contract:** the dataset does not yet carry light/dark pairing metadata (tracked upstream: [`oklch-terminal-themes#128`](https://github.com/williamzujkowski/oklch-terminal-themes/issues/128)), so `--dark <slug>` is explicitly required — there is no implicit or guessed dark counterpart. `remarque-theme` also rejects a light slug that isn't tagged `isDark: false` and a dark slug that isn't tagged `isDark: true`.
+
+---
+
 ## Font Slots
 
 Remarque uses a three-slot font system. Each slot has a strict role, and each slot accepts a small set of approved faces — swap the face, keep the role.
@@ -172,7 +190,7 @@ Never mix the two: a numeral inside running prose should never be tabular, and a
 
 ## Content Density Rule
 
-No page should show more than three distinct content sections above the fold. The first screen of any page contains only: title, metadata, and the opening of content. Hero sections with CTAs, feature grids, and social proof are not part of Remarque's vocabulary.
+No page should show more than three distinct content sections above the fold. The first screen of any page contains only: title, metadata, and the opening of content. Hero sections with CTAs, feature grids, and social proof are not part of Remarque's vocabulary. (The CLI-tool landing install block, see the Landing archetype, is a single command — not a CTA — and does not count against this rule.)
 
 ---
 
@@ -187,6 +205,28 @@ Remarque is typography-first, but projects include screenshots, architecture dia
 - No rounded corners on images beyond `--radius-sm`
 - Images are never decorative — every image must serve the content
 
+### Plate (screenshot-heavy pages)
+
+Reference/Docs and Project Dossier pages often need to show several screenshots — six or more UI captures walking through a workflow — where "one image at a time" doesn't scale. Plate is the sanctioned pattern; everything above still applies, it only adds:
+
+- Default to single-column figures at `--content-reading` width, one screenshot per figure
+- Every figure gets a numbered mono caption in the form `Fig. 01 — description` (`--font-mono`, `--text-meta`) — the number is mandatory once a page has more than one figure, so prose can cross-reference a specific plate
+- A 2-up grid is permitted only for terminal/CLI captures, and only at `--content-standard` width — the one sanctioned exception to "images never wider than `--content-reading`," reserved for this narrow case
+- A page with six or more plates gets prev/next figure navigation (mono, matching Reference/Docs' footer convention) rather than an unbroken scroll
+
+---
+
+## Dataviz Tokens
+
+Charts are not yet a first-class Remarque surface, but tools built with the system inevitably need them. Rather than inventing chart-specific tokens, map dataviz elements onto vocabulary that already exists, so a chart survives a palette swap the same way prose and chrome do:
+
+- **Grid lines** use `--color-border` — never a separate "chart gray." Grid lines are structural, not decorative, and already have a sanctioned quiet role.
+- **Axis text and tick labels** use `--font-mono` at `--text-meta`, `--color-muted` — the same register as metadata rows and captions, never the body or display face.
+- **Categorical color ramp** is derived, not hand-picked: rotate hue at the accent's lightness/chroma steps — the same discipline "Changing the Accent Hue" already prescribes (fix lightness, vary hue, reduce chroma until every value clears the gamut) — producing a small hue family distinct from `--color-accent` itself, so chart color is never mistaken for the system's one interactive signal.
+- That ramp must be **audit-validated**, exactly like a palette override: every ramp color needs to clear gamut and 4.5:1 contrast against `--color-bg`/`--color-surface` in both themes before it ships.
+
+**Precedent:** [tsundoku](https://github.com/williamzujkowski/tsundoku) built the underlying pattern already — its `DESIGN-NOTES.md` documents an 8-hue "orthogonal category system" (`--pop-pink`/`--pop-blue`/`--pop-green`/etc.), kept deliberately separate from `--color-accent` and used for content taxonomy (book categories, reading status) rather than interactivity. It held those hues to roughly the same lightness/contrast discipline as its audited palette, but by its own admission the hues were **never run through `remarque-audit`'s `CHECKS` array** — that is the one gap this guidance closes. A dataviz ramp should follow tsundoku's separation-from-accent instinct, but unlike its precedent, it must pass the audit before it ships.
+
 ---
 
 ## Motion Rules
@@ -324,7 +364,7 @@ This order is not a suggestion. It is the tiebreaker for every design decision.
 
 ## Page Archetypes
 
-Every page built with Remarque must conform to one of these four archetypes. Agents and implementers should not invent new page structures.
+Every page built with Remarque must conform to one of these seven archetypes: Essay, Project Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery. Agents and implementers should not invent new page structures — the last three exist precisely because real downstream projects (tsundoku, and the multi-site review that produced this revision) needed shapes the first four actively fought, and inventing an unsanctioned workaround is worse than extending the vocabulary here.
 
 ### Essay
 
@@ -396,6 +436,7 @@ The homepage or entry point. Sets the tone.
 **Optionally includes:**
 - Recent entries or updates (3–5 max)
 - A brief "about" line
+- **CLI-tool landing only:** a single mono install command block (styled as prose `<pre>`, copy button allowed) — the one sanctioned interactive element on an otherwise CTA-free page — and an optional `--help`-output figure (follows the Plate convention, see Image Treatment)
 
 **Never includes:**
 - Hero images or banners
@@ -404,6 +445,67 @@ The homepage or entry point. Sets the tone.
 - Testimonial carousels
 - Newsletter signup forms above the fold
 
+The CLI install block is not a CTA exception in disguise — it is the single piece of information a CLI tool's landing page cannot omit (how do I get this), same status as a book's title. One block, one command, no surrounding marketing copy. A page with an install block *and* a separate "Sign up now" button has smuggled in a second CTA and fails this archetype.
+
+### Reference/Docs
+
+Persistent technical documentation: API references, config guides, multi-page manuals. Reuses the Essay archetype's existing three-column shape (nav rail outside the reading column · reading column · optional desktop ToC outside the reading column) — this is not a new layout engine, only a different left rail.
+
+**Always includes:**
+- A persistent left nav rail listing every doc page (mono, quiet, `--text-meta` — a list of links, not a component), sitting outside the reading column exactly like Essay's optional ToC sits outside it on the other side
+- A breadcrumb kicker above the title (mono, `--text-meta`, e.g. `Reference / Configuration`)
+- Content constrained to `--content-reading`, matching Essay's prose column
+- A low-noise prev/next footer nav between adjacent doc pages (mono, matching Essay's footer nav)
+
+**Optionally includes:**
+- Tables and code blocks widening past the reading column to `--content-standard` when the content genuinely needs the room (a config reference table, a wide code sample) — the surrounding prose stays at `--content-reading`
+- A desktop-only "on this page" ToC, reusing Essay's optional side-ToC convention, on the side opposite the nav rail
+
+**Never includes:**
+- Sidebar content mixed *into* the reading column itself (the nav rail is a fourth structural region, not reading-column content — same rule Essay already enforces for its own ToC)
+- Card grids for the page listing (the nav rail is a list, not a grid of cards)
+- More than one accent color
+- CTAs, feature grids, or any Landing-archetype vocabulary
+
+### Changelog
+
+A tool or project's primary log of released changes. Built from the Notebook archetype's entry structure, not a new component: compact, mono-timestamped, content-forward entries, applied to version history instead of notes.
+
+**Always includes:**
+- A mono version + date headline per entry (e.g. `0.7.0 — 2026-07-21`) — semver renders as plain mono text, never a colored pill or badge
+- Grouped category lists per entry (Added / Changed / Fixed, or whatever categories the project uses), reusing Notebook's compact entry rhythm
+- Reverse-chronological order, most recent release first
+
+**Optionally includes:**
+- An inline mono link to the relevant issue/PR per line item
+- A "compare" or diff link per version, mono, in the entry headline row
+
+**Never includes:**
+- Semver rendered as a pill/badge (`.rounded-full` chips, colored status pills) — plain mono text only, same rule as tags elsewhere in the system
+- Card-based per-version layout
+- Marketing framing of a change ("Exciting new feature!") — changelog prose stays as flat and factual as commit messages
+
+A changelog embedded as an optional subsection of a Project Dossier (already sanctioned) remains valid for short update logs. Promote to the standalone Changelog archetype once the log is long enough, or important enough, to be the page rather than a section of one — typically once a tool ships its own versioned releases.
+
+### Gallery
+
+Cover-grid and catalog pages — a page whose primary content unit is a grid of images with a caption, not prose. None of the other archetypes are shaped for this: they are all fundamentally text/document-shaped. **Reference implementation: [tsundoku](https://github.com/williamzujkowski/tsundoku)**, which needed this shape immediately for its book-catalog `/browse` grid and documented it as an informal fifth archetype in its `DESIGN-NOTES.md` before this spec existed; Gallery formalizes that implementation rather than inventing a new one.
+
+**Always includes:**
+- A grid container widened beyond `--content-standard` (72rem) to `--content-wide` (88rem) — Gallery is the only archetype permitted to exceed `--content-standard`, because a grid of cover-aspect thumbnails needs more horizontal room before it feels cramped than an essay or a dossier ever would
+- Cover/thumbnail images exempt from the `--content-reading` width cap that Image Treatment otherwise mandates — cover art *is* the content here, not illustrative decoration of prose. Every other Image Treatment rule still applies without exception: 1px `--color-border`, no drop shadow, mono captions
+- Grid item hover restricted to a border-color shift only (`--motion-fast`) — no scale, no lift, no shadow growth, matching Motion Rules' general prohibition on attention-seeking animation
+- Grid density driven by content (`repeat(auto-fill, minmax(...))` or breakpoint-based column counts), never a fixed card size that fights the image's native aspect ratio
+
+**Optionally includes:**
+- Prose-bearing sections within a Gallery page (an "about" blurb, an item description) narrowed back down to `--content-reading` — the widened container serves the grid only, not every element on the page
+- Mono captions under each cover (title, author, or other item metadata)
+
+**Never includes:**
+- Card shadows or scale/lift-on-hover
+- Masonry layouts (Notebook's existing prohibition applies here too — a fixed-ratio grid only)
+- The `--content-wide` container used for anything other than the grid itself
+
 ---
 
 ## Signature Moves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "engines": {
     "node": ">=18"
   },
@@ -23,12 +23,24 @@
   "main": "tokens.css",
   "bin": {
     "remarque-audit": "scripts/audit.mjs",
-    "remarque-drift": "scripts/drift-check.mjs"
+    "remarque-drift": "scripts/drift-check.mjs",
+    "remarque-theme": "scripts/theme.mjs"
   },
   "scripts": {
     "audit": "node scripts/audit.mjs",
     "drift": "node scripts/drift-check.mjs"
   },
+  "devDependencies": {
+    "@williamzujkowski/oklch-terminal-themes": "0.1.0"
+  },
+  "peerDependencies": {
+    "@williamzujkowski/oklch-terminal-themes": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@williamzujkowski/oklch-terminal-themes": {
+      "optional": true
+    }
+  },
   "exports": {
     ".": "./tokens.css",
     "./tokens": "./tokens.css",
@@ -47,6 +59,8 @@
     "./prose.css": "./prose.css",
     "./print": "./print.css",
     "./print.css": "./print.css",
+    "./agent-rules": "./AGENT_RULES.md",
+    "./spec": "./REMARQUE.md",
     "./package.json": "./package.json"
   },
   "files": [
@@ -57,6 +71,7 @@
     "fonts/",
     "scripts/audit.mjs",
     "scripts/drift-check.mjs",
+    "scripts/theme.mjs",
     "tailwind.config.js",
     "REMARQUE.md",
     "AGENT_RULES.md",

package/scripts/theme.mjs

@@ -0,0 +1,440 @@
+#!/usr/bin/env node
+/*
+ * remarque-theme — derive a Remarque palette-tier override from an
+ * @williamzujkowski/oklch-terminal-themes light+dark pair.
+ *
+ *   node scripts/theme.mjs <light-slug> --dark <dark-slug> [-o out.css]
+ *   npx remarque-theme <light-slug> --dark <dark-slug> [-o out.css]
+ *
+ * Terminal themes carry only background/foreground/cursor/selection + 16
+ * ANSI slots — most of Remarque's 15 semantic slots don't map directly,
+ * and most themes fail the AAA fg-muted 7:1 line as authored. So this
+ * DERIVES rather than maps: hue + chroma come from the theme (its
+ * personality), lightness is solved per slot to hit the exact ratio
+ * targets from REMARQUE.md's Enforcement Checklist (binary search over
+ * L, with in-gamut chroma clamping inside the solver). Output passes
+ * remarque-audit BY CONSTRUCTION — this script self-verifies the same
+ * pairings before it will emit anything.
+ *
+ * Security (non-negotiable, per the panel security review on #75):
+ *   - Both slugs are checked against the package's own index.json BEFORE
+ *     any path is built from them — an unknown slug never reaches a
+ *     require.resolve() or fs call. This is the actual guard against
+ *     path traversal; the slug regex below is defense-in-depth, not the
+ *     primary control.
+ *   - Every OKLCH triplet read from theme JSON is validated as finite
+ *     numbers (l in [0,1], c >= 0, h in [0,360)) before it touches any
+ *     math. Malformed/hostile theme JSON fails loudly, never silently.
+ *   - CSS is never built by string-interpolating raw JSON. Every number
+ *     emitted has passed through our own rounding + validation first.
+ */
+
+import { createRequire } from 'node:module';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const PKG_SPEC = '@williamzujkowski/oklch-terminal-themes';
+const HERE = dirname(fileURLToPath(import.meta.url));
+let OWN_VERSION = 'unknown';
+try {
+  OWN_VERSION = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version;
+} catch { /* provenance is best-effort */ }
+
+const USAGE = `usage: remarque-theme <light-slug> --dark <dark-slug> [-o out.css]
+
+  <light-slug>     slug of a theme with isDark=false in ${PKG_SPEC}
+  --dark <slug>    slug of a theme with isDark=true (required — the
+                    dataset has no light/dark pairing metadata yet, see
+                    oklch-terminal-themes#128)
+  -o, --output     write the derived palette here instead of stdout`;
+
+function die(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
+/* ── CLI args ─────────────────────────────────────────────────────── */
+
+const argv = process.argv.slice(2);
+let darkSlug, outFile;
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--dark') darkSlug = argv[++i];
+  else if (a === '-o' || a === '--output') outFile = argv[++i];
+  else if (a === '-h' || a === '--help') { console.log(USAGE); process.exit(0); }
+  else positional.push(a);
+}
+const lightSlug = positional[0];
+if (!lightSlug || !darkSlug) die(USAGE);
+
+/* ── Resolve @williamzujkowski/oklch-terminal-themes ─────────────────
+ * Tried from the consumer's cwd first (a project that installs the
+ * themes package at its own top level), then from this script's own
+ * location (covers hoisting layouts where only remarque-tokens itself
+ * declares the peerDependency). First resolvable wins. */
+
+function tryResolveFrom(base) {
+  try {
+    const req = createRequire(base);
+    const indexPath = req.resolve(`${PKG_SPEC}/index.json`);
+    return { req, indexPath };
+  } catch {
+    return null;
+  }
+}
+
+const resolved =
+  tryResolveFrom(pathToFileURL(join(process.cwd(), 'package.json')).href) ||
+  tryResolveFrom(import.meta.url);
+
+if (!resolved) {
+  die(
+    `${PKG_SPEC} is not installed (checked from the current project and from remarque-tokens itself).\n\n` +
+    `Install it and retry:\n  npm install ${PKG_SPEC}@0.1.0\n`
+  );
+}
+
+const index = JSON.parse(readFileSync(resolved.indexPath, 'utf8'));
+const bySlug = new Map((index.themes || []).map((t) => [t.slug, t]));
+
+// Package root sits two directories above data/index.json; read its
+// package.json for the provenance header directly via fs (not through
+// "exports" — the package does not publish that subpath).
+const themesPkgRoot = dirname(dirname(resolved.indexPath));
+let themesVersion = 'unknown';
+try {
+  themesVersion = JSON.parse(readFileSync(join(themesPkgRoot, 'package.json'), 'utf8')).version;
+} catch { /* provenance is best-effort */ }
+
+/* ── Slug validation — the actual security boundary ──────────────────
+ * A slug is only ever used to build a require specifier AFTER it has
+ * been matched, byte-for-byte, against an entry in the package's own
+ * index. Nothing user-supplied reaches require.resolve()/fs otherwise. */
+
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function requireSlug(slug, label) {
+  if (typeof slug !== 'string' || !SLUG_RE.test(slug) || !bySlug.has(slug)) {
+    die(`${label} slug "${slug}" is not a known theme in ${PKG_SPEC} (see its index.json for valid slugs)`);
+  }
+  return bySlug.get(slug);
+}
+
+const lightMeta = requireSlug(lightSlug, 'light');
+const darkMeta = requireSlug(darkSlug, 'dark');
+if (lightMeta.isDark !== false) die(`light slug "${lightSlug}" has isDark=${lightMeta.isDark}, expected false`);
+if (darkMeta.isDark !== true) die(`dark slug "${darkSlug}" has isDark=${darkMeta.isDark}, expected true`);
+
+function loadTheme(slug) {
+  // Safe: slug has already been matched against the package's index above.
+  const path = resolved.req.resolve(`${PKG_SPEC}/themes/${slug}.json`);
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+const themeLight = loadTheme(lightSlug);
+const themeDark = loadTheme(darkSlug);
+
+/* ── Numeric validation ───────────────────────────────────────────── */
+
+const isNum = (x) => typeof x === 'number' && Number.isFinite(x);
+
+function validateOklch(o, where) {
+  if (!o || !isNum(o.l) || o.l < 0 || o.l > 1) die(`${where}: invalid or missing OKLCH l (${o && o.l})`);
+  if (!isNum(o.c) || o.c < 0) die(`${where}: invalid or missing OKLCH c (${o && o.c})`);
+  if (!isNum(o.h) || o.h < 0 || o.h >= 360) die(`${where}: invalid or missing OKLCH h (${o && o.h})`);
+  return [o.l, o.c, o.h];
+}
+
+function slotLch(theme, slot, label) {
+  const entry = theme.colors && theme.colors[slot];
+  if (!entry || !entry.oklch) die(`${label}: missing colors.${slot}.oklch`);
+  return validateOklch(entry.oklch, `${label} colors.${slot}`);
+}
+
+/* ── OKLCH → sRGB → WCAG luminance (same Ottosson matrices as audit.mjs) */
+
+function oklchToLinearSrgb(L, C, H) {
+  const h = (H * Math.PI) / 180;
+  const a = C * Math.cos(h), b = C * Math.sin(h);
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+  const l = l_ ** 3, m = m_ ** 3, s = s_ ** 3;
+  return [
+    +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
+  ];
+}
+const inGamut = (rgb) => rgb.every((x) => x >= -0.0005 && x <= 1.0005);
+const clip = (x) => Math.min(1, Math.max(0, x));
+const luminance = (rgb) => {
+  const [r, g, b] = rgb.map(clip);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+function ratio(c1, c2) {
+  const l1 = luminance(oklchToLinearSrgb(...c1));
+  const l2 = luminance(oklchToLinearSrgb(...c2));
+  const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+const r3 = (x) => +x.toFixed(3);
+const r1 = (x) => +x.toFixed(1);
+
+/* Largest chroma <= C that stays in sRGB gamut at (L, H).
+ * Round-then-verify (fixes the spike's bug, see #75): stepping in
+ * unrounded space and only rounding the final answer can round a
+ * borderline-in-gamut value back OUT of gamut (float rounding is not
+ * gamut-aware). So after the coarse search we round, then keep backing
+ * off in already-rounded steps until the ROUNDED value itself verifies. */
+function fitChroma(L, C, H) {
+  let c = Math.max(0, C);
+  while (c > 0 && !inGamut(oklchToLinearSrgb(L, c, H))) c -= 0.001;
+  c = Math.max(0, c);
+  let rounded = r3(c);
+  while (rounded > 0 && !inGamut(oklchToLinearSrgb(L, rounded, H))) rounded = r3(rounded - 0.001);
+  return Math.max(0, rounded);
+}
+
+/* Solve lightness so [L, C', H] hits >= target ratio against bg.
+ * dir 'darker': text on a light bg — find the MAX L that still passes
+ * (stays closest to the theme's own feel). dir 'lighter': text on a
+ * dark bg — find the MIN L. Chroma is clamped in-gamut INSIDE the
+ * solver at every candidate L, and the final [L, C, H] is rounded, then
+ * re-verified against the real (non-margin) target — nudging L further
+ * in the safe direction if rounding cost just enough ratio to fail. */
+function solveLOnce(C, H, bg, target, dir) {
+  const searchTarget = target * 1.03; // margin over the audit threshold
+  let lo = 0, hi = 1;
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    const c = fitChroma(mid, C, H);
+    const passes = ratio([mid, c, H], bg) >= searchTarget;
+    if (dir === 'darker') { if (passes) lo = mid; else hi = mid; }
+    else { if (passes) hi = mid; else lo = mid; }
+  }
+  let L = r3(dir === 'darker' ? lo : hi);
+  let c = fitChroma(L, C, H);
+  let guard = 0;
+  while (ratio([L, c, H], bg) < target && guard < 100) {
+    const next = dir === 'darker' ? r3(L - 0.001) : r3(L + 0.001);
+    if (next < 0 || next > 1 || next === L) break;
+    L = next;
+    c = fitChroma(L, C, H);
+    guard++;
+  }
+  const ok = ratio([L, c, H], bg) >= target;
+  return { L, C: c, H: r1(H), ok };
+}
+
+function solveL(C, H, bg, target, dir) {
+  let r = solveLOnce(C, H, bg, target, dir);
+  if (r.ok) return [r.L, r.C, r.H];
+  // Chroma-collapse fallback: retry as a neutral if the chromatic
+  // solve can't reach the target ratio at any lightness.
+  r = solveLOnce(0, H, bg, target, dir);
+  if (r.ok) return [r.L, r.C, r.H];
+  die(
+    `internal error: cannot solve lightness for a ${target}:1 target ` +
+    `(hue ${H.toFixed(1)}, direction ${dir}) even with chroma collapsed to 0 — pathological theme colors`
+  );
+}
+
+/* Accent hue: cursor if it's chromatic, else the most-chromatic classic ANSI. */
+function accentHue(theme, label) {
+  const cursor = theme.colors && theme.colors.cursor && theme.colors.cursor.oklch;
+  if (cursor) {
+    const [, c, h] = validateOklch(cursor, `${label} colors.cursor`);
+    if (c >= 0.05) return { h, c, from: 'cursor' };
+  }
+  const names = ['blue', 'purple', 'red', 'green', 'cyan', 'yellow'];
+  const cands = [];
+  for (const name of names) {
+    const o = theme.colors && theme.colors[name] && theme.colors[name].oklch;
+    if (!o) continue;
+    const [, c, h] = validateOklch(o, `${label} colors.${name}`);
+    cands.push({ name, c, h });
+  }
+  if (!cands.length) die(`${label}: no classic ANSI colors available to derive an accent hue`);
+  cands.sort((a, b) => b.c - a.c);
+  return { h: cands[0].h, c: cands[0].c, from: cands[0].name };
+}
+
+function fmt(triple) {
+  const [L, C, H] = triple;
+  if (!isNum(L) || !isNum(C) || !isNum(H)) die('internal error: attempted to emit a non-finite color component');
+  return `oklch(${L} ${C} ${H})`;
+}
+
+/* ── LIGHT derivation ─────────────────────────────────────────────── */
+
+function deriveLight(t) {
+  const [bgL0, bgC0, bgH0] = slotLch(t, 'background', 'light');
+  const bgH = r1(bgH0);
+  const bgL = r3(Math.max(bgL0, 0.93));
+  const bgC = fitChroma(bgL, Math.min(bgC0, 0.02), bgH);
+  const bg = [bgL, bgC, bgH];
+  const surface = [r3(bgL - 0.01), bgC, bgH];
+  const [, fgC0, fgH] = slotLch(t, 'foreground', 'light');
+  const fgC = Math.min(fgC0, 0.03);
+  const fg = solveL(fgC, fgH, surface, 10, 'darker');
+  const fgMuted = solveL(fgC, fgH, bg, 7.0, 'darker');
+  const muted = solveL(Math.min(fgC0, 0.02), fgH, surface, 4.5, 'darker');
+  const borderBold = solveL(0.01, bgH, bg, 3.0, 'darker');
+  const ac = accentHue(t, 'light');
+  const acC = Math.min(ac.c, 0.14);
+  const accent = solveL(acC, ac.h, bg, 4.5, 'darker');
+  const accentHover = [r3(accent[0] - 0.08), fitChroma(r3(accent[0] - 0.08), acC * 0.8, ac.h), r1(ac.h)];
+  const raw = {
+    'color-bg': bg,
+    'color-bg-subtle': [r3(bg[0] - 0.02), bg[1], bg[2]],
+    'color-fg': fg,
+    'color-fg-muted': fgMuted,
+    'color-muted': muted,
+    'color-border': [r3(bg[0] - 0.095), bg[1], bg[2]],
+    'color-border-bold': borderBold,
+    'color-surface': surface,
+    'color-accent': accent,
+    'color-accent-hover': accentHover,
+    'color-accent-subtle': [0.95, fitChroma(0.95, 0.02, ac.h), r1(ac.h)],
+    'color-selection-bg': [0.92, fitChroma(0.92, 0.04, ac.h), r1(ac.h)],
+    'color-selection-fg': { ref: 'color-fg' },
+    'color-code-bg': [r3(bg[0] - 0.03), bg[1], bg[2]],
+    'color-code-fg': { ref: 'color-fg' },
+  };
+  const tokens = {};
+  for (const [name, v] of Object.entries(raw)) tokens[name] = v.ref ? `var(--${v.ref})` : fmt(v);
+  return { accentFrom: ac.from, accentH: ac.h, raw, tokens };
+}
+
+/* ── DARK derivation ──────────────────────────────────────────────── */
+
+function deriveDark(t, accentHueLight) {
+  const [bgL0, bgC0, bgH0] = slotLch(t, 'background', 'dark');
+  const bgH = r1(bgH0);
+  const bgL = r3(Math.min(Math.max(bgL0, 0.14), 0.22));
+  const bgC = fitChroma(bgL, Math.min(bgC0, 0.03), bgH);
+  const bg = [bgL, bgC, bgH];
+  const surface = [r3(bg[0] + 0.03), bgC, bgH];
+  const [, fgC0, fgH] = slotLch(t, 'foreground', 'dark');
+  const fgC = Math.min(fgC0, 0.02);
+  const fg = solveL(fgC, fgH, surface, 10, 'lighter');
+  const fgMuted = solveL(fgC, fgH, bg, 7.0, 'lighter');
+  const muted = solveL(fgC, fgH, surface, 4.5, 'lighter');
+  const borderBold = solveL(0.01, bgH, bg, 3.0, 'lighter');
+  const ac = accentHue(t, 'dark');
+  const h = accentHueLight ?? ac.h; // keep hue consistent across the pair
+  const acC = Math.min(ac.c, 0.12);
+  const accent = solveL(acC, h, bg, 4.5, 'lighter');
+  const accentHover = [r3(accent[0] + 0.07), fitChroma(r3(accent[0] + 0.07), acC, h), r1(h)];
+  const selBg = [r3(bg[0] + 0.14), fitChroma(r3(bg[0] + 0.14), 0.06, h), r1(h)];
+  const selFg = solveL(0.005, fgH, selBg, 4.5, 'lighter');
+  const codeBg = [r3(bg[0] + 0.04), bgC, bgH];
+  const codeFg = solveL(0.005, fgH, codeBg, 7, 'lighter');
+  const raw = {
+    'color-bg': bg,
+    'color-bg-subtle': surface,
+    'color-fg': fg,
+    'color-fg-muted': fgMuted,
+    'color-muted': muted,
+    'color-border': [r3(bg[0] + 0.09), bg[1], bg[2]],
+    'color-border-bold': borderBold,
+    'color-surface': surface,
+    'color-accent': accent,
+    'color-accent-hover': accentHover,
+    'color-accent-subtle': [r3(bg[0] + 0.06), fitChroma(r3(bg[0] + 0.06), 0.04, h), r1(h)],
+    'color-selection-bg': selBg,
+    'color-selection-fg': selFg,
+    'color-code-bg': codeBg,
+    'color-code-fg': codeFg,
+  };
+  const tokens = {};
+  for (const [name, v] of Object.entries(raw)) tokens[name] = fmt(v);
+  tokens['weight-display'] = '500';
+  return { raw, tokens };
+}
+
+const light = deriveLight(themeLight);
+const dark = deriveDark(themeDark, light.accentH);
+
+/* ── Self-verify — the same pairings + gamut rule as scripts/audit.mjs,
+ * run in-process against the raw [L,C,H] triples (mirrored here rather
+ * than reparsing the CSS we're about to emit). This should be
+ * impossible to fail; a failure means a bug in the derivation above,
+ * not a bad input theme, so it errors as an internal error. */
+
+const CHECKS = [
+  ['color-fg', 'color-bg', 4.5, 'primary text'],
+  ['color-fg', 'color-surface', 4.5, 'primary text on surface'],
+  ['color-fg-muted', 'color-bg', 7.0, 'secondary text (spec AAA line)'],
+  ['color-muted', 'color-bg', 4.5, 'tertiary text'],
+  ['color-muted', 'color-surface', 4.5, 'tertiary text on surface'],
+  ['color-accent', 'color-bg', 4.5, 'links'],
+  ['color-accent-hover', 'color-bg', 4.5, 'link hover'],
+  ['color-code-fg', 'color-code-bg', 4.5, 'code text'],
+  ['color-border-bold', 'color-bg', 3.0, 'functional borders (WCAG 1.4.11)'],
+  ['color-selection-fg', 'color-selection-bg', 4.5, 'selected text'],
+];
+
+function resolveRaw(raw, name, seen = new Set()) {
+  if (seen.has(name)) die(`internal error: circular var() chain at --${name}`);
+  seen.add(name);
+  const v = raw[name];
+  if (v === undefined) die(`internal error: --${name} was never derived`);
+  return v.ref ? resolveRaw(raw, v.ref, seen) : v;
+}
+
+function selfVerify(themeName, raw) {
+  for (const [name, v] of Object.entries(raw)) {
+    const triple = v.ref ? resolveRaw(raw, name) : v;
+    if (!inGamut(oklchToLinearSrgb(...triple))) {
+      die(`internal error: derived --${name} (${themeName}) oklch(${triple.join(' ')}) is outside sRGB gamut`);
+    }
+  }
+  for (const [fgName, bgName, min, label] of CHECKS) {
+    const fg = resolveRaw(raw, fgName);
+    const bg = resolveRaw(raw, bgName);
+    const r = ratio(fg, bg);
+    if (r < min) {
+      die(`internal error: derived --${fgName}/--${bgName} (${themeName}) = ${r.toFixed(2)}:1 < ${min}:1 (${label}) — this should be impossible; the derivation has a bug`);
+    }
+  }
+}
+selfVerify('light', light.raw);
+selfVerify('dark', dark.raw);
+
+/* ── Emit ─────────────────────────────────────────────────────────── */
+
+const decls = (tokens, indent = '  ') => Object.entries(tokens).map(([k, v]) => `${indent}--${k}: ${v};`).join('\n');
+
+const css = `/*
+ * Generated by remarque-theme (remarque-tokens ${OWN_VERSION}) — DO NOT HAND-EDIT.
+ * Regenerate instead: npx remarque-theme ${lightSlug} --dark ${darkSlug}
+ *
+ * Source themes (${PKG_SPEC}@${themesVersion}):
+ *   light = "${lightSlug}"   dark = "${darkSlug}"
+ *   accent hue derived from: ${light.accentFrom} (H=${light.accentH.toFixed(1)})
+ *
+ * Palette tier only (--color-*, --weight-display) — see REMARQUE.md
+ * "Token Tiers" / "Color Providers". Self-verified against the same
+ * contrast + gamut checks as remarque-audit before being emitted.
+ */
+
+:root {
+${decls(light.tokens)}
+  --weight-display: 400;
+}
+
+[data-theme="dark"] {
+${decls(dark.tokens)}
+}
+`;
+
+if (outFile) {
+  writeFileSync(outFile, css);
+  console.error(`remarque-theme: wrote ${outFile}`);
+} else {
+  process.stdout.write(css);
+}

package/tokens.json

@@ -2,7 +2,7 @@
   "$description": "Remarque design tokens — GENERATED from tokens-core.css + tokens-palette.css by scripts/tokens-json.mjs. Do not edit; the CSS is the source of truth.",
   "$extensions": {
     "remarque": {
-      "version": "0.7.0",
+      "version": "0.9.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"