foundry-design-web-adapter 0.2.0-beta.4 → 0.2.0-beta.6

package/README.md

@@ -6,30 +6,40 @@ Foundry is a local-first precision design workbench for Codex, Cursor, and Claud
 
 Foundry is distributed through npm, so testers do not need GitHub access.
 
-### Recommended: let your coding agent install it
+> **Current public beta:** `0.2.0-beta.6`. Install Foundry with the `@beta` tag. The unqualified npm `latest` tag still points to an earlier beta and is not the current testing channel.
 
-Open the project in Codex, Cursor, or Claude Code and paste:
+Full documentation is available at [withfoundry.ai](https://withfoundry.ai).
 
-```text
-Install Foundry for this project by running npx foundry-design@beta setup --yes. Check the result and tell me when I need to restart.
+### Recommended: one command
+
+Open a terminal in the project, or ask Codex, Cursor, or Claude Code to run:
+
+```bash
+npx foundry-design@beta
 ```
 
-Setup detects the project and active coding agent, installs development-only instrumentation, configures the local agent connection, validates the integration, and records everything it owns for safe updates or removal.
+That command detects the project and active coding agent, installs or safely updates Foundry, repairs the shared agent connection, validates its integration, starts the project when needed, and opens the visual session. On the first installation only, restart the coding agent once so it can load the shared MCP connection. A reviewed batch can be queued before the restart and will be claimed when the agent reconnects.
 
-Restart the coding agent once, reopen the same project folder, and paste:
+After the restart, reopen the same project folder and ask:
 
 ```text
 Start Foundry for this project and keep listening for Apply with agent requests.
 ```
 
-That is the normal workflow. Foundry starts the project when needed, opens an authenticated local preview, and shows **Agent is ready** before it allows an apply request.
+That is the normal workflow. Foundry resumes the most recent session for the current source revision and keeps all review and apply state local.
 
 ### Manual installation
 
-From the project you want to inspect, run:
+From the first project you want to inspect, run:
+
+```bash
+npx foundry-design@beta setup --global
+```
+
+For later projects, keep the shared agent connection and install only the development adapter:
 
 ```bash
-npx foundry-design@beta setup
+npx foundry-design@beta setup --agent none
 ```
 
 Then restart the coding agent, reopen the same project folder, and ask:
@@ -38,7 +48,7 @@ Then restart the coding agent, reopen the same project folder, and ask:
 Start Foundry for this project and keep listening for Apply with agent requests.
 ```
 
-You do not need to run a second terminal command when the agent starts Foundry for you. For a manual-only preview, run `npx foundry-design@beta start`, but Apply with agent still requires a restarted and actively listening coding agent.
+You do not need to run a second terminal command when the agent starts Foundry for you. Apply requests remain queued safely when the agent is offline. Run `npx foundry-design@beta doctor --repair` if the connection or generated integration needs repair.
 
 Update an existing installation with:
 
@@ -56,13 +66,13 @@ npx foundry-design@beta uninstall
 
 Supported automatic web integration currently includes Next.js App Router, Vite, and plain HTML. Generic web, SwiftUI, and React Native projects receive explicit setup guidance when a safe automatic edit is not available.
 
-The repository also contains a portable plugin bundle for future marketplace distribution. The npm setup above is the public beta installation path.
+The npm setup above is the public beta installation path and includes the same portable skill and MCP connection used by the agent plugin bundle.
 
-The beta supports Node.js 20 or newer. Read [Privacy](PRIVACY.md), [Security](SECURITY.md), and the [beta changelog](CHANGELOG.md) before using it with sensitive work.
+The beta supports Node.js 20 or newer. Read the [local-first safety model](https://withfoundry.ai/#safety) before using it with sensitive work.
 
 ## Agent plugin
 
-The portable plugin lives at `plugins/foundry-design-control`. The repository also includes marketplace manifests for Codex, Cursor, and Claude-compatible plugin import. Once installed, ask your agent:
+The portable plugin lives at `plugins/foundry-design-control`. The repository also includes marketplace manifests for Codex, Cursor, and Claude-compatible plugin import. Until public marketplace review is complete, `setup --global` installs the same reusable skill and MCP connection from npm without requiring source-repository access. Once installed, ask your agent:
 
 ```text
 Start Foundry for this project.

package/dist/adapter.js

@@ -896,6 +896,25 @@ var FOUNDRY_UI_FOUNDATION_CSS = `
   }
 `;
 
+// src/diagnostics.ts
+function createSafeDiagnostics(input) {
+  return {
+    product: "Foundry Design Control",
+    protocolVersion: input.protocolVersion ?? "1.1.0",
+    interfaceTheme: input.interfaceTheme,
+    connection: {
+      runtime: input.runtimeConnected ? "connected" : "disconnected",
+      agent: input.agentConnected ? "connected" : "disconnected",
+      ...input.agentConnected && input.agentName ? { agentName: input.agentName } : {}
+    },
+    workspace: {
+      selectedElementCount: Math.max(0, input.selectedCount),
+      recordedChangeCount: Math.max(0, input.recordedChangeCount),
+      latestApplyState: input.latestApplyState ?? "none"
+    }
+  };
+}
+
 // src/workspace.ts
 function resolveInterfaceTheme(preference, systemPrefersDark) {
   return preference === "system" ? systemPrefersDark ? "dark" : "light" : preference;
@@ -1197,6 +1216,8 @@ var PANEL_CSS = `
   .review-head strong { font-size:12px; }.review-summary { padding:12px 16px 12px;border-bottom:1px solid var(--fdc-line);background:#fcfcfc; }.review-summary strong { display:block;font-size:12px;font-weight:550;letter-spacing:-.01em; }.review-summary span { display:block;margin-top:4px;color:var(--fdc-muted);font-size:12px;line-height:1.45; }.review-summary.attention strong { color:#8b4d3d; }.review-toolbar button { height:28px;padding:0 8px;font-size:12px; }
   .onboarding-card { bottom:84px;width:340px;padding:16px;border-radius:12px;box-shadow:0 16px 40px rgb(0 0 0 / 15%); }.onboarding-card-head { gap:8px; }.onboarding-card-head span { width:28px;height:28px;display:grid;place-items:center;color:#a75031;background:#fbf1ed;border-radius:8px; }.onboarding-card-head svg { width:16px;height:16px;color:inherit; }.onboarding-card-head strong { font-size:12px;letter-spacing:-.015em; }.onboarding-card>p { margin:8px 0 16px;font-size:12px;line-height:1.55; }.onboarding-steps { display:grid;grid-template-columns:1fr;gap:1px;border:1px solid var(--fdc-line);border-radius:8px;overflow:hidden;background:var(--fdc-line); }.onboarding-step { display:grid;grid-template-columns:24px 1fr;gap:8px;padding:8px 12px;background:white;text-align:left; }.onboarding-step b { color:#8a8a8a;font-size:8px;font-weight:500;letter-spacing:.04em; }.onboarding-step strong { display:block;font-size:12px;font-weight:550; }.onboarding-step small { display:block;margin-top:4px;color:var(--fdc-muted);font-size:8px;line-height:1.35; }.onboarding-actions { gap:8px;margin-top:12px; }.onboarding-actions button { height:32px;padding:0 12px;border-radius:8px;font-size:12px; }
   .onboarding-card,.onboarding-step { color:var(--fdc-ink);background:var(--fdc-surface); }.onboarding-card-head span { color:#e7a68c;background:#36231d; }.onboarding-actions button { color:var(--fdc-ink);background:var(--fdc-elevated);border-color:var(--fdc-line); }.onboarding-actions .onboarding-start { color:#141416;background:#f0f1f3;border-color:#f0f1f3; }
+  .status-popover { width:256px; }.status-popover-actions { display:grid;grid-template-columns:1fr 1fr;gap:4px;margin-top:8px; }.status-popover .status-popover-actions button { height:32px;margin:0; }.status-popover .status-popover-actions [data-status-retry],.status-popover .status-popover-actions [data-status-repair] { grid-column:1/-1; }
+  .onboarding-card { width:360px; }.onboarding-card-head>strong { flex:1; }.onboarding-card-head .onboarding-close { width:28px;height:28px;display:grid;place-items:center;padding:0;border:0;border-radius:4px;background:transparent;color:var(--fdc-muted);cursor:pointer; }.onboarding-card-head .onboarding-close:hover { color:var(--fdc-ink);background:var(--fdc-subtle); }.onboarding-card-head .onboarding-close svg { width:12px;height:12px; }.onboarding-steps { gap:4px;border:0;overflow:visible;background:transparent; }.onboarding-step { min-height:40px;grid-template-columns:24px minmax(0,1fr);align-items:center;gap:8px;padding:8px;border:1px solid var(--fdc-line);border-radius:8px; }.onboarding-step b { width:20px;height:20px;display:grid;place-items:center;border:1px solid var(--fdc-line);border-radius:50%;color:var(--fdc-muted);font:500 8px/1 var(--fdc-font);letter-spacing:0; }.onboarding-step b svg { width:12px;height:12px; }.onboarding-step.complete>b { color:#141416;background:#8ae0c2;border-color:#8ae0c2; }.onboarding-step.current { border-color:var(--fdc-signal);box-shadow:0 0 0 4px rgb(59 130 246 / 10%); }
   .review-summary { color:var(--fdc-ink);background:var(--fdc-paper); }.empty-state-icon { color:#9ec5ff;background:var(--fdc-signal-soft); }
   .component-card,.health-card { color:var(--fdc-ink);background:var(--fdc-surface);border-color:var(--fdc-line); }.component-card.selected { color:var(--fdc-ink);background:var(--fdc-component-soft);border-color:#5c4b9e;box-shadow:0 0 0 4px rgb(155 135 245 / 10%); }.component-variants span,.component-actions button,.component-variants button { color:#c1b5f5;background:var(--fdc-component-soft);border-color:#4a406f; }.health-score::before { background:var(--fdc-surface); }.health-filters button { color:var(--fdc-muted); }.health-filters button:hover,.health-filters button.active { color:var(--fdc-ink);background:var(--fdc-elevated);border-color:var(--fdc-line); }.health-card p,.health-evidence { color:var(--fdc-muted); }.mapping-chooser { color:#f0c9a8;background:#35291d;border-color:#665039; }.mapping-chooser>strong,.mapping-option,.mapping-option small { color:#e7c29f; }.review-card.locating { background:var(--fdc-signal-soft); }.baseline-badge { color:#83d8bb;background:#18352c; }
   /* Workspace ownership */
@@ -1891,7 +1912,7 @@ function installFoundryInspector(options = {}) {
   statusPill.setAttribute("aria-label", "Foundry session status");
   statusPill.insertAdjacentHTML(
     "afterend",
-    '<div class="status-popover" hidden><strong data-status-title>Session connected</strong><span data-status-detail>Changes are stored locally.</span><code data-status-project></code><code data-status-revision></code><button data-status-retry>Check connection</button></div>'
+    '<div class="status-popover" hidden><strong data-status-title>Session connected</strong><span data-status-detail>Changes are stored locally.</span><code data-status-project></code><code data-status-revision></code><div class="status-popover-actions"><button data-status-checklist>Getting started</button><button data-status-diagnostics>Copy diagnostics</button><button data-status-retry>Check connection</button><button data-status-repair>Copy repair command</button></div></div>'
   );
   shadow.querySelector(".panel").insertAdjacentHTML(
     "beforeend",
@@ -1901,7 +1922,7 @@ function installFoundryInspector(options = {}) {
   onboarding.className = "onboarding-card";
   onboarding.hidden = true;
   onboarding.setAttribute("aria-label", "Getting started with Foundry");
-  onboarding.innerHTML = '<div class="onboarding-card-head"><span><i data-foundry-icon="sparkles"></i></span><strong>Start with the interface</strong></div><p>Foundry stays in Select mode while you work. Click anything, refine measured values, then apply one reviewed batch.</p><div class="onboarding-steps"><div class="onboarding-step"><b>01</b><span><strong>Select</strong><small>Click the page or choose a layer.</small></span></div><div class="onboarding-step"><b>02</b><span><strong>Refine</strong><small>Adjust real layout, type, color, and motion.</small></span></div><div class="onboarding-step"><b>03</b><span><strong>Apply</strong><small>Review once, update source, and verify.</small></span></div></div><div class="onboarding-actions"><button class="onboarding-shortcuts">View shortcuts</button><button class="onboarding-start">Select an element</button></div>';
+  onboarding.innerHTML = '<div class="onboarding-card-head"><span><i data-foundry-icon="sparkles"></i></span><strong>Getting started</strong><button class="onboarding-close" aria-label="Close getting started"><i data-foundry-icon="x"></i></button></div><p>Complete one real design loop. Progress stays in this browser and contains no project content.</p><div class="onboarding-steps"></div><div class="onboarding-actions"><button class="onboarding-shortcuts">View shortcuts</button><button class="onboarding-start">Continue</button></div>';
   shadow.append(onboarding);
   const compareBar = document.createElement("div");
   compareBar.className = "compare-bar";
@@ -2152,10 +2173,84 @@ function installFoundryInspector(options = {}) {
   const capturedBaselineRuns = /* @__PURE__ */ new Set();
   let projectRoot = location.origin;
   let projectRevision = "";
+  let runtimeConnected = false;
+  let recordedChangeCount = 0;
+  let latestApplyState = "none";
+  const onboardingCompleted = /* @__PURE__ */ new Set();
   let designMemory = emptyDesignMemory();
   let matrixMode = false;
   let lastUtilityTrigger = null;
   const utilityRects = /* @__PURE__ */ new Map();
+  const onboardingSteps = [
+    {
+      id: "setup",
+      title: "Setup complete",
+      detail: "The project adapter and local session are ready."
+    },
+    {
+      id: "agent",
+      title: "Agent connection",
+      detail: "Keep it listening while you design. Offline batches wait safely."
+    },
+    {
+      id: "selection",
+      title: "First element selected",
+      detail: "Click the canvas or choose an item in Layers."
+    },
+    {
+      id: "change",
+      title: "First change recorded",
+      detail: "Adjust a measured value in the Inspector."
+    },
+    {
+      id: "apply",
+      title: "First batch applied and verified",
+      detail: "Review once, update source, then measure the rebuild."
+    }
+  ];
+  function onboardingStorageKey(suffix) {
+    return `__foundry_getting_started:${suffix}:${projectRoot}`;
+  }
+  function loadOnboardingProgress() {
+    onboardingCompleted.clear();
+    try {
+      const stored = JSON.parse(localStorage.getItem(onboardingStorageKey("completed")) ?? "[]");
+      for (const id of stored) {
+        if (onboardingSteps.some((step) => step.id === id)) onboardingCompleted.add(id);
+      }
+    } catch {
+      localStorage.removeItem(onboardingStorageKey("completed"));
+    }
+  }
+  function completeOnboardingStep(id) {
+    if (onboardingCompleted.has(id)) return;
+    onboardingCompleted.add(id);
+    try {
+      localStorage.setItem(
+        onboardingStorageKey("completed"),
+        JSON.stringify([...onboardingCompleted])
+      );
+    } catch {
+    }
+    renderOnboardingChecklist();
+  }
+  function renderOnboardingChecklist(forceOpen = false) {
+    const nextStep = onboardingSteps.find((step) => !onboardingCompleted.has(step.id));
+    const complete = !nextStep;
+    const stepsRoot = onboarding.querySelector(".onboarding-steps");
+    stepsRoot.innerHTML = onboardingSteps.map((step, index) => {
+      const done = onboardingCompleted.has(step.id);
+      const current = step.id === nextStep?.id;
+      return `<div class="onboarding-step ${done ? "complete" : ""} ${current ? "current" : ""}"><b>${done ? '<i data-foundry-icon="check"></i>' : String(index + 1).padStart(2, "0")}</b><span><strong>${step.title}</strong><small>${step.detail}</small></span></div>`;
+    }).join("");
+    renderIcons(stepsRoot);
+    const continueButton = onboarding.querySelector(".onboarding-start");
+    const action = nextStep?.id ?? "done";
+    continueButton.dataset.action = action;
+    continueButton.textContent = action === "agent" ? "Copy restart prompt" : action === "selection" ? "Select an element" : action === "change" ? "Adjust a value" : action === "apply" ? "Review changes" : "Done";
+    const dismissed = localStorage.getItem(onboardingStorageKey("dismissed")) === "1";
+    onboarding.hidden = complete || !forceOpen && dismissed;
+  }
   function utilityStorageKey(utility) {
     return `__foundry_utility_rect:${utility}:${projectRoot}`;
   }
@@ -2389,16 +2484,23 @@ function installFoundryInspector(options = {}) {
   async function hydrateSession() {
     if (!sessionId || !token) return;
     try {
-      const response = await fetch(`${runtimeUrl}/v1/sessions/${sessionId}`, {
-        headers: { "x-foundry-token": token }
-      });
+      const [response, presence] = await Promise.all([
+        fetch(`${runtimeUrl}/v1/sessions/${sessionId}`, {
+          headers: { "x-foundry-token": token }
+        }),
+        sessionRequest("/agent-presence").catch(() => ({ connected: false, presence: null }))
+      ]);
       if (!response.ok) throw new Error("The local session could not be read.");
-      const { changeSet, designGraph: graph } = await response.json();
+      const payload = await response.json();
+      const { changeSet, designGraph: graph } = payload;
+      runtimeConnected = true;
+      activeAgentPresence = presence;
       statusPopover.querySelector("[data-status-project]").textContent = changeSet.context.projectRoot;
       statusPopover.querySelector("[data-status-revision]").textContent = `Revision ${changeSet.context.revision ?? "working tree"}`;
       const nextProjectRoot = changeSet.context.projectRoot || location.origin;
       if (projectRoot !== nextProjectRoot || !hydratedOnce) {
         projectRoot = nextProjectRoot;
+        loadOnboardingProgress();
         designMemory = readDesignMemory(localStorage, projectRoot);
         utilityRects.clear();
         positionWorkspaceSurfaces();
@@ -2411,15 +2513,23 @@ function installFoundryInspector(options = {}) {
       const activeChanges = changeSet.changes.filter(
         (change) => change.status !== "rejected" && String(change.before) !== String(change.after)
       );
+      recordedChangeCount = activeChanges.length;
+      latestApplyState = payload.applyRuns?.at(-1)?.state ?? "none";
       updateChangeCount(activeChanges.length, activeChanges.at(-1));
+      completeOnboardingStep("setup");
+      if (activeAgentPresence.connected) completeOnboardingStep("agent");
+      if (selectedElements.length) completeOnboardingStep("selection");
+      if (activeChanges.length) completeOnboardingStep("change");
+      if (latestApplyState === "passed") completeOnboardingStep("apply");
+      renderOnboardingChecklist();
       setSessionStatus("live");
       if (!libraryPanel.hidden) renderDesignMemory();
       if (changeSet.changes.length === 0 && !hydratedOnce) {
         showToast("Click any element. Shift-click builds a selection.");
-        if (!localStorage.getItem("__foundry_onboarded")) onboarding.hidden = false;
       }
       hydratedOnce = true;
     } catch (error) {
+      runtimeConnected = false;
       setSessionStatus(
         "error",
         error instanceof Error ? error.message : "The local session could not be read."
@@ -3403,12 +3513,12 @@ function installFoundryInspector(options = {}) {
       const count = group.querySelector(".included-count");
       if (count) count.textContent = `${included} included`;
     });
-    applyButton.textContent = !activeAgentPresence.connected ? "Connect agent to apply" : selectedCount ? `Apply ${selectedCount} with agent` : "Apply with agent";
-    applyButton.disabled = selectedCount === 0 || !activeAgentPresence.connected;
+    applyButton.textContent = selectedCount ? activeAgentPresence.connected ? `Apply ${selectedCount} with agent` : `Queue ${selectedCount} for agent` : "Apply with agent";
+    applyButton.disabled = selectedCount === 0;
   }
   function agentConnectionMarkup() {
     const agentName = activeAgentPresence.presence?.agent?.name;
-    return `<div class="review-agent ${activeAgentPresence.connected ? "connected" : "disconnected"}" aria-live="polite"><i></i><div><strong>${activeAgentPresence.connected ? `${escapeHtml(agentName ?? "Coding agent")} is ready` : "Connect your coding agent"}</strong><span>${activeAgentPresence.connected ? "Apply requests will be claimed automatically while this agent keeps listening." : "In the same project, ask your agent to start Foundry and keep listening for Apply requests."}</span></div>${activeAgentPresence.connected ? "" : "<button data-copy-agent-listener>Copy instruction</button>"}</div>`;
+    return `<div class="review-agent ${activeAgentPresence.connected ? "connected" : "disconnected"}" aria-live="polite"><i></i><div><strong>${activeAgentPresence.connected ? `${escapeHtml(agentName ?? "Coding agent")} is ready` : "Agent currently offline"}</strong><span>${activeAgentPresence.connected ? "Apply requests will be claimed automatically while this agent keeps listening." : "You can queue this batch now. Codex, Cursor, or Claude Code will claim it when the Foundry listener reconnects."}</span></div>${activeAgentPresence.connected ? "" : "<button data-copy-agent-listener>Copy reconnect instruction</button>"}</div>`;
   }
   function updateAgentConnection() {
     const current = reviewBody.querySelector(".review-agent");
@@ -3639,6 +3749,8 @@ function installFoundryInspector(options = {}) {
     const passed = run.state === "passed";
     const active = ["queued", "claimed", "applying", "rebuilding", "verifying"].includes(run.state);
     const latestMessage = run.state === "queued" ? "The reviewed changes are queued. Keep your coding agent active, or ask it to apply your reviewed Foundry changes." : run.messages.at(-1)?.message ?? run.error ?? "Apply run created.";
+    latestApplyState = run.state;
+    if (run.state === "passed") completeOnboardingStep("apply");
     captureVerifiedRun(run);
     reviewCount.textContent = `Attempt ${run.attempts}`;
     reviewBody.innerHTML = `<div class="run-summary"><div class="run-state"><i class="${passed ? "passed" : attention ? "attention" : active ? "active" : ""}"></i><strong>${escapeHtml(runStateLabels[run.state] ?? run.state)}</strong></div><p>${escapeHtml(latestMessage)}</p></div><div class="run-steps">${run.messages.map(
@@ -3709,6 +3821,7 @@ function installFoundryInspector(options = {}) {
         sessionRequest("/agent-presence")
       ]);
       activeAgentPresence = presence;
+      if (presence.connected) completeOnboardingStep("agent");
       const latestRun = payload.applyRuns?.at(-1);
       const runNeedsRefresh = latestRun && [
         "queued",
@@ -3748,6 +3861,7 @@ function installFoundryInspector(options = {}) {
       sessionRequest("/agent-presence")
     ]);
     activeAgentPresence = presence;
+    if (presence.connected) completeOnboardingStep("agent");
     renderReviewPayload(payload);
     requestAnimationFrame(() => {
       reviewBody.scrollTop = reviewScrollTop;
@@ -3790,11 +3904,6 @@ function installFoundryInspector(options = {}) {
     applyButton.disabled = true;
     try {
       activeAgentPresence = await sessionRequest("/agent-presence");
-      if (!activeAgentPresence.connected) {
-        updateAgentConnection();
-        showToast("No coding agent is listening yet");
-        return;
-      }
       const payload = await sessionRequest("/apply-runs", {
         method: "POST",
         body: JSON.stringify({
@@ -3804,6 +3913,8 @@ function installFoundryInspector(options = {}) {
       });
       clearReviewDraft();
       renderReviewPayload(payload);
+      if (!activeAgentPresence.connected)
+        showToast("Queued. Your coding agent will claim this batch when it reconnects.");
     } catch (error) {
       showToast(error instanceof Error ? error.message : "Could not start apply run");
       updateReviewSelection();
@@ -4049,6 +4160,8 @@ function installFoundryInspector(options = {}) {
       const activeChanges = responsePayload.changeSet.changes.filter(
         (change) => change.status !== "rejected" && String(change.before) !== String(change.after)
       );
+      recordedChangeCount = activeChanges.length;
+      completeOnboardingStep("change");
       lastRecordedSummary = `${target.label} \xB7 ${control.label} ${before}${control.unit ?? ""} \u2192 ${after}${control.unit ?? ""}`;
       updateChangeCount(activeChanges.length, activeChanges.at(-1));
       showToast(ambiguous ? "Choose the source intent in review" : "Change recorded");
@@ -5485,6 +5598,7 @@ function installFoundryInspector(options = {}) {
       selectedElements = [element];
       selected = element;
     }
+    completeOnboardingStep("selection");
     if (!sectionPreferenceTouched) {
       const categoryKeys = [
         "position",
@@ -6085,6 +6199,29 @@ function installFoundryInspector(options = {}) {
     }
   });
   statusPopover.querySelector("[data-status-retry]").addEventListener("click", () => void hydrateSession());
+  statusPopover.querySelector("[data-status-checklist]").addEventListener("click", () => {
+    localStorage.removeItem(onboardingStorageKey("dismissed"));
+    renderOnboardingChecklist(true);
+    statusPopover.hidden = true;
+    sessionStatus.setAttribute("aria-expanded", "false");
+  });
+  statusPopover.querySelector("[data-status-diagnostics]").addEventListener("click", () => {
+    const diagnostics = createSafeDiagnostics({
+      interfaceTheme: resolvedInterfaceTheme(),
+      runtimeConnected,
+      agentConnected: activeAgentPresence.connected,
+      agentName: activeAgentPresence.presence?.agent?.name,
+      selectedCount: selectedElements.length,
+      recordedChangeCount,
+      latestApplyState
+    });
+    void navigator.clipboard.writeText(JSON.stringify(diagnostics, null, 2));
+    showToast("Privacy-safe diagnostics copied");
+  });
+  statusPopover.querySelector("[data-status-repair]").addEventListener("click", () => {
+    void navigator.clipboard.writeText("npx foundry-design@beta doctor --repair");
+    showToast("Repair command copied");
+  });
   interfaceThemeTrigger.addEventListener("click", () => {
     if (interfaceThemeMenu.hidden) openInterfaceThemeMenu();
     else closeInterfaceThemeMenu();
@@ -6097,15 +6234,36 @@ function installFoundryInspector(options = {}) {
   );
   changeDock.querySelector(".dock-undo")?.addEventListener("click", () => void replayHistory(-1));
   changeDock.querySelector(".dock-review")?.addEventListener("click", () => void openReview());
+  onboarding.querySelector(".onboarding-close")?.addEventListener("click", () => {
+    localStorage.setItem(onboardingStorageKey("dismissed"), "1");
+    onboarding.hidden = true;
+  });
   onboarding.querySelector(".onboarding-start")?.addEventListener("click", () => {
-    localStorage.setItem("__foundry_onboarded", "1");
+    const action = onboarding.querySelector(".onboarding-start")?.dataset.action;
+    if (action === "agent") {
+      void navigator.clipboard.writeText(
+        "Start Foundry for this project and keep listening for Apply with agent requests."
+      );
+      showToast("Listener prompt copied");
+      return;
+    }
+    if (action === "apply" && recordedChangeCount > 0) {
+      onboarding.hidden = true;
+      void openReview();
+      return;
+    }
+    if (action === "done") {
+      onboarding.hidden = true;
+      return;
+    }
     onboarding.hidden = true;
     inspecting = true;
     updateInspectionMode();
-    showToast("Select mode stays on \xB7 click any element to begin");
+    showToast(
+      action === "change" ? "Adjust any Inspector value to record a change" : "Select mode stays on \xB7 click any element to begin"
+    );
   });
   onboarding.querySelector(".onboarding-shortcuts")?.addEventListener("click", () => {
-    localStorage.setItem("__foundry_onboarded", "1");
     onboarding.hidden = true;
     openCommands();
   });

package/dist/diagnostics.d.ts

@@ -0,0 +1,27 @@
+export interface SafeDiagnosticsInput {
+    interfaceTheme: 'light' | 'dark';
+    runtimeConnected: boolean;
+    agentConnected: boolean;
+    agentName?: string;
+    selectedCount: number;
+    recordedChangeCount: number;
+    latestApplyState?: string;
+    protocolVersion?: string;
+}
+/** Build useful support state without exposing project content or session credentials. */
+export declare function createSafeDiagnostics(input: SafeDiagnosticsInput): {
+    product: string;
+    protocolVersion: string;
+    interfaceTheme: "light" | "dark";
+    connection: {
+        agentName?: string | undefined;
+        runtime: string;
+        agent: string;
+    };
+    workspace: {
+        selectedElementCount: number;
+        recordedChangeCount: number;
+        latestApplyState: string;
+    };
+};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB;;;;;;;;;;;;;;EAgBhE"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6DA,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,IAAI,IAAI,CAAC;IAChB,cAAc,IAAI,IAAI,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,OAAO,IAAI,IAAI,CAAC;CACjB;AAq/BD,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,uBAA4B,GACpC,0BAA0B,CA4yK5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8DA,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,IAAI,IAAI,CAAC;IAChB,cAAc,IAAI,IAAI,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,OAAO,IAAI,IAAI,CAAC;CACjB;AAu/BD,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,uBAA4B,GACpC,0BAA0B,CAm9K5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foundry-design-web-adapter",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.6",
   "description": "Development-only browser inspector for Foundry",
   "type": "module",
   "main": "dist/adapter.js",