foundry-design 0.2.0-beta.1 → 0.2.0-beta.10

package/README.md

@@ -4,35 +4,82 @@ Foundry is a local-first precision design workbench for Codex, Cursor, and Claud
 
 ## Beta installation
 
-Foundry `0.2.0-beta.1` is the first shareable beta. From the project you want to inspect, run:
+Foundry is distributed through npm, so testers do not need GitHub access.
+
+> **Current public beta:** `0.2.0-beta.10`. Both npm `latest` and `beta` point to the same tested release. Use the unqualified command below for normal installation.
+
+Full documentation is available at [withfoundry.ai](https://withfoundry.ai).
+
+### Recommended: one command
+
+Open a terminal in the project, or ask Codex, Cursor, or Claude Code to run:
+
+```bash
+npx foundry-design
+```
+
+That command detects the project and active coding agent, installs or safely updates Foundry, repairs the shared agent connection, validates its integration, starts the project when needed, and opens the visual session. Before changing local configuration, Foundry prints the exact CLI and MCP bridge versions it will use. On the first installation only, restart the coding agent once so it can load the shared MCP connection. A reviewed batch can be queued before the restart and will be claimed when the agent reconnects.
+
+After the restart, reopen the same project folder and ask:
+
+```text
+Start Foundry for this project and keep listening for Apply with agent requests.
+```
+
+That is the normal workflow. Foundry resumes the most recent session for the current source revision and keeps all review and apply state local.
+
+### Manual installation
+
+From the first project you want to inspect, run:
 
 ```bash
-npx foundry-design@beta setup
+npx foundry-design setup --global
+```
+
+For later projects, keep the shared agent connection and install only the development adapter:
+
+```bash
+npx foundry-design setup --agent none
+```
+
+Then restart the coding agent, reopen the same project folder, and ask:
+
+```text
+Start Foundry for this project and keep listening for Apply with agent requests.
 ```
 
-Setup detects the platform, framework, package manager, development command, and installed coding agents. It previews every file it will manage, adds development-only instrumentation for supported web frameworks, configures the selected MCP clients, and records a reversible install manifest.
+You do not need to run a second terminal command when the agent starts Foundry for you. Apply requests remain queued safely when the agent is offline. Run `npx foundry-design doctor --repair` if the connection or generated integration needs repair.
 
-Then start a session with:
+Update an existing installation with:
 
 ```bash
-npx foundry-design@beta start
+npx foundry-design update
 ```
 
-Foundry reuses an available project server or starts the detected development command, launches the loopback runtime, and opens an authenticated visual preview. Remove only Foundry-managed integration with:
+The updater refreshes checksum-matched Foundry files, agent connections, and skill bundles. It preserves and reports files changed since setup, validates the project, and rolls back the update if Foundry introduces a TypeScript or lint failure. Restart the coding agent after updating.
+
+Remove only Foundry-managed integration with:
 
 ```bash
-npx foundry-design@beta uninstall
+npx foundry-design uninstall
 ```
 
 Supported automatic web integration currently includes Next.js App Router, Vite, and plain HTML. Generic web, SwiftUI, and React Native projects receive explicit setup guidance when a safe automatic edit is not available.
 
-Codex, Cursor, and Claude Code users can alternatively install the bundled plugin from this repository. The plugin contains the Foundry skill and MCP server definition, so project setup uses `--agent none` and does not create duplicate MCP configuration.
+The npm setup above is the public beta installation path and includes the same portable skill and MCP connection used by the agent plugin bundle.
+
+If an npm mirror or existing `npx` cache reports an old tag, bypass it with a temporary cache and the exact current release:
+
+```bash
+FOUNDRY_NPX_CACHE="$(mktemp -d)"
+npx --yes --prefer-online --registry=https://registry.npmjs.org --cache "$FOUNDRY_NPX_CACHE" --package=foundry-design@0.2.0-beta.10 foundry-design
+```
 
-The beta supports Node.js 20 or newer. Read [Privacy](PRIVACY.md), [Security](SECURITY.md), and the [beta changelog](CHANGELOG.md) before using it with sensitive work.
+The beta supports Node.js 20 or newer. Read the [local-first safety model](https://withfoundry.ai/#safety) before using it with sensitive work.
 
 ## Agent plugin
 
-The portable plugin lives at `plugins/foundry-design-control`. The repository also includes marketplace manifests for Codex, Cursor, and Claude-compatible plugin import. Once installed, ask your agent:
+The portable plugin lives at `plugins/foundry-design-control`. The repository also includes marketplace manifests for Codex, Cursor, and Claude-compatible plugin import. Until public marketplace review is complete, `setup --global` installs the same reusable skill and MCP connection from npm without requiring source-repository access. Once installed, ask your agent:
 
 ```text
 Start Foundry for this project.
@@ -42,7 +89,8 @@ Foundry remains local-first. Installing the plugin does not create an account, e
 
 ## Current capabilities
 
-- Measured browser selection with overlap cycling, parent/child traversal, hover previews, and an isolated Shadow DOM inspector
+- A dedicated local design workspace with a live product canvas, equal Layers and Inspector docks, and a direct-overlay fallback when a product blocks framing
+- Measured browser selection with overlap cycling, parent/child traversal, hover previews, and isolated Shadow DOM canvas instrumentation
 - A searchable, collapsible, virtualized live layer hierarchy with mapped-source context, Shadow DOM traversal, drag reordering, and selection persistence across HMR
 - Multi-selection, measured spacing annotations, sibling-aware resize snapping, keyboard nudging, alignment, distribution, and preview undo/redo
 - A revisioned local design graph for CSS tokens, components, Storybook variants, breakpoints, themes, states, and motion presets
@@ -54,9 +102,11 @@ Foundry remains local-first. Installing the plugin does not create an account, e
 - Design Health scans for contrast, overflow and clipping, touch targets, accessible names, reduced-motion coverage, and project spacing consistency, with evidence, intentional-issue ignores, and safe corrections routed into review
 - An in-app state workbench with real viewport frames, theme switching, forced interaction states, motion controls, and contextual verification
 - Persistent, coalescing change ledger with JSON and consolidated prompt export
-- Compact in-preview review with editable approved batches and unresolved-target blocking
+- Center-workspace review with editable approved batches, grouped targets, and unresolved-target blocking
 - Persistent Apply with agent runs across Codex, Cursor, and Claude Code through MCP
+- Leased agent handoffs that safely return abandoned or interrupted claims to the queue
 - Live source, rebuild, validation, retry, and rendered-verification progress
+- Rendered verification that resumes after refresh and does not depend on Review remaining open
 - Local MCP bridge for agent access
 - Debug adapters for web, SwiftUI, and React Native on iOS Simulator
 - Verification records that compare requested and rendered values
@@ -90,7 +140,7 @@ The runtime binds to `127.0.0.1:4387`. Inspector preview changes remain temporar
 - `packages/react-native-adapter`: React Native debug bridge
 - `packages/mcp-server`: agent tools backed by the runtime
 - `packages/swiftui-adapter`: Swift package for inspectable SwiftUI views
-- `apps/inspector`: session dashboard and review surface
+- `apps/inspector`: authenticated local design workspace, canvas shell, and review surface
 - `examples/web-fixture`: end-to-end browser fixture
 
 ## Safety model

package/dist/index.js

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
+import { access, appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
 import { renderChangePrompt } from 'foundry-design-protocol';
 import { FoundryRuntime, SessionStore } from 'foundry-design-runtime';
-import { createSetupPlan, setupProject, uninstallProject, } from './installer.js';
+import { createSetupPlan, createUpdatePlan, installHostAgentIntegration, installAgentIntegration, setupProject, updateProject, uninstallProject, } from './installer.js';
 import { addSessionParams, detectPlatform } from './project.js';
 import { indexProjectDesign } from './indexer.js';
+import { startBasicPreviewProxy } from './proxy.js';
+import { FOUNDRY_VERSION, releasePreflight } from './release.js';
 const args = process.argv.slice(2);
-const command = args[0] ?? 'help';
+const command = args[0]?.startsWith('-') ? 'launch' : (args[0] ?? 'launch');
 const runtimeRepository = resolve(fileURLToPath(new URL('../../../', import.meta.url)));
 function flag(name) {
     const index = args.indexOf(name);
@@ -27,17 +30,24 @@ function printHelp() {
     console.log(`Foundry Design Control
 
 Usage:
-  foundry-design setup [--project PATH] [--agent codex,cursor,claude] [--url URL] [--yes]
+  foundry-design [--project PATH] [--url URL] [--yes] [--no-start]
+  foundry-design setup [--project PATH] [--agent codex,cursor,claude] [--global] [--url URL] [--yes]
+  foundry-design update [--project PATH] [--agent codex,cursor,claude] [--yes]
   foundry-design init <web|swiftui|react-native> [--project PATH]
-  foundry-design start [--project PATH] [--url URL] [--platform PLATFORM] [--no-open] [--no-dev]
-  foundry-design doctor [--project PATH]
+  foundry-design start [--project PATH] [--url URL] [--platform PLATFORM] [--new] [--no-open] [--no-dev]
+  foundry-design doctor [--project PATH] [--repair]
   foundry-design index [--project PATH] [--output FILE]
   foundry-design uninstall [--project PATH] [--yes]
   foundry-design export <SESSION_ID> [--format json|prompt|full] [--output FILE]
-  foundry-design install-agent <cursor|claude|codex> [--project PATH]
+  foundry-design install-agent <cursor|claude|codex> [--global | --project PATH]
 
 Foundry is local-only and never edits product source from inspector controls.`);
 }
+async function pathExists(path) {
+    return access(path)
+        .then(() => true)
+        .catch(() => false);
+}
 async function gitOutput(root, gitArgs) {
     return new Promise((resolveRevision) => {
         const child = spawn('git', gitArgs, {
@@ -106,9 +116,15 @@ function requestedAgents() {
     return [...new Set(agents)];
 }
 async function setup() {
+    console.log(`${releasePreflight('set up this project')}\n`);
     const root = projectRoot();
+    const requested = requestedAgents();
+    const sharedAgentSetup = has('--global');
+    const detectedPlan = sharedAgentSetup
+        ? await createSetupPlan(root, { agents: requested })
+        : undefined;
     const options = {
-        agents: requestedAgents(),
+        agents: sharedAgentSetup ? [] : requested,
         targetUrl: flag('--url'),
         packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
     };
@@ -116,7 +132,11 @@ async function setup() {
     console.log(`Foundry setup\n\nProject: ${root}\nPlatform: ${plan.platform}`);
     if (plan.framework)
         console.log(`Framework: ${plan.framework}`);
-    console.log(`Agent integration: ${plan.agents.length ? plan.agents.join(', ') : 'plugin-provided'}`);
+    console.log(`Agent integration: ${sharedAgentSetup
+        ? `${detectedPlan?.agents.join(', ')} (shared across projects)`
+        : plan.agents.length
+            ? plan.agents.join(', ')
+            : 'plugin-provided'}`);
     console.log('\nFiles Foundry will manage:');
     for (const path of plan.files)
         console.log(`  ${path}`);
@@ -128,14 +148,71 @@ async function setup() {
         return;
     }
     const result = await setupProject(root, options);
+    if (sharedAgentSetup) {
+        for (const agent of detectedPlan?.agents ?? []) {
+            await installHostAgentIntegration(homedir(), agent, {
+                packageRoot: options.packageRoot,
+            });
+        }
+    }
     console.log(`\n✓ Foundry configured ${result.changed.length} files.`);
+    for (const check of result.validation) {
+        const marker = check.status === 'passed' ? '✓' : check.status === 'skipped' ? '–' : '!';
+        console.log(`${marker} ${check.name}: ${check.status.replaceAll('-', ' ')}`);
+    }
+    if (result.skillDirectories.length) {
+        console.log(`✓ Installed the Foundry skill for ${result.agents.join(', ')}.`);
+    }
+    if (sharedAgentSetup && detectedPlan?.agents.length) {
+        console.log(`✓ Installed the shared Foundry connection for ${detectedPlan.agents.join(', ')}.`);
+    }
     if (result.targetUrl)
         console.log(`✓ Preview URL: ${result.targetUrl}`);
     if (result.devCommand)
         console.log(`✓ Development command: ${result.devCommand.command} ${result.devCommand.args.join(' ')}`);
-    console.log('\nNext: foundry-design start');
+    console.log('\nSetup complete. One coding-agent restart is required so it can load Foundry.');
+    console.log(`1. Restart ${sharedAgentSetup && detectedPlan?.agents.length
+        ? detectedPlan.agents.join(', ')
+        : result.agents.length
+            ? result.agents.join(', ')
+            : 'your coding agent'}.`);
+    console.log('2. Reopen this exact project folder.');
+    console.log('3. Ask: "Start Foundry for this project and keep listening for Apply with agent requests."');
+    console.log('\nAfter that, the browser will confirm when the agent is ready.');
+}
+async function update() {
+    console.log(`${releasePreflight('update this project')}\n`);
+    const root = projectRoot();
+    const options = {
+        agents: requestedAgents(),
+        packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+    };
+    const plan = await createUpdatePlan(root, options);
+    console.log(`Foundry update\n\nProject: ${root}`);
+    console.log(`Agent integration: ${plan.agents.join(', ')}`);
+    console.log('\nFoundry will refresh these managed paths:');
+    for (const path of plan.files)
+        console.log(`  ${path}`);
+    console.log('\nFiles changed since Foundry installed them will be preserved.');
+    if (!(await confirm('\nContinue with this update?'))) {
+        console.log('Update cancelled.');
+        return;
+    }
+    const result = await updateProject(root, options);
+    console.log(`\n✓ Foundry refreshed ${result.changed.length} managed paths.`);
+    if (result.preserved.length) {
+        console.log('Preserved files containing user changes:');
+        for (const path of result.preserved)
+            console.log(`  ${path}`);
+    }
+    for (const check of result.validation) {
+        const marker = check.status === 'passed' ? '✓' : check.status === 'skipped' ? '–' : '!';
+        console.log(`${marker} ${check.name}: ${check.status.replaceAll('-', ' ')}`);
+    }
+    console.log('\nRestart your coding agent so it loads the refreshed Foundry connection and skill.');
 }
 async function initProject() {
+    console.log(`${releasePreflight('initialize this project')}\n`);
     const platform = (args[1] ?? 'web');
     if (!['web', 'swiftui', 'react-native'].includes(platform))
         throw new Error(`Unsupported platform: ${platform}`);
@@ -192,9 +269,7 @@ async function start() {
         config?.platform ??
         (await detectPlatform(root));
     const targetUrl = flag('--url') ?? config?.targetUrl;
-    if (platform === 'web' && config && !config.instrumented) {
-        throw new Error('Foundry setup is incomplete. Connect .foundry/web-adapter.ts to a development-only client entry, then set instrumented to true.');
-    }
+    let basicPreview;
     let developmentServer;
     if (platform === 'web' &&
         targetUrl &&
@@ -220,54 +295,88 @@ async function start() {
         }
     }
     const projectRevision = await revision(root);
+    const configuredViewports = config?.design?.viewports ?? [];
+    const initialViewport = configuredViewports.find((viewport) => viewport.id.toLowerCase() === 'desktop' || viewport.label.toLowerCase() === 'desktop') ??
+        [...configuredViewports].sort((left, right) => right.width - left.width)[0] ?? {
+        width: 1440,
+        height: 900,
+    };
     const context = {
         projectRoot: root,
         revision: projectRevision,
         platform,
         targetUrl,
         targetName: basename(root),
+        viewport: { width: initialViewport.width, height: initialViewport.height ?? 900 },
         theme: 'system',
         breakpoint: 'current',
         state: 'current',
     };
     const store = new SessionStore();
-    const session = await store.create(context);
+    const resumable = has('--new')
+        ? undefined
+        : (await store.list()).find((candidate) => candidate.changeSet.context.projectRoot === root &&
+            candidate.changeSet.context.revision === projectRevision &&
+            candidate.changeSet.context.targetUrl === targetUrl);
+    const session = resumable
+        ? await store.read(resumable.changeSet.sessionId)
+        : await store.create(context);
     if (platform === 'web') {
         const graph = await indexProjectDesign(root, config, projectRevision);
         await store.setDesignGraph(session.changeSet.sessionId, graph);
         console.log(`Indexed ${graph.tokens.length} tokens, ${graph.components.length} components, and ${graph.breakpoints.length} viewports.`);
     }
     const runtime = new FoundryRuntime({ store });
+    let ownsRuntime = false;
     try {
         await runtime.start();
+        ownsRuntime = true;
     }
     catch (error) {
         if (error.code !== 'EADDRINUSE')
             throw error;
-        developmentServer?.kill('SIGTERM');
-        console.error('Port 4387 is already in use. Stop the existing Foundry runtime before starting another session.');
-        process.exitCode = 1;
-        return;
+        const healthy = await fetch('http://127.0.0.1:4387/v1/health')
+            .then((response) => response.ok)
+            .catch(() => false);
+        if (!healthy)
+            throw new Error('Port 4387 is in use by another process. Stop it and run Foundry again.');
+        console.log('Using the existing local Foundry runtime.');
     }
     const reviewUrl = `http://127.0.0.1:4387/?session=${encodeURIComponent(session.changeSet.sessionId)}&token=${encodeURIComponent(session.token)}`;
+    if (platform === 'web' && targetUrl && config && !config.instrumented) {
+        basicPreview = await startBasicPreviewProxy(targetUrl, config.runtimeUrl);
+        console.log('Basic mode: Foundry is attached without changing the project entry point.');
+        console.log('Run setup again after adding a supported client entry to enable exact source mapping.');
+    }
     const productUrl = targetUrl && platform === 'web'
-        ? addSessionParams(targetUrl, session.changeSet.sessionId, session.token)
+        ? addSessionParams(basicPreview?.url ?? targetUrl, session.changeSet.sessionId, session.token)
+        : reviewUrl;
+    const workspaceUrl = platform === 'web' && targetUrl
+        ? `${reviewUrl}&preview=${encodeURIComponent(productUrl)}`
         : reviewUrl;
     console.log(`Foundry session ${session.changeSet.sessionId}`);
+    if (resumable)
+        console.log('Resumed the most recent session for this project revision.');
     console.log(`Platform: ${platform}`);
-    console.log(`Inspector: ${reviewUrl}`);
+    console.log(`Workspace: ${workspaceUrl}`);
     if (targetUrl && platform === 'web')
-        console.log(`Instrumented preview: ${productUrl}`);
+        console.log(`${basicPreview ? 'Basic' : 'Precision'} preview: ${productUrl}`);
     if (platform === 'web') {
         console.log('\nFirst edit:');
         console.log('  1. Option-click an element. Shift-click to add more.');
         console.log('  2. Drag a blue handle or use the inspector for exact values.');
         console.log('  3. Review the semantic mapping, then Apply with agent.');
+        console.log('\nAgent handoff:');
+        console.log('  Keep this process running while you design.');
+        console.log('  Foundry will show “Agent is ready” only while a coding agent is listening.');
+        console.log('  If it is not ready, ask the agent: “Keep listening for Apply with agent requests.”');
     }
     if (!has('--no-open'))
-        await openUrl(productUrl);
+        await openUrl(workspaceUrl);
     const shutdown = async () => {
-        await runtime.stop();
+        if (ownsRuntime)
+            await runtime.stop();
+        await basicPreview?.stop();
         developmentServer?.kill('SIGTERM');
         process.exit(0);
     };
@@ -291,6 +400,7 @@ async function indexDesign() {
         console.log(content);
 }
 async function uninstall() {
+    console.log(`${releasePreflight('remove managed project integration')}\n`);
     const root = projectRoot();
     if (!(await confirm(`Remove Foundry-managed project integration from ${root}?`))) {
         console.log('Uninstall cancelled.');
@@ -309,32 +419,39 @@ async function doctor() {
     const platform = await detectPlatform(root);
     const configPath = join(root, '.foundry', 'foundry.config.json');
     let config;
+    const manifest = await readFile(join(root, '.foundry', 'install-manifest.json'), 'utf8')
+        .then((content) => JSON.parse(content))
+        .catch(() => undefined);
     try {
         config = JSON.parse(await readFile(configPath, 'utf8'));
     }
     catch {
         /* Report setup as missing below. */
     }
-    const agentFiles = [
+    const projectAgentFiles = [
         join(root, '.codex', 'config.toml'),
         join(root, '.cursor', 'mcp.json'),
         join(root, '.mcp.json'),
     ];
+    const sharedAgentFiles = [
+        join(homedir(), '.codex', 'config.toml'),
+        join(homedir(), '.cursor', 'mcp.json'),
+        join(homedir(), '.claude.json'),
+    ];
     const configuredAgents = [];
-    for (const path of agentFiles) {
+    for (const path of [...projectAgentFiles, ...sharedAgentFiles]) {
         if ((await readFile(path, 'utf8').catch(() => '')).includes('foundry-design-control'))
             configuredAgents.push(path);
     }
-    const pluginProvided = await readFile(join(root, '.foundry', 'install-manifest.json'), 'utf8')
-        .then((content) => {
-        const manifest = JSON.parse(content);
-        return Array.isArray(manifest.agents) && manifest.agents.length === 0;
-    })
-        .catch(() => false);
     const checks = [
         ['Project', root, true],
         ['Detected platform', platform, true],
         ['Foundry config', configPath, Boolean(config)],
+        [
+            'Managed integration',
+            manifest?.generatorVersion ?? 'not installed',
+            manifest?.generatorVersion === FOUNDRY_VERSION,
+        ],
         [
             'Instrumentation',
             config?.instrumented ? `${config.framework ?? config.platform}` : 'integration pending',
@@ -342,12 +459,8 @@ async function doctor() {
         ],
         [
             'Agent connection',
-            configuredAgents.length
-                ? configuredAgents.join(', ')
-                : pluginProvided
-                    ? 'plugin-provided'
-                    : 'not configured',
-            configuredAgents.length > 0 || pluginProvided,
+            configuredAgents.length ? configuredAgents.join(', ') : 'not configured',
+            configuredAgents.length > 0,
         ],
         [
             'Project preview',
@@ -364,8 +477,49 @@ async function doctor() {
     ];
     for (const [label, value, passed] of checks)
         console.log(`${passed ? '✓' : '○'} ${label}: ${value}`);
-    if (!config)
-        console.log('Run: foundry-design setup');
+    if (has('--repair')) {
+        console.log(`\n${releasePreflight('repair this project and agent connection')}\n`);
+        const detectedAgents = (await createSetupPlan(root)).agents;
+        const result = config
+            ? await updateProject(root, { agents: [] })
+            : await setupProject(root, { agents: [], targetUrl: flag('--url') });
+        for (const agent of detectedAgents)
+            await installHostAgentIntegration(homedir(), agent, {
+                packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+            });
+        console.log(`✓ Repaired ${result.changed.length} managed paths and the shared ${detectedAgents.join(', ')} connection.`);
+    }
+    else if (!config || !configuredAgents.length) {
+        console.log('Run: foundry-design doctor --repair');
+    }
+}
+async function launch() {
+    console.log(`${releasePreflight('install, update, and start Foundry')}\n`);
+    const root = projectRoot();
+    const manifest = join(root, '.foundry', 'install-manifest.json');
+    const installed = await pathExists(manifest);
+    const detectedAgents = (await createSetupPlan(root)).agents;
+    console.log(`Foundry\n\nProject: ${root}`);
+    console.log(`${installed ? 'Refreshing' : 'Preparing'} the project and shared ${detectedAgents.join(', ')} connection.`);
+    if (!(await confirm('Continue?'))) {
+        console.log('Foundry cancelled.');
+        return;
+    }
+    const result = installed
+        ? await updateProject(root, { agents: [], targetUrl: flag('--url') })
+        : await setupProject(root, { agents: [], targetUrl: flag('--url') });
+    for (const agent of detectedAgents)
+        await installHostAgentIntegration(homedir(), agent, {
+            packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+        });
+    console.log(`✓ ${installed ? 'Updated' : 'Installed'} and validated Foundry.`);
+    for (const check of result.validation)
+        console.log(`${check.status === 'passed' ? '✓' : check.status === 'skipped' ? '–' : '!'} ${check.name}: ${check.status.replaceAll('-', ' ')}`);
+    if (!installed)
+        console.log(`\nRestart ${detectedAgents.join(', ')} once to load the shared connection. The visual session will open now and queued batches will wait safely until it reconnects.`);
+    if (has('--no-start'))
+        return;
+    await start();
 }
 async function exportSession() {
     const id = args[1];
@@ -392,39 +546,41 @@ async function exportSession() {
         console.log(content);
 }
 async function installAgent() {
+    console.log(`${releasePreflight('install the coding-agent connection')}\n`);
     const agent = args[1];
     if (!agent || !['cursor', 'claude', 'codex'].includes(agent))
         throw new Error('install-agent requires cursor, claude, or codex');
-    const root = projectRoot();
-    const server = {
-        command: 'pnpm',
-        args: ['--dir', runtimeRepository, '--filter', 'foundry-design-mcp-server', 'start'],
-        env: { FOUNDRY_DESIGN_RUNTIME_URL: 'http://127.0.0.1:4387' },
-    };
-    if (agent === 'codex') {
-        const directory = join(root, '.codex');
-        await mkdir(directory, { recursive: true });
-        const file = join(directory, 'foundry-mcp.toml');
-        await writeFile(file, `# Merge this project-scoped server into your Codex MCP configuration.\n[mcp_servers.foundry-design-control]\ncommand = "pnpm"\nargs = ["--dir", "${runtimeRepository}", "--filter", "foundry-design-mcp-server", "start"]\n[mcp_servers.foundry-design-control.env]\nFOUNDRY_DESIGN_RUNTIME_URL = "http://127.0.0.1:4387"\n`);
-        console.log(`Wrote Codex MCP snippet: ${file}`);
+    if (has('--global')) {
+        const result = await installHostAgentIntegration(homedir(), agent, {
+            packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+        });
+        console.log(`Installed the shared Foundry connection for ${agent}.`);
+        console.log(`MCP configuration: ${result.configFile}`);
+        console.log(`Skill: ${result.skillDirectory}`);
+        if (result.preserved.length) {
+            console.log('Preserved customized skill files:');
+            for (const path of result.preserved)
+                console.log(`  ${path}`);
+        }
+        console.log(`Restart ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'} once. Future projects can use "npx foundry-design setup --agent none --yes" without another MCP install.`);
         return;
     }
-    const file = agent === 'cursor' ? join(root, '.cursor', 'mcp.json') : join(root, '.mcp.json');
-    await mkdir(dirname(file), { recursive: true });
-    let current = {};
-    try {
-        current = JSON.parse(await readFile(file, 'utf8'));
-    }
-    catch {
-        /* Create a new project config. */
-    }
-    current.mcpServers = { ...current.mcpServers, 'foundry-design-control': server };
-    await writeFile(file, `${JSON.stringify(current, null, 2)}\n`);
+    const root = projectRoot();
+    const file = await installAgentIntegration(root, agent, has('--local-mcp') ? runtimeRepository : undefined);
     console.log(`Installed Foundry MCP configuration for ${agent}: ${file}`);
+    console.log(`Restart ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'} before starting a Foundry apply session.`);
 }
 try {
-    if (command === 'setup')
+    if (has('--version') || command === 'version')
+        console.log(FOUNDRY_VERSION);
+    else if (has('--help') || command === 'help')
+        printHelp();
+    else if (command === 'launch')
+        await launch();
+    else if (command === 'setup')
         await setup();
+    else if (command === 'update')
+        await update();
     else if (command === 'init')
         await initProject();
     else if (command === 'start')