@synap-core/workspace-templates 0.12.0 → 0.23.0

package/src/fal-generate-image.test.ts

@@ -0,0 +1,200 @@
+/**
+ * fal.ai `fal_generate_image` (capability `fal-ai`): two defects reproduced on
+ * the founder's pod, 2026-10-27, through `synap_run_capability`.
+ *
+ *  1. `numImages: "3"` returned `imageCount: 3` but ONE `imageUrl` — the other
+ *     two images were generated, billed and dropped.
+ *  2. `model: "fal-ai/nano-banana/edit"` with reference images got fal's 422:
+ *     the code built a fixed `{ prompt, image_size, num_images }` body, so the
+ *     model's required `image_urls` never reached fal.
+ *
+ * SEAM: the verb's REAL `code` body, run the way the pod's executor wraps it
+ * (`async (args, context) => { <code> }` with `callProvider` / `propose` in
+ * scope), against a fal response shaped like fal's documented output. The
+ * request body asserted is exactly what `callProvider` would send to fal.run.
+ *
+ * NOT covered: fal's live behaviour per model (payloads are hand-written), the
+ * pod's propose-moment arg check (backend `validate-verb-parameters`) and the
+ * IS isolate (Node's AsyncFunction is used).
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const manifest = JSON.parse(readFileSync(join(HERE, "../capabilities/fal-ai.capability.json"), "utf8"));
+type Skill = { name: string; code?: string; parameters?: Record<string, string> };
+const verb = (manifest.spec.skills as Skill[]).find((s) => s.name === "fal_generate_image")!;
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as new (
+  ...args: string[]
+) => (...a: unknown[]) => Promise<unknown>;
+const body = new AsyncFunction("args", "context", "callProvider", "propose", verb.code!);
+
+type Call = { tool: string; method: string; path: string; input: Record<string, unknown> };
+async function run(args: Record<string, unknown>, images = 1) {
+  const calls: Call[] = [];
+  const writes: Array<{ title: string; properties: Record<string, unknown> }> = [];
+  const callProvider = async (tool: string, method: string, path: string, input: Record<string, unknown>) => {
+    calls.push({ tool, method, path, input });
+    return {
+      status: 200,
+      headers: {},
+      body: {
+        images: Array.from({ length: images }, (_, i) => ({ url: `https://v3.fal.media/files/out-${i + 1}.png`, width: 1024, height: 1024 })),
+        seed: 42,
+      },
+    };
+  };
+  const propose = { entity: async (x: { title: string; properties: Record<string, unknown> }) => (writes.push(x), { status: "proposed" }) };
+  const raw = (await body(args, {}, callProvider, propose)) as Record<string, any>;
+  return { raw, calls, writes };
+}
+
+const REF = "https://v3.fal.media/files/brand-logo.png";
+
+describe("fal_generate_image — every generated image comes back", () => {
+  it("numImages 3 returns all three URLs, keeps imageUrl as the first, files one bookmark each", async () => {
+    const { raw, calls, writes } = await run({ prompt: "a red fox", numImages: "3" }, 3);
+    expect(calls[0].input.num_images).toBe(3);
+    expect(raw.imageUrls).toEqual([
+      "https://v3.fal.media/files/out-1.png",
+      "https://v3.fal.media/files/out-2.png",
+      "https://v3.fal.media/files/out-3.png",
+    ]);
+    expect(raw.imageUrl).toBe("https://v3.fal.media/files/out-1.png");
+    expect(raw.imageCount).toBe(3);
+    expect(writes.map((w) => w.properties.url)).toEqual(raw.imageUrls);
+  });
+});
+
+/**
+ * Third defect (2026-10-27): the bookmark title was the truncated prompt alone,
+ * identical for every variant and every re-run of a prompt. The duplicate door's
+ * name leg filed each image after the first as POSSIBLE_DUPLICATE (pending
+ * proposals 7a1ad4a2, 9568bd99, …) until the agent hit its pending cap, and the
+ * cap's 403 thrown by propose.entity then failed a run whose images were already
+ * generated and billed.
+ */
+describe("fal_generate_image — bookmarks never pile up as duplicates or sink the run", () => {
+  it("every image's bookmark title carries that image's own fal file id, so no two images share one", async () => {
+    const prompt = "Square editorial illustration, flat gouache style with soft risograph grain on warm cream paper";
+    const a = await run({ prompt, numImages: "3" }, 3);
+    const titles = a.writes.map((w) => w.title);
+    expect(new Set(titles).size).toBe(3);
+    expect(titles.map((t) => t.split(" #").pop())).toEqual(["out-1", "out-2", "out-3"]);
+    for (const t of titles) expect(t.length).toBeLessThanOrEqual(110);
+  });
+
+  it("a refused bookmark write is reported beside the URLs and the run still succeeds", async () => {
+    const callProvider = async () => ({ status: 200, body: { images: [{ url: "https://v3.fal.media/files/a.png" }, { url: "https://v3.fal.media/files/b.png" }] } });
+    let n = 0;
+    const propose = {
+      entity: async () => {
+        if (++n === 2) throw new Error("propose.entity failed: Hub API error: 403 Forbidden — Agent proposal limit reached (15 pending)");
+        return { status: "proposed", proposalId: "p1", proposedEntityId: "e1" };
+      },
+    };
+    const raw = (await body({ prompt: "x", numImages: "2" }, {}, callProvider, propose)) as Record<string, any>;
+    expect(raw.success).toBe(true);
+    expect(raw.imageUrls).toEqual(["https://v3.fal.media/files/a.png", "https://v3.fal.media/files/b.png"]);
+    expect(raw.bookmarkFailures).toBe(1);
+    expect(raw.bookmarks[0]).toMatchObject({ status: "proposed", proposalId: "p1" });
+    expect(raw.bookmarks[1]).toMatchObject({ url: "https://v3.fal.media/files/b.png", status: "failed" });
+    expect(raw.bookmarks[1].error).toMatch(/proposal limit reached/);
+  });
+});
+
+describe("fal_generate_image — declared model inputs reach fal, nothing else does", () => {
+  it("declares imageUrls / aspectRatio / seed beside the original args", () => {
+    expect(verb.parameters).toEqual({
+      prompt: "string",
+      model: "string?",
+      imageSize: "string?",
+      numImages: "string?",
+      imageUrls: "array?",
+      images: "file[]:url?",
+      aspectRatio: "string?",
+      seed: "string?",
+    });
+  });
+
+  it("an edit model gets image_urls, aspect_ratio and seed in fal's own names, and no default image_size", async () => {
+    const { calls, raw } = await run({
+      prompt: "put the logo on a mug",
+      model: "fal-ai/nano-banana/edit",
+      imageUrls: [REF],
+      aspectRatio: "16:9",
+      seed: "7",
+    });
+    expect(calls[0].path).toBe("/fal-ai/nano-banana/edit");
+    expect(calls[0].input).toEqual({
+      prompt: "put the logo on a mug",
+      num_images: 1,
+      image_urls: [REF],
+      aspect_ratio: "16:9",
+      seed: 7,
+    });
+    expect(raw.success).toBe(true);
+  });
+
+  it("a plain text-to-image call is unchanged: prompt, num_images, image_size square_hd", async () => {
+    const { calls } = await run({ prompt: "a red fox" });
+    expect(calls[0]).toMatchObject({ tool: "fal_api", method: "POST", path: "/fal-ai/flux/schnell" });
+    expect(calls[0].input).toEqual({ prompt: "a red fox", num_images: 1, image_size: "square_hd" });
+  });
+
+  it("undeclared keys are never forwarded to fal", async () => {
+    const { calls } = await run({ prompt: "x", apiKey: "sk-secret", sync_mode: true, enable_safety_checker: false });
+    expect(Object.keys(calls[0].input).sort()).toEqual(["image_size", "num_images", "prompt"]);
+  });
+
+  it.each([
+    [{ image_urls: [REF] }, /pass imageUrls, not image_urls/],
+    [{ aspect_ratio: "16:9" }, /pass aspectRatio, not aspect_ratio/],
+    [{ imageUrls: REF }, /imageUrls must be an array/],
+    [{ imageUrls: [] }, /imageUrls is empty/],
+    [{ imageUrls: Array(9).fill(REF) }, /at most 8/],
+    [{ imageUrls: ["data:image/png;base64,AAAA"] }, /public http\(s\) URLs/],
+    [{ imageUrls: ["https://user:pass@example.com/a.png"] }, /without credentials/],
+    [{ imageUrls: ["https://example.com/" + "a".repeat(2100)] }, /public http\(s\) URLs/],
+    [{ aspectRatio: "wide" }, /aspectRatio must be/],
+    [{ seed: "-1" }, /seed must be a whole number/],
+    [{ seed: "1.5" }, /seed must be a whole number/],
+    [{ model: "../../admin" }, /model must be a fal model id/],
+  ])("refuses %j before any billed call", async (extra, message) => {
+    const calls: unknown[] = [];
+    const callProvider = async (...a: unknown[]) => (calls.push(a), { status: 200, body: { images: [] } });
+    await expect(body({ prompt: "x", ...extra }, {}, callProvider, { entity: async () => ({}) })).rejects.toThrow(message);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+/**
+ * Phase 1c (pod files to tools by URL, backend #469): reference images can be
+ * POD FILES. `images` is declared "file[]:url?"; the caller passes file entity
+ * ids and the pod swaps them for fresh signed URLs at run time (6 h, the verb
+ * is async). They join imageUrls in fal's image_urls, and the signed URLs are
+ * never written into a bookmark.
+ */
+describe("fal_generate_image — reference images from the pod", () => {
+  const SIGNED = "https://s3.example.synap.live/pod/logo.png?X-Amz-Signature=secret123";
+
+  it("sends the pod's signed URLs to fal beside public ones, 8 at most together", async () => {
+    const { calls, writes } = await run({ prompt: "logo on a mug", model: "fal-ai/nano-banana/edit", imageUrls: [REF], images: [SIGNED] });
+    expect(calls[0].input.image_urls).toEqual([REF, SIGNED]);
+    expect(writes[0].properties.referenceUrls).toEqual([REF]);
+    expect(writes[0].properties.referencePodFiles).toBe(1);
+    expect(JSON.stringify(writes)).not.toContain("X-Amz-Signature");
+  });
+
+  it("refuses an unswapped id and more than 8 images in all, before any billed call", async () => {
+    const calls: unknown[] = [];
+    const callProvider = async (...a: unknown[]) => (calls.push(a), { status: 200, body: { images: [] } });
+    const propose = { entity: async () => ({}) };
+    await expect(body({ prompt: "x", images: ["8d2f4c1e-0b7a-4c55-9a7e-3f1f0d1c2b3a"] }, {}, callProvider, propose)).rejects.toThrow(/did not arrive as signed pod file URLs/);
+    await expect(body({ prompt: "x", imageUrls: Array(5).fill(REF), images: Array(4).fill(SIGNED) }, {}, callProvider, propose)).rejects.toThrow(/at most 8 images together/);
+    expect(calls).toHaveLength(0);
+  });
+});

package/src/fal-media-lab-pod-files.test.ts

@@ -0,0 +1,180 @@
+/**
+ * fal Media Lab (capability `fal-media-lab`): its image inputs can be POD FILES
+ * (phase 1c of pod files to tools by URL, backend #469). `images` (edit) and
+ * `image` / `endImage` (Seedance) are declared `file:url`; the caller passes
+ * file entity ids and the pod swaps them for fresh signed URLs at run time
+ * (6 h: both verbs are async, and the Seedance queue fetches its frames
+ * later). Public URLs keep working; a signed URL is never stored in the
+ * bookmark the verb proposes.
+ *
+ * SEAM: each verb's REAL `code` body, wrapped the way the pod's executor wraps
+ * it, against fal responses shaped like fal's documented output. NOT covered:
+ * the pod's swap itself (backend file-parameters.ts) and fal live.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const manifest = JSON.parse(
+  readFileSync(
+    join(HERE, "../capabilities/fal-media-lab.capability.json"),
+    "utf8"
+  )
+);
+type Skill = {
+  name: string;
+  code: string;
+  parameters: Record<string, string>;
+  executionMode?: string;
+  metadata?: Record<string, unknown>;
+};
+const verb = (name: string) =>
+  (manifest.spec.skills as Skill[]).find((s) => s.name === name)!;
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as new (
+  ...args: string[]
+) => (...a: unknown[]) => Promise<unknown>;
+const bodyOf = (name: string) =>
+  new AsyncFunction(
+    "args",
+    "context",
+    "callProvider",
+    "propose",
+    verb(name).code
+  );
+
+const PUBLIC = "https://v3.fal.media/files/ref.png";
+const SIGNED =
+  "https://s3.example.synap.live/pod/frame.png?X-Amz-Signature=secret123";
+const FILE_ID = "8d2f4c1e-0b7a-4c55-9a7e-3f1f0d1c2b3a";
+
+async function run(name: string, args: Record<string, unknown>) {
+  const calls: Array<{ path: string; input: Record<string, any> }> = [];
+  const writes: Array<{ properties: Record<string, unknown> }> = [];
+  const callProvider = async (
+    _t: string,
+    _m: string,
+    path: string,
+    input: Record<string, any>
+  ) => {
+    calls.push({ path, input });
+    return {
+      status: 200,
+      body: {
+        images: [{ url: "https://v3.fal.media/files/out.png" }],
+        request_id: "req-1",
+        status_url: "https://queue.fal.run/x/status",
+      },
+    };
+  };
+  const propose = {
+    entity: async (x: { properties: Record<string, unknown> }) => (
+      writes.push(x),
+      { status: "proposed" }
+    ),
+  };
+  const raw = (await bodyOf(name)(args, {}, callProvider, propose)) as Record<
+    string,
+    any
+  >;
+  return { raw, calls, writes };
+}
+
+describe("fal-media-lab — pod files are declared, by URL, on async verbs", () => {
+  it("declares images / image / endImage as file:url, never on a read-only verb", () => {
+    expect(verb("fal_edit_reference_image").parameters).toMatchObject({
+      imageUrls: "string?",
+      images: "file[]:url?",
+    });
+    expect(verb("fal_submit_seedance_video").parameters).toMatchObject({
+      imageUrl: "string?",
+      image: "file:url?",
+      endImage: "file:url?",
+    });
+    for (const n of ["fal_edit_reference_image", "fal_submit_seedance_video"]) {
+      expect(verb(n).executionMode).toBe("async");
+      expect(verb(n).metadata?.readOnly).toBeUndefined();
+    }
+  });
+});
+
+describe("fal_edit_reference_image — reference images from the pod", () => {
+  it("sends pod and public references together; the bookmark keeps only the public ones", async () => {
+    const { calls, writes, raw } = await run("fal_edit_reference_image", {
+      prompt: "swap the mug",
+      imageUrls: PUBLIC,
+      images: [SIGNED],
+    });
+    expect(calls[0].input.image_urls).toEqual([PUBLIC, SIGNED]);
+    expect(writes[0].properties).toMatchObject({
+      referenceUrls: [PUBLIC],
+      referencePodFiles: 1,
+    });
+    expect(JSON.stringify([writes, raw])).not.toContain("X-Amz-Signature");
+  });
+
+  it("a pod image alone is enough; no image at all and an unswapped id are refused before any call", async () => {
+    expect(
+      (await run("fal_edit_reference_image", { prompt: "x", images: [SIGNED] }))
+        .calls
+    ).toHaveLength(1);
+    await expect(
+      run("fal_edit_reference_image", { prompt: "x" })
+    ).rejects.toThrow(/at least one reference image/);
+    await expect(
+      run("fal_edit_reference_image", { prompt: "x", images: [FILE_ID] })
+    ).rejects.toThrow(/did not arrive as signed pod file URLs/);
+  });
+});
+
+describe("fal_submit_seedance_video — first and last frame from the pod", () => {
+  it("queues the pod's signed frames; the bookmark records that they came from the pod, not their URLs", async () => {
+    const { calls, writes } = await run("fal_submit_seedance_video", {
+      prompt: "a slow push-in",
+      image: SIGNED,
+      endImage: SIGNED,
+    });
+    expect(calls[0].input).toMatchObject({
+      image_url: SIGNED,
+      end_image_url: SIGNED,
+    });
+    expect(writes[0].properties).toMatchObject({
+      imageUrl: null,
+      endImageUrl: null,
+      imageFromPod: true,
+      endImageFromPod: true,
+    });
+    expect(JSON.stringify(writes)).not.toContain("X-Amz-Signature");
+  });
+
+  it("a public first frame works as before", async () => {
+    const { calls, writes } = await run("fal_submit_seedance_video", {
+      prompt: "x",
+      imageUrl: PUBLIC,
+    });
+    expect(calls[0].input.image_url).toBe(PUBLIC);
+    expect(calls[0].input.end_image_url).toBeUndefined();
+    expect(writes[0].properties).toMatchObject({
+      imageUrl: PUBLIC,
+      imageFromPod: false,
+    });
+  });
+
+  it.each([
+    [{ prompt: "x" }, /the first frame is required/],
+    [{ prompt: "x", imageUrl: PUBLIC, image: SIGNED }, /not both/],
+    [
+      { prompt: "x", image: SIGNED, endImageUrl: PUBLIC, endImage: SIGNED },
+      /not both/,
+    ],
+    [
+      { prompt: "x", image: FILE_ID },
+      /did not arrive as a signed pod file URL/,
+    ],
+  ])("refuses %j before any call", async (args, message) => {
+    await expect(run("fal_submit_seedance_video", args)).rejects.toThrow(
+      message
+    );
+  });
+});

package/src/finance.yaml

@@ -12,6 +12,12 @@ meta:
   color: "#16A34A"
   tags: [finance, accounting, revenue]
   isPublic: true
+  # What this space PRODUCES (homes): the purpose word, then its kinds/roles.
+  intent:
+    label: Finance
+    produces:
+      - profile: invoice
+      - profile: expense
 
 workspace:
   name: Finance
@@ -19,7 +25,10 @@ workspace:
   proposalId: finance-v1
   subtype: finance
   visibility: members
-  workspaceType: operational
+  # A DOMAIN workspace that holds entities — NOT `operational`. `operational`
+  # marks an admin/system surface: `isDomainHomeWorkspace` refuses filing
+  # entities into it and excludes it from auto-placement (2026-09-25).
+  workspaceType: personal
   capabilities:
     - finance.accounts
     - finance.revenue
@@ -76,6 +85,15 @@ profiles:
     icon: receipt
     color: blue
     description: An accounts-receivable invoice — money customers owe us.
+    # The ONE lifecycle (work model L1): every option's category.
+    lifecycle:
+      property: status
+      options:
+        - { key: draft, category: open }
+        - { key: sent, category: active }
+        - { key: paid, category: done }
+        - { key: overdue, category: active }
+        - { key: void, category: lost, humanOnly: true }
     properties:
       - slug: invoice-number
         label: Invoice #
@@ -119,6 +137,15 @@ profiles:
     icon: credit-card
     color: orange
     description: An accounts-payable expense or spend commitment.
+    # The ONE lifecycle (work model L1): every option's category.
+    lifecycle:
+      property: status
+      options:
+        - { key: pending, category: open }
+        - { key: approved, category: active }
+        - { key: paid, category: done }
+        - { key: reimbursed, category: done, humanOnly: true }
+        - { key: rejected, category: lost, humanOnly: true }
     properties:
       - slug: category
         label: Category
@@ -393,6 +420,16 @@ entityLinks:
     targetProfileSlug: account
     type: deposits_to
     label: Deposits to
+  # Who a recurring stream bills — read by "Bill a recurring fee" to address
+  # the month's invoice. A stream can bill a company or a person (a solo client).
+  - sourceProfileSlug: revenue-stream
+    targetProfileSlug: company
+    type: billed_to
+    label: Billed to
+  - sourceProfileSlug: revenue-stream
+    targetProfileSlug: person
+    type: billed_to
+    label: Billed to
 
 onboarding:
   goal: Capture the company's real money model — where cash sits, what revenue comes in, what it burns on, and its current runway — so the workspace reflects the actual financial position, not a generic ledger.
@@ -444,10 +481,12 @@ onboarding:
       distinct from collected cash, and at least a rough gross margin and LTV:CAC in view.
   collect:
     - profileSlug: account
+      min: 1
       what: The bank and credit accounts holding company cash, with current balances.
       cardinality: few
       keyFields: [title, account-type, balance]
     - profileSlug: revenue-stream
+      min: 1
       what: How the company makes money — each recurring or one-off revenue stream and its MRR/ARR.
       cardinality: several
       keyFields: [title, stream-type, mrr]
@@ -456,6 +495,7 @@ onboarding:
       cardinality: several
       keyFields: [title, category, amount]
     - profileSlug: financial-metric
+      min: 1
       what: The current vital signs, above all RUNWAY (months of cash left) plus burn rate and MRR.
       cardinality: few
       keyFields: [metric-type, value, unit]
@@ -524,3 +564,216 @@ bento:
     - kind: view
       viewName: Budget vs Actual
       pos: { x: 6, y: 8, w: 6, h: 4 }
+
+playbooks:
+  - name: Bill a client
+    description: Take an invoice from draft to paid — prepare it, send it with a person's approval, chase it when late, and confirm the payment.
+    goalTemplate: >-
+      Bill this invoice ({invoice}); each stage moves its status. PREPARE: set
+      the invoice number, customer, amount, currency, issue date and due date
+      from the engagement or deal it bills, and check the amount against what
+      was agreed. SEND: a person approves the invoice before it goes to the
+      client; record the issue date. DUE: wait for the payment; look for it in
+      the bank or payment provider (match the amount and the reference), and
+      move on once it is found or the due date has passed. PAID: its check
+      reads the payment; set the paid date and link the account it was
+      deposited to. When the due date passed unpaid, the check sends the run
+      to CHASE instead: the invoice becomes overdue and you draft a polite
+      reminder for a person to send; once the payment is found, move the run
+      back to Paid. Voiding an invoice is a person's call.
+    subjectProfile:
+      profileSlug: invoice
+      statusProperty: status
+    humanOnlyStatuses: [void]
+    activators:
+      - { on: created, mode: propose }
+    params:
+      - { name: invoice, type: entity, label: Invoice, required: true }
+    executor: is-agent
+    status: active
+    requiredIntents: [fetch_record, list_records, send_message]
+    expectedOutputs:
+      - { kind: document, label: Invoice sent to the client }
+    stages:
+      - key: prepare
+        name: Prepare
+        category: planned
+        subjectStatus: draft
+        goal: Fill every invoice field and check the amount against what was agreed.
+        criteria:
+          - key: invoice-fields-set
+            statement: The invoice number, customer, amount, currency, issue date and due date are set.
+            check: { kind: judge }
+          - key: invoice-amount-matches
+            statement: The amount matches the contract, engagement or deal it bills.
+            check: { kind: judge }
+      - key: send
+        name: Send
+        category: started
+        subjectStatus: sent
+        goal: A person approves the invoice before it goes to the client.
+        gate: { kind: human }
+        onFail: { toStage: prepare }
+      - key: due
+        name: Awaiting payment
+        category: started
+        goal: Wait for the payment and look for it; move on once it is found or the due date has passed.
+        indefinite: true
+        criteria:
+          - key: payment-matched
+            statement: A payment matching the invoice amount and reference was found.
+            check: { kind: evidence, evidenceKey: payment-reference }
+      - key: paid
+        name: Paid
+        category: completed
+        subjectStatus: paid
+        goal: Confirm the payment, set the paid date and link the account it was deposited to.
+        gate: { kind: check }
+        onFail: { toStage: chase }
+      - key: chase
+        name: Chase
+        category: started
+        subjectStatus: overdue
+        goal: The due date passed unpaid — draft a reminder for a person to send; once the payment is found, move the run back to Paid.
+        indefinite: true
+        criteria:
+          - key: late-payment-matched
+            statement: A payment matching the invoice amount and reference was found after the reminder.
+            check: { kind: evidence, evidenceKey: payment-reference }
+
+  # Recurring billing (founder decision 2026-10-12). Monthly, ONE run per
+  # active monthly revenue stream: the schedule is bound to the kind, so the
+  # pod's backing cron fans out query → loop → playbook_run over the streams
+  # the filter selects. The filter is a JSON STRING because the pod's cron door
+  # reads only a string (`readSubjectProfile`, cron-automation.ts) and refuses
+  # an unfiltered AI fan-out. The run only drafts the invoice: "Bill a client"
+  # takes it from there (its `created` activator). Writes are proposed, never
+  # applied unattended. Retainer specifics (quarterly/annual cadences, usage
+  # true-ups) are deliberately left for later.
+  - name: Bill a recurring fee
+    description: Once a month, draft the invoice for each active monthly revenue stream, for a person to approve; Bill a client then sends and collects it.
+    goalTemplate: >-
+      Draft this month's invoice for the recurring revenue stream ({stream}).
+      First look for an invoice already linked to this stream for this month;
+      if one exists, stop and say so. Otherwise create one invoice in Finance
+      at the draft status: the amount is the stream's MRR, the currency and
+      customer are those of the company or person it is billed to, the issue
+      date is today, and the due date follows the customer's usual terms (30
+      days when nothing says otherwise). Link it to the stream. When the
+      stream is billed to nobody, ask the person which client it bills
+      instead of guessing. Never send the invoice: Bill a client takes it
+      from the draft.
+    subjectProfile:
+      profileSlug: revenue-stream
+      filter: '{"properties.status":"active","properties.billing-cadence":"monthly"}'
+    params:
+      - { name: stream, type: entity, label: Revenue stream, required: true }
+    executor: is-agent
+    status: active
+    schedule: { cron: "0 8 1 * *", enabled: true }
+    metadata:
+      governance:
+        forceProposeWrites: true
+    requiredIntents: [list_records]
+    expectedOutputs:
+      - { kind: invoice, label: This month's invoice, relationToSubject: relates_to }
+
+  - name: Approve an expense
+    description: Review an expense against its budget, get a person's approval, and record the payment.
+    goalTemplate: >-
+      Handle this expense ({expense}); each stage moves its status. REVIEW:
+      check the vendor, amount, date, category and receipt, link the budget it
+      counts against and say how much of that budget is left after it. APPROVE:
+      a person approves or rejects the spend. PAY: a person confirms it was
+      paid; link the account it was paid from. Reimbursement and rejection are
+      a person's call.
+    subjectProfile:
+      profileSlug: expense
+      statusProperty: status
+    humanOnlyStatuses: [reimbursed, rejected]
+    activators:
+      - { on: created, mode: propose }
+    params:
+      - { name: expense, type: entity, label: Expense, required: true }
+    executor: is-agent
+    status: active
+    stages:
+      - key: review
+        name: Review
+        category: planned
+        subjectStatus: pending
+        goal: Check the expense's facts and receipt and link the budget it counts against.
+        criteria:
+          - key: expense-facts
+            statement: The vendor, amount, date and category are set.
+            check: { kind: judge }
+          - key: expense-budget-linked
+            statement: The expense is linked to the budget it counts against, with the remaining amount stated.
+            check: { kind: judge }
+      - key: approve
+        name: Approve
+        category: started
+        subjectStatus: approved
+        goal: A person approves the spend.
+        gate: { kind: human }
+        onFail: { toStage: review }
+      - key: pay
+        name: Pay
+        category: completed
+        subjectStatus: paid
+        goal: A person confirms the expense was paid; link the account it was paid from.
+        gate: { kind: human }
+        onFail: { toStage: approve }
+
+  - name: Close the month
+    description: Once a month, reconcile the accounts, chase what is owed, and record runway, burn and revenue for a person to review.
+    goalTemplate: >-
+      Close the month. RECONCILE: compare each account's balance with the bank
+      or payment provider and list every difference; when an account has no
+      bank or payment-provider connection, ask the person to `provide` it (a
+      connection, never a password in a form). RECEIVABLES: list unpaid
+      and overdue invoices and propose a reminder for each overdue one.
+      PAYABLES: list expenses still pending or approved but unpaid. METRICS:
+      record this month's cash in bank, net burn, runway in months and monthly
+      recurring revenue as financial metrics, each with its as-of date and how
+      it was computed. REVIEW: write a one-page month-end note for a person —
+      what changed, what is at risk, what to decide — and wait for their
+      approval before closing.
+    executor: is-agent
+    status: active
+    schedule: { cron: "0 9 1 * *", enabled: false, mode: appointment }
+    requiredIntents: [fetch_record, list_records]
+    expectedOutputs:
+      - { kind: financial-metric, label: Month-end metrics, relationToSubject: none }
+      - { kind: document, label: Month-end note, relationToSubject: none }
+    stages:
+      - key: reconcile
+        name: Reconcile
+        category: started
+        goal: Compare every account with the bank or payment provider and list differences.
+        criteria:
+          - key: accounts-reconciled
+            statement: Every active account has a balance compared with its source, and every difference is listed.
+            check: { kind: judge }
+      - key: receivables
+        name: Receivables
+        category: started
+        goal: List unpaid and overdue invoices and propose a reminder for each overdue one.
+      - key: payables
+        name: Payables
+        category: started
+        goal: List pending and approved-but-unpaid expenses.
+      - key: metrics
+        name: Metrics
+        category: started
+        goal: Record cash, net burn, runway and monthly recurring revenue as dated metrics.
+        criteria:
+          - key: metrics-recorded
+            statement: Cash in bank, net burn, runway and monthly recurring revenue are recorded with this month's as-of date.
+            check: { kind: judge }
+      - key: review
+        name: Review
+        category: completed
+        goal: A person reads the month-end note and approves the close.
+        gate: { kind: human }
+        onFail: { toStage: reconcile }