@pylonsync/create-pylon 0.19.1 → 0.21.0

package/templates/imessage/tests/lib.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import { buildTurnInput, formatLocalTime } from "../lib/assistant";
+import { formatHandle, normalizeHandle } from "../lib/handles";
+import { parseRelayInbound } from "../lib/relay-protocol";
+import { checkReminderTime, cleanStoredText } from "../lib/reminders";
+import { selectedTransport, transportChecklist } from "../lib/transport";
+
+describe("handles", () => {
+  test("normalizes phone numbers and emails", () => {
+    expect(normalizeHandle("(512) 555-0148")).toEqual({ handle: "+15125550148", kind: "phone" });
+    expect(normalizeHandle("1-512-555-0148")).toEqual({ handle: "+15125550148", kind: "phone" });
+    expect(normalizeHandle("+44 20 7946 0958")).toEqual({ handle: "+442079460958", kind: "phone" });
+    expect(normalizeHandle("tel:+15125550148")).toEqual({ handle: "+15125550148", kind: "phone" });
+    expect(normalizeHandle("iMessage;-;+15125550148")).toEqual({ handle: "+15125550148", kind: "phone" });
+    expect(normalizeHandle(" Maya@Example.COM ")).toEqual({ handle: "maya@example.com", kind: "email" });
+  });
+
+  test("rejects anything else", () => {
+    for (const bad of ["", "chat123456789", "12345", "+0123456789", "hello", "a@b", "5125550148; rm -rf", null, undefined]) {
+      expect(normalizeHandle(bad as string)).toBeNull();
+    }
+  });
+
+  test("formats North American numbers", () => {
+    expect(formatHandle("+15125550148")).toBe("(512) 555-0148");
+    expect(formatHandle("+442079460958")).toBe("+442079460958");
+  });
+});
+
+describe("reminders", () => {
+  const now = new Date("2026-09-26T15:00:00Z");
+  test("accepts an offset time within a year", () => {
+    expect(checkReminderTime("2026-09-27T08:00:00-05:00", now)).toEqual({
+      ok: true,
+      dueAt: "2026-09-27T13:00:00.000Z",
+      dueMs: Date.parse("2026-09-27T13:00:00Z"),
+    });
+  });
+  test("rejects times without an offset, in the past, too soon, or too far", () => {
+    expect(checkReminderTime("2026-09-27T08:00:00", now).ok).toBe(false);
+    expect(checkReminderTime("tomorrow at 8", now).ok).toBe(false);
+    expect(checkReminderTime("2026-09-26T14:00:00Z", now).ok).toBe(false);
+    expect(checkReminderTime("2026-09-26T15:04:00Z", now).ok).toBe(false);
+    expect(checkReminderTime("2026-09-26T15:06:00Z", now).ok).toBe(true);
+    expect(checkReminderTime("2028-01-01T00:00:00Z", now).ok).toBe(false);
+  });
+  test("cleans stored text", () => {
+    expect(cleanStoredText("  a \n\n b  ", 10)).toBe("a b");
+    expect(cleanStoredText("x".repeat(20), 5)).toBe("xxxxx");
+  });
+});
+
+describe("turn input", () => {
+  test("carries who, when, and the texts", () => {
+    const input = buildTurnInput(
+      { ownerName: "Jordan", contactName: "Maya", handle: "+15125550148", timezone: "America/Chicago", now: new Date("2026-09-26T15:04:00Z") },
+      ["first", "second"],
+    );
+    expect(input.split("\n")[0]).toContain("Maya (+15125550148)");
+    expect(input).toContain("10:04 AM");
+    expect(input.split("\n")[0]).toContain("you assist Jordan");
+    expect(input.endsWith("first\nsecond")).toBe(true);
+  });
+  test("an invalid timezone falls back to UTC", () => {
+    expect(formatLocalTime(new Date("2026-09-26T15:04:00Z"), "Not/AZone")).toContain("UTC");
+  });
+});
+
+describe("relay protocol + transport selection", () => {
+  test("parses a relay item", () => {
+    expect(
+      parseRelayInbound({ guid: "ABC-123", handle: "(512) 555-0148", text: "yo", sentAt: "2026-09-26T15:00:00Z", service: "iMessage" }),
+    ).toEqual({
+      message: { externalId: "relay:ABC-123", handle: "+15125550148", text: "yo", sentAt: "2026-09-26T15:00:00.000Z", service: "iMessage" },
+    });
+    expect("skip" in parseRelayInbound({ guid: "../../etc", handle: "+15125550148", text: "x" })).toBe(true);
+    expect("skip" in parseRelayInbound({ guid: "A", handle: "chat123", text: "x" })).toBe(true);
+    expect("skip" in parseRelayInbound({ guid: "A", handle: "+15125550148", text: "" })).toBe(true);
+  });
+
+  test("transport selection and checklist", () => {
+    expect(selectedTransport({ IMESSAGE_TRANSPORT: "Relay" })).toBe("relay");
+    expect(selectedTransport({ IMESSAGE_TRANSPORT: "twilio" })).toBeNull();
+    const list = transportChecklist({ RELAY_TOKEN: "short" }, "relay");
+    expect(list).toEqual([expect.objectContaining({ key: "RELAY_TOKEN", ok: false })]);
+    expect(JSON.stringify(transportChecklist({ SENDBLUE_API_SECRET: "super-secret-value" }, "sendblue"))).not.toContain(
+      "super-secret-value",
+    );
+  });
+});
+
+describe("tool activity", () => {
+  test("recognizes refused tool results", async () => {
+    const { toolRefusal } = await import("../lib/format");
+    expect(toolRefusal('{"scheduled":false,"error":"too soon"}', false)).toBe("too soon");
+    expect(toolRefusal('{"scheduled":true}', false)).toBeNull();
+    expect(toolRefusal("Unknown tool", true)).toBe("Unknown tool");
+  });
+});

package/templates/imessage/tests/review-fixes.test.ts

@@ -0,0 +1,138 @@
+// Regression tests for the adversarial review's findings. Each test pins one
+// class of hole so it cannot come back.
+import { describe, expect, test } from "bun:test";
+import claimOutbound from "../functions/claimOutbound";
+import fireReminder from "../functions/fireReminder";
+import settleOutbound from "../functions/settleOutbound";
+import toolSetReminder from "../functions/toolSetReminder";
+import { DEFAULT_SETTINGS, NEW_UNKNOWN_CONTACTS_PER_HOUR } from "../lib/gate";
+import { MAX_REMINDERS_PER_CONTACT_PER_DAY } from "../lib/reminders";
+import { ingestInbound, queueOutbound } from "../lib/store";
+import { isDryRun } from "../lib/transport";
+import { fakeCtx } from "./fake-ctx";
+
+type Handler = (ctx: unknown, args: Record<string, unknown>) => Promise<any>;
+const run = (def: unknown, ctx: unknown, args: Record<string, unknown>) =>
+  (def as { handler: Handler }).handler(ctx, args);
+
+const msg = (id: string, handle: string, text: string) => ({
+  externalId: `relay:${id}`,
+  handle,
+  text,
+  sentAt: new Date().toISOString(),
+  service: "iMessage",
+});
+
+describe("dev server cannot text real people by default", () => {
+  test("pylon dev implies dry run unless explicitly allowed", () => {
+    expect(isDryRun({ PYLON_DEV_MODE: "1" })).toBe(true);
+    expect(isDryRun({ PYLON_DEV_MODE: "1", IMESSAGE_ALLOW_DEV_SENDS: "1" })).toBe(false);
+    expect(isDryRun({})).toBe(false);
+    expect(isDryRun({ IMESSAGE_DRY_RUN: "true" })).toBe(true);
+  });
+
+  test("a reply queued on a dev server is recorded as dry_run and never scheduled", async () => {
+    const f = fakeCtx({ IMESSAGE_TRANSPORT: "sendblue", PYLON_DEV_MODE: "1" });
+    await queueOutbound(f.ctx, { conversationId: "c", contactId: "k", handle: "+15125550148", text: "hi", kind: "owner" });
+    expect(f.table("Message")[0].status).toBe("dry_run");
+    expect(f.scheduled.length).toBe(0);
+  });
+});
+
+describe("STOP/START cannot make the number send in a loop", () => {
+  test("at most one confirmation of each kind per day", async () => {
+    const f = fakeCtx({ IMESSAGE_TRANSPORT: "relay" });
+    await f.ctx.db.insert("Contact", { handle: "+15125550163", kind: "phone", status: "allowed", optedOut: false });
+    const words = ["STOP", "START", "STOP", "START", "STOP", "START"];
+    for (const [i, w] of words.entries()) await ingestInbound(f.ctx, msg(`K${i}`, "+15125550163", w), "relay");
+    const out = f.table("Message").filter((m) => m.direction === "out");
+    expect(out.length).toBe(2);
+    expect(f.table("Contact")[0].optedOut).toBe(false);
+  });
+});
+
+describe("new senders are bounded", () => {
+  test("new unknown contacts per hour are capped", async () => {
+    const f = fakeCtx({ IMESSAGE_TRANSPORT: "relay" });
+    const now = new Date().toISOString();
+    for (let i = 0; i < NEW_UNKNOWN_CONTACTS_PER_HOUR; i++) {
+      await f.ctx.db.insert("Contact", { handle: `+1512555${String(1000 + i)}`, status: "unknown", createdAt: now });
+    }
+    const r = await ingestInbound(f.ctx, msg("N1", "+19995550100", "hi"), "relay");
+    expect(r.status).toBe("dropped");
+    // An existing contact still gets through.
+    await f.ctx.db.insert("Contact", { handle: "+15125550148", kind: "phone", status: "allowed", optedOut: false, createdAt: "2020-01-01T00:00:00Z" });
+    expect((await ingestInbound(f.ctx, msg("N2", "+15125550148", "hi"), "relay")).status).toBe("answer");
+  });
+});
+
+describe("reminders", () => {
+  test("a paused assistant does not send reminders", async () => {
+    const f = fakeCtx({ IMESSAGE_TRANSPORT: "relay" });
+    await f.ctx.db.insert("Settings", { ...DEFAULT_SETTINGS, key: "main", paused: true });
+    const contactId = await f.ctx.db.insert("Contact", { handle: "+15125550148", status: "allowed", optedOut: false });
+    const conversationId = await f.ctx.db.insert("Conversation", { contactId, handle: "+15125550148" });
+    const reminderId = await f.ctx.db.insert("Reminder", { contactId, conversationId, text: "x", status: "scheduled" });
+    expect(await run(fireReminder, f.ctx, { reminderId })).toEqual({ sent: false });
+    expect(f.table("Message").length).toBe(0);
+    expect(f.table("Reminder")[0].status).toBe("cancelled");
+  });
+
+  test("a contact cannot get more than the daily reminder cap", async () => {
+    const f = fakeCtx({});
+    const contactId = await f.ctx.db.insert("Contact", { handle: "+15125550148", status: "allowed" });
+    const conversationId = await f.ctx.db.insert("Conversation", { contactId, handle: "+15125550148" });
+    const when = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+    const results = [];
+    for (let i = 0; i < MAX_REMINDERS_PER_CONTACT_PER_DAY + 3; i++) {
+      const r = await run(toolSetReminder, f.ctx, { contactId, conversationId, when, text: `r${i}` });
+      results.push(r.scheduled);
+      // Simulate the reminder firing so it no longer counts as open.
+      const row = f.table("Reminder").at(-1);
+      if (row && r.scheduled) row.status = "sent";
+    }
+    expect(results.filter(Boolean).length).toBe(MAX_REMINDERS_PER_CONTACT_PER_DAY);
+  });
+
+  test("a reminder cannot target another contact's conversation", async () => {
+    const f = fakeCtx({});
+    const a = await f.ctx.db.insert("Contact", { handle: "+15125550148", status: "allowed" });
+    const b = await f.ctx.db.insert("Contact", { handle: "+15125550163", status: "allowed" });
+    const convB = await f.ctx.db.insert("Conversation", { contactId: b, handle: "+15125550163" });
+    const when = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+    const r = await run(toolSetReminder, f.ctx, { contactId: a, conversationId: convB, when, text: "x" });
+    expect(r.scheduled).toBe(false);
+    expect(f.scheduled.length).toBe(0);
+  });
+});
+
+describe("Sendblue delivery leases", () => {
+  test("only the lease holder can settle; a taken-over lease is refused", async () => {
+    const f = fakeCtx({ IMESSAGE_TRANSPORT: "sendblue" });
+    const conversationId = await f.ctx.db.insert("Conversation", { contactId: "k", handle: "+15125550148" });
+    for (let i = 0; i < 7; i++) {
+      await f.ctx.db.insert("Message", {
+        conversationId,
+        direction: "out",
+        transport: "sendblue",
+        status: "queued",
+        text: `m${i}`,
+        createdAt: `2026-09-26T15:00:0${i}Z`,
+      });
+    }
+    const first = await run(claimOutbound, f.ctx, { conversationId });
+    expect(first.messages.map((m: { text: string }) => m.text)).toEqual(["m0", "m1", "m2", "m3", "m4"]);
+    // A second job while the lease is live claims nothing (order holds).
+    expect((await run(claimOutbound, f.ctx, { conversationId })).messages).toEqual([]);
+
+    // Expire the lease; another job takes it over.
+    for (const m of f.table("Message")) if (m.status === "leased") m.leaseUntil = "2000-01-01T00:00:00Z";
+    const second = await run(claimOutbound, f.ctx, { conversationId });
+    expect(second.messages[0].text).toBe("m0");
+
+    const id = first.messages[0].id;
+    expect(await run(settleOutbound, f.ctx, { messageId: id, leaseToken: first.leaseToken, status: "sent" })).toEqual({ ok: false });
+    expect(await run(settleOutbound, f.ctx, { messageId: id, leaseToken: second.leaseToken, status: "sent" })).toEqual({ ok: true });
+    expect(f.table("Message").find((m) => m.id === id)?.status).toBe("sent");
+  });
+});

package/templates/imessage/tests/secrets.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { bearerToken, checkSecret, constantTimeEqual, headerValue } from "../lib/secrets";
+
+const TOKEN = "relay-token-0123456789abcdef0123";
+
+describe("relay token auth", () => {
+  test("accepts the configured bearer token", () => {
+    expect(checkSecret(bearerToken(`Bearer ${TOKEN}`), TOKEN)).toEqual({ ok: true });
+    expect(checkSecret(bearerToken(`bearer   ${TOKEN}  `), TOKEN)).toEqual({ ok: true });
+  });
+
+  test("rejects a wrong or missing token", () => {
+    expect(checkSecret(bearerToken(`Bearer ${TOKEN}0`), TOKEN)).toEqual({ ok: false, reason: "invalid" });
+    expect(checkSecret(bearerToken("Bearer nope"), TOKEN)).toEqual({ ok: false, reason: "invalid" });
+    expect(checkSecret(bearerToken(TOKEN), TOKEN)).toEqual({ ok: false, reason: "missing" });
+    expect(checkSecret(bearerToken(undefined), TOKEN)).toEqual({ ok: false, reason: "missing" });
+    expect(checkSecret(bearerToken("Basic abc"), TOKEN)).toEqual({ ok: false, reason: "missing" });
+  });
+
+  test("an unset or short server token rejects everything", () => {
+    expect(checkSecret("anything", undefined)).toEqual({ ok: false, reason: "not_configured" });
+    expect(checkSecret("", "")).toEqual({ ok: false, reason: "not_configured" });
+    expect(checkSecret("abc", "abc")).toEqual({ ok: false, reason: "not_configured" });
+  });
+
+  test("constantTimeEqual compares full strings", () => {
+    expect(constantTimeEqual("same-value", "same-value")).toBe(true);
+    expect(constantTimeEqual("same-value", "same-valuf")).toBe(false);
+    expect(constantTimeEqual("", "x")).toBe(false);
+  });
+
+  test("headerValue is case-insensitive", () => {
+    expect(headerValue({ Authorization: "x" }, "authorization")).toBe("x");
+    expect(headerValue(null, "authorization")).toBeNull();
+  });
+});

package/templates/imessage/tests/sendblue.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildSendblueRequest,
+  parseSendblueInbound,
+  SENDBLUE_SEND_URL,
+  sendblueConfig,
+  sendblueTransport,
+  verifySendblueWebhook,
+} from "../lib/sendblue";
+
+const SECRET = "test-webhook-secret-0123456789abcdef";
+
+describe("Sendblue webhook verification", () => {
+  test("accepts the configured secret", () => {
+    expect(verifySendblueWebhook({ "sb-signing-secret": SECRET }, SECRET)).toEqual({ ok: true });
+  });
+
+  test("header name is case-insensitive", () => {
+    expect(verifySendblueWebhook({ "SB-Signing-Secret": SECRET }, SECRET)).toEqual({ ok: true });
+  });
+
+  test("rejects a wrong secret", () => {
+    expect(verifySendblueWebhook({ "sb-signing-secret": `${SECRET}x` }, SECRET)).toEqual({
+      ok: false,
+      reason: "invalid",
+    });
+    expect(verifySendblueWebhook({ "sb-signing-secret": SECRET.slice(0, -1) }, SECRET)).toEqual({
+      ok: false,
+      reason: "invalid",
+    });
+  });
+
+  test("rejects a missing header", () => {
+    expect(verifySendblueWebhook({}, SECRET)).toEqual({ ok: false, reason: "missing" });
+    expect(verifySendblueWebhook({ "sb-signing-secret": "  " }, SECRET)).toEqual({ ok: false, reason: "missing" });
+    expect(verifySendblueWebhook(undefined, SECRET)).toEqual({ ok: false, reason: "missing" });
+  });
+
+  test("fails closed when no secret (or a short one) is configured", () => {
+    expect(verifySendblueWebhook({ "sb-signing-secret": "" }, "")).toEqual({ ok: false, reason: "not_configured" });
+    expect(verifySendblueWebhook({ "sb-signing-secret": "short" }, "short")).toEqual({
+      ok: false,
+      reason: "not_configured",
+    });
+  });
+});
+
+describe("Sendblue inbound parsing", () => {
+  const base = {
+    accountEmail: "you@example.com",
+    content: "Hello!",
+    is_outbound: false,
+    status: "RECEIVED",
+    message_handle: "99DCC379-DD76-4712-BA65-11EFB33B8CD6",
+    from_number: "+19998887777",
+    to_number: "+15122164639",
+    date_sent: "2025-12-12T15:41:20.932Z",
+    service: "iMessage",
+  };
+
+  test("normalizes a received message", () => {
+    const r = parseSendblueInbound(base, "+15122164639");
+    expect(r).toEqual({
+      message: {
+        externalId: "sendblue:99DCC379-DD76-4712-BA65-11EFB33B8CD6",
+        handle: "+19998887777",
+        text: "Hello!",
+        sentAt: "2025-12-12T15:41:20.932Z",
+        service: "iMessage",
+      },
+    });
+  });
+
+  test("skips outbound status events, groups, other numbers, and empty bodies", () => {
+    expect("skip" in parseSendblueInbound({ ...base, is_outbound: true }, "")).toBe(true);
+    expect("skip" in parseSendblueInbound({ ...base, group_id: "g1" }, "")).toBe(true);
+    expect("skip" in parseSendblueInbound(base, "+15125550000")).toBe(true);
+    expect("skip" in parseSendblueInbound({ ...base, content: "  " }, "")).toBe(true);
+    expect("skip" in parseSendblueInbound({ ...base, message_handle: "" }, "")).toBe(true);
+    expect("skip" in parseSendblueInbound({ ...base, from_number: "chat123456" }, "")).toBe(true);
+    expect("skip" in parseSendblueInbound("not an object", "")).toBe(true);
+  });
+
+  test("an attachment without text becomes a placeholder", () => {
+    const r = parseSendblueInbound({ ...base, content: "", media_url: "https://cdn.example/x.jpg" }, "");
+    expect("message" in r && r.message.text).toBe("[sent an attachment]");
+  });
+});
+
+describe("Sendblue outbound", () => {
+  const config = sendblueConfig(
+    {
+      SENDBLUE_API_KEY: "key-id",
+      SENDBLUE_API_SECRET: "key-secret",
+      SENDBLUE_FROM_NUMBER: "(512) 555-0100",
+      SENDBLUE_WEBHOOK_SECRET: SECRET,
+    },
+    false,
+  );
+
+  test("builds the documented request", () => {
+    const { url, init } = buildSendblueRequest(config, { messageId: "m1", to: "+15125550148", text: "hi" });
+    expect(url).toBe(SENDBLUE_SEND_URL);
+    expect(init.method).toBe("POST");
+    const headers = init.headers as Record<string, string>;
+    expect(headers["sb-api-key-id"]).toBe("key-id");
+    expect(headers["sb-api-secret-key"]).toBe("key-secret");
+    expect(JSON.parse(String(init.body))).toEqual({ number: "+15125550148", from_number: "+15125550100", content: "hi" });
+  });
+
+  test("send reports the provider message handle", async () => {
+    const calls: string[] = [];
+    const transport = sendblueTransport(config, async (url) => {
+      calls.push(url);
+      return new Response(JSON.stringify({ status: "QUEUED", message_handle: "abc" }), { status: 200 });
+    });
+    expect(await transport.send({ messageId: "m1", to: "+15125550148", text: "hi" })).toEqual({
+      status: "sent",
+      externalId: "sendblue:abc",
+    });
+    expect(calls).toEqual([SENDBLUE_SEND_URL]);
+  });
+
+  test("send reports provider errors", async () => {
+    const transport = sendblueTransport(config, async () =>
+      new Response(JSON.stringify({ status: "ERROR", error_message: "bad number" }), { status: 200 }),
+    );
+    expect(await transport.send({ messageId: "m1", to: "+15125550148", text: "hi" })).toEqual({
+      status: "failed",
+      error: "Sendblue: bad number",
+    });
+  });
+
+  test("dry run never calls the network", async () => {
+    let called = false;
+    const transport = sendblueTransport({ ...config, dryRun: true }, async () => {
+      called = true;
+      return new Response("{}");
+    });
+    expect(await transport.send({ messageId: "m1", to: "+15125550148", text: "hi" })).toEqual({ status: "dry_run" });
+    expect(called).toBe(false);
+  });
+});

package/templates/imessage/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/imessage/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ES2022", "DOM"],
+    "types": ["react", "react-dom", "node"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["app.ts", "app/**/*", "components/**/*", "lib/**/*", "functions/**/*"]
+}

package/templates/inventory/AGENTS.md

@@ -62,7 +62,7 @@ this pass before the user has to ask.
 - **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
 - **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready; status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
 - **`ctx.llm`, `ctx.rooms`, and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db`; use `ctx.runQuery` / `ctx.runMutation`.
-- **`ctx.llm.stream(request, onEvent)` streams tokens as they generate** and still resolves with the full response, so `stop_reason === "tool_use"` drives an agent tool loop. Events are `text_delta` / `tool_use_start` / `tool_input_delta` / `done`. Same auth + model-allowlist gating as `ctx.llm.complete`. Streaming does NOT extend the call deadline (`PYLON_FN_CALL_TIMEOUT`, 30s default) — set `timeout: <secs>` on the def for a long run.
+- **`ctx.llm.stream(request, onEvent)` streams tokens as they generate** and still resolves with the full response, so `stop_reason === "tool_use"` drives an agent tool loop. Events are `text_delta` / `tool_use_start` / `tool_input_delta` / `done`. Same auth + model-allowlist gating as `ctx.llm.complete`. The call timeout is an idle timeout (`PYLON_FN_CALL_TIMEOUT`, 30s default; Stack0 Cloud 300s): each stream event resets it, and the total run is capped at 10× the timeout. Set `timeout: <secs>` on the def when a step (a slow tool call) can be silent longer than that.
 - **`ctx.stream.write(text)` streams to the caller — and every fn stream is RESUMABLE**: the server buffers frames under a stream id (`streamFn`'s `onStreamId`), so a dropped connection or closed tab catches up via `resumeStream(id)`, including the final result after the handler finished. `ctx.rooms.broadcast(room, topic, data)` fans out to every CURRENTLY-CONNECTED subscriber (second device, second tab) but does not replay missed messages — use the stream id for anything that must survive a gap. Broadcast resolves `{ delivered: false }` when the room has no members — a no-op, not an error. Clients receive with `useRoomMessages(room, cb)` from `@pylonsync/react`; `useRoom` is the send side.
 - **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
 - **Use the supported file and scheduling APIs.** Files go through `<FileUpload>` and `/api/files/*`; an upload is readable by its uploader only, so pass `visibility: "public"` to `uploadFile` or `<FileUpload>` for files every visitor sees; there is no `ctx.files`. One-shot work uses `ctx.scheduler.runAfter`, `runAt`, or `cancel`; there is no `defineWorkflow` or `defineJob`. Recurring work uses `cron("0 * * * *", "fnName")` in `buildManifest({ crons: [...] })`, imported from `@pylonsync/sdk`. Make the target function `internal: true`. It runs with anonymous auth, but its own `ctx.db.*` calls are server-side and bypass policies. Use `ctx.auth.elevate({ admin: true, reason: "..." })`, with a mandatory reason, only when chaining another internal function through `ctx.scheduler`.

package/templates/inventory/README.md

@@ -15,6 +15,11 @@ realistic shelf — including one line out of stock and one below its reorder
 point — so those states are visible rather than theoretical. Delete
 `functions/seedWorkspace.ts` and `lib/seed.ts` once you stock real products.
 
+The movements are spread across you and four demo teammates. Each is a User
+row with a `@demo.invalid` address and no password, so outside dev mode nobody
+can sign in as one (see `lib/demo-team.ts`). Delete those users along with the
+seed.
+
 ## The one design decision that matters
 
 **There is no `quantity` column.** On-hand is the SUM of a product\'s movements.
@@ -56,6 +61,22 @@ a stock count instead.
 **It\'s live.** A movement recorded at the back door updates the level on the
 shop floor\'s screen immediately, so nobody sells what was just damaged.
 
+## Brand and layout
+
+The product ships as **Stockroom**. The name lives in `lib/brand.ts`, and the
+sidebar, sign-in screen, page titles, and phone drawer all read it. The mark is
+`components/brand-mark.tsx`; `app/icon.svg`, `app/apple-icon.png`, and
+`public/favicon.ico` draw the same shape for browsers and home screens. The
+accent colour is `--brand` at the top of `app/globals.css`, and the typeface
+(IBM Plex Sans (and IBM Plex Mono for SKUs)) is set in `fonts` in `app.ts`.
+
+The frame is `components/app-shell.tsx`. From 768px up the sidebar is a fixed
+rail; below that it opens as a drawer from the menu button in each page header,
+tables drop their lower-priority columns (`hideBelow` in
+`components/data-table.tsx`), and boards scroll one column at a time. The nav
+links are in `components/nav.tsx`. Every nav count comes from `navCounts` in
+`app/workspace.tsx`, and page headers and tabs read the same numbers.
+
 ## Layout
 
 ```

package/templates/inventory/app/globals.css

@@ -9,15 +9,21 @@
 /* ---------------------------------------------------------------------------
    Design tokens.
 
-   Tuned for a dense internal tool rather than a marketing page: a near-neutral
-   surface ramp, hairline borders instead of shadows, and one accent used
-   sparingly so status colour still means something. Dark is the primary theme —
-   `app/layout.tsx` sets `class="dark"` — and light is a real, tested
-   alternative, not an afterthought.
+   Tuned for a dense internal tool: a near-neutral surface ramp, hairline
+   borders instead of shadows, and one accent used sparingly so status colour
+   still means something. Light is the default; `.dark` holds a complete dark
+   set (add `class="dark"` to <html> in app/layout.tsx to switch).
 
-   These are the same variable names shadcn/ui generates against, so
+   These are the variable names shadcn/ui generates against, so
    `npx shadcn@latest add <component>` drops in already themed.
 --------------------------------------------------------------------------- */
+:root {
+  /* The brand accent: primary buttons, the brand mark, focus rings, and the
+     active nav icon. Change these two lines to re-colour the product. */
+  --brand: oklch(0.5 0.11 152);
+  --brand-dark: oklch(0.66 0.13 152);
+}
+
 :root {
   --radius: 0.5rem;
 
@@ -28,7 +34,7 @@
   --popover: oklch(1 0 0);
   --popover-foreground: var(--foreground);
 
-  --primary: oklch(0.55 0.204 274.5);
+  --primary: var(--brand);
   --primary-foreground: oklch(1 0 0);
   --secondary: oklch(0.968 0.002 286.4);
   --secondary-foreground: oklch(0.27 0.006 286);
@@ -40,7 +46,7 @@
 
   --border: oklch(0.918 0.004 286.3);
   --input: oklch(0.918 0.004 286.3);
-  --ring: oklch(0.55 0.204 274.5);
+  --ring: var(--brand);
 
   /* Surfaces above the page: sidebar, popovers, hover rows. */
   --surface-1: oklch(0.985 0.001 286.4);
@@ -51,6 +57,7 @@
   --stage-lead: oklch(0.62 0.03 264);
   --stage-qualified: oklch(0.6 0.13 240);
   --stage-proposal: oklch(0.68 0.15 78);
+  --stage-negotiation: oklch(0.64 0.16 45);
   --stage-won: oklch(0.6 0.15 155);
   --stage-lost: oklch(0.6 0.11 25);
 }
@@ -63,7 +70,7 @@
   --popover: oklch(0.216 0.006 285.9);
   --popover-foreground: var(--foreground);
 
-  --primary: oklch(0.62 0.19 274.5);
+  --primary: var(--brand-dark);
   --primary-foreground: oklch(1 0 0);
   --secondary: oklch(0.25 0.006 286);
   --secondary-foreground: oklch(0.93 0.002 286.3);
@@ -75,7 +82,7 @@
 
   --border: oklch(1 0 0 / 9%);
   --input: oklch(1 0 0 / 12%);
-  --ring: oklch(0.62 0.19 274.5);
+  --ring: var(--brand-dark);
 
   --surface-1: oklch(0.186 0.004 285.9);
   --surface-2: oklch(0.216 0.006 285.9);
@@ -83,6 +90,7 @@
   --stage-lead: oklch(0.68 0.03 264);
   --stage-qualified: oklch(0.68 0.13 240);
   --stage-proposal: oklch(0.75 0.14 78);
+  --stage-negotiation: oklch(0.72 0.15 45);
   --stage-won: oklch(0.7 0.15 155);
   --stage-lost: oklch(0.68 0.14 25);
 }
@@ -118,6 +126,7 @@
   --color-stage-lead: var(--stage-lead);
   --color-stage-qualified: var(--stage-qualified);
   --color-stage-proposal: var(--stage-proposal);
+  --color-stage-negotiation: var(--stage-negotiation);
   --color-stage-won: var(--stage-won);
   --color-stage-lost: var(--stage-lost);
 }
@@ -143,15 +152,21 @@
     height: 100%;
     background-color: var(--color-background);
     color: var(--color-foreground);
-    /* 13px is the density these screens are designed at; the slight negative
-       tracking is what keeps Inter from looking loose at that size. */
-    font-size: 13px;
+    /* 14px on phones, 13px from the md breakpoint up: the density these
+       screens are designed at on a desktop. */
+    font-size: 14px;
     line-height: 1.5;
-    letter-spacing: -0.006em;
+    letter-spacing: -0.003em;
     -webkit-font-smoothing: antialiased;
     text-rendering: optimizeLegibility;
   }
 
+  @media (min-width: 768px) {
+    body {
+      font-size: 13px;
+    }
+  }
+
   button {
     cursor: pointer;
   }

package/templates/inventory/app/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#267543"/><g fill="#fff"><rect x="10.6" y="6" width="10.8" height="9" rx="1.8"/><rect x="5.4" y="17" width="10.2" height="9" rx="1.8"/><rect x="16.4" y="17" width="10.2" height="9" rx="1.8"/></g></svg>

package/templates/inventory/app/layout.tsx

@@ -18,12 +18,14 @@ export default function RootLayout({ children }: LayoutProps) {
     <html lang="en">
       <head>
         <meta charSet="utf-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1" />
-        <title>__APP_NAME__</title>
+        <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+        {/* No <title> here: each page's `metadata` sets "<Page> · <Brand>".
+            A title in the layout renders first and wins over the page's. */}
         {/* Tailwind is compiled by Pylon from app/globals.css and the
-            stylesheet link is injected here automatically. Inter is declared in
-            app.ts (fonts: [...]) and self-hosted by the build — @font-face, the
-            preload link, and a size-adjusted fallback are injected too. */}
+            stylesheet link is injected here automatically. The typeface is
+            declared in app.ts (fonts: [...]) and self-hosted by the build;
+            @font-face, the preload link, and a size-adjusted fallback are
+            injected too. */}
       </head>
       <body className="h-full">{children}</body>
     </html>