@foldspace_npm/harness 0.1.27 → 0.1.28

package/recipes/create-a-record/README.md

@@ -0,0 +1,97 @@
+# Create a record — L4
+
+**The user says** "create a project called Website relaunch, Dana owns it". **The user sees** a card pre-filled from what they said: name, a key made from the name, a dropdown of owners read from the app with Dana already chosen, status, description, and visibility. They can change anything. Nothing is written until they press Create project. **The agent gets** whether it was created, the new id, the written name, key, owner, status and visibility (in the step-by-step version, kind and client too) and which fields the user changed.
+
+**Proven by 2 production builds.** One product has four create actions, each with the all-at-once card. The other creates projects one step at a time, with the first answer deciding what is asked next.
+
+`execute` writes nothing. It loads what the dropdowns need and returns a proposal. `render` draws the card. Create project runs the write, then draws the outcome and calls `callback`. Cancel, a failed load, a failed or refused write, a write the app did not confirm, and a card that could not be drawn each call `callback` too, exactly once. This is an input card: because `render` uses `callback`, the agent waits until `callback` runs. Never set `awaitUserInput` - it is not needed.
+
+## Which version
+
+Two versions of the same action, with the same key. Both pre-fill from what the user said, both end on the same review card, and both write only on Create project. They differ in how the values are confirmed before that card.
+
+| Version | File | What the user sees |
+|---|---|---|
+| **All at once** (the default) | `agent/actions/create_project.ts` | One card with every field, pre-filled. They check it and press Create project |
+| **Step by step** | `variants/actions/create_project.steps.ts` | One question per card, each pre-filled with what they said: they confirm or change it and press Continue. Then a final review card with every value: all but the first answer can still be edited |
+
+**Use all at once unless one of these is true.** Decide once, when you build the action, by the record and the people who create it. Build one version per action - never both - and never let the agent choose.
+
+| Use **all at once** when | Use **step by step** when |
+|---|---|
+| Every record of this kind has the same fields | One answer decides which questions come next. A client project asks for a client and a rate; an internal one does not |
+| The user usually says the details in their request | The user usually starts with nothing ("create a new project") and fills it in as they go |
+| The card is short enough to check at a glance | A choice needs explaining before anyone can pick it: two or three options, each with a sentence on what it means |
+| Speed matters: one click to create | Each value deserves its own look: an address, a client, a rate that is costly to get wrong |
+
+**How the step-by-step version runs:**
+
+1. **The deciding question first**, as option cards with a caption each. If the user already said the answer it is pre-chosen; if not, nothing is, so they pick rather than approve a default they may not notice.
+2. **Every field that applies, one per card**, in the same order as the review card. Each starts with what the user said, so a step they already answered is one Continue.
+3. **The final review card**: every value together; all but the first answer can still be edited. Only Create project writes, and the agent gets one callback with what was written and every field changed on any step.
+
+A step is skipped only when there is nothing to ask. A field with one possible value is kept and shown on the review card. A field that does not apply to the answers so far is left out, like the client fields for an internal project, or the email question unless the project is private. Every step has Cancel, and Cancel on any step answers the agent as `cancelled`.
+
+To use the step-by-step version, copy it over `agent/actions/create_project.ts`. It imports the same `../projects` and `../views/*`, so no other file changes. In Agent Studio its parameters and its instructions differ: **In Agent Studio** gives both. Replace `KINDS`, `QUESTIONS` and `fieldsFor` with your record's deciding question, the question each field asks, and the fields each answer calls for.
+
+## In Agent Studio
+
+An action with key `create_project`. Each parameter is something the user said, as they said it; the action matches it to what the app takes, and the card shows the result for the user to confirm or change. Describe each one in Agent Studio by where it comes from:
+
+| Parameter | Where it comes from |
+|---|---|
+| `name` (required) | The project's name as the user said it |
+| `owner` | The owner's name as the user said it - the action matches it to an id; with no single match, the user picks on the card |
+| `status` | The status as the user said it ("on hold") - the action matches it to one of the app's statuses, else Planned |
+| `description` | What the user said the project is for |
+| `key` | Only a key the user gave - otherwise the action makes one from the name |
+| `private` | `true` only when the user said only members should see it |
+| `notify_members` | `true` only when the user asked for members to be emailed. It counts only for a private project |
+
+The step-by-step version adds three optional parameters - `kind` (`client` or `internal`, only when the user said which), `client` (the client's name as the user said it) and `hourly_rate` (a number, only when the user gave one) - and makes `name` optional too: its own step asks for it. Leave **`confirmation_required`** off (the default): the card is the confirmation, and turning it on asks the user twice.
+
+The action's instructions must keep two questions apart:
+
+- *"What should it be called?"* is a missing required parameter, and the agent must ask it.
+- *"Shall I go ahead?"* is the card's job, and the agent must not ask it.
+
+Something like:
+
+> Creates a project. If the user has not given a name, ask for it in one sentence and do not call this action. Once you have a name, call this action; do not ask for confirmation in chat, because the card shows every value and has its own Create project button. After it runs, use the names in the result, not the ones you passed, because the user may have edited them on the card. If status is `created`, say in one sentence that it was created, with its name. If status is `not_created`, say in one sentence that it was not created: give `error` as the reason when the result has one, and otherwise say that the card shows why. If status is `unconfirmed`, say in one sentence that it is not known whether it was created. If status is `cancelled`, acknowledge it in one short sentence. No emoji.
+
+For the step-by-step version, the card asks every question, the deciding one and the name included, so the agent asks nothing in chat. Replace the sample up to "After it runs" with:
+
+> Creates a project. Call this action as soon as the user wants a project, and pass whatever they already said, `kind` included; do not ask for anything in chat first, because the card asks each question and has its own Create project button.
+
+Keep the rest of the sample, from "After it runs" on.
+
+The result carries the new project's `id`. Pair it with a navigation route to the project's page, so the agent can offer to open what was just created.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/projects.ts` | Mock paths. Replace them with the app's own calls: the one that lists what a dropdown offers, and the create call. ⚠️ No harness command records the create call: `observe screen` reloads the page (or moves to another) as it starts listening, which clears a half-filled form, and stops once the network goes quiet, so it never sees a create the human makes by hand. You submit nothing in a signed-in account unless the human named it a test environment. Finding the create call is a platform gap: handle it as rule 9 of the manual's **Rules that are not negotiable** says. Keep the signed-in check: a value that must be there, such as the workspace id |
+| `agent/projects.ts` | The fields the create call takes (`projectFields`), and what `proposeProject` pre-fills. Each field's kind follows the API: free text becomes a text box, a limited set becomes a dropdown, a value with only one possibility becomes read-only, and a choice that decides what comes next becomes option cards |
+| `agent/actions/create_project.ts` | Rename the action to your entity. Or copy the step-by-step version over it (**Which version**) |
+| `agent/views/project-card.ts` | The review card, the write, and what goes back to the agent. The facts and labels on the outcome card |
+| `agent/views/fields.ts`, `approval.ts`, `steps.ts` | Copy them unchanged. Every create card in the project shares them; `steps.ts` is used only by the step-by-step version |
+| `agent/views/brand.ts` | A placeholder: keep the `agent/views/brand.ts` that `npx foldspace observe styles --write` wrote - it has every key the recipe cards read. If the project has none yet, run that command first; do not copy this one |
+
+## What those builds learned the hard way
+
+- **A missing required value is not a failure.** The all-at-once build drew a red "Not created: a title is required" card when the user had only said "let's create one". Nothing had been attempted. The instructions above have the agent ask for it in chat first. If the agent calls anyway, the card draws the field empty and keeps Create project disabled.
+- **The field kind follows the API, not convenience.** A dropdown for every limited set, read from the app when the app defines it.
+- **One possible value is shown, not asked.** When the app offers exactly one owner, office or workspace, the card shows it as plain text instead of a dropdown with one item. A one-option dropdown is still sent and is not counted as an edit; the workspace here is a fact on the card and is not sent.
+- **Dropdown values are ids, not names.** Two records can share a name. The label adds something distinguishing only where names repeat.
+- **Pre-select only on a single confident match.** `matchOption` tries an exact match, then a single "contains" match, then a single fuzzy hit. Anything else leaves "Choose an owner", so the user picks rather than approving a guess they may not notice. The deciding question in the step-by-step version starts with nothing chosen unless the user said which, for the same reason.
+- **Start each step with what the user said.** The step-by-step build's action took no parameters, so the user typed again the address and name they had just given.
+- **End on a review.** In the step-by-step build the last answer wrote the record and earlier answers were locked. Here the review card shows everything, and all but the first answer can still be edited.
+- **Send back what was written, and what was edited.** The user can change the name on the card, so the agent's own arguments are stale. The result carries the written values and `edited`.
+- **Return the new id.** Without it the agent cannot offer to open the record it just created.
+- **What goes back is state, never a next step.** The step-by-step build sent `directive: "The action is complete."` and messages such as "Let the user know..." with its result. Those are instructions inside a tool response (the manual's **Rules that are not negotiable**, 1), and lint rejects the `directive` key. The same holds for the runtime's failure sentences ("Your session has expired.", "Too many requests right now."): the card draws them, and the agent gets only `reason`.
+- **No status pill on the proposal.** The buttons already say what is being asked, and a coloured "Needs approval" pill made a routine create look risky.
+- **Each button resolves once.** A double click is not two records. Create project swaps the buttons for a working line.
+- **The app's refusal message stays in the console.** `detail` is the app's own message from the response body. It is never drawn on the card and never returned. A 400 or 422 is drawn as "The app did not accept these values.", and the same words go back as `error`. No other failure returns `error`.
+- ⚠️ **Closing the panel cancelled the open card** in the step-by-step build, so a half-finished create never held the conversation. That build ran the agent in its own embedded panel and wired this itself. In the standard panel, Cancel on the card is the way out (without it the agent waits until the user presses stop), so never draw a step without one.
+- ⚠️ **The all-at-once build wrote by replaying the app's own HTML form,** reading the nonce and posting the fields by label. The app had no JSON create call. Use the app's JSON create call when it has one. When it has none, post the app's own form behind Create project: load the form, take every hidden field from it, and post it back filled by label.

package/recipes/create-a-record/agent/actions/create_project.ts

@@ -0,0 +1,26 @@
+// Create one record from what the user said, behind an editable approval card.
+// This is the all-at-once version: every field on one card, pre-filled. For a create
+// where one answer decides which fields come next, see
+// variants/actions/create_project.steps.ts - the README says which to use.
+//
+// execute writes nothing: it reads what the card's dropdowns need and proposes.
+// The project is created only when the user presses Create project. An input card:
+// render uses callback, so the agent waits until callback runs. Every path calls it,
+// exactly once. Never set awaitUserInput - it is not needed.
+
+import { proposeProject, type Params, type Proposal } from "../projects";
+import { drawFailed, mountLoadFailure, mountProjectCard, type Callback } from "../views/project-card";
+
+export const create_project = {
+  // Reads and proposes. Writes nothing.
+  execute: async (params: Params = {}): Promise<Proposal> => proposeProject(params),
+
+  render: (proposal: Proposal | undefined, host: HTMLElement, header: HTMLElement, callback: Callback) => {
+    try {
+      if (!proposal?.success) return mountLoadFailure(host, proposal, callback);
+      mountProjectCard(host, header, proposal, callback);
+    } catch (error) {
+      drawFailed(host, callback, error);
+    }
+  },
+};

package/recipes/create-a-record/agent/api/projects.ts

@@ -0,0 +1,62 @@
+// Mock API. These paths are not a real product. Find the app's own call that
+// lists who can own a project (for the card's dropdown) and the call that
+// creates one, then replace the paths and the envelopes with the app's own.
+// `__observe_me` cannot succeed until you do.
+//
+// ⚠️ No harness command records the create call, and you submit nothing in a
+// signed-in account unless the human named it a test environment: finding the
+// create call is a platform gap (rule 9 of the manual's "Rules that are not
+// negotiable").
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type Owner = { id: string; name: string; email?: string | null };
+
+export type Directory = {
+  /** The one workspace the signed-in user is in: a fact on the card, not a field. */
+  workspace: { id: string; name: string };
+  owners: Owner[];
+};
+
+export type ProjectDraft = {
+  name: string;
+  key: string;
+  ownerId: string;
+  status: string;
+  description: string | null;
+  private: boolean;
+  notifyMembers: boolean;
+  /** Set by the step-by-step variant: the answer that decided which fields were asked. */
+  kind?: string;
+  clientName?: string | null;
+  hourlyRate?: number | null;
+};
+
+export type CreatedProject = { id?: string | null; name?: string | null; key?: string | null };
+
+export async function listOwners(): Promise<ApiResult<Directory>> {
+  const res = await apiFetch<{ workspace?: { id?: string; name?: string } | null; items?: Owner[] | null }>(
+    "/__observe_me/users?role=project_owner",
+  );
+  if (!res.ok) return res;
+
+  // A signed-out response can be a 200 with nothing in it. The workspace has to be
+  // there for a signed-in user; without it, this is not an empty list.
+  const workspace = res.data?.workspace;
+  if (!workspace?.id) {
+    return { ok: false, status: res.status, reason: "signed_out", error: "Not signed in." };
+  }
+  const owners = (Array.isArray(res.data?.items) ? res.data.items : []).filter((owner) => owner?.id && owner?.name);
+  return {
+    ok: true,
+    status: res.status,
+    data: { workspace: { id: workspace.id, name: workspace.name ?? "" }, owners },
+  };
+}
+
+export async function createProject(draft: ProjectDraft): Promise<ApiResult<CreatedProject>> {
+  return apiFetch<CreatedProject>("/__observe_me/projects", {
+    method: "POST",
+    body: JSON.stringify(draft),
+  });
+}

package/recipes/create-a-record/agent/projects.ts

@@ -0,0 +1,145 @@
+// What a new project is made of, between the agent's parameters, the card and
+// the create call. Replace the fields with the ones the app's create call takes.
+
+import { listOwners, type Owner, type ProjectDraft } from "./api/projects";
+import type { FailureReason } from "./utils";
+import { matchOption, type Field, type Option, type Values } from "./views/fields";
+
+/** What the agent passes: whatever the user said, all of it optional. */
+export type Params = {
+  name?: string;
+  owner?: string;
+  status?: string;
+  description?: string;
+  key?: string;
+  private?: boolean;
+  notify_members?: boolean;
+};
+
+/** A limited set the app defines: a dropdown, not a text box. */
+export const STATUSES: Option[] = [
+  { value: "planned", label: "Planned" },
+  { value: "active", label: "Active" },
+  { value: "on_hold", label: "On hold" },
+];
+
+/** The app's rule for a project key. Placeholder: 2 to 6 capital letters - use the rule the app enforces. */
+export const KEY_PATTERN = /^[A-Z]{2,6}$/;
+
+export function text(value: unknown, max: number): string {
+  return typeof value === "string" ? value.trim().slice(0, max) : "";
+}
+
+/** A key from the name: initials of several words, else the first letters of one. */
+export function toKey(name: string): string {
+  const words = name.toUpperCase().replace(/[^A-Z\s]/g, " ").split(/\s+/).filter(Boolean);
+  const initials = words.length > 1 ? words.map((word) => word[0]).join("") : (words[0] ?? "").slice(0, 4);
+  return initials.slice(0, 6).length >= 2 ? initials.slice(0, 6) : "";
+}
+
+/**
+ * Owners as dropdown options. The value is the id, never the name: two people can
+ * share a name, and the label adds the email only where they do.
+ */
+export function ownerOptions(owners: Owner[]): Option[] {
+  const counts = new Map<string, number>();
+  for (const owner of owners) counts.set(owner.name, (counts.get(owner.name) ?? 0) + 1);
+  return owners.map((owner) => ({
+    value: owner.id,
+    label: (counts.get(owner.name) ?? 0) > 1 && owner.email ? `${owner.name} (${owner.email})` : owner.name,
+  }));
+}
+
+/** The card's values as the create call's body. */
+export function draftFrom(values: Values): ProjectDraft {
+  const isPrivate = values.private === true;
+  return {
+    name: String(values.name ?? "").trim(),
+    key: String(values.key ?? "").trim(),
+    ownerId: String(values.owner ?? ""),
+    status: String(values.status ?? "planned"),
+    description: String(values.description ?? "").trim() || null,
+    private: isPrivate,
+    notifyMembers: isPrivate && values.notify_members === true,
+  };
+}
+
+/** What execute hands to render: the user's words, normalised, plus what the dropdowns need. */
+export type Proposal = {
+  success: boolean;
+  error?: string;
+  reason?: FailureReason;
+  workspace?: string;
+  /** Empty when the user has not said one yet: the card asks for it, nothing has failed. */
+  name?: string;
+  key?: string;
+  owner_options?: Option[];
+  /** The option the user's words point at, or "" when none or several do. */
+  owner_value?: string;
+  status?: string;
+  description?: string;
+  private?: boolean;
+  notify_members?: boolean;
+};
+
+/** Reads what the card's dropdowns need and normalises what the user said. Writes nothing. */
+export async function proposeProject(params: Params = {}): Promise<Proposal> {
+  const directory = await listOwners();
+  if (!directory.ok) return { success: false, error: directory.error, reason: directory.reason ?? "server" };
+
+  const name = text(params.name, 120);
+  const options = ownerOptions(directory.data.owners);
+  const key = text(params.key, 6).toUpperCase();
+  return {
+    success: true,
+    workspace: directory.data.workspace.name,
+    name,
+    key: KEY_PATTERN.test(key) ? key : toKey(name),
+    owner_options: options,
+    owner_value: matchOption(text(params.owner, 120), options),
+    status: matchOption(text(params.status, 40), STATUSES) || "planned",
+    description: text(params.description, 2000),
+    private: params.private === true,
+    notify_members: params.notify_members === true,
+  };
+}
+
+/**
+ * Every project's fields, pre-filled from the proposal. `more` goes after the owner:
+ * fields only some projects have (the step-by-step variant adds a client's).
+ */
+export function projectFields(proposal: Proposal, more: Field[] = []): Field[] {
+  return [
+    { key: "name", label: "Name", kind: "text", value: proposal.name ?? "", maxLength: 120, required: true },
+    {
+      key: "key",
+      label: "Key",
+      kind: "text",
+      value: proposal.key ?? "",
+      maxLength: 6,
+      required: true,
+      hint: "2 to 6 capital letters, e.g. WEB.",
+      check: (value) => (KEY_PATTERN.test(value) ? null : "2 to 6 capital letters only."),
+    },
+    {
+      key: "owner",
+      label: "Owner",
+      kind: "select",
+      value: proposal.owner_value ?? "",
+      options: proposal.owner_options ?? [],
+      required: true,
+      placeholder: "Choose an owner",
+    },
+    ...more,
+    { key: "status", label: "Status", kind: "select", value: proposal.status ?? "planned", options: STATUSES },
+    { key: "description", label: "Description", kind: "text", multiline: true, value: proposal.description ?? "", maxLength: 2000 },
+    { key: "private", label: "Private - only members can see it", kind: "checkbox", value: proposal.private === true },
+    {
+      key: "notify_members",
+      label: "Email members when it is created",
+      kind: "checkbox",
+      value: proposal.notify_members === true,
+      showWhen: (values) => values.private === true,
+    },
+  ];
+}

package/recipes/create-a-record/agent/views/approval.ts

@@ -0,0 +1,181 @@
+// One card for a create: first the proposal (editable fields, Cancel and the approve
+// button - "Create project" on the review, "Continue" or "Review" on a step), then the
+// outcome (created, not created, not confirmed, cancelled) drawn in the same slot.
+// The card keeps references to its own parts instead of querying the DOM: the
+// host belongs to the agent panel's frame. textContent only - never innerHTML
+// with API data. Styles go in `header`.
+
+import { brand } from "./brand";
+import { buildForm, type Field, type Values } from "./fields";
+
+export type Tone = "success" | "warning" | "danger";
+
+export type Outcome = {
+  tone: Tone;
+  /** "Project created", "Not created", "Not confirmed", "Cancelled". "" draws no pill. */
+  status: string;
+  /** "New project" */
+  kicker: string;
+  /** The record's name. */
+  headline: string;
+  /** Read-only lines: a value with only one possibility, or what was written. Empty values are skipped. */
+  facts: Array<[string, string]>;
+  /** One line under the facts - the card's or the runtime's sentence, never the app's response body (`detail`). */
+  note?: string | null;
+  footer: string;
+};
+
+const TONES: Record<Tone, { bg: string; fg: string; dot: string }> = {
+  success: { bg: "#ECFDF5", fg: "#047857", dot: "#10B981" },
+  warning: { bg: "#FFFBEB", fg: "#B45309", dot: "#F59E0B" },
+  danger: { bg: "#FEF2F2", fg: "#B91C1C", dot: "#EF4444" },
+};
+
+const CSS = `
+.fs-rec{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.4}
+.fs-rec *{box-sizing:border-box;margin:0}
+.fs-rec-top{display:flex;align-items:center;justify-content:space-between;gap:10px;padding:12px 14px 0}
+.fs-rec-pill{display:inline-flex;align-items:center;gap:6px;border-radius:999px;padding:3px 10px;font-size:12px;font-weight:600}
+.fs-rec-dot{width:7px;height:7px;border-radius:50%}
+.fs-rec-kicker{font-size:11px;color:${brand.muted};text-transform:uppercase;letter-spacing:.04em;white-space:nowrap}
+.fs-rec-head{padding:10px 14px 12px;border-bottom:1px solid ${brand.border}}
+.fs-rec-title{font-size:17px;font-weight:600;word-break:break-word}
+.fs-rec-facts{display:grid;grid-template-columns:auto 1fr;gap:6px 14px;padding:12px 14px}
+.fs-rec-k{color:${brand.muted};font-size:12px;white-space:nowrap}
+.fs-rec-v{font-size:12px;font-weight:500;overflow-wrap:anywhere}
+.fs-rec-note{margin:0 14px 12px;padding:8px 10px;border-radius:6px;font-size:12px}
+.fs-rec-actions{display:flex;justify-content:flex-end;gap:8px;padding:10px 14px;border-top:1px solid ${brand.border}}
+.fs-rec-btn{font-family:${brand.font};font-size:13px;font-weight:600;border-radius:6px;padding:7px 14px;cursor:pointer;
+  border:1px solid ${brand.border};background:${brand.surface};color:${brand.text}}
+.fs-rec-btn.primary{background:${brand.accent};border-color:${brand.accent};color:${brand.accentText}}
+.fs-rec-btn:disabled{opacity:.55;cursor:default}
+.fs-rec-working{font-size:12px;color:${brand.muted}}
+.fs-rec-foot{padding:8px 14px;background:${brand.surface2};border-top:1px solid ${brand.border};font-size:11px;color:${brand.muted}}
+`;
+
+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 addStyle(host: HTMLElement, header: HTMLElement | undefined, css: string): void {
+  const style = el("style", "");
+  style.textContent = css;
+  (header ?? host).append(style);
+}
+
+/** Draws a card. `form` and `actions` go where a proposal needs them; an outcome has neither. */
+function draw(outcome: Outcome, form?: HTMLElement, actions?: HTMLElement): { card: HTMLElement; title: HTMLElement } {
+  const tone = TONES[outcome.tone];
+  const card = el("div", "fs-rec");
+
+  const top = el("div", "fs-rec-top");
+  if (outcome.status) {
+    const pill = el("span", "fs-rec-pill");
+    pill.style.background = tone.bg;
+    pill.style.color = tone.fg;
+    const dot = el("span", "fs-rec-dot");
+    dot.style.background = tone.dot;
+    pill.append(dot, document.createTextNode(outcome.status));
+    top.append(pill);
+  }
+  top.append(el("span", "fs-rec-kicker", outcome.kicker));
+  card.append(top);
+
+  const head = el("div", "fs-rec-head");
+  const title = el("div", "fs-rec-title", outcome.headline || "Untitled");
+  head.append(title);
+  card.append(head);
+  if (form) card.append(form);
+
+  const facts = outcome.facts.filter(([, value]) => value);
+  if (facts.length) {
+    const grid = el("div", "fs-rec-facts");
+    for (const [key, value] of facts) grid.append(el("div", "fs-rec-k", key), el("div", "fs-rec-v", value));
+    card.append(grid);
+  }
+
+  if (outcome.note) {
+    const note = el("div", "fs-rec-note", outcome.note);
+    note.style.background = tone.bg;
+    note.style.color = tone.fg;
+    card.append(note);
+  }
+
+  if (actions) card.append(actions);
+  card.append(el("div", "fs-rec-foot", outcome.footer));
+  return { card, title };
+}
+
+/** The outcome drawn in the card's place: the result of the write, or of Cancel. No buttons. */
+export function mountOutcome(host: HTMLElement, header: HTMLElement | undefined, outcome: Outcome): void {
+  addStyle(host, header, CSS);
+  host.textContent = "";
+  host.append(draw(outcome).card);
+}
+
+/**
+ * A proposal the user must approve: the card, plus editable fields, Cancel and the approve
+ * button (`labels.approve`). The inputs start pre-filled, the approve button stays disabled
+ * until every shown field passes its check, and it hands over what the card shows. Facts
+ * stay read-only. Nothing is written before it is pressed. Both buttons resolve exactly once.
+ */
+export function mountApproval(
+  host: HTMLElement,
+  header: HTMLElement | undefined,
+  proposal: Outcome,
+  labels: { approve: string; working: string },
+  fields: Field[],
+  handlers: { onApprove: (values: Values, edited: string[]) => void; onCancel: () => void },
+  /** The field whose value is the card's headline, kept in step as it is edited. */
+  headlineKey?: string,
+): void {
+  addStyle(host, header, CSS);
+  const form = buildForm(fields);
+  (header ?? host).append(form.style);
+
+  // The button bar is a slot: the approve button swaps its contents for a "working" line.
+  const actions = el("div", "fs-rec-actions");
+  const cancel = el("button", "fs-rec-btn", "Cancel") as HTMLButtonElement;
+  const approve = el("button", "fs-rec-btn primary", labels.approve) as HTMLButtonElement;
+  cancel.type = "button";
+  approve.type = "button";
+  actions.append(cancel, approve);
+
+  const { card, title } = draw(proposal, form.node, actions);
+  if (headlineKey) {
+    form.onChange(() => {
+      title.textContent = String(form.values()[headlineKey] ?? "").trim() || proposal.headline || "Untitled";
+    });
+  }
+
+  let done = false;
+  const sync = () => {
+    if (!done) approve.disabled = !form.valid();
+  };
+  form.onChange(sync);
+  sync();
+
+  cancel.addEventListener("click", () => {
+    if (done) return;
+    done = true;
+    handlers.onCancel();
+  });
+  approve.addEventListener("click", () => {
+    if (done || !form.valid()) return;
+    done = true;
+    approve.disabled = true;
+    cancel.disabled = true;
+    const values = form.values();
+    const edited = form.edited();
+    actions.textContent = "";
+    actions.append(el("div", "fs-rec-working", labels.working));
+    handlers.onApprove(values, edited);
+  });
+
+  host.textContent = "";
+  host.append(card);
+}

package/recipes/create-a-record/agent/views/brand.ts

@@ -0,0 +1,35 @@
+// Placeholder with the keys of the agent/views/brand.ts that
+// `npx foldspace observe styles --write` writes. When you copy this recipe,
+// keep the project's own brand.ts; if it has none yet, run that command.
+
+export const brand = {
+  surface: "#FFFFFF",
+  surface2: "#F5F6FA",
+  text: "#374151",
+  muted: "#6B7280",
+  border: "#E5E7EB",
+  accent: "#3248F2",
+  accentText: "#FFFFFF",
+  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
+  radius: "8px",
+  size: { base: "14px", small: "12px" },
+  textStrong: "#111827",
+  faint: "#9CA3AF",
+  row: "#F9FAFB",
+  tableHead: "#F3F4F6",
+  accentDeep: "#2538D6",
+  accentSoft: "#EEF0FE",
+  headerStart: "#F0F1FE",
+  good: "#047857",
+  warn: "#B45309",
+  warnInk: "#FEF3C7",
+  bad: "#B91C1C",
+  primary: "#3248F2",
+  tint: "#F3F4F6",
+  disabled: "#9CA3AF",
+  money: "#047857",
+  ok: "#047857",
+  deals: "#3248F2",
+  contacts: "#2538D6",
+  cases: "#B45309",
+} as const;