feat: npx fdeops demo - the whole loop on a fake client in one command

[devin-ai-integration]

Summary

Today the only way to see what fdeops does is to bind a real client and use it for a week. That is the wrong first ask for a tool whose pitch is "your client's memory lives on your disk". npx fdeops demo runs the entire loop on a fake engagement in under a second, then tells you how to delete it.

Ten steps, all real subprocess invocations of the same CLI (spawnSync(process.execPath, [__filename, ...argv])) — nothing in the transcript is canned, so the demo cannot drift from the product:

resume --init acme-payments   →  debrief --smart kickoff-notes.md  →  debrief --apply
log phase land                →  brief.md + success.md (what @fde drafts with you)
log contact … --signal amber  →  resume  (cold session)  →  prep  →  receipts  →  dashboard

The seeded notes deliberately contain a <private> block, so the demo is the privacy proof: the secret is sealed into context.md yet appears in no step's output and not in the rendered HTML.

Isolation, since a demo that touches real client memory would be indefensible:

FDEOPS_ENGAGEMENTS_ROOT = ~/fde-engagements/.demo   // own root ⇒ own .registry
FDEOPS_ENGAGEMENT = ''                              // ignore whatever the shell points at

The leading dot is load-bearing: status --all, dashboard --all, and resume's "existing:" line all skip dot-entries, so the fake client never shows up in your portfolio. demo wipes the sandbox before each run (idempotent), and demo --clean removes it.

Two honesty details worth knowing rather than discovering:

• brief.md / success.md have no CLI command by design (judgment, not appends), so the demo writes them and labels them as what the agent drafts with you rather than implying a command exists.
• They are committed via commitMemory(...); otherwise every later step correctly warns "memory has uncommitted manual edits" — right behaviour, wrong lesson for a first run.

Test asserts the value claims, the non-leak (with a non-vacuous check that the secret is sealed in context.md), portfolio isolation, no duplicate stacking on a second run, and that --clean leaves a real engagement intact. 79/79 tests + gates pass.

Link to Devin session: https://app.devin.ai/sessions/f135381c4682413bae73dff38eb6d1a3
Requested by: @suboss87

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Devin Review found 1 potential issue.

[devin-ai-integration]

🟡 Demo prints a truncated fieldbook file path when the user's home folder name contains a space

The final "Open the fieldbook" line is built by pulling the path out of the printed command output with a whitespace-sensitive pattern (dash.match(/\S+fieldbook[^\s]*\.html/) at bin/fde.js:2662), so any sandbox path containing a space yields a cut-off path.
Impact: Users whose home directory contains a space (common on Windows/macOS, e.g. "John Doe") are shown a broken path they cannot open.

Why the extraction fails for paths with spaces

cmdDashboard prints fieldbook → <outPath> (bin/fde.js:2530), and the demo re-parses that line instead of computing the path it already knows. The regex requires the whole path to be non-whitespace, so for /Users/John Doe/fde-engagements/.demo/fieldbook-current.html it matches only Doe/fde-engagements/.demo/fieldbook-current.html. The demo already knows the value deterministically: path.join(demoRoot(), 'fieldbook-current.html') (see bin/fde.js:2466 for how the default out path is derived), or the line could be split on the → separator.

Suggested change

	const dash = demoStep('10. The whole engagement on one page', ['dashboard'], workspace, env)
	const html = (dash.match(/\S+fieldbook[^\s]*\.html/) || [])[0]
	demoStep('10. The whole engagement on one page', ['dashboard'], workspace, env)
	const html = (dash => dash)(path.join(root, 'fieldbook-current.html'))

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Confirmed and fixed in 9f59a88 — real bug, not a nit: with FDEOPS_ENGAGEMENTS_ROOT=/tmp/x/John Doe/engagements the old parse printed Doe/engagements/.demo/fieldbook-current.html.

The demo now computes the path (path.join(root, 'fieldbook-current.html'), the same default cmdDashboard derives) instead of re-parsing stdout, and only prints the line when the file actually exists. Regression test asserts the printed path equals the expected one and that it opens (fs.existsSync), under a root containing a space.