fdeops 3.10.2 → 3.11.1

package/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.**
 
 [![npm version](https://img.shields.io/npm/v/fdeops.svg)](https://www.npmjs.com/package/fdeops)
 [![CI](https://github.com/suboss87/fdeops/actions/workflows/validate.yml/badge.svg)](https://github.com/suboss87/fdeops/actions)
 [![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 - 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,46 +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
-
-`@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/<client>/.fde/`.
-
 ---
 
-## See it
+## A real session
 
-```bash
-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).
+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).
 
 <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.
+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
@@ -66,9 +41,13 @@ Two things a chat window cannot do: **nothing is written until you confirm**, an
 ```
 
 ```bash
-npx skills add suboss87/fdeops          # Cursor, Codex, skills-compatible hosts
+npx skills add suboss87/fdeops --skill fde   # Cursor, Codex, skills-compatible hosts
 ```
 
+That is one skill, not a catalogue - `@fde` routes the whole method. The CLI needs no install either: the skill reaches for `npx fdeops` when `fde` is not on the PATH. (Drop `--skill fde` and you also get `testing-fieldbook`, which is for people contributing to this repo, not for field work.)
+
+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
@@ -76,46 +55,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).
 
 <details>
 <summary>Other install paths · scan · env</summary>
 
-- **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)
 
 </details>
 
 ---
 
+## 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/<client>/.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/<client>/.fde/`, not inside any vendor - change hosts, install `@fde` on the new one, keep talking.
+
+### What works where
 
-`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.
+Honest boundaries, so nothing here needs a footnote:
+
+| | 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/)
 
 <details>
 <summary>Phase verbs (land → close)</summary>
 
 | 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 |
@@ -127,9 +134,26 @@ 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)
 
 <details>
 <summary>All 37 methods</summary>
@@ -149,28 +173,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.
 
-<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>
+<p align="center"><img width="1336" height="624" alt="The fdeops Fieldbook dashboard: engagements with trust signal, phase and next action" src="https://github.com/user-attachments/assets/5683614c-7730-4a3a-860d-185053a377eb" /></p>
 
 ---
 
@@ -178,10 +185,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 |
 
 ---
@@ -189,22 +196,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. `<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.
+- **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. `<private>` 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
 
 ---
 
@@ -218,8 +224,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

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 § Switch coding agents](../README.md#switch-coding-agents-anytime).
+**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 § What works where](../README.md#what-works-where).
 
 ## What goes where
 

package/bin/check.js

@@ -221,17 +221,20 @@ const readme = read('README.md')
 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')
+// The recording may live on the front door or one click in (docs/USAGE.md), but
+// it must stay reachable and reproducible - an orphaned gif rots silently.
+const recordingHosts = ['README.md', 'docs/USAGE.md'].filter(f => read(f).includes('media/session.gif'))
+if (!recordingHosts.length) {
+  fail('media/session.gif must be embedded in README.md or docs/USAGE.md (the recorded session is the proof)')
+} else if (!recordingHosts.some(f => read(f).includes('media/record-session.sh'))) {
+  fail('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)')
+  else ok(`recorded session in ${recordingHosts.join(' + ')} (gif + reproducible recorder + cast)`)
 }
 
 // Every repo-relative README link and image must resolve, or the front door 404s.
@@ -267,6 +270,22 @@ if (!readme.includes('fde-engagements') || !/fdeops.*init.*engagement/i.test(rea
   fail('README must document fde-engagements + init flow')
 } else ok('README engagement path')
 
+// The contributor-only testing skill lives in .agents/skills/, so a bare
+// `skills add` installs it too. The advertised command must name the one skill
+// a field user wants.
+for (const m of readme.match(/^.*npx skills add .*$/gm) || []) {
+  if (!m.includes('--skill fde')) {
+    fail(`README skills-add command must pin --skill fde: ${m.trim()}`)
+  }
+}
+ok('README skills install is one skill')
+
+// A skill-only install has no fde on the PATH; the router must reach npx before
+// falling back to writing memory by hand.
+if (!read('skills/fde/SKILL.md').includes('npx --yes fdeops')) {
+  fail('skills/fde/SKILL.md must fall back to npx --yes fdeops when the CLI is not installed')
+} else ok('SKILL.md npx CLI fallback')
+
 if (!fs.existsSync(path.join(root, 'docs', 'USAGE.md'))) {
   fail('docs/USAGE.md missing')
 } else ok('docs/USAGE.md')
@@ -461,7 +480,7 @@ if (!fs.existsSync(path.join(root, 'bin', 'fde.js'))) {
       .map(name => path.join('bin', 'lib', name)),
   ]
   const cliSource = cliFiles.map(read).join('\n')
-  for (const sub of ['cmdScan', 'cmdResume', 'cmdLog', 'cmdDebrief', 'cmdIngest', 'cmdReceipts', 'cmdCapture', 'cmdStatus', 'cmdDashboard']) {
+  for (const sub of ['cmdScan', 'cmdResume', 'cmdLog', 'cmdDebrief', 'cmdIngest', 'cmdReceipts', 'cmdCapture', 'cmdStatus', 'cmdDashboard', 'cmdVault']) {
     if (!cliSource.includes(sub)) fail(`CLI sources missing ${sub}`)
   }
   if (!JSON.parse(read('package.json')).bin.fde) fail('package.json must expose the fde bin')