fdeops 3.29.0 → 3.31.0

package/README.md

@@ -56,6 +56,8 @@ Read-only HTML of the record - promised, measured, accepted, and evidence. Regen
 /plugin install fdeops@fdeops
 ```
 
+Make it fit your day: `fde setup` asks how you work, what would help first, and what to mask before sharing context with your agent. [First-use setup](docs/USAGE.md#make-fdeops-fit-your-day).
+
 The plugin adds session hooks and the slash commands below. Skill-only installation does not add hooks. See the [installation guide](docs/install.md) for setup details.
 
 </details>

package/bin/fde.js

@@ -46,8 +46,26 @@ const ENGAGEMENTS_ROOT = ((process.env.FDEOPS_ENGAGEMENTS_ROOT || '').trim().rep
   || path.join(HOME, 'fde-engagements')
 const REGISTRY = path.join(ENGAGEMENTS_ROOT, '.registry')
 const masking = require('./lib/masking').createMasking(ENGAGEMENTS_ROOT)
+const setup = require('./lib/setup')
+const setupStore = setup.createSetup(ENGAGEMENTS_ROOT)
+let preferences = setup.DEFAULTS
+function contextBudget(args) {
+  return context.budgetArgs(args, preferences.context === 'compact' ? 4096 : 16384)
+}
+function portfolioView(args) {
+  if (args.includes('--all') && args.includes('--current')) throw new Error('Choose --all or --current, not both.')
+  return args.includes('--all') || (!args.includes('--current') && preferences.view === 'portfolio')
+}
 function maskDisplay(text) {
-  return ['dashboard', 'vault'].includes(process.argv[2]) ? String(text) : masking.mask(text)
+  return ['dashboard', 'vault'].includes(process.argv[2]) && preferences.privacy !== 'reports' ? String(text) : masking.mask(text)
+}
+// Classify the original record first; aliases must never become evidence or a signer.
+function maskReport(value) {
+  if (preferences.privacy !== 'reports') return value
+  if (typeof value === 'string') return masking.mask(value)
+  if (Array.isArray(value)) return value.map(maskReport)
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskReport(item)]))
+  return value
 }
 function maskedSections(sections, maxBytes) {
   return context.boundedSections(sections.map(text => masking.mask(text)), maxBytes)
@@ -80,9 +98,9 @@ function gitIsAncestor(eng, olderHash, newerHash) {
   } catch (_) { return false }
 }
 
-function gitLogHash(eng, args) {
+function gitLogHash(eng, args, format = '%H') {
   try {
-    return execFileSync('git', ['log', '-1', '--format=%H', ...args], {
+    return execFileSync('git', ['log', '-1', `--format=${format}`, ...args], {
       cwd: eng, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 15000,
     }).trim()
   } catch (_) { return '' }
@@ -803,7 +821,7 @@ function phaseLabel(phase) {
 // colon) collapses to '' here, which callers treat as "nothing to show".
 function firstLine(md, maxLen) {
   for (const raw of md.split('\n')) {
-    const l = raw.trim()
+    const l = maskDisplay(raw).trim()
     if (!l || /^#{1,6}\s/.test(l)) continue
     const clean = maskDisplay(l.replace(/^\*\*[^*]+:\*\*\s*/, '').replace(/\*\*/g, '').replace(/^["']|["']$/g, '').trim())
     if (!clean) continue
@@ -990,7 +1008,7 @@ const {
   countOpenRisks,
 } = createTrustApi({
   fs, path, readClean, readEng, parseMdTable, sectionBody, SIGNAL_LEDGER, memoryDirtyManual,
-  stripTemplateNoise, stripLegendLines, extractRisks,
+  stripTemplateNoise, stripLegendLines, extractRisks, maskDisplay,
 })
 
 // Stakeholders: columns are matched by header wording, not position - real
@@ -1023,6 +1041,7 @@ function parseSignalHistoryEntries(eng) {
 }
 
 function displayNameFromSignalText(text) {
+  if ((preferences.privacy === 'reports' || !['dashboard', 'vault'].includes(process.argv[2])) && masking.mask(text) !== text) return 'Contact (identifier masked)'
   const person = personFromSignalText(text)
   if (person) return person
   const t = String(text).trim()
@@ -1147,7 +1166,7 @@ function extractRisks(eng) {
 // sides look like real numbers/percentages, deduped by value pair, capped at
 // 4; nothing reliable found -> the widget stays empty, never an invented number.
 function extractStats(eng) {
-  const text = readClean(eng, 'delivery.md') + '\n' + readClean(eng, 'decisions.md')
+  const text = maskDisplay(readClean(eng, 'delivery.md') + '\n' + readClean(eng, 'decisions.md'))
   const patterns = [
     /(\d+(?:\.\d+)?%)[^\n%]{0,40}?(?:→|->)[^\n%]{0,20}?(\d+(?:\.\d+)?%)/g, // "X% ... -> Y%"
     /(\d+(?:\.\d+)?%)\s+to\s+(\d+(?:\.\d+)?%)/gi,                               // "X% to Y%"
@@ -1162,7 +1181,7 @@ function extractStats(eng) {
       const key = from + '→' + to
       if (seen.has(key)) continue
       seen.add(key)
-      const pre = text.slice(Math.max(0, m.index - 40), m.index)
+      const pre = maskDisplay(text.slice(0, m.index)).slice(-40)
       const label = pre.split(/\s+/).filter(Boolean).slice(-3).join(' ').replace(/^[,:;.\-]+|[,:;.\-]+$/g, '') || 'metric'
       stats.push({ label, from, to })
     }
@@ -1315,7 +1334,7 @@ function cmdScan() {
 
 function cmdResume(args) {
   let maxBytes
-  try { ({ args, maxBytes } = context.budgetArgs(args)) } catch (e) { console.error(e.message); process.exit(2) }
+  try { ({ args, maxBytes } = contextBudget(args)) } catch (e) { console.error(e.message); process.exit(2) }
 
   const initIdx = args.indexOf('--init')
   if (initIdx !== -1) {
@@ -1400,6 +1419,10 @@ function cmdResume(args) {
       const head = memoryHead(fdeDir)
       console.log(`memory git: ${head || 'ready'}${owner ? `  owner: ${owner.email}` : ''}`)
     }
+    if (!setupStore.read()) {
+      if (process.stdin.isTTY && process.stdout.isTTY) return setup.command(setupStore, [])
+      console.log('Make FDEOps fit your day: run fde setup once for three short choices. Agents: ask these after binding; do not guess the answers.')
+    }
     return
   }
   if (args[0] === '--bind') {
@@ -1435,6 +1458,7 @@ function cmdResume(args) {
   const risks = readClean(eng, 'risks.md')
   process.stdout.write(maskedSections([
     policy ? `CLIENT POLICY - trust-profile.md\n${policy}` : '',
+    preferences.work ? `WORKING PREFERENCES: ${preferences.work}. Starting help: ${preferences.start}.\n${setup.nextStep(preferences)}\nThis is a starting preference, not a client fact; current instructions and engagement state take precedence.` : '',
     `${intro}\n\nENGAGEMENT: ${eng}`,
     success ? `CURRENT GOALS & ACCEPTANCE - success.md\n${success}` : '',
     risks ? `OPEN RISKS - risks.md\n${extractRisks(eng).map(r => r.text).join('\n') || '(none recorded)'}` : '',
@@ -1552,7 +1576,7 @@ function cmdLog(args) {
   if (hit && force) console.error(`warning: logging possible ${hit} (--force)`)
   if (retire) {
     const n = retireOpenRisks(eng, text)
-    if (!n) { console.error(`no open risk matched ${JSON.stringify(text)}`); process.exit(1) }
+    if (!n) { console.error(`no open risk matched ${JSON.stringify(masking.mask(text))}`); process.exit(1) }
     const hash = commitMemory(eng, 'retire risk', { files: ['risks.md'] })
     console.log(`retired ${n} risk(s) → risks.md${hash ? ` @${hash}` : ''}`)
     return
@@ -1982,7 +2006,7 @@ function changeReviewIssues(eng) {
   const del = latestDeliveryEntry(readClean(eng, 'delivery.md'))
   const dec = latestDatedDecision(readClean(eng, 'decisions.md'))
   const delHash = del.line
-    ? sh(`git log -1 --format=%H -S${JSON.stringify(del.line)} -- delivery.md`, eng)
+    ? gitLogHash(eng, ['-S', del.line, '--', 'delivery.md'])
     : ''
   if (del.date && dec.date && dec.date > del.date && delHash) {
     issues.push(
@@ -2548,7 +2572,7 @@ function cmdReceipts(args) {
 // overwrites an engagement record, existing file, or symlink.
 function cmdHandoff(args, label = 'Handoff') {
   let parsed
-  try { parsed = context.budgetArgs(args) } catch (e) { console.error(e.message); process.exit(1) }
+  try { parsed = contextBudget(args) } catch (e) { console.error(e.message); process.exit(1) }
   let out = ''
   if (parsed.args.length) {
     if (parsed.args.length !== 2 || parsed.args[0] !== '--out' || !parsed.args[1] || parsed.args[1].startsWith('--')) {
@@ -2594,7 +2618,7 @@ function cmdHandoff(args, label = 'Handoff') {
 
 function cmdRecall(args) {
   let maxBytes
-  try { ({ args, maxBytes } = context.budgetArgs(args)) } catch (e) { console.error(e.message); process.exit(2) }
+  try { ({ args, maxBytes } = contextBudget(args)) } catch (e) { console.error(e.message); process.exit(2) }
   const query = args.join(' ').trim()
   if (!query || Buffer.byteLength(query) > 2048 || args.some(a => a.startsWith('--'))) {
     console.error('usage: fde recall <topic> [--max-bytes 4096..65536]'); process.exit(2)
@@ -2796,7 +2820,7 @@ function silentCommitIssues(eng) {
     // Pickaxe on the entry text, not the file: a later status edit to
     // delivery.md must not become the cutoff and hide commits before it.
     const raw = entry.line
-      ? sh(`git log -1 --format=%cI -S${JSON.stringify(entry.line)} -- delivery.md`, eng)
+      ? gitLogHash(eng, ['-S', entry.line, '--', 'delivery.md'], '%cI')
       : ''
     // git --since is inclusive at second grain; a commit in the same second as
     // the receipt is the receipt's own work, not a silent one.
@@ -3332,10 +3356,10 @@ function cmdRedact(args) {
     })
   }
   if (!hits.length) {
-    console.log(`redact: no lines contain ${JSON.stringify(term)}`)
+    console.log(`redact: no lines contain ${JSON.stringify(masking.mask(term))}`)
     return
   }
-  console.log(`REDACT - ${hits.length} matching line(s) for ${JSON.stringify(term)}`)
+  console.log(`REDACT - ${hits.length} matching line(s) for ${JSON.stringify(masking.mask(term))}`)
   hits.slice(0, 20).forEach(h => {
     const preview = h.line.length > 100 ? masking.mask(h.line).slice(0, 97) + '…' : h.line
     console.log(`  ${h.file}:${h.lineNo}  ${preview}`)
@@ -3609,7 +3633,7 @@ function engagementSlugFromPath(eng) {
 }
 
 function cmdStatus(args) {
-  const all = args.includes('--all')
+  const all = portfolioView(args)
   if (!fs.existsSync(ENGAGEMENTS_ROOT)) { console.log('no engagements yet - fde resume --init <name>'); return }
   const rows = []
   if (all) {
@@ -3678,7 +3702,7 @@ function gatherEngagements(opts = {}) {
 }
 
 function cmdDashboard(args) {
-  const all = args.includes('--all')
+  const all = portfolioView(args)
   const outIdx = args.indexOf('--out')
   const outPath = outIdx !== -1 && args[outIdx + 1]
     ? path.resolve(args[outIdx + 1].replace(/^~/, HOME))
@@ -3734,17 +3758,17 @@ function cmdDashboard(args) {
       ['trust-profile.md', 'Trust profile'],
     ].map(([f, title]) => [title, readClean(e.dir, f)])
     .filter(([, md]) => render.hasRealContent(md))
-    .map(([title, md]) => ({ title, html: render.mdBlockHtml(md, parseMdTable) }))
-    e.searchBlob = render.escapeHtml([
+    .map(([title, md]) => ({ title, html: render.mdBlockHtml(maskDisplay(md), parseMdTable) }))
+    e.searchBlob = render.escapeHtml(maskDisplay([
       e.name, e.next, e.lastSession, e.reality, e.brief,
       ...e.log.map(g => g.text), ...e.risks.map(r => r.text),
       ...e.stakeholders.map(p => `${p.name} ${p.role} ${p.note}`),
       ...e.moreSections.map(s => s.title),
       ...e.valueRows.map(r => `${r.slice} ${r.promised} ${r.measured} ${r.accepted} ${r.evidence}`),
-    ].join(' ').toLowerCase())
+    ].join(' ').toLowerCase()))
   })
 
-  const html = render.buildFieldbookHtml({ engagements, today, generatedAt: new Date().toISOString() })
+  const html = render.buildFieldbookHtml({ engagements: maskReport(engagements), today, generatedAt: new Date().toISOString() })
 
   try {
     const isRecordPath = p => p.split(path.sep).some(part => ['.fde', '.git'].includes(part.toLowerCase()))
@@ -3915,10 +3939,10 @@ function cmdVault(args) {
   })
 
   const files = vault.buildVaultFiles({
-    engagements,
+    engagements: maskReport(engagements),
     today: render.formatToday(new Date()),
     redacted,
-    engagementsRoot: ENGAGEMENTS_ROOT,
+    engagementsRoot: maskReport(ENGAGEMENTS_ROOT),
     version: cliVersion(),
   })
 
@@ -4102,6 +4126,7 @@ ${fs.existsSync(html) ? `\n  Open the fieldbook:  ${html}` : ''}
 function printUsage() {
   console.log(`fde - deterministic core of fdeops
   fde demo                 the whole loop on a fake client (fde demo --clean removes it)
+  fde setup                three first-use choices (or --show for saved preferences)
   fde privacy              show masking capability and its boundaries
   fde scan                 day-1 recon of this repo (facts, no AI)
   fde resume               load this workspace's engagement memory (bounded)
@@ -4131,8 +4156,8 @@ function printUsage() {
   fde receipts <term>      source-backed records versus claims
   fde defend              sponsor readout: accepted assertions, claims, sources, gaps
   fde handoff [--out file] portable redacted packet; stdout by default, new file only
-  fde status [--all]       value ledger, then trust (pass --all for full portfolio)
-  fde dashboard [--all] [--open] [--out <path>]  bound fieldbook (pass --all for every client)
+  fde status [--all|--current] value ledger, then trust (scope follows setup)
+  fde dashboard [--all|--current] [--open] [--out <path>] fieldbook (scope follows setup)
   fde vault                derived Obsidian vault of every engagement (--current for one, --redacted for a shared screen, --out <dir>)
   hooks call these; you do not: capture (session-end snapshot), preserve (pre-compaction snapshot)
   env FDEOPS_ENGAGEMENTS_ROOT  override ~/fde-engagements (init/status/dashboard/registry)
@@ -4144,9 +4169,10 @@ function printUsage() {
 const [cmd, ...rawArgs] = process.argv.slice(2)
 let outputBudget
 if (['resume', 'recall', 'handoff', 'defend'].includes(cmd) && !rawArgs.some(a => ['--full', '--init', '--bind', '--out'].includes(a))) {
-  try { outputBudget = context.budgetArgs(rawArgs).maxBytes } catch (_) {}
+  try { outputBudget = context.budgetArgs(rawArgs, (setupStore.read() || setup.DEFAULTS).context === 'compact' ? 4096 : 16384).maxBytes } catch (_) {}
 }
-require('./lib/masking').protectOutput(masking, { maxBytes: outputBudget })
+require('./lib/masking').protectOutput(cmd === 'setup' && rawArgs.length === 1 && rawArgs[0] === '--show'
+  ? require('./lib/masking').createMasking(ENGAGEMENTS_ROOT, { custom: false }) : masking, { maxBytes: outputBudget })
 let args
 try {
   args = rawArgs.map(arg => masking.restore(arg))
@@ -4162,14 +4188,17 @@ if (args.includes('--help') || args.includes('-h') || cmd === 'help' || cmd ===
   process.exit(0)
 }
 try {
+  if (cmd !== 'setup' && cmd !== 'privacy') preferences = setupStore.read() || setup.DEFAULTS
+  const finishAsync = result => { if (result && typeof result.catch === 'function') result.catch(error => { console.error(error.message); process.exitCode = 1 }) }
 switch (cmd) {
+  case 'setup': finishAsync(setup.command(setupStore, args)); break
   case 'privacy':
     if (args.length) { console.error('usage: fde privacy'); process.exitCode = 2; break }
-    console.log(`FDEOps ${require('../package.json').version} - identifier masking enabled by default.\nCLI responses, smart proposals, handoff packets and ingest MCP results use local aliases.\nPatterns: common emails, international/US phones, SSN-shaped identifiers and supported credentials.\nNames and arbitrary sensitive prose are not detected; mark them <private>.\nRaw files, pasted chat, upstream MCP content and local dashboard/vault files bypass this protection.`)
+    console.log(`FDEOps ${require('../package.json').version} - identifier masking enabled by default.\nCLI responses, smart proposals, handoff packets and ingest MCP results use local aliases.\nPatterns: common emails, international/US phones, SSN-shaped identifiers and supported credentials.\nNames and arbitrary sensitive prose are not automatically detected; mark them <private> or supply local custom terms with fde setup.\nRaw files, pasted chat and upstream MCP content bypass this protection. Local reports retain identifiers by default; fde setup can also mask newly generated report content.`)
     break
   case 'demo': cmdDemo(args); break
   case 'scan': cmdScan(); break
-  case 'resume': cmdResume(args); break
+  case 'resume': finishAsync(cmdResume(args)); break
   case 'recall': cmdRecall(args); break
   case 'triage': cmdTriage(); break
   case 'log': cmdLog(args); break

package/bin/install.js

@@ -376,7 +376,7 @@ function cmdInstall(opts = {}) {
 // `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 = [
-  'demo', 'scan', 'resume', 'triage', 'log', 'debrief', 'ingest', 'prep', 'doctor', 'redact',
+  'setup', 'privacy', 'demo', 'scan', 'resume', 'triage', 'log', 'debrief', 'ingest', 'prep', 'doctor', 'redact',
   'tidy', 'garden', 'owner', 'receipts', 'recall', 'handoff', 'defend', 'capture', 'preserve', 'status', 'dashboard', 'vault', 'help',
 ]
 

package/bin/lib/context.js

@@ -14,9 +14,9 @@ function clipUtf8(text, bytes) {
   while (end > 0 && (buf[end] & 0xc0) === 0x80) end--
   return buf.subarray(0, end).toString('utf8')
 }
-function budgetArgs(args) {
+function budgetArgs(args, defaultBytes = DEFAULT_BYTES) {
   const rest = [...args]
-  let maxBytes = DEFAULT_BYTES
+  let maxBytes = defaultBytes
   const at = rest.indexOf('--max-bytes')
   if (at !== -1) {
     const raw = rest[at + 1]

package/bin/lib/masking.js

@@ -6,7 +6,7 @@ const fs = require('node:fs')
 const path = require('node:path')
 const crypto = require('node:crypto')
 const { StringDecoder } = require('node:string_decoder')
-const ALIAS = /\[\[(email|phone|identifier|credential):[a-f0-9]{16}\]\]/g
+const ALIAS = /\[\[(email|phone|identifier|credential|term):[a-f0-9]{16}\]\]/g
 const PATTERNS = [
   ['credential', /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?(?:-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|$)/g],
   ['credential', /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,})\b/g],
@@ -25,7 +25,27 @@ function replacements(text, replace) {
   for (const [kind, pattern] of PATTERNS) out = out.replace(pattern, value => replace(kind, value))
   return out
 }
-function createMasking(root) {
+function createMasking(root, { custom = true } = {}) {
+  const settings = require('./setup').createSetup(root)
+  function replaceAll(text, replace) {
+    let terms = []
+    if (custom) {
+      const profile = settings.read()
+      if (profile && profile.masking === 'custom') terms = profile.terms
+    }
+    const escape = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const pattern = terms.length ? new RegExp(terms.slice().sort((a, b) => b.length - a.length).map(term =>
+      '(?<![\\p{L}\\p{N}_])' + escape(term) + '(?![\\p{L}\\p{N}_])').join('|'), 'giu') : null
+    // Existing aliases are protocol tokens, never input for further masking.
+    const pieces = String(text).split(/(\[\[(?:email|phone|identifier|credential|term):[a-f0-9]{16}\]\])/g)
+    return pieces.map((piece, i) => {
+      if (i % 2) return piece
+      const builtIn = replacements(piece, replace)
+      if (!pattern) return builtIn
+      return builtIn.split(/(\[\[(?:email|phone|identifier|credential|term):[a-f0-9]{16}\]\])/g)
+        .map((part, j) => j % 2 ? part : part.replace(pattern, value => replace('term', value))).join('')
+    }).join('')
+  }
   const directory = path.join(root, '.privacy'), file = path.join(directory, 'identifiers.json')
   function directoryReady(create) {
     if (create) fs.mkdirSync(root, { recursive: true })
@@ -43,7 +63,7 @@ function createMasking(root) {
       if (data.version !== 1 || !Array.isArray(data.entries) || data.entries.length > 50000) throw new Error(FAIL)
       const seen = new Set()
       for (const entry of data.entries) {
-        if (!entry || typeof entry.value !== 'string' || !/^\[\[(email|phone|identifier|credential):[a-f0-9]{16}\]\]$/.test(entry.alias) || seen.has(entry.alias)) throw new Error(FAIL)
+        if (!entry || typeof entry.value !== 'string' || !/^\[\[(email|phone|identifier|credential|term):[a-f0-9]{16}\]\]$/.test(entry.alias) || seen.has(entry.alias)) throw new Error(FAIL)
         seen.add(entry.alias)
       }
       return data
@@ -76,11 +96,11 @@ function createMasking(root) {
   function mask(text) {
     text = String(text)
     let detected = false
-    replacements(text, (_, value) => { detected = true; return value })
+    replaceAll(text, (_, value) => { detected = true; return value })
     if (!detected) return text
     return transact(true, entries => {
       const values = new Map(entries.map(e => [e.value, e.alias]))
-      return replacements(text, (kind, value) => {
+      return replaceAll(text, (kind, value) => {
         if (!values.has(value)) {
           const alias = `[[${kind}:${crypto.randomBytes(8).toString('hex')}]]`
           entries.push({ alias, value }); values.set(value, alias)
@@ -91,7 +111,7 @@ function createMasking(root) {
   }
   function restore(text) {
     text = String(text)
-    if (/\[\[(email|phone|identifier|credential):/.test(text.replace(ALIAS, ''))) throw new Error(FAIL)
+    if (/\[\[(email|phone|identifier|credential|term):/.test(text.replace(ALIAS, ''))) throw new Error(FAIL)
     if (!text.match(ALIAS)) return text
     return transact(false, entries => {
       const aliases = new Map(entries.map(e => [e.alias, e.value]))

package/bin/lib/memory.js

@@ -53,7 +53,7 @@ function createMemoryApi(deps) {
           execFileSync('git', ['add', '--', f], { cwd: eng, stdio: 'ignore', timeout: 10000 })
         }
       } else {
-        execFileSync('git', ['add', '-A', '--', '.', ':(exclude).privacy'], { cwd: eng, stdio: 'ignore', timeout: 10000 })
+        execFileSync('git', ['add', '-A', '--', '.', ':(exclude).privacy', ':(exclude).preferences.json'], { cwd: eng, stdio: 'ignore', timeout: 10000 })
       }
       const porcelain = execFileSync('git', ['status', '--porcelain'], {
         cwd: eng, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'],
@@ -73,7 +73,7 @@ function createMemoryApi(deps) {
         }
       }
       // Even a previously staged alias dictionary must never enter a CLI commit.
-      const privateStaged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: eng, encoding: 'utf8', timeout: 10000 }).split('\n').some(f => f.split('/').includes('.privacy'))
+      const privateStaged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: eng, encoding: 'utf8', timeout: 10000 }).split('\n').some(f => f.split('/').some(part => ['.privacy', '.preferences.json'].includes(part)))
       if (privateStaged) throw new Error('private alias state must not be staged in engagement history')
       const still = execFileSync('git', ['diff', '--cached', '--name-only'], {
         cwd: eng, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'],
@@ -134,7 +134,7 @@ function createMemoryApi(deps) {
       execFileSync('git', ['init'], { cwd: eng, stdio: 'ignore', timeout: 10000 })
       atomicWriteFile(
         path.join(eng, '.gitignore'),
-        ['*.lock', '*.tmp', '.last-write', '.debrief-propose', '.debrief-private', '.debrief-seal', '.privacy/', ''].join('\n')
+        ['*.lock', '*.tmp', '.last-write', '.debrief-propose', '.debrief-private', '.debrief-seal', '.privacy/', '.preferences.json', ''].join('\n')
       )
       const owner = writeOwnerIfMissing(eng)
       configureMemoryGitIdentity(eng, owner)

package/bin/lib/setup.js

@@ -0,0 +1,191 @@
+'use strict'
+const fs = require('node:fs')
+const path = require('node:path')
+const crypto = require('node:crypto')
+const paths = require('./install-paths')
+
+const DEFAULTS = { view: 'current', context: 'standard', privacy: 'agent' }
+const SETTINGS = [
+  { key: 'view', title: 'What should your daily overview show?', options: [
+    ['current', 'The client I am working on'], ['portfolio', 'All my clients'],
+  ] },
+  { key: 'context', title: 'How much context should your agent start with?', options: [
+    ['standard', 'Standard (up to 16 KiB)'], ['compact', 'Compact (up to 4 KiB; retrieve details as needed)'],
+  ] },
+  { key: 'privacy', title: 'Where should common identifiers be masked?', options: [
+    ['agent', 'Agent context; keep originals in my local reports'],
+    ['reports', 'Agent context and newly generated Fieldbook/vault reports'],
+  ] },
+]
+const QUESTIONS = [
+  { key: 'work', title: 'How do you work?', options: [
+    ['single', 'One client'], ['multiple', 'Several clients'], ['team', 'Leading a delivery team'],
+  ] },
+  { key: 'start', title: 'What would help you first?', options: [
+    ['new', 'Starting an engagement'], ['daily', 'Continuing daily work'], ['takeover', 'Taking over existing work'],
+  ] },
+  { key: 'masking', title: 'What should FDEOps hide before sharing context with your agent?', options: [
+    ['standard', 'Common identifiers and secrets'], ['custom', 'Those, plus names and terms I specify'],
+  ] },
+]
+const PROFILE_DEFAULTS = { work: 'single', start: 'daily', masking: 'standard', terms: [] }
+const LIMITS = 'Both choices hide marked private content. Masking reduces exposure; it does not guarantee anonymity or permission to share client data. Raw file tools, pasted chat and other tools can bypass it. AI-provider settings are unchanged.'
+function validateTerms(terms) {
+  if (!Array.isArray(terms) || terms.length > 100 || terms.some(t => typeof t !== 'string' || t.length < 2 || t.length > 128 || t !== t.trim() || /[\r\n\x00-\x1f]|\[\[|\]\]/.test(t))) {
+    throw new Error('Use up to 100 names or terms, one per line, each 2-128 characters; control characters and alias markers are not allowed.')
+  }
+  return [...new Set(terms)]
+}
+function validate(value) {
+  const keys = value && Object.keys(value)
+  const personal = value && Object.hasOwn(value, 'work')
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      keys.length !== (personal ? 7 : 3) ||
+      (personal ? SETTINGS.concat(QUESTIONS) : SETTINGS).some(q => !q.options.some(([v]) => value[q.key] === v))) {
+    throw new Error('Invalid setup choices; run fde setup to see the supported options.')
+  }
+  if (personal) {
+    validateTerms(value.terms)
+    if (value.masking === 'custom' && !value.terms.length) throw new Error('Custom masking needs at least one name or term.')
+  }
+  return value
+}
+function readTerms(file) {
+  let fd
+  try {
+    paths.checkPath(file)
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
+    const st = fs.fstatSync(fd)
+    if (!st.isFile() || st.nlink !== 1 || st.size > 65536) throw new Error('unsafe')
+    const terms = validateTerms(fs.readFileSync(fd, 'utf8').split(/\r?\n/).map(t => t.trim()).filter(Boolean))
+    if (!terms.length) throw new Error('empty')
+    return terms
+  } catch (_) { throw new Error('Cannot load custom terms. Use an ordinary local UTF-8 file with 1-100 terms, one per line, each 2-128 characters.') }
+  finally { if (fd !== undefined) fs.closeSync(fd) }
+}
+function nextStep(value) {
+  const start = {
+    new: 'Clarify the client problem, one measurable outcome, and who will accept it. Start with land.',
+    daily: 'Resume the current client and choose one action from the existing blockers. Start with triage.',
+    takeover: 'Check the existing evidence, open risks and previous commitments before changing anything. Start with audit.',
+  }
+  return (start[value.start] || '') + (value.work === 'team' ? ' Make responsibility and handoff clear; do not assume shared access or synchronization.' : '')
+}
+function createSetup(root) {
+  const file = path.join(root, '.preferences.json')
+  function read() {
+    let fd
+    try {
+      paths.checkPath(file)
+      fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
+      const st = fs.fstatSync(fd)
+      if (!st.isFile() || st.nlink !== 1 || st.size > 65536 || (process.platform !== 'win32' && (st.mode & 0o077))) throw new Error('unsafe')
+      return validate(JSON.parse(fs.readFileSync(fd, 'utf8')))
+    } catch (e) {
+      if (e.code === 'ENOENT') return null
+      throw new Error('Cannot read setup safely. Check .preferences.json in your engagements folder; no settings were changed.')
+    } finally { if (fd !== undefined) fs.closeSync(fd) }
+  }
+  function save(value) {
+    validate(value)
+    paths.mkdir(root)
+    paths.checkPath(file)
+    const temporary = path.join(root, `.preferences-${crypto.randomBytes(12).toString('hex')}.tmp`)
+    try {
+      fs.writeFileSync(temporary, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 })
+      paths.checkPath(file)
+      fs.renameSync(temporary, file)
+    } finally { try { fs.unlinkSync(temporary) } catch (_) {} }
+  }
+  return { read, save }
+}
+function describe(value, questions = QUESTIONS) {
+  return questions.map(q => `${q.title} ${q.options.find(([v]) => v === value[q.key])[1]}`).join('\n')
+}
+function saveAnswers(store, choices, questions, termsFile) {
+  const saved = store.read(), current = saved || DEFAULTS
+  if (questions.some(q => !q.options.some(([v]) => choices[q.key] === v)) || Object.keys(choices).length !== questions.length) throw new Error('Supply one valid answer for each question.')
+  let result
+  if (questions === SETTINGS) result = { ...current, ...choices }
+  else {
+    if (termsFile && choices.masking !== 'custom') throw new Error('A terms file requires custom masking.')
+    const terms = termsFile ? readTerms(termsFile) : current.terms || []
+    result = { ...current, ...choices, terms, view: !saved || (saved.work && saved.work !== choices.work) ? (choices.work === 'multiple' ? 'portfolio' : 'current') : saved.view }
+  }
+  store.save(result)
+  return result
+}
+function command(store, args) {
+  if (args.length === 1 && args[0] === '--show') {
+    const saved = store.read(), { terms, ...safe } = saved || DEFAULTS
+    console.log(JSON.stringify({ configured: !!saved, ...safe, ...(terms ? { termCount: terms.length, nextStep: nextStep(saved) } : {}) }))
+    return
+  }
+  if (args.length && !(args.length === 1 && args[0] === '--settings')) {
+    const choices = {}, rest = args.filter(a => a !== '--save')
+    let termsFile
+    if (args.filter(a => a === '--save').length !== 1) throw new Error('Use fde setup, or supply all three answers with --save.')
+    for (let i = 0; i < rest.length; i += 2) {
+      const key = rest[i].replace(/^--/, '')
+      if (key === 'terms-file' && !termsFile && rest[i + 1]) { termsFile = rest[i + 1]; continue }
+      if (!rest[i].startsWith('--') || !SETTINGS.concat(QUESTIONS).some(q => q.key === key) || Object.hasOwn(choices, key)) throw new Error('Unknown or repeated setup option.')
+      choices[key] = rest[i + 1]
+    }
+    const questions = Object.hasOwn(choices, 'work') ? QUESTIONS : SETTINGS
+    if (termsFile && questions === SETTINGS) throw new Error('Use personal setup to change custom terms.')
+    const result = saveAnswers(store, choices, questions, termsFile)
+    console.log('Setup saved locally. Change it anytime with fde setup.\n' + describe(result, questions) + '\n' + nextStep(result) + '\n' + LIMITS)
+    return
+  }
+  const questions = args[0] === '--settings' ? SETTINGS : QUESTIONS
+  if (process.stdin.isTTY && process.stdout.isTTY) return interactive(store, questions)
+  console.log('SETUP: ask these three questions together. No settings have been changed.')
+  for (const [i, q] of questions.entries()) console.log(`${i + 1}. ${q.title}\n` + q.options.map(([value, label]) => `   ${value}: ${label}`).join('\n'))
+  console.log(LIMITS)
+  console.log(questions === QUESTIONS
+    ? 'After answers: fde setup --work single|multiple|team --start new|daily|takeover --masking standard|custom [--terms-file LOCAL_FILE] --save\nFor custom masking, enter names locally with fde setup, or provide a local terms-file path; do not ask to paste sensitive names into chat. Existing terms are kept unless a replacement file is supplied.'
+    : 'Save settings: fde setup --view current|portfolio --context standard|compact --privacy agent|reports --save')
+  console.log('fde setup --show shows choices and term count only. fde setup --settings changes display and context options.')
+}
+async function interactive(store, questions) {
+  const emit = text => fs.writeSync(1, text)
+  const current = { ...PROFILE_DEFAULTS, ...(store.read() || DEFAULTS) }, choices = {}
+  const rl = require('node:readline').createInterface({ input: process.stdin, terminal: false })
+  const lines = rl[Symbol.asyncIterator]()
+  try {
+    emit('Make FDEOps fit your work. Enter keeps the current choice. Ctrl-C cancels.\n' + LIMITS + '\n')
+    for (const q of questions) {
+      const selected = q.options.findIndex(([v]) => v === current[q.key])
+      while (true) {
+        emit(q.title + '\n' + q.options.map(([, label], i) => `  ${i + 1}. ${label}${i === selected ? ' (current)' : ''}`).join('\n') + '\n> ')
+        const next = await lines.next()
+        if (next.done) { emit('\nCancelled; nothing saved.\n'); return }
+        const value = next.value.trim(), index = value === '' ? selected : /^[123]$/.test(value) ? Number(value) - 1 : -1
+        if (index >= 0 && index < q.options.length) { choices[q.key] = q.options[index][0]; break }
+        emit('Choose a listed number, or press Enter.\n')
+      }
+    }
+    let terms = current.terms
+    if (choices.masking === 'custom') {
+      emit(`Names or terms to hide, one per line; finish with an empty line. Enter alone keeps ${terms.length} saved terms. This input stays local.\n`)
+      const entered = []
+      while (true) {
+        const next = await lines.next()
+        if (next.done) { emit('\nCancelled; nothing saved.\n'); return }
+        if (!next.value.trim()) break
+        entered.push(next.value.trim())
+        validateTerms(entered)
+      }
+      terms = entered.length ? validateTerms(entered) : terms
+      if (!terms.length) throw new Error('Custom masking needs at least one term; nothing saved.')
+    }
+    const saved = store.read()
+    const result = questions === SETTINGS ? { ...(saved || DEFAULTS), ...choices }
+      : { ...(saved || DEFAULTS), ...choices, terms, view: !saved || (saved.work && saved.work !== choices.work) ? (choices.work === 'multiple' ? 'portfolio' : 'current') : saved.view }
+    emit('\n' + describe(result, questions) + (choices.masking === 'custom' ? `\n${terms.length} custom terms ready to save locally.` : '') + '\nSave these choices? [y/N] ')
+    const next = await lines.next()
+    if (!next.done && /^y(es)?$/i.test(next.value.trim())) { store.save(result); emit('\nSetup saved. Change it anytime with fde setup.\n' + nextStep(result) + '\n') }
+    else emit('\nCancelled; nothing saved.\n')
+  } finally { rl.close() }
+}
+module.exports = { createSetup, command, DEFAULTS, nextStep }

package/bin/lib/trust.js

@@ -3,7 +3,7 @@
 function createTrustApi(deps) {
   const {
     fs, path, readClean, readEng, parseMdTable, sectionBody, SIGNAL_LEDGER, memoryDirtyManual,
-    stripTemplateNoise, stripLegendLines, extractRisks,
+    stripTemplateNoise, stripLegendLines, extractRisks, maskDisplay = text => text,
   } = deps
 
   // phase / trust / top risk / freshness - identical heuristic for status + dashboard.
@@ -138,7 +138,7 @@ function createTrustApi(deps) {
     const body = sectionBody(ctx, 'Next action', { lastNonEmpty: true })
     for (const raw of body.split('\n')) {
       const t = raw.trim().replace(/^[-*]\s+/, '')
-      if (t) return t.slice(0, 120)
+      if (t) return maskDisplay(t).slice(0, 120)
     }
     return ''
   }
@@ -180,7 +180,7 @@ function createTrustApi(deps) {
       trustReason = mem.warn
     } else if (worst) {
       trust = worst.sig === 'red' ? 'RED' : worst.sig
-      trustReason = (worst.text || '').slice(0, 80)
+      trustReason = maskDisplay(worst.text || '').slice(0, 80)
       if (worst.date) {
         signalAge = Math.max(0, Math.floor((Date.now() - Date.parse(worst.date)) / 86400000))
         stale = signalAge > 21
@@ -195,7 +195,7 @@ function createTrustApi(deps) {
       trust = sLines.some(l => /\bred\b/i.test(l)) ? 'RED'
         : sLines.some(l => /amber|gone quiet|routing around|escalat/i.test(l)) ? 'amber' : 'new'
     }
-    const topRisk = (extractRisks(eng)[0]?.text || '').replace(/\s+/g, ' ').trim().slice(0, 80)
+    const topRisk = maskDisplay((extractRisks(eng)[0]?.text || '').replace(/\s+/g, ' ').trim()).slice(0, 80)
     // Prefer trust trigger / memory warn over a random risk line; always keep mem.warn available
     const reason = (trustReason || mem.warn) ? (trustReason || mem.warn) : topRisk
     // What the triage line is actually quoting. A risk bullet printed under

package/mcp/fdeops-ingest/package.json

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

package/mcp/fdeops-ingest/server.js

@@ -176,7 +176,13 @@ function cliPayload(out) {
 
 function toolResult(payload) {
   let text
-  try { text = masking.mask(typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2)) }
+  try {
+    const clean = value => typeof value === 'string' ? masking.mask(value)
+      : Array.isArray(value) ? value.map(clean)
+      : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clean(item)])) : value
+    const safe = clean(payload)
+    text = typeof safe === 'string' ? safe : JSON.stringify(safe, null, 2)
+  }
   catch (_) { return { isError: true, content: [{ type: 'text', text: 'privacy masking unavailable; no unmasked tool output returned' }] } }
   return { content: [{ type: 'text', text }] }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.29.0",
+  "version": "3.31.0",
   "description": "Client delivery tools for Forward Deployed Engineers. One @fde skill, local Markdown engagement records, and an offline dashboard for decisions, evidence, approvals, and next actions.",
   "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.29.0",
+  "version": "3.31.0",
   "description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code. You confirm; then it lands in .fde/ on your laptop.",
   "author": {
     "name": "Subash Natarajan",

package/skills/fde/SKILL.md

@@ -56,9 +56,15 @@ Use the customer's existing coding, testing, review, and repository instructions
 
 Fallbacks: `node ~/.claude/fdeops/fde.js …`, then `npx --yes fdeops …`. Skill-only install is not "unavailable."
 
+## First-use preferences
+
+Run `fde setup --show` before client reads. If unavailable, update the CLI before offering setup. If `configured` is false, bind the named client, then run `fde setup` and present its three questions together: how they work, what would help first, and what to mask. Save their explicit answers; never infer permission to share data. For custom masking, the optional fourth question asks them to enter terms **locally** with `fde setup`, or give a local terms-file path. Do not ask them to paste sensitive names into chat or open that file with model-facing file tools. Pass the path directly to `--terms-file`; inspect only the returned count, never `.preferences.json` or the alias dictionary. If they skip, keep existing defaults.
+
+Use `work` to tailor the help: single = focus on the bound client; multiple = portfolio overview with one bound client per write; team = clarify responsibility and handoff, without implying shared storage. `start` chooses the initial route when no more specific request or record determines it: new → land, daily → triage, takeover → audit. Current client evidence and the user's request always take precedence; never restart an existing engagement because of this preference. `masking` selects standard patterns or those plus custom terms. Older technical settings remain valid; offer personal setup when requested rather than resetting them. Do not ask again per client. `fde setup --settings` keeps display, context size and report masking editable. Choices do not configure models or approve client data use.
+
 ## Entry (every session)
 
-1. `fde resume` (16 KiB output ceiling, not a model token count). Read client constraints first, then signer, goals, risks, delivery ledger and current context. This command is the inspectable packet the session hook loads; never substitute a recursive read of `.fde/` or raw transcripts. If truncated or a decision needs evidence, run `fde recall <specific topic>`; narrow the query rather than loading the whole history. `--max-bytes 4096` reduces the allowance for smaller models. `--full` only when the complete log is explicitly needed.
+1. `fde resume` (16 KiB by default, 4 KiB with compact setup; a byte ceiling, not a model token count). Read client constraints first, then signer, goals, risks, delivery ledger and current context. This command is the inspectable packet the session hook loads; never substitute a recursive read of `.fde/` or raw transcripts. If truncated or a decision needs evidence, run `fde recall <specific topic>`; narrow the query rather than loading the whole history. `--max-bytes 4096` reduces the allowance for smaller models. `--full` only when the complete log is explicitly needed.
 2. **NO ENGAGEMENT:** ask "What should we call this client?" then **you** init. Pasted notes → debrief after bind.
 3. Playback 2-3 lines. `hygiene:` → offer `fde doctor`; **never auto-rewrite**.
 4. Route. Read **one** `references/*.md`. Confirm, then write.
@@ -214,4 +220,4 @@ Ready to build with no `terrain.md` / plan: discover or plan first. Takeover wit
 
 ## Identifier masking
 
-Before reading engagement content in a session, run `fde privacy` to verify runtime support. If the command is unavailable, stop and update the CLI; a new skill alone does not upgrade an older executable. Use CLI context and previews for model input. They mask common email, phone, SSN-shaped, and credential patterns by default; aliases remain consistent within the local engagements root. Preserve complete alias tokens when drafting updates; the CLI resolves them locally. Never read the private `.privacy/` dictionary, sealed sidecars, raw sensitive notes, or local dashboard/vault files to recover an identity. Names, company names, addresses, and unrecognized formats are not automatically detected: keep sensitive prose in `<private>` blocks. Direct file tools, pasted chat, and upstream source MCPs bypass this boundary.
+Before reading engagement content in a session, run `fde privacy` to verify runtime support. If the command is unavailable, stop and update the CLI; a new skill alone does not upgrade an older executable. Use CLI context and previews for model input. They mask common email, phone, SSN-shaped, and credential patterns by default; aliases remain consistent within the local engagements root. Preserve complete alias tokens when drafting updates; the CLI resolves them locally. Never read the private `.privacy/` dictionary, sealed sidecars, raw sensitive notes, or local dashboard/vault files to recover an identity. Custom masking additionally hides the literal names or terms the user supplied locally, ignoring letter case and matching whole terms. It does not infer variants or discover names. Names, company names, addresses, and unrecognized formats are otherwise not automatically detected: keep sensitive prose in `<private>` blocks. Direct file tools, pasted chat, and upstream source MCPs bypass this boundary.