@foldspace_npm/harness 0.1.16 → 0.1.17

package/CLAUDE.md

@@ -71,11 +71,15 @@ current CLI contract — risk, prerequisites, effects, next step.
    so and offer the next one. On an empty account the useful first action is
    one that creates data - say so instead.
 
-**Say when the test window is yours, and when it is theirs.** You and the
-human share one Chrome window. Before you start looking at the app or testing
-in it: *"I'm going to work in that Chrome window for a few minutes - please
-leave it alone until I tell you it's ready."* When it is their turn: *"It's
-ready. Try asking: <the question this experience answers>."*
+**Say when the test window is yours, and when it is theirs - on the page and
+in chat.** You and the human share one Chrome window. Before you start looking
+at the app or testing in it, run `npx foldspace badge working` (a bar across
+the top of the window says Foldspace is building here, leave it alone) and say
+so in chat: *"I'm going to work in that Chrome window for a few minutes -
+please leave it alone until I tell you it's ready."* When it is their turn,
+`npx foldspace badge ready --text "Try asking: <the question this experience
+answers>"` and the same line in chat. `foldspace badge label` puts the small
+corner tag back; `off` removes it, for a screenshot they will share.
 
 Navigation, uploads, extraction and anything that writes are a later session.
 
@@ -207,11 +211,17 @@ with how you established each.
 | Navigation route | **yes** | `isActive: true` |
 
 Publishing a **new** object is inert; publishing an **edit to a live one** is
-the deploy above. Navigation has **no publish tool on the MCP** and
-`get_navigation_route` returns only `isActive` — publish routes in Agent Studio
-and say so. Route descriptions are a retrieval surface: write what the page is
-*for*, in the user's words, and pair every parameterised route with the lookup
-action that produces its parameter — or ship neither.
+the deploy above. **Navigation has two switches, and both must be on.** Each
+route has its own `isActive`, set when you create it (`create_navigation_route`
+/ `bulk_create_navigation_routes`, `isActive: true`). The agent has one
+agent-level switch, **off by default on a new subscription**: `publish_navigation`
+turns it on, `unpublish_navigation` off, and neither touches the routes' own
+`isActive`. `list_navigation_routes` shows both. There is no MCP tool to flip a
+single route's `isActive` after creation (it was disabled until Agent Studio
+can reverse it) - create it right, or `update_navigation_route`, which replaces
+the whole route. Route descriptions are a retrieval surface: write what the
+page is *for*, in the user's words, and pair every parameterised route with the
+lookup action that produces its parameter — or ship neither.
 
 **Ask before publishing.** It is required only so the copilot can call the
 action, and it is a live product change when the agent has real users.
@@ -247,6 +257,23 @@ copilot, read the daemon log for `[actions]` SDK callback and local
 execute/render lines. Those record names, statuses, durations and parameter keys
 only — never results or error bodies.
 
+## Done, and what you say at the end
+
+A first session is done when the customer has seen one experience answer from
+their own data, in the test window, and been invited to try it. Not when the
+gates pass, and not when there is nothing left to improve.
+
+If they ask *"how do I put this in front of my users?"*, the honest answer is:
+
+> What you've seen runs in a test window on your machine. Putting it in front
+> of your users is a separate step, and the Foldspace team does it with you.
+> Reach them through the website - <https://foldspace.ai/demo> - or at
+> <support@foldspace.ai>. Everything built today carries over: the actions are
+> already in your Foldspace account, and the code is in this folder.
+
+Never run `foldspace deploy`, never install cloud tooling, never ask them for
+cloud credentials: `deploy` is Foldspace-internal and no customer can run it.
+
 ## Verification gates
 
 Do not report success without all six:
@@ -288,14 +315,17 @@ Do not report success without all six:
    MCP (`search_docs`, `fetch_page`) before asserting how the platform behaves;
    cite the page, or say plainly that the docs do not cover it and write down
    what you learned.
-4. **Do not send chat messages to test.** Every message is a real conversation
-   in the customer's list. `runTask` creates no conversation record — use it.
-5. **Test mode is off by default.** A new agent has no traffic to pollute, and
-   watching real conversations appear is the point of the first run. Arm it
-   only when the tenant already has real conversations — and then on **every**
-   instance via `armAllInstances`, because `foldspace.agent({apiName})` returns
-   the overlay handle, which is not the one serving an embedded chat. Nothing
-   can confirm it is on afterwards; never send probe messages to find out.
+4. **Test through the agent, then let them.** In a first session, talk to the
+   agent yourself to prove an experience - type the real question into its
+   panel in the test window and read the reply - and only then invite the
+   customer to try it. Those conversations appear in their Foldspace dashboard,
+   and that is wanted: seeing their own conversations recorded is part of what
+   they came to see. Never pass `--test-mode` in a first session.
+5. **Test mode is for an agent that already has real users.** Then `attach
+   --test-mode` keeps your conversations out of their data. It is not a safety
+   net: publishing still changes the live agent. Working on an agent in
+   production - test mode, pinned action versions, what may be published - is
+   a separate playbook, not this one.
 6. **The human is not necessarily a developer.** Never hand over a terminal
    line, a stack trace, or a choice between flags. Name experiences by outcome
    — *"show my plan and credits"*, not `get_account_status`. Their two jobs:

package/README.md

@@ -252,7 +252,7 @@ and **neither had all five**:
 | SDK load guard + retry | On an app with no `document.body` at document-start the append throws; the old guard tested for the stub, so nothing retried and the agent silently never loaded |
 | Worker release on auto-attach | Auto-attach pauses every worker until the attaching client releases it — the harness froze the app's own workers for the whole session |
 | `agentIds` enumeration | `agent({apiName})` returns the OVERLAY handle; arming it on an embedded copilot leaves real conversations untagged |
-| `--no-test-mode` | Test mode was armed unconditionally, hiding exactly what initial setup needs to see |
+| `--test-mode` (off by default) | Test mode was armed unconditionally, hiding exactly what initial setup needs to see; now it is opt-in |
 | Honest badge | It asserted `TEST MODE` whether or not test mode was on |
 
 Two further changes came from packaging it: the bundle is **injected** rather

package/bin/attach.mjs

@@ -135,11 +135,13 @@ try {
 }
 const bootstrap = attachMode === ATTACH_MODES.BOOTSTRAP;
 const replace = attachMode === ATTACH_MODES.REPLACE;
-// Test mode keeps conversations out of the customer's default list. Turn it off
-// only when you WANT the conversations and action calls to show up in the
-// Foldspace dashboard — a brand-new agent during initial setup, where there is
-// no production traffic to pollute.
-const noTestMode = process.argv.includes("--no-test-mode");
+// Test mode keeps conversations out of the customer's default list. It is OFF
+// by default: in a first session the customer's own conversations appearing in
+// their dashboard is the point - they see what Foldspace records - and an
+// orange TEST MODE label would imply a safety (nothing published) that does
+// not exist. --test-mode opts in, for an agent that already has real users.
+// --no-test-mode is still accepted so older instructions keep working.
+const noTestMode = !process.argv.includes("--test-mode");
 // The badge used to hardcode "TEST MODE" whether or not test mode was on — a
 // string that asserts you are safe while you are not. It now states what is
 // actually true. --no-badge drops it entirely, for recording a demo.
@@ -171,8 +173,8 @@ const agentKey = cfgTarget.overrideKey || `EU-${productId}-1-1`;
 const sdkUrl = cfgTarget.sdkUrl || cfg.sdkUrl;
 const actionTarget = { productId, agentApiName };
 const badgeText = noTestMode
-  ? `FOLDSPACE DEV \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 LIVE`
-  : `FOLDSPACE DEV \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 TEST MODE`;
+  ? `FOLDSPACE AGENT BUILDER \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 LIVE`
+  : `FOLDSPACE AGENT BUILDER \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 TEST MODE`;
 
 // Refuse to run against an uninitialised template. Without this, attach injects
 // the literal placeholder as an agent api name and the page fails with an opaque
@@ -218,19 +220,45 @@ const SDK_PATTERNS = [
   "*://*/*eucera.js*",
 ];
 
+// The badge has three states, set from outside with \`foldspace badge\`:
+//   label   - the small corner tag (default): who is attached, which mode
+//   working - a bar across the top: the agent is building in this window,
+//             please leave it alone
+//   ready   - a bar: it is the human's turn, with the question to try
+// The state lives in sessionStorage so it survives navigation inside the
+// test window; \`foldspace badge\` writes it and the script redraws.
 const badgeSrc = `(() => {
   if (window.top !== window.self) return;
-  const add = () => {
-    if (document.getElementById("foldspace-dev-badge") || !document.body) return;
-    const b = document.createElement("div");
-    b.id = "foldspace-dev-badge";
-    b.textContent = ${JSON.stringify(badgeText)};
-    b.style.cssText = "position:fixed;top:0;left:0;z-index:2147483647;background:#3247F2;color:#fff;font:700 10px/1 ui-monospace,Menlo,monospace;letter-spacing:.12em;padding:5px 10px;border-bottom-right-radius:4px;pointer-events:none;box-shadow:0 1px 6px rgba(0,0,0,.35)";
-    document.body.appendChild(b);
+  const LABEL = ${JSON.stringify(badgeText)};
+  const KEY = "__foldspace_badge__";
+  const read = () => {
+    try { return JSON.parse(sessionStorage.getItem(KEY) || "null") || { state: "label" }; }
+    catch (e) { return { state: "label" }; }
   };
-  add();
-  document.addEventListener("DOMContentLoaded", add);
-  setInterval(add, 2000);
+  const draw = () => {
+    if (!document.body) return;
+    const s = read();
+    if (s.state === "off") { document.getElementById("foldspace-dev-badge")?.remove(); return; }
+    let b = document.getElementById("foldspace-dev-badge");
+    if (!b) { b = document.createElement("div"); b.id = "foldspace-dev-badge"; document.body.appendChild(b); }
+    const want = s.state + "|" + (s.text || "");
+    if (b.dataset.fsState === want) return;
+    b.dataset.fsState = want;
+    const base = "position:fixed;top:0;left:0;z-index:2147483647;color:#fff;font:700 10px/1 ui-monospace,Menlo,monospace;letter-spacing:.12em;pointer-events:none;box-shadow:0 1px 6px rgba(0,0,0,.35);";
+    if (s.state === "working") {
+      b.style.cssText = base + "right:0;background:#3247F2;padding:9px 14px;font-size:12px;letter-spacing:.04em;text-align:center;";
+      b.textContent = s.text || "Foldspace is building your agent on this page. Please leave this window alone until Claude says it is ready.";
+    } else if (s.state === "ready") {
+      b.style.cssText = base + "right:0;background:#0F9D58;padding:9px 14px;font-size:12px;letter-spacing:.04em;text-align:center;";
+      b.textContent = s.text || "Ready - your turn. Open your agent and try it.";
+    } else {
+      b.style.cssText = base + "background:#3247F2;padding:5px 10px;border-bottom-right-radius:4px;";
+      b.textContent = LABEL;
+    }
+  };
+  draw();
+  document.addEventListener("DOMContentLoaded", draw);
+  setInterval(draw, 1000);
 })();`;
 
 // Flag every local session as test traffic so it is excluded from analytics and
@@ -951,7 +979,7 @@ const ver = await connect(owned.version);
 console.log(`Attached to ${ver.Browser} on :${port}`);
 console.log(`Mode:  ${attachMode}`);
 console.log(`Agent: ${agentApiName} (product ${productId}, ${agentMode})`);
-console.log(`Test:  ${noTestMode ? "OFF — conversations WILL appear in the dashboard" : "on"}`);
+console.log(`Test:  ${noTestMode ? "off — conversations appear in the dashboard (pass --test-mode to hide them)" : "on"}`);
 console.log(`Hosts: ${hostPatterns.join(", ")}`);
 console.log(`Serving: ${path.relative(root, bundlePath)}`);
 console.log(

package/bin/badge.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * foldspace badge <working|ready|label|off> [--text "<what to show>"]
+ *
+ * Sets the banner the attach badge draws across the top of the test window.
+ * The agent and the human share that one Chrome window, so the banner says
+ * whose turn it is:
+ *   working - "Foldspace is building your agent on this page. Please leave
+ *             this window alone until Claude says it is ready."
+ *   ready   - "Ready - your turn. Open your agent and try it." (pass --text
+ *             with the question to try)
+ *   label   - back to the small corner tag
+ *   off     - remove it
+ * The state is kept in the page's sessionStorage, so it survives navigation;
+ * attach's badge script redraws within a second. Nothing else on the page is
+ * touched.
+ */
+import { CdpPage, parseArgs, printJson } from "../src/cdp-client.mjs";
+import { resolveProjectDir } from "../src/upgrade.mjs";
+import { badgePayload } from "../src/badge-core.mjs";
+
+const projectDir = resolveProjectDir();
+const { flags, rest } = parseArgs(process.argv.slice(2), ["text"]);
+
+let payload;
+try {
+  const unknown = Object.keys(flags).filter((name) => name !== "text");
+  if (unknown.length) throw new Error(`unknown option '--${unknown[0]}'`);
+  if (rest.length > 1) throw new Error(`unexpected argument '${rest[1]}'`);
+  payload = badgePayload(rest[0], flags.text);
+} catch (error) {
+  console.error(`badge: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
+
+let page;
+try {
+  page = await CdpPage.open({ projectDir });
+  const shown = await page.evaluate(
+    `sessionStorage.setItem("__foldspace_badge__", ${JSON.stringify(JSON.stringify(payload))});
+     const b = document.getElementById("foldspace-dev-badge");
+     return { url: location.href.split(/[?#]/)[0], hadBadge: Boolean(b) };`,
+  );
+  printJson({ ok: true, state: payload.state, ...(payload.text ? { text: payload.text } : {}), ...shown });
+} catch (error) {
+  printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+  process.exit(1);
+} finally {
+  page?.close();
+}

package/bin/inject.mjs

@@ -144,7 +144,7 @@ fs.writeFileSync(
   path.join(themeDir, "manifest.json"),
   JSON.stringify({
     manifest_version: 3,
-    name: "Foldspace Dev Theme",
+    name: "Foldspace Agent Builder Theme",
     version: "1.0",
     description: "Paints the dev browser Foldspace blue.",
     theme: {
@@ -197,7 +197,7 @@ function nameProfile() {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(data));
   };
-  const label = `Foldspace Dev \u2014 ${target.name}`;
+  const label = `Foldspace Agent Builder \u2014 ${target.name}`;
   writeMerged(path.join(profileDir, "Local State"), (d) => {
     d.profile = d.profile || {};
     d.profile.info_cache = d.profile.info_cache || {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/recipes/INDEX.md

@@ -7,6 +7,7 @@ Read this whole table, then open the recipe closest to the outcome.
 | [`who-is-the-user`](who-is-the-user/) | **L0** | Foldspace knows who is signed in — id, email, name, role, subscription — so conversations and analytics are not anonymous | Runs once at start-up. No action, no card | 4 production builds |
 | [`find-by-name`](find-by-name/) | **L2** | The agent turns a name the user said into the id the next action needs; a count when no name is given; every tie when the name is ambiguous; near-misses when nothing matches | A data action. **No card** | 3 production builds |
 | [`pick-from-a-list`](pick-from-a-list/) | **L2** | A clickable list, shown **only** when the user has to choose — with "none of these" and cancel | An action with a card that waits for the user | 1 production build |
+| [`bottom-bar`](bottom-bar/) | **L0** | The agent's resting entry point is a bar at the foot of the page whose starters change with the screen the user is on — configured from code, the way customers do it | Page set-up, runs once at start-up | 2 |
 | [`swap-the-login-method`](swap-the-login-method/) | any | `apiFetch` for an app that authenticates with a custom header, or with cookies, instead of a bearer token | A replacement `agent/utils.ts` | 2 production builds (3 builds, 3 different schemes) |
 
 **Not here yet — no production build proves it:** the user's own plan or

package/recipes/bottom-bar/README.md

@@ -0,0 +1,43 @@
+# Bottom bar with page starters — L0
+
+The bottom bar is the agent's resting entry point: a bar at the foot of the
+page that shows a few starters and opens the agent when one is clicked. Its
+starters change with the screen the user is on, so an agent with two actions
+still looks useful everywhere.
+
+It is configured **from code** — Agent Studio has no UI for it today, and this
+is how customers set it. **Proven by 2 production builds** (one in the
+product's own source, one from the agent project behind a feature flag).
+
+## Adapt it
+
+| In `agent/bottomBar.ts` | Change |
+|---|---|
+| `PAGE_STARTERS` | This product's screens (path prefixes) and, for each, two or three questions **its actions can answer**. A starter for something the agent cannot do is worse than none |
+| `DEFAULT_STARTERS` | What to show on any other page |
+| `BOTTOM_BAR_SETTINGS` | Leave as the docs' defaults unless the product asks |
+
+Then call it from the bundle's entry point:
+
+```ts
+// agent/actions/index.ts — last line
+import { installBottomBar } from "../bottomBar";
+installBottomBar();
+```
+
+## What those builds learned
+
+- **`setConversationStarters` replaces the whole set for the page** — both
+  groups. `null` restores Agent Studio's. So always pass the full list you
+  want shown.
+- **In embedded mode the bar needs `openEmbeddedCallback`**, or nothing opens
+  when a starter is clicked. This recipe is for the overlay agent; see the
+  docs for embedded.
+- **Route changes in a single-page app don't reload**, so the starters must be
+  re-applied on navigation — this recipe wraps `pushState` / `replaceState`
+  and listens to `popstate`.
+- **Dark mode**: the SDK's default colours are being fixed (PLG-5891). Until
+  then a product in dark mode may need `theme` / `darkModeSettings` set.
+
+Docs: [Bottom Bar](https://docs.foldspace.ai/customize/bottom-bar/) ·
+[Conversation starters](https://docs.foldspace.ai/customize/conversation-starters/)

package/recipes/bottom-bar/agent/bottomBar.ts

@@ -0,0 +1,94 @@
+// The bottom bar: the agent's resting entry point at the foot of the page,
+// cycling starters that fit the screen the user is on. Configured from code -
+// Agent Studio has no UI for it today, and this is how customers set it.
+// https://docs.foldspace.ai/customize/bottom-bar/
+// https://docs.foldspace.ai/customize/conversation-starters/
+//
+// Product-neutral: the paths and starters below are placeholders. Replace them
+// with this product's own screens and with questions its actions can answer.
+
+import { getAgent } from "./utils";
+
+/** Starters per screen. Paths are matched as prefixes, first match wins. */
+export const PAGE_STARTERS: Array<{ match: RegExp; starters: string[] }> = [
+  { match: /^\/dashboard/, starters: ["<A question about what this screen shows>", "<Another one>"] },
+  { match: /^\/<records>/, starters: ["Find <a record> by name", "Show me <a record>'s details"] },
+];
+
+/** Shown on any page not listed above. */
+export const DEFAULT_STARTERS: string[] = ["What can you do?", "Show my account"];
+
+// The docs' own settings, unchanged. Change nothing here unless the product
+// asks for it: every field is documented on the Bottom Bar page.
+export const BOTTOM_BAR_SETTINGS = {
+  enabled: true,
+  maxVisibleStarters: 3,
+  reopenFrequency: "EVERY_LOAD",
+  starterClickBehavior: "OPEN_AGENT",
+  idleTimeoutMs: 5000,
+  initialBehaviorMode: "FULL",
+} as const;
+
+export function startersForPath(pathname: string): string[] {
+  const hit = PAGE_STARTERS.find((entry) => entry.match.test(pathname));
+  return hit ? hit.starters : DEFAULT_STARTERS;
+}
+
+// On window, not in module scope: a bundle evaluated twice on one page must
+// not install two route listeners.
+const INSTALLED_FLAG = "__foldspace_bottom_bar__";
+
+/**
+ * Turn the bar on and keep its starters matched to the page. Call once from
+ * the bundle's entry point; safe to call again.
+ *
+ * `setConversationStarters` REPLACES the whole set for this page view (both
+ * groups); passing `null` restores what Agent Studio has. Starters go in the
+ * KNOWLEDGE group so the bar shows them as plain questions.
+ */
+export function installBottomBar(): void {
+  const foldspace = (window as any).foldspace;
+  if (typeof foldspace !== "function") return;
+  if ((window as any)[INSTALLED_FLAG]) return;
+  (window as any)[INSTALLED_FLAG] = true;
+
+  foldspace("when", "ready", () => {
+    const agent = getAgent();
+    if (!agent) return;
+    let current: string[] = [];
+
+    const apply = () => {
+      const next = startersForPath(window.location.pathname);
+      if (next === current) return;
+      current = next;
+      agent.setConversationStarters?.(
+        { KNOWLEDGE: next.map((title) => ({ title })), ACTION: [] },
+        "KNOWLEDGE",
+      );
+    };
+
+    // One whole settings group per call, as the docs do.
+    agent.setConfiguration?.({ bottomBarSettings: BOTTOM_BAR_SETTINGS });
+    apply();
+
+    // Single-page apps change the URL without a load: re-apply on navigation
+    // and bring the bar back so the new starters are seen.
+    const onRouteChange = () => {
+      apply();
+      agent.openBottomBar?.({ mode: "FULL" });
+    };
+    window.addEventListener("popstate", onRouteChange);
+    const history = window.history as any;
+    for (const method of ["pushState", "replaceState"] as const) {
+      const original = history[method];
+      if (typeof original !== "function" || original.__foldspaceWrapped) continue;
+      const wrapped = function (this: any, ...args: unknown[]) {
+        const result = original.apply(this, args);
+        onRouteChange();
+        return result;
+      };
+      (wrapped as any).__foldspaceWrapped = true;
+      history[method] = wrapped;
+    }
+  });
+}

package/recipes/bottom-bar/fixtures/configuration.sent.json

@@ -0,0 +1,17 @@
+{
+  "note": "This recipe makes no network calls. What it sends to the SDK on /dashboard:",
+  "setConfiguration": {
+    "bottomBarSettings": {
+      "enabled": true,
+      "maxVisibleStarters": 3,
+      "reopenFrequency": "EVERY_LOAD",
+      "starterClickBehavior": "OPEN_AGENT",
+      "idleTimeoutMs": 5000,
+      "initialBehaviorMode": "FULL"
+    }
+  },
+  "setConversationStarters": {
+    "starters": { "KNOWLEDGE": [{ "title": "<A question about what this screen shows>" }, { "title": "<Another one>" }], "ACTION": [] },
+    "defaultStarterType": "KNOWLEDGE"
+  }
+}

package/recipes/bottom-bar/recipe.json

@@ -0,0 +1,9 @@
+{
+  "title": "Bottom bar with page starters",
+  "level": "L0",
+  "family": "entry-point",
+  "kind": "page-setup",
+  "entry": "agent/bottomBar.ts",
+  "outcome": "The agent's resting entry point is a bar at the bottom of the page whose starters change with the page the user is on",
+  "provenBy": 2
+}

package/src/badge-core.mjs

@@ -0,0 +1,22 @@
+// Pure logic behind `foldspace badge`, unit-tested.
+
+export const BADGE_STATES = ["working", "ready", "label", "off"];
+
+/** What gets written into the page for a badge state, or throws on bad input. */
+export function badgePayload(state, text) {
+  const wanted = String(state || "").trim().toLowerCase();
+  if (!BADGE_STATES.includes(wanted)) {
+    throw new Error(`usage: foldspace badge <${BADGE_STATES.join("|")}> [--text "<what to show>"]`);
+  }
+  const payload = { state: wanted };
+  if (text !== undefined) {
+    if (wanted !== "working" && wanted !== "ready") {
+      throw new Error(`--text only applies to working or ready (got ${wanted}).`);
+    }
+    const clean = String(text).replace(/\s+/g, " ").trim();
+    if (!clean) throw new Error("--text is empty.");
+    if (clean.length > 160) throw new Error("--text is longer than 160 characters; keep it to one line.");
+    payload.text = clean;
+  }
+  return payload;
+}

package/src/cli-registry.mjs

@@ -241,9 +241,10 @@ export const CLI_COMMANDS = Object.freeze([
       ),
       value("--agent", "api-name", "Override the configured agent API name"),
       flag(
-        "--no-test-mode",
-        "Do not mark conversations as test traffic; use deliberately",
+        "--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(
         "--daemon",
@@ -261,7 +262,7 @@ export const CLI_COMMANDS = Object.freeze([
     effects: [
       "May reload and instrument matching target pages",
       "Refuses a Chrome that is not the profile inject launched",
-      "Test mode is enabled unless --no-test-mode is passed",
+      "Test mode is off unless --test-mode is passed: conversations appear in the dashboard",
       "Never directly invokes an action handler",
       "An empty local action registry is valid; named actions are not required",
       "Restores prepared pages when detached cleanly",
@@ -316,6 +317,34 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     next: ["Record what you established in docs/app-profile.md", "Write the handler"],
   }),
+  Object.freeze({
+    name: "badge",
+    entry: "badge.mjs",
+    group: "verify",
+    summary: "Set the banner across the top of the test window: working, ready, label or off",
+    usage: 'foldspace badge <working|ready|label|off> [--text "<what to show>"]',
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT"],
+    capabilities: ["browser.cdp", "page.evaluate"],
+    positionals: [
+      Object.freeze({
+        name: "state",
+        required: true,
+        description:
+          "working: the agent is building here, leave the window alone | ready: the human's turn | label: the small corner tag | off: remove it",
+      }),
+    ],
+    options: [
+      value("--text", "text", "working/ready: the line to show, e.g. the question to try (one line, up to 160 characters)"),
+    ],
+    prerequisites: ["foldspace attach is running (it draws the badge)"],
+    effects: [
+      "Writes one key to the test window's sessionStorage; touches nothing else on the page",
+      "The banner survives navigation inside the test window",
+    ],
+    next: ["Tell the human in chat what the banner says"],
+  }),
   Object.freeze({
     name: "deploy",
     // Foldspace-internal: it uploads to Foldspace's own storage, which no