@foldspace_npm/harness 0.1.16 → 0.1.18

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 "<the question this experience answers>"` -
+the bar adds "Try asking:" and a Copy button itself - and say the same 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:
@@ -408,10 +438,14 @@ placeholder path and fields with what you observed. They match the harness
 version you have installed, and every one is built and run on each release.
 
 L0 → `who-is-the-user`. L2 → `find-by-name`, and `pick-from-a-list` when the
-user has to choose. App does not use a bearer token → `swap-the-login-method`.
+user has to choose. Show one account on a card → `account-overview`. Upload a
+CSV of contacts → `upload-contacts`. Save a note on a meeting →
+`update-meeting-notes`. Prepare for a meeting → `prepare-for-a-meeting`. The records that need
+attention, with reasons → `opportunities-at-risk`.
+App does not use a bearer token → `swap-the-login-method`.
 Each says how many production builds carry the pattern and what they learned.
-If nothing fits — there is no L1 card recipe yet — say so and build from
-`agent/actions/_example.ts`.
+If nothing fits — there is no L1 card recipe yet, and no navigation recipe —
+say so and build from `agent/actions/_example.ts`.
 
 ## What you already have
 

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

@@ -44,6 +44,7 @@ import {
 } from "../src/attach-preflight.mjs";
 import { serializeDiagnostic } from "../src/diagnostics.mjs";
 import { recordEvent } from "../src/session-events.mjs";
+import { withoutStealingFocus } from "../src/keep-focus.mjs";
 import {
   ERROR_CODES,
   createLifecycleResult,
@@ -135,11 +136,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 +174,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 +221,69 @@ 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") {
+      // Attention, not decoration: a pulsing marker, the ask in bold, and an
+      // animated line underneath so it reads as "in progress" at a glance.
+      b.style.cssText = base + "right:0;background:#1F2A8A;padding:10px 14px 12px;font-size:13px;letter-spacing:.02em;text-align:center;line-height:1.3;";
+      b.innerHTML =
+        '<style>@keyframes fsPulse{0%,100%{opacity:1}50%{opacity:.25}}@keyframes fsSweep{0%{left:-30%}100%{left:100%}}' +
+        '#foldspace-dev-badge .fs-dot{display:inline-block;width:10px;height:10px;border-radius:50%;background:#FFB300;margin-right:10px;vertical-align:middle;animation:fsPulse 1s ease-in-out infinite}' +
+        '#foldspace-dev-badge .fs-line{position:absolute;left:0;right:0;bottom:0;height:3px;background:rgba(255,255,255,.15);overflow:hidden}' +
+        '#foldspace-dev-badge .fs-line::after{content:"";position:absolute;top:0;width:30%;height:100%;background:#FFB300;animation:fsSweep 1.4s linear infinite}</style>' +
+        '<span class="fs-dot"></span>Foldspace is building your agent on this page. <b style="color:#FFD54F">Please leave this window alone</b> until Claude says it is ready.' +
+        (s.text ? " " + s.text.replace(/[<>&]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c]) : "") +
+        '<span class="fs-line"></span>';
+    } else if (s.state === "ready") {
+      // Calm, and useful: the question to try, with a Copy button so nobody
+      // retypes it into the panel. The bar accepts clicks only on that button.
+      const esc = (t) => String(t).replace(/[<>&"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;" })[c]);
+      const question = s.text ? esc(s.text) : "";
+      b.style.cssText = base + "right:0;background:#0F9D58;padding:10px 14px;font-size:13px;letter-spacing:.02em;text-align:center;line-height:1.3;pointer-events:none;";
+      b.innerHTML =
+        '<style>#foldspace-dev-badge .fs-copy{pointer-events:auto;margin-left:12px;padding:4px 10px;border:1px solid rgba(255,255,255,.7);border-radius:4px;background:transparent;color:#fff;font:inherit;font-size:12px;cursor:pointer;letter-spacing:0}' +
+        '#foldspace-dev-badge .fs-copy:hover{background:rgba(255,255,255,.15)}</style>' +
+        '<b>Ready - your turn.</b> ' +
+        (question ? 'Try asking: <span class="fs-q">' + question + '</span><button class="fs-copy" type="button">Copy</button>' : "Open your agent and try it.");
+      const btn = b.querySelector(".fs-copy");
+      if (btn) btn.addEventListener("click", () => {
+        const q = b.querySelector(".fs-q")?.textContent || "";
+        const done = () => { btn.textContent = "Copied"; setTimeout(() => { btn.textContent = "Copy"; }, 1500); };
+        if (navigator.clipboard?.writeText) navigator.clipboard.writeText(q).then(done, done);
+        else { const ta = document.createElement("textarea"); ta.value = q; document.body.appendChild(ta); ta.select(); try { document.execCommand("copy"); } catch (e) {} ta.remove(); done(); }
+      });
+    } 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
@@ -696,7 +749,7 @@ async function prepare(ws, sessionId, url) {
       ),
     });
     console.log(`  attached -> ${url}`);
-    await call(ws, "Page.reload", { ignoreCache: true }, sessionId);
+    await withoutStealingFocus(() => call(ws, "Page.reload", { ignoreCache: true }, sessionId));
 
     {
       const verification = await verifyPreparedPage(ws, sessionId);
@@ -951,7 +1004,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(
@@ -1011,7 +1064,7 @@ async function cleanupPreparedSession(
   // identity aliases alike.
   if (reload) {
     try {
-      await call(socket, "Page.reload", { ignoreCache: true }, sessionId);
+      await withoutStealingFocus(() => call(socket, "Page.reload", { ignoreCache: true }, sessionId));
     } catch (error) {
       failures.push(`restore reload: ${error instanceof Error ? error.message : String(error)}`);
     }

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/bin/observe.mjs

@@ -22,6 +22,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { CdpPage, parseArgs, printJson, readLaunchState, sleep } from "../src/cdp-client.mjs";
+import { withoutStealingFocus } from "../src/keep-focus.mjs";
 import {
   NAV_ITEM_SELECTOR,
   NAV_SCOPE_SELECTOR,
@@ -330,7 +331,7 @@ async function runScreen(page, flags) {
   let reached;
 
   if (destination) {
-    await page.send("Page.navigate", { url: destination.url });
+    await withoutStealingFocus(() => page.send("Page.navigate", { url: destination.url }));
     reached = { how: "goto", path: destination.path };
     if (flags.click !== undefined) await network.settle(Math.min(waitMs, 3000));
   }
@@ -360,7 +361,7 @@ async function runScreen(page, flags) {
   }
   if (!reached) {
     // Nothing to reach: reload so this screen's own requests are seen.
-    await page.send("Page.reload");
+    await withoutStealingFocus(() => page.send("Page.reload"));
     reached = { how: "reload" };
   }
   await network.settle(waitMs);
@@ -456,7 +457,7 @@ async function runAuth(page, flags) {
   const waitMs = numberFlag(flags.wait, 5000, "wait");
   await page.send("Network.enable");
   const network = recordNetwork(page);
-  await page.send("Page.reload");
+  await withoutStealingFocus(() => page.send("Page.reload"));
   await network.settle(waitMs);
 
   const url = await page.evaluate("return location.href;");

package/package.json

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

package/recipes/INDEX.md

@@ -7,9 +7,14 @@ 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) |
+| [`account-overview`](account-overview/) | **L2** | One account on a card: identity, pipeline total, contacts, cases, meetings. The model does not see the card | A view-only card. **No** `awaitUserInput` | 1 production build |
+| [`upload-contacts`](upload-contacts/) | **L4** | A CSV is previewed, then written only after the user chooses Import | An action with a card that waits for the user | 1 production build |
+| [`update-meeting-notes`](update-meeting-notes/) | **L4** | A note is saved on a meeting and the new note id comes back | A write. **No card** | 1 production build |
+| [`prepare-for-a-meeting`](prepare-for-a-meeting/) | **L2** | Meeting facts are gathered in code, then a task agent writes the summary | A data action plus a task agent. **No card** | 1 production build |
+| [`opportunities-at-risk`](opportunities-at-risk/) | **L2** | Every open opportunity the app flags as at risk, on one card: count, total, and why each one is at risk. The model does not see the card | A view-only card. **No** `awaitUserInput` | 1 production build |
 
 **Not here yet — no production build proves it:** the user's own plan or
 settings drawn as a card (L1). In production that data is sent to `identify`
-(`who-is-the-user`), not rendered. Navigation (L3), writes (L4), uploads and
-task agents are also still to come.
+(`who-is-the-user`), not rendered. Navigation (L3) is also still to come.

package/recipes/account-overview/README.md

@@ -0,0 +1,26 @@
+# Account overview — L2
+
+**The user says** "show me this account". **The user sees** the account card: identity, phone, revenue, a metrics bar, and tabs for opportunities, meetings, cases, and contacts.
+
+**Proven by 1 production build.**
+
+This card is the base layout. Copy it, then replace the `/__observe_me` routes with the app's own paths and re-sample `brand.ts` if the product is not this dark theme.
+
+The card is view-only. `awaitUserInput` stays off. For a component that only shows something, the model is told that the information was displayed — nothing `execute` returned and nothing the card drew. One tab is on screen at a time; an empty tab says so. A signed-out or failed call is drawn with `renderFailure`, never as zeros. A 200 full of nulls is signed out when the account has no id and no name.
+
+In Agent Studio: an action with key `show_account_overview` and one string parameter `accountId`.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/accounts.ts` | Mock path and envelope. Find a real API that returns a similar shape |
+| `agent/accounts.ts` | Which fields a summary carries. The pipeline total is summed here |
+| `agent/views/overview.ts` | The card. Routes under `/__observe_me` are placeholders for the app's own paths. Re-sample `brand.ts` when the host product is not this dark theme |
+
+## What that build learned the hard way
+
+- **The card is the experience.** A rich object returned from `execute` does not reach the model when the action only draws.
+- **Add the money in code.** Line items summed by the model eventually come out wrong. The card shows the total the code computed.
+- **The links only work where the app listens.** "Open Account", the rows and "View All" post a message the build's single-page app routed on; other apps do not. ⚠️ Wire that message in the host app, or replace the links with a navigation route.
+- **A signed-out response often looks empty.** Zeros and nulls on a 200 are not an account with no pipeline. Check for an id and a name before drawing numbers.

package/recipes/account-overview/agent/accounts.ts

@@ -0,0 +1,159 @@
+// Totals are computed here, from the API's own numbers. The model does not add them.
+
+import type { OverviewPayload } from "./api/accounts";
+
+export type AccountSummary = {
+  id: string;
+  name: string;
+  industry: string | null;
+  website: string | null;
+  phone: string | null;
+  revenue: number | null;
+  employeeCount: number | null;
+};
+
+export type OpportunitySummary = {
+  id: string;
+  name: string;
+  value: number;
+  stage: string | null;
+  closeDate: string | null;
+};
+
+export type ContactSummary = {
+  id: string;
+  name: string;
+  email: string | null;
+  phone: string | null;
+  title: string | null;
+};
+
+export type CaseSummary = {
+  id: string;
+  title: string;
+  priority: string | null;
+  status: string | null;
+  createdAt: string | null;
+};
+
+export type MeetingSummary = {
+  id: string;
+  title: string;
+  startTime: string | null;
+  attendees: number;
+};
+
+export type AccountMetrics = {
+  openOpportunities: number;
+  pipelineValue: number;
+  contacts: number;
+  openCases: number;
+};
+
+export type AccountOverview = {
+  account: AccountSummary;
+  metrics: AccountMetrics;
+  opportunities: OpportunitySummary[];
+  contacts: ContactSummary[];
+  openCases: CaseSummary[];
+  recentMeetings: MeetingSummary[];
+};
+
+/** A 200 full of nulls is not an account. Zeros are only real once an id and a name are present. */
+export function belongsToSignedInUser(payload: OverviewPayload): boolean {
+  const id = payload.account?.id;
+  const name = payload.account?.name;
+  return typeof id === "string" && id.trim() !== "" && typeof name === "string" && name.trim() !== "";
+}
+
+export function formatMoney(value: number): string {
+  const rounded = Math.round(value);
+  const sign = rounded < 0 ? "-" : "";
+  const digits = String(Math.abs(rounded));
+  const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return `${sign}$${grouped}`;
+}
+
+/** The metrics bar shortens the pipeline: $18K, $2.4M. Row amounts stay full. */
+export function formatPipeline(value: number): string {
+  const amount = Math.abs(value);
+  const sign = value < 0 ? "-" : "";
+  if (amount >= 1_000_000) return `${sign}$${(amount / 1_000_000).toFixed(1)}M`;
+  if (amount >= 1000) return `${sign}$${(amount / 1000).toFixed(0)}K`;
+  return `${sign}$${amount.toFixed(0)}`;
+}
+
+export function formatWhen(iso: string | null, withTime = false): string | null {
+  if (!iso) return null;
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return null;
+  const day = date.toLocaleDateString();
+  if (!withTime) return day;
+  const time = date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  return `${day} at ${time}`;
+}
+
+export function titleCase(value: string): string {
+  return value
+    .split(/[_\s]+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(" ");
+}
+
+const text = (value: string | null | undefined, fallback: string) => value?.trim() || fallback;
+
+export function toOverview(payload: OverviewPayload): AccountOverview {
+  const account = payload.account ?? {};
+  const opportunities = (payload.opportunities ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    name: text(row.name, "Untitled"),
+    value: typeof row.value === "number" && Number.isFinite(row.value) ? row.value : 0,
+    stage: row.stage?.trim() || null,
+    closeDate: row.closeDate?.trim() || null,
+  }));
+  const contacts = (payload.contacts ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    name: text(row.name, "Untitled"),
+    email: row.email?.trim() || null,
+    phone: row.phone?.trim() || null,
+    title: row.title?.trim() || null,
+  }));
+  const openCases = (payload.openCases ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    title: text(row.title, "Untitled"),
+    priority: row.priority?.trim() || null,
+    status: row.status?.trim() || null,
+    createdAt: row.createdAt?.trim() || null,
+  }));
+  const recentMeetings = (payload.recentMeetings ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    title: text(row.title, "Untitled"),
+    startTime: row.startTime?.trim() || null,
+    attendees: Array.isArray(row.attendees) ? row.attendees.length : 0,
+  }));
+  const revenue = account.revenue;
+  const employees = account.employeeCount;
+
+  return {
+    account: {
+      id: String(account.id),
+      name: String(account.name).trim(),
+      industry: account.industry?.trim() || null,
+      website: account.website?.trim() || null,
+      phone: account.phone?.trim() || null,
+      revenue: typeof revenue === "number" && Number.isFinite(revenue) ? revenue : null,
+      employeeCount: typeof employees === "number" && Number.isFinite(employees) ? employees : null,
+    },
+    metrics: {
+      openOpportunities: opportunities.length,
+      pipelineValue: opportunities.reduce((sum, row) => sum + row.value, 0),
+      contacts: contacts.length,
+      openCases: openCases.length,
+    },
+    opportunities,
+    contacts,
+    openCases,
+    recentMeetings,
+  };
+}