the-grimoire-cli 0.3.2 → 0.4.0

package/.agents/standards/testing-strategy.md

@@ -1,61 +1,61 @@
----
-updated: 2026-05-31
-status: canonical
-description: "The project-wide testing approach: the pyramid, what to test at each level, the active policy, and what 'tested' means."
----
-
-# Standards — testing strategy
-
-The per-stack **policy** (`tdd-mandatory | test-ready-deferred | none`) says *whether* you write
-tests now (`stack/`). This standard says *how* you test when you do — so "add tests" is never an
-open question.
-
-## The pyramid (most tests cheap, few tests broad)
-
-| Level | Tests | Speed | Use for |
-|---|---|---|---|
-| **Unit** | pure functions, domain/engine logic, reducers, validators | ms, no I/O | the bulk; every branch of business logic |
-| **Integration** | a module against its real boundaries (DB, queue, an adapter) | seconds | data access, server actions, wiring |
-| **E2E / contract** | a user-visible flow or a published API contract | slow | a few critical happy paths + key failure paths |
-
-Push logic **down** the pyramid: keep the domain layer pure (`standards/architecture.md`) so most
-behavior is unit-testable without spinning up I/O.
-
-## What a good test asserts
-
-- **Behavior, not implementation.** Assert observable output/effect for an input, not internal calls.
-  A refactor that preserves behavior must not break the test.
-- **One reason to fail.** Each test pins one behavior; the name states it (`returns 409 when the
-  slot is already taken`).
-- **Failure paths first-class.** Test the error/empty/forbidden branches, not just the happy path —
-  the launch-security checklist requires abuse-path tests for user-facing apps.
-- **Deterministic.** No real clock, network, or randomness — inject them. A seeded RNG or a fixed
-  clock makes a flaky test impossible. Flaky = broken; fix or quarantine, never ignore.
-- **Error codes, not strings.** Switch assertions on stable codes (`standards/error-codes.md`), not
-  on message text.
-
-## Coverage — a floor, not a goal
-
-Aim for meaningful coverage of branches and failure modes, not a vanity percent. 100% line coverage
-with no failure-path assertions is weaker than 70% that exercises every error branch. Untested code
-on a critical path (auth, money, data integrity) is a defect regardless of the overall number.
-
-## Structural / guardrail tests
-
-Some invariants are not example-based — "every module's public API is re-exported", "every error
-code is unique", "the registry and the routes agree". Encode these as **guardrail tests** that fail
-CI when two sources of truth drift (`standards/guardrail-tests.md`).
-
-## When tests are deferred
-
-Under `test-ready-deferred` (or any unit of work shipped without tests), the absence is a **recorded
-decision**, not a silent gap: open an ADR stating why and the conditions for backfill
-(`codex/decisions/`). Keep the code test-ready meanwhile — pure logic, injected dependencies, small units —
-so tests drop in later without a rewrite.
-
-## Definition of "tested" (feeds Definition of Done)
-
-A change is tested when: the new/changed behavior has assertions at the right pyramid level · failure
-paths are covered · the suite is green on fresh context · and (user-facing) the launch checklist's
-abuse-path tests exist. The independent verifier (`rules/30-verification.md`) runs the real suite and
-quotes real output — it does not take "tests pass" on trust.
+---
+updated: 2026-05-31
+status: canonical
+description: "The project-wide testing approach: the pyramid, what to test at each level, the active policy, and what 'tested' means."
+---
+
+# Standards — testing strategy
+
+The per-stack **policy** (`tdd-mandatory | test-ready-deferred | none`) says *whether* you write
+tests now (`stack/`). This standard says *how* you test when you do — so "add tests" is never an
+open question.
+
+## The pyramid (most tests cheap, few tests broad)
+
+| Level | Tests | Speed | Use for |
+|---|---|---|---|
+| **Unit** | pure functions, domain/engine logic, reducers, validators | ms, no I/O | the bulk; every branch of business logic |
+| **Integration** | a module against its real boundaries (DB, queue, an adapter) | seconds | data access, server actions, wiring |
+| **E2E / contract** | a user-visible flow or a published API contract | slow | a few critical happy paths + key failure paths |
+
+Push logic **down** the pyramid: keep the domain layer pure (`standards/architecture.md`) so most
+behavior is unit-testable without spinning up I/O.
+
+## What a good test asserts
+
+- **Behavior, not implementation.** Assert observable output/effect for an input, not internal calls.
+  A refactor that preserves behavior must not break the test.
+- **One reason to fail.** Each test pins one behavior; the name states it (`returns 409 when the
+  slot is already taken`).
+- **Failure paths first-class.** Test the error/empty/forbidden branches, not just the happy path —
+  the launch-security checklist requires abuse-path tests for user-facing apps.
+- **Deterministic.** No real clock, network, or randomness — inject them. A seeded RNG or a fixed
+  clock makes a flaky test impossible. Flaky = broken; fix or quarantine, never ignore.
+- **Error codes, not strings.** Switch assertions on stable codes (`standards/error-codes.md`), not
+  on message text.
+
+## Coverage — a floor, not a goal
+
+Aim for meaningful coverage of branches and failure modes, not a vanity percent. 100% line coverage
+with no failure-path assertions is weaker than 70% that exercises every error branch. Untested code
+on a critical path (auth, money, data integrity) is a defect regardless of the overall number.
+
+## Structural / guardrail tests
+
+Some invariants are not example-based — "every module's public API is re-exported", "every error
+code is unique", "the registry and the routes agree". Encode these as **guardrail tests** that fail
+CI when two sources of truth drift (`standards/guardrail-tests.md`).
+
+## When tests are deferred
+
+Under `test-ready-deferred` (or any unit of work shipped without tests), the absence is a **recorded
+decision**, not a silent gap: open an ADR stating why and the conditions for backfill
+(`codex/decisions/`). Keep the code test-ready meanwhile — pure logic, injected dependencies, small units —
+so tests drop in later without a rewrite.
+
+## Definition of "tested" (feeds Definition of Done)
+
+A change is tested when: the new/changed behavior has assertions at the right pyramid level · failure
+paths are covered · the suite is green on fresh context · and (user-facing) the launch checklist's
+abuse-path tests exist. The independent verifier (`rules/30-verification.md`) runs the real suite and
+quotes real output — it does not take "tests pass" on trust.

package/.agents/standards/typescript.md

@@ -1,19 +1,19 @@
----
-updated: 2026-05-31
-status: canonical
-description: 'TypeScript specifics: strict mode, no any, type-safety expectations.'
----
-
-# Standards — TypeScript
-
-- **`strict: true`.** No implicit `any`. Prefer `unknown` over `any` at boundaries, then narrow.
-- **No non-null `!`** except where provably safe with a comment. Prefer guards.
-- **Types over interfaces** for unions/utility; `interface` for extendable object shapes — pick one
-  per project and stay consistent.
-- **Discriminated unions** for state; avoid boolean-flag soup.
-- **`const` by default**; `let` only when reassigned; never `var`.
-- **No default exports** for modules with logic (named exports aid refactor + grep). Components MAY
-  use default export if the framework expects it.
-- **Async:** always `await` or explicitly `void` a promise; no floating promises.
-- **Validation at boundaries** with a schema lib (zod/valibot). Internal code trusts validated types.
-- **Errors** carry a code (`error-codes.md`); never throw strings.
+---
+updated: 2026-05-31
+status: canonical
+description: 'TypeScript specifics: strict mode, no any, type-safety expectations.'
+---
+
+# Standards — TypeScript
+
+- **`strict: true`.** No implicit `any`. Prefer `unknown` over `any` at boundaries, then narrow.
+- **No non-null `!`** except where provably safe with a comment. Prefer guards.
+- **Types over interfaces** for unions/utility; `interface` for extendable object shapes — pick one
+  per project and stay consistent.
+- **Discriminated unions** for state; avoid boolean-flag soup.
+- **`const` by default**; `let` only when reassigned; never `var`.
+- **No default exports** for modules with logic (named exports aid refactor + grep). Components MAY
+  use default export if the framework expects it.
+- **Async:** always `await` or explicitly `void` a promise; no floating promises.
+- **Validation at boundaries** with a schema lib (zod/valibot). Internal code trusts validated types.
+- **Errors** carry a code (`error-codes.md`); never throw strings.

package/.agents/standards/writing.md

@@ -1,58 +1,58 @@
----
-updated: 2026-05-31
-status: canonical
-description: How to write agent-facing docs so they are high-signal and versioned.
----
-
-# Standards — writing docs
-
-How to write the Markdown agents read (rules, standards, agents, skills, commands, ADRs). Goal: an
-agent finds the right file and the right line fast. High-signal docs are part of code quality
-(`rules/35-context-economy.md`).
-
-## Lead with purpose
-
-The first line after the H1 is one crisp sentence: **what this file is + when to read it.** The
-per-folder `INDEX.md` generator lifts this as the blurb — a vague lead ("Always-on.") makes a useless
-index entry. Files that carry frontmatter may set a `description:` field, which the generator prefers.
-
-## Voice
-
-- Terse, technical, active voice. Cut filler, hedging, throat-clearing.
-- Address the agent directly ("do X", not "one should do X").
-- Match the register of the surrounding docs.
-
-## Structure
-
-- **One topic per file.** If it grows a second concern, split it (`rules/35`).
-- **Tables and lists for enumerations**; prose only for reasoning a reader must follow.
-- **H1 = `Area — topic`** (e.g. `Standards — clean code`); sections scannable by heading.
-- **Link, don't inline.** Point to the canonical file; never paste a catalog or long procedure into
-  an entry file. When you move detail out, leave a one-line pointer behind.
-
-## Versioning
-
-Git holds full history; a visible stamp answers "is this current?" at a glance.
-
-- Canonical docs (standards, ADRs, long-lived references) carry frontmatter `updated: YYYY-MM-DD`,
-  and `status:` (`draft` | `canonical` | `deprecated`) where a lifecycle matters.
-- **Bump `updated` in the same commit as any change to the doc's meaning** — this extends the
-  doc-sync rule (`rules/00-always.md`): behaviour and its doc move together, and the stamp records when.
-- A `status: deprecated` doc names its replacement (`superseded-by:` or an inline pointer); never
-  delete silently. ADRs already follow this (`codex/decisions/`).
-- `updated` with no `description:` does not change a file's INDEX blurb (the generator falls back to
-  the H1 + first line), so stamping is safe to add incrementally.
-
-## Do / don't
-
-- ✅ `# 30 — Verification` → "The agent that writes code cannot mark it done. ..." (lead states what + why).
-- ❌ Restating the heading, or opening with backstory before the point.
-- ✅ A five-row table of limits. ❌ The same limits as five paragraphs.
-- ✅ "See `standards/clean-code.md`." ❌ Copying its content into three files.
-
-## Before you commit a doc
-
-- The lead sentence works as a standalone INDEX blurb.
-- No duplicated content that will drift — one canonical home, others point to it.
-- `updated` bumped if the meaning changed.
-- Regenerate indexes: `grimoire index` (CI runs `--check`).
+---
+updated: 2026-05-31
+status: canonical
+description: How to write agent-facing docs so they are high-signal and versioned.
+---
+
+# Standards — writing docs
+
+How to write the Markdown agents read (rules, standards, agents, skills, commands, ADRs). Goal: an
+agent finds the right file and the right line fast. High-signal docs are part of code quality
+(`rules/35-context-economy.md`).
+
+## Lead with purpose
+
+The first line after the H1 is one crisp sentence: **what this file is + when to read it.** The
+per-folder `INDEX.md` generator lifts this as the blurb — a vague lead ("Always-on.") makes a useless
+index entry. Files that carry frontmatter may set a `description:` field, which the generator prefers.
+
+## Voice
+
+- Terse, technical, active voice. Cut filler, hedging, throat-clearing.
+- Address the agent directly ("do X", not "one should do X").
+- Match the register of the surrounding docs.
+
+## Structure
+
+- **One topic per file.** If it grows a second concern, split it (`rules/35`).
+- **Tables and lists for enumerations**; prose only for reasoning a reader must follow.
+- **H1 = `Area — topic`** (e.g. `Standards — clean code`); sections scannable by heading.
+- **Link, don't inline.** Point to the canonical file; never paste a catalog or long procedure into
+  an entry file. When you move detail out, leave a one-line pointer behind.
+
+## Versioning
+
+Git holds full history; a visible stamp answers "is this current?" at a glance.
+
+- Canonical docs (standards, ADRs, long-lived references) carry frontmatter `updated: YYYY-MM-DD`,
+  and `status:` (`draft` | `canonical` | `deprecated`) where a lifecycle matters.
+- **Bump `updated` in the same commit as any change to the doc's meaning** — this extends the
+  doc-sync rule (`rules/00-always.md`): behaviour and its doc move together, and the stamp records when.
+- A `status: deprecated` doc names its replacement (`superseded-by:` or an inline pointer); never
+  delete silently. ADRs already follow this (`codex/decisions/`).
+- `updated` with no `description:` does not change a file's INDEX blurb (the generator falls back to
+  the H1 + first line), so stamping is safe to add incrementally.
+
+## Do / don't
+
+- ✅ `# 30 — Verification` → "The agent that writes code cannot mark it done. ..." (lead states what + why).
+- ❌ Restating the heading, or opening with backstory before the point.
+- ✅ A five-row table of limits. ❌ The same limits as five paragraphs.
+- ✅ "See `standards/clean-code.md`." ❌ Copying its content into three files.
+
+## Before you commit a doc
+
+- The lead sentence works as a standalone INDEX blurb.
+- No duplicated content that will drift — one canonical home, others point to it.
+- `updated` bumped if the meaning changed.
+- Regenerate indexes: `grimoire index` (CI runs `--check`).

package/.agents/tooling.json

@@ -1,19 +1,19 @@
-{
-  "plugins": [
-    { "name": "superpowers", "marketplace": "claude-plugins-official", "scope": "user" },
-    { "name": "skill-creator", "marketplace": "claude-plugins-official", "scope": "user" },
-    { "name": "ecc", "marketplace": "ecc", "scope": "user" },
-    { "name": "ui-ux-pro-max", "marketplace": "ui-ux-pro-max-skill", "scope": "user" },
-    { "name": "andrej-karpathy-skills", "marketplace": "karpathy-skills", "scope": "user" },
-    { "name": "pordee", "marketplace": "pordee", "scope": "user" },
-    { "name": "caveman", "marketplace": "caveman", "scope": "user" }
-  ],
-  "skills": [
-    { "name": "mattpocock", "install": "npx skills@latest add mattpocock/skills", "setup": "/setup-matt-pocock-skills", "source": "https://github.com/mattpocock/skills", "scope": "user" },
-    { "name": "find-skills", "vendored": ".agents/skills/find-skills", "scope": "project" }
-  ],
-  "mcp": [
-    { "name": "playwright", "server": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } },
-    { "name": "stitch", "server": { "type": "http", "url": "https://stitch.googleapis.com/mcp", "headers": { "X-Goog-Api-Key": "${STITCH_API_KEY}" } }, "note": "Google Stitch — HTTP MCP; generate the key in Stitch Settings, set STITCH_API_KEY" }
-  ]
-}
+{
+  "plugins": [
+    { "name": "superpowers", "marketplace": "claude-plugins-official", "scope": "user" },
+    { "name": "skill-creator", "marketplace": "claude-plugins-official", "scope": "user" },
+    { "name": "ecc", "marketplace": "ecc", "scope": "user" },
+    { "name": "ui-ux-pro-max", "marketplace": "ui-ux-pro-max-skill", "scope": "user" },
+    { "name": "andrej-karpathy-skills", "marketplace": "karpathy-skills", "scope": "user" },
+    { "name": "pordee", "marketplace": "pordee", "scope": "user" },
+    { "name": "caveman", "marketplace": "caveman", "scope": "user" }
+  ],
+  "skills": [
+    { "name": "mattpocock", "install": "npx skills@latest add mattpocock/skills", "setup": "/setup-matt-pocock-skills", "source": "https://github.com/mattpocock/skills", "scope": "user" },
+    { "name": "find-skills", "vendored": ".agents/skills/find-skills", "scope": "project" }
+  ],
+  "mcp": [
+    { "name": "playwright", "server": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } },
+    { "name": "stitch", "server": { "type": "http", "url": "https://stitch.googleapis.com/mcp", "headers": { "X-Goog-Api-Key": "${STITCH_API_KEY}" } }, "note": "Google Stitch — HTTP MCP; generate the key in Stitch Settings, set STITCH_API_KEY" }
+  ]
+}

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,139 +1,139 @@
-# Grimoire
-
-A single, version-controlled **AI-agent operating system** you pull into every project.
-One command gives a new repo a complete, orderly set of working rules, coding standards,
-subagents, skills, commands, tech-stack defaults, and a self-bias-free verification protocol.
-
-The core is **tool-agnostic** (`.agents/AGENTS.md`) so any agent can read it; Claude Code
-binding sits on top. Template updates propagate to old projects without clobbering their
-per-project customization.
-
-> **Full structure & component reference:** [`.agents/NAVIGATOR.md`](.agents/NAVIGATOR.md) — what Grimoire
-> creates, what each CLI command does, the three lifecycles, and the seed/migration model.
-
-## What is in `.agents/`
-
-| Path | Holds |
-|---|---|
-| `AGENTS.md` | entry contract + load-order index |
-| `rules/` | always-on working process + protocols (numbered) |
-| `standards/` | coding standards (general + per-language) |
-| `stack/` | tech-stack presets (web-app / desktop / library) |
-| `agents/` | subagents — e.g. the independent `verifier` |
-| `commands/` | slash commands (`verify`, `checkpoint`, `grimoire`) |
-| `skills/` | reusable, re-runnable workflows |
-| `local/` | per-project overrides; `sync` never touches |
-
-`init` also seeds **`codex/`** at the **repo root** (not under `.agents/`) — the project's knowledge
-base: `domain/`, `requirements/`, `decisions/`, `evidence/`, `resources/`, `reference/`, `runbooks/`.
-It is read-first for any domain/feature work (start at `codex/INDEX.md`), project-owned, and lives
-outside every managed path, so `grimoire sync` is sync-safe and never touches it.
-
-## Quick start
-
-Published on npm as [`the-grimoire-cli`](https://www.npmjs.com/package/the-grimoire-cli); the command
-it installs is `grimoire`.
-
-```sh
-# New project — scaffold .agents/ + pointers
-npx the-grimoire-cli init
-
-# Existing project — pull latest template (managed paths only; codex/ journal/ local/ untouched)
-npx the-grimoire-cli sync
-```
-
-Install it globally for the `grimoire` command everywhere, and update in place:
-
-```sh
-npm i -g the-grimoire-cli       # install
-grimoire init                   # or: grimoire sync
-npm update -g the-grimoire-cli  # pull the latest template release
-grimoire --version              # release version + build sha
-```
-
-Prefer pinning straight to the repo? `npx github:nuttchanon/the-grimoire init` works too, no npm needed.
-
-## Two-layer model
-
-- **Managed base** — the template owns it; `grimoire sync` overwrites it. Listed in
-  `.agents/grimoire.manifest`.
-- **Local overrides** (`local/`, at the repo root) — the project owns it; sync never touches it. To change a
-  base rule, **do not edit the base** — add an override in `local/`. That is what keeps sync
-  conflict-free.
-
-Precedence: base loads first, `local/` loads last and **wins**.
-
-## Session-state — 3 homes
-
-| Layer | Answers | Home | Git |
-|---|---|---|---|
-| **NOW** | "what am I doing right now?" | `journal/session/` | gitignored |
-| **KNOWLEDGE** | "what do we already know?" | `journal/memory/` | tracked |
-| **QUEUE** | "what work is pending?" | `journal/backlog/` | tracked |
-
-## Verification
-
-The agent that writes code cannot mark it done. After a change, the main thread spawns the
-**verifier** subagent on fresh context (requirements + diff + checklist only — not the
-implementer's reasoning). It refutes by default, runs the real `verify` script, and quotes real
-output. Definition of Done = tests green **AND** verifier `pass` **AND** checklist complete.
-
-## Tooling — skills, plugins & MCP
-
-`.agents/tooling.json` declares the plugins, skills, and MCP servers a project relies on, and
-`.agents/skills/catalog.md` maps `task → capability` (primary + alternates). The always-on rule
-`rules/15-skills.md` makes consulting the catalog reflexive; anything uncovered is found via the
-vendored `find-skills` skill.
-
-```sh
-# enable required plugins / MCP / skills (prints a plan; nothing is written)
-npx github:nuttchanon/the-grimoire bootstrap
-
-# actually apply (additive, backs up ~/.claude/settings.json, never disables anything)
-npx github:nuttchanon/the-grimoire bootstrap --apply
-```
-
-`init` runs `bootstrap` in dry-run automatically and mirrors `find-skills` into `.claude/skills/`.
-The mattpocock engineering skills install separately via `npx skills@latest add mattpocock/skills`
-followed by `/setup-matt-pocock-skills`. Editing `~/.claude/settings.json` is a machine-wide change —
-bootstrap defaults to dry-run, backs up first, and only adds.
-
-A project declares its **own** plugins / MCP servers (Linear, Sentry, Supabase, Figma, …) in
-`local/tooling.json` — same shape as the base. `bootstrap` merges it **additively** (base
-wins on conflict, local adds new entries), so project integrations live in `local/` instead of
-bloating the managed base.
-
-## Navigation — generated per-folder indexes
-
-Each managed folder carries an `INDEX.md`: a one-line-per-file table generated from each file's
-frontmatter or H1. Agents read it before opening files — two-level progressive disclosure
-(`AGENTS.md` map → folder `INDEX.md` → file) that keeps context lean (`rules/35-context-economy.md`).
-It is generated, never hand-edited:
-
-```sh
-# regenerate every INDEX.md (runs automatically inside init + sync)
-npx github:nuttchanon/the-grimoire index
-
-# CI guard: fail if any INDEX.md is stale, or a tooling.json MCP is undocumented in the catalog
-npx github:nuttchanon/the-grimoire index --check
-```
-
-`init`/`sync` generate an `INDEX.md` for both the managed folders and your `local/` folders.
-
-## Health check — doctor
-
-`grimoire doctor` verifies a project is correctly wired: `CLAUDE.md` imports, skill frontmatter
-(`name:`/`description:` so mirrored skills are discoverable), INDEX/catalog drift, unfilled
-`AGENTS.local.md` placeholders, and oversized entry files. One line per
-finding; exits non-zero on any error, so it drops straight into CI:
-
-```sh
-npx github:nuttchanon/the-grimoire doctor
-```
-
-## Decisions — ADRs
-
-`init` seeds `codex/decisions/` (a template + README) into the project; it is project-owned and
-survives `sync`. ADRs record lasting choices, carry an `updates-confirmed-values` flag (ground-truth
-values change with their ADR in the same PR), and a missing test suite must be a recorded ADR rather
-than a silent gap (`rules/00-always.md`).
+# Grimoire
+
+A single, version-controlled **AI-agent operating system** you pull into every project.
+One command gives a new repo a complete, orderly set of working rules, coding standards,
+subagents, skills, commands, tech-stack defaults, and a self-bias-free verification protocol.
+
+The core is **tool-agnostic** (`.agents/AGENTS.md`) so any agent can read it; Claude Code
+binding sits on top. Template updates propagate to old projects without clobbering their
+per-project customization.
+
+> **Full structure & component reference:** [`.agents/NAVIGATOR.md`](.agents/NAVIGATOR.md) — what Grimoire
+> creates, what each CLI command does, the three lifecycles, and the seed/migration model.
+
+## What is in `.agents/`
+
+| Path | Holds |
+|---|---|
+| `AGENTS.md` | entry contract + load-order index |
+| `rules/` | always-on working process + protocols (numbered) |
+| `standards/` | coding standards (general + per-language) |
+| `stack/` | tech-stack presets (web-app / desktop / library) |
+| `agents/` | subagents — e.g. the independent `verifier` |
+| `commands/` | slash commands (`verify`, `checkpoint`, `grimoire`) |
+| `skills/` | reusable, re-runnable workflows |
+| `local/` | per-project overrides; `sync` never touches |
+
+`init` also seeds **`codex/`** at the **repo root** (not under `.agents/`) — the project's knowledge
+base: `domain/`, `requirements/`, `decisions/`, `evidence/`, `resources/`, `reference/`, `runbooks/`.
+It is read-first for any domain/feature work (start at `codex/INDEX.md`), project-owned, and lives
+outside every managed path, so `grimoire sync` is sync-safe and never touches it.
+
+## Quick start
+
+Published on npm as [`the-grimoire-cli`](https://www.npmjs.com/package/the-grimoire-cli); the command
+it installs is `grimoire`.
+
+```sh
+# New project — scaffold .agents/ + pointers
+npx the-grimoire-cli init
+
+# Existing project — pull latest template (managed paths only; codex/ journal/ local/ untouched)
+npx the-grimoire-cli sync
+```
+
+Install it globally for the `grimoire` command everywhere, and update in place:
+
+```sh
+npm i -g the-grimoire-cli       # install
+grimoire init                   # or: grimoire sync
+npm update -g the-grimoire-cli  # pull the latest template release
+grimoire --version              # release version + build sha
+```
+
+Prefer pinning straight to the repo? `npx github:nuttchanon/the-grimoire init` works too, no npm needed.
+
+## Two-layer model
+
+- **Managed base** — the template owns it; `grimoire sync` overwrites it. Listed in
+  `.agents/grimoire.manifest`.
+- **Local overrides** (`local/`, at the repo root) — the project owns it; sync never touches it. To change a
+  base rule, **do not edit the base** — add an override in `local/`. That is what keeps sync
+  conflict-free.
+
+Precedence: base loads first, `local/` loads last and **wins**.
+
+## Session-state — 3 homes
+
+| Layer | Answers | Home | Git |
+|---|---|---|---|
+| **NOW** | "what am I doing right now?" | `journal/session/` | gitignored |
+| **KNOWLEDGE** | "what do we already know?" | `journal/memory/` | tracked |
+| **QUEUE** | "what work is pending?" | `journal/backlog/` | tracked |
+
+## Verification
+
+The agent that writes code cannot mark it done. After a change, the main thread spawns the
+**verifier** subagent on fresh context (requirements + diff + checklist only — not the
+implementer's reasoning). It refutes by default, runs the real `verify` script, and quotes real
+output. Definition of Done = tests green **AND** verifier `pass` **AND** checklist complete.
+
+## Tooling — skills, plugins & MCP
+
+`.agents/tooling.json` declares the plugins, skills, and MCP servers a project relies on, and
+`.agents/skills/catalog.md` maps `task → capability` (primary + alternates). The always-on rule
+`rules/15-skills.md` makes consulting the catalog reflexive; anything uncovered is found via the
+vendored `find-skills` skill.
+
+```sh
+# enable required plugins / MCP / skills (prints a plan; nothing is written)
+npx github:nuttchanon/the-grimoire bootstrap
+
+# actually apply (additive, backs up ~/.claude/settings.json, never disables anything)
+npx github:nuttchanon/the-grimoire bootstrap --apply
+```
+
+`init` runs `bootstrap` in dry-run automatically and mirrors `find-skills` into `.claude/skills/`.
+The mattpocock engineering skills install separately via `npx skills@latest add mattpocock/skills`
+followed by `/setup-matt-pocock-skills`. Editing `~/.claude/settings.json` is a machine-wide change —
+bootstrap defaults to dry-run, backs up first, and only adds.
+
+A project declares its **own** plugins / MCP servers (Linear, Sentry, Supabase, Figma, …) in
+`local/tooling.json` — same shape as the base. `bootstrap` merges it **additively** (base
+wins on conflict, local adds new entries), so project integrations live in `local/` instead of
+bloating the managed base.
+
+## Navigation — generated per-folder indexes
+
+Each managed folder carries an `INDEX.md`: a one-line-per-file table generated from each file's
+frontmatter or H1. Agents read it before opening files — two-level progressive disclosure
+(`AGENTS.md` map → folder `INDEX.md` → file) that keeps context lean (`rules/35-context-economy.md`).
+It is generated, never hand-edited:
+
+```sh
+# regenerate every INDEX.md (runs automatically inside init + sync)
+npx github:nuttchanon/the-grimoire index
+
+# CI guard: fail if any INDEX.md is stale, or a tooling.json MCP is undocumented in the catalog
+npx github:nuttchanon/the-grimoire index --check
+```
+
+`init`/`sync` generate an `INDEX.md` for both the managed folders and your `local/` folders.
+
+## Health check — doctor
+
+`grimoire doctor` verifies a project is correctly wired: `CLAUDE.md` imports, skill frontmatter
+(`name:`/`description:` so mirrored skills are discoverable), INDEX/catalog drift, unfilled
+`AGENTS.local.md` placeholders, and oversized entry files. One line per
+finding; exits non-zero on any error, so it drops straight into CI:
+
+```sh
+npx github:nuttchanon/the-grimoire doctor
+```
+
+## Decisions — ADRs
+
+`init` seeds `codex/decisions/` (a template + README) into the project; it is project-owned and
+survives `sync`. ADRs record lasting choices, carry an `updates-confirmed-values` flag (ground-truth
+values change with their ADR in the same PR), and a missing test suite must be a recorded ADR rather
+than a silent gap (`rules/00-always.md`).