phewsh 0.14.5 → 0.15.0

package/README.md

@@ -31,18 +31,32 @@ phewsh ai providers                           # see what's installed
 API keys (OpenRouter, Anthropic, Groq, …) and PHEWSH pooled credits remain
 available as alternatives — `phewsh login --set-key`.
 
-## Two packages, one system
+## One package, one system
 
-- **`phewsh`** (this package) — the CLI: intent authoring, sync, bridges,
-  receipts, dispatch.
-- **`phewsh-mcp-server`** — the MCP server that `phewsh mcp setup` wires into
-  Claude Code / Cursor / any MCP client. It gives an *interactive* agent
-  session your project's briefing, task queue, and enforcement gate over
-  stdio, and shares state with the bridges (`~/.phewsh/`).
+Everything ships in `phewsh` — the CLI (intent authoring, sync, bridges,
+receipts, dispatch) *and* the MCP server. `phewsh mcp setup` wires the
+bundled server into Claude Code / Cursor / any MCP client via
+`phewsh mcp serve --stdio`: an *interactive* agent session gets your
+project's briefing, task queue, and enforcement gate over stdio, and shares
+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/clarify.js

@@ -82,7 +82,7 @@ ${isRefine ? '\nThis is a refinement of existing intent. The previous goal was:
       'content-type': 'application/json',
     },
     body: JSON.stringify({
-      model: 'claude-sonnet-4-6',
+      model: require('../lib/providers').DEFAULT_ANTHROPIC_MODEL,
       max_tokens: 1024,
       system: systemPrompt,
       messages: [{ role: 'user', content: raw }],

package/commands/gate.js

@@ -237,7 +237,7 @@ ${(plan || 'No plan yet').slice(0, 1500)}`;
       'content-type': 'application/json',
     },
     body: JSON.stringify({
-      model: 'claude-sonnet-4-6',
+      model: require('../lib/providers').DEFAULT_ANTHROPIC_MODEL,
       max_tokens: 1024,
       messages: [{ role: 'user', content: prompt }],
     }),

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/intent.js

@@ -261,7 +261,7 @@ ${(next || 'No next actions yet').slice(0, 2000)}`;
         'content-type': 'application/json',
       },
       body: JSON.stringify({
-        model: 'claude-sonnet-4-6',
+        model: require('../lib/providers').DEFAULT_ANTHROPIC_MODEL,
         max_tokens: 4096,
         system: systemPrompt,
         messages: [{ role: 'user', content: userPrompt }],

package/commands/mcp.js

@@ -1,15 +1,19 @@
 // phewsh mcp — Set up and sync the PHEWSH MCP coordination layer.
 //
+// The MCP server ships inside this package (mcp/ — ESM subtree).
+// No second install, no phewsh-mcp-server package.
+//
 // Usage:
-//   phewsh mcp setup    — Install MCP server deps + configure Claude Code
-//   phewsh mcp sync     — Sync local .intent/ + cloud projects → ~/.phewsh/projects.json
-//   phewsh mcp status   — Check what agents can see right now
-//   phewsh mcp serve    — Start the HTTP transport for the web bridge (:7483)
+//   phewsh mcp setup           — Configure Claude Code to use the bundled server
+//   phewsh mcp sync            — Sync local .intent/ + cloud projects → ~/.phewsh/projects.json
+//   phewsh mcp status          — Check what agents can see right now
+//   phewsh mcp serve           — Start the HTTP transport for the web bridge (:7483)
+//   phewsh mcp serve --stdio   — Run the stdio MCP server (what agent configs point at)
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync, spawn } = require('child_process');
+const { spawn } = require('child_process');
 
 const PHEWSH_DIR = path.join(os.homedir(), '.phewsh');
 const PROJECTS_FILE = path.join(PHEWSH_DIR, 'projects.json');
@@ -130,30 +134,16 @@ async function loadCloudProjects() {
   }
 }
 
-function findMcpServerPath() {
-  // Check common locations
-  const candidates = [
-    path.join(__dirname, '..', '..', 'mcp', 'src', 'index.js'),  // monorepo sibling
-    path.join(process.cwd(), 'mcp', 'src', 'index.js'),           // cwd
-  ];
-
-  // Also check if phewsh-mcp-server is globally installed
-  try {
-    const globalPath = execSync('npm root -g', { encoding: 'utf-8' }).trim();
-    candidates.push(path.join(globalPath, 'phewsh-mcp-server', 'src', 'index.js'));
-  } catch { /* not installed globally */ }
+// The server is bundled with this package — no hunting.
+const MCP_SERVER_PATH = path.join(__dirname, '..', 'mcp', 'index.js');
+const MCP_HTTP_PATH = path.join(__dirname, '..', 'mcp', 'http-server.js');
 
-  for (const p of candidates) {
-    if (fs.existsSync(p)) return path.resolve(p);
-  }
-  return null;
+function findMcpServerPath() {
+  return fs.existsSync(MCP_SERVER_PATH) ? MCP_SERVER_PATH : null;
 }
 
 function findHttpServerPath() {
-  const stdioPath = findMcpServerPath();
-  if (!stdioPath) return null;
-  const httpPath = path.join(path.dirname(stdioPath), 'http-server.js');
-  return fs.existsSync(httpPath) ? httpPath : null;
+  return fs.existsSync(MCP_HTTP_PATH) ? MCP_HTTP_PATH : null;
 }
 
 const DEFAULT_HTTP_PORT = 7483;
@@ -170,7 +160,25 @@ async function probeHttp(port = DEFAULT_HTTP_PORT) {
   }
 }
 
+function serveStdio() {
+  // stdio MCP server: stdout IS the protocol — print nothing here.
+  ensureDirs();
+  const child = spawn(process.execPath, [MCP_SERVER_PATH], {
+    stdio: 'inherit',
+    env: { ...process.env },
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+  const shutdown = () => { if (!child.killed) child.kill('SIGTERM'); };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
 async function serve() {
+  if (process.argv.includes('--stdio')) {
+    serveStdio();
+    return;
+  }
+
   console.log('');
   console.log(`  ${b(w('PHEWSH MCP HTTP transport'))}`);
   console.log('');
@@ -179,8 +187,8 @@ async function serve() {
 
   const httpPath = findHttpServerPath();
   if (!httpPath) {
-    console.log(`  ${yellow('HTTP transport not found.')} Expected at mcp/src/http-server.js`);
-    console.log(`  ${g('Make sure you have the latest phewsh monorepo or reinstall the MCP package.')}`);
+    console.log(`  ${yellow('HTTP transport not found.')} Expected bundled at ${g(MCP_HTTP_PATH)}`);
+    console.log(`  ${g('Reinstall: npm i -g phewsh')}`);
     return;
   }
 
@@ -222,42 +230,24 @@ async function setup() {
 
   ensureDirs();
 
-  // 1. Find or install MCP server
-  let serverPath = findMcpServerPath();
+  // 1. Confirm the bundled server is present
+  const serverPath = findMcpServerPath();
 
   if (!serverPath) {
-    console.log(`  ${yellow('MCP server not found locally.')}`);
-    console.log(`  ${g('Install it:')}`);
-    console.log(`    npm install -g phewsh-mcp-server`);
-    console.log('');
-    console.log(`  ${g('Or if you have the phewsh repo:')}`);
-    console.log(`    cd mcp && npm install`);
+    console.log(`  ${yellow('Bundled MCP server missing.')} Reinstall: ${w('npm i -g phewsh')}`);
     console.log('');
     return;
   }
 
-  console.log(`  ${green('Found MCP server:')} ${g(serverPath)}`);
-
-  // 2. Check if deps are installed
-  const mcpDir = path.dirname(path.dirname(serverPath));
-  const nodeModules = path.join(mcpDir, 'node_modules');
-  if (!fs.existsSync(nodeModules)) {
-    console.log(`  ${yellow('Installing dependencies...')}`);
-    try {
-      execSync('npm install', { cwd: mcpDir, stdio: 'pipe' });
-      console.log(`  ${green('Dependencies installed.')}`);
-    } catch (err) {
-      console.log(`  ${yellow('Failed to install deps.')} Run manually: cd ${mcpDir} && npm install`);
-    }
-  }
+  console.log(`  ${green('MCP server:')} ${g('bundled with phewsh — no separate install')}`);
 
-  // 3. Generate settings.json snippet
+  // 2. Generate settings.json snippet — points at phewsh itself, survives upgrades
   const claudeSettingsPath = path.join(os.homedir(), '.claude', 'settings.json');
   const snippet = {
     mcpServers: {
       phewsh: {
-        command: 'node',
-        args: [serverPath],
+        command: 'phewsh',
+        args: ['mcp', 'serve', '--stdio'],
       },
     },
   };
@@ -268,12 +258,16 @@ async function setup() {
   console.log(g('  ' + JSON.stringify(snippet, null, 2).split('\n').join('\n  ')));
   console.log('');
 
-  // Check if already configured
+  // Check if already configured — and flag stale configs from the two-package era
   if (fs.existsSync(claudeSettingsPath)) {
     try {
       const existing = JSON.parse(fs.readFileSync(claudeSettingsPath, 'utf-8'));
-      if (existing.mcpServers?.phewsh) {
+      const current = existing.mcpServers?.phewsh;
+      if (current?.command === 'phewsh') {
         console.log(`  ${green('Already configured in Claude Code settings.')}`);
+      } else if (current) {
+        console.log(`  ${yellow('Configured the old way')} (${g(current.command + ' ' + (current.args || []).join(' '))}).`);
+        console.log(`  ${g('Update it to the snippet above — the server now ships inside phewsh.')}`);
       } else {
         console.log(`  ${yellow('Not yet configured.')} Add the snippet above to your settings.`);
       }
@@ -442,10 +436,11 @@ async function main() {
       break;
     default:
       console.log(`\n  ${b('phewsh mcp')} — Connect AI agents to your project intelligence\n`);
-      console.log(`  ${w('setup')}    Install and configure the MCP server`);
-      console.log(`  ${w('sync')}     Sync projects → ~/.phewsh/projects.json`);
-      console.log(`  ${w('status')}   Check what agents can see right now`);
-      console.log(`  ${w('serve')}    Run the HTTP bridge for the web app (:7483)`);
+      console.log(`  ${w('setup')}            Configure agents to use the bundled MCP server`);
+      console.log(`  ${w('sync')}             Sync projects → ~/.phewsh/projects.json`);
+      console.log(`  ${w('status')}           Check what agents can see right now`);
+      console.log(`  ${w('serve')}            Run the HTTP bridge for the web app (:7483)`);
+      console.log(`  ${w('serve --stdio')}    Run the stdio MCP server (for agent configs)`);
       console.log('');
   }
 }