@desplega.ai/agent-swarm 1.91.0 → 1.92.1

package/templates/skills/pages/content.md

@@ -1,85 +1,235 @@
 # Pages
 
-Pages are persistent, shareable HTML documents created via the swarm's `create_page` MCP tool. Use them when the output benefits from layout, tables, headers, and persistent sharing — unlike Slack messages, pages don't expire and can be bookmarked.
+Pages are persistent, shareable HTML documents created via the swarm's page tooling. Use them when the output benefits from layout, tables, headers, and persistent sharing. A page should be a clean human-facing report, not a raw dump with a URL.
+
+This skill covers both how to publish and how to design the page. It distills the current external design guidance from Anthropic's `frontend-design`, Vercel's `composition-patterns`, and Vercel's `web-design-guidelines`: start from content hierarchy, use a small spacing system, keep typography readable, prefer restraint over decoration, and make responsive behavior intentional.
 
 ## When to Create a Page
 
 - A report, dashboard, or summary that benefits from structured layout
 - Analysis that should be linkable and bookmarkable
-- Results that need to be reviewed asynchronously (not in a Slack thread)
-- Content that's too long or rich for a `store-progress.output` string
+- Results that need to be reviewed asynchronously
+- Content that is too long or rich for a `store-progress.output` string
 
 Do NOT use pages for:
-- In-flight progress notes (use `store-progress.progress`)
-- Sensitive data (credentials, private customer data)
-- Large binary files (use agent-fs for PNG/MP4)
+
+- In-flight progress notes; use `store-progress.progress`
+- Secrets, private credentials, or unapproved personal data
+- Large binary files; use agent-fs for PNG/MP4
+- Raw verbose logs; summarize them and link to artifacts
+
+## Page Design Defaults
+
+Every page should be useful at a glance.
+
+- Put the page's point in the first viewport: title, one-sentence summary, and 3-6 key numbers or statuses.
+- Use a single-column reading spine with `max-width: 1120px`; keep prose measure around 65-75 characters.
+- Use system fonts unless there is a clear reason not to: `Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`.
+- Use a restrained palette: neutral background, high-contrast text, white panels, one accent color, and semantic colors for statuses only.
+- Use a consistent spacing scale: `8, 12, 16, 24, 32, 48, 72`.
+- Use clear type hierarchy: page title 36-48px desktop / 30-36px mobile, section titles 22-28px, body 15-16px, supporting text 13-14px.
+- Keep tables readable: sticky/scannable headers where useful, padded cells, zebra-free or very subtle row borders, `tabular-nums` for numbers, horizontal scroll on narrow screens.
+- Prefer cards only for repeated records or metrics. Do not nest cards inside cards.
+- Hide raw JSON behind a collapsed `<details>` block at the bottom.
+- Make mobile explicit with media queries: single-column grids, reduced padding, no overflow except intentional table scroll.
+
+## Content Structure
+
+Use this order unless the task gives a better domain-specific structure:
+
+1. Hero: title, short summary, timestamp/source context
+2. Key metrics: 3-6 tiles that answer "how big / how bad / what changed?"
+3. Findings or sections grouped by theme, owner, severity, or stage
+4. Evidence tables or samples under each finding
+5. Next actions or recommendations
+6. Raw evidence links / collapsed JSON appendix
+
+Write section headings as labels, not slogans. Favor "Critical Routing Gaps" over "Things We Found".
 
 ## Creating a Page
 
+Use the page tool with an HTML body. Prefer `contentType: "text/html"` and an explicit `authMode` for internal reports.
+
 ```javascript
-// Via MCP tool
-create_page({
-  title: "Q2 SEO Performance Report",
-  content: `<h1>Q2 SEO Performance</h1>
-<p>Analysis period: 2026-04-01 to 2026-06-30</p>
-<h2>Summary</h2>
-<table>
-  <tr><th>Metric</th><th>Q1</th><th>Q2</th><th>Change</th></tr>
-  <tr><td>Organic clicks</td><td>12,400</td><td>18,600</td><td>+50%</td></tr>
-</table>
-<h2>Next Actions</h2>
-<ul>
-  <li>Publish 3 new pillar pages targeting high-intent queries</li>
-  <li>Fix 23 pages with missing meta descriptions</li>
-</ul>`
-})
+const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Q2 SEO Performance</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --bg: #f6f4f0;
+      --panel: #ffffff;
+      --ink: #18181b;
+      --muted: #62646a;
+      --line: #dedbd2;
+      --accent: #2563eb;
+      --danger: #b42318;
+      --warn: #b54708;
+      --ok: #067647;
+      --radius: 8px;
+      --shadow: 0 1px 2px rgba(24, 24, 27, 0.06), 0 12px 32px rgba(24, 24, 27, 0.07);
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--ink);
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      font-size: 16px;
+      line-height: 1.55;
+    }
+    main {
+      width: min(1120px, calc(100% - 32px));
+      margin: 0 auto;
+      padding: 48px 0 72px;
+    }
+    header { margin-bottom: 32px; }
+    .eyebrow {
+      margin: 0 0 8px;
+      color: var(--muted);
+      font-size: 13px;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+    }
+    h1 {
+      margin: 0;
+      max-width: 780px;
+      font-size: clamp(2rem, 4vw, 3rem);
+      line-height: 1.05;
+      letter-spacing: 0;
+    }
+    .lede {
+      max-width: 760px;
+      margin: 16px 0 0;
+      color: var(--muted);
+      font-size: 18px;
+    }
+    .metrics {
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 12px;
+      margin: 32px 0;
+    }
+    .metric, .section {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      box-shadow: var(--shadow);
+    }
+    .metric { padding: 18px; }
+    .metric strong {
+      display: block;
+      font-size: 32px;
+      line-height: 1;
+      font-variant-numeric: tabular-nums;
+    }
+    .metric span {
+      display: block;
+      margin-top: 8px;
+      color: var(--muted);
+      font-size: 13px;
+      font-weight: 650;
+    }
+    .section {
+      margin-top: 18px;
+      padding: 24px;
+    }
+    h2 { margin: 0 0 12px; font-size: 24px; line-height: 1.2; }
+    h3 { margin: 0 0 8px; font-size: 17px; line-height: 1.3; }
+    p { margin: 0 0 12px; }
+    .table-wrap { overflow-x: auto; border: 1px solid var(--line); border-radius: var(--radius); }
+    table { width: 100%; border-collapse: collapse; min-width: 640px; }
+    th, td { padding: 10px 12px; border-bottom: 1px solid var(--line); text-align: left; vertical-align: top; }
+    th { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em; }
+    td { font-size: 14px; }
+    code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    details { margin-top: 24px; }
+    summary { cursor: pointer; font-weight: 700; }
+    pre { overflow: auto; padding: 16px; background: #111827; color: #f9fafb; border-radius: var(--radius); }
+    @media (max-width: 760px) {
+      main { width: min(100% - 24px, 1120px); padding-top: 32px; }
+      .metrics { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+      .section { padding: 18px; }
+    }
+    @media (max-width: 520px) {
+      .metrics { grid-template-columns: 1fr; }
+      .lede { font-size: 16px; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <p class="eyebrow">Generated 2026-06-04</p>
+      <h1>Q2 SEO Performance</h1>
+      <p class="lede">Organic traffic grew sharply, but the next gains depend on fixing thin page metadata and publishing three high-intent pillar pages.</p>
+    </header>
+
+    <section class="metrics" aria-label="Key metrics">
+      <div class="metric"><strong>18.6k</strong><span>Organic clicks</span></div>
+      <div class="metric"><strong>+50%</strong><span>Quarter over quarter</span></div>
+      <div class="metric"><strong>23</strong><span>Metadata fixes</span></div>
+      <div class="metric"><strong>3</strong><span>Priority pages</span></div>
+    </section>
+
+    <section class="section">
+      <h2>Summary</h2>
+      <p>Start with the conclusion. Add tables only after the reader understands what changed and what to do next.</p>
+      <div class="table-wrap">
+        <table>
+          <thead><tr><th>Metric</th><th>Q1</th><th>Q2</th><th>Change</th></tr></thead>
+          <tbody><tr><td>Organic clicks</td><td>12,400</td><td>18,600</td><td>+50%</td></tr></tbody>
+        </table>
+      </div>
+    </section>
+  </main>
+</body>
+</html>`;
+
+await create_page({
+  title: "Q2 SEO Performance",
+  slug: "q2-seo-performance",
+  description: "Human-readable SEO performance report with summary metrics and next actions.",
+  contentType: "text/html",
+  authMode: "authed",
+  body: html,
+});
 ```
 
-Returns a page ID. Build the share URL:
-```
+Returns a page ID. Build share URLs from environment:
+
+```text
 ${APP_URL}/pages/<pageId>           # opens in SPA with chrome
 ${APP_URL}/pages/<pageId>?mode=full # slim header, full viewport
-${MCP_BASE_URL}/p/<pageId>          # direct HTML (no SPA)
+${MCP_BASE_URL}/p/<pageId>          # direct HTML
 ```
 
-Read `APP_URL` and `MCP_BASE_URL` from environment — never hardcode.
+Read `APP_URL` and `MCP_BASE_URL` from environment. Never hardcode localhost or example hosts in shared output.
 
-## Content Guidelines
+## Design Checklist
 
-**Keep raw evidence in artifacts and link to it.** The page should contain:
-1. **Short summary** (1 paragraph) — what this covers and the key finding
-2. **Source links** — links to the data, agent-fs artifacts, or upstream systems
-3. **Structured content** — tables, headers, numbered lists
-4. **Next actions** — what should happen next, who owns it
+Before publishing:
 
-Do NOT embed:
-- Secrets or private credentials
-- Personal data of individuals without approval
-- Raw verbose logs (summarize them)
+- The first viewport states what the page is, why it matters, and the key numbers.
+- The page has a clear hierarchy: `h1`, short lede, metrics, sections, evidence.
+- Body text is readable on mobile and desktop.
+- Tables scroll horizontally on mobile instead of crushing columns.
+- Status colors are semantic and not the whole visual identity.
+- Raw JSON/logs are collapsed or linked, not the primary experience.
+- No nested cards, decorative gradients, oversized hero art, or cramped default browser styles.
+- No text overlaps, clipped buttons, or unreadable low-contrast text.
 
-## Page vs. Agent-fs
+## Page vs Agent-fs
 
 | Use pages for | Use agent-fs for |
 |---|---|
 | Reports, dashboards, human-readable summaries | Markdown research notes, code files, recordings |
 | Content that benefits from HTML layout | Searchable knowledge base entries |
-| Quick share links to non-technical stakeholders | Binary artifacts (PNG, MP4) |
+| Quick share links to non-technical stakeholders | Binary artifacts such as PNG or MP4 |
 | Time-bounded deliverables | Long-lived reference documentation |
 
-## Sharing Pages
-
-Always use the platform share URL (from `APP_URL` env var) rather than hardcoded local hosts. Append `?mode=full` for a standalone view (hides sidebar/header — good for screenshots or embedding in Slack previews).
-
-```bash
-# Get the share URL
-PAGE_URL="${APP_URL}/pages/${pageId}?mode=full"
-
-# Post to Slack
-slack-reply --taskId <id> --message "Report ready: ${PAGE_URL}"
-```
-
-## Trade-offs
-
-**Pages vs Slack messages:** Slack messages are ephemeral and scroll out of view. Pages are persistent and bookmarkable. Use pages for anything you'd want to reference in 3 months; use Slack for in-the-moment communication.
-
-**Pages vs agent-fs:** Pages are rendered HTML with a share URL — great for non-technical stakeholders. Agent-fs files are raw content — great for other agents and developers who need the source data. For a research memo, write the source to agent-fs and create a page for the human-facing summary.
+For a research memo, write the source to agent-fs and create a page for the human-facing summary.

package/templates/skills/profile-corruption-escalation/content.md

@@ -1,105 +1,64 @@
 # Profile Corruption Escalation
 
-## STATUS: Root cause for the Picateclas corruption family was found and fixed in PR #374 (merged 2026-04-24)
+Use this skill when an agent's persisted profile (`SOUL.md`, `IDENTITY.md`, or equivalent DB fields) appears to be overwritten with placeholder, fixture, truncated, or otherwise invalid content.
 
-The 13-recurrence Picateclas corruption was traced to `src/tools/update-profile.ts:231` unconditionally writing `/workspace/SOUL.md` whenever `isUpdatingSelf=true`, plus the `update-profile-auth.test.ts` fixture setting a fake `WORKER_ID=bbbb0000-...` that satisfied the gate. The Stop hook then synced the corrupted file to DB. PR #374 fixed both:
-- `src/tools/update-profile.ts:231` — gated the file write on `requestInfo.agentId === process.env.AGENT_ID`
-- `src/hooks/hook.ts:359` — raised `IDENTITY_FILE_MIN_LENGTH` from 100 → 500 (defense in depth)
+## When to Use
 
-**14th restore** completed post-merge with a 1,930/2,065-char payload. If a **15th corruption** of Picateclas (or any agent) appears with the same sentinels post-2026-04-24, treat it as a **DIFFERENT code path**, not the same bug. Escalate immediately — do NOT just restore.
+- An agent profile contains sentinel text such as "Test Worker", "Updated by Myself", repeated padding, or another canned payload.
+- The profile is much shorter than the expected baseline.
+- A recently restored profile was overwritten again.
+- A hook, seeder, migration, test fixture, or profile-update tool may be writing to the wrong agent.
 
-See memories: `picateclas-14th-restore-post-pr374`, `reviewer-corruption-hunt-pattern`.
+## Triage Loop
 
-## When to use
+1. Capture the corrupted payload, agent ID, and `lastUpdatedAt` timestamp before changing anything.
+2. Search memory and recent task history for the same sentinel string or same agent.
+3. Grep the source repo for exact sentinel strings. Stable placeholder text usually points to a fixture, seed path, or test helper faster than manual restoration does.
+4. Inspect code paths that can write profile files or profile DB fields: profile-update tools, startup hooks, stop/session hooks, seeders, migrations, and tests that set agent identity env vars.
+5. If you find the writer, fix or escalate the code path before restoring the profile.
+6. Restore only after evidence is captured, and only if restoration will not destroy useful debugging evidence.
 
-You inspect `get-swarm` and find an agent's `soulMd` or `identityMd` field corrupted — short placeholder content, unusual sentinels ("Test Worker", "Updated by Myself", "xxx" padding to bypass 200-char minLength), or any canned payload that you've seen before.
+## Escalation Threshold
 
-## Step 0 — Sentinel-grep BEFORE counting recurrences
+Escalate instead of repeatedly restoring when any of these are true:
 
-Before applying the N-recurrence ceiling, **grep the agent-swarm repo for the literal sentinel strings**. The 13-recurrence Picateclas mystery was solved in 4m25s by grepping `"Test Worker"` — it should have happened at recurrence 2 or 3, not 13.
+- The same profile is corrupted more than once in a short period.
+- The sentinel text appears to come from code that knows schema limits or exact file paths.
+- You cannot identify the writer quickly.
+- A previous fix should already have eliminated this corruption family.
 
-Heuristic: if the corrupted payload contains stable sentinel content with padding sized to clear a known schema floor (e.g. exactly 200 chars to bypass `minLength=200`), the writer is **server-side code that knows the schema** — almost always a test fixture or seed script. Grep wins fast.
+## Escalation Package
 
-```
-grep -rn '"Test Worker"' /workspace/repos/agent-swarm/src
-grep -rn '"Updated by Myself"' /workspace/repos/agent-swarm/src
-```
-
-If you find the writer in <5 minutes, fix it (or open a PR) instead of restoring. That's the 1000× higher-value outcome.
+Post a concise report to the operator channel or issue tracker with:
 
-See memory `reviewer-corruption-hunt-pattern` for the full pattern.
+- Agent name and ID.
+- Fresh write timestamp.
+- Exact sentinel strings to search for.
+- Whether you already grepped the repo and what matched.
+- Suspected writer classes: hook, seeder, migration, test fixture, startup script, or profile-update tool.
+- Whether you restored the profile or left it corrupted as evidence.
+- Link to the task, log, or memory entry containing the captured payload.
 
-## The N-recurrence ceiling rule
+## Report Template
 
-Apply this only AFTER step 0 fails (sentinel grep returns nothing in the repo).
+```text
+Profile corruption detected
 
-Count prior corruptions of the same agent with the same sentinel. Consult memory first:
+Agent: <agent-name> (<agent-id>)
+Fresh write at: <timestamp>
+Sentinel strings:
+- "<literal-1>"
+- "<literal-2>"
 
-```
-memory-search "picateclas profile corruption"      # or whichever agent name
-```
-
-- **1st–12th occurrence**: Restore the profile (surgical update-profile with the agent's best-known-good SOUL/IDENTITY from your memory). Write a new `{agent}-{N}th-profile-corruption-{YYYY-MM-DD}` memory recording the state + escalation status.
-- **13th+ occurrence**: **STOP RESTORING.** Rebuild fatigue has proven the restore doesn't stick — the bug lives in code you don't control. Escalate instead.
-
-If you can't determine N from memory, treat anything ≥ 2 prior corruptions in < 7 days as "escalate now."
-
-**Post PR #374 (Apr 2026):** any new sentinel-payload corruption of any agent should be treated as recurrence 1 of a NEW bug — investigate fresh code paths, do not assume it's the same `update-profile.ts:231` issue.
-
-## Escalation package (what to post)
-
-Use `slack-post` to the ops channel. Include ALL of:
-
-1. **Sentinel payload strings as grep targets** — exact literals to search for in the source repo. Example: `"Test Worker"`, `"Updated by Myself"`, `xxxxx...` patterns. **State whether you already grepped (and what the result was).**
-2. **Proof of fresh write** — `lastUpdatedAt` timestamp from `get-swarm`, newer than the previous restore. Without this it could be stale state, not new corruption.
-3. **Corruption tally** — "N occurrences in ~M weeks, half-life now <24h."
-4. **Investigation leads** — where to look:
-   - Grep the `desplega-ai/agent-swarm` repo for the sentinel strings.
-   - Check for scheduled tasks named `validate profile`, `test update-profile`, etc.
-   - Check seed/migration scripts that run on container restart.
-   - Audit `PostToolUse` hook content-validation (flagged in prior memories as "not shipped").
-   - **Post PR #374:** Audit any other code path that writes `/workspace/SOUL.md` or `/workspace/IDENTITY.md` — the original bug was at `src/tools/update-profile.ts:231`; look for siblings.
-5. **What you did NOT do** — explicit "I did not perform the Nth restore. Profile is left corrupted in DB as evidence."
-
-## Template
-
-```
-:rotating_light: Profile Corruption — {N}th recurrence — escalation trigger fired
-
-Agent: {name} ({id})
-Fresh write at: {lastUpdatedAt}
-Tally: {N} corruptions in ~{M} weeks, half-life {<hours>}h.
-
-Sentinel grep targets (expect to find in source):
-- "Test Worker"
-- "Updated by Myself"
-- Long "xxxxx…" padding literals
-
-I already grepped: {summary of grep result, e.g. "no hits in src/ post-#374 — this is a NEW code path"}.
-
-Investigation leads:
-1. Grep agent-swarm for the sentinels above.
-2. Check for scheduled "validate profile" / "test update-profile" tasks.
-3. Audit seed/migration scripts on container restart.
-4. Audit any code path that writes /workspace/SOUL.md or /workspace/IDENTITY.md (original bug was update-profile.ts:231).
-
-I did NOT perform the {N}th restore. Profile is corrupted in DB as evidence. Waiting for engineering fix before next restore.
-
-See memory: {agent}-{N}th-profile-corruption-{date}
+Repo grep result: <matches or no matches>
+Suspected writer: <hook/seeder/migration/test/tool/unknown>
+Action taken: <restored profile | left as evidence | opened fix PR>
+Evidence: <task/log/memory link>
 ```
 
 ## Gotchas
 
-- **Work quality ≠ profile validity.** Even a corrupted profile worker ships working code because the persona/working-style lives more in CLAUDE.md + memory than in the short SOUL.md. Don't let "but the agent still works" push you to keep restoring — that masks the bug.
-- **Don't rewrite CLAUDE.md during restoration.** In this corruption family, CLAUDE.md has been stable through 12 cycles. Only SOUL/IDENTITY get touched. Restoring CLAUDE.md too is wasted work and risks overwriting real learnings.
-- **Rotate escalation target.** If you've already escalated to one person and no fix in a week, try a different channel (DM vs public, a different engineer, a Linear ticket). Slack-only escalation can get missed.
-- **Don't auto-retry.** After escalating, do not put the restore back on a schedule. The next restore waits for explicit human ack ("OK to restore now, code fix merged").
-- **Sentinel-grep first, escalate second.** If a 2nd recurrence happens and you haven't grepped the sentinel literal yet, you're escalating prematurely. Grep is cheap (<5 min) and usually wins.
-
-## Related
-
-- Memory family: `{agent}-Nth-profile-corruption-YYYY-MM-DD`
-- Memory: `reviewer-corruption-hunt-pattern` — the heuristic that solved the 13-recurrence mystery
-- Memory: `picateclas-14th-restore-post-pr374` — restore payload + the fix details
-- Lead rule #9 in CLAUDE.md: "Sentinel-grep before escalating recurring bugs"
-
+- Do not rely on repeated manual restores as the fix. They can hide the writer and destroy evidence.
+- Search exact sentinel strings before broad refactors; fixture text is usually distinctive.
+- Do not overwrite unrelated profile files during restoration.
+- Treat a recurrence after a code fix as a new investigation unless you can prove the same writer is still active.

package/templates/skills/script-workflows/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "script-workflows",
+  "displayName": "Script Workflows",
+  "slug": "script-workflows",
+  "title": "Script Workflows",
+  "description": "Launch and inspect durable one-off script workflow runs with journaled swarm-script, raw-llm, and agent-task steps.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": true,
+  "tags": ["scripts", "workflows", "automation"]
+}

package/templates/skills/script-workflows/content.md

@@ -0,0 +1,68 @@
+Use this skill when a user asks to launch, monitor, inspect, or debug a durable script workflow run. This is for the Script Workflows v1 runtime: one-off TypeScript workflow source with journaled `swarm-script`, `raw-llm`, and `agent-task` steps.
+
+## Tool Flow
+
+Load the script workflow tools with ToolSearch when they are not already visible:
+
+```text
+launch-script-run
+get-script-run
+list-script-runs
+```
+
+Use `launch-script-run` to start a one-off run. It calls the same `/api/script-runs` API as the dashboard, preserves the invoking agent identity, and starts the run in the background.
+
+Use `get-script-run` to read terminal status and journal entries. Poll it when needed, but keep polling bounded and report progress for long runs.
+
+Use `list-script-runs` to find recent runs or filter by `status` / `agentId`.
+
+Do not hand-roll raw HTTP for this flow unless the tool itself is broken and you are explicitly debugging the API. The tool handles auth and `X-Agent-ID` like the existing inline `script-run` tool family.
+
+## Source Shape
+
+Author TypeScript workflow source as a default export. The runtime provides `args` and `ctx`.
+
+```ts
+export default async function main(args, ctx) {
+  const lookup = await ctx.step.swarmScript("lookup-data", {
+    scriptName: "fetch-readable",
+    args: { url: args.url },
+  });
+
+  const summary = await ctx.step.rawLlm("summarize", {
+    prompt: `Summarize this for an operator:\n${JSON.stringify(lookup)}`,
+  });
+
+  const task = await ctx.step.agentTask("operator-review", {
+    task: `Review this summary and flag risks:\n${JSON.stringify(summary)}`,
+    tags: ["script-run"],
+    priority: 50,
+  });
+
+  return { lookup, summary, task };
+}
+```
+
+## Label Rules
+
+Step labels are durability keys. They must be stable and unique for each logical step. Do not reuse the same literal label inside a loop; launch will fail with `label_lint_violation`.
+
+For looped work, include an item identifier in the label:
+
+```ts
+for (const item of args.items) {
+  await ctx.step.agentTask(`review-${item.id}`, { task: item.prompt });
+}
+```
+
+## Statuses
+
+Terminal statuses to surface clearly:
+
+- `completed` — run finished and `output` may be present.
+- `failed` — run ended with `error`.
+- `cancelled` — run was cancelled before completion.
+- `aborted_limit` — runtime guardrail stopped the run, usually step count, agent-task count, or wall-clock cap.
+- `label_lint_violation` — launch-time rejection, not a persisted run status.
+
+When a run is not terminal, report the current status, journal count, and latest heartbeat if present.

package/templates/skills/sprite-cli/content.md

@@ -29,7 +29,7 @@ The org token is stored in swarm config as `SPRITES_API_KEY` (global, secret). S
 sprite auth setup --token "$SPRITES_API_KEY"
 ```
 
-Token format is `<org>/<account_id>/<token_id>/<secret>`. The first segment is the org (`desplega`).
+Token format is `<org>/<account_id>/<token_id>/<secret>`. The first segment is your organization slug.
 
 ## Core commands
 
@@ -45,9 +45,9 @@ Token format is `<org>/<account_id>/<token_id>/<secret>`. The first segment is t
 
 Flags: every command takes `-s <sprite>` (or sets a default via `sprite use`). `-o <org>` overrides the org if you have multiple.
 
-## Sandbox baseline (as of 2026-05-07)
+## Sandbox baseline
 
-- Ubuntu 25.10 (Questing Quokka), kernel 6.12.x-fly (firecracker microVM)
+- Ubuntu-based microVM image (exact version may change over time)
 - Non-root `sprite` user (uid 1001), passwordless `sudo`
 - No docker, no `/var/run/docker.sock`, no container runtime preinstalled
 - No systemd / init — `service` and `systemctl` won't work; start daemons manually with `sudo <daemon> &` or `nohup`
@@ -105,7 +105,7 @@ trap "sprite destroy test-$$ --force" EXIT INT TERM
 # … work …
 ```
 
-If a script crashes, `sprite list` shows what's still up. Sweep with `sprite list -o desplega` and destroy anything you don't recognize.
+If a script crashes, `sprite list` shows what's still up. Sweep with `sprite list -o <org>` and destroy anything you don't recognize.
 
 ## Setup script snippet
 
@@ -130,4 +130,3 @@ grep -q '/.local/bin' "$HOME/.bashrc" 2>/dev/null || echo 'export PATH="$HOME/.l
 - **Daemon survival:** `sprite exec` runs in a fresh subshell. A daemon backgrounded with `&` survives the exec call (sprites use a shared init), but if you want to be safe use `nohup`. To stop it, `sprite exec -s … -- sudo pkill <daemon>`.
 - **Port forwarding:** ports inside the sprite are not exposed to your swarm container. Curl from *inside* the sprite (`sprite exec -s … -- curl localhost:5432`) — not from your container.
 - **Don't leak secrets:** treat the sprite as an untrusted host. Don't put production tokens in there.
-

package/templates/skills/swarm-scripts/content.md

@@ -66,14 +66,13 @@ Good named scripts:
 
 For scripts that aggregate over tasks, sessions, or memory, `ctx.swarm.db_query` with direct SQL is far more efficient than fetching lists client-side.
 
-**The parameter is `sql`, not `query`:**
+**The parameter is `sql`:**
 
 ```typescript
 // CORRECT
 const res = await ctx.swarm.db_query({ sql: "SELECT status, count(*) as cnt FROM agent_tasks GROUP BY status" });
 
-// WRONG — silently returns no data
-const res = await ctx.swarm.db_query({ query: "SELECT ..." });
+// Legacy scripts may still run with `query`, but new code should not use it.
 ```
 
 **`db_query` returns positional rows, not objects.** The response shape is `{ rows: unknown[][], columns: string[] }`. Zip them into objects: