@foldspace_npm/harness 0.1.16 → 0.1.18

package/recipes/bottom-bar/recipe.json

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

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

@@ -0,0 +1,26 @@
+# Opportunities at risk — L2
+
+**The user says** "which deals are at risk?". **The user sees** one card: how many, their total value, the average days stalled, and a row per opportunity with the reasons the app flagged it.
+
+**Proven by 1 production build.**
+
+The app decides what "at risk" means, on the server. In that build it was: stalled 14+ days, past its close date, low probability in a late stage, critical support cases on the account, no recent meetings — each reason comes back as a short label and the card shows them as tags. The action does not re-judge anything; it draws what the API says.
+
+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 the empty state ("No opportunities are at risk.") is on the card, not in a message. The count, the total and the average are computed in code from the rows.
+
+In Agent Studio: an action with key `show_opportunities_at_risk` and no parameters.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `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 |
+
+## What that build learned the hard way
+
+- **A list has nothing to prove who it belongs to.** An account has an id and a name; a list does not. The build answered signed-out calls with a 401, which `apiFetch` already reports as `signed_out`. What the code still checks is that a 200 is the list at all — the rows array has to be there. ⚠️ If the app you are on answers a signed-out call with a 200 and an empty list, that check is not enough; find something in the response that only a signed-in user gets.
+- **Empty is an answer.** Zero at risk is drawn as a card that says so — never as a failure, and never as a hint about what to do next.
+- **Rows are not links.** The production build made every name clickable through a message its own single-page app listened for. No other app does; on any other product the click would do nothing. Open a record with a navigation route instead.
+- **The agent cannot see the card.** In the production build the render also handed the rows to the agent through `callback`, so it could answer "tell me more about the second one". That path is not in this recipe: with `awaitUserInput` off the platform does not deliver it, and a view-only action's data does not reach the model by design. If the agent needs the rows, that is a second, data-only action.

package/recipes/opportunities-at-risk/agent/actions/show_opportunities_at_risk.ts

@@ -0,0 +1,49 @@
+// View-only card. Do not set awaitUserInput: the model is told only that the
+// information was displayed, so the card carries every fact — including "nothing
+// is at risk". A failed or signed-out call is drawn with renderFailure, never as
+// a count of zero.
+
+import { getOpportunitiesAtRisk } from "../api/opportunities";
+import { isAtRiskList, toAtRisk, type AtRiskOverview } from "../opportunities";
+import { renderFailure, type FailureReason } from "../utils";
+import { mountOpportunitiesAtRisk } from "../views/at-risk";
+
+type ShowResult = {
+  success: boolean;
+  message?: string;
+  error?: string;
+  reason?: FailureReason;
+  data?: AtRiskOverview;
+};
+
+export const show_opportunities_at_risk = {
+  execute: async (): Promise<ShowResult> => {
+    const res = await getOpportunitiesAtRisk();
+    if (!res.ok) {
+      console.warn("[show_opportunities_at_risk]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason };
+    }
+    if (!isAtRiskList(res.data)) {
+      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: toAtRisk(res.data) };
+  },
+
+  render: (result: ShowResult | undefined, host: HTMLElement, header: HTMLElement) => {
+    if (!result?.success || !result.data) {
+      renderFailure(
+        host,
+        {
+          ok: false,
+          status: 0,
+          error: result?.error ?? "The opportunities could not be loaded.",
+          reason: result?.reason ?? "server",
+        },
+        { notFound: "The at-risk list could not be found." },
+      );
+      return;
+    }
+    mountOpportunitiesAtRisk(host, header, result.data);
+  },
+};

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

@@ -0,0 +1,30 @@
+// Mock API. This path is not a real product. Find an API that returns the open
+// opportunities the app itself considers at risk — each with the reasons — and
+// replace the path and the envelope with what you observed. `__observe_me`
+// cannot succeed until you do.
+//
+// The production build decided "at risk" on the server: stalled 14+ days, past
+// its close date, low probability in a late stage, critical support cases on
+// the account, no recent meetings. The card only shows what the API says.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type AtRiskRecord = {
+  id?: string | null;
+  name?: string | null;
+  account?: { id?: string | null; name?: string | null } | null;
+  value?: number | string | null;
+  stage?: string | null;
+  closeDate?: string | null;
+  daysSinceUpdate?: number | null;
+  risks?: string[] | null;
+};
+
+export type AtRiskPayload = {
+  summary?: { dealCount?: number | null; totalValue?: number | null; avgDaysStalled?: number | null } | null;
+  deals?: AtRiskRecord[] | null;
+};
+
+export async function getOpportunitiesAtRisk(): Promise<ApiResult<AtRiskPayload>> {
+  return apiFetch<AtRiskPayload>("/__observe_me/opportunities/at-risk");
+}

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

@@ -0,0 +1,75 @@
+// The count, the total and the average are computed here, from the rows the API
+// returned. The model does not add them, and the card does not trust a total the
+// server sent alongside rows that may disagree with it.
+
+import type { AtRiskPayload } from "./api/opportunities";
+
+export type AtRiskOpportunity = {
+  id: string;
+  name: string;
+  accountName: string | null;
+  value: number;
+  stage: string | null;
+  closeDate: string | null;
+  daysSinceUpdate: number | null;
+  risks: string[];
+};
+
+export type AtRiskOverview = {
+  metrics: { count: number; totalValue: number; avgDaysStalled: number };
+  opportunities: AtRiskOpportunity[];
+};
+
+/**
+ * A list has no id or name of its own to prove it belongs to a signed-in user.
+ * The production build answered a signed-out call with a 401, which `apiFetch`
+ * already maps to `signed_out`. What this guards against is a 200 that is not
+ * the list at all — a login page, an empty object — being drawn as "nothing at
+ * risk". The rows array has to be there; an empty one is a real answer.
+ */
+export function isAtRiskList(payload: AtRiskPayload): boolean {
+  return Array.isArray(payload.deals);
+}
+
+export function formatMoney(value: number): string {
+  const rounded = Math.round(value);
+  const sign = rounded < 0 ? "-" : "";
+  const digits = String(Math.abs(rounded));
+  const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return `${sign}$${grouped}`;
+}
+
+export function stageLabel(stage: string | null): string {
+  return stage ? stage.replace(/_/g, " ") : "unknown";
+}
+
+function toNumber(value: number | string | null | undefined): number {
+  const parsed = typeof value === "string" ? Number(value) : value;
+  return typeof parsed === "number" && Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function toAtRisk(payload: AtRiskPayload): AtRiskOverview {
+  const opportunities = (payload.deals ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    name: row.name?.trim() || "Untitled",
+    accountName: row.account?.name?.trim() || null,
+    value: toNumber(row.value),
+    stage: row.stage?.trim() || null,
+    closeDate: row.closeDate?.trim() || null,
+    daysSinceUpdate:
+      typeof row.daysSinceUpdate === "number" && Number.isFinite(row.daysSinceUpdate) ? row.daysSinceUpdate : null,
+    risks: (row.risks ?? []).filter((risk): risk is string => typeof risk === "string" && risk.trim() !== ""),
+  }));
+
+  const stalled = opportunities.map((row) => row.daysSinceUpdate).filter((days): days is number => days !== null);
+  const avgDaysStalled = stalled.length ? Math.round(stalled.reduce((sum, days) => sum + days, 0) / stalled.length) : 0;
+
+  return {
+    metrics: {
+      count: opportunities.length,
+      totalValue: opportunities.reduce((sum, row) => sum + row.value, 0),
+      avgDaysStalled,
+    },
+    opportunities,
+  };
+}

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

@@ -0,0 +1,115 @@
+// The at-risk card from the production build, laid out as rows instead of the
+// build's five-column table: the chat is ~400px wide and a table clipped the
+// reasons. textContent only — never innerHTML with API data. Styles go in
+// `header`.
+//
+// Rows are not links. The production build made each name clickable through a
+// message its own single-page app listened for; no other app does. To open a
+// record from here, use a navigation route (see CLAUDE.md, "Product defaults").
+
+import { formatMoney, stageLabel, type AtRiskOverview } from "../opportunities";
+import { brand } from "./brand";
+
+const CSS = `
+.fs-risk{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-risk *{box-sizing:border-box;margin:0}
+.fs-risk-head{padding:16px;background:linear-gradient(135deg, ${brand.headerStart} 0%, ${brand.surface} 100%);border-bottom:1px solid ${brand.border}}
+.fs-risk-title{font-size:16px;font-weight:600;color:${brand.textStrong};display:flex;align-items:center;gap:8px}
+.fs-risk-mark{width:18px;height:18px;color:${brand.warn};flex-shrink:0}
+.fs-risk-stats{display:grid;grid-template-columns:repeat(3, 1fr);gap:1px;background:${brand.border};border-bottom:1px solid ${brand.border}}
+.fs-risk-stat{padding:12px;background:${brand.surface};display:flex;flex-direction:column;gap:2px;text-align:center;align-items:center}
+.fs-risk-stat b{font-size:20px;font-weight:600;color:${brand.textStrong}}
+.fs-risk-stat b.is-money{color:${brand.money}}
+.fs-risk-label{font-size:10px;color:${brand.muted};text-transform:uppercase;letter-spacing:.5px}
+.fs-risk-list{display:flex;flex-direction:column;gap:10px;padding:16px}
+.fs-risk-row{background:${brand.row};border-radius:6px;padding:12px;border-left:3px solid ${brand.warn}}
+.fs-risk-line{display:flex;justify-content:space-between;align-items:baseline;gap:12px;margin-bottom:4px}
+.fs-risk-name{font-size:13px;font-weight:600;color:${brand.textStrong};overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.fs-risk-money{font-weight:600;color:${brand.money};font-size:12px;white-space:nowrap}
+.fs-risk-detail{font-size:11px;color:${brand.muted};line-height:1.3;margin-bottom:8px}
+.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-empty{text-align:center;padding:24px 16px;color:${brand.faint};font-style:italic;font-size:12px}
+`;
+
+const WARN_PATH =
+  "M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z";
+
+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 warnIcon(): SVGElement | null {
+  if (typeof document.createElementNS !== "function") return null;
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("class", "fs-risk-mark");
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("stroke", "currentColor");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  path.setAttribute("stroke-linecap", "round");
+  path.setAttribute("stroke-linejoin", "round");
+  path.setAttribute("stroke-width", "2");
+  path.setAttribute("d", WARN_PATH);
+  svg.appendChild(path);
+  return svg;
+}
+
+export function mountOpportunitiesAtRisk(host: HTMLElement, header: HTMLElement, overview: AtRiskOverview): void {
+  const style = el("style", "");
+  style.textContent = CSS;
+  header.append(style);
+
+  const { metrics, opportunities } = overview;
+  const card = el("div", "fs-risk");
+
+  const head = el("div", "fs-risk-head");
+  const title = el("div", "fs-risk-title");
+  const mark = warnIcon();
+  if (mark) title.append(mark);
+  title.append(el("span", "", "Opportunities at risk"));
+  head.append(title);
+  card.append(head);
+
+  const stats = el("div", "fs-risk-stats");
+  const stat = (label: string, value: string, money = false) => {
+    const node = el("div", "fs-risk-stat");
+    node.append(el("b", money ? "is-money" : "", value), el("div", "fs-risk-label", label));
+    return node;
+  };
+  stats.append(
+    stat("At risk", String(metrics.count)),
+    stat("Total value", formatMoney(metrics.totalValue), true),
+    stat("Avg days stalled", String(metrics.avgDaysStalled)),
+  );
+  card.append(stats);
+
+  if (opportunities.length === 0) {
+    card.append(el("div", "fs-risk-empty", "No opportunities are at risk."));
+  } else {
+    const list = el("div", "fs-risk-list");
+    for (const row of opportunities) {
+      const item = el("div", "fs-risk-row");
+      const line = el("div", "fs-risk-line");
+      line.append(el("div", "fs-risk-name", row.name), el("div", "fs-risk-money", formatMoney(row.value)));
+      item.append(line);
+      const detail = el("div", "fs-risk-detail", row.accountName ?? "No account");
+      detail.append(el("span", "fs-risk-stage", stageLabel(row.stage)));
+      item.append(detail);
+      const tags = el("div", "fs-risk-tags");
+      for (const risk of row.risks) tags.append(el("span", "fs-risk-tag", risk));
+      item.append(tags);
+      list.append(item);
+    }
+    card.append(list);
+  }
+
+  host.textContent = "";
+  host.append(card);
+}

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

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

package/recipes/opportunities-at-risk/fixtures/at-risk.empty.json

@@ -0,0 +1,4 @@
+{
+  "summary": { "dealCount": 0, "totalValue": 0, "avgDaysStalled": 0 },
+  "deals": []
+}

package/recipes/opportunities-at-risk/fixtures/at-risk.ok.json

@@ -0,0 +1,25 @@
+{
+  "summary": { "dealCount": 2, "totalValue": 30000, "avgDaysStalled": 15 },
+  "deals": [
+    {
+      "id": "opp_1",
+      "name": "Renewal",
+      "account": { "id": "acct_1", "name": "Northwind" },
+      "value": 18000,
+      "stage": "negotiation",
+      "closeDate": "2026-09-01T00:00:00.000Z",
+      "daysSinceUpdate": 21,
+      "risks": ["Stalled 21 days", "20 days past close date", "Low probability in late stage"]
+    },
+    {
+      "id": "opp_2",
+      "name": "Expansion",
+      "account": { "id": "acct_2", "name": "Contoso" },
+      "value": "12000",
+      "stage": "proposal",
+      "closeDate": null,
+      "daysSinceUpdate": 9,
+      "risks": ["1 critical case"]
+    }
+  ]
+}

package/recipes/opportunities-at-risk/fixtures/at-risk.unsigned.json

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

package/recipes/opportunities-at-risk/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Opportunities at risk",
+  "level": "L2",
+  "family": "show-a-list",
+  "kind": "action",
+  "action": "show_opportunities_at_risk",
+  "entry": "agent/actions/show_opportunities_at_risk.ts",
+  "outcome": "Every open opportunity the app flags as at risk, on one card: count, total value, and why each one is at risk",
+  "provenBy": 1
+}

package/recipes/prepare-for-a-meeting/README.md

@@ -0,0 +1,27 @@
+# Prepare for a meeting — L2
+
+**The user says** "prepare me for this meeting". **The agent gets** a summary, plus the facts the summary was written from. There is no card.
+
+**Proven by 1 production build.**
+
+One request loads the meeting, the account, the opportunities, the open cases, and past notes. Counts and the pipeline total are computed in code. Those facts are passed to `runTask` as `data`. There is no `prompt`: the task agent's instructions are created in Agent Studio. The key in this recipe, `__observe_me_summary`, is a placeholder — replace it with the key you publish. ⚠️ Check `list_task_agents` first; if the MCP has no tool to create one, the task agent is created by hand in Agent Studio and this recipe waits for it.
+
+If `runTask` is missing or throws, `summary` is null and the message says a summary was not produced. The gathered facts still come back.
+
+A meeting with no account id and no account name is `signed_out`, not a pipeline of zero.
+
+In Agent Studio: an action with key `prepare_for_meeting` and one string parameter `meetingId`. Also a task agent whose key matches `TASK_KEY`.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/meetings.ts` | Mock path and envelope. Find a real API that returns a similar shape |
+| `agent/meetings.ts` | Which facts the summary needs. Totals stay computed here |
+| `agent/actions/prepare_for_meeting.ts` | `TASK_KEY`, after the task agent exists in Agent Studio |
+
+## What that build learned the hard way
+
+- **The task agent receives facts, not instructions.** `prompt` in `data` is a second instruction channel. The wording belongs on the task agent.
+- **Keep the facts when the summary fails.** A task-agent outage is not a lost meeting.
+- **Add the pipeline in code** before it is handed to the task agent, so the summary is not asked to do the arithmetic.

package/recipes/prepare-for-a-meeting/agent/actions/prepare_for_meeting.ts

@@ -0,0 +1,70 @@
+// Gather the meeting, then ask the task agent to summarise it. `data` is facts
+// only. The task agent's instructions live in Agent Studio, under the key below.
+// If the task agent does not answer, the facts still come back and summary is null.
+
+import { getMeetingPrep } from "../api/meetings";
+import { belongsToSignedInUser, toPrep, type MeetingPrep } from "../meetings";
+import { getAgent } from "../utils";
+
+/** Replace with the task-agent key created in Agent Studio. */
+const TASK_KEY = "__observe_me_summary";
+
+type PrepResult = {
+  success: boolean;
+  summary?: string | null;
+  message?: string;
+  error?: string;
+  reason?: string;
+  data?: MeetingPrep;
+};
+
+function readSummary(taskResult: unknown): string | null {
+  if (typeof taskResult === "string") return taskResult.trim() || null;
+  if (!taskResult || typeof taskResult !== "object") return null;
+  const record = taskResult as { summary?: unknown; result?: unknown };
+  if (typeof record.summary === "string" && record.summary.trim()) return record.summary.trim();
+  const inner = record.result;
+  if (typeof inner === "string") return inner.trim() || null;
+  if (inner && typeof inner === "object" && typeof (inner as { summary?: unknown }).summary === "string") {
+    return (inner as { summary: string }).summary.trim() || null;
+  }
+  return null;
+}
+
+export const prepare_for_meeting = {
+  execute: async (params: { meetingId?: string }): Promise<PrepResult> => {
+    const meetingId = typeof params?.meetingId === "string" ? params.meetingId.trim() : "";
+    if (!meetingId) {
+      return { success: false, error: "meetingId was not provided.", reason: "config" };
+    }
+
+    const res = await getMeetingPrep(meetingId);
+    if (!res.ok) {
+      console.warn("[prepare_for_meeting]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason };
+    }
+    if (!belongsToSignedInUser(res.data)) {
+      return { success: false, error: "Not signed in.", reason: "signed_out" };
+    }
+
+    const facts = toPrep(res.data);
+    const agent = getAgent();
+    if (!agent || typeof agent.runTask !== "function") {
+      return { success: true, summary: null, message: "A summary was not produced.", data: facts };
+    }
+
+    try {
+      const taskResult = await agent.runTask({ taskKey: TASK_KEY, data: facts });
+      const summary = readSummary(taskResult);
+      return {
+        success: true,
+        summary,
+        message: summary ? "A meeting summary was produced." : "A summary was not produced.",
+        data: facts,
+      };
+    } catch (error) {
+      console.warn("[prepare_for_meeting]", error);
+      return { success: true, summary: null, message: "A summary was not produced.", data: facts };
+    }
+  },
+};

package/recipes/prepare-for-a-meeting/agent/api/meetings.ts

@@ -0,0 +1,24 @@
+// Mock API. This path is not a real product. Find an API that returns a similar
+// shape — the meeting, its account, opportunities, open cases, and past notes —
+// 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 PrepPayload = {
+  meeting?: {
+    id?: string | null;
+    title?: string | null;
+    startTime?: string | null;
+    attendees?: string[] | null;
+    notes?: { content?: string | null }[] | null;
+  } | null;
+  account?: { id?: string | null; name?: string | null; industry?: string | null } | null;
+  opportunities?: { name?: string | null; value?: number | null; stage?: string | null }[] | null;
+  openCases?: { title?: string | null; priority?: string | null }[] | null;
+  pastMeetings?: { title?: string | null; notes?: string | null }[] | null;
+};
+
+export async function getMeetingPrep(meetingId: string): Promise<ApiResult<PrepPayload>> {
+  return apiFetch<PrepPayload>(`/__observe_me/meetings/${encodeURIComponent(meetingId)}/prep`);
+}

package/recipes/prepare-for-a-meeting/agent/meetings.ts

@@ -0,0 +1,66 @@
+// Counts and the pipeline total are computed here. The task agent receives facts, not a prompt.
+
+import type { PrepPayload } from "./api/meetings";
+
+export type MeetingPrep = {
+  meeting: {
+    id: string;
+    title: string;
+    startTime: string | null;
+    attendees: string[];
+    notes: string[];
+  };
+  account: { id: string; name: string; industry: string | null };
+  metrics: { openOpportunities: number; pipelineValue: number; openCases: number };
+  opportunities: { name: string; value: number; stage: string | null }[];
+  openCases: { title: string; priority: string | null }[];
+  pastMeetings: { title: string; notes: string | null }[];
+};
+
+export function belongsToSignedInUser(payload: PrepPayload): boolean {
+  const id = payload.account?.id;
+  const name = payload.account?.name;
+  return typeof id === "string" && id.trim() !== "" && typeof name === "string" && name.trim() !== "";
+}
+
+export function toPrep(payload: PrepPayload): MeetingPrep {
+  const meeting = payload.meeting ?? {};
+  const account = payload.account ?? {};
+  const opportunities = (payload.opportunities ?? []).map((row) => ({
+    name: row.name?.trim() || "Untitled",
+    value: typeof row.value === "number" && Number.isFinite(row.value) ? row.value : 0,
+    stage: row.stage?.trim() || null,
+  }));
+  const openCases = (payload.openCases ?? []).map((row) => ({
+    title: row.title?.trim() || "Untitled",
+    priority: row.priority?.trim() || null,
+  }));
+
+  return {
+    meeting: {
+      id: meeting.id?.trim() || "",
+      title: meeting.title?.trim() || "Untitled",
+      startTime: meeting.startTime?.trim() || null,
+      attendees: (meeting.attendees ?? []).filter((name): name is string => typeof name === "string" && name.trim() !== ""),
+      notes: (meeting.notes ?? [])
+        .map((note) => note.content?.trim() || "")
+        .filter((content) => content !== ""),
+    },
+    account: {
+      id: String(account.id),
+      name: String(account.name).trim(),
+      industry: account.industry?.trim() || null,
+    },
+    metrics: {
+      openOpportunities: opportunities.length,
+      pipelineValue: opportunities.reduce((sum, row) => sum + row.value, 0),
+      openCases: openCases.length,
+    },
+    opportunities,
+    openCases,
+    pastMeetings: (payload.pastMeetings ?? []).map((row) => ({
+      title: row.title?.trim() || "Untitled",
+      notes: row.notes?.trim() || null,
+    })),
+  };
+}

package/recipes/prepare-for-a-meeting/fixtures/prep.ok.json

@@ -0,0 +1,24 @@
+{
+  "meeting": {
+    "id": "mtg_1",
+    "title": "Quarterly review",
+    "startTime": "2026-09-22T15:00:00Z",
+    "attendees": ["Dana Reyes"],
+    "notes": [{ "content": "Send the renewal numbers." }]
+  },
+  "account": {
+    "id": "acct_1",
+    "name": "Northwind",
+    "industry": "Logistics"
+  },
+  "opportunities": [
+    { "id": "opp_1", "name": "Renewal", "value": 12000, "stage": "proposal" },
+    { "id": "opp_2", "name": "Expansion", "value": 6000, "stage": "qualified" }
+  ],
+  "openCases": [
+    { "id": "case_1", "title": "Billing question", "priority": "high" }
+  ],
+  "pastMeetings": [
+    { "id": "mtg_0", "title": "Intro", "notes": "They asked about onboarding." }
+  ]
+}

package/recipes/prepare-for-a-meeting/fixtures/prep.unsigned.json

@@ -0,0 +1,9 @@
+{
+  "meeting": { "id": "mtg_1", "title": "Quarterly review" },
+  "account": { "id": null, "name": null },
+  "opportunities": [
+    { "id": "opp_1", "name": "Renewal", "value": 18000, "stage": "proposal" }
+  ],
+  "openCases": [],
+  "pastMeetings": []
+}

package/recipes/prepare-for-a-meeting/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Prepare for a meeting",
+  "level": "L2",
+  "family": "task-agent",
+  "kind": "action",
+  "action": "prepare_for_meeting",
+  "entry": "agent/actions/prepare_for_meeting.ts",
+  "outcome": "Meeting facts are gathered, then a task agent writes the summary",
+  "provenBy": 1
+}

package/recipes/update-meeting-notes/README.md

@@ -0,0 +1,22 @@
+# Update meeting notes — L4
+
+**The user says** "add this to the meeting notes". **The agent gets** the new note id. There is no card.
+
+**Proven by 1 production build.**
+
+A missing `meetingId` or empty notes fails and names the field that was absent. A missing meeting comes back as `not_found`. The saved result is the note id and the meeting id.
+
+In Agent Studio: an action with key `update_meeting_notes` and string parameters `meetingId`, `notes`, and optional `author`.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/meetings.ts` | Mock path and body. Find a real API that saves a note and returns its id |
+| `agent/actions/update_meeting_notes.ts` | The field names, if the product calls them something else |
+
+## What that build learned the hard way
+
+- **Return the id the server created.** "Saved" without an id is not something the next action can use.
+- **Name the missing field.** An empty notes string and a missing meeting are different failures.
+- **This is a live write.** Ask before publishing an edit to an action that already has users.