phewsh 0.15.30 → 0.15.32

package/bin/phewsh.js

@@ -189,6 +189,12 @@ if (!command) {
   exitAfterUpdate(0);
 } else if (COMMANDS[command]) {
   COMMANDS[command]();
+} else if (require('../lib/harnesses').HARNESSES[command]) {
+  // `phewsh <harness>` — a doorway shortcut. Launch the session and have it
+  // auto-run /work for that harness (preflight → brief → native handoff →
+  // postflight). This is what the phewsh.com doorways copy as a single command.
+  process.env.PHEWSH_AUTOWORK = command;
+  maybeFirstRunIntro().then(() => COMMANDS.session());
 } else {
   console.error(`\n  Unknown command: ${command}\n  Run 'phewsh help' for available commands.\n`);
   process.exit(1);

package/commands/session.js

@@ -17,13 +17,14 @@ const intentDir = () => path.join(process.cwd(), '.intent');
 const { select, refreshSession: refreshSess } = require('../lib/supabase');
 const { readPPS } = require('../lib/pps');
 const { push, pull, ensureValidToken } = require('./sync');
-const { HARNESSES, interactiveLaunchArgs, listHarnesses, runViaHarness, cancelActive } = require('../lib/harnesses');
+const { HARNESSES, INSTALL, interactiveLaunchArgs, listHarnesses, runViaHarness, cancelActive } = require('../lib/harnesses');
 const { recordDecision, labelOutcome, pendingDecisions, recentDecisions, outcomeStats, OUTCOMES } = require('../lib/outcomes');
 const { suggest, suggestAll } = require('../lib/suggest');
 const continuity = require('../lib/continuity');
 const selfheal = require('../lib/selfheal');
 const learning = require('../lib/learning');
 const recall = require('../lib/recall');
+const { routeCoach } = require('../lib/route-coach');
 const { closest } = require('../lib/closest');
 const cmdHistory = require('../lib/history');
 const { recordSessionEvent } = require('../lib/receipts-data');
@@ -55,6 +56,23 @@ const { recordProject, listProjects, scanForProjects, fmtAgo } = require('../lib
 const { b, d, w, g, green, cyan, yellow,
         teal, peach, sage, slate, cream, ember } = ui;
 
+// Best-effort copy to the system clipboard so the brief survives the native
+// tool taking over the terminal (and any trust/permission gate). Returns true
+// if a clipboard tool accepted it. Never throws — it's a convenience.
+function copyToClipboard(text) {
+  const { spawnSync } = require('child_process');
+  const tries = process.platform === 'darwin' ? [['pbcopy', []]]
+    : process.platform === 'win32' ? [['clip', []]]
+    : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+  for (const [bin, args] of tries) {
+    try {
+      const r = spawnSync(bin, args, { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+      if (r.status === 0) return true;
+    } catch (_) { /* try next */ }
+  }
+  return false;
+}
+
 // Sync awareness: compare local .intent/ timestamps with cloud updated_at
 async function checkSyncStatus(config) {
   if (!config?.supabaseUserId || !config?.supabaseAccessToken) return null;
@@ -180,6 +198,31 @@ const INTENT_MODES = {
   4: { id: 'review',   label: 'Review',   hint: 'The user wants critical review. Find what is wrong or risky before praising anything. Be specific about severity.' },
 };
 
+const BARE_COMMANDS = {
+  help: '/help',
+  h: '/help',
+  next: '/next',
+  guide: '/next',
+  recommend: '/next',
+  tools: '/harnesses',
+  tool: '/harnesses',
+  agents: '/harnesses',
+  harnesses: '/harnesses',
+  routes: '/provider',
+  route: '/provider',
+  provider: '/provider',
+  status: '/status',
+  truth: '/truth',
+  brief: '/brief',
+  thread: '/thread',
+  outcomes: '/outcomes',
+  clarify: '/clarify',
+  setup: '/setup',
+  work: '/work',
+  quit: '/quit',
+  exit: '/quit',
+};
+
 function loadConfig() {
   return configFile.loadConfig(CONFIG_PATH);
 }
@@ -348,10 +391,34 @@ async function main() {
   let nextChoices = null;          // ranked /next suggestions awaiting a numeric pick
   let pendingDidYouMean = null;    // a suggested command; bare Enter accepts + runs it
   let decisionsThisSession = 0;
+  let lastRouteCoachId = null;     // avoid repeating the same best-door hint
 
   // ── The Exhale: animated brand reveal ──────────────────
   await ui.brandReveal();
 
+  // Self-aware, plain-language summary — the value prop made real with THIS
+  // machine's state. Non-technical readers get one warm sentence; the rows
+  // below give engineers the exact facts. Fail-soft: a missing piece just
+  // shortens the line, it never blocks the door.
+  (function narrativeSummary() {
+    try {
+      const toolCount = harnesses.filter(h => h.installed).length;
+      const hasProject = intentFiles.length > 0;
+      const dot = teal('●');
+      const tools = `${toolCount} AI tool${toolCount !== 1 ? 's' : ''}`;
+      if (hasProject && toolCount > 0) {
+        console.log(`  ${dot} ${sage(`${tools} here, all sharing one memory of`)} ${cream(projectName)}${sage(' — so you never start this project over.')}`);
+      } else if (hasProject) {
+        console.log(`  ${dot} ${sage('phewsh holds one verified memory of')} ${cream(projectName)} ${sage('— ready for whatever AI tool you bring.')}`);
+      } else if (toolCount > 0) {
+        console.log(`  ${dot} ${sage(`${tools} here.`)} ${sage('Run')} ${cream('/init')} ${sage('and they all work from one shared project memory.')}`);
+      } else {
+        console.log(`  ${dot} ${sage('Install Claude Code, Codex, or Gemini — phewsh keeps them all on the same page.')}`);
+      }
+      console.log('');
+    } catch { /* the summary is a flourish, never a blocker */ }
+  })();
+
   if (config?.apiKey && !config.apiKey.startsWith('sk-')) {
     // Persist the cleanup so this never nags again — an unusable key
     // (not sk-…) helps nobody, and harness routes need no key at all.
@@ -563,13 +630,30 @@ async function main() {
   }
 
   // One subtle line under the menu — the single highest-leverage nudge, if any.
-  function showInlineTip() {
+  function showInlineTip(filter = null) {
     let tip = null;
     try { tip = suggest(buildSuggestState()); } catch { /* never block the prompt on guidance */ }
     if (!tip) return;
+    if (filter && !filter(tip)) return;
     console.log(`  ${teal('⤷')} ${sage(tip.message)} ${cream(tip.command.trim())} ${slate('· /next for options')}`);
   }
 
+  // The front door should steer, not trap. For a plain-language ask, point to
+  // the better native door when the pattern is obvious, then still run the turn.
+  function showRouteCoach(input) {
+    try {
+      const advice = routeCoach(input, {
+        route,
+        harnesses,
+        hasIntentDir: intentFiles.length > 0,
+        turnsThisSession: Math.floor(messages.length / 2),
+      });
+      if (!advice || advice.id === lastRouteCoachId) return;
+      lastRouteCoachId = advice.id;
+      console.log(`  ${peach('↪')} ${sage(advice.message)} ${cream(advice.command)} ${slate('· still sending this turn')}`);
+    } catch { /* route coaching is advisory, never a blocker */ }
+  }
+
   // Open a known project from the bootstrap menu: chdir, reload memory,
   // back to the normal flow. The session is the cockpit; projects swap in.
   function openProjectAt(dir) {
@@ -669,6 +753,7 @@ async function main() {
       lastTurnFailure = null;
       awaitingOutcome = decisionId;
       console.log(slate(`  via ${HARNESSES[harnessId].label} · how'd it go? 1 kept · 2 undid · 3 redid · 4 flopped · or keep typing`));
+      showInlineTip((tip) => tip.id === 'capture-intent');
       return true;
     } catch (err) {
       turnInFlight = false;
@@ -719,6 +804,7 @@ async function main() {
         completionTokens: result.completionTokens,
         accessToken: config.supabaseAccessToken,
       });
+      showInlineTip((tip) => tip.id === 'capture-intent');
       return true;
     } catch (err) {
       turnInFlight = false;
@@ -1040,6 +1126,16 @@ async function main() {
     // Any typed input supersedes a pending "did you mean" offer.
     if (pendingDidYouMean) pendingDidYouMean = null;
 
+    // Exact bare words are front-door controls too. Keep this exact-match only:
+    // "help" opens help; "help me build X" still routes as natural language.
+    if (!input.startsWith('/')) {
+      const bare = input.trim().toLowerCase();
+      if (BARE_COMMANDS[bare]) {
+        await handleInput(BARE_COMMANDS[bare]);
+        return;
+      }
+    }
+
     // A bare number right after a route failure picks the fallback
     if (awaitingFallback) {
       const af = awaitingFallback;
@@ -1565,15 +1661,14 @@ async function main() {
       }
 
       if (cmd === 'clarify') {
-        if (!config?.apiKey) {
-          console.log(`\n  ${ember('!')} ${sage('No API key. Run /key to set one.')}\n`);
-          rl.prompt();
-          return;
-        }
         try {
-          const { execSync } = require('child_process');
-          const args = cmdArg ? `--text "${cmdArg.replace(/"/g, '\\"')}"` : '';
-          execSync(`node ${path.join(__dirname, 'clarify.js')} ${args}`, { stdio: 'inherit' });
+          const { spawnSync } = require('child_process');
+          const args = ['clarify'];
+          if (cmdArg) args.push('--text', cmdArg);
+          const res = spawnSync(process.execPath, [path.join(__dirname, '..', 'bin', 'phewsh.js'), ...args], { stdio: 'inherit' });
+          if (res.status !== 0) {
+            console.error(`  ${ember('!')} ${sage('Clarify exited without writing context.')}`);
+          }
           intentFiles = loadIntentContext();
           systemPrompt = buildSystemPrompt(intentFiles);
           if (intentFiles.length > 0) {
@@ -2092,7 +2187,7 @@ async function main() {
           }
           if (!h.installed) continue; // hide the long tail of uninstalled extras
           const via = h.headless ? '' : ' · /work only';
-          rows.push([h.label, `ready — ${h.role}${via}`, 'green']);
+          rows.push([h.label, `ready — ${h.bestFor || h.role}${via}`, 'green']);
         }
         rows.push(['API key', config?.apiKey ? config.apiKey.slice(0, 8) + '... (' + (config.provider || 'anthropic') + ')' : 'not set — optional', config?.apiKey ? 'green' : 'yellow']);
         rows.push(['Fallback', (config?.fallback === 'auto' ? 'auto-switch on failure' : 'ask before switching') + ' — /fallback to change', 'peach']);
@@ -2184,7 +2279,7 @@ async function main() {
           const mode = h.headless ? '' : slate(' · /work only');
           const badge = hStats ? learning.keptBadge(hStats, h.id) : '';
           const rec = badge ? ` ${slate('· ' + badge)}` : '';
-          console.log(`    ${dot} ${cream(h.id.padEnd(11))} ${sage((h.role || h.label).padEnd(20))} ${slate(h.label)}${mode}${rec}${active}`);
+          console.log(`    ${dot} ${cream(h.id.padEnd(11))} ${sage((h.bestFor || h.role || h.label).padEnd(38))} ${slate(h.label)}${mode}${rec}${active}`);
         }
         ui.divider('line');
         const learned = hStats ? learning.learningLine(hStats) : null;
@@ -2289,7 +2384,16 @@ async function main() {
           return;
         }
         if (!harnesses.find(x => x.id === target)?.installed) {
-          console.log(`  ${ember('!')} ${sage(h.label + ' is not installed on this machine.')}`);
+          const how = INSTALL[target];
+          console.log('');
+          console.log(`  ${ember('!')} ${sage(h.label + ' isn\'t installed on this machine yet.')}`);
+          if (how) {
+            const isCmd = !how.startsWith('see ');
+            console.log(`  ${sage('Install:')}  ${isCmd ? cream(how) : slate(how)}`);
+          }
+          if (h.auth) console.log(`  ${sage('Sign in:')}  ${slate(h.auth + ' (the tool prompts you on first run)')}`);
+          console.log(`  ${sage('Then run:')} ${cream('phewsh ' + target)} ${slate('— phewsh briefs it and hands off')}`);
+          console.log('');
           rl.prompt();
           return;
         }
@@ -2297,9 +2401,13 @@ async function main() {
         const preflightTruth = await auditTruth();
         const before = captureSnapshot(preflightTruth);
         const generatedBrief = await generateBrief({ report: preflightTruth });
-        const launchBrief = `${generatedBrief.content}\n\nThis is a PHEWSH transition briefing. Use it as project context, preserve native tool behavior, and verify claims against the repository before acting. When you finish, exit this tool — PHEWSH resumes, runs an automatic postflight comparing what changed against this brief, and offers reconciliation.`;
+        const launchBrief = `${generatedBrief.content}\n\nYou are receiving a PHEWSH handoff brief — acknowledge in one short line that you've loaded it, then proceed. Use it as project context, preserve native tool behavior, and verify claims against the repository before acting. When you finish, exit this tool — PHEWSH resumes, runs an automatic postflight comparing what changed against this brief, and offers reconciliation.`;
         const savedBrief = persistBrief(generatedBrief.content, { project: projectName, route: target });
         const launch = interactiveLaunchArgs(target, launchBrief, { model: harnessModel });
+        // Foolproof fallback: the brief on the clipboard survives the native
+        // tool taking over the terminal and any trust/permission gate. If the
+        // tool ignores or never received it, the human just pastes it in.
+        const briefOnClipboard = copyToClipboard(launchBrief);
         const decisionId = recordDecision({
           project: projectName,
           route: target,
@@ -2313,8 +2421,13 @@ async function main() {
         console.log(`  ${sage('Route:')} ${cream(h.label)}${harnessModel ? slate(' · model ' + harnessModel) : slate(' · native default model')}`);
         console.log(`  ${sage('Git:')} ${cream(preflightTruth.git.shortHead || 'unknown')} ${slate('· ' + before.dirty.length + ' uncommitted path(s) before work')}`);
         console.log(`  ${sage('Truth:')} ${preflightTruth.conflicts.length ? peach(preflightTruth.conflicts.length + ' conflict(s) carried explicitly') : green('no explicit conflicts')}`);
-        console.log(`  ${sage('Brief:')} ${launch.briefingPassed ? green('passed directly to the native harness') : peach('not injectable for this harness; available via /brief')}`);
-        console.log(`  ${sage('Record:')} ${savedBrief.written ? slate('exact briefing saved locally for this transition') : peach('briefing persistence unavailable; launch continues')}`);
+        console.log(`  ${sage('Brief:')} ${launch.briefingPassed ? green('auto-attached to ' + h.label) : peach('not auto-injectable for this tool')}${briefOnClipboard ? slate(' · copied to your clipboard') : ''}`);
+        console.log(`  ${sage('Record:')} ${savedBrief.written ? slate('exact briefing saved locally' + (savedBrief.file ? ' → ' + savedBrief.file : '')) : peach('briefing persistence unavailable; launch continues')}`);
+        if (briefOnClipboard) {
+          console.log(`  ${slate('Foolproof:')} ${sage('if ' + h.label + ' shows a trust prompt or doesn\'t mention the brief, just paste it in')} ${slate('(⌘V / Ctrl+V)')}`);
+        } else if (savedBrief.file) {
+          console.log(`  ${slate('Foolproof:')} ${sage('if ' + h.label + ' doesn\'t pick up the brief, paste from')} ${cream(savedBrief.file)}`);
+        }
         console.log(`  ${slate('After exit PHEWSH will compare Git, files, intent claims, generated drift, and contradictions.')}`);
         ui.divider('line');
         console.log(`  ${teal('●')} ${sage('Handing the terminal to')} ${cream(h.label)} ${slate('— exit to return for postflight')}`);
@@ -2420,8 +2533,10 @@ async function main() {
     // Regular input → route it (harness = your subscription, api = your key)
     if (!route) {
       console.log('');
-      console.log(`  ${sage('No route yet —')} ${cream('/key')} ${sage('to set an API key, or install Claude Code / Codex')}`);
-      console.log(`  ${slate('phewsh uses installed agent CLIs automatically, no key needed.')}`);
+      console.log(`  ${sage('That request is valid — phewsh just needs an AI worker behind the door.')}`);
+      console.log(`  ${cream('phewsh setup')} ${sage('detects installed tools and picks a route')}`);
+      console.log(`  ${cream('/key')} ${sage('adds an API key, or install Claude Code / Codex / Gemini and rerun phewsh')}`);
+      console.log(`  ${slate('Once a route exists, plain typing works; no slash command needed.')}`);
       console.log('');
       rl.prompt();
       return;
@@ -2452,6 +2567,8 @@ async function main() {
       return;
     }
 
+    showRouteCoach(input);
+
     const ok = route.type === 'harness'
       ? await runHarnessTurn(input, route.id, fullSystem)
       : await runApiTurn(input, fullSystem);
@@ -2490,6 +2607,14 @@ async function main() {
     console.log(`\n  ${sage('session ended')}\n`);
     process.exit(0);
   });
+
+  // Doorway shortcut: `phewsh <harness>` sets PHEWSH_AUTOWORK so we drop the
+  // user straight into /work for that tool after the front door renders.
+  const autoWork = process.env.PHEWSH_AUTOWORK;
+  if (autoWork && HARNESSES[autoWork]) {
+    delete process.env.PHEWSH_AUTOWORK;
+    handleInput('/work ' + autoWork).catch(() => {});
+  }
 }
 
 main().catch(err => {

package/commands/setup.js

@@ -47,7 +47,8 @@ module.exports = async function setup() {
   for (const h of harnesses) {
     const status = h.installed ? green('✓ installed') : slate('✗ not installed');
     const mode = h.headless ? '' : slate(' · interactive — /work ' + h.id);
-    console.log(`    ${cream(h.label.padEnd(14))} ${status}  ${slate('(' + h.auth + ')')}${mode}`);
+    const fit = h.bestFor ? slate(' · best for ' + h.bestFor) : '';
+    console.log(`    ${cream(h.label.padEnd(14))} ${status}  ${slate('(' + h.auth + ')')}${mode}${fit}`);
   }
   if (installed.length === 0) {
     console.log('');
@@ -95,7 +96,7 @@ module.exports = async function setup() {
   // ── 2. Pick the default route ─────────────────────────
   // Interactive-only harnesses (Hermes, Pi) can't take chat routing — they
   // stay reachable via /work in a session, so they're not default options.
-  const options = chatCapable.map(h => ({ kind: 'harness', id: h.id, label: `${h.label} — your ${h.auth.split(' / ')[0].toLowerCase()}, no API key` }));
+  const options = chatCapable.map(h => ({ kind: 'harness', id: h.id, label: `${h.label} — ${h.bestFor || h.role}; your ${h.auth.split(' / ')[0].toLowerCase()}, no API key` }));
   options.push({ kind: 'api', id: 'api', label: 'Direct API — bring your own Anthropic/OpenRouter key' });
 
   console.log(`  ${b(cream('Where should phewsh route your work by default?'))}`);

package/lib/harnesses.js

@@ -20,20 +20,41 @@ const { execSync, spawn } = require('child_process');
 // list of its own, so it can never go stale. Harnesses without a known
 // model flag ignore the preference and use their own config.
 const HARNESSES = {
-  'claude-code': { bin: 'claude',       label: 'Claude Code',  role: 'writes code',          auth: 'Claude subscription / Console', models: true, modelHints: ['sonnet', 'opus', 'haiku'], streamFormat: 'claude-json', args: (p, m) => ['-p', p, '--output-format', 'stream-json', '--include-partial-messages', '--verbose', ...(m ? ['--model', m] : [])], interactiveArgs: (brief, m) => ['--append-system-prompt', brief, ...(m ? ['--model', m] : [])] },
-  'codex':       { bin: 'codex',        label: 'Codex CLI',    role: 'reasons & reviews',    auth: 'ChatGPT plan',                  models: true, args: (p, m) => ['exec', '--skip-git-repo-check', ...(m ? ['-m', m] : []), p], interactiveArgs: (brief, m) => [...(m ? ['-m', m] : []), brief] },
-  'gemini':      { bin: 'gemini',       label: 'Gemini CLI',   role: "another model's take", auth: 'Google login',                  models: true, args: (p, m) => ['-p', p, ...(m ? ['-m', m] : [])], interactiveArgs: (brief, m) => ['--prompt-interactive', brief, ...(m ? ['--model', m] : [])] },
-  'cursor':      { bin: 'cursor-agent', label: 'Cursor Agent', role: 'edits files',          auth: 'Cursor account',                models: true, args: (p, m) => ['-p', p, '--output-format', 'text', ...(m ? ['--model', m] : [])] },
-  'opencode':    { bin: 'opencode',     label: 'OpenCode',     role: 'general agent',        auth: 'OpenCode Zen / configured',     args: (p) => ['run', p], interactiveArgs: (brief) => ['--prompt', brief] },
-  'grok':        { bin: 'grok',         label: 'Grok Build',   role: "xAI's take",           auth: 'SuperGrok / X Premium+',        args: (p) => ['-p', p] },
-  'kiro':        { bin: 'kiro-cli',     label: 'Kiro CLI',     role: 'spec-driven dev',      auth: 'Kiro / AWS account',            args: (p) => ['chat', '--no-interactive', p] },
-  'copilot':     { bin: 'copilot',      label: 'Copilot CLI',  role: 'github-native',        auth: 'GitHub Copilot plan',           args: (p) => ['-p', p] },
-  'hermes':      { bin: 'hermes',       label: 'Hermes',       role: 'runs loops',           auth: 'Nous account',                  args: null },
-  'pi':          { bin: 'pi',           label: 'Pi',           role: 'conversation',         auth: 'Pi login',                      args: null },
-  'aider':       { bin: 'aider',        label: 'Aider',        role: 'pair-codes',           auth: 'configured keys',               models: true, args: (p, m) => ['--message', p, ...(m ? ['--model', m] : [])] },
-  'goose':       { bin: 'goose',        label: 'Goose',        role: 'automates tasks',      auth: 'Block / configured',            args: (p) => ['run', '-t', p] },
-  'amp':         { bin: 'amp',          label: 'Amp',          role: 'agentic coding',       auth: 'Sourcegraph account',           args: (p) => ['-x', p] },
-  'droid':       { bin: 'droid',        label: 'Droid',        role: 'agentic coding',       auth: 'Factory account',               args: (p) => ['exec', p] },
+  'claude-code': { bin: 'claude',       label: 'Claude Code',  role: 'writes code',          bestFor: 'repo edits, tests, native coding loops',     auth: 'Claude subscription / Console', models: true, modelHints: ['sonnet', 'opus', 'haiku'], streamFormat: 'claude-json', args: (p, m) => ['-p', p, '--output-format', 'stream-json', '--include-partial-messages', '--verbose', ...(m ? ['--model', m] : [])], interactiveArgs: (brief, m) => ['--append-system-prompt', brief, ...(m ? ['--model', m] : [])] },
+  'codex':       { bin: 'codex',        label: 'Codex CLI',    role: 'reasons & reviews',    bestFor: 'reviews, reasoning, second opinions',       auth: 'ChatGPT plan',                  models: true, args: (p, m) => ['exec', '--skip-git-repo-check', ...(m ? ['-m', m] : []), p], interactiveArgs: (brief, m) => [...(m ? ['-m', m] : []), brief] },
+  'gemini':      { bin: 'gemini',       label: 'Gemini CLI',   role: "another model's take", bestFor: 'broad scans, alternate framing',              auth: 'Google login',                  models: true, args: (p, m) => ['-p', p, ...(m ? ['-m', m] : [])], interactiveArgs: (brief, m) => ['--prompt-interactive', brief, ...(m ? ['--model', m] : [])] },
+  'cursor':      { bin: 'cursor-agent', label: 'Cursor Agent', role: 'edits files',          bestFor: 'editor-side file edits',                    auth: 'Cursor account',                models: true, args: (p, m) => ['-p', p, '--output-format', 'text', ...(m ? ['--model', m] : [])] },
+  'opencode':    { bin: 'opencode',     label: 'OpenCode',     role: 'general agent',        bestFor: 'open-source agent work',                    auth: 'OpenCode Zen / configured',     args: (p) => ['run', p], interactiveArgs: (brief) => ['--prompt', brief] },
+  'grok':        { bin: 'grok',         label: 'Grok Build',   role: "xAI's take",           bestFor: 'outside take from xAI',                     auth: 'SuperGrok / X Premium+',        args: (p) => ['-p', p] },
+  'kiro':        { bin: 'kiro-cli',     label: 'Kiro CLI',     role: 'spec-driven dev',      bestFor: 'spec-driven development',                   auth: 'Kiro / AWS account',            args: (p) => ['chat', '--no-interactive', p] },
+  'copilot':     { bin: 'copilot',      label: 'Copilot CLI',  role: 'github-native',        bestFor: 'GitHub-native tasks',                      auth: 'GitHub Copilot plan',           args: (p) => ['-p', p] },
+  'hermes':      { bin: 'hermes',       label: 'Hermes',       role: 'runs loops',           bestFor: 'orchestration and continuity',              auth: 'Nous account',                  args: null },
+  'pi':          { bin: 'pi',           label: 'Pi',           role: 'conversation',         bestFor: 'conversation',                             auth: 'Pi login',                      args: null },
+  'aider':       { bin: 'aider',        label: 'Aider',        role: 'pair-codes',           bestFor: 'pair-programming patches',                  auth: 'configured keys',               models: true, args: (p, m) => ['--message', p, ...(m ? ['--model', m] : [])] },
+  'goose':       { bin: 'goose',        label: 'Goose',        role: 'automates tasks',      bestFor: 'automation runs',                          auth: 'Block / configured',            args: (p) => ['run', '-t', p] },
+  'amp':         { bin: 'amp',          label: 'Amp',          role: 'agentic coding',       bestFor: 'agentic coding',                           auth: 'Sourcegraph account',           args: (p) => ['-x', p] },
+  'droid':       { bin: 'droid',        label: 'Droid',        role: 'agentic coding',       bestFor: 'agentic coding',                           auth: 'Factory account',               args: (p) => ['exec', p] },
+};
+
+// Best-effort install hints, shown when a harness isn't on the machine yet.
+// Commands where the install path is well-known and stable; a docs pointer
+// otherwise. We never auto-run these — phewsh shows them; the human decides.
+// (Install paths and auth change upstream; treat as a guidepost, not gospel.)
+const INSTALL = {
+  'claude-code': 'npm i -g @anthropic-ai/claude-code',
+  'codex':       'npm i -g @openai/codex',
+  'gemini':      'npm i -g @google/gemini-cli',
+  'cursor':      'curl https://cursor.com/install -fsS | bash',
+  'opencode':    'npm i -g opencode-ai',
+  'grok':        'npm i -g @vibe-kit/grok-cli',
+  'copilot':     'npm i -g @github/copilot',
+  'kiro':        'see kiro.dev/downloads',
+  'hermes':      'see nousresearch.com',
+  'pi':          'see pi.ai',
+  'aider':       'python -m pip install aider-chat',
+  'goose':       'see block.github.io/goose',
+  'amp':         'npm i -g @sourcegraph/amp',
+  'droid':       'see factory.ai',
 };
 
 // In-flight harness children — so ESC in the session can cancel a turn.
@@ -199,6 +220,7 @@ function runViaHarness(id, systemPrompt, userPrompt, opts = {}) {
 
 module.exports = {
   HARNESSES,
+  INSTALL,
   isInstalled,
   detectInstalled,
   interactiveLaunchArgs,

package/lib/intro.js

@@ -83,7 +83,7 @@ async function playIntro(opts = {}) {
     out(`  ${slate('· none found yet — install Claude Code, Codex, or Gemini and phewsh picks it up.')}`);
   } else {
     for (const h of harnesses) {
-      out(`    ${green('✓')} ${cream(h.label.padEnd(14))} ${sage(h.role || '')}`);
+      out(`    ${green('✓')} ${cream(h.label.padEnd(14))} ${sage(h.bestFor || h.role || '')}`);
       await pause(130);
     }
     await pause(160);
@@ -93,7 +93,11 @@ async function playIntro(opts = {}) {
   }
   out('');
   await pause(160);
-  out(`  ${sage('Next:')} ${cream('just type to start')} ${slate('·')} ${cream('phewsh setup')} ${slate('to pick a default route')}`);
+  if (harnesses.length > 0) {
+    out(`  ${sage('Next:')} ${cream('just type to start')} ${slate('·')} ${cream('phewsh setup')} ${slate('to pick a default route')}`);
+  } else {
+    out(`  ${sage('Next:')} ${cream('phewsh setup')} ${slate('after installing Claude Code, Codex, or Gemini')}`);
+  }
   out('');
 
   return { toolsFound: harnesses.length };

package/lib/route-coach.js

@@ -0,0 +1,91 @@
+// Route coach — tiny deterministic hints for the front door.
+//
+// PHEWSH should not become a new agent. It should notice when the user's
+// message is better served by a native harness, a second opinion, or a council
+// and point to that door without blocking the current turn.
+
+const CODE_RE = /\b(implement|edit|change|patch|fix|debug|bug|refactor|test|tests|failing|failure|build|ship|commit|diff|file|code|function|module|schema|migration|auth|deploy|npm|lint)\b/i;
+const STRONG_CODE_RE = /\b(implement|edit|change|patch|fix|debug|refactor|failing|failure|commit|schema|migration|auth|deploy|lint)\b/i;
+const REVIEW_RE = /\b(review|audit|critique|risk|risks|regression|security|edge case|edge cases|sanity check)\b/i;
+const COMPARE_RE = /\b(compare|options|which|tradeoff|trade-off|pros and cons|brainstorm|strategy|what should i do|where should i start|best approach|decide)\b/i;
+const INTENT_RE = /\b(i want to build|idea|project|startup|app|tool|product|trying to build|what i'm building|what i am building)\b/i;
+
+function routeId(route) {
+  if (!route) return null;
+  if (typeof route === 'string') return route;
+  return route.id || route.type || null;
+}
+
+function installed(harnesses, id) {
+  return (harnesses || []).find((h) => h.id === id && h.installed);
+}
+
+function headless(harnesses) {
+  return (harnesses || []).filter((h) => h.installed && h.headless);
+}
+
+function firstInstalled(harnesses, ids) {
+  return ids.map((id) => installed(harnesses, id)).find(Boolean) || null;
+}
+
+function canInjectBrief(h) {
+  return !!h && typeof h.interactiveArgs === 'function';
+}
+
+function routeCoach(input, {
+  route = null,
+  harnesses = [],
+  hasIntentDir = false,
+  turnsThisSession = 0,
+} = {}) {
+  const text = String(input || '').trim();
+  if (!text || text.startsWith('/') || text.startsWith('@')) return null;
+
+  const current = routeId(route);
+  const codeish = CODE_RE.test(text);
+  const strongCode = STRONG_CODE_RE.test(text);
+  const reviewish = REVIEW_RE.test(text);
+  const compareish = COMPARE_RE.test(text);
+
+  if (!hasIntentDir && turnsThisSession === 0 && INTENT_RE.test(text) && text.length >= 40) {
+    return {
+      id: 'clarify-first',
+      command: '/clarify',
+      message: 'This sounds like raw project intent; clarify turns it into memory every tool can share.',
+    };
+  }
+
+  if (codeish && (strongCode || text.length >= 80)) {
+    const target = firstInstalled(harnesses, ['claude-code', 'opencode', 'codex', 'gemini']);
+    if (canInjectBrief(target)) {
+      return {
+        id: `native-work:${target.id}`,
+        command: `/work ${target.id}`,
+        message: `${target.label} native mode is the better door for repo changes; phewsh will verify before and after.`,
+      };
+    }
+  }
+
+  if (reviewish && !strongCode) {
+    const codex = installed(harnesses, 'codex');
+    if (codex && current !== 'codex') {
+      return {
+        id: 'review-with-codex',
+        command: '@codex <same ask>',
+        message: 'For review, use a second model without switching the whole session.',
+      };
+    }
+  }
+
+  if (compareish && headless(harnesses).length >= 2) {
+    return {
+      id: 'ask-council',
+      command: '/council <same ask>',
+      message: 'This is a judgment call; ask every installed tool and keep the best answer.',
+    };
+  }
+
+  return null;
+}
+
+module.exports = { routeCoach };

package/lib/suggest.js

@@ -46,11 +46,12 @@ function suggestAll(s = {}) {
 
   // 1. Working without captured intent — the biggest miss. Every AI tool here
   //    could be reading the same goal; right now none are.
-  if (intentFileCount === 0 && turnsThisSession >= 2) {
+  if (intentFileCount === 0 && turnsThisSession >= 1) {
+    const noun = turnsThisSession === 1 ? 'message' : 'messages';
     out.push({
       id: 'capture-intent',
       priority: 100,
-      message: `${turnsThisSession} messages in, no captured intent — every AI here is guessing.`,
+      message: `${turnsThisSession} ${noun} in, no captured intent — every AI here is guessing.`,
       command: '/clarify',
       why: 'Turns what you just said into a spec every tool (this one, Claude Code, Codex) reads.',
     });

package/lib/ui.js

@@ -98,7 +98,16 @@ async function brandReveal(fast = false) {
   console.log(`  ${b(cream('█▀█ █░█ █▀▀ █░█ █▀ █░█'))}`);
   console.log(`  ${b(cream('█▀▀ █▀█ ██▄ ▀▄▀ ▄█ █▀█'))}`);
   await pause(160);
-  console.log(`  ${sage(".intent/ is your project's working memory.")}`);
+  // The value prop, plain language, off the bat — the approved north-star line.
+  // It exhales in (typewriter) when animated; lands instantly otherwise. Safe:
+  // the color wrapper is emitted up front, so only the words reveal.
+  const tagline = 'Stop re-explaining yourself to AI.';
+  if (fast || !process.stdout.isTTY) {
+    console.log(`  ${sage(tagline)}`);
+  } else {
+    process.stdout.write('  ');
+    await typewrite(sage(tagline), 20);
+  }
   console.log('');
 }
 

package/package.json

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