the-grimoire-cli 0.3.2 → 0.5.0

package/.agents/AGENTS.md

@@ -1,112 +1,112 @@
-# AGENTS.md — master contract (tool-agnostic)
-
-This is the **canonical entry** for every agent working in this repo. Claude Code reaches it via
-`CLAUDE.md` (`@.agents/AGENTS.md`). Read in the order below — do **not** "read everything" up front.
-
-Keep this file lean (`rules/35-context-economy.md`): tone, hardest rules, the map, pointers — detail
-lives in the files it links.
-
-## Tone
-
-The person you work with is a **Product Builder** — address them directly ("you"), not as a passive
-third party. Talk straight: factual and data-driven, no hype, no flattery, no telling them what they
-want to hear. State trade-offs, risks, and disagreements plainly, with the evidence behind them —
-being right matters more than being agreeable. Stay calm and professional, never emotional or
-defensive. They may not know a given technical detail; explain it when it matters, plainly and
-without condescension. Be terse and technical, and match the surrounding code and the user's
-register. Project-specific tone or any communication mode lives in `local/AGENTS.local.md`.
-
-## Load order
-
-1. **This file** — hardest rules + the map (below).
-2. **`rules/`** — always-on working process. Read `00-always.md` every session.
-3. **`codex/INDEX.md`** — the project's knowledge base (domain, requirements, decisions, evidence,
-   resources, reference, runbooks). Read-on-demand, but **read-first for any domain/feature work**.
-4. **`standards/`** — when writing code, load `general.md` + the per-language file.
-5. **`stack/`** — when scaffolding or configuring, load the active profile.
-6. **`codex/decisions/`** — when a decision's *why* matters.
-7. **`local/`** — per-project customization. Read `local/AGENTS.local.md`, then the matching
-   `local/<area>/` (rules/standards/stack/skills/commands/reference) for any base area you touch;
-   **loads last and wins**.
-
-## The map
-
-| Need | Go to |
-|---|---|
-| System structure / what grimoire creates / CLI behavior / layout & lifecycles | `NAVIGATOR.md` |
-| Project knowledge / domain / evidence / resources / requirements / decisions | `codex/` (start at `codex/INDEX.md`) |
-| Working process, modes, handoff routing | `rules/` |
-| Coding standards, naming, error codes | `standards/` |
-| Requirements (base / addon / change request) | `standards/requirements.md` + `codex/requirements/` |
-| Test strategy, release/versioning, accessibility | `standards/testing-strategy.md` · `standards/release-versioning.md` · `standards/accessibility.md` |
-| Framework / lint / test / CI **starter templates** (copy manually — not auto-seeded) | `stack/` + `templates/ci/` · `templates/lint/` · `templates/tests/` |
-| Independent verification (the verifier) | `rules/30-verification.md` + `agents/verifier.md` |
-| What am I doing right now? | `journal/session/current.md` (NOW) |
-| What do we already know? | `journal/memory/` + `journal/memory/MEMORY.md` (KNOWLEDGE) |
-| What work is pending? | `journal/backlog/` (QUEUE) |
-| Project-specific overrides | `local/` |
-| Project domain reference (big contracts, IPC tables, confirmed values) | `local/reference/` |
-| Keeping entry files lean | `rules/35-context-economy.md` |
-| Presenting to a human (HTML) | `rules/45-presentation.md` + `commands/present.md` |
-
-Inside any managed folder **or `local/` folder**, read its generated `INDEX.md` (one line per file)
-**before** opening files — that is the per-folder resource map (regenerate with `grimoire index`; CI
-runs `--check`). `grimoire doctor` health-checks the whole wiring (exits non-zero on error, for CI).
-
-### Hot keywords (jump straight to the file)
-
-| Keyword | File |
-|---|---|
-| error code / error catalog | `standards/error-codes.md` |
-| verify command / done | active `stack/<profile>.md` + `rules/30-verification.md` |
-| security / auth / secrets | `rules/50-security.md` |
-| code quality / clean code | `standards/clean-code.md` + `rules/05-code-quality.md` |
-| over-engineering / laziness / minimal code / the ladder / `ponytail:` marker | `standards/clean-code.md` (ladder + guardrail) · ADR `docs/adr/0007-adopt-ponytail-laziness-ladder.md` |
-| launch / privacy gate | `standards/launch-security-checklist.md` + `standards/security-scanners.md` |
-| requirement / spec / REQ-id / change request | `standards/requirements.md` + `codex/requirements/` |
-| test strategy / how to test / coverage | `standards/testing-strategy.md` |
-| release / changelog / version / rollback | `standards/release-versioning.md` |
-| accessibility / a11y / WCAG | `standards/accessibility.md` |
-| incident / runbook / on-call / outage | `codex/runbooks/` |
-| CI / pipeline / workflow | `templates/ci/ci.yml` + `templates/ci/sast.yml` |
-| commit format | `rules/60-commit-style.md` |
-| HOTFIX | `rules/20-modes.md` |
-| codex / knowledge base / provenance | `standards/codex.md` + `codex/INDEX.md` |
-| domain / glossary / context | `codex/domain/` |
-| evidence / investigation / decompile / reverse-engineer / provenance | `codex/evidence/` + `standards/codex.md` |
-| decision / ADR / "why" | `codex/decisions/` |
-| which skill / capability | `skills/catalog.md` |
-| writing / editing a contract doc | `standards/writing.md` |
-| credit / attribution / license / external source / adopt a tool | `standards/attribution.md` |
-| knowledge retrieval / search the codebase / code graph | `graphify` (ADR `docs/adr/0006-delegate-retrieval-to-external-tooling.md`) |
-| structure / architecture / navigator / what does grimoire create / layout / lifecycle | `NAVIGATOR.md` |
-
-## Source priority (when sources conflict)
-
-Trust in this order: **live code + committed docs/specs** (current) > **this base template**
-(`rules/ standards/ stack/`) > **`journal/memory/` cards** (may be stale — verify before acting on one).
-A memory never overrides what the code currently says; treat it as a lead, not as truth.
-
-## Hardest rules (full text in `rules/00-always.md`)
-
-- **Verify before done.** Code you wrote is not done until the verifier returns `pass` on fresh
-  context. The author cannot mark their own work done.
-- **Doc-sync same turn.** Behavior change and its doc/memory update ship in the same turn.
-- **Security first.** No hardcoded roles/secrets; validate + authorize on the server; fail closed.
-- **Effort is not a constraint.** Do not scope-cut to save effort. Spawn parallel subagents instead.
-
-## Customization & precedence
-
-Base (this template) loads first; `local/` loads last and **wins**.
-
-**In a consuming project, never edit the managed base** — `.agents/AGENTS.md`, `rules/`,
-`standards/`, `stack/`, `agents/`, `skills/`, `commands/`, `tooling.json`. `grimoire sync`
-overwrites all of them, so edits there are lost. Put **every** customization under root `local/`
-(it is never synced): **override** a base behavior by restating it in `local/` (it wins), or **add**
-a project-only rule/skill/command/standard under the matching `local/<area>/`. Protocol:
-`local/README.md`.
-
-**Project domain docs** that don't fit the lean `AGENTS.md` (a big runtime contract, confirmed-value
-tables, an IPC catalog) live in `local/reference/` — `grimoire index` generates its `INDEX.md` too.
-Run `grimoire doctor` to verify the wiring (imports, skill frontmatter, INDEX drift, placeholders);
-it exits non-zero on error, for CI.
+# AGENTS.md — master contract (tool-agnostic)
+
+This is the **canonical entry** for every agent working in this repo. Claude Code reaches it via
+`CLAUDE.md` (`@.agents/AGENTS.md`). Read in the order below — do **not** "read everything" up front.
+
+Keep this file lean (`rules/35-context-economy.md`): tone, hardest rules, the map, pointers — detail
+lives in the files it links.
+
+## Tone
+
+The person you work with is a **Product Builder** — address them directly ("you"), not as a passive
+third party. Talk straight: factual and data-driven, no hype, no flattery, no telling them what they
+want to hear. State trade-offs, risks, and disagreements plainly, with the evidence behind them —
+being right matters more than being agreeable. Stay calm and professional, never emotional or
+defensive. They may not know a given technical detail; explain it when it matters, plainly and
+without condescension. Be terse and technical, and match the surrounding code and the user's
+register. Project-specific tone or any communication mode lives in `local/AGENTS.local.md`.
+
+## Load order
+
+1. **This file** — hardest rules + the map (below).
+2. **`rules/`** — always-on working process. Read `00-always.md` every session.
+3. **`codex/INDEX.md`** — the project's knowledge base (domain, requirements, decisions, evidence,
+   resources, reference, runbooks). Read-on-demand, but **read-first for any domain/feature work**.
+4. **`standards/`** — when writing code, load `general.md` + the per-language file.
+5. **`stack/`** — when scaffolding or configuring, load the active profile.
+6. **`codex/decisions/`** — when a decision's *why* matters.
+7. **`local/`** — per-project customization. Read `local/AGENTS.local.md`, then the matching
+   `local/<area>/` (rules/standards/stack/skills/commands/reference) for any base area you touch;
+   **loads last and wins**.
+
+## The map
+
+| Need | Go to |
+|---|---|
+| System structure / what grimoire creates / CLI behavior / layout & lifecycles | `NAVIGATOR.md` |
+| Project knowledge / domain / evidence / resources / requirements / decisions | `codex/` (start at `codex/INDEX.md`) |
+| Working process, modes, handoff routing | `rules/` |
+| Coding standards, naming, error codes | `standards/` |
+| Requirements (base / addon / change request) | `standards/requirements.md` + `codex/requirements/` |
+| Test strategy, release/versioning, accessibility | `standards/testing-strategy.md` · `standards/release-versioning.md` · `standards/accessibility.md` |
+| Framework / lint / test / CI **starter templates** (copy manually — not auto-seeded) | `stack/` + `templates/ci/` · `templates/lint/` · `templates/tests/` |
+| Independent verification (the verifier) | `rules/30-verification.md` + `agents/verifier.md` |
+| What am I doing right now? | `journal/session/current.md` (NOW) |
+| What do we already know? | `journal/memory/` + `journal/memory/MEMORY.md` (KNOWLEDGE) |
+| What work is pending? | `journal/backlog/` (QUEUE) |
+| Project-specific overrides | `local/` |
+| Project domain reference (big contracts, IPC tables, confirmed values) | `local/reference/` |
+| Keeping entry files lean | `rules/35-context-economy.md` |
+| Presenting to a human (HTML) | `rules/45-presentation.md` + `commands/present.md` |
+
+Inside any managed folder **or `local/` folder**, read its generated `INDEX.md` (one line per file)
+**before** opening files — that is the per-folder resource map (regenerate with `grimoire index`; CI
+runs `--check`). `grimoire doctor` health-checks the whole wiring (exits non-zero on error, for CI).
+
+### Hot keywords (jump straight to the file)
+
+| Keyword | File |
+|---|---|
+| error code / error catalog | `standards/error-codes.md` |
+| verify command / done | active `stack/<profile>.md` + `rules/30-verification.md` |
+| security / auth / secrets | `rules/50-security.md` |
+| code quality / clean code | `standards/clean-code.md` + `rules/05-code-quality.md` |
+| over-engineering / laziness / minimal code / the ladder / `ponytail:` marker | `standards/clean-code.md` (ladder + guardrail) · ADR `docs/adr/0007-adopt-ponytail-laziness-ladder.md` |
+| launch / privacy gate | `standards/launch-security-checklist.md` + `standards/security-scanners.md` |
+| requirement / spec / REQ-id / change request | `standards/requirements.md` + `codex/requirements/` |
+| test strategy / how to test / coverage | `standards/testing-strategy.md` |
+| release / changelog / version / rollback | `standards/release-versioning.md` |
+| accessibility / a11y / WCAG | `standards/accessibility.md` |
+| incident / runbook / on-call / outage | `codex/runbooks/` |
+| CI / pipeline / workflow | `templates/ci/ci.yml` + `templates/ci/sast.yml` |
+| commit format | `rules/60-commit-style.md` |
+| HOTFIX | `rules/20-modes.md` |
+| codex / knowledge base / provenance | `standards/codex.md` + `codex/INDEX.md` |
+| domain / glossary / context | `codex/domain/` |
+| evidence / investigation / decompile / reverse-engineer / provenance | `codex/evidence/` + `standards/codex.md` |
+| decision / ADR / "why" | `codex/decisions/` |
+| which skill / capability | `skills/catalog.md` |
+| writing / editing a contract doc | `standards/writing.md` |
+| credit / attribution / license / external source / adopt a tool | `standards/attribution.md` |
+| knowledge retrieval / search the codebase / code graph | `graphify` (ADR `docs/adr/0006-delegate-retrieval-to-external-tooling.md`) |
+| structure / architecture / navigator / what does grimoire create / layout / lifecycle | `NAVIGATOR.md` |
+
+## Source priority (when sources conflict)
+
+Trust in this order: **live code + committed docs/specs** (current) > **this base template**
+(`rules/ standards/ stack/`) > **`journal/memory/` cards** (may be stale — verify before acting on one).
+A memory never overrides what the code currently says; treat it as a lead, not as truth.
+
+## Hardest rules (full text in `rules/00-always.md`)
+
+- **Verify before done.** Code you wrote is not done until the verifier returns `pass` on fresh
+  context. The author cannot mark their own work done.
+- **Doc-sync same turn.** Behavior change and its doc/memory update ship in the same turn.
+- **Security first.** No hardcoded roles/secrets; validate + authorize on the server; fail closed.
+- **Effort is not a constraint.** Do not scope-cut to save effort. Spawn parallel subagents instead.
+
+## Customization & precedence
+
+Base (this template) loads first; `local/` loads last and **wins**.
+
+**In a consuming project, never edit the managed base** — `.agents/AGENTS.md`, `rules/`,
+`standards/`, `stack/`, `agents/`, `skills/`, `commands/`, `tooling.json`. `grimoire sync`
+overwrites all of them, so edits there are lost. Put **every** customization under root `local/`
+(it is never synced): **override** a base behavior by restating it in `local/` (it wins), or **add**
+a project-only rule/skill/command/standard under the matching `local/<area>/`. Protocol:
+`local/README.md`.
+
+**Project domain docs** that don't fit the lean `AGENTS.md` (a big runtime contract, confirmed-value
+tables, an IPC catalog) live in `local/reference/` — `grimoire index` generates its `INDEX.md` too.
+Run `grimoire doctor` to verify the wiring (imports, skill frontmatter, INDEX drift, placeholders);
+it exits non-zero on error, for CI.

package/.agents/NAVIGATOR.md

@@ -1,168 +1,193 @@
-# NAVIGATOR — Grimoire structure & components
-
-Canonical reference for **what Grimoire is, what it creates, and what each part does**. Read this to
-get a consistent mental model before touching the CLI, the contract, or the layout. It ships inside the
-contract (`.agents/NAVIGATOR.md`) so every project shares the same map; it complements `README.md`
-(quickstart) and `.agents/AGENTS.md` (the working contract an agent loads each session).
-
-Grimoire is a single, version-controlled **AI-agent operating system** you pull into any repo. One
-command (`grimoire init`) gives a project a complete contract — rules, standards, subagents, skills,
-commands, stack presets, a verification protocol — plus the root folders an agent writes into. Later,
-`grimoire sync` propagates template updates to old projects **without clobbering** their own data.
-
-The CLI (`grimoire`, source `bin/grimoire.mjs` in the template repo) is **zero dependencies**,
-Node ≥18, ESM. The Grimoire repo itself *is* the template and dogfoods this layout
-(`TEMPLATE_ROOT` = repo root, so its own `.agents/` is the template source).
-
-## The one mental model: three lifecycles
-
-Everything Grimoire manages falls into exactly one of three buckets. This split is the whole design.
-
-| Lifecycle | Who owns it | `grimoire sync` | Where it lives |
-|---|---|---|---|
-| **Contract** (read-only) | the base template | **overwrites wholesale** (delete + copy) | `.agents/` |
-| **Project-owned state/knowledge** | the project / the agent | **never touches** | `codex/`, `journal/`, `local/` (repo root) |
-| **Seed sources** | the base template | shipped, copied into new projects | `templates/` |
-
-Rule of thumb: **`.agents/` is 100% read-only.** Nothing an agent or project writes lives under it.
-Anything written goes to a root folder (`codex/`, `journal/`, `local/`). To customize base behavior,
-never edit `.agents/` in a consuming project — restate it in `local/` (loads last, wins).
-
-## Top-level layout (what a Grimoire project contains)
-
-```
-<repo>/
-├─ CLAUDE.md            # thin pointer: imports @.agents/AGENTS.md + @local/AGENTS.local.md
-├─ .agents/             # CONTRACT — read-only, wholesale-synced
-│  ├─ AGENTS.md         #   canonical entry: tone, hardest rules, the map, load order
-│  ├─ rules/            #   always-on working process (numbered 00–60)
-│  ├─ standards/        #   coding standards (general + per-language) + writing/codex
-│  ├─ stack/            #   tech-stack presets (web-app / desktop / library)
-│  ├─ agents/           #   subagents (e.g. the independent verifier)
-│  ├─ skills/           #   reusable workflows (incl. vendored find-skills)
-│  ├─ commands/         #   slash commands (verify, checkpoint, onboard, present, grimoire)
-│  ├─ tooling.json      #   declared plugins / skills / MCP servers
-│  ├─ grimoire.manifest #   documents the contract surface (no longer used for carve-outs)
-│  └─ VERSION           #   template version + source sha (stamped by init/sync)
-├─ codex/               # KNOWLEDGE — project-owned, seeded once, never synced
-│  ├─ INDEX.md  domain/  requirements/  decisions/  evidence/  resources/  reference/  runbooks/
-├─ journal/             # AGENT STATE — project-owned, never synced
-│  ├─ memory/  (+ MEMORY.md)   # KNOWLEDGE: durable facts (tracked)
-│  ├─ backlog/                 # QUEUE: pending work items (tracked)
-│  └─ session/                 # NOW: per-run state (gitignored)
-└─ local/               # OVERRIDE CONFIG — project-owned, never synced, loads LAST and wins
-   ├─ AGENTS.local.md   #   profile (stack, testing policy), project facts, override declarations
-   ├─ README.md  rules/  standards/  stack/  skills/  commands/  reference/
-   └─ tooling.json      #   project-only plugins / MCP (merged additively by bootstrap)
-```
-
-### The contract — `.agents/` (read-only)
-
-| Path | Holds |
-|---|---|
-| `AGENTS.md` | entry contract + load-order + the map + hot-keywords |
-| `rules/` | always-on process: 00-always, verification, modes, handoff, context-economy, commit-style, … |
-| `standards/` | coding standards (general + per-language), writing, codex, knowledge-management |
-| `stack/` | per-profile defaults (framework / lint / test / verify command) |
-| `agents/` | subagent definitions — notably `verifier` (independent done-check) |
-| `skills/` | re-runnable workflows; `find-skills` is vendored + mirrored to `.claude/skills/` |
-| `commands/` | slash commands |
-| `tooling.json` | source of truth for required plugins / skills / MCP |
-| `grimoire.manifest` | lists the managed paths — documentation only (sync is wholesale) |
-
-### Project-owned roots (never synced)
-
-- **`codex/`** — the project's knowledge base; read-first for any domain/feature work (start at
-  `codex/INDEX.md`). Holds `domain/`, `requirements/`, `decisions/` (ADRs), `evidence/`, `resources/`,
-  `reference/`, `runbooks/`. Seeded once from `templates/codex/`.
-- **`journal/`** — the agent's working state, the "3 homes":
-  - `journal/session/` = **NOW** (current run; gitignored),
-  - `journal/memory/` = **KNOWLEDGE** (durable facts + `MEMORY.md` index; tracked),
-  - `journal/backlog/` = **QUEUE** (pending work; tracked).
-- **`local/`** — the project's customization layer. Loads **last and wins**. Override a base rule by
-  restating it here; add project-only rules/skills/commands/standards under the matching `local/<area>/`.
-
-## What each CLI command creates / does
-
-`grimoire <command> [--dir <path>]` (default dir = cwd).
-
-### `init` — scaffold a project
-1. **Auto-migrate** an old-layout project first (`migrateLegacyLayout`, see below).
-2. **Wholesale-copy** the template `.agents/` into the project (`copyAgentsWholesale`).
-3. Stamp `VERSION` (template version + git sha).
-4. Write `CLAUDE.md` pointer (if absent).
-5. Ensure `.gitignore` has the session/backup ignore snippet.
-6. **Seed root folders** (only if absent / per-file gap-fill, never overwriting):
-   `seedCodex` → `codex/`; `seedRoot("journal")` → `journal/`; `seedRoot("local")` → `local/`.
-7. Mirror discoverable skills into `.claude/skills/` (`find-skills` + every `local/skills/<x>`).
-8. Generate per-folder `INDEX.md` (after all mutations).
-9. Run `bootstrap` in dry-run (prints the plugin/MCP plan; writes nothing).
-
-### `sync` — pull template updates into an existing project
-1. Fail if no `.agents/` (must `init` first).
-2. **Auto-migrate** an old layout (once, with backup).
-3. **Wholesale-replace** `.agents/` from the template (delete + copy) — your contract is refreshed.
-4. Re-stamp `VERSION`; re-seed `codex/`/`journal/`/`local/` (gap-fill only, never clobbers your files);
-   re-mirror skills; regenerate `INDEX.md`.
-   **`codex/`, `journal/`, `local/` are never overwritten** — only missing files are filled in.
-
-### `bootstrap` — wire plugins / MCP / skills
-Reads base `tooling.json` ∪ `local/tooling.json` (base wins on key conflict; local adds new keys).
-- Dry-run (default): prints missing plugins, MCP servers to ensure, and skill install hints.
-- `--apply`: enables missing plugins in `~/.claude/settings.json` (backs it up first, only **adds**,
-  never disables), and merges MCP servers into `.mcp.json` (never clobbers an existing server). Flags
-  unresolved `${ENV}` placeholders.
-
-### `index` — regenerate per-folder `INDEX.md`
-One-line-per-file table built from each file's frontmatter `description:` or its H1 + first sentence.
-Two groups: the contract (`.agents/<folder>`) and the override layer (`local/<folder>`).
-`index --check` is the CI drift gate: fails if any `INDEX.md` is stale, or a `tooling.json` MCP isn't
-documented in `skills/catalog.md`. Newline-agnostic (tolerates CRLF checkouts).
-
-### `doctor` — health-check the wiring (CI-friendly, exits non-zero on error)
-Checks: `CLAUDE.md` imports `@.agents/AGENTS.md` (error) and `@local/AGENTS.local.md` (warn); mirrored
-skills have `name:`+`description:`; INDEX/catalog drift; `local/AGENTS.local.md` stack-profile +
-testing-policy filled; entry files ≤300 lines; `codex/INDEX.md` scaffolded; `local/tooling.json` valid.
-
-## Seed-source map (`templates/` → project root)
-
-`init`/`sync` seed project-owned roots from `templates/`. Source and destination are separate so this
-repo's own live state never doubles as the seed.
-
-| Seed source | Seeds into | How |
-|---|---|---|
-| `templates/codex/` | `codex/` | `seedCodex` — dir-level **seed-once** (skips if `codex/` exists) |
-| `templates/journal/` | `journal/` | `seedRoot` — **per-file gap-fill** (fills missing files only) |
-| `templates/local/` | `local/` | `seedRoot` — **per-file gap-fill** |
-| `templates/CLAUDE.md` | `CLAUDE.md` | copied once (if absent) |
-| `templates/gitignore-snippet.txt` | `.gitignore` | appended once (`journal/session/`, `.agents.bak-*/`) |
-
-## Migration (old layout → new)
-
-Older projects kept agent state under `.agents/{memory,backlog,session,local}`. On the next
-`init`/`sync`, `migrateLegacyLayout` runs once: it backs up the whole `.agents/` to
-`.agents.bak-<stamp>/`, then **moves** each legacy dir to its root home —
-`.agents/memory→journal/memory`, `…/backlog→journal/backlog`, `…/session→journal/session`,
-`…/local→local/` — **only if the destination is absent** (a conflict leaves the legacy copy in the
-backup, never overwriting a newer root copy). Idempotent: a no-op once the legacy dirs are gone.
-
-## How an agent reads a Grimoire project (load order)
-
-1. `CLAUDE.md` → imports `@.agents/AGENTS.md` (contract) + `@local/AGENTS.local.md` (overrides).
-2. `.agents/AGENTS.md` — hardest rules + the map; **read first, don't read everything**.
-3. `.agents/rules/00-always.md` — every session.
-4. `codex/INDEX.md` — read-first for any domain/feature work.
-5. `standards/` + `stack/` — when writing/scaffolding code.
-6. `local/` — loads **last and wins**.
-
-Inside any folder, read its generated `INDEX.md` before opening files (two-level progressive
-disclosure: map → INDEX → file), keeping context lean.
-
-## Invariants (don't break these)
-
-- **Zero runtime dependencies** in `bin/grimoire.mjs` (Node stdlib only).
-- **`.agents/` is read-only** and wholesale-replaced by `sync` — never store project data there.
-- **`codex/`, `journal/`, `local/` are never synced** — safe homes for project-owned content.
-- **`local/` wins** on any conflict (loads last).
-- Behavior change ships with its doc/INDEX update in the **same change** (doc-sync).
-- Code an agent wrote is not done until the independent **verifier** returns `pass`.
+# NAVIGATOR — Grimoire structure & components
+
+Canonical reference for **what Grimoire is, what it creates, and what each part does**. Read this to
+get a consistent mental model before touching the CLI, the contract, or the layout. It ships inside the
+contract (`.agents/NAVIGATOR.md`) so every project shares the same map; it complements `README.md`
+(quickstart) and `.agents/AGENTS.md` (the working contract an agent loads each session).
+
+Grimoire is a single, version-controlled **AI-agent operating system** you pull into any repo. One
+command (`grimoire init`) gives a project a complete contract — rules, standards, subagents, skills,
+commands, stack presets, a verification protocol — plus the root folders an agent writes into. Later,
+`grimoire sync` propagates template updates to old projects **without clobbering** their own data.
+
+The CLI (`grimoire`, source `bin/grimoire.mjs` in the template repo) is **zero dependencies**,
+Node ≥18, ESM. The Grimoire repo itself *is* the template and dogfoods this layout
+(`TEMPLATE_ROOT` = repo root, so its own `.agents/` is the template source).
+
+## The one mental model: three lifecycles
+
+Everything Grimoire manages falls into exactly one of three buckets. This split is the whole design.
+
+| Lifecycle | Who owns it | `grimoire sync` | Where it lives |
+|---|---|---|---|
+| **Contract** (read-only) | the base template | **overwrites wholesale** (delete + copy) | `.agents/` |
+| **Project-owned state/knowledge** | the project / the agent | **never touches** | `codex/`, `journal/`, `local/` (repo root) |
+| **Seed sources** | the base template | shipped, copied into new projects | `templates/` |
+
+Rule of thumb: **`.agents/` is 100% read-only.** Nothing an agent or project writes lives under it.
+Anything written goes to a root folder (`codex/`, `journal/`, `local/`). To customize base behavior,
+never edit `.agents/` in a consuming project — restate it in `local/` (loads last, wins).
+
+## Top-level layout (what a Grimoire project contains)
+
+```
+<repo>/
+├─ CLAUDE.md            # thin pointer: imports @.agents/AGENTS.md + @local/AGENTS.local.md
+├─ .agents/             # CONTRACT — read-only, wholesale-synced
+│  ├─ AGENTS.md         #   canonical entry: tone, hardest rules, the map, load order
+│  ├─ rules/            #   always-on working process (numbered 00–60)
+│  ├─ standards/        #   coding standards (general + per-language) + writing/codex
+│  ├─ stack/            #   tech-stack presets (web-app / desktop / library)
+│  ├─ agents/           #   subagents (e.g. the independent verifier)
+│  ├─ skills/           #   reusable workflows (incl. vendored find-skills)
+│  ├─ commands/         #   slash commands (verify, checkpoint, onboard, present, grimoire)
+│  ├─ tooling.json      #   declared plugins / skills / MCP servers
+│  ├─ grimoire.manifest #   documents the contract surface (no longer used for carve-outs)
+│  └─ VERSION           #   template version + source sha (stamped by init/sync)
+├─ codex/               # KNOWLEDGE — project-owned, seeded once, never synced
+│  ├─ INDEX.md  domain/  requirements/  decisions/  evidence/  resources/  reference/  runbooks/
+├─ journal/             # AGENT STATE — project-owned, never synced
+│  ├─ memory/  (+ MEMORY.md)   # KNOWLEDGE: durable facts (tracked)
+│  ├─ backlog/                 # QUEUE: pending work items (tracked)
+│  └─ session/                 # NOW: per-run state (gitignored)
+└─ local/               # OVERRIDE CONFIG — project-owned, never synced, loads LAST and wins
+   ├─ AGENTS.local.md   #   profile (stack, testing policy), project facts, override declarations
+   ├─ README.md  rules/  standards/  stack/  skills/  commands/  reference/
+   └─ tooling.json      #   project-only plugins / MCP (merged additively by bootstrap)
+```
+
+### The contract — `.agents/` (read-only)
+
+| Path | Holds |
+|---|---|
+| `AGENTS.md` | entry contract + load-order + the map + hot-keywords |
+| `rules/` | always-on process: 00-always, verification, modes, handoff, context-economy, commit-style, … |
+| `standards/` | coding standards (general + per-language), writing, codex, knowledge-management |
+| `stack/` | per-profile defaults (framework / lint / test / verify command) |
+| `agents/` | subagent definitions — notably `verifier` (independent done-check) |
+| `skills/` | re-runnable workflows; `find-skills` is vendored + mirrored to `.claude/skills/` |
+| `commands/` | slash commands |
+| `tooling.json` | source of truth for required plugins / skills / MCP |
+| `grimoire.manifest` | lists the managed paths — documentation only (sync is wholesale) |
+
+### Project-owned roots (never synced)
+
+- **`codex/`** — the project's knowledge base; read-first for any domain/feature work (start at
+  `codex/INDEX.md`). Holds `domain/`, `requirements/`, `decisions/` (ADRs), `evidence/`, `resources/`,
+  `reference/`, `runbooks/`. Seeded once from `templates/codex/`.
+- **`journal/`** — the agent's working state, the "3 homes":
+  - `journal/session/` = **NOW** (current run; gitignored),
+  - `journal/memory/` = **KNOWLEDGE** (durable facts + `MEMORY.md` index; tracked),
+  - `journal/backlog/` = **QUEUE** (pending work; tracked).
+- **`local/`** — the project's customization layer. Loads **last and wins**. Override a base rule by
+  restating it here; add project-only rules/skills/commands/standards under the matching `local/<area>/`.
+
+## What each CLI command creates / does
+
+`grimoire <command> [--dir <path>]` (default dir = cwd).
+
+### `init` — scaffold a project
+1. **Auto-migrate** an old-layout project first (`migrateLegacyLayout`, see below).
+2. **Wholesale-copy** the template `.agents/` into the project (`copyAgentsWholesale`).
+3. Stamp `VERSION` (template version + git sha).
+4. Write `CLAUDE.md` pointer (if absent).
+5. Ensure `.gitignore` has the session/backup ignore snippet.
+6. **Seed root folders** (only if absent / per-file gap-fill, never overwriting):
+   `seedCodex` → `codex/`; `seedRoot("journal")` → `journal/`; `seedRoot("local")` → `local/`.
+7. Mirror discoverable skills into `.claude/skills/` (`find-skills` + every `local/skills/<x>`).
+8. Generate per-folder `INDEX.md` (after all mutations).
+9. Run `bootstrap` in dry-run (prints the plugin/MCP plan; writes nothing).
+
+### `sync` — pull template updates into an existing project
+1. Fail if no `.agents/` (must `init` first).
+2. **Auto-migrate** an old layout (once, with backup).
+3. **Wholesale-replace** `.agents/` from the template (delete + copy) — your contract is refreshed.
+4. Re-stamp `VERSION`; re-seed `codex/`/`journal/`/`local/` (gap-fill only, never clobbers your files);
+   re-mirror skills; regenerate `INDEX.md`.
+   **`codex/`, `journal/`, `local/` are never overwritten** — only missing files are filled in.
+
+### `bootstrap` — wire plugins / MCP / skills
+Reads base `tooling.json` ∪ `local/tooling.json` (base wins on key conflict; local adds new keys).
+For every missing plugin it prints the **paste-in-Claude** install command (`/plugin marketplace add
+<source> && /plugin install <name>@<marketplace>`) — the CLI can only flip the enable flag, it cannot
+register a marketplace or run a slash command.
+- **Interactive** (default, in a terminal): asks `enable <plugin>? [y/N]` per missing plugin, then
+  enables the chosen ones in `~/.claude/settings.json` and merges MCP servers.
+- **Dry-run** (no TTY — CI/piped, and the `init`-embedded preview): prints the plan, writes nothing.
+- `--apply`: non-interactive enable-all — enables every missing plugin in `~/.claude/settings.json`
+  (backs it up first, only **adds**, never disables), and merges MCP servers into `.mcp.json` (never
+  clobbers an existing server). Flags unresolved `${ENV}` placeholders.
+
+### `index` — regenerate per-folder `INDEX.md`
+One-line-per-file table built from each file's frontmatter `description:` or its H1 + first sentence.
+Two groups: the contract (`.agents/<folder>`) and the override layer (`local/<folder>`).
+`index --check` is the CI drift gate: fails if any `INDEX.md` is stale, or a `tooling.json` MCP isn't
+documented in `skills/catalog.md`. Newline-agnostic (tolerates CRLF checkouts).
+
+### `doctor` — health-check the wiring (CI-friendly, exits non-zero on error)
+Checks: `CLAUDE.md` imports `@.agents/AGENTS.md` (error) and `@local/AGENTS.local.md` (warn); mirrored
+skills have `name:`+`description:`; INDEX/catalog drift; `local/AGENTS.local.md` stack-profile +
+testing-policy filled; entry files ≤300 lines; `codex/INDEX.md` scaffolded; `local/tooling.json` valid.
+
+## Seed-source map (`templates/` → project root)
+
+`init`/`sync` seed project-owned roots from `templates/`. Source and destination are separate so this
+repo's own live state never doubles as the seed.
+
+| Seed source | Seeds into | How |
+|---|---|---|
+| `templates/codex/` | `codex/` | `seedCodex` — dir-level **seed-once** (skips if `codex/` exists) |
+| `templates/journal/` | `journal/` | `seedRoot` — **per-file gap-fill** (fills missing files only) |
+| `templates/local/` | `local/` | `seedRoot` — **per-file gap-fill** |
+| `templates/CLAUDE.md` | `CLAUDE.md` | copied once (if absent) |
+| `templates/gitignore-snippet.txt` | `.gitignore` | appended once (`journal/session/`, `.agents.bak-*/`) |
+
+## Migration (old layout → new)
+
+Older projects kept agent state under `.agents/{memory,backlog,session,local}`. On the next
+`init`/`sync`, `migrateLegacyLayout` runs once: it backs up the whole `.agents/` to
+`.agents.bak-<stamp>/`, then **moves** each legacy dir to its root home —
+`.agents/memory→journal/memory`, `…/backlog→journal/backlog`, `…/session→journal/session`,
+`…/local→local/` — **only if the destination is absent** (a conflict leaves the legacy copy in the
+backup, never overwriting a newer root copy). Idempotent: a no-op once the legacy dirs are gone.
+
+The same `sync` also **repairs the wiring** the move would otherwise break: it rewrites a `CLAUDE.md`
+still importing `@.agents/local/…` to `@local/…`, and refreshes `.gitignore` (drops the stale
+`.agents/session/` line, adds `journal/session/`, `.agents.bak-*/`, and `graphify-out/`). `doctor`
+warns if a stale `@.agents/local/` import survives.
+
+### Adopting an existing repo's `docs/` into `codex/`
+
+Moving a project's hand-kept `docs/` tree into `codex/` is **manual and project-owned** (the CLI never
+touches `docs/` or `codex/`). Place by *kind*, not by old folder: ADRs → `codex/decisions/`, specs →
+`codex/requirements/`, contracts/lookups/IPC tables → `codex/reference/`, "what the system is" →
+`codex/domain/`, runbooks → `codex/runbooks/`, investigations/postmortems/release evidence →
+`codex/evidence/`. Drop low-value process exhaust (it stays recoverable in git history).
+
+**Before calling it done, grep the codebase for runtime reads of the moved paths.** Code that does
+`readFileSync(join(cwd, "docs", …))` — test oracles, `db:seed` scripts, fixture loaders — breaks
+silently when the file moves. Two consequences: (1) update that path in the code; (2) if the moved
+files are *loaded by code* (seed CSVs, test fixtures), they are runtime assets, not knowledge — keep
+them where the loader expects, or treat `codex/` as their home and point the loader there. **Never let
+PII (staff/patient rosters) land in `codex/` if `codex/` is fed to retrieval/wiki tooling.**
+
+## How an agent reads a Grimoire project (load order)
+
+1. `CLAUDE.md` → imports `@.agents/AGENTS.md` (contract) + `@local/AGENTS.local.md` (overrides).
+2. `.agents/AGENTS.md` — hardest rules + the map; **read first, don't read everything**.
+3. `.agents/rules/00-always.md` — every session.
+4. `codex/INDEX.md` — read-first for any domain/feature work.
+5. `standards/` + `stack/` — when writing/scaffolding code.
+6. `local/` — loads **last and wins**.
+
+Inside any folder, read its generated `INDEX.md` before opening files (two-level progressive
+disclosure: map → INDEX → file), keeping context lean.
+
+## Invariants (don't break these)
+
+- **Zero runtime dependencies** in `bin/grimoire.mjs` (Node stdlib only).
+- **`.agents/` is read-only** and wholesale-replaced by `sync` — never store project data there.
+- **`codex/`, `journal/`, `local/` are never synced** — safe homes for project-owned content.
+- **`local/` wins** on any conflict (loads last).
+- Behavior change ships with its doc/INDEX update in the **same change** (doc-sync).
+- Code an agent wrote is not done until the independent **verifier** returns `pass`.

package/.agents/VERSION

@@ -1,4 +1,4 @@
-grimoire v0.3.2
-source: this repository IS the template (canonical source of truth)
-note: informational only — package.json `version` is the single source of truth;
-      `grimoire init` / `grimoire sync` regenerate this from it and stamp the build sha.
+grimoire v0.5.0
+source: this repository IS the template (canonical source of truth)
+note: informational only — package.json `version` is the single source of truth;
+      `grimoire init` / `grimoire sync` regenerate this from it and stamp the build sha.