fdeops 3.9.20 → 3.10.2

package/README.md

@@ -7,7 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**Memory + methodology + skills, in one kit.** Skill packs teach your AI agent how to build. None of them remember who the client is, what was decided, or what's safe to ship. FDEOps adds the missing layer: a private fieldbook per engagement (`.fde/`), a field methodology (land → close), and one `@fde` skill that routes it all. 
+**Memory + methodology + skills, in one kit.** Skill packs - BMAD, Spec-Kit, [mattpocock/skills](https://github.com/mattpocock/skills) - teach your AI coding agent how to *build*. None of them remember who the client is, what you promised them, or who agreed it was delivered. FDEOps adds the missing layer: a private fieldbook per engagement (`.fde/`), a field methodology (land → close), and one `@fde` skill that routes it all.
 
 Built for Forward Deployed Engineers, and anyone embedded in client work: consultants, agency developers, solutions architects, fractional CTOs. Feels like a second brain; behaves like a defensible record (dated, sourced, yours).
 
@@ -19,69 +19,82 @@ Built for Forward Deployed Engineers, and anyone embedded in client work: consul
              written as a side effect of the work
 ```
 
-**You talk in plain language with `@fde`.** The agent (and an optional CLI) handles the boring memory work. You still confirm anything that goes into the record.
+Talk in plain language with `@fde`. The AI coding agent runs the plumbing. You confirm anything that enters the record.
 
 ---
 
 ## The week
 
-Day to day you only need `@fde` and normal English. No command cheat sheet.
+`@fde` plus English. No cheat sheet.
 
 | When | What you say | What you get |
 |------|--------------|--------------|
-| **Start of week** | Open your AI coding agent (nothing to paste) | It already knows where you left off - trust, phase, what's next |
-| **After a meeting** | `@fde` debrief these notes *(paste or attach them)* | Proposed updates to the record - you review, then confirm |
-| **Pull from tools** | `@fde` connect Granola *(once)* · then `@fde` pull today's Acme transcript | Wire any source MCP you choose; FDEOps stages → proposes → you confirm. Recipes: [mcp/recipes/](mcp/recipes/) |
-| **Before a stakeholder meeting** | `@fde` prep me for tomorrow's meeting with the sponsor | A short brief from what you already logged - not a blank chat |
-| **Someone disputes scope** | `@fde` when did we agree to drop that feature? | Dated answers from the record (or a clear gap if nothing was logged) |
-| **End of week** | `@fde` draft the sponsor update from the record | Status grounded in what actually happened |
+| **Start of week** | `@fde` — or just open Claude Code | Fieldbook on disk either way. **Claude Code** injects trust, phase, next before you type. **Cursor / Codex / others:** say `@fde` or `resume` — nothing auto-loads. |
+| **After a meeting** | `@fde` debrief these notes *(paste or attach)* | Proposed updates. You review, then confirm. |
+| **Optional: pull** | `@fde` connect Granola *(once)* · `@fde` pull today's Acme transcript | You add that source MCP. We **pull** on request — no push, no sync. [mcp/recipes/](mcp/recipes/) |
+| **Before a stakeholder meeting** | `@fde` prep me for tomorrow with the sponsor | Brief from what you already logged. |
+| **Scope dispute** | `@fde` when did we agree to drop that? | Dated answers, or a clear gap. |
+| **End of week** | `@fde` draft the sponsor update from the record | Status grounded in what happened. |
 
-Same client folder every time (`~/fde-engagements/<client>/.fde/`). Your AI coding agent reads it on every session.
+Same folder every time: `~/fde-engagements/<client>/.fde/`.
 
 ---
 
-## Quickstart
-
-**1. Install** (pick one)
+## See it
 
 ```bash
-npx skills add suboss87/fdeops          # Cursor, Codex, and skills-compatible agents
+npx fdeops demo
 ```
 
+Real commands on a fake client: messy notes → you confirm → cold reload → prep → receipts → fieldbook page. Nothing of yours is read. Lives in `~/fde-engagements/.demo/`. Remove with `npx fdeops demo --clean`.
+
+One recorded session — kickoff notes, next morning, “when did we agree?” weeks later. CLI output; typing pace is staged. Re-record: [`media/record-session.sh`](media/record-session.sh).
+
+<p align="center"><img alt="A real fdeops session: messy kickoff notes routed into dated memory after you confirm, then a cold session that already knows the client, a grounded sponsor-meeting brief, and dated receipts" src="media/session.gif" width="900" /></p>
+
+Two things a chat window cannot do: **nothing is written until you confirm**, and `<private>` lands sealed as `(private - redacted)` — never in `resume`, `prep`, `receipts`, or the dashboard.
+
+---
+
+## Quickstart
+
+**1. Install.** Claude Code: session hooks (context before you type). Everywhere else: the same fieldbook, loaded when you ask.
+
 ```text
-/plugin marketplace add suboss87/fdeops # Claude Code
+/plugin marketplace add suboss87/fdeops
 /plugin install fdeops@fdeops
 ```
 
-**2. Bind once** - inside the client workspace (setup only; not a daily habit):
-
 ```bash
-npx fdeops resume --init garvey   # creates ~/fde-engagements/garvey engagement + binds workspace
+npx skills add suboss87/fdeops          # Cursor, Codex, skills-compatible hosts
 ```
 
-**Check it worked:**
+**2. Bind once** in the client workspace:
 
 ```bash
-npx fdeops resume                 # prints a short "where we are" for this client
+npx fdeops resume --init garvey   # ~/fde-engagements/garvey + bind this checkout
+npx fdeops resume                 # where we are
 ```
 
-**3. Work** - talk normally:
+**3. Work**
 
 ```text
-@fde I just got the brief. New client, payments platform, they want it live before their Q3 audit.
+@fde New client. Payments platform. They want it live before the Q3 audit.
 ```
 
-`@fde` routes and updates the fieldbook - you confirm judgment. Full workflow: [docs/USAGE.md](docs/USAGE.md).
+`@fde` routes and drafts; you confirm judgment. Workflow: [docs/USAGE.md](docs/USAGE.md).
+
+Working: `npx fdeops resume` prints this client's phase, trust, and next action. Tomorrow that file is still there. Auto-load at session start is Claude Code; elsewhere you invoke `@fde`.
 
 <details>
-<summary><strong>Other install paths</strong> · scan · env</summary>
+<summary>Other install paths · scan · env</summary>
 
-- **Cursor / Codex / Copilot / Gemini CLI:** `npx fdeops adapters .` - [adapters/](adapters/README.md)
-- **Local LLMs (Ollama, LM Studio, llama.cpp):** load `skills/fde/SKILL.md` as the system prompt - [guide](adapters/LOCAL-LLM.md)
-- **Manual / air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js`
-- **Try without install:** `npx fdeops scan` - day-1 recon (heuristic leads, not findings)
-- **Requires:** [Node.js](https://nodejs.org) >= 18 for the CLI and adapters
-- **Advanced:** `FDEOPS_ENGAGEMENT` overrides the workspace registry. Full matrix: [docs/install.md](docs/install.md)
+- **Adapters:** `npx fdeops adapters .` — [adapters/](adapters/README.md)
+- **Local LLMs:** load `skills/fde/SKILL.md` — [guide](adapters/LOCAL-LLM.md)
+- **Air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js`
+- **No install:** `npx fdeops demo` · `npx fdeops scan` (heuristic recon, not findings)
+- **Requires:** Node.js >= 18
+- **Override:** `FDEOPS_ENGAGEMENT` — [docs/install.md](docs/install.md)
 
 </details>
 
@@ -89,38 +102,48 @@ npx fdeops resume                 # prints a short "where we are" for this clien
 
 ## How it works
 
-- **You** describe the situation with `@fde` (or plain language once the skill is loaded)
-- **Session start / end** - small hooks load where you left off and capture what changed (no re-paste)
-- **Local CLI** - memory writes, search, and status with no model tokens; the agent runs it. You do not need to learn it for daily use ([docs/USAGE.md](docs/USAGE.md))
-- **Pluggable pull (ingest)** - FDEOps is the **sink**, not a connector pack. You add any source MCP (Granola, Notion, Drive, …) in Cursor/Claude; say `@fde connect …` for a guided config + recipe, then pull in plain language. Raw text → `.inbox/` → propose → you confirm → `.fde/`. No ambient sync; nothing unreviewed enters the fieldbook. See [mcp/recipes/](mcp/recipes/).
+- **You** describe the situation with `@fde` (or plain language once the skill is loaded).
+- **Hooks (Claude Code)** load where you left off and snapshot on the way out. Other hosts: same CLI and files; you call `@fde` / `resume`.
+- **Local CLI** — writes, receipts, status. Zero model tokens. The AI coding agent runs it; you do not live in the CLI. [docs/USAGE.md](docs/USAGE.md)
+- **Pull (optional)** — FDEOps is the sink. Paste is the daily path. A source MCP you add (Granola, Slack, Notion, …) can fetch text; `@fde connect …` walks config. No push, no sync, no tokens in `.fde/`. [mcp/recipes/](mcp/recipes/)
+
+`CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. The record lives at `~/fde-engagements/<client>/.fde/` — not inside any vendor. Change hosts, install `@fde` on the new one, bind if needed, keep talking.
+
+<details>
+<summary>Phase verbs (land → close)</summary>
 
-fdeops complements repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *client engagement* works.
+| Verb | When |
+|------|------|
+| **land** | First days — brief, stakeholders, success |
+| **discover** | The brief is wrong — evidence from the repo |
+| **plan** | Sequence backwards from done, PR-sized |
+| **build** | Blast radius, log what shipped |
+| **ship** | Pre-flight, canary, rollback |
+| **close** | Handoff, retro, receipts that survive you |
 
-### Switch coding agents anytime
+Overlays (AI, fintech, healthcare, gov) fire on signal. [docs/skills.md](docs/skills.md)
 
-The fieldbook lives on disk at `~/fde-engagements/<client>/.fde/` - not inside Claude, Cursor, or any other tool. Change AI coding agents and the **same client record** is still there.
+</details>
 
-On the new tool:
+---
 
-1. Install `@fde` for that tool (plugin, `npx skills add suboss87/fdeops`, or `npx fdeops adapters .` - see [adapters/](adapters/README.md))
-2. Open a workspace already bound with `npx fdeops resume --init <client>` (or bind once if this checkout is new)
-3. Talk with `@fde` or run `npx fdeops resume`
+## The field methods
 
-Same fieldbook. **Claude Code** gets the fullest ride (session start/stop hooks). Elsewhere the memory and CLI are the same; context usually loads when you ask `@fde` / `resume`, not automatically. Details: [docs/install.md](docs/install.md).
+You never pick one. You describe the situation; `@fde` routes. **37 methods**, six domains — each a method (thinking, artifact, checkpoint), not a tip sheet. [docs/skills.md](docs/skills.md) · [docs/skills-reference.md](docs/skills-reference.md)
 
 <details>
-<summary><strong>Phase verbs</strong> (land → close)</summary>
+<summary>All 37 methods</summary>
 
-| Verb | When |
-|------|------|
-| **land** | First days at a new client - interrogate the brief, map stakeholders, define success |
-| **discover** | The brief feels wrong - find the real problem, with evidence from the repo |
-| **plan** | Scope agreed - sequence it backwards from success, in PR-sized slices |
-| **build** | Ready to write code - declare blast radius, log deliveries as you ship |
-| **ship** | Going to production - pre-flight, canary, tested rollback |
-| **close** | Engagement ending - handoff doc, retrospective, receipts that survive you |
+| Domain | Methods |
+|--------|---------|
+| **1. Embed & Trust** | [land](skills/fde/references/land.md) · [audit](skills/fde/references/audit.md) · [stakeholder-radar](skills/fde/references/stakeholder-radar.md) · [trust-engineering](skills/fde/references/trust-engineering.md) · [scope-defense](skills/fde/references/scope-defense.md) |
+| **2. Discover & Diagnose** | [discover](skills/fde/references/discover.md) · [assumption-audit](skills/fde/references/assumption-audit.md) · [use-case-scoring](skills/fde/references/use-case-scoring.md) · [sketch](skills/fde/references/sketch.md) |
+| **3. Plan & Align** | [plan](skills/fde/references/plan.md) · [business-case](skills/fde/references/business-case.md) · [options-analysis](skills/fde/references/options-analysis.md) · [initiative-triage](skills/fde/references/initiative-triage.md) |
+| **4. Build & Guard** | [build](skills/fde/references/build.md) · [incremental-build](skills/fde/references/incremental-build.md) · [test-on-legacy](skills/fde/references/test-on-legacy.md) · [blast-radius](skills/fde/references/blast-radius.md) · [debug](skills/fde/references/debug.md) · [rescue](skills/fde/references/rescue.md) · [security-audit](skills/fde/references/security-audit.md) · [observability](skills/fde/references/observability.md) |
+| **5. Ship & Verify** | [ship](skills/fde/references/ship.md) · [review](skills/fde/references/review.md) · [rollback-drill](skills/fde/references/rollback-drill.md) · [qa-live](skills/fde/references/qa-live.md) |
+| **6. Operate & Close** | [status](skills/fde/references/status.md) · [demo-prep](skills/fde/references/demo-prep.md) · [debrief](skills/fde/references/debrief.md) · [exec-narrative](skills/fde/references/exec-narrative.md) · [dashboard](skills/fde/references/dashboard.md) · [multi-customer-ops](skills/fde/references/multi-customer-ops.md) · [close](skills/fde/references/close.md) · [handoff-engineering](skills/fde/references/handoff-engineering.md) · [pattern-extract](skills/fde/references/pattern-extract.md) · [red-team](skills/fde/references/red-team.md) · [ingest](skills/fde/references/ingest.md) · [ingest-connect](skills/fde/references/ingest-connect.md) |
 
-Overlays for regulated domains (AI, fintech, healthcare, government) activate on signal. Full matrix: [docs/skills.md](docs/skills.md).
+Overlays: [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references/artifacts.md) · [fintech](skills/fde/references/fintech.md) · [healthcare](skills/fde/references/healthcare.md) · [gov](skills/fde/references/gov.md)
 
 </details>
 
@@ -128,24 +151,24 @@ Overlays for regulated domains (AI, fintech, healthcare, government) activate on
 
 ## Engagement memory (`.fde/`)
 
-The **fieldbook** is the system of record for the embed - one folder per client, plain markdown you can read, grep, and take with you:
+One folder per client. Plain markdown. Grep it, copy it, defend it.
 
 | File | Holds |
 |------|-------|
-| `context.md` | Where you are - loaded first every session |
-| `brief.md` / `success.md` | What they asked for; what "done" means and who signs it off |
-| `reality.md` / `terrain.md` | The real problem; the codebase map |
-| `stakeholders.md` | Champions, resistance, `[signal:green\|amber\|red]` trust tokens |
+| `context.md` | Where you are |
+| `brief.md` / `success.md` | What they asked; what “done” is and who signs |
+| `reality.md` / `terrain.md` | The real problem; the map |
+| `stakeholders.md` | `[signal:green\|amber\|red]` |
 | `trust-profile.md` | Sacred data, AI policy, approval chain |
-| `decisions.md` / `risks.md` / `delivery.md` | Choices with dates; live risk register; what shipped and its rollback |
+| `decisions.md` / `risks.md` / `delivery.md` | Dated choices; live risks; what shipped and how it rolls back |
 
-Every entry is dated and sourced, so you can defend it in front of skeptical stakeholders. Schema: [docs/schema.md](docs/schema.md).
+Schema: [docs/schema.md](docs/schema.md).
 
 ---
 
 ## Fieldbook UI
 
-Open the system of record in a browser - trust, phase, next action, and the full record in one local page. Ask `@fde` for the dashboard, or run `npx fdeops dashboard` (current engagement by default; `--all` for the portfolio).
+Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops dashboard` (`--all` for the portfolio).
 
 <p align="center"><img width="1336" height="624" alt="fdeops Fieldbook in the browser" src="https://github.com/user-attachments/assets/5683614c-7730-4a3a-860d-185053a377eb" /></p>
 
@@ -153,54 +176,50 @@ Open the system of record in a browser - trust, phase, next action, and the full
 
 ## Who this is for
 
-| You are... | What fdeops does for you |
-|----------|-------------------|
-| **Forward Deployed Engineer** | The role this was built for - the full lifecycle, first meeting to final handoff |
-| **Consultant or contractor at a client site** | Remembers the engagement so you stop re-explaining it |
-| **Solutions architect / engineer** | Methods for the politics as well as the architecture |
-| **Agency developer running 3-5 clients** | One `.fde/` per client - details stop blurring |
-| **Fractional CTO doing client work** | The fieldbook is your system of record for the embed - and your audit trail for billable work |
+| You are | What this is |
+|---------|----------------|
+| **Forward Deployed Engineer** | The job this was built for — first meeting through handoff |
+| **Consultant / contractor on site** | The engagement stops resetting every morning |
+| **Solutions architect** | Politics and architecture in the same record |
+| **Agency, 3–5 clients** | One `.fde/` each — they stop blurring |
+| **Fractional CTO on client work** | System of record for the embed, and the billable trail |
 
 ---
 
 ## Your data stays yours
 
-- **Local only.** Pure `git` + file reads - no network calls, no telemetry, no account. Works air-gapped.
-- **Plain markdown.** No database, no lock-in.
-- **No new data path.** The AI sees client code only when *you* point your agent at it. `<private>` tags are redacted from CLI/dashboard/hook output; do not feed raw private blocks into the model (file tools bypass that redaction).
-- **Nothing enters the record unreviewed.** The model drafts, you confirm (`fde debrief --dry-run` shows the routing first); the hooks record only git facts. Your fieldbook stays yours to defend.
-- **Know your sync surface.** `~/fde-engagements` lives in your home directory - your backup and cloud-sync setup now covers client notes. `fde resume --init` warns if the folder sits in a synced path. Read [PRIVACY.md](PRIVACY.md) before your first NDA'd engagement.
+- **Local only.** `git` + files. No network, no telemetry, no account. Air-gapped is fine.
+- **Plain markdown.** No database.
+- **No new data path.** The model sees client code only when you point the AI coding agent at it. `<private>` is redacted from CLI, dashboard, and hooks — do not open raw private blocks with file tools.
+- **Nothing unreviewed.** Draft → you confirm. `fde debrief --dry-run` shows routing first.
+- **Know the sync surface.** `~/fde-engagements` is in `$HOME`. iCloud/Dropbox is an NDA incident waiting. `resume --init` warns. [PRIVACY.md](PRIVACY.md) before the first NDA.
 
-Details: [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
+[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
 
 ---
 
 ## Principles
 
-- **The artifact is the memory** - producing work and recording it are one action
-- **Methods, not autonomy** - each skill tells you what to check; the judgment, the trust, and the consequences stay yours
-- **Brief is a hypothesis** - discover before building the wrong thing
-- **Evidence on every claim** - these files get defended in front of skeptical clients
-- **One customer, one folder** - context never bleeds
+- **The artifact is the memory** — producing the work and recording it are one action
+- **Methods, not autonomy** — the kit says what to check; judgment stays yours
+- **Brief is a hypothesis** — discover before building the wrong thing
+- **Evidence on every claim** — these files get defended in the room
+- **One customer, one folder** — context never bleeds
 
 ---
 
 ## Updating
 
-```bash
-# Plugin / skills install: re-run the install command from Quickstart
-# From a git clone:
-cd fdeops && git pull && node bin/install.js
-```
+Re-run the Quickstart install, or from a clone: `git pull && node bin/install.js`
 
 ---
 
 ## Contributing
 
-Built and maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Share your feedback via [Issues](https://github.com/suboss87/fdeops/issues) - see [CONTRIBUTING.md](CONTRIBUTING.md).
+**[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. [Issues](https://github.com/suboss87/fdeops/issues) · [CONTRIBUTING.md](CONTRIBUTING.md)
 
-Thanks to builders whose craft helped sharpen the thinking behind this kit, among them [Andrej Karpathy](https://karpathy.ai/)'s engineering guidelines and the [agentic engineering workflow](https://github.com/pawel-cell/micky-podcast-agentic-engineering) notes from David Ondrej / Michael Shimeles. FDEOps itself is handcrafted for field work; any resemblance is inspiration, not a fork.
+Thanks to builders whose craft sharpened the thinking, among them [Andrej Karpathy](https://karpathy.ai/)'s engineering guidelines and the [agentic engineering workflow](https://github.com/pawel-cell/micky-podcast-agentic-engineering) notes from David Ondrej / Michael Shimeles. FDEOps is handcrafted for field work; resemblance is craft, not a fork.
 
-**What we won't build:** SaaS sync or Slack/Notion connectors inside the CLI, CRM as core, hardware capture, or generic code-craft skill packs (TDD/review already exist elsewhere - FDEOps owns the engagement, not the keyboard). The `fde` CLI stays local-only.
+**What we won't build:** SaaS sync; Slack/Notion/Granola connectors or **push** inside the CLI; CRM as core; hardware capture; generic code-craft packs (TDD/review live elsewhere). You may **pull** via *your* MCP. The `fde` CLI stays local-only.
 
-[FDE Methodology](FDE-METHODOLOGY.md) - [SECURITY.md](SECURITY.md) - [PRIVACY.md](PRIVACY.md) - [Repo layout](docs/REPO_LAYOUT.md) - [Skills matrix](docs/skills.md) - MIT
+[FDE Methodology](FDE-METHODOLOGY.md) · [SECURITY.md](SECURITY.md) · [PRIVACY.md](PRIVACY.md) · [Repo layout](docs/REPO_LAYOUT.md) · [Skills matrix](docs/skills.md) · MIT

package/adapters/LOCAL-LLM.md

@@ -62,7 +62,7 @@ The model reads SKILL.md, routes to the right skill, and produces artifacts in y
 
 ## Model size recommendations
 
-The methodology is detailed (35 skills, routing logic, evidence format, memory contract). Larger models handle it better:
+The methodology is detailed (37 methods, routing logic, evidence format, memory contract). Larger models handle it better:
 
 | Model class | Experience |
 |-------------|-----------|

package/adapters/README.md

@@ -31,4 +31,4 @@ Defaults to the current directory if no path is given. Existing files are never
 
 ## The principle
 
-The adapter only tells the tool **where the brain is and how to behave**. All the method - the 35 skills, the overlays, the memory contract - lives once in `skills/fde/SKILL.md`. Update the brain, every platform gets it. That's why fdeops feels native in whatever the FDE already uses, without five things to keep in sync.
+The adapter only tells the tool **where the brain is and how to behave**. All the method - the 37 methods, the overlays, the memory contract - lives once in `skills/fde/SKILL.md`. Update the brain, every platform gets it. That's why fdeops feels native in whatever the FDE already uses, without five things to keep in sync.

package/bin/check.js

@@ -76,6 +76,29 @@ for (const f of requiredReferences) {
 }
 ok('phase references')
 
+// A method reference teaches by showing one engagement, not by describing a shape:
+// every judgment-heavy reference carries a worked example that names the memory
+// file the work lands in. Prose-only guidance drifts into advice nobody can apply.
+const exampleReferences = [
+  'land.md', 'discover.md', 'plan.md', 'build.md', 'ship.md', 'close.md',
+  'status.md', 'stakeholder-radar.md', 'options-analysis.md', 'business-case.md',
+  'assumption-audit.md', 'scope-defense.md',
+]
+for (const f of exampleReferences) {
+  const p = path.join(root, 'skills', 'fde', 'references', f)
+  if (!fs.existsSync(p)) { fail(`missing method reference skills/fde/references/${f}`); continue }
+  const body = fs.readFileSync(p, 'utf8')
+  const section = (body.match(/\n## Worked example\n([\s\S]*?)(?=\n## |$)/) || [])[1]
+  if (!section) {
+    fail(`references/${f} missing ## Worked example`)
+  } else if (section.trim().length < 400) {
+    fail(`references/${f} worked example is too thin to teach anything`)
+  } else if (!/`[a-z-]+\.md`/.test(section)) {
+    fail(`references/${f} worked example never names the memory file the work lands in`)
+  }
+}
+ok(`worked examples (${exampleReferences.length} references)`)
+
 const router = read('skills/fde/SKILL.md')
 if (!router.includes('memory contract')) fail('SKILL.md must define the memory contract')
 // every references/<name>.md the router mentions must exist
@@ -88,6 +111,94 @@ for (const refFile of mentioned) {
 }
 ok(`router dispatch (${mentioned.length} reference targets verified) + memory contract`)
 
+// Public claims must match the router. The docs advertise a method count and a
+// per-domain list; both drifted from SKILL.md once (ingest / ingest-connect
+// routed but undocumented), and a number nobody can verify is worse than none.
+{
+  // Every routing row must parse. A row this misses is a method that could go
+  // undocumented for free, so an unparsed row is a hard failure, not a silent skip.
+  const routed = new Set()
+  const routing = (router.split('## Routing - 6 domains')[1] || '').split('**Overlays')[0]
+  const methodCell = line => (line.split('|')[2] || '').trim().replace(/\s*\([^)]*\)\s*$/, '')
+  for (const line of routing.split('\n')) {
+    if (!/^\|/.test(line)) continue
+    // A row that names a method but no reference would route that method while
+    // nothing requires anyone to document it - shape checks can only police rows
+    // they recognise, so name a method here and you must name its reference.
+    if (!/references\/[a-z0-9-]+\.md/.test(line)) {
+      const orphan = methodCell(line)
+      // a method name, not a `-` placeholder (CLI-only rows) or a `---` separator
+      if (/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(orphan)) {
+        fail(`SKILL.md routes '${orphan}' without naming a reference: ${line.trim().slice(0, 80)}`)
+      }
+      continue
+    }
+    // Candidate rows are selected on the reference name in ANY form, then the
+    // shape is enforced - a row this cannot read must fail, never be skipped,
+    // or a method could go undocumented by being written unusually.
+    if (!/`references\/[a-z0-9-]+\.md`/.test(line)) {
+      fail(`SKILL.md routing row must name its reference as \`references/<name>.md\`: ${line.trim().slice(0, 80)}`)
+      continue
+    }
+    // | You hear | <method> | <cell mentioning references/*.md> |
+    const method = methodCell(line)
+    if (!/^[a-z0-9-]+$/.test(method)) {
+      fail(`check.js cannot read the method name in a SKILL.md routing row: ${line.trim().slice(0, 80)}`)
+      continue
+    }
+    routed.add(method)
+  }
+  if (!routed.size) fail('check.js could not parse the SKILL.md routing table')
+
+  // docs/skills-reference.md is the canonical per-method list: one row per
+  // method inside the six domain tables, ending at the Overlays section.
+  const reference = read('docs/skills-reference.md')
+  const documented = new Set()
+  let documentedRows = 0
+  for (const line of reference.split('### Overlays')[0].split('\n')) {
+    const m = line.match(/^\|\s*\[([a-z0-9-]+)\]\(\.\.\/skills\/fde\/references\/([a-z0-9-]+\.md)\)/)
+    if (!m) continue
+    documentedRows++
+    documented.add(m[1])
+    // A link nobody followed is the same unverifiable claim this gate exists for:
+    // the target must exist, and it must be the method the text names.
+    if (m[2] !== `${m[1]}.md`) {
+      fail(`docs/skills-reference.md links [${m[1]}] at references/${m[2]}`)
+    } else if (!fs.existsSync(path.join(root, 'skills', 'fde', 'references', m[2]))) {
+      fail(`docs/skills-reference.md links references/${m[2]}, which does not exist`)
+    }
+  }
+  if (documented.size !== documentedRows) {
+    fail(`docs/skills-reference.md lists ${documentedRows} method rows for ${documented.size} methods - a duplicate row inflates the count`)
+  }
+  const undocumented = [...routed].filter(name => !documented.has(name))
+  if (undocumented.length) {
+    fail(`SKILL.md routes skill(s) missing from docs/skills-reference.md: ${undocumented.join(', ')}`)
+  }
+  // and the other direction: a documented method nothing routes to is a method
+  // the agent can never reach, advertised anyway.
+  const unrouted = [...documented].filter(name => !routed.has(name))
+  if (unrouted.length) {
+    fail(`docs/skills-reference.md documents method(s) SKILL.md never routes to: ${unrouted.join(', ')}`)
+  }
+  for (const rel of ['docs/skills.md', 'docs/skills-reference.md']) {
+    const body = read(rel)
+    // `-` is a word boundary, so \bingest\b matches inside `ingest-connect`:
+    // a method could disappear from the docs behind a hyphenated sibling.
+    const absent = [...documented].filter(name => !new RegExp(`(?<![\\w-])${name}(?![\\w-])`).test(body))
+    if (absent.length) fail(`${rel} does not list method(s): ${absent.join(', ')}`)
+    // every count claim, not just the first: an earlier sentence must not shadow
+    // a stale headline (or the reverse).
+    const claims = [...body.matchAll(/(\d+)\s+methods/g)].map(m => Number(m[1]))
+    if (!claims.length) fail(`${rel} must state how many methods it documents`)
+    const wrong = [...new Set(claims.filter(n => n !== documented.size))]
+    if (wrong.length) {
+      fail(`${rel} claims ${wrong.join('/')} methods; ${documented.size} are documented`)
+    }
+  }
+  ok(`public method count is verifiable (${documented.size} documented, ${routed.size} routed)`)
+}
+
 const install = read('bin/install.js')
 if (install.includes('scaffoldFdeInProject(process.cwd())')) {
   fail('install.js must not auto-scaffold .fde in customer cwd')
@@ -104,8 +215,34 @@ if (read('package.json').includes('postinstall')) {
 }
 
 const readme = read('README.md')
-if (readme.includes('demo.gif')) fail('README must not embed demo.gif (removed for clarity)')
-else ok('README no demo gif')
+// The README shows one recording: media/session.gif, a real CLI session.
+// media/demo.gif is a hand-typed mock kept for history - it must never be embedded,
+// or the front door shows output no command actually produced.
+if (readme.includes('demo.gif')) fail('README must not embed media/demo.gif (staged mock, not real CLI output)')
+else ok('README no staged demo gif')
+
+if (!readme.includes('media/session.gif')) {
+  fail('README must embed media/session.gif (the recorded session is the front door)')
+} else if (!readme.includes('media/record-session.sh')) {
+  fail('README must link media/record-session.sh next to the recording, so it can be re-recorded')
+} else {
+  const gifPath = path.join(root, 'media', 'session.gif')
+  const rec = path.join(root, 'media', 'record-session.sh')
+  if (!fs.existsSync(gifPath) || fs.statSync(gifPath).size < 50000) fail('media/session.gif missing or too small')
+  else if (!fs.existsSync(rec)) fail('media/record-session.sh missing - the recording must be reproducible')
+  else if (!fs.existsSync(path.join(root, 'media', 'session.cast'))) fail('media/session.cast missing - keep the source recording next to the gif')
+  else ok('README recorded session (gif + reproducible recorder + cast)')
+}
+
+// Every repo-relative README link and image must resolve, or the front door 404s.
+const brokenLinks = []
+for (const m of readme.matchAll(/(?:\]\(|src=")([^)"#\s]+)(?:\)|")/g)) {
+  const target = m[1]
+  if (/^(https?:|mailto:|#|\/)/.test(target)) continue
+  if (!fs.existsSync(path.join(root, target))) brokenLinks.push(target)
+}
+if (brokenLinks.length) fail(`README links to missing paths: ${brokenLinks.join(', ')}`)
+else ok('README links all resolve')
 
 for (const section of [
   'How it works',
@@ -180,7 +317,15 @@ if (!fs.existsSync(path.join(root, 'docs', 'schema.md'))) fail('docs/schema.md m
 else ok('docs/schema.md')
 
 if (!fs.existsSync(path.join(root, 'SECURITY.md'))) fail('SECURITY.md missing')
-else ok('SECURITY.md')
+else {
+  // A reporting section that only offers GitHub Security Advisories is a dead end
+  // whenever private reporting is off for the repo (that page 403s), which is how
+  // issue #9 sat unreported. Require a channel that does not depend on a repo setting.
+  const sec = read('SECURITY.md')
+  if (!/[\w.+-]+@[\w-]+\.[\w.]+/.test(sec)) {
+    fail('SECURITY.md must give a reporting channel that works when GitHub private reporting is off (an email address)')
+  } else ok('SECURITY.md (reachable reporting channel)')
+}
 
 const exampleFiles = ['reality.md', 'decisions.md', 'delivery.md', 'stakeholders.md', 'assumptions.md']
 for (const f of exampleFiles) {
@@ -354,13 +499,75 @@ if (!fs.existsSync(path.join(root, 'mcp', 'fdeops-ingest', 'server.js'))) {
 } else if (!fs.existsSync(path.join(root, 'skills', 'fde', 'references', 'ingest-connect.md'))) {
   fail('skills/fde/references/ingest-connect.md missing')
 } else {
-  for (const recipe of ['file.md', 'granola.md', 'notion.md']) {
+  for (const recipe of ['file.md', 'granola.md', 'slack.md', 'notion.md']) {
     if (!fs.existsSync(path.join(root, 'mcp', 'recipes', recipe))) fail(`mcp/recipes/${recipe} missing`)
   }
   if (!read('README.md').includes('mcp/recipes')) fail('README must point at mcp/recipes for connect clarity')
   ok('ingest MCP + connect recipes + skill reference')
 }
 
+// Agent Plugins 1.0.0 conformance (agent-plugins.org/specification).
+// plugin.json has a closed schema: an illegal field is fatal to the whole plugin,
+// and an mcp.json whose $schema version differs from plugin.json silently disables MCP.
+const AP_VERSION = '1.0.0'
+const AP_PLUGIN_SCHEMA = `https://agent-plugins.org/schemas/${AP_VERSION}/plugin.schema.json`
+const AP_MCP_SCHEMA = `https://agent-plugins.org/schemas/${AP_VERSION}/mcp.schema.json`
+const AP_MANIFEST_FIELDS = [
+  '$schema', 'name', 'version', 'description', 'author',
+  'homepage', 'repository', 'license', 'keywords', 'extensions',
+]
+
+const apManifest = JSON.parse(read('plugin.json'))
+const apUnknown = Object.keys(apManifest).filter(k => !AP_MANIFEST_FIELDS.includes(k))
+if (apManifest.$schema !== AP_PLUGIN_SCHEMA) {
+  fail(`plugin.json $schema must be ${AP_PLUGIN_SCHEMA}`)
+} else if (apUnknown.length) {
+  fail(`plugin.json has non-portable field(s) ${apUnknown.join(', ')} - client-specific data belongs under extensions`)
+} else if (!/^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(apManifest.name)) {
+  fail(`plugin.json name "${apManifest.name}" violates Agent Plugins name constraints`)
+} else if (apManifest.version !== pkg.version) {
+  fail(`version mismatch package.json ${pkg.version} vs plugin.json ${apManifest.version}`)
+} else ok('agent plugins manifest')
+
+const apMcp = JSON.parse(read('mcp.json'))
+const apServers = apMcp.mcpServers || {}
+if (apMcp.$schema !== AP_MCP_SCHEMA) {
+  fail(`mcp.json $schema must be ${AP_MCP_SCHEMA} (a version mismatch with plugin.json disables MCP)`)
+} else if (Object.keys(apMcp).some(k => k !== '$schema' && k !== 'mcpServers')) {
+  fail('mcp.json permits only $schema and mcpServers')
+} else {
+  for (const [name, srv] of Object.entries(apServers)) {
+    if (srv.type !== 'stdio') fail(`mcp.json ${name}: fdeops ships stdio servers only (local-only core)`)
+    else if (!srv.command || (/[\s/]/.test(srv.command) && !srv.command.startsWith('./'))) {
+      fail(`mcp.json ${name}: command must be one executable token or a ./-relative path`)
+    } else if ((srv.args || []).some(a => path.isAbsolute(a))) {
+      fail(`mcp.json ${name}: args must use \${PLUGIN_ROOT}, never an absolute path`)
+    } else if (Object.keys(srv.env || {}).some(k => k === 'PLUGIN_ROOT' || k === 'PLUGIN_DATA')) {
+      fail(`mcp.json ${name}: env must not set PLUGIN_ROOT/PLUGIN_DATA (client-supplied)`)
+    }
+  }
+  const ingest = apServers['fdeops-ingest']
+  const rootArg = ingest && (ingest.args || []).find(a => String(a).startsWith('${PLUGIN_ROOT}/'))
+  const target = rootArg ? String(rootArg).replace('${PLUGIN_ROOT}/', '') : ''
+  if (!ingest) fail('mcp.json must declare the fdeops-ingest stdio server')
+  else if (!rootArg) fail('mcp.json fdeops-ingest: args must include a ${PLUGIN_ROOT}-relative server path')
+  else if (!fs.existsSync(path.join(root, target))) fail(`mcp.json fdeops-ingest points at missing ${target}`)
+  else ok('agent plugins mcp config')
+}
+
+// A manifest that ships only in git and not in the npm tarball is the worst kind of drift.
+for (const manifest of ['plugin.json', 'mcp.json']) {
+  if (!(pkg.files || []).includes(manifest)) fail(`package.json files must include ${manifest}`)
+  else ok(`${manifest} published to npm`)
+}
+
+for (const entry of fs.readdirSync(path.join(root, 'skills'))) {
+  const dir = path.join(root, 'skills', entry)
+  if (!fs.statSync(dir).isDirectory()) continue
+  if (!fs.existsSync(path.join(dir, 'SKILL.md'))) fail(`skills/${entry}/ has no SKILL.md - clients skip it`)
+  else ok(`skill ${entry} discoverable`)
+}
+
 if (!fs.existsSync(path.join(root, '.github', 'ISSUE_TEMPLATE', 'bug_report.yml'))) {
   fail('GitHub issue template missing')
 } else ok('issue templates')