@desplega.ai/agent-swarm 2.4.3 → 2.4.5

package/templates/extensions/slack-reply-gate/hooks.ts

@@ -6,8 +6,9 @@ import { z } from "zod";
  *
  * Every human message in a Slack thread the swarm takes part in is buffered and
  * flushed into a Lead task ("[Thread follow-up — N message(s) buffered]"), even
- * "lol", ":joy:" or two people bantering. This hook asks TypeSafe Jev whether
- * Lead should answer, and drops the wake-up when the answer is no.
+ * "lol", ":joy:" or two people bantering. This hook asks a SystemOne decision
+ * model (Jev or Clef) whether Lead should answer, and drops the wake-up when the
+ * answer is no.
  *
  * Hook: `pre.task.create`, origin "slack", description carrying the
  * thread-buffer header. `pre.slack.route` cannot be used: the buffered thread
@@ -15,17 +16,20 @@ import { z } from "zod";
  * re-target a message, never drop it.
  *
  * Rules:
- *   - A message that @mentions Lead passes without a Jev call.
- *   - Otherwise one Jev `choice` question classifies the message into a reason;
+ *   - A message that @mentions Lead passes without a decision call.
+ *   - Otherwise one `choice` question classifies the message into a reason;
  *     reply=false only for reaction_only | banter_between_others |
  *     not_addressed_to_lead, and only when the summed probability of those
  *     three labels is >= minConfidence (a banter/reaction split is still a skip).
  *   - Fails OPEN on every error, timeout or missing key.
  *
- * Transport (config.provider): Jev is served by TypeSafe directly and by
- * OpenRouter's Decisions endpoint. Both take the same {model, state, questions}
- * body and return the same `answers` shape. `auto` uses TYPESAFE_API_KEY when
- * set, else OPENROUTER_API_KEY.
+ * Provider (config.provider): the decision is made server-side by the
+ * `system-one-decide` tool (`ctx.swarm.systemOne_decide`), the same path as a
+ * `system-one-decision` workflow node, so every SystemOne host works and no key
+ * enters this hook. `auto` picks the first host with a configured credential:
+ * typesafe (Jev, TYPESAFE_API_KEY), openrouter (Jev, OPENROUTER_API_KEY), then
+ * cloudflare (Clef, CLOUDFLARE_API_TOKEN or CLOUDFLARE_API_KEY, plus
+ * CLOUDFLARE_ACCOUNT_ID). laya and openai are explicit choices only.
  *
  * modes (config.mode):
  *   off     -> never evaluate
@@ -48,17 +52,19 @@ import { z } from "zod";
 export const config = z.object({
   mode: z.enum(["off", "shadow", "enforce"]).default("shadow"),
   timeoutMs: z.number().int().positive().default(3000),
-  provider: z.enum(["auto", "typesafe", "openrouter"]).default("auto"),
-  /** Jev model on the TypeSafe transport. */
+  provider: z
+    .enum(["auto", "typesafe", "openrouter", "cloudflare", "laya", "openai"])
+    .default("auto"),
+  /** Jev model on TypeSafe. */
   model: z.string().default("jev-latest"),
-  /** Jev model on the OpenRouter transport. */
+  /** Jev model on OpenRouter. */
   openrouterModel: z.string().default("typesafe/jev-1.13"),
+  /** Clef model on Cloudflare Workers AI: clef or clef-flash. */
+  cloudflareModel: z.string().default("clef"),
   minConfidence: z.number().min(0).max(1).default(0.55),
   contextMessages: z.number().int().min(0).max(20).default(6),
   leadAliases: z.array(z.string()).default(["lead"]),
   botSlackUserIds: z.array(z.string()).default([]),
-  /** Explicit TypeSafe key; otherwise TYPESAFE_API_KEY from the API process env. */
-  apiKey: z.string().optional(),
   /**
    * Reaction for a dropped message in enforce mode. "" only removes the bot's
    * acceptance reaction(s) and adds nothing.
@@ -71,13 +77,13 @@ type Cfg = z.infer<typeof config>;
 type Swarm = ApiCtx["swarm"];
 
 const NS = "ext:slack-reply-gate";
-const TYPESAFE_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
-const OPENROUTER_ENDPOINT = "https://openrouter.ai/api/alpha/decisions";
 const HEADER_LINE_RE = /(?:^|\n)\[Thread follow-up — \d+ message\(s\) buffered\]\n/g;
 const CTX_OPEN = "<thread_context>";
 const CTX_CLOSE = "</thread_context>";
 // The dispatcher cancels a handler after 5 s; leave room for the KV writes.
 const MAX_TIMEOUT_MS = 4000;
+// The smallest time budget system-one-decide accepts.
+const MIN_DECIDE_TIMEOUT_MS = 1000;
 
 export const REASONS = {
   direct_ask:
@@ -179,14 +185,14 @@ const usable = (v: string): boolean => Boolean(v) && !v.startsWith("[REDACTED");
 const envOf = (name: string): string => String(process.env[name] ?? "");
 
 /**
- * Resolve a secret: explicit value, then the API process env. The API process loads
- * global swarm_config rows into process.env at boot and on config reload.
+ * Resolve a secret from the API process env. The API process loads global
+ * swarm_config rows into process.env at boot and on config reload.
  * ctx.swarm.config_get cannot serve it: the SDK scrubs secrets to "[REDACTED:<name>]".
  */
-const secret = (name: string, explicit?: string): string => {
+const secret = (name: string): string => {
   const cached = secretCache.get(name);
   if (cached && Date.now() - cached.at < KEY_TTL_MS) return cached.value;
-  const value = [String(explicit ?? ""), envOf(name)].find(usable) ?? "";
+  const value = usable(envOf(name)) ? envOf(name) : "";
   if (usable(value)) secretCache.set(name, { value, at: Date.now() });
   return value;
 };
@@ -196,46 +202,51 @@ export const resetKeyCache = (): void => {
   secretCache.clear();
 };
 
-export type JevTransport = {
-  provider: "typesafe" | "openrouter";
-  endpoint: string;
-  key: string;
-  model: string;
-};
+export type ProviderId = Exclude<Cfg["provider"], "auto">;
+
+/** Where the decision is made. No model means the provider's own default. */
+export type DecisionTarget = { provider: ProviderId; model?: string };
+
+/** What `auto` needs per provider: every group must have one usable value. */
+const AUTO_CREDENTIALS: ReadonlyArray<[ProviderId, string[][]]> = [
+  ["typesafe", [["TYPESAFE_API_KEY"]]],
+  ["openrouter", [["OPENROUTER_API_KEY"]]],
+  ["cloudflare", [["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_API_KEY"], ["CLOUDFLARE_ACCOUNT_ID"]]],
+];
+
+const modelFor = (provider: ProviderId, cfg: Cfg): string | undefined =>
+  provider === "typesafe"
+    ? cfg.model
+    : provider === "openrouter"
+      ? cfg.openrouterModel
+      : provider === "cloudflare"
+        ? cfg.cloudflareModel
+        : undefined;
 
 /**
- * Pick the Jev transport. `auto` prefers TypeSafe and falls back to OpenRouter.
- * Throws when the chosen provider has no usable key; the handler fails open.
+ * The decision providers to try, in order. An explicit one is used as is: the
+ * server checks its credential. `auto` lists every provider in `AUTO_CREDENTIALS`
+ * whose credential is set and throws when none is; the handler then fails open.
  */
-export const resolveTransport = (cfg: Cfg): JevTransport => {
-  const typesafe = (): JevTransport | null => {
-    const key = secret("TYPESAFE_API_KEY", cfg.apiKey);
-    return usable(key)
-      ? { provider: "typesafe", endpoint: TYPESAFE_ENDPOINT, key, model: cfg.model }
-      : null;
-  };
-  const openrouter = (): JevTransport | null => {
-    const key = secret("OPENROUTER_API_KEY");
-    return usable(key)
-      ? { provider: "openrouter", endpoint: OPENROUTER_ENDPOINT, key, model: cfg.openrouterModel }
-      : null;
-  };
-  const transport =
-    cfg.provider === "typesafe"
-      ? typesafe()
-      : cfg.provider === "openrouter"
-        ? openrouter()
-        : (typesafe() ?? openrouter());
-  if (transport) return transport;
+export const resolveProviders = (cfg: Cfg): DecisionTarget[] => {
+  if (cfg.provider !== "auto") {
+    return [{ provider: cfg.provider, model: modelFor(cfg.provider, cfg) }];
+  }
+  const targets = AUTO_CREDENTIALS.filter(([, groups]) =>
+    groups.every((keys) => keys.some((key) => usable(secret(key)))),
+  ).map(([provider]) => ({ provider, model: modelFor(provider, cfg) }));
+  if (targets.length > 0) return targets;
   throw new Error(
-    cfg.provider === "typesafe"
-      ? "no TYPESAFE_API_KEY"
-      : cfg.provider === "openrouter"
-        ? "no OPENROUTER_API_KEY"
-        : "no TYPESAFE_API_KEY or OPENROUTER_API_KEY",
+    "no TYPESAFE_API_KEY, OPENROUTER_API_KEY, or CLOUDFLARE_API_TOKEN with CLOUDFLARE_ACCOUNT_ID",
   );
 };
 
+/** The first provider `resolveProviders` would try. */
+export const resolveProvider = (cfg: Cfg): DecisionTarget => resolveProviders(cfg)[0]!;
+
+/** The server refused the provider for a deployment setting and sent nothing. */
+export class ProviderUnavailableError extends Error {}
+
 const SLACK_API = "https://slack.com/api";
 // The engine's acceptance reactions (src/slack/reaction-shortcode.ts), by config key.
 const ACCEPTANCE_REACTIONS: ReadonlyArray<[string, string]> = [
@@ -323,7 +334,7 @@ export const settleMutes = async (): Promise<void> => {
   await Promise.allSettled([...pendingMutes]);
 };
 
-export type JevVerdict = {
+export type Verdict = {
   reason: string;
   confidence: number | null;
   probabilities: Record<string, number> | null;
@@ -331,56 +342,73 @@ export type JevVerdict = {
 };
 
 /**
- * One Jev call: classify the newest message into a reason. Throws on any failure.
- * TypeSafe and OpenRouter share the request body and the `answers` response shape.
+ * One decision: classify the newest message into a reason. Throws on any failure.
+ * The server makes the call (`system-one-decide`), so every provider returns the
+ * same `answers` shape. The time budget is enforced here and on the server.
  */
-export const askJev = async (
+export const askModel = async (
+  swarm: Swarm,
   input: {
     messages: string[];
     context: string[];
     sender: string;
     leadNames: readonly string[];
   },
-  transport: JevTransport,
+  target: DecisionTarget,
   cfg: Cfg,
   outer?: AbortSignal,
-): Promise<JevVerdict> => {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), Math.min(cfg.timeoutMs, MAX_TIMEOUT_MS));
-  const onOuterAbort = () => controller.abort();
-  outer?.addEventListener("abort", onOuterAbort);
+): Promise<Verdict> => {
+  const budgetMs = Math.min(cfg.timeoutMs, MAX_TIMEOUT_MS);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onOuterAbort: (() => void) | undefined;
+  const stop = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`timed out after ${budgetMs}ms`)), budgetMs);
+    onOuterAbort = () => reject(new Error("aborted"));
+    outer?.addEventListener("abort", onOuterAbort);
+  });
   const t0 = Date.now();
   try {
-    const res = await fetch(transport.endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${transport.key}`,
+    const call = swarm.systemOne_decide({
+      provider: target.provider,
+      ...(target.model ? { model: target.model } : {}),
+      state: {
+        role: "Decide whether Lead, the coordinating AI agent of a team's agent swarm, should answer a new Slack message in a thread it takes part in. Lead is woken by every message in the thread, including ones not meant for it. Answering noise wastes everyone's time; missing a real ask is worse.",
+        lead_names: [...input.leadNames],
+        recent_thread_messages: input.context,
+        new_message: input.messages.join("\n---\n"),
+        new_message_sender: input.sender,
       },
-      body: JSON.stringify({
-        state: {
-          role: "Decide whether Lead, the coordinating AI agent of a team's agent swarm, should answer a new Slack message in a thread it takes part in. Lead is woken by every message in the thread, including ones not meant for it. Answering noise wastes everyone's time; missing a real ask is worse.",
-          lead_names: input.leadNames,
-          recent_thread_messages: input.context,
-          new_message: input.messages.join("\n---\n"),
-          new_message_sender: input.sender,
-        },
-        model: transport.model,
-        questions: {
-          reason: {
-            type: "choice",
-            instructions:
-              "Which label best describes new_message from Lead's point of view? Use recent_thread_messages to tell who it is talking to. Lines starting with [Agent] are swarm bots.",
-            criteria: REASONS,
-          },
+      questions: {
+        reason: {
+          type: "choice",
+          instructions:
+            "Which label best describes new_message from Lead's point of view? Use recent_thread_messages to tell who it is talking to. Lines starting with [Agent] are swarm bots.",
+          criteria: REASONS,
         },
-      }),
-      signal: controller.signal,
+      },
+      timeoutMs: Math.max(budgetMs, MIN_DECIDE_TIMEOUT_MS),
+      maxRetries: 0,
     });
-    if (!res.ok) throw new Error(`${transport.provider} ${res.status}`);
-    const body = (await res.json()) as {
+    // After a timeout nobody awaits the call; its late failure must not go unhandled.
+    call.catch(() => {});
+    const res = (await Promise.race([call, stop])) as {
+      success?: boolean;
+      status?: number;
+      data?: unknown;
+    } | null;
+    const body = (res?.data ?? res) as {
+      success?: boolean;
+      message?: unknown;
+      error?: unknown;
+      providerUnavailable?: unknown;
       answers?: { reason?: { choice?: unknown; confidence?: unknown; probabilities?: unknown } };
     } | null;
+    if (res?.success === false || body?.success === false) {
+      const why = `${target.provider}: ${String(body?.message ?? body?.error ?? `HTTP ${res?.status}`).slice(0, 200)}`;
+      throw body?.providerUnavailable === true
+        ? new ProviderUnavailableError(why)
+        : new Error(why);
+    }
     const answer = body?.answers?.reason;
     const reason = typeof answer?.choice === "string" ? answer.choice : "";
     if (!(reason in REASONS)) throw new Error(`unexpected choice: ${String(reason).slice(0, 60)}`);
@@ -392,12 +420,34 @@ export const askJev = async (
     return { reason, confidence, probabilities, latencyMs: Date.now() - t0 };
   } finally {
     clearTimeout(timer);
-    outer?.removeEventListener("abort", onOuterAbort);
+    if (onOuterAbort) outer?.removeEventListener("abort", onOuterAbort);
   }
 };
 
+/**
+ * `askModel` on each target in turn, moving on only when the server refused the
+ * provider for a deployment setting (no request was sent). Any other failure, or
+ * a refusal of the last target, throws.
+ */
+export const askFirstAvailable = async (
+  swarm: Swarm,
+  input: Parameters<typeof askModel>[1],
+  targets: readonly DecisionTarget[],
+  cfg: Cfg,
+  outer?: AbortSignal,
+): Promise<{ verdict: Verdict; target: DecisionTarget }> => {
+  for (const [i, target] of targets.entries()) {
+    try {
+      return { verdict: await askModel(swarm, input, target, cfg, outer), target };
+    } catch (err) {
+      if (!(err instanceof ProviderUnavailableError) || i === targets.length - 1) throw err;
+    }
+  }
+  throw new Error("no decision provider");
+};
+
 /** Probability that the message needs no reply: the summed mass of the skip labels. */
-export const skipProbability = (verdict: JevVerdict): number | null => {
+export const skipProbability = (verdict: Verdict): number | null => {
   if (verdict.probabilities) {
     let sum = 0;
     for (const [label, p] of Object.entries(verdict.probabilities)) {
@@ -408,9 +458,9 @@ export const skipProbability = (verdict: JevVerdict): number | null => {
   return verdict.confidence;
 };
 
-/** Map a Jev verdict to the typed decision. An unsure skip verdict replies. */
+/** Map a verdict to the typed decision. An unsure skip verdict replies. */
 export const decide = (
-  verdict: JevVerdict,
+  verdict: Verdict,
   minConfidence: number,
 ): { reply: boolean; reason: Reason; skipP: number | null; lowConfidence: boolean } => {
   const reason = verdict.reason as Reason;
@@ -507,7 +557,7 @@ const extension: SwarmExtension = (api) => {
         return;
       }
 
-      const transport = resolveTransport(cfg);
+      const targets = resolveProviders(cfg);
 
       const sender =
         opts.slackUserId && cfg.botSlackUserIds.includes(opts.slackUserId)
@@ -516,14 +566,15 @@ const extension: SwarmExtension = (api) => {
             ? "human (known teammate)"
             : "unknown (not a known teammate; may be a bot or an external person)";
 
-      const verdict = await askJev(
+      const { verdict, target } = await askFirstAvailable(
+        ctx.swarm,
         {
           messages,
           context: context.slice(-cfg.contextMessages).map((m) => m.slice(0, 500)),
           sender,
           leadNames: cfg.leadAliases,
         },
-        transport,
+        targets,
         cfg,
         ctx.signal,
       );
@@ -542,7 +593,7 @@ const extension: SwarmExtension = (api) => {
           skipP: decision.skipP,
           lowConfidence: decision.lowConfidence,
           latencyMs: verdict.latencyMs,
-          provider: transport.provider,
+          provider: target.provider,
           sender,
           preview,
         },

package/templates/extensions/slack-reply-gate/manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "../manifest.schema.json",
   "name": "slack-reply-gate",
-  "description": "Asks Jev (TypeSafe or OpenRouter) whether Lead should answer a buffered Slack thread follow-up, and drops the wake-up when it should not",
-  "version": "1.2.0",
+  "description": "Asks a SystemOne decision model (Jev or Clef) whether Lead should answer a buffered Slack thread follow-up, and drops the wake-up when it should not",
+  "version": "1.3.0",
   "runtime": "api",
   "assets": { "hooks": "hooks.ts" }
 }

package/templates/official/lead/HEARTBEAT.md

@@ -11,5 +11,5 @@
 ## Tracked Items
 
 - Live items only: active blockers and watch items. Cap 10, 20 max during a surge; prune before you add.
-- Each item states its lift trigger and a calendar date (e.g. `lift when X; check 2026-08-22`).
+- Each item states its lift trigger and a calendar date as a bare `MM-DD` (e.g. `lift when X; check 08-22`) or `DELETE MM-DD`. A full `YYYY-MM-DD` stamp does not arm the gate.
 - An item closes: move its durable facts to memory, then delete the line. Never strike it through.

package/templates/skills/apps/SKILL.md

@@ -475,7 +475,7 @@ Param `kind` is `string` by default, or `number` / `boolean`; `required` default
 
 Within each page, `root` names one entry in its non-empty `elements` map. Elements are a flat, single-parent tree: ids are map keys, `children` contains ids (not nested elements), all elements must be reachable from `root`, and cycles, missing children, or shared children are invalid. Element and Form/UI ids are page-local. Element keys are `type`, `props`, `children`, `on`, `visible`, `repeat`, and `watch`; only components with a `default` child slot accept `children` (Stack, Grid, Split, Tabs, Container, Card, Section, and Drawer). `watch` maps state paths to an action step or chain.
 
-## Component catalog (all 33)
+## Component catalog (all 34)
 
 Props reject unknown keys. A `{"$state":"..."}` binding may replace a literal prop value at any depth.
 
@@ -485,9 +485,9 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
 
 | Component | Required props | Optional props / values |
 |---|---|---|
-| `Stack` | none | Primary layout; `direction: "column", "row"`, `gap`, `padding: "none", "xs", "sm", "md", "lg", "xl"`; `align: "start", "center", "end", "stretch"`, `justify: "start", "center", "end", "between"`, `wrap`; `motion: "rise"` (default), `"fade"`, or `"none"` (see Motion below); has the `default` child slot. |
+| `Stack` | none | Primary layout; `direction: "column", "row"`, `gap`, `padding: "none", "xs", "sm", "md", "lg", "xl"`; `align: "start", "center", "end", "stretch"`, `justify: "start", "center", "end", "between"`, `wrap`; `motion: "rise"` (default), `"fade"`, or `"none"` (see Motion below); `fill` (grow to fill a `fill`-aware parent; see Layout below); has the `default` child slot. |
 | `Grid` | none | Responsive `columns`: integer 1 through 6, or `{ base, sm, md, lg }` counts 1 through 6; `gap` uses the Stack spacing values; has the `default` child slot. |
-| `Split` | none | `ratio: "1-1", "1-2", "2-1", "1-3", "3-1"`, `gap`, `collapseBelow: "sm", "md", "lg"`, `reverse`; has the positional `default` child slot. |
+| `Split` | none | `ratio: "1-1", "1-2", "2-1", "1-3", "3-1"`, `gap`, `collapseBelow: "sm", "md", "lg"`, `reverse`, `fill` (same contract as Stack); has the positional `default` child slot. |
 | `Divider` | none | `label`; no children. |
 | `Tabs` | `id`, `tabs` | `tabs` entries are `{ key, label?, icon?, count? }` (`count` is a number shown as a small pill); `defaultTab`; `variant: "line"` (default) or `"segmented"` (a compact segmented control, same state and warm panels); has the positional `default` child slot. |
 | `Container` | none | Legacy layout primitive; prefer Stack. `direction: "row", "column"`, `gap: "none", "sm", "md", "lg"`; has the `default` child slot. |
@@ -496,7 +496,8 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
 | `Text` | `content` | `tone: "default" or "muted"`. |
 | `Markdown` | `content` | Rendered Markdown for help, instructions, and rich prose; no children. |
 | `SearchInput` | `id` | `placeholder`, `label`, `shortcut` (one key, usually `"/"`: shows a keycap and focuses the field); writes debounced text to `/ui/<id>/value`; no children. |
-| `Select` | `id`, `options` | `options` are strings or `{ value, label?, icon?, hint? }`; `placeholder`, `label`, `clearable`, `searchable` (type to filter; on by default past 8 options), `searchPlaceholder`, `multiple`; writes a string or null to `/ui/<id>/value`, or with `multiple` a string array (empty = nothing picked); no children. |
+| `Select` | `id`, `options` | `options` are strings or `{ value, label?, icon?, hint? }`; `placeholder`, `label`, `clearable`, `searchable` (type to filter; on by default past 8 options), `searchPlaceholder`, `multiple`, `defaultValue` (seeds `/ui/<id>/value` once, before any interaction; a one-entry array with `multiple`); writes a string or null to `/ui/<id>/value`, or with `multiple` a string array (empty = nothing picked); no children. |
+| `NumberInput` | `id` | `label`, `placeholder`, `min`, `max`; a text field with a decimal keyboard that writes the parsed number to `/ui/<id>/value` on every change (no debounce), or null when the field is empty; non-numeric text (a bare `-` mid-edit, letters) leaves the stored value untouched; `min`/`max` clamp the stored value and the visible text snaps to it when the field loses focus; no children. |
 | `Chips` | `id`, `options` | Toggle chips for quick filters. `options` are strings or `{ value, label?, icon? }`; `multiple`; `label` (group name for screen readers). Writes a string or null to `/ui/<id>/value`, or a string array with `multiple`; pressing the selected chip clears it. |
 | `Button` | `label` | `variant: "default", "secondary", "outline", "ghost", "destructive", or "destructive-outline"` (use `destructive-outline` for standalone deletes); `disabled` (constant or bound boolean); `busyWith: "<actionName>"` swaps the label for a spinner while that custom action's `/actions/<name>/status` is `"running"` (presses are ignored), then shows a check and `successLabel` for about 1.5s when it turns `"ok"`; `icon`, `iconPosition: "start" or "end"`; `size: "sm", "default", or "lg"`; `shortcut` (one key, shown as a keycap, presses the button); `hint` (tooltip); dispatch with element-level `on.press`. |
 | `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: "up", "down", or "flat", label }`; `info` (explanation tooltip next to the label). |
@@ -515,17 +516,20 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
 | `Form` | `id`, `fields`, `onSubmit` | `title`, `submitLabel`; see below. |
 | `Drawer` | `param` | `title`, `description`, `side: "right" or "left"`, `size: "sm", "md" (default), "lg", or "xl"` (about 480/660/900/1010px at 1440px; grows with the viewport up to 640/960/1280/1600px; full width on phones), `actions` (sticky footer buttons; see below); has the `default` child slot. |
 | `DetailList` | `fields` | `data`, `emptyMessage`, `columns: 1 or 2`, `loading` (bind `/queries/<name>/loading` for skeleton fields while loading); renders one record without edit controls; see below for field kinds. |
+| `CardGrid` | `titleKey` | `data`, `loading`, `error`, `emptyMessage`, `imageKey`, `fields`, `columns`, `onClick`; one card per row for record browsers; see below. |
 | `Kanban` | `columnField`, `columns`, `titleField` | `data`, `loading`, `cardFields`, `idField` (default `id`), `onMove`, `onCardClick`; see below. |
 | `Calendar` | `startField`, `titleField` | `data`, `loading`, `endField`, `idField`, `onSelect`; read-only month grid; see below. |
 | `ContributionGraph` | none | `data`, `loading`, `dateField` (default `date`), `countField`, `days` (7-730, default 365); read-only activity heatmap. |
+| `Tree` | `id`, `nodes` | `label`, `maxHeight` (default `480px`), `fill`; collapsible outline of a doc-shaped value that writes the clicked node key to `/ui/<id>/value`; see below. |
 
 Table details:
 
-- `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: "left" or "right", align?: "start" or "end", truncate?: "end" or "middle", icon?, tooltip?: "<row field>", max?: number, onChange?: chain }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, `link`, or `json`; `string` and `enum` render as text, and `json` renders a truncated single-line `JSON.stringify` preview. Pin id/actions columns so they survive horizontal scroll on narrow viewports.
+- `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: "left" or "right", align?: "start" or "end", truncate?: "end" or "middle", icon?, tooltip?: "<row field>", max?: number, format?: "<template>", onChange?: chain }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, `link`, or `json`; `string` and `enum` render as text, and `json` renders a truncated single-line `JSON.stringify` preview. Pin id/actions columns so they survive horizontal scroll on narrow viewports.
   - `status`: lifecycle values (`pending`, `in_progress`, `running`, `completed`, `failed`, `cancelled`, `paused`, `reviewing`, ...) render the dashboard status chip with its icon; other values use `tones` like `badge`.
   - `user` / `agent`: avatar plus name. `relative` (and `date`): smart time, exact time on hover. `duration`: milliseconds as `1m 23s`. `progress`: a bar against `max` (default 100). `copy`: the value plus a copy button. `link`: an http(s) URL opening in a new tab (other values render as text).
   - `switch`: a toggle. `onChange` runs with `$row` = the row with this column already set to the new value, e.g. `[{ "action": "app.mutate", "params": { "model": "m", "op": "update", "rowId": { "$row": "id" }, "values": { "enabled": { "$row": "enabled" } } } }]`. Without `onChange` the switch is read-only.
   - Numbers, durations and progress right-align by default. `truncate: "middle"` keeps both ends of ids and paths. `icon` shows in the header; `tooltip` names a row field shown on hover.
+  - `format`: a `{{field}}` template that combines several row fields into one cell, e.g. `"{{name}} ({{status}})"`. Placeholder names match `[\w.]+` (letters, digits, `_` and `.`; no hyphens or spaces). Each placeholder reads that row field as-is (a dotted name such as `{{owner.name}}` is a literal column name, not a nested path); a missing or null field becomes an empty string and an object or array becomes a JSON preview cut to 120 characters. The whole cell is capped at 500 characters. A templated column ignores `kind`, shows the same text in the phone list, and sorts by the composed text. `search` and `filters` still read the column's `key`.
 - `onRowClick`: action chain with `$row` / `$rowIndex`, run when a row is clicked (or Enter on a focused cell). Pair it with `app.navigate` that sets a Drawer param, and bind `selectedId` to `{ "$state": "/route/params/<param>" }` so the open row stays highlighted. `rowId` names the id field (default `id`).
 - Phones (below 768px): the table renders as a card list. `mobileFields: { title, subtitle?, meta?: string or string[], status? }` picks the columns; by default the first text column is the title and the first `status`/`badge` column the chip. `mobile: "scroll"` keeps the grid; it is the default when the table has `rowActions` but no `onRowClick`.
 - `emptyState: { icon?, title, body? }` replaces the plain empty message. A search or filter that hides every row shows its own "No rows match" state.
@@ -550,6 +554,12 @@ ContributionGraph details:
 
 - Buckets `data` rows by the calendar day of `dateField` over the trailing `days`. Each row counts 1, or adds its numeric `countField` when set.
 
+Tree details:
+
+- `nodes` is a doc-shaped value: `{ root: string | string[], elements: { <key>: { type, children?: string[] } } }`, the json-render flat element map. Usually bind it to a json column: `{ "$state": "/queries/<name>/data/0/<column>" }`. A malformed or absent value renders an empty state; a `children` key missing from `elements` shows as `key — ?`. Outlines are cut at 2,000 rows with a notice; branches deeper than 32 levels keep a disabled chevron.
+- Each row shows `key — type`. Clicking a row writes its key to `/ui/<id>/value`, and the row bound to that path renders selected; read the selection with `{ "$state": "/ui/<id>/value" }`. The Tree never writes `null`: when the selected key leaves the doc (a refetch, an edit) the stored key stays and no row renders selected. Selection and collapse are keyed by node key, so a key reachable through two parents selects and collapses in both places.
+- Rows scroll inside `maxHeight` (default `480px`). Set `fill: true` inside a `fill` Stack or Split pane to grow to that height instead and scroll within it (ignores `maxHeight`).
+
 Form details:
 
 - `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, or `enum`, and enum fields need `options`.
@@ -569,6 +579,16 @@ Motion details:
 
 - Every `Stack` fades its direct children in and lifts them 4px over 200ms on first paint, staggered 30ms (capped at the 10th child). It never replays on the 5s data poll. A Stack nested inside another one does not add its own entrance. `motion: "fade"` drops the lift; `motion: "none"` turns it off. Viewers with reduced motion get a 150ms fade.
 
+CardGrid details — the visual counterpart to Table for record browsers (projects, documents, media):
+
+- `titleKey` (required) picks the row field shown as the card title (an object value shows a JSON preview; titles are capped at 500 characters).
+- `imageKey` (optional) picks a row field holding an absolute http(s) image URL and adds an image tile to every card. When it is set, a non-URL value, a missing value, or a failed load shows a placeholder tile. Omit it for text-only cards with no tile.
+- `fields[]`: `{ key, kind?, tones? }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge` (with `tones`), or `json` (no `label`, no `format`). A field with no `kind` whose value is an object renders like `json`. They render as an unlabeled `·`-joined meta line under the title, e.g. a `date` field for "created" and a `text` field for the author.
+- `columns`: same responsive shorthand as `Grid.columns` (default `{ "base": 1, "sm": 2, "md": 3 }`).
+- `onClick`: an action chain with `$row` / `$rowIndex`, run when a card is clicked or activated with Enter or Space. Commonly `app.navigate` into a detail page, the CardGrid equivalent of Table's `onRowClick`.
+- Bind `data` / `loading` / `error` to a named query like Table. Loading shows skeleton cards, an error shows a callout, and no rows shows `emptyMessage`.
+- It renders 200 cards at a time with a Show more button below the grid that reveals the next 200.
+
 Shortcut details:
 
 - `Button.shortcut` and `SearchInput.shortcut` are one key. Letters and digits match without Shift; symbols such as `/` and `?` match as typed. They do nothing while focus is in a text field, while Ctrl, Cmd, or Alt is held, or while a dialog or menu is open (unless the control is inside it, such as a Button in an open Drawer).
@@ -577,9 +597,11 @@ Shortcut details:
 
 Use `Stack` as the primary page and section layout; `Container` is the legacy two-prop primitive retained for existing pages. Stack supports vertical or horizontal flow, shared spacing, alignment, justification, wrapping, and padding; row Stacks (filter bars, button rows) should set `collapseBelow: "sm"|"md"|"lg"` so they stack vertically on phones. Use `Grid` for responsive card or metric strips: a bare column count is responsive shorthand (1 column on phones, 2 from `sm`, the count from `md` up), or pin breakpoints explicitly with `{ "base": 1, "md": 2, "lg": 3 }`. `Grid` and `Split` also accept `padding` on the shared spacing scale.
 
+`Stack` and `Split` size to their content by default, so a page scrolls as a whole. Set `fill: true` to make one grow to fill the remaining height of a `fill`-aware parent (another `fill` Stack or Split) instead; chain it from the page root down through every container on the path to the element that should scroll, and that element scrolls within whatever height is left while the page itself does not. A non-`fill` sibling (a toolbar, a header) keeps its natural height and the `fill` sibling absorbs the rest. A `fill` Split stretches both panes to the full row height, so nesting a `fill` Split inside one pane of another `fill` Split is the way to build a three-or-more column viewport-height layout (`ratio` is only ever two panes).
+
 `Split` and `Tabs` children are positional. For Split, `children[0]` is the first pane, `children[1]` is the second, and extra children append inside the second pane. Below `collapseBelow`, panes stack; `reverse` changes only that narrow-layout stacking order. For Tabs, `children[i]` is the body for `tabs[i]`; keep both arrays in the same order and with the same count. Inactive tab children stay mounted but hidden, so Tables keep polling. Use `Divider` to separate sections and `Markdown` for richer explanatory content.
 
-SearchInput, Select, and Chips are client-side controls: each needs a literal `id` and writes state under `/ui/<id>/value`; Tabs writes its active key to `/ui/<id>/tab`. Bind those values into a Table's `search` and `filters` props. This filters already-polled rows locally; it does not alter or re-run the named query.
+SearchInput, Select, NumberInput, Chips, and Tree are client-side controls: each needs a literal `id` and writes state under `/ui/<id>/value` (Tree writes the clicked node key); Tabs writes its active key to `/ui/<id>/tab`. Bind those values into a Table's `search` and `filters` props. This filters already-polled rows locally; it does not alter or re-run the named query.
 
 ```json
 {
@@ -645,6 +667,8 @@ Only inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, o
 | `{ "$form": "title" }` | One current Form value. |
 | `{ "$form": "" }` | All current Form values. |
 | `{ "$state": "/queries/allIdeas/data" }` | Current value at a valid app state path, including action state such as `/actions/refreshIssues/status`. |
+| `{ "$chain": "leafTaskId" }` | One chain-scope value, published by a component that runs a task chain; it carries `leafTaskId` and `newTaskId`. Where no chain scope is published, the sentinel is left in place and the action fails instead of silently dropping the parent. |
+| `{ "$chain": "" }` | The whole chain scope. |
 
 Each sentinel object must contain exactly the single key shown.
 
@@ -652,7 +676,7 @@ An action-chain step is `{ "action": "<type>", "params": {...} }`. Available act
 
 - `app.mutate`: `{ model, op, rowId?, values?, formId? }`, where `op` is `"create"`, `"update"`, or `"delete"`. `update`/`delete` require `rowId` (usually `{ "$row": "id" }`, or `{ "$state": "/route/params/<param>" }` in a Drawer footer); literal `values` keys must be model columns. Successful mutation refetches all queries on that model.
 - `app.refresh`: `{ query? }`; omit `query` to refetch all, or name a declared query.
-- `app.action`: `{ name, input? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { "$row": "" } }`.
+- `app.action`: `{ name, input?, parentTaskId? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { "$row": "" } }`. `parentTaskId` chains the created task under an existing one for task-kind actions (typically `{ "$chain": "leafTaskId" }`; a literal or `$state` task id also works); a script or sync action rejects it with 400.
 - `app.navigate`: `{ page, params? }`; `page` must be declared, supplied keys must be params of the target page, and every required target param must be supplied. `params` replace the current route params wholesale and may contain action sentinels. Navigation pushes history, so browser Back returns to the previous page/params; only `mode` is preserved automatically.
 - `ui.toast`: `{ message, description?, tone?, undo? }`, where `tone` is `"success"`, `"error"`, `"info"` (default), or `"warning"`. `undo: { label?, actions }` adds an Undo button (default label `Undo`) that runs `actions` as a chain; its steps are validated like any chain. Put it after the step it confirms, e.g. a row delete followed by `{ "action": "ui.toast", "params": { "message": "Order deleted", "undo": { "actions": [{ "action": "app.mutate", "params": { "model": "order", "op": "create", "values": { "title": { "$row": "title" } } } }] } } }`. Undo params resolve `$state` when Undo is pressed; `$row` / `$form` resolve when the toast is shown.
 - `swarm.sdk`: `{ sdk, args? }`; invokes a catalog-supported Swarm browser SDK method with the viewer's bearer.