@foldspace_npm/harness 0.1.26 → 0.1.28

package/src/attach-preflight.mjs

@@ -44,7 +44,7 @@ export function guardAttachMode({
     // navigates within the app the SDK on the page is OUR bootstrap, carrying
     // the configured agent. That is the expected state, not a foreign SDK:
     // refusing it made the agent vanish on every in-app navigation
-    // (Buildium, 2026-09-22). Only a page whose SDK belongs to someone else
+    // (a customer build, 2026-09-22). Only a page whose SDK belongs to someone else
     // is a real mismatch.
     if (characterization.status === "same-agent") {
       return { ok: true, mode, reattached: true };
@@ -78,8 +78,7 @@ export function guardAttachMode({
         code: ERROR_CODES.REGISTRATION_MISMATCH,
         message:
           "Swap mode requires exactly the configured agent on the page.",
-        suggestion:
-          "Use --replace when the page embeds a different agent, or close duplicate agent instances.",
+        suggestion: "Use --replace.",
       };
     }
     if (pageProductIds.length === 0) {
@@ -89,8 +88,7 @@ export function guardAttachMode({
         code: ERROR_CODES.REGISTRATION_MISMATCH,
         message:
           "Swap mode could not verify which product owns the page agent.",
-        suggestion:
-          "Use --replace, or update the page SDK so its tracker key is inspectable.",
+        suggestion: "Use --replace.",
       };
     }
     if (productMismatch) {
@@ -99,7 +97,7 @@ export function guardAttachMode({
         mode,
         code: ERROR_CODES.REGISTRATION_MISMATCH,
         message:
-          "The page agent API name matches, but its product does not match the configured product.",
+          "The page's agent has this project's Agent Key but belongs to another product.",
         suggestion: "Use --replace for a cross-product development session.",
       };
     }
@@ -184,6 +182,7 @@ export function buildReplacePrelude({
   mode = "OVERLAY",
   namespace = "foldspace",
   aliases = [],
+  testMode = false,
 }) {
   const source = `(() => {
   if (window.top !== window.self) return;
@@ -248,6 +247,20 @@ export function buildReplacePrelude({
           configuration: { enableDebugLogs: true },
         });
         window.__FOLDSPACE_AGENT__ = target;
+        // Open the chat panel when the agent is first put on the page. The
+        // SDK closes the panel as the agent becomes ready, which undoes an
+        // open() sent before then, so open() runs once more just after
+        // agent.ready. Nothing else here opens it, so a panel the human
+        // closes stays closed until the page loads again.
+        try { target?.open?.(); } catch {}
+        let reopened = false;
+        try {
+          target?.on?.("agent.ready", () => {
+            if (reopened) return;
+            reopened = true;
+            setTimeout(() => { try { target.open?.(); } catch {} }, 0);
+          });
+        } catch {}
       }
       if (!target) return null;
 
@@ -265,12 +278,22 @@ export function buildReplacePrelude({
       }
       try { if (localActions && rawAddHandlers) rawAddHandlers(localActions); }
       catch {}
-      try { target.setTestMode?.(true); } catch {}
+      // Test mode follows the attach: on only with --test-mode, off otherwise.
+      // Each pass of ensureTarget (at start, on every foldspace.agent() call
+      // that names an agent, and every second) sets that value again, so the
+      // chat panel shows test mode exactly when the corner tag says TEST MODE.
+      try { target.setTestMode?.(${testMode === true}); } catch {}
+      // show() on every pass brings the agent back if something hid it with
+      // hide().
       try { target.show?.(); } catch {}
-      try { target.open?.(); } catch {}
-      // A regular extension can intentionally hide the SDK view while its own
-      // dock is closed. Explicit replace mode owns visibility, so override only
-      // that external display:none rule for the lifetime of this document.
+      // In overlay mode, something on the page can set display:none on the
+      // agent's view - the SDK does it itself while its bottom bar is
+      // showing. Replace mode overrides any display:none on that view on
+      // every pass, for the life of this page. In other modes it leaves the
+      // view alone.
+      // ⚠️ That includes the bottom bar's display:none: with the bar on,
+      // closing the chat panel brings the bar back, and this may put the
+      // agent's view back beside it. Not checked live yet.
       if (MODE === "OVERLAY") {
         try {
           const widget = window.document?.querySelector?.("#eucera-agent-view");

package/src/badge-core.mjs

@@ -11,7 +11,7 @@ export function badgePayload(state, text) {
   const payload = { state: wanted };
   if (text !== undefined) {
     if (wanted !== "working") {
-      throw new Error(`--text only applies to working (got ${wanted}); their turn needs no bar.`);
+      throw new Error(`--text only applies to working (got ${wanted}); ready, label and off draw no pill.`);
     }
     const clean = String(text).replace(/\s+/g, " ").trim();
     if (!clean) throw new Error("--text is empty.");

package/src/cdp-client.mjs

@@ -1,6 +1,6 @@
-// A small CDP page client for the read-only verbs (`observe`, `ask`, `run`).
+// A small CDP page client for `observe`, `ask`, `badge` and `published`.
 //
-// It is a second client on the inject Chrome and is safe to use while
+// It is a second client on the test window and is safe to use while
 // `foldspace attach` is running: attach's claim on the debug port is about
 // request interception (`Fetch.enable`) and navigation, and nothing here
 // enables Fetch. `Runtime.evaluate`, `Network.enable` and
@@ -33,20 +33,19 @@ export function readLaunchState(projectDir = resolveProjectDir()) {
     projectDir,
     port: String(port),
     hosts,
+    targetName: state.target || null,
     target: state.resolvedTarget || {},
     sentinel: state.sentinel,
     profileDir: chromeProfileDir(projectDir),
   };
 }
 
-async function listTargets(port) {
+async function listTargets(port, command) {
   let response;
   try {
     response = await fetch(`http://127.0.0.1:${port}/json/list`);
   } catch {
-    throw new Error(
-      `The inject Chrome is not answering on :${port}. It was closed; run \`npm run inject\` again.`,
-    );
+    throw new Error(ownershipErrorMessage("cdp_not_ready", { port, command }));
   }
   return response.json();
 }
@@ -81,15 +80,15 @@ export function choosePage(pages, hosts = []) {
     throw new Error(
       off
         ? `The test window is on ${off.host}, which this project does not cover (hosts: ${hosts.join(", ")}). ` +
-            `If it is part of the product, add "${off.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then run inject and attach again.`
-        : `The test window has no tab on ${hosts.join(", ")}. Open the product there (or finish signing in), then try again.`,
+            `If it is part of the product, add "${off.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then \`npx foldspace attach --stop\`, \`npm run inject\` and \`npx foldspace attach --daemon\` with the flags it ran with. If it is not, ask the human to go back to the product in the test window.`
+        : `The test window has no tab on ${hosts.join(", ")}. Ask the human to open the product there (or finish signing in), then run the command again.`,
     );
   }
   return real[0];
 }
 
-export async function pickPage(port, hosts = []) {
-  return choosePage(await listTargets(port), hosts);
+export async function pickPage(port, hosts = [], command) {
+  return choosePage(await listTargets(port, command), hosts);
 }
 
 // One check per process: it opens a browser-level session.
@@ -100,16 +99,12 @@ let ownershipVerified = false;
  * same check as `attach`. A stale port, or CDP_PORT pointing elsewhere, would
  * otherwise have these commands reload and click in someone else's browser.
  */
-export async function assertTestWindow(state, verify = assertOwnedCdp) {
+export async function assertTestWindow(state, verify = assertOwnedCdp, command) {
   if (ownershipVerified) return;
   const owned = await verify({ profileDir: state.profileDir, port: state.port, token: state.sentinel });
   if (!owned.ok) {
     throw new Error(
-      ownershipErrorMessage(owned.reason, {
-        port: state.port,
-        profileDir: state.profileDir,
-        root: state.projectDir,
-      }),
+      ownershipErrorMessage(owned.reason, { port: state.port, command }),
     );
   }
   ownershipVerified = true;
@@ -127,10 +122,11 @@ export class CdpPage {
     socket.addEventListener("message", (event) => this.#dispatch(JSON.parse(event.data)));
   }
 
-  static async open({ projectDir } = {}) {
+  // `command` names the refusing command in a closed-window message.
+  static async open({ projectDir, command } = {}) {
     const state = readLaunchState(projectDir);
-    await assertTestWindow(state);
-    const page = await pickPage(state.port, state.hosts);
+    await assertTestWindow(state, assertOwnedCdp, command);
+    const page = await pickPage(state.port, state.hosts, command);
     const socket = new WebSocket(page.webSocketDebuggerUrl);
     await new Promise((resolve, reject) => {
       socket.addEventListener("open", resolve, { once: true });

package/src/cdp-ownership.mjs

@@ -88,26 +88,47 @@ export function verifyCdpOwnership({ profileDir, token, reported } = {}) {
   return { ok: true };
 }
 
-export function ownershipErrorMessage(
-  reason,
-  { port, profileDir, root } = {},
-) {
-  const profile =
-    root && profileDir
-      ? path.relative(root, profileDir) || profileDir
-      : profileDir || ".foldspace-dev/chrome-profile";
-  const hints = {
-    sentinel_mismatch:
-      "Launch sentinel is missing or does not match. Run foldspace inject again.",
-    profile_mismatch: `The browser on :${port} is using a different user-data-dir than ${profile}.`,
-    cdp_inspect_failed: `Could not read the profile path from Chrome on :${port}.`,
-    cdp_not_ready: `Chrome did not expose CDP on :${port}.`,
-  };
-  return (
-    `Chrome on :${port} is not the Foldspace profile.\n` +
-    `        ${hints[reason] || reason}\n` +
-    `        Close the other debugging Chrome, or pass --port <free-port>.`
-  );
+/**
+ * Why the Chrome on `port` cannot be used, and the one next step.
+ *
+ * `command` is the command that is refusing. Only `inject` launches Chrome and
+ * takes `--port`; attach, observe, ask, badge and published use the port inject
+ * recorded, so for them a free-port hint is wrong (observe, ask, badge and
+ * published refuse `--port`), and a closed test window is the usual cause.
+ * `published` runs with attach stopped on purpose, so its closed window ends in
+ * running it again, never in attaching.
+ */
+export function ownershipErrorMessage(reason, { port, command } = {}) {
+  if (command === "inject") {
+    const inject = {
+      profile_mismatch: `Another Chrome holds :${port}. Run \`npm run inject -- --port <a free port>\`.`,
+      cdp_inspect_failed:
+        `Chrome on :${port} did not say which profile it runs, so it cannot be proven to be the test window. ` +
+        `Run \`npm run inject -- --port <a free port>\`.`,
+      cdp_not_ready:
+        `Chrome did not answer on :${port} after launch. Close the test window if it is open (it may be on another port), ` +
+        `then run \`npm run inject\` again.`,
+      sentinel_mismatch:
+        "Another inject started while this one was launching. Run `npm run inject` again.",
+    };
+    return inject[reason] || `${reason} on :${port}.`;
+  }
+  if (reason === "cdp_not_ready") {
+    const then =
+      command === "published"
+        ? "then run the same `npx foldspace published` command again - attach stays stopped."
+        : "then `npx foldspace attach --daemon` with the flags it ran with.";
+    return (
+      `The test window is closed: nothing answers on :${port}. ` +
+      "Run `npm run inject` to reopen it, then `npx foldspace observe wait-login` " +
+      `(it returns within seconds if the site kept the sign-in), ${then}`
+    );
+  }
+  const again = "Run `npm run inject` again; attach, observe, ask, badge and published use the port it records.";
+  if (reason === "cdp_inspect_failed") {
+    return `Chrome on :${port} did not say which profile it runs, so it cannot be proven to be the test window. ${again}`;
+  }
+  return `Chrome on :${port} is not the test window this project opened. ${again}`;
 }
 
 export async function fetchCdpVersion(port) {

package/src/cli-help.mjs

@@ -20,9 +20,11 @@ export function renderGeneralHelp(registry) {
     "",
     "Typical local workflow:",
     "  foldspace init <directory>",
-    "  foldspace build",
-    "  foldspace inject",
-    "  foldspace attach",
+    "  # before the first build, CLAUDE.md step 5: a code project's agent/ replaces the scaffold's",
+    "  npm run build",
+    "  npm run inject   # the human signs in in that window",
+    "  npx foldspace observe wait-login",
+    "  npx foldspace attach --daemon",
   ];
 
   for (const [group, title] of GROUPS) {
@@ -46,10 +48,10 @@ export function renderGeneralHelp(registry) {
     "  foldspace help --json            Print the machine-readable CLI contract",
     "  foldspace help <command> --json  Print one command contract",
     "  foldspace --version              Show package and protocol versions",
-    "  foldspace upgrade --check        Compare the installed pin to npm latest",
+    "  foldspace upgrade --check        Compare the version this project uses to npm latest",
     "",
     "attach loads local actions and observes the normal agent experience.",
-    "observe, ask and run look at and test that experience without the customer's help.",
+    "observe looks at the app, and ask tests the agent through its panel; both work while attach runs.",
     ...(registry.publishWorkflow.length ? ["deploy is a separate remote publication step."] : []),
   );
   return sections.join("\n");

package/src/cli-registry.mjs

@@ -64,17 +64,19 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     effects: ["Creates a new local project; never initializes Git"],
     next: [
-      "Install dependencies",
-      "Run foldspace build",
-      "Run foldspace inject",
-      "Run foldspace attach",
+      "npm install --ignore-scripts",
+      "Before the first build, CLAUDE.md step 5 (\"Every session starts the same way\"): with a code project, its agent/ replaces the scaffold's",
+      "npm run build",
+      "npm run inject - the human signs in in that window",
+      "npx foldspace observe wait-login",
+      "npx foldspace attach --daemon",
     ],
   }),
   Object.freeze({
     name: "upgrade",
     entry: null,
     group: "start",
-    summary: "Check for a newer harness and update the exact pin after asking",
+    summary: "Check for a newer harness and, after asking, update the version this project uses",
     usage:
       "foldspace upgrade [--check | --yes] [--refresh-instructions]",
     risk: "local-write",
@@ -89,7 +91,7 @@ export const CLI_COMMANDS = Object.freeze([
       flag("--check", "Compare versions and print JSON; never install"),
       flag(
         "--yes",
-        "Install the latest exact pin after the user has already agreed",
+        "Install the latest version after the human has agreed",
       ),
       flag(
         "--refresh-instructions",
@@ -102,14 +104,14 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     effects: [
       "Without --yes, writes nothing except an optional update cache",
-      "With --yes, rewrites the exact harness pin and runs npm install --ignore-scripts",
-      "Does not rebuild dist/index.js or deploy",
+      "With --yes, writes the latest version into package.json (exact) and runs npm install --ignore-scripts",
+      "Does not rebuild dist/index.js or publish anything",
       "--refresh-instructions copies CLAUDE.md to CLAUDE.md.bak then writes the stub",
     ],
     next: [
-      "If outdated, ask the user, then run foldspace upgrade --yes",
-      "Run npm run build after a pin bump",
-      "Deploy only if product users should receive the rebuilt runtime",
+      "If outdated, ask the human, then run npx foldspace upgrade --yes",
+      "Run npm run build after an upgrade",
+      "If attach is running: `npx foldspace attach --stop`, then `npx foldspace attach --daemon` with the flags it ran with, to load the rebuild",
     ],
   }),
   Object.freeze({
@@ -130,13 +132,16 @@ export const CLI_COMMANDS = Object.freeze([
       "Runs foldspace lint first; errors skip bundling",
       "Writes dist/index.js when lint has no errors",
     ],
-    next: ["Run foldspace inject", "Run foldspace attach"],
+    next: [
+      "First build: `npm run inject` (the human signs in in that window), `npx foldspace observe wait-login`, then `npx foldspace attach --daemon`",
+      "Rebuild while attach runs: `npx foldspace attach --stop`, then `npx foldspace attach --daemon` with the flags it ran with (`--bootstrap`, `--replace`, `--test-mode`) - a running attach keeps the actions it loaded",
+    ],
   }),
   Object.freeze({
     name: "lint",
     entry: "lint.mjs",
     group: "develop",
-    summary: "Check action handlers for prompt, registry, and copy issues",
+    summary: "Check the code under agent/ for prompt, card, registry, copy and test-mode issues",
     usage: "foldspace lint [--json]",
     risk: "local-write",
     environment: "node",
@@ -148,7 +153,7 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     prerequisites: ["agent/actions/index.ts"],
     effects: [
-      "Reads agent/actions (and agent/views when present); writes nothing",
+      "Reads the code under agent/; writes nothing",
       "Errors fail the process; warnings print and still exit 0",
     ],
     next: ["Fix reported findings", "Run foldspace build"],
@@ -157,7 +162,7 @@ export const CLI_COMMANDS = Object.freeze([
     name: "inject",
     entry: "inject.mjs",
     group: "verify",
-    summary: "Launch an isolated Chrome profile for local verification",
+    summary: "Open the test window: an isolated Chrome profile for local verification",
     usage: "foldspace inject [options]",
     risk: "browser-session",
     environment: "local-chrome",
@@ -168,7 +173,7 @@ export const CLI_COMMANDS = Object.freeze([
       value("--target", "name", "Use a target from foldspace.dev.json"),
       value("--url", "url", "Override the target start URL"),
       value("--product", "id", "Override the local-session product ID"),
-      value("--agent", "api-name", "Override the local-session agent"),
+      value("--agent", "agent-key", "Use another Agent Key (as shown in Agent Studio)"),
       value("--hosts", "a,b", "Override allowed host patterns"),
       value(
         "--key",
@@ -194,7 +199,10 @@ export const CLI_COMMANDS = Object.freeze([
       "Otherwise creates an isolated profile and writes .foldspace-dev/state.json",
       "Does not load the SDK or action artifact",
     ],
-    next: ["Sign in to the target application", "Observe the real workflow, or run foldspace attach"],
+    next: [
+      "The human signs in in that window; run `npx foldspace observe wait-login` - it returns when they are in",
+      "Run `npx foldspace attach --daemon` (L0); until an experience is chosen, observe only `screenshot` and `menu`",
+    ],
   }),
   Object.freeze({
     name: "attach",
@@ -203,7 +211,7 @@ export const CLI_COMMANDS = Object.freeze([
     summary:
       "Load local actions over CDP and observe the normal agent experience",
     usage:
-      "foldspace attach [--bootstrap | --replace] [--daemon | --status | --stop] [--target <name>] [--port <number>] [--agent <api-name>] [--no-test-mode] [--no-badge]",
+      "foldspace attach [--bootstrap | --replace] [--daemon | --status | --stop] [--target <name>] [--port <number>] [--agent <agent-key>] [--test-mode] [--no-badge]",
     risk: "browser-session",
     environment: "local-chrome",
     environmentVariables: [
@@ -249,13 +257,13 @@ export const CLI_COMMANDS = Object.freeze([
         "number",
         "CDP port: CLI, CDP_PORT, or the port inject recorded",
       ),
-      value("--agent", "api-name", "Override the configured agent API name"),
+      value("--agent", "agent-key", "Use another Agent Key (as shown in Agent Studio)"),
       flag(
         "--test-mode",
         "Mark this session's conversations as test traffic, so they stay out of the dashboard; for an agent that already has real users",
       ),
-      flag("--no-test-mode", "Accepted for older instructions; test mode is already off by default"),
-      flag("--no-badge", "Hide the visible Foldspace development badge"),
+      flag("--no-test-mode", "Has no effect: test mode is off unless --test-mode is passed"),
+      flag("--no-badge", "Draw no corner tag and no working pill (for a recording)"),
       flag(
         "--daemon",
         "Start attach in the background and return after inspect_registration",
@@ -280,12 +288,12 @@ export const CLI_COMMANDS = Object.freeze([
       "--daemon returns after inspect_registration and keeps CDP in a child process",
     ],
     next: [
-      "Coding agents should use foldspace attach --daemon so the invoking tool returns",
-      "Exercise the visible agent normally",
+      "Coding agents run `npx foldspace attach --daemon`, so the command returns",
       "Confirm [lifecycle] inspect_registration:registration_ok in the terminal or daemon log",
-      "On mismatch, read foldspace help attach --json diagnostics and the lifecycle details",
+      "On registration_mismatch, read the lines printed under it: what differs, and the next step",
+      "Prove a published action with `npx foldspace ask \"<question>\" --retry 2`",
       "After a named action, read [actions] execute/render lines from the attach log",
-      "Detach with Ctrl-C, or foldspace attach --stop for a daemon",
+      "Keep attach running; `attach --stop` only to load rebuilt actions or changed hosts, or to check published code on dev (manual: \"Done, and what you say at the end\")",
     ],
   }),
   Object.freeze({
@@ -326,9 +334,16 @@ export const CLI_COMMANDS = Object.freeze([
       "GET only. Never submits a form; clicks navigation elements only",
       "Prints names, shapes and counts - never values, tokens or cookies",
       "Works while foldspace attach is running",
-      "Raises the working pill on the window while it runs (not for screenshot), and drops it after",
+      "Raises the working pill on the window while it runs (not for pages, screenshot or wait-login), and drops it after",
+    ],
+    next: [
+      "wait-login: run `npx foldspace attach --daemon`",
+      "screenshot: send the image to the human",
+      "menu: offer experiences from what it shows",
+      "screen, read, auth: record what you established in docs/app-profile.md, then write the handler",
+      "pages: if it returns hostsHint, follow it; otherwise run the subcommand the experience needs",
+      "styles: run it with --write, then record in docs/app-profile.md the page and date it sampled and anything it fell back on; cards import agent/views/brand.ts",
     ],
-    next: ["Record what you established in docs/app-profile.md", "Write the handler"],
   }),
   Object.freeze({
     name: "ask",
@@ -344,19 +359,22 @@ export const CLI_COMMANDS = Object.freeze([
       Object.freeze({ name: "question", required: true, description: "What an end user would type" }),
     ],
     options: [
-      value("--retry", "n", "Ask again when no action fired (a newly published action can take a minute to be picked up)", { default: "0" }),
+      value("--retry", "n", "Ask again when no action fired - without attach, whenever no card came back, even if an action without a card ran (a newly published action can take a minute to be picked up)", { default: "0" }),
       value("--every", "seconds", "Pause between retries", { default: "20" }),
       value("--timeout", "seconds", "Wait this long for a reply", { default: "90" }),
     ],
-    prerequisites: ["foldspace attach is running, so the handlers on the page are this project's build"],
+    prerequisites: [
+      "To test this project's build, `npx foldspace attach --daemon` is running: the handlers on the page are this build, and execute/render are read from its log. After `npx foldspace published`, the page runs the published code instead: execute/render read \"not tracked here (published code)\", and the reply, the card text and the screenshot are the proof",
+    ],
     effects: [
       "Types into the panel the way a person does; touches nothing inside the SDK",
+      "handler.execute / handler.render come from the attach daemon's log; without the daemon they read \"not tracked here (published code)\" and the reply, cards and screenshot still come back",
       "Creates a real conversation: it appears in the customer's Foldspace dashboard (test traffic only under attach --test-mode)",
       "Saves panel and full-page screenshots under .foldspace-dev/ask/",
     ],
     next: [
-      "Read reply, cards and handler.execute / handler.render; look at the screenshot",
-      "Only then: foldspace badge ready, and invite the customer to try it",
+      "Read reply, cards and handler.execute / handler.render, and look at the screenshot; after `npx foldspace published`, the reply, cards and screenshot are the proof",
+      "Only then invite the human to try it: with attach running, `npx foldspace badge ready` first; after `npx foldspace published` there is no pill - say in chat it is ready (a reload takes it off the published code), then `npx foldspace attach --daemon` before you build anything else",
     ],
   }),
   Object.freeze({
@@ -374,19 +392,52 @@ export const CLI_COMMANDS = Object.freeze([
         name: "state",
         required: true,
         description:
-          "working: the agent is building here, leave the window alone | ready: the pill goes away, their turn | label: the small corner tag | off: remove it",
+          "working: you are working in the window; the human leaves it alone | ready: the pill goes away, their turn | label: the small corner tag | off: draw nothing - no pill, no corner tag",
       }),
     ],
     options: [
-      value("--text", "text", "working only: one extra line under the ask (up to 160 characters)"),
+      value("--text", "text", "working only: a short sentence added at the end of the pill (up to 160 characters)"),
     ],
-    prerequisites: ["foldspace attach is running (it draws the badge)"],
+    prerequisites: ["foldspace attach is running (it draws the pill and the corner tag)"],
     effects: [
       "Writes one key to the test window's sessionStorage; touches nothing else on the page",
       "The pill survives navigation inside the test window",
     ],
     next: ["Say in chat whose turn it is and what to try"],
   }),
+  Object.freeze({
+    name: "published",
+    entry: "published.mjs",
+    group: "verify",
+    summary: "Point the test window's agent at its published dev or prod code, so foldspace ask checks that code",
+    usage: "foldspace published <dev|prod>",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT"],
+    capabilities: ["browser.cdp", "page.evaluate", "page.mutate"],
+    positionals: [
+      Object.freeze({
+        name: "environment",
+        required: true,
+        description:
+          "dev: the code the `deploy` tool published to dev | prod: the code their users get",
+      }),
+    ],
+    options: [],
+    prerequisites: [
+      "attach is not running: npx foldspace attach --stop (while it runs the page serves your local build)",
+      "The page loads this project's agent by itself: the same product and Agent Key as foldspace.dev.json",
+    ],
+    effects: [
+      "Points this page's agent, in this test window, at the code published to the environment you name; the actions that code defines answer from it, the others keep the page's own handlers",
+      "A reload puts the page back on what the agent loads normally",
+      "Publishes nothing and changes nothing in Foldspace",
+    ],
+    next: [
+      'Prove it: npx foldspace ask "<question>" --retry 2',
+      "To go back to the local build: npx foldspace attach --daemon",
+    ],
+  }),
   Object.freeze({
     name: "deploy",
     // Foldspace-internal: it uploads to Foldspace's own storage, which no
@@ -431,7 +482,7 @@ export const CLI_COMMANDS = Object.freeze([
 
 export const CAPABILITY_CATALOGUE = Object.freeze([
   ["project.scaffold", "Create a new configured project on local disk"],
-  ["project.upgrade", "Update the consuming project's exact harness pin"],
+  ["project.upgrade", "Update the harness version the consuming project uses"],
   ["artifact.build", "Build the portable dist/index.js action artifact"],
   ["browser.launch", "Launch an isolated local Chrome profile"],
   ["browser.cdp", "Connect to local Chrome through CDP"],
@@ -470,6 +521,7 @@ export function commandByName(name) {
 export function createCliRegistry({ packageName, packageVersion, env = process.env }) {
   const showInternal = env.FOLDSPACE_INTERNAL === "1";
   const visible = CLI_COMMANDS.filter((command) => showInternal || !command.internal);
+  const used = (key) => new Set(visible.flatMap((command) => [].concat(command[key] ?? [])));
   const diagnostics = diagnosticCatalogue()
     .filter((diagnostic) => PUBLIC_DIAGNOSTICS.has(diagnostic.name))
     .map((diagnostic) => ({
@@ -488,27 +540,30 @@ export function createCliRegistry({ packageName, packageVersion, env = process.e
     workflow: ["init", "build", "inject", "attach"],
     verifyWorkflow: ["observe", "ask"],
     publishWorkflow: showInternal ? ["deploy"] : [],
-    capabilities: CAPABILITY_CATALOGUE.map(([id, description]) => ({
-      id,
-      description,
-    })),
-    risks: RISK_CATALOGUE.map(([id, description]) => ({ id, description })),
-    environments: ENVIRONMENT_CATALOGUE.map(([id, description]) => ({
+    // Only what a listed command uses: a hidden command's publish capability,
+    // risk or cloud environment would advertise a path nobody in a build takes.
+    capabilities: CAPABILITY_CATALOGUE.filter(([id]) => used("capabilities").has(id)).map(
+      ([id, description]) => ({ id, description }),
+    ),
+    risks: RISK_CATALOGUE.filter(([id]) => used("risk").has(id)).map(([id, description]) => ({
       id,
       description,
     })),
+    environments: ENVIRONMENT_CATALOGUE.filter(([id]) => used("environment").has(id)).map(
+      ([id, description]) => ({ id, description }),
+    ),
     commands: visible.map(({ entry: _entry, internal: _internal, ...command }) => command),
     diagnostics,
     notes: [
       "Capability metadata describes current behavior; it is not hosted-environment enforcement.",
-      "Action verification is passive and agent-driven.",
+      "Actions are verified only through the agent: `npx foldspace ask` asks it through its panel; nothing calls a handler directly.",
       "The harness bin alias is equivalent to foldspace.",
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
-      "Coding agents should run attach --daemon; foreground attach is for humans watching the terminal.",
-      "If update.outdated is true, ask the user before foldspace upgrade --yes.",
-      "If update.broken is true, this version was withdrawn and build and attach refuse to run. Ask the user to upgrade; set FOLDSPACE_SKIP_UPDATE_CHECK=1 only if they decline.",
-      "observe, ask and run are read-only second clients on the test window and work while attach runs.",
-      "There is no customer-run publication step: putting actions in front of end users is done with Foldspace's team.",
+      "Coding agents run attach --daemon; foreground attach is for someone watching the terminal.",
+      "If update.outdated is true, ask the human before npx foldspace upgrade --yes.",
+      "If update.broken is true, this version was withdrawn and build and attach refuse to run. Ask the human to agree to the upgrade; set FOLDSPACE_SKIP_UPDATE_CHECK=1 only if they decline.",
+      "observe looks at the app, and ask tests the agent through its panel; both work while attach runs.",
+      "`foldspace deploy` is for Foldspace staff only: never run or offer it - it is not the `deploy` tool. With a code project, putting the agent's code in front of their users is yours, as the manual's \"Done, and what you say at the end\" says: save with `repo_write`; publish to dev with the `deploy` tool (say you are doing it, then do it - unless its dev preview comes back with no warnings, which means this agent loads dev for its users: then ask first, as for production); check dev with `npx foldspace attach --stop`, `npx foldspace published dev` and `npx foldspace ask \"<question>\" --retry 2`; and publish to production only once that check passed and the human says yes. The dev check and production need a site that loads the agent by itself: after `attach --bootstrap` or `--replace`, publish to dev only, keep attach running, and the rest is a step the Foldspace team does with the human. If `published` says this window cannot show dev, say so in one sentence, attach again, and stop after dev. Without a code project, or when a Foldspace tool refuses (except a save refused because someone saved after you read: redo it as `repo_read` command `instructions` says), the Foldspace team does it with the human (https://foldspace.ai/demo, support@foldspace.ai).",
     ],
   };
 }

package/src/diagnostics.mjs

@@ -193,7 +193,7 @@ export const DIAGNOSTICS = Object.freeze({
 
   verifyWidgetVisible: Object.freeze({
     description:
-      "Report whether a Foldspace widget candidate is mounted and has a visible bounding box.",
+      "Report whether the Foldspace agent's panel is mounted and has a visible bounding box.",
     risk: "observe",
     capabilities: Object.freeze([CAPABILITIES.PAGE_EVALUATE]),
     run: function verifyWidgetVisible(args = {}) {