@phantomcodes/cli 1.2.2 → 1.2.4

package/dist/setup/agents.mjs

@@ -8,10 +8,11 @@ import { SETUP_MODEL, agentBaseUrl, readText, configHome, onPath, phantomCommand
 import { jsonObject, jsonEdit, tomlSet, tomlRemoveOurs, yamlSetTop, yamlAddModel, yamlRemoveOurs } from "./editors.mjs";
 // ── Manual Provider Helper ───────────────────────────────────────────────────
 /** An agent whose model settings live on its own settings screen: setup prints the steps. */
-export function manualProvider(where, steps) {
+export function manualProvider(where, steps, note) {
     return (ctx, off) => ({
         edits: [],
-        result: { settings: where, on: false, warnings: [], manual: off ? [`Remove the Phantom AI settings in ${where}.`] : steps(ctx) },
+        // The note is something to know, not a step to do, so it shows apart from the numbered steps.
+        result: { settings: where, on: false, warnings: off || !note ? [] : [note], manual: off ? [`Remove the Phantom AI settings in ${where}.`] : steps(ctx) },
     });
 }
 // ── Codex ────────────────────────────────────────────────────────────────────
@@ -76,7 +77,7 @@ export function claudePlan(env, opts) {
         };
     }
     if (!resolveApiKey(env))
-        die('No API key to give Claude Code. Run: phantom login', 'no_key');
+        die('No Phantom key yet to give Claude Code. Run phantom login to sign in, then run this again.', 'no_key');
     const baseUrl = agentBaseUrl(env, 'claude-code');
     // `phantom` if it's installed, else this very phantom by absolute path: Claude Code
     // runs the helper outside this shell, so a relative or npx path won't do.
@@ -354,13 +355,12 @@ export const SETUP_AGENTS = {
         home: '.cursor',
         /** ~/.cursor/skills */
         skills: '.cursor/skills',
+        // Three short steps; the key gets copied without being shown (phantom's menu has "Copy my key").
         provider: manualProvider('Cursor Settings, Models', (ctx) => [
             'Open Cursor Settings (Cmd+Shift+J on macOS), then Models.',
-            `Under OpenAI API Key, paste your Phantom AI key, then turn on Override OpenAI Base URL and set it to ${agentBaseUrl(ctx.env, 'cursor')}`,
-            'Copy the key without showing it: phantom key show | pbcopy',
-            `Use Add model to add ${ctx.model ?? SETUP_MODEL} and any other Phantom AI model ids you want in the picker.`,
-            'While the override is on, Cursor\'s own non-OpenAI models stop working; turn it off to go back. Tab completions never use your own key.',
-        ]),
+            `Paste your Phantom AI key under OpenAI API Key (copy it with "Copy my key" in phantom's menu, or phantom keys show --copy), then turn on Override OpenAI Base URL and set it to ${agentBaseUrl(ctx.env, 'cursor')}`,
+            `Under Add model, add ${ctx.model ?? SETUP_MODEL}.`,
+        ], "While the override is on, Cursor's own non-OpenAI models stop working; turn it off to go back. Tab completions never use your key."),
         shellEnv: () => ({}),
     },
     /** opencode. */

package/dist/setup/apply.mjs

@@ -1,6 +1,7 @@
+import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
 import { stateDir } from "../core/state.mjs";
 import { readText } from "./shared.mjs";
 import { jsonText } from "./editors.mjs";
@@ -52,28 +53,6 @@ export function lineDiff(before, after) {
     }
     return out.join('\n');
 }
-/** A plan as people read it: each file with its diff (keys masked), the skill in one line, then commands, skips and steps to do by hand. */
-export function setupPreview(plan) {
-    const parts = [];
-    for (const f of plan.files) {
-        if (f.skill)
-            parts.push(`${f.action === 'create' ? 'install' : 'update'} skill ${f.file}`);
-        else if (f.action === 'remove')
-            parts.push(`remove ${f.file}`);
-        else
-            parts.push(`${f.action} ${f.file}\n${maskKeys(lineDiff(f.before, f.after))}`);
-    }
-    for (const s of plan.skipped)
-        parts.push(`skip ${s.agent}: ${s.reason}`);
-    for (const a of plan.agents) {
-        const steps = a.provider?.manual ?? [];
-        if (steps.length)
-            parts.push([`${SETUP_AGENTS[a.agent].label}, by hand:`, ...steps.map((s, k) => `  ${k + 1}. ${s}`)].join('\n'));
-    }
-    for (const n of plan.notes)
-        parts.push(n);
-    return parts.length ? parts.join('\n\n') : 'Nothing to change.';
-}
 function backupsFile(env) {
     return path.join(stateDir(env), 'setup-backups.json');
 }
@@ -89,6 +68,10 @@ function writeBackups(env, entries) {
     mkdirSync(stateDir(env), { recursive: true, mode: 0o700 });
     writeFileSync(backupsFile(env), jsonText(entries), { mode: 0o600 });
 }
+/** Whether setup has written anything on this computer that undo could put back: it keeps a record of each file. */
+export function isSetUp(env) {
+    return Object.keys(readBackups(env)).length > 0;
+}
 const sha256 = (text) => createHash('sha256').update(text).digest('hex');
 /**
  * Writes a plan from {@link planSetup}. Before it edits a file it copies it
@@ -213,5 +196,25 @@ export function restoreSetup(env, opts = {}) {
     }
     if (!opts.dryRun && restored.length)
         writeBackups(env, backups);
+    // The phantom-ai skill is phantom's own file, kept out of the backups, so undo removes it here.
+    const home = env.HOME || os.homedir();
+    for (const [agent, spec] of Object.entries(SETUP_AGENTS)) {
+        if (!spec.skills || (opts.agent && opts.agent !== 'all' && agent !== opts.agent))
+            continue;
+        const skill = path.join(home, spec.skills, 'phantom-ai', 'SKILL.md');
+        // Two agents can share a skills folder (pi and Codex use ~/.agents/skills), so each file is listed once.
+        if (!existsSync(skill) || restored.some((r) => r.file === skill) || !/^name: phantom-ai$/m.test(readText(skill) ?? ''))
+            continue;
+        if (!opts.dryRun) {
+            rmSync(skill, { force: true });
+            try {
+                rmdirSync(path.dirname(skill));
+            }
+            catch {
+                // Not empty: something else lives there, so the folder stays.
+            }
+        }
+        restored.push({ file: skill, from: null });
+    }
     return { restored, skipped, ...(opts.dryRun ? { dry_run: true } : {}) };
 }

package/dist/setup/command.mjs

@@ -1,62 +1,68 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { die } from "../core/errors.mjs";
-import { out } from "../core/helpers.mjs";
+import { out, pickIo } from "../core/helpers.mjs";
+import { BackToMenu, checklist, choose } from "../core/pick.mjs";
 import { resolveApiKey } from "../keys/saved.mjs";
 import { workspaceLogin } from "../workspace/command.mjs";
 import { SETUP_AGENTS, SETUP_NAMES } from "./agents.mjs";
 import { planSetup } from "./plan.mjs";
-import { setupPreview, applySetup, previewSetup, restoreSetup } from "./apply.mjs";
-/** `--table` output for `setup`. */
-export function tableSetup(d) {
-    const r = d;
-    const pad = ''.padEnd(16);
-    const lines = r.agents.map((a) => {
-        const label = SETUP_AGENTS[a.agent]?.label ?? a.agent;
-        const p = a.provider;
-        return [
-            `${a.agent.padEnd(16)}${a.skill ? `skill ${r.dry_run || r.applied === false ? 'goes' : 'installed'} at ${a.skill}` : 'no skill (this agent does not read skills)'}`,
-            ...(!p
-                ? []
-                : p.manual
-                    ? [`${pad}set up by hand in ${p.settings}:`, ...p.manual.map((step, k) => `${pad}  ${k + 1}. ${step}`)]
-                    : p.on
-                        ? [
-                            `${pad}models via Phantom AI at ${p.base_url}${p.model ? `, model ${p.model}` : ''} (${p.settings})`,
-                            `${pad}restart ${label} to pick it up; undo with: phantom setup --agent ${a.agent} --provider off`,
-                        ]
-                        : [a.agent === 'claude' ? `${pad}models back to Anthropic (${p.settings})` : `${pad}Phantom AI settings removed (${p.settings})`]),
-            ...(p?.warnings ?? []).map((w) => `${pad}warning: ${w}`),
-        ].join('\n');
-    });
-    const files = (r.files ?? []).filter((f) => f.diff !== undefined);
-    if (files.length) {
-        lines.push('');
-        for (const f of files) {
-            lines.push(`${r.dry_run || r.applied === false ? `would ${f.action}` : `${f.action}d`} ${f.file}${f.backup ? ` (copy before: ${f.backup})` : ''}`);
-            if (f.diff && (r.dry_run || r.applied === false))
-                lines.push(f.diff.replace(/^/gm, '    '));
-        }
-    }
-    for (const s of r.skipped ?? [])
-        lines.push(`skipped ${s.agent}: ${s.reason}`);
-    for (const n of r.notes ?? [])
-        lines.push(n);
-    if (r.applied === false)
-        lines.push('Nothing was changed.');
-    return lines.join('\n');
+import { applySetup, previewSetup, restoreSetup } from "./apply.mjs";
+import { setupScreen } from "./screen.mjs";
+import { colorOn, paint, unstyled } from "../core/style.mjs";
+import { inApp } from "../cli/screens.mjs";
+import { brandIntro, motionOn, play, reveal } from "../core/motion.mjs";
+/** `--table` output for `setup`, and what a terminal shows: see {@link setupScreen}. */
+export function tableSetup(d, opts = {}) {
+    return setupScreen(d, opts);
 }
-/** `--table` output for `setup --restore`. */
-export function tableRestore(d) {
+/** `--table` output for `setup --restore`, and what a terminal shows: a ✓ per file put back, a ✗ per file left alone. */
+export function tableRestore(d, opts = {}) {
     const r = d;
+    const p = paint(opts.env ?? {}, Boolean(opts.color));
+    const home = opts.env?.HOME;
+    const short = (file) => (home && file.startsWith(home + '/') ? '~' + file.slice(home.length) : file);
+    if (!r.restored.length && !r.skipped.length)
+        return 'Nothing to restore.';
     const lines = [
-        ...r.restored.map((x) => `${r.dry_run ? 'would restore' : 'restored'} ${x.file}${x.from ? ` from ${x.from}` : ' (phantom created it, so it is removed)'}`),
-        ...r.skipped.map((x) => `skipped ${x.file}: ${x.reason}`),
+        ...r.restored.map((x) => {
+            const verb = x.from ? (r.dry_run ? 'puts back' : 'put back') : r.dry_run ? 'deletes' : 'removed';
+            const what = x.from ? `${verb} ${short(x.file)} as it was before setup` : `${verb} ${short(x.file)} (phantom made this file)`;
+            return `  ${r.dry_run ? p.dim('·') : p.lime('✓')} ${what}`;
+        }),
+        ...r.skipped.map((x) => `  ${p.red('✗')} left ${short(x.file)}: ${x.reason}`),
     ];
-    return lines.length ? lines.join('\n') : 'Nothing to restore.';
+    if (!r.dry_run && r.restored.length) {
+        // What undo leaves alone, so nobody thinks they're back to nothing when they're still signed in.
+        lines.push('', inApp() ? `  ${p.dim('Still here: your sign-in and saved keys. To remove those too, pick Sign out below.')}` : `  ${p.dim('Still here: your sign-in and saved keys. To remove those too:')} ${p.cyan('phantom logout --all')}`);
+        // Cursor was set up by hand, so undo can't reach it; say what to do there.
+        if (opts.env?.HOME && existsSync(path.join(opts.env.HOME, '.cursor')))
+            lines.push(`  ${p.dim("Cursor: if you set it up by hand, turn off Override OpenAI Base URL in Cursor Settings, Models.")}`);
+        lines.push(`  ${p.lime('→')} Restart your agents (and open a new terminal) so they go back to how they were.`);
+    }
+    return lines.join('\n');
 }
 /** `phantom setup`: plans, previews, asks, applies or restores agent setup. Plain setup with no key yet signs in first when it runs in a terminal. Run by `run()`. */
 export async function setupCommand(input) {
-    const { env, io, flags, table } = input;
+    const { env, io, flags } = input;
+    // A person at a terminal gets the short summary; a pipe, or --json, gets JSON.
+    const table = input.table || (Boolean(io.stdoutIsTTY) && !flags['json']);
+    const diff = Boolean(flags['diff']);
+    // The summary goes to stdout and the question to stderr, so each gets color only when it is a terminal.
+    const shown = (opts = {}) => (d) => tableSetup(d, { env, diff, color: colorOn(env, io.stdoutIsTTY), columns: process.stdout.columns, ...opts });
+    /**
+     * Prints a result to stdout: JSON for a pipe, the screen otherwise, played
+     * as a flipbook when motion is on. The header draws in on a preview; after
+     * the changes, each ✓ ticks in after the one before.
+     */
+    const emit = async (result) => {
+        if (!table || !motionOn(env, io.stdoutIsTTY))
+            return out(result, table, shown(), io.stdout);
+        const lines = shown()(result).split('\n');
+        const book = result.dry_run ? brandIntro(lines) : reveal(lines, (line) => (/^\s+\S*[✓!✗]/.test(unstyled(line)) ? 60 : 0));
+        await play(io.stdout, book, { rows: process.stdout.rows, skipOnKey: true });
+    };
     const agent = flags['agent'];
     if (agent === true)
         die(`--agent requires ${SETUP_NAMES.join(', ')} or all`);
@@ -70,8 +76,29 @@ export async function setupCommand(input) {
         die('--mcp has been removed. Phantom inference runs directly through phantom claude, phantom codex, or phantom pi.');
     const dryRun = Boolean(flags['dry-run']);
     if (flags['restore']) {
+        // At a terminal, undo shows what it will put back, and asks, the way setup asks before it changes anything.
+        const pick = !dryRun && !flags['yes'] ? pickIo(input) : null;
+        if (pick) {
+            const preview = restoreSetup(env, { agent, dryRun: true });
+            if (!preview.restored.length && !preview.skipped.length) {
+                io.stdout('  Nothing to undo: setup has no changes on this computer.\n');
+                return 0;
+            }
+            io.stderr(`\n${tableRestore(preview, { env, color: colorOn(env, io.isTTY) })}\n\n`);
+            // The marker starts on Cancel: undo can't itself be undone, so it takes a deliberate move.
+            const go = await choose(pick, 'Undo these changes?', [
+                { label: 'Undo them', hint: 'your agents go back to how they were', value: true },
+                { label: 'Cancel', hint: 'change nothing', value: false },
+            ], 1);
+            if (!go) {
+                if (go === null && io.fromMenu)
+                    throw new BackToMenu();
+                io.stderr('  Nothing was changed.\n');
+                return 0;
+            }
+        }
         const result = restoreSetup(env, { agent, dryRun });
-        out(result, table, tableRestore, io.stdout);
+        out(result, table, (d) => tableRestore(d, { env, color: colorOn(env, io.stdoutIsTTY) }), io.stdout);
         return result.skipped.length ? 1 : 0;
     }
     // Plain `phantom setup` sets up everything it finds and asks first. Any of
@@ -80,20 +107,91 @@ export async function setupCommand(input) {
     // With no key yet, sign in first, as phantom claude does, so the agents
     // get one in this run. Its words go to stderr; stdout stays setup's result.
     if (guided && !dryRun && io.isTTY && !resolveApiKey(env)) {
-        await workspaceLogin({ ...input, io: { ...io, stdout: io.stderr }, flags: flags['no-browser'] ? { 'no-browser': true } : {} });
+        await workspaceLogin({ ...input, io: { ...io, stdout: io.stderr }, flags: flags['no-browser'] ? { 'no-browser': true } : {} }, { inSetup: true });
+        // Sign-in was cancelled: stop here rather than set up the agents without a key.
+        if (!resolveApiKey(env)) {
+            io.stderr('  Nothing was changed.\n');
+            return 0;
+        }
     }
-    const plan = planSetup(env, {
+    const options = {
         agent,
         provider: guided || provider === true ? true : provider === 'off' ? 'off' : false,
         model: typeof model === 'string' ? model : undefined,
         guided,
-    });
+    };
+    const found = planSetup(env, options);
+    let plan = found;
+    // At a terminal, plain setup asks which of the agents it found to connect (all ticked, Space unticks),
+    // then whether to make the changes. Esc on the question goes back to the checklist.
+    const pick = guided && !flags['yes'] && !dryRun ? pickIo(input) : null;
+    const ticks = Boolean(pick) && found.agents.length > 1;
+    /** Shows the checklist, or returns false when Esc there means leave. */
+    const tick = async () => {
+        const only = await checklist(pick, 'Which agents should use Phantom AI?', found.agents.map((a) => ({ label: SETUP_AGENTS[a.agent].label, hint: a.provider ? 'skill and model settings' : 'skill', value: a.agent, checked: plan.agents.some((p) => p.agent === a.agent) })));
+        if (!only)
+            return false;
+        plan = planSetup(env, { ...options, only });
+        return true;
+    };
+    /** Esc on setup's first step: back to the menu when it started setup, otherwise stop with nothing changed. */
+    const leave = () => {
+        if (io.fromMenu)
+            throw new BackToMenu();
+        io.stderr('  Nothing was changed.\n');
+        return 0;
+    };
+    if (ticks && !(await tick()))
+        return leave();
+    /**
+     * Prints the result and gives the exit code: 1 when a file was skipped, or
+     * when there was no key so the agents weren't pointed at Phantom AI. A script
+     * checking only the exit code then can't mistake half a setup for all of it.
+     */
+    const finish = async (result) => {
+        const partial = guided && provider !== 'off' && !resolveApiKey(env);
+        await emit(partial ? { ...result, complete: false } : result);
+        return result.skipped || partial ? 1 : 0;
+    };
     if (dryRun) {
-        out(previewSetup(plan), table, tableSetup, io.stdout);
+        await emit(previewSetup(plan));
         return 0;
     }
     if (guided && !flags['yes'] && plan.files.length) {
-        io.stderr(setupPreview(plan) + '\n\n');
+        const preview = setupScreen(previewSetup(plan), { env, diff, color: colorOn(env, io.isTTY), columns: process.stderr.columns, mode: 'ask', hint: !(pick && !io.ask) });
+        // The question waits for the header and rows to finish drawing in.
+        if (motionOn(env, io.isTTY))
+            await play(io.stderr, brandIntro(preview.split('\n')), { rows: process.stderr.rows, skipOnKey: true });
+        else
+            io.stderr(preview + '\n');
+        io.stderr('\n');
+        // At a terminal: a choice instead of typing y or n, with a look at every line first if wanted.
+        if (pick && !io.ask) {
+            for (;;) {
+                const answer = await choose({ ...pick, esc: ticks || io.fromMenu ? 'back' : 'quit' }, 'Make these changes?', [
+                    { label: 'Make these changes', value: 'yes' },
+                    { label: 'Show every line first', value: 'diff' },
+                    { label: 'Cancel', hint: 'change nothing', value: 'no' },
+                ]);
+                if (answer === 'diff') {
+                    io.stderr(setupScreen(previewSetup(plan), { env, diff: true, color: colorOn(env, io.isTTY), columns: process.stderr.columns, mode: 'ask' }) + '\n\n');
+                    continue;
+                }
+                // Esc: back to the checklist, then the preview again; or out, when there was no checklist.
+                if (answer === null) {
+                    if (!ticks || !(await tick()))
+                        return leave();
+                    io.stderr('\n' + setupScreen(previewSetup(plan), { env, diff, color: colorOn(env, io.isTTY), columns: process.stderr.columns, mode: 'ask', hint: false }) + '\n\n');
+                    continue;
+                }
+                if (answer !== 'yes') {
+                    await emit({ ...previewSetup(plan), dry_run: undefined, applied: false });
+                    return 0;
+                }
+                break;
+            }
+            return finish(applySetup(env, plan));
+        }
         const ask = io.ask ??
             (process.stdin.isTTY
                 ? async (q) => {
@@ -108,13 +206,12 @@ export async function setupCommand(input) {
                 : null);
         if (!ask)
             die('phantom setup changes the files above. Run it in a terminal to confirm, or add --yes (or --dry-run to only look)', 'confirm_needed');
-        const answer = await ask('Make these changes? [y/N] ');
+        const q = paint(env, colorOn(env, io.isTTY));
+        const answer = await ask(`  ${q.lime('?')} ${q.bold('Make these changes?')} ${q.dim('[y/N]')} `);
         if (!/^y(es)?$/i.test(answer.trim())) {
-            out({ ...previewSetup(plan), dry_run: undefined, applied: false }, table, tableSetup, io.stdout);
+            await emit({ ...previewSetup(plan), dry_run: undefined, applied: false });
             return 0;
         }
     }
-    const result = applySetup(env, plan);
-    out(result, table, tableSetup, io.stdout);
-    return result.skipped ? 1 : 0;
+    return finish(applySetup(env, plan));
 }

package/dist/setup/editors.mjs

@@ -373,7 +373,7 @@ export function shellBlock(env, fish, state, onPathFn = onPath) {
         '# Written by phantom setup. Sets PHANTOM_API_KEY to the key phantom uses when the',
         '# shell starts, for coding agents that read it. The key is not stored here.',
         `# agents: ${state.agents.join(' ')}`,
-        '# Undo: phantom setup --provider off',
+        '# Undo: phantom setup --restore',
     ];
     if (fish) {
         return [

package/dist/setup/plan.mjs

@@ -33,6 +33,8 @@ export function planSetup(env, opts = {}) {
         picked = names.filter((a) => SETUP_AGENTS[a].detect?.(env, home) ?? existsSync(path.join(home, SETUP_AGENTS[a].home)));
         if (picked.length === 0)
             die(`Found no agent to set up. Pass --agent ${names.join('|')}`);
+        if (opts.only)
+            picked = picked.filter((a) => opts.only.includes(a));
     }
     else if (names.includes(opts.agent)) {
         picked = [opts.agent];
@@ -55,8 +57,8 @@ export function planSetup(env, opts = {}) {
     }
     if (provider === true && !resolveApiKey(env)) {
         if (!opts.guided)
-            die('No API key to give the agents. Run: phantom login', 'no_key');
-        notes.push('No Phantom AI key yet, so only the skills are installed. Run phantom login, then phantom setup again.');
+            die('No Phantom key yet to give the agents. Run phantom login to sign in, then run this again.', 'no_key');
+        notes.push('No Phantom key yet, so only the skills are installed. Run phantom setup in a terminal to sign in and set up the rest.');
         provider = false;
     }
     const ctx = { env, home, onPath: opts.onPath, model: opts.model, shellRc: shellRcFile(env, home) };

package/dist/setup/screen.mjs

@@ -0,0 +1,237 @@
+// How `phantom setup` looks in a terminal, drawn in the site's style: the
+// ghost and a title, an uppercase caption over a thin rule, one row per agent
+// with its files lined up in columns, and after the changes a ✓ per agent and
+// the next step in corner brackets, like the site's hero.
+// The JSON result (setupCommand without a terminal) never goes through here.
+import os from 'node:os';
+import path from 'node:path';
+import { paint, unstyled } from "../core/style.mjs";
+import { brandHeader } from "../core/brand.mjs";
+import { inApp } from "../cli/screens.mjs";
+import { SETUP_AGENTS } from "./agents.mjs";
+/** `text` broken at spaces into lines of at most `width` characters; a single longer word stays whole. */
+export function wrapWords(text, width) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(' ')) {
+        if (line && (line + ' ' + word).length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? line + ' ' + word : word;
+    }
+    return [...lines, line];
+}
+/** The name a person knows an agent by: "Claude Code", or "Your shell" for the startup file. */
+const label = (agent) => (agent === 'shell' ? 'Your shell' : (SETUP_AGENTS[agent]?.label ?? agent));
+/** How many lines a diff from `lineDiff` adds and removes. */
+function counts(diff) {
+    const rows = (diff ?? '').split('\n');
+    return { added: rows.filter((r) => r.startsWith('+')).length, removed: rows.filter((r) => r.startsWith('-')).length };
+}
+/** An uppercase caption over a thin rule, like the site's section labels (SPEND, CALLS). */
+function caption(p, text, extra, width) {
+    return [`  ${p.bold(text)}  ${extra}`.trimEnd(), `  ${p.dim('─'.repeat(width))}`];
+}
+/** Text framed by corner brackets, the site's hero frame, for the one thing to do next. */
+function framed(p, text, columns) {
+    const inner = unstyled(text).length + 4;
+    // Too wide for the window: the corners would wrap away from the text, so it's a plain line instead.
+    if (columns && inner + 4 > columns)
+        return [`  ${text}`];
+    return [`  ${p.lime('┌')}${' '.repeat(inner)}${p.lime('┐')}`, `     ${text}`, `  ${p.lime('└')}${' '.repeat(inner)}${p.lime('┘')}`];
+}
+/** `phantom setup`'s screen for one result. See {@link ScreenMode} for the moments it shows. */
+export function setupScreen(r, opts = {}) {
+    const env = opts.env ?? {};
+    const color = Boolean(opts.color);
+    const p = paint(env, color);
+    const mode = opts.mode ?? (r.dry_run ? 'dry' : r.applied === false ? 'declined' : 'done');
+    // The list is already on screen above the question, so a no only needs saying.
+    if (mode === 'declined')
+        return '\n  Nothing was changed.';
+    const home = env.HOME || os.homedir();
+    const short = (file) => (file === home || file.startsWith(home + path.sep) ? '~' + file.slice(home.length) : file);
+    // Rows run in the order setup found the agents, then the shell file last.
+    const agents = [...r.agents.map((a) => a.agent), ...(r.files.some((f) => f.agent === 'shell') ? ['shell'] : [])];
+    const skipped = (r.skipped ?? []).filter((s) => !agents.includes(s.agent));
+    const names = [...agents, ...skipped.map((s) => s.agent)];
+    const width = Math.max(12, ...names.map((a) => label(a).length + 2));
+    const pad = ' '.repeat(width + 4);
+    const name = (agent) => p.bold(label(agent).padEnd(width));
+    // Every path is padded to the longest, so the line counts form one column,
+    // unless that's wider than the window: then rows stay short and unaligned.
+    const longest = Math.max(0, ...r.files.map((f) => short(f.file).length));
+    const columns = opts.columns ?? process.stdout.columns ?? 100;
+    const fits = width + 4 + 10 + longest + 2 + 8 + 4 <= columns;
+    const pathWidth = fits ? longest : 0;
+    // As wide as a file row (name, kind, path, action and a line count), and never wider than the window.
+    const rule = Math.max(20, Math.min(width + 2 + 10 + longest + 2 + 8 + 4, columns - 4));
+    // After the prompt, a blank line sets the result apart from the answer typed above it.
+    const lines = [''];
+    const found = r.agents.length;
+    if (mode !== 'done') {
+        lines.push(...brandHeader(p, color, 'setup'), ...caption(p, 'AGENTS FOUND', p.lime(p.bold(String(found))), rule));
+    }
+    else {
+        lines.push(...caption(p, 'DONE', '', rule));
+    }
+    for (const agent of agents) {
+        const a = r.agents.find((x) => x.agent === agent);
+        // The agent's settings before its skill: the settings are what change how it runs.
+        const files = r.files.filter((f) => f.agent === agent).sort((x, y) => Number(!x.diff) - Number(!y.diff));
+        const skip = (r.skipped ?? []).filter((s) => s.agent === agent);
+        const manual = a?.provider?.manual ?? [];
+        const warnings = a?.provider?.warnings ?? [];
+        const detail = [];
+        if (mode === 'done') {
+            // Turning Phantom off for an agent that was never on changed nothing, so it gets no check mark.
+            const unchanged = !files.length && a?.provider && !a.provider.on;
+            const mark = skip.length ? p.red('✗') : manual.length ? p.yellow('!') : unchanged ? p.dim('·') : p.lime('✓');
+            lines.push(`  ${mark} ${name(agent)}${doneSummary(agent, a, files.length, skip.length > 0, p)}`);
+        }
+        else {
+            // The files first, so the eye reads down one column of paths.
+            const [first, ...rest] = files.map((f) => fileRow(f, p, short, pathWidth));
+            lines.push(`    ${name(agent)}${first ?? p.dim(manual.length ? 'nothing to write' : 'already set up')}`);
+            for (const row of rest)
+                detail.push(pad + row);
+            if (opts.diff) {
+                for (const f of files.filter((x) => x.diff)) {
+                    detail.push('', ...f.diff.split('\n').map((row) => pad + '  ' + diffRow(row, p)), '');
+                }
+            }
+        }
+        for (const s of skip)
+            detail.push(pad + p.red(`skipped: ${s.reason}`));
+        for (const w of warnings)
+            detail.push(pad + p.yellow(w));
+        // Steps to do by hand show once, after the changes, when they can be done.
+        if (manual.length && mode !== 'done')
+            detail.push(pad + p.yellow(`then a few steps by hand in ${a?.provider?.settings}, shown after`));
+        else if (manual.length) {
+            detail.push(pad + p.yellow(`In ${a?.provider?.settings}:`));
+            // Each step wraps under its own first word, not under the number.
+            const room = Math.max(30, (opts.columns ?? 100) - pad.length - 5);
+            manual.forEach((step, k) => {
+                const [first, ...rest] = wrapWords(step, room);
+                detail.push(`${pad}  ${p.dim(`${k + 1}.`)} ${first}`, ...rest.map((l) => `${pad}     ${l}`));
+            });
+        }
+        lines.push(...detail);
+    }
+    for (const s of skipped)
+        lines.push(`  ${mode === 'done' ? p.red('✗') + ' ' : '  '}${name(s.agent)}${p.red(`skipped: ${s.reason}`)}`);
+    const notes = r.notes ?? [];
+    if (notes.length)
+        lines.push('', ...notes.map((n) => `  ${n}`));
+    if (mode === 'ask' || mode === 'dry') {
+        // The file list says where; these lines say what it means, in plain words, before anyone reads a diff.
+        const routes = r.files.some((f) => f.diff && f.agent !== 'shell');
+        const skills = r.files.some((f) => !f.diff);
+        if (routes || skills)
+            lines.push('');
+        if (routes) {
+            lines.push(`  ${p.dim('What this does:')} these agents send their model requests to Phantom AI, and phantom-1 picks the model.`);
+            lines.push(`  ${p.dim('Nothing is bought:')} phantom-1 runs free until you add credit.`);
+        }
+        if (skills)
+            lines.push(`  ${p.dim('skill:')} a short note that teaches the agent the phantom commands.`);
+        // Most people only see the 'ask' screen, so its hint is the plain command they just ran, plus --diff.
+        if (!opts.diff && opts.hint !== false && r.files.some((f) => f.diff)) {
+            lines.push('', mode === 'ask' ? `  To see every line first, answer n and run: ${p.cyan('phantom setup --diff')}` : `  To see every line, add ${p.cyan('--diff')}.`);
+        }
+        if (mode === 'dry')
+            lines.push(p.dim('  This was a preview. Nothing was changed.'));
+    }
+    else if (!r.files.length && !(r.skipped ?? []).length && !r.agents.some((a) => a.provider?.manual?.length)) {
+        const off = r.agents.length > 0 && r.agents.every((a) => a.provider && !a.provider.on);
+        lines.push(off ? `  ${p.dim('·')} Phantom AI was already off for these agents. Nothing to change.` : `  ${p.lime('✓')} Everything is already set up. Nothing to change.`);
+    }
+    else if (r.files.length) {
+        lines.push('', ...nextStep(r, p, opts.columns));
+        lines.push('', inApp() ? `  ${p.dim('Undo any time: More, then Undo setup.')}` : `  Undo any time: ${p.cyan('phantom setup --restore')}`);
+    }
+    return lines.join('\n');
+}
+/** What a file is, in the words the screen uses: its settings (an agent's, or the shell's ~/.zshrc), or its skill. */
+function kind(f) {
+    if (!f.diff)
+        return 'skill';
+    // ~/.zshrc is the shell's own settings file, and the row already says "Your shell".
+    return 'settings';
+}
+/** What happens to a file, in one short word. */
+const ACTION = { create: 'new', update: 'update', remove: 'remove' };
+/**
+ * One file under an agent, in columns: what the file is, where it is, what
+ * happens to it, and how many lines change. For example
+ * `settings  ~/.codex/config.toml  new  +12`.
+ */
+function fileRow(f, p, short, pathWidth) {
+    const action = ACTION[f.action].padEnd(6);
+    const { added, removed } = counts(f.diff);
+    const change = [added ? p.green(`+${added}`) : '', removed ? p.red(`-${removed}`) : ''].filter(Boolean).join(' ');
+    return [
+        p.dim(kind(f).padEnd(8)),
+        short(f.file).padEnd(pathWidth),
+        f.action === 'remove' ? p.red(action) : p.cyan(action),
+        change + (f.backup ? p.dim('  copy kept') : ''),
+    ]
+        .join('  ')
+        .trimEnd();
+}
+/** One line of a diff, colored by whether it adds, removes or only shows context. */
+function diffRow(row, p) {
+    if (row.startsWith('+'))
+        return p.green(row);
+    if (row.startsWith('-'))
+        return p.red(row);
+    return p.dim(row);
+}
+/** After the changes: one plain sentence per agent on what it does now. */
+function doneSummary(agent, a, files, skipped, p) {
+    if (skipped)
+        return p.red('left as it was.');
+    if (agent === 'shell')
+        return 'loads your Phantom AI key in new terminals.';
+    const prov = a?.provider;
+    if (prov?.manual?.length)
+        return p.yellow('not finished: 2 minutes by hand:');
+    if (prov && !prov.on)
+        return !files ? p.dim('already off: nothing to remove.') : agent === 'claude' ? 'back on Anthropic.' : 'Phantom AI settings removed.';
+    if (prov?.on) {
+        const model = prov.model ? ` ${p.pill(` ${prov.model} `)}` : '';
+        return `runs on Phantom AI${model}  ${p.dim(`restart ${label(agent)} to pick it up`)}`;
+    }
+    return files ? 'skill installed.' : p.dim('already set up.');
+}
+/** The command that starts each agent that runs in a terminal. Editors (Cursor, Continue, Cline) are opened, not run. */
+const START = { claude: 'claude', codex: 'codex', pi: 'pi', opencode: 'opencode', goose: 'goose', aider: 'aider', copilot: 'copilot' };
+/**
+ * The one thing to do after setup, in corner brackets: run the agent. When an
+ * agent reads its key from the shell (Codex, Goose and others), the step says
+ * to open a new terminal first, and names that agent; otherwise it doesn't.
+ */
+function nextStep(r, p, columns) {
+    const on = r.agents.filter((a) => a.provider?.on || (!a.provider && r.files.some((f) => f.agent === a.agent)));
+    const shell = r.files.some((f) => f.agent === 'shell');
+    const readsShell = on.filter((a) => SETUP_AGENTS[a.agent]?.shellEnv);
+    const first = (readsShell.length && shell ? readsShell : on).find((a) => START[a.agent]) ?? on[0];
+    if (!first)
+        return [];
+    const cmd = START[first.agent];
+    const name = label(first.agent);
+    const step = cmd
+        ? shell && readsShell.some((a) => a.agent === first.agent)
+            ? `${p.lime('→')} ${p.bold('Open a new terminal')}, then run ${p.cyan(cmd)}`
+            : `${p.lime('→')} ${p.bold('Next:')} run ${p.cyan(cmd)}`
+        : `${p.lime('→')} ${p.bold('Next:')} open ${name}`;
+    const lines = framed(p, step, columns);
+    if (cmd && ['claude', 'codex', 'pi'].includes(first.agent))
+        lines.push(p.dim(`     or start it through phantom: phantom ${first.agent}`));
+    if (shell && readsShell.length)
+        lines.push(p.dim(`     ${readsShell.map((a) => label(a.agent)).join(', ')} ${readsShell.length === 1 ? 'reads' : 'read'} your Phantom AI key from the shell, so a new terminal is needed.`));
+    return lines;
+}