the-grimoire-cli 0.3.2

package/.agents/standards/observability.md

@@ -0,0 +1,35 @@
+---
+updated: 2026-05-31
+status: canonical
+description: Production logging, metrics, and tracing lessons from real data/sync tools.
+---
+
+# Standards — observability
+
+Lessons from production data/sync tools. The goal: an operator can self-diagnose a live issue from
+logs alone, without attaching a debugger.
+
+## Make the diagnosable facts visible at INFO
+
+- When a query/request returns **zero rows or an empty result on a path that usually has data**, log
+  enough to tell "correct empty" from "wrong input" — at **INFO**, not DEBUG. Operators rarely have
+  debug mode on in production.
+- For generated queries, log the **rendered parameters** (the actual values sent), not just the
+  template. A silent 0-row from a bad default (locale, era, timezone, unit) is otherwise invisible.
+
+## No silent empty results
+
+- A path that returns nothing where data was expected must surface *why* (filtered, unauthorized,
+  no-match) — never an unexplained empty array.
+
+## Per-source / per-locale overrides are first-class
+
+- Defaults that vary by deployment (date era, timezone, encoding, ID format, DB dialect) must be
+  **documented in onboarding** and overridable per source. Bake the override point in; don't assume
+  one global default fits every site.
+
+## Logging hygiene
+
+- Never log secrets, tokens, or full PII; scrub before logging (`rules/50-security.md`).
+- Structured logs (level + code + context) over free-text — pairs with the error-code catalog
+  (`standards/error-codes.md`).

package/.agents/standards/release-versioning.md

@@ -0,0 +1,53 @@
+---
+updated: 2026-05-31
+status: canonical
+description: "Versioning, changelog, and release discipline across app and library profiles — what ships, how it's tagged, how it's recorded."
+---
+
+# Standards — release & versioning
+
+Every project needs an answer to "what version is live, and what changed since the last one." This
+standard gives the default; the active `stack/` profile refines the tooling.
+
+## Versioning scheme
+
+- **Libraries** (`stack/library.md`): strict **SemVer** — major = breaking API, minor = added API,
+  patch = fix. Public API changes drive the bump. Use **changesets** so each PR declares its bump.
+- **Apps** (web-app / desktop): SemVer-ish or CalVer — pick one and stay consistent. The number is
+  for humans tracing "which build has this fix," so what matters is that a tag exists per release and
+  maps to a commit. Tag the release commit (`vX.Y.Z`); the tag is the source of truth for "what
+  shipped."
+
+## Changelog — required, generated from commits
+
+- Keep a `CHANGELOG.md` (Keep-a-Changelog style: grouped Added / Changed / Fixed / Removed /
+  Security under each version + date).
+- It is **derived from Conventional Commits** (`rules/60-commit-style.md`): `feat:` → Added,
+  `fix:` → Fixed, `feat!:`/`BREAKING CHANGE:` → a major bump + a Changed/Removed entry. A tool
+  (changesets, release-please, or `git-cliff`) generates it; do not hand-curate from memory.
+- Cite requirement and ADR ids where relevant (`implements REQ-…`, `see ADR 00NN`) so a release
+  links back to *why* (`standards/requirements.md`).
+
+## Release checklist (gate before tagging)
+
+1. Verifier `pass` on fresh context; full suite green (`rules/30-verification.md`).
+2. For a user-facing app: the launch-security checklist passes
+   (`standards/launch-security-checklist.md`).
+3. `CHANGELOG.md` updated for this version; version bumped in the manifest (`package.json` etc.).
+4. Any `updates-confirmed-values: yes` ADR in this range has its confirmed-values table updated.
+5. Docs synced (`rules/00-always.md`) — no behavior shipped with stale docs.
+6. Tag the release commit; push the tag; publish (library: registry; app: deploy).
+
+## Deploy & rollback
+
+- The deploy target and any region/config pinning that the code depends on belong in the project's
+  `local/` notes or an ADR (not hardcoded, not tribal knowledge).
+- Every release must be **rollback-able**: know the previous good tag and the procedure to redeploy
+  it. A migration that can't roll back is itself a decision — record it in an ADR with the
+  forward-fix plan.
+
+## Pre-release / staged rollout
+
+Feature flags or env gates (same mechanism as HOTFIX, `rules/20-modes.md`) let a change ship dark and
+ramp. A flag is debt: record its name, the ramp/cleanup condition, and remove it once fully rolled
+out — a stale flag is a silent fork in behavior.

package/.agents/standards/requirements.md

@@ -0,0 +1,75 @@
+---
+updated: 2026-05-31
+status: canonical
+description: "How requirements are captured, identified, versioned, and traced — base requirements plus addons and change requests."
+---
+
+# Standards — requirements
+
+A project's requirements are a **tracked, referenceable artifact**, not scattered chat history. They
+live under `codex/requirements/` (project-owned; `grimoire sync` never touches them — seeded by
+`grimoire init` from `templates/codex/`). Every requirement has a stable ID so code, tests,
+commits, ADRs, and change requests can cite it.
+
+## The three documents
+
+| File | Holds | When it changes |
+|---|---|---|
+| `codex/requirements/base.md` | The **baseline** — the agreed requirements at the current accepted state | Only via an applied change request (CR) |
+| `codex/requirements/addons/<id>-<slug>.md` | A self-contained **addon** — a new feature/capability layered on the base | New file per feature; merged into base when it ships |
+| `codex/requirements/changes/<id>-<slug>.md` | A **change request (CR)** — a modification to an existing requirement | New file per change; records old → new |
+
+Base = the source of truth for "what the system must do *now*." Addons and CRs are the **audit
+trail** of how it got there. Nothing edits a requirement silently — the diff always exists as a CR
+or an addon.
+
+## Requirement IDs — stable and traceable
+
+- Format: `REQ-<area>-<NNN>` — e.g. `REQ-AUTH-001`, `REQ-ROSTER-014`. Area is a short uppercase
+  domain tag; number is zero-padded, sequential per area, **never reused or renumbered**.
+- A requirement keeps its ID for life. If it is removed, mark it `status: withdrawn` — do not delete
+  the row (the ID must never point at something else later).
+- Cite the ID everywhere the requirement is realized: commit body (`implements REQ-AUTH-001`), test
+  name/describe block, the ADR that decided *how*, and the CR that last changed it. An auditor reads
+  one ID and finds the whole chain.
+
+## Each requirement row carries
+
+`id` · `statement` (one testable "the system must …" sentence) · `rationale` (why) ·
+`acceptance` (how we verify it — links to the test or the manual check) · `status`
+(`proposed | accepted | implemented | withdrawn`) · `priority` (`must | should | could`) ·
+`source` (who asked / which CR or addon introduced it).
+
+A requirement that cannot be phrased as a **testable** statement is not done being written — sharpen
+it until its acceptance criterion is observable.
+
+## Change flow (base ← addon / CR)
+
+1. **New feature** → write an **addon** (`addons/<id>-<slug>.md`) with its own `REQ-…` rows. It is
+   reviewable on its own and references the base requirements it depends on or extends.
+2. **Modify an existing requirement** → write a **CR** (`changes/<id>-<slug>.md`): name the affected
+   `REQ-…` id(s), give **old statement → new statement**, the reason, and the impact (code, tests,
+   ADRs, confirmed-values).
+3. **On merge**, fold the addon's / CR's outcome into `base.md` (update the rows, bump the base
+   `version`), and leave the addon/CR file in place as history. The base always reflects *now*; the
+   addon/CR explains *the change*.
+4. If the change alters a **ground-truth value** (error code, permission key, enum, channel name),
+   the linked ADR sets `updates-confirmed-values: yes` and the confirmed-values table updates in the
+   **same PR** (`codex/decisions/` + `standards/error-codes.md`).
+
+## Versioning the base
+
+`base.md` carries a `version` (semantic-ish: bump minor for an added requirement, patch for a
+clarification, major for a breaking removal/redefinition) and a `changelog` table listing each
+applied addon/CR by id and date. Diffing two base versions = the requirements delta between releases.
+
+## Relationship to the rest of the contract
+
+- **Planning** (`rules/10-working-process.md`): the task contract's *goal* and *acceptance criteria*
+  should cite the `REQ-…` ids it satisfies.
+- **Verification** (`rules/30-verification.md`): the verifier checks output against the cited
+  requirement's acceptance criterion — "done" means that criterion is met.
+- **Decisions** (`codex/decisions/`): requirements say *what*; ADRs say *how* and *why*. A CR that needs a
+  design choice spawns an ADR; the ADR's `supersedes` and the CR cross-link.
+- **PRD/spec skills** (`skills/catalog.md`: `to-prd`, `brainstorming`) produce the prose; this
+  standard is where that prose lands as IDed, versioned rows.

package/.agents/standards/security-scanners.md

@@ -0,0 +1,42 @@
+---
+updated: 2026-05-31
+status: canonical
+description: SAST scanners by language and how to wire them into CI to catch exploitable bugs.
+---
+
+# Security scanners (SAST)
+
+Linters find what is ugly; **SAST** finds what is exploitable — SQLi, XSS, RCE, path traversal,
+hardcoded secrets, weak crypto. Pick by language, run in CI, fail on High/Critical. OSS unless noted.
+
+| Scanner | Scope | Use when |
+|---|---|---|
+| **Semgrep** | pattern-based, 30+ languages | default for any project (incl. TS/JS) |
+| **njsscan** | JS / Node / React Native | Next.js, Electron, React Native |
+| **CodeQL** | semantic taint-tracking, GitHub-native | any repo on GitHub (free for public) — enable Code Scanning |
+| **Bandit** | Python | any Python service |
+| **Brakeman** | Ruby on Rails | Rails apps |
+| **gosec** | Go | Go services |
+| **Snyk Code** | AI-assisted, inline fixes (freemium) | optional, on top of the above |
+
+## For this org's stacks (TypeScript · Next.js · Electron)
+
+Run **Semgrep + njsscan** in CI and enable **CodeQL** Code Scanning on GitHub. Add **Bandit** if a
+Python service appears.
+
+## CI wiring
+
+Drop-in workflow: copy `templates/ci/sast.yml` → `.github/workflows/sast.yml` (Semgrep + njsscan;
+CodeQL enabled separately). It fails the build on findings. Per profile:
+
+| Profile | Run |
+|---|---|
+| web-app (Next.js) | Semgrep + njsscan + CodeQL (js/ts) |
+| desktop (Electron) | Semgrep + njsscan + CodeQL |
+| library | Semgrep + the language's native scanner (bandit/gosec/…) if not JS/TS |
+| + any Python service | add Bandit (`bandit -r src -ll`) |
+
+CodeQL: GitHub → Security → Code scanning → enable, or the `github/codeql-action` workflow.
+
+Pre-launch: clear High/Critical and wire the scan into `standards/launch-security-checklist.md`. For
+user-facing, data-collecting apps this is part of Definition of Done (`rules/00-always.md`).

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

@@ -0,0 +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.

package/.agents/standards/typescript.md

@@ -0,0 +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.

package/.agents/standards/writing.md

@@ -0,0 +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`).

package/.agents/tooling.json

@@ -0,0 +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" }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nuttchanon Jantawong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

package/README.md

@@ -0,0 +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`).