phewsh 0.14.6 → 0.15.0

package/README.md

@@ -43,6 +43,20 @@ state with the bridges (`~/.phewsh/`). No second install.
 Rule of thumb: `phewsh serve` = dispatch tasks *to* your agents.
 `phewsh mcp setup` = your agents pull tasks *from* PHEWSH mid-session.
 
+## Ambient — continuity without launching phewsh
+
+```bash
+phewsh ambient on
+```
+
+A consent screen shows exactly what changes (two hook entries in Claude
+Code's settings), then: every Claude Code session in a project with
+`.intent/` starts pre-briefed, and every session leaves a one-line
+metadata breadcrumb (never transcript contents) in
+`~/.phewsh/ambient-sessions.jsonl`. `phewsh ambient status` shows the
+full ledger; `phewsh ambient off` removes everything. Mission control
+is optional. Continuity is not.
+
 ## Live Execution
 
 Connect the web app to your local machine for real-time task execution:

package/bin/phewsh.js

@@ -71,6 +71,8 @@ const COMMANDS = {
   serve:   () => require('../commands/serve')(),
   sequence: () => require('../commands/sequence')(),
   seq:     () => require('../commands/sequence')(),
+  ambient: () => require('../commands/ambient')(),
+  hook:    () => require('../commands/hook')(),
   help:    showHelp,
   version: showVersion,
 };
@@ -103,6 +105,7 @@ function showHelp() {
   console.log(`    ${cyan('push/pull')}  ${g('Manual sync to/from phewsh.com/intent')}`);
   console.log(`    ${cyan('serve')}      ${g('Execution bridge — run from phewsh.com/intent')}`);
   console.log(`    ${cyan('mcp')}        ${g('Connect AI agents via MCP protocol')}`);
+  console.log(`    ${cyan('ambient')}    ${g('Continuity without launching phewsh — enhance your other tools')}`);
   console.log(`    ${cyan('receipts')}   ${g('Proof trail — what agents actually did, with evidence')}`);
   console.log(`    ${cyan('outcomes')}   ${g('Decision record — what was kept, reverted, or failed')}`);
   console.log(`    ${cyan('bypass')}     ${g('Went around phewsh? Record why — 10 seconds, no guilt')}`);

package/commands/ambient.js

@@ -0,0 +1,238 @@
+// phewsh ambient — continuity without launching phewsh.
+//
+// Principle (Jun 12): ambient before primary. Installing phewsh should make
+// the tools you already use better — context arrives, sessions leave
+// breadcrumbs — without you ever typing `phewsh`.
+//
+// Constraint (non-negotiable): radical transparency. Nothing changes
+// without a consent screen that names every file and every line. The
+// ledger (~/.phewsh/ambient.json) records exactly what was applied and
+// how to undo it. Trust matters more than automation here.
+//
+//   phewsh ambient            — status: detected tools, what's enhanced
+//   phewsh ambient on [--yes] — consent screen, then apply
+//   phewsh ambient off        — remove everything, update ledger
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { listHarnesses } = require('../lib/harnesses');
+
+const PHEWSH_DIR = path.join(os.homedir(), '.phewsh');
+const LEDGER_FILE = path.join(PHEWSH_DIR, 'ambient.json');
+const CLAUDE_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+
+const HOOK_START = { type: 'command', command: 'phewsh hook session-start' };
+const HOOK_END = { type: 'command', command: 'phewsh hook session-end' };
+
+// ANSI helpers (256-color per cli/lib/ui.js palette rules)
+const b = (s) => `\x1b[1m${s}\x1b[0m`;
+const teal = (s) => `\x1b[38;5;79m${s}\x1b[0m`;
+const sage = (s) => `\x1b[38;5;151m${s}\x1b[0m`;
+const slate = (s) => `\x1b[38;5;247m${s}\x1b[0m`;
+const cream = (s) => `\x1b[38;5;230m${s}\x1b[0m`;
+const peach = (s) => `\x1b[38;5;216m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+function loadLedger() {
+  try { return JSON.parse(fs.readFileSync(LEDGER_FILE, 'utf-8')); } catch { return { version: 1, applied: {}, seenHarnesses: [] }; }
+}
+
+function saveLedger(ledger) {
+  if (!fs.existsSync(PHEWSH_DIR)) fs.mkdirSync(PHEWSH_DIR, { recursive: true });
+  fs.writeFileSync(LEDGER_FILE, JSON.stringify(ledger, null, 2));
+}
+
+function loadClaudeSettings() {
+  try { return JSON.parse(fs.readFileSync(CLAUDE_SETTINGS, 'utf-8')); } catch { return null; }
+}
+
+function hasHook(settings, eventName, command) {
+  const entries = settings?.hooks?.[eventName];
+  if (!Array.isArray(entries)) return false;
+  return entries.some(e => (e.hooks || []).some(h => h.command === command));
+}
+
+function claudeApplied() {
+  const s = loadClaudeSettings();
+  return !!s && hasHook(s, 'SessionStart', HOOK_START.command) && hasHook(s, 'SessionEnd', HOOK_END.command);
+}
+
+function applyClaudeHooks() {
+  const settings = loadClaudeSettings() || {};
+  settings.hooks = settings.hooks || {};
+  const changes = [];
+  for (const [event, hook] of [['SessionStart', HOOK_START], ['SessionEnd', HOOK_END]]) {
+    settings.hooks[event] = settings.hooks[event] || [];
+    if (!hasHook(settings, event, hook.command)) {
+      settings.hooks[event].push({ hooks: [hook] });
+      changes.push(`hooks.${event} += "${hook.command}"`);
+    }
+  }
+  if (changes.length > 0) {
+    fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+  }
+  return changes;
+}
+
+function removeClaudeHooks() {
+  const settings = loadClaudeSettings();
+  if (!settings?.hooks) return [];
+  const removed = [];
+  for (const [event, hook] of [['SessionStart', HOOK_START], ['SessionEnd', HOOK_END]]) {
+    const entries = settings.hooks[event];
+    if (!Array.isArray(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 !== before) removed.push(`hooks.${event} -= "${hook.command}"`);
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+  if (removed.length > 0) fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+  return removed;
+}
+
+function showConsentScreen(harnesses) {
+  console.log('');
+  console.log(`  ${b(cream('PHEWSH ambient'))} ${sage('— continuity without launching phewsh')}`);
+  console.log('');
+  console.log(`  ${sage('Detected on this machine:')}`);
+  for (const h of harnesses.filter(h => h.installed)) {
+    const note = h.id === 'claude-code' ? teal('enhanceable now') : slate('detection only in v1 — `phewsh sequence` + `phewsh mcp setup` work today');
+    console.log(`    ${green('✓')} ${cream(h.label.padEnd(14))} ${note}`);
+  }
+  console.log('');
+  console.log(`  ${b('Claude Code enhancements:')}`);
+  console.log(`    ${teal('Context sync')}     ${sage('SessionStart hook — when a project has')} ${cream('.intent/')}${sage(', a short brief')}`);
+  console.log(`                     ${sage('(vision, next steps, constraints) is injected at session start.')}`);
+  console.log(`    ${teal('Session capture')}  ${sage('SessionEnd hook — appends one metadata line (time, project, cwd)')}`);
+  console.log(`                     ${sage('to')} ${cream('~/.phewsh/ambient-sessions.jsonl')}${sage('.')} ${b(sage('Never transcript contents.'))}`);
+  console.log('');
+  console.log(`  ${peach('Exactly what changes:')} ${sage('two hook entries in')} ${cream(CLAUDE_SETTINGS)}${sage('. Nothing else is touched.')}`);
+  console.log(`  ${sage('Undo anytime:')} ${cream('phewsh ambient off')} ${sage('· full record:')} ${cream('phewsh ambient status')}`);
+  console.log('');
+}
+
+async function confirm(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+async function turnOn(skipConfirm) {
+  const harnesses = listHarnesses();
+  showConsentScreen(harnesses);
+
+  if (claudeApplied()) {
+    console.log(`  ${green('Already applied.')} ${sage('Status:')} ${cream('phewsh ambient status')}`);
+    console.log('');
+    return;
+  }
+
+  if (!skipConfirm) {
+    const ok = await confirm(`  ${b('Apply?')} ${slate('[y/N] ')}`);
+    if (!ok) {
+      console.log(`  ${sage('Nothing changed.')}`);
+      console.log('');
+      return;
+    }
+  }
+
+  const changes = applyClaudeHooks();
+  const ledger = loadLedger();
+  ledger.applied['claude-code'] = {
+    at: new Date().toISOString(),
+    file: CLAUDE_SETTINGS,
+    changes,
+    captures: '~/.phewsh/ambient-sessions.jsonl — timestamp, project, cwd only',
+    undo: 'phewsh ambient off',
+  };
+  ledger.seenHarnesses = harnesses.filter(h => h.installed).map(h => h.id);
+  saveLedger(ledger);
+
+  console.log('');
+  console.log(`  ${green('●')} ${b('Ambient is on.')}`);
+  changes.forEach(c => console.log(`    ${teal('+')} ${slate(c)}`));
+  console.log('');
+  console.log(`  ${sage('Next Claude Code session in a project with')} ${cream('.intent/')} ${sage('starts pre-briefed.')}`);
+  console.log(`  ${sage('You never have to launch phewsh for this to work.')}`);
+  console.log('');
+}
+
+function turnOff() {
+  const removed = removeClaudeHooks();
+  const ledger = loadLedger();
+  delete ledger.applied['claude-code'];
+  saveLedger(ledger);
+  console.log('');
+  if (removed.length > 0) {
+    console.log(`  ${green('●')} ${b('Ambient is off.')}`);
+    removed.forEach(c => console.log(`    ${peach('-')} ${slate(c)}`));
+    console.log(`  ${sage('Breadcrumb log kept at')} ${cream('~/.phewsh/ambient-sessions.jsonl')} ${sage('— delete it if you want; phewsh never will.')}`);
+  } else {
+    console.log(`  ${sage('Nothing was applied — nothing to remove.')}`);
+  }
+  console.log('');
+}
+
+function status() {
+  const harnesses = listHarnesses();
+  const ledger = loadLedger();
+  console.log('');
+  console.log(`  ${b(cream('PHEWSH ambient'))} ${sage('— status')}`);
+  console.log('');
+  for (const h of harnesses.filter(h => h.installed)) {
+    if (h.id === 'claude-code') {
+      const on = claudeApplied();
+      console.log(`    ${on ? green('●') : yellow('○')} ${cream(h.label.padEnd(14))} ${on ? teal('ambient on') : sage('not enhanced — phewsh ambient on')}`);
+      const entry = ledger.applied['claude-code'];
+      if (entry) {
+        console.log(`        ${slate('applied ' + entry.at)}`);
+        (entry.changes || []).forEach(c => console.log(`        ${slate('· ' + c + ' (' + entry.file + ')')}`));
+        console.log(`        ${slate('· captures: ' + entry.captures)}`);
+      }
+    } else {
+      console.log(`    ${slate('○')} ${cream(h.label.padEnd(14))} ${slate('detected — v1 enhances Claude Code only')}`);
+    }
+  }
+
+  // New harnesses since last apply — the re-offer.
+  const seen = ledger.seenHarnesses || [];
+  const fresh = harnesses.filter(h => h.installed && !seen.includes(h.id));
+  if (seen.length > 0 && fresh.length > 0) {
+    console.log('');
+    console.log(`  ${peach('New since last time:')} ${cream(fresh.map(h => h.label).join(', '))}`);
+  }
+
+  // Recent breadcrumbs — show the user exactly what ambient has recorded.
+  const logFile = path.join(PHEWSH_DIR, 'ambient-sessions.jsonl');
+  try {
+    const lines = fs.readFileSync(logFile, 'utf-8').trim().split('\n');
+    console.log('');
+    console.log(`  ${sage('Last ambient breadcrumbs (' + lines.length + ' total):')}`);
+    lines.slice(-3).forEach(l => {
+      try {
+        const e = JSON.parse(l);
+        console.log(`    ${slate(e.ts + ' · ' + e.event + ' · ' + (e.project || path.basename(e.cwd || '?')))}`);
+      } catch { /* skip bad line */ }
+    });
+  } catch { /* no breadcrumbs yet */ }
+  console.log('');
+}
+
+async function main() {
+  const sub = process.argv[3] || 'status';
+  const skipConfirm = process.argv.includes('--yes');
+  if (sub === 'on') return turnOn(skipConfirm);
+  if (sub === 'off') return turnOff();
+  return status();
+}
+
+module.exports = main;

package/commands/hook.js

@@ -0,0 +1,120 @@
+// phewsh hook — runtime endpoints for ambient harness hooks.
+//
+// These are invoked BY other tools (Claude Code hooks), not by people.
+// Contract: fast, silent when there's nothing to say, and they never
+// read or store transcript contents — metadata only. What gets written
+// is documented in `phewsh ambient status`.
+//
+//   phewsh hook session-start   stdout → injected into the agent's context
+//   phewsh hook session-end     stdin (hook JSON) → metadata breadcrumb
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PHEWSH_DIR = path.join(os.homedir(), '.phewsh');
+const AMBIENT_LOG = path.join(PHEWSH_DIR, 'ambient-sessions.jsonl');
+const INTENT_DIR = path.join(process.cwd(), '.intent');
+
+function readIfExists(p, maxBytes = 16384) {
+  try { return fs.readFileSync(p, 'utf-8').slice(0, maxBytes); } catch { return null; }
+}
+
+function projectName() {
+  const meta = readIfExists(path.join(INTENT_DIR, 'project.json'));
+  if (meta) {
+    try { const m = JSON.parse(meta); if (m.name) return m.name; } catch { /* fall through */ }
+  }
+  return path.basename(process.cwd());
+}
+
+function appendBreadcrumb(event, extra = {}) {
+  try {
+    if (!fs.existsSync(PHEWSH_DIR)) fs.mkdirSync(PHEWSH_DIR, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      event,
+      cwd: process.cwd(),
+      project: fs.existsSync(INTENT_DIR) ? projectName() : null,
+      source: 'claude-code-ambient',
+      ...extra,
+    });
+    fs.appendFileSync(AMBIENT_LOG, line + '\n');
+  } catch { /* breadcrumbs must never break the host tool */ }
+}
+
+function firstLines(text, n) {
+  let body = text;
+  // Strip YAML frontmatter — metadata, not context.
+  if (body.startsWith('---')) {
+    const end = body.indexOf('\n---', 3);
+    if (end !== -1) body = body.slice(end + 4);
+  }
+  return body.split('\n')
+    .filter(l => l.trim())
+    .filter(l => !/^#+\s*$/.test(l.trim()))
+    .slice(0, n)
+    .join('\n');
+}
+
+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.
+    process.exit(0);
+  }
+
+  const parts = [];
+  parts.push(`# Project brief (from .intent/ — PHEWSH continuity layer)`);
+  parts.push(`Project: ${projectName()}`);
+
+  const meta = readIfExists(path.join(INTENT_DIR, 'project.json'));
+  if (meta) {
+    try {
+      const m = JSON.parse(meta);
+      if (m.tldr) parts.push(`TLDR: ${m.tldr}`);
+      if (m.constraints) {
+        const c = Object.entries(m.constraints).map(([k, v]) => `${k}: ${v}`).join(' · ');
+        if (c) parts.push(`Constraints: ${c}`);
+      }
+    } catch { /* skip meta */ }
+  }
+
+  const vision = readIfExists(path.join(INTENT_DIR, 'vision.md'));
+  if (vision) parts.push(`\n## Vision (excerpt)\n${firstLines(vision, 8)}`);
+
+  const next = readIfExists(path.join(INTENT_DIR, 'next.md'));
+  if (next) parts.push(`\n## Next (excerpt)\n${firstLines(next, 8)}`);
+
+  const status = readIfExists(path.join(INTENT_DIR, 'status.md'));
+  if (status) parts.push(`\n## Status (excerpt)\n${firstLines(status, 5)}`);
+
+  parts.push(`\n(Brief injected by PHEWSH ambient from .intent/. Honor the constraints above. The human can run \`phewsh\` for mission control — council, outcomes, the decision record.)`);
+
+  process.stdout.write(parts.join('\n') + '\n');
+  appendBreadcrumb('session-start');
+  process.exit(0);
+}
+
+function sessionEnd() {
+  let stdin = '';
+  process.stdin.on('data', d => { stdin += d.toString(); });
+  process.stdin.on('end', () => {
+    let reason = null;
+    try { reason = JSON.parse(stdin).reason || null; } catch { /* metadata only; fine */ }
+    appendBreadcrumb('session-end', reason ? { reason } : {});
+    process.exit(0);
+  });
+  // If the host never closes stdin, don't hang it.
+  setTimeout(() => { appendBreadcrumb('session-end'); process.exit(0); }, 1500);
+}
+
+function main() {
+  const event = process.argv[3];
+  if (event === 'session-start') return sessionStart();
+  if (event === 'session-end') return sessionEnd();
+  // Unknown event: exit silently — hooks must never error the host tool.
+  process.exit(0);
+}
+
+module.exports = main;

package/commands/session.js

@@ -274,6 +274,31 @@ async function main() {
   }
   let currentModel = DEFAULT_MODEL;
   let harnessModel = null; // pass-through preference; the harness validates it
+  let liveModelsCache = null; // fetched once per session from the provider's own list
+
+  // Discovery, not hardcoding: the provider's models endpoint is the truth.
+  async function fetchLiveModels() {
+    if (liveModelsCache) return liveModelsCache;
+    try {
+      if (config?.provider === 'openrouter') {
+        const res = await fetch('https://openrouter.ai/api/v1/models', { signal: AbortSignal.timeout(4000) });
+        if (res.ok) {
+          const data = await res.json();
+          liveModelsCache = (data.data || []).map(m => m.id);
+        }
+      } else if (config?.apiKey) {
+        const res = await fetch('https://api.anthropic.com/v1/models?limit=100', {
+          headers: { 'x-api-key': config.apiKey, 'anthropic-version': '2023-06-01' },
+          signal: AbortSignal.timeout(4000),
+        });
+        if (res.ok) {
+          const data = await res.json();
+          liveModelsCache = (data.data || []).map(m => m.id);
+        }
+      }
+    } catch { /* offline or no key — aliases still work */ }
+    return liveModelsCache;
+  }
   let totalPromptTokens = 0;
   let totalCompletionTokens = 0;
 
@@ -561,6 +586,29 @@ async function main() {
     historySize: 100,
   });
 
+  // Live input coloring: slash commands render teal, @mentions peach, as
+  // you type — same signal Claude Code gives. TTY-only, fail-soft: if the
+  // private readline API ever changes, input falls back to plain.
+  if (process.stdout.isTTY && typeof rl._writeToOutput === 'function') {
+    const origWrite = rl._writeToOutput.bind(rl);
+    rl._writeToOutput = function (s) {
+      try {
+        const cur = rl.line || '';
+        if ((cur[0] === '/' || cur[0] === '@') && typeof s === 'string' && s.includes(cur)) {
+          const c = cur[0] === '/' ? '\x1b[38;5;79m' : '\x1b[38;5;216m';
+          s = s.split(cur).join(c + cur + '\x1b[0m');
+        }
+      } catch { /* never break input */ }
+      origWrite(s);
+    };
+    process.stdin.on('keypress', () => {
+      try {
+        const cur = rl.line || '';
+        if (cur[0] === '/' || cur[0] === '@') rl._refreshLine();
+      } catch { /* never break input */ }
+    });
+  }
+
   rl.prompt();
 
   rl.on('line', async (line) => {
@@ -713,6 +761,7 @@ async function main() {
         console.log('');
         console.log(`  ${cream('author .intent/')}`);
         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('/clarify')}     ${sage('Turn ideas into .intent/ artifacts')}`);
         console.log(`    ${teal('/gate')}        ${sage('Set constraints (budget, time, skill)')}`);
         console.log(`    ${teal('/context')}     ${sage('Show loaded .intent/ files')}`);
@@ -1085,16 +1134,41 @@ async function main() {
       if (cmd === 'models') {
         console.log('');
         ui.divider('line');
-        console.log(`  ${b(cream('Available models'))}`);
-        ui.divider('line');
-        for (const [key, model] of Object.entries(MODELS)) {
-          const active = key === currentModel ? ` ${teal('●')}` : '';
-          console.log(`    ${cream(key.padEnd(16))} ${sage(model.name)}${active}`);
+        if (route?.type === 'harness') {
+          const h = HARNESSES[route.id];
+          console.log(`  ${b(cream('Models'))} ${sage('— ' + h.label + ' owns its own model list')}`);
+          ui.divider('line');
+          console.log(`  ${sage('Current preference:')} ${cream(harnessModel || h.label + ' default')}`);
+          console.log(`  ${sage('Set one with')} ${cream('/model <anything ' + h.label + ' accepts>')} ${slate('— it validates, not phewsh')}`);
+          console.log(`  ${slate('shortcuts that work for Claude Code: sonnet · opus · haiku · fable · any full model id')}`);
+          console.log('');
+          rl.prompt();
+          return;
         }
-        if (!MODELS[currentModel] && route?.type !== 'harness') {
+        // API route: ask the provider for its real list.
+        const providerName = config?.provider === 'openrouter' ? 'OpenRouter' : 'Anthropic';
+        const live = await fetchLiveModels();
+        if (live && live.length > 0) {
+          console.log(`  ${b(cream('Available models'))} ${sage('— live from ' + providerName)}`);
+          ui.divider('line');
+          const shown = live.slice(0, 24);
+          shown.forEach(id => {
+            const active = modelId(currentModel) === id ? ` ${teal('●')}` : '';
+            console.log(`    ${cream(id)}${active}`);
+          });
+          if (live.length > shown.length) console.log(`    ${slate('… +' + (live.length - shown.length) + ' more — /model <id> takes any of them')}`);
+        } else {
+          console.log(`  ${b(cream('Available models'))} ${slate('(offline — shortcuts only; any id still passes through)')}`);
+          ui.divider('line');
+          for (const [key, model] of Object.entries(MODELS)) {
+            const active = key === currentModel ? ` ${teal('●')}` : '';
+            console.log(`    ${cream(key.padEnd(16))} ${sage(model.name)}${active}`);
+          }
+        }
+        if (!MODELS[currentModel] && !live?.includes(modelId(currentModel))) {
           console.log(`    ${cream(String(currentModel).padEnd(16))} ${sage('(pass-through)')} ${teal('●')}`);
         }
-        console.log(`\n  ${sage('Switch with:')} ${cream('/model <name>')} ${slate('— aliases above, or any model id (passed through)')}\n`);
+        console.log(`\n  ${sage('Switch with:')} ${cream('/model <name>')} ${slate('— shortcuts: ' + Object.keys(MODELS).map(k => k.replace('claude-', '')).join(' · '))}\n`);
         rl.prompt();
         return;
       }
@@ -1150,6 +1224,105 @@ async function main() {
         return;
       }
 
+      if (cmd === 'intent') {
+        // Pause and reflect before moving forward — the samurai check.
+        // View what the project says it is; update it when reality moved.
+        const artifacts = ['vision', 'plan', 'next', 'status'];
+        const intentDir = path.join(process.cwd(), '.intent');
+
+        const renderMd = (raw) => {
+          let body = raw;
+          if (body.startsWith('---')) {
+            const end = body.indexOf('\n---', 3);
+            if (end !== -1) body = body.slice(end + 4);
+          }
+          return body.trim().split('\n').map(l => {
+            if (/^#{1,2}\s/.test(l)) return `  ${b(teal(l.replace(/^#+\s*/, '')))}`;
+            if (/^#{3,}\s/.test(l)) return `  ${cream(l.replace(/^#+\s*/, ''))}`;
+            if (/^\s*[-*]\s/.test(l)) return `    ${teal('·')} ${sage(l.replace(/^\s*[-*]\s*/, ''))}`;
+            if (/^\s*\d+\.\s/.test(l)) return `    ${sage(l.trim())}`;
+            return `  ${slate(l)}`;
+          }).join('\n');
+        };
+
+        if (!fs.existsSync(intentDir)) {
+          console.log(`  ${sage('No .intent/ here yet.')} ${cream('/init')} ${sage('creates it — that is the whole point.')}`);
+          rl.prompt();
+          return;
+        }
+
+        const sub = (cmdArg || '').trim().toLowerCase();
+
+        if (sub.startsWith('view')) {
+          const which = sub.split(/\s+/)[1];
+          const targets = which && artifacts.includes(which) ? [which] : artifacts;
+          for (const a of targets) {
+            const p = path.join(intentDir, `${a}.md`);
+            if (!fs.existsSync(p)) continue;
+            console.log('');
+            ui.divider('line');
+            console.log(`  ${b(cream(a.toUpperCase()))} ${slate('.intent/' + a + '.md')}`);
+            ui.divider('line');
+            console.log(renderMd(fs.readFileSync(p, 'utf-8')));
+          }
+          console.log('');
+          console.log(`  ${slate('moved on since this was written?')} ${cream('/intent update')}`);
+          console.log('');
+          rl.prompt();
+          return;
+        }
+
+        if (sub === 'update') {
+          // Reflect first: what does the record say happened since last update?
+          console.log('');
+          console.log(`  ${b(cream('Before updating — what actually happened:'))}`);
+          try {
+            const { recentDecisions } = require('../lib/outcomes');
+            const recent = recentDecisions(5, { project: projectName });
+            if (recent.length > 0) {
+              recent.forEach(d => {
+                const mark = d.outcome === 'kept' ? green('✓') : d.outcome ? yellow('~') : slate('·');
+                console.log(`    ${mark} ${sage((d.summary || '').slice(0, 70))} ${slate('[' + (d.outcome || 'unlabeled') + ']')}`);
+              });
+            } else {
+              console.log(`    ${slate('no decisions recorded yet')}`);
+            }
+          } catch { console.log(`    ${slate('record unavailable')}`); }
+          console.log('');
+          console.log(`  ${teal('●')} ${sage('Handing you to the guided update')} ${slate('— exit to come back to phewsh')}`);
+          console.log('');
+          rl.pause();
+          const { spawnSync } = require('child_process');
+          spawnSync(process.execPath, [path.join(__dirname, '..', 'bin', 'phewsh.js'), 'clarify'], { stdio: 'inherit' });
+          rl.resume();
+          console.log('');
+          console.log(`  ${teal('●')} ${sage('Back in phewsh.')} ${slate('/intent view to see the result — agents pick it up automatically')}`);
+          console.log('');
+          rl.prompt();
+          return;
+        }
+
+        // No arg: the pause. Where the project stands, in one screen.
+        const present = artifacts.filter(a => fs.existsSync(path.join(intentDir, `${a}.md`)));
+        const stale = present.map(a => {
+          const raw = fs.readFileSync(path.join(intentDir, `${a}.md`), 'utf-8');
+          const m = raw.match(/^updated:\s*(\S+)/m);
+          return { a, updated: m ? m[1] : null };
+        });
+        console.log('');
+        console.log(`  ${b(cream('INTENT'))} ${slate('— .intent/ in ' + projectName)}`);
+        stale.forEach(({ a, updated }) => {
+          const age = updated ? slate('updated ' + updated) : slate('no date');
+          console.log(`    ${teal('·')} ${cream(a.padEnd(8))} ${age}`);
+        });
+        console.log('');
+        console.log(`    ${cream('/intent view')} ${slate('[vision|plan|next|status]')}  ${sage('read it, rendered')}`);
+        console.log(`    ${cream('/intent update')}                       ${sage('reflect on the record, then guided rewrite')}`);
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'council' || cmd === 'all') {
         // One prompt, every installed harness, in parallel. Different
         // models disagreeing is the signal — and which answer you KEEP

package/package.json

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