phewsh 0.11.10 → 0.11.11

package/bin/phewsh.js

@@ -8,6 +8,8 @@ const b  = (s) => `\x1b[1m${s}\x1b[0m`;   // bold
 const d  = (s) => `\x1b[2m${s}\x1b[0m`;   // dim
 const w  = (s) => `\x1b[97m${s}\x1b[0m`;  // bright white
 const g  = (s) => `\x1b[90m${s}\x1b[0m`;  // dark gray
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
 
 function showBrand() {
   const fs = require('fs');
@@ -15,24 +17,32 @@ function showBrand() {
   const os = require('os');
   const hasIntent = fs.existsSync(path.join(process.cwd(), '.intent', 'vision.md'));
   const configPath = path.join(os.homedir(), '.phewsh', 'config.json');
-  let hint = g('  run "phewsh intent --init" to start');
-  if (hasIntent) {
-    hint = g('  .intent/ loaded  ·  run "phewsh ai run \\"...\\"" to execute');
-  } else {
-    try {
-      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-      if (config?.email) hint = g(`  logged in as ${config.email}  ·  run "phewsh intent --init" to start`);
-    } catch { /* no config */ }
-  }
+  let hasKey = false;
+  let email = null;
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    hasKey = !!config?.apiKey;
+    email = config?.email;
+  } catch { /* no config */ }
 
   console.log('');
   console.log(`  ${d('😮\u200d💨')} ${d('🤫')}`);
   console.log('');
   console.log(`  ${b(w('█▀█ █░█ █▀▀ █░█ █▀ █░█'))}`);
   console.log(`  ${b(w('█▀▀ █▀█ ██▄ ▀▄▀ ▄█ █▀█'))}`);
-  console.log(`  ${g('Build with clarity. Execute without drift.')}`);
+  console.log(`  ${g('Your project identity for every AI tool.')}`);
   console.log('');
-  console.log(hint);
+
+  // Context-aware hint
+  if (!hasKey) {
+    console.log(`  ${g('Get started:')} ${w('phewsh')}  ${g('(guided setup, takes 60 seconds)')}`);
+  } else if (hasIntent) {
+    console.log(`  ${green('●')} .intent/ loaded  ${g('·')}  ${w('phewsh')} ${g('to chat ·')} ${w('phewsh watch')} ${g('to sync')}`);
+  } else if (email) {
+    console.log(`  ${g('logged in as')} ${email}  ${g('·')}  ${w('phewsh')} ${g('to start')}`);
+  } else {
+    console.log(`  ${g('Ready.')} ${w('phewsh')} ${g('to start a session.')}`);
+  }
   console.log('');
 }
 
@@ -64,33 +74,38 @@ function showVersion() {
 function showHelp() {
   const pkg = require('../package.json');
   showBrand();
-  console.log(`  ${g('v' + pkg.version)}  ·  ${g('phewsh.com')}\n`);
-  console.log(`  ${b('Just type')} ${w('phewsh')} ${b('to start a session.')}`);
-  console.log(`  ${g('Opens a persistent AI shell with your .intent/ context injected.')}`);
+  console.log(`  ${g('v' + pkg.version)}  ·  ${g('phewsh.com/cli')}\n`);
+  console.log(`  ${g('─'.repeat(48))}`);
+  console.log(`  ${b('Just type')} ${w('phewsh')} ${b('to start.')} ${g('Everything else is optional.')}`);
+  console.log(`  ${g('─'.repeat(48))}`);
+  console.log('');
+  console.log(`  ${b(w('start here'))}`);
+  console.log(`    ${cyan('phewsh')}          Open AI session — type naturally, get guided`);
+  console.log(`    ${cyan('phewsh clarify')}   Turn a messy idea into a structured spec`);
+  console.log(`    ${cyan('phewsh login')}     Set up identity + API key`);
+  console.log('');
+  console.log(`  ${b(w('project'))}`);
+  console.log(`    ${cyan('intent')}    ${g('Manage .intent/ artifacts — status, open, evolve')}`);
+  console.log(`    ${cyan('gate')}      ${g('Declare constraints (budget, time, skill, urgency)')}`);
+  console.log(`    ${cyan('context')}   ${g('Export portable context for any AI tool')}`);
+  console.log(`    ${cyan('ai')}        ${g('One-shot AI prompt with .intent/ context')}`);
+  console.log('');
+  console.log(`  ${b(w('sync'))}`);
+  console.log(`    ${cyan('push')}      ${g('Push .intent/ to cloud')}`);
+  console.log(`    ${cyan('pull')}      ${g('Pull from cloud to .intent/')}`);
+  console.log(`    ${cyan('watch')}     ${g('Live sync — CLAUDE.md + web dashboard auto-update')}`);
+  console.log(`    ${cyan('serve')}     ${g('Execution bridge for the web app')}`);
+  console.log('');
+  console.log(`  ${b(w('connect'))}`);
+  console.log(`    ${cyan('mcp')}       ${g('Connect AI agents via MCP protocol')}`);
+  console.log(`    ${cyan('link')}      ${g('Link local .intent/ to cloud project')}`);
   console.log('');
-  console.log(`  ${b('Commands')}`);
-  console.log(`    ${w('(bare)')}    Open persistent AI session — just type naturally`);
-  console.log(`    ${w('clarify')}   Turn messy intent into a structured project spec`);
-  console.log(`    ${w('push')}      Push local .intent/ to cloud`);
-  console.log(`    ${w('pull')}      Pull project from cloud to .intent/`);
-  console.log(`    ${w('link')}      Link local .intent/ to a cloud project`);
-  console.log(`    ${w('intent')}    Manage .intent/ artifacts — status, open, evolve`);
-  console.log(`    ${w('ai')}        One-shot AI prompt (reads .intent/)`);
-  console.log(`    ${w('gate')}      Declare operational constraints (budget, time, skill)`);
-  console.log(`    ${w('context')}   Export portable context for any AI tool`);
-  console.log(`    ${w('login')}     Set up identity, API key, and cloud sync`);
-  console.log(`    ${w('watch')}     Live sync — .intent/ changes push to cloud + CLAUDE.md`);
-  console.log(`    ${w('serve')}     Start live execution bridge for the web app`);
-  console.log(`    ${w('mcp')}       Connect AI agents — setup, sync, status`);
-  console.log(`    ${w('sap')}       Sustainable AI Protocol — usage and accountability`);
-  console.log(`    ${w('style')}     Build your style identity — ingest, profile, sync`);
-  console.log(`    ${w('mbhd')}      MBHD music engine`);
+  console.log(`  ${b(w('more'))}`);
+  console.log(`    ${cyan('sap')}       ${g('Sustainable AI Protocol — usage tracking')}`);
+  console.log(`    ${cyan('style')}     ${g('Style identity — ingest, profile, sync')}`);
+  console.log(`    ${cyan('mbhd')}      ${g('MBHD music engine')}`);
   console.log('');
-  console.log(`  ${b('Quick start')}`);
-  console.log(`    ${g('phewsh login')}                          Set up identity + API key`);
-  console.log(`    ${g('phewsh')}                                Open AI session (with .intent/ context)`);
-  console.log(`    ${g('phewsh clarify')}                        Compile messy intent → structured spec`);
-  console.log(`    ${g('phewsh ai run "what\'s next?"')}         One-shot prompt`);
+  console.log(`  ${g('Works standalone · Inside Claude Code · Inside Cursor · With any MCP agent')}`);
   console.log('');
 }
 

package/commands/session.js

@@ -7,6 +7,7 @@ const path = require('path');
 const os = require('os');
 const readline = require('readline');
 const { trackSap } = require('../lib/supabase');
+const ui = require('../lib/ui');
 
 const CONFIG_DIR = path.join(os.homedir(), '.phewsh');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
@@ -16,13 +17,7 @@ const { select, refreshSession: refreshSess } = require('../lib/supabase');
 const { readPPS } = require('../lib/pps');
 const { push, pull, ensureValidToken } = require('./sync');
 
-const b = (s) => `\x1b[1m${s}\x1b[0m`;
-const d = (s) => `\x1b[2m${s}\x1b[0m`;
-const w = (s) => `\x1b[97m${s}\x1b[0m`;
-const g = (s) => `\x1b[90m${s}\x1b[0m`;
-const green = (s) => `\x1b[32m${s}\x1b[0m`;
-const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
-const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const { b, d, w, g, green, cyan, yellow } = ui;
 
 // Sync awareness: compare local .intent/ timestamps with cloud updated_at
 async function checkSyncStatus(config) {
@@ -145,6 +140,9 @@ async function streamChat(apiKey, messages, systemPrompt, modelId) {
   const body = { model: modelId, max_tokens: 2048, messages, stream: true };
   if (systemPrompt) body.system = systemPrompt;
 
+  // Start spinner while waiting for first token
+  const spin = ui.spinner('thinking');
+
   const response = await fetch('https://api.anthropic.com/v1/messages', {
     method: 'POST',
     headers: {
@@ -156,6 +154,7 @@ async function streamChat(apiKey, messages, systemPrompt, modelId) {
   });
 
   if (!response.ok) {
+    spin.stop();
     const err = await response.json().catch(() => ({}));
     const msg = err.error?.message || `API error ${response.status}`;
     if (response.status === 401 || msg.includes('invalid')) {
@@ -167,6 +166,7 @@ async function streamChat(apiKey, messages, systemPrompt, modelId) {
   let fullResponse = '';
   let promptTokens = null;
   let completionTokens = null;
+  let firstToken = true;
 
   for await (const chunk of response.body) {
     const text = Buffer.from(chunk).toString('utf-8');
@@ -177,6 +177,10 @@ async function streamChat(apiKey, messages, systemPrompt, modelId) {
       try {
         const parsed = JSON.parse(data);
         if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+          if (firstToken) {
+            spin.stop(); // Clear spinner before first output
+            firstToken = false;
+          }
           process.stdout.write(parsed.delta.text);
           fullResponse += parsed.delta.text;
         }
@@ -190,6 +194,7 @@ async function streamChat(apiKey, messages, systemPrompt, modelId) {
     }
   }
 
+  if (firstToken) spin.stop(); // In case we got no tokens
   process.stdout.write('\n');
 
   return { content: fullResponse, promptTokens, completionTokens, model: modelId };
@@ -205,14 +210,10 @@ async function main() {
   let totalPromptTokens = 0;
   let totalCompletionTokens = 0;
 
-  // Session banner with PHEWSH branding
-  console.log('');
-  console.log(`  ${d('😮‍💨')} ${d('🤫')}`);
-  console.log('');
-  console.log(`  ${b(w('█▀█ █░█ █▀▀ █░█ █▀ █░█'))}`);
-  console.log(`  ${b(w('█▀▀ █▀█ ██▄ ▀▄▀ ▄█ █▀█'))}`);
-  console.log('');
+  // ── Animated brand reveal ──────────────────────────────
+  await ui.brandReveal();
 
+  // ── First-run welcome or status panel ──────────────────
   if (!config?.apiKey) {
     console.log(`  ${b(w('Welcome to PHEWSH.'))}`);
     console.log(`  ${g('Your AI knows your project. No more re-explaining.')}`);
@@ -230,6 +231,7 @@ async function main() {
     console.log('');
     console.log(`  ${g('Got a key? Type')} /key ${g('to paste it in.')}`);
     console.log(`  ${g('Want cloud sync too?')} /login ${g('connects your identity.')}`);
+    console.log(`  ${g('Curious?')} /tour ${g('to see what PHEWSH can do (no key needed).')}`);
     console.log('');
   } else if (!config.apiKey.startsWith('sk-')) {
     console.log(`  ${yellow('!')} Stored API key looks invalid.`);
@@ -238,6 +240,7 @@ async function main() {
     config.apiKey = null; // Don't try to use a bad key
   }
 
+  // ── Project status ─────────────────────────────────────
   if (intentFiles.length > 0) {
     console.log(`  ${green('●')} ${cyan(projectName)} ${g('·')} ${intentFiles.map(f => f.file).join(', ')}`);
   } else {
@@ -249,6 +252,9 @@ async function main() {
     console.log(`  ${g('  user:')} ${config.email}`);
   }
 
+  // ── Interop line ───────────────────────────────────────
+  ui.interopLine(config, intentFiles);
+
   // Sync status check (non-blocking, 3s timeout)
   if (config?.supabaseUserId && intentFiles.length > 0) {
     const syncResult = await Promise.race([
@@ -269,17 +275,20 @@ async function main() {
   }
 
   console.log('');
+  ui.divider('─');
   if (!config?.apiKey) {
-    console.log(`  ${g('type')} /key ${g('to get started · /help for all commands · /quit to exit')}`);
+    console.log(`  ${g('type')} /key ${g('to get started ·')} /tour ${g('to explore ·')} /help ${g('for all commands')}`);
   } else {
+    console.log(`  ${ui.randomTip()}`);
     console.log(`  ${g('type naturally · /help for commands · /quit to exit')}`);
   }
+  ui.divider('─');
   console.log('');
 
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
-    prompt: `  ${green('>')} `,
+    prompt: `  ${cyan('phewsh')} ${green('>')} `,
     historySize: 100,
   });
 
@@ -301,48 +310,77 @@ async function main() {
 
       if (cmd === 'quit' || cmd === 'exit' || cmd === 'q') {
         const turns = messages.length / 2;
-        console.log(`\n  ${g('Session ended · ' + turns + ' exchanges · ' + (totalPromptTokens + totalCompletionTokens) + ' tokens')}\n`);
+        console.log('');
+        ui.divider('─');
+        console.log(`  ${g('session ended · ' + turns + ' exchanges · ' + (totalPromptTokens + totalCompletionTokens) + ' tokens')}`);
+        ui.divider('─');
+        console.log('');
         process.exit(0);
       }
 
       if (cmd === 'help' || cmd === 'h') {
         console.log(`
-  ${b('Session commands')}
+  ${b(w('Session commands'))}
 
   ${w('conversation')}
-    ${g('/clear')}       Clear conversation history
-    ${g('/run')} ${d('<prompt>')} One-shot prompt (doesn't add to conversation)
-    ${g('/quit')}        End session
+    ${cyan('/clear')}       Clear conversation history
+    ${cyan('/run')} ${d('<prompt>')} One-shot prompt (doesn't add to conversation)
+    ${cyan('/quit')}        End session
 
   ${w('project')}
-    ${g('/init')}        Create .intent/ artifacts in this directory
-    ${g('/clarify')}     AI-assisted artifact generation
-    ${g('/gate')}        Declare operational constraints (budget, time, skill)
-    ${g('/export')}      Export portable context for other AI tools
-    ${g('/context')}     Show loaded .intent/ files
-    ${g('/reload')}      Reload .intent/ context from disk
-    ${g('/status')}      Show session stats
+    ${cyan('/init')}        Create .intent/ artifacts in this directory
+    ${cyan('/clarify')}     AI-assisted artifact generation
+    ${cyan('/gate')}        Declare operational constraints (budget, time, skill)
+    ${cyan('/export')}      Export portable context for other AI tools
+    ${cyan('/context')}     Show loaded .intent/ files
+    ${cyan('/reload')}      Reload .intent/ context from disk
+    ${cyan('/status')}      Show session stats
 
   ${w('sync')}
-    ${g('/push')}        Push .intent/ to cloud
-    ${g('/pull')}        Pull .intent/ from cloud (reloads context)
-    ${g('/sync')}        Check sync status
+    ${cyan('/push')}        Push .intent/ to cloud
+    ${cyan('/pull')}        Pull .intent/ from cloud (reloads context)
+    ${cyan('/sync')}        Check sync status
 
   ${w('configuration')}
-    ${g('/login')}       Set up identity + cloud sync
-    ${g('/key')}         Set or update your API key
-    ${g('/model')} ${d('<name>')} Switch model (sonnet, opus, haiku)
-    ${g('/models')}      List available models
-    ${g('/provider')}    Show current provider info
-    ${g('/update')}      Update phewsh to the latest version
-
-  ${w('debug')}
-    ${g('/system')}      Show current system prompt
+    ${cyan('/login')}       Set up identity + cloud sync
+    ${cyan('/key')}         Set or update your API key
+    ${cyan('/model')} ${d('<name>')} Switch model (sonnet, opus, haiku)
+    ${cyan('/models')}      List available models
+    ${cyan('/provider')}    Show current provider info
+    ${cyan('/update')}      Update phewsh to the latest version
+
+  ${w('explore')}
+    ${cyan('/tour')}        Guided walkthrough of everything PHEWSH can do
+    ${cyan('/system')}      Show current system prompt
 `);
         rl.prompt();
         return;
       }
 
+      // ── /tour — guided walkthrough ─────────────────────
+      if (cmd === 'tour') {
+        const pages = ui.TOUR_PAGES;
+        let pageIdx = cmdArg ? parseInt(cmdArg) - 1 : 0;
+        if (isNaN(pageIdx) || pageIdx < 0) pageIdx = 0;
+        if (pageIdx >= pages.length) pageIdx = pages.length - 1;
+
+        const page = pages[pageIdx];
+        console.log('');
+        ui.divider('─');
+        console.log(`  ${b(w(page.title))}  ${g(`(${pageIdx + 1}/${pages.length})`)}`);
+        ui.divider('─');
+        page.body.forEach(line => console.log(line));
+        console.log('');
+        if (pageIdx < pages.length - 1) {
+          console.log(`  ${g('next:')} /tour ${pageIdx + 2}  ${g('·')}  ${g('or /tour 1-' + pages.length + ' to jump')}`);
+        } else {
+          console.log(`  ${green('●')} ${g('End of tour. You\'re ready to go.')}`);
+        }
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'clear') {
         messages.length = 0;
         console.log(`  ${g('conversation cleared')}`);
@@ -352,8 +390,11 @@ async function main() {
 
       if (cmd === 'context') {
         if (intentFiles.length > 0) {
-          console.log(`\n  Loaded from ${cyan('.intent/')}:`);
-          intentFiles.forEach(f => console.log(`    ${green('●')} ${f.file} ${g('(' + f.content.length + ' chars)')}`));
+          console.log('');
+          console.log(`  ${b('Loaded from')} ${cyan('.intent/')}`);
+          ui.divider('─');
+          intentFiles.forEach(f => console.log(`    ${green('●')} ${w(f.file)} ${g('(' + f.content.length + ' chars)')}`));
+          ui.divider('─');
         } else {
           console.log(`\n  ${g('No .intent/ context found in')} ${process.cwd()}`);
           console.log(`  ${g('Run')} /init ${g('to create one')}`);
@@ -366,16 +407,16 @@ async function main() {
       if (cmd === 'status') {
         const turns = messages.length / 2;
         config = loadConfig(); // refresh
-        console.log(`\n  ${b('Session')}`);
-        console.log(`    Turns      ${turns}`);
-        console.log(`    Tokens     ${totalPromptTokens}→${totalCompletionTokens} (in→out)`);
-        console.log(`    Project    ${projectName}`);
-        console.log(`    Context    ${intentFiles.length > 0 ? intentFiles.map(f => f.file).join(', ') : 'none'}`);
-        console.log(`    Model      ${MODELS[currentModel].name}`);
-        console.log(`    Provider   ${MODELS[currentModel].provider}`);
-        if (config?.email) console.log(`    User       ${config.email}`);
-        console.log(`    API key    ${config?.apiKey ? config.apiKey.slice(0, 8) + '...' : yellow('not set')}`);
-        console.log('');
+        ui.statusPanel('Session', [
+          ['Turns', String(turns)],
+          ['Tokens', `${totalPromptTokens} in → ${totalCompletionTokens} out`],
+          ['Project', projectName, 'cyan'],
+          ['Context', intentFiles.length > 0 ? intentFiles.map(f => f.file).join(', ') : 'none', intentFiles.length > 0 ? 'green' : 'yellow'],
+          ['Model', MODELS[currentModel].name],
+          ['Provider', MODELS[currentModel].provider],
+          ['User', config?.email || g('not logged in')],
+          ['API key', config?.apiKey ? config.apiKey.slice(0, 8) + '...' : 'not set', config?.apiKey ? 'green' : 'yellow'],
+        ]);
         rl.prompt();
         return;
       }
@@ -420,7 +461,7 @@ async function main() {
 
       if (cmd === 'clarify') {
         if (!config?.apiKey) {
-          console.log(`\n  ${yellow('⚠')} No API key. Run /key to set one.\n`);
+          console.log(`\n  ${yellow('!')} No API key. Run /key to set one.\n`);
           rl.prompt();
           return;
         }
@@ -464,7 +505,7 @@ async function main() {
           if (content) {
             const outPath = path.join(process.cwd(), '.phewsh.context');
             fs.writeFileSync(outPath, content);
-            console.log(`\n  ${green('✓')} Written to ${outPath}\n`);
+            console.log(`\n  ${green('●')} Written to ${outPath}\n`);
           } else {
             console.log(`\n  ${g('No artifacts to export')}\n`);
           }
@@ -477,16 +518,16 @@ async function main() {
 
       if (cmd === 'push') {
         if (!config?.supabaseUserId) {
-          console.log(`\n  ${yellow('⚠')} Not logged in. Run /login first.\n`);
+          console.log(`\n  ${yellow('!')} Not logged in. Run /login first.\n`);
           rl.prompt();
           return;
         }
         try {
           const token = await ensureValidToken(config);
-          if (!token) { console.log(`\n  ${yellow('⚠')} Session expired. Run /login.\n`); rl.prompt(); return; }
+          if (!token) { console.log(`\n  ${yellow('!')} Session expired. Run /login.\n`); rl.prompt(); return; }
           await push(config, token);
         } catch (err) {
-          console.error(`  ${yellow('⚠')} Push failed: ${err.message}\n`);
+          console.error(`  ${yellow('!')} Push failed: ${err.message}\n`);
         }
         rl.prompt();
         return;
@@ -494,13 +535,13 @@ async function main() {
 
       if (cmd === 'pull') {
         if (!config?.supabaseUserId) {
-          console.log(`\n  ${yellow('⚠')} Not logged in. Run /login first.\n`);
+          console.log(`\n  ${yellow('!')} Not logged in. Run /login first.\n`);
           rl.prompt();
           return;
         }
         try {
           const token = await ensureValidToken(config);
-          if (!token) { console.log(`\n  ${yellow('⚠')} Session expired. Run /login.\n`); rl.prompt(); return; }
+          if (!token) { console.log(`\n  ${yellow('!')} Session expired. Run /login.\n`); rl.prompt(); return; }
           await pull(config, token);
           // Reload context after pull
           intentFiles = loadIntentContext();
@@ -509,7 +550,7 @@ async function main() {
             console.log(`  ${green('●')} Context reloaded: ${intentFiles.map(f => f.file).join(', ')}`);
           }
         } catch (err) {
-          console.error(`  ${yellow('⚠')} Pull failed: ${err.message}\n`);
+          console.error(`  ${yellow('!')} Pull failed: ${err.message}\n`);
         }
         console.log('');
         rl.prompt();
@@ -519,22 +560,24 @@ async function main() {
       if (cmd === 'sync') {
         // Show sync status
         if (!config?.supabaseUserId) {
-          console.log(`\n  ${yellow('⚠')} Not logged in. Run /login first.\n`);
+          console.log(`\n  ${yellow('!')} Not logged in. Run /login first.\n`);
           rl.prompt();
           return;
         }
+        const syncSpin = ui.spinner('checking sync');
         const syncResult = await checkSyncStatus(config);
         if (!syncResult) {
-          console.log(`\n  ${g('Could not check sync status')}\n`);
+          syncSpin.stop(`${g('Could not check sync status')}`);
         } else if (syncResult.status === 'cloud-newer') {
-          console.log(`\n  ${yellow('↓')} Cloud is newer (${syncResult.ago}) — run /pull\n`);
+          syncSpin.stop(`${yellow('↓')} Cloud is newer (${syncResult.ago}) — run /pull`);
         } else if (syncResult.status === 'local-newer') {
-          console.log(`\n  ${yellow('↑')} Local changes not pushed (${syncResult.ago}) — run /push\n`);
+          syncSpin.stop(`${yellow('↑')} Local changes not pushed (${syncResult.ago}) — run /push`);
         } else if (syncResult.status === 'synced') {
-          console.log(`\n  ${green('↕')} In sync\n`);
+          syncSpin.stop(`${green('↕')} In sync`);
         } else if (syncResult.status === 'local-only') {
-          console.log(`\n  ${g('↕ Not linked to cloud — run /push to sync')}\n`);
+          syncSpin.stop(`${g('↕ Not linked to cloud — run /push to sync')}`);
         }
+        console.log('');
         rl.prompt();
         return;
       }
@@ -575,7 +618,9 @@ async function main() {
           return;
         }
         console.log('');
-        console.log(`  ${b('Where to get an API key:')}`);
+        ui.divider('─');
+        console.log(`  ${b(w('Where to get an API key'))}`);
+        ui.divider('─');
         console.log('');
         console.log(`  ${cyan('Anthropic')} ${g('(recommended)')}`);
         console.log(`    ${g('1.')} Go to ${w('console.anthropic.com/settings/keys')}`);
@@ -585,6 +630,9 @@ async function main() {
         console.log(`    ${g('1.')} Go to ${w('openrouter.ai/keys')}`);
         console.log(`    ${g('2.')} Create key → copy it (starts with sk-or-)`)
         console.log('');
+        console.log(`  ${g('Note: API keys are separate from ChatGPT Plus / Claude Pro subscriptions.')}`);
+        console.log(`  ${g('Both providers offer free credits to get started.')}`);
+        console.log('');
         const keyRl = readline.createInterface({ input: process.stdin, output: process.stdout });
         keyRl.question(`  Paste your API key\n  > `, (apiKey) => {
           keyRl.close();
@@ -605,7 +653,10 @@ async function main() {
       }
 
       if (cmd === 'models') {
-        console.log(`\n  ${b('Available models')}\n`);
+        console.log('');
+        ui.divider('─');
+        console.log(`  ${b(w('Available models'))}`);
+        ui.divider('─');
         for (const [key, model] of Object.entries(MODELS)) {
           const active = key === currentModel ? ` ${green('●')}` : '';
           console.log(`    ${w(key.padEnd(16))} ${g(model.name)}${active}`);
@@ -639,35 +690,36 @@ async function main() {
 
       if (cmd === 'provider') {
         const model = MODELS[currentModel];
-        console.log(`\n  ${b('Provider')}`);
-        console.log(`    API        Anthropic (direct)`);
-        console.log(`    Model      ${model.name}`);
-        console.log(`    Endpoint   api.anthropic.com/v1/messages`);
-        console.log(`    Key        ${config?.apiKey ? config.apiKey.slice(0, 8) + '...' : yellow('not set')}`);
-        console.log('');
+        ui.statusPanel('Provider', [
+          ['API', 'Anthropic (direct)'],
+          ['Model', model.name, 'cyan'],
+          ['Endpoint', 'api.anthropic.com/v1/messages'],
+          ['Key', config?.apiKey ? config.apiKey.slice(0, 8) + '...' : 'not set', config?.apiKey ? 'green' : 'yellow'],
+        ]);
         rl.prompt();
         return;
       }
 
       if (cmd === 'update' || cmd === 'upgrade') {
-        console.log(`\n  ${g('Checking for updates...')}`);
+        const updateSpin = ui.spinner('checking for updates');
         try {
           const pkg = require('../../package.json');
           const res = await fetch(`https://registry.npmjs.org/${pkg.name}/latest`, { signal: AbortSignal.timeout(5000) });
           const data = await res.json();
           if (!data.version || data.version === pkg.version) {
-            console.log(`  ${green('●')} Already on the latest version (${pkg.version})\n`);
+            updateSpin.stop(`${green('●')} Already on the latest version (${pkg.version})`);
+            console.log('');
             rl.prompt();
             return;
           }
-          console.log(`  ${cyan(pkg.version)} → ${cyan(data.version)}`);
+          updateSpin.stop(`${cyan(pkg.version)} → ${cyan(data.version)}`);
           console.log(`  ${g('Installing...')}\n`);
           const { execSync } = require('child_process');
           execSync(`npm install -g ${pkg.name}@latest`, { stdio: 'inherit' });
           console.log(`\n  ${green('●')} Updated to ${data.version}`);
           console.log(`  ${g('Restart phewsh to use the new version.')}\n`);
         } catch (err) {
-          console.log(`  ${yellow('!')} Update failed: ${err.message}`);
+          updateSpin.stop(`${yellow('!')} Update failed: ${err.message}`);
           console.log(`  ${g('You can update manually:')} npm install -g phewsh\n`);
         }
         rl.prompt();
@@ -681,7 +733,7 @@ async function main() {
           return;
         }
         if (!config?.apiKey) {
-          console.log(`  ${yellow('⚠')} No API key. Run /key to set one.`);
+          console.log(`  ${yellow('!')} No API key. Run /key to set one.`);
           rl.prompt();
           return;
         }
@@ -727,6 +779,7 @@ async function main() {
       console.log('');
       console.log(`  ${g('Get a key:')}  ${cyan('console.anthropic.com/settings/keys')}`);
       console.log(`  ${g('Or try:')}     ${cyan('openrouter.ai/keys')}`);
+      console.log(`  ${g('Explore:')}    ${cyan('/tour')} ${g('to see what PHEWSH does (no key needed)')}`);
       console.log('');
       rl.prompt();
       return;

package/lib/ui.js

@@ -0,0 +1,252 @@
+// phewsh ui — zero-dependency terminal animations and visual helpers
+// Pure ANSI escape sequences. No chalk, no ora, no bloat.
+
+const b  = (s) => `\x1b[1m${s}\x1b[0m`;
+const d  = (s) => `\x1b[2m${s}\x1b[0m`;
+const w  = (s) => `\x1b[97m${s}\x1b[0m`;
+const g  = (s) => `\x1b[90m${s}\x1b[0m`;
+const green  = (s) => `\x1b[32m${s}\x1b[0m`;
+const cyan   = (s) => `\x1b[36m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const magenta = (s) => `\x1b[35m${s}\x1b[0m`;
+const blue   = (s) => `\x1b[34m${s}\x1b[0m`;
+const red    = (s) => `\x1b[31m${s}\x1b[0m`;
+
+// ANSI cursor control
+const hide = '\x1b[?25l';
+const show = '\x1b[?25h';
+const up = (n = 1) => `\x1b[${n}A`;
+const clearLine = '\x1b[2K\r';
+
+// ── Spinner ──────────────────────────────────────────────
+// Returns { stop } — call stop() when work is done.
+const SPINNER_FRAMES = ['    ·', '   · ·', '  · · ·', ' · · · ·', '· · · · ·', ' · · · ·', '  · · ·', '   · ·'];
+const BRAILLE_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const BREATH_FRAMES = ['░', '▒', '▓', '█', '▓', '▒', '░', ' '];
+const PULSE_FRAMES = ['·', '•', '●', '•'];
+
+function spinner(text = 'thinking', style = 'braille') {
+  const frames = style === 'dots' ? SPINNER_FRAMES
+    : style === 'breath' ? BREATH_FRAMES
+    : style === 'pulse' ? PULSE_FRAMES
+    : BRAILLE_FRAMES;
+  let i = 0;
+  let stopped = false;
+  process.stdout.write(hide);
+  const interval = setInterval(() => {
+    if (stopped) return;
+    const frame = frames[i % frames.length];
+    process.stdout.write(`${clearLine}  ${cyan(frame)} ${g(text)}`);
+    i++;
+  }, style === 'breath' ? 120 : 80);
+
+  return {
+    update(newText) { text = newText; },
+    stop(finalText) {
+      stopped = true;
+      clearInterval(interval);
+      process.stdout.write(`${clearLine}${show}`);
+      if (finalText) process.stdout.write(`  ${finalText}\n`);
+    }
+  };
+}
+
+// ── Animated brand reveal ────────────────────────────────
+// Draws the PHEWSH logo line by line with a cascading effect.
+function brandReveal(fast = false) {
+  return new Promise((resolve) => {
+    const lines = [
+      '',
+      `  ${d('😮\u200d💨')} ${d('🤫')}`,
+      '',
+      `  ${b(w('█▀█ █░█ █▀▀ █░█ █▀ █░█'))}`,
+      `  ${b(w('█▀▀ █▀█ ██▄ ▀▄▀ ▄█ █▀█'))}`,
+      '',
+    ];
+
+    if (fast) {
+      lines.forEach(l => console.log(l));
+      resolve();
+      return;
+    }
+
+    let idx = 0;
+    const interval = setInterval(() => {
+      if (idx >= lines.length) {
+        clearInterval(interval);
+        resolve();
+        return;
+      }
+      console.log(lines[idx]);
+      idx++;
+    }, 60);
+  });
+}
+
+// ── Status panel ─────────────────────────────────────────
+// Draws a bordered status box with labeled rows.
+function statusPanel(title, rows) {
+  const maxLabel = Math.max(...rows.map(r => r[0].length));
+  console.log('');
+  console.log(`  ${b(w(title))}`);
+  console.log(`  ${g('─'.repeat(48))}`);
+  for (const [label, value, color] of rows) {
+    const colorFn = color === 'green' ? green
+      : color === 'yellow' ? yellow
+      : color === 'cyan' ? cyan
+      : color === 'red' ? red
+      : (s) => s;
+    console.log(`  ${g(label.padEnd(maxLabel + 2))} ${colorFn(value)}`);
+  }
+  console.log(`  ${g('─'.repeat(48))}`);
+  console.log('');
+}
+
+// ── Interop badge line ───────────────────────────────────
+// Shows where phewsh is connected / can connect.
+function interopLine(config, intentFiles) {
+  const parts = [];
+  if (intentFiles.length > 0) parts.push(green('●') + ' .intent/');
+  if (config?.apiKey) parts.push(green('●') + ' AI');
+  if (config?.supabaseUserId) parts.push(green('●') + ' cloud');
+
+  // Always show what's available
+  const available = [];
+  available.push(g('Claude Code'));
+  available.push(g('Cursor'));
+  available.push(g('ChatGPT'));
+  available.push(g('MCP'));
+
+  if (parts.length > 0) {
+    console.log(`  ${g('connected')}  ${parts.join(g('  ·  '))}`);
+  }
+  console.log(`  ${g('works with')}  ${available.join(g(' · '))}`);
+}
+
+// ── Divider ──────────────────────────────────────────────
+function divider(char = '·', width = 48) {
+  console.log(`  ${g(char.repeat(width))}`);
+}
+
+// ── Typewriter ───────────────────────────────────────────
+// Writes text character by character. Returns a promise.
+function typewrite(text, speed = 20) {
+  return new Promise((resolve) => {
+    let i = 0;
+    const interval = setInterval(() => {
+      if (i >= text.length) {
+        clearInterval(interval);
+        process.stdout.write('\n');
+        resolve();
+        return;
+      }
+      process.stdout.write(text[i]);
+      i++;
+    }, speed);
+  });
+}
+
+// ── Welcome tips (rotates each session) ──────────────────
+const TIPS = [
+  `${g('tip:')} Type ${w('/clarify')} to turn a messy idea into a structured spec`,
+  `${g('tip:')} ${w('/gate')} lets you set budget, time, and skill constraints`,
+  `${g('tip:')} Run ${w('phewsh watch')} in another tab for live sync to CLAUDE.md`,
+  `${g('tip:')} ${w('/export')} creates a portable context file for any AI tool`,
+  `${g('tip:')} ${w('/model opus')} switches to Claude Opus for complex reasoning`,
+  `${g('tip:')} Your ${w('.intent/')} files are plain markdown — edit them anytime`,
+  `${g('tip:')} ${w('phewsh context --copy')} puts your project context on the clipboard`,
+  `${g('tip:')} ${w('/tour')} walks you through everything PHEWSH can do`,
+];
+
+function randomTip() {
+  return TIPS[Math.floor(Math.random() * TIPS.length)];
+}
+
+// ── Tour content ─────────────────────────────────────────
+const TOUR_PAGES = [
+  {
+    title: 'What is PHEWSH?',
+    body: [
+      `  PHEWSH gives your project a ${b('portable identity')}.`,
+      `  Define what you're building once — every AI tool reads it.`,
+      '',
+      `  It works ${w('standalone')} as its own AI shell,`,
+      `  and ${w('inside')} Claude Code, Cursor, ChatGPT, and any MCP agent.`,
+      '',
+      `  ${g('Your project context lives in')} ${cyan('.intent/')} ${g('— plain markdown files.')}`,
+      `  ${g('You own them. They travel with your code.')}`,
+    ]
+  },
+  {
+    title: 'The .intent/ directory',
+    body: [
+      `  ${cyan('.intent/')}`,
+      `    ${green('vision.md')}    ${g('What this project is and why it exists')}`,
+      `    ${green('plan.md')}      ${g('Strategy, phases, milestones')}`,
+      `    ${green('next.md')}      ${g('Current tasks and what to do right now')}`,
+      `    ${yellow('gate.json')}    ${g('Your constraints (budget, time, skill)')}`,
+      '',
+      `  ${g('Create these with')} /init ${g('or')} /clarify`,
+    ]
+  },
+  {
+    title: 'Standalone mode',
+    body: [
+      `  When you run ${w('phewsh')} on its own, you get an AI shell`,
+      `  that knows your project inside and out.`,
+      '',
+      `  Just type naturally:`,
+      `    ${cyan('>')} what should I focus on today?`,
+      `    ${cyan('>')} is my plan realistic given my budget?`,
+      `    ${cyan('>')} break this feature into tasks`,
+      '',
+      `  ${g('Every message includes your vision, plan, and constraints.')}`,
+    ]
+  },
+  {
+    title: 'Inside other tools',
+    body: [
+      `  ${b('Claude Code')}   ${g('phewsh watch → auto-updates CLAUDE.md')}`,
+      `  ${b('Cursor')}        ${g('phewsh context --file → .phewsh.context')}`,
+      `  ${b('ChatGPT')}       ${g('phewsh context --copy → paste into Custom Instructions')}`,
+      `  ${b('MCP agents')}    ${g('phewsh mcp setup → agents pull tasks automatically')}`,
+      '',
+      `  ${g('Same project identity, every tool. No re-explaining.')}`,
+    ]
+  },
+  {
+    title: 'The Decision Gate',
+    body: [
+      `  Before you build, decide ${b('whether')} to build.`,
+      `  The gate captures what you can actually spend:`,
+      '',
+      `    ${g('Budget')}     ${w('$50')}            ${g('Skill')}      ${w('expert')}`,
+      `    ${g('Time')}       ${w('15 hrs/week')}     ${g('Urgency')}    ${w('high')}`,
+      '',
+      `  ${g('These constraints shape every AI response.')}`,
+      `  ${g('Run')} /gate activate ${g('to set yours.')}`,
+    ]
+  },
+  {
+    title: 'You\'re ready',
+    body: [
+      `  ${green('●')} Type naturally to chat with your project context`,
+      `  ${green('●')} ${w('/init')} or ${w('/clarify')} to create .intent/ artifacts`,
+      `  ${green('●')} ${w('/gate')} to set your constraints`,
+      `  ${green('●')} ${w('/help')} for all commands`,
+      '',
+      `  ${g('PHEWSH is your project\'s home base.')}`,
+      `  ${g('The AI that knows you doesn\'t need to be re-taught.')}`,
+    ]
+  },
+];
+
+module.exports = {
+  // Colors
+  b, d, w, g, green, cyan, yellow, magenta, blue, red,
+  // Components
+  spinner, brandReveal, statusPanel, interopLine, divider, typewrite,
+  randomTip, TOUR_PAGES,
+  // ANSI helpers
+  hide, show, up, clearLine,
+};

package/package.json

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