diff --git a/README.md b/README.md
index d81a610..0d10809 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,15 @@
# FDEOps
-**Your AI coding agent forgets your client every morning. fdeops remembers.**
+**Your AI coding agent forgets your client every morning. FDEOps remembers.**
[](https://www.npmjs.com/package/fdeops)
[](https://github.com/suboss87/fdeops/actions)
[](LICENSE)
[](https://nodejs.org)
-**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.
+Skill packs teach your AI coding agent how to *build*. None of them remember who the client is, what you promised, or who agreed it was delivered. FDEOps adds that layer: a private fieldbook per engagement (`.fde/`), a field methodology from land to close, and one `@fde` skill that routes it.
-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).
+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, on your laptop.
```
land discover plan build ship close
@@ -19,30 +19,21 @@ Built for Forward Deployed Engineers, and anyone embedded in client work: consul
written as a side effect of the work
```
-Talk in plain language with `@fde`. The AI coding agent runs the plumbing. You confirm anything that enters the record.
-
---
-## The week
+## A real session
-`@fde` plus English. No cheat sheet.
+Kickoff notes go in messy. You confirm what enters the record. A cold session the next morning already knows the client, the sponsor brief is grounded in dated facts, and the receipts survive the argument. Real CLI output - only the typing pace is staged, and you can [re-record it yourself](media/record-session.sh).
-| When | What you say | What you get |
-|------|--------------|--------------|
-| **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 folder every time: `~/fde-engagements//.fde/`.
+Nothing to install to see it on a fake client: `npx fdeops demo`.
---
## Quickstart
-**1. Install.** Claude Code: session hooks (context before you type). Everywhere else: the same fieldbook, loaded when you ask.
+**1. Install** on your machine - never in the customer's repo.
```text
/plugin marketplace add suboss87/fdeops
@@ -53,6 +44,8 @@ Same folder every time: `~/fde-engagements//.fde/`.
npx skills add suboss87/fdeops # Cursor, Codex, skills-compatible hosts
```
+Claude Code additionally gets session hooks, so context arrives before you type. Everywhere else it is the same fieldbook, loaded when you ask.
+
**2. Bind once** in the client workspace:
```bash
@@ -60,46 +53,74 @@ npx fdeops resume --init garvey # ~/fde-engagements/garvey + bind this checkou
npx fdeops resume # where we are
```
-**3. Work**
+**3. Work** in plain language:
```text
@fde New client. Payments platform. They want it live before the Q3 audit.
```
-`@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`.
+**It is working if** `npx fdeops resume` prints this client's phase, trust signal, and next action - and prints the same thing tomorrow, from a new session, with no explaining. Full workflow: [docs/USAGE.md](docs/USAGE.md).
Other install paths · scan · env
-- **Adapters:** `npx fdeops adapters .` — [adapters/](adapters/README.md)
-- **Local LLMs:** load `skills/fde/SKILL.md` — [guide](adapters/LOCAL-LLM.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)
+- **Override:** `FDEOPS_ENGAGEMENT` - [docs/install.md](docs/install.md)
---
+## The week
+
+`@fde` plus English. No cheat sheet.
+
+| When | What you say | What you get |
+|------|--------------|--------------|
+| **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 folder every time: `~/fde-engagements//.fde/`.
+
+---
+
## How it works
-- **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/)
+- **You** describe the situation with `@fde`, in plain language.
+- **The AI coding agent** routes to a method, does the work, and drafts the memory.
+- **The CLI** (`bin/fde.js`) does every write, receipt, and status check - git and file reads only, no network, no model tokens. You do not live in the CLI; your agent runs it. [docs/USAGE.md](docs/USAGE.md)
+- **You confirm.** Nothing enters the record unreviewed; `fde debrief --dry-run` shows the routing first.
+
+`CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. It lives at `~/fde-engagements//.fde/`, not inside any vendor - change hosts, install `@fde` on the new one, keep talking.
+
+### What works where
+
+Honest boundaries, so nothing here needs a footnote:
-`CLAUDE.md` is how the *code* works. The fieldbook is how the *engagement* works. The record lives at `~/fde-engagements//.fde/` — not inside any vendor. Change hosts, install `@fde` on the new one, bind if needed, keep talking.
+| | Claude Code | Cursor · Codex · Copilot · Gemini · local LLMs |
+|---|---|---|
+| Fieldbook, methods, CLI, dashboard | yes | yes |
+| Context loaded before you type | session hooks | you say `@fde` / `resume` |
+| Snapshot on session end | session hooks | `@fde` capture, or `fde capture` |
+| Pull from Granola / Slack / Notion | you add that source MCP; FDEOps only ingests | same |
+
+FDEOps is the sink, never the source: no push, no sync, no third-party tokens in `.fde/`. [mcp/recipes/](mcp/recipes/)
Phase verbs (land → close)
| Verb | When |
|------|------|
-| **land** | First days — brief, stakeholders, success |
-| **discover** | The brief is wrong — evidence from the repo |
+| **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 |
@@ -111,12 +132,29 @@ Overlays (AI, fintech, healthcare, gov) fire on signal. [docs/skills.md](docs/sk
---
+## Engagement memory (`.fde/`)
+
+One folder per client. Plain markdown, so you can grep it, diff it, copy it into a readout, and defend it in a room.
+
+| 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 |
+
+A day-one fieldbook ships **empty** - headings and allowed values, no invented rows - so anything you read in it is something that actually happened. Schema: [docs/schema.md](docs/schema.md).
+
+---
+
## The field methods
-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)
+You never pick one. You describe the situation and `@fde` routes. **37 methods** across 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)
-All 37 Skills
+All 37 methods
| Domain | Methods |
|--------|---------|
@@ -133,28 +171,11 @@ Overlays: [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references
---
-## 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).
-
----
-
## Fieldbook UI
-Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops dashboard` (`--all` for the portfolio).
+`@fde` dashboard, or `npx fdeops dashboard` (`--all` for the portfolio): one local HTML file - trust, phase, next action, and the record behind them. Generated on demand, no server.
-
+
---
@@ -162,10 +183,10 @@ Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops das
| You are | What this is |
|---------|----------------|
-| **Forward Deployed Engineer** | The job this was built for — first meeting through handoff |
+| **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 |
+| **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 |
---
@@ -173,22 +194,21 @@ Local HTML: trust, phase, next, the record. `@fde` dashboard, or `npx fdeops das
## Your data stays yours
- **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. `` 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.
+- **Plain markdown.** No database, no lock-in, nothing to export.
+- **No new data path.** The model sees client code only when you point the AI coding agent at it. `` blocks are redacted from CLI, dashboard, and hook output - do not open raw private blocks with file tools.
+- **Know the sync surface.** `~/fde-engagements` lives in `$HOME`. iCloud or Dropbox is an NDA incident waiting; `resume --init` warns you.
-[PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
+[PRIVACY.md](PRIVACY.md) before the first NDA · [SECURITY.md](SECURITY.md)
---
## Principles
-- **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
+- **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
---
@@ -202,8 +222,8 @@ Re-run the Quickstart install, or from a clone: `git pull && node bin/install.js
**[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. [Issues](https://github.com/suboss87/fdeops/issues) · [CONTRIBUTING.md](CONTRIBUTING.md)
-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.
+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.
-**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.
+**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 and 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
diff --git a/adapters/README.md b/adapters/README.md
index ea52979..f6f1c40 100644
--- a/adapters/README.md
+++ b/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//.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 § Switch coding agents](../README.md#switch-coding-agents-anytime).
+**Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements//.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 § What works where](../README.md#what-works-where).
## What goes where