pi-archimedes 2.8.0 → 2.9.0

package/README.md

@@ -3,7 +3,7 @@
 
 An extra pair of eyes on your code. Agents working in parallel. A terminal that keeps you in the loop—and looks good doing it.
 
-**Archimedes brings subagents, shared task lists, MCP tools, and a polished interface to [Pi](https://github.com/earendil-works/pi). Install them together, use what you like, and make the setup yours.**
+**Archimedes brings subagents, shared task lists, and a polished interface to [Pi](https://github.com/earendil-works/pi). Install them together, use what you like, and make the setup yours.**
 
 [![npm version](https://img.shields.io/npm/v/pi-archimedes?style=flat-square)](https://www.npmjs.com/package/pi-archimedes)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.19.0-brightgreen?style=flat-square)](https://nodejs.org)
@@ -23,7 +23,7 @@ One command:
 pi install npm:pi-archimedes
 ```
 
-Your `~/.pi/agent/` stays as it is — Archimedes only adds its namespaces under `settings.json`. Pi's own `auth.json`, `keybindings.json`, agents, and sessions are untouched (and `/mcp setup` only writes the project's `.mcp.json`, when you run it).
+Your `~/.pi/agent/` stays as it is — Archimedes only adds its namespaces under `settings.json`. Pi's own `auth.json`, `keybindings.json`, agents, and sessions are untouched.
 
 Then run `/reload` in your session (or start a new one) to pick it up — that reloads the extensions *and* your keybindings, so any shortcuts you've customized in `~/.pi/agent/keybindings.json` keep working.
 
@@ -104,14 +104,6 @@ You don't have to copy messages between terminals to stay involved.
 
 ---
 
-## Bring the tools you already use.
-
-[Connect MCP servers](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/mcp/README.md), browse their tools, and handle authentication inside Pi. Import server definitions from Cursor, Claude Code, Claude Desktop, or VS Code rather than rebuilding your setup.
-
-Start with `/mcp setup`. Manage it with `/mcp`.
-
----
-
 ## See what changed. Not just that something changed.
 
 [Syntax-highlighted diffs](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/diff/README.md), side by side when there's room and unified when there isn't. Word-level highlights draw your eye to the changes inside each line.
@@ -150,7 +142,7 @@ You can leave the terminal to do its thing.
 
 One install brings everything together. Switch optional extensions on or off with `/plugins`, then `/reload` to apply. Use `/archimedes` to adjust the available settings.
 
-Only want the diffs, footer, or MCP tools? Each component is available separately — see [Components](#components).
+Only want the diffs or footer? Each component is available separately — see [Components](#components).
 
 ---
 
@@ -158,11 +150,10 @@ Only want the diffs, footer, or MCP tools? Each component is available separatel
 
 | Command | Scope | Notes |
 |---------|-------|-------|
-| `/plugins` | Suite | Toggle the ten optional extensions (core is always on and not toggleable). Toggles persist immediately; `/reload` (or a fresh session) applies them. |
+| `/plugins` | Suite | Toggle the eleven optional extensions (core is always on and not toggleable). Toggles persist immediately; `/reload` (or a fresh session) applies them. |
 | `/archimedes` | Suite | Interactive settings panel — up/down moves, left/right changes values, Enter edits supported fields, `s` saves, Esc discards the current edits. Settings captured at startup need `/reload`. Not every setting has a panel control. |
 | `/agents` | Suite, subagent enabled | Browse, create, and edit custom subagent definitions in `.pi/agents/*.md`. |
 | `/todos` | Todo component | Refreshes the todo widget and reports its status. `/todos clear` clears the list. (The board's visibility is not a `/todos` toggle — see the [todo docs](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/todo/README.md).) |
-| `/mcp`, `/mcp setup` | MCP component | Manage servers and run logins; the setup wizard scaffolds `.mcp.json` or imports configs from Cursor, Claude Code, Claude Desktop, or VS Code. |
 | `/sudo`, `/sudo forget` | Sudo component | Inspect cached credential state; `forget` clears it. |
 | `/reload` | Pi | Applies plugin changes and settings read at startup. |
 
@@ -170,7 +161,7 @@ Only want the diffs, footer, or MCP tools? Each component is available separatel
 
 ## Settings
 
-Every component keeps its own namespace under `~/.pi/agent/settings.json`, which Pi parses as **strict JSON** (no comments — unlike MCP server configs, which accept JSONC). Each component's README documents its namespace, fields, and defaults — including [core](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/core/README.md) (chrome, spinner, thinking), [footer](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/footer/README.md), [diff](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/diff/README.md), [notify](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/notify/README.md), [mcp](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/mcp/README.md), [image-paste](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/image-paste/README.md), and [sudo](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/sudo/README.md) (also strict JSON). The `/archimedes` panel covers the settings that have a control; not everything does.
+Every component keeps its own namespace under `~/.pi/agent/settings.json`, which Pi parses as **strict JSON**. Each component's README documents its namespace, fields, and defaults — including [core](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/core/README.md) (chrome, spinner, thinking), [footer](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/footer/README.md), [diff](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/diff/README.md), [notify](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/notify/README.md), [image-paste](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/image-paste/README.md), and [sudo](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/sudo/README.md) (also strict JSON). The `/archimedes` panel covers the settings that have a control; not everything does.
 
 ---
 
@@ -182,7 +173,6 @@ Every component keeps its own namespace under `~/.pi/agent/settings.json`, which
 | **Subagent** | [`@pi-archimedes/subagent`](https://www.npmjs.com/package/@pi-archimedes/subagent) | Live subagent dispatch, custom agent definitions; `/agents` editor with the suite |
 | **Todo** | [`@pi-archimedes/todo`](https://www.npmjs.com/package/@pi-archimedes/todo) | Multi-column todo board with subagent columns and auto-clear |
 | **Ask** | [`@pi-archimedes/ask`](https://www.npmjs.com/package/@pi-archimedes/ask) | Structured questions — including subagent questions relayed into your terminal |
-| **MCP** | [`@pi-archimedes/mcp`](https://www.npmjs.com/package/@pi-archimedes/mcp) | `/mcp` management, setup wizard, OAuth, config imports |
 | **Sudo** | [`@pi-archimedes/sudo`](https://www.npmjs.com/package/@pi-archimedes/sudo) | `sudo_exec` with masked password prompt and interactive-sudo guard |
 | **Diff** | [`@pi-archimedes/diff`](https://www.npmjs.com/package/@pi-archimedes/diff) | Syntax-highlighted side-by-side and unified diffs with word-level highlights |
 | **Footer** | [`@pi-archimedes/footer`](https://www.npmjs.com/package/@pi-archimedes/footer) | Branch, model, context usage, and token/cost status bar |
@@ -199,7 +189,6 @@ pi install npm:@pi-archimedes/core
 pi install npm:@pi-archimedes/subagent
 pi install npm:@pi-archimedes/todo
 pi install npm:@pi-archimedes/ask
-pi install npm:@pi-archimedes/mcp
 pi install npm:@pi-archimedes/sudo
 pi install npm:@pi-archimedes/diff
 pi install npm:@pi-archimedes/footer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-archimedes",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -9,32 +9,33 @@
   "keywords": [
     "pi-package"
   ],
-  "description": "Parallel agents, shared task lists, MCP tools, and a polished terminal for the Pi coding agent.",
+  "description": "Parallel agents, shared task lists, and a polished terminal for the Pi coding agent.",
   "files": [
     "src",
     "README.md"
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.8.0",
-    "@pi-archimedes/footer": "2.8.0",
-    "@pi-archimedes/diff": "2.8.0",
-    "@pi-archimedes/ask": "2.8.0",
-    "@pi-archimedes/image-paste": "2.8.0",
-    "@pi-archimedes/subagent": "2.8.0",
-    "@pi-archimedes/notify": "2.8.0",
-    "@pi-archimedes/todo": "2.8.0",
-    "@pi-archimedes/session-name": "2.8.0",
-    "@pi-archimedes/mcp": "2.8.0",
-    "@pi-archimedes/sudo": "2.8.0"
+    "@pi-archimedes/core": "2.9.0",
+    "@pi-archimedes/footer": "2.9.0",
+    "@pi-archimedes/diff": "2.9.0",
+    "@pi-archimedes/ask": "2.9.0",
+    "@pi-archimedes/image-paste": "2.9.0",
+    "@pi-archimedes/subagent": "2.9.0",
+    "@pi-archimedes/todo": "2.9.0",
+    "@pi-archimedes/notify": "2.9.0",
+    "@pi-archimedes/session-name": "2.9.0",
+    "@pi-archimedes/sudo": "2.9.0",
+    "@pi-archimedes/ui": "2.9.0",
+    "@pi-archimedes/web": "2.9.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",
     "@earendil-works/pi-tui": ">=0.1.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-tui": "^0.87.0",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/config.ts

@@ -1,20 +1,31 @@
-// ── Re-export core config ──────────────────────────────────────────────
+// ── Re-export UI config ──────────────────────────────────────────────
 
 import {
   loadCoreConfig,
-  saveCoreConfig,
-  DEFAULT_CORE_CONFIG,
-  ANIMATION_STYLES,
   type CoreConfig,
 } from "@pi-archimedes/core/config";
 export {
   loadCoreConfig,
-  saveCoreConfig,
-  DEFAULT_CORE_CONFIG,
-  ANIMATION_STYLES,
   type CoreConfig,
 } from "@pi-archimedes/core/config";
 
+// ── Re-export UI config ──────────────────────────────────────────────
+
+import {
+  loadUIConfig,
+  saveUIConfig,
+  DEFAULT_UI_CONFIG,
+  type UIConfig,
+  ANIMATION_STYLES,
+} from "@pi-archimedes/ui/config";
+export {
+  loadUIConfig,
+  saveUIConfig,
+  DEFAULT_UI_CONFIG,
+  type UIConfig,
+  ANIMATION_STYLES,
+} from "@pi-archimedes/ui/config";
+
 // ── Re-export footer config ────────────────────────────────────────────
 
 import {
@@ -40,6 +51,7 @@ export const DEFAULT_DIFF_CONFIG: DiffConfig = {
   diffTheme: "github-dark",
   diffSplitMinWidth: 150,
   diffSplitMinCodeWidth: 60,
+  diffSplitWrapCheck: true,
 };
 
 const NAMESPACE = "archimedes.diff";
@@ -71,6 +83,7 @@ export {
 
 export function loadAllConfig(): {
   core: CoreConfig;
+  ui: UIConfig;
   footer: FooterConfig;
   diff: DiffConfig;
   notify: NotifyConfig;
@@ -78,6 +91,7 @@ export function loadAllConfig(): {
 } {
   return {
     core: loadCoreConfig(),
+    ui: loadUIConfig(),
     footer: loadFooterConfig(),
     diff: loadDiffConfig(),
     notify: loadNotifyConfig(),

package/src/factory-lifecycle.test.ts

@@ -53,6 +53,9 @@ vi.mock("@pi-archimedes/core/profiler", () => ({
 }));
 vi.mock("@pi-archimedes/core", () => ({
   registerCore: vi.fn(),
+}));
+vi.mock("@pi-archimedes/ui", () => ({
+  registerUI: vi.fn(),
   unpatchConsoleLog: vi.fn(),
 }));
 vi.mock("@pi-archimedes/footer", () => ({ registerFooter: vi.fn() }));
@@ -63,8 +66,8 @@ vi.mock("@pi-archimedes/session-name", () => ({ registerSessionName: vi.fn() }))
 vi.mock("@pi-archimedes/sudo", () => ({ registerSudo: vi.fn() }));
 
 // Dynamic imports done in the session_start handler — mock EXACTLY the
-// properties index.ts uses via destructured `ipMod.*` / `diffMod` / `saMod` /
-// `mcpMod` access (import result objects, not named destructure).
+// properties index.ts uses via destructured `ipMod.*` / `diffMod` / `saMod`
+// access (import result objects, not named destructure).
 vi.mock("@pi-archimedes/diff", () => ({
   registerDiffTools: vi.fn(),
 }));
@@ -80,14 +83,12 @@ vi.mock("@pi-archimedes/subagent", () => ({
   registerSubagent: vi.fn(),
   registerAgentsCommand: vi.fn(),
 }));
-vi.mock("@pi-archimedes/mcp", () => ({
-  registerMcp: vi.fn(),
-}));
 
 // Meta-local modules the factory imports — not under test here
 vi.mock("./config.js", () => ({ loadDiffConfig: vi.fn(() => ({})) }));
 vi.mock("./settings.js", () => ({ openSettings: vi.fn() }));
 vi.mock("./plugin-manager.js", () => ({ registerPluginsCommand: vi.fn() }));
+vi.mock("./onboarding/index.js", () => ({ runOnboarding: vi.fn(async () => {}) }));
 
 // The real plugins.ts gate semantics are what these tests exercise
 // (read via the mocked settings-io on each call → mutable mid-session).
@@ -95,9 +96,11 @@ const { default: metaFactory } = await import("./index.js");
 
 const { registerImagePaste, shutdownImagePaste, initImagePasteSession } =
   await import("@pi-archimedes/image-paste");
+const { unpatchConsoleLog } = await import("@pi-archimedes/ui");
 
 const { offerKeybindingFix } =
   await import("@pi-archimedes/image-paste/keybinding-offer");
+const { runOnboarding } = await import("./onboarding/index.js");
 
 // ── Stub pi: record pi.on() registrations and command/tool registrations ───
 
@@ -132,10 +135,13 @@ function freshFactory(): {
   harness: PiHarness;
   startSession: (ctx: unknown) => Promise<unknown>;
   shutdownSession: () => unknown;
-  /** Fire ONLY the keybinding-offer session_start handler (the one registered
-   *  before the lazy-load handler). Useful for isolating offer behaviour
-   *  without triggering the heavy dynamic-import path. */
-  fireOfferHandler: (ctx: unknown) => void;
+  /** Fire ONLY the first-run (merged) session_start handler (the one
+   *  registered before the lazy-load handler). Useful for isolating the
+   *  offer → onboarding sequencing without triggering the heavy
+   *  dynamic-import path. */
+  fireFirstRunHandler: (ctx: unknown) => void;
+  /** Number of session_start handlers the factory registered. */
+  startRcCount: number;
 } {
   const harness = makePi();
   metaFactory(harness.pi);
@@ -147,18 +153,20 @@ function freshFactory(): {
   // The LAST session_start handler is the lazy-load one (existing tests rely on this).
   const startRc = (startRcs[startRcs.length - 1] ?? expect.fail("no session_start handler")) as (...args: unknown[]) => unknown;
   const shutdownRc = (shutdownRcs[shutdownRcs.length - 1] ?? expect.fail("no session_shutdown handler")) as (...args: unknown[]) => unknown;
-  // The keybinding-offer handler is at index 0 in this fully-mocked harness —
-  // all earlier package registrations are stubbed to no-op vi.fn(); if a
-  // package is un-mocked here, update the index.
-  const offerRc = (startRcs[0] ?? expect.fail("no offer session_start handler")) as (...args: unknown[]) => unknown;
+  // The first-run MERGED handler (offer + onboarding, sequenced) is at
+  // index 0 in this fully-mocked harness — all earlier package
+  // registrations are stubbed to no-op vi.fn(); if a package is un-mocked
+  // here, update the index.
+  const firstRunRc = (startRcs[0] ?? expect.fail("no first-run session_start handler")) as (...args: unknown[]) => unknown;
 
   return {
     harness,
     startSession: (ctx: unknown) => startRc(undefined, ctx) as Promise<unknown>,
     shutdownSession: () => shutdownRc(undefined, {}),
-    fireOfferHandler: (ctx: unknown) => {
-      offerRc(undefined, ctx);
+    fireFirstRunHandler: (ctx: unknown) => {
+      firstRunRc(undefined, ctx);
     },
+    startRcCount: startRcs.length,
   };
 }
 
@@ -182,6 +190,7 @@ describe("image-paste factory lifecycle (registration is config-gated, teardown
     // Session ends → cleanup MUST still run for this session's registration.
     shutdownSession();
     expect(vi.mocked(shutdownImagePaste)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(unpatchConsoleLog)).toHaveBeenCalledTimes(1);
   });
 
   it("registers nothing and tears down nothing when config is off at session start", async () => {
@@ -214,30 +223,68 @@ describe("image-paste factory lifecycle (registration is config-gated, teardown
   });
 });
 
-describe("keybinding-offer wiring (session_start → offerKeybindingFix, fire-and-forget)", () => {
-  it("calls offerKeybindingFix exactly once with the session ctx", () => {
+describe("first-run sequencing (session_start → offerKeybindingFix, then runOnboarding)", () => {
+  it("registers exactly two session_start handlers (merged first-run + lazy-load)", () => {
+    const { startRcCount } = freshFactory();
+    // The keybinding offer and the onboarding are ONE merged handler — not
+    // two stacked first-run dialogs (which is what this guards against).
+    expect(startRcCount).toBe(2);
+  });
+
+  it("calls offerKeybindingFix exactly once with the session ctx (before the onboarding)", () => {
     const ctx = { ui: { theme: "dark" } };
-    // Return a resolved promise so the handler's .catch() has nothing to report.
-    vi.mocked(offerKeybindingFix).mockResolvedValueOnce(undefined);
-    const { fireOfferHandler } = freshFactory();
+    // The merged handler awaits the offer; resolve false so the onboarding
+    // branch runs (a resolved promise, so nothing is left pending).
+    vi.mocked(offerKeybindingFix).mockResolvedValueOnce(false);
+    const { fireFirstRunHandler } = freshFactory();
 
-    // The offer handler is synchronous from the caller's perspective (fire-and-forget).
-    fireOfferHandler(ctx);
+    fireFirstRunHandler(ctx);
 
     expect(vi.mocked(offerKeybindingFix)).toHaveBeenCalledTimes(1);
     expect(vi.mocked(offerKeybindingFix)).toHaveBeenCalledWith(ctx);
   });
 
+  it("when offerKeybindingFix resolves true (reloaded), runOnboarding is NOT called", async () => {
+    // The offer triggered a reload: the reloaded session runs this handler
+    // again (where the offer is a no-op), so the onboarding must NOT run on
+    // the now-stale ctx.
+    vi.mocked(offerKeybindingFix).mockResolvedValueOnce(true);
+    const ctx = { ui: { theme: "dark" } };
+    const { fireFirstRunHandler } = freshFactory();
+
+    fireFirstRunHandler(ctx);
+    // Drain the microtask queue so the awaited offer has resolved.
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(vi.mocked(offerKeybindingFix)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(runOnboarding)).not.toHaveBeenCalled();
+  });
+
+  it("when offerKeybindingFix resolves false, runOnboarding IS called (fire-and-forget)", async () => {
+    vi.mocked(offerKeybindingFix).mockResolvedValueOnce(false);
+    const ctx = { ui: { theme: "dark" } };
+    const { fireFirstRunHandler } = freshFactory();
+
+    fireFirstRunHandler(ctx);
+    // Drain the microtask queue so the awaited offer has resolved and the
+    // (fire-and-forget) onboarding has been kicked off.
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(vi.mocked(offerKeybindingFix)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(runOnboarding)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(runOnboarding)).toHaveBeenCalledWith(ctx);
+  });
+
   it("session_start resolves even when offerKeybindingFix rejects (fire-and-forget safety)", async () => {
     // Arrange: make the mock reject once to simulate an unexpected failure.
     vi.mocked(offerKeybindingFix).mockRejectedValueOnce(new Error("boom"));
     const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
 
     const ctx = { ui: { theme: "dark" } };
-    const { fireOfferHandler } = freshFactory();
+    const { fireFirstRunHandler } = freshFactory();
 
-    // Act: invoke the offer handler; it must not throw synchronously.
-    expect(() => fireOfferHandler(ctx)).not.toThrow();
+    // Act: invoke the handler; it must not throw synchronously.
+    expect(() => fireFirstRunHandler(ctx)).not.toThrow();
 
     // Drain the microtask queue so the .catch() branch has had time to run.
     await new Promise((r) => setTimeout(r, 0));
@@ -247,6 +294,8 @@ describe("keybinding-offer wiring (session_start → offerKeybindingFix, fire-an
       "[archimedes] keybinding offer failed:",
       expect.any(Error),
     );
+    // A failed offer must not block the onboarding (reloaded stays false).
+    expect(vi.mocked(runOnboarding)).toHaveBeenCalledTimes(1);
 
     consoleSpy.mockRestore();
   });

package/src/index.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 import { time as archTime, print as archPrintTimings, reset as archResetTimings } from "@pi-archimedes/core/profiler";
-import { registerCore, unpatchConsoleLog } from "@pi-archimedes/core";
+import { registerCore } from "@pi-archimedes/core";
+import { registerUI, unpatchConsoleLog } from "@pi-archimedes/ui";
 import { registerFooter } from "@pi-archimedes/footer";
 
 // Mark when module finishes evaluating (before factory runs) for gap analysis
@@ -15,9 +16,10 @@ import { registerNotify } from "@pi-archimedes/notify";
 import { registerSessionName } from "@pi-archimedes/session-name";
 import { registerSudo } from "@pi-archimedes/sudo";
 // Light module from the image-paste package (no heavy deps) — the offer
-// gates are self-contained, so it is statically imported and runs in its
-// own top-level session_start handler, independent of the lazy-load.
+// gates are self-contained, so it is statically imported and sequenced in
+// the first-run session_start handler below, before the lazy-load.
 import { offerKeybindingFix } from "@pi-archimedes/image-paste/keybinding-offer";
+import { runOnboarding } from "./onboarding/index.js";
 import { loadDiffConfig } from "./config.js";
 import { openSettings } from "./settings.js"
 import { registerPluginsCommand } from "./plugin-manager.js"
@@ -39,6 +41,10 @@ export default function (pi: ExtensionAPI): void {
   // Register all component extensions (static imports already compiled by jiti above)
   registerCore(pi);
   archTime("registerCore");
+  if (isPluginEnabled("ui")) {
+    registerUI(pi);
+    archTime("registerUI");
+  }
   if (isPluginEnabled("footer")) registerFooter(pi);
   archTime("registerFooter");
 
@@ -79,31 +85,34 @@ export default function (pi: ExtensionAPI): void {
     archPrintTimings();
   });
 
-  // First-run keybinding offer (see the module doc in
-  // packages/image-paste/src/keybinding-offer.ts). Registered at top level
-  // (AGENTS.md), and placed BEFORE the lazy-load handler below: the
-  // module's own gates (config enabled → TUI → flag unset → file absent
-  // → confirm) are self-contained, so ordering with that handler is not a
-  // correctness issue.
+  // First-run flows, sequenced in ONE handler (see the module docs in
+  // packages/image-paste/src/keybinding-offer.ts and meta/src/onboarding/
+  // index.ts): the keybinding offer (if any) fully resolves BEFORE the
+  // onboarding overlay shows — no stacked first-run dialogs.
   //
   // Deliberately NOT gated with isPluginEnabled("image-paste"): that call
   // resolves to isConfigEnabled("archimedes.imagePaste") (ADR 0012), which
   // is exactly the same key the module's own gate 1 already checks — adding
   // a wrapper here would be a redundant duplicate of the identical check.
-  // This handler runs unconditionally on every session_start; the module's
-  // five gates make it a no-op when not applicable.
-  pi.on("session_start", (_event, ctx: ExtensionContext) => {
-    // Fire-and-forget: the offer is async (it may block on a user
-    // confirm) and must never block or take down session startup — any
-    // throw is logged, never propagated.
+  // This handler runs unconditionally on every session_start; the offer's
+  // five gates (and the onboarding's two) make it a no-op when not
+  // applicable.
+  pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+    // The offer may block on a user confirm; it must never fail session
+    // startup — any throw is logged, never propagated.
+    let reloaded = false;
     try {
-      void offerKeybindingFix(ctx).catch((e) => {
-        console.error("[archimedes] keybinding offer failed:", e);
-      });
+      reloaded = await offerKeybindingFix(ctx);
     } catch (e) {
       console.error("[archimedes] keybinding offer failed:", e);
     }
+    // If the offer triggered a reload, the fresh session runs this handler
+    // again (where the offer is a no-op — keybindings.json now exists), so
+    // do NOT run the onboarding on the now-stale ctx.
+    if (reloaded) return;
+    void runOnboarding(ctx).catch((err) => console.error("[archimedes] onboarding failed:", err));
   });
+  archTime("first-run handler");
 
   pi.on("session_start", async (_event, ctx: ExtensionContext) => {
     archTime(`session_start (factory was ${Date.now() - _moduleEvalAt}ms ago)`);
@@ -111,8 +120,8 @@ export default function (pi: ExtensionAPI): void {
     // Update module-level context ref so lazy-loaded callbacks always see current session
     currentCtx = ctx;
 
-    // ── Parallel lazy-load all three packages (saves ~100ms vs sequential) ──
-    const [diffMod, ipMod, saMod, mcpMod] = await Promise.all([
+    // ── Parallel lazy-load all four packages (saves ~100ms vs sequential) ──
+    const [diffMod, ipMod, saMod, webMod] = await Promise.all([
       isPluginEnabled("diff")
         ? import("@pi-archimedes/diff").catch((e) => { console.error("[archimedes] diff load failed:", e); return null; })
         : Promise.resolve(null),
@@ -122,8 +131,11 @@ export default function (pi: ExtensionAPI): void {
       isPluginEnabled("subagent")
         ? import("@pi-archimedes/subagent").catch((e) => { console.error("[archimedes] subagent load failed:", e); return null; })
         : Promise.resolve(null),
-      isPluginEnabled("mcp")
-        ? import("@pi-archimedes/mcp").catch((e) => { console.error("[archimedes] mcp load failed:", e); return null; })
+      isPluginEnabled("web")
+        ? import("@pi-archimedes/web").catch((e) => {
+            console.error("[archimedes] web load failed:", e);
+            return null;
+          })
         : Promise.resolve(null),
     ]);
     archTime("4 packages loaded in parallel");
@@ -151,8 +163,8 @@ export default function (pi: ExtensionAPI): void {
       saMod.registerSubagent(pi);
       saMod.registerAgentsCommand(pi);
     }
-    if (mcpMod) {
-      mcpMod.registerMcp(pi);
+    if (webMod) {
+      webMod.registerWeb(pi);
     }
   });