fdeops 3.9.5 → 3.9.8

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)
 
-CLI + one `@fde` skill + hooks over a local `.fde/` fieldbook - one folder per client. The **second brain for Forward Deployed Engineers** - engineers embedded at a client, from first meeting to final handoff. Works the same for consultants, agency developers, solutions architects, and fractional CTOs.
+One `@fde` skill over a local client notebook (the **fieldbook** under `.fde/`) - one folder per client. The **system of record for embeds** - Forward Deployed Engineers and anyone living on a client site from first meeting to handoff. Feels like a second brain; behaves like a defensible record (dated, sourced, yours). Works the same for consultants, agency developers, solutions architects, and fractional CTOs.
 
 ```
   land      discover      plan      build      ship      close
@@ -17,25 +17,23 @@ CLI + one `@fde` skill + hooks over a local `.fde/` fieldbook - one folder per c
              written as a side effect of the work
 ```
 
-**Glossary:** **fieldbook** = the `.fde/` folder · **TRIAGE** = trust + phase + next from memory · **receipts** = dated search of what you logged · **hooks** = auto load/capture at session start/end.
-
-Describe your situation - `@fde` routes to the right method and writes the matching `.fde/` artifact. Phase methods (land → close) live in the skill; the CLI owns scan, memory, and receipts. You still confirm judgment - the fieldbook does not maintain itself without you.
+**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.
 
 ---
 
 ## The week
 
-What you actually run most days - the habit that compounds the fieldbook:
+Day to day you only need `@fde` and normal English. No command cheat sheet.
 
-| When | What you do | Why it matters |
-|------|-------------|----------------|
-| **Monday** | Open your AI coding agent → TRIAGE loads (trust, phase, next) | Start where last week left off - no re-paste |
-| **After a meeting** | `fde debrief --smart notes.txt` → review → `--apply` | Messy notes become dated decisions, risks, contacts |
-| **Before a walk-in** | `fde prep "Denise sync"` | Walk in with memory, not a blank chat |
-| **Scope fight** | `fde receipts descope` (+ memory git hash) | Answer "when did we agree?" from the record |
-| **Friday** | `fde status` → sponsor update from the real record | Status from evidence, not memory theater |
+| 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 |
+| **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 |
 
-Same engagement folder every time (`~/fde-engagements/<client>/.fde/`). Git versions it. Your AI coding agent reads it on every session.
+Same client folder every time (`~/fde-engagements/<client>/.fde/`). Your AI coding agent reads it on every session.
 
 ---
 
@@ -52,25 +50,25 @@ npx skills add suboss87/fdeops          # Cursor, Codex, and skills-compatible a
 /plugin install fdeops@fdeops
 ```
 
-**2. Bind** - once, inside the client workspace:
+**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
 ```
 
-**Verify:**
+**Check it worked:**
 
 ```bash
-npx fdeops resume                 # should print TRIAGE (trust, phase, next) for garvey
+npx fdeops resume                 # prints a short "where we are" for this client
 ```
 
-**3. Work**
+**3. Work** - talk normally:
 
 ```text
 @fde I just got the brief. New client, payments platform, they want it live before their Q3 audit.
 ```
 
-`@fde` routes and writes `.fde/` artifacts - you confirm judgment. Use `npx fdeops …` until you want a short command: `npm i -g fdeops` (optional). Full workflow: [docs/USAGE.md](docs/USAGE.md).
+`@fde` routes and updates the fieldbook - you confirm judgment. Full workflow: [docs/USAGE.md](docs/USAGE.md).
 
 <details>
 <summary><strong>Other install paths</strong> · scan · env</summary>
@@ -88,14 +86,11 @@ npx fdeops resume                 # should print TRIAGE (trust, phase, next) for
 
 ## How it works
 
-Three pieces on top of the fieldbook:
-
-- **Session start** - a hook loads where you left off into your AI coding agent's context
-- **Session end** - a hook captures what happened back into the fieldbook
-- **`@fde`** - routes your situation to a field method; you confirm before memory sticks
-- **CLI** - deterministic, offline (`scan`, `debrief`, `prep`, `receipts`, `status`)
+- **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))
 
-fdeops complements repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *engagement* works.
+fdeops complements repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *client engagement* works.
 
 Works with **Claude Code** · **Cursor** · **Copilot** · **Gemini CLI** · **Ollama** · **LM Studio** - any model that reads markdown.
 
@@ -119,7 +114,7 @@ Overlays for regulated domains (AI, fintech, healthcare, government) activate on
 
 ## Engagement memory (`.fde/`)
 
-The **fieldbook** - one folder per client, plain markdown you can read, grep, and take with you:
+The **fieldbook** is the system of record for the embed - one folder per client, plain markdown you can read, grep, and take with you:
 
 | File | Holds |
 |------|-------|
@@ -134,43 +129,11 @@ Every entry is dated and sourced, so you can defend it in front of skeptical sta
 
 ---
 
-## The CLI
-
-Commands that match **The week** (skill adds judgment on top):
-
-```bash
-fde resume                        # TRIAGE + load this workspace's engagement
-fde resume --init <client>        # create + bind + git-version .fde/
-fde debrief --smart notes.md      # propose routing → --apply to confirm
-fde prep "Denise sync"            # walk-in brief from existing memory
-fde receipts <term>               # dated search (gap ≠ proof of absence)
-fde status                        # sponsor-ready triage (--all for portfolio)
-fde scan                          # day-1 recon + ASK ON DAY 1 (works via npx)
-```
-
-<details>
-<summary><strong>More commands</strong></summary>
-
-```bash
-fde triage                        # TRIAGE only (hooks / Cursor entry)
-fde debrief notes.md              # prefix router: decision: / risk: / delivery: / contact:
-fde doctor                        # lint: stale signals, unset phase, gaps
-fde log decision "…"
-fde log contact "…" --signal amber
-fde dashboard                     # FieldBook HTML (--all for every client)
-```
-
-Optional: `export FDEOPS_ENGAGEMENTS_ROOT=~/path/to/engagements` to isolate from `~/fde-engagements`.
-
-Each `.fde/` is a local git repo (no remote, no telemetry) - dated entries carry an author tag; every write commits so receipts are tamper-evident. Worst-of `[signal:...]` per stakeholder drives trust; signals older than 21 days show as stale.
-
-</details>
-
-<p align="center"><img src="media/terminal-demo.svg" alt="fde CLI - status, scan, dashboard" width="720"/></p>
+## Fieldbook UI
 
-`fde dashboard` (FieldBook) renders the **current** engagement by default. Pass `--all` for every client sorted by trust:
+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).
 
-<p align="center"><img width="1336" height="624" alt="fde dashboard FieldBook" src="https://github.com/user-attachments/assets/5683614c-7730-4a3a-860d-185053a377eb" /></p>
+<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>
 
 ---
 
@@ -182,7 +145,7 @@ Each `.fde/` is a local git repo (no remote, no telemetry) - dated entries carry
 | **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 second brain - and your audit trail for billable work |
+| **Fractional CTO doing client work** | The fieldbook is your system of record for the embed - and your audit trail for billable work |
 
 ---
 

package/adapters/cursor.fde.mdc

@@ -9,10 +9,11 @@ You are the AI coding agent for a **Forward Deployed Engineer (FDE)** - the huma
 
 ## Entry
 
-When the FDE types **`@fde`** or describes an engagement situation (new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship), load the skill and route.
+When the FDE types **`@fde`** or describes an engagement situation in plain language (new customer, meeting notes, prep for a stakeholder meeting, scope dispute, ready to ship), load the skill and route.
 
 - 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.
+- **Never ask the FDE to type `fde …` commands.** You run the local CLI; they confirm judgment in chat.
 
 ## Engagement memory
 
@@ -20,7 +21,7 @@ Read and write engagement files under the workspace's bound engagement: run `fde
 
 **On every session entry (before other work):** run `fde triage` (fallback `node ~/.claude/fdeops/fde.js triage`, then `fde resume`). Lead with that TRIAGE block — trust, phase, open risks, next action, record owner/hash. Do not invent stakeholders or status.
 
-Use the CLI for deterministic work - `fde scan | log | debrief | prep | doctor | receipts | status | dashboard` - instead of improvising shell.
+You run the CLI for deterministic work - `fde scan | log | debrief | prep | doctor | receipts | status | dashboard` - instead of improvising shell or handing commands to the human.
 
 ### Meeting → memory loop
 - Messy notes: `fde debrief --smart notes.md` → review `.debrief-propose` → `fde debrief --apply`

package/bin/check.js

@@ -214,8 +214,21 @@ if (/\$\(cat\s+"\$BOOTSTRAP"\)|cat\s+"\$BOOTSTRAP"|cat\s+[^\n]*SKILL\.md/.test(h
 if (hookCode.includes('BOOTSTRAP=')) {
   fail('session-start must not resolve BOOTSTRAP skill path for inject')
 }
-if (!hook.includes('invoke @fde')) {
-  fail('session-start must include a lean @fde pointer (not full skill)')
+if (!/plain language with @fde|invoke @fde/.test(hook)) {
+  fail('session-start must include a lean @fde / plain-language pointer (not full skill)')
+}
+const skillBody = read('skills/fde/SKILL.md')
+if (!skillBody.includes('Human surface vs agent plumbing')) {
+  fail('SKILL.md must define human NL surface vs agent CLI plumbing')
+}
+if (!/never tell the FDE to type|Never tell the FDE to type|never ask the human to type fde/i.test(skillBody)) {
+  fail('SKILL.md must forbid asking the human to type fde commands')
+}
+if (!skillBody.includes('fde prep')) {
+  fail('SKILL.md must route walk-in prep to fde prep')
+}
+if (!skillBody.includes('debrief --smart')) {
+  fail('SKILL.md must prefer fde debrief --smart for messy notes')
 }
 if (!/\btriage\b/.test(hook)) {
   fail('session-start must still inject TRIAGE')
@@ -253,15 +266,25 @@ ok('hooks registry-aware')
 if (!fs.existsSync(path.join(root, 'bin', 'fde.js'))) {
   fail('bin/fde.js missing (the deterministic core)')
 } else {
-  const cli = read('bin/fde.js')
-  for (const sub of ['cmdScan', 'cmdResume', 'cmdLog', 'cmdDebrief', 'cmdReceipts', 'cmdCapture', 'cmdStatus']) {
-    if (!cli.includes(sub)) fail(`fde.js missing ${sub}`)
+  const cliFiles = [
+    'bin/fde.js',
+    ...fs.readdirSync(path.join(root, 'bin', 'lib'))
+      .filter(name => name.endsWith('.js'))
+      .map(name => path.join('bin', 'lib', name)),
+  ]
+  const cliSource = cliFiles.map(read).join('\n')
+  for (const sub of ['cmdScan', 'cmdResume', 'cmdLog', 'cmdDebrief', 'cmdReceipts', 'cmdCapture', 'cmdStatus', 'cmdDashboard']) {
+    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')
   if (!read('bin/install.js').includes('fde.js')) fail('install.js must deploy fde.js')
+  if (!read('bin/install.js').includes('LIB_SRC')) fail('install.js must deploy bin/lib/')
   if (!read('skills/fde/SKILL.md').includes('fde resume')) fail('SKILL.md must use the CLI for memory ops')
-  if (!cli.includes('[signal:')) fail('fde.js must support structured [signal:x] trust tokens')
-  if (!cli.includes('ASK ON DAY 1')) fail('fde.js scan must emit ASK ON DAY 1 questions')
+  if (!cliSource.includes('[signal:')) fail('CLI sources must support structured [signal:x] trust tokens')
+  if (!cliSource.includes('ASK ON DAY 1')) fail('CLI sources must emit ASK ON DAY 1 questions')
+  for (const renderSymbol of ['buildFieldbookHtml', 'dashStyles', 'dashScript', 'FONT_FACE_CSS']) {
+    if (!cliSource.includes(renderSymbol)) fail(`CLI sources missing dashboard renderer symbol ${renderSymbol}`)
+  }
   if (!read('bin/install.js').includes('FDE_SUBCOMMANDS')) fail('install.js must pass fde subcommands through (npx fdeops scan)')
   ok('fde CLI present and wired')
 }