the-grimoire-cli 0.3.2 → 0.5.0

package/.agents/stack/README.md

@@ -1,66 +1,71 @@
-# Stack — tech-stack presets
-
-A **profile** pins the framework, lint/format, test setup, and CI scaffold for a project type.
-Pick one at `init`; record the active profile in `local/AGENTS.local.md`.
-
-## Profiles (v0.1 starter set)
-
-- `web-app.md` — full-stack / front-end web.
-- `desktop.md` — Electron / desktop app.
-- `library.md` — published or internal reusable package.
-
-## Testing-policy knob (per profile, project chooses — not hardcoded)
-
-| Policy | Meaning |
-|---|---|
-| `tdd-mandatory` | Red-green-refactor required before merge (ever-sync style). |
-| `test-ready-deferred` | Test harness wired; tests written as features stabilize (pharma style). |
-| `none` | No automated tests (spikes/throwaway only). **Requires a recorded ADR** (`codex/decisions/`) — see `rules/00-always.md` "No silent test gaps". |
-
-## The `verify` script
-
-Every profile defines a `verify` command — the single gate the **verifier** runs
-(`rules/30-verification.md`):
-
-```
-verify = typecheck + lint + test + coverage + format:check
-```
-
-Wire it as a package script (`npm run verify`) so it is one command everywhere. The verifier runs it
-and quotes the real output; "looks good" is never acceptable.
-
-## Knowledge retrieval — graphify (ADR 0006)
-
-Grimoire does **not** ship a homegrown retrieval engine. Searching the codebase (and `codex/`) is
-delegated to **graphify**, a code+docs knowledge graph. The base prescribes the convention; install is
-per-machine.
-
-- **Install** (one-time, per machine): `uv tool install graphifyy` then `graphify install`.
-- **Build / refresh** the graph for a repo: `graphify .` (PowerShell: no leading slash). Code is
-  extracted locally via AST (free, no API); docs/PDFs use the IDE session model (no separate key).
-  `graphify hook install` rebuilds the code graph on every commit (AST only, free).
-- **Query-first**: prefer `graphify query "<question>"` / `graphify path A B` / `graphify explain X`
-  over grepping raw files or reading the whole report — it is the cheaper, structured path.
-- **Commit policy**: `graphify-out/` is committed so the team shares one map; local-only artifacts
-  (`cost.json`, `cache/`, `.graphify_python`) are gitignored (`templates/gitignore-snippet.txt`).
-- **`codex/` is the source of truth** graphify indexes — content vs retrieval stay separate.
-
-Optional personal layer (not a base dependency): **obsidian-wiki** maintains a cross-project Obsidian
-vault via the coding agent (Karpathy LLM-Wiki). Install it in your global agent skills, never in the
-managed contract.
-
-## Laziness enforcement — ponytail (ADR 0007)
-
-The **principle** lives in the contract: `standards/clean-code.md` owns the ladder, the "never
-simplify away" guardrail, and the `ponytail:` shortcut marker — tool-agnostic, every agent gets it.
-**Enforcement automation** is delegated to the **ponytail** plugin (skill-capable hosts: Claude Code,
-Codex, OpenCode, Gemini, pi); install is per-machine, optional.
-
-- **Install** (Claude Code): `/plugin marketplace add DietrichGebert/ponytail` then
-  `/plugin install ponytail@ponytail`. Other hosts: see the ponytail README.
-- **`/ponytail-review`** — review the current diff for over-engineering; hands back a delete-list.
-- **`/ponytail-audit`** — same, whole repo instead of the diff.
-- **`/ponytail-debt`** — harvest the `ponytail:` shortcut markers into a ledger so "later" isn't
-  "never". This is why the marker token in `clean-code.md` is literally `ponytail:`.
-- Without the plugin the principle still holds (the marker is self-documenting); you just lose the
-  automated harvest/review.
+# Stack — tech-stack presets
+
+A **profile** pins the framework, lint/format, test setup, and CI scaffold for a project type.
+Pick one at `init`; record the active profile in `local/AGENTS.local.md`.
+
+## Profiles (v0.1 starter set)
+
+- `web-app.md` — full-stack / front-end web.
+- `desktop.md` — Electron / desktop app.
+- `library.md` — published or internal reusable package.
+
+## Testing-policy knob (per profile, project chooses — not hardcoded)
+
+| Policy | Meaning |
+|---|---|
+| `tdd-mandatory` | Red-green-refactor required before merge (ever-sync style). |
+| `test-ready-deferred` | Test harness wired; tests written as features stabilize (pharma style). |
+| `none` | No automated tests (spikes/throwaway only). **Requires a recorded ADR** (`codex/decisions/`) — see `rules/00-always.md` "No silent test gaps". |
+
+## The `verify` script
+
+Every profile defines a `verify` command — the single gate the **verifier** runs
+(`rules/30-verification.md`):
+
+```
+verify = typecheck + lint + test + coverage + format:check
+```
+
+Wire it as a package script (`npm run verify`) so it is one command everywhere. The verifier runs it
+and quotes the real output; "looks good" is never acceptable.
+
+## Knowledge retrieval — graphify (ADR 0006)
+
+Grimoire does **not** ship a homegrown retrieval engine. Searching the codebase (and `codex/`) is
+delegated to **graphify**, a code+docs knowledge graph. The base prescribes the convention; install is
+per-machine.
+
+- **Install** (one-time, per machine): `uv tool install graphifyy` then `graphify install`.
+- **Build / refresh** the graph for a repo: `graphify .` (PowerShell: no leading slash). Code is
+  extracted locally via AST (free, no API); docs/PDFs use the IDE session model (no separate key).
+  `graphify hook install` rebuilds the code graph on every commit (AST only, free).
+- **Query-first**: prefer `graphify query "<question>"` / `graphify path A B` / `graphify explain X`
+  over grepping raw files or reading the whole report — it is the cheaper, structured path.
+- **Commit policy**: `graphify-out/` is **gitignored by default** (`templates/gitignore-snippet.txt`)
+  — when `graphify hook install` rebuilds the graph on every commit, a committed graph would churn on
+  each commit and always sit one commit stale, so each clone rebuilds it locally instead. Commit the
+  graph only if you do **not** use the post-commit hook (rebuild it deliberately) and want it browsable
+  in-repo; whitelist `graph.json`/`graph.html`/`GRAPH_REPORT.md`/`manifest.json` then.
+- **`codex/` is the source of truth** graphify indexes — content vs retrieval stay separate.
+
+Optional personal layer (not a base dependency): **obsidian-wiki** maintains a cross-project Obsidian
+vault via the coding agent (Karpathy LLM-Wiki). Install it in your global agent skills, never in the
+managed contract.
+
+## Laziness enforcement — ponytail (ADR 0007)
+
+The **principle** lives in the contract: `standards/clean-code.md` owns the ladder, the "never
+simplify away" guardrail, and the `ponytail:` shortcut marker — tool-agnostic, every agent gets it.
+**Enforcement automation** is delegated to the **ponytail** plugin (skill-capable hosts: Claude Code,
+Codex, OpenCode, Gemini, pi); install is per-machine, optional.
+
+- **Install** (Claude Code): `/plugin marketplace add DietrichGebert/ponytail` then
+  `/plugin install ponytail@ponytail`. Other hosts: see the ponytail README. ponytail is declared in
+  `tooling.json` (with a `source` field = the marketplace repo), so `grimoire bootstrap` lists it and
+  prints exactly this paste command.
+- **`/ponytail-review`** — review the current diff for over-engineering; hands back a delete-list.
+- **`/ponytail-audit`** — same, whole repo instead of the diff.
+- **`/ponytail-debt`** — harvest the `ponytail:` shortcut markers into a ledger so "later" isn't
+  "never". This is why the marker token in `clean-code.md` is literally `ponytail:`.
+- Without the plugin the principle still holds (the marker is self-documenting); you just lose the
+  automated harvest/review.

package/.agents/stack/desktop.md

@@ -1,36 +1,36 @@
-# Profile: desktop
-
-Default for Electron / desktop apps (harvested from ever-sync-adapter).
-
-| Concern | Default |
-|---|---|
-| Shell | Electron |
-| Language | TypeScript (`strict`) |
-| Lint / format | ESLint + Prettier |
-| Test | Vitest (unit) + Playwright/Spectron-style (integration) |
-| IPC | typed channels; document the channel table in `journal/memory/` |
-| Release | new code paths behind env flags (single-unset rollback) |
-| CI | typecheck + lint + test + package on tag |
-| Testing policy | `tdd-mandatory` (override per project) |
-
-`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check .`
-
-Note: for on-site/production tools, pair with HOTFIX mode (`rules/20-modes.md`).
-
-## Reference defaults (adapt per project; vendor names are examples)
-
-- **Process boundaries:** separate tsconfig per process (main / renderer / preload / shared) with
-  path aliases; explicit IPC channel registry (one `channels.ts`), preload bridge, and typed API.
-- **IPC discipline:** adding a channel touches several files (registry, preload, types, handler, the
-  AGENTS.md/`local/` channel table) — keep that checklist explicit and, ideally, a guardrail test
-  that diffs the registry against the allow-list in CI.
-- **Secrets at rest:** OS keystore (`safeStorage` / keychain), never plaintext in the local DB
-  (`rules/50`).
-- **Native modules:** rebuild for Electron (`electron-rebuild`) before dev/dist; pin native driver
-  versions per backend (e.g. Oracle Instant Client per server version).
-- **Local DB:** embedded SQLite via a typed query builder; a single factory is the only legal
-  instantiation point; temp-DB fixtures (`mkdtemp` + cleanup) for tests.
-- **Tests:** Vitest (unit + integration) + Playwright (E2E); CSP + boundary regression as gates in
-  the `verify` chain. Desktop profile defaults to `tdd-mandatory`.
-- **Lint preset:** start from `templates/lint/` (clean-code limits + type-safety); enforce via
-  `eslint .` in `verify`.
+# Profile: desktop
+
+Default for Electron / desktop apps (harvested from ever-sync-adapter).
+
+| Concern | Default |
+|---|---|
+| Shell | Electron |
+| Language | TypeScript (`strict`) |
+| Lint / format | ESLint + Prettier |
+| Test | Vitest (unit) + Playwright/Spectron-style (integration) |
+| IPC | typed channels; document the channel table in `journal/memory/` |
+| Release | new code paths behind env flags (single-unset rollback) |
+| CI | typecheck + lint + test + package on tag |
+| Testing policy | `tdd-mandatory` (override per project) |
+
+`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check .`
+
+Note: for on-site/production tools, pair with HOTFIX mode (`rules/20-modes.md`).
+
+## Reference defaults (adapt per project; vendor names are examples)
+
+- **Process boundaries:** separate tsconfig per process (main / renderer / preload / shared) with
+  path aliases; explicit IPC channel registry (one `channels.ts`), preload bridge, and typed API.
+- **IPC discipline:** adding a channel touches several files (registry, preload, types, handler, the
+  AGENTS.md/`local/` channel table) — keep that checklist explicit and, ideally, a guardrail test
+  that diffs the registry against the allow-list in CI.
+- **Secrets at rest:** OS keystore (`safeStorage` / keychain), never plaintext in the local DB
+  (`rules/50`).
+- **Native modules:** rebuild for Electron (`electron-rebuild`) before dev/dist; pin native driver
+  versions per backend (e.g. Oracle Instant Client per server version).
+- **Local DB:** embedded SQLite via a typed query builder; a single factory is the only legal
+  instantiation point; temp-DB fixtures (`mkdtemp` + cleanup) for tests.
+- **Tests:** Vitest (unit + integration) + Playwright (E2E); CSP + boundary regression as gates in
+  the `verify` chain. Desktop profile defaults to `tdd-mandatory`.
+- **Lint preset:** start from `templates/lint/` (clean-code limits + type-safety); enforce via
+  `eslint .` in `verify`.

package/.agents/stack/library.md

@@ -13,4 +13,4 @@ Default for published or internal reusable packages.
 | CI | typecheck + lint + test + build + pack-check on PR |
 | Testing policy | `tdd-mandatory` (public contract — override per project) |
 
-`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check . && npm pack --dry-run`
+`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check . && npm pack --dry-run`

package/.agents/stack/web-app.md

@@ -1,32 +1,32 @@
-# Profile: web-app
-
-Default for full-stack / front-end web projects.
-
-| Concern | Default |
-|---|---|
-| Framework | Next.js (App Router) or Vite + React |
-| Language | TypeScript (`strict`) — see `standards/typescript.md` |
-| Lint / format | ESLint + Prettier |
-| Test | Vitest + React Testing Library; Playwright for e2e |
-| Coverage | reported in `verify`; threshold set per project |
-| Validation | zod at every boundary |
-| CI | typecheck + lint + test + build on PR |
-| Testing policy | `test-ready-deferred` (override per project) |
-
-`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check .`
-
-## Reference defaults (adapt per project; vendor names are examples)
-
-- **Auth guards — one model, three call-site shapes:** a single `can(permission)` policy with
-  `requirePermission()` (throws, for actions), `requirePermissionResponse()` (returns 401, for route
-  handlers), `requirePermissionOrRedirect()` (for pages). Zero inline `role === "x"` checks.
-- **Edge-safe auth split:** keep an edge/middleware config with **no DB** separate from the full
-  server auth that hits the DB at sign-in (Auth.js v5 pattern).
-- **Validation:** zod at every server-action boundary; client validation is UX only (`rules/50`).
-- **Module layering:** pure engine + read/write/projection split + schema-ownership by module
-  (`standards/architecture.md`).
-- **Security headers in one place** (e.g. `next.config` headers): CSP, HSTS, X-Frame-Options DENY,
-  X-Content-Type-Options, Referrer-Policy, Permissions-Policy; disable `poweredByHeader`.
-- **DB:** typed query builder / ORM with tracked migrations (generate → migrate); `db:push` dev-only.
-- **Lint preset:** start from `templates/lint/` (clean-code limits + type-safety); `eslint .` in the
-  `verify` script enforces it.
+# Profile: web-app
+
+Default for full-stack / front-end web projects.
+
+| Concern | Default |
+|---|---|
+| Framework | Next.js (App Router) or Vite + React |
+| Language | TypeScript (`strict`) — see `standards/typescript.md` |
+| Lint / format | ESLint + Prettier |
+| Test | Vitest + React Testing Library; Playwright for e2e |
+| Coverage | reported in `verify`; threshold set per project |
+| Validation | zod at every boundary |
+| CI | typecheck + lint + test + build on PR |
+| Testing policy | `test-ready-deferred` (override per project) |
+
+`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check .`
+
+## Reference defaults (adapt per project; vendor names are examples)
+
+- **Auth guards — one model, three call-site shapes:** a single `can(permission)` policy with
+  `requirePermission()` (throws, for actions), `requirePermissionResponse()` (returns 401, for route
+  handlers), `requirePermissionOrRedirect()` (for pages). Zero inline `role === "x"` checks.
+- **Edge-safe auth split:** keep an edge/middleware config with **no DB** separate from the full
+  server auth that hits the DB at sign-in (Auth.js v5 pattern).
+- **Validation:** zod at every server-action boundary; client validation is UX only (`rules/50`).
+- **Module layering:** pure engine + read/write/projection split + schema-ownership by module
+  (`standards/architecture.md`).
+- **Security headers in one place** (e.g. `next.config` headers): CSP, HSTS, X-Frame-Options DENY,
+  X-Content-Type-Options, Referrer-Policy, Permissions-Policy; disable `poweredByHeader`.
+- **DB:** typed query builder / ORM with tracked migrations (generate → migrate); `db:push` dev-only.
+- **Lint preset:** start from `templates/lint/` (clean-code limits + type-safety); `eslint .` in the
+  `verify` script enforces it.

package/.agents/standards/INDEX.md

@@ -1,23 +1,23 @@
-# standards — index
-
-<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
-
-| File | What it covers |
-|---|---|
-| `accessibility.md` | Baseline accessibility (WCAG 2.x AA) for any user-facing surface — the non-negotiable floor plus how to verify it. |
-| `architecture.md` | Module layering and boundaries distilled from real modular codebases. |
-| `attribution.md` | Credit the external work the project builds on: what to record when adopting a tool/pattern/idea, where it goes, and the adapt-not-copy rul… |
-| `clean-code.md` | The canonical code-quality standard: minimize complexity, with limits, type-safety, and performance rules. |
-| `codex.md` | The codex — the project's knowledge/resource root at the repo root: read-first rule, provenance discipline, secrets boundary, and how it re… |
-| `error-codes.md` | Every error carries a stable code so logs, tests, and UIs switch on it, not on message strings. |
-| `general.md` | Baseline conventions: naming, file size, import order, error handling, formatting. |
-| `guardrail-tests.md` | Structural-invariant tests that fail CI when two sources of truth drift apart. |
-| `knowledge-management.md` | The second-brain model: three homes for work-state, and how to view memory as an optional Obsidian vault. |
-| `launch-security-checklist.md` | Pre-launch privacy + security gate for any app that collects user data. |
-| `observability.md` | Production logging, metrics, and tracing lessons from real data/sync tools. |
-| `release-versioning.md` | Versioning, changelog, and release discipline across app and library profiles — what ships, how it's tagged, how it's recorded. |
-| `requirements.md` | How requirements are captured, identified, versioned, and traced — base requirements plus addons and change requests. |
-| `security-scanners.md` | SAST scanners by language and how to wire them into CI to catch exploitable bugs. |
-| `testing-strategy.md` | The project-wide testing approach: the pyramid, what to test at each level, the active policy, and what 'tested' means. |
-| `typescript.md` | TypeScript specifics: strict mode, no any, type-safety expectations. |
-| `writing.md` | How to write agent-facing docs so they are high-signal and versioned. |
+# standards — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `accessibility.md` | Baseline accessibility (WCAG 2.x AA) for any user-facing surface — the non-negotiable floor plus how to verify it. |
+| `architecture.md` | Module layering and boundaries distilled from real modular codebases. |
+| `attribution.md` | Credit the external work the project builds on: what to record when adopting a tool/pattern/idea, where it goes, and the adapt-not-copy rul… |
+| `clean-code.md` | The canonical code-quality standard: minimize complexity, with limits, type-safety, and performance rules. |
+| `codex.md` | The codex — the project's knowledge/resource root at the repo root: read-first rule, provenance discipline, secrets boundary, and how it re… |
+| `error-codes.md` | Every error carries a stable code so logs, tests, and UIs switch on it, not on message strings. |
+| `general.md` | Baseline conventions: naming, file size, import order, error handling, formatting. |
+| `guardrail-tests.md` | Structural-invariant tests that fail CI when two sources of truth drift apart. |
+| `knowledge-management.md` | The second-brain model: three homes for work-state, and how to view memory as an optional Obsidian vault. |
+| `launch-security-checklist.md` | Pre-launch privacy + security gate for any app that collects user data. |
+| `observability.md` | Production logging, metrics, and tracing lessons from real data/sync tools. |
+| `release-versioning.md` | Versioning, changelog, and release discipline across app and library profiles — what ships, how it's tagged, how it's recorded. |
+| `requirements.md` | How requirements are captured, identified, versioned, and traced — base requirements plus addons and change requests. |
+| `security-scanners.md` | SAST scanners by language and how to wire them into CI to catch exploitable bugs. |
+| `testing-strategy.md` | The project-wide testing approach: the pyramid, what to test at each level, the active policy, and what 'tested' means. |
+| `typescript.md` | TypeScript specifics: strict mode, no any, type-safety expectations. |
+| `writing.md` | How to write agent-facing docs so they are high-signal and versioned. |

package/.agents/standards/accessibility.md

@@ -1,50 +1,50 @@
----
-updated: 2026-05-31
-status: canonical
-description: "Baseline accessibility (WCAG 2.x AA) for any user-facing surface — the non-negotiable floor plus how to verify it."
----
-
-# Standards — accessibility
-
-Applies to every user-facing surface (web, desktop UI). Target: **WCAG 2.2 level AA**. Accessibility
-is part of Definition of Done for UI work, not a later pass — it is cheapest built in and most
-expensive retrofitted.
-
-## The non-negotiable floor
-
-- **Semantic HTML first.** Use the right element (`button`, `a`, `nav`, `main`, `label`, `table`).
-  A `div` with a click handler is not a button — it loses keyboard, focus, and screen-reader
-  semantics. Reach for ARIA only when no native element fits, and prefer a native one.
-- **Keyboard operable.** Every interactive control is reachable and operable by keyboard alone, in a
-  logical tab order, with a **visible focus indicator**. No keyboard trap. Test by unplugging the
-  mouse.
-- **Labels & names.** Every input has an associated `<label>`; every icon-only control has an
-  accessible name (`aria-label`); every meaningful image has `alt` (decorative → `alt=""`).
-- **Contrast.** Text ≥ 4.5:1 (≥ 3:1 for large text); UI/graphics ≥ 3:1. Don't encode meaning by
-  **color alone** — pair it with text, icon, or pattern.
-- **Forms & errors.** Errors are announced (not color-only), tied to their field
-  (`aria-describedby`), and the message says how to fix it. Don't disable submit silently.
-- **Structure.** One `h1`; headings nest without skipping. Landmarks (`main`, `nav`) so AT users can
-  jump. Page has a sensible `<title>` and `lang`.
-- **Motion & media.** Respect `prefers-reduced-motion`; no content flashes > 3×/sec; captions/text
-  alternatives for audio/video.
-- **Targets & zoom.** Touch targets ≥ 24×24 CSS px; layout survives 200% zoom and 320px width
-  (reflow, no horizontal scroll).
-- **Live regions.** Dynamic updates (toasts, async results) use `aria-live` so they are announced.
-
-## Internationalization note
-
-If the app is localized (e.g. Thai-first), set `lang` correctly, don't hardcode LTR assumptions, and
-don't build strings by concatenation — these intersect with screen-reader correctness.
-
-## Verify it (not by eye alone)
-
-1. **Automated:** run an axe-based check (axe-core / Playwright `@axe-core/playwright` / Lighthouse)
-   in CI for key pages. Catches ~40% of issues — necessary, not sufficient.
-2. **Keyboard pass:** tab through the whole flow; confirm order, focus visibility, no trap.
-3. **Screen reader smoke:** one pass with VoiceOver/NVDA on the primary flow.
-4. **Zoom/reflow:** 200% zoom + 320px width with no loss of content or function.
-
-The `ecc:frontend-a11y` skill (`skills/catalog.md`) automates much of the audit; this standard is the
-floor it audits against. For UI work, an a11y check is part of the verifier's review
-(`rules/30-verification.md`).
+---
+updated: 2026-05-31
+status: canonical
+description: "Baseline accessibility (WCAG 2.x AA) for any user-facing surface — the non-negotiable floor plus how to verify it."
+---
+
+# Standards — accessibility
+
+Applies to every user-facing surface (web, desktop UI). Target: **WCAG 2.2 level AA**. Accessibility
+is part of Definition of Done for UI work, not a later pass — it is cheapest built in and most
+expensive retrofitted.
+
+## The non-negotiable floor
+
+- **Semantic HTML first.** Use the right element (`button`, `a`, `nav`, `main`, `label`, `table`).
+  A `div` with a click handler is not a button — it loses keyboard, focus, and screen-reader
+  semantics. Reach for ARIA only when no native element fits, and prefer a native one.
+- **Keyboard operable.** Every interactive control is reachable and operable by keyboard alone, in a
+  logical tab order, with a **visible focus indicator**. No keyboard trap. Test by unplugging the
+  mouse.
+- **Labels & names.** Every input has an associated `<label>`; every icon-only control has an
+  accessible name (`aria-label`); every meaningful image has `alt` (decorative → `alt=""`).
+- **Contrast.** Text ≥ 4.5:1 (≥ 3:1 for large text); UI/graphics ≥ 3:1. Don't encode meaning by
+  **color alone** — pair it with text, icon, or pattern.
+- **Forms & errors.** Errors are announced (not color-only), tied to their field
+  (`aria-describedby`), and the message says how to fix it. Don't disable submit silently.
+- **Structure.** One `h1`; headings nest without skipping. Landmarks (`main`, `nav`) so AT users can
+  jump. Page has a sensible `<title>` and `lang`.
+- **Motion & media.** Respect `prefers-reduced-motion`; no content flashes > 3×/sec; captions/text
+  alternatives for audio/video.
+- **Targets & zoom.** Touch targets ≥ 24×24 CSS px; layout survives 200% zoom and 320px width
+  (reflow, no horizontal scroll).
+- **Live regions.** Dynamic updates (toasts, async results) use `aria-live` so they are announced.
+
+## Internationalization note
+
+If the app is localized (e.g. Thai-first), set `lang` correctly, don't hardcode LTR assumptions, and
+don't build strings by concatenation — these intersect with screen-reader correctness.
+
+## Verify it (not by eye alone)
+
+1. **Automated:** run an axe-based check (axe-core / Playwright `@axe-core/playwright` / Lighthouse)
+   in CI for key pages. Catches ~40% of issues — necessary, not sufficient.
+2. **Keyboard pass:** tab through the whole flow; confirm order, focus visibility, no trap.
+3. **Screen reader smoke:** one pass with VoiceOver/NVDA on the primary flow.
+4. **Zoom/reflow:** 200% zoom + 320px width with no loss of content or function.
+
+The `ecc:frontend-a11y` skill (`skills/catalog.md`) automates much of the audit; this standard is the
+floor it audits against. For UI work, an a11y check is part of the verifier's review
+(`rules/30-verification.md`).

package/.agents/standards/architecture.md

@@ -1,39 +1,39 @@
----
-updated: 2026-05-31
-status: canonical
-description: Module layering and boundaries distilled from real modular codebases.
----
-
-# Standards — architecture
-
-Patterns distilled from real modular codebases. Apply where the module is non-trivial; don't
-over-structure a thin CRUD screen (YAGNI).
-
-## Pure domain layer
-
-- Keep business logic in a layer with **zero framework/DB/IO imports** (call it `engine/`, `domain/`,
-  or `core/`). Plain functions in, plain data out.
-- DB/IO lives only in dedicated read/write modules that call into the pure layer — never the reverse.
-- Make non-determinism injectable: pass a **seeded RNG** / clock, so generation is reproducible and
-  unit-testable without mocks.
-
-## Read / write / projection split
-
-- **reads** — query module (`data/queries.ts`), `server-only`, returns raw rows.
-- **writes** — action module (`actions/`), the only place that mutates.
-- **projections** — pure shape transforms for each render surface, no DB. Independently testable.
-- A view layer composes reads + projections and owns the cache tag.
-
-## Schema / ownership by module
-
-- Core owns identity-level schema only; each module owns its own tables. The shared DB client is
-  **schema-less** (doesn't import module tables at init), so modules don't become a circular hub.
-- Modules may re-export core tables for FK convenience — never invert the dependency.
-
-## Invariants
-
-- Where correctness depends on a structural fact (an inner-join that excludes ghosts, an ordering, a
-  default), state it with a `// INVARIANT:` comment **and** a test. A silent structural invariant
-  breaks the first time someone writes a left-join.
-- Validate required env at the **startup boundary** with a clear error — never `process.env.X!`
-  scattered at use sites (a missing var should fail loud at init, not as a random runtime error).
+---
+updated: 2026-05-31
+status: canonical
+description: Module layering and boundaries distilled from real modular codebases.
+---
+
+# Standards — architecture
+
+Patterns distilled from real modular codebases. Apply where the module is non-trivial; don't
+over-structure a thin CRUD screen (YAGNI).
+
+## Pure domain layer
+
+- Keep business logic in a layer with **zero framework/DB/IO imports** (call it `engine/`, `domain/`,
+  or `core/`). Plain functions in, plain data out.
+- DB/IO lives only in dedicated read/write modules that call into the pure layer — never the reverse.
+- Make non-determinism injectable: pass a **seeded RNG** / clock, so generation is reproducible and
+  unit-testable without mocks.
+
+## Read / write / projection split
+
+- **reads** — query module (`data/queries.ts`), `server-only`, returns raw rows.
+- **writes** — action module (`actions/`), the only place that mutates.
+- **projections** — pure shape transforms for each render surface, no DB. Independently testable.
+- A view layer composes reads + projections and owns the cache tag.
+
+## Schema / ownership by module
+
+- Core owns identity-level schema only; each module owns its own tables. The shared DB client is
+  **schema-less** (doesn't import module tables at init), so modules don't become a circular hub.
+- Modules may re-export core tables for FK convenience — never invert the dependency.
+
+## Invariants
+
+- Where correctness depends on a structural fact (an inner-join that excludes ghosts, an ordering, a
+  default), state it with a `// INVARIANT:` comment **and** a test. A silent structural invariant
+  breaks the first time someone writes a left-join.
+- Validate required env at the **startup boundary** with a clear error — never `process.env.X!`
+  scattered at use sites (a missing var should fail loud at init, not as a random runtime error).

package/.agents/standards/attribution.md

@@ -1,39 +1,39 @@
----
-updated: 2026-06-14
-status: canonical
-description: "Credit the external work the project builds on: what to record when adopting a tool/pattern/idea, where it goes, and the adapt-not-copy rule."
----
-
-# Standards — attribution
-
-Credit the external work the project builds on. When you adopt something from outside — a tool,
-library, framework, pattern, or idea (including an article or gist you adapt) — record it and credit
-its author. This is ethics **and** provenance: a future reader must know what is ours, what is
-borrowed, and where it came from. It is the same discipline as `standards/codex.md` (every fact cites
-its source), applied to dependencies.
-
-## What to record
-
-For every external adoption:
-
-- **Name** + **author** (handle / org if known)
-- **Source** — repo URL, package name, or article/gist link
-- **License** — and any redistribution constraint. **Verify it; never guess a license.**
-- **What you adopted** — the tool/pattern, and whether used **as-is** or **adapted**
-- **Where it's wired** — the adopting ADR, and the files/standards that reference it
-- **Date**
-
-## Where it goes
-
-- **The adopting ADR cites the source.** Any decision to bring in an external tool/pattern names and
-  links it in `codex/decisions/` (this template repo: `docs/adr/`). The *why* carries the credit —
-  non-negotiable.
-- **A running ledger** collects them in one place: `docs/attributions.md` at the repo root (the
-  Grimoire template uses this), or `codex/resources/manifest.md` for a consuming project's resources.
-
-## Adapt, don't copy
-
-When you adapt an external idea to this stack, say so and say what you changed — a vendor example is an
-illustration, not a mandate. Credit the source for the idea even when little of its form survives.
-
-Keep this lean (`rules/35-context-economy.md`).
+---
+updated: 2026-06-14
+status: canonical
+description: "Credit the external work the project builds on: what to record when adopting a tool/pattern/idea, where it goes, and the adapt-not-copy rule."
+---
+
+# Standards — attribution
+
+Credit the external work the project builds on. When you adopt something from outside — a tool,
+library, framework, pattern, or idea (including an article or gist you adapt) — record it and credit
+its author. This is ethics **and** provenance: a future reader must know what is ours, what is
+borrowed, and where it came from. It is the same discipline as `standards/codex.md` (every fact cites
+its source), applied to dependencies.
+
+## What to record
+
+For every external adoption:
+
+- **Name** + **author** (handle / org if known)
+- **Source** — repo URL, package name, or article/gist link
+- **License** — and any redistribution constraint. **Verify it; never guess a license.**
+- **What you adopted** — the tool/pattern, and whether used **as-is** or **adapted**
+- **Where it's wired** — the adopting ADR, and the files/standards that reference it
+- **Date**
+
+## Where it goes
+
+- **The adopting ADR cites the source.** Any decision to bring in an external tool/pattern names and
+  links it in `codex/decisions/` (this template repo: `docs/adr/`). The *why* carries the credit —
+  non-negotiable.
+- **A running ledger** collects them in one place: `docs/attributions.md` at the repo root (the
+  Grimoire template uses this), or `codex/resources/manifest.md` for a consuming project's resources.
+
+## Adapt, don't copy
+
+When you adapt an external idea to this stack, say so and say what you changed — a vendor example is an
+illustration, not a mandate. Credit the source for the idea even when little of its form survives.
+
+Keep this lean (`rules/35-context-economy.md`).