@foldspace_npm/harness 0.1.27 → 0.1.28

package/bin/cli.mjs

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
+import { isWriteFlag } from "../src/observe-core.mjs";
 import {
   checkForUpdate,
   gateForCommand,
@@ -17,7 +18,6 @@ import {
   runAttachControl,
 } from "../src/attach-daemon.mjs";
 import {
-  CLI_COMMANDS,
   createCliRegistry,
   commandByName,
 } from "../src/cli-registry.mjs";
@@ -75,13 +75,17 @@ function printHelp(topic, json) {
     );
     return;
   }
-  const update = checkForUpdate(resolveProjectDir());
   if (json) {
-    const payload = topic ? document : { ...document, update };
+    // help --json is the first thing the manual reads, so it asks the registry
+    // now (as upgrade does) rather than trusting a 12-hour-old answer; offline,
+    // it falls back to that answer. One command's contract carries no update.
+    const payload = topic
+      ? document
+      : { ...document, update: checkForUpdate(resolveProjectDir(), { preferFresh: true }) };
     console.log(JSON.stringify(payload, null, 2));
     return;
   }
-  nagIfOutdated(update);
+  nagIfOutdated(checkForUpdate(resolveProjectDir()));
   console.log(
     topic ? renderCommandHelp(registry, topic) : renderGeneralHelp(registry),
   );
@@ -112,7 +116,18 @@ function normalizeCommandArgs(command, args) {
     const separator = token.indexOf("=");
     const name = separator > -1 ? token.slice(0, separator) : token;
     const match = options.get(name);
-    if (!match) throw new Error(`unknown option '${name}'`);
+    if (!match) {
+      // The reason matters more than the refusal: observe never writes, and
+      // always prints JSON. The write reason fits only `observe read`.
+      const verb = args.find((item) => !item.startsWith("--"));
+      throw new Error(
+        command.name === "observe" && name === "--json"
+          ? "unknown option '--json': observe always prints JSON."
+          : command.name === "observe" && verb === "read" && isWriteFlag(name)
+            ? `unknown option '${name}': observe read is GET only - it never sets a method, a header or a body.`
+            : `unknown option '${name}'`,
+      );
+    }
     const { option, canonicalName } = match;
     if (seen.has(canonicalName)) {
       throw new Error(`option '${canonicalName}' was provided twice`);
@@ -233,7 +248,9 @@ if (!command || command === "--help" || command === "-h") {
     }
   }
 } else {
-  const names = CLI_COMMANDS.map((entry) => entry.name).join(", ");
+  // The visible commands only: listing deploy here would offer a coding agent
+  // the Foldspace-internal command help hides.
+  const names = registry.commands.map((entry) => entry.name).join(", ");
   fail(
     `unknown command '${command}'. Available commands: ${names}. ` +
       `Run 'foldspace help'.`,

package/bin/inject.mjs

@@ -235,8 +235,8 @@ const chromeArgs = [
   startUrl,
 ];
 
-console.log(`\nLaunching Chrome \u2014 profile ${path.relative(root, profileDir)}, devtools on :${debugPort}.`);
-console.log("Log in to the app once — the profile persists between runs.\n");
+console.log(`\nOpening the test window - profile ${path.relative(root, profileDir)}, debugging port :${debugPort}.`);
+console.log("The human signs in there; the profile keeps what the site remembers between runs.\n");
 
 const child = spawn(chrome, chromeArgs, { detached: true, stdio: "ignore" });
 child.unref();
@@ -254,8 +254,7 @@ if (!owned.ok) {
   }
   console.error(`inject: ${ownershipErrorMessage(owned.reason, {
     port: debugPort,
-    profileDir,
-    root,
+    command: "inject",
   })}`);
   process.exit(1);
 }

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 { ownershipErrorMessage } from "../src/cdp-ownership.mjs";
 import { withoutStealingFocus } from "../src/keep-focus.mjs";
 import { withWorkingBadge } from "../src/badge-auto.mjs";
 import {
@@ -294,9 +295,7 @@ async function runPages() {
   try {
     targets = await (await fetch(`http://127.0.0.1:${state.port}/json/list`)).json();
   } catch {
-    throw new Error(
-      `The inject Chrome is not answering on :${state.port}. It was closed; run \`npm run inject\` again.`,
-    );
+    throw new Error(ownershipErrorMessage("cdp_not_ready", { port: state.port }));
   }
   const real = targets.filter(
     (target) => target.type === "page" && !String(target.url).startsWith("devtools://"),
@@ -321,7 +320,7 @@ async function runPages() {
       ? {
           hostsHint:
             `The window is on ${off.host}, which this project does not cover (hosts: ${state.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.`,
+            `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.`,
         }
       : {}),
   };
@@ -338,7 +337,7 @@ async function runMenu(page) {
     items.push(publicItem(entry));
   }
   const url = await page.evaluate("return location.href;");
-  // Links that leave this host but stay in the product (analyze., admin. ...).
+  // Links that leave this host but stay in the product (reports., admin. ...).
   // Looked for across the whole page: product tiles are often not navigation.
   const leaving = await page
     .evaluate(
@@ -768,7 +767,24 @@ async function runWaitLogin(flags) {
     }
     await sleep(1500);
   }
-  throw new ObserveExit({ ok: false, loggedIn: false, url, ...(lastError ? { lastError } : {}) }, 2);
+  // A last check that failed (window closed, or on a host this project does
+  // not cover) says what to do itself; asking the human would only loop.
+  const secs = Math.round(timeoutMs / 1000);
+  throw new ObserveExit(
+    {
+      ok: false,
+      loggedIn: false,
+      error: lastError
+        ? `No sign-in seen in ${secs} seconds. The last check said: ${lastError}`
+        : `No sign-in seen in ${secs} seconds: the test window still shows a sign-in page (${url}). ` +
+          "Ask the human whether they managed to sign in there. If they have not, run " +
+          "`npx foldspace observe wait-login` again while they do; if they say they are in, run " +
+          "`npx foldspace observe screenshot` and look at the page.",
+      url,
+      ...(lastError ? { lastError } : {}),
+    },
+    2,
+  );
 }
 
 // -------------------------------------------------------------------- main

package/bin/published.mjs

@@ -89,7 +89,7 @@ async function main() {
     finish({ ok: false, environment: environment.name, reason: ATTACH_RUNNING }, 1);
   }
 
-  page = await CdpPage.open({ projectDir });
+  page = await CdpPage.open({ projectDir, command: "published" });
   const agent = projectAgent(page.info.target, configTarget(page.info.targetName));
 
   let seen = await readPage(agent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
   },
   "files": [
     "bin",
@@ -35,5 +36,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "linkedom": "^0.18.13"
   }
 }

package/recipes/INDEX.md

@@ -6,16 +6,21 @@ 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 |
+| [`lookup-then-view`](lookup-then-view/) | **L2** | Show one account the user names - **start here**. One clear match: its card, no question. Several or none: the **pick-one** list - search, pages, one click - then the card: who it is, the money, open deals, people, open cases. The card action's **required** `accountId`, described as coming from the lookup, makes the agent call the lookup first. The app already hands over the id → `account-overview` | Two actions - an input card (`find_account`) and a view card (`show_account_overview`) - with their Agent Studio definitions word for word | 1 production build |
+| [`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 input card: the agent waits for the user's answer | 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 production builds |
+| [`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 (a third uses the default bearer token) |
+| [`account-overview`](account-overview/) | **L2** | One account on a card, when the app already hands over its id: identity, pipeline total, contacts, cases, meetings. The agent gets what the card shows. An account the user names → `lookup-then-view` | A view card: no `callback`, no `awaitUserInput` | 1 production build |
+| [`upload-contacts`](upload-contacts/) | **L4** | A CSV is previewed, then written only after the user chooses Import | An input card: the agent waits for the user's answer | 1 production build |
+| [`create-a-record`](create-a-record/) | **L4** | One record created from what the user said: an editable card, pre-filled, with dropdowns read from the app, written only after they approve. The new id comes back. **Two versions**: everything on one card (default), or one question per card and then a final review, for when an answer changes what is asked next - the README says which | An action with a card that waits for the user | 2 production builds |
 | [`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 |
-| [`several-hosts`](several-hosts/) | any | The product lives on several hosts (`www.`, `analyze.`, `admin.` ...): an action asked from the wrong host says which page it needs, and the conversation carries on after the agent moves the user there. **The resume is a registered workaround** (PLG-5962) | Page set-up, plus a guard each action calls | 1 production build |
-| [`records-list`](records-list/) | **L2** | The user's records on one card: a row each with name, two facts and a number, matched to the agent's white panel. The model does not see the card | A view-only card. **No** `awaitUserInput` | 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 |
+| [`server-rendered-forms`](server-rendered-forms/) | **L4** | The product renders its pages on the server and has no JSON API: records are read off its pages, and a record is created through the same form a person fills in - fields found by label, the app's own validation messages back as data | A write. **No card of its own** - always behind approval: the approve button of a card, or `confirmation_required: true` | 1 production build |
+| [`several-hosts`](several-hosts/) | any | The product lives on several hosts (`www.`, `app.`, `reports.`, `admin.` ...): an action asked from the wrong host says which page it needs. After the agent moves the user there, the SDK carries the user, their conversations and the agent's turn to that host when it shares the domain (PLG-5962) | A guard each action calls | 1 production build |
+| [`records-list`](records-list/) | **L2** | The user's records on one card: a row each with name, two facts and a number, matched to the agent's white panel. The agent gets what the card shows | A view card: no `callback`, no `awaitUserInput` | 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 agent gets what the card shows | A view card: no `callback`, no `awaitUserInput` | 1 production build |
+
+Levels: L0 the agent is live · L1 the user's own settings · L2 look up records · L3 navigation · L4 a write.
 
 **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`

package/recipes/README.md

@@ -13,11 +13,21 @@ of a customer session.
 ## Use one
 
 1. Read `INDEX.md` and pick the closest outcome.
-2. Copy its `agent/` files into your project's `agent/` — the layout is the
-   same, so the imports already resolve.
-3. Replace every `__observe_me` placeholder — paths, storage keys, claim names —
-   with what you **observed** in the live app, and record how you know in
-   `docs/app-profile.md`. The placeholders are deliberate: none can succeed.
+2. Copy its `agent/` files into your project's `agent/` - the layout is the
+   same, so the imports resolve. Never copy its `agent/views/brand.ts`: keep
+   the one `npx foldspace observe styles --write` wrote, and if the project
+   has none yet, run that command first. Do not overwrite any other file that
+   already exists: `agent/accounts.ts`, `agent/api/accounts.ts` and
+   `agent/api/meetings.ts` differ between recipes - add what the new recipe
+   imports to the file you have. Where the two files define the same name
+   (`AccountRecord`, `formatMoney`), keep one: one type with the fields of
+   both, one copy of the helper. The one file a recipe replaces is
+   `agent/utils.ts`, from `swap-the-login-method`.
+3. Replace every placeholder with what you **observed** in the live app - the
+   `__observe_me` paths and keys, and each default the recipe's **Adapt it**
+   table names (claim names, starters) - and record how you know in
+   `docs/app-profile.md`. The `__observe_me` ones cannot succeed; the defaults
+   can, so check each.
 4. Register actions in `agent/actions/index.ts` under the **same key** as in
    Agent Studio, then run the six gates.
 
@@ -29,10 +39,13 @@ Each recipe's README says how many production builds carry the pattern and what
 those builds learned the hard way. **What is taken is the shape** — the order of
 calls, what is returned to the agent, where the traps are. **What is not taken**
 is any customer's name, endpoint, identifier, styling or code. Contracts are the
-documented ones: `execute(params)` and
-`render(data, host, header, callback, cancel)`
+SDK's: `execute(params)` and
+`render(data, host, header, callback, cancel, readyState)`
 (<https://docs.foldspace.ai/guides/in-chat-ui/>), `foldspace.identify(context)`
 (<https://docs.foldspace.ai/start/user-context/>), and the harness runtime.
+Where the in-chat UI page says to set `awaitUserInput`, do not - the SDK waits
+when `render` uses `callback` or `cancel` (see the card bullet below). That
+page does not list `readyState`; CLAUDE.md describes it, and no recipe uses it.
 
 Error handling is **not** taken from those builds. They predate `reason`: one
 turns every failure into "unexpected error", another reports a missing session
@@ -42,5 +55,15 @@ as "no projects found". Recipes use the runtime's failure reasons instead.
 
 - `execute` returns **data and facts** — never `detail`, never instructions.
 - A missing or expired session is `signed_out`, not an empty result.
+- A **view card** shows something - an account, a list. Its
+  `render(data, host, header)` uses no `callback` and no `cancel`, and the
+  agent gets at once "Shown to the user. The user has not acted on it." with
+  exactly what `execute` returned. So `execute` returns the facts the card
+  shows: to change what the agent gets, change `execute`, not the card. An
+  **input card** asks the user: it calls `callback` (or `cancel`) on every
+  path - choosing, "none of these", closing, failing - and the agent waits
+  until it does. Never set `awaitUserInput`: an input card does not need it,
+  and on a view card in headless mode the agent waits for a callback that
+  never comes.
 - DOM is built with `textContent`, never `innerHTML` with API data, and styles
   go in `header` — `host` lives inside the component's frame.

package/recipes/account-overview/README.md

@@ -4,11 +4,11 @@
 
 **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. The palette is light because the card sits in the agent's white panel; put the agent's own primary colour in `brand.ts` (`accent`), and re-sample only font and radius from the page.
+This card is the base layout. Copy it, then replace the `/__observe_me` routes with the app's own paths. `brand.ts` here is a placeholder: keep the `agent/views/brand.ts` that `npx foldspace observe styles --write` wrote - it has every key the recipe cards read. If the project has none yet, run that command first; do not copy this one.
 
-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.
+A view card: `render` takes no `callback` and the action sets no `awaitUserInput`. As soon as the card is drawn, the agent gets "Shown to the user. The user has not acted on it." plus exactly what `execute` returned - the account, the totals and every row behind the tabs, or the failure (`success: false`, `error` and `reason`) - and it answers questions about the account from that. So `execute` returns the overview the card draws and nothing else. 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 is signed out unless the account has both an id and a name.
 
-In Agent Studio: an action with key `show_account_overview` and one string parameter `accountId`.
+In Agent Studio: an action with key `show_account_overview` and one string parameter `accountId`, described as "The account's id. Never taken from the user's words: get it from `<lookup action key>`." Replace `<lookup action key>` with the key of this agent's action that returns account ids; if the agent has none, build that action first - `find-by-name` has the shape. Its `instructions`: "Answer follow-up questions about this account from the data you receive: quote money and counts exactly as given, and never add them up yourself. Right after the card, one short sentence at most - do not repeat what it shows. On a failure, the card already says why: say so in one short sentence and stop. No emoji."
 
 ## Adapt it
 
@@ -16,11 +16,11 @@ In Agent Studio: an action with key `show_account_overview` and one string param
 |---|---|
 | `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. `brand.ts` matches the panel, not the page |
+| `agent/views/overview.ts` | The card. Routes under `/__observe_me` are placeholders for the app's own paths |
 
 ## 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.
+- **The agent answers from what `execute` returns.** A view card hands the agent everything `execute` returned, so `execute` returns the card's facts as fields, totals included. The build that proved this card ran before the SDK did that: its agent was told only that something was displayed, and could not answer a question about the account.
 - **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.
+- **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. The account's website is plain text, never a link out of the product.
 - **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/actions/show_account_overview.ts

@@ -1,5 +1,7 @@
-// View-only card. Do not set awaitUserInput: the model is told only that the
-// information was displayed, so the card itself carries every fact. A failed
+// A view card: render takes no callback and the action sets no
+// awaitUserInput. As soon as the card is drawn, the agent is told it was shown
+// and gets everything execute returned - so execute returns the overview the
+// card draws and nothing else, or the failure the card draws instead. A failed
 // or signed-out call is drawn with renderFailure, never as a row of zeros.
 
 import { belongsToSignedInUser, toOverview, type AccountOverview } from "../accounts";
@@ -9,40 +11,33 @@ import { mountAccountOverview } from "../views/overview";
 
 type ShowResult = {
   success: boolean;
-  message?: string;
   error?: string;
   reason?: FailureReason;
-  data?: AccountOverview | { accountId: string };
+  data?: AccountOverview;
 };
 
-function isOverview(data: NonNullable<ShowResult["data"]>): data is AccountOverview {
-  return "account" in data;
-}
-
 export const show_account_overview = {
   execute: async (params: { accountId?: string }): Promise<ShowResult> => {
     const accountId = typeof params?.accountId === "string" ? params.accountId.trim() : "";
     if (!accountId) {
-      return { success: false, error: "accountId was not provided.", reason: "config" };
+      return { success: false, error: "No account was given.", reason: "config" };
     }
 
     const res = await getAccountOverview(accountId);
     if (!res.ok) {
       console.warn("[show_account_overview]", res.status, res.reason, res.detail);
-      return { success: false, error: res.error, reason: res.reason, data: { accountId } };
+      return { success: false, error: res.error, reason: res.reason };
     }
 
     if (!belongsToSignedInUser(res.data)) {
-      return { success: false, error: "Not signed in.", reason: "signed_out", data: { accountId } };
+      return { success: false, error: "Not signed in.", reason: "signed_out" };
     }
 
-    // `message` never reaches the model for a view-only action; it is for the console.
-    return { success: true, message: "Displayed.", data: toOverview(res.data) };
+    return { success: true, data: toOverview(res.data) };
   },
 
   render: (result: ShowResult | undefined, host: HTMLElement, header: HTMLElement) => {
-    if (!result?.success || !result.data || !isOverview(result.data)) {
-      const accountId = result?.data && "accountId" in result.data ? result.data.accountId : "";
+    if (!result?.success || !result.data) {
       renderFailure(
         host,
         {
@@ -51,7 +46,7 @@ export const show_account_overview = {
           error: result?.error ?? "The account could not be loaded.",
           reason: result?.reason ?? "server",
         },
-        { notFound: accountId ? `No account ${accountId}.` : "No account." },
+        { notFound: "That account could not be found." },
       );
       return;
     }

package/recipes/account-overview/agent/views/brand.ts

@@ -1,26 +1,35 @@
-// The card lives in the agent's panel, which is white by default (the agent's
-// theme: backgroundColor #FFFFFF, primaryColor for accents) - so the palette
-// matches the panel, not the page. Plain hex/rgba only: the panel saves every
-// card to history as an image drawn with html2canvas, which cannot read
-// oklch()/lab()/color-mix(). Take `accent` from the agent's own primaryColor
-// (get_agent_settings); re-sample font and radius from the page if you want
-// them to match; swap for a dark set only when the panel itself is dark.
+// Placeholder with the keys of the agent/views/brand.ts that
+// `npx foldspace observe styles --write` writes. When you copy this recipe,
+// keep the project's own brand.ts; if it has none yet, run that command.
 
 export const brand = {
   surface: "#FFFFFF",
-  headerStart: "#F0F1FE",
-  border: "#E5E7EB",
+  surface2: "#F5F6FA",
   text: "#374151",
-  textStrong: "#111827",
   muted: "#6B7280",
-  faint: "#9CA3AF",
+  border: "#E5E7EB",
   accent: "#3248F2",
+  accentText: "#FFFFFF",
+  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
+  radius: "8px",
+  size: { base: "14px", small: "12px" },
+  textStrong: "#111827",
+  faint: "#9CA3AF",
+  row: "#F9FAFB",
+  tableHead: "#F3F4F6",
   accentDeep: "#2538D6",
+  accentSoft: "#EEF0FE",
+  headerStart: "#F0F1FE",
+  good: "#047857",
+  warn: "#B45309",
+  warnInk: "#FEF3C7",
+  bad: "#B91C1C",
+  primary: "#3248F2",
+  tint: "#F3F4F6",
+  disabled: "#9CA3AF",
   money: "#047857",
+  ok: "#047857",
   deals: "#2563EB",
   contacts: "#7C3AED",
   cases: "#B45309",
-  row: "#F9FAFB",
-  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
-  radius: "8px",
 } as const;

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

@@ -34,7 +34,6 @@ const CSS = `
 .fs-ov-grid{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin-top:12px}
 .fs-ov-label{font-size:10px;color:${brand.muted};text-transform:uppercase;letter-spacing:.5px;margin-bottom:2px}
 .fs-ov-value{font-size:12px;color:${brand.textStrong};font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
-.fs-ov-value a{color:${brand.accent};text-decoration:none}
 .fs-ov-metrics{display:grid;grid-template-columns:repeat(4, 1fr);gap:1px;background:${brand.border}}
 .fs-ov-metric{padding:12px;background:${brand.surface};display:flex;flex-direction:column;gap:2px;text-align:center;align-items:center}
 .fs-ov-metric b{font-size:20px;font-weight:600}
@@ -198,23 +197,20 @@ export function mountAccountOverview(host: HTMLElement, header: HTMLElement, ove
   title.append(name, open);
   head.append(title);
 
-  const size = account.employeeCount === null ? "Size unknown" : `${account.employeeCount.toLocaleString()} employees`;
-  head.append(el("div", "fs-ov-sub", `${account.industry || "Industry not specified"} • ${size}`));
+  // What is known, and nothing else: a missing value reads "Not provided" in
+  // the grid below.
+  const known = [
+    account.industry,
+    account.employeeCount === null ? null : `${account.employeeCount.toLocaleString()} employees`,
+  ].filter((fact): fact is string => Boolean(fact));
+  if (known.length) head.append(el("div", "fs-ov-sub", known.join(" • ")));
 
   const grid = el("div", "fs-ov-grid");
   grid.append(field("Phone", account.phone || "Not provided"));
-  const website = el("div", "fs-ov-value");
-  if (account.website) {
-    const site = el("a", "", account.website) as HTMLAnchorElement;
-    site.href = account.website;
-    attr(site, "target", "_blank");
-    website.append(site);
-  } else {
-    website.textContent = "Not provided";
-  }
-  grid.append(field("Website", website));
-  grid.append(field("Annual Revenue", account.revenue === null ? "Not disclosed" : formatMoney(account.revenue)));
-  grid.append(field("Employees", account.employeeCount === null ? "Not specified" : account.employeeCount.toLocaleString()));
+  // Plain text, never a link out of the product.
+  grid.append(field("Website", account.website || "Not provided"));
+  grid.append(field("Annual Revenue", account.revenue === null ? "Not provided" : formatMoney(account.revenue)));
+  grid.append(field("Employees", account.employeeCount === null ? "Not provided" : account.employeeCount.toLocaleString()));
   head.append(grid);
   card.append(head);
 
@@ -225,10 +221,10 @@ export function mountAccountOverview(host: HTMLElement, header: HTMLElement, ove
     return item;
   };
   metricsBar.append(
-    metric("Open Deals", String(metrics.openOpportunities), "fs-ov-deals"),
+    metric("Opportunities", String(metrics.openOpportunities), "fs-ov-deals"),
     metric("Pipeline", formatPipeline(metrics.pipelineValue), "fs-ov-pipeline"),
     metric("Contacts", String(metrics.contacts), "fs-ov-contacts"),
-    metric("Open Cases", String(metrics.openCases), "fs-ov-cases"),
+    metric("Cases", String(metrics.openCases), "fs-ov-cases"),
   );
   card.append(metricsBar);
 

package/recipes/bottom-bar/README.md

@@ -14,8 +14,8 @@ product's own source, one from the agent project behind a feature flag).
 | 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 |
+| `DEFAULT_STARTERS` | What to show on any other page. It replaces the agent-wide starters there |
+| `BOTTOM_BAR_SETTINGS` | The docs' settings, except two: `enabled: true` (the docs default it to `false`, and the bar then never renders) and `maxVisibleStarters: 3` (the docs default 5). Change any of them only if the human asks |
 
 Then call it from the bundle's entry point:
 
@@ -30,14 +30,17 @@ installBottomBar();
 - **`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.
+- **In embedded mode the bar needs `openEmbeddedCallback`**, or the bar does
+  not render at all. 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.
+  re-applied on navigation - this recipe wraps `pushState` / `replaceState`
+  and listens to `popstate`. It brings the bar back to full only when the
+  starters change; a navigation that keeps the same starters leaves a bar
+  that has folded to compact (after `idleTimeoutMs`) as it is.
+- **Dark mode**: the SDK's default colours do not follow a dark theme yet
+  (PLG-5891, in the backlog); 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

@@ -16,10 +16,12 @@ export const PAGE_STARTERS: Array<{ match: RegExp; starters: string[] }> = [
 ];
 
 /** Shown on any page not listed above. */
-export const DEFAULT_STARTERS: string[] = ["What can you do?", "Show my account"];
+export const DEFAULT_STARTERS: string[] = ["What can you do?", "<A question one of its actions can answer>"];
 
-// The docs' own settings, unchanged. Change nothing here unless the product
-// asks for it: every field is documented on the Bottom Bar page.
+// The docs' settings, except two: `enabled: true` (the docs default it to
+// `false`, and the bar then never renders) and `maxVisibleStarters: 3` (the
+// docs default 5). Change any of them only if the human asks: every field is
+// documented on the Bottom Bar page.
 export const BOTTOM_BAR_SETTINGS = {
   enabled: true,
   maxVisibleStarters: 3,
@@ -39,7 +41,7 @@ export function startersForPath(pathname: string): string[] {
 const INSTALLED_FLAG = "__foldspace_bottom_bar__";
 
 /**
- * Turn the bar on and keep its starters matched to the page. Call once from
+ * Set up the bar 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
@@ -57,7 +59,10 @@ export function installBottomBar(): void {
     if (!agent) return;
     let current: string[] = [];
 
-    const apply = () => {
+    // On a navigation, the bar is brought back to full only when its starters
+    // changed, so the new ones are seen. Same starters: nothing is sent, and a
+    // bar that has folded to compact stays compact.
+    const apply = (reopen: boolean) => {
       const next = startersForPath(window.location.pathname);
       if (next === current) return;
       current = next;
@@ -65,18 +70,15 @@ export function installBottomBar(): void {
         { KNOWLEDGE: next.map((title) => ({ title })), ACTION: [] },
         "KNOWLEDGE",
       );
+      if (reopen) agent.openBottomBar?.({ mode: "FULL" });
     };
 
     // One whole settings group per call, as the docs do.
     agent.setConfiguration?.({ bottomBarSettings: BOTTOM_BAR_SETTINGS });
-    apply();
+    apply(false);
 
-    // 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" });
-    };
+    // Single-page apps change the URL without a load: re-apply on navigation.
+    const onRouteChange = () => apply(true);
     window.addEventListener("popstate", onRouteChange);
     const history = window.history as any;
     for (const method of ["pushState", "replaceState"] as const) {