fdeops 3.9.19 → 3.9.20

package/README.md

@@ -31,6 +31,7 @@ Day to day you only need `@fde` and normal English. No command cheat sheet.
 |------|--------------|--------------|
 | **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 |
+| **Pull from tools** | `@fde` connect Granola *(once)* · then `@fde` pull today's Acme transcript | Wire any source MCP you choose; FDEOps stages → proposes → you confirm. Recipes: [mcp/recipes/](mcp/recipes/) |
 | **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 |
@@ -91,7 +92,7 @@ npx fdeops resume                 # prints a short "where we are" for this clien
 - **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))
-- **Pluggable pull (ingest)** - large transcripts and emails can land in `.inbox/` via `fde ingest stage` after **your** source MCPs fetch them (Granola, Gmail, Notion, custom — not bundled in fdeops). Same propose → confirm → apply loop as debrief; nothing unreviewed enters the fieldbook. No ambient sync.
+- **Pluggable pull (ingest)** - FDEOps is the **sink**, not a connector pack. You add any source MCP (Granola, Notion, Drive, …) in Cursor/Claude; say `@fde connect …` for a guided config + recipe, then pull in plain language. Raw text → `.inbox/` → propose → you confirm → `.fde/`. No ambient sync; nothing unreviewed enters the fieldbook. See [mcp/recipes/](mcp/recipes/).
 
 fdeops complements repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *client engagement* works.
 

package/bin/check.js

@@ -351,7 +351,15 @@ if (!fs.existsSync(path.join(root, 'mcp', 'fdeops-ingest', 'server.js'))) {
   fail('ingest MCP must expose ingest_stage')
 } else if (!read('skills/fde/references/ingest.md').includes('stage')) {
   fail('skills/fde/references/ingest.md missing stage contract')
-} else ok('ingest MCP + skill reference')
+} else if (!fs.existsSync(path.join(root, 'skills', 'fde', 'references', 'ingest-connect.md'))) {
+  fail('skills/fde/references/ingest-connect.md missing')
+} else {
+  for (const recipe of ['file.md', 'granola.md', 'notion.md']) {
+    if (!fs.existsSync(path.join(root, 'mcp', 'recipes', recipe))) fail(`mcp/recipes/${recipe} missing`)
+  }
+  if (!read('README.md').includes('mcp/recipes')) fail('README must point at mcp/recipes for connect clarity')
+  ok('ingest MCP + connect recipes + skill reference')
+}
 
 if (!fs.existsSync(path.join(root, '.github', 'ISSUE_TEMPLATE', 'bug_report.yml'))) {
   fail('GitHub issue template missing')

package/mcp/README.md

@@ -36,6 +36,10 @@ Source MCP(s)          fdeops-ingest MCP           fde CLI
 |---------|------|---------|
 | `fdeops-ingest-mcp` | [`fdeops-ingest/`](./fdeops-ingest/) | Ingest sink (stage, list, propose, apply) |
 
+## Recipes (copy-paste connect)
+
+See [`recipes/`](./recipes/) for file, Granola-shaped, and Notion-shaped setup. In chat: `@fde I want to connect Granola` → skill `ingest-connect` walks the FDE through config + reload + verify.
+
 ## Adding a source MCP
 
 Source MCPs are **not** bundled in fdeops. To add Granola, Gmail, or another provider:

package/mcp/fdeops-ingest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops-ingest-mcp",
-  "version": "3.9.19",
+  "version": "3.9.20",
   "private": true,
   "description": "Thin stdio MCP sink for FDEOps ingest (stage → propose → apply). Zero runtime dependencies.",
   "bin": {

package/mcp/recipes/README.md

@@ -0,0 +1,15 @@
+# Ingest source recipes
+
+FDEOps does **not** bundle Granola / Notion / Drive OAuth. These recipes show how an FDE wires a **source MCP** (or file drop) into the FDEOps **sink**.
+
+**Contract every source must satisfy:** fetch text → `fde ingest stage` (or MCP `ingest_stage`) with `{ source, title, content }` → propose → FDE confirms → apply.
+
+| Recipe | When |
+|--------|------|
+| [file.md](./file.md) | Local transcript / export already on disk (no source MCP) |
+| [granola.md](./granola.md) | Meeting transcripts via a Granola-shaped MCP (or export) |
+| [notion.md](./notion.md) | Notion pages / meeting notes via a Notion MCP |
+
+Also wire the sink once: [fdeops-ingest/README.md](../fdeops-ingest/README.md).
+
+**Natural language:** `@fde I want to connect Granola` → agent follows `skills/fde/references/ingest-connect.md` and this recipe.

package/mcp/recipes/file.md

@@ -0,0 +1,25 @@
+# Recipe: local file / paste (no source MCP)
+
+**Use when:** you already have a transcript, `.eml`, or export on disk — or you paste into chat.
+
+## Setup
+
+None beyond the FDEOps sink (`fde` CLI and optionally `fdeops-ingest` MCP).
+
+## Pull phrase
+
+```text
+@fde stage this transcript into the fieldbook and propose updates
+```
+
+(or attach / point at a path)
+
+## Agent steps
+
+1. Bind engagement.
+2. `fde ingest stage --source file --title "<short>" <path>` (or stdin).
+3. `fde ingest propose <id>` → rewrite prefixes → show FDE → on confirm `fde ingest apply`.
+
+## mcp.json
+
+Not required for the source. Optional sink only — see [../fdeops-ingest/README.md](../fdeops-ingest/README.md).

package/mcp/recipes/granola.md

@@ -0,0 +1,58 @@
+# Recipe: Granola-shaped meeting transcripts
+
+**Use when:** meeting notes live in Granola (or a similar notes MCP). FDEOps does not ship a Granola server — you add whichever MCP/export path you trust.
+
+## Setup (once)
+
+1. Install / enable a **Granola (or notes) MCP** in Cursor/Claude per that product’s docs.
+2. Add the FDEOps **sink** MCP (`fdeops-ingest`) — [../fdeops-ingest/README.md](../fdeops-ingest/README.md).
+3. Reload MCP / restart the agent host.
+4. Test: `@fde what can you pull?` — agent should see both sink tools and the notes source tools.
+
+### Example mcp.json shape (illustrative)
+
+Replace `granola-mcp` command/args with whatever the real server documents. FDEOps only needs *some* tool that returns transcript text.
+
+```json
+{
+  "mcpServers": {
+    "granola": {
+      "command": "npx",
+      "args": ["-y", "YOUR-GRANOLA-MCP-PACKAGE"],
+      "env": {
+        "GRANOLA_API_KEY": "from-your-secrets"
+      }
+    },
+    "fdeops-ingest": {
+      "command": "node",
+      "args": ["/absolute/path/to/fdeops/mcp/fdeops-ingest/server.js"],
+      "env": {
+        "FDEOPS_ENGAGEMENT": "/Users/you/fde-engagements/acme/.fde"
+      }
+    }
+  }
+}
+```
+
+**No Granola MCP available?** Export transcript to a file → follow [file.md](./file.md).
+
+## Pull phrase
+
+```text
+@fde pull today's Acme Granola into the fieldbook
+```
+
+## Agent steps
+
+1. Capability check — if no notes/Granola tools, run connect flow (`ingest-connect.md`).
+2. Fetch transcript via source MCP (or ask which meeting).
+3. `ingest_stage` / `fde ingest stage --source granola --title "…"`.
+4. Propose → confirm → apply. Never auto-apply.
+
+## Common fails
+
+| Symptom | Fix |
+|---------|-----|
+| Agent says it can’t reach Granola | MCP not saved / host not reloaded / wrong env key |
+| Wrong client inbox | Set `FDEOPS_ENGAGEMENT` or bind workspace (`fde resume --init`) |
+| Empty propose | Agent must rewrite `.debrief-propose` with type prefixes |

package/mcp/recipes/notion.md

@@ -0,0 +1,56 @@
+# Recipe: Notion docs / meeting notes
+
+**Use when:** useful engagement notes live in Notion. FDEOps does not ship a Notion server — use a Notion MCP (or export markdown).
+
+## Setup (once)
+
+1. Enable a **Notion MCP** (official or community) with a token that can read the pages you need.
+2. Add **fdeops-ingest** sink — [../fdeops-ingest/README.md](../fdeops-ingest/README.md).
+3. Reload MCP / restart host.
+4. Test: `@fde what can you pull?`
+
+### Example mcp.json shape (illustrative)
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "YOUR-NOTION-MCP-PACKAGE"],
+      "env": {
+        "NOTION_TOKEN": "from-your-secrets"
+      }
+    },
+    "fdeops-ingest": {
+      "command": "node",
+      "args": ["/absolute/path/to/fdeops/mcp/fdeops-ingest/server.js"],
+      "env": {
+        "FDEOPS_ENGAGEMENT": "/Users/you/fde-engagements/acme/.fde"
+      }
+    }
+  }
+}
+```
+
+**No Notion MCP?** Export page to markdown → [file.md](./file.md).
+
+## Pull phrase
+
+```text
+@fde pull the Acme discovery notes Notion page into the fieldbook
+```
+
+## Agent steps
+
+1. Capability check — Notion tools present?
+2. Fetch page/block text via Notion MCP (ask which page if ambiguous).
+3. Stage with `--source notion`.
+4. Propose → confirm → apply.
+
+## Common fails
+
+| Symptom | Fix |
+|---------|-----|
+| 401 / forbidden | Token lacks access to that workspace/page |
+| Huge page dump | Stage full text in `.inbox/`; propose only short dated facts |
+| Wrong engagement | Bind / `FDEOPS_ENGAGEMENT` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.9.19",
+  "version": "3.9.20",
   "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

@@ -83,7 +83,8 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
 | (session entry / where are we) | `fde resume` or use injected TRIAGE; `fde resume --init <name>` only if unbound |
 | Day-1 look at the repo | `fde scan` - then you interpret against the brief |
 | "Debrief these notes" / pastes meeting notes | Prefer `fde debrief --smart <notes>` → **you** (the agent) rewrite `.debrief-propose` with `decision:`/`risk:`/`delivery:`/`contact:`/`next:` prefixes where needed → show FDE → on confirm `fde debrief --apply`. `--smart` is a prefix/keyword gate, not a brain. Fallback: structure prefixed lines yourself, show FDE, then `fde debrief` |
-| "Make sure we're up to date" / "pull relevant info" / "pull from Granola/email/transcript" | Bind engagement; if ambiguous ask which meeting/thread. Use whatever source MCPs the FDE has configured (Granola, Gmail, Notion, custom — **not bundled in fdeops**) to fetch raw text → `fde ingest stage [--source NAME] [--title TEXT]` → `fde ingest propose <id>` → **you** rewrite `.debrief-propose` with type prefixes → show FDE → on confirm `fde ingest apply`. **Never auto-apply. Never ambient sync.** Detail: `references/ingest.md` |
+| "Make sure we're up to date" / "pull relevant info" / "pull from Granola/email/transcript" | Bind engagement; **capability check** (which source MCPs exist this session — never pretend). If missing → connect flow. Else fetch → `fde ingest stage` → `fde ingest propose` → rewrite prefixes → show FDE → on confirm `fde ingest apply`. **Never auto-apply. Never ambient sync.** Detail: `references/ingest.md` |
+| "Connect a new MCP" / "connect Granola/Notion" / "what can you pull?" | Follow `references/ingest-connect.md`: ask which source → emit `mcp.json` from `mcp/recipes/` + sink block → they save/reload in Cursor/Claude → verify tools → optional test stage to `.inbox/` only. You cannot silently install host MCPs. |
 | "Prep me for the meeting with …" / walk-in brief | `fde prep "<short label>"` - present the brief in plain language; do not invent facts missing from `.fde/` |
 | "When did we agree…?" / scope dispute | `fde receipts <term>` - answer with dates; no hit = gap, not proof |
 | "Draft the sponsor update" / how are we doing | `fde status` then follow `references/status.md` for the narrative |
@@ -270,7 +271,8 @@ Running the engagement and ending it well.
 | Weekly update due, "need to send the sponsor something" | status | `references/status.md` |
 | Demo coming up, show-and-tell, exec walkthrough | demo-prep | `references/demo-prep.md` |
 | Just out of a meeting, raw notes, "they said…", "debrief" | debrief | the debrief verb (above) + `references/debrief.md` |
-| Make sure we're up to date, pull what's relevant, fetch from Granola/Gmail/transcript | ingest | `references/ingest.md` (stage → propose → confirm → apply; source MCPs are user-configured) |
+| Make sure we're up to date, pull what's relevant, fetch from Granola/Gmail/transcript | ingest | `references/ingest.md` (capability check → stage → propose → confirm → apply) |
+| Connect a new MCP / connect Granola or Notion / what can you pull | ingest-connect | `references/ingest-connect.md` (+ `mcp/recipes/`) |
 | Prep me for a meeting / walk-in brief / "what should I know before I talk to…" | - | run `fde prep "<label>"`, present in plain language |
 | Sponsor's boss needs a summary, board update, justify continued investment | exec-narrative | `references/exec-narrative.md` |
 | Status across all my customers | dashboard | `references/dashboard.md` |

package/skills/fde/references/ingest-connect.md

@@ -0,0 +1,36 @@
+# ingest-connect - wire a source MCP in plain language
+
+**Enter when:** the FDE says "I want to connect a new MCP", "connect Granola / Notion / Drive", "how do I pull from …", or a pull request fails because no source tools exist.
+
+**Read first:** `references/ingest.md` (sink contract). Recipe pack: `mcp/recipes/` in the fdeops install (file, granola, notion).
+
+**Who runs setup:** you guide; the **host** (Cursor/Claude) must save MCP config. You cannot silently install servers into the host.
+
+## Honest contract
+
+- FDEOps = **sink** (`fdeops-ingest` / `fde ingest`). Sources = **whatever MCP the FDE adds**.
+- You produce a ready config snippet + steps. They save + reload. Then you verify with a capability check + optional test stage.
+- Never invent that Granola/Notion is available if tools are missing. Never ambient sync. Never auto-apply to `.fde/`.
+
+## Method
+
+1. **Ask one question** — which source? (`file` / `granola` / `notion` / other name). If "other", ask for the MCP package or docs URL they intend to use.
+2. **Capability check (current session)** — list MCP tools you can actually call:
+   - Sink present? (`ingest_stage` / `ingest_list` / or `fde ingest` CLI)
+   - Source present? (anything that can fetch that system's content)
+   - Say clearly: *available now* vs *needs config*.
+3. **Emit config** — open the matching recipe under `mcp/recipes/<source>.md`. Fill absolute paths:
+   - path to `mcp/fdeops-ingest/server.js` (from this fdeops install)
+   - `FDEOPS_ENGAGEMENT` → this client's `…/<slug>/.fde`
+   - placeholders for source API keys (tell them to paste secrets into host env — do not commit keys into the fieldbook)
+4. **Tell them where to paste** — Cursor: MCP settings / `~/.cursor/mcp.json` (or project MCP). Claude Code: MCP config per their docs. One sentence: save → reload MCP / restart session.
+5. **Verify** — after they confirm reload: re-run capability check. If source tools appear, offer a **test pull** into `.inbox/` only (stage + show list). Stop before apply unless they ask to propose.
+6. **Handoff phrase** — give them the daily line, e.g. `@fde pull today's Acme Granola into the fieldbook`.
+
+## If they only want the sink
+
+Still wire `fdeops-ingest` (or rely on CLI). File drops work with [mcp/recipes/file.md](../../../mcp/recipes/file.md) without any source MCP.
+
+## Checkpoint
+
+Before ending connect: (1) sink reachable, (2) source reachable or honest gap, (3) they know the pull phrase. Do not write `.fde/` during connect.

package/skills/fde/references/ingest.md

@@ -2,6 +2,8 @@
 
 **Enter when:** the FDE wants to catch the engagement up from external sources — "make sure Acme is up to date," "pull what's relevant," "grab today's Granola and Denise's last email." Raw transcripts and long emails that are too big to paste usefully.
 
+**Connect / capability (different entry):** "connect a new MCP", "connect Granola/Notion", "what can you pull?" → `references/ingest-connect.md` first. Recipes: `mcp/recipes/` (file, granola, notion).
+
 **Read first:** `context.md` (what's already logged, what's stale). Bind the engagement before staging anything.
 
 **Who runs the CLI:** you (the agent). Never tell the FDE to type `fde ingest …`. Never auto-apply. Never background-sync or poll sources on your own.
@@ -13,10 +15,18 @@
 - The core `fde` CLI stays local (git + file reads). Source credentials live with that MCP; fdeops never stores them.
 - After apply, raw stays in `.inbox/`; the system of record (`.fde/`) stays thin dated facts.
 
+## Capability check (before every pull)
+
+List what you can actually call **this session**:
+
+1. **Sink** — `ingest_stage` / `fde ingest` available?
+2. **Sources** — which fetch tools exist (Granola-shaped, Notion, Drive, file-only)?
+3. Tell the FDE in one line: *I can pull from X; Y is not connected.* If they asked to pull Y and it is missing → switch to `ingest-connect.md`. Never pretend a source exists.
+
 ## Ground loop (you do this work)
 
 1. **Bind** the engagement (`fde resume` / registry). If multiple meetings or threads could apply, ask **one** clarifying question — which meeting, which thread, which date range.
-2. **Fetch** via the FDE's available source MCP(s). You pull; the CLI does not reach the network.
+2. **Capability check** (above). Then **fetch** via available source MCP(s). You pull; the CLI does not reach the network.
 3. **Stage** — `fde ingest stage [--source NAME] [--title TEXT] [file|-]` writes raw text into `<engagement>/.inbox/` (outside the memory git ledger).
 4. **List** (optional) — `fde ingest list` shows staged items when you need an id or filename.
 5. **Propose** — `fde ingest propose <id-or-filename>` runs the debrief `--smart` path on the staged body (+ provenance line). Opens `.debrief-propose`.
@@ -47,9 +57,9 @@ fde ingest apply
 
 When a staged fact came from a named source, carry `via:<source>` on the applied line where useful (e.g. `via:granola`, `via:gmail`). Helps receipts and sponsor disputes later — not mandatory on every context line.
 
-## MCP sink
+## MCP sink + recipes
 
-Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate — the FDE adds whichever fetch tools they trust.
+Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate — the FDE adds whichever fetch tools they trust. Setup coach: `ingest-connect.md`. Copy-paste recipes: `mcp/recipes/`.
 
 ## Checkpoint