the-grimoire-cli 0.3.2 → 0.5.0

package/.agents/rules/10-working-process.md

@@ -1,31 +1,31 @@
----
-updated: 2026-05-31
-description: 'How to work a task end to end: plan, task contract, right altitude, small increments, tools, TDD.'
----
-
-# 10 — Working process
-
-- **Plan before code.** For anything beyond a trivial edit, state the plan (files, approach,
-  test strategy) before touching code. For large/ambiguous work, get a thumbs-up first.
-- **Goal-driven.** Turn the task into a verifiable goal before starting: "fix the bug" → "write a
-  test that reproduces it, then make it pass". Strong success criteria let you loop to done without
-  re-asking; weak ones ("make it work") force constant clarification.
-- **Task contract.** Before non-trivial code, state the contract: the verifiable **goal**, explicit
-  **acceptance criteria**, and what is **out of scope**. The verifier checks output against it — "done"
-  means the criteria are met and nothing out-of-scope crept in.
-- **Right altitude.** Match effort and abstraction to the ask. Do the full *right* thing for the
-  actual request — neither gold-plate (speculative abstraction; YAGNI, `rules/05`) nor scope-cut to
-  save effort (`rules/00`). When the right altitude is unclear, state your read and proceed.
-- **Ask before large work.** Multi-session, schema-changing, or architecture-shifting work →
-  route to **BACKLOG** (`40-handoff.md`) and confirm scope before starting.
-- **Small increments.** Land coherent, reviewable slices. Vertical (tracer-bullet) over horizontal.
-- **Use the tools.** When a skill or command fits the task, use it instead of improvising.
-- **Adapt external guidance.** When applying an article, talk, or vendor doc, extract the principle and fit it to this stack and domain. Vendor names and examples in the source are illustrations, not mandates — keep the core tool-agnostic.
-- **Update NOW.** Keep `journal/session/current.md` reflecting the live state (focus / last-done /
-  next-step / blockers). Rewrite in place; do not append.
-- **Session hygiene.** Batch related asks into one well-planned request — every prompt reloads the
-  always-on context, so one-shotting beats drip-feeding. Finish a task, then compact or clear:
-  continuity lives in the three homes (`standards/knowledge-management.md`), not in chat history.
-  For work-in-progress, capture state via `journal/session/current.md` or the `handoff` skill before clearing.
-- **TDD per stack policy.** Follow the active profile's testing policy
-  (`tdd-mandatory` | `test-ready-deferred` | `none`) — see `stack/`.
+---
+updated: 2026-05-31
+description: 'How to work a task end to end: plan, task contract, right altitude, small increments, tools, TDD.'
+---
+
+# 10 — Working process
+
+- **Plan before code.** For anything beyond a trivial edit, state the plan (files, approach,
+  test strategy) before touching code. For large/ambiguous work, get a thumbs-up first.
+- **Goal-driven.** Turn the task into a verifiable goal before starting: "fix the bug" → "write a
+  test that reproduces it, then make it pass". Strong success criteria let you loop to done without
+  re-asking; weak ones ("make it work") force constant clarification.
+- **Task contract.** Before non-trivial code, state the contract: the verifiable **goal**, explicit
+  **acceptance criteria**, and what is **out of scope**. The verifier checks output against it — "done"
+  means the criteria are met and nothing out-of-scope crept in.
+- **Right altitude.** Match effort and abstraction to the ask. Do the full *right* thing for the
+  actual request — neither gold-plate (speculative abstraction; YAGNI, `rules/05`) nor scope-cut to
+  save effort (`rules/00`). When the right altitude is unclear, state your read and proceed.
+- **Ask before large work.** Multi-session, schema-changing, or architecture-shifting work →
+  route to **BACKLOG** (`40-handoff.md`) and confirm scope before starting.
+- **Small increments.** Land coherent, reviewable slices. Vertical (tracer-bullet) over horizontal.
+- **Use the tools.** When a skill or command fits the task, use it instead of improvising.
+- **Adapt external guidance.** When applying an article, talk, or vendor doc, extract the principle and fit it to this stack and domain. Vendor names and examples in the source are illustrations, not mandates — keep the core tool-agnostic.
+- **Update NOW.** Keep `journal/session/current.md` reflecting the live state (focus / last-done /
+  next-step / blockers). Rewrite in place; do not append.
+- **Session hygiene.** Batch related asks into one well-planned request — every prompt reloads the
+  always-on context, so one-shotting beats drip-feeding. Finish a task, then compact or clear:
+  continuity lives in the three homes (`standards/knowledge-management.md`), not in chat history.
+  For work-in-progress, capture state via `journal/session/current.md` or the `handoff` skill before clearing.
+- **TDD per stack policy.** Follow the active profile's testing policy
+  (`tdd-mandatory` | `test-ready-deferred` | `none`) — see `stack/`.

package/.agents/rules/15-skills.md

@@ -1,27 +1,27 @@
----
-updated: 2026-05-31
-description: Consult skills/catalog.md and use the right skill/plugin/MCP before improvising.
----
-
-# 15 — Use the right tool (skills / plugins / MCP)
-
-Before improvising any non-trivial task, **consult `skills/catalog.md`** and invoke the primary
-capability for the trigger. If the catalog does not cover it, run **`find-skills`** before
-hand-rolling a solution. For multi-step work, run the matching **workflow chain** end to end — do
-not stop early.
-
-Precedence: this rule defers to `local/`. A project may swap a primary (e.g. pin
-`superpowers:test-driven-development` instead of `tdd`) or disable a tool in `local/AGENTS.local.md`.
-
-## Workflow chains
-
-- **Feature:** `brainstorming → writing-plans → [using-git-worktrees] → tdd → verifier → ecc:code-review → ecc:pr`
-- **Bugfix:** `diagnose → tdd (reproduce) → verifier → ecc:pr`
-- **UI:** `stitch (mockup) → ui-ux-pro-max → react-test → ecc:frontend-a11y → playwright (visual) → verifier`
-- **Architecture:** `improve-codebase-architecture → grill-with-docs → writing-plans → …`
-- **Research-first:** `ecc:deep-research → brainstorming → …`
-
-The required tools for this project are declared in `tooling.json`; run `grimoire bootstrap` to
-install/enable them. The mattpocock engineering skills (`tdd`, `diagnose`, `to-prd`, `to-issues`,
-`triage`, `improve-codebase-architecture`, `zoom-out`) require running `/setup-matt-pocock-skills`
-once per repo first.
+---
+updated: 2026-05-31
+description: Consult skills/catalog.md and use the right skill/plugin/MCP before improvising.
+---
+
+# 15 — Use the right tool (skills / plugins / MCP)
+
+Before improvising any non-trivial task, **consult `skills/catalog.md`** and invoke the primary
+capability for the trigger. If the catalog does not cover it, run **`find-skills`** before
+hand-rolling a solution. For multi-step work, run the matching **workflow chain** end to end — do
+not stop early.
+
+Precedence: this rule defers to `local/`. A project may swap a primary (e.g. pin
+`superpowers:test-driven-development` instead of `tdd`) or disable a tool in `local/AGENTS.local.md`.
+
+## Workflow chains
+
+- **Feature:** `brainstorming → writing-plans → [using-git-worktrees] → tdd → verifier → ecc:code-review → ecc:pr`
+- **Bugfix:** `diagnose → tdd (reproduce) → verifier → ecc:pr`
+- **UI:** `stitch (mockup) → ui-ux-pro-max → react-test → ecc:frontend-a11y → playwright (visual) → verifier`
+- **Architecture:** `improve-codebase-architecture → grill-with-docs → writing-plans → …`
+- **Research-first:** `ecc:deep-research → brainstorming → …`
+
+The required tools for this project are declared in `tooling.json`; run `grimoire bootstrap` to
+install/enable them. The mattpocock engineering skills (`tdd`, `diagnose`, `to-prd`, `to-issues`,
+`triage`, `improve-codebase-architecture`, `zoom-out`) require running `/setup-matt-pocock-skills`
+once per repo first.

package/.agents/rules/20-modes.md

@@ -1,41 +1,41 @@
----
-updated: 2026-05-31
-description: 'NORMAL vs HOTFIX: how a user phrase sets the working mode and what each mode requires.'
----
-
-# 20 — Modes: NORMAL vs HOTFIX
-
-A mode is set by a user phrase and **persists for the whole session**. Record it at the top of
-`journal/session/current.md`.
-
-## NORMAL (default)
-
-Full discipline:
-- Plan before code; TDD per the active stack testing-policy.
-- Full `verify` script (`stack/`): typecheck + lint + test + coverage + format:check.
-- Docs and `journal/memory/` updated **same turn** as the change.
-- Commits go through hooks (husky + lint-staged). No `--no-verify`.
-- The verifier must `pass` before "done".
-
-## HOTFIX (on-site fire)
-
-Triggered by phrases like "hotfix", "production down", "on-site fire" (localize the trigger words
-per project in `local/`). Once declared, HOTFIX **persists the whole session** — don't silently
-revert on the next message. Minimize blast radius:
-- **Smallest diff** — one file if possible.
-- **TDD waived** — backfill tests in the cleanup item.
-- **Gate the new path behind an env flag** — single-unset rollback. Document the flag and how to
-  unset it **in the commit body**, so an operator who only has `git log` can roll back.
-- `--no-verify` **allowed** for the emergency commit only.
-- **Never `npm ci`** (or any clean-install that wipes deps) on-site — a cancelled run leaves a
-  half-installed tree and a dead app. If deps are unchanged, build only; otherwise `npm install`
-  (resumable).
-- **Log a `journal/backlog/` item** (`priority: hotfix`) with: a `Hypothesis:` line (keep the disproven ones
-  too), the env flag + rollback, and a cleanup checklist (tests to backfill, flag to remove, ADR if
-  implied). An empty cleanup section means the HOTFIX is undocumented.
-
-**Environmental fire ≠ code fire.** If the on-site cause is hardware / OS / network / AV (RAM,
-keyring, co-tenant load), it is **not** a HOTFIX. Route per `40-handoff.md` — record in `journal/memory/` as
-a `type: field-report`, do not patch code.
-
-Leaving HOTFIX → the cleanup item must be closed under NORMAL discipline.
+---
+updated: 2026-05-31
+description: 'NORMAL vs HOTFIX: how a user phrase sets the working mode and what each mode requires.'
+---
+
+# 20 — Modes: NORMAL vs HOTFIX
+
+A mode is set by a user phrase and **persists for the whole session**. Record it at the top of
+`journal/session/current.md`.
+
+## NORMAL (default)
+
+Full discipline:
+- Plan before code; TDD per the active stack testing-policy.
+- Full `verify` script (`stack/`): typecheck + lint + test + coverage + format:check.
+- Docs and `journal/memory/` updated **same turn** as the change.
+- Commits go through hooks (husky + lint-staged). No `--no-verify`.
+- The verifier must `pass` before "done".
+
+## HOTFIX (on-site fire)
+
+Triggered by phrases like "hotfix", "production down", "on-site fire" (localize the trigger words
+per project in `local/`). Once declared, HOTFIX **persists the whole session** — don't silently
+revert on the next message. Minimize blast radius:
+- **Smallest diff** — one file if possible.
+- **TDD waived** — backfill tests in the cleanup item.
+- **Gate the new path behind an env flag** — single-unset rollback. Document the flag and how to
+  unset it **in the commit body**, so an operator who only has `git log` can roll back.
+- `--no-verify` **allowed** for the emergency commit only.
+- **Never `npm ci`** (or any clean-install that wipes deps) on-site — a cancelled run leaves a
+  half-installed tree and a dead app. If deps are unchanged, build only; otherwise `npm install`
+  (resumable).
+- **Log a `journal/backlog/` item** (`priority: hotfix`) with: a `Hypothesis:` line (keep the disproven ones
+  too), the env flag + rollback, and a cleanup checklist (tests to backfill, flag to remove, ADR if
+  implied). An empty cleanup section means the HOTFIX is undocumented.
+
+**Environmental fire ≠ code fire.** If the on-site cause is hardware / OS / network / AV (RAM,
+keyring, co-tenant load), it is **not** a HOTFIX. Route per `40-handoff.md` — record in `journal/memory/` as
+a `type: field-report`, do not patch code.
+
+Leaving HOTFIX → the cleanup item must be closed under NORMAL discipline.

package/.agents/rules/25-surgical-changes.md

@@ -1,29 +1,29 @@
----
-updated: 2026-05-31
-description: Touch only what the request needs; do not refactor or "improve" adjacent code.
----
-
-# 25 — Surgical changes
-
-Touch only what you must. Clean up only your own mess.
-
-## When editing existing code
-
-- **Change only what the request needs.** Every changed line must trace directly to the task. If you
-  cannot explain why a line changed in terms of the request, revert it.
-- **Do not "improve" adjacent code, comments, or formatting.** Not yours to touch this turn.
-- **Do not refactor what is not broken.** Unrelated refactoring is a separate, named task.
-- **Match the existing style** even if you would do it differently. Mirror the surrounding idiom,
-  casing, and comment density.
-- **Notice ≠ delete.** If you spot unrelated dead code, **mention it** — do not remove it unless asked.
-
-## Orphans
-
-- Remove imports / variables / functions that **your** change made unused.
-- Do **not** remove pre-existing dead code unless the task asks for it.
-
-## The test
-
-> Could a reviewer read the diff and see nothing in it that the request did not call for?
-
-If not, trim the diff until they can.
+---
+updated: 2026-05-31
+description: Touch only what the request needs; do not refactor or "improve" adjacent code.
+---
+
+# 25 — Surgical changes
+
+Touch only what you must. Clean up only your own mess.
+
+## When editing existing code
+
+- **Change only what the request needs.** Every changed line must trace directly to the task. If you
+  cannot explain why a line changed in terms of the request, revert it.
+- **Do not "improve" adjacent code, comments, or formatting.** Not yours to touch this turn.
+- **Do not refactor what is not broken.** Unrelated refactoring is a separate, named task.
+- **Match the existing style** even if you would do it differently. Mirror the surrounding idiom,
+  casing, and comment density.
+- **Notice ≠ delete.** If you spot unrelated dead code, **mention it** — do not remove it unless asked.
+
+## Orphans
+
+- Remove imports / variables / functions that **your** change made unused.
+- Do **not** remove pre-existing dead code unless the task asks for it.
+
+## The test
+
+> Could a reviewer read the diff and see nothing in it that the request did not call for?
+
+If not, trim the diff until they can.

package/.agents/rules/30-verification.md

@@ -1,36 +1,36 @@
----
-updated: 2026-05-31
-description: 'The independent verifier: the author cannot mark their own work done; verify on fresh context.'
----
-
-# 30 — Verification (independent verifier)
-
-**Principle: the agent that writes code cannot mark it done.** Bias comes from *shared context*,
-not from the model. Cut the context → cut the bias. One Claude Code subscription is enough via a
-**subagent with fresh context** — the **verifier**.
-
-## Flow (one session)
-
-1. Implementer (main thread) finishes the change.
-2. Main spawns the **verifier** subagent, passing **only**: the requirements, the diff, and the
-   checklist. **Not** the implementer's reasoning or conversation.
-3. The verifier is prompted to **refute** (skeptic; default to FAIL when unsure). It **runs the real
-   commands** (`verify` script — tests/build/lint) and **quotes real output**. No "looks good".
-4. The verifier returns a structured verdict: `pass | fail` + reasons + commands run + quoted output,
-   saved as an artifact.
-5. **Definition of Done** = tests green **AND** verifier `pass` **AND** checklist complete. Missing
-   any one → not done.
-
-## Scaling
-
-- Large work → multiple verifier lenses (correctness / security / requirements-match), run in parallel.
-- Same model family shares blind spots. Mitigate with: refute-style prompt, mandatory quoted
-  evidence, optionally run the verifier on a different model tier. Cross-model verification arrives
-  free when a second tool is added later.
-
-## Tool binding
-
-- Tool-agnostic: this file states the protocol in prose — any agent can follow it.
-- Claude Code: subagent `agents/verifier.md` + command `commands/verify.md`. For big changes, pair
-  with `/code-review` (or `/code-review ultra`).
-- A Stop-hook may warn if "done" is declared without a verifier artifact (per-project opt-in).
+---
+updated: 2026-05-31
+description: 'The independent verifier: the author cannot mark their own work done; verify on fresh context.'
+---
+
+# 30 — Verification (independent verifier)
+
+**Principle: the agent that writes code cannot mark it done.** Bias comes from *shared context*,
+not from the model. Cut the context → cut the bias. One Claude Code subscription is enough via a
+**subagent with fresh context** — the **verifier**.
+
+## Flow (one session)
+
+1. Implementer (main thread) finishes the change.
+2. Main spawns the **verifier** subagent, passing **only**: the requirements, the diff, and the
+   checklist. **Not** the implementer's reasoning or conversation.
+3. The verifier is prompted to **refute** (skeptic; default to FAIL when unsure). It **runs the real
+   commands** (`verify` script — tests/build/lint) and **quotes real output**. No "looks good".
+4. The verifier returns a structured verdict: `pass | fail` + reasons + commands run + quoted output,
+   saved as an artifact.
+5. **Definition of Done** = tests green **AND** verifier `pass` **AND** checklist complete. Missing
+   any one → not done.
+
+## Scaling
+
+- Large work → multiple verifier lenses (correctness / security / requirements-match), run in parallel.
+- Same model family shares blind spots. Mitigate with: refute-style prompt, mandatory quoted
+  evidence, optionally run the verifier on a different model tier. Cross-model verification arrives
+  free when a second tool is added later.
+
+## Tool binding
+
+- Tool-agnostic: this file states the protocol in prose — any agent can follow it.
+- Claude Code: subagent `agents/verifier.md` + command `commands/verify.md`. For big changes, pair
+  with `/code-review` (or `/code-review ultra`).
+- A Stop-hook may warn if "done" is declared without a verifier artifact (per-project opt-in).

package/.agents/rules/35-context-economy.md

@@ -1,41 +1,41 @@
----
-updated: 2026-05-31
-description: Keep entry and always-on files lean; push detail to references read on demand.
----
-
-# 35 — Context economy (keep entry files lean)
-
-Entry and always-loaded files are read every session — bloat there taxes every turn (tokens +
-latency). Keep them lean; push detail to reference files reached on demand. This is the whole point
-of the load-order in `AGENTS.md`: start narrow, pull in depth only when the task needs it.
-
-How to write any of these docs (lead, voice, structure, versioning): `standards/writing.md`.
-
-## Budget
-
-- **Entry files** (`CLAUDE.md`, `.agents/AGENTS.md`, `local/AGENTS.local.md`): target **≤250 lines**,
-  **hard ceiling 300**. Line count is a proxy — the real test is *"is every line read most sessions?"*
-- **Each rule / standard file:** one focused topic. If a file grows past its single concern, split it.
-- **Skills / commands:** a skill body loads in full **when invoked** (its name + description load
-  cheaply; the body does not, until used). Keep a skill focused, **~200 lines max** — split a larger
-  one into sub-skills so unrelated capability is not pulled into context on use.
-- **`journal/memory/MEMORY.md`:** one line per memory; the fact itself lives in its own card.
-
-## What an entry file keeps (and little else)
-
-- tone / persona
-- the hardest **always-on** rules (full text lives in `rules/00-always.md`)
-- load order + routing map (where to find everything)
-- pointers to references (`rules/ standards/ stack/ journal/memory/ local/`)
-- precedence / customization note
-
-## What moves out (linked, read on demand)
-
-full rule text · coding standards · stack configs · the capability catalog · ADRs · examples · any
-long procedure. Replace the moved section with a one-line pointer — never inline a catalog or a long
-procedure into an entry file.
-
-## When an entry file crosses the ceiling
-
-Move the least-daily section into its matching reference file (or a new one) and leave a one-line
-pointer behind. Re-check after every edit that adds to an entry file.
+---
+updated: 2026-05-31
+description: Keep entry and always-on files lean; push detail to references read on demand.
+---
+
+# 35 — Context economy (keep entry files lean)
+
+Entry and always-loaded files are read every session — bloat there taxes every turn (tokens +
+latency). Keep them lean; push detail to reference files reached on demand. This is the whole point
+of the load-order in `AGENTS.md`: start narrow, pull in depth only when the task needs it.
+
+How to write any of these docs (lead, voice, structure, versioning): `standards/writing.md`.
+
+## Budget
+
+- **Entry files** (`CLAUDE.md`, `.agents/AGENTS.md`, `local/AGENTS.local.md`): target **≤250 lines**,
+  **hard ceiling 300**. Line count is a proxy — the real test is *"is every line read most sessions?"*
+- **Each rule / standard file:** one focused topic. If a file grows past its single concern, split it.
+- **Skills / commands:** a skill body loads in full **when invoked** (its name + description load
+  cheaply; the body does not, until used). Keep a skill focused, **~200 lines max** — split a larger
+  one into sub-skills so unrelated capability is not pulled into context on use.
+- **`journal/memory/MEMORY.md`:** one line per memory; the fact itself lives in its own card.
+
+## What an entry file keeps (and little else)
+
+- tone / persona
+- the hardest **always-on** rules (full text lives in `rules/00-always.md`)
+- load order + routing map (where to find everything)
+- pointers to references (`rules/ standards/ stack/ journal/memory/ local/`)
+- precedence / customization note
+
+## What moves out (linked, read on demand)
+
+full rule text · coding standards · stack configs · the capability catalog · ADRs · examples · any
+long procedure. Replace the moved section with a one-line pointer — never inline a catalog or a long
+procedure into an entry file.
+
+## When an entry file crosses the ceiling
+
+Move the least-daily section into its matching reference file (or a new one) and leave a one-line
+pointer behind. Re-check after every edit that adds to an entry file.

package/.agents/rules/40-handoff.md

@@ -1,25 +1,25 @@
----
-updated: 2026-05-31
-description: 'Route every incoming request to exactly one home: chat, backlog, hotfix, or field-report.'
----
-
-# 40 — Handoff routing
-
-Every incoming chat request routes to exactly one of:
-
-- **do-now** — single-commit, finishable this session, no ADR needed. No file; just do it and update
-  `journal/session/current.md`.
-- **BACKLOG** — multi-session, needs an ADR, touches schema/architecture, or the user says "add to
-  backlog". Create a `journal/backlog/<id>.md` item (`status: open`, `priority: normal`).
-- **HOTFIX** — production fire in the **code**. Create a `journal/backlog/<id>.md` item (`priority: hotfix`)
-  with a cleanup checklist, then fix under HOTFIX mode (`20-modes.md`).
-- **FIELD-REPORT** — on-site issue whose cause is **environmental** (hardware / OS / network / AV),
-  not the codebase. Record as a `journal/memory/` `type: field-report`; don't patch code. Grep field-reports
-  before assuming a code defect.
-
-Decision rule of thumb:
-
-> Right-now & small → do-now. Big / needs-a-decision / "later" → BACKLOG. Code on fire → HOTFIX.
-> Site/environment on fire → FIELD-REPORT.
-
-When unsure between do-now and BACKLOG, prefer BACKLOG and confirm scope before building.
+---
+updated: 2026-05-31
+description: 'Route every incoming request to exactly one home: chat, backlog, hotfix, or field-report.'
+---
+
+# 40 — Handoff routing
+
+Every incoming chat request routes to exactly one of:
+
+- **do-now** — single-commit, finishable this session, no ADR needed. No file; just do it and update
+  `journal/session/current.md`.
+- **BACKLOG** — multi-session, needs an ADR, touches schema/architecture, or the user says "add to
+  backlog". Create a `journal/backlog/<id>.md` item (`status: open`, `priority: normal`).
+- **HOTFIX** — production fire in the **code**. Create a `journal/backlog/<id>.md` item (`priority: hotfix`)
+  with a cleanup checklist, then fix under HOTFIX mode (`20-modes.md`).
+- **FIELD-REPORT** — on-site issue whose cause is **environmental** (hardware / OS / network / AV),
+  not the codebase. Record as a `journal/memory/` `type: field-report`; don't patch code. Grep field-reports
+  before assuming a code defect.
+
+Decision rule of thumb:
+
+> Right-now & small → do-now. Big / needs-a-decision / "later" → BACKLOG. Code on fire → HOTFIX.
+> Site/environment on fire → FIELD-REPORT.
+
+When unsure between do-now and BACKLOG, prefer BACKLOG and confirm scope before building.

package/.agents/rules/45-presentation.md

@@ -1,35 +1,35 @@
----
-updated: 2026-05-31
-description: When and how to render human-facing deliverables as HTML instead of long Markdown.
----
-
-# 45 — Presentation (HTML for humans)
-
-Long Markdown gets skimmed. For human-facing deliverables an interactive HTML page communicates
-better — tables, side-by-side comparisons, diff annotations, SVG diagrams, toggles. Render with
-`/present` (`commands/present.md`).
-
-## Toggle (default off)
-
-- Project default: set in `local/AGENTS.local.md` ("Presentation mode").
-- Session override: user says **"html on" / "html off"**. When off, reply in Markdown only.
-- Even when on, use HTML for the deliverable types below — not routine replies.
-
-## Use HTML for
-
-spec comparison · code-review dashboard · report / explainer · design prototype · custom editing UI.
-(Catalog: `skills/catalog.md` -> Presentation.)
-
-## Guardrails
-
-- **Agent files stay Markdown.** Load-path files an agent parses — `AGENTS.md`, `SKILL.md`, `rules/`,
-  `standards/`, `tooling.json`, `INDEX.md`, `journal/memory/`, context files — are never rendered as HTML.
-  HTML is only a human-facing *view* of a deliverable; the agent-readable + git-diffable source is
-  always Markdown.
-- **Source stays canonical.** HTML is an ephemeral *view* generated from the Markdown/spec — never
-  the source of truth. Durable decisions still land in `docs/`, `journal/memory/`, specs.
-- **Self-contained + offline.** One file, inline CSS/JS, no remote `<script>`/CDN.
-- **Security.** Escape embedded code/diff/user text; never run untrusted script; no secrets in the page.
-- **Ephemeral.** Artifacts live in `journal/session/artifacts/` (gitignored). Don't commit them.
-- **Close the loop.** Editing UIs export back as JSON/Markdown so changes re-enter the workflow.
-- **Token-aware.** Generating HTML is expensive; reserve it for deliverables that earn it.
+---
+updated: 2026-05-31
+description: When and how to render human-facing deliverables as HTML instead of long Markdown.
+---
+
+# 45 — Presentation (HTML for humans)
+
+Long Markdown gets skimmed. For human-facing deliverables an interactive HTML page communicates
+better — tables, side-by-side comparisons, diff annotations, SVG diagrams, toggles. Render with
+`/present` (`commands/present.md`).
+
+## Toggle (default off)
+
+- Project default: set in `local/AGENTS.local.md` ("Presentation mode").
+- Session override: user says **"html on" / "html off"**. When off, reply in Markdown only.
+- Even when on, use HTML for the deliverable types below — not routine replies.
+
+## Use HTML for
+
+spec comparison · code-review dashboard · report / explainer · design prototype · custom editing UI.
+(Catalog: `skills/catalog.md` -> Presentation.)
+
+## Guardrails
+
+- **Agent files stay Markdown.** Load-path files an agent parses — `AGENTS.md`, `SKILL.md`, `rules/`,
+  `standards/`, `tooling.json`, `INDEX.md`, `journal/memory/`, context files — are never rendered as HTML.
+  HTML is only a human-facing *view* of a deliverable; the agent-readable + git-diffable source is
+  always Markdown.
+- **Source stays canonical.** HTML is an ephemeral *view* generated from the Markdown/spec — never
+  the source of truth. Durable decisions still land in `docs/`, `journal/memory/`, specs.
+- **Self-contained + offline.** One file, inline CSS/JS, no remote `<script>`/CDN.
+- **Security.** Escape embedded code/diff/user text; never run untrusted script; no secrets in the page.
+- **Ephemeral.** Artifacts live in `journal/session/artifacts/` (gitignored). Don't commit them.
+- **Close the loop.** Editing UIs export back as JSON/Markdown so changes re-enter the workflow.
+- **Token-aware.** Generating HTML is expensive; reserve it for deliverables that earn it.

package/.agents/rules/50-security.md

@@ -1,30 +1,30 @@
----
-updated: 2026-05-31
-description: Server-side authorization, no hardcoded secrets/roles, fail closed.
----
-
-# 50 — Security
-
-- **Permissions via helpers, not literals.** Authorize through a single helper/policy layer.
-  Never `if (role === "admin")` scattered across the code.
-- **Validate + authorize on the server.** Client checks are UX only; the server is the boundary.
-  Validate every input; reject by default.
-- **Fail closed.** On error, missing data, or unknown state → deny, do not allow.
-- **Parameterized queries only.** Never string-concatenate SQL or shell. No dynamic `eval`.
-- **No secrets in code or logs.** Secrets come from env/secret-store. Never commit them; never log
-  them. Scrub before logging.
-- **Least privilege.** Tokens, DB roles, and API scopes get the minimum needed.
-- **Row-level authorization.** Every user row is restricted to its owner (Postgres/Supabase RLS or
-  an app-layer check). **Default-deny** — zero policies means a wide-open database.
-- **Test the abuse paths.** Wrong password, reset for a non-existent email (no user enumeration),
-  expired session, malformed/oversized input — not just the happy path.
-- **Security headers.** Set CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy.
-- **Privacy by default.** Collect the minimum personal data, know where it lives, publish a privacy
-  policy (GDPR/CCPA/PDPA; PHI → HIPAA).
-- **Validate env at startup.** Required env vars are checked at the init boundary with a clear error — never `process.env.X!` at use sites.
-- **Secrets at rest.** Desktop/native apps store secrets in the OS keystore (Electron `safeStorage` / OS keychain), never plaintext on disk.
-- **Dependencies.** Pin versions; review before adding; prefer the std lib when it suffices.
-
-**Before launching a user-facing, data-collecting app:** clear `standards/launch-security-checklist.md`
-(privacy · row-level authz · abuse-path tests · server validation · headers · OWASP) and run a SAST
-scan (`standards/security-scanners.md`). This is part of Definition of Done (`rules/30-verification.md`).
+---
+updated: 2026-05-31
+description: Server-side authorization, no hardcoded secrets/roles, fail closed.
+---
+
+# 50 — Security
+
+- **Permissions via helpers, not literals.** Authorize through a single helper/policy layer.
+  Never `if (role === "admin")` scattered across the code.
+- **Validate + authorize on the server.** Client checks are UX only; the server is the boundary.
+  Validate every input; reject by default.
+- **Fail closed.** On error, missing data, or unknown state → deny, do not allow.
+- **Parameterized queries only.** Never string-concatenate SQL or shell. No dynamic `eval`.
+- **No secrets in code or logs.** Secrets come from env/secret-store. Never commit them; never log
+  them. Scrub before logging.
+- **Least privilege.** Tokens, DB roles, and API scopes get the minimum needed.
+- **Row-level authorization.** Every user row is restricted to its owner (Postgres/Supabase RLS or
+  an app-layer check). **Default-deny** — zero policies means a wide-open database.
+- **Test the abuse paths.** Wrong password, reset for a non-existent email (no user enumeration),
+  expired session, malformed/oversized input — not just the happy path.
+- **Security headers.** Set CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy.
+- **Privacy by default.** Collect the minimum personal data, know where it lives, publish a privacy
+  policy (GDPR/CCPA/PDPA; PHI → HIPAA).
+- **Validate env at startup.** Required env vars are checked at the init boundary with a clear error — never `process.env.X!` at use sites.
+- **Secrets at rest.** Desktop/native apps store secrets in the OS keystore (Electron `safeStorage` / OS keychain), never plaintext on disk.
+- **Dependencies.** Pin versions; review before adding; prefer the std lib when it suffices.
+
+**Before launching a user-facing, data-collecting app:** clear `standards/launch-security-checklist.md`
+(privacy · row-level authz · abuse-path tests · server validation · headers · OWASP) and run a SAST
+scan (`standards/security-scanners.md`). This is part of Definition of Done (`rules/30-verification.md`).