create-nudge-ui 0.2.1 → 0.2.3

package/README.md

@@ -1,59 +1,105 @@
-# `create-nudge-ui`
+# create-nudge-ui
 
-`create-nudge-ui` detects an application's host framework, installs the
-corresponding Nudge UI adapter, and updates the host configuration. The guided
-setup can also connect a coding agent to the project-local Nudge MCP server.
+Add Nudge UI to an existing app with one command. `create-nudge-ui` detects your
+framework, installs `nudge-ui`, and updates your development configuration. It
+can also connect your coding agent so you can send design changes from the browser.
 
-Run the initializer from the application root:
+[Nudge UI](https://www.npmjs.com/package/nudge-ui) lets you inspect your running
+app, preview visual edits, and turn them into a prompt for a coding agent.
+
+## Get started
+
+From your application's root directory, run:
 
 ```sh
 npm create nudge-ui@latest
 ```
 
-The initializer supports Next.js, Astro, Vite with React, and static HTML. Host
-frameworks take precedence over their underlying tools, so an Astro project
-with React islands receives `nudge-ui/astro`, not `nudge-ui/vite`.
+Follow the prompts, then start your app with its usual development command and
+open the local URL. For static HTML, run the `nudge-ui serve` command printed by
+the initializer.
+
+Requires Node.js 20 or later and a supported app. Your framework or build tool
+may require a newer Node.js version.
 
-In an interactive terminal, the initializer asks whether to connect a coding
-agent. It detects installed agents, installs the matching `@nudge-ui/mcp`
-version in the project, and adds a project-scoped MCP entry. The entry launches
-the package from this project's `node_modules` directory and passes the
-canonical workspace path, so different Git worktrees do not share a server
-configuration.
+## What setup does
 
-Reload an agent that was already running, then ask it to “listen to Nudge.”
+- Detects Next.js, Astro, Vite with React, or a static HTML directory.
+- Installs `nudge-ui` as a development dependency using npm, pnpm, Yarn, or Bun.
+- Adds the framework integration to your configuration. Static HTML uses the
+  bundled development server instead.
+- Offers to connect a coding agent through
+  [`@nudge-ui/mcp`](https://www.npmjs.com/package/@nudge-ui/mcp).
 
-Use an explicit framework when automatic detection is ambiguous:
+Run it inside the app directory in a monorepo. If detection is ambiguous, choose
+the framework explicitly:
 
 ```sh
 npm create nudge-ui@latest -- --framework astro
 ```
 
-Use `--dry-run` to print the package installation and configuration change
-without modifying the project. Run `npm create nudge-ui@latest -- --help` for
-the complete command reference.
+## Connect a coding agent
 
-For scripts, select the MCP behavior explicitly:
+Choose agent setup during initialization, or add it later:
 
 ```sh
-# Configure detected agents without prompts.
-npm create nudge-ui@latest -- --mcp --yes
+npm create nudge-ui@latest -- --agent-only
+```
 
-# Configure one or more supported add-mcp agent IDs.
-npm create nudge-ui@latest -- --mcp --agent codex --agent cursor --yes
+Setup installs a bridge dependency in the app and a reusable MCP adapter under
+`~/.nudge-ui/adapters/`. It registers the adapter globally for the selected
+agents, so other checkouts and Git worktrees can use it. Each app still needs
+its own Nudge integration and bridge dependency.
 
-# Skip agent setup.
-npm create nudge-ui@latest -- --no-mcp
-```
+Setup verifies the adapter before changing agent settings. If automatic
+configuration fails, it prints a global stdio configuration you
+can add manually. npm must be available to install the reusable adapter, even
+when your app uses another package manager.
 
-Use agent-only mode to add or repair the integration without changing the host
-framework configuration:
+Fully restart your agent host, then ask it to **listen to Nudge in this
+workspace**. Keep the agent listening while you send changes from the browser.
+The MCP integration is early alpha; host behavior and setup may change.
+
+## Common commands
 
 ```sh
-npm create nudge-ui@latest -- --agent-only --agent codex --yes
+# Preview setup without changing files or installing packages.
+npm create nudge-ui@latest -- --dry-run
+
+# Install the inspector without agent setup.
+npm create nudge-ui@latest -- --no-mcp
+
+# Set up a specific agent without prompts.
+npm create nudge-ui@latest -- --agent codex --yes
+
+# Connect an agent to an existing Nudge installation.
+npm create nudge-ui@latest -- --agent-only --agent cursor --yes
 ```
 
-Agent configuration is best-effort. If an agent is not supported or its native
-configuration cannot be updated, the initializer prints the complete stdio
-configuration to add to that agent's project settings. Other MCP servers and
-agent settings are preserved on every run.
+## Options
+
+Pass options after `--` when using `npm create`.
+
+| Option | Purpose |
+| --- | --- |
+| `--framework <name>` | Select `nextjs`, `astro`, `vite-react`, or `standalone`. |
+| `--package-manager <name>` | Select `npm`, `pnpm`, `yarn`, or `bun`. |
+| `--mcp` | Enable agent setup. |
+| `--no-mcp` | Skip agent setup. |
+| `--agent <id>` | Select an agent, such as `codex` or `cursor`. Repeat for multiple agents. Enables agent setup. |
+| `--agent-only` | Install or repair agent integration without changing framework configuration. |
+| `--yes`, `-y` | Accept defaults without prompts, including setup for detected agents. Use `--no-mcp` to skip agent setup. |
+| `--dry-run` | Print planned changes without applying them. |
+| `--mcp-package <specifier>` | Use a specific MCP package or local tarball for both the bridge and adapter. |
+| `--help`, `-h` | Show command help. |
+
+For troubleshooting and custom integrations, see the
+[coding-agent guide](https://github.com/charlessmart/nudge-ui/blob/main/docs/agent-integration.md).
+For manual framework setup, see
+[`nudge-ui`](https://www.npmjs.com/package/nudge-ui).
+
+## Links
+
+[Repository](https://github.com/charlessmart/nudge-ui) ·
+[Issues](https://github.com/charlessmart/nudge-ui/issues) ·
+[MIT license](https://github.com/charlessmart/nudge-ui/blob/main/LICENSE)

package/dist/agent-setup.d.ts

@@ -6,25 +6,29 @@ export interface AgentSetupPlan {
     readonly projectRoot: string;
     readonly packageSpecifier: string;
     readonly installCommand: InstallCommand;
+    readonly adapterRoot: string;
+    readonly adapterInstallCommand: InstallCommand;
     readonly serverConfig: McpServerConfig;
-    readonly serverEntry?: string;
+    readonly serverEntry: string;
 }
 export interface AgentInstallOutcome {
     readonly agent: string;
     readonly displayName: string;
     readonly result?: InstallResult;
     readonly unsupported: boolean;
+    readonly migrationError?: string;
+    readonly backups?: readonly string[];
 }
-/** Builds the reproducible, project-local MCP installation and launch plan. */
-export declare function planAgentSetup(projectRoot: string, packageManager: PackageManager, nudgeUiVersion?: string): AgentSetupPlan;
+/** Plans the project bridge dependency and an independent, versioned adapter installation. */
+export declare function planAgentSetup(projectRoot: string, packageManager: PackageManager, nudgeUiVersion?: string, adapterDirectory?: string, mcpPackageSpecifier?: string): AgentSetupPlan;
 /** Checks that a node_modules based install produced the configured executable. */
 export declare function isAgentServerAvailable(plan: AgentSetupPlan): boolean;
-/** Returns agents that can store an MCP configuration in this project. */
+/** Returns agents that support a reusable stdio MCP configuration. */
 export declare function projectAgentTypes(): AgentType[];
-/** Detects installed or already configured agents while preserving project scope. */
+/** Detects installed or already configured agents. */
 export declare function detectProjectAgentCandidates(projectRoot: string): Promise<AgentType[]>;
-/** Adds or repairs Nudge's project-scoped MCP entry without replacing other servers. */
-export declare function configureProjectAgents(plan: AgentSetupPlan, selectedAgents: readonly string[]): AgentInstallOutcome[];
+/** Registers the reusable adapter and removes the current project's overriding entry. */
+export declare function configureProjectAgents(plan: AgentSetupPlan, selectedAgents: readonly string[]): Promise<AgentInstallOutcome[]>;
 /** Formats a complete stdio entry for agents that add-mcp cannot configure. */
 export declare function manualAgentConfiguration(plan: AgentSetupPlan): string;
 export declare function projectAgentChoices(detected: readonly AgentType[]): Array<{

package/dist/agent-setup.js

@@ -1,40 +1,40 @@
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
-import { agents, detectGlobalAgents, detectProjectAgents, getAgentTypes, upsertServer, } from "add-mcp";
+import { agents, detectGlobalAgents, detectProjectAgents, getAgentTypes, upsertServer, listInstalledServers, removeServer, } from "add-mcp";
 import { installCommand } from "./installer.js";
 export const nudgeServerName = "nudge_ui";
-/** Builds the reproducible, project-local MCP installation and launch plan. */
-export function planAgentSetup(projectRoot, packageManager, nudgeUiVersion) {
+/** Plans the project bridge dependency and an independent, versioned adapter installation. */
+export function planAgentSetup(projectRoot, packageManager, nudgeUiVersion, adapterDirectory = join(homedir(), ".nudge-ui", "adapters"), mcpPackageSpecifier) {
     const canonicalRoot = realpathSync.native(projectRoot);
-    const packageSpecifier = `@nudge-ui/mcp@${nudgeUiVersion ?? installedNudgeUiVersion(canonicalRoot) ?? initializerVersion()}`;
-    const serverEntry = join(canonicalRoot, "node_modules", "@nudge-ui", "mcp", "dist", "cli.mjs");
-    const usesPlugAndPlay = packageManager === "yarn";
-    const serverConfig = usesPlugAndPlay
-        ? {
-            command: "yarn",
-            args: ["--cwd", canonicalRoot, "exec", "nudge-mcp", "--workspace-root", canonicalRoot],
-        }
-        : {
-            command: "node",
-            args: [serverEntry, "--workspace-root", canonicalRoot],
-        };
+    const packageSpecifier = mcpPackageSpecifier ?? `@nudge-ui/mcp@${nudgeUiVersion ?? installedNudgeUiVersion(canonicalRoot) ?? initializerVersion()}`;
+    const adapterPackageSpecifier = mcpPackageSpecifier ?? `@nudge-ui/mcp@${initializerVersion()}`;
+    const adapterRoot = join(adapterDirectory, initializerVersion());
+    const serverEntry = join(adapterRoot, "node_modules", "@nudge-ui", "mcp", "dist", "cli.mjs");
+    const serverConfig = { command: process.execPath, args: [serverEntry] };
     return {
         projectRoot: canonicalRoot,
         packageSpecifier,
         installCommand: installCommand(packageManager, packageSpecifier),
         serverConfig,
-        serverEntry: usesPlugAndPlay ? undefined : serverEntry,
+        adapterRoot,
+        adapterInstallCommand: {
+            executable: "npm",
+            args: ["install", "--prefix", adapterRoot, "--no-save", "--package-lock=false", adapterPackageSpecifier],
+        },
+        serverEntry,
     };
 }
 /** Checks that a node_modules based install produced the configured executable. */
 export function isAgentServerAvailable(plan) {
-    return plan.serverEntry === undefined || existsSync(plan.serverEntry);
+    return existsSync(plan.serverEntry);
 }
-/** Returns agents that can store an MCP configuration in this project. */
+/** Returns agents that support a reusable stdio MCP configuration. */
 export function projectAgentTypes() {
-    return getAgentTypes().filter((agent) => agents[agent].localConfigPath !== undefined);
+    return getAgentTypes().filter((agent) => agents[agent].supportedTransports.includes("stdio"));
 }
-/** Detects installed or already configured agents while preserving project scope. */
+/** Detects installed or already configured agents. */
 export async function detectProjectAgentCandidates(projectRoot) {
     const supported = new Set(projectAgentTypes());
     const detected = [
@@ -43,25 +43,45 @@ export async function detectProjectAgentCandidates(projectRoot) {
     ].filter((agent) => supported.has(agent));
     return [...new Set(detected)];
 }
-/** Adds or repairs Nudge's project-scoped MCP entry without replacing other servers. */
-export function configureProjectAgents(plan, selectedAgents) {
+/** Registers the reusable adapter and removes the current project's overriding entry. */
+export async function configureProjectAgents(plan, selectedAgents) {
     const supported = new Set(projectAgentTypes());
-    return [...new Set(selectedAgents)].map((agent) => {
+    const outcomes = [];
+    for (const agent of new Set(selectedAgents)) {
         if (!supported.has(agent)) {
-            return { agent, displayName: agent, unsupported: true };
+            outcomes.push({ agent, displayName: agent, unsupported: true });
+            continue;
         }
         const agentType = agent;
-        const result = upsertServer(agentType, nudgeServerName, plan.serverConfig, {
-            cwd: plan.projectRoot,
-            local: true,
+        const global = await listInstalledServers({ agents: [agentType], global: true, cwd: plan.projectRoot });
+        const local = agents[agentType].localConfigPath
+            ? await listInstalledServers({ agents: [agentType], global: false, cwd: plan.projectRoot })
+            : [];
+        const configurations = [...global, ...local];
+        const invalid = configurations.find((configuration) => configuration.error);
+        if (invalid) {
+            outcomes.push({ agent, displayName: agents[agentType].displayName, unsupported: false,
+                result: { success: false, path: invalid.configPath, error: invalid.error } });
+            continue;
+        }
+        const backups = [];
+        for (const configuration of configurations) {
+            if (!configuration.servers.some((server) => server.serverName === nudgeServerName))
+                continue;
+            const backup = `${configuration.configPath}.nudge-backup-${randomUUID()}`;
+            copyFileSync(configuration.configPath, backup);
+            backups.push(backup);
+        }
+        const result = upsertServer(agentType, nudgeServerName, plan.serverConfig, { local: false, cwd: plan.projectRoot });
+        const removal = result.success && agents[agentType].localConfigPath
+            ? removeServer(agentType, nudgeServerName, { local: true, cwd: plan.projectRoot })
+            : undefined;
+        outcomes.push({
+            agent, displayName: agents[agentType].displayName, result, unsupported: false, backups,
+            ...(removal && !removal.success ? { migrationError: removal.error ?? "Could not remove the project override." } : {}),
         });
-        return {
-            agent,
-            displayName: agents[agentType].displayName,
-            result,
-            unsupported: false,
-        };
-    });
+    }
+    return outcomes;
 }
 /** Formats a complete stdio entry for agents that add-mcp cannot configure. */
 export function manualAgentConfiguration(plan) {

package/dist/agent-verification.d.ts

@@ -0,0 +1,3 @@
+import type { McpServerConfig } from "add-mcp";
+/** Verifies the configured executable, initialization, and tools without claiming a project. */
+export declare function verifyAgentServer(config: McpServerConfig): Promise<void>;

package/dist/agent-verification.js

@@ -0,0 +1,21 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+/** Verifies the configured executable, initialization, and tools without claiming a project. */
+export async function verifyAgentServer(config) {
+    if (!config.command)
+        throw new Error("The MCP adapter has no executable.");
+    const client = new Client({ name: "nudge-setup", version: "1.0.0" });
+    const transport = new StdioClientTransport({ command: config.command, args: config.args, stderr: "inherit" });
+    try {
+        await client.connect(transport, { timeout: 15_000 });
+        const { tools } = await client.listTools({}, { timeout: 15_000 });
+        const listen = tools.find((tool) => tool.name === "nudge_listen");
+        if (!listen?.inputSchema.required?.includes("workspaceRoot") || !tools.some((tool) => tool.name === "nudge_list_sessions")) {
+            throw new Error("The installed adapter does not support connection-time project selection. Upgrade @nudge-ui/mcp.");
+        }
+    }
+    finally {
+        await transport.close();
+        await client.close();
+    }
+}

package/dist/arguments.d.ts

@@ -4,6 +4,7 @@ export interface CliOptions {
     readonly packageManager?: PackageManager;
     readonly agentOnly: boolean;
     readonly agents: readonly string[];
+    readonly mcpPackageSpecifier?: string;
     readonly mcp?: boolean;
     readonly yes: boolean;
     readonly dryRun: boolean;
@@ -11,4 +12,4 @@ export interface CliOptions {
 }
 /** Parses the initializer command line. */
 export declare function parseArguments(args: readonly string[]): CliOptions;
-export declare const helpText = "Set up Nudge UI in the current project.\n\nUsage: npm create nudge-ui@latest -- [options]\n\nOptions:\n  --framework <nextjs|astro|vite-react|standalone>\n  --package-manager <pnpm|npm|yarn|bun>\n  --mcp                         Configure the local Nudge MCP server\n  --no-mcp                      Skip coding-agent setup\n  --agent <id>                  Configure a supported agent (repeatable)\n  --agent-only                  Install or repair only the agent integration\n  -y, --yes                     Accept defaults without prompting\n  --dry-run\n  -h, --help";
+export declare const helpText = "Set up Nudge UI in the current project.\n\nUsage: npm create nudge-ui@latest -- [options]\n\nOptions:\n  --framework <nextjs|astro|vite-react|standalone>\n  --package-manager <pnpm|npm|yarn|bun>\n  --mcp                         Configure the reusable Nudge MCP adapter\n  --no-mcp                      Skip coding-agent setup\n  --agent <id>                  Configure a supported agent (repeatable)\n  --mcp-package <path|package> Use this MCP package for the project and adapter\n  --agent-only                  Install or repair only the agent integration\n  -y, --yes                     Accept defaults without prompting\n  --dry-run\n  -h, --help";

package/dist/arguments.js

@@ -5,6 +5,7 @@ export function parseArguments(args) {
     let packageManager;
     let agentOnly = false;
     const agents = [];
+    let mcpPackageSpecifier;
     let mcp;
     let yes = false;
     let dryRun = false;
@@ -32,6 +33,10 @@ export function parseArguments(args) {
             agents.push(requiredValue(args, ++index, argument));
         else if (argument.startsWith("--agent="))
             agents.push(requiredValue([argument.slice("--agent=".length)], 0, "--agent"));
+        else if (argument === "--mcp-package")
+            mcpPackageSpecifier = requiredValue(args, ++index, argument);
+        else if (argument.startsWith("--mcp-package="))
+            mcpPackageSpecifier = requiredValue([argument.slice("--mcp-package=".length)], 0, "--mcp-package");
         else if (argument === "--help" || argument === "-h")
             help = true;
         else if (argument === "--framework")
@@ -51,7 +56,7 @@ export function parseArguments(args) {
         throw new Error("--agent cannot be combined with --no-mcp.");
     if (agentOnly && mcp === false)
         throw new Error("--agent-only cannot be combined with --no-mcp.");
-    return { framework, packageManager, agentOnly, agents, mcp, yes, dryRun, help };
+    return { framework, packageManager, agentOnly, agents, mcpPackageSpecifier, mcp, yes, dryRun, help };
 }
 function setMcpPreference(current, next) {
     if (current !== undefined && current !== next)
@@ -71,9 +76,10 @@ Usage: npm create nudge-ui@latest -- [options]
 Options:
   --framework <nextjs|astro|vite-react|standalone>
   --package-manager <pnpm|npm|yarn|bun>
-  --mcp                         Configure the local Nudge MCP server
+  --mcp                         Configure the reusable Nudge MCP adapter
   --no-mcp                      Skip coding-agent setup
   --agent <id>                  Configure a supported agent (repeatable)
+  --mcp-package <path|package> Use this MCP package for the project and adapter
   --agent-only                  Install or repair only the agent integration
   -y, --yes                     Accept defaults without prompting
   --dry-run

package/dist/cli.d.ts

@@ -1,6 +1,8 @@
 import { type PackageManager } from "./types.js";
 export interface RunAgentSetupOptions {
     readonly agents?: readonly string[];
+    /** Optional package specifier or tarball used for both bridge and adapter testing. */
+    readonly mcpPackageSpecifier?: string;
     readonly dryRun?: boolean;
     readonly nudgeUiVersion?: string;
     readonly packageManager?: PackageManager;
@@ -8,5 +10,5 @@ export interface RunAgentSetupOptions {
 }
 /** Runs the Nudge UI project initializer. */
 export declare function runCli(args?: string[], projectRoot?: string): Promise<void>;
-/** Installs and configures the project-local MCP companion. Safe to rerun for repairs. */
+/** Installs and configures the reusable MCP adapter and project bridge dependency. Safe to rerun for repairs. */
 export declare function runAgentSetup(projectRoot?: string, options?: RunAgentSetupOptions): Promise<void>;

package/dist/cli.js

@@ -1,4 +1,5 @@
-import { rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { verifyAgentServer } from "./agent-verification.js";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { basename, relative } from "node:path";
@@ -20,6 +21,7 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
     if (options.agentOnly) {
         await runAgentSetup(projectRoot, {
             agents: options.agents,
+            mcpPackageSpecifier: options.mcpPackageSpecifier,
             dryRun: options.dryRun,
             packageManager,
             yes: options.yes,
@@ -44,6 +46,7 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
         if (await shouldConfigureAgent(options.mcp, options.agents.length > 0, options.yes)) {
             await runAgentSetup(projectRoot, {
                 agents: options.agents,
+                mcpPackageSpecifier: options.mcpPackageSpecifier,
                 dryRun: true,
                 nudgeUiVersion: initializerVersion(),
                 packageManager,
@@ -73,17 +76,18 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
     if (await shouldConfigureAgent(options.mcp, options.agents.length > 0, options.yes)) {
         await runAgentSetup(projectRoot, {
             agents: options.agents,
+            mcpPackageSpecifier: options.mcpPackageSpecifier,
             nudgeUiVersion: initializerVersion(),
             packageManager,
             yes: options.yes,
         });
     }
 }
-/** Installs and configures the project-local MCP companion. Safe to rerun for repairs. */
+/** Installs and configures the reusable MCP adapter and project bridge dependency. Safe to rerun for repairs. */
 export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
     const manifest = readProjectManifest(projectRoot);
     const packageManager = options.packageManager ?? detectPackageManager(projectRoot, manifest);
-    const plan = planAgentSetup(projectRoot, packageManager, options.nudgeUiVersion);
+    const plan = planAgentSetup(projectRoot, packageManager, options.nudgeUiVersion, undefined, options.mcpPackageSpecifier);
     const detected = await detectProjectAgentCandidates(plan.projectRoot);
     const selected = options.agents && options.agents.length > 0
         ? options.agents
@@ -92,8 +96,9 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
             : await selectAgents(detected);
     if (options.dryRun) {
         stdout.write(`Would run: ${formatCommand(plan.installCommand)}\n`);
+        stdout.write(`Would run: ${formatCommand(plan.adapterInstallCommand)}\n`);
         if (selected.length > 0) {
-            stdout.write(`Would configure project MCP for: ${selected.join(", ")}\n`);
+            stdout.write(`Would configure global MCP and migrate this project override for: ${selected.join(", ")}\n`);
         }
         else {
             stdout.write("No coding agent was detected. Use --agent <id> or add the configuration below manually.\n");
@@ -102,11 +107,33 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
         return;
     }
     installPackage(plan.installCommand, plan.projectRoot);
+    try {
+        mkdirSync(plan.adapterRoot, { recursive: true });
+        installPackage(plan.adapterInstallCommand, plan.adapterRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stdout.write(`Could not install the reusable MCP adapter: ${message}\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
+        stdout.write("The coding-agent configuration was not changed. After the adapter install succeeds, rerun with --agent-only.\n");
+        return;
+    }
     if (!isAgentServerAvailable(plan)) {
-        stdout.write(`Installed ${plan.packageSpecifier}, but its local MCP executable was not found at ${plan.serverEntry}.\n`);
+        stdout.write(`Installed ${plan.packageSpecifier}, but its reusable MCP executable was not found at ${plan.serverEntry}.\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
         stdout.write("The coding-agent configuration was not changed. Check the package-manager install output, then rerun with --agent-only.\n");
         return;
     }
+    try {
+        await verifyAgentServer(plan.serverConfig);
+        stdout.write("Verified MCP initialization and tool discovery with a fresh client.\n");
+    }
+    catch (error) {
+        stdout.write(`MCP verification failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
+        stdout.write("The coding-agent configuration was not changed. After repairing the adapter install, rerun with --agent-only.\n");
+        return;
+    }
     if (selected.length === 0) {
         stdout.write(`Installed ${plan.packageSpecifier}, but no coding agent was detected.\n`);
         writeManualInstructions(plan);
@@ -114,7 +141,7 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
     }
     let outcomes;
     try {
-        outcomes = configureProjectAgents(plan, selected);
+        outcomes = await configureProjectAgents(plan, selected);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -125,7 +152,13 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
     let configured = 0;
     for (const outcome of outcomes) {
         if (outcome.unsupported) {
-            stdout.write(`${outcome.displayName} is not supported for automatic project setup.\n`);
+            stdout.write(`${outcome.displayName} is not supported for automatic global setup.\n`);
+            continue;
+        }
+        for (const backup of outcome.backups ?? [])
+            stdout.write(`Saved previous MCP configuration: ${backup}\n`);
+        if (outcome.migrationError) {
+            stdout.write(`Global adapter configured, but project override migration failed: ${outcome.migrationError}\n`);
             continue;
         }
         if (outcome.result?.success) {
@@ -138,7 +171,7 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
     if (configured !== outcomes.length)
         writeManualInstructions(plan);
     if (configured > 0) {
-        stdout.write("Coding-agent setup is ready. Reload the agent if it is already open, then ask it to listen to Nudge.\n");
+        stdout.write("Adapter configuration is ready. Fully restart the agent host to load it, then ask it to listen to Nudge in the current workspace. Existing overrides in other projects require one setup rerun there.\n");
     }
 }
 async function shouldConfigureAgent(preference, hasExplicitAgents, yes) {
@@ -189,7 +222,7 @@ async function selectAgents(detected) {
     }
 }
 function writeManualInstructions(plan) {
-    stdout.write("Add this project-scoped stdio server to your agent's MCP settings:\n");
+    stdout.write("Add this global stdio server to your agent's MCP settings:\n");
     stdout.write(`${manualAgentConfiguration(plan)}\n`);
 }
 async function selectFramework(detected) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nudge-ui",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Framework-detecting installer for Nudge UI.",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,8 @@
   },
   "dependencies": {
     "add-mcp": "^2.4.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {
     "vitest": "^2.1.9"