fdeops 3.17.0 → 3.21.0

package/AGENTS.md

@@ -4,7 +4,7 @@ This repository **is** fdeops - the engagement record for Forward Deployed Engin
 
 ## If you are helping use fdeops in an engagement
 
-Route via **`@fde`** - read `skills/fde/SKILL.md` (the single source of truth), pick the phase, do the work, and write `.fde/` memory. Never ask the human to pick a skill. Other tools get the same behavior through thin pointer files in [`adapters/`](adapters/README.md).
+Route via **`@fde`** - read `skills/fde/SKILL.md` (the single source of truth), route to one `references/*.md`, do the work, and write `.fde/` memory. Never ask the human to pick a skill. Other tools get the same behavior through thin pointer files in [`adapters/`](adapters/README.md).
 
 ## If you are contributing to this repository
 

package/README.md

@@ -2,89 +2,76 @@
 
 **Forward deployed engineering skills for AI coding agents.**
 
-Skills encode the workflows, quality gates, and judgment Forward Deployed Engineers use on someone else's site. Packaged so an AI coding agent can run the embed end-to-end: discovery, POC, their codebase (greenfield or brownfield), go-live, eval, signed outcome. The workspace still compiles and commits. `@fde` does not leave.
+You're on a customer site. The AI coding agent writes code in their repo. This kit is the work around that code: the brief, who can say yes, proof on their staging then live, whether they signed off, whether they can run it after you leave.
 
-<img width="1774" height="887" alt="FDEops-githubposter" src="https://github.com/user-attachments/assets/9eb842d2-a356-4995-9057-841f1b2d15d6" />
+Notes stay on your laptop. Their repo stays theirs. You confirm before anything is written down.
 
----
-
-## Commands
-
-Each command loads the same `@fde` skill. You never pick from 31 names.
+<img width="1536" height="1024" alt="fdeops" src="https://github.com/user-attachments/assets/2bcb8739-55ee-445d-8a1a-8b38433b7b58" />
 
-| What you're doing | Command | Key principle |
-|-------------------|---------|-----------|
-| First week on site | `/brief` | Name who signs done |
-| Find the real problem | `/discover` | Treat the brief as a hypothesis |
-| Sequence the work | `/plan` | Work backwards from done |
-| Ship to their production | `/ship` | One change they can see, then go live with a rollback you have run |
-| Get the number accepted | `/outcome` | Promised, measured, accepted |
-| Hand off so they run it | `/close` | They operate it without you |
+---
 
-Also:
+## Quick Start
 
-| What you're doing | Command | Key principle |
-|-------------------|---------|-----------|
-| Sponsor went quiet | `/trust` | Process gap, or they stopped trusting you |
-| When did we agree? | `/receipts` | A dated line, or it did not happen |
-| After a meeting | `/debrief` | Notes into the record |
-| Prep before the meeting | `/prep` | One page from the record |
-| Friday sponsor update | `/readout` | Promised, measured, accepted |
+**Try it first, nothing installed.** In any repo:
 
-Skills also activate on English: naming a client, running a POC, changing their checkout, going live, asking what was agreed. A throwaway one-liner in an unbound repo can skip `@fde`. Bound client work cannot.
+```bash
+npx fdeops scan
+```
 
----
+Two minutes. It prints what to look at on day one and the questions to ask. Local only, nothing written.
 
-## Quick Start
+**Then install the skill:**
 
 ```bash
 npx skills add suboss87/fdeops --skill fde
 ```
 
-Then one chat. Name the client. The AI coding agent binds.
+One chat. Name the client:
 
 ```text
-@fde this is Acme
+@fde this is client01
 ```
 
-Paste kickoff notes in the same thread. `@fde` routes; you confirm judgment. Same folder every time: `~/fde-engagements/<client>/.fde/`. Workflow: [docs/USAGE.md](docs/USAGE.md).
+That creates `~/fde-engagements/client01/.fde/` on your laptop. Paste kickoff notes in the same thread. `@fde` picks what to check. You still decide.
+
+Day to day: [docs/USAGE.md](docs/USAGE.md).
 
 <details>
-<summary><b>Claude Code (recommended)</b></summary>
+<summary><b>Claude Code</b></summary>
 
 ```text
 /plugin marketplace add suboss87/fdeops
 /plugin install fdeops@fdeops
 ```
 
-Hooks load where you left off. Slash commands match the map above.
+Hooks resume where you left off. Slash commands match the table below.
 
 </details>
 
 <details>
 <summary><b>Cursor</b></summary>
 
+After the skill install, in the **client repo** you have open (pointer, not a second pack):
+
 ```bash
-npx skills add suboss87/fdeops --skill fde
+npx fdeops adapters .
 ```
 
-Or `npx fdeops adapters .`. See [adapters/](adapters/README.md).
+See [adapters/](adapters/README.md).
 
 </details>
 
 <details>
-<summary><b>Other agents</b></summary>
+<summary><b>Air-gap, PATH, override</b></summary>
 
 ```bash
-npx skills add suboss87/fdeops --skill fde
+git clone https://github.com/suboss87/fdeops.git && node bin/install.js
 ```
 
-Gemini, Copilot, Codex, local LLMs: [adapters/](adapters/README.md). Air-gapped: `git clone https://github.com/suboss87/fdeops.git && node bin/install.js`.
-
-Fallback if the agent cannot bind:
+If the agent cannot create the folder:
 
 ```bash
-npx fdeops resume --init acme   # ~/fde-engagements/acme + bind this checkout
+npx fdeops resume --init client01   # ~/fde-engagements/client01
 ```
 
 Requires Node.js >= 18. Override: `FDEOPS_ENGAGEMENT`. See [docs/install.md](docs/install.md). Try the loop: `npx fdeops demo`.
@@ -93,71 +80,94 @@ Requires Node.js >= 18. Override: `FDEOPS_ENGAGEMENT`. See [docs/install.md](doc
 
 ---
 
+## Commands
+
+One command per stage. Skills load automatically.
+
+Six stages, same order every job: Land, Discover, Plan, Ship, Outcome, Close.
+
+| What you're doing | Command | Stage |
+|-------------------|---------|-------|
+| First days. Get the brief. Name who signs. | `/brief` | Land |
+| Check the brief is the real job. | `/discover` | Discover |
+| Sequence from done, not from the ticket. | `/plan` | Plan |
+| Prove it on their staging, then go live. | `/ship` | Ship |
+| What you promised, measured, and who accepted. | `/outcome` | Outcome |
+| Hand it over. They run it without you. | `/close` | Close |
+
+Same `@fde`, when you need them: `/debrief` (notes into the record), `/prep` (one page before you walk in), `/trust` (process gap, or they stopped trusting you), `/receipts` (a dated line, or it did not happen), `/readout` (Friday page for the sponsor; not a seventh stage).
+
+You can also just say it: naming a client, a POC, changing their checkout, going live, asking what was agreed. A typo in a repo that is not a client job can skip this. A named client, a POC, or go-live cannot.
+
+---
+
 ## All 30 Skills
 
-The commands above are the entry points. Under the hood, `@fde` activates these 30 skills, each a structured workflow with steps, an artifact, and a checkpoint. You never pick one by name. Full detail: [docs/skills-reference.md](docs/skills-reference.md).
+Thirty situations, grouped by stage. Not prompts - each one has steps, a file it writes, and a checkpoint with you. Type English or a slash command. `@fde` opens the matching skill. You never pick one by name.
+
+Full detail: [docs/skills-reference.md](docs/skills-reference.md).
 
-### Land - Brief and trust
+### Land
 
-| Skill | What It Does | Use When |
+| Skill | What it does | Use when |
 |--------|--------------|----------|
-| [land](skills/fde/references/land.md) | Interrogate the brief, map stakeholders, define success | New client, first meeting, just got the brief |
-| [audit](skills/fde/references/audit.md) | Verify claims, find the load-bearing wall | Taking over, previous consultant left |
-| [who-decides](skills/fde/references/who-decides.md) | Who decides, who blocks, who escalates | Need to know who matters |
-| [earn-trust](skills/fde/references/earn-trust.md) | Observer → trusted; navigate AI policy | Need access or credibility |
-| [hold-scope](skills/fde/references/hold-scope.md) | Scope receipts; the accumulation conversation | "Also can you…", timeline unchanged |
+| [land](skills/fde/references/land.md) | Interrogate the brief | New client, first meeting, just got the brief |
+| [audit](skills/fde/references/audit.md) | Verify inherited claims | Taking over, previous consultant left |
+| [who-decides](skills/fde/references/who-decides.md) | Map decision rights | Need to know who matters |
+| [earn-trust](skills/fde/references/earn-trust.md) | Earn access | Need access or credibility |
+| [hold-scope](skills/fde/references/hold-scope.md) | Hold scope | "Also can you…", timeline unchanged |
 
-### Discover - Find the real problem
+### Discover
 
-| Skill | What It Does | Use When |
+| Skill | What it does | Use when |
 |--------|--------------|----------|
-| [discover](skills/fde/references/discover.md) | Question first, then repo + workaround | Brief feels wrong, shadow processes |
-| [test-assumptions](skills/fde/references/test-assumptions.md) | Untested assumptions by blast radius | Brief feels too neat |
-| [score-use-cases](skills/fde/references/score-use-cases.md) | Value × urgency × alignment / complexity | Everything is P0 |
-| [poc](skills/fde/references/poc.md) | Kill the killer assumption in a day | POC, spike, need to de-risk |
+| [discover](skills/fde/references/discover.md) | Frame the problem | Brief feels wrong, shadow processes |
+| [test-assumptions](skills/fde/references/test-assumptions.md) | Test assumptions | Brief feels too neat |
+| [score-use-cases](skills/fde/references/score-use-cases.md) | Score use cases | Everything is P0 |
+| [poc](skills/fde/references/poc.md) | Validate the solution | POC, spike, need to de-risk |
 
-### Plan - Sequence the work
+### Plan
 
-| Skill | What It Does | Use When |
+| Skill | What it does | Use when |
 |--------|--------------|----------|
-| [plan](skills/fde/references/plan.md) | Backwards from done, Kill if on each PR | What order, what is done |
-| [business-case](skills/fde/references/business-case.md) | Cost of nothing → investment → return | Defend budget or timeline |
-| [three-options](skills/fde/references/three-options.md) | Three genuine options | "What should we do?" |
-| [pick-three](skills/fde/references/pick-three.md) | Pick three from twenty urgents | Everything is urgent |
+| [plan](skills/fde/references/plan.md) | Sequence the work | What order, what is done |
+| [business-case](skills/fde/references/business-case.md) | Build the business case | Defend budget or timeline |
+| [three-options](skills/fde/references/three-options.md) | Generate options | "What should we do?" |
+| [pick-three](skills/fde/references/pick-three.md) | Prioritize three | Everything is urgent |
 
-### Ship - On their repo, then live
+### Ship
 
-| Skill | What It Does | Use When |
+| Skill | What it does | Use when |
 |--------|--------------|----------|
-| [ship](skills/fde/references/ship.md) | One change they can see (greenfield or brownfield), proven on their staging, then go live | Building, updating, or going live |
-| [what-breaks](skills/fde/references/what-breaks.md) | Impact from contained → irreversible | Touching shared infrastructure |
-| [rescue](skills/fde/references/rescue.md) | Production fire or trust fire | Down, or they went quiet |
-| [review](skills/fde/references/review.md) | Did we only build what we agreed | Before merge, scope creep |
-| [rollback](skills/fde/references/rollback.md) | Test the escape route before 2am | "We can always revert" |
+| [ship](skills/fde/references/ship.md) | Deliver the increment | Building, updating, or going live |
+| [what-breaks](skills/fde/references/what-breaks.md) | Assess impact | Touching shared infrastructure |
+| [rescue](skills/fde/references/rescue.md) | Resolve the incident | Down, or they went quiet |
+| [review](skills/fde/references/review.md) | Review the change | Before merge, scope creep |
+| [rollback](skills/fde/references/rollback.md) | Rehearse rollback | "We can always revert" |
 
-### Outcome - Get the number accepted
+### Outcome
 
-| Skill | What It Does | Use When |
+| Skill | What it does | Use when |
 |--------|--------------|----------|
-| [readout](skills/fde/references/readout.md) | Promised → measured → accepted | Friday, sponsor update |
-| [demo-prep](skills/fde/references/demo-prep.md) | One number, five hard questions | Demo or exec walkthrough |
-| [debrief](skills/fde/references/debrief.md) | Meeting notes into the record | Just left a meeting |
-| [board-memo](skills/fde/references/board-memo.md) | Board / sponsor's boss | Justify continued investment |
-| [dashboard](skills/fde/references/dashboard.md) | Portfolio, trust-ordered | All my customers |
-| [ingest](skills/fde/references/ingest.md) | Pull text you confirm | Transcript, Notion, Slack |
-| [connect](skills/fde/references/connect.md) | Wire a source MCP | Connect Granola |
+| [readout](skills/fde/references/readout.md) | Report the outcome | Friday, sponsor update |
+| [demo-prep](skills/fde/references/demo-prep.md) | Prepare the demo | Demo or exec walkthrough |
+| [debrief](skills/fde/references/debrief.md) | Capture the meeting | Just left a meeting |
+| [board-memo](skills/fde/references/board-memo.md) | Brief the board | Justify continued investment |
+| [dashboard](skills/fde/references/dashboard.md) | View the portfolio | All my customers |
+| [ingest](skills/fde/references/ingest.md) | Ingest sources | Transcript, Notion, Slack |
+| [connect](skills/fde/references/connect.md) | Connect a source | Connect Granola |
 
-### Close - They run it
+### Close
 
-| Skill | What It Does | Use When |
+| Skill | What it does | Use when |
 |--------|--------------|----------|
-| [close](skills/fde/references/close.md) | Handoff that survives you | Wrapping up |
-| [runbook](skills/fde/references/runbook.md) | Runbook, confidence scoring | They must operate without you |
-| [switch-clients](skills/fde/references/switch-clients.md) | Switch without bleed | 2+ clients |
-| [encode-pattern](skills/fde/references/encode-pattern.md) | If you did it twice, encode it | It will apply again |
-| [red-team](skills/fde/references/red-team.md) | Stress-test before they do | "Poke holes in this" |
+| [close](skills/fde/references/close.md) | Transfer operations | Wrapping up |
+| [runbook](skills/fde/references/runbook.md) | Write the runbook | They must operate without you |
+| [switch-clients](skills/fde/references/switch-clients.md) | Switch engagements | 2+ clients |
+| [encode-pattern](skills/fde/references/encode-pattern.md) | Encode the pattern | It will apply again |
+| [red-team](skills/fde/references/red-team.md) | Challenge the plan | "Poke holes in this" |
 
-Overlays (on signal, not on request): [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) · [eval-pack](skills/fde/references/eval-pack.md)
+Overlays (on signal, not on request): [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). AI companion (not a sixth overlay): [eval-pack](skills/fde/references/eval-pack.md).
 
 Optional pull: you add the source MCP; we **pull** on request. [mcp/recipes/](mcp/recipes/)
 
@@ -165,31 +175,84 @@ Optional pull: you add the source MCP; we **pull** on request. [mcp/recipes/](mc
 
 ## How Skills Work
 
-One skill. One reference file per situation. One folder per client.
+One `@fde`. One file per situation. One folder per client.
 
 ```
-  /brief   or   "@fde this is Acme"
-           │
-           ▼
-  skills/fde/SKILL.md          hosts load this one file
+  "@fde this is client01"      creates ~/fde-engagements/client01/.fde/
+  /brief  or  English          the AI coding agent loads skills/fde/SKILL.md
            │  routes. you never pick a skill by name
            ▼
-  references/land.md           one workflow, then stop
+  references/<one>.md          one skill, then stop
            │
            ▼
   fde CLI (local)              dates, gates, redacts. no network
            │  after you confirm
            ▼
-  ~/fde-engagements/<client>/.fde/
+  ~/fde-engagements/client01/.fde/
 ```
 
-- **Process, not prose.** Each reference is a workflow with an artifact and a checkpoint, not a tip sheet.
-- **Ground loop.** Name → characterise → prove where they live → go live → log. The workspace compiles; `@fde` stays.
-- **You confirm.** Nothing is written until you say so.
-- **Progressive disclosure.** `SKILL.md` is the entry point. One `references/*.md` loads when routed.
-- **Local CLI.** Writes and status cost zero model tokens. The AI coding agent runs it.
+**A dated line, or it did not happen.** Promised → measured → accepted. If it is not in `.fde/`, it is not on the record.
+
+**Confirm, then it is written.** The CLI stays on your laptop: git and files, no network. The AI coding agent runs the command. You say yes. Then it is in the folder.
 
-Change hosts, install `@fde` on the new one, bind if needed, keep talking. The record is not inside any vendor.
+**The record is on your laptop.** Change hosts, install `@fde` on the new one, keep talking. The notes are not inside any vendor.
+
+One skill hosts load: `skills/fde/SKILL.md`. It opens one file in `skills/fde/references/` and stops. Slash commands live in `.claude/commands/`. The local CLI is `bin/fde.js` (git + files, no network). Layout: [docs/REPO_LAYOUT.md](docs/REPO_LAYOUT.md).
+
+---
+
+## Engagement memory (`.fde/`)
+
+One folder per client. Plain markdown. Grep it, copy it, take it into a meeting.
+
+| File | Holds |
+|------|-------|
+| `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` | Dated choices; live risks; what shipped and how it rolls back |
+
+Schema: [docs/schema.md](docs/schema.md). Local HTML: `npx fdeops dashboard`.
+
+---
+
+## Who this is for
+
+You sit with a customer's team. An AI coding agent writes in their repo. You need a record of the brief, who can say yes, what went live, and whether they signed off.
+
+If you ship your own company's product from HQ, with no customer team that has to run it after you leave, you do not need this kit.
+
+---
+
+## Your data stays yours
+
+The **CLI** is local: git + files, no network, no telemetry. The **host model** sees `.fde/` the agent loads (usually a bounded `context.md`) and any client code you open. It must not see `<private>` blocks - redacted from CLI, dashboard, and hooks; do not paste them or open them with file tools. Nothing is written until you confirm. `~/fde-engagements` is in `$HOME`; iCloud/Dropbox is an NDA incident waiting.
+
+[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
+
+---
+
+## Why FDEOps?
+
+AI coding agents are built for a repo, not for a client. Left alone they skip who signs, whether the brief is true, and whether anyone accepted the number. Monday they start from the ticket again.
+
+This is the kit you take on site. `@fde` runs the client work around the code. A local command dates every decision. The notes are markdown on your laptop. You confirm; then it is on the record.
+
+---
+
+## Principles
+
+- **Who signs** - name them in the first days
+- **Brief vs real job** - check the floor, not only the slide
+- **Back from done** - sequence from signed-off, not from the ticket
+- **Their staging then live** - prove it where they operate, then go live
+- **Promised, measured, accepted** - a number nobody signed is claimed, not delivered
+- **They run it** - if they cannot operate it without you, you are not done
+- **A dated line, or it did not happen** - these files get defended in the room
+- **One customer, one folder** - context never bleeds
+- **The kit says what to check. You still decide.**
 
 ---
 
@@ -252,7 +315,7 @@ fdeops/
 ├── bin/                                   # local CLI: git + files, no network
 ├── hooks/                                 # session-start / session-stop / pre-compact
 ├── adapters/                              # Cursor, Gemini, Copilot, Codex pointers
-├── templates/.fde/                        # memory files created on bind
+├── templates/.fde/                        # memory files created on first client
 ├── examples/                              # fictional walkthroughs
 ├── mcp/                                   # optional ingest + source recipes
 ├── evals/                                 # routing checks
@@ -261,58 +324,6 @@ fdeops/
 
 ---
 
-## Why FDEOps?
-
-AI coding agents are built for a repo, not for a client. They forget the sponsor, the promise, who can say yes, and whether anyone accepted the number. Monday morning they start from the ticket again.
-
-FDEOps is what you take on site. One `@fde` skill runs the embed from discovery to signed outcome: POC, their codebase, go-live, eval when a model judges, promised → measured → accepted. A local CLI dates every decision. `.fde/` is markdown on your laptop. You confirm; then it is on the record.
-
----
-
-## Engagement memory (`.fde/`)
-
-One folder per client. Plain markdown. Grep it, copy it, defend it.
-
-| File | Holds |
-|------|-------|
-| `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` | Dated choices; live risks; what shipped and how it rolls back |
-
-Schema: [docs/schema.md](docs/schema.md). Local HTML: `npx fdeops dashboard`.
-
----
-
-## Who this is for
-
-You embed with a customer and an AI coding agent. Take this on the ground. Discovery through signed outcome lives in `@fde`. One `.fde/` per client so they do not blur.
-
-If you only write code in your own repo with no client record to defend, you do not need this kit.
-
----
-
-## Your data stays yours
-
-Local only - `git` + files, no network, no telemetry. Plain markdown. The model sees client code only when you point the AI coding agent at it. `<private>` is redacted from CLI, dashboard, and hooks. Nothing is written until you confirm. `~/fde-engagements` is in `$HOME`; iCloud/Dropbox is an NDA incident waiting.
-
-[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
-
----
-
-## Principles
-
-- **The artifact is the memory** - producing the work and recording it are one action
-- **Ground loop** - name the change, characterise their code, prove it on their staging, go live, log the outcome
-- **Skills, 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
-
----
-
 ## Contributing
 
 **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. [Issues](https://github.com/suboss87/fdeops/issues) · [Discussions](https://github.com/suboss87/fdeops/discussions) · [CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)

package/adapters/AGENTS.md

@@ -6,7 +6,7 @@ You are the AI coding agent for a **Forward Deployed Engineer (FDE)** - the huma
 
 When the FDE types **`@fde`**, names a client, pastes meeting notes, asks what was agreed, or describes embed work (quiet sponsor, brief feels wrong, Friday update) - load the skill. If `fde resume` says NO ENGAGEMENT: ask the client name once, then **you** run `fde resume --init <slug>`. Never tell them to type it.
 
-Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client, stay on `@fde` for POC, small PRs, characterisation, proof on their staging, eval, and go-live.
+Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client, stay on `@fde` for POC, the change on their repo, characterisation, proof on their staging, eval, and go-live.
 
 - Skill (single source of truth): `~/.claude/skills/fde/SKILL.md`
 - **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work.

package/adapters/GEMINI.md

@@ -6,7 +6,7 @@ Context for Gemini CLI when assisting a **Forward Deployed Engineer (FDE)** - th
 
 When the FDE types **`@fde`**, names a client, pastes meeting notes, asks what was agreed, or describes embed work (quiet sponsor, brief feels wrong, Friday update) - load the skill. If `fde resume` says NO ENGAGEMENT: ask the client name once, then **you** run `fde resume --init <slug>`. Never tell them to type it.
 
-Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client, stay on `@fde` for POC, small PRs, characterisation, proof on their staging, eval, and go-live.
+Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client, stay on `@fde` for POC, the change on their repo, characterisation, proof on their staging, eval, and go-live.
 
 - Skill (single source of truth): `~/.claude/skills/fde/SKILL.md`
 - **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work.

package/adapters/LOCAL-LLM.md

@@ -4,7 +4,7 @@ Use fdeops with **any local model** - Ollama, LM Studio, llama.cpp, vLLM, Open W
 
 ## Why it works
 
-fdeops is a SKILL.md file + markdown memory + a Node.js CLI. It calls no external API. The AI does the methodology; the CLI does the mechanics. Any model that can read a markdown system prompt can run fdeops.
+fdeops is a SKILL.md file + markdown memory + a Node.js CLI. It calls no external API. The AI does the skills; the CLI does the mechanics. Any model that can read a markdown system prompt can run fdeops.
 
 ## Setup
 
@@ -62,12 +62,12 @@ The model reads SKILL.md, routes to the right skill, and produces artifacts in y
 
 ## Model size recommendations
 
-The methodology is detailed (30 skills, routing logic, evidence format, memory contract). Larger models handle it better:
+The kit is detailed (30 skills, routing logic, evidence format, memory contract). Larger models handle it better:
 
 | Model class | Experience |
 |-------------|-----------|
 | **7-8B** (Llama 3.1 8B, Mistral 7B, Qwen 2.5 7B) | Handles individual skills (readout, log, land). May struggle with complex routing or multi-skill sessions. Good for the CLI-heavy workflow where you invoke skills explicitly. |
-| **13-34B** (Llama 3.1 13B, Mixtral 8x7B, Qwen 2.5 32B, DeepSeek-R1 32B) | Good across all domains. Routes correctly, follows memory contract, writes structured artifacts. Recommended minimum for full methodology use. |
+| **13-34B** (Llama 3.1 13B, Mixtral 8x7B, Qwen 2.5 32B, DeepSeek-R1 32B) | Good across all domains. Routes correctly, follows memory contract, writes structured artifacts. Recommended minimum for full use. |
 | **70B+** (Llama 3.1 405B, DeepSeek V3, Qwen 2.5 72B) | Full capability. Handles regulated overlays, switch-clients, board-memo pyramid, runbook handoff. |
 
 ## The CLI works without ANY model
@@ -105,6 +105,6 @@ ollama run my-fde-model --system "$(cat skills/fde/SKILL.md)"
 ## Tips for local models
 
 - **Context window matters.** SKILL.md + references can be large. Use a model with at least 8K context; 32K+ is ideal for loading skill references on demand.
-- **Temperature 0.2-0.4 works best.** The methodology is structured - lower temperature keeps routing accurate and artifacts consistent.
+- **Temperature 0.2-0.4 works best.** The skills are structured - lower temperature keeps routing accurate and artifacts consistent.
 - **Use the CLI for mechanics.** Don't ask the model to do what the CLI already does deterministically. Use `fde scan` for repo recon, `fde log` for memory writes, `fde receipts` for searching. Let the model handle judgment, routing, and artifact drafting.
-- **Explicit skill invocation.** If a smaller model struggles with routing, you can invoke skills directly: "@fde run the discover phase" or "@fde use hold-scope." The model skips routing and goes straight to the method.
+- **Explicit skill invocation.** If a smaller model struggles with routing, you can invoke skills directly: "@fde run the discover phase" or "@fde use hold-scope." The model skips routing and goes straight to the skill.

package/adapters/README.md

@@ -2,7 +2,7 @@
 
 **One brain, thin adapters.** fdeops has a single source of truth - the `@fde` skill at `skills/fde/SKILL.md` and the `fde` CLI. Each AI coding tool discovers it through a small pointer file in the place that tool already looks. No forked logic, no five copies to maintain - every adapter says the same thing: *route via `@fde`, read/write `.fde/` memory, talk like a peer, never touch what isn't yours.*
 
-**Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements/<client>/.fde/`. Point a new tool at a bound workspace, drop adapters (or install the skill/plugin for that tool), and the same client record opens. Auto session hooks are Claude Code-first; elsewhere load via `@fde` / `fde resume`. See [README § How it works](../README.md#how-it-works).
+**Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements/<client>/.fde/`. Point a new tool at a bound workspace, drop adapters (or install the skill/plugin for that tool), and the same client record opens. Auto session hooks are Claude Code-first; elsewhere load via `@fde` / `fde resume`. See [README § How Skills Work](../README.md#how-skills-work).
 
 ## What goes where
 

package/adapters/copilot-instructions.md

@@ -6,7 +6,7 @@ You are the AI coding agent for a **Forward Deployed Engineer (FDE)** - the huma
 
 When the FDE types **`@fde`**, names a client, pastes meeting notes, asks what was agreed, or describes embed work (quiet sponsor, brief feels wrong, Friday update) - load the skill. If `fde resume` says NO ENGAGEMENT: ask the client name once, then **you** run `fde resume --init <slug>`. Never tell them to type it.
 
-Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client, stay on `@fde` for POC, small PRs, characterisation, proof on their staging, eval, and go-live.
+Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client, stay on `@fde` for POC, the change on their repo, characterisation, proof on their staging, eval, and go-live.
 
 - Skill (single source of truth): `~/.claude/skills/fde/SKILL.md`
 - **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work.

package/adapters/cursor.fde.mdc

@@ -11,7 +11,7 @@ You are the AI coding agent for a **Forward Deployed Engineer (FDE)** - the huma
 
 When the FDE types **`@fde`**, names a client, pastes meeting notes, asks what was agreed, or describes embed work (quiet sponsor, brief feels wrong, Friday update) - load `@fde`. If `fde resume` says NO ENGAGEMENT: ask the client name once, then **you** run `fde resume --init <slug>`. Never tell them to type it.
 
-Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client, stay on `@fde` for POC, small PRs, characterisation, proof on their staging, eval, and go-live.
+Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client, stay on `@fde` for POC, the change on their repo, characterisation, proof on their staging, eval, and go-live.
 
 - Skill (single source of truth): `~/.claude/skills/fde/SKILL.md` (or the copy this install placed)
 - **Never ask the FDE to pick a skill.** Read the situation, route silently, do the work.

package/bin/check.js

@@ -57,7 +57,7 @@ for (const dir of fs.readdirSync(path.join(root, 'skills'))) {
 ok('skills structure')
 
 if (fs.existsSync(path.join(root, 'skills', 'fde', 'archive'))) {
-  fail('skills/fde/archive must not exist - unrouted methods are dead code')
+  fail('skills/fde/archive must not exist - unrouted skills are dead code')
 } else ok('no archived skill dump')
 
 // v3: one skill + phase references (progressive disclosure)
@@ -153,8 +153,8 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
   }
   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.
+  // docs/skills-reference.md is the canonical per-skill list: one row per
+  // skill inside the six stage tables, ending at the Overlays section.
   const reference = read('docs/skills-reference.md')
   const documented = new Set()
   let documentedRows = 0
@@ -164,7 +164,7 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
     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.
+    // the target must exist, and it must be the skill 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]))) {
@@ -172,13 +172,13 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
     }
   }
   if (documented.size !== documentedRows) {
-    fail(`docs/skills-reference.md lists ${documentedRows} method rows for ${documented.size} methods - a duplicate row inflates the count`)
+    fail(`docs/skills-reference.md lists ${documentedRows} skill rows for ${documented.size} skills - 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
+  // and the other direction: a documented skill nothing routes to is a skill
   // the agent can never reach, advertised anyway.
   const unrouted = [...documented].filter(name => !routed.has(name))
   if (unrouted.length) {
@@ -187,7 +187,7 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
   for (const rel of ['docs/skills.md', 'docs/skills-reference.md']) {
     const body = read(rel)
     // `-` is a word boundary, so \bscore\b matches inside `score-use-cases`:
-    // a method could disappear from the docs behind a hyphenated sibling.
+    // a skill 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 skill(s): ${absent.join(', ')}`)
     const claims = [...body.matchAll(/(\d+)\s+skills/g)].map(m => Number(m[1]))
@@ -201,16 +201,23 @@ ok(`router dispatch (${mentioned.length} reference targets verified) + memory co
 
   const refDir = path.join(root, 'skills', 'fde', 'references')
   const extra = fs.readdirSync(refDir).filter(f => f.endsWith('.md') && !mentioned.includes(f))
-  if (extra.length) fail(`unrouted reference file(s) - dead method: ${extra.join(', ')}`)
+  if (extra.length) fail(`unrouted reference file(s) - dead skill: ${extra.join(', ')}`)
   else ok('no unrouted reference files')
 
-  // The on-site change loop lives in ship.md. A sibling method is a split.
+  // The on-site change loop lives in ship.md. A sibling skill is a split.
   for (const dead of ['small-prs.md', 'thin-slices.md', 'implement.md']) {
     if (fs.existsSync(path.join(refDir, dead))) {
       fail(`${dead} must not exist - that craft lives in ship.md`)
     }
   }
-  ok('ship is one method (no implement / small-prs / thin-slices sibling)')
+  ok('ship is one skill (no implement / small-prs / thin-slices sibling)')
+
+  if (/^### Prove\b/m.test(read('skills/fde/SKILL.md'))) {
+    fail('SKILL.md must not use Prove as a stage heading - the public stage is Outcome')
+  } else ok('SKILL.md stage heading is Outcome')
+  if (/\b31 names\b|\b31 skills\b/.test(read('README.md'))) {
+    fail('README must not advertise 31 skills')
+  } else ok('README skill count is 30')
 }
 
 const install = read('bin/install.js')
@@ -349,6 +356,18 @@ for (const rx of derivativeFraming) {
 if (/docs\/internal|PMF_360/i.test(readme)) {
   fail('README must not link docs/internal or PMF_360')
 }
+if (!/One command per stage/.test(readme) || !/Skills load automatically/.test(readme)) {
+  fail('README must formulate Commands as: one command per stage, skills load automatically')
+}
+if (!/Not prompts/.test(readme)) {
+  fail('README catalog must say skills are not prompts')
+}
+if (/\b(30|31|37)\s+methods\b|\broutes methods\b|\bphase methods\b|\bfield methods\b|\bengagement methods\b/.test(readme)) {
+  fail('README must call the catalog skills, not methods')
+}
+if (/\broutes methods\b|\bphase methods\b|\bengagement methods\b/.test(usage)) {
+  fail('docs/USAGE.md must call them skills, not methods')
+}
 ok('README tone')
 
 if (fs.existsSync(path.join(root, '.codex')) || fs.existsSync(path.join(root, '.opencode'))) {