fdeops 3.10.2 → 3.11.1

package/bin/lib/vault.js

@@ -0,0 +1,323 @@
+'use strict'
+
+// Derived Obsidian view of the fieldbook. Pure builders: in comes already-redacted
+// engagement data, out comes a list of { rel, content } files. No fs, no network.
+//
+// Two rules this file exists to keep:
+//   1. `.fde/` stays the only source of truth. Nothing here is ever parsed back,
+//      so an FDE can edit the vault, delete it, or ignore it with no consequence.
+//   2. The vault is an output of the CLI, so <private> blocks are already gone
+//      before anything reaches these builders (callers use readClean). `redacted`
+//      goes further and drops the political layer for a shared screen.
+
+const FORMAT = 1
+const STAMP = '.fdeops-vault'
+
+// Obsidian resolves [[links]] by note name, and | # ^ [ ] break the link syntax.
+// A client called "Acme | EU" must still get a reachable page.
+function safeTitle(s) {
+  return String(s || '')
+    .replace(/[[\]|#^\\/:*?"<>]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim() || 'untitled'
+}
+
+function cell(s) {
+  return String(s || '').replace(/\|/g, '\\|').replace(/\n+/g, ' ').trim()
+}
+
+function yamlStr(s) {
+  return `"${String(s == null ? '' : s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+}
+
+// Frontmatter is what makes the vault queryable (Obsidian properties, Dataview,
+// Bases). It exists only in generated files - the authoritative .fde/ markdown
+// stays plain, so a client can read it without a tool.
+function frontmatter(fields) {
+  const lines = ['---']
+  for (const [k, v] of Object.entries(fields)) {
+    if (v == null || v === '') continue
+    if (Array.isArray(v)) {
+      if (!v.length) continue
+      lines.push(`${k}:`)
+      v.forEach(item => lines.push(`  - ${yamlStr(item)}`))
+    } else if (typeof v === 'number' || typeof v === 'boolean') {
+      lines.push(`${k}: ${v}`)
+    } else {
+      lines.push(`${k}: ${yamlStr(v)}`)
+    }
+  }
+  lines.push('---', '')
+  return lines.join('\n')
+}
+
+function trustWord(trust) {
+  return String(trust || '').toLowerCase() === 'red' ? 'red' : String(trust || '')
+}
+
+// A signal token is internal shorthand; the sponsor view keeps the fact and
+// drops the grading. Whole section bodies pass through here, so only the space
+// the token itself occupied is closed up: a global whitespace collapse ate the
+// newlines, glued headings to prose and broke every table on these pages.
+function stripInternalTokens(text) {
+  return String(text || '')
+    .replace(/[^\S\n]*\[signal:(red|amber|green)\]/gi, '')
+    .replace(/[^\S\n]*\[@[^\]]+\]/g, '')
+    .trim()
+}
+
+function sectionPage({ eng, title, body, kind, redacted, today }) {
+  return frontmatter({
+    client: eng.name,
+    fde_page: kind,
+    phase: eng.signals.phase === '?' ? '' : eng.signals.phase,
+    generated: today,
+    tags: ['fdeops', `fdeops/${kind}`],
+  }) + `# ${safeTitle(eng.name)} - ${title}\n\n` +
+    `Engagement: [[${safeTitle(eng.name)}]]\n\n` +
+    (body.trim() ? body.trim() + '\n' : `*(nothing recorded yet)*\n`) +
+    `\n---\n*Generated from \`${eng.name}/.fde/${kind}.md\`${redacted ? ' - sponsor-safe copy' : ''}. Edit the fieldbook, not this page.*\n`
+}
+
+function personPage({ eng, person, today }) {
+  return frontmatter({
+    client: eng.name,
+    fde_page: 'person',
+    role: person.role,
+    signal: person.signal,
+    generated: today,
+    tags: ['fdeops', 'fdeops/person', `fdeops/signal/${person.signal || 'unknown'}`],
+  }) + `# ${safeTitle(person.name)}\n\n` +
+    `${person.role ? `**Role:** ${person.role}  \n` : ''}` +
+    `**Latest signal:** ${person.signal || 'unrecorded'}\n\n` +
+    (person.note ? `${person.note}\n\n` : '') +
+    `Engagement: [[${safeTitle(eng.name)}]]\n`
+}
+
+function hubPage({ eng, today, redacted }) {
+  const s = eng.signals
+  // Next action / Brief / Reality are free text an FDE types, so they carry the
+  // same internal tokens the timeline does - strip them on the sponsor page too.
+  const plain = (text) => redacted ? stripInternalTokens(text) : String(text || '')
+  const links = [
+    ['Decisions', 'decisions'],
+    ['Risks', 'risks'],
+    ['Delivery', 'delivery'],
+    ...(redacted ? [] : [['Stakeholders', 'stakeholders']]),
+    ['Terrain', 'terrain'],
+    ['Success', 'success'],
+    ...(redacted ? [] : [['Trust profile', 'trust-profile']]),
+  ].filter(([, kind]) => eng.pages[kind] != null)
+
+  const timeline = (redacted ? eng.log.filter(e => e.kind !== 'note') : eng.log)
+    .map(e => `- **${e.date}** ${cell(redacted ? stripInternalTokens(e.text) : e.text)}${e.sig && !redacted ? ` \`[${e.sig}]\`` : ''}`)
+
+  const people = redacted ? [] : eng.stakeholders.map(p =>
+    `- [[${safeTitle(eng.name)}/People/${safeTitle(p.name)}|${safeTitle(p.name)}]]${p.role ? ` - ${cell(p.role)}` : ''} \`${p.signal || 'unrecorded'}\``)
+
+  return frontmatter({
+    client: eng.name,
+    fde_page: 'engagement',
+    phase: s.phase === '?' ? '' : s.phase,
+    ...(redacted ? {} : { trust: trustWord(s.trust), signal_age_days: s.signalAge == null ? '' : s.signalAge, signal_stale: !!s.stale }),
+    open_risks: s.openRisks,
+    days_elapsed: eng.days == null ? '' : eng.days,
+    last_updated: s.updated,
+    overlay: eng.overlay || '',
+    generated: today,
+    tags: ['fdeops', 'fdeops/engagement', ...(redacted ? [] : [`fdeops/trust/${trustWord(s.trust) || 'unknown'}`])],
+  }) + [
+    `# ${safeTitle(eng.name)}`,
+    '',
+    `**Phase:** ${s.phase === '?' ? 'unset' : s.phase}` +
+      (redacted ? '' : `  ·  **Trust:** ${trustWord(s.trust)}${s.stale ? ' (signal stale - reconfirm)' : ''}`) +
+      `  ·  **Open risks:** ${s.openRisks}  ·  **Updated:** ${s.updated}`,
+    '',
+    '## Next action',
+    '',
+    eng.next ? plain(eng.next) : '*(none recorded - `fde log`/`@fde` writes one)*',
+    '',
+    ...(eng.brief ? ['## Brief', '', plain(eng.brief), ''] : []),
+    ...(eng.reality ? ['## Reality', '', plain(eng.reality), ''] : []),
+    '## The record',
+    '',
+    ...links.map(([label, kind]) => `- [[${safeTitle(eng.name)}/${label}|${label}]]`),
+    '',
+    ...(people.length ? ['## People', '', ...people, ''] : []),
+    ...(timeline.length ? ['## Timeline', '', ...timeline, ''] : []),
+    '---',
+    `*Derived from \`${eng.name}/.fde/\` on ${today}. Regenerate with \`fde vault${redacted ? ' --redacted' : ''}\`.*`,
+    '',
+  ].join('\n')
+}
+
+function portfolioPage({ engagements, today, redacted }) {
+  const order = { RED: 0, amber: 1, green: 2 }
+  const rows = [...engagements].sort((a, b) =>
+    (order[a.signals.trust] ?? 3) - (order[b.signals.trust] ?? 3) || a.name.localeCompare(b.name))
+
+  const head = redacted
+    ? ['| Engagement | Phase | Open risks | Next action |', '|---|---|---|---|']
+    : ['| Engagement | Phase | Trust | Open risks | Updated | Next action |', '|---|---|---|---|---|---|']
+
+  const body = rows.map(e => {
+    const link = `[[${safeTitle(e.name)}]]`
+    const phase = e.signals.phase === '?' ? 'unset' : e.signals.phase
+    const next = cell(redacted ? stripInternalTokens(e.next) : e.next) || '-'
+    return redacted
+      ? `| ${link} | ${phase} | ${e.signals.openRisks} | ${next} |`
+      : `| ${link} | ${phase} | ${trustWord(e.signals.trust)}${e.signals.stale ? '?' : ''} | ${e.signals.openRisks} | ${cell(e.signals.updated)} | ${next} |`
+  })
+
+  return frontmatter({
+    fde_page: 'portfolio',
+    engagements: rows.length,
+    generated: today,
+    tags: ['fdeops', 'fdeops/portfolio'],
+  }) + [
+    '# Portfolio',
+    '',
+    rows.length
+      ? `${rows.length} engagement${rows.length === 1 ? '' : 's'}${redacted ? '' : ', worst trust first'}.`
+      : 'No engagements yet - `fde resume --init <name>`.',
+    '',
+    ...(rows.length ? [...head, ...body, ''] : []),
+    ...(redacted ? [] : ['See [[Questions]] for what the record is missing.', '']),
+  ].join('\n')
+}
+
+// Deterministic answers, computed here rather than shipped as Dataview queries:
+// the vault must work in a stock Obsidian with no plugins installed.
+function questionsPage({ engagements, today }) {
+  const quiet = engagements.filter(e => e.signals.ageDays !== Infinity && e.signals.ageDays >= 14)
+  const staleSignal = engagements.filter(e => e.signals.stale)
+  const noNext = engagements.filter(e => !e.next)
+  const unaccepted = []
+  const noSignal = []
+  for (const e of engagements) {
+    for (const row of e.valueRows || []) {
+      if (!row.acceptedBy) unaccepted.push({ eng: e, row })
+    }
+    if (!e.stakeholders.length) noSignal.push(e)
+  }
+
+  const list = (items, empty) => items.length ? items : [`- ${empty}`]
+
+  return frontmatter({
+    fde_page: 'questions',
+    generated: today,
+    tags: ['fdeops', 'fdeops/questions'],
+  }) + [
+    '# Questions',
+    '',
+    'What the record cannot answer is the part worth reading. Recomputed on every `fde vault`.',
+    '',
+    '## Gone quiet (14+ days since a memory write)',
+    '',
+    ...list(quiet.map(e => `- [[${safeTitle(e.name)}]] - ${e.signals.updated}`), 'none'),
+    '',
+    '## Value promised but nobody accepted it',
+    '',
+    ...list(unaccepted.map(({ eng, row }) => `- [[${safeTitle(eng.name)}]] - ${cell(row.slice || row.promised || 'unnamed slice')}`),
+      'none - every delivered slice names a customer-side acceptor'),
+    '',
+    '## Trust signal older than 21 days',
+    '',
+    ...list(staleSignal.map(e => `- [[${safeTitle(e.name)}]] - signal ${e.signals.signalAge}d old`), 'none'),
+    '',
+    '## No stakeholder signal at all',
+    '',
+    ...list(noSignal.map(e => `- [[${safeTitle(e.name)}]]`), 'none'),
+    '',
+    '## No next action recorded',
+    '',
+    ...list(noNext.map(e => `- [[${safeTitle(e.name)}]]`), 'none'),
+    '',
+    `Portfolio: [[Portfolio]]`,
+    '',
+  ].join('\n')
+}
+
+function readmePage({ engagements, today, redacted, engagementsRoot }) {
+  return [
+    '# FDEOps vault (generated - do not keep anything here)',
+    '',
+    `Generated ${today} from \`${engagementsRoot}\`. ${engagements.length} engagement${engagements.length === 1 ? '' : 's'}.`,
+    '',
+    'Open this folder as an Obsidian vault. Start at [[Portfolio]]' + (redacted ? '.' : ' and [[Questions]].'),
+    '',
+    '## What this is',
+    '',
+    '- A **derived** view. The fieldbook at `~/fde-engagements/<client>/.fde/` is the only source of truth.',
+    '- **Disposable.** `fde vault` deletes and rebuilds this folder, so anything you type here is lost. Log to the fieldbook instead (`@fde` or `fde log`).',
+    '- **Nothing is read back.** No plugin required, no sync, no network - plain markdown, wikilinks and frontmatter.',
+    '',
+    '## What is not here',
+    '',
+    '- `<private>` blocks. They never leave `.fde/`; every page here is built from redacted reads.',
+    ...(redacted
+      ? [
+        '- Stakeholders, people pages, trust signals and `trust-profile.md` - this is the `--redacted` build, meant for a shared screen.',
+        '- Internal `[signal:x]` and `[@owner]` tokens, and contact notes in the timeline.',
+        '',
+        '**Still check before you screen-share.** Redaction removes the political layer, not judgement: `decisions.md`, `risks.md` and `delivery.md` are shown as written.',
+      ]
+      : [
+        '- Nothing else. This is the full working view, for your machine only. For a sponsor meeting run `fde vault --redacted`.',
+      ]),
+    '',
+  ].join('\n')
+}
+
+function buildVaultFiles({ engagements, today, redacted = false, engagementsRoot = '~/fde-engagements', version = '' }) {
+  const files = []
+  const SECTIONS = [
+    ['Decisions', 'decisions'],
+    ['Risks', 'risks'],
+    ['Delivery', 'delivery'],
+    ['Stakeholders', 'stakeholders'],
+    ['Terrain', 'terrain'],
+    ['Success', 'success'],
+    ['Trust profile', 'trust-profile'],
+  ]
+  const REDACTED_OUT = new Set(['stakeholders', 'trust-profile'])
+
+  files.push({ rel: 'README.md', content: readmePage({ engagements, today, redacted, engagementsRoot }) })
+  files.push({ rel: 'Portfolio.md', content: portfolioPage({ engagements, today, redacted }) })
+  if (!redacted) files.push({ rel: 'Questions.md', content: questionsPage({ engagements, today }) })
+
+  for (const eng of engagements) {
+    const dir = safeTitle(eng.name)
+    files.push({ rel: `${dir}/${dir}.md`, content: hubPage({ eng, today, redacted }) })
+    for (const [title, kind] of SECTIONS) {
+      if (redacted && REDACTED_OUT.has(kind)) continue
+      const body = eng.pages[kind]
+      if (body == null) continue
+      files.push({
+        rel: `${dir}/${title}.md`,
+        content: sectionPage({ eng, title, body: redacted ? stripInternalTokens(body) : body, kind, redacted, today }),
+      })
+    }
+    if (!redacted) {
+      for (const person of eng.stakeholders) {
+        files.push({ rel: `${dir}/People/${safeTitle(person.name)}.md`, content: personPage({ eng, person, today }) })
+      }
+    }
+  }
+
+  // A generated vault must not become a commit. `*` covers the whole tree, so a
+  // vault written inside a repo checkout stays out of `git status` too.
+  files.push({ rel: '.gitignore', content: '# generated by fde vault - never commit a client record\n*\n' })
+  files.push({
+    rel: STAMP,
+    content: JSON.stringify({
+      tool: 'fdeops', format: FORMAT, version, generated: today,
+      mode: redacted ? 'redacted' : 'full', engagements: engagements.length,
+      source: engagementsRoot,
+      note: 'Written by `fde vault`. Deleted and rebuilt on every run - this file is how the CLI knows the folder is safe to replace.',
+    }, null, 2) + '\n',
+  })
+  return files
+}
+
+module.exports = { buildVaultFiles, safeTitle, stripInternalTokens, frontmatter, STAMP, FORMAT }

package/hooks/pre-compact

@@ -7,7 +7,23 @@ resolve_engagement_dir() {
   [ -z "$raw" ] && return 1
   # strip surrounding whitespace/quotes only - paths may contain spaces
   raw=$(printf '%s' "$raw" | sed -e 's/^[[:space:]"'"'"']*//' -e 's/[[:space:]"'"'"']*$//' -e "s|^~|$HOME|")
-  [ -d "$raw" ] && printf '%s\n' "$raw" && return 0
+  # Same forms bin/fde.js accepts: an absolute .fde, an absolute engagement
+  # folder, or a bare slug under the engagements root - keep the two in lockstep.
+  # Anything relative is refused: it would resolve against whatever directory
+  # the agent happened to start in.
+  case $raw in
+    /*)
+      [ -d "$raw/.fde" ] && printf '%s\n' "$raw/.fde" && return 0
+      [ -d "$raw" ] && printf '%s\n' "$raw" && return 0
+      return 1
+      ;;
+    */*|.*) return 1 ;;
+  esac
+  local root="${FDEOPS_ENGAGEMENTS_ROOT:-$HOME/fde-engagements}"
+  root="${root/#\~/$HOME}"
+  local slug
+  slug=$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -e 's/[^a-z0-9]\+/-/g' -e 's/^-//' -e 's/-$//')
+  [ -n "$slug" ] && [ -d "$root/$slug/.fde" ] && printf '%s\n' "$root/$slug/.fde" && return 0
   return 1
 }
 
@@ -57,6 +73,13 @@ resolve_fde() {
 
 ENG_DIR=$(resolve_engagement_dir "${FDEOPS_ENGAGEMENT:-${FDEOS_ENGAGEMENT:-}}")
 
+# An override that cannot be honored is never ignored: falling through to the
+# registry would write this session into whichever engagement the workspace is
+# bound to, and the operator named a different one. bin/fde.js refuses; so do we.
+if [ -z "$ENG_DIR" ] && [ -n "${FDEOPS_ENGAGEMENT:-${FDEOS_ENGAGEMENT:-}}" ]; then
+  exit 0
+fi
+
 if [ -z "$ENG_DIR" ]; then
   ENG_DIR=$(registry_engagement_dir)
 fi

package/hooks/session-start

@@ -11,7 +11,23 @@ resolve_engagement_dir() {
   [ -z "$raw" ] && return 1
   # strip surrounding whitespace/quotes only - paths may contain spaces
   raw=$(printf '%s' "$raw" | sed -e 's/^[[:space:]"'"'"']*//' -e 's/[[:space:]"'"'"']*$//' -e "s|^~|$HOME|")
-  [ -d "$raw" ] && printf '%s\n' "$raw" && return 0
+  # Same forms bin/fde.js accepts: an absolute .fde, an absolute engagement
+  # folder, or a bare slug under the engagements root - keep the two in lockstep.
+  # Anything relative is refused: it would resolve against whatever directory
+  # the agent happened to start in.
+  case $raw in
+    /*)
+      [ -d "$raw/.fde" ] && printf '%s\n' "$raw/.fde" && return 0
+      [ -d "$raw" ] && printf '%s\n' "$raw" && return 0
+      return 1
+      ;;
+    */*|.*) return 1 ;;
+  esac
+  local root="${FDEOPS_ENGAGEMENTS_ROOT:-$HOME/fde-engagements}"
+  root="${root/#\~/$HOME}"
+  local slug
+  slug=$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -e 's/[^a-z0-9]\+/-/g' -e 's/^-//' -e 's/-$//')
+  [ -n "$slug" ] && [ -d "$root/$slug/.fde" ] && printf '%s\n' "$root/$slug/.fde" && return 0
   return 1
 }
 
@@ -46,6 +62,13 @@ if [ -z "$CONTEXT_FILE" ]; then
   [ -n "$ENG_DIR" ] && CONTEXT_FILE="$ENG_DIR/context.md"
 fi
 
+# An override that cannot be honored is never ignored: falling through to the
+# registry would load whichever engagement the workspace is bound to, and the
+# operator named a different one. bin/fde.js refuses; so do we.
+if [ -z "$CONTEXT_FILE" ] && [ -n "${FDEOPS_ENGAGEMENT:-${FDEOS_ENGAGEMENT:-}}" ]; then
+  exit 0
+fi
+
 # 2) Workspace registry binding (written by fde resume --init)
 if [ -z "$CONTEXT_FILE" ]; then
   ENG_DIR=$(registry_engagement_dir)

package/hooks/session-stop

@@ -14,7 +14,23 @@ resolve_engagement_dir() {
   [ -z "$raw" ] && return 1
   # strip surrounding whitespace/quotes only - paths may contain spaces
   raw=$(printf '%s' "$raw" | sed -e 's/^[[:space:]"'"'"']*//' -e 's/[[:space:]"'"'"']*$//' -e "s|^~|$HOME|")
-  [ -d "$raw" ] && printf '%s\n' "$raw" && return 0
+  # Same forms bin/fde.js accepts: an absolute .fde, an absolute engagement
+  # folder, or a bare slug under the engagements root - keep the two in lockstep.
+  # Anything relative is refused: it would resolve against whatever directory
+  # the agent happened to start in.
+  case $raw in
+    /*)
+      [ -d "$raw/.fde" ] && printf '%s\n' "$raw/.fde" && return 0
+      [ -d "$raw" ] && printf '%s\n' "$raw" && return 0
+      return 1
+      ;;
+    */*|.*) return 1 ;;
+  esac
+  local root="${FDEOPS_ENGAGEMENTS_ROOT:-$HOME/fde-engagements}"
+  root="${root/#\~/$HOME}"
+  local slug
+  slug=$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -e 's/[^a-z0-9]\+/-/g' -e 's/^-//' -e 's/-$//')
+  [ -n "$slug" ] && [ -d "$root/$slug/.fde" ] && printf '%s\n' "$root/$slug/.fde" && return 0
   return 1
 }
 
@@ -77,6 +93,13 @@ ENG_DIR=""
 # 1) Environment variable (any agent)
 ENG_DIR=$(resolve_engagement_dir "${FDEOPS_ENGAGEMENT:-${FDEOS_ENGAGEMENT:-}}")
 
+# An override that cannot be honored is never ignored: falling through to the
+# registry would write this session into whichever engagement the workspace is
+# bound to, and the operator named a different one. bin/fde.js refuses; so do we.
+if [ -z "$ENG_DIR" ] && [ -n "${FDEOPS_ENGAGEMENT:-${FDEOS_ENGAGEMENT:-}}" ]; then
+  exit 0
+fi
+
 # 2) Workspace registry binding (written by fde resume --init)
 if [ -z "$ENG_DIR" ]; then
   ENG_DIR=$(registry_engagement_dir)

package/mcp/fdeops-ingest/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.10.2",
+  "version": "3.11.1",
   "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/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "3.10.2",
+  "version": "3.11.1",
   "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",

package/skills/fde/SKILL.md

@@ -74,7 +74,7 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
 - Data tagged `<private>` (sacred data, PHI, cardholder, classified) is **redacted from CLI, dashboard, and hook-injected context**. Do **not** open raw `<private>` blocks with file tools (that bypasses redaction) or paste them into prompts/subagents - work around them, never with them.
 - Locked-down engagement (no AI on their code)? Use the CLI + the fieldbook only. The memory layer is the FDE's own notes, not customer code.
 
-**Engagement path - zero ceremony.** Run `fde resume` (fallback: `node ~/.claude/fdeops/fde.js resume`). The **workspace registry** (written once by `fde resume --init <name>`) is the normal path; resolution order is env var override → registry → pointer file → workspace-name match (read-only) → `./.fde`. Writes require a bind (or `FDEOPS_ENGAGEMENT`), not folder name alone. It prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init <name>` yourself - the one setup step; the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control.
+**Engagement path - zero ceremony.** Run `fde resume` (fallbacks, in order: `node ~/.claude/fdeops/fde.js resume`, then `npx --yes fdeops resume` - the CLI is one command away on any machine with Node, so reach for it before doing memory work by hand). The **workspace registry** (written once by `fde resume --init <name>`) is the normal path; resolution order is env var override → registry → pointer file → workspace-name match (read-only) → `./.fde`. Writes require a bind (or `FDEOPS_ENGAGEMENT`), not folder name alone. It prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init <name>` yourself - the one setup step; the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control.
 
 **You run the `fde` CLI for deterministic work - never improvise shell, never hand the command to the FDE:**
 
@@ -90,12 +90,13 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
 | "Draft the sponsor update" / how are we doing | `fde status` then follow `references/status.md` for the narrative |
 | "Log that they went quiet" / trust signal | `fde log contact "…" --signal amber\|green\|red`. If they already named the color ("log that as amber"), that is the confirm — write it. If they only described the situation, playback the color once, then write. |
 | Want the HTML fieldbook | `fde dashboard` |
+| "Open my clients in Obsidian" / one window over everything / "can I show this to the sponsor?" | `fde vault` (add `--redacted` for a shared screen). Derived and disposable: it is rebuilt from `.fde/` on every run and never read back, so tell them to keep logging to the fieldbook, not to the vault. |
 | "Clean up the fieldbook" / hygiene / memory feels messy | `fde doctor` - walk issues in plain language; propose fixes; never auto-rewrite without confirm. Includes structural gaps: empty operating map (plan+), stakeholder name forks (Denise vs Denise Chen), duplicates, ship/close risks. Contradictions need judgment (brief vs reality) - doctor is structural; you handle meaning. |
 | "Scrub this secret / redact that token" (buried line, not just last write) | `fde redact <term>` preview, then `fde redact <term> --apply` after confirm. Undo is last-write only; redact is for buried lines. Remind them to rotate the real credential. |
 
 **The debrief verb.** Highest-frequency loop. When the FDE shares notes or says "debrief": **you** run the smart path (write notes to a temp file if needed). `--smart` writes a propose file via deterministic heuristics (existing prefixes + light keywords); authentic rambling notes often land mostly in context until **you** rewrite lines with type prefixes. Show the proposed routing in plain language. Only `--apply` (or pipe prefixed lines) after they confirm. Never ask them to run the CLI. Detail: `references/debrief.md`.
 
-CLI missing → use the manual fallbacks inside each reference (still you write files; still never ask the FDE to run setup).
+CLI genuinely unavailable (no Node, offline, npx blocked) → use the manual fallbacks inside each reference (still you write files; still never ask the FDE to run setup). A skill-only install is not "unavailable": run the verb through `npx --yes fdeops …` so the gates, dating and redaction still hold.
 
 **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.
 

package/templates/.fde/assumptions.md

@@ -4,8 +4,8 @@
 
 | # | Assumption | Blast radius | How we test | Status | Evidence |
 |---|------------|--------------|-------------|--------|----------|
-| 1 | *(seed from brief - stated, unverified)* | CRITICAL / LOAD-BEARING / CONVENIENCE | | OPEN | |
 
-**Status values:** `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`
+**Blast radius:** `CRITICAL` · `LOAD-BEARING` · `CONVENIENCE`  
+**Status:** `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`
 
 **Rule:** a CRITICAL assumption still OPEN blocks plan. DISPROVED → update `reality.md` / `success.md` and log the reset in `decisions.md` the same day.

package/templates/.fde/decisions.md

@@ -6,13 +6,5 @@
 
 ## Decision log
 
-<!-- Use this format for each decision. The rationale is the part that survives the engagement. -->
-
-<!--
-### [Date] Decision title
-- Context: what prompted this decision
-- Options considered: what was on the table
-- Decision: what was chosen
-- Rationale: why this over the alternatives
-- Owner: who approved
--->
+<!-- Dated lines: what was chosen, and why over the alternatives. Long form: docs/schema.md
+     - [2026-07-18] kept the vendor connector over an in-house rewrite - Priya wants the Q3 audit clean first -->

package/templates/.fde/delivery.md

@@ -6,7 +6,9 @@
 
 | Date | Slice | Bucket | Promised | Measured | Accepted by | Evidence | Rollback |
 |------|-------|--------|----------|----------|-------------|----------|----------|
-| | | *(cost-save / risk-mitigation / revenue-uplift)* | *(what we said it would change)* | *(what actually changed, or pending)* | *(customer-side name + date, or it stays claimed)* | *(who/when/metric)* | |
+
+**Bucket:** `cost-save` · `risk-mitigation` · `revenue-uplift`  
+**Accepted by:** a customer-side name and date - without one the value stays *claimed*, not accepted.
 
 ## Ship receipts
 
@@ -14,7 +16,9 @@
 
 | Date | Slice | Audit receipt | Eval receipt |
 |------|-------|---------------|--------------|
-| | | *(dated cite: exceptions/operating path verified — terrain/reality/audit)* | *(n/a \| evals.md pass + HITL owner)* |
+
+**Audit receipt:** dated cite that the exception/operating path was verified (`terrain.md` / `reality.md`).  
+**Eval receipt:** `n/a` unless AI touches the slice, else `evals.md` pass + the HITL owner.
 
 ## Shipped
 

package/templates/.fde/evals.md

@@ -13,13 +13,11 @@
 
 | ID | Input (sanitized) | Expected | Pass rule | Last run | Result |
 |----|-------------------|----------|-----------|----------|--------|
-| G1 | | | | | |
 
 ## Failure modes
 
 | Mode | How it shows up | Detection | Mitigation |
 |------|-----------------|-----------|------------|
-| | | | |
 
 ## Pass / fail (this ship)
 - **Golden:** _/_ pass (threshold: _)
@@ -31,7 +29,6 @@
 
 | Decision / action | Autonomous OK? | Reviewer role | Escalation |
 |-------------------|----------------|---------------|------------|
-| | | | |
 
 **HITL rule for this ship:**
 
@@ -39,4 +36,3 @@
 
 | Date | What changed | Pack re-run? | Notes |
 |------|--------------|--------------|-------|
-| | | | |

package/templates/.fde/risks.md

@@ -2,4 +2,6 @@
 
 | Risk | Status | Owner | Mitigation |
 |------|--------|-------|------------|
-| | open | | |
+
+**Status:** `open` · `mitigating` · `closed` · `accepted`  
+<!-- `fde log risk "<text>"` appends a dated line; the table is for live, owned risk. -->

package/templates/.fde/stakeholders.md

@@ -5,7 +5,8 @@
 
 | Name | Role | Stance | Notes |
 |------|------|--------|-------|
-| | | champion / neutral / resistant | |
+
+**Stance:** `champion` · `neutral` · `resistant`
 
 **Trust signal:** green | amber | red  
 **Last trust check:**

package/templates/.fde/terrain.md

@@ -13,7 +13,6 @@
 
 | Exception / break | Who notices first | What they do today (workaround) | System of record then | Blast if wrong | Evidence |
 |-------------------|-------------------|---------------------------------|-----------------------|----------------|----------|
-| | | | | | |
 
 **Shadow systems / silent workarounds:**
 **Sacred / untouchable in ops:**
@@ -23,4 +22,3 @@
 
 | Step | Deterministic | Model judgement | Human approve |
 |------|---------------|-----------------|---------------|
-| | | | |