@foldspace_npm/harness 0.1.18 → 0.1.20

package/CLAUDE.md

@@ -409,6 +409,18 @@ Each of these cost a real build.
   in the component. The action's instructions tell the model not to restate or
   recompute them: a model that adds up line items will eventually add them up
   wrong.
+- **A card matches the panel, not the page.** The card sits in the agent's
+  panel - white by default (the agent's theme: `backgroundColor #FFFFFF`,
+  `primaryColor` for accents; a `darkTheme` when the panel is dark, and the
+  panel follows the OS colour scheme, not the app's own toggle). `observe
+  styles` samples the page: a dark app gives a dark card in a white panel
+  (seen 2026-09-22). Start from the recipe palettes, put the agent's
+  `primaryColor` in `accent`, and take only font and radius from the page.
+- **Plain hex or rgba only.** The panel saves every card to the conversation
+  history as an image drawn with html2canvas, which cannot read `oklch()`,
+  `lab()` or `color-mix()`: one such value and the saved card is blank
+  (`data:,` where the card was). Lint flags them. Do not read the app's CSS
+  variables either - on modern apps they resolve to oklch.
 
 ## Layout
 
@@ -438,7 +450,7 @@ 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. Show one account on a card → `account-overview`. Upload a
+user has to choose. The user's records on one card → `records-list`. 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`.

package/bin/attach.mjs

@@ -223,9 +223,12 @@ const SDK_PATTERNS = [
 
 // 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
+//   working - a pill at the foot of the window: the agent is building in this
+//             window, please leave it alone
+//   ready   - the same pill: it is the human's turn, with the question to try
+// The pill sits bottom-left, never across the top: a bar there covered the
+// app's own header and menu (seen on a CRM, 2026-09-22). The agent's panel
+// is on the right, so bottom-left is the corner nothing else uses.
 // The state lives in sessionStorage so it survives navigation inside the
 // test window; \`foldspace badge\` writes it and the script redraws.
 const badgeSrc = `(() => {
@@ -249,7 +252,7 @@ const badgeSrc = `(() => {
     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.style.cssText = base + "top:auto;bottom:16px;left:16px;right:auto;max-width:min(560px,calc(100vw - 32px));border-radius:8px;overflow:hidden;background:#1F2A8A;padding:10px 14px 13px;font-size:13px;letter-spacing:.02em;text-align:left;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}' +
@@ -263,7 +266,7 @@ const badgeSrc = `(() => {
       // 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.style.cssText = base + "top:auto;bottom:16px;left:16px;right:auto;max-width:min(560px,calc(100vw - 32px));border-radius:8px;overflow:hidden;background:#0F9D58;padding:10px 14px;font-size:13px;letter-spacing:.02em;text-align:left;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>' +

package/package.json

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

package/recipes/INDEX.md

@@ -13,6 +13,7 @@ Read this whole table, then open the recipe closest to the outcome.
 | [`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 |
+| [`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 |
 
 **Not here yet — no production build proves it:** the user's own plan or

package/recipes/account-overview/README.md

@@ -4,7 +4,7 @@
 
 **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.
+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.
 
 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.
 
@@ -16,7 +16,7 @@ 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. Re-sample `brand.ts` when the host product is not this dark theme |
+| `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 |
 
 ## What that build learned the hard way
 

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

@@ -1,22 +1,26 @@
-// Palette sampled from the production build this recipe came from (a dark CRM).
-// Re-sample these from the host page when that product's brand differs.
-// Record where each value came from in docs/app-profile.md.
+// 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.
 
 export const brand = {
-  surface: "#0E1729",
-  headerStart: "#1a2332",
-  border: "#344256",
-  text: "#E0E0E0",
-  textStrong: "#FFFFFF",
-  muted: "#94A3B8",
-  faint: "#6B7280",
-  accent: "#60A5FA",
-  accentDeep: "#3B82F6",
-  money: "#34D399",
-  deals: "#60A5FA",
-  contacts: "#A78BFA",
-  cases: "#FBBF24",
-  row: "rgba(255, 255, 255, 0.03)",
-  font: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  surface: "#FFFFFF",
+  headerStart: "#F0F1FE",
+  border: "#E5E7EB",
+  text: "#374151",
+  textStrong: "#111827",
+  muted: "#6B7280",
+  faint: "#9CA3AF",
+  accent: "#3248F2",
+  accentDeep: "#2538D6",
+  money: "#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

@@ -1,6 +1,7 @@
 // The account card from the production build. textContent only — never innerHTML
 // with API data. Styles go in `header`. Routes under `/__observe_me` are
-// placeholders: replace them with the app's own paths.
+// placeholders: replace them with the app's own paths. Light palette: the
+// card sits in the agent's white panel (see brand.ts).
 
 import {
   formatMoney,
@@ -32,7 +33,7 @@ const CSS = `
 .fs-ov-sub{font-size:12px;color:${brand.muted};margin-bottom:12px;line-height:1.3}
 .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:#E2E8F0;font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.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}
@@ -53,15 +54,15 @@ const CSS = `
 .fs-ov-detail{font-size:11px;color:${brand.muted};line-height:1.3}
 .fs-ov-money{font-weight:600;color:${brand.money};font-size:12px}
 .fs-ov-badge{display:inline-block;padding:2px 8px;border-radius:8px;font-size:10px;font-weight:500}
-.fs-ov-stage-proposal{background:#6B21A8;color:#D8B4FE}
-.fs-ov-stage-qualified,.fs-ov-stage-qualification,.fs-ov-stage-discovery{background:#1E40AF;color:#DBEAFE}
-.fs-ov-stage-negotiation{background:#B45309;color:#FED7AA}
-.fs-ov-stage-closed-won,.fs-ov-stage-closed_won{background:#166534;color:#DCFCE7}
-.fs-ov-stage-closed-lost,.fs-ov-stage-closed_lost{background:#374151;color:#9CA3AF}
-.fs-ov-priority-critical{background:#DC2626;color:#FEE2E2}
-.fs-ov-priority-high{background:#EA580C;color:#FFEDD5}
-.fs-ov-priority-medium{background:#CA8A04;color:#FEF9C3}
-.fs-ov-priority-low{background:#2563EB;color:#DBEAFE}
+.fs-ov-stage-proposal{background:#F3E8FF;color:#6B21A8}
+.fs-ov-stage-qualified,.fs-ov-stage-qualification,.fs-ov-stage-discovery{background:#DBEAFE;color:#1E40AF}
+.fs-ov-stage-negotiation{background:#FFEDD5;color:#9A3412}
+.fs-ov-stage-closed-won,.fs-ov-stage-closed_won{background:#DCFCE7;color:#166534}
+.fs-ov-stage-closed-lost,.fs-ov-stage-closed_lost{background:#F3F4F6;color:#4B5563}
+.fs-ov-priority-critical{background:#FEE2E2;color:#B91C1C}
+.fs-ov-priority-high{background:#FFEDD5;color:#C2410C}
+.fs-ov-priority-medium{background:#FEF9C3;color:#A16207}
+.fs-ov-priority-low{background:#DBEAFE;color:#1D4ED8}
 .fs-ov-empty{text-align:center;padding:20px 16px;color:${brand.faint};font-style:italic;font-size:12px}
 .fs-ov-more{display:flex;justify-content:flex-end;margin-bottom:12px}
 .fs-ov-more a{font-size:11px;color:${brand.accent};text-decoration:none}

package/recipes/opportunities-at-risk/README.md

@@ -16,7 +16,7 @@ In Agent Studio: an action with key `show_opportunities_at_risk` and no paramete
 |---|---|
 | `agent/api/opportunities.ts` | Mock path and envelope. Find the app's own "needs attention" list — the one with reasons per row |
 | `agent/opportunities.ts` | Which fields a row carries. Totals stay computed here |
-| `agent/views/at-risk.ts` | The card. Re-sample `brand.ts` from the host page |
+| `agent/views/at-risk.ts` | The card. `brand.ts` matches the agent's white panel; put the agent's primary colour in `accent` |
 
 ## What that build learned the hard way
 

package/recipes/opportunities-at-risk/agent/views/at-risk.ts

@@ -31,7 +31,7 @@ const CSS = `
 .fs-risk-stage{display:inline-block;padding:2px 8px;border-radius:8px;font-size:10px;font-weight:500;background:${brand.headerStart};
   color:${brand.accent};text-transform:capitalize;white-space:nowrap;margin-left:6px}
 .fs-risk-tags{display:flex;flex-wrap:wrap;gap:4px}
-.fs-risk-tag{display:inline-block;padding:2px 8px;border-radius:8px;font-size:10px;font-weight:500;background:${brand.warnInk};color:${brand.warn}}
+.fs-risk-tag{display:inline-block;padding:2px 8px;border-radius:8px;font-size:10px;font-weight:500;background:${brand.warnInk};color:#92400E}
 .fs-risk-empty{text-align:center;padding:24px 16px;color:${brand.faint};font-style:italic;font-size:12px}
 `;
 

package/recipes/opportunities-at-risk/agent/views/brand.ts

@@ -1,20 +1,24 @@
-// Palette sampled from the production build this recipe came from (a dark CRM).
-// Re-sample these from the host page when that product's brand differs, and
-// record where each value came from in docs/app-profile.md.
+// 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.
 
 export const brand = {
-  surface: "#0E1729",
-  headerStart: "#1a2332",
-  border: "#344256",
-  text: "#E0E0E0",
-  textStrong: "#FFFFFF",
-  muted: "#94A3B8",
-  faint: "#6B7280",
-  accent: "#60A5FA",
-  money: "#34D399",
-  warn: "#FBBF24",
-  warnInk: "#78350F",
-  row: "rgba(255, 255, 255, 0.03)",
-  font: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  surface: "#FFFFFF",
+  headerStart: "#F0F1FE",
+  border: "#E5E7EB",
+  text: "#374151",
+  textStrong: "#111827",
+  muted: "#6B7280",
+  faint: "#9CA3AF",
+  accent: "#3248F2",
+  money: "#047857",
+  warn: "#B45309",
+  warnInk: "#FEF3C7",
+  row: "#F9FAFB",
+  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
   radius: "8px",
 } as const;

package/recipes/records-list/README.md

@@ -0,0 +1,27 @@
+# Records list — L2
+
+**The user says** "show me my accounts". **The user sees** one card: how many, the total, then a row per account — name, two facts underneath, and the money on the right.
+
+**Proven by 1 production build**, where the first version was a five-column table: at chat width (~400px) the columns collapsed and it looked wrong. Rows fixed it. This is the base layout for any list of records — contacts, projects, tickets — not just accounts.
+
+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. So "No accounts yet." is on the card, not in a message. The count and the total are computed in code from the rows.
+
+The palette matches the agent's panel (white, with the agent's primary colour for the marks), not the page: a card sampled from a dark app sits badly in a white panel. Put the agent's own `primaryColor` in `brand.ts`.
+
+In Agent Studio: an action with key `list_accounts` and no parameters.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/accounts.ts` | Mock path and envelope. Find the call the app's own list screen makes — a bare array or a wrapped one both work |
+| `agent/accounts.ts` | The two facts and the number a row carries |
+| `agent/views/list.ts` | The card. `brand.ts`: the agent's primary colour in `accent` |
+
+## What that build learned the hard way
+
+- **Rows, not a table.** Five columns in a 400px panel is a table nobody can read. Name, two facts, one number.
+- **A list has nothing to prove whose it is.** An account has an id and a name; a list does not. The build answered signed-out calls with a 401 (which `apiFetch` maps to `signed_out`); what the code still checks is that a 200 is the list at all. ⚠️ If the app answers a signed-out call with a 200 and an empty array, find something in the response only a signed-in user gets.
+- **Empty is an answer.** Zero rows draws a card that says so — never a failure.
+- **Match the panel.** The first card copied the app's dark theme (sampled with `observe styles` while the app was in dark mode) and landed in a white panel.
+- **Rows are not links.** Open a record with a navigation route.

package/recipes/records-list/agent/accounts.ts

@@ -0,0 +1,67 @@
+// Row shapes, and the total the header shows - computed here from the rows,
+// never by the model.
+
+import type { AccountsPayload } from "./api/accounts";
+
+export type AccountRow = {
+  id: string;
+  name: string;
+  industry: string | null;
+  employeeCount: number | null;
+  openOpportunities: number | null;
+  pipelineValue: number;
+};
+
+export type AccountsList = {
+  count: number;
+  pipelineValue: number;
+  accounts: AccountRow[];
+};
+
+/** The rows array, wherever the app puts it - or null when the 200 is not a list at all. */
+export function rowsOf(payload: AccountsPayload): unknown[] | null {
+  if (Array.isArray(payload)) return payload;
+  if (payload && typeof payload === "object" && Array.isArray(payload.accounts)) return payload.accounts;
+  return null;
+}
+
+export function formatMoney(value: number): string {
+  const rounded = Math.round(value);
+  const sign = rounded < 0 ? "-" : "";
+  const digits = String(Math.abs(rounded));
+  return `${sign}$${digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",")}`;
+}
+
+/** The header shortens money: $18K, $2.4M. Rows stay full. */
+export function formatShort(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)}`;
+}
+
+function toNumber(value: number | string | null | undefined): number | null {
+  const parsed = typeof value === "string" ? Number(value) : value;
+  return typeof parsed === "number" && Number.isFinite(parsed) ? parsed : null;
+}
+
+export function toList(payload: AccountsPayload): AccountsList {
+  const accounts = (rowsOf(payload) ?? []).map((raw) => {
+    const row = (raw ?? {}) as Record<string, unknown>;
+    const name = typeof row.name === "string" ? row.name.trim() : "";
+    return {
+      id: typeof row.id === "string" ? row.id.trim() : "",
+      name: name || "Untitled",
+      industry: typeof row.industry === "string" && row.industry.trim() ? row.industry.trim() : null,
+      employeeCount: toNumber(row.employeeCount as number | null),
+      openOpportunities: toNumber(row.openOpportunities as number | null),
+      pipelineValue: toNumber(row.pipelineValue as number | string | null) ?? 0,
+    };
+  });
+  return {
+    count: accounts.length,
+    pipelineValue: accounts.reduce((sum, row) => sum + row.pipelineValue, 0),
+    accounts,
+  };
+}

package/recipes/records-list/agent/actions/list_accounts.ts

@@ -0,0 +1,52 @@
+// View-only card. Do not set awaitUserInput: the model is told only that the
+// information was displayed, so the card carries every fact - including "no
+// accounts yet". A failed or signed-out call is drawn with renderFailure,
+// never as an empty list.
+
+import { getAccounts } from "../api/accounts";
+import { rowsOf, toList, type AccountsList } from "../accounts";
+import { renderFailure, type FailureReason } from "../utils";
+import { mountAccountsList } from "../views/list";
+
+type ListResult = {
+  success: boolean;
+  message?: string;
+  error?: string;
+  reason?: FailureReason;
+  data?: AccountsList;
+};
+
+export const list_accounts = {
+  execute: async (): Promise<ListResult> => {
+    const res = await getAccounts();
+    if (!res.ok) {
+      console.warn("[list_accounts]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason };
+    }
+    // A 200 that is not the list at all (a login page, an empty object) is not
+    // "no accounts". The build answered signed-out calls with a 401 - this is
+    // the second guard. A list has nothing else to prove whose it is.
+    if (rowsOf(res.data) === null) {
+      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: toList(res.data) };
+  },
+
+  render: (result: ListResult | undefined, host: HTMLElement, header: HTMLElement) => {
+    if (!result?.success || !result.data) {
+      renderFailure(
+        host,
+        {
+          ok: false,
+          status: 0,
+          error: result?.error ?? "The accounts could not be loaded.",
+          reason: result?.reason ?? "server",
+        },
+        { notFound: "The accounts list could not be found." },
+      );
+      return;
+    }
+    mountAccountsList(host, header, result.data);
+  },
+};

package/recipes/records-list/agent/api/accounts.ts

@@ -0,0 +1,21 @@
+// Mock API. This path is not a real product. Find the app's own list call -
+// the one its list screen loads - and replace the path and the envelope with
+// what you observed. `__observe_me` cannot succeed until you do.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type AccountRecord = {
+  id?: string | null;
+  name?: string | null;
+  industry?: string | null;
+  employeeCount?: number | null;
+  openOpportunities?: number | null;
+  pipelineValue?: number | string | null;
+};
+
+/** The production build answered with a bare array; other apps wrap it. */
+export type AccountsPayload = AccountRecord[] | { accounts?: AccountRecord[] | null } | null;
+
+export async function getAccounts(): Promise<ApiResult<AccountsPayload>> {
+  return apiFetch<AccountsPayload>("/__observe_me/accounts");
+}

package/recipes/records-list/agent/views/brand.ts

@@ -0,0 +1,23 @@
+// 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.
+
+export const brand = {
+  surface: "#FFFFFF",
+  headerStart: "#F0F1FE",
+  border: "#E5E7EB",
+  text: "#374151",
+  textStrong: "#111827",
+  muted: "#6B7280",
+  faint: "#9CA3AF",
+  accent: "#3248F2",
+  money: "#047857",
+  row: "#F9FAFB",
+  rowHover: "#F3F4F6",
+  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
+  radius: "8px",
+} as const;

package/recipes/records-list/agent/views/list.ts

@@ -0,0 +1,93 @@
+// A list of records at chat width (~400px): a header with the count and the
+// total, then one row per record - name, two facts, and one number on the
+// right. Not a table: five columns do not fit, and a row reads better.
+// textContent only - never innerHTML with API data. Styles go in `header`.
+//
+// Rows are not links. To open a record from here, use a navigation route
+// (CLAUDE.md, "Product defaults").
+
+import { formatMoney, formatShort, type AccountsList } from "../accounts";
+import { brand } from "./brand";
+
+const CSS = `
+.fs-list{background:${brand.surface};border-radius:${brand.radius};font-family:${brand.font};color:${brand.text};
+  border:1px solid ${brand.border};overflow:hidden;width:100%;box-sizing:border-box;font-size:13px;line-height:1.35}
+.fs-list *{box-sizing:border-box;margin:0}
+.fs-list-head{display:flex;align-items:baseline;justify-content:space-between;gap:12px;padding:12px 14px;
+  background:${brand.headerStart};border-bottom:1px solid ${brand.border}}
+.fs-list-title{font-size:15px;font-weight:600;color:${brand.textStrong}}
+.fs-list-total{font-size:12px;color:${brand.muted};white-space:nowrap}
+.fs-list-total b{color:${brand.money};font-weight:600}
+.fs-list-rows{display:flex;flex-direction:column}
+.fs-list-row{display:flex;align-items:center;gap:12px;padding:10px 14px;border-bottom:1px solid ${brand.border}}
+.fs-list-row:last-child{border-bottom:none}
+.fs-list-row:nth-child(even){background:${brand.row}}
+.fs-list-mark{width:30px;height:30px;border-radius:8px;background:${brand.accent};color:#FFFFFF;font-weight:600;font-size:11px;
+  display:flex;align-items:center;justify-content:center;flex-shrink:0}
+.fs-list-who{flex:1;min-width:0}
+.fs-list-name{font-weight:600;color:${brand.textStrong};overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.fs-list-facts{font-size:11px;color:${brand.muted};overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.fs-list-num{text-align:right;flex-shrink:0}
+.fs-list-money{font-weight:600;color:${brand.money};white-space:nowrap}
+.fs-list-sub{font-size:11px;color:${brand.faint};white-space:nowrap}
+.fs-list-empty{text-align:center;padding:24px 16px;color:${brand.faint};font-style:italic;font-size:12px}
+`;
+
+function el(tag: string, className: string, text?: string): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function initials(name: string): string {
+  const letters = name
+    .split(/\s+/)
+    .map((word) => word[0] ?? "")
+    .join("")
+    .slice(0, 2)
+    .toUpperCase();
+  return letters || "-";
+}
+
+export function mountAccountsList(host: HTMLElement, header: HTMLElement, list: AccountsList): void {
+  const style = el("style", "");
+  style.textContent = CSS;
+  header.append(style);
+
+  const card = el("div", "fs-list");
+  const head = el("div", "fs-list-head");
+  head.append(el("div", "fs-list-title", `${list.count} account${list.count === 1 ? "" : "s"}`));
+  const total = el("div", "fs-list-total", "Pipeline ");
+  total.append(el("b", "", formatShort(list.pipelineValue)));
+  head.append(total);
+  card.append(head);
+
+  if (list.accounts.length === 0) {
+    card.append(el("div", "fs-list-empty", "No accounts yet."));
+  } else {
+    const rows = el("div", "fs-list-rows");
+    for (const account of list.accounts) {
+      const row = el("div", "fs-list-row");
+      row.append(el("div", "fs-list-mark", initials(account.name)));
+      const who = el("div", "fs-list-who");
+      who.append(el("div", "fs-list-name", account.name));
+      const facts = [
+        account.industry,
+        account.employeeCount === null ? null : `${account.employeeCount.toLocaleString()} employees`,
+      ].filter((fact): fact is string => fact !== null);
+      who.append(el("div", "fs-list-facts", facts.length ? facts.join(" · ") : "No details"));
+      row.append(who);
+      const num = el("div", "fs-list-num");
+      num.append(el("div", "fs-list-money", formatMoney(account.pipelineValue)));
+      const deals = account.openOpportunities;
+      num.append(el("div", "fs-list-sub", deals === null ? "" : `${deals} open deal${deals === 1 ? "" : "s"}`));
+      row.append(num);
+      rows.append(row);
+    }
+    card.append(rows);
+  }
+
+  host.textContent = "";
+  host.append(card);
+}

package/recipes/records-list/fixtures/accounts.empty.json

@@ -0,0 +1 @@
+[]

package/recipes/records-list/fixtures/accounts.ok.json

@@ -0,0 +1,5 @@
+[
+  { "id": "acct_1", "name": "Northwind", "industry": "Logistics", "employeeCount": 500, "openOpportunities": 3, "pipelineValue": 210000 },
+  { "id": "acct_2", "name": "Contoso", "industry": "Software", "employeeCount": 1200, "openOpportunities": 1, "pipelineValue": "45000" },
+  { "id": "acct_3", "name": "Fabrikam", "industry": null, "employeeCount": null, "openOpportunities": 0, "pipelineValue": 0 }
+]

package/recipes/records-list/fixtures/accounts.unsigned.json

@@ -0,0 +1 @@
+{ "redirect": "/login" }

package/recipes/records-list/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Records list",
+  "level": "L2",
+  "family": "show-a-list",
+  "kind": "action",
+  "action": "list_accounts",
+  "entry": "agent/actions/list_accounts.ts",
+  "outcome": "The user's records on one card - a row each with name, two facts and a number - matched to the agent's panel",
+  "provenBy": 1
+}

package/recipes/upload-contacts/README.md

@@ -14,7 +14,7 @@ In Agent Studio: an action with key `upload_contacts` and no parameters. The fil
 |---|---|
 | `agent/api/contacts.ts` | Mock import path. Find a real API that accepts a list of contacts and returns created and skipped rows |
 | `agent/contacts.ts` | The columns the file actually has |
-| `agent/views/uploader.ts` | The card. `brand.ts` is the live import card; re-sample it when the host brand differs |
+| `agent/views/uploader.ts` | The card. `brand.ts` matches the agent's white panel; put the agent's primary colour in `accent` |
 
 ## What that build learned the hard way
 

package/recipes/upload-contacts/agent/views/brand.ts

@@ -1,21 +1,25 @@
-// Palette sampled from the production build this recipe came from (a dark CRM).
-// Re-sample these from the host page when that product's brand differs.
-// Record where each value came from in docs/app-profile.md.
+// 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.
 
 export const brand = {
-  surface: "#0E1729",
-  border: "#344256",
-  text: "#E0E0E0",
-  textStrong: "#FFFFFF",
-  muted: "#94A3B8",
-  faint: "#64748B",
-  accent: "#60A5FA",
-  accentDeep: "#3B82F6",
-  ok: "#34D399",
-  warn: "#FBBF24",
-  bad: "#F87171",
-  tableHead: "#1E293B",
-  disabled: "#475569",
-  font: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  surface: "#FFFFFF",
+  border: "#E5E7EB",
+  text: "#374151",
+  textStrong: "#111827",
+  muted: "#6B7280",
+  faint: "#9CA3AF",
+  accent: "#3248F2",
+  accentDeep: "#2538D6",
+  ok: "#047857",
+  warn: "#B45309",
+  bad: "#B91C1C",
+  tableHead: "#F3F4F6",
+  disabled: "#9CA3AF",
+  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
   radius: "8px",
 } as const;

package/recipes/upload-contacts/agent/views/uploader.ts

@@ -17,13 +17,13 @@ const CSS = `
 .fs-up-icon{width:20px;height:20px;color:${brand.accent};flex-shrink:0}
 .fs-up-icon.is-ok{color:${brand.ok}}
 .fs-up-zone{border:2px dashed ${brand.border};border-radius:6px;padding:24px 16px;text-align:center;cursor:pointer;
-  background:rgba(96,165,250,.05)}
-.fs-up-zone:hover,.fs-up-zone.is-drag{border-color:${brand.accent};background:rgba(96,165,250,.1)}
+  background:rgba(50,72,242,.04)}
+.fs-up-zone:hover,.fs-up-zone.is-drag{border-color:${brand.accent};background:rgba(50,72,242,.08)}
 .fs-up-zone svg{width:40px;height:40px;margin:0 auto 12px;color:${brand.accent};display:block}
 .fs-up-zone-text{font-size:13px;color:${brand.text};margin-bottom:6px}
 .fs-up-hint{font-size:11px;color:${brand.faint}}
 .fs-up-file{display:none}
-.fs-up-sum{display:flex;gap:12px;margin-bottom:12px;padding:12px;background:rgba(30,41,59,.5);border-radius:6px;
+.fs-up-sum{display:flex;gap:12px;margin-bottom:12px;padding:12px;background:${brand.tableHead};border-radius:6px;
   flex-wrap:wrap;justify-content:center}
 .fs-up-stat{display:flex;flex-direction:column;gap:2px;flex:1;min-width:80px;align-items:center;text-align:center}
 .fs-up-num{font-size:24px;font-weight:600;color:${brand.textStrong}}
@@ -34,13 +34,13 @@ const CSS = `
 .fs-up-table{width:100%;border-collapse:collapse;font-size:12px}
 .fs-up-table th{background:${brand.tableHead};padding:8px 10px;text-align:left;font-weight:600;color:${brand.muted};
   text-transform:uppercase;font-size:10px;letter-spacing:.5px;border-bottom:1px solid ${brand.border}}
-.fs-up-table td{padding:8px 10px;border-bottom:1px solid ${brand.border};color:#E2E8F0}
+.fs-up-table td{padding:8px 10px;border-bottom:1px solid ${brand.border};color:${brand.text}}
 .fs-up-ready,.fs-up-invalid{display:inline-flex;align-items:center;padding:4px 8px;border-radius:12px;font-size:11px;font-weight:500}
-.fs-up-ready{background:rgba(52,211,153,.15);color:${brand.ok}}
-.fs-up-invalid{background:rgba(248,113,113,.15);color:${brand.bad}}
+.fs-up-ready{background:#ECFDF5;color:${brand.ok}}
+.fs-up-invalid{background:#FEF2F2;color:${brand.bad}}
 .fs-up-actions{display:flex;gap:8px;justify-content:flex-end;margin-top:12px;flex-wrap:wrap}
 .fs-up-btn{padding:8px 16px;border-radius:6px;font-size:13px;font-weight:500;cursor:pointer;white-space:nowrap;font-family:inherit}
-.fs-up-primary{background:${brand.accent};color:${brand.textStrong};border:none}
+.fs-up-primary{background:${brand.accent};color:#FFFFFF;border:none}
 .fs-up-primary:hover{background:${brand.accentDeep}}
 .fs-up-primary:disabled{background:${brand.disabled};cursor:not-allowed}
 .fs-up-secondary{background:transparent;border:1px solid ${brand.border};color:${brand.text}}
@@ -52,14 +52,14 @@ const CSS = `
 .fs-up-wait-text{margin-top:16px;color:${brand.muted};font-size:14px}
 .fs-up-section{margin-top:12px}
 .fs-up-section-title{font-size:13px;font-weight:600;color:${brand.text};margin-bottom:8px}
-.fs-up-list{max-height:200px;overflow:auto;font-size:12px;line-height:1.5;padding:8px;background:rgba(30,41,59,.3);border-radius:6px}
-.fs-up-item{padding:6px 0;border-bottom:1px solid rgba(52,66,86,.5);display:flex;flex-direction:column;gap:4px}
-.fs-up-name{color:#E2E8F0;font-weight:500}
+.fs-up-list{max-height:200px;overflow:auto;font-size:12px;line-height:1.5;padding:8px;background:${brand.tableHead};border-radius:6px}
+.fs-up-item{padding:6px 0;border-bottom:1px solid ${brand.border};display:flex;flex-direction:column;gap:4px}
+.fs-up-name{color:${brand.textStrong};font-weight:500}
 .fs-up-email{color:${brand.faint};font-size:11px}
 .fs-up-reason{color:${brand.warn};font-size:10px;font-style:italic}
-.fs-up-tag{background:rgba(96,165,250,.15);color:${brand.accent};padding:3px 8px;border-radius:10px;font-size:10px;font-weight:500}
+.fs-up-tag{background:#EEF0FE;color:${brand.accent};padding:3px 8px;border-radius:10px;font-size:10px;font-weight:500}
 .fs-up-rule{height:1px;background:${brand.border};margin:12px 0}
-.fs-up-error{padding:10px;background:rgba(248,113,113,.1);border:1px solid rgba(248,113,113,.3);border-radius:6px;
+.fs-up-error{padding:10px;background:#FEF2F2;border:1px solid #FECACA;border-radius:6px;
   color:${brand.bad};font-size:12px;line-height:1.4}
 `;
 

package/src/lint/rules.mjs

@@ -450,15 +450,43 @@ export function ruleRegistryIntegrity({ indexFile, indexSource, actionFiles, pro
   }
 }
 
+// The panel saves every rendered card to the conversation history as an image
+// drawn with html2canvas, which cannot parse modern colour functions: one such
+// value and the saved card is blank ("data:," where the card was - seen on a
+// CRM, 2026-09-22). Hex and rgba survive.
+const UNSNAPSHOTTABLE_COLOR = /\b(oklch|oklab|lch|lab|color-mix|light-dark)\s*\(/i;
+
+export function ruleNoUnsnapshottableColor(sourceFile, relative, findings) {
+  forEachStringLiteral(sourceFile, (node) => {
+    if (ts.isImportDeclaration(node.parent) || ts.isExportDeclaration(node.parent)) return;
+    const text = node.getText(sourceFile);
+    const match = UNSNAPSHOTTABLE_COLOR.exec(text);
+    if (!match) return;
+    findings.push(
+      finding({
+        rule: "no-unsnapshottable-color",
+        severity: "error",
+        sourceFile,
+        node,
+        file: relative,
+        message: `${match[1]}() in a card: the panel saves cards to history as an image drawn with html2canvas, which cannot read it - the saved card comes out blank.`,
+        fix: "Use plain hex or rgba. Do not read the app's CSS variables either: on modern apps they resolve to oklch.",
+      }),
+    );
+  });
+}
+
 export function lintActionFile(filePath, relative, findings) {
   if (shouldSkipActionFile(filePath)) return;
   const sourceFile = parseFile(filePath);
   ruleNoStaticAgentPrompt(sourceFile, relative, findings);
   ruleNoRunTaskPrompt(sourceFile, relative, findings);
   ruleNoEmoji(sourceFile, relative, findings);
+  ruleNoUnsnapshottableColor(sourceFile, relative, findings);
 }
 
 export function lintViewsFile(filePath, relative, findings) {
   const sourceFile = parseFile(filePath);
   ruleNoEmoji(sourceFile, relative, findings, { wholeFile: true });
+  ruleNoUnsnapshottableColor(sourceFile, relative, findings);
 }