@akon-labs/nexus-cli 0.1.10 → 0.1.11

package/dist/extensions/mcp/mcp-setup-panel.js

@@ -38,14 +38,84 @@ function wrapText(text, width) {
         lines.push(current);
     return lines.length > 0 ? lines : [""];
 }
+const SETUP_TABS = [
+    { id: "presets", label: "Presets" },
+    { id: "custom", label: "Custom" },
+    { id: "installed", label: "Installed" },
+];
+/** Server-type tag shown next to a preset row; color must survive any terminal, so it's always plain colored text. */
+/** Color a JSON-ish line: keys cyan, string values green, braces/brackets dim. Safe only for short, unwrapped lines. */
+function colorizeJsonLine(line) {
+    let result = "";
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === '"') {
+            let end = i + 1;
+            while (end < line.length && line[end] !== '"')
+                end++;
+            const str = line.slice(i, Math.min(end + 1, line.length));
+            const isKey = line
+                .slice(i + str.length)
+                .trimStart()
+                .startsWith(":");
+            result += fg(isKey ? "36" : "32", str);
+            i += str.length;
+            continue;
+        }
+        if (ch === "{" || ch === "}" || ch === "[" || ch === "]") {
+            result += fg("2", ch);
+            i++;
+            continue;
+        }
+        result += ch;
+        i++;
+    }
+    return result;
+}
+/** Diff-line color by prefix, or undefined for a context line that needs no color. */
+function diffLineColor(line) {
+    if (line.startsWith("+++") || line.startsWith("---"))
+        return "2";
+    if (line.startsWith("+"))
+        return "32";
+    if (line.startsWith("-"))
+        return "31";
+    return undefined;
+}
+/** Color `/mcp add` command syntax: the command itself cyan, --flags yellow, <placeholders> dim italic. Leaves spacing untouched. */
+function colorizeCommandLine(line) {
+    return line.replace(/(\/mcp add\b|--[a-zA-Z-]+|<[^>]+>|\[[^\]]+\])/g, (match) => {
+        if (match.startsWith("<") || match.startsWith("["))
+            return fg("2;3", match);
+        if (match.startsWith("--"))
+            return fg("33", match);
+        return fg("36", match);
+    });
+}
+/** Per-preset accent color for the name, so the list scans by identity, not just by type. 256-color codes, distinct from the type-tag palette above. */
+const PRESET_ACCENT_COLORS = {
+    deepwiki: "38;5;111", // soft blue
+    context7: "38;5;80", // teal
+    notion: "38;5;141", // purple
+    github: "38;5;215", // orange
+    "chrome-devtools": "38;5;211", // pink
+};
+function presetAccent(preset) {
+    return PRESET_ACCENT_COLORS[preset.id] ?? "37";
+}
 export class McpSetupPanel {
     screen;
+    activeTab;
     actionCursor = 0;
     importCursor = 0;
     pathCursor = 0;
+    advancedCursor = 0;
     selectedImports = new Set();
     busy = false;
     notice = null;
+    pendingAction;
+    maxHeight;
     tui;
     t = DEFAULT_THEME;
     keys;
@@ -53,16 +123,20 @@ export class McpSetupPanel {
     discovery;
     callbacks;
     options;
+    /** Mutable copy of options.installedServers, updated in-place after a successful add so the Installed tab and Presets "active" tag reflect it immediately, without needing to close and reopen the panel. */
+    installedServers;
     done;
     static INACTIVITY_MS = 60_000;
     constructor(discovery, callbacks, options, tui, done) {
         this.discovery = discovery;
         this.callbacks = callbacks;
         this.options = options;
+        this.installedServers = [...options.installedServers];
         this.done = done;
         this.tui = tui;
         this.keys = createPanelKeys(options.keybindings);
         this.screen = options.mode;
+        this.activeTab = "presets";
         for (const entry of discovery.imports) {
             this.selectedImports.add(entry.kind);
         }
@@ -82,15 +156,9 @@ export class McpSetupPanel {
             this.inactivityTimeout = null;
         }
     }
-    getActions() {
+    /** The old "Setup" tab's contents — now a sub-screen opened from Custom's "Advanced options...", not a permanent top-level tab. */
+    getAdvancedActions() {
         const actions = [];
-        if (this.screen === "empty") {
-            actions.push({
-                id: "run-setup",
-                label: "Run setup",
-                description: "Inspect detected configs, adopt imports, and scaffold a minimal `.nexus/mcp.json`.",
-            });
-        }
         if (this.discovery.imports.length > 0) {
             actions.push({
                 id: "adopt-imports",
@@ -122,6 +190,10 @@ export class McpSetupPanel {
                 description: "Browse the actual config files that Nexus discovered on this machine.",
             });
         }
+        return actions;
+    }
+    getPresetsTabActions() {
+        const actions = [];
         for (const preset of KNOWN_SERVER_PRESETS) {
             actions.push({ id: "add-known-server", label: preset.name, description: preset.summary, preset });
         }
@@ -136,9 +208,86 @@ export class McpSetupPanel {
                 description: "Write an MCP entry for RepoPrompt to the recommended Nexus target, then reload MCP in-session.",
             });
         }
-        actions.push({ id: "close", label: "Close", description: "Exit the onboarding flow." });
         return actions;
     }
+    getCustomTabActions() {
+        return [
+            {
+                id: "add-custom-stdio",
+                label: "Add a local server (stdio)...",
+                description: "Runs a command on your machine, e.g. an npx-installed MCP server.",
+            },
+            {
+                id: "add-custom-url",
+                label: "Add a remote server (URL)...",
+                description: "Connects to an MCP server over HTTP.",
+            },
+            {
+                id: "open-advanced",
+                label: "Advanced options...",
+                description: "Import from other tools, scaffold an empty config, or check how config precedence works.",
+            },
+        ];
+    }
+    getInstalledTabActions() {
+        const servers = this.installedServers;
+        if (servers.length === 0) {
+            return [
+                {
+                    id: "view-installed-server",
+                    label: "No servers configured yet.",
+                    description: "Add one from the Presets or Custom tab.",
+                },
+            ];
+        }
+        return servers.map((server) => ({
+            id: "view-installed-server",
+            label: server.name,
+            description: server.disabled
+                ? "Disabled in the effective config."
+                : server.authCapable && !server.signedIn
+                    ? "Active, but not signed in yet."
+                    : "Active in the effective config.",
+            installed: server,
+        }));
+    }
+    /**
+     * Single-glyph prefix instead of a tag chip: ✓ for a preset you already have
+     * (dim if you've disabled it), ✓/⊘ for an Installed-tab row's active state.
+     * No mark at all for a preset you don't have yet, to keep the list scannable.
+     */
+    getRowMark(action) {
+        if (action.preset) {
+            const installed = this.installedServers.find((server) => server.name === action.preset.id);
+            return installed ? fg(installed.disabled ? this.t.muted : this.t.success, "✓ ") : "  ";
+        }
+        if (action.installed) {
+            if (action.installed.disabled)
+                return fg(this.t.muted, "⊘ ");
+            if (action.installed.authCapable && !action.installed.signedIn)
+                return fg(this.t.warning, "! ");
+            return fg(this.t.success, "✓ ");
+        }
+        return "";
+    }
+    getActions() {
+        switch (this.activeTab) {
+            case "presets":
+                return this.getPresetsTabActions();
+            case "custom":
+                return this.getCustomTabActions();
+            case "installed":
+                return this.getInstalledTabActions();
+        }
+    }
+    cycleTab(direction) {
+        const order = SETUP_TABS.map((tab) => tab.id);
+        const index = order.indexOf(this.activeTab);
+        this.activeTab = order[(index + direction + order.length) % order.length];
+        this.actionCursor = 0;
+        this.notice = null;
+        this.tui.requestRender();
+    }
     getDetectedPaths() {
         const paths = [
             ...this.discovery.sources.filter((source) => source.exists).map((source) => source.path),
@@ -146,10 +295,6 @@ export class McpSetupPanel {
         ];
         return [...new Set(paths)];
     }
-    getSelectedAction() {
-        const actions = this.getActions();
-        return actions[this.actionCursor];
-    }
     handleInput(data) {
         this.resetInactivityTimeout();
         if (!this.busy)
@@ -161,6 +306,13 @@ export class McpSetupPanel {
         }
         if (matchesKey(data, "escape")) {
             if (this.screen === "imports" || this.screen === "paths") {
+                // Both are only reachable from the Advanced sub-screen now — back out one level, not all the way to the tabs.
+                this.screen = "advanced";
+                this.tui.requestRender();
+                return;
+            }
+            if (this.screen === "confirm-preset" || this.screen === "advanced") {
+                this.pendingAction = undefined;
                 this.screen = this.discovery.hasAnyConfig ? "setup" : "empty";
                 this.tui.requestRender();
                 return;
@@ -179,6 +331,22 @@ export class McpSetupPanel {
             this.handlePathsInput(data);
             return;
         }
+        if (this.screen === "confirm-preset") {
+            this.handleConfirmPresetInput(data);
+            return;
+        }
+        if (this.screen === "advanced") {
+            this.handleAdvancedInput(data);
+            return;
+        }
+        if (matchesKey(data, "left")) {
+            this.cycleTab(-1);
+            return;
+        }
+        if (matchesKey(data, "right")) {
+            this.cycleTab(1);
+            return;
+        }
         const actions = this.getActions();
         if (this.keys.selectUp(data)) {
             this.actionCursor = Math.max(0, this.actionCursor - 1);
@@ -190,6 +358,14 @@ export class McpSetupPanel {
             this.tui.requestRender();
             return;
         }
+        if (data === "o" || data === "O") {
+            this.openSelectedDocs();
+            return;
+        }
+        if ((data === "a" || data === "A") && this.activeTab === "installed") {
+            this.authenticateSelected();
+            return;
+        }
         if (this.keys.selectConfirm(data)) {
             const selected = this.getSelectedAction();
             if (selected)
@@ -247,13 +423,118 @@ export class McpSetupPanel {
             });
         }
     }
-    async runAction(action) {
-        if (action.id === "run-setup") {
-            this.screen = "setup";
-            this.actionCursor = 0;
+    handleAdvancedInput(data) {
+        const actions = this.getAdvancedActions();
+        if (this.keys.selectUp(data)) {
+            this.advancedCursor = Math.max(0, this.advancedCursor - 1);
+            this.tui.requestRender();
+            return;
+        }
+        if (this.keys.selectDown(data)) {
+            this.advancedCursor = Math.min(actions.length - 1, this.advancedCursor + 1);
             this.tui.requestRender();
             return;
         }
+        if (this.keys.selectConfirm(data)) {
+            const selected = actions[this.advancedCursor];
+            if (selected)
+                void this.runAction(selected);
+        }
+    }
+    handleConfirmPresetInput(data) {
+        if (data === "o" || data === "O") {
+            this.openSelectedDocs();
+            return;
+        }
+        if (this.keys.selectConfirm(data)) {
+            void this.confirmPendingAction();
+        }
+    }
+    /** Getter used by openSelectedDocs while the confirm screen is up (no action-list cursor there). */
+    getSelectedAction() {
+        if (this.screen === "confirm-preset")
+            return this.pendingAction;
+        const actions = this.getActions();
+        return actions[this.actionCursor];
+    }
+    /** Add or replace an entry so the Installed tab and Presets "active" tag update immediately, without closing the panel. */
+    upsertInstalledServer(entry) {
+        const index = this.installedServers.findIndex((server) => server.name === entry.name);
+        if (index === -1)
+            this.installedServers.push(entry);
+        else
+            this.installedServers[index] = entry;
+    }
+    async confirmPendingAction() {
+        const action = this.pendingAction;
+        if (!action)
+            return;
+        if (action.id === "add-repoprompt") {
+            await this.runBusy(async () => {
+                const result = await this.callbacks.addRepoPrompt();
+                this.callbacks.markSetupCompleted();
+                this.upsertInstalledServer({
+                    name: result.serverName,
+                    disabled: false,
+                    kind: "stdio",
+                    authCapable: false,
+                    signedIn: false,
+                });
+                this.notice = {
+                    text: `Added ${result.serverName} to ${result.path}. Nexus will reload after this panel closes.`,
+                    tone: "success",
+                };
+            });
+        }
+        else if (action.id === "add-known-server" && action.preset) {
+            const preset = action.preset;
+            const authCapable = preset.entry.auth === "oauth";
+            await this.runBusy(async () => {
+                const result = await this.callbacks.addKnownServer(preset);
+                this.callbacks.markSetupCompleted();
+                const kind = preset.entry.command ? "stdio" : "http";
+                this.upsertInstalledServer({
+                    name: result.serverName,
+                    disabled: false,
+                    kind,
+                    authCapable,
+                    signedIn: false,
+                });
+                if (!authCapable) {
+                    this.notice = {
+                        text: `Added ${result.serverName} to ${result.path}. Nexus will reload after this panel closes.`,
+                        tone: "success",
+                    };
+                    return;
+                }
+                // Sign in right now, in the same flow — this is the whole point of a preset:
+                // don't make the user hunt down a separate command after the fact.
+                this.notice = { text: `Added ${result.serverName}. Opening your browser to sign in…`, tone: "muted" };
+                this.tui.requestRender();
+                const authResult = await this.callbacks.authenticateServer(result.serverName, preset.entry);
+                this.upsertInstalledServer({
+                    name: result.serverName,
+                    disabled: false,
+                    kind,
+                    authCapable,
+                    signedIn: authResult.ok,
+                });
+                this.notice = authResult.ok
+                    ? {
+                        text: `Added and signed in to ${result.serverName} (${result.path}). Nexus will reload after this panel closes.`,
+                        tone: "success",
+                    }
+                    : {
+                        text: `Added ${result.serverName} to ${result.path}, but sign-in didn't finish: ${authResult.message} Retry anytime from the Installed tab (press "a").`,
+                        tone: "warning",
+                    };
+            });
+        }
+        this.pendingAction = undefined;
+        this.screen = this.discovery.hasAnyConfig ? "setup" : "empty";
+        this.tui.requestRender();
+    }
+    async runAction(action) {
         if (action.id === "adopt-imports") {
             this.screen = "imports";
             this.importCursor = 0;
@@ -277,34 +558,38 @@ export class McpSetupPanel {
             });
             return;
         }
-        if (action.id === "add-repoprompt") {
-            await this.runBusy(async () => {
-                const result = await this.callbacks.addRepoPrompt();
-                this.callbacks.markSetupCompleted();
-                this.notice = {
-                    text: `Added ${result.serverName} to ${result.path}. Nexus will reload after this panel closes.`,
-                    tone: "success",
-                };
-            });
+        if (action.id === "add-repoprompt" || (action.id === "add-known-server" && action.preset)) {
+            this.pendingAction = action;
+            this.screen = "confirm-preset";
+            this.tui.requestRender();
             return;
         }
-        if (action.id === "add-known-server" && action.preset) {
-            const preset = action.preset;
+        if (action.id === "add-custom-stdio" || action.id === "add-custom-url") {
+            const template = action.id === "add-custom-stdio" ? "/mcp add my-server -- " : "/mcp add my-server --url ";
+            this.callbacks.seedEditor(template);
+            this.cleanup();
+            this.done();
+            return;
+        }
+        if (action.id === "open-advanced") {
+            this.screen = "advanced";
+            this.advancedCursor = 0;
+            this.tui.requestRender();
+            return;
+        }
+        if (action.id === "view-installed-server" && action.installed) {
+            const server = action.installed;
+            const nextDisabled = !server.disabled;
             await this.runBusy(async () => {
-                const result = await this.callbacks.addKnownServer(preset);
-                this.callbacks.markSetupCompleted();
+                const result = await this.callbacks.toggleServerDisabled(server.name, nextDisabled);
+                this.upsertInstalledServer({ ...server, disabled: nextDisabled });
                 this.notice = {
-                    text: `Added ${result.serverName} to ${result.path}. Nexus will reload after this panel closes.`,
+                    text: `${nextDisabled ? "Disabled" : "Enabled"} "${server.name}" in ${result.path} — run /reload to apply.`,
                     tone: "success",
                 };
             });
             return;
         }
-        if (action.id === "close") {
-            this.cleanup();
-            this.done();
-            return;
-        }
         this.notice = {
             text: "Review the details below. Press Enter on an action with a side effect to apply it.",
             tone: "muted",
@@ -330,8 +615,39 @@ export class McpSetupPanel {
                         tone: "success",
                     }
                     : { text: `No changes needed in ${result.path}.`, tone: "muted" };
-            this.screen = this.discovery.hasAnyConfig ? "setup" : "empty";
-            this.actionCursor = 0;
+            this.screen = "advanced";
+            this.advancedCursor = 0;
+        });
+    }
+    openSelectedDocs() {
+        const selected = this.getSelectedAction();
+        const docsUrl = selected?.preset?.docsUrl;
+        if (!docsUrl) {
+            this.notice = { text: "No docs link for this item.", tone: "muted" };
+            this.tui.requestRender();
+            return;
+        }
+        void this.runBusy(async () => {
+            await this.callbacks.openPath(docsUrl);
+            this.notice = { text: `Opened ${docsUrl}`, tone: "success" };
+        });
+    }
+    authenticateSelected() {
+        const selected = this.getSelectedAction();
+        const server = selected?.installed;
+        if (!server)
+            return;
+        if (!server.authCapable) {
+            this.notice = { text: `"${server.name}" isn't configured for OAuth sign-in.`, tone: "muted" };
+            this.tui.requestRender();
+            return;
+        }
+        void this.runBusy(async () => {
+            this.notice = { text: `Opening your browser to sign in to "${server.name}"…`, tone: "muted" };
+            this.tui.requestRender();
+            const result = await this.callbacks.authenticateServer(server.name);
+            this.upsertInstalledServer({ ...server, signedIn: result.ok });
+            this.notice = { text: result.message, tone: result.ok ? "success" : "warning" };
         });
     }
     async runBusy(fn) {
@@ -385,17 +701,56 @@ export class McpSetupPanel {
         else if (this.screen === "paths") {
             lines.push(...this.renderPaths(innerW));
         }
+        else if (this.screen === "confirm-preset") {
+            lines.push(...this.renderConfirmPreset(innerW));
+        }
+        else if (this.screen === "advanced") {
+            lines.push(...this.renderAdvanced(innerW));
+        }
         else {
             lines.push(...this.renderActions(innerW));
         }
         lines.push(`└${border}┘`);
-        return lines;
+        return this.clampHeight(lines, innerW, border);
+    }
+    setMaxHeight(lines) {
+        this.maxHeight = lines;
+    }
+    /**
+     * The overlay host may cap total rows and, absent this hook, would slice
+     * blindly from the bottom — cutting off the closing border and leaving the
+     * box looking broken. Truncate the content instead, keeping the header and
+     * action list (the interactive part) and dropping preview/diff lines first.
+     */
+    clampHeight(lines, innerW, _border) {
+        if (this.maxHeight === undefined || lines.length <= this.maxHeight)
+            return lines;
+        const budget = Math.max(5, this.maxHeight);
+        // The last line is the closing border, the one before it is the hint/controls
+        // line — both must always stay visible, or the panel loses its own instructions.
+        const closing = lines[lines.length - 1];
+        const footer = lines[lines.length - 2];
+        const head = lines.slice(0, Math.max(1, budget - 3));
+        const hidden = lines.length - head.length - 2;
+        if (hidden <= 0)
+            return lines;
+        return [
+            ...head,
+            this.padLine(fg(this.t.muted, `… ${hidden} more line${hidden === 1 ? "" : "s"} hidden to fit the window`), innerW),
+            footer,
+            closing,
+        ];
+    }
+    renderTabBar() {
+        return SETUP_TABS.map((tab) => tab.id === this.activeTab ? fg(this.t.selected, `[ ${tab.label} ]`) : fg(this.t.muted, `  ${tab.label}  `)).join(" ");
     }
     renderActions(innerW) {
         const lines = [];
         const actions = this.getActions();
         const compact = innerW < COMPACT_WIDTH;
         const { start, end } = compact ? this.visibleActionRange(actions.length) : { start: 0, end: actions.length };
+        lines.push(this.padLine(this.renderTabBar(), innerW));
+        lines.push(this.padLine("", innerW));
         if (start > 0) {
             lines.push(this.padLine(fg(this.t.muted, `… ${start} more above`), innerW));
         }
@@ -403,23 +758,46 @@ export class McpSetupPanel {
             const action = actions[index];
             if (!action)
                 continue;
-            if (action.id === "add-known-server" && (index === start || actions[index - 1]?.id !== "add-known-server")) {
-                lines.push(this.padLine(fg(this.t.title, "Add a known server"), innerW));
-            }
             const selected = index === this.actionCursor;
             const cursor = selected ? fg(this.t.selected, "›") : " ";
-            lines.push(this.padLine(`${cursor} ${truncateToWidth(action.label, this.contentWidth(innerW) - 2)}`, innerW));
+            const mark = this.getRowMark(action);
+            const label = truncateToWidth(action.label, Math.max(1, this.contentWidth(innerW) - 2 - visibleWidth(mark)));
+            const installedColor = action.installed
+                ? action.installed.disabled
+                    ? this.t.muted
+                    : action.installed.authCapable && !action.installed.signedIn
+                        ? this.t.warning
+                        : this.t.success
+                : undefined;
+            const labelRendered = action.preset
+                ? fg(presetAccent(action.preset), label)
+                : installedColor
+                    ? fg(installedColor, label)
+                    : label;
+            lines.push(this.padLine(`${cursor} ${mark}${labelRendered}`, innerW));
         }
         if (end < actions.length) {
             lines.push(this.padLine(fg(this.t.muted, `… ${actions.length - end} more below`), innerW));
         }
         lines.push(this.padLine("", innerW));
-        const preview = this.getActionPreview(this.getSelectedAction(), this.previewWidth(innerW));
-        for (const line of preview) {
-            lines.push(this.padLine(line, innerW));
+        // Presets stay a clean, scannable list — no inline summary/diff while browsing.
+        // The write preview only shows on the confirm screen, after pressing Enter.
+        if (this.activeTab !== "presets") {
+            const preview = this.getActionPreview(this.getSelectedAction(), this.previewWidth(innerW));
+            for (const line of preview) {
+                lines.push(this.padLine(line, innerW));
+            }
+            lines.push(this.padLine("", innerW));
         }
-        lines.push(this.padLine("", innerW));
-        const hint = compact ? "Enter select · Esc back" : "Enter selects, Esc goes back, Ctrl+C closes.";
+        const docsHint = this.activeTab === "presets" ? " · o docs" : "";
+        const confirmHint = this.activeTab === "presets" ? " · enter to review & confirm" : "";
+        const checkHint = this.activeTab === "presets" && this.installedServers.length > 0 ? " · ✓ already added" : "";
+        const authHint = this.activeTab === "installed" && this.installedServers.some((server) => server.authCapable)
+            ? " · a sign in"
+            : "";
+        const hint = compact
+            ? `Enter select · ←/→ tabs${docsHint} · Esc back`
+            : `Enter selects${confirmHint}, ←/→ switch tabs${docsHint}${checkHint}${authHint}, Esc goes back, Ctrl+C closes.`;
         lines.push(this.padLine(fg(this.t.muted, hint), innerW));
         return lines;
     }
@@ -458,6 +836,48 @@ export class McpSetupPanel {
         }
         return lines;
     }
+    renderAdvanced(innerW) {
+        const lines = [];
+        const actions = this.getAdvancedActions();
+        lines.push(this.padLine(`${fg(this.t.muted, "Custom")} > ${fg(this.t.title, "Advanced options")}`, innerW));
+        lines.push(this.padLine("", innerW));
+        if (actions.length === 0) {
+            lines.push(this.padLine(fg(this.t.muted, "Nothing here right now — nice, config is already tidy."), innerW));
+        }
+        for (let index = 0; index < actions.length; index++) {
+            const action = actions[index];
+            if (!action)
+                continue;
+            const cursor = index === this.advancedCursor ? fg(this.t.selected, "›") : " ";
+            const label = truncateToWidth(action.label, Math.max(1, this.contentWidth(innerW) - 2));
+            lines.push(this.padLine(`${cursor} ${label}`, innerW));
+        }
+        lines.push(this.padLine("", innerW));
+        // This is the one screen where showing the full explanation on highlight is the point —
+        // you only ever get here by deliberately asking for "Advanced options".
+        const preview = this.getActionPreview(actions[this.advancedCursor], this.previewWidth(innerW));
+        for (const line of preview) {
+            lines.push(this.padLine(line, innerW));
+        }
+        lines.push(this.padLine("", innerW));
+        lines.push(this.padLine(fg(this.t.muted, "Enter selects, Esc back to Custom, Ctrl+C closes."), innerW));
+        return lines;
+    }
+    renderConfirmPreset(innerW) {
+        const lines = [];
+        const action = this.pendingAction;
+        const name = action?.preset?.name ?? (action?.id === "add-repoprompt" ? "RepoPrompt" : "this server");
+        lines.push(this.padLine(fg(this.t.title, `Confirm: add ${name}`), innerW));
+        lines.push(this.padLine("", innerW));
+        const preview = this.getActionPreview(action, this.previewWidth(innerW));
+        for (const line of preview) {
+            lines.push(this.padLine(line, innerW));
+        }
+        lines.push(this.padLine("", innerW));
+        const docsHint = action?.preset?.docsUrl ? " · o docs" : "";
+        lines.push(this.padLine(fg(this.t.muted, `Enter writes this file${docsHint} · Esc goes back`), innerW));
+        return lines;
+    }
     discoverySummaryLine() {
         if (!this.discovery.hasAnyConfig) {
             return fg(this.t.warning, this.options.onboardingState.setupCompleted
@@ -501,10 +921,6 @@ export class McpSetupPanel {
     }
     getActionPreview(action, previewW = DESKTOP_PREVIEW_WIDTH) {
         switch (action?.id) {
-            case "run-setup":
-                return this.formatPreview([
-                    "Run setup to adopt host-specific imports, inspect detected paths, and scaffold a minimal `.nexus/mcp.json` if needed.",
-                ], previewW);
             case "adopt-imports":
                 return this.formatWritePreview("Compatibility import write preview", this.callbacks.previewImports(this.discovery.imports
                     .filter((entry) => this.selectedImports.has(entry.kind))
@@ -513,31 +929,50 @@ export class McpSetupPanel {
                     "Selected imports are written to the Nexus global MCP configuration shown above.",
                 ], previewW);
             case "view-example":
+                return [
+                    ...this.formatPreview(["Example Nexus `.nexus/mcp.json`:"], previewW),
+                    // Truncate, don't word-wrap: wrapText would collapse JSON's indentation.
+                    ...[
+                        "{",
+                        '  "mcpServers": {',
+                        '    "chrome-devtools": {',
+                        '      "command": "npx",',
+                        '      "args": ["-y", "chrome-devtools-mcp@1.6.0"]',
+                        "    }",
+                        "  }",
+                        "}",
+                    ].map((line) => colorizeJsonLine(truncateToWidth(line, previewW, "…"))),
+                    ...this.formatPreview([
+                        "",
+                        "Use Scaffold project `.nexus/mcp.json` when you want a safe empty shell instead of a live example server.",
+                    ], previewW),
+                ];
+            case "show-precedence": {
+                const hostNote = this.discovery.hostConfigDiscovery === "off"
+                    ? "Configs from other tools (Cursor, Claude Code, VS Code, etc.) are NOT being read right now — Nexus only looks at its own two files above. You can turn that on if you'd rather not redefine servers you already set up elsewhere."
+                    : this.discovery.hostConfigDiscovery === "prompt"
+                        ? "Nexus will ask before reading configs from other tools (Cursor, Claude Code, VS Code, etc.). If you say yes, they're used as a fallback — only for a server name that isn't already defined in either file above."
+                        : "Nexus is also reading configs from other tools (Cursor, Claude Code, VS Code, etc.) as a fallback — they only apply to a server name that isn't already defined in either file above.";
+                const conflictNote = this.discovery.conflicts.length === 0
+                    ? "Right now no server name is defined in more than one place, so there's nothing actually being overridden."
+                    : `Right now ${this.discovery.conflicts.length} server name${this.discovery.conflicts.length === 1 ? " is" : "s are"} defined in more than one place — whichever file is read last wins, and the loser is silently ignored:`;
                 return this.formatPreview([
-                    "Example Nexus `.nexus/mcp.json`:",
-                    "{",
-                    '  "mcpServers": {',
-                    '    "chrome-devtools": {',
-                    '      "command": "npx",',
-                    '      "args": ["-y", "chrome-devtools-mcp@1.6.0"]',
-                    "    }",
-                    "  }",
-                    "}",
+                    "Nexus can load MCP servers from a few different places, so when the same server name shows up twice, something has to decide which definition actually gets used.",
                     "",
-                    "Use Scaffold project `.nexus/mcp.json` when you want a safe empty shell instead of a live example server.",
-                ], previewW);
-            case "show-precedence":
-                return this.formatPreview([
-                    "Read order (later entries win):",
-                    "0. detected host configs (opt-in lowest-precedence fallback)",
-                    "1. ~/.config/nexus/mcp.json",
-                    `2. ${getConfigDirName()}/mcp.json`,
-                    `Host discovery: ${this.discovery.hostConfigDiscovery}. Conflicts reported: ${this.discovery.conflicts.length}.`,
+                    "It reads, in this order — each one can override a server name defined before it:",
+                    "  1. Global — ~/.config/nexus/mcp.json (applies to every project on this machine)",
+                    `  2. Project — ${getConfigDirName()}/mcp.json (just this project; wins over global for the same name)`,
+                    "",
+                    hostNote,
+                    "",
+                    "Everything you add from this panel (a preset, a custom server) gets written to the project file, so it's scoped to this project and takes priority over anything global.",
+                    "",
+                    conflictNote,
                     ...this.discovery.conflicts
                         .slice(0, 8)
-                        .map((conflict) => `${conflict.serverName}: ${conflict.sources.map((source) => source.path).join(" -> ")} (winner: ${conflict.winner.path})`),
-                    "Nexus writes global MCP state to ~/.config/nexus/mcp.json and project state to .nexus/mcp.json.",
+                        .map((conflict) => `  ${conflict.serverName}: ${conflict.sources.map((source) => source.path).join(" then ")} — "${conflict.winner.path}" wins`),
                 ], previewW);
+            }
             case "open-paths":
                 return this.formatPreview(this.getDetectedPaths().length > 0
                     ? ["Detected paths:", ...this.getDetectedPaths()]
@@ -558,13 +993,60 @@ export class McpSetupPanel {
                 const preset = action.preset;
                 if (!preset)
                     return this.formatPreview(["Known server preset is unavailable."], previewW);
-                return this.formatWritePreview(`${preset.name} write preview`, this.callbacks.previewKnownServer(preset), [preset.summary], previewW);
+                return this.formatWritePreview(`${preset.name} write preview`, this.callbacks.previewKnownServer(preset), [preset.summary, ...(preset.docsUrl ? [`Docs: ${preset.docsUrl}`, 'Press "o" to open docs.'] : [])], previewW);
             }
             case "scaffold-project":
                 return this.formatWritePreview("Starter project `.nexus/mcp.json` write preview", this.callbacks.previewStarterProject(), [
-                    "This writes a minimal `.nexus/mcp.json` in the current project using the Nexus MCP layout.",
-                    "It intentionally avoids adding a fake placeholder server that would fail on first reload.",
+                    `This creates ${getConfigDirName()}/mcp.json right here in this project — the file everything you add from the Presets or Custom tab actually gets written into. If you already have one, this action doesn't show up (check the Installed tab instead).`,
+                    "",
+                    `It starts out empty on purpose (just an empty "mcpServers" list). A fake placeholder server would fail the moment Nexus tried to connect to it on your very next reload, so this just gives you a valid, empty file to add real servers into afterward.`,
                 ], previewW);
+            case "add-custom-stdio":
+                return [
+                    ...this.formatPreview(["Runs a command on your machine over stdio — e.g. an npx-installed MCP server."], previewW),
+                    "",
+                    colorizeCommandLine(truncateToWidth("/mcp add <name> -- <command> [args...]", previewW, "…")),
+                    "",
+                    fg(this.t.muted, "Example (real, runnable):"),
+                    colorizeCommandLine(truncateToWidth("/mcp add chrome-devtools -- npx -y chrome-devtools-mcp@1.6.0", previewW, "…")),
+                    "",
+                    ...this.formatPreview([
+                        'Enter fills in "/mcp add my-server -- " into the chat input below — finish typing there.',
+                        "Run `/mcp add` with no arguments (from chat) for the full flag list.",
+                    ], previewW),
+                ];
+            case "add-custom-url":
+                return [
+                    ...this.formatPreview(["Connects to a remote MCP server over HTTP."], previewW),
+                    "",
+                    colorizeCommandLine(truncateToWidth("/mcp add <name> --url <url> [--header K=V] [--auth oauth|bearer] [--bearer-env VAR]", previewW, "…")),
+                    "",
+                    fg(this.t.muted, "Example (real, runnable):"),
+                    colorizeCommandLine(truncateToWidth("/mcp add context7 --url https://mcp.context7.com/mcp", previewW, "…")),
+                    "",
+                    ...this.formatPreview([
+                        'Enter fills in "/mcp add my-server --url " into the chat input below — finish typing there.',
+                        "Run `/mcp add` with no arguments (from chat) for the full flag list.",
+                    ], previewW),
+                ];
+            case "view-installed-server": {
+                const server = action.installed;
+                if (!server)
+                    return this.formatPreview(["Add a server from the Presets or Custom tab to see it here."], previewW);
+                return this.formatPreview([
+                    `${server.name} — ${server.kind === "stdio" ? "local (stdio)" : "remote (HTTP)"}, currently ${server.disabled ? "disabled" : "active"}${server.authCapable ? (server.signedIn ? ", signed in" : ", NOT signed in yet") : ""}.`,
+                    "",
+                    `Press Enter to ${server.disabled ? "enable" : "disable"} it here. Takes effect after /reload.`,
+                    ...(server.authCapable
+                        ? [
+                            "",
+                            server.signedIn
+                                ? 'Press "a" to sign in again (e.g. to switch accounts). This re-opens your browser.'
+                                : 'Press "a" to sign in now — opens your browser for this server\'s OAuth login. Tokens refresh automatically after that; you should not need to repeat this unless access is revoked.',
+                        ]
+                        : []),
+                ], previewW);
+            }
             default:
                 return this.formatPreview(["Close the setup flow."], previewW);
         }
@@ -589,10 +1071,14 @@ export class McpSetupPanel {
             : "New file will be created. Showing exact content diff.", width));
         lines.push("");
         const diffLines = preview.diffText.split("\n");
-        const maxLines = 18;
+        const maxLines = 12;
         const shown = diffLines.slice(0, maxLines);
         for (const line of shown) {
-            lines.push(...wrapText(line, width));
+            // Truncate, don't word-wrap: wrapText collapses whitespace and would
+            // destroy JSON's nested indentation.
+            const color = diffLineColor(line);
+            const truncated = truncateToWidth(line, width, "…");
+            lines.push(color ? fg(color, truncated) : colorizeJsonLine(truncated));
         }
         if (diffLines.length > maxLines) {
             lines.push(...wrapText(`… ${diffLines.length - maxLines} more diff line${diffLines.length - maxLines === 1 ? "" : "s"}`, width));