create-egregore 0.21.6 → 0.22.0

package/runtime/claude/.claude/skills/dark-mode/SKILL.md

@@ -1,410 +1,89 @@
 ---
 name: dark-mode
-description: "Use when authoring or modifying browser-rendered visual output: HTML, CSS, React SSR, artifact templates, markdown renderers, design tokens, themes, or composed pages. Do not invoke for an ordinary /view render—the checked-in renderer already owns its theme contract. The load-bearing rule is that theme-sensitive colors must be emitted as `var(--token)`, never resolved inline hex."
+description: "Use when authoring or modifying browser-rendered visual output: HTML, CSS, React SSR, artifact templates, markdown renderers, design tokens, themes, or composed pages. Do not invoke for an ordinary /view render—the checked-in renderer already owns its theme contract. The load-bearing rule is that theme-sensitive colors must be emitted as `var(--token)`, never resolved inline hex; the colors themselves come from the design system registry."
 ---
 
 # Dark Mode
 
 ## Voice Complex
 
-This skill governs BROWSER VISUAL RENDERING — warm palette, CSS token system, theme behavior. The warm-brown base (#1D1611) and terracotta accent (#D4875A) are the visual expression of the same warmth that runs through all Egregore registers.
+This skill governs browser visual rendering: theme tokens and theme behavior. It carries no palette; every color comes from the design system.
 Shared aesthetic: voice-bedrock (`.claude/rules/voice-bedrock.md`).
+For pair routing, component profiles, or adding a pair: `packages/design-system/skill/SKILL.md`.
 For terminal rendering: `tui-design` skill.
 For product copy in rendered pages: `product-voice` skill.
 For prose content in rendered pages: `egregore-voice` skill.
 
-This skill is a behavioral constraint system for Egregore visual output. It exists to stop the most common failure mode before it happens: an otherwise correct dark palette being defeated by SSR-emitted inline styles.
-
 ## When to invoke
 
-User says: "dark mode", "theme toggle", "color system", "card surface", "make this work in dark mode", or any request to generate or modify browser-rendered visual output (HTML, CSS, React SSR, Egregore artifacts, design tokens)
-Not this: TUI terminal output → `tui-design` · plain markdown files with no styled HTML
-
-## The Bitter Lesson
-
-**If React SSR renders `style="color:#2A2A2A"`, dark mode loses.** CSS variable overrides only work when the rendered value is itself a variable reference. If a color must adapt across themes, emit `var(--token)` at the render site. Not in comments. Not in a later stylesheet. In the actual rendered style.
-
-Treat this as a hard constraint:
-
-1. Every theme-sensitive color in CSS or inline `style` props must use `var(--token)`.
-2. Theme state lives on `<html data-theme="...">`.
-3. Theme restoration happens before paint, in `<head>`.
+User says: "dark mode", "theme toggle", "color system", "card surface", "make this work in dark mode", or any request to generate or modify browser-rendered visual output (HTML, CSS, React SSR, Egregore artifacts, design tokens).
 
-Everything else is secondary.
-
-## When To Invoke
-
-- Generating standalone HTML
-- Building or editing React SSR output
-- Writing CSS for Egregore artifacts
-- Modifying markdown renderers that emit inline styles
-- Adding a theme toggle
-- Extending the design system with dark surfaces
-- Producing any browser-rendered visual artifact
-
-## Not This
+Not this:
 
 - An ordinary deterministic `/view` render; the checked-in renderer already
   owns and tests its theme contract
-- TUI terminal output; use `/tui-design`
+- TUI terminal output; use `tui-design`
 - Plain markdown files that do not render styled HTML
 - Backend or CLI code with no visual surface
-- Non-rendered config changes unrelated to color or theme behavior
 
-## The Egregore Dark Palette
+## The rule
 
-The palette stays warm. The base dark background is `#1D1611`, not pure black. Accent colors stay the same in both modes because terracotta and muted blue already survive the transition cleanly.
+If a renderer emits `style="color:#15212e"`, theming loses: CSS can re-theme a value only when the rendered value is itself a variable reference. Every theme-sensitive color, in a stylesheet or an inline `style` prop, is `var(--token)` at the render site.
 
-### Core CSS Variables
+## Where colors come from
 
-| Token | Light | Dark | Role |
-|---|---|---|---|
-| `--cream` | `#F5F2ED` | `#1D1611` | Page background; inverted selection text in dark |
-| `--black` | `#16100B` | `rgba(255, 255, 255, 0.92)` | Primary text, titles, completed badges |
-| `--dark` | `#2A2A2A` | `rgba(255, 255, 255, 0.75)` | Body text, secondary copy, blocked badge fill |
-| `--border` | `#E0D8CC` | `rgba(255, 255, 255, 0.06)` | Rules, card borders, checkbox outlines |
-| `--muted` | `#8a8578` | `rgba(255, 255, 255, 0.50)` | Metadata, labels, de-emphasized text |
-| `--warm-gray` | `#d4cfc5` | `rgba(255, 255, 255, 0.30)` | Tertiary marks, dim text, faint structure |
-| `--terminal-bg` | `#1D1611` | `#161210` | Code blocks and terminal surfaces |
+- **Registry**: `packages/design-system/themes/registry.json` holds every palette pair and its theme tokens. The default pair is `registry.routing.defaultPair`, currently `sovereign` (`ledger` light, `bedrock` dark: cool stone with verdigris and steel accents). Use another registered pair only when the content matches that pair's `semantics.useWhen` and you can state the reason.
+- **CSS**: inline the committed, generated `packages/design-system/dist/egregore-design.css`. It defines each theme as a `[data-theme="<theme id>"]` block plus legacy aliases (`--bg`, `--text`, `--accent` and the rest). Never copy its values into a page and never edit it by hand; `npm run build` in `packages/design-system` regenerates it from the registry.
+- **Without the design package**: public and downstream instances do not carry `packages/design-system`. The same files ship vendored in `egregore-artifacts`, both in a checked-out `packages/egregore-artifacts` and in the installed package: `lib/vendor/design-system/themes/registry.json` and `lib/vendor/design-system/dist/egregore-design.css`.
+- **Tokens**: use the role tokens from `contract.roleTokens`: `--paper --paper-2 --card`, `--ink --ink-soft --ink-faint`, `--line --line-soft`, `--t1 --t2 --t3` with their `-bg` washes, the tone tokens `--ok --note --warn --critical --neutral` with their `-bg` washes, `--series-1` to `--series-5` with `--chart-grid --chart-axis` for charts, and `--grain --shadow`.
+- **Status colour**: read meaning from the tone tokens, never from `--t1`..`--t3` positions. The meaning is the same in every pair: `--ok` decided or done, `--note` aside or context, `--warn` owed or gated, `--critical` blocked or at risk, `--neutral` background or later.
+- **No local palette**: a page or a skill never defines its own theme colors. If the role tokens do not cover a color you need, that is a registry change; see the design system skill.
 
-### Dark-Only Surface Helpers
+## Highlights
 
-Use these when a component needs separation beyond the base variable set. The current artifacts shell uses `--card-bg` and `--code-bg`; `--elevated-bg` and `--strong-border` come from the same shipped token palette and are the right extensions when extra depth is needed.
+No side stripes: a coloured bar down one side of a box is retired in every render. Mark reading emphasis with a marker under the words (`.eg-mark`), a label in the margin (`.eg-margin` holding an `.eg-label`) or a quote with a hanging opening mark (`.eg-quote`). Mark status with a quiet panel (`.eg-panel`) whose `.eg-label` carries the tone's shape (● ok, ◆ note, ▲ warn, ■ critical, ○ neutral), so the state reads without colour and in both themes. A selected item gets weight plus a filled shape, never a stripe. The classes are `RECIPE_CSS` in `packages/egregore-artifacts/lib/recipe.js`, which the kit's shell injects into every render; the design system skill has the full rule.
 
-| Token | Light Fallback | Dark | Role |
-|---|---|---|---|
-| `--card-bg` | `#FFFFFF` | `#241E19` | Cards, pills, theme toggle background |
-| `--code-bg` | `rgba(59, 45, 33, 0.06)` | `rgba(212, 135, 90, 0.08)` | Inline code background |
-| `--elevated-bg` | `#FFFFFF` | `#2A231D` | Raised panels or overlays above cards |
-| `--strong-border` | `#d4cfc5` | `rgba(255, 255, 255, 0.10)` | Emphasized borders when `--border` is too faint |
+## The theme contract
 
-### Palette Rules
+The kit's renderers set three attributes on `<html>`:
 
-- Warm character first: dark surfaces are brown-black, not blue-black and not pure black.
-- Text opacity hierarchy is fixed: `0.92` primary, `0.75` secondary, `0.50` muted, `0.30` dim.
-- `--terracotta` stays `#D4875A` in both modes.
-- `--blue-muted` stays `#7B9DB7` in both modes.
-- Selection inverts: terracotta highlight remains, but dark mode switches the selected text to `#1D1611`.
+| Attribute | Value | Role |
+|---|---|---|
+| `data-theme` | resolved theme id, e.g. `ledger` or `bedrock` | the only CSS selector |
+| `data-theme-pair` | pair id, e.g. `sovereign` | names the family; never a CSS selector |
+| `data-theme-mode` | `auto`, `light` or `dark` | the reader's choice |
+
+- Persist only the mode. Resolve it through the pair: `auto` follows `prefers-color-scheme`, with the local clock as the fallback, and the result writes the pair's light or dark member into `data-theme`.
+- Resolve before paint, in a blocking `<head>` script.
+- Storage can throw in sandboxed and private pages: wrap every read and write in try/catch and keep the mode in memory.
+- Reference implementation: the theme script in `packages/egregore-artifacts/lib/shell.js` (a three-state toggle, `light → auto → dark`). Reuse its structure; do not write a second engine.
 
 ## Anti-Patterns
 
 | Pattern | Why It Breaks | Instead |
 |---|---|---|
-| `style={{ color: colors.black }}` | React resolves `colors.black` to a hex during SSR, so dark CSS cannot override it later | `style={{ color: 'var(--black)' }}` or a class that resolves to `var(--black)` |
-| `style={{ color: colors.muted }}` in markdown or components | Same SSR trap, just less obvious because muted copy often escapes review | Emit `style={{ color: 'var(--muted)' }}` |
-| `background: white` on cards | The card stays white in dark mode and blows out contrast | `background: var(--card-bg, white)` with a dark override on `[data-theme="dark"]` |
-| `border-bottom: 1px solid rgba(224, 216, 204, 0.5)` | You hardcoded a light border into a supposedly themeable component | `border-bottom: 1px solid var(--border)` or `var(--strong-border, var(--border))` |
-| `#000000` or `#111111` for dark backgrounds | Cold, dead black clashes with Egregore's warm substrate | Use `#1D1611` or `var(--cream)` once dark mode remaps it |
-| `opacity: 0.5` on already-colored text | Multiplies contrast unpredictably and usually makes dark text too faint | Use the precomputed text tokens: `var(--muted)` or `var(--warm-gray)` |
-| `@media (prefers-color-scheme: dark)` as the only mechanism | No manual override, no persistence, no explicit state | Use a three-state `light / auto / dark` system |
-| Separate `.dark-*` classes for every component | Duplicates the design system and drifts fast | Override variables once under `[data-theme="dark"]` and keep component styles shared |
-| Putting theme state on `body` or a wrapper div | Inconsistent scope; portals, overlays, and SSR shells can fall out of sync | Put `data-theme` on `<html>` |
-| Restoring the saved theme after the page renders | Causes a flash of the wrong theme | Apply the saved theme in a blocking `<head>` script before paint |
-| Converting CSS files to variables but leaving inline `colors.*` references behind | Mixed models create false confidence; one stray inline color is enough to break dark mode | Grep every render path for `colors.` and hardcoded hex in inline styles, then replace with `var(--token)` |
-
-## Signature Patterns
-
-1. Variable-first inline styles. Inline styles are allowed only when they emit CSS variables, never resolved palette values.
-2. `data-theme` on `<html>`. No `body.dark`, no component-local theme root.
-3. Three-state theme toggle. Support `light`, `auto`, and `dark`, with persistence.
-4. Auto resolves OS preference first, then local-clock fallback. If the system exposes no preference, dark runs from `19:00` to `07:00`.
-5. No-flash initialization. Restore theme state in `<head>` before anything visible paints.
-6. Card elevation through background lightness, not shadow stacks. In dark mode, depth comes from surface contrast.
-7. Accent colors stay stable. Terracotta and muted blue do not get separate dark variants unless there is a proven contrast failure.
-8. Selection highlight inversion. The highlight stays terracotta; selected text flips to the dark background color.
+| `style={{ color: palette.ink }}` with a JS constant | SSR resolves the constant to a fixed hex, so the theme cannot override it | `style={{ color: 'var(--ink)' }}` or a class |
+| `background: white` on cards | The card stays white in a dark theme | `background: var(--card)` |
+| `border: 1px solid rgba(0, 0, 0, 0.08)` | A light-only value inside a themeable component | `var(--line)` or `var(--line-soft)` |
+| `[data-theme="dark"]` overrides or `.dark-*` classes | Theme ids are names like `bedrock`, and role tokens already flip per resolved theme | Style with role tokens; add no per-mode overrides |
+| Selecting on `data-theme-pair` | The pair names the family; it is not a selector | Use role tokens, or `[data-theme="<theme id>"]` when one theme needs its own rule |
+| `opacity: 0.5` on colored text | Contrast changes unpredictably between themes | `var(--ink-soft)` or `var(--ink-faint)` |
+| `@media (prefers-color-scheme: dark)` as the only mechanism | No manual override and no persistence | The three-state mode above |
+| Theme state on `body` or a wrapper div | Portals, overlays and shells fall out of sync | The three attributes on `<html>` |
+| Restoring the saved mode after the page renders | A flash of the wrong theme | A blocking `<head>` script |
 
 ## Context Modes
 
-### Egregore Artifacts (React SSR)
-
-- Start from `packages/egregore-artifacts/lib/shell.js`, `markdown.js`, `components.js`, and `tokens.js`.
-- In render functions, replace `colors.black`, `colors.muted`, `colors.dark`, and similar inline values with `'var(--black)'`, `'var(--muted)'`, `'var(--dark)'`, and so on.
-- Keep structural values such as spacing, font families, and dimensions in JS as normal. The rule is specifically about theme-sensitive colors.
-- Put the dark variable remap in the shell, not on individual components.
-
-### Standalone HTML
-
-- Emit a full `:root` block plus a `[data-theme="dark"]` override block.
-- Put the theme restore script in `<head>` before visible markup.
-- Mount the toggle in fixed position and hide it in print.
-- Use CSS variable strings in any inline HTML styles you generate.
-
-### Tailwind CSS
-
-- Configure `darkMode: ['selector', '[data-theme=\"dark\"]']`.
-- Keep the root selector on `<html>`.
-- Prefer CSS custom properties for brand tokens, then map Tailwind utilities to those variables.
-- Do not sneak theme-sensitive hex colors into JSX `style` props just because the rest of the page uses Tailwind.
-
-### Vanilla CSS
-
-- Define light tokens in `:root`.
-- Override only variables under `[data-theme="dark"]`.
-- Component rules should read like `color: var(--black)` and `border-color: var(--border)`.
-
-### Email HTML
-
-- This is the one context where `@media (prefers-color-scheme: dark)` with `!important` is correct.
-- Do not build a JS toggle for email.
-- Accept that support is partial and optimize for legibility, not full parity.
-
-## Calibration Examples
-
-### 1. React Component Color Reference
-
-**Off target**
-
-```js
-h('span', { style: { color: colors.muted, fontSize: '13px' } }, `(${author})`)
-```
-
-**On point**
-
-```js
-h('span', { style: { color: 'var(--muted)', fontSize: '13px' } }, `(${author})`)
-```
-
-Why: the first version serializes to a fixed hex during SSR. The second survives theme remapping.
-
-### 2. Card Background And Elevation
-
-**Off target**
-
-```css
-.card {
-  background: white;
-  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.24);
-}
-```
-
-**On point**
-
-```css
-.card {
-  background: var(--card-bg, white);
-  border: 1px solid var(--border);
-}
-
-[data-theme="dark"] .card {
-  --card-bg: #241E19;
-}
-```
-
-Why: dark separation comes from a warmer surface step, not a generic shadow preset.
-
-### 3. Code Block In A Markdown Renderer
-
-**Off target**
-
-```js
-h('code', {
-  style: {
-    background: 'rgba(59, 45, 33, 0.06)',
-    color: colors.black,
-    padding: '2px 5px',
-  },
-}, text)
-```
-
-**On point**
-
-```js
-h('code', {
-  className: 'eg-code',
-}, text)
-```
-
-```css
-.eg-code {
-  background: var(--code-bg, rgba(59, 45, 33, 0.06));
-  color: var(--black);
-}
-
-[data-theme="dark"] .eg-code {
-  --code-bg: rgba(212, 135, 90, 0.08);
-  color: var(--terracotta);
-}
-```
-
-Why: inline code needs a dedicated surface token in dark mode; a light-only rgba wash will disappear.
-
-## Toggle Reference Implementation
-
-This is the canonical Egregore pattern: one HTML attribute, one variable override block, one small engine. Keep the structure; adapt only if the host environment forces it.
-
-### JS Engine
-
-```html
-<script>
-  (function() {
-    var MODES = ['light', 'auto', 'dark'];
-    var ICONS = ['\u2600', '\u25D0', '\u263D'];
-    var LABELS = ['light', 'auto', 'dark'];
-
-    function resolveAuto() {
-      if (window.matchMedia('(prefers-color-scheme: dark)').matches) return 'dark';
-      if (window.matchMedia('(prefers-color-scheme: light)').matches) return 'light';
-      var h = new Date().getHours();
-      return (h >= 19 || h < 7) ? 'dark' : 'light';
-    }
-
-    function applyTheme(mode) {
-      var resolved = mode === 'auto' ? resolveAuto() : mode;
-      document.documentElement.setAttribute('data-theme', resolved);
-    }
-
-    function updateToggle(mode) {
-      var idx = MODES.indexOf(mode);
-      var btn = document.querySelector('.eg-theme-toggle');
-      if (!btn) return;
-      btn.querySelector('.eg-t-icon').textContent = ICONS[idx];
-      btn.querySelector('.eg-t-label').textContent = LABELS[idx];
-    }
-
-    var saved = localStorage.getItem('eg-theme-mode') || 'auto';
-    applyTheme(saved);
-
-    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function() {
-      if ((localStorage.getItem('eg-theme-mode') || 'auto') === 'auto') applyTheme('auto');
-    });
-
-    window.__egTheme = {
-      cycle: function() {
-        var cur = localStorage.getItem('eg-theme-mode') || 'auto';
-        var next = MODES[(MODES.indexOf(cur) + 1) % 3];
-        localStorage.setItem('eg-theme-mode', next);
-        applyTheme(next);
-        updateToggle(next);
-      },
-      init: function() { updateToggle(saved); }
-    };
-  })();
-</script>
-```
-
-### CSS Shell
-
-```css
-:root {
-  --cream: #F5F2ED;
-  --black: #16100B;
-  --dark: #2A2A2A;
-  --border: #E0D8CC;
-  --muted: #8a8578;
-  --warm-gray: #d4cfc5;
-  --terminal-bg: #1D1611;
-  --terracotta: #D4875A;
-  --blue-muted: #7B9DB7;
-}
-
-[data-theme="dark"] {
-  --cream: #1D1611;
-  --black: rgba(255, 255, 255, 0.92);
-  --dark: rgba(255, 255, 255, 0.75);
-  --border: rgba(255, 255, 255, 0.06);
-  --muted: rgba(255, 255, 255, 0.50);
-  --warm-gray: rgba(255, 255, 255, 0.30);
-  --terminal-bg: #161210;
-}
-
-::selection { background: var(--terracotta); color: var(--cream); }
-[data-theme="dark"] ::selection { color: #1D1611; }
-
-.eg-theme-toggle {
-  position: fixed;
-  top: 1.25rem;
-  right: 1.25rem;
-  width: 36px;
-  height: 36px;
-  border-radius: 50px;
-  border: 1px solid var(--border);
-  background: var(--card-bg, white);
-  cursor: pointer;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: 15px;
-  line-height: 1;
-  transition: background 0.2s, border-color 0.2s, width 0.2s;
-  z-index: 100;
-  padding: 0;
-  gap: 6px;
-  overflow: hidden;
-}
-.eg-theme-toggle:hover {
-  border-color: var(--terracotta);
-  width: 92px;
-  padding: 0 12px;
-}
-[data-theme="dark"] .eg-theme-toggle { --card-bg: #241E19; }
-.eg-theme-toggle .eg-t-icon { flex-shrink: 0; }
-.eg-theme-toggle .eg-t-label {
-  font-family: var(--font-mono);
-  font-size: 10px;
-  letter-spacing: 0.04em;
-  color: var(--muted);
-  white-space: nowrap;
-  width: 0;
-  overflow: hidden;
-  transition: width 0.2s, opacity 0.2s;
-  opacity: 0;
-}
-.eg-theme-toggle:hover .eg-t-label { width: 32px; opacity: 1; }
-
-@media print {
-  body { background: white; }
-  .eg-artifact { padding: 1rem; max-width: none; }
-  .eg-card { break-inside: avoid; }
-  .eg-theme-toggle { display: none; }
-}
-
-@media (max-width: 640px) {
-  .eg-artifact { padding: 2rem 1.25rem 3rem; }
-  .eg-title { font-size: 28px; }
-  .eg-section-title { font-size: 20px; }
-  .eg-meta-row { gap: 10px; }
-  .eg-theme-toggle { top: 0.75rem; right: 0.75rem; width: 32px; height: 32px; font-size: 14px; }
-}
-```
-
-### HTML Hookup
-
-```html
-<html lang="en" data-theme="light">
-  <head>
-    <!-- theme restore script goes here -->
-  </head>
-  <body>
-    <button class="eg-theme-toggle" aria-label="Toggle theme" onclick="__egTheme.cycle()">
-      <span class="eg-t-icon">&#9680;</span>
-      <span class="eg-t-label">auto</span>
-    </button>
-    <script>__egTheme.init();</script>
-  </body>
-</html>
-```
+- **Egregore artifacts** (`packages/egregore-artifacts`): the shell inlines the design CSS, bridges legacy chrome names onto role tokens, and runs the theme script. Component code uses role tokens only.
+- **Python pages** (`api/`): `api/design_system.py` (`design_head`, `html_attrs`, `bridge_css`) reads the same dist CSS and registry as static files.
+- **Standalone HTML**: inline the dist CSS, set the three attributes on `<html>`, and add the `<head>` theme script.
+- **Tailwind**: map utilities to role-token variables (for example `ink: 'var(--ink)'`); do not use the `dark:` variant for theme colors.
+- **Email HTML**: the one context where `@media (prefers-color-scheme: dark)` with `!important` is correct. Build no JS toggle, and optimize for legibility over parity.
 
 ## Pre-Ship Checklist
 
-1. Grep for hardcoded hex colors and `colors.` references in render paths that emit inline styles.
-2. Verify every theme-sensitive inline color is a `var(--token)` string.
-3. Verify both `:root` and `[data-theme="dark"]` blocks exist.
-4. Verify `data-theme` is set on `<html>`, not `body`.
-5. Verify the saved theme is restored in `<head>` before visible markup paints.
-6. Verify the toggle cycles `light -> auto -> dark` and persists to `localStorage`.
-7. Verify auto mode follows OS preference first and local time second.
-8. Verify no surface uses pure black or a cool gray dark background.
-9. Verify cards, code, and elevated surfaces separate by warm lightness steps rather than shadow spam.
-10. Verify selection, print, and mobile behavior still work after the theme system is added.
-
-## Reference Files
-
-Read these conditionally, depending on the task:
-
-- `packages/egregore-artifacts/lib/shell.js` for the canonical shell structure, variable overrides, and toggle wiring.
-- `packages/egregore-artifacts/lib/tokens.js` for the shipped light and dark token values.
-- `packages/egregore-artifacts/lib/markdown.js` for the inline-style `var(--token)` conversion pattern.
-- `packages/egregore-artifacts/lib/components.js` for component-level inline style usage that must stay variable-first.
-- `packages/design-system/tokens.css` for the broader design-system token vocabulary.
-
-If the current checkout does not yet contain the merged dark-mode implementation in those artifact files, inspect the shipped worktree copies under `.claude/worktrees/soul-document-design/packages/egregore-artifacts/lib/`.
+1. No hex or resolved color constant in any render path that emits inline styles.
+2. Every `var(--x)` the page uses is defined for both members of its pair (for `sovereign`: `ledger` and `bedrock`).
+3. `<html>` carries all three attributes, and the mode is restored in `<head>` before paint.
+4. The toggle cycles `light → auto → dark`; the choice survives a reload where storage works, and nothing throws where it does not.
+5. Print and phone-width layouts still work.

package/runtime/claude/.claude/skills/records/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: records
+description: View or change your session records, hold the current session, redact a past record, record past sessions from this machine, and close or file the open items records carry.
+---
+
+# /records — your session records
+
+Session records put asked, decided, left open, touched and cost in shared
+memory. Organization policy sets the default; each person controls their own
+records. The full trail stays on this machine as a file under
+`~/.egregore/trails/<folder>/<session>.md`. Your own Claude
+account reads it once to write an outline. The model
+call can be disabled. See [Session records](../../../docs/session-records.md)
+for the exact content checks and their limits.
+
+Claude Code, Codex CLI, Pi and Prime share the same record and hold controls.
+Pi and Prime record at session end; an idle sweep also covers Codex and
+continued sessions. `/records sweep` requests that sweep after the first
+offer has been answered. Codex reports tokens and price coverage; Pi and
+Prime use their usage ledger. Working-directory checks exclude other projects.
+
+## When to invoke
+
+Use for `/records`, session record settings, the greeting's past-session
+offer, "off the record", a request to hold or redact a session record, or
+the open items the records carry: listing them, closing one, or filing one as
+an issue.
+
+## Commands
+
+Use `bin/records.sh`; do not edit personal state directly.
+
+| Intent | Command |
+|---|---|
+| Show settings and unrecorded count | `bash bin/records.sh status` |
+| Read recent decisions and open items | `bash bin/records.sh digest` |
+| Read the organization's vitals, the last seven days beside the seven before | `bash bin/records.sh vitals` (`--json` for measurements and findings; `--findings` for actions and verification) |
+| Record a concrete outcome and its contributing sessions | `bash bin/records.sh outcome record --file <manifest.json>` |
+| Inspect accepted-outcome costs and coverage | `bash bin/records.sh outcome report --json` |
+| Register or update a measured correction | `bash bin/records.sh intervention record --file <manifest.json>` |
+| Inspect the five/ten-outcome checkpoints | `bash bin/records.sh intervention report --json` |
+| Retry a waiting records push | `bash bin/records.sh status --push` |
+| Turn your records on or off | `bash bin/records.sh on` or `off` |
+| Choose the detail | `bash bin/records.sh detail outline` or `detail full` |
+| Hold this session | `bash bin/records.sh hold` |
+| Hold a past session of yours | `bash bin/records.sh redact <id-or-prefix>` |
+| Review past sessions before recording | `bash bin/records.sh backfill --dry-run` |
+| Record the listed past sessions | `bash bin/records.sh backfill --yes` |
+| Sweep idle sessions and refresh continued ones | `bash bin/records.sh sweep` |
+| Limit the past-session window | `bash bin/records.sh backfill --days 30 --dry-run` |
+| Read one local trail | `bash bin/records.sh show <id-or-prefix>` |
+| Mark the greeting offer answered | `bash bin/records.sh noticed` |
+| List active open items | `bash bin/records.sh open` |
+| Review retained stale items | `bash bin/records.sh open --stale` |
+| Renew the relevance of a verified existing outcome | `bash bin/records.sh reactivate <item-id>` |
+| Remove an item from current relevance | `bash bin/records.sh stale <item-id>` |
+| Mark an open item done | `bash bin/records.sh close <item-id>` |
+| Prepare an issue draft for an open item | `bash bin/records.sh file <item-id>` |
+| File that draft after the person confirms it | `bash bin/records.sh file <item-id> --confirm <request-id>` |
+
+For "off the record", run `hold` immediately and confirm the returned result
+in one line. The durable hold applies across checkpoints, resumes and
+backfill. An existing record becomes a stub by default; a person who has
+turned off hold stubs gets a removal. Revisions already pushed remain in
+memory repository history. Purging history is a separate future command.
+Do not imply that hold removes earlier published revisions.
+
+When the greeting offer is answered: yes runs `backfill --yes`; no keeps
+past sessions unpublished, and only sessions from now on are recorded; an
+explicit request to turn recording off runs `off`. Then run `noticed`. Only a
+later `backfill --yes` publishes the earlier sessions. For "show one", first
+run `backfill --dry-run`, choose one listed session, and use `show` to
+display its local trail. Return
+to the offer after the preview. Do not record the batch until the person says
+yes. A direct request to backfill is already that instruction.
+
+`full` includes prompt excerpts and selected assistant text. Explain that
+before changing from outline when the person's intent is unclear. Outline
+asks are paraphrased with mechanical checks, while deterministic sections
+retain paths, command names, commit subjects and counts. The checks do not
+guarantee removal of every sensitive detail or outside name. Hold or redact
+is the person's remedy when something should stay out of shared memory.
+
+If `hold` cannot identify the invoking session, report its one-line result.
+Never guess a session id from a shared file or apply another person's id.
+A past-session redaction is restricted to this person's records.
+
+## Digest
+
+`/records digest` shows what the day's sessions decided and left open,
+including yesterday and today across all authors, and under Carried the open
+items still carried from earlier days. Each open item starts with its id. Use
+`--days N` or `--since YYYY-MM-DD` for a longer window. The digest reads
+records only and writes nothing. To keep a decision or finding in
+organizational knowledge, hand the line to `/reflect`.
+
+## Open items
+
+An open item has two independent properties: **resolution** (open until an
+explicit close or filing) and **relevance** (active or stale). Its id remains
+the first six hex digits of the normalized line's SHA-256, without attribution.
+Its original age never resets. Similar wording is not proof of the same task.
+
+After fourteen days without an explicit reactivation, an unresolved item is
+**open but stale**. This is a read-time projection; no timer rewrites records or
+appends expiry noise. Repeating the line does not renew relevance, and a
+mention cannot reopen a closed or filed item. Existing expired ledger events
+remain terminal for backward compatibility; no new expiry events are created.
+
+`/records open` shows active work; `open --stale` shows the retained stale
+backlog; `open --all --json` exposes both with their original and relevance
+ages. The greeting shows the active count and a bounded stale count/link,
+without expanding stale text into the working context or demanding an owner.
+
+`/records stale <id>` removes an item from current relevance immediately.
+`/records reactivate <id>` appends an explicit relevance renewal, retaining its
+original age and record. Reactivate only after checking that the same concrete
+outcome is still needed. If the goal or scope changed, close the old item with
+a successor reference in the next record and start a new concrete item. Never
+attach new work to a stale item merely because its broad topic sounds similar.
+Filed items continue in their linked issue, preventing duplicate carry work.
+
+`close`, `stale`, `reactivate` and successful `file` append events to
+`memory/sessions/open-items.jsonl`. Events contain the item id, state, Runtime
+actor id, timestamp and optional issue URL, never item text. The latest valid
+event by time wins; the union merge rule preserves concurrent histories.
+
+`file` without `--confirm` prepares a draft through the issue flow and files
+nothing. Show the person the draft it prints. Only after they confirm that
+exact draft, run `file <item-id> --confirm <request-id>` with the printed
+request id. The event is written only when the filing succeeds, with the
+issue link. Filing needs the configured GitHub issue tracker
+(`issues.backend: github` in `egregore.json`); without one, `file` says so
+and writes nothing.
+
+## Outcomes and measured corrections
+
+Use the [outcome economics workflow](../../../docs/plans/outcome-economics-workflow.md)
+when implementing findings from the scorecard. The agent prepares manifests and
+records the work; no additional roles or approval queues are needed. Register a
+concrete outcome as open, link native aggregate session scopes, and append its
+verified disposition when the agreed acceptance condition is met. Do not infer
+acceptance from a merge, topic similarity or an open item. Do not invent a human
+verification. Keep attribution incomplete until driver, worker, retry and review
+costs are accounted for.
+
+The explicit scorecard joins canonical final costs. Missing prices or records,
+held work and overlapping parent/worker scopes cannot become measured zero or
+complete unit cost. Repeated finding tags rank associated spend, not recoverable
+waste. Register an intervention's baseline before post-change work; inspect five
+comparable terminal outcomes, decide at ten, and revisit quality regressions
+immediately. These checkpoints never require delaying an already justified fix.
+
+## Telemetry
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"records"}' 2>/dev/null &
+```