fdeops 3.9.19 → 3.10.0

package/bin/install.js

@@ -53,6 +53,49 @@ function slugify(name) {
     || 'engagement'
 }
 
+// Written into every skill directory this installer creates. Nothing is ever
+// removed or overwritten without it: `healthcare-fde` and `fintech-fde` are
+// plausible names for a skill the user wrote themselves, and a name collision
+// must be reported, not silently resolved by deleting their work.
+const MANAGED_MARKER = '.fdeops-managed'
+
+function markManaged(dir) {
+  let version = 'unknown'
+  try { version = require(path.join(__dirname, '..', 'package.json')).version } catch (_) {}
+  try {
+    fs.writeFileSync(
+      path.join(dir, MANAGED_MARKER),
+      `managed-by: fdeops\nversion: ${version}\ninstalled: ${new Date().toISOString()}\n` +
+      'Delete this file to make fdeops treat the directory as yours and leave it alone.\n',
+    )
+  } catch (_) {}
+}
+
+function isManaged(dir) {
+  return fs.existsSync(path.join(dir, MANAGED_MARKER))
+}
+
+// A skill "directory" that is really a symlink points somewhere outside
+// ~/.claude/skills that fdeops has no claim on. Writing through it would edit
+// files in the user's own tree - refuse even under --force, which is permission
+// to take over this location, not to follow it elsewhere.
+function isLink(p) {
+  try { return fs.lstatSync(p).isSymbolicLink() } catch (_) { return false }
+}
+
+// Fingerprint of a skill fdeops itself wrote before markers existed. Anchored on
+// the shipped frontmatter, not a bare "fdeops" substring: a skill of the user's
+// that merely mentions fdeops in prose is theirs, not ours. Only consulted for a
+// directory whose name matches one we ship, and only to overwrite - never to delete.
+function wasInstalledByUs(dir) {
+  try {
+    const md = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8')
+    const fm = (md.match(/^---\n([\s\S]*?)\n---/) || [])[1]
+    if (!fm) return false
+    return /^description:\s*Engagement fieldbook for Forward Deployed Engineers\b/im.test(fm)
+  } catch (_) { return false }
+}
+
 // v2 shipped 16 standalone skills; v3 is one `fde` skill + references.
 // Leaving the old ones in place would route users to stale content.
 const LEGACY_SKILL_DIRS = [
@@ -62,22 +105,105 @@ const LEGACY_SKILL_DIRS = [
   'gov-fde',
 ]
 
-function removeLegacySkills() {
+function removeLegacySkills(opts = {}) {
   let removed = 0
+  const skipped = []
+  const links = []
   for (const dir of LEGACY_SKILL_DIRS) {
     const p = path.join(GLOBAL_SKILLS_DIR, dir)
-    if (fs.existsSync(path.join(p, 'SKILL.md'))) {
+    if (isLink(p)) { links.push(dir); continue }
+    if (!fs.existsSync(path.join(p, 'SKILL.md'))) continue
+    if (isManaged(p) || opts.force) {
       fs.rmSync(p, { recursive: true, force: true })
       removed++
+    } else {
+      skipped.push(dir)
     }
   }
-  return removed
+  return { removed, skipped, links }
 }
 
-function installSkills() {
-  const removed = removeLegacySkills()
-  if (removed > 0) console.log(`  Removed ${removed} v2 skill dir(s) (now covered by @fde)`)
-  copyDir(SKILLS_SRC, GLOBAL_SKILLS_DIR)
+// Copy each skill in, but never over a directory fdeops did not create.
+function installSkillDirs(opts = {}) {
+  const skipped = []
+  const links = []
+  const failed = []
+  fs.mkdirSync(GLOBAL_SKILLS_DIR, { recursive: true })
+  for (const entry of fs.readdirSync(SKILLS_SRC, { withFileTypes: true })) {
+    const src = path.join(SKILLS_SRC, entry.name)
+    const dest = path.join(GLOBAL_SKILLS_DIR, entry.name)
+    if (!entry.isDirectory()) { fs.copyFileSync(src, dest); continue }
+    if (isLink(dest)) { links.push(entry.name); continue }
+    if (fs.existsSync(dest) && !isManaged(dest) && !opts.force) {
+      // Installs predating the marker are still ours: adopt a same-named dir
+      // whose SKILL.md is recognizably fdeops', so upgrades keep working.
+      if (!wasInstalledByUs(dest)) {
+        skipped.push(entry.name)
+        continue
+      }
+      console.log(`  adopt  ~/.claude/skills/${entry.name} (earlier fdeops install)`)
+    }
+    // One unwritable skill dir must not abort the install with a stack trace:
+    // say it in human terms, place the rest, and exit non-zero at the end.
+    try {
+      copyDir(src, dest)
+      markManaged(dest)
+    } catch (e) {
+      failed.push({ name: entry.name, code: e.code || 'error', path: destPathFor(e.path, src, dest) })
+    }
+  }
+  return { skipped, links, failed }
+}
+
+// A failed copy can surface either side of the operation; the user can only fix
+// the destination, so never point them at a path inside the package.
+function destPathFor(failedPath, src, dest) {
+  if (!failedPath) return dest
+  if (failedPath === src || failedPath.startsWith(src + path.sep)) {
+    return path.join(dest, path.relative(src, failedPath))
+  }
+  return failedPath
+}
+
+function reportCollisions(paths, verb) {
+  if (!paths.length) return
+  console.log(`  skip   ${paths.length} skill dir(s) fdeops did not create - ${verb} would destroy your own work:`)
+  for (const name of paths) console.log(`           ~/.claude/skills/${name}`)
+  console.log('         move or delete them yourself, or re-run with --force to let fdeops take them over')
+}
+
+function reportLinks(names) {
+  if (!names.length) return
+  console.log(`  skip   ${names.length} skill path(s) that are symlinks - fdeops will not write through them:`)
+  for (const name of names) console.log(`           ~/.claude/skills/${name} -> ${readLinkQuiet(path.join(GLOBAL_SKILLS_DIR, name))}`)
+  console.log('         remove the link if you want fdeops to install at that path itself')
+}
+
+function readLinkQuiet(p) {
+  try { return fs.readlinkSync(p) } catch (_) { return '(unreadable)' }
+}
+
+// Anything here means part of the install did not land; cmdInstall exits non-zero.
+let installIncomplete = false
+function reportFailures(failures) {
+  if (!failures.length) return
+  installIncomplete = true
+  console.log(`  error  ${failures.length} skill dir(s) could not be written:`)
+  for (const f of failures) {
+    const why = f.code === 'EACCES' || f.code === 'EPERM' ? 'permission denied' : f.code
+    console.log(`           ~/.claude/skills/${f.name} - ${why} at ${f.path}`)
+  }
+  console.log('         fix the permissions (or remove the directory) and re-run - the rest of the install continued')
+}
+
+function installSkills(opts = {}) {
+  const legacy = removeLegacySkills(opts)
+  if (legacy.removed > 0) console.log(`  Removed ${legacy.removed} v2 skill dir(s) (now covered by @fde)`)
+  const placed = installSkillDirs(opts)
+  reportCollisions(legacy.skipped, 'removing them')
+  reportCollisions(placed.skipped, 'overwriting them')
+  reportLinks([...new Set([...legacy.links, ...placed.links])])
+  reportFailures(placed.failed)
   fs.mkdirSync(GLOBAL_HOOKS_DIR, { recursive: true })
   for (const name of HOOK_SCRIPTS) {
     const src = path.join(HOOKS_SRC, name)
@@ -138,7 +264,7 @@ function placePointer(destPath, content, label, appendable) {
   console.log(`  write  ${label}`)
 }
 
-function cmdAdapters(targetDir) {
+function cmdAdapters(targetDir, opts = {}) {
   const dest = path.resolve(targetDir || process.cwd())
   console.log('')
   console.log(`  fdeops cross-platform adapters → ${dest}`)
@@ -150,7 +276,7 @@ function cmdAdapters(targetDir) {
   // yet, a dangling reference for anyone following the documented Cursor/Codex
   // path. installSkills() is idempotent (safe to call every run).
   if (!fs.existsSync(path.join(GLOBAL_SKILLS_DIR, 'fde', 'SKILL.md'))) {
-    installSkills()
+    installSkills(opts)
     console.log('  Skills → ~/.claude/skills/  (installed - the pointers below need this)')
     console.log('')
   }
@@ -198,11 +324,11 @@ function cmdInit(engagementName) {
   console.log('')
 }
 
-function cmdInstall() {
+function cmdInstall(opts = {}) {
   console.log('')
   console.log('  fdeops - installs on YOUR machine only')
   console.log('')
-  installSkills()
+  installSkills(opts)
   console.log('  Skills → ~/.claude/skills/')
   console.log('  Hooks → ~/.claude/hooks/fdeops-*')
   console.log('  CLI → ~/.claude/fdeops/fde.js  (try: node ~/.claude/fdeops/fde.js scan)')
@@ -220,22 +346,99 @@ function cmdInstall() {
   console.log('  Then open your workspace and use @fde')
   console.log('  Docs: docs/install.md')
   console.log('')
+  // A partly-installed skill set is not success - a script that ran this must be
+  // able to tell, and the reason is already printed above.
+  if (installIncomplete) process.exit(1)
 }
 
 // `npx fdeops scan` must recon, not install - any fde subcommand passes straight
 // through to the CLI (fde.js reads process.argv itself, so require() is enough).
 const FDE_SUBCOMMANDS = [
-  'scan', 'resume', 'triage', 'log', 'debrief', 'ingest', 'prep', 'doctor', 'redact',
-  'garden', 'owner', 'receipts', 'capture', 'status', 'dashboard', 'help',
+  'demo', 'scan', 'resume', 'triage', 'log', 'debrief', 'ingest', 'prep', 'doctor', 'redact',
+  'garden', 'owner', 'receipts', 'capture', 'preserve', 'status', 'dashboard', 'help',
 ]
 
-const arg = process.argv[2]
-if (arg === 'init') {
-  cmdInit(process.argv[3])
-} else if (arg === 'adapters') {
-  cmdAdapters(process.argv[3])
-} else if (FDE_SUBCOMMANDS.includes(arg)) {
+const INSTALL_SUBCOMMANDS = ['init', 'adapters', 'install']
+
+function editDistance(a, b) {
+  let prev = [...Array(b.length + 1).keys()]
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    prev = row
+  }
+  return prev[b.length]
+}
+
+function nearest(word, known) {
+  const w = word.toLowerCase()
+  let best = null
+  let bestScore = 3
+  for (const k of known) {
+    const d = editDistance(w, k)
+    if (d < bestScore) { best = k; bestScore = d }
+  }
+  return best
+}
+
+const argv = process.argv.slice(2)
+const force = argv.includes('--force')
+const positional = argv.filter(a => !a.startsWith('-'))
+const raw = positional[0]
+// `fdeops Demo` is a typo, not a request to rewrite ~/.claude: verbs match
+// case-insensitively, and anything unrecognized fails loudly instead of
+// falling through to a full install. Asking a question (`--help`, `--version`)
+// is not consent to write to the home directory either.
+const known = INSTALL_SUBCOMMANDS.concat(FDE_SUBCOMMANDS)
+const arg = raw ? known.find(k => k === raw.toLowerCase()) : undefined
+const askedHelp = argv.some(a => /^--?(h|help)$/i.test(a))
+const askedVersion = argv.some(a => /^--?(v|version)$/i.test(a))
+
+// Flags before the verb belong to fdeops, so an unknown one is a mistake worth
+// saying out loud - the alternative is honoring `fdeops --all status` by
+// quietly dropping --all.
+const FDEOPS_FLAGS = /^--?(force|h|help|v|version)$/i
+const leading = (raw === undefined ? argv : argv.slice(0, argv.indexOf(raw))).filter(a => !FDEOPS_FLAGS.test(a))
+if (leading.length) {
+  console.error(`  fdeops: unknown option '${leading[0]}'${raw ? ` before '${raw}' - put command options after the command: fdeops ${raw} ${leading[0]}` : ''}`)
+  console.error('  fdeops itself takes only --force, --help and --version.')
+  process.exit(1)
+}
+
+if (raw && !arg) {
+  const guess = nearest(raw, known)
+  console.error(`  fdeops: unknown command '${raw}'${guess ? ` - did you mean '${guess}'?` : ''}`)
+  console.error('  Run `npx fdeops help` for the command list, or `npx fdeops` with no arguments to install.')
+  process.exit(1)
+}
+
+// The verb the user typed may not be argv[0] (`fdeops --force redact ledger`),
+// and fde.js reads process.argv itself - hand it back the positional order it
+// expects with only the verb's case normalized.
+function handOffToCli(verb) {
+  // fde.js reads process.argv itself and takes the verb first, so hand it the
+  // verb (case-normalized) plus everything the user typed after it. A flag
+  // typed BEFORE the verb (`fdeops --force redact ledger`) belongs to fdeops,
+  // not to the command - passing it on would make it part of the command's own
+  // arguments (here: a search term of "--force ledger").
+  const at = raw === undefined ? -1 : argv.indexOf(raw)
+  const rest = at === -1 ? [] : argv.slice(at + 1)
+  process.argv = [process.argv[0], process.argv[1], verb, ...rest]
   require(path.join(__dirname, 'fde.js'))
+}
+
+if (!raw && askedVersion) {
+  console.log(require(path.join(__dirname, '..', 'package.json')).version)
+} else if (!raw && askedHelp) {
+  handOffToCli('help')
+} else if (arg === 'init') {
+  cmdInit(positional[1])
+} else if (arg === 'adapters') {
+  cmdAdapters(positional[1], { force })
+} else if (arg && arg !== 'install') {
+  handOffToCli(arg)
 } else {
-  cmdInstall()
+  cmdInstall({ force })
 }

package/bin/lib/memory.js

@@ -3,7 +3,7 @@
 const { execFileSync } = require('child_process')
 
 // Ephemeral sidecar files - never treated as "manual tamper" dirt.
-const MEMORY_EPHEMERAL = new Set(['.last-write', '.debrief-propose'])
+const MEMORY_EPHEMERAL = new Set(['.last-write', '.debrief-propose', '.debrief-private', '.debrief-seal'])
 
 function createMemoryApi(deps) {
   const { fs, path, gitBinOk, writeOwnerIfMissing, atomicWriteFile } = deps
@@ -131,7 +131,7 @@ function createMemoryApi(deps) {
       execFileSync('git', ['init'], { cwd: eng, stdio: 'ignore', timeout: 10000 })
       atomicWriteFile(
         path.join(eng, '.gitignore'),
-        ['*.lock', '*.tmp', '.last-write', '.debrief-propose', ''].join('\n')
+        ['*.lock', '*.tmp', '.last-write', '.debrief-propose', '.debrief-private', '.debrief-seal', ''].join('\n')
       )
       const owner = writeOwnerIfMissing(eng)
       configureMemoryGitIdentity(eng, owner)

package/bin/lib/render.js

@@ -196,6 +196,7 @@ strong{font-weight:600}
 .fb-log-date{font-family:'Geist Mono',monospace;font-size:11.5px;color:var(--ink-faint);flex:0 0 48px}
 .fb-log-kind{font-family:'Geist Mono',monospace;font-size:10px;letter-spacing:.03em;text-transform:uppercase;flex:0 0 62px}
 .fb-log-text{flex:1 1 auto;font-size:14px;line-height:1.5;color:var(--ink)}
+.fb-log-sig{font-family:'Geist Mono',monospace;font-size:10px;letter-spacing:.03em;text-transform:uppercase;white-space:nowrap}
 .fb-more{border-top:1px solid var(--line);padding:12px 0}
 .fb-more:first-child{border-top:none;padding-top:0}
 .fb-more-sum{cursor:pointer;list-style:none;display:flex;align-items:center;gap:6px}
@@ -537,6 +538,7 @@ ${e.log.map(g => `<div class="fb-row fb-log">
 <span class="fb-log-date">${escapeHtml(formatLogDate(g.date))}</span>
 <span class="fb-log-kind t-${g.kind === 'receipt' ? 'green' : g.kind === 'decision' ? 'accent' : 'faint'}">${escapeHtml(g.kind)}</span>
 <span class="fb-log-text">${inlineMd(g.text)}</span>
+${g.sig ? `<span class="fb-log-sig t-${g.sig}" title="trust signal ${escapeHtml(g.sig)}">●&nbsp;${escapeHtml(g.sig)}</span>` : ''}
 </div>`).join('\n')}
 </div>
 </div>` : ''

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:
@@ -46,6 +50,4 @@ Source MCPs are **not** bundled in fdeops. To add Granola, Gmail, or another pro
 
 FDEOps credentials stay local to the CLI; source MCP credentials stay with that MCP.
 
-## Design reference
-
-See [`docs/plans/2026-07-29-ingest-mcp-design.md`](../docs/plans/2026-07-29-ingest-mcp-design.md) for the approved ingest MCP design.
+**Non-goals:** no bundled OAuth/connectors, no ambient sync, no unreviewed writes to `.fde/`. Method: [`skills/fde/references/ingest.md`](../skills/fde/references/ingest.md).

package/mcp/fdeops-ingest/README.md

@@ -22,7 +22,9 @@ Each tool returns `{ stdout, stderr, status }` from the CLI.
 
 ## Configure in Cursor / Claude
 
-Add to your MCP config (`~/.cursor/mcp.json`, Claude Desktop config, etc.):
+**Agent Plugins clients: nothing to configure.** fdeops ships a root [`mcp.json`](../../mcp.json) declaring this server as `stdio` with a `${PLUGIN_ROOT}`-relative path, so a client that supports [Agent Plugins 1.0.0](https://agent-plugins.org/specification) wires it on install - no absolute paths to edit.
+
+Everywhere else, add to your MCP config (`~/.cursor/mcp.json`, Claude Desktop config, etc.):
 
 ```json
 {

package/mcp/fdeops-ingest/package.json

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

package/mcp/fdeops-ingest/server.js

@@ -70,31 +70,41 @@ const TOOLS = [
 let readBuffer = Buffer.alloc(0)
 
 function writeMessage(obj) {
-  const body = JSON.stringify(obj)
-  process.stdout.write(`Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`)
+  process.stdout.write(`${JSON.stringify(obj)}\n`)
 }
 
+// MCP stdio frames messages by newline. Content-Length headers are tolerated on
+// input only, so an LSP-style client still gets through.
 function parseMessages() {
   const messages = []
-  while (true) {
-    const headerEnd = readBuffer.indexOf('\r\n\r\n')
-    if (headerEnd === -1) break
-
-    const header = readBuffer.slice(0, headerEnd).toString('utf8')
-    const match = header.match(/Content-Length:\s*(\d+)/i)
-    if (!match) {
-      readBuffer = readBuffer.slice(headerEnd + 4)
+  while (readBuffer.length) {
+    if (/^Content-Length:/i.test(readBuffer.slice(0, 15).toString('utf8'))) {
+      const headerEnd = readBuffer.indexOf('\r\n\r\n')
+      if (headerEnd === -1) break
+      const header = readBuffer.slice(0, headerEnd).toString('utf8')
+      const match = header.match(/Content-Length:\s*(\d+)/i)
+      if (!match) {
+        readBuffer = readBuffer.slice(headerEnd + 4)
+        continue
+      }
+      const length = parseInt(match[1], 10)
+      const bodyStart = headerEnd + 4
+      if (readBuffer.length < bodyStart + length) break
+      const body = readBuffer.slice(bodyStart, bodyStart + length).toString('utf8')
+      readBuffer = readBuffer.slice(bodyStart + length)
+      try {
+        messages.push(JSON.parse(body))
+      } catch (_) {}
       continue
     }
 
-    const length = parseInt(match[1], 10)
-    const bodyStart = headerEnd + 4
-    if (readBuffer.length < bodyStart + length) break
-
-    const body = readBuffer.slice(bodyStart, bodyStart + length).toString('utf8')
-    readBuffer = readBuffer.slice(bodyStart + length)
+    const newline = readBuffer.indexOf('\n')
+    if (newline === -1) break
+    const line = readBuffer.slice(0, newline).toString('utf8').trim()
+    readBuffer = readBuffer.slice(newline + 1)
+    if (!line) continue
     try {
-      messages.push(JSON.parse(body))
+      messages.push(JSON.parse(line))
     } catch (_) {}
   }
   return messages

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/mcp.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "fdeops-ingest": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/mcp/fdeops-ingest/server.js"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.9.19",
+  "version": "3.10.0",
   "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",
@@ -20,7 +20,9 @@
     "adapters/",
     "mcp/",
     "CLAUDE.md.template",
-    "AGENTS.md"
+    "AGENTS.md",
+    "plugin.json",
+    "mcp.json"
   ],
   "keywords": [
     "claude-code",

package/plugin.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "fdeops",
+  "version": "3.10.0",
+  "description": "Engagement fieldbook for Forward Deployed Engineers: per-client memory in local .fde/ files, one @fde skill, land to close methodology. Local-only, no network.",
+  "author": {
+    "name": "Subash Natarajan",
+    "url": "https://github.com/suboss87"
+  },
+  "homepage": "https://fdeops.io/",
+  "repository": "https://github.com/suboss87/FDEOps",
+  "license": "MIT",
+  "keywords": [
+    "fde",
+    "forward-deployed",
+    "engagement-memory",
+    "client-work",
+    "consulting",
+    "brownfield"
+  ]
+}