foundry-design-web-adapter 0.2.0-beta.3 → 0.2.0-beta.5

package/README.md

@@ -4,27 +4,51 @@ Foundry is a local-first precision design workbench for Codex, Cursor, and Claud
 
 ## Beta installation
 
-Foundry is distributed through npm, so testers do not need access to the private GitHub repository. From the project you want to inspect, run:
+Foundry is distributed through npm, so testers do not need GitHub access.
+
+### Recommended: let your coding agent install it
+
+Open the project in Codex, Cursor, or Claude Code and paste:
+
+```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.
+```
+
+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.
+
+Restart the coding agent once, reopen the same project folder, and paste:
+
+```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.
+
+### Manual installation
+
+From the project you want to inspect, run:
 
 ```bash
 npx foundry-design@beta setup
 ```
 
-Setup detects the platform, framework, package manager, development command, and installed coding agents. It previews every file it will manage, adds development-only instrumentation for supported web frameworks, installs the Foundry skill for Codex, Cursor, or Claude Code, configures the selected MCP clients, and records a reversible install manifest.
-
-Restart the coding agent after setup, then ask:
+Then restart the coding agent, reopen the same project folder, and ask:
 
 ```text
-Start Foundry for this project.
+Start Foundry for this project and keep listening for Apply with agent requests.
 ```
 
-Then start a session with:
+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.
+
+Update an existing installation with:
 
 ```bash
-npx foundry-design@beta start
+npx foundry-design@beta update
 ```
 
-Foundry reuses an available project server or starts the detected development command, launches the loopback runtime, and opens an authenticated visual preview. Remove only Foundry-managed integration with:
+The updater refreshes checksum-matched Foundry files, agent connections, and skill bundles. It preserves and reports files changed since setup, validates the project, and rolls back the update if Foundry introduces a TypeScript or lint failure. Restart the coding agent after updating.
+
+Remove only Foundry-managed integration with:
 
 ```bash
 npx foundry-design@beta uninstall

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] { 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 */
@@ -1264,6 +1285,14 @@ var PANEL_CSS = `
   .review-overview .review-toolbar { position:static;z-index:auto;flex:none;padding:0;border:0;background:transparent;backdrop-filter:none; }
   .review-overview .review-toolbar button { height:28px;padding:0 8px;border-color:transparent;background:transparent;color:var(--fdc-muted);font-size:8px; }
   .review-overview .review-toolbar button:hover { color:var(--fdc-ink);background:var(--fdc-elevated);border-color:var(--fdc-line); }
+  .review-agent { display:grid;grid-template-columns:8px minmax(0,1fr) auto;align-items:center;gap:12px;margin:12px 16px 0;padding:12px;border:1px solid var(--fdc-line);border-radius:8px;background:var(--fdc-paper); }
+  .review-agent>i { width:8px;height:8px;border-radius:50%;background:#d16d51; }
+  .review-agent.connected>i { background:#2ca67f;box-shadow:0 0 0 4px rgb(44 166 127 / 12%); }
+  .review-agent strong,.review-agent span { display:block; }
+  .review-agent strong { font-size:12px;font-weight:600; }
+  .review-agent span { margin-top:4px;color:var(--fdc-muted);font-size:12px;line-height:1.45; }
+  .review-agent button { height:32px;padding:0 12px;border:1px solid var(--fdc-line);border-radius:8px;background:var(--fdc-elevated);color:var(--fdc-ink);font-size:12px;cursor:pointer; }
+  .review-agent button:hover { border-color:var(--fdc-muted); }
   .change-tray .review-group { border-right:0;border-bottom:1px solid var(--fdc-line); }
   .change-tray .review-group-title { position:sticky;top:52px;z-index:2;min-height:40px;padding:0 12px;background:rgb(28 28 31 / 98%); }
   .review-group-title .included-count { font-size:8px; }
@@ -1883,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></div></div>'
   );
   shadow.querySelector(".panel").insertAdjacentHTML(
     "beforeend",
@@ -1893,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";
@@ -2081,6 +2110,7 @@ function installFoundryInspector(options = {}) {
   let selectedControls = [];
   let resizeObserver;
   let activeReviewPayload = null;
+  let activeAgentPresence = { connected: false, presence: null };
   const reviewDraftKey = `__foundry_review_draft:${sessionId || "local"}`;
   let reviewDraft = (() => {
     try {
@@ -2143,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 restarted and connected",
+      detail: "Keep the coding agent listening while you design."
+    },
+    {
+      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}`;
   }
@@ -2380,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();
@@ -2402,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."
@@ -3394,8 +3513,29 @@ function installFoundryInspector(options = {}) {
       const count = group.querySelector(".included-count");
       if (count) count.textContent = `${included} included`;
     });
-    applyButton.textContent = selectedCount ? `Apply ${selectedCount} with agent` : "Apply with agent";
-    applyButton.disabled = selectedCount === 0;
+    applyButton.textContent = !activeAgentPresence.connected ? "Connect agent to apply" : selectedCount ? `Apply ${selectedCount} with agent` : "Apply with agent";
+    applyButton.disabled = selectedCount === 0 || !activeAgentPresence.connected;
+  }
+  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>`;
+  }
+  function updateAgentConnection() {
+    const current = reviewBody.querySelector(".review-agent");
+    if (!current) {
+      updateReviewSelection();
+      return;
+    }
+    const replacement = document.createElement("div");
+    replacement.innerHTML = agentConnectionMarkup();
+    current.replaceWith(replacement.firstElementChild);
+    reviewBody.querySelector("[data-copy-agent-listener]")?.addEventListener("click", () => {
+      void navigator.clipboard.writeText(
+        "Start Foundry for this project and keep listening for Apply with agent requests."
+      );
+      showToast("Agent instruction copied");
+    });
+    updateReviewSelection();
   }
   function renderReviewList(changes) {
     const groups = /* @__PURE__ */ new Map();
@@ -3409,7 +3549,7 @@ function installFoundryInspector(options = {}) {
     const unresolvedCount = changes.filter(
       (change) => change.confidence === "unresolved" || change.mappingCandidates?.length > 1 && !change.selectedMappingId
     ).length;
-    reviewBody.innerHTML = changes.length || rejectedCount ? `<div class="review-overview"><div class="review-summary" data-unresolved="${unresolvedCount}" aria-live="polite"><strong>Preparing review\u2026</strong><span>Only included, exactly mapped changes will be sent to your agent.</span></div><div class="review-toolbar"><button data-review-compare>Compare</button><button data-review-approve-exact>Include all</button><button data-review-toggle-rejected>${reviewShowRejected ? "Hide removed" : rejectedCount ? `${rejectedCount} removed` : "Removed"}</button></div></div>${[
+    reviewBody.innerHTML = changes.length || rejectedCount ? `<div class="review-overview"><div class="review-summary" data-unresolved="${unresolvedCount}" aria-live="polite"><strong>Preparing review\u2026</strong><span>Only included, exactly mapped changes will be sent to your agent.</span></div><div class="review-toolbar"><button data-review-compare>Compare</button><button data-review-approve-exact>Include all</button><button data-review-toggle-rejected>${reviewShowRejected ? "Hide removed" : rejectedCount ? `${rejectedCount} removed` : "Removed"}</button></div></div>${agentConnectionMarkup()}${[
       ...groups.values()
     ].map((group) => {
       const target = group[0].target;
@@ -3443,6 +3583,12 @@ function installFoundryInspector(options = {}) {
     reviewCancel.dataset.action = "back";
     reviewCancel.textContent = "Back";
     renderIcons(reviewBody);
+    reviewBody.querySelector("[data-copy-agent-listener]")?.addEventListener("click", () => {
+      void navigator.clipboard.writeText(
+        "Start Foundry for this project and keep listening for Apply with agent requests."
+      );
+      showToast("Agent instruction copied");
+    });
     reviewBody.querySelectorAll("[data-review-change]").forEach(
       (field) => field.addEventListener("change", () => {
         reviewDraft.selections[field.dataset.reviewChange] = field.checked;
@@ -3603,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(
@@ -3668,7 +3816,12 @@ function installFoundryInspector(options = {}) {
   async function refreshReview() {
     if (!workspaceState.reviewOpen || !sessionId || !token) return;
     try {
-      const payload = await sessionRequest();
+      const [payload, presence] = await Promise.all([
+        sessionRequest(),
+        sessionRequest("/agent-presence")
+      ]);
+      activeAgentPresence = presence;
+      if (presence.connected) completeOnboardingStep("agent");
       const latestRun = payload.applyRuns?.at(-1);
       const runNeedsRefresh = latestRun && [
         "queued",
@@ -3681,6 +3834,7 @@ function installFoundryInspector(options = {}) {
       ].includes(latestRun.state);
       if (applyButton.dataset.action === "apply" && !runNeedsRefresh) {
         activeReviewPayload = payload;
+        updateAgentConnection();
         return;
       }
       renderReviewPayload(payload);
@@ -3702,7 +3856,13 @@ function installFoundryInspector(options = {}) {
     workspaceState = updateWorkspace(workspaceState, { type: "set-review", open: true });
     reviewTakeover.hidden = false;
     outline.hidden = true;
-    renderReviewPayload(await sessionRequest());
+    const [payload, presence] = await Promise.all([
+      sessionRequest(),
+      sessionRequest("/agent-presence")
+    ]);
+    activeAgentPresence = presence;
+    if (presence.connected) completeOnboardingStep("agent");
+    renderReviewPayload(payload);
     requestAnimationFrame(() => {
       reviewBody.scrollTop = reviewScrollTop;
       shadow.querySelector(".review-back")?.focus();
@@ -3743,6 +3903,12 @@ 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({
@@ -3997,6 +4163,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");
@@ -5433,6 +5601,7 @@ function installFoundryInspector(options = {}) {
       selectedElements = [element];
       selected = element;
     }
+    completeOnboardingStep("selection");
     if (!sectionPreferenceTouched) {
       const categoryKeys = [
         "position",
@@ -6033,6 +6202,25 @@ 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");
+  });
   interfaceThemeTrigger.addEventListener("click", () => {
     if (interfaceThemeMenu.hidden) openInterfaceThemeMenu();
     else closeInterfaceThemeMenu();
@@ -6045,15 +6233,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("Restart 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;AA6+BD,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,uBAA4B,GACpC,0BAA0B,CAqvK5B"}
+{"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,CAg9K5B"}

package/package.json

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