the-grimoire-cli 0.3.2 → 0.4.0

package/package.json

@@ -1,32 +1,32 @@
-{
-  "name": "the-grimoire-cli",
-  "version": "0.3.2",
-  "description": "A reusable, tool-agnostic AI-agent operating system. Init it into any project; sync template updates without clobbering local customization.",
-  "type": "module",
-  "bin": {
-    "grimoire": "bin/grimoire.mjs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nuttchanon/the-grimoire.git"
-  },
-  "homepage": "https://github.com/nuttchanon/the-grimoire#readme",
-  "bugs": "https://github.com/nuttchanon/the-grimoire/issues",
-  "keywords": ["ai", "agent", "claude", "claude-code", "scaffold", "template", "cli", "agents.md"],
-  "files": [
-    "bin/",
-    ".agents/",
-    "templates/",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test \"test/**/*.test.mjs\"",
-    "index:check": "node bin/grimoire.mjs index --dir . --check"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "MIT",
-  "author": "Nutt"
-}
+{
+  "name": "the-grimoire-cli",
+  "version": "0.4.0",
+  "description": "A reusable, tool-agnostic AI-agent operating system. Init it into any project; sync template updates without clobbering local customization.",
+  "type": "module",
+  "bin": {
+    "grimoire": "bin/grimoire.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuttchanon/the-grimoire.git"
+  },
+  "homepage": "https://github.com/nuttchanon/the-grimoire#readme",
+  "bugs": "https://github.com/nuttchanon/the-grimoire/issues",
+  "keywords": ["ai", "agent", "claude", "claude-code", "scaffold", "template", "cli", "agents.md"],
+  "files": [
+    "bin/",
+    ".agents/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "index:check": "node bin/grimoire.mjs index --dir . --check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Nutt"
+}

package/templates/CLAUDE.md

@@ -1,7 +1,7 @@
-# CLAUDE.md
-
-This project uses **Grimoire**. The canonical agent contract is `.agents/AGENTS.md`.
-Read it first, then follow its load order.
-
-@.agents/AGENTS.md
-@local/AGENTS.local.md
+# CLAUDE.md
+
+This project uses **Grimoire**. The canonical agent contract is `.agents/AGENTS.md`.
+Read it first, then follow its load order.
+
+@.agents/AGENTS.md
+@local/AGENTS.local.md

package/templates/ci/ci.yml

@@ -1,49 +1,49 @@
-# CI — lint, typecheck, test, build. Copy to .github/workflows/ci.yml.
-# This is the correctness gate; security scanning lives in the sibling sast.yml.
-# Commands here must match the active stack profile's `verify` (.agents/stack/<profile>.md) —
-# keep them in sync so local `verify` and CI run the same checks.
-name: ci
-
-on:
-  pull_request:
-  push:
-    branches: [main, master]
-
-permissions:
-  contents: read
-
-jobs:
-  verify:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          cache: npm           # change to pnpm/yarn to match the project
-
-      - run: npm ci
-
-      # --- The four gates. Drop any line a profile doesn't have; order is cheapest-first. ---
-      - name: Lint
-        run: npm run lint
-
-      - name: Typecheck
-        run: npx tsc --noEmit
-
-      - name: Test
-        run: npm test          # node --test / vitest / jest per profile
-
-      - name: Build
-        run: npm run build
-
-      # --- Contract guard: agent docs/index must not drift (.agents/) ---
-      - name: Grimoire index check
-        run: npx github:nuttchanon/the-grimoire index --check
-        # Remove this step if the project does not vendor Grimoire's INDEX.md generation.
-
-# Per stack profile (.agents/stack/):
-#   web-app  : lint + typecheck + test (vitest) + build (next build). Add the e2e job when present.
-#   desktop  : lint + typecheck + test + build (electron-builder --dir for PR; full pack on release).
-#   library  : lint + typecheck + test + build (tsup/unbuild) + a changesets status check on PRs.
-# Accessibility: add an axe/Lighthouse job for user-facing apps (.agents/standards/accessibility.md).
+# CI — lint, typecheck, test, build. Copy to .github/workflows/ci.yml.
+# This is the correctness gate; security scanning lives in the sibling sast.yml.
+# Commands here must match the active stack profile's `verify` (.agents/stack/<profile>.md) —
+# keep them in sync so local `verify` and CI run the same checks.
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm           # change to pnpm/yarn to match the project
+
+      - run: npm ci
+
+      # --- The four gates. Drop any line a profile doesn't have; order is cheapest-first. ---
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+
+      - name: Test
+        run: npm test          # node --test / vitest / jest per profile
+
+      - name: Build
+        run: npm run build
+
+      # --- Contract guard: agent docs/index must not drift (.agents/) ---
+      - name: Grimoire index check
+        run: npx github:nuttchanon/the-grimoire index --check
+        # Remove this step if the project does not vendor Grimoire's INDEX.md generation.
+
+# Per stack profile (.agents/stack/):
+#   web-app  : lint + typecheck + test (vitest) + build (next build). Add the e2e job when present.
+#   desktop  : lint + typecheck + test + build (electron-builder --dir for PR; full pack on release).
+#   library  : lint + typecheck + test + build (tsup/unbuild) + a changesets status check on PRs.
+# Accessibility: add an axe/Lighthouse job for user-facing apps (.agents/standards/accessibility.md).

package/templates/ci/sast.yml

@@ -1,44 +1,44 @@
-# SAST — static application security testing. Copy to .github/workflows/sast.yml.
-# Linters find what is ugly; SAST finds what is exploitable (SQLi, XSS, RCE, secrets, weak crypto).
-# Fail the build on High/Critical. Scanner choice is per stack profile — see notes at the bottom.
-name: sast
-
-on:
-  pull_request:
-  push:
-    branches: [main, master]
-
-permissions:
-  contents: read
-  security-events: write   # for SARIF upload to GitHub code scanning
-
-jobs:
-  semgrep:
-    # Pattern-based, 30+ languages. Default for every profile.
-    runs-on: ubuntu-latest
-    container: { image: semgrep/semgrep }
-    steps:
-      - uses: actions/checkout@v4
-      - run: semgrep ci --config auto --error
-        env:
-          # Optional: set SEMGREP_APP_TOKEN to use org rules + the Semgrep dashboard.
-          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
-
-  njsscan:
-    # JS / Node / React / React Native / Electron. Drop this job for non-JS profiles.
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with: { python-version: "3.12" }
-      - run: pip install njsscan
-      - run: njsscan --exit-on-warn .
-
-# Per stack profile (standards/security-scanners.md):
-#   web-app  (Next.js)   : semgrep + njsscan here, AND enable CodeQL code scanning (js/ts).
-#   desktop  (Electron)  : semgrep + njsscan here (njsscan flags Electron sinks), AND CodeQL.
-#   library              : semgrep here; add the language's native scanner (bandit/gosec/…) if not JS/TS.
-#   any Python service   : add a bandit job (pip install bandit; bandit -r src -ll).
-#
-# CodeQL is configured separately — GitHub → Security → Code scanning → enable default setup,
-# or add github/codeql-action via its own workflow. It is free for public repos.
+# SAST — static application security testing. Copy to .github/workflows/sast.yml.
+# Linters find what is ugly; SAST finds what is exploitable (SQLi, XSS, RCE, secrets, weak crypto).
+# Fail the build on High/Critical. Scanner choice is per stack profile — see notes at the bottom.
+name: sast
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+  security-events: write   # for SARIF upload to GitHub code scanning
+
+jobs:
+  semgrep:
+    # Pattern-based, 30+ languages. Default for every profile.
+    runs-on: ubuntu-latest
+    container: { image: semgrep/semgrep }
+    steps:
+      - uses: actions/checkout@v4
+      - run: semgrep ci --config auto --error
+        env:
+          # Optional: set SEMGREP_APP_TOKEN to use org rules + the Semgrep dashboard.
+          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+
+  njsscan:
+    # JS / Node / React / React Native / Electron. Drop this job for non-JS profiles.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install njsscan
+      - run: njsscan --exit-on-warn .
+
+# Per stack profile (standards/security-scanners.md):
+#   web-app  (Next.js)   : semgrep + njsscan here, AND enable CodeQL code scanning (js/ts).
+#   desktop  (Electron)  : semgrep + njsscan here (njsscan flags Electron sinks), AND CodeQL.
+#   library              : semgrep here; add the language's native scanner (bandit/gosec/…) if not JS/TS.
+#   any Python service   : add a bandit job (pip install bandit; bandit -r src -ll).
+#
+# CodeQL is configured separately — GitHub → Security → Code scanning → enable default setup,
+# or add github/codeql-action via its own workflow. It is free for public repos.

package/templates/codex/INDEX.md

@@ -1,18 +1,18 @@
-# codex — index (read this first)
-
-The project's **knowledge / resource root**. Read this signpost before touching any domain reference,
-then open the matching subfolder's own `INDEX.md`. Project-owned: `grimoire sync` never touches
-`codex/`; the base holds only a pointer to it. Every folder below keeps its own `INDEX.md`.
-
-| Folder | What it holds |
-|---|---|
-| `domain/` | What the system **is** — glossary, context, business rules, capabilities. |
-| `requirements/` | What it must **do** — IDed, versioned base + addons + change requests. |
-| `decisions/` | **Why** it is built this way — ADRs (one file per decision). |
-| `evidence/` | Investigation / reverse-engineering / extraction outputs, each fact sourced. |
-| `resources/` | Raw materials — datasets, vendor specs, dumps, external artifacts/snapshots. |
-| `reference/` | Confirmed-value tables, API/IPC catalogs, big contracts the code reads back. |
-| `runbooks/` | The on-call answer to "production is broken — what now." |
-
-Protocol: `.agents/standards/codex.md`. The structure is **extensible** — add a folder when a new
-kind of knowledge appears; give it an `INDEX.md` and list it here.
+# codex — index (read this first)
+
+The project's **knowledge / resource root**. Read this signpost before touching any domain reference,
+then open the matching subfolder's own `INDEX.md`. Project-owned: `grimoire sync` never touches
+`codex/`; the base holds only a pointer to it. Every folder below keeps its own `INDEX.md`.
+
+| Folder | What it holds |
+|---|---|
+| `domain/` | What the system **is** — glossary, context, business rules, capabilities. |
+| `requirements/` | What it must **do** — IDed, versioned base + addons + change requests. |
+| `decisions/` | **Why** it is built this way — ADRs (one file per decision). |
+| `evidence/` | Investigation / reverse-engineering / extraction outputs, each fact sourced. |
+| `resources/` | Raw materials — datasets, vendor specs, dumps, external artifacts/snapshots. |
+| `reference/` | Confirmed-value tables, API/IPC catalogs, big contracts the code reads back. |
+| `runbooks/` | The on-call answer to "production is broken — what now." |
+
+Protocol: `.agents/standards/codex.md`. The structure is **extensible** — add a folder when a new
+kind of knowledge appears; give it an `INDEX.md` and list it here.

package/templates/codex/README.md

@@ -1,28 +1,28 @@
-# codex
-
-The project's **knowledge and resource root**, at the repo root (not under `.agents/`). It is the
-rebuild's source of truth: what the system is, what it must do, why it's built that way, and the raw
-materials and evidence behind those claims. Project-owned — `grimoire sync` never touches it; the
-base contract only points here. Full protocol: `.agents/standards/codex.md`.
-
-## Read-first rule
-
-Any domain reference starts at `codex/INDEX.md`, then the relevant subfolder's `INDEX.md`. New work
-reads the matching INDEX **before** acting — don't start a task blind to recorded knowledge.
-
-## Provenance discipline
-
-Every recorded fact cites its **source** (file + offset/record) and a **CONFIRMED | INFERRED** tag.
-Unsupported claims are removed or demoted to "not recovered" — no unsourced guesses. Pre-existing
-docs are not trusted until audited to this standard (carry `audited: <date>`).
-
-## How to add a folder
-
-codex is extensible. When a new kind of knowledge appears, add a folder, give it an `INDEX.md`
-(signpost table) and a short `README.md`, and list it in the master `codex/INDEX.md`. Keep every
-file lean (context economy).
-
-## Secrets
-
-Real secrets / PHI never go in tracked knowledge docs — see `resources/README.md` and
-`.agents/standards/codex.md`. The chat is the leak boundary: never echo a secret or PHI into output.
+# codex
+
+The project's **knowledge and resource root**, at the repo root (not under `.agents/`). It is the
+rebuild's source of truth: what the system is, what it must do, why it's built that way, and the raw
+materials and evidence behind those claims. Project-owned — `grimoire sync` never touches it; the
+base contract only points here. Full protocol: `.agents/standards/codex.md`.
+
+## Read-first rule
+
+Any domain reference starts at `codex/INDEX.md`, then the relevant subfolder's `INDEX.md`. New work
+reads the matching INDEX **before** acting — don't start a task blind to recorded knowledge.
+
+## Provenance discipline
+
+Every recorded fact cites its **source** (file + offset/record) and a **CONFIRMED | INFERRED** tag.
+Unsupported claims are removed or demoted to "not recovered" — no unsourced guesses. Pre-existing
+docs are not trusted until audited to this standard (carry `audited: <date>`).
+
+## How to add a folder
+
+codex is extensible. When a new kind of knowledge appears, add a folder, give it an `INDEX.md`
+(signpost table) and a short `README.md`, and list it in the master `codex/INDEX.md`. Keep every
+file lean (context economy).
+
+## Secrets
+
+Real secrets / PHI never go in tracked knowledge docs — see `resources/README.md` and
+`.agents/standards/codex.md`. The chat is the leak boundary: never echo a secret or PHI into output.

package/templates/codex/decisions/0000-template.md

@@ -1,36 +1,36 @@
----
-id: 0000
-title: <short decision title>
-status: proposed        # proposed | accepted | superseded | deprecated
-date: <YYYY-MM-DD>
-updates-confirmed-values: no   # yes | no — see "Confirmed values" below
-supersedes:             # ADR id(s) this replaces, if any
----
-
-# ADR 0000 — <short decision title>
-
-## Context
-
-What forces this decision? The problem, constraints, and the options actually on the table. Keep it
-factual — no solution yet.
-
-## Decision
-
-The choice, stated as one sentence in active voice ("We will …"). Then the *why* in a few lines.
-
-## Consequences
-
-What becomes easier, what becomes harder, what we now owe (migrations, follow-ups, risks).
-
-## Confirmed values
-
-> Set `updates-confirmed-values: yes` in the frontmatter **only if this decision changes a value the
-> code treats as ground truth** — an IPC channel name, an error code, a permission key, a hospital/
-> tenant config, an enum the UI and server both depend on.
-
-If `yes`: list each value below **and** update the project's confirmed-values table
-(`codex/reference/`) in the same PR (the PR checklist enforces this). If `no`, delete this section.
-
-| Value | Old | New | Where it lives |
-|---|---|---|---|
-| | | | |
+---
+id: 0000
+title: <short decision title>
+status: proposed        # proposed | accepted | superseded | deprecated
+date: <YYYY-MM-DD>
+updates-confirmed-values: no   # yes | no — see "Confirmed values" below
+supersedes:             # ADR id(s) this replaces, if any
+---
+
+# ADR 0000 — <short decision title>
+
+## Context
+
+What forces this decision? The problem, constraints, and the options actually on the table. Keep it
+factual — no solution yet.
+
+## Decision
+
+The choice, stated as one sentence in active voice ("We will …"). Then the *why* in a few lines.
+
+## Consequences
+
+What becomes easier, what becomes harder, what we now owe (migrations, follow-ups, risks).
+
+## Confirmed values
+
+> Set `updates-confirmed-values: yes` in the frontmatter **only if this decision changes a value the
+> code treats as ground truth** — an IPC channel name, an error code, a permission key, a hospital/
+> tenant config, an enum the UI and server both depend on.
+
+If `yes`: list each value below **and** update the project's confirmed-values table
+(`codex/reference/`) in the same PR (the PR checklist enforces this). If `no`, delete this section.
+
+| Value | Old | New | Where it lives |
+|---|---|---|---|
+| | | | |

package/templates/codex/decisions/INDEX.md

@@ -1,11 +1,11 @@
-# decisions — index
-
-**Why** the system is built the way it is: Architecture Decision Records, one file per decision.
-Requirements say *what*; decisions say *how* and *why*.
-
-| Entry | What it holds |
-|---|---|
-| `README.md` | When to write an ADR, the `updates-confirmed-values` field, the status lifecycle. |
-| `0000-template.md` | Copy this for each new decision: `NNNN-kebab-title.md`. |
-
-<!-- ADRs accumulate here as NNNN-kebab-title.md; number sequentially, never renumber. -->
+# decisions — index
+
+**Why** the system is built the way it is: Architecture Decision Records, one file per decision.
+Requirements say *what*; decisions say *how* and *why*.
+
+| Entry | What it holds |
+|---|---|
+| `README.md` | When to write an ADR, the `updates-confirmed-values` field, the status lifecycle. |
+| `0000-template.md` | Copy this for each new decision: `NNNN-kebab-title.md`. |
+
+<!-- ADRs accumulate here as NNNN-kebab-title.md; number sequentially, never renumber. -->

package/templates/codex/decisions/README.md

@@ -1,25 +1,25 @@
-# Architecture Decision Records
-
-One file per decision: `codex/decisions/NNNN-kebab-title.md`, copied from `0000-template.md`. ADRs are
-**project-owned** — `grimoire sync` never touches this folder. Number sequentially; never renumber.
-
-## When to write one
-
-- A choice with lasting consequences (framework, data model, auth model, module boundaries).
-- A trade-off a future reader would otherwise relitigate.
-- **No test suite for a unit of work.** Absence of tests is a *recorded decision*, not a silent
-  omission: open an ADR stating why (spike/throwaway, external constraint) and the conditions under
-  which tests get backfilled. A missing test suite with no ADR is a defect.
-
-## The `updates-confirmed-values` field
-
-Some values are **ground truth** the code reads back — IPC channel names, error codes, permission
-keys, tenant/hospital configs, shared enums. When an ADR changes one of these, set
-`updates-confirmed-values: yes` and, **in the same PR**, update the project's confirmed-values table
-(`codex/reference/`). The PR checklist must verify the table was updated; a `yes` ADR without a
-matching table change does not merge.
-
-## Status lifecycle
-
-`proposed` → `accepted` (merged) → later `superseded` (point the new ADR's `supersedes:` at it) or
-`deprecated`. Never delete an accepted ADR; supersede it so the history stays legible.
+# Architecture Decision Records
+
+One file per decision: `codex/decisions/NNNN-kebab-title.md`, copied from `0000-template.md`. ADRs are
+**project-owned** — `grimoire sync` never touches this folder. Number sequentially; never renumber.
+
+## When to write one
+
+- A choice with lasting consequences (framework, data model, auth model, module boundaries).
+- A trade-off a future reader would otherwise relitigate.
+- **No test suite for a unit of work.** Absence of tests is a *recorded decision*, not a silent
+  omission: open an ADR stating why (spike/throwaway, external constraint) and the conditions under
+  which tests get backfilled. A missing test suite with no ADR is a defect.
+
+## The `updates-confirmed-values` field
+
+Some values are **ground truth** the code reads back — IPC channel names, error codes, permission
+keys, tenant/hospital configs, shared enums. When an ADR changes one of these, set
+`updates-confirmed-values: yes` and, **in the same PR**, update the project's confirmed-values table
+(`codex/reference/`). The PR checklist must verify the table was updated; a `yes` ADR without a
+matching table change does not merge.
+
+## Status lifecycle
+
+`proposed` → `accepted` (merged) → later `superseded` (point the new ADR's `supersedes:` at it) or
+`deprecated`. Never delete an accepted ADR; supersede it so the history stays legible.

package/templates/codex/domain/INDEX.md

@@ -1,14 +1,14 @@
-# domain — index
-
-What the system **is**: the shared language and rules that everything else cites. Read before
-writing requirements or code in an unfamiliar area.
-
-| Entry | What it holds |
-|---|---|
-| `README.md` | What belongs in `domain/` and how to keep it sourced. |
-| `glossary.md` | Domain terms → precise definitions (add as the language stabilizes). |
-| `context.md` | The business/system context: actors, boundaries, why the system exists. |
-| `business-rules.md` | The rules the system must enforce, each cited to its source. |
-| `capabilities.md` | What the system can do, at the capability (not requirement) level. |
-
-<!-- Seed these files as the domain takes shape; delete rows you don't use yet. -->
+# domain — index
+
+What the system **is**: the shared language and rules that everything else cites. Read before
+writing requirements or code in an unfamiliar area.
+
+| Entry | What it holds |
+|---|---|
+| `README.md` | What belongs in `domain/` and how to keep it sourced. |
+| `glossary.md` | Domain terms → precise definitions (add as the language stabilizes). |
+| `context.md` | The business/system context: actors, boundaries, why the system exists. |
+| `business-rules.md` | The rules the system must enforce, each cited to its source. |
+| `capabilities.md` | What the system can do, at the capability (not requirement) level. |
+
+<!-- Seed these files as the domain takes shape; delete rows you don't use yet. -->

package/templates/codex/domain/README.md

@@ -1,10 +1,10 @@
-# domain
-
-What the system **is** — the shared vocabulary and the business rules that requirements, decisions,
-and code all refer back to. This is where you fix the language so two people (or agents) mean the
-same thing by the same word. Glossary, business/system context, enforced business rules, and the
-high-level capability map live here.
-
-Hold to the codex provenance discipline: each rule or definition that comes from a source artifact
-cites it (file + offset, `CONFIRMED | INFERRED`). A definition you invented for convenience is
-`INFERRED` until confirmed. See `.agents/standards/codex.md`.
+# domain
+
+What the system **is** — the shared vocabulary and the business rules that requirements, decisions,
+and code all refer back to. This is where you fix the language so two people (or agents) mean the
+same thing by the same word. Glossary, business/system context, enforced business rules, and the
+high-level capability map live here.
+
+Hold to the codex provenance discipline: each rule or definition that comes from a source artifact
+cites it (file + offset, `CONFIRMED | INFERRED`). A definition you invented for convenience is
+`INFERRED` until confirmed. See `.agents/standards/codex.md`.

package/templates/codex/evidence/0000-extraction-template.md

@@ -1,36 +1,36 @@
----
-id: 0000
-title: <what was extracted / investigated>
-status: draft           # draft | reviewed
-date: <YYYY-MM-DD>
-audited: <YYYY-MM-DD>   # date this doc was checked to the provenance standard
----
-
-# Extraction 0000 — <what was extracted / investigated>
-
-## Source artifact
-
-What you investigated: file path / binary / dump / vendor doc, version or hash if known. One artifact
-per doc where possible.
-
-## Method / tool
-
-How you extracted it — the tool, command, decompiler, query, or manual read. Enough that someone
-could repeat it and get the same result.
-
-## Findings
-
-| item | source (file + offset/record) | CONFIRMED \| INFERRED | purpose |
-|---|---|---|---|
-| <value / rule / field> | `<file>:<offset>` or `<table>:<row>` | CONFIRMED | <what it's for> |
-
-## Not recovered
-
-What you looked for and could **not** establish, and why (encrypted, stripped, absent). This bounds
-the claim — don't let a gap pass as settled.
-
-## Security / redaction note
-
-Confirm no real secret / PHI is recorded above. If the artifact contained any, record only its
-**location + purpose** here for rotate/revoke; the value goes in the gitignored inventory
-(`resources/`), never in this tracked doc.
+---
+id: 0000
+title: <what was extracted / investigated>
+status: draft           # draft | reviewed
+date: <YYYY-MM-DD>
+audited: <YYYY-MM-DD>   # date this doc was checked to the provenance standard
+---
+
+# Extraction 0000 — <what was extracted / investigated>
+
+## Source artifact
+
+What you investigated: file path / binary / dump / vendor doc, version or hash if known. One artifact
+per doc where possible.
+
+## Method / tool
+
+How you extracted it — the tool, command, decompiler, query, or manual read. Enough that someone
+could repeat it and get the same result.
+
+## Findings
+
+| item | source (file + offset/record) | CONFIRMED \| INFERRED | purpose |
+|---|---|---|---|
+| <value / rule / field> | `<file>:<offset>` or `<table>:<row>` | CONFIRMED | <what it's for> |
+
+## Not recovered
+
+What you looked for and could **not** establish, and why (encrypted, stripped, absent). This bounds
+the claim — don't let a gap pass as settled.
+
+## Security / redaction note
+
+Confirm no real secret / PHI is recorded above. If the artifact contained any, record only its
+**location + purpose** here for rotate/revoke; the value goes in the gitignored inventory
+(`resources/`), never in this tracked doc.