fdeops 3.9.4 → 3.9.5

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)
 
-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.
+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.
 
 ```
   land      discover      plan      build      ship      close
@@ -17,48 +17,52 @@ The **second brain for Forward Deployed Engineers** - engineers embedded at a cl
              written as a side effect of the work
 ```
 
-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.
+**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.
 
----
-
-## The problem
+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.
 
-Your AI agent's memory is scoped to a **repo**. Client work isn't: one engagement spans several repos, a dozen stakeholders, and decisions made in meetings your agent never saw. That context lives in rooms, chats, and hallway conversations - nothing writes it down where your tools can use it.
+---
 
-fdeops adds the missing layer: memory scoped to the **client** - plain markdown at `~/fde-engagements/<client>/.fde/`, written as a side effect of doing the work. Local only, zero dependencies, no network, no telemetry.
+## The week
 
-A notes app stores what you type. fdeops loads the right client into your AI agent's context automatically and turns meetings into dated receipts you can defend - the difference is what happens without you opening it.
+What you actually run most days - the habit that compounds the fieldbook:
 
-## Without fdeops vs with fdeops
+| 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 |
 
-| Moment | Without fdeops | With fdeops |
-|---|---|---|
-| **Monday morning** | Re-paste last week's context, re-explain the stakeholders | A hook loads the engagement at session start - the agent opens knowing the deadline and the open thread |
-| **After a meeting** | Notes rot in a scratch file | `fde debrief` routes decisions, risks, deliveries, and contacts into the record, dated |
-| **Scope dispute** | "Small" additions absorbed silently; no record when the sponsor asks | `fde receipts <term>` answers "when did we agree to that?" with dates |
-| **Quiet stakeholder** | Noticed three weeks too late | `fde log contact --signal amber` the day it happens; `fde status` surfaces it |
-| **Multiple clients** | Details blur across engagements | One folder per client; bind the workspace so writes cannot land on a name-alike checkout |
+Same engagement folder every time (`~/fde-engagements/<client>/.fde/`). Git versions it. Your AI coding agent reads it on every session.
 
 ---
 
 ## Quickstart
 
-**1. Install** (Claude Code)
+**1. Install** (pick one)
+
+```bash
+npx skills add suboss87/fdeops          # Cursor, Codex, and skills-compatible agents
+```
 
 ```text
-/plugin marketplace add suboss87/fdeops
+/plugin marketplace add suboss87/fdeops # Claude Code
 /plugin install fdeops@fdeops
 ```
 
-**2. Bind your client workspace** - run once, inside the workspace:
+**2. Bind** - once, inside the client workspace:
 
 ```bash
-npx fdeops resume --init garvey
+npx fdeops resume --init garvey   # creates ~/fde-engagements/garvey engagement + binds workspace
 ```
 
-(`npx` needs nothing pre-installed. Want the bare `fde` command the rest of this README uses? `npm i -g fdeops` - the plugin install alone does not put `fde` on your PATH.)
+**Verify:**
 
-fdeops' `--init` creates the engagement memory at `~/fde-engagements/garvey/.fde/` (plain markdown, private to your machine) and binds this workspace to it. The hooks read that binding - context auto-loads at session start, auto-captures at session end. That is the whole setup.
+```bash
+npx fdeops resume                 # should print TRIAGE (trust, phase, next) for garvey
+```
 
 **3. Work**
 
@@ -66,43 +70,37 @@ fdeops' `--init` creates the engagement memory at `~/fde-engagements/garvey/.fde
 @fde I just got the brief. New client, payments platform, they want it live before their Q3 audit.
 ```
 
-`@fde` is the one skill fdeops installs. Describe what's happening; it routes to the right field method and writes matching `.fde/` artifacts — you still confirm judgment. Full workflow: [docs/USAGE.md](docs/USAGE.md).
-
-Not ready to install? `npx fdeops scan` runs on any repo you can read - day-1 recon (pure `git` + file reads, no config, no account) that maps hotspots, test gaps, and reverted attempts, and ends with the ASK ON DAY 1 questions the brief never mentions. The scan is heuristic by design - treat its output as leads to verify on day one, not findings.
+`@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).
 
 <details>
-<summary><strong>Other install paths</strong> - Cursor, Codex, Copilot, Gemini CLI, local LLMs, air-gapped</summary>
+<summary><strong>Other install paths</strong> · scan · env</summary>
 
-- **Cursor / Codex / Copilot / Gemini CLI:** `npx fdeops adapters .` drops a thin pointer to the same `@fde` skill - [adapters/](adapters/README.md)
+- **Cursor / Codex / Copilot / Gemini CLI:** `npx fdeops adapters .` - [adapters/](adapters/README.md)
 - **Local LLMs (Ollama, LM Studio, llama.cpp):** load `skills/fde/SKILL.md` as the system prompt - [guide](adapters/LOCAL-LLM.md)
-- **Skills CLI:** `npx skills add suboss87/fdeops`
 - **Manual / air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js`
-- **Requires:** [Node.js](https://nodejs.org) >= 18 for the CLI and adapters; the Claude Code plugin install does not need Node separately.
-- **Advanced:** the `FDEOPS_ENGAGEMENT` env var overrides the workspace registry - only for unusual setups. Full matrix: [docs/install.md](docs/install.md)
+- **Try without install:** `npx fdeops scan` - day-1 recon (heuristic leads, not findings)
+- **Requires:** [Node.js](https://nodejs.org) >= 18 for the CLI and adapters
+- **Advanced:** `FDEOPS_ENGAGEMENT` overrides the workspace registry. Full matrix: [docs/install.md](docs/install.md)
 
 </details>
 
 ---
 
-## The week
-
-This is the actual habit — the high-frequency loop, not the full skill matrix:
-
-- **Monday morning** - open your agent, context loads, you're not re-explaining anything
-- **After a meeting** - `fde debrief` turns raw notes into dated decisions, risks, and signals
-- **Mid-scope-fight** - `fde receipts <term>` answers "when did we agree to that?"
-- **Friday** - `fde status` gives you the sponsor update from the week's actual record
-
----
-
 ## How it works
 
-Two hooks and one router, on top of the fieldbook:
+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
-- **After meetings** - `fde debrief notes.md` routes lines prefixed `decision:` / `risk:` / `delivery:` / `contact:` to the matching file, dated; everything else lands as a dated block in `context.md`
-- **On top of the memory** - the `@fde` skill routes six phase verbs:
+- **`@fde`** - routes your situation to a field method; you confirm before memory sticks
+- **CLI** - deterministic, offline (`scan`, `debrief`, `prep`, `receipts`, `status`)
+
+fdeops complements repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *engagement* works.
+
+Works with **Claude Code** · **Cursor** · **Copilot** · **Gemini CLI** · **Ollama** · **LM Studio** - any model that reads markdown.
+
+<details>
+<summary><strong>Phase verbs</strong> (land → close)</summary>
 
 | Verb | When |
 |------|------|
@@ -113,9 +111,9 @@ Two hooks and one router, on top of the fieldbook:
 | **ship** | Going to production - pre-flight, canary, tested rollback |
 | **close** | Engagement ending - handoff doc, retrospective, receipts that survive you |
 
-Overlays for regulated domains (AI, fintech, healthcare, government) activate on signal. fdeops complements your agent's native repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *engagement* works. Full matrix: [docs/skills.md](docs/skills.md).
+Overlays for regulated domains (AI, fintech, healthcare, government) activate on signal. Full matrix: [docs/skills.md](docs/skills.md).
 
-Works with **Claude Code** - **Cursor** - **Copilot** - **Gemini CLI** - **Ollama** - **LM Studio** - any model that reads a markdown file.
+</details>
 
 ---
 
@@ -138,33 +136,41 @@ Every entry is dated and sourced, so you can defend it in front of skeptical sta
 
 ## The CLI
 
-Deterministic, offline, zero tokens - the skill adds judgment on top:
+Commands that match **The week** (skill adds judgment on top):
 
 ```bash
-fde scan                          # day-1 recon + ASK ON DAY 1 questions (works via npx)
 fde resume                        # TRIAGE + load this workspace's engagement
-fde resume --init <client>        # THE setup step: create + bind + git-version .fde/
-fde triage                        # TRIAGE only (session hooks / Cursor entry)
-fde debrief notes.md              # route prefixed meeting notes (also reads stdin)
-fde debrief --smart notes.md      # propose routing from messy notes → --apply to confirm
-fde prep "Denise sync"            # grounded walk-in brief from existing memory
+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 "descope agreed with Kowalczyk"
-fde log contact "Denise gone quiet" --signal amber
-fde receipts <term>               # dated search; no hit = a gap in the record, not proof of absence
-fde status                        # current engagement triage (add --all for every client)
-fde dashboard                     # current engagement fieldbook (add --all for every client)
+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 init/status/dashboard from the default `~/fde-engagements`.
+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.
 
-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>
 
 `fde dashboard` (FieldBook) renders the **current** engagement by default. Pass `--all` for every client sorted by trust:
 
-<p align="center"><img width="1336" height="624" alt="Screenshot 2026-07-08 at 12 45 07" src="https://github.com/user-attachments/assets/5683614c-7730-4a3a-860d-185053a377eb" /></p>
+<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>
 
 ---
 
@@ -196,10 +202,8 @@ Details: [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
 
 - **The artifact is the memory** - producing work and recording it are one action
 - **Methods, not autonomy** - each skill tells you what to check; the judgment, the trust, and the consequences stay yours
-- **Trust before production** - earn the right to touch their systems
 - **Brief is a hypothesis** - discover before building the wrong thing
 - **Evidence on every claim** - these files get defended in front of skeptical clients
-- **Thin slices** - ship learning, not theatre
 - **One customer, one folder** - context never bleeds
 
 ---
@@ -207,6 +211,8 @@ Details: [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
 ## Updating
 
 ```bash
+# Plugin / skills install: re-run the install command from Quickstart
+# From a git clone:
 cd fdeops && git pull && node bin/install.js
 ```
 

package/bin/check.js

@@ -111,7 +111,7 @@ for (const section of [
   'Quickstart',
   'Engagement memory',
   'Who this is for',
-  'Without fdeops vs with fdeops',
+  'The week',
   'Principles',
 ]) {
   if (!readme.includes(section)) fail(`README missing section: ${section}`)
@@ -205,6 +205,22 @@ const hook = read('hooks/session-start')
 if (!hook.includes('FDEOPS_ENGAGEMENT')) {
   fail('session-start hook must read FDEOPS_ENGAGEMENT env var')
 } else ok('hook FDEOPS_ENGAGEMENT')
+// Token discipline: SessionStart must not dump the full skill (L1 progressive disclosure).
+// Strip comments before scanning for a real `cat …SKILL.md` / BOOTSTRAP inject.
+const hookCode = hook.replace(/^[ \t]*#.*$/gm, '')
+if (/\$\(cat\s+"\$BOOTSTRAP"\)|cat\s+"\$BOOTSTRAP"|cat\s+[^\n]*SKILL\.md/.test(hookCode)) {
+  fail('session-start must not cat SKILL.md - inject TRIAGE + bounded context + pointer only')
+}
+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 (!/\btriage\b/.test(hook)) {
+  fail('session-start must still inject TRIAGE')
+}
+ok('session-start lean inject (no SKILL dump)')
 
 // v3: write-side memory backstop
 if (!fs.existsSync(path.join(root, 'hooks', 'session-stop'))) {

package/hooks/session-start

@@ -1,18 +1,10 @@
 #!/bin/bash
-# fdeops SessionStart - load @fde + engagement context from FDE laptop path.
+# fdeops SessionStart - inject TRIAGE + bounded engagement context (not the full skill).
+# Token discipline (L1 progressive disclosure): Claude/Cursor already discover @fde via
+# skill metadata. Dumping skills/fde/SKILL.md here paid ~6-8k tokens every session even
+# when the FDE was not doing field work. Load the skill body only when @fde triggers.
 
 CONTEXT_FILE=""
-BOOTSTRAP=""
-
-for candidate in \
-  "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/fde/SKILL.md}" \
-  "$(dirname "$0")/../skills/fde/SKILL.md" \
-  "$HOME/.claude/skills/fde/SKILL.md"; do
-  if [ -n "$candidate" ] && [ -f "$candidate" ]; then
-    BOOTSTRAP="$candidate"
-    break
-  fi
-done
 
 resolve_engagement_dir() {
   local raw="$1"
@@ -143,9 +135,8 @@ bounded_context() {
 
 CONTENT=""
 
-if [ -n "$BOOTSTRAP" ]; then
-  CONTENT="$CONTENT$(cat "$BOOTSTRAP")\n\n"
-fi
+# Lean pointer only - never cat SKILL.md. Methods load on @fde / skill trigger.
+CONTENT="${CONTENT}fdeops: engagement fieldbook active. For field methods, invoke @fde (loads skills/fde/SKILL.md + one references/*.md). Plumbing is zero-token CLI: fde triage | resume | debrief | prep | receipts | status.\n\n"
 
 # Same TRIAGE block as `fde resume` / `fde triage` - Monday morning must not
 # depend on the model remembering to run a CLI command. Prefer the installed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.9.4",
+  "version": "3.9.5",
   "description": "Field kit for engineers embedded in client work - a real CLI (recon, memory, portfolio), one @fde skill with field judgment on top, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.",
   "bin": {
     "fdeops": "bin/install.js",

package/skills/fde/SKILL.md

@@ -70,7 +70,7 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
 
 CLI missing → use the manual fallback commands inside each reference.
 
-**Token model - where the cost goes.** Deterministic work is the CLI's job and costs **zero model tokens**: memory writes, recon, receipts, status, dashboard, and the bounded `fde resume`. Spend tokens only on judgment - reading the situation, routing, running the phase method, writing the artifact. Three rules keep a full day of FDE work cheap: load the router first and pull **one** reference only when you route to it; never dump a whole `.fde/` file into context - read the bounded resume, or `fde receipts <term>` for a targeted slice; don't re-read files you already have. The expensive model should fire for real decisions, not for plumbing the CLI already does.
+**Token model - where the cost goes.** Deterministic work is the CLI's job and costs **zero model tokens**: memory writes, recon, receipts, status, dashboard, and the bounded `fde resume`. Session-start hooks inject **TRIAGE + bounded `context.md` + a one-line pointer** - never this full skill body (that loads only when `@fde` triggers). Spend tokens only on judgment - reading the situation, routing, running the phase method, writing the artifact. Three rules keep a full day of FDE work cheap: load the router first and pull **one** reference only when you route to it; never dump a whole `.fde/` file into context - read the bounded resume, or `fde receipts <term>` for a targeted slice; don't re-read files you already have. The expensive model should fire for real decisions, not for plumbing the CLI already does.
 
 ## Proactive intelligence (run on every session start)