@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/templates/skills/apps/content.md

@@ -1,6 +1,6 @@
 # Swarm Apps
 
-Swarm Apps are persistent, agent-authored internal applications: a schema-backed row store, named queries, custom script/task actions, and a validated json-render interface served at `/apps/<id>`. Use an app when people need to view and change live records; use `create_page` for a static snapshot and `artifacts` for custom server logic or a UI outside this catalog.
+Swarm Apps are persistent, agent-authored internal applications: a schema-backed row store, named queries, custom script/task actions, and a validated json-render interface served at `/apps/<id>`. Use an app when people need to view and change live records; use `create_page` for a static snapshot.
 
 > **Capability gate**: app tools are available when the server's `CAPABILITIES` includes `pages` (for example `CAPABILITIES=core,task-pool,pages`). There is no separate `apps` capability. If these tools are absent from your MCP list, this is why.
 
@@ -425,50 +425,71 @@ Drawer variant: declare a route param on the containing page, set the Drawer `pr
 
 Param `kind` is `string` by default, or `number` / `boolean`; `required` defaults to false. The names `mode`, `apiUrl`, `apiKey`, `email`, and `name` are reserved. `/apps/<id>` renders `defaultPage`; `/apps/<id>/p/<page>?issueId=42` is the shareable deep link for another page. Browser navigation is client-side, so app state and polled data stay warm across page changes.
 
-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, and Drawer). `watch` maps state paths to an action step or chain.
+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 23)
+## Component catalog (all 33)
 
 Props reject unknown keys. A `{"$state":"..."}` binding may replace a literal prop value at any depth.
 
+Icons: every `icon` prop (and the `Icon` block) takes one name from a curated lucide set: `plus`, `refresh-cw`, `search`, `filter`, `download`, `upload`, `external-link`, `copy`, `check`, `x`, `trash-2`, `pencil`, `eye`, `calendar`, `clock`, `user`, `users`, `bot`, `git-pull-request`, `git-branch`, `github`, `slack`, `mail`, `link`, `file-text`, `folder`, `database`, `zap`, `sparkles`, `flag`, `star`, `tag`, `alert-triangle`, `info`, `circle-check`, `trending-up`, `trending-down`, `dollar-sign`, `activity`, `rocket`. Any other name is rejected.
+
+Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `error`, `info`, `pending`, `warning`, or `paused`.
+
 | 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`; 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); 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. |
 | `Divider` | none | `label`; no children. |
-| `Tabs` | `id`, `tabs` | `tabs` entries are `{ key, label? }`; `defaultTab`; has the positional `default` child slot. |
+| `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. |
 | `Card` | none | `title`, `description`; has the `default` child slot. |
 | `Heading` | `text` | `level: "h1", "h2", or "h3"`. |
 | `Text` | `content` | `tone: "default" or "muted"`. |
 | `Markdown` | `content` | Rendered Markdown for help, instructions, and rich prose; no children. |
-| `SearchInput` | `id` | `placeholder`, `label`; writes debounced text to `/ui/<id>/value`; no children. |
-| `Select` | `id`, `options` | `options` are strings or `{ value, label? }`; `placeholder`, `label`, `clearable`; writes a string or null to `/ui/<id>/value`; no children. |
-| `Button` | `label` | `variant: "default", "secondary", "outline", "ghost", "destructive", or "destructive-outline"` (use `destructive-outline` for standalone deletes); `disabled` (constant or bound boolean); `busyWith: "<actionName>"` disables and spins while that custom action's `/actions/<name>/status` is `"running"`; dispatch with element-level `on.press`. |
-| `Metric` | `label`, `value` | `value` is string or number; bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads. |
-| `Alert` | `message` | `title`, `tone: "info", "success", "warning", or "error"`. |
-| `Badge` | `text` | `text` is string or number; `tone: "neutral", "success", "active", "error", "info", "pending", "warning", or "paused"`. |
-| `Table` | `columns` | `data`, `loading`, `error`, `emptyMessage`, `rowActions`, `search`, `filters`; see below. |
+| `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. |
+| `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). |
+| `Alert` | `message` | `title`, `tone: "info", "success", "warning", or "error"`, `icon` (overrides the tone icon), `actionLabel` (a button inside the callout that emits `press`; wire it with `on.press`). |
+| `Badge` | `text` | `text` is string or number; `tone`; `icon` replaces the dot; `variant: "tag"` (default uppercase chip), `"status"` (sentence-case pill), `"count"` (numeric pill), or `"beta"` (the BETA tag); `status` (a lifecycle value renders the dashboard status chip); `hint` (tooltip; the beta tag's explanation). |
+| `Icon` | `name` | `size: "sm", "md", or "lg"`, `tone: "default", "muted", "success", "warning", "error", or "info"`, `label` (accessible name; decorative without it). |
+| `Progress` | `value` | `max` (default 100), `tone`, `label`, `variant: "bar"` (default) or `"ring"` (the dashboard progress ring; ignores `tone`), `showValue` (default true: percent for a bar, `value / max` for a ring). |
+| `EmptyState` | `title` | `icon` (default inbox), `body`, `actionLabel` (a button that emits `press`; wire it with `on.press`). |
+| `CopyButton` | `value` | `value` is string or number; `label` is the visible text, icon-only without it. Renders nothing for an empty value. |
+| `Kbd` | `keys` | Keycaps, one per string (`["⌘", "K"]`). Display only. |
+| `Skeleton` | `shape` | `shape: "line", "block", "rows", "metric", or "card"`; `count` (1-20: lines, rows, tiles, or cards); `height` (px, `block` only, default 128). Show it with `visible` bound to a query's `loading`. |
+| `Spinner` | none | `variant: "ring", "ellipsis", or "bars"` (default: the dashboard spinner), `size: "sm" or "md"`, `label` (visible text and accessible name). |
+| `AvatarStack` | `users` | `users` are display names (initials avatars); `max` (default 4) before a `+N` count. Hover lists every name. |
+| `Section` | `title` | `description`, `collapsible`, `defaultOpen` (default true); has the `default` child slot. |
+| `Table` | `columns` | `data`, `loading`, `error`, `emptyMessage`, `emptyState`, `rowActions`, `onRowClick`, `selectedId`, `rowId`, `mobile`, `mobileFields`, `search`, `filters`; see below. |
 | `Form` | `id`, `fields`, `onSubmit` | `title`, `submitLabel`; see below. |
-| `Drawer` | `param` | `title`, `description`, `side: "right" or "left"`, `size: "sm", "md", "lg", or "xl"`; 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. |
+| `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. |
 | `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. |
 
 Table details:
 
-- `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: "left" or "right" }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, or `badge`; `string` and `enum` render as text. 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, onChange?: chain }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, or `link`; `string` and `enum` render as text. 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.
+- `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.
 - `pagination`: boolean; defaults to auto-enabling past 200 rows (set `false` to force one scroll region). `density: "compact"` tightens row height for dense readouts.
-- `rowActions[]`: `{ label, variant?, confirm?, actions }`. Variants add `destructive-outline` to the Button variants. `destructive` and `destructive-outline` confirm by default; customize with `{ "title": ..., "description": ..., "confirmLabel": ... }`, or use a bare `confirm` string as the dialog description (use `confirm: false` only for a reversible action).
+- `rowActions[]`: `{ label, variant?, icon?, placement?: "inline" or "menu", confirm?, actions }`. `placement: "menu"` moves the action into the row's More menu. Variants add `destructive-outline` to the Button variants. `destructive` and `destructive-outline` confirm by default; customize with `{ "title": ..., "description": ..., "confirmLabel": ... }`, or use a bare `confirm` string as the dialog description (use `confirm: false` only for a reversible action).
 - `search`: optional string; case-insensitive substring matching across the listed string and number columns. Bind a SearchInput value for client-side search.
-- `filters`: optional record of per-column string, number, boolean, or null values. Null, empty, or absent values disable one filter. Bind Select values for client-side equality filters.
+- `filters`: optional record of per-column string, number, boolean, null, or array values. An array means "the cell is one of these" (what a `multiple` Chips or Select writes). Null, empty strings, empty arrays, or absent values disable one filter. Bind Select or Chips values for client-side filters.
 
 Kanban details:
 
 - One card per `data` row, grouped by the row's `columnField` value. `columns[]` are plain strings or `{ id, label? }`, in display order; rows matching no column are hidden.
-- `cardFields[]` uses the DetailList field shape (`{ key, label?, kind?, tones? }`) for extra lines under the title.
+- `cardFields[]` uses the DetailList field shape (`{ key, label?, kind?, tones? }`, same kinds) for extra lines under the title.
 - `onMove` is an action chain run when a card is dropped in another column. `$row` is the moved row with `columnField` already set to the new column: `[{ "action": "app.mutate", "params": { "model": "deal", "op": "update", "rowId": { "$row": "id" }, "values": { "stage": { "$row": "stage" } } } }]`. Without `onMove`, cards cannot be dragged.
 - `onCardClick` is an action chain with `$row`; pair it with `app.navigate` and a `Drawer` to open a card.
 
@@ -490,10 +511,19 @@ Form details:
 Drawer details:
 
 - `param` must name a param declared on the containing page. The drawer is open exactly when `/route/params/<param>` has a non-empty value, so its open state survives refresh and is shareable. Its children mount only while open; closing it clears that param with history replacement.
+- `actions[]`: `{ label, variant?, icon?, confirm?, actions }`, rendered as buttons in a sticky footer under the scrolling body. Confirmation follows Table `rowActions`: destructive variants confirm by default, and a chain with an `app.mutate` delete always confirms. Chains have no `$row`; address the open record with `{ "$state": "/route/params/<param>" }`, for example `{ "action": "app.mutate", "params": { "model": "order", "op": "delete", "rowId": { "$state": "/route/params/panel" } } }`. Prev/next record navigation is not available.
 
 DetailList details:
 
-- `fields[]`: `{ key, label?, kind?, tones? }`. Kinds reuse Table formatting (`text`, `string`, `number`, `boolean`, `date`, `badge`, `enum`) and add `code` for monospace raw or JSON values. Bind `data` to one record, commonly `/queries/<detailQuery>/data/0`.
+- `fields[]`: `{ key, label?, kind?, tones? }`. Kinds reuse Table formatting (`text`, `string`, `number`, `boolean`, `date`, `badge`, `enum`) and the Table cell renderers (`status`: lifecycle chip or `tones` pill; `user`: avatar plus name; `relative`: smart time, exact on hover; `copy`: value plus copy button), and add `code` for a monospace block and `json` for a collapsible JSON tree (objects, or a string holding JSON). Bind `data` to one record, commonly `/queries/<detailQuery>/data/0`.
+
+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.
+
+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).
 
 ## Layout & interactivity
 
@@ -501,7 +531,7 @@ Use `Stack` as the primary page and section layout; `Container` is the legacy tw
 
 `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 and Select 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, 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.
 
 ```json
 {
@@ -550,7 +580,7 @@ Valid `$state` roots are:
 
 - `/queries/<declaredQuery>/...`
 - `/forms/<formId>/...`, where a `Form` element has that literal `props.id`
-- `/ui/<id>/...`, where a SearchInput, Select, or Tabs element has that literal `props.id` (SearchInput and Select use `/value`; Tabs uses `/tab`)
+- `/ui/<id>/...`, where a SearchInput, Select, Chips, or Tabs element has that literal `props.id` (SearchInput, Select, and Chips use `/value`; Tabs uses `/tab`)
 - `/actions/<declaredAction>/...`
 - `/route/page` for the active page name
 - `/route/params/<declaredParam>` for a param declared on the current page
@@ -572,10 +602,11 @@ Each sentinel object must contain exactly the single key shown.
 
 An action-chain step is `{ "action": "<type>", "params": {...} }`. Available action types:
 
-- `app.mutate`: `{ model, op, rowId?, values?, formId? }`, where `op` is `"create"`, `"update"`, or `"delete"`. `update`/`delete` require `rowId` (usually `{ "$row": "id" }`); literal `values` keys must be model columns. Successful mutation refetches all queries on that model.
+- `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.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.
 - `swarm.call`: `{ method, endpoint: "/api/...", body? }`, where `method` is `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, or `"PATCH"`; raw authenticated API call.
 
@@ -704,3 +735,10 @@ Create this with `app-upsert`:
 ```
 
 The tool returns `{ appId, url: "/apps/<id>" }`. Open that URL to verify the live UI, then continue with the read-patch-validate loop above.
+
+## View and screenshot a live app
+
+- An app renders at `<dashboard>/apps/<id>`. Two view modes are set by query string: `?mode=full` (full-viewport overlay with a slim header) and `?mode=chromeless` (only the rendered page, the embed surface). `app.navigate` keeps only `?mode`.
+- Logged-in browser: a fresh dashboard has no connection and redirects to /setup. Seed the localStorage key `agent-swarm-connections` with `{connections:[{id,name,apiUrl,apiKey}],activeId}`. Build the value from an env var and pipe it to `agent-browser eval --stdin`, so the key never reaches a command line. Reload, then pick a user in the "Who are you?" dialog.
+- Apps scroll inside an inner canvas, so a full-page screenshot captures only the viewport. Scroll the canvas or raise the viewport height. For mobile, set a 375px-wide viewport before the screenshot.
+- App definitions: `GET /api/apps` and `GET /api/apps/<id>` with the API key as Bearer.

package/templates/skills/chat-sdk/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "chat-sdk",
+  "displayName": "Chat SDK",
+  "slug": "chat-sdk",
+  "title": "Chat SDK",
+  "description": "Chat threads from Telegram, Slack (Chat SDK), Discord, and Teams. Use when a task carries a task:chat-sdk contextKey or a user asked through Telegram, Slack, Discord, or Teams. Covers what the swarm posts for you, `chat-reply`, markdown and length per platform, attachments, `chat-read-thread` limits, and channel routes with `register-chat-channel`.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": false,
+  "tags": ["chat", "telegram", "discord", "teams", "slack", "communication"]
+}

package/templates/skills/chat-sdk/content.md

@@ -0,0 +1,84 @@
+# Chat SDK
+
+The swarm receives messages from Telegram, Slack, Discord, and Microsoft Teams through the Chat SDK channel. A person mentions the bot or sends it a direct message, and the swarm creates a task for it. This skill tells you how to work on such a task.
+
+## How you know you are on a chat task
+
+- The task has `source: "chat"`, or it is a lead follow-up of one.
+- The task `contextKey` starts with `task:chat-sdk:`. The full form is `task:chat-sdk:<adapter>:<encoded thread id>`, for example `task:chat-sdk:telegram:555001`.
+- The task text holds the user's message. Later replies in the same thread arrive as follow-up tasks with the same `contextKey`, or as steering messages on your running task.
+- The user has four slash commands that never reach you as a task: `/help`, `/status`, `/cancel` and `/reset`. `/cancel` ends the thread's active tasks, yours included, with status `cancelled`. After `/reset` the next task has no parent task and no earlier thread context, so treat it as a new conversation.
+
+Use `get-task-details` to read the `contextKey` when you are not sure.
+
+## Reply with `chat-reply`
+
+`chat-reply { text }` posts to the thread your current task came from. It finds the thread from your task, so you do not pass ids.
+
+- Use it to ask the user a question you cannot answer yourself. Ask once, with all your questions together.
+- Use it for one short progress note when work takes more than a few minutes, such as "Started. This takes about 10 minutes."
+- Do not use it for receipts ("Got it", "On it"), and do not send many progress notes.
+- It works only on a task with a `task:chat-sdk:` contextKey. A session bound to a non-chat task does not see `chat-reply` at all, because the tool is left out of its tool list.
+
+## The final summary is posted automatically
+
+When your task ends, the swarm posts the task output to the thread:
+
+- Completed: your `store-progress` output.
+- Failed: a "Task failed." line, then the failure reason.
+- Cancelled: a "Task cancelled." line, then the reason when there is one.
+
+Do not post your final answer with `chat-reply` as well. The user would get it twice. Put the answer in the `store-progress` output and stop.
+
+The post is durable. If the platform is down, the swarm retries with backoff for up to 24 hours.
+
+## Markdown per platform
+
+Write plain, short markdown: bold, italic, inline code, code blocks, bullet lists, and links. Avoid tables, nested lists, and HTML.
+
+| Platform | What renders | Limit per message |
+|---|---|---|
+| Telegram | Bold, italic, code, code blocks, links, lists. No tables. | 4096 characters |
+| Discord | Bold, italic, code, code blocks, lists, headings, links. No tables. | 2000 characters |
+| Slack | Converted to Slack mrkdwn: bold, italic, code, lists, links. Tables do not render well. | 4000 characters |
+| Teams | Basic markdown: bold, italic, code, lists, links. | 20000 characters |
+
+The swarm splits longer text into several messages at line breaks. Long answers are hard to read in chat, so keep the answer short and put long material in an artifact or page, then post the link.
+
+## Attachments arrive as task attachments
+
+Files and images the user sends in the thread are stored as attachments of the task. The task text names them. Download them with the `download-task-attachment` skill. You cannot send files back to the thread in this version. Share a link instead.
+
+## `chat-read-thread` limits per platform
+
+`chat-read-thread { threadId, limit? }` returns the most recent messages of a thread, oldest first. The thread id is the adapter name plus the URI-decoded remainder of the contextKey. Telegram ids have no escaping, so `telegram:555001` stays as it is. Slack, Discord, and Teams ids contain `%3A` in the contextKey, so do not build the id by hand. `chat-reply` resolves the thread itself. For `chat-read-thread`, use the thread id returned by `chat-reply`, `chat-post`, or `chat-open-dm`. You can read the thread of your current task. Any other thread needs lead privileges.
+
+- Telegram has no history API. The SDK keeps the Telegram thread history it saw in the swarm database, capped at 100 messages and 7 days.
+- Teams needs the `Chat.Read.*` Graph permission on the bot. Without it, the call fails.
+- Slack and Discord return the platform history.
+
+The task text already holds the earlier swarm messages of the thread, so read the thread only when you need more.
+
+## Other tools
+
+- `chat-post { adapter, threadId | channelId, text }` posts outside your task's thread. Lead only. Use it only when the task asks you to message another thread or channel.
+- `chat-open-dm { adapter, userId }` returns the direct-message thread id for a user. Lead only. Then post to it with `chat-post`.
+
+## Leads: `register-chat-channel`
+
+By default every message addressed to the swarm goes to the lead. A lead can route one channel to a fixed agent or workflow:
+
+```
+register-chat-channel { adapter: "telegram", channelId: "telegram:-100123", agentId: "<agent id>" }
+register-chat-channel { adapter: "slack", channelId: "slack:C123", workflowId: "<workflow id>" }
+unregister-chat-channel { adapter: "telegram", channelId: "telegram:-100123" }
+```
+
+Give exactly one of `agentId` or `workflowId`. A `swarm#<agentId>` token in a message still wins over the route. A workflow mapping fires only for a bot mention or a DM; a plain reply in the subscribed thread does not start another run. Only the lead can call these tools.
+
+## Etiquette
+
+- Keep messages short. Chat is read on phones.
+- Never post secrets, tokens, internal URLs with credentials, or private data from other users. The swarm scrubs known secrets, but do not depend on it.
+- When you ask a question in a group, start with the user's name so they see it.
+- One question message is better than several.

package/templates/skills/composio-gmail/content.md

@@ -62,6 +62,13 @@ agent-swarm x composio POST /tools/execute/GMAIL_SEND_EMAIL \
 - `recipient_email` is the primary; add more via `extra_recipients` / `cc` / `bcc`.
 - **Sending is a write action** — only do it when the task explicitly asks.
 
+## Sender (From) and footer
+
+- A draft defaults to the connected account's primary address. Before you create drafts, list the account's verified send-as aliases and set From to the alias the requester prefers (requester profile or brief). Take the footer and signature domain from the same source.
+- Never set From to an alias that is not verified. Gmail rewrites it to the primary address.
+- After you create the drafts, check From as well as To and Subject on each one.
+- To fix existing drafts, update each draft in place with the alias. Draft ids stay the same, so there is no need to delete and recreate.
+
 ## Reply in a thread
 
 ```bash

package/templates/skills/composio-google-docs/content.md

@@ -67,7 +67,7 @@ agent-swarm x composio POST /tools/execute/GOOGLEDOCS_CREATE_DOCUMENT_MARKDOWN \
 2. Write the converted content to your own agent-fs namespace with a short
    provenance header naming the source document and import method.
 3. Resolve the destination org and drive from the environment or
-   `agent-fs stat <path> --json`; the `artifacts` skill documents the canonical
+   `agent-fs stat <path> --json`; the `agent-fs` skill documents the canonical
    storage and share-link workflow. Never copy org or drive IDs from an example.
 4. Read the stored file back and assert several markers: the title, a middle
    phrase, and the final sentence. A successful byte-count response alone does

package/templates/skills/email-domain-health/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "email-domain-health",
+  "displayName": "Email Domain Health",
+  "slug": "email-domain-health",
+  "title": "Email Domain Health",
+  "description": "Build a scheduled email domain health monitor: ask the user for domains, providers, test inbox, schedule and alert rules, then build a checks script (SPF, DKIM, DMARC, MX, provider records, blocklists with positive controls), a daily test send with score capture, bounce rate, run history in a Swarm App, and alerts only on a new red or a score drop. Orchestrates the swarm-scripts, apps, scheduling and composio-gmail skills.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": true,
+  "tags": ["email", "deliverability", "dns", "monitoring", "apps"]
+}

package/templates/skills/email-domain-health/content.md

@@ -0,0 +1,131 @@
+# Email Domain Health
+
+Build a monitor that tells a person, every working day, whether mail from their
+domains authenticates, lands, and stays off blocklists. It has four parts: one
+saved script (checks + test send), a Swarm App with run history, one or two
+schedules, and an alert that fires only when something gets worse.
+
+This skill decides **what** to build. The mechanics live in other skills; read
+them, do not re-derive them:
+
+- [[swarm-scripts]]: authoring, `script-upsert`, scope, connections, secrets.
+- [[apps]]: models, named queries, pages, row writes.
+- [[scheduling]]: `targetType: "script"` schedules, cron and timezone.
+- [[composio-gmail]] (or the user's own mail integration): the test send and
+  the bounce search.
+
+Full design notes and pitfalls: the "Email domain health" playbook on the docs
+site.
+
+## 1. Ask for requirements first
+
+Ask before building (one batched question, see [[ask-user]]). Do not guess any
+of these; a wrong selector or From address makes every later check wrong.
+
+| Ask | Why it matters |
+|---|---|
+| Domains to monitor, and which one is the envelope/bounce domain | One check set per domain; SPF is judged on the envelope domain. |
+| Sending providers per domain (Google Workspace, Microsoft 365, an ESP such as Resend, SES, Postmark) and each DKIM selector | DKIM is looked up at `<selector>._domainkey.<domain>`; there is no way to list selectors. |
+| The From address for the test send, and the integration that sends it (Composio Gmail, SMTP, ESP API) | The test must leave through the real path, alias included. |
+| Test inbox: mail-tester (free tier has a small daily cap) or an inbox the user owns | Decides how the score is captured. |
+| Schedule and timezone | Default: weekdays, morning, user's timezone. |
+| Alert channel and thresholds (score floor, bounce rate) | Defaults: score < 6/10, bounces >= 5% on >= 10 sends. |
+| History retention | Default 90 days of runs. |
+
+Read the answers back in one short message before you write code.
+
+## 2. Build the checks script
+
+One saved script with modes `send`, `check`, and optionally `backfill`. Keep
+domains, selectors, thresholds and ids in a config block at the top or in
+`args`, never scattered through the code.
+
+**DNS over HTTPS, two resolvers.** Query every record on two public DoH
+resolvers (for example dns.google and Cloudflare's JSON endpoint).
+NOERROR and NXDOMAIN are answers; SERVFAIL, REFUSED and timeouts are not.
+Same verdict on both: use it. Different verdicts: `warn` ("resolvers
+disagree", often propagation). One failed: use the other, note it. Both
+failed: `unknown`.
+
+**Checks per domain:**
+
+- SPF: exactly one `v=spf1` record, includes each provider, total DNS lookups
+  <= 10 (recurse `include:`/`redirect=`; warn at 9), ends `~all` or `-all`.
+- DKIM: TXT at each selector (follow a CNAME), non-empty `p=` (empty means
+  revoked), key length.
+- DMARC: exactly one `v=DMARC1` at `_dmarc.<domain>`, a `p=` tag, `rua=` (warn
+  without it).
+- MX: present and pointing at the expected provider.
+- Provider records the ESP documents (bounce subdomain SPF and MX, DKIM
+  CNAMEs).
+- Blocklists: domain lists such as Spamhaus DBL, SURBL, URIBL (details below).
+- Test-send result: score plus the SPF, DKIM and DMARC verdicts from the
+  receiver's headers.
+- Bounce rate: sent vs bounced in the last 24h from the sending mailbox,
+  excluding test sends.
+
+**Verdicts:** `ok`, `warn`, `red`, `unknown`. Overall = worst. `unknown` means
+"could not read", and it is **never** reported as clean.
+
+**Controls, not hope.** Every negative result needs a positive control in the
+same run:
+
+- Blocklists: before trusting a list, query its documented test entry
+  (`dbltest.com` on `dbl.spamhaus.org`, `test.surbl.org` on `multi.surbl.org`,
+  `test.uribl.com` on `multi.uribl.com`) on each resolver. Use the list only on
+  a resolver where the test entry answers "listed". Refusal codes
+  (`127.255.255.x` from Spamhaus, `127.0.0.1` from SURBL and URIBL) mean the
+  resolver is blocked: `unknown`.
+- Bounce rate: a whole-mailbox 24h count of 0 means the search failed:
+  `unknown`, not "0 bounces".
+- Test result page without a score yet: `unknown` for the first hour after the
+  send, then `red`.
+
+Return a `controls.ok` flag with the result so a run that read nothing cannot
+pass as green.
+
+**Send mode.** Send one realistic message (the same template and links real
+mail uses) to a fresh test address, through the user's integration. Read the
+sent message back and confirm the From header kept the address the user asked
+for. Store the pending test id in KV with a per-day key so a retry never
+sends twice.
+
+## 3. Build the app
+
+Use [[apps]]. Minimum models:
+
+- `run`: one row per run (time, overall, red/warn/unknown counts, score,
+  bounces, sent).
+- `check`: one row per check per run (history).
+- `current`: one row per `domain|check`, updated in place, with `since` = when
+  the status last changed.
+
+Optional per-domain views (`domainRun`, `domainCheck`) make tabs per domain
+cheap to render. Page: one tab per domain (problems first, raw record on
+hover), a score trend, and a collapsed "How it works". The script writes rows
+through the row endpoints; prune `run` and `check` rows older than the
+retention window.
+
+## 4. Schedule it
+
+Use [[scheduling]] with `targetType: "script"`, not an agent task that says
+"run the script". Two schedules: `send`, then `check` 10 to 15 minutes later
+in the user's timezone, so the test inbox has the message before the check
+reads it.
+
+## 5. Alert only on change
+
+Compare with the previous `current` rows. Alert when a check **turns** red, or
+the score drops below the floor after being above it. Never alert on a
+steady-state warn or an unknown. The message lists each new red with its raw
+detail and links the app. If the script's identity cannot post to the chosen
+channel, have it hand the message to an agent that can.
+
+## Done when
+
+- A manual `check` run returns every check, `controls.ok: true`, and writes
+  rows the app renders.
+- Every blocklist shows either a passing control or `unknown`, never a bare
+  "not listed".
+- One full scheduled send + check cycle has run and the score landed in `run`.
+- You reported the app link, script name and scope, and schedule ids.

package/templates/skills/kv-storage/content.md

@@ -287,8 +287,8 @@ value so you can detect a clobber.
 ## See also
 
 - The **`pages`** skill — companion skill for authed pages and `swarmSdk.kv`.
-- The **`artifacts`** skill — for anything too big or too binary for KV.
+- The **`agent-fs`** skill — for anything too big or too binary for KV.
 - `src/be/migrations/061_kv_store.sql` — schema (`kv_entries`)
 - `src/http/kv.ts` — REST handler + namespace resolution
 - `src/tools/kv/*` — MCP tool registrars
-- `src/artifact-sdk/browser-sdk.ts` — `swarmSdk.kv` for pages
+- `src/pages/browser-sdk.ts` — `swarmSdk.kv` for pages

package/templates/skills/pages/content.md

@@ -1,8 +1,8 @@
 # Pages — DB-backed Static Artifacts
 
 DB-backed static content (HTML or JSON) served by the API directly. Cheap,
-versioned, share-able by URL. The lighter-weight cousin of `artifacts` —
-no PM2, no tunnels, no port allocation, no `services` registry row.
+versioned, share-able by URL. No server process, no tunnel, no port
+allocation.
 
 A page should be a clean human-facing artifact, not a raw dump with a URL. This
 skill covers both halves: **how to publish** a page, and **the taste baseline**
@@ -13,7 +13,7 @@ every page should meet.
 > (e.g. `CAPABILITIES=core,task-pool,pages`). If the tool is missing from
 > your MCP list, this is why.
 
-## When to use Pages vs Artifacts
+## When to use Pages vs Apps
 
 | You need… | Use |
 |---|---|
@@ -21,12 +21,11 @@ every page should meet.
 | A JSON status payload + a few buttons that call swarm APIs | **Pages** (`contentType: 'application/json'`) |
 | To share an output via a URL with no server logic | **Pages** |
 | Analysis that should be linkable and bookmarkable | **Pages** |
-| Custom routes, websockets, server-side logic | The **`artifacts`** skill |
-| File uploads or per-request computation | The **`artifacts`** skill |
+| Persistent records, queries, and server-side actions | The **`apps`** skill |
+| Large or binary files (PNG, MP4, exports) | The **`agent-fs`** skill |
 
 Rule of thumb: if the content is a snapshot (you can write the full HTML/JSON
-in a single call), use pages. If the content is a *running program*, use
-artifacts.
+in a single call), use pages. If it needs stored data and actions, use apps.
 
 Do **not** use pages for:
 
@@ -533,9 +532,8 @@ human-facing summary.
 
 ## See Also
 
-- The **`artifacts`** skill — durable storage (agent-fs, shared workspace) plus
-  full custom Hono apps with PM2 + a tunneled subdomain. Use it for interactive
-  servers, not static content.
+- The **`apps`** skill — schema-backed records, named queries, and actions.
+- The **`agent-fs`** skill — durable file storage and share links.
 - The **`kv-storage`** skill — page-scoped state via `swarmSdk.kv`.
 - `runbooks/secret-scrubbing.md` — egress scrubbing details.
 - SPA listing: `${APP_URL}/pages` — the same `APP_URL` used for share links above.

package/templates/skills/qa-loom/config.json

@@ -0,0 +1,14 @@
+{
+  "category": "skills",
+  "description": "Narrated QA loom for UI work: record a UI QA pass with agent-browser and a timestamped step log, voice it with ElevenLabs, burn one-line subtitles with ffmpeg, and embed the narrated mp4 (plus an optional GIF preview) in the PR as GitHub user attachments. Use on UI-changing PRs and UI QA passes. Layers on the `qa` and `agent-browser` skills. Needs ELEVENLABS_API_KEY, ffmpeg with libass, and agent-browser.",
+  "displayName": "QA Loom",
+  "kind": "skill",
+  "name": "qa-loom",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "slug": "qa-loom",
+  "systemDefault": true,
+  "tags": ["qa", "video", "screen-recording", "evidence", "elevenlabs"],
+  "title": "QA Loom",
+  "version": "1.0.0"
+}