@kata-sh/cli 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lex Christopherson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# Kata CLI
+
+A terminal coding agent built on [pi](https://github.com/badlogic/pi-mono) (`@mariozechner/pi-coding-agent`). Kata CLI bundles a curated set of extensions for structured planning, browser automation, web search, subagent orchestration, and more.
+
+## Quick Start
+
+```bash
+# From the monorepo root
+bun install
+cd apps/cli
+npx tsc
+npm run copy-themes
+node dist/loader.js
+```
+
+Authenticate with an API key:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+node dist/loader.js
+```
+
+## Architecture
+
+Kata CLI is a thin wrapper around pi-coding-agent. It does not fork pi — it consumes it as an npm dependency and layers on branding, config, and bundled extensions.
+
+```
+apps/cli/
+  src/
+    loader.ts              — Entry point: sets KATA_* env vars, imports cli.ts
+    cli.ts                 — Calls pi-coding-agent's main()
+    app-paths.ts           — ~/.kata-cli/ path constants
+    resource-loader.ts     — Syncs bundled resources to ~/.kata-cli/agent/
+    wizard.ts              — First-run setup, env key hydration
+    resources/
+      KATA-WORKFLOW.md     — The Kata planning methodology
+      AGENTS.md            — System prompt instructions (synced to agent dir)
+      agents/              — Agent templates (worker, scout, researcher)
+      extensions/          — Bundled extensions (see below)
+      skills/              — Bundled skills
+  pkg/
+    package.json           — piConfig shim (name: "kata", configDir: ".kata-cli")
+    dist/                  — Theme assets copied from pi-coding-agent
+```
+
+### How It Works
+
+1. `loader.ts` sets `PI_PACKAGE_DIR` to `pkg/` so pi reads Kata's branding config
+2. `loader.ts` sets `KATA_CODING_AGENT_DIR` so pi uses `~/.kata-cli/agent/` instead of `~/.pi/agent/`
+3. `resource-loader.ts` syncs bundled extensions, agents, skills, and `AGENTS.md` to `~/.kata-cli/agent/` on every launch
+4. `cli.ts` calls pi-coding-agent's `main()` — pi handles everything from there
+
+## Bundled Extensions
+
+| Extension | Description |
+|-----------|-------------|
+| `kata/` | Main extension: `/kata` command, auto-mode, planning, state management |
+| `browser-tools/` | Playwright-based browser automation |
+| `subagent/` | Spawns child Kata processes for parallel work |
+| `slash-commands/` | `/kata-run` and other slash commands |
+| `bg-shell/` | Background shell execution |
+| `context7/` | Context7 library documentation lookup |
+| `search-the-web/` | Web search via Brave API |
+| `mac-tools/` | macOS-specific utilities |
+| `shared/` | Shared UI components (library, not an entry point) |
+
+## The /kata Command
+
+The main extension registers `/kata` with subcommands:
+
+| Command | Description |
+|---------|-------------|
+| `/kata` | Contextual wizard — smart entry point based on project state |
+| `/kata auto` | Start auto-mode (loops fresh sessions until milestone complete) |
+| `/kata stop` | Stop auto-mode gracefully |
+| `/kata status` | Progress dashboard |
+| `/kata queue` | View/manage work queue |
+| `/kata discuss` | Discuss gray areas before planning |
+| `/kata prefs` | Manage preferences (global/project/status) |
+| `/kata doctor` | Diagnose and fix project state |
+
+### Project State
+
+Kata stores planning state in `.kata/` at the project root:
+
+```
+.kata/
+  STATE.md              — Dashboard (read first)
+  DECISIONS.md          — Append-only decisions register
+  PROJECT.md            — Project description
+  REQUIREMENTS.md       — Requirements tracking
+  milestones/
+    M001/
+      M001-ROADMAP.md   — Milestone plan with slices
+      slices/
+        S01/
+          S01-PLAN.md   — Task decomposition
+          tasks/
+            T01-PLAN.md
+            T01-SUMMARY.md
+```
+
+## Config Directory
+
+Kata uses `~/.kata-cli/` (not `~/.kata/`) to avoid collision with other Kata apps (desktop, etc.):
+
+```
+~/.kata-cli/
+  agent/
+    extensions/          — Synced from src/resources/extensions/
+    agents/              — Synced from src/resources/agents/
+    skills/              — Synced from src/resources/skills/
+    AGENTS.md            — Synced from src/resources/AGENTS.md
+    auth.json            — API keys
+    settings.json        — User settings
+    models.json          — Custom model definitions
+  sessions/              — Session history
+  preferences.md         — Global Kata preferences
+```
+
+## Environment Variables
+
+Set by `loader.ts` before pi starts:
+
+| Variable | Purpose |
+|----------|---------|
+| `PI_PACKAGE_DIR` | Points to `pkg/` for Kata's piConfig |
+| `KATA_CODING_AGENT_DIR` | Tells pi to use `~/.kata-cli/agent/` |
+| `KATA_VERSION` | Package version for display |
+| `KATA_BIN_PATH` | Absolute path to loader, used by subagent |
+| `KATA_WORKFLOW_PATH` | Absolute path to bundled KATA-WORKFLOW.md |
+| `KATA_BUNDLED_EXTENSION_PATHS` | Colon-joined extension entry points for subagent |
+
+## Development
+
+```bash
+# Build
+npx tsc
+
+# Copy theme assets (required once, or after pi-coding-agent updates)
+npm run copy-themes
+
+# Run
+node dist/loader.js
+
+# Test
+npm test
+```
+
+### Key Dependency
+
+`@mariozechner/pi-coding-agent` is consumed via npm (hoisted to monorepo root `node_modules/`). Never fork — run `npm update` to pick up upstream changes.
+
+## License
+
+MIT

package/dist/app-paths.d.ts

@@ -0,0 +1,4 @@
+export declare const appRoot: string;
+export declare const agentDir: string;
+export declare const sessionsDir: string;
+export declare const authFilePath: string;

package/dist/app-paths.js

@@ -0,0 +1,6 @@
+import { homedir } from 'os';
+import { join } from 'path';
+export const appRoot = join(homedir(), '.kata-cli');
+export const agentDir = join(appRoot, 'agent');
+export const sessionsDir = join(appRoot, 'sessions');
+export const authFilePath = join(agentDir, 'auth.json');

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,56 @@
+import { AuthStorage, ModelRegistry, SettingsManager, SessionManager, createAgentSession, InteractiveMode, } from '@mariozechner/pi-coding-agent';
+import { agentDir, sessionsDir, authFilePath } from './app-paths.js';
+import { buildResourceLoader, initResources } from './resource-loader.js';
+import { loadStoredEnvKeys, runWizardIfNeeded } from './wizard.js';
+const authStorage = AuthStorage.create(authFilePath);
+loadStoredEnvKeys(authStorage);
+await runWizardIfNeeded(authStorage);
+const modelRegistry = new ModelRegistry(authStorage);
+const settingsManager = SettingsManager.create(agentDir);
+// Always ensure defaults: anthropic/claude-sonnet-4-6, thinking off.
+// Validates on every startup — catches stale settings from prior installs
+// (e.g. grok-2 which no longer exists) and fresh installs with no settings.
+const configuredProvider = settingsManager.getDefaultProvider();
+const configuredModel = settingsManager.getDefaultModel();
+const allModels = modelRegistry.getAll();
+const configuredExists = configuredProvider && configuredModel &&
+    allModels.some((m) => m.provider === configuredProvider && m.id === configuredModel);
+if (!configuredModel || !configuredExists) {
+    // Preferred default: anthropic/claude-sonnet-4-6
+    const preferred = allModels.find((m) => m.provider === 'anthropic' && m.id === 'claude-sonnet-4-6') ||
+        allModels.find((m) => m.provider === 'anthropic' && m.id.includes('sonnet')) ||
+        allModels.find((m) => m.provider === 'anthropic');
+    if (preferred) {
+        settingsManager.setDefaultModelAndProvider(preferred.provider, preferred.id);
+    }
+}
+// Default thinking level: off (always reset if not explicitly set)
+if (settingsManager.getDefaultThinkingLevel() !== 'off' && !configuredExists) {
+    settingsManager.setDefaultThinkingLevel('off');
+}
+// Quiet startup — the kata extension renders its own branded header
+if (!settingsManager.getQuietStartup()) {
+    settingsManager.setQuietStartup(true);
+}
+// Collapse changelog by default — avoid wall of text on updates
+if (!settingsManager.getCollapseChangelog()) {
+    settingsManager.setCollapseChangelog(true);
+}
+const sessionManager = SessionManager.create(process.cwd(), sessionsDir);
+initResources(agentDir);
+const resourceLoader = buildResourceLoader(agentDir);
+await resourceLoader.reload();
+const { session, extensionsResult } = await createAgentSession({
+    authStorage,
+    modelRegistry,
+    settingsManager,
+    sessionManager,
+    resourceLoader,
+});
+if (extensionsResult.errors.length > 0) {
+    for (const err of extensionsResult.errors) {
+        process.stderr.write(`[kata] Extension load error: ${err.error}\n`);
+    }
+}
+const interactiveMode = new InteractiveMode(session);
+await interactiveMode.run();

package/dist/loader.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/loader.js

@@ -0,0 +1,95 @@
+#!/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";
+// pkg/ is a shim directory: contains kata's piConfig (package.json) and pi's
+// theme assets (dist/modes/interactive/theme/) without a src/ directory.
+// This allows config.js to:
+//   1. Read piConfig.name → "kata" (branding)
+//   2. Resolve themes via dist/ (no src/ present → uses dist path)
+const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "pkg");
+// MUST be set before any dynamic import of pi SDK fires — this is what config.js
+// reads to determine APP_NAME and CONFIG_DIR_NAME
+process.env.PI_PACKAGE_DIR = pkgDir;
+process.env.PI_SKIP_VERSION_CHECK = "1";
+process.title = "kata";
+// Print branded banner on first launch (before ~/.kata-cli/ 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" +
+        `  Kata CLI ${dim}v${version}${reset}\n` +
+        `  ${green}Welcome.${reset} Setting up your environment...\n\n`);
+}
+// KATA_CODING_AGENT_DIR — tells pi's getAgentDir() to return ~/.kata-cli/agent/
+process.env.KATA_CODING_AGENT_DIR = agentDir;
+// NODE_PATH — make kata's own node_modules available to extensions loaded via jiti.
+// Without this, extensions (e.g. browser-tools) can't resolve dependencies like
+// `playwright` because jiti resolves modules from pi-coding-agent's location, not kata's.
+const kataRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const kataNodeModules = join(kataRoot, "node_modules");
+process.env.NODE_PATH = process.env.NODE_PATH
+    ? `${kataNodeModules}:${process.env.NODE_PATH}`
+    : kataNodeModules;
+// Force Node to re-evaluate module search paths with the updated NODE_PATH.
+// Must happen synchronously before cli.js imports → extension loading.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { Module } = await import("module");
+Module._initPaths?.();
+// KATA_VERSION — expose package version so extensions can display it
+try {
+    const kataPkg = JSON.parse(readFileSync(join(kataRoot, "package.json"), "utf-8"));
+    process.env.KATA_VERSION = kataPkg.version || "0.0.0";
+}
+catch {
+    process.env.KATA_VERSION = "0.0.0";
+}
+// KATA_BIN_PATH — absolute path to this loader (dist/loader.js), used by subagent
+// to spawn kata instead of pi when dispatching workflow tasks
+process.env.KATA_BIN_PATH = process.argv[1];
+// KATA_WORKFLOW_PATH — absolute path to bundled KATA-WORKFLOW.md
+// when dispatching workflow prompts
+const resourcesDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "src", "resources");
+process.env.KATA_WORKFLOW_PATH = join(resourcesDir, "KATA-WORKFLOW.md");
+// KATA_BUNDLED_EXTENSION_PATHS — colon-joined list of all bundled extension entry point absolute
+// paths, used by subagent to pass --extension <path> to spawned processes.
+// IMPORTANT: paths point to agentDir (~/.kata-cli/agent/extensions/) NOT src/resources/extensions/.
+// initResources() syncs bundled extensions to agentDir before any extension loading occurs,
+// so these paths are always valid at runtime. Using agentDir paths matches what buildResourceLoader
+// discovers (it scans agentDir), so pi's deduplication works correctly and extensions are not
+// double-loaded in subagent child processes.
+// Note: shared/ is NOT included — it's a library imported by kata and ask-user-questions, not an entry point.
+process.env.KATA_BUNDLED_EXTENSION_PATHS = [
+    join(agentDir, "extensions", "kata", "index.ts"),
+    join(agentDir, "extensions", "bg-shell", "index.ts"),
+    join(agentDir, "extensions", "browser-tools", "index.ts"),
+    join(agentDir, "extensions", "context7", "index.ts"),
+    join(agentDir, "extensions", "search-the-web", "index.ts"),
+    join(agentDir, "extensions", "slash-commands", "index.ts"),
+    join(agentDir, "extensions", "subagent", "index.ts"),
+    join(agentDir, "extensions", "mac-tools", "index.ts"),
+    join(agentDir, "extensions", "ask-user-questions.ts"),
+    join(agentDir, "extensions", "get-secrets-from-user.ts"),
+].join(":");
+// Dynamic import defers ESM evaluation — config.js will see PI_PACKAGE_DIR above
+await import("./cli.js");

package/dist/resource-loader.d.ts

@@ -0,0 +1,18 @@
+import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
+/**
+ * Syncs all bundled resources to agentDir (~/.kata-cli/agent/) on every launch.
+ *
+ * - extensions/ → ~/.kata-cli/agent/extensions/   (always overwrite)
+ * - agents/     → ~/.kata-cli/agent/agents/        (always overwrite)
+ * - AGENTS.md   → ~/.kata-cli/agent/AGENTS.md      (always overwrite)
+ * - KATA-WORKFLOW.md is read directly from bundled path via KATA_WORKFLOW_PATH env var
+ *
+ * Always-overwrite ensures updates take effect immediately.
+ */
+export declare function initResources(agentDir: string): void;
+/**
+ * Constructs a DefaultResourceLoader with no additionalExtensionPaths.
+ * Extensions are synced to agentDir by initResources() and pi auto-discovers
+ * them from ~/.kata-cli/agent/extensions/ via its normal agentDir scan.
+ */
+export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -0,0 +1,50 @@
+import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Resolves to the bundled src/resources/ inside the npm package at runtime:
+//   dist/resource-loader.js → .. → package root → src/resources/
+const resourcesDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'resources');
+const bundledExtensionsDir = join(resourcesDir, 'extensions');
+/**
+ * Syncs all bundled resources to agentDir (~/.kata-cli/agent/) on every launch.
+ *
+ * - extensions/ → ~/.kata-cli/agent/extensions/   (always overwrite)
+ * - agents/     → ~/.kata-cli/agent/agents/        (always overwrite)
+ * - AGENTS.md   → ~/.kata-cli/agent/AGENTS.md      (always overwrite)
+ * - KATA-WORKFLOW.md is read directly from bundled path via KATA_WORKFLOW_PATH env var
+ *
+ * Always-overwrite ensures updates take effect immediately.
+ */
+export function initResources(agentDir) {
+    mkdirSync(agentDir, { recursive: true });
+    // Sync extensions — always overwrite so updates land on next launch
+    const destExtensions = join(agentDir, 'extensions');
+    cpSync(bundledExtensionsDir, destExtensions, { recursive: true, force: true });
+    // Sync agents
+    const destAgents = join(agentDir, 'agents');
+    const srcAgents = join(resourcesDir, 'agents');
+    if (existsSync(srcAgents)) {
+        cpSync(srcAgents, destAgents, { recursive: true, force: true });
+    }
+    // Sync skills — always overwrite so updates land on next launch
+    const destSkills = join(agentDir, 'skills');
+    const srcSkills = join(resourcesDir, 'skills');
+    if (existsSync(srcSkills)) {
+        cpSync(srcSkills, destSkills, { recursive: true, force: true });
+    }
+    // Sync AGENTS.md
+    const srcAgentsMd = join(resourcesDir, 'AGENTS.md');
+    const destAgentsMd = join(agentDir, 'AGENTS.md');
+    if (existsSync(srcAgentsMd)) {
+        writeFileSync(destAgentsMd, readFileSync(srcAgentsMd));
+    }
+}
+/**
+ * Constructs a DefaultResourceLoader with no additionalExtensionPaths.
+ * Extensions are synced to agentDir by initResources() and pi auto-discovers
+ * them from ~/.kata-cli/agent/extensions/ via its normal agentDir scan.
+ */
+export function buildResourceLoader(agentDir) {
+    return new DefaultResourceLoader({ agentDir });
+}

package/dist/wizard.d.ts

@@ -0,0 +1,15 @@
+import type { AuthStorage } from '@mariozechner/pi-coding-agent';
+/**
+ * Hydrate process.env from stored auth.json credentials for optional tool keys.
+ * Runs on every launch so extensions see Brave/Context7/Jina keys stored via the
+ * 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

@@ -0,0 +1,159 @@
+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 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') {
+                    if (value.length > 0) {
+                        value = value.slice(0, -1);
+                    }
+                    process.stdout.clearLine(0);
+                    process.stdout.cursorTo(0);
+                    process.stdout.write('  ' + '*'.repeat(value.length));
+                }
+                else {
+                    value += ch;
+                    process.stdout.write('*');
+                }
+            };
+            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.
+ * Runs on every launch so extensions see Brave/Context7/Jina keys stored via the
+ * wizard on prior launches.
+ */
+export function loadStoredEnvKeys(authStorage) {
+    const providers = [
+        ['brave', 'BRAVE_API_KEY'],
+        ['brave_answers', 'BRAVE_ANSWERS_KEY'],
+        ['context7', 'CONTEXT7_API_KEY'],
+        ['jina', 'JINA_API_KEY'],
+    ];
+    for (const [provider, envVar] of providers) {
+        if (!process.env[envVar]) {
+            const cred = authStorage.get(provider);
+            if (cred?.type === 'api_key') {
+                process.env[envVar] = cred.key;
+            }
+        }
+    }
+}
+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',
+    },
+];
+/**
+ * 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(`[kata] 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 {
+            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}~/.kata-cli/agent/auth.json${reset}\n` +
+            `  ${dim}Run ${reset}${cyan}/login${reset}${dim} inside kata to connect your LLM provider.${reset}\n\n`);
+    }
+    else {
+        process.stdout.write(`  ${yellow}↷${reset}  All keys skipped — you can add them later via ${dim}~/.kata-cli/agent/auth.json${reset}\n` +
+            `  ${dim}Run ${reset}${cyan}/login${reset}${dim} inside kata to connect your LLM provider.${reset}\n\n`);
+    }
+}