phewsh 0.15.71 → 0.15.73

package/commands/ambient.js

@@ -31,6 +31,10 @@ const HOOK_END = { type: 'command', command: 'phewsh hook session-end' };
 // matcher scopes the hook to the tools the policy actually judges, so it never
 // fires on harmless reads.
 const HOOK_PRETOOL = { type: 'command', command: 'phewsh hook pre-tool' };
+// The receipt half of the lifecycle: after a write-ish tool runs, record a
+// redacted breadcrumb (tool + target, never args/content). Installed and
+// removed together with the pre-tool gate — one toggle, whole lifecycle.
+const HOOK_POSTTOOL = { type: 'command', command: 'phewsh hook post-tool' };
 const PRETOOL_MATCHER = 'Write|Edit|MultiEdit|NotebookEdit|Bash';
 
 // ANSI helpers (256-color per cli/lib/ui.js palette rules)
@@ -111,22 +115,31 @@ function preToolGateApplied() {
 function enablePreToolGate() {
   const settings = loadClaudeSettings() || {};
   settings.hooks = settings.hooks || {};
-  settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
-  if (hasHook(settings, 'PreToolUse', HOOK_PRETOOL.command)) return false;
-  settings.hooks.PreToolUse.push({ matcher: PRETOOL_MATCHER, hooks: [HOOK_PRETOOL] });
-  fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
-  return true;
+  let changed = false;
+  for (const [event, hook] of [['PreToolUse', HOOK_PRETOOL], ['PostToolUse', HOOK_POSTTOOL]]) {
+    settings.hooks[event] = settings.hooks[event] || [];
+    if (hasHook(settings, event, hook.command)) continue;
+    settings.hooks[event].push({ matcher: PRETOOL_MATCHER, hooks: [hook] });
+    changed = true;
+  }
+  if (changed) fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+  return changed;
 }
 
 function disablePreToolGate() {
   const settings = loadClaudeSettings();
-  if (!settings?.hooks?.PreToolUse) return false;
-  const before = settings.hooks.PreToolUse.length;
-  settings.hooks.PreToolUse = settings.hooks.PreToolUse
-    .map(e => ({ ...e, hooks: (e.hooks || []).filter(h => h.command !== HOOK_PRETOOL.command) }))
-    .filter(e => e.hooks.length > 0);
-  if ((settings.hooks.PreToolUse || []).length === 0) delete settings.hooks.PreToolUse;
-  const changed = before !== (settings.hooks.PreToolUse?.length ?? 0);
+  if (!settings?.hooks) return false;
+  let changed = false;
+  for (const [event, hook] of [['PreToolUse', HOOK_PRETOOL], ['PostToolUse', HOOK_POSTTOOL]]) {
+    const entries = settings.hooks[event];
+    if (!entries) continue;
+    const before = entries.length;
+    settings.hooks[event] = entries
+      .map(e => ({ ...e, hooks: (e.hooks || []).filter(h => h.command !== hook.command) }))
+      .filter(e => e.hooks.length > 0);
+    if ((settings.hooks[event] || []).length === 0) delete settings.hooks[event];
+    if (before !== (settings.hooks[event]?.length ?? 0)) changed = true;
+  }
   if (changed) fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
   return changed;
 }
@@ -249,6 +262,10 @@ async function turnOn(skipConfirm) {
 
 function turnOff() {
   const removed = removeClaudeHooks();
+  // Full reversibility: ambient off takes the lifecycle hooks with it too.
+  let gateRemoved = false;
+  try { gateRemoved = disablePreToolGate(); } catch { /* best-effort */ }
+  if (gateRemoved) removed.push('lifecycle hooks (PreToolUse gate + PostToolUse receipt)');
   const { removed: removedGlobal } = selfheal.removeGlobalBaseFiles();
   const { removed: removedProject } = selfheal.removeProjectContextFiles();
   const { removed: removedSlash } = slash.removeSlashCommands();
@@ -256,6 +273,7 @@ function turnOff() {
   delete ledger.applied['claude-code'];
   delete ledger.applied.globalBase;
   delete ledger.applied.slashCommands;
+  delete ledger.applied.lifecycle;
   delete ledger.autoEnabledAt;
   ledger.disabled = true; // sticky opt-out — first-run auto-enable must respect this
   saveLedger(ledger);
@@ -352,6 +370,11 @@ async function ensureAuto() {
 
   const hasClaude = installed.some(h => h.id === 'claude-code');
   const changes = hasClaude ? applyClaudeHooks() : [];
+  // Neal's ruling (Jul 5): the lifecycle hooks (PreToolUse gate + PostToolUse
+  // receipt) install with first-run auto-enable too — they're fail-open,
+  // redacted, and removed by the same `phewsh ambient off` / `gate enforce off`.
+  let gateApplied = false;
+  if (hasClaude) { try { gateApplied = enablePreToolGate(); } catch { /* best-effort */ } }
   const { written } = selfheal.syncGlobalBaseFiles();
   const slashWritten = slash.installSlashCommands().written;
   // Refresh existing project files only — first-run auto-enable must not dump
@@ -365,6 +388,13 @@ async function ensureAuto() {
       captures: '~/.phewsh/ambient-sessions.jsonl — timestamp, project, cwd only',
       undo: 'phewsh ambient off',
     };
+    if (gateApplied) {
+      ledger.applied.lifecycle = {
+        at: now, file: CLAUDE_SETTINGS,
+        what: 'PreToolUse gate (deny protected paths, ask on high blast radius) + PostToolUse redacted receipt',
+        undo: 'phewsh gate enforce off (or phewsh ambient off)',
+      };
+    }
   }
   if (written.length > 0) {
     ledger.applied.globalBase = { at: now, files: written, undo: 'phewsh ambient off' };
@@ -381,6 +411,7 @@ async function ensureAuto() {
     console.log('');
     console.log(`  ${b(cream('phewsh set itself up across your AI tools'))} ${sage('— so they stay in sync with your project intent.')}`);
     if (hasClaude) console.log(`    ${teal('+')} ${slate('Claude Code gets a brief from a project\'s .intent/ at session start')}`);
+    if (gateApplied) console.log(`    ${teal('+')} ${slate('guardrails: protected-path writes gated + a redacted receipt of what ran')}`);
     written.forEach(f => console.log(`    ${teal('+')} ${slate('environment note added to ' + f)}`));
     if (slashWritten.length) console.log(`    ${teal('+')} ${cream('/intent')} ${slate('command added to ' + slashWritten.join(', '))}`);
     console.log(`    ${sage('In any project with')} ${cream('.intent/')}${sage(', your tools now read its real intent. Reversible:')} ${cream('phewsh ambient off')}`);

package/commands/clarify.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');
-const { readPPS, writePPS, createPPS, generateViews } = require('../lib/pps');
+const { readPPS, createPPS, writeGuardedViews } = require('../lib/pps');
 const configFile = require('../lib/config-file');
 
 const CONFIG_PATH = path.join(os.homedir(), '.phewsh', 'config.json');
@@ -45,35 +45,28 @@ async function askForInput() {
   });
 }
 
-// The guided walk — the five strongest nodes of the web's 12-node Intent
-// Compass, asked one at a time. The web compass helps the user *see* what
-// they're building; this brings that to the terminal. Not a form: every
-// question is skippable, and the point is to help you think, not interrogate.
-const GUIDE_NODES = [
-  { id: 'purpose', title: 'Purpose', directive: 'the core reason this exists',
-    q: 'What outcome are you really after — and why does this need to exist?' },
-  { id: 'audience', title: 'Audience', directive: 'the people this serves',
-    q: 'Who is this for? Who feels it most when it works?' },
-  { id: 'method', title: 'Method', directive: 'the mechanism and approach',
-    q: 'How does it actually work — the core mechanism or approach?' },
-  { id: 'scope', title: 'Scope', directive: 'boundaries, in and out',
-    q: "What's in — and just as important, what's deliberately out, for now?" },
-  { id: 'differentiation', title: 'Edge', directive: 'what makes this yours',
-    q: 'What would be lost if someone else built this instead of you?' },
-];
+// The guided walk — nodes of the 12-node Intent Compass, asked one at a
+// time. Default: the five strongest (CORE_NODES). --deep: all twelve. The
+// web compass helps the user *see* what they're building; this brings that
+// to the terminal. Not a form: every question is skippable, and the point
+// is to help you think, not interrogate.
+const { INTENT_NODES, CORE_NODES } = require('../lib/intent-nodes');
+const GUIDE_NODES = CORE_NODES;
 
 function ask(rl, question) {
   return new Promise((resolve) => rl.question(question, (a) => resolve((a || '').trim())));
 }
 
 // rl is injectable so the walk can be driven deterministically in tests.
-async function askGuided(rl = readline.createInterface({ input: process.stdin, output: process.stdout })) {
-  console.log('\n  Five quick questions to align your own thinking first —');
+// nodes defaults to the five-node core walk; --deep passes all twelve.
+async function askGuided(rl = readline.createInterface({ input: process.stdin, output: process.stdout }), nodes = GUIDE_NODES) {
+  const count = nodes.length === 5 ? 'Five quick questions' : `${nodes.length} questions — the full compass`;
+  console.log(`\n  ${count} to align your own thinking first —`);
   console.log('  a sentence or two each. Blank skips. (esc stops, nothing saved.)\n');
   const answers = [];
-  for (let i = 0; i < GUIDE_NODES.length; i++) {
-    const n = GUIDE_NODES[i];
-    console.log(`  ${i + 1}/${GUIDE_NODES.length}  ${n.title} — ${n.directive}`);
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    console.log(`  ${i + 1}/${nodes.length}  ${n.title} — ${n.directive}`);
     const a = await ask(rl, `  ${n.q}\n  > `);
     if (a) answers.push({ ...n, answer: a });
     console.log('');
@@ -169,13 +162,6 @@ async function callClarifyViaHarness(harnessId, raw, existing) {
   return extractJson(out || '');
 }
 
-function writeViews(intentDir, pps) {
-  const { vision, plan, next } = generateViews(pps);
-  fs.writeFileSync(path.join(intentDir, 'vision.md'), vision);
-  fs.writeFileSync(path.join(intentDir, 'plan.md'), plan);
-  fs.writeFileSync(path.join(intentDir, 'next.md'), next);
-}
-
 async function main() {
   // ESC backs out cleanly at any point — nothing half-written, no error.
   if (process.stdin.isTTY) {
@@ -194,17 +180,19 @@ async function main() {
 
   Usage:
     phewsh clarify                    Guided: a 5-question walk that aligns your thinking, then compiles
+    phewsh clarify --deep             The full 12-node compass, one question at a time
     phewsh clarify --freeform         Free-form: describe it all in one messy blob
     phewsh clarify --text "..."       Inline: pass raw text directly
-    phewsh clarify --update           Refine existing PPS with new input
+    phewsh clarify --update           Refine existing intent with new input
 
   What it does:
-    Walks you through the five strongest nodes of the Intent Compass —
-    Purpose, Audience, Method, Scope, Edge — one question at a time, so the
-    terminal helps you *think*, not just compile. Then turns your answers
-    into a structured project spec (PPS):
-    Writes .intent/pps.json as the source of truth.
-    Generates vision.md, plan.md, next.md as human-readable views.
+    Walks you through the strongest nodes of the 12-node Intent Compass —
+    Purpose, Audience, Method, Scope, Edge (--deep adds Context, Resources,
+    Strategy, Signals, Risks, Values, Impact) — one question at a time, so
+    the terminal helps you *think*, not just compile. Then it writes
+    vision.md, plan.md, next.md — YOUR files, the project truth every AI
+    tool reads. Files you've edited by hand are never overwritten.
+    (.intent/pps.json holds the compiled spec + generation receipts.)
 
   Requires:
     An installed agent CLI (Claude Code, Codex, Gemini…) — phewsh uses its
@@ -249,7 +237,9 @@ async function main() {
       raw = await askForInput();
     } else {
       // Guided is the default interactive path: help the user think first.
-      const answers = await askGuided();
+      // --deep walks the full 12-node compass instead of the strongest five.
+      const deep = args.includes('--deep') || args.includes('-d');
+      const answers = await askGuided(undefined, deep ? INTENT_NODES : GUIDE_NODES);
       raw = assembleRaw(answers);
       if (!raw) {
         // Skipped every question — fall back to a single free-form description.
@@ -310,14 +300,19 @@ async function main() {
     pps.state.phase = 'plan';
   }
 
-  fs.mkdirSync(INTENT_DIR, { recursive: true });
-  writePPS(INTENT_DIR, pps);
-  writeViews(INTENT_DIR, pps);
-
-  console.log(`  ✓ .intent/pps.json       — structured project spec`);
-  console.log(`  ✓ .intent/vision.md      — ${pps.intent.goal}`);
-  console.log(`  ✓ .intent/plan.md        — ${pps.intent.success_criteria.length} outcomes, ${pps.intent.constraints.length} constraints`);
-  console.log(`  ✓ .intent/next.md        — ${pps.tasks.length} actions\n`);
+  // The truth guard: the .md files are user-owned truth. Hand-edited (or
+  // pre-existing hand-authored) files are preserved, never regenerated.
+  const { written, preserved } = writeGuardedViews(INTENT_DIR, pps);
+
+  console.log(`  ✓ .intent/pps.json       — compiled spec (the .md files are the truth)`);
+  const detail = {
+    'vision.md': pps.intent.goal,
+    'plan.md': `${pps.intent.success_criteria.length} outcomes, ${pps.intent.constraints.length} constraints`,
+    'next.md': `${pps.tasks.length} actions`,
+  };
+  for (const f of written) console.log(`  ✓ .intent/${f.padEnd(14)} — ${detail[f]}`);
+  for (const f of preserved) console.log(`  ● .intent/${f.padEnd(14)} — kept as-is (yours — edited by hand, phewsh won't overwrite it)`);
+  console.log('');
   console.log(`  Goal: ${pps.intent.goal}\n`);
   if (pps.tasks.length > 0) {
     console.log('  First actions:');
@@ -338,4 +333,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { run: main, GUIDE_NODES, assembleRaw, askGuided, extractJson };
+module.exports = { run: main, GUIDE_NODES, INTENT_NODES, assembleRaw, askGuided, extractJson };

package/commands/gate.js

@@ -402,21 +402,22 @@ function enforce(action) {
   if (on === 'on' || on === 'enable') {
     const changed = amb.enablePreToolGate();
     console.log(changed
-      ? `\n  ${green('●')} Gate enforcement ${green('ON')} — Claude Code asks/denies on protected-path writes and high-blast-radius commands before they run.\n  ${g('Reversible:')} phewsh gate enforce off\n`
+      ? `\n  ${green('●')} Gate enforcement ${green('ON')} — before a tool runs, Claude Code asks/denies on protected-path writes and high-blast-radius commands; after, a redacted receipt records what ran (tool + target, never content).\n  ${g('Reversible:')} phewsh gate enforce off\n`
       : `\n  Gate enforcement already on.\n`);
     return;
   }
   if (on === 'off' || on === 'disable') {
     const changed = amb.disablePreToolGate();
-    console.log(changed ? `\n  Gate enforcement ${yellow('OFF')} — PreToolUse hook removed.\n` : `\n  Gate enforcement was not on.\n`);
+    console.log(changed ? `\n  Gate enforcement ${yellow('OFF')} — PreToolUse + PostToolUse hooks removed.\n` : `\n  Gate enforcement was not on.\n`);
     return;
   }
   // status
   const applied = amb.preToolGateApplied();
-  console.log(`\n  Gate enforcement: ${applied ? green('ON') : g('off')} ${g('(Claude Code PreToolUse)')}`);
+  console.log(`\n  Gate enforcement: ${applied ? green('ON') : g('off')} ${g('(Claude Code PreToolUse + PostToolUse)')}`);
   console.log(`  ${g('Turn on:')} phewsh gate enforce on   ${g('· off:')} phewsh gate enforce off`);
-  console.log(`  ${g('What it does: deny writes to protected paths (.env, keys, .git/…),')}`);
+  console.log(`  ${g('Before: deny writes to protected paths (.env, keys, .git/…),')}`);
   console.log(`  ${g('ask before high-blast-radius shell (rm -rf, force-push, sudo…).')}`);
+  console.log(`  ${g('After: redacted receipt of what ran — tool + target, never args or content.')}`);
   console.log(`  ${g('Opt-in, local-only, fail-open. Other tools: advisory only for now.')}\n`);
 }
 

package/commands/hook.js

@@ -74,10 +74,39 @@ function firstLines(text, n) {
     .join('\n');
 }
 
+// The accountability invitation. A real project (it has .git) with no
+// .intent/ gets ONE gentle note injected — telling the agent to offer
+// grounding once, and to drop it if declined. Once per project, ever
+// (tracked in ~/.phewsh/intent-nudges.json); every later session is
+// silent again. Invite, never nag — the recorded stance (decisions.md).
+function maybeIntentInvitation() {
+  try {
+    if (!fs.existsSync(path.join(process.cwd(), '.git'))) return; // not a real project — cost nothing
+    const nudgeFile = path.join(PHEWSH_DIR, 'intent-nudges.json');
+    let seen = {};
+    try { seen = JSON.parse(fs.readFileSync(nudgeFile, 'utf-8')); } catch { /* first nudge ever */ }
+    if (seen && seen[process.cwd()]) return; // already invited here — never again
+    seen = (seen && typeof seen === 'object') ? seen : {};
+    seen[process.cwd()] = new Date().toISOString();
+    fs.mkdirSync(PHEWSH_DIR, { recursive: true });
+    fs.writeFileSync(nudgeFile, JSON.stringify(seen, null, 2));
+    process.stdout.write([
+      '# phewsh — one-time note for this project',
+      'This repo has no `.intent/` yet — no durable project truth that travels between AI tools.',
+      'If the user starts substantial (non-trivial) work here, offer ONCE, in plain language, to ground the project:',
+      '`phewsh clarify` (guided walk) or `phewsh init` (two questions) creates `.intent/` — vision, plan, and next steps that every AI tool reads, so the next session picks up where this one left off.',
+      'If they decline, or the work is trivial/exploratory, drop it and never raise it again. Do not create `.intent/` yourself uninvited.',
+    ].join('\n') + '\n');
+    appendBreadcrumb('intent-invite');
+  } catch { /* the invitation is a nicety — never break the host */ }
+}
+
 function sessionStart() {
   if (!fs.existsSync(path.join(INTENT_DIR, 'vision.md')) &&
       !fs.existsSync(path.join(INTENT_DIR, 'plan.md'))) {
-    // No .intent/ here — stay silent, cost the host nothing.
+    // No .intent/ here — one gentle invitation if this is a real project,
+    // then silence forever.
+    maybeIntentInvitation();
     process.exit(0);
   }
 
@@ -215,11 +244,41 @@ function preTool() {
   }
 }
 
+// PostToolUse adapter — the other half of the lifecycle. After a write-ish
+// tool runs, leave a redacted receipt (tool name + relative target, or just
+// the binary name for shell — NEVER args, content, or output) so `phewsh`
+// can show what agents actually did here. Always silent to the host, always
+// fail-open: a broken receipt must never slow or break the tool that ran.
+function postTool() {
+  try {
+    if (process.stdin.isTTY) process.exit(0); // not a real hook invocation
+    let raw = '';
+    try { raw = fs.readFileSync(0, 'utf-8'); } catch { process.exit(0); }
+    let payload = {};
+    try { payload = JSON.parse(raw || '{}'); } catch { process.exit(0); }
+    const tool = payload.tool_name || payload.toolName;
+    if (!tool) process.exit(0);
+    const input = payload.tool_input || payload.toolInput || {};
+    const cwd = payload.cwd || process.cwd();
+    let target = null;
+    if (typeof input.file_path === 'string') {
+      target = path.relative(cwd, input.file_path) || input.file_path;
+    } else if (typeof input.command === 'string') {
+      target = String(input.command).trim().split(/\s+/)[0] || null; // binary only, never args
+    }
+    appendBreadcrumb('post-tool', { tool, ...(target ? { target } : {}) });
+    process.exit(0);
+  } catch {
+    process.exit(0); // fail open, always
+  }
+}
+
 function main() {
   const event = process.argv[3];
   if (event === 'session-start') return sessionStart();
   if (event === 'session-end') return sessionEnd();
   if (event === 'pre-tool') return preTool();
+  if (event === 'post-tool') return postTool();
   // Unknown event: exit silently — hooks must never error the host tool.
   process.exit(0);
 }

package/commands/intent.js

@@ -2,7 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
-const { createPPS, writePPS, generateViews } = require('../lib/pps');
+const { createPPS, writeGuardedViews } = require('../lib/pps');
 
 const os = require('os');
 const configFile = require('../lib/config-file');
@@ -136,16 +136,14 @@ async function initIntent() {
     },
   });
 
-  writePPS(INTENT_DIR, pps);
-  const { vision, plan, next } = generateViews(pps);
-  fs.writeFileSync(path.join(INTENT_DIR, 'vision.md'), vision);
-  fs.writeFileSync(path.join(INTENT_DIR, 'plan.md'), plan);
-  fs.writeFileSync(path.join(INTENT_DIR, 'next.md'), next);
+  // Truth guard: never overwrite a hand-authored file (a partial .intent/
+  // slips past hasExistingArtifacts — e.g. vision.md alone).
+  const { written, preserved } = writeGuardedViews(INTENT_DIR, pps);
 
-  console.log(`  ✓ .intent/pps.json     — Structured project spec (source of truth)`);
-  console.log(`  ✓ .intent/vision.md    — The north star`);
-  console.log(`  ✓ .intent/plan.md      — The strategy`);
-  console.log(`  ✓ .intent/next.md      — What to do right now`);
+  console.log(`  ✓ .intent/pps.json     — Compiled spec (the .md files are the truth)`);
+  const label = { 'vision.md': 'The north star', 'plan.md': 'The strategy', 'next.md': 'What to do right now' };
+  for (const f of written) console.log(`  ✓ .intent/${f.padEnd(12)} — ${label[f]}`);
+  for (const f of preserved) console.log(`  ● .intent/${f.padEnd(12)} — kept as-is (yours, hand-authored)`);
   console.log(`
   Tip: Run \`phewsh clarify\` to have AI compile your messy intent into a precise spec.
 

package/commands/pack.js

@@ -36,7 +36,39 @@ function list() {
     console.log(`    ${slate('source: ' + p.source)}`);
   }
   console.log('');
-  console.log(`  ${sage('Install:')} ${cream('phewsh pack install <name>')}   ${sage('Remove:')} ${cream('phewsh pack remove <name>')}`);
+  console.log(`  ${sage('Install:')} ${cream('phewsh pack install <name>')}   ${sage('All official packs at once:')} ${cream('phewsh pack install all')}`);
+  console.log(`  ${sage('Remove:')}  ${cream('phewsh pack remove <name>')}    ${sage('Read about every pack:')} ${cream('phewsh.com/cli#packs')}`);
+  console.log('');
+}
+
+// `phewsh pack install all` — every official (vendored) pack in one confirmed
+// pass. Linked packs stay pointers to their upstream source; we list them so
+// nothing external ever installs silently.
+async function installAll() {
+  const vendored = Object.entries(packs.PACKS).filter(([, p]) => p.kind !== 'linked');
+  const linked = Object.entries(packs.PACKS).filter(([, p]) => p.kind === 'linked');
+  const pending = vendored.filter(([name]) => !packs.isInstalled(name));
+
+  console.log('');
+  if (pending.length === 0) {
+    console.log(`  ${sage('All official packs are already installed here.')}`);
+  } else {
+    console.log(`  ${b(cream('Official phewsh packs'))} ${sage('— ' + pending.length + ' to install:')}`);
+    pending.forEach(([name, p]) => console.log(`    ${cream(name.padEnd(16))} ${slate(p.desc)}`));
+    console.log('');
+    const ok = await confirm(`  ${b('Install ' + (pending.length === 1 ? 'it' : 'all ' + pending.length) + ' here?')} ${slate('[y/N] ')}`);
+    if (!ok) { console.log(`  ${sage('Nothing changed.')}\n`); return; }
+    for (const [name] of pending) {
+      const { written } = packs.install(name);
+      console.log(`  ${green('●')} ${cream(name)} ${slate('→ ' + written.join(', '))}`);
+    }
+    console.log(`  ${sage('Remove any:')} ${cream('phewsh pack remove <name>')}`);
+  }
+  if (linked.length > 0) {
+    console.log('');
+    console.log(`  ${sage(linked.length + ' more are linked packs — separate tools phewsh points at but never auto-installs:')}`);
+    console.log(`    ${cream('phewsh pack')} ${sage('lists them ·')} ${cream('phewsh.com/cli#packs')} ${sage('tells their stories')}`);
+  }
   console.log('');
 }
 
@@ -89,6 +121,7 @@ function remove(name) {
 async function main() {
   const sub = process.argv[3];
   const name = process.argv[4];
+  if (sub === 'install' && name === 'all') return installAll();
   if (sub === 'install' && name) return install(name);
   if (sub === 'remove' && name) return remove(name);
   return list();

package/commands/session.js

@@ -50,7 +50,7 @@ const {
   relativeFolder,
   shouldCollapsePaste,
 } = require('../lib/session-display');
-const { recordProject, listProjects, scanForProjects, fmtAgo } = require('../lib/projects-index');
+const { recordProject, listProjects, scanForProjects, scanForCandidates, fmtAgo } = require('../lib/projects-index');
 
 // Brand palette shortcuts
 const { b, d, w, g, green, cyan, yellow,
@@ -500,7 +500,7 @@ async function main() {
   } else if (atHome || recents.length > 0) {
     row('PROJECT', slate('none here — your projects are listed below'));
   } else {
-    row('PROJECT', cream(projectName) + slate(' · no memory yet — ') + sage('/init'));
+    row('PROJECT', cream(projectName) + slate(' · no memory yet — ') + sage('/init') + slate(' fast · ') + sage('/clarify') + slate(' guided'));
   }
 
   row('ROUTE', route
@@ -718,7 +718,13 @@ async function main() {
     try { recordProject(dir); } catch { /* best-effort */ }
     bootstrapChoices = null;
     console.log('');
-    console.log(`  ${teal('●')} ${cream(projectName)} ${slate('·')} ${sage(`.intent/ ${intentFiles.length} file${intentFiles.length !== 1 ? 's' : ''} loaded`)} ${slate('· via ' + routeLabel(route, config))}`);
+    if (intentFiles.length === 0) {
+      // A candidate, not yet a project — invite intent, don't fake context.
+      console.log(`  ${teal('●')} ${cream(projectName)} ${slate('·')} ${sage('no .intent/ yet')} ${slate('· via ' + routeLabel(route, config))}`);
+      console.log(`  ${sage('Ground it:')} ${cream('/init')} ${sage('two questions, instant artifacts')} ${slate('·')} ${cream('/clarify')} ${sage('guided — compiles your messy idea into a spec')}`);
+    } else {
+      console.log(`  ${teal('●')} ${cream(projectName)} ${slate('·')} ${sage(`.intent/ ${intentFiles.length} file${intentFiles.length !== 1 ? 's' : ''} loaded`)} ${slate('· via ' + routeLabel(route, config))}`);
+    }
     console.log('');
     maybeHealOnEntry();
     showContinuity();
@@ -727,6 +733,39 @@ async function main() {
     console.log('');
   }
 
+  // The project scanner — bootstrap option AND /scan slash command. Lists
+  // .intent/ projects plus likely candidates (git, no .intent yet, reason
+  // shown) from the usual folders, numbered so a bare digit opens one.
+  function runScanMenu() {
+    const spin = ui.spinner('scanning your usual folders');
+    const found = scanForProjects();
+    let candidates = [];
+    try { candidates = scanForCandidates(); } catch { /* advisory — scan still useful without it */ }
+    spin.stop();
+    if (found.length === 0 && candidates.length === 0) {
+      bootstrapChoices = null;
+      console.log(`  ${sage('No .intent/ projects found in the usual folders.')}`);
+      console.log(`  ${slate('cd into a project and run phewsh, or /init to start one here.')}`);
+      return;
+    }
+    bootstrapChoices = [];
+    if (found.length > 0) {
+      console.log(`  ${teal('●')} ${sage(`Found ${found.length} project${found.length !== 1 ? 's' : ''} with .intent/:`)}`);
+      for (const p of found) {
+        bootstrapChoices.push({ kind: 'open', path: p.path });
+        console.log(`  ${teal(String(bootstrapChoices.length))} ${cream(p.name)} ${slate('· ' + tildify(p.path))}`);
+      }
+    }
+    if (candidates.length > 0) {
+      console.log(`  ${teal('●')} ${sage(`${candidates.length} likely candidate${candidates.length !== 1 ? 's' : ''} — no shared memory yet:`)}`);
+      for (const p of candidates) {
+        bootstrapChoices.push({ kind: 'open', path: p.path });
+        console.log(`  ${teal(String(bootstrapChoices.length))} ${cream(p.name)} ${slate('· ' + tildify(p.path) + ' · ' + p.reason)}`);
+      }
+    }
+    console.log(`  ${slate('pick a number to open it')}`);
+  }
+
   function showBootstrapMenu(projects) {
     console.log(`  ${b(cream('Where do you want to work?'))}`);
     bootstrapChoices = [];
@@ -970,7 +1009,7 @@ async function main() {
   // RECOGNIZED leading /command (or @harness) token turns teal (peach for @)
   // so you know it registered. Arguments stay plain. TTY-only, fail-soft.
   const KNOWN_COMMANDS = new Set([
-    'quit', 'exit', 'q', 'help', 'h', 'init', 'intent', 'clarify', 'model',
+    'quit', 'exit', 'q', 'help', 'h', 'init', 'intent', 'clarify', 'scan', 'model',
     'models', 'council', 'all', 'provider', 'route', 'use', 'work', 'switch', 'run',
     'clear', 'status', 'key', 'login', 'export', 'push', 'pull', 'serve',
     'sync', 'harnesses', 'fallback', 'outcomes', 'tour', 'update', 'upgrade',
@@ -1271,8 +1310,11 @@ async function main() {
       return;
     }
 
-    // Root bootstrap: a bare number opens a project, inits, or scans
-    if (bootstrapChoices && messages.length === 0 && /^[0-9]{1,2}$/.test(input)) {
+    // Scan/bootstrap menu: a bare number opens a project, inits, or scans.
+    // Any other input means the user moved on — drop the menu so it never
+    // shadows a later digit (mirrors the nextChoices rule above).
+    if (bootstrapChoices && !/^[0-9]{1,2}$/.test(input)) bootstrapChoices = null;
+    if (bootstrapChoices && /^[0-9]{1,2}$/.test(input)) {
       const choice = bootstrapChoices[parseInt(input, 10) - 1];
       if (!choice) {
         console.log(`  ${sage('Pick 1-' + bootstrapChoices.length)}`);
@@ -1303,21 +1345,7 @@ async function main() {
         return;
       }
       if (choice.kind === 'scan') {
-        const spin = ui.spinner('scanning your usual folders');
-        const found = scanForProjects();
-        spin.stop();
-        if (found.length === 0) {
-          bootstrapChoices = null;
-          console.log(`  ${sage('No .intent/ projects found in the usual folders.')}`);
-          console.log(`  ${slate('cd into a project and run phewsh, or /init to start one here.')}`);
-        } else {
-          console.log(`  ${teal('●')} ${sage(`Found ${found.length} project${found.length !== 1 ? 's' : ''}:`)}`);
-          bootstrapChoices = found.map(p => ({ kind: 'open', path: p.path }));
-          found.forEach((p, i) => {
-            console.log(`  ${teal(String(i + 1))} ${cream(p.name)} ${slate('· ' + tildify(p.path))}`);
-          });
-          console.log(`  ${slate('pick a number to open it')}`);
-        }
+        runScanMenu();
         console.log('');
         rl.prompt();
         return;
@@ -1651,6 +1679,7 @@ async function main() {
           console.log(`    ${teal('@name')} ${slate('<msg>')}   ${sage('one message to one tool — @codex review this')}`);
           console.log(`    ${teal('/work')} ${slate('[tool]')}  ${sage('hand off to the full interactive tool, outcome on return')}`);
           console.log(`    ${teal('/clarify')}       ${sage('turn messy thoughts into .intent/ artifacts')}`);
+          console.log(`    ${teal('/scan')}          ${sage('find your projects — and repos that need shared memory')}`);
           console.log(`    ${teal('/outcomes')}      ${sage('label what you kept — the record that gets smarter')}`);
           console.log('');
           console.log(`  ${slate('/help all')} ${sage('everything')}  ${slate('·')}  ${slate('/tour')} ${sage('walkthrough')}  ${slate('·')}  ${slate('/quit')} ${sage('exit')}`);
@@ -1668,6 +1697,7 @@ async function main() {
         console.log(`    ${teal('/learn')}       ${sage('what your record taught — which tool keeps best, by kind of work')}`);
         console.log('');
         console.log(`  ${cream('author .intent/')}`);
+        console.log(`    ${teal('/scan')}        ${sage('Find your projects — and likely candidates with no .intent/ yet')}`);
         console.log(`    ${teal('/init')}        ${sage('Create .intent/ for this project')}`);
         console.log(`    ${teal('/intent')}      ${sage('Pause and reflect — view or update .intent/ before moving on')}`);
         console.log(`    ${teal('/remember')}    ${sage('Jot a decision to .intent/decisions.md — every tool inherits it')}`);
@@ -1902,6 +1932,13 @@ async function main() {
         return;
       }
 
+      if (cmd === 'scan') {
+        runScanMenu();
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'clarify') {
         try {
           const { spawnSync } = require('child_process');

package/lib/cors.js

@@ -37,6 +37,12 @@ function corsHeaders(req) {
     'Access-Control-Allow-Origin': origin,
     'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
     'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Phewsh-Runtime',
+    // Chrome Local/Private Network Access: an HTTPS page (phewsh.com) fetching
+    // plain-http loopback gets a preflight carrying Access-Control-Request-
+    // Private-Network; without this answer Chrome kills the request before it
+    // is ever sent — the cockpit shows "bridge offline" while serve is
+    // demonstrably up. Loopback-only server, allowlisted origins only.
+    'Access-Control-Allow-Private-Network': 'true',
     'Access-Control-Max-Age': '600',
     Vary: 'Origin',
   };

package/lib/intent-nodes.js

@@ -0,0 +1,38 @@
+// The 12-node Intent Compass — the CLI's canonical copy of the model the web
+// compass renders (intent/app/src/lib/intent-analysis.ts). One definition,
+// two surfaces: the web helps you SEE your intent; the terminal helps you
+// SAY it. Ordered as a ladder — the first five are the strongest nodes and
+// form the default clarify walk; --deep continues through all twelve.
+
+const INTENT_NODES = [
+  { id: 'purpose', title: 'Purpose', directive: 'the core reason this exists',
+    q: 'What outcome are you really after — and why does this need to exist?' },
+  { id: 'audience', title: 'Audience', directive: 'the people this serves',
+    q: 'Who is this for? Who feels it most when it works?' },
+  { id: 'method', title: 'Method', directive: 'the mechanism and approach',
+    q: 'How does it actually work — the core mechanism or approach?' },
+  { id: 'scope', title: 'Scope', directive: 'boundaries, in and out',
+    q: "What's in — and just as important, what's deliberately out, for now?" },
+  { id: 'differentiation', title: 'Edge', directive: 'what makes this yours',
+    q: 'What would be lost if someone else built this instead of you?' },
+  // ── the deep walk continues here (--deep) ──
+  { id: 'context', title: 'Context', directive: 'the situation that led here',
+    q: "What's happening right now that makes this relevant — what led to it?" },
+  { id: 'resources', title: 'Resources', directive: 'time, money, energy, tools',
+    q: 'What does this require — time, money, energy, tools you already have?' },
+  { id: 'strategy', title: 'Strategy', directive: 'the roadmap and sequence',
+    q: 'How do you get from here to success — what happens first, second, third?' },
+  { id: 'signals', title: 'Signals', directive: 'metrics, validation, feedback',
+    q: 'How will you know this is working — what would you actually measure?' },
+  { id: 'risks', title: 'Risks', directive: 'threats, unknowns, failure modes',
+    q: "What could go wrong — what's the biggest unknown or exposure?" },
+  { id: 'values', title: 'Values', directive: 'ethics, trust, non-negotiables',
+    q: 'What do you refuse to compromise on, even under pressure?' },
+  { id: 'impact', title: 'Impact', directive: 'long-term effects and sustainability',
+    q: 'If this fully succeeds, what changes — and how does it sustain itself?' },
+];
+
+// The five strongest nodes — the default clarify walk.
+const CORE_NODES = INTENT_NODES.slice(0, 5);
+
+module.exports = { INTENT_NODES, CORE_NODES };

package/lib/intro.js

@@ -57,6 +57,8 @@ async function playIntro(opts = {}) {
     delay = sleep,
     out = console.log,
     listHarnesses = require('./harnesses').listHarnesses,
+    scanProjects = require('./projects-index').scanForProjects,
+    scanCandidates = require('./projects-index').scanForCandidates,
   } = opts;
 
   const { b, cream, sage, slate, teal, green } = ui;
@@ -93,6 +95,24 @@ async function playIntro(opts = {}) {
   }
   out('');
   await pause(160);
+
+  // Second beat: the tools share memory *per project* — so show the projects.
+  // Shallow scan of the usual folders only (same rules as /scan): existing
+  // .intent/ projects, plus likely candidates (git repos with no .intent yet).
+  let projects = [];
+  let candidates = [];
+  try { projects = scanProjects(); } catch { /* none */ }
+  try { candidates = scanCandidates(); } catch { /* none */ }
+  if (projects.length > 0 || candidates.length > 0) {
+    const bits = [];
+    if (projects.length > 0) bits.push(`${projects.length} project${projects.length !== 1 ? 's' : ''} already share memory (.intent/)`);
+    if (candidates.length > 0) bits.push(`${candidates.length} likely candidate${candidates.length !== 1 ? 's' : ''} (git, no .intent yet)`);
+    out(`  ${teal('●')} ${sage(bits.join(' · '))}`);
+    out(`  ${slate('run phewsh inside one — or pick from the list when the session opens.')}`);
+    out('');
+    await pause(160);
+  }
+
   if (harnesses.length > 0) {
     out(`  ${sage('Next:')} ${cream('just type to start')} ${slate('·')} ${cream('phewsh setup')} ${slate('to pick a default route')}`);
   } else {
@@ -100,7 +120,7 @@ async function playIntro(opts = {}) {
   }
   out('');
 
-  return { toolsFound: harnesses.length };
+  return { toolsFound: harnesses.length, projectsFound: projects.length, candidatesFound: candidates.length };
 }
 
 // Quiet sign-off — the shush mark, printed static (no animation; exit is instant).

package/lib/pps.js

@@ -1,5 +1,10 @@
-// PPS — Portable Project Spec
-// pps.json is the source of truth. .md files are generated views.
+// PPS — Portable Project Spec compiler.
+//
+// TRUTH RULING (decisions.md, Jul 5 2026): the .md files ARE the project
+// truth — user-owned, hand-editable, what every tool reads. pps.json is the
+// compiler's receipt: structured output from clarify/init plus the hashes of
+// what it generated, so regeneration can tell machine-owned files from
+// hand-authored ones. phewsh never overwrites a file the human has edited.
 
 const fs = require('fs');
 const path = require('path');
@@ -63,6 +68,10 @@ function createPPS({ entity, archetype = 'product', raw = '', intent = {} }) {
   };
 }
 
+// One line of provenance in every generated file — the user must never
+// mistake compiled output for something they wrote (or vice versa).
+const PROVENANCE = 'provenance: compiled by phewsh clarify — yours to edit; phewsh never regenerates a file you have edited';
+
 function generateViews(pps) {
   const { entity, intent, tasks, created, updated, archetype } = pps;
 
@@ -71,6 +80,7 @@ entity: ${entity}
 archetype: ${archetype}
 created: ${created}
 updated: ${updated}
+${PROVENANCE}
 ---
 
 # Vision
@@ -97,6 +107,7 @@ entity: ${entity}
 archetype: ${archetype}
 created: ${created}
 updated: ${updated}
+${PROVENANCE}
 ---
 
 # Plan
@@ -131,6 +142,7 @@ entity: ${entity}
 archetype: ${archetype}
 created: ${created}
 updated: ${updated}
+${PROVENANCE}
 ---
 
 # Next
@@ -155,4 +167,37 @@ ${tasks.length > 0
   return { vision, plan, next };
 }
 
-module.exports = { readPPS, writePPS, createPPS, generateViews, genId };
+function hashContent(s) {
+  return crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+}
+
+// The truth guard. Writes generated views, but a file is only machine-owned
+// while its on-disk content still matches the hash recorded when we generated
+// it. Hand-edited since then — or existing before we ever generated it (a
+// hand-authored .intent/, like phewsh's own) — means it IS the truth now:
+// preserve it, never overwrite. Records fresh hashes in pps.generated and
+// persists pps.json. Returns { written, preserved }.
+function writeGuardedViews(intentDir, pps) {
+  fs.mkdirSync(intentDir, { recursive: true });
+  const views = generateViews(pps);
+  const prior = (pps.generated && pps.generated.hashes) || {};
+  const written = [];
+  const preserved = [];
+  pps.generated = { ...(pps.generated || {}), hashes: { ...prior } };
+  for (const [key, file] of [['vision', 'vision.md'], ['plan', 'plan.md'], ['next', 'next.md']]) {
+    const fp = path.join(intentDir, file);
+    let current = null;
+    try { current = fs.readFileSync(fp, 'utf-8'); } catch { /* absent → ours to write */ }
+    if (current !== null && (!prior[file] || hashContent(current) !== prior[file])) {
+      preserved.push(file);
+      continue;
+    }
+    fs.writeFileSync(fp, views[key]);
+    pps.generated.hashes[file] = hashContent(views[key]);
+    written.push(file);
+  }
+  writePPS(intentDir, pps);
+  return { written, preserved };
+}
+
+module.exports = { readPPS, writePPS, createPPS, generateViews, writeGuardedViews, genId };

package/lib/projects-index.js

@@ -64,10 +64,10 @@ function listProjects() {
 }
 
 /** Shallow scan: direct children of common roots that contain .intent/. */
-function scanForProjects() {
+function scanForProjects(roots = SCAN_ROOTS) {
   const found = [];
   const seen = new Set(); // realpath-dedupe — case-insensitive FS makes ~/Projects and ~/projects one dir
-  for (const root of SCAN_ROOTS) {
+  for (const root of roots) {
     let entries;
     try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { continue; }
     for (const e of entries) {
@@ -86,6 +86,34 @@ function scanForProjects() {
   return found;
 }
 
+// Likely candidates: real projects (a .git repo is the conservative signal)
+// that don't have .intent/ yet. Same shallow, opt-in scan as scanForProjects —
+// one level deep in the usual folders, never recursive, never dotfiles read.
+// Each hit carries its `reason` so the user sees WHY it was suggested.
+const CANDIDATE_CAP = 15;
+function scanForCandidates(roots = SCAN_ROOTS) {
+  const found = [];
+  const seen = new Set();
+  for (const root of roots) {
+    let entries;
+    try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith('.')) continue;
+      const dir = path.join(root, e.name);
+      try {
+        if (!fs.existsSync(path.join(dir, '.git'))) continue;
+        if (fs.existsSync(path.join(dir, '.intent'))) continue; // already phewsh-enabled (or partially)
+        const real = fs.realpathSync(dir);
+        if (seen.has(real)) continue;
+        seen.add(real);
+        found.push({ name: e.name, path: real, reason: 'git repo, no .intent/ yet' });
+        if (found.length >= CANDIDATE_CAP) return found;
+      } catch { /* unreadable dir — skip */ }
+    }
+  }
+  return found;
+}
+
 function fmtAgo(ts) {
   if (!ts) return '';
   const mins = Math.floor((Date.now() - new Date(ts).getTime()) / 60000);
@@ -95,4 +123,4 @@ function fmtAgo(ts) {
   return `${Math.floor(hrs / 24)}d ago`;
 }
 
-module.exports = { INDEX_FILE, SCAN_ROOTS, recordProject, listProjects, scanForProjects, fmtAgo };
+module.exports = { INDEX_FILE, SCAN_ROOTS, recordProject, listProjects, scanForProjects, scanForCandidates, fmtAgo };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phewsh",
-  "version": "0.15.71",
+  "version": "0.15.73",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"