@assethub/cli 0.1.33 → 0.1.36

package/dist/setupCommand.js

@@ -1,11 +1,14 @@
 import { execFile } from 'node:child_process';
 import { constants } from 'node:fs';
-import { access, copyFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
+import { access, copyFile, mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { delimiter, dirname, join } from 'node:path';
 import { API_KEY_ENV, launchAgentPath, launchAgentPlist, loadKeyIntoLaunchd, readLaunchdKey } from './appEnv.js';
 import { hookScopeError, sessionSaveDisclosure } from './hooks/install.js';
-import { mcpConfig } from './setup.js';
+import { agentSpec, cliHome, detectAgents, installAgentSkills, mcpServerEntry, mergeJsonServer, readJsonServer, } from './agentSetup.js';
+import { cliVersion, mcpConfig, validatedBaseUrl } from './setup.js';
+// The steps `--only` and `--skip` name, in the order setup runs them. `agents`
+// is not one: the mcp and skills steps need it.
+export const SETUP_STEPS = ['login', 'workspace', 'mcp', 'skills', 'auto-update', 'app-env', 'hook', 'doctor'];
 export const redactKey = (key) => `ah_…${key.slice(-4)}`;
 const scrub = (text, key) => key ? text.split(key).join(redactKey(key)) : text;
 const TOML_HEADER = /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/;
@@ -107,15 +110,48 @@ export const claudeServerConfig = (baseUrl, workspaceId) => ({
         ...(workspaceId ? { 'X-AssetHub-Workspace': workspaceId } : {}),
     },
 });
-export const claudeAddArgs = (baseUrl, workspaceId) => [
-    'mcp', 'add-json', 'assethub', JSON.stringify(claudeServerConfig(baseUrl, workspaceId)), '--scope', 'user',
+export const claudeAddArgs = (baseUrl, workspaceId, scope = 'user') => [
+    'mcp', 'add-json', 'assethub', JSON.stringify(claudeServerConfig(baseUrl, workspaceId)), '--scope', scope,
 ];
 const shellQuoteSingle = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+/** "A", "A and B", "A, B and C". */
+const listJoin = (items) => items.length <= 1 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+// How each agent's desktop app is named in restart instructions.
+const APP_NAMES = { 'claude-code': 'Claude (Cmd+Q)', codex: 'Codex', cursor: 'Cursor' };
 export const runSetup = async (options, deps) => {
     const steps = [];
     const say = (line) => deps.log(line);
-    const wantClaude = options.client !== 'codex';
-    const wantCodex = options.client !== 'claude';
+    const skipped = (step) => options.skip?.includes(step) ?? false;
+    const scope = options.project ? 'project' : 'global';
+    const root = options.project ? deps.cwd : deps.home;
+    const needsAgents = !skipped('mcp') || !skipped('skills') || !skipped('hook');
+    // 0. Agents: the ones asked for, or every one found on this machine. Nothing
+    // else is changed when there is none to configure.
+    const version = await deps.version();
+    const detected = needsAgents ? await deps.detectAgents() : [];
+    const agents = options.agents ?? detected;
+    const agentNames = agents.map(agent => agentSpec(agent).name);
+    const failEarly = (step, nextStep) => ({
+        ok: false,
+        dryRun: options.dryRun,
+        profile: '',
+        baseUrl: '',
+        version,
+        scope,
+        agents,
+        detected,
+        steps: [step],
+        nextStep,
+    });
+    // MCP needs an agent to configure; the skill copy alone does not.
+    if (!skipped('mcp') && agents.length === 0)
+        return failEarly({ name: 'agents', status: 'fail', detail: `no Claude Code, Codex or Cursor found under ${deps.home} or on PATH` }, 'Install a coding agent, or pass --agent claude-code|codex|cursor to configure one anyway.');
+    if (needsAgents && agents.length === 0)
+        steps.push({ name: 'agents', status: 'skip', detail: 'no coding agent found; the skill is installed without agent links' });
+    else if (needsAgents)
+        steps.push({ name: 'agents', status: 'ok', detail: `${listJoin(agentNames)}${options.agents ? '' : ' (detected)'}` });
+    const wantClaude = agents.includes('claude-code');
+    const wantCodex = agents.includes('codex');
     const hookClients = [...(wantClaude ? ['claude'] : []), ...(wantCodex ? ['codex'] : [])];
     const hookNames = hookClients.map(client => (client === 'claude' ? 'Claude Code' : 'Codex')).join(' and ');
     let hookRefusal;
@@ -126,59 +162,72 @@ export const runSetup = async (options, deps) => {
             break;
         }
     }
-    // 0. --save-sessions asks for something the home folder cannot have, so stop
+    // --save-sessions asks for something the home folder cannot have, so stop
     // before login, MCP or app-env changes rather than half-applying setup.
-    if (hookRefusal && options.saveSessions && !options.noHook) {
-        return {
-            ok: false,
-            dryRun: options.dryRun,
-            profile: '',
-            baseUrl: '',
-            steps: [{ name: 'hook', status: 'fail', detail: hookRefusal }],
-            nextStep: 'Run `assethub setup --save-sessions` inside the project folder whose sessions should be saved, or run it without --save-sessions.',
-        };
-    }
-    // 1. Login (reuses the existing `auth login` path through deps.login)
-    const explicitKey = options.apiKeySource === 'flag' ? options.apiKey : undefined;
-    const hadKey = explicitKey ? false : await deps.hasWorkingKey();
-    const givenKey = explicitKey ?? (options.apiKeySource === 'env' ? options.apiKey : undefined);
-    const givenFrom = explicitKey ? '--api-key' : 'ASSETHUB_API_KEY';
-    if (hadKey) {
-        steps.push({ name: 'login', status: 'ok', detail: 'reusing the saved API key' });
-    }
-    else if (options.dryRun) {
-        steps.push({
-            name: 'login',
-            status: 'skip',
-            detail: givenKey
-                ? `would verify and save the API key from ${givenFrom}`
-                : options.apiKeyStdin
-                    ? 'would read the API key from stdin'
-                    : 'would prompt for an API key',
-        });
+    if (hookRefusal && options.saveSessions && !options.noHook && !skipped('hook'))
+        return failEarly({ name: 'hook', status: 'fail', detail: hookRefusal }, 'Run `assethub setup --save-sessions` inside the project folder whose sessions should be saved, or run it without --save-sessions.');
+    // 1. Login (reuses the existing `auth login` path through deps.login). With
+    // login skipped, a saved key is still used for app-env and doctor if there is one.
+    let auth;
+    let hadKey = false;
+    if (skipped('login')) {
+        auth = await deps.resolveAuth().catch(() => undefined);
     }
     else {
-        let apiKey = givenKey;
-        if (!apiKey && !options.apiKeyStdin) {
-            if (!deps.interactive)
-                throw new Error('No saved API key. Re-run with --api-key-stdin, set ASSETHUB_API_KEY, or run interactively to be prompted.');
-            apiKey = await deps.promptApiKey();
+        const explicitKey = options.apiKeySource === 'flag' ? options.apiKey : undefined;
+        hadKey = explicitKey ? false : await deps.hasWorkingKey();
+        const givenKey = explicitKey ?? (options.apiKeySource === 'env' ? options.apiKey : undefined);
+        const givenFrom = explicitKey ? '--api-key' : 'ASSETHUB_API_KEY';
+        if (hadKey) {
+            steps.push({ name: 'login', status: 'ok', detail: 'reusing the saved API key' });
         }
-        await deps.login({ apiKey });
-        steps.push({
-            name: 'login',
-            status: 'ok',
-            detail: givenKey ? `API key from ${givenFrom} verified and saved` : 'API key verified and saved',
-        });
+        else if (options.dryRun) {
+            steps.push({
+                name: 'login',
+                status: 'skip',
+                detail: givenKey
+                    ? `would verify and save the API key from ${givenFrom}`
+                    : options.apiKeyStdin
+                        ? 'would read the API key from stdin'
+                        : 'would prompt for an API key',
+            });
+        }
+        else {
+            let apiKey = givenKey;
+            if (!apiKey && !options.apiKeyStdin) {
+                if (!deps.interactive)
+                    throw new Error('No saved API key. Re-run with --api-key-stdin, set ASSETHUB_API_KEY, or run interactively to be prompted.');
+                apiKey = await deps.promptApiKey();
+            }
+            await deps.login({ apiKey });
+            steps.push({
+                name: 'login',
+                status: 'ok',
+                detail: givenKey ? `API key from ${givenFrom} verified and saved` : 'API key verified and saved',
+            });
+        }
+        if (!options.dryRun || hadKey)
+            auth = await deps.resolveAuth();
     }
-    let auth;
-    if (!options.dryRun || hadKey)
-        auth = await deps.resolveAuth();
+    // Without a login, the saved profile still names the server and workspace.
+    const target = auth ?? (skipped('login') ? await deps.resolveTarget() : undefined);
     const key = auth?.apiKey ?? '';
-    const baseUrl = (auth?.baseUrl ?? '').replace(/\/+$/, '');
+    const baseUrl = (target?.baseUrl ?? '').replace(/\/+$/, '');
+    // Every agent entry is built from this URL: refuse a bad one before writing any of them.
+    if (baseUrl) {
+        try {
+            validatedBaseUrl(baseUrl);
+        }
+        catch (error) {
+            return failEarly({ name: 'mcp', status: 'fail', detail: `${baseUrl}: ${error instanceof Error ? error.message : String(error)}` }, 'Pass --base-url with an HTTPS origin (HTTP only for localhost), then re-run setup.');
+        }
+    }
     // 2. Workspace
-    let workspaceId = auth?.workspaceId;
-    if (options.workspace) {
+    let workspaceId = target?.workspaceId;
+    if (skipped('workspace')) {
+        workspaceId = options.workspace ?? workspaceId;
+    }
+    else if (options.workspace) {
         workspaceId = options.workspace;
         if (options.dryRun) {
             steps.push({ name: 'workspace', status: 'skip', detail: `would select workspace ${workspaceId}` });
@@ -209,114 +258,207 @@ export const runSetup = async (options, deps) => {
         auth = await deps.resolveAuth();
         steps.push({ name: 'workspace', status: 'ok', detail: `selected ${workspaceId}` });
     }
-    const workspaceForConfig = workspaceId ?? '<workspace-id>';
+    // A placeholder is shown only in a dry run that would still ask for the workspace.
+    const workspaceForConfig = workspaceId ?? (options.dryRun && !skipped('workspace') ? '<workspace-id>' : undefined);
     const shownKey = key ? redactKey(key) : 'ah_…<key>';
-    if (!options.dryRun &&
+    const writesConfig = !skipped('mcp') || !skipped('skills');
+    if (writesConfig &&
+        !options.dryRun &&
         deps.interactive &&
         !options.yes &&
-        !(await deps.confirm('Write MCP configuration for the selected client(s)?')))
-        throw new Error('Cancelled before changing any client configuration.');
-    // 3. Claude Code
-    if (wantClaude) {
+        !(await deps.confirm(`Write AssetHub configuration for ${listJoin(agentNames)}${options.project ? ` in ${deps.cwd}` : ''}?`)))
+        throw new Error('Cancelled before changing any agent configuration.');
+    // Writes a merged config file, backing up the previous one; reports "unchanged" when nothing differs.
+    const writeConfig = async (name, path, existing, merged, what, diff) => {
+        if (merged === existing) {
+            steps.push({ name, status: 'ok', detail: `${path} already up to date`, change: 'unchanged', path });
+        }
+        else if (options.dryRun) {
+            say(`[dry-run] would ${existing === undefined ? 'create' : 'update'} ${path}`);
+            if (existing !== undefined)
+                say(`[dry-run] would back up to ${path}.bak-<timestamp>`);
+            for (const line of diff)
+                say(`  ${line}`);
+            steps.push({ name, status: 'skip', detail: `would write ${what} to ${path} (dry run)`, change: 'would-update', path });
+        }
+        else {
+            let backup = '';
+            if (existing !== undefined) {
+                // Never overwrite an earlier backup made in the same instant, even by
+                // another setup running at the same time: the copy refuses an existing name.
+                const base = `${path}.bak-${timestamp(deps.now())}`;
+                for (let n = 0;; n++) {
+                    backup = n === 0 ? base : `${base}-${n}`;
+                    if ((await deps.readFileIfExists(backup)) !== undefined)
+                        continue;
+                    try {
+                        await deps.backupFile(path, backup);
+                        break;
+                    }
+                    catch (error) {
+                        if (error.code !== 'EEXIST')
+                            throw error;
+                    }
+                }
+            }
+            await deps.writeFileEnsuringDir(path, merged);
+            steps.push({ name, status: 'ok', detail: `wrote ${what} to ${path}${backup ? ` (backup: ${backup})` : ''}`, change: 'updated', path });
+        }
+    };
+    // 3. MCP: one writer per agent. Claude Code owns ~/.claude.json, so it is
+    // changed through `claude mcp` and read only to skip an identical entry. When
+    // `claude` is not on PATH (an IDE extension bundles its own), the same entry is
+    // written into the same file directly, as `claude mcp add-json` would.
+    if (!skipped('mcp') && wantClaude) {
+        const claudeScope = options.project ? 'project' : 'user';
+        const configPath = options.project ? join(deps.cwd, '.mcp.json') : join(deps.home, '.claude.json');
+        const desired = claudeServerConfig(baseUrl || '<base-url>', workspaceForConfig);
+        const configText = await deps.readFileIfExists(configPath);
+        const current = readJsonServer(configText);
         const claude = await deps.findBinary('claude');
-        const args = claudeAddArgs(baseUrl || '<base-url>', workspaceForConfig);
+        const args = claudeAddArgs(baseUrl || '<base-url>', workspaceForConfig, claudeScope);
         const shown = `claude ${args.slice(0, 3).join(' ')} ${shellQuoteSingle(args[3])} ${args.slice(4).join(' ')}`;
-        if (!claude) {
-            say(`claude not found on PATH. Run this later:\n  ${shown}`);
-            // Claude was the only client asked for, so nothing got configured: say so
-            // in the exit code rather than reporting success.
-            steps.push({
-                name: 'claude-mcp',
-                status: wantCodex ? 'skip' : 'fail',
-                detail: 'claude CLI not found; run the printed command later',
-            });
+        if (JSON.stringify(current) === JSON.stringify(desired)) {
+            steps.push({ name: 'claude-mcp', status: 'ok', detail: `assethub is already registered in Claude Code (${claudeScope} scope)`, change: 'unchanged', path: configPath });
+        }
+        else if (!claude && !baseUrl) {
+            // Nothing real to write yet (a dry run before login): show the command instead.
+            say(`claude not found on PATH. Setup will write ${configPath} directly, or run:\n  ${shown}`);
+            steps.push({ name: 'claude-mcp', status: 'skip', detail: `would write mcpServers.assethub to ${configPath} (dry run)`, change: 'would-update', path: configPath });
+        }
+        else if (!claude) {
+            let merged;
+            try {
+                merged = mergeJsonServer(configPath, configText, desired);
+            }
+            catch (error) {
+                say(`Run this once ${configPath} is fixed:\n  ${shown}`);
+                steps.push({ name: 'claude-mcp', status: 'fail', detail: `${configPath} left unchanged: ${error instanceof Error ? error.message : String(error)}`, path: configPath });
+            }
+            if (merged !== undefined)
+                await writeConfig('claude-mcp', configPath, configText, merged, 'mcpServers.assethub directly (claude CLI not on PATH)', sectionDiff(current === undefined ? '' : JSON.stringify(current, null, 2), JSON.stringify(desired, null, 2)));
         }
         else if (options.dryRun) {
             say(`[dry-run] ${shown}`);
-            say('[dry-run] if an assethub entry already exists: claude mcp remove assethub --scope user, then add again');
-            steps.push({ name: 'claude-mcp', status: 'skip', detail: 'would register the assethub MCP server (dry run)' });
+            if (current !== undefined)
+                say(`[dry-run] the existing assethub entry would be replaced: claude mcp remove assethub --scope ${claudeScope}, then add again`);
+            steps.push({ name: 'claude-mcp', status: 'skip', detail: 'would register the assethub MCP server (dry run)', change: 'would-update', path: configPath });
         }
         else {
             // Add first, and replace only an entry that already exists, so a failing
             // add never costs the user a working one.
-            const addArgs = claudeAddArgs(baseUrl, workspaceForConfig);
-            let added = await deps.run(claude, addArgs);
+            let added = await deps.run(claude, args);
             let replaced = false;
+            let restored;
+            let removeFailure;
             if (added.code !== 0 && /already exists/i.test(added.output)) {
-                await deps.run(claude, ['mcp', 'remove', 'assethub', '--scope', 'user']);
-                replaced = true;
-                added = await deps.run(claude, addArgs);
+                const removed = await deps.run(claude, ['mcp', 'remove', 'assethub', '--scope', claudeScope]);
+                if (removed.code !== 0) {
+                    removeFailure = scrub(removed.output, key).trim().slice(0, 300);
+                }
+                else {
+                    replaced = true;
+                    added = await deps.run(claude, args);
+                    // Put the previous entry back rather than leave Claude Code without one.
+                    if (added.code !== 0 && current !== undefined)
+                        restored =
+                            (await deps.run(claude, ['mcp', 'add-json', 'assethub', JSON.stringify(current), '--scope', claudeScope]))
+                                .code === 0;
+                }
             }
             const failure = scrub(added.output, key).trim().slice(0, 300);
-            steps.push(added.code === 0
+            steps.push(removeFailure !== undefined
                 ? {
-                    name: 'claude-mcp',
-                    status: 'ok',
-                    detail: `registered assethub in Claude Code (user scope; it reads the key from \$${API_KEY_ENV}, the key is not stored in Claude Code)`,
-                }
-                : {
                     name: 'claude-mcp',
                     status: 'fail',
-                    detail: replaced
-                        ? `claude mcp add failed after the old assethub entry was removed; run \`${shown}\` to restore it: ${failure}`
-                        : `claude mcp add failed: ${failure}`,
-                });
+                    detail: `the existing assethub entry was left as it is: claude mcp remove failed: ${removeFailure}`,
+                    path: configPath,
+                }
+                : added.code === 0
+                    ? {
+                        name: 'claude-mcp',
+                        status: 'ok',
+                        detail: `registered assethub in Claude Code (${claudeScope} scope; it reads the key from \$${API_KEY_ENV}, the key is not stored in Claude Code)`,
+                        change: 'updated',
+                        path: configPath,
+                    }
+                    : {
+                        name: 'claude-mcp',
+                        status: 'fail',
+                        detail: !replaced
+                            ? `claude mcp add failed: ${failure}`
+                            : restored
+                                ? `claude mcp add failed, so the previous assethub entry was put back: ${failure}`
+                                : `claude mcp add failed after the old assethub entry was removed; run \`${shown}\` to add it again: ${failure}`,
+                        path: configPath,
+                    });
         }
     }
-    // 4. Codex
-    let exportLine;
-    if (wantCodex) {
-        const path = join(deps.codexHome, 'config.toml');
+    if (!skipped('mcp') && wantCodex) {
+        const path = options.project ? join(deps.cwd, '.codex', 'config.toml') : join(deps.codexHome, 'config.toml');
         const section = mcpConfig('codex', baseUrl || 'https://app.assethub.io', false, workspaceId);
         const existing = await deps.readFileIfExists(path);
         let merged;
-        let mergeError;
         try {
             merged = mergeCodexSection(existing ?? '', section);
         }
         catch (error) {
-            mergeError = error instanceof Error ? error.message : String(error);
+            steps.push({ name: 'codex-mcp', status: 'fail', detail: `${path} left unchanged: ${error instanceof Error ? error.message : String(error)}`, path });
         }
-        if (merged === undefined) {
-            steps.push({ name: 'codex-mcp', status: 'fail', detail: `${path} left unchanged: ${mergeError}` });
+        if (merged !== undefined)
+            await writeConfig('codex-mcp', path, existing, merged, '[mcp_servers.assethub]', sectionDiff(extractCodexSection(existing ?? ''), extractCodexSection(merged)));
+    }
+    if (!skipped('mcp') && agents.includes('cursor')) {
+        const path = join(root, '.cursor', 'mcp.json');
+        const existing = await deps.readFileIfExists(path);
+        const entry = mcpServerEntry('cursor', baseUrl || 'https://app.assethub.io', workspaceId);
+        let merged;
+        try {
+            merged = mergeJsonServer(path, existing, entry);
         }
-        else if (options.dryRun) {
-            say(`[dry-run] would ${existing === undefined ? 'create' : 'update'} ${path}`);
-            if (existing !== undefined)
-                say(`[dry-run] would back up to ${path}.bak-<timestamp>`);
-            for (const line of sectionDiff(extractCodexSection(existing ?? ''), extractCodexSection(merged)))
-                say(`  ${line}`);
-            steps.push({ name: 'codex-mcp', status: 'skip', detail: `would write [mcp_servers.assethub] to ${path} (dry run)` });
+        catch (error) {
+            steps.push({ name: 'cursor-mcp', status: 'fail', detail: `${path} left unchanged: ${error instanceof Error ? error.message : String(error)}`, path });
         }
-        else if (merged === existing) {
-            steps.push({ name: 'codex-mcp', status: 'ok', detail: `${path} already up to date` });
-        }
-        else {
-            let backup = '';
-            if (existing !== undefined) {
-                // Never overwrite an earlier backup made in the same instant.
-                const base = `${path}.bak-${timestamp(deps.now())}`;
-                backup = base;
-                for (let n = 1; (await deps.readFileIfExists(backup)) !== undefined; n++)
-                    backup = `${base}-${n}`;
-                await deps.backupFile(path, backup);
-            }
-            await deps.writeFileEnsuringDir(path, merged);
-            steps.push({ name: 'codex-mcp', status: 'ok', detail: `wrote [mcp_servers.assethub] to ${path}${backup ? ` (backup: ${backup})` : ''}` });
+        if (merged !== undefined) {
+            const before = readJsonServer(existing);
+            await writeConfig('cursor-mcp', path, existing, merged, 'mcpServers.assethub', sectionDiff(before === undefined ? '' : JSON.stringify(before, null, 2), JSON.stringify(entry, null, 2)));
         }
     }
-    // Both clients read the key from the environment; the MCP server needs nothing else.
-    say(`${wantClaude && wantCodex ? 'Claude Code and Codex read' : wantClaude ? 'Claude Code reads' : 'Codex reads'} the key from the ${API_KEY_ENV} environment variable: export it in your shell (run \`assethub setup --print-env\` to print the line). Setup never writes it to a shell profile.`);
+    // Every agent reads the key from the environment; the MCP server needs nothing else.
+    if (!skipped('mcp'))
+        say(`${listJoin(agentNames)} ${agents.length > 1 ? 'read' : 'reads'} the key from the ${API_KEY_ENV} environment variable: export it in your shell (run \`assethub setup --print-env\` to print the line). Setup never writes it to a shell profile.`);
+    let exportLine;
     if (options.printEnv)
         exportLine = `export ${API_KEY_ENV}=${options.dryRun || !key ? shownKey : key}`;
+    // 4. Skill: one copy under <root>/.agents/skills, linked into each agent.
+    let skill;
+    if (!skipped('skills')) {
+        try {
+            skill = await deps.installSkills({ root, agents, dryRun: options.dryRun });
+            steps.push(skillsStep(skill, options.dryRun));
+        }
+        catch (error) {
+            steps.push({ name: 'skills', status: 'fail', detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    // 4b. Auto-update: on by default; shown so nobody is surprised by it.
+    if (!skipped('auto-update')) {
+        try {
+            steps.push(await autoUpdateStep(options, deps));
+        }
+        catch (error) {
+            steps.push({ name: 'auto-update', status: 'fail', detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
     // 5. Make the key visible to apps started outside a shell (macOS).
-    const appEnv = await ensureAppEnv(options, deps, key);
-    steps.push(appEnv);
+    const appEnv = skipped('app-env') ? undefined : await ensureAppEnv(options, deps, key);
+    if (appEnv)
+        steps.push(appEnv);
     // 6. Session saving: opt-in, and offered only to accounts that may upload
     // sessions (internal for now). Anyone else gets no question and no step.
-    const sessionsAvailable = auth != null && (await deps.canSaveSessions(auth));
+    const sessionsAvailable = !skipped('hook') && hookClients.length > 0 && auth != null && (await deps.canSaveSessions(auth));
     if (!sessionsAvailable) {
-        if (options.saveSessions)
+        if (options.saveSessions && !skipped('hook'))
             steps.push({ name: 'hook', status: 'skip', detail: 'session saving is not available for this account' });
     }
     else if (options.noHook) {
@@ -383,7 +525,10 @@ export const runSetup = async (options, deps) => {
         }
     }
     // 7. Doctor
-    if (options.dryRun) {
+    if (skipped('doctor')) {
+        // left out on request
+    }
+    else if (options.dryRun) {
         steps.push({ name: 'doctor', status: 'skip', detail: 'skipped (dry run)' });
     }
     else {
@@ -403,24 +548,78 @@ export const runSetup = async (options, deps) => {
         }
     }
     const ok = steps.every(step => step.status !== 'fail');
+    const apps = listJoin(agents.map(agent => APP_NAMES[agent]));
     const nextStep = options.dryRun
         ? 'Re-run without --dry-run to apply these changes.'
         : !ok
             ? 'Fix the failed steps above, then re-run `assethub setup` (it is safe to repeat).'
-            : appEnv.status === 'ok'
-                ? `Quit and reopen ${wantClaude && wantCodex ? 'Claude (Cmd+Q) and Codex' : wantClaude ? 'Claude (Cmd+Q)' : 'Codex'} so it reads ${API_KEY_ENV}, then ask it to use the AssetHub tools. Terminal tabs opened before setup still need \`export ${API_KEY_ENV}=…\`.`
-                : `Export ${API_KEY_ENV} in the shell that starts ${wantClaude && wantCodex ? 'Claude Code / Codex' : wantClaude ? 'Claude Code' : 'Codex'}, restart it, then ask it to use the AssetHub tools.`;
+            : skipped('mcp')
+                ? agents.length > 0
+                    ? `Restart ${listJoin(agentNames)} so ${agents.length > 1 ? 'they reload their' : 'it reloads its'} skills.`
+                    : 'Done.'
+                : appEnv?.status === 'ok'
+                    ? `Quit and reopen ${apps} so it reads ${API_KEY_ENV}, then ask it to use the AssetHub tools. Terminal tabs opened before setup still need \`export ${API_KEY_ENV}=…\`.`
+                    : `Export ${API_KEY_ENV} in the shell that starts ${agentNames.join(' / ')}, restart it, then ask it to use the AssetHub tools.`;
     return {
         ok,
         dryRun: options.dryRun,
         profile: auth?.profile ?? '',
         baseUrl,
         workspaceId,
+        version,
+        scope,
+        agents,
+        detected,
+        ...(skill ? { skill } : {}),
         steps,
         nextStep,
         ...(exportLine ? { exportLine } : {}),
     };
 };
+const autoUpdateStep = async (options, deps) => {
+    const name = 'auto-update';
+    const saved = await deps.readAutoUpdate();
+    const wanted = options.autoUpdate ?? saved ?? true;
+    const changes = options.autoUpdate !== undefined && options.autoUpdate !== (saved ?? true);
+    const onText = 'on: once a day a newer CLI installs itself in the background, keeping your login (turn off: `assethub setup --no-auto-update`)';
+    const offText = 'off: run `assethub update` yourself (turn on: `assethub setup --auto-update`)';
+    if (changes && options.dryRun)
+        return { name, status: 'skip', detail: `would turn auto-update ${wanted ? 'on' : 'off'} (dry run)`, change: 'would-update' };
+    if (options.autoUpdate !== undefined && options.autoUpdate !== saved)
+        await deps.writeAutoUpdate(options.autoUpdate);
+    const change = changes ? 'updated' : 'unchanged';
+    if (!wanted)
+        return { name, status: 'ok', detail: offText, change };
+    if (!(await deps.canSelfUpdate()))
+        return { name, status: 'skip', detail: 'this CLI is not a global install (npx or a source checkout), so it cannot update itself', change };
+    if (deps.autoUpdateBlockedByEnv)
+        return { name, status: 'skip', detail: 'on, but ASSETHUB_NO_AUTO_UPDATE, ASSETHUB_NO_UPDATE_CHECK or CI turns it off in this environment', change };
+    return { name, status: 'ok', detail: onText, change };
+};
+const skillsStep = (report, dryRun) => {
+    const changedLinks = report.links.filter(link => link.status === 'linked' || link.status === 'relinked');
+    const keptLinks = report.links.filter(link => link.status === 'kept-existing');
+    const copyChanged = report.status === 'installed' || report.status === 'updated';
+    const changed = copyChanged || changedLinks.length > 0;
+    const parts = [
+        report.status === 'kept-existing'
+            ? `kept ${report.path} (not created by AssetHub)`
+            : report.status === 'kept-newer'
+                ? `kept ${report.path} (${report.version}, newer than this CLI)`
+                : `${dryRun && copyChanged ? `would ${report.status === 'installed' ? 'install' : 'update'}` : report.status} ${report.path}${report.version ? ` (${report.version})` : ''}`,
+        ...(changedLinks.length > 0
+            ? [`${dryRun ? 'would link' : 'linked'} into ${listJoin(changedLinks.map(link => agentSpec(link.agent).name))}`]
+            : []),
+        ...keptLinks.map(link => `kept ${link.path} (not created by AssetHub)`),
+    ];
+    return {
+        name: 'skills',
+        path: report.path,
+        status: dryRun && changed ? 'skip' : 'ok',
+        detail: changed || report.links.length === 0 ? parts.join('; ') : `${parts.join('; ')}; links already in place`,
+        change: !changed ? 'unchanged' : dryRun ? 'would-update' : 'updated',
+    };
+};
 const APP_ENV_MISSING = `Claude and Codex apps cannot see ${API_KEY_ENV} yet, so their MCP calls get HTTP 401`;
 const ensureAppEnv = async (options, deps, key) => {
     const name = 'app-env';
@@ -492,11 +691,14 @@ export const runProcess = (file, args) => new Promise(done => {
 });
 export const defaultFileDeps = () => ({
     platform: process.platform,
-    home: homedir(),
+    home: cliHome(),
     cwd: process.cwd(),
-    codexHome: process.env.CODEX_HOME?.trim() || join(homedir(), '.codex'),
+    codexHome: process.env.CODEX_HOME?.trim() || join(cliHome(), '.codex'),
     now: () => new Date(),
     findBinary: (name) => findOnPath(name),
+    detectAgents: () => detectAgents(cliHome(), name => findOnPath(name), process.env.CODEX_HOME?.trim() || undefined),
+    version: cliVersion,
+    installSkills: installAgentSkills,
     run: runProcess,
     readFileIfExists: async (path) => {
         try {
@@ -508,11 +710,22 @@ export const defaultFileDeps = () => ({
             throw error;
         }
     },
+    // Written beside the target and renamed over it, so an interrupted setup never
+    // leaves a truncated config. A symlinked config (dotfiles) is replaced at its target.
     writeFileEnsuringDir: async (path, content) => {
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, content);
+        const target = await realpath(path).catch(() => path);
+        await mkdir(dirname(target), { recursive: true });
+        const temporary = `${target}.assethub-${process.pid}-${Date.now()}.tmp`;
+        try {
+            await writeFile(temporary, content, { mode: await stat(target).then(info => info.mode & 0o777, () => 0o644) });
+            await rename(temporary, target);
+        }
+        catch (error) {
+            await rm(temporary, { force: true });
+            throw error;
+        }
     },
-    backupFile: (from, to) => copyFile(from, to),
+    backupFile: (from, to) => copyFile(from, to, constants.COPYFILE_EXCL),
 });
 // ---- interactive prompts (TTY only; prompts go to stderr so stdout stays clean) ----
 export const promptLine = async (question) => {