@foldspace_npm/harness 0.1.16 → 0.1.18

package/recipes/account-overview/agent/actions/show_account_overview.ts

@@ -0,0 +1,61 @@
+// 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
+// or signed-out call is drawn with renderFailure, never as a row of zeros.
+
+import { belongsToSignedInUser, toOverview, type AccountOverview } from "../accounts";
+import { getAccountOverview } from "../api/accounts";
+import { renderFailure, type FailureReason } from "../utils";
+import { mountAccountOverview } from "../views/overview";
+
+type ShowResult = {
+  success: boolean;
+  message?: string;
+  error?: string;
+  reason?: FailureReason;
+  data?: AccountOverview | { accountId: string };
+};
+
+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" };
+    }
+
+    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 } };
+    }
+
+    if (!belongsToSignedInUser(res.data)) {
+      return { success: false, error: "Not signed in.", reason: "signed_out", data: { accountId } };
+    }
+
+    // `message` never reaches the model for a view-only action; it is for the console.
+    return { success: true, message: "Displayed.", 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 : "";
+      renderFailure(
+        host,
+        {
+          ok: false,
+          status: 0,
+          error: result?.error ?? "The account could not be loaded.",
+          reason: result?.reason ?? "server",
+        },
+        { notFound: accountId ? `No account ${accountId}.` : "No account." },
+      );
+      return;
+    }
+
+    mountAccountOverview(host, header, result.data);
+  },
+};

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

@@ -0,0 +1,59 @@
+// Mock API. These paths are not a real product. Find an API that returns a
+// similar shape — one account, its opportunities, contacts, open cases, and
+// recent meetings — 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;
+  website?: string | null;
+  phone?: string | null;
+  revenue?: number | null;
+  employeeCount?: number | null;
+};
+
+export type OpportunityRecord = {
+  id?: string | null;
+  name?: string | null;
+  value?: number | null;
+  stage?: string | null;
+  closeDate?: string | null;
+};
+
+export type ContactRecord = {
+  id?: string | null;
+  name?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  title?: string | null;
+};
+
+export type CaseRecord = {
+  id?: string | null;
+  title?: string | null;
+  priority?: string | null;
+  status?: string | null;
+  createdAt?: string | null;
+};
+
+export type MeetingRecord = {
+  id?: string | null;
+  title?: string | null;
+  startTime?: string | null;
+  attendees?: unknown[] | null;
+};
+
+export type OverviewPayload = {
+  account?: AccountRecord | null;
+  opportunities?: OpportunityRecord[] | null;
+  contacts?: ContactRecord[] | null;
+  openCases?: CaseRecord[] | null;
+  recentMeetings?: MeetingRecord[] | null;
+};
+
+export async function getAccountOverview(accountId: string): Promise<ApiResult<OverviewPayload>> {
+  return apiFetch<OverviewPayload>(`/__observe_me/accounts/${encodeURIComponent(accountId)}/overview`);
+}

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

@@ -0,0 +1,22 @@
+// 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.
+
+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',
+  radius: "8px",
+} as const;

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

@@ -0,0 +1,303 @@
+// 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.
+
+import {
+  formatMoney,
+  formatPipeline,
+  formatWhen,
+  titleCase,
+  type AccountOverview,
+  type CaseSummary,
+  type ContactSummary,
+  type MeetingSummary,
+  type OpportunitySummary,
+} from "../accounts";
+import { brand } from "./brand";
+
+const SHOWN = 5;
+
+const CSS = `
+.fs-ov{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}
+.fs-ov *{box-sizing:border-box}
+.fs-ov-head{padding:16px;background:linear-gradient(135deg, ${brand.headerStart} 0%, ${brand.surface} 100%);border-bottom:1px solid ${brand.border}}
+.fs-ov-title{font-size:18px;font-weight:600;color:${brand.textStrong};margin-bottom:6px;display:flex;align-items:center;justify-content:space-between}
+.fs-ov-name{display:flex;align-items:center}
+.fs-ov-mark{width:28px;height:28px;background:linear-gradient(135deg, ${brand.accent} 0%, ${brand.accentDeep} 100%);border-radius:6px;
+  display:flex;align-items:center;justify-content:center;margin-right:10px;color:#fff;font-weight:600;font-size:11px;flex-shrink:0}
+.fs-ov-open{background:${brand.accent};color:#fff;border:none;padding:6px 12px;border-radius:4px;font-size:11px;font-weight:500;
+  cursor:pointer;text-decoration:none;display:inline-flex;align-items:center;gap:4px}
+.fs-ov-open svg{width:12px;height:12px}
+.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 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}
+.fs-ov-deals{color:${brand.deals}}
+.fs-ov-pipeline{color:${brand.money}}
+.fs-ov-contacts{color:${brand.contacts}}
+.fs-ov-cases{color:${brand.cases}}
+.fs-ov-tabs{display:grid;grid-template-columns:1fr 1fr;border-bottom:1px solid ${brand.border}}
+.fs-ov-tab{padding:12px 16px;background:transparent;border:none;color:${brand.muted};font-size:13px;font-weight:500;cursor:pointer;
+  border-bottom:2px solid transparent;text-align:center}
+.fs-ov-tab.is-active{color:${brand.accent};border-bottom-color:${brand.accent}}
+.fs-ov-panel{padding:16px}
+.fs-ov-list{display:flex;flex-direction:column;gap:10px}
+.fs-ov-row{background:${brand.row};border-radius:6px;padding:12px;border-left:3px solid ${brand.accent};color:inherit;display:block;text-decoration:none}
+.fs-ov-row-title{font-size:13px;font-weight:600;color:${brand.textStrong};margin-bottom:4px}
+.fs-ov-row-meta{display:flex;justify-content:space-between;align-items:center;margin-bottom:4px}
+.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-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}
+`;
+
+type Tab = "opportunities" | "meetings" | "cases" | "contacts";
+
+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 attr(node: HTMLElement, name: string, value: string): void {
+  if (typeof node.setAttribute === "function") node.setAttribute(name, value);
+}
+
+// The production build's single-page app listened for this message and routed
+// on it. No other app does — on any other product these links do nothing.
+// Open a record with a navigation route instead (CLAUDE.md, "Product defaults").
+function go(path: string): void {
+  const top = window.top;
+  if (top && typeof top.postMessage === "function") {
+    top.postMessage({ type: "NAVIGATE", path }, "*");
+  }
+}
+
+function link(className: string, path: string, text?: string): HTMLAnchorElement {
+  const node = el("a", className, text) as HTMLAnchorElement;
+  node.href = path;
+  node.addEventListener("click", (event) => {
+    if (typeof event.preventDefault === "function") event.preventDefault();
+    go(path);
+  });
+  return node;
+}
+
+function initials(name: string): string {
+  const letters = name
+    .split(" ")
+    .map((word) => word[0])
+    .join("")
+    .slice(0, 2)
+    .toUpperCase();
+  return letters || "AC";
+}
+
+function openIcon(): SVGElement | null {
+  if (typeof document.createElementNS !== "function") return null;
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  attr(svg as unknown as HTMLElement, "viewBox", "0 0 24 24");
+  const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  attr(path as unknown as HTMLElement, "fill", "currentColor");
+  attr(
+    path as unknown as HTMLElement,
+    "d",
+    "M14,3V5H17.59L7.76,14.83L9.17,16.24L19,6.41V10H21V3M19,19H5V5H12V3H5C3.89,3 3,3.9 3,5V19A2,2 0 0,0 5,21H19A2,2 0 0,0 21,19V12H19V19Z",
+  );
+  svg.appendChild(path);
+  return svg;
+}
+
+function field(label: string, value: HTMLElement | string): HTMLElement {
+  const item = el("div", "fs-ov-field");
+  item.append(el("div", "fs-ov-label", label));
+  item.append(typeof value === "string" ? el("div", "fs-ov-value", value) : value);
+  return item;
+}
+
+function opportunityRow(row: OpportunitySummary): HTMLElement {
+  const node = link("fs-ov-row", `/__observe_me/opportunities/${row.id}`);
+  node.append(el("div", "fs-ov-row-title", row.name));
+  const meta = el("div", "fs-ov-row-meta");
+  meta.append(el("span", "fs-ov-money", formatMoney(row.value)));
+  node.append(meta);
+  const stage = row.stage ? row.stage.replaceAll("_", " ") : "unknown";
+  const close = formatWhen(row.closeDate);
+  node.append(el("div", "fs-ov-detail", close ? `Stage: ${stage} • Close: ${close}` : `Stage: ${stage}`));
+  return node;
+}
+
+function contactRow(row: ContactSummary): HTMLElement {
+  const node = link("fs-ov-row", `/__observe_me/contacts/${row.id}`);
+  node.append(el("div", "fs-ov-row-title", row.name));
+  node.append(el("div", "fs-ov-detail", row.title || "No title"));
+  const phone = row.phone ? ` • ${row.phone}` : "";
+  node.append(el("div", "fs-ov-detail", `${row.email ?? ""}${phone}`.trim()));
+  return node;
+}
+
+function caseRow(row: CaseSummary): HTMLElement {
+  const node = link("fs-ov-row", `/__observe_me/cases/${row.id}`);
+  node.append(el("div", "fs-ov-row-title", row.title));
+  if (row.priority) {
+    const meta = el("div", "fs-ov-row-meta");
+    const badge = el("span", `fs-ov-badge fs-ov-priority-${row.priority.toLowerCase()}`, titleCase(row.priority));
+    meta.append(badge);
+    node.append(meta);
+  }
+  const created = formatWhen(row.createdAt) ?? "Unknown";
+  const status = row.status ? titleCase(row.status) : "Open";
+  node.append(el("div", "fs-ov-detail", `Created: ${created} • ${status}`));
+  return node;
+}
+
+function meetingRow(row: MeetingSummary): HTMLElement {
+  const node = link("fs-ov-row", `/__observe_me/meetings/${row.id}`);
+  node.append(el("div", "fs-ov-row-title", row.title));
+  const when = formatWhen(row.startTime, true);
+  if (when) node.append(el("div", "fs-ov-detail", when));
+  const count = row.attendees;
+  node.append(el("div", "fs-ov-detail", `${count} attendee${count === 1 ? "" : "s"}`));
+  return node;
+}
+
+export function mountAccountOverview(host: HTMLElement, header: HTMLElement, overview: AccountOverview): void {
+  const style = el("style", "");
+  style.textContent = CSS;
+  header.append(style);
+
+  const { account, metrics } = overview;
+  const card = el("div", "fs-ov");
+
+  const head = el("div", "fs-ov-head");
+  const title = el("div", "fs-ov-title");
+  const name = el("div", "fs-ov-name");
+  name.append(el("div", "fs-ov-mark", initials(account.name)), el("span", "fs-ov-account", account.name));
+  const open = link("fs-ov-open", `/__observe_me/accounts/${account.id}`);
+  const icon = openIcon();
+  if (icon) open.append(icon);
+  open.append(el("span", "fs-ov-open-label", "Open Account"));
+  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}`));
+
+  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()));
+  head.append(grid);
+  card.append(head);
+
+  const metricsBar = el("div", "fs-ov-metrics");
+  const metric = (label: string, value: string, tone: string) => {
+    const item = el("div", "fs-ov-metric");
+    item.append(el("div", "fs-ov-label", label), el("b", tone, value));
+    return item;
+  };
+  metricsBar.append(
+    metric("Open Deals", 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"),
+  );
+  card.append(metricsBar);
+
+  const tabs: { id: Tab; label: string; count: number; empty: string; rows: HTMLElement[] }[] = [
+    {
+      id: "opportunities",
+      label: "Opportunities",
+      count: overview.opportunities.length,
+      empty: "No open opportunities",
+      rows: overview.opportunities.slice(0, SHOWN).map(opportunityRow),
+    },
+    {
+      id: "meetings",
+      label: "Meetings",
+      count: overview.recentMeetings.length,
+      empty: "No recent meetings",
+      rows: overview.recentMeetings.slice(0, SHOWN).map(meetingRow),
+    },
+    {
+      id: "cases",
+      label: "Cases",
+      count: overview.openCases.length,
+      empty: "No open cases",
+      rows: overview.openCases.slice(0, SHOWN).map(caseRow),
+    },
+    {
+      id: "contacts",
+      label: "Contacts",
+      count: overview.contacts.length,
+      empty: "No contacts",
+      rows: overview.contacts.slice(0, SHOWN).map(contactRow),
+    },
+  ];
+
+  const tabBar = el("div", "fs-ov-tabs");
+  const panel = el("div", "fs-ov-panel");
+  const buttons = new Map<Tab, HTMLButtonElement>();
+
+  const show = (id: Tab) => {
+    const tab = tabs.find((item) => item.id === id);
+    if (!tab) return;
+    for (const item of tabs) {
+      const button = buttons.get(item.id);
+      if (button) button.className = item.id === id ? "fs-ov-tab is-active" : "fs-ov-tab";
+    }
+    panel.textContent = "";
+    if (tab.count > SHOWN) {
+      const more = el("div", "fs-ov-more");
+      more.append(link("", `/__observe_me/${tab.id}?accountId=${account.id}`, "View All"));
+      panel.append(more);
+    }
+    if (tab.rows.length === 0) {
+      panel.append(el("div", "fs-ov-empty", tab.empty));
+      return;
+    }
+    const list = el("div", "fs-ov-list");
+    for (const row of tab.rows) list.append(row);
+    panel.append(list);
+  };
+
+  for (const tab of tabs) {
+    const button = el("button", "fs-ov-tab", `${tab.label} (${tab.count})`) as HTMLButtonElement;
+    button.type = "button";
+    button.addEventListener("click", () => show(tab.id));
+    buttons.set(tab.id, button);
+    tabBar.append(button);
+  }
+  card.append(tabBar, panel);
+  show("opportunities");
+
+  host.textContent = "";
+  host.append(card);
+}

package/recipes/account-overview/fixtures/overview.empty.json

@@ -0,0 +1,12 @@
+{
+  "account": {
+    "id": "acct_1",
+    "name": "Northwind",
+    "industry": "Logistics",
+    "website": null
+  },
+  "opportunities": [],
+  "contacts": [],
+  "openCases": [],
+  "recentMeetings": []
+}

package/recipes/account-overview/fixtures/overview.ok.json

@@ -0,0 +1,30 @@
+{
+  "account": {
+    "id": "acct_1",
+    "name": "Northwind",
+    "industry": "Logistics",
+    "website": "https://northwind.example",
+    "phone": "(415) 555-0148",
+    "revenue": 2400000,
+    "employeeCount": 180
+  },
+  "opportunities": [
+    { "id": "opp_1", "name": "Renewal", "value": 12000, "stage": "proposal", "closeDate": "2026-10-15" },
+    { "id": "opp_2", "name": "Expansion", "value": 6000, "stage": "qualified", "closeDate": "2026-11-02" }
+  ],
+  "contacts": [
+    { "id": "ct_1", "name": "Dana Reyes", "email": "dana@example.com", "phone": "(415) 555-0199", "title": "Buyer" },
+    { "id": "ct_2", "name": "Sam Lee", "email": "sam@example.com", "phone": "", "title": "Ops" }
+  ],
+  "openCases": [
+    { "id": "case_1", "title": "Billing question", "priority": "high", "status": "open", "createdAt": "2026-09-12" }
+  ],
+  "recentMeetings": [
+    {
+      "id": "mtg_1",
+      "title": "Quarterly review",
+      "startTime": "2026-09-22T15:00:00Z",
+      "attendees": ["Dana Reyes", "Sam Lee", "Pat"]
+    }
+  ]
+}

package/recipes/account-overview/fixtures/overview.unsigned.json

@@ -0,0 +1,9 @@
+{
+  "account": { "id": null, "name": null },
+  "opportunities": [
+    { "id": "opp_1", "name": "Renewal", "value": 18000, "stage": "proposal" }
+  ],
+  "contacts": [],
+  "openCases": [],
+  "recentMeetings": []
+}

package/recipes/account-overview/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Account overview",
+  "level": "L2",
+  "family": "show-a-record",
+  "kind": "action",
+  "action": "show_account_overview",
+  "entry": "agent/actions/show_account_overview.ts",
+  "outcome": "One account drawn as a card: identity, pipeline, contacts, cases, meetings",
+  "provenBy": 1
+}

package/recipes/bottom-bar/README.md

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

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

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

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

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