gsd-pi 2.3.9 → 2.3.11

package/README.md

@@ -200,7 +200,7 @@ Both terminals read and write the same `.gsd/` files on disk. Your decisions in
 
 ### First launch
 
-On first run, GSD prompts for optional API keys (Brave Search, Google Gemini, Context7, Jina, Tavily) for web research and documentation tools. All optional — press Enter to skip any.
+On first run, GSD launches a branded setup wizard that walks you through LLM provider selection (OAuth or API key), then optional tool API keys (Brave Search, Context7, Jina, Slack, Discord). Every step is skippable — press Enter to skip any. Run `gsd config` anytime to re-run the wizard.
 
 ### Commands
 
@@ -223,6 +223,7 @@ On first run, GSD prompts for optional API keys (Brave Search, Google Gemini, Co
 | `Ctrl+Alt+G` | Toggle dashboard overlay |
 | `Ctrl+Alt+V` | Toggle voice transcription |
 | `Ctrl+Alt+B` | Show background shell processes |
+| `gsd config` | Re-run the setup wizard (LLM provider + tool keys) |
 
 ---
 
@@ -360,7 +361,8 @@ GSD is a TypeScript application that embeds the Pi coding agent SDK.
 gsd (CLI binary)
   └─ loader.ts          Sets PI_PACKAGE_DIR, GSD env vars, dynamic-imports cli.ts
       └─ cli.ts         Wires SDK managers, loads extensions, starts InteractiveMode
-          ├─ wizard.ts       First-run API key collection (Brave/Gemini/Context7/Jina)
+          ├─ onboarding.ts   First-run setup wizard (LLM provider + tool keys)
+          ├─ wizard.ts       Env hydration from stored auth.json credentials
           ├─ app-paths.ts    ~/.gsd/agent/, ~/.gsd/sessions/, auth.json
           ├─ resource-loader.ts  Syncs bundled extensions + agents to ~/.gsd/agent/
           └─ src/resources/

package/dist/cli.js

@@ -4,7 +4,8 @@ import { join } from 'node:path';
 import { agentDir, sessionsDir, authFilePath } from './app-paths.js';
 import { initResources } from './resource-loader.js';
 import { ensureManagedTools } from './tool-bootstrap.js';
-import { loadStoredEnvKeys, runWizardIfNeeded } from './wizard.js';
+import { loadStoredEnvKeys } from './wizard.js';
+import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 function parseCliArgs(argv) {
     const flags = { extensions: [], messages: [] };
     const args = argv.slice(2); // skip node + script
@@ -49,6 +50,8 @@ function parseCliArgs(argv) {
             process.stdout.write('  --tools <a,b,c>          Restrict available tools\n');
             process.stdout.write('  --version, -v            Print version and exit\n');
             process.stdout.write('  --help, -h               Print this help and exit\n');
+            process.stdout.write('\nSubcommands:\n');
+            process.stdout.write('  config                   Re-run the setup wizard\n');
             process.exit(0);
         }
         else if (!arg.startsWith('--') && !arg.startsWith('-')) {
@@ -59,15 +62,21 @@ function parseCliArgs(argv) {
 }
 const cliFlags = parseCliArgs(process.argv);
 const isPrintMode = cliFlags.print || cliFlags.mode !== undefined;
+// `gsd config` — replay the setup wizard and exit
+if (cliFlags.messages[0] === 'config') {
+    const authStorage = AuthStorage.create(authFilePath);
+    await runOnboarding(authStorage);
+    process.exit(0);
+}
 // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
 // Provision local managed binaries first so Pi sees them without probing PATH.
 ensureManagedTools(join(agentDir, 'bin'));
 const authStorage = AuthStorage.create(authFilePath);
 loadStoredEnvKeys(authStorage);
-// Skip the setup wizard in print mode — it requires TTY interaction
-if (!isPrintMode) {
-    await runWizardIfNeeded(authStorage);
+// Run onboarding wizard on first launch (no LLM provider configured)
+if (!isPrintMode && shouldRunOnboarding(authStorage)) {
+    await runOnboarding(authStorage);
 }
 const modelRegistry = new ModelRegistry(authStorage);
 const settingsManager = SettingsManager.create(agentDir);

package/dist/loader.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'url';
 import { dirname, resolve, join } from 'path';
-import { existsSync, readFileSync } from 'fs';
-import { agentDir, appRoot } from './app-paths.js';
+import { readFileSync } from 'fs';
+import { agentDir } from './app-paths.js';
 // pkg/ is a shim directory: contains gsd's piConfig (package.json) and pi's
 // theme assets (dist/modes/interactive/theme/) without a src/ directory.
 // This allows config.js to:
@@ -14,30 +14,7 @@ const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'pkg');
 process.env.PI_PACKAGE_DIR = pkgDir;
 process.env.PI_SKIP_VERSION_CHECK = '1'; // GSD ships its own update check — suppress pi's
 process.title = 'gsd';
-// Print branded banner on first launch (before ~/.gsd/ exists)
-if (!existsSync(appRoot)) {
-    const cyan = '\x1b[36m';
-    const green = '\x1b[32m';
-    const dim = '\x1b[2m';
-    const reset = '\x1b[0m';
-    let version = '';
-    try {
-        const pkgJson = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8'));
-        version = pkgJson.version ?? '';
-    }
-    catch { /* ignore */ }
-    process.stderr.write('\n' +
-        cyan +
-        '   ██████╗ ███████╗██████╗ \n' +
-        '  ██╔════╝ ██╔════╝██╔══██╗\n' +
-        '  ██║  ███╗███████╗██║  ██║\n' +
-        '  ██║   ██║╚════██║██║  ██║\n' +
-        '  ╚██████╔╝███████║██████╔╝\n' +
-        '   ╚═════╝ ╚══════╝╚═════╝ ' +
-        reset + '\n\n' +
-        `  Get Shit Done ${dim}v${version}${reset}\n` +
-        `  ${green}Welcome.${reset} Setting up your environment...\n\n`);
-}
+// First-launch branding is handled by the onboarding wizard (src/onboarding.ts)
 // GSD_CODING_AGENT_DIR — tells pi's getAgentDir() to return ~/.gsd/agent/ instead of ~/.gsd/agent/
 process.env.GSD_CODING_AGENT_DIR = agentDir;
 // NODE_PATH — make gsd's own node_modules available to extensions loaded via jiti.

package/dist/logo.d.ts

@@ -6,11 +6,11 @@
  *   - src/onboarding.ts (via ./logo.js)
  */
 /** Raw logo lines — no ANSI codes, no leading newline. */
-export declare const GSD_LOGO: readonly string[];
+export declare const GSD_LOGO: string[];
 /**
  * Render the logo block with a color function applied to each line.
  *
- * @param color — e.g. `(s) => `\x1b[36m${s}\x1b[0m`` or picocolors.cyan
+ * @param color — e.g. picocolors.cyan or `(s) => `\x1b[36m${s}\x1b[0m``
  * @returns Ready-to-write string with leading/trailing newlines.
  */
 export declare function renderLogo(color: (s: string) => string): string;

package/dist/logo.js

@@ -17,7 +17,7 @@ export const GSD_LOGO = [
 /**
  * Render the logo block with a color function applied to each line.
  *
- * @param color — e.g. `(s) => `\x1b[36m${s}\x1b[0m`` or picocolors.cyan
+ * @param color — e.g. picocolors.cyan or `(s) => `\x1b[36m${s}\x1b[0m``
  * @returns Ready-to-write string with leading/trailing newlines.
  */
 export function renderLogo(color) {

package/dist/onboarding.d.ts

@@ -4,8 +4,8 @@
  * Replaces the raw API-key-only wizard with a branded, clack-based experience
  * that guides users through LLM provider authentication before the TUI launches.
  *
- * Flow: logo → choose LLM provider → authenticate (OAuth or API key) →
- *       optional tool keys → summary → TUI launches.
+ * Flow: logo -> choose LLM provider -> authenticate (OAuth or API key) ->
+ *       optional tool keys -> summary -> TUI launches.
  *
  * All steps are skippable. All errors are recoverable. Never crashes boot.
  */

package/dist/onboarding.js

@@ -4,8 +4,8 @@
  * Replaces the raw API-key-only wizard with a branded, clack-based experience
  * that guides users through LLM provider authentication before the TUI launches.
  *
- * Flow: logo → choose LLM provider → authenticate (OAuth or API key) →
- *       optional tool keys → summary → TUI launches.
+ * Flow: logo -> choose LLM provider -> authenticate (OAuth or API key) ->
+ *       optional tool keys -> summary -> TUI launches.
  *
  * All steps are skippable. All errors are recoverable. Never crashes boot.
  */
@@ -69,12 +69,17 @@ const API_KEY_PREFIXES = {
     anthropic: ['sk-ant-'],
     openai: ['sk-'],
 };
+const OTHER_PROVIDERS = [
+    { value: 'google', label: 'Google (Gemini)' },
+    { value: 'groq', label: 'Groq' },
+    { value: 'xai', label: 'xAI (Grok)' },
+    { value: 'openrouter', label: 'OpenRouter' },
+    { value: 'mistral', label: 'Mistral' },
+];
 // ─── Dynamic imports ──────────────────────────────────────────────────────────
 /**
  * Dynamically import @clack/prompts and picocolors.
- * These are transitive dependencies — they exist in node_modules but are not
- * in our direct dependencies. We use dynamic import with a fallback so the
- * module doesn't crash if they're missing.
+ * Dynamic import with fallback so the module doesn't crash if they're missing.
  */
 async function loadClack() {
     try {
@@ -86,15 +91,13 @@ async function loadClack() {
 }
 async function loadPico() {
     try {
-        return await import('picocolors');
+        const mod = await import('picocolors');
+        return mod.default ?? mod;
     }
     catch {
         // Fallback: return identity functions
         const identity = (s) => s;
-        return {
-            default: { cyan: identity, green: identity, yellow: identity, dim: identity, bold: identity, red: identity, reset: identity },
-            cyan: identity, green: identity, yellow: identity, dim: identity, bold: identity, red: identity, reset: identity,
-        };
+        return { cyan: identity, green: identity, yellow: identity, dim: identity, bold: identity, red: identity, reset: identity };
     }
 }
 // ─── Utilities ────────────────────────────────────────────────────────────────
@@ -107,6 +110,10 @@ function openBrowser(url) {
         // Ignore errors — user can manually open the URL
     });
 }
+/** Check if an error is a clack cancel signal */
+function isCancelError(p, err) {
+    return p.isCancel(err);
+}
 // ─── Public API ───────────────────────────────────────────────────────────────
 /**
  * Determine if the onboarding wizard should run.
@@ -156,7 +163,6 @@ export async function runOnboarding(authStorage) {
     p.intro(pc.bold('Welcome to GSD — let\'s get you set up'));
     // ── LLM Provider Selection ────────────────────────────────────────────────
     let llmConfigured = false;
-    let llmProviderName = '';
     try {
         llmConfigured = await runLlmStep(p, pc, authStorage);
     }
@@ -338,13 +344,6 @@ async function runApiKeyFlow(p, pc, authStorage, providerId, providerLabel) {
     return true;
 }
 // ─── "Other Provider" Sub-Flow ────────────────────────────────────────────────
-const OTHER_PROVIDERS = [
-    { value: 'google', label: 'Google (Gemini)' },
-    { value: 'groq', label: 'Groq' },
-    { value: 'xai', label: 'xAI (Grok)' },
-    { value: 'openrouter', label: 'OpenRouter' },
-    { value: 'mistral', label: 'Mistral' },
-];
 async function runOtherProviderFlow(p, pc, authStorage) {
     const provider = await p.select({
         message: 'Select provider',
@@ -393,12 +392,6 @@ async function runToolKeysStep(p, pc, authStorage) {
     }
     return savedCount;
 }
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-/** Check if an error is a clack cancel signal */
-function isCancelError(p, err) {
-    // Clack throws a symbol when the user cancels (Ctrl+C)
-    return p.isCancel(err);
-}
 // ─── Env hydration (migrated from wizard.ts) ─────────────────────────────────
 /**
  * Hydrate process.env from stored auth.json credentials for optional tool keys.

package/dist/wizard.d.ts

@@ -5,11 +5,3 @@ import type { AuthStorage } from '@mariozechner/pi-coding-agent';
  * wizard on prior launches.
  */
 export declare function loadStoredEnvKeys(authStorage: AuthStorage): void;
-/**
- * Check for missing optional tool API keys and prompt for them if on a TTY.
- *
- * Anthropic auth is handled by pi's own OAuth/API key flow — we don't touch it.
- * This wizard only collects Brave Search, Context7, and Jina keys which are needed
- * for web search and documentation tools.
- */
-export declare function runWizardIfNeeded(authStorage: AuthStorage): Promise<void>;

package/dist/wizard.js

@@ -1,74 +1,3 @@
-import { createInterface } from 'readline';
-// ─── Colors ──────────────────────────────────────────────────────────────────
-const cyan = '\x1b[36m';
-const green = '\x1b[32m';
-const yellow = '\x1b[33m';
-const dim = '\x1b[2m';
-const bold = '\x1b[1m';
-const reset = '\x1b[0m';
-// ─── Masked input ─────────────────────────────────────────────────────────────
-/**
- * Prompt for masked input using raw mode stdin.
- * Handles backspace, Ctrl+C, and Enter.
- * Falls back to plain readline if setRawMode is unavailable (e.g. some SSH contexts).
- */
-async function promptMasked(label, hint) {
-    return new Promise((resolve) => {
-        const question = `  ${cyan}›${reset} ${label} ${dim}${hint}${reset}\n  `;
-        try {
-            process.stdout.write(question);
-            process.stdin.setRawMode(true);
-            process.stdin.resume();
-            process.stdin.setEncoding('utf8');
-            let value = '';
-            const redraw = () => {
-                process.stdout.clearLine(0);
-                process.stdout.cursorTo(0);
-                if (value.length === 0) {
-                    process.stdout.write('  ');
-                }
-                else {
-                    const dots = '●'.repeat(Math.min(value.length, 24));
-                    const counter = value.length > 24 ? ` ${dim}(${value.length})${reset}` : ` ${dim}${value.length}${reset}`;
-                    process.stdout.write(`  ${dots}${counter}`);
-                }
-            };
-            const handler = (ch) => {
-                if (ch === '\r' || ch === '\n') {
-                    process.stdin.setRawMode(false);
-                    process.stdin.pause();
-                    process.stdin.off('data', handler);
-                    process.stdout.write('\n');
-                    resolve(value);
-                }
-                else if (ch === '\u0003') {
-                    process.stdin.setRawMode(false);
-                    process.stdout.write('\n');
-                    process.exit(0);
-                }
-                else if (ch === '\u007f' || ch === '\b') {
-                    if (value.length > 0) {
-                        value = value.slice(0, -1);
-                    }
-                    redraw();
-                }
-                else {
-                    value += ch;
-                    redraw();
-                }
-            };
-            process.stdin.on('data', handler);
-        }
-        catch (_err) {
-            process.stdout.write(` ${dim}(input will be visible)${reset}\n  `);
-            const rl = createInterface({ input: process.stdin, output: process.stdout });
-            rl.question('', (answer) => {
-                rl.close();
-                resolve(answer);
-            });
-        }
-    });
-}
 // ─── Env hydration ────────────────────────────────────────────────────────────
 /**
  * Hydrate process.env from stored auth.json credentials for optional tool keys.
@@ -94,101 +23,3 @@ export function loadStoredEnvKeys(authStorage) {
         }
     }
 }
-const API_KEYS = [
-    {
-        provider: 'brave',
-        envVar: 'BRAVE_API_KEY',
-        label: 'Brave Search',
-        hint: '(search-the-web + search_and_read tools)',
-        description: 'Web search and page extraction',
-    },
-    {
-        provider: 'brave_answers',
-        envVar: 'BRAVE_ANSWERS_KEY',
-        label: 'Brave Answers',
-        hint: '(AI-summarised search answers)',
-        description: 'AI-generated search summaries',
-    },
-    {
-        provider: 'context7',
-        envVar: 'CONTEXT7_API_KEY',
-        label: 'Context7',
-        hint: '(up-to-date library docs)',
-        description: 'Live library and framework documentation',
-    },
-    {
-        provider: 'jina',
-        envVar: 'JINA_API_KEY',
-        label: 'Jina AI',
-        hint: '(clean page extraction)',
-        description: 'High-quality web page content extraction',
-    },
-    {
-        provider: 'tavily',
-        envVar: 'TAVILY_API_KEY',
-        label: 'Tavily Search',
-        hint: '(search-the-web + search_and_read tools, starts with tvly-)',
-        description: 'Web search and page extraction (alternative to Brave)',
-    },
-    {
-        provider: 'slack_bot',
-        envVar: 'SLACK_BOT_TOKEN',
-        label: 'Slack Bot',
-        hint: '(remote questions in auto-mode)',
-        description: 'Bot token for remote questions via Slack',
-    },
-    {
-        provider: 'discord_bot',
-        envVar: 'DISCORD_BOT_TOKEN',
-        label: 'Discord Bot',
-        hint: '(remote questions in auto-mode)',
-        description: 'Bot token for remote questions via Discord',
-    },
-];
-/**
- * Check for missing optional tool API keys and prompt for them if on a TTY.
- *
- * Anthropic auth is handled by pi's own OAuth/API key flow — we don't touch it.
- * This wizard only collects Brave Search, Context7, and Jina keys which are needed
- * for web search and documentation tools.
- */
-export async function runWizardIfNeeded(authStorage) {
-    const missing = API_KEYS.filter(k => !authStorage.has(k.provider) && !process.env[k.envVar]);
-    if (missing.length === 0)
-        return;
-    // Non-TTY: warn and continue
-    if (!process.stdin.isTTY) {
-        const names = missing.map(k => k.label).join(', ');
-        process.stderr.write(`[gsd] Warning: optional tool API keys not configured (${names}). Some tools may not work.\n`);
-        return;
-    }
-    // ── Header ──────────────────────────────────────────────────────────────────
-    process.stdout.write(`\n  ${bold}Optional API keys${reset}\n` +
-        `  ${dim}─────────────────────────────────────────────${reset}\n` +
-        `  These unlock additional tools. All optional — press ${cyan}Enter${reset} to skip any.\n\n`);
-    // ── Prompts ─────────────────────────────────────────────────────────────────
-    let savedCount = 0;
-    for (const key of missing) {
-        const value = await promptMasked(key.label, key.hint);
-        if (value.trim()) {
-            authStorage.set(key.provider, { type: 'api_key', key: value.trim() });
-            process.env[key.envVar] = value.trim();
-            process.stdout.write(`  ${green}✓${reset} ${key.label} saved\n\n`);
-            savedCount++;
-        }
-        else {
-            authStorage.set(key.provider, { type: 'api_key', key: '' });
-            process.stdout.write(`  ${dim}↷  ${key.label} skipped${reset}\n\n`);
-        }
-    }
-    // ── Footer ───────────────────────────────────────────────────────────────────
-    process.stdout.write(`  ${dim}─────────────────────────────────────────────${reset}\n`);
-    if (savedCount > 0) {
-        process.stdout.write(`  ${green}✓${reset} ${savedCount} key${savedCount > 1 ? 's' : ''} saved to ${dim}~/.gsd/agent/auth.json${reset}\n` +
-            `  ${dim}Run ${reset}${cyan}/login${reset}${dim} inside gsd to connect your LLM provider.${reset}\n\n`);
-    }
-    else {
-        process.stdout.write(`  ${yellow}↷${reset}  All keys skipped — you can add them later via ${dim}~/.gsd/agent/auth.json${reset}\n` +
-            `  ${dim}Run ${reset}${cyan}/login${reset}${dim} inside gsd to connect your LLM provider.${reset}\n\n`);
-    }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "2.3.9",
+  "version": "2.3.11",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,9 @@
     "prepublishOnly": "npm run sync-pkg-version && npm run build"
   },
   "dependencies": {
+    "@clack/prompts": "^1.1.0",
     "@mariozechner/pi-coding-agent": "^0.57.1",
+    "picocolors": "^1.1.1",
     "playwright": "^1.58.2"
   },
   "devDependencies": {

package/scripts/postinstall.js

@@ -1,18 +1,38 @@
 #!/usr/bin/env node
-import { execSync } from 'child_process'
+
+import { exec as execCb } from 'child_process'
 import { createRequire } from 'module'
 import os from 'os'
-import { fileURLToPath } from 'url'
 import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const require = createRequire(import.meta.url)
 const pkg = require(resolve(__dirname, '..', 'package.json'))
+const cwd = resolve(__dirname, '..')
+
+// ---------------------------------------------------------------------------
+// Async exec helper — captures stdout+stderr, never inherits to terminal
+// ---------------------------------------------------------------------------
+function run(cmd, options = {}) {
+  return new Promise((resolve) => {
+    execCb(cmd, { cwd, ...options }, (error, stdout, stderr) => {
+      resolve({ ok: !error, stdout, stderr, error })
+    })
+  })
+}
 
-// Colors
+// ---------------------------------------------------------------------------
+// Redirect stdout → stderr so npm always shows postinstall output.
+// npm ≥7 suppresses stdout from lifecycle scripts by default; stderr is
+// always forwarded. Clack writes to process.stdout, so we reroute it.
+// ---------------------------------------------------------------------------
+process.stdout.write = process.stderr.write.bind(process.stderr)
+
+// ---------------------------------------------------------------------------
+// ASCII banner — printed before clack UI for brand recognition
+// ---------------------------------------------------------------------------
 const cyan    = '\x1b[36m'
-const green   = '\x1b[32m'
-const yellow  = '\x1b[33m'
 const dim     = '\x1b[2m'
 const reset   = '\x1b[0m'
 
@@ -27,58 +47,81 @@ const banner =
   '   ╚═════╝ ╚══════╝╚═════╝ ' +
   reset + '\n' +
   '\n' +
-  `  Get Shit Done ${dim}v${pkg.version}${reset}\n` +
-  `  A standalone coding agent that plans, executes, and ships.\n` +
-  '\n' +
-  `  ${green}✓${reset} Installed successfully\n` +
-  `  ${dim}Run ${reset}${cyan}gsd${reset}${dim} to get started.${reset}\n`
-
-function run(command, options = {}) {
-  return execSync(command, {
-    cwd: resolve(__dirname, '..'),
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    ...options,
-  })
-}
+  `  Get Shit Done ${dim}v${pkg.version}${reset}\n`
 
-function printCaptured(output) {
-  if (output) process.stderr.write(output)
-}
+// ---------------------------------------------------------------------------
+// Main — wrapped in async IIFE, with graceful fallback if clack fails
+// ---------------------------------------------------------------------------
+;(async () => {
+  process.stderr.write(banner)
 
-process.stderr.write(banner)
-
-// Apply patches to upstream dependencies (non-fatal)
-try {
-  const output = run('npx patch-package')
-  printCaptured(output)
-  process.stderr.write(`\n  ${green}✓${reset} Patches applied\n`)
-} catch (error) {
-  printCaptured(error.stdout)
-  printCaptured(error.stderr)
-  process.stderr.write(`\n  ${yellow}⚠${reset}  Failed to apply patches — run ${cyan}npx patch-package${reset} manually\n`)
-}
+  let p, pc
 
-// Install Playwright chromium for browser tools (non-fatal).
-// We intentionally avoid --with-deps here because install scripts should not
-// block on interactive sudo prompts. Playwright validates host requirements
-// after download; if Linux libs are missing, suggest the explicit follow-up.
-try {
-  const output = run('npx playwright install chromium')
-  printCaptured(output)
-  process.stderr.write(`\n  ${green}✓${reset} Browser tools ready\n\n`)
-} catch (error) {
-  const output = `${error.stdout ?? ''}${error.stderr ?? ''}`
-  printCaptured(output)
-
-  if (os.platform() === 'linux' && output.includes('Host system is missing dependencies to run browsers.')) {
-    process.stderr.write(
-      `\n  ${yellow}⚠${reset}  Browser downloaded, but Linux system dependencies are missing.\n` +
-      `  ${dim}Run ${reset}${cyan}sudo npx playwright install-deps chromium${reset}${dim} to finish setup.${reset}\n\n`
-    )
+  try {
+    p = await import('@clack/prompts')
+    pc = (await import('picocolors')).default
+  } catch {
+    // Clack or picocolors unavailable — fall back to minimal output
+    process.stderr.write(`  Run gsd to get started.\n\n`)
+    await run('npx patch-package')
+    await run('npx playwright install chromium')
+    return
+  }
+
+  // --- Branded intro -------------------------------------------------------
+  p.intro('Setup')
+
+  const results = []
+  const s = p.spinner()
+
+  // --- Step 1: Apply patches -----------------------------------------------
+  s.start('Applying patches…')
+  const patchResult = await run('npx patch-package')
+  if (patchResult.ok) {
+    s.stop('Patches applied')
+    results.push({ label: 'Patches applied', ok: true })
   } else {
-    process.stderr.write(
-      `\n  ${yellow}⚠${reset}  Browser tools unavailable — run ${cyan}npx playwright install chromium${reset} to enable\n\n`
-    )
+    s.stop(pc.yellow('Patches — skipped (non-fatal)'))
+    results.push({
+      label: 'Patches skipped — run ' + pc.cyan('npx patch-package') + ' manually',
+      ok: false,
+    })
   }
-}
+
+  // --- Step 2: Playwright browser ------------------------------------------
+  // Avoid --with-deps: install scripts should not block on interactive sudo
+  // prompts. If Linux libs are missing, suggest the explicit follow-up.
+  s.start('Setting up browser tools…')
+  const pwResult = await run('npx playwright install chromium')
+  if (pwResult.ok) {
+    s.stop('Browser tools ready')
+    results.push({ label: 'Browser tools ready', ok: true })
+  } else {
+    const output = `${pwResult.stdout ?? ''}${pwResult.stderr ?? ''}`
+    if (os.platform() === 'linux' && output.includes('Host system is missing dependencies to run browsers.')) {
+      s.stop(pc.yellow('Browser downloaded, missing Linux deps'))
+      results.push({
+        label: 'Run ' + pc.cyan('sudo npx playwright install-deps chromium') + ' to finish setup',
+        ok: false,
+      })
+    } else {
+      s.stop(pc.yellow('Browser tools — skipped (non-fatal)'))
+      results.push({
+        label: 'Browser tools unavailable — run ' + pc.cyan('npx playwright install chromium'),
+        ok: false,
+      })
+    }
+  }
+
+  // --- Summary note --------------------------------------------------------
+  const lines = results.map(
+    (r) => (r.ok ? pc.green('✓') : pc.yellow('⚠')) + ' ' + r.label
+  )
+  lines.push('')
+  lines.push('Run ' + pc.cyan('gsd') + ' to get started.')
+
+  p.note(lines.join('\n'), 'Installed')
+
+  // --- Outro ---------------------------------------------------------------
+  p.outro(pc.green('Done!'))
+})()

package/src/resources/extensions/bg-shell/index.ts

@@ -48,6 +48,7 @@ import { createConnection } from "node:net";
 import { randomUUID } from "node:crypto";
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { shortcutDesc } from "../shared/terminal.js";
 import { createRequire } from "node:module";
 
 // ── Windows VT Input Restoration ────────────────────────────────────────────
@@ -2356,7 +2357,7 @@ export default function (pi: ExtensionAPI) {
 	// ── Ctrl+Alt+B shortcut ──────────────────────────────────────────────
 
 	pi.registerShortcut(Key.ctrlAlt("b"), {
-		description: "Open background process manager",
+		description: shortcutDesc("Open background process manager", "/bg"),
 		handler: async (ctx) => {
 			latestCtx = ctx;
 			await ctx.ui.custom<void>(

package/src/resources/extensions/gsd/index.ts

@@ -47,6 +47,7 @@ import {
 import { Key } from "@mariozechner/pi-tui";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
+import { shortcutDesc } from "../shared/terminal.js";
 import { Text } from "@mariozechner/pi-tui";
 
 // ── ASCII logo ────────────────────────────────────────────────────────────
@@ -184,10 +185,8 @@ export default function (pi: ExtensionAPI) {
   });
 
   // ── Ctrl+Alt+G shortcut — GSD dashboard overlay ────────────────────────
-  // Requires Kitty keyboard protocol or modifyOtherKeys support.
-  // Terminals without support (macOS Terminal.app, JetBrains): use /gsd status instead.
   pi.registerShortcut(Key.ctrlAlt("g"), {
-    description: "Open GSD dashboard (or use /gsd status)",
+    description: shortcutDesc("Open GSD dashboard", "/gsd status"),
     handler: async (ctx) => {
       // Only show if .gsd/ exists
       if (!existsSync(join(process.cwd(), ".gsd"))) {

package/src/resources/extensions/shared/terminal.ts

@@ -0,0 +1,23 @@
+/**
+ * Terminal capability detection for keyboard shortcut support.
+ *
+ * Ctrl+Alt shortcuts require the Kitty keyboard protocol or modifyOtherKeys.
+ * Terminals that lack this support silently swallow the key combos.
+ */
+
+const UNSUPPORTED_TERMS = ["apple_terminal"];
+
+export function supportsCtrlAltShortcuts(): boolean {
+  const term = (process.env.TERM_PROGRAM || "").toLowerCase();
+  const jetbrains = (process.env.TERMINAL_EMULATOR || "").toLowerCase().includes("jetbrains");
+  return !UNSUPPORTED_TERMS.some((t) => term.includes(t)) && !jetbrains;
+}
+
+/**
+ * Returns a shortcut description that includes a slash-command fallback hint
+ * when the current terminal likely can't fire Ctrl+Alt combos.
+ */
+export function shortcutDesc(base: string, fallbackCmd: string): string {
+  if (supportsCtrlAltShortcuts()) return base;
+  return `${base} — shortcut may not work in this terminal, use ${fallbackCmd}`;
+}

package/src/resources/extensions/subagent/index.ts

@@ -654,8 +654,7 @@ export default function (pi: ExtensionAPI) {
 					const output = isError
 						? (r.errorMessage || r.stderr || getFinalOutput(r.messages) || "(no output)")
 						: getFinalOutput(r.messages);
-					const preview = output.slice(0, 200) + (output.length > 200 ? "..." : "");
-					return `[${r.agent}] ${r.exitCode === 0 ? "completed" : `failed (exit ${r.exitCode})`}: ${preview || "(no output)"}`;
+					return `[${r.agent}] ${r.exitCode === 0 ? "completed" : `failed (exit ${r.exitCode})`}: ${output || "(no output)"}`;
 				});
 				return {
 					content: [

package/src/resources/extensions/voice/index.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { shortcutDesc } from "../shared/terminal.js";
 import type { AssistantMessage } from "@mariozechner/pi-ai";
 import { isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { spawn, execSync, type ChildProcess } from "node:child_process";
@@ -131,7 +132,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerShortcut("ctrl+alt+v", {
-		description: "Toggle voice mode",
+		description: shortcutDesc("Toggle voice mode", "/voice"),
 		handler: async (ctx) => toggleVoice(ctx),
 	});