@desplega.ai/agent-swarm 1.92.0 → 1.92.2

package/templates/skills/jira-interaction/content.md

@@ -5,15 +5,15 @@ The swarm has Jira OAuth connected but **no inbound sync** (unlike Linear). Ever
 ## TL;DR — minimum knowledge
 
 1. Pull the access token from `oauth_tokens` (provider = `jira`).
-2. Hit `https://api.atlassian.com/ex/jira/<CLOUD_ID>/rest/api/3/...` — *not* `desplega.atlassian.net` directly. 3LO bearer tokens only work via the `api.atlassian.com` proxy.
+2. Hit `https://api.atlassian.com/ex/jira/<CLOUD_ID>/rest/api/3/...` — not your site hostname directly. 3LO bearer tokens only work via the `api.atlassian.com` proxy.
 3. Bodies for descriptions/comments must be in **ADF** (Atlassian Document Format), not plain text or markdown.
 
-## Known constants (Desplega tenant)
+## Deployment constants
 
-- Site: `desplega.atlassian.net`
-- Cloud ID: `0054e739-8d39-4f01-8d6a-431619cae8fc`
-- Default project: `KAN` ("Swarm")
-- Scopes on the stored token: `manage:jira-webhook offline_access read:jira-work read:me write:jira-work`
+- Site: `<your-site>.atlassian.net`
+- Cloud ID: `<cloud-id>`
+- Default project: `<PROJECT>`
+- Scopes on the stored token: confirm from `oauth_tokens.scope` before write operations
 
 If the cloudId ever changes, rediscover it:
 ```bash
@@ -33,7 +33,7 @@ SELECT accessToken, expiresAt, scope FROM oauth_tokens WHERE provider = 'jira';
 **Always check `expiresAt` first.** Atlassian access tokens are short-lived (~1h). If expired, do NOT keep retrying — report it. Re-auth path:
 
 ```
-https://api.desplega.agent-swarm.dev/api/trackers/jira/authorize
+<SWARM_API_BASE_URL>/api/trackers/jira/authorize
 ```
 (User may need to remove the app and re-auth.)
 
@@ -65,7 +65,7 @@ curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
 
 ```bash
 curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/project/KAN" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/project/$PROJECT_KEY" \
   | jq '{key, name, lead: .lead.displayName, issueTypes: [.issueTypes[] | {id, name, subtask}]}'
 ```
 
@@ -76,7 +76,7 @@ Use the **`/search/jql`** endpoint (the older `/search` is deprecated for cloud)
 ```bash
 curl -s -G \
   -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  --data-urlencode 'jql=project = KAN AND statusCategory != Done' \
+  --data-urlencode 'jql=project = <PROJECT> AND statusCategory != Done' \
   --data-urlencode 'fields=summary,status,assignee,priority' \
   "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/search/jql" \
   | jq '[.issues[] | {key, summary: .fields.summary, status: .fields.status.name, assignee: .fields.assignee.displayName}]'
@@ -92,7 +92,7 @@ curl -s -X POST \
   "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue" \
   -d '{
     "fields": {
-      "project": { "key": "KAN" },
+      "project": { "key": "<PROJECT>" },
       "summary": "Short title",
       "issuetype": { "name": "Task" },
       "description": {
@@ -106,9 +106,9 @@ curl -s -X POST \
   }'
 ```
 
-Returns `{ id, key, self }` on success (HTTP 201). The `key` (e.g. `KAN-7`) is what humans use; URL is `https://desplega.atlassian.net/browse/<KEY>`.
+Returns `{ id, key, self }` on success (HTTP 201). The `key` (e.g. `<PROJECT>-7`) is what humans use; URL is `https://<your-site>.atlassian.net/browse/<KEY>`.
 
-Available issue types in `KAN` (verify per-project): `Epic, Subtask, Task, Story, Feature, Request, Bug`.
+Available issue types are project-specific; list the project before creating issues.
 
 ### 5. Transition issue status (e.g. → Done)
 
@@ -120,23 +120,15 @@ curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
   | jq '.transitions[] | {id, name, to: .to.name}'
 ```
 
-For project `KAN` (verified 2026-04-27), the workflow exposes ALL transitions from any state — you do not need to walk through intermediate states:
-
-| Transition ID | Target state |
-|---|---|
-| `11` | To Do |
-| `21` | In Progress |
-| `31` | In Review |
-| `41` | Backlog |
-| `51` | **Done** |
+Transition IDs are project-specific. Do not copy IDs between Jira projects; discover them for the issue you are about to update.
 
 Transition (returns HTTP 204 on success, no body):
 
 ```bash
 curl -s -X POST \
   -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/KAN-3/transitions" \
-  -d '{"transition":{"id":"51"}}'
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>/transitions" \
+  -d '{"transition":{"id":"<TRANSITION_ID>"}}'
 ```
 
 ### 6. Comment on an issue
@@ -146,7 +138,7 @@ ADF body again:
 ```bash
 curl -s -X POST \
   -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/KAN-3/comment" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>/comment" \
   -d '{
     "body": {
       "type": "doc", "version": 1,
@@ -161,7 +153,7 @@ Atlassian Cloud uses **accountId**, not username. Find one via:
 
 ```bash
 curl -s -G -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  --data-urlencode 'query=taras' \
+  --data-urlencode 'query=<name-or-email>' \
   "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/user/search" \
   | jq '.[] | {accountId, displayName, emailAddress}'
 ```
@@ -170,7 +162,7 @@ Assign:
 ```bash
 curl -s -X PUT \
   -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/KAN-3/assignee" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>/assignee" \
   -d '{"accountId":"<ACCOUNT_ID>"}'
 ```
 
@@ -181,7 +173,7 @@ To unassign: `{"accountId": null}`.
 ```bash
 curl -s -X PUT \
   -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/KAN-3" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>" \
   -d '{ "fields": { "summary": "New summary", "labels": ["swarm","auto"] } }'
 ```
 
@@ -204,7 +196,7 @@ If you need rich content, build it in a script — don't try to write deep ADF i
 ## Operational rules
 
 - **Token-expiry first.** Always check `expiresAt`. Don't loop on 401s.
-- **Use the proxy.** All authenticated calls go through `api.atlassian.com/ex/jira/<cloudId>/...`. Hitting `desplega.atlassian.net/rest/api/3/...` with a 3LO bearer token will fail.
+- **Use the proxy.** All authenticated calls go through `api.atlassian.com/ex/jira/<cloudId>/...`. Hitting `<your-site>.atlassian.net/rest/api/3/...` with a 3LO bearer token will fail.
 - **Discover transitions per issue** before transitioning — different projects/workflows have different IDs.
 - **Use `/search/jql`**, not the legacy `/search` (which is deprecated and may be removed).
 - **ADF is mandatory** for `description`, `comment`, and rich text fields. Plain strings will be rejected.
@@ -226,21 +218,22 @@ If you need rich content, build it in a script — don't try to write deep ADF i
 
 ```bash
 TOKEN=$(db-query "SELECT accessToken FROM oauth_tokens WHERE provider='jira'")
-CLOUD_ID="0054e739-8d39-4f01-8d6a-431619cae8fc"
+CLOUD_ID="<cloud-id>"
+PROJECT_KEY="<PROJECT>"
 
 # 1. List open issues in KAN
 curl -s -G -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  --data-urlencode 'jql=project = KAN AND statusCategory != Done' \
+  --data-urlencode "jql=project = $PROJECT_KEY AND statusCategory != Done" \
   --data-urlencode 'fields=summary,status' \
   "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/search/jql" \
   | jq -r '.issues[].key' > /tmp/keys.txt
 
-# 2. Transition each to Done (id 51 in KAN)
+# 2. Transition each to Done using the transition ID discovered for this workflow
 for KEY in $(cat /tmp/keys.txt); do
   curl -s -X POST \
     -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
     "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/$KEY/transitions" \
-    -d '{"transition":{"id":"51"}}'
+    -d '{"transition":{"id":"<DONE_TRANSITION_ID>"}}'
   sleep 0.3
 done
 ```
@@ -249,4 +242,3 @@ done
 
 - The MCP tracker tools (`tracker-link-task`, `tracker-sync-status`, etc.) are designed for two-way sync mappings. Jira tracker support exists at the schema level but is not currently wired up to inbound webhooks. Until it is, all Jira interaction must go through this skill.
 - If/when inbound Jira webhooks land, this skill should add a "When to transition" section mirroring the Linear one.
-

package/templates/skills/kapso-whatsapp/content.md

@@ -1,10 +1,10 @@
 # Kapso WhatsApp
 
-Kapso (https://kapso.ai) is the WhatsApp platform vendor we use for the Meta Cloud API. The swarm has one phone number provisioned and either a native inbound handler (PR #560) or a workflow wired to dispatch a task per inbound message.
+Kapso (https://kapso.ai) is a WhatsApp platform vendor for the Meta Cloud API. A swarm can provision one or more phone numbers and use either native inbound handlers or workflows to dispatch a task per inbound message.
 
 ## When to use MCP tools vs this skill's REST recipes
 
-PR #560 ships **thin MCP-tool wrappers for the common case only**:
+Some deployments expose **thin MCP-tool wrappers for the common case only**:
 
 | Tool | Use for |
 |---|---|
@@ -32,7 +32,7 @@ Swarm config keys (resolve with `get-config key:<NAME> includeSecrets:true` —
 |---|---|
 | `KAPSO_API_BASE_URL` | `https://api.kapso.ai` (host only, no `/platform/v1`) |
 | `KAPSO_API_KEY` | API key (`X-API-Key` header) |
-| `KAPSO_PHONE_NUMBER_ID` | `1035039933036854` — our provisioned number's Meta ID |
+| `KAPSO_PHONE_NUMBER_ID` | Provisioned number's Meta ID |
 | `KAPSO_WEBHOOK_HMAC_SECRET` | Shared HMAC secret. Kapso signs every webhook request with `X-Webhook-Signature: <hex>` |
 
 The Kapso CLI is NOT installed in worker containers. Use direct HTTP or clone the `gokapso/agent-skills` repo for fallback scripts.
@@ -46,7 +46,7 @@ The Meta Cloud API is proxied at `$KAPSO_API_BASE_URL/meta/whatsapp/v24.0/...` (
 
 ## Inbound webhook payload (v2)
 
-The `kapso-whatsapp-inbound-demo` workflow (`a5700897-8f6b-4e1e-9e6b-dcc10e479cb5`) receives `whatsapp.message.*` and `whatsapp.conversation.*` events at `POST https://api.desplega.agent-swarm.dev/api/webhooks/<workflow-id>`.
+Your inbound workflow receives `whatsapp.message.*` and `whatsapp.conversation.*` events at `POST <SWARM_API_BASE_URL>/api/webhooks/<workflow-id>`.
 
 Shape (top-level keys):
 
@@ -54,7 +54,7 @@ Shape (top-level keys):
 {
   "message": {
     "id": "wamid.HBgL...",            // Meta message id (WAMID)
-    "from": "34679077777",            // E.164 without +
+    "from": "15550100000",            // dummy E.164 without +
     "from_user_id": "ES.26772...",    // Meta-internal user id
     "timestamp": "1779281573",        // unix seconds (string)
     "type": "text",                   // text | image | audio | video | document | sticker | location | contacts | reaction | ...
@@ -71,9 +71,9 @@ Shape (top-level keys):
   },
   "conversation": {
     "id": "bd7e888e-...",
-    "phone_number": "34679077777",
-    "phone_number_id": "1035039933036854",
-    "contact_name": "Taras",
+    "phone_number": "15550100000",
+    "phone_number_id": "<phone-number-id>",
+    "contact_name": "Example Contact",
     "status": "active",
     "last_active_at": "...",
     "created_at": "...",
@@ -86,7 +86,7 @@ Shape (top-level keys):
     }
   },
   "is_new_conversation": false,
-  "phone_number_id": "1035039933036854"
+  "phone_number_id": "<phone-number-id>"
 }
 ```
 
@@ -143,7 +143,7 @@ NB: verify the exact proxy path against a real media message — the swarm has o
 
 Two paths in order:
 
-1. By name: `resolve-user name:"<contact_name>"` (fuzzy substring match). Returns the canonical profile if there's one. Useful for known team members (Taras / Eze).
+1. By name: `resolve-user name:"<contact_name>"` (fuzzy substring match). Returns the canonical profile if there's one. Useful for known team members.
 2. If no match — the contact is unknown. Lead can run `manage-user create name:"<contact_name>" notes:"WhatsApp +<phone>"` to register them. Workers should NOT create users autonomously; ask Lead.
 
 Always quote the phone number in `manage-user notes` so future lookups by phone work (until we add a `phone` column to the user registry).
@@ -158,7 +158,7 @@ API_KEY=$(get-config KAPSO_API_KEY)
 
 # List conversations for our number
 curl -s -H "X-API-Key: $API_KEY" \
-  "$API_BASE/platform/v1/whatsapp/conversations?phone_number_id=1035039933036854&status=active" | jq
+  "$API_BASE/platform/v1/whatsapp/conversations?phone_number_id=$KAPSO_PHONE_NUMBER_ID&status=active" | jq
 
 # Get a single conversation
 curl -s -H "X-API-Key: $API_KEY" \
@@ -183,8 +183,8 @@ Per WhatsApp policy, free-form text is only allowed within 24h of the last inbou
 **Common case shortcut:** call the `send-whatsapp-message` MCP tool — it wraps exactly this REST call. The recipe below is the canonical reference and the fallback when you need fields the tool doesn't expose.
 
 ```bash
-TO="34679077777"
-TEXT="Hi Taras 👋"
+TO="15550100000"
+TEXT="Hi there"
 
 curl -s -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
   -d "{
@@ -194,7 +194,7 @@ curl -s -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
     \"type\": \"text\",
     \"text\": { \"preview_url\": false, \"body\": \"$TEXT\" }
   }" \
-  "$API_BASE/meta/whatsapp/v24.0/1035039933036854/messages" | jq
+  "$API_BASE/meta/whatsapp/v24.0/$KAPSO_PHONE_NUMBER_ID/messages" | jq
 ```
 
 Returns `{ "messages": [{ "id": "wamid..." }] }` on success. Log the wamid.
@@ -218,7 +218,7 @@ Prefer quote-replies when answering a specific question — it keeps long conver
 
 ## Sending media (image, document, audio, video)
 
-Two-step pipeline through Kapso's Meta proxy: **upload, then send by id**. Sending by `id` is more reliable than `link` (no public-host requirement) — validated 2026-05-20.
+Two-step pipeline through Kapso's Meta proxy: **upload, then send by id**. Sending by `id` is more reliable than `link` because it does not require the media to be hosted at a public URL.
 
 ### 1. Upload
 
@@ -227,7 +227,7 @@ curl -s -X POST -H "X-API-Key: $API_KEY" \
   -F "messaging_product=whatsapp" \
   -F "type=<mime>" \
   -F "file=@/path/to/file.ext;type=<mime>" \
-  "$API_BASE/meta/whatsapp/v24.0/1035039933036854/media"
+  "$API_BASE/meta/whatsapp/v24.0/$KAPSO_PHONE_NUMBER_ID/media"
 # → {"id":"<media-id>"}
 ```
 
@@ -242,7 +242,7 @@ curl -s -X POST -H "X-API-Key: $API_KEY" \
 
 Quote-reply works on media too — add `"context": { "message_id": "<wamid>" }` at the top level.
 
-### Wide images: pad to ~square, send as image (validated 2026-05-20)
+### Wide images: pad to ~square, send as image
 
 WhatsApp scales `type:image` to bubble width + recompresses, so a wide 1200×630 social card renders as a tiny shrunken strip. **The fix is NOT `type:document`** — a `.png` sent as a document shows a plain file card with NO inline preview (must tap+download). Bad UX both ways.
 
@@ -280,7 +280,7 @@ curl -s -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
     "message_id": "<inbound_wamid>",
     "typing_indicator": { "type": "text" }
   }' \
-  "$API_BASE/meta/whatsapp/v24.0/1035039933036854/messages"
+  "$API_BASE/meta/whatsapp/v24.0/$KAPSO_PHONE_NUMBER_ID/messages"
 # → {"success":true}
 ```
 
@@ -297,7 +297,7 @@ curl -s -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
     "type": "reaction",
     "reaction": { "message_id": "<wamid>", "emoji": "👀" }
   }' \
-  "$API_BASE/meta/whatsapp/v24.0/1035039933036854/messages"
+  "$API_BASE/meta/whatsapp/v24.0/$KAPSO_PHONE_NUMBER_ID/messages"
 ```
 
 A user can have only ONE reaction per message — sending a new emoji REPLACES the previous one (no explicit remove needed). Send `"emoji": ""` to clear a reaction entirely.
@@ -310,21 +310,21 @@ If `send-whatsapp-message` returns `sessionWindowExpired: true`, fall through to
 curl -s -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
   -d '{
     "messaging_product": "whatsapp",
-    "to": "34679077777",
+    "to": "15550100000",
     "type": "template",
     "template": {
       "name": "<template_name>",
       "language": { "code": "en_US" }
     }
   }' \
-  "$API_BASE/meta/whatsapp/v24.0/1035039933036854/messages"
+  "$API_BASE/meta/whatsapp/v24.0/$KAPSO_PHONE_NUMBER_ID/messages"
 ```
 
-List approved templates first: `GET $API_BASE/platform/v1/whatsapp/templates?phone_number_id=1035039933036854`.
+List approved templates first: `GET $API_BASE/platform/v1/whatsapp/templates?phone_number_id=$KAPSO_PHONE_NUMBER_ID`.
 
 ## Webhook signature verification
 
-Every Kapso webhook delivery includes `X-Webhook-Signature: <hex>` (HMAC-SHA256 of the raw body using `KAPSO_WEBHOOK_HMAC_SECRET`). The native handler (`/api/integrations/kapso/webhook`, PR #560) and the workflow webhook trigger both verify automatically — the trigger's `hmacHeader` is `X-Webhook-Signature` and `hmacSecret` resolves from swarm config.
+Every Kapso webhook delivery includes `X-Webhook-Signature: <hex>` (HMAC-SHA256 of the raw body using `KAPSO_WEBHOOK_HMAC_SECRET`). Native handlers and workflow webhook triggers should verify the signature automatically; if you configure a custom trigger, set its HMAC header to `X-Webhook-Signature` and resolve the secret from swarm config.
 
 To verify manually:
 
@@ -337,17 +337,17 @@ echo -n "$RAW_BODY" | openssl dgst -sha256 -hmac "$HMAC_SECRET" -hex | awk '{pri
 
 - Same language as the inbound message (Spanish/English/Catalan — match what they wrote).
 - Brief. WhatsApp is not Slack — 1-3 short messages max.
-- Identify yourself if it's a first interaction in the conversation: "Hi! This is the Desplega agent — Taras wired me up to handle WhatsApp."
+- Identify yourself if it's a first interaction in the conversation: "Hi! This is the agent handling this WhatsApp inbox."
 - Quote-reply (`context.message_id`) when answering a specific question.
 - If you can't help (no skill for the request, out of scope) — say so and either escalate to Lead or ask the human to use Slack instead.
 - Always log the outbound wamid in your task output so it's traceable.
 
 ## Where this fits in the swarm
 
-Two inbound paths exist (PR #560 adds the first, the original demo workflow remains):
+Two common inbound paths exist:
 
-- **Native handler** (`/api/integrations/kapso/webhook`, PR #560) — fires for any phone number registered via `register-kapso-number`. Verifies HMAC, dedupes by message id (KV `integrations:kapso:dedupe`, 24h TTL), reads the routing mapping from KV (`integrations:kapso:numbers`), and either dispatches a `kapso-inbound` task or delegates to a workflow trigger (advanced override). Also emits a `kapso.message.received` event on the workflow event bus.
-- **Workflow `kapso-whatsapp-inbound-demo`** (`a5700897-8f6b-4e1e-9e6b-dcc10e479cb5`) — fires for unregistered numbers (or numbers whose mapping points at this workflow). Pipeline: `react-eyes` (mark read + typing + 👀) → `debounce` (collapse rapid-fire bursts) → `gate-proceed` → `notify-taras` (agent-task triage) → `finalize` (✅/❌ reaction).
+- **Native handler** (`/api/integrations/kapso/webhook`) — fires for any phone number registered via `register-kapso-number`. Verifies HMAC, dedupes by message id, reads the routing mapping, and either dispatches an inbound-message task or delegates to a workflow trigger.
+- **Workflow trigger** (`<workflow-id>`) — useful when you want custom routing, batching, triage, or approval steps before a reply is sent. A typical pipeline marks the message read, debounces rapid-fire bursts, routes to an agent task, and optionally sends a final reaction or status update.
 
 **Debounce / batching:** the demo workflow's `debounce` node waits ~8s after each message and only the LAST message of a burst proceeds to the agent task — so a user firing 3 quick messages produces ONE task, not three. The agent is told the `batchSize` and should read trailing history and answer the whole burst in one reply. When >1 messages are collapsed, the user sees a "🧵 Got your N messages" note.
 
@@ -357,13 +357,12 @@ HMAC verification is enforced (signed mode) on both paths.
 
 ## Common gotchas
 
-- Phone numbers from Kapso are E.164 **without `+`** (e.g. `34679077777`). Add `+` when displaying to humans, drop it when calling the API.
+- Phone numbers from Kapso are E.164 **without `+`** (e.g. `15550100000`). Add `+` when displaying to humans, drop it when calling the API.
 - `message.text.body` is only present for `type:"text"`. For other types read `message.<type>` (see the table above) or `message.kapso.content` for a text representation.
 - Outbound status events (`delivered`, `read`) are NOT a customer interaction — skip them. Filter by `message.kapso.direction == "inbound"`.
 - Real inbound messages commonly arrive with `status: "delivered"` (delivered to us). Do NOT skip on status — only `direction` signals inbound vs outbound.
 - Kapso sometimes sends test payloads with `"test": true` and `wamid.TEST_*` ids. Don't reply to test payloads — just complete the task with a note.
-- The provisioned phone number id (`1035039933036854`) is **our** number, not the recipient's. The recipient is in `message.from` / `conversation.phone_number`.
+- The provisioned phone number id is your sender number, not the recipient's. The recipient is in `message.from` / `conversation.phone_number`.
 - The message-list endpoint is `/platform/v1/whatsapp/messages?conversation_id=X` — the conversation-scoped `/conversations/<id>/messages` path 404s.
 - **Wide images shrink — pad them, don't send as document.** `type:image` scales to bubble width; a wide social card becomes a strip. Sending it as `type:document` removes the preview entirely. Fix: pad onto a ~1:1/4:5 canvas and send as `type:image`. See "Sending media".
 - **MCP tools cover text-only.** `send-whatsapp-message` and `reply-whatsapp-message` are deliberately thin — templates / media / reactions / typing / mark-as-read are NOT in the tool surface. For those, use the REST recipes in this skill directly.
-

package/templates/skills/linear-interaction/content.md

@@ -7,7 +7,7 @@ db-query: SELECT accessToken, expiresAt FROM oauth_tokens WHERE provider = 'line
 ```
 If `expiresAt` is in the past, do NOT attempt the API calls — just report the needed update in your task output.
 
-To authorize the user should use: https://api.desplega.agent-swarm.dev/api/trackers/linear/authorize (potentially needing to remove the app and re-auth). Only mention this if you can confirm it's expired or not present.
+To re-authorize, use your swarm API base URL with `/api/trackers/linear/authorize` (potentially needing to remove the app and re-auth). Only mention this if you can confirm the token is expired or not present.
 
 ---
 
@@ -22,7 +22,7 @@ The available MCP tracker tools (`tracker-link-task`, `tracker-link-epic`, `trac
 
 ## When to Transition (Timing)
 
-- **Sprint cadence with direct-to-main commits (e.g. chat-py port):** Transition the Linear ticket to **Done** the moment the worker reports ship (commits on `main`). Do NOT wait for review, test-run, or merge — there's no PR to wait for. Waiting causes HEARTBEAT/blocker-digest to flag RESOLVED-STALE tickets.
+- **Direct-to-main work:** Transition the Linear ticket to **Done** the moment the worker reports ship (commits on `main`). Do NOT wait for review, test-run, or merge when there is no PR to wait for. Waiting causes blocker digests to flag RESOLVED-STALE tickets.
 - **Standard PR workflow:** Transition to **In Review** on PR open, **Done** after merge. If the ticket is still "In Progress" 30 min after the PR merges, you're late.
 - **Blocked:** If a ticket is stuck on a dependency, add a comment linking the blocker — don't leave it silent.
 
@@ -54,9 +54,9 @@ curl -s -X POST https://api.linear.app/graphql \
   -d '{"query": "<GRAPHQL_QUERY>"}'
 ```
 
-## Agent Interaction API — `action` vs `thought` (added 2026-05-19)
+## Agent Interaction API — `action` vs `thought`
 
-Linear's **Agent Interaction API** (different from issue mutations above) supports two activity payload kinds. The swarm's agent-activity sync was broken for ~weeks because they were confused; PRs #495 / #497 fixed it. Use this section whenever emitting `agentActivityCreate` mutations.
+Linear's **Agent Interaction API** (different from issue mutations above) supports two activity payload kinds. Use this section whenever emitting `agentActivityCreate` mutations.
 
 | Activity kind | When to use | `parameter` field |
 |---|---|---|
@@ -76,7 +76,7 @@ Linear's **Agent Interaction API** (different from issue mutations above) suppor
 | Branch create / merge / delete | `action` | branch name |
 | PR open / review / merge | `action` | PR URL |
 
-**Why this trips people:** "action" reads naturally as "every tool call IS an action…". But Linear uses `action` to mean *parameterized operation Linear can index/route on*, not *task-progress-narration*. Narration is `thought`. See shared memory `linear-agent-activity-action-vs-thought-2026-05-18`.
+**Why this trips people:** "action" reads naturally as "every tool call IS an action…". But Linear uses `action` to mean *parameterized operation Linear can index/route on*, not *task-progress-narration*. Narration is `thought`.
 
 ## Common Operations
 
@@ -120,8 +120,8 @@ mutation {
 }
 ```
 
-**Known state IDs for Desplega Labs team:**
-- Done: `83d3fcc6-dfeb-44fa-b719-64108ddc850d`
+**Known state IDs:**
+- Store your team's common state UUIDs in local notes or swarm config; do not hardcode another team's IDs into this template.
 
 ### 2. Add a Comment to an Issue
 
@@ -213,7 +213,7 @@ curl -s -X POST https://api.linear.app/graphql \
 ## Important Notes
 
 - **Always update Linear when completing Linear-sourced tasks.** The user expects the ticket to reflect the swarm's work. Marking only the swarm task as complete is insufficient. Do not complete only the swarm task — failing to update Linear breaks the sync and wastes resources.
-- **Transition timing:** see the "When to Transition" section above. Sprint-cadence ports = transition on ship, not on merge.
+- **Transition timing:** see the "When to Transition" section above. Direct-to-main work transitions on ship, not on merge.
 - **Token expiry:** Check `expiresAt` before making calls. If expired, notify the user — they need to re-authorize.
 - **Rate limits:** Linear has rate limits. For bulk operations, add small delays between calls.
 - **Issue identifiers vs UUIDs:** The human-readable identifier (e.g., "DES-12") works for queries but the `issueUpdate` mutation requires the actual UUID. Always fetch the UUID first via a query.
@@ -227,4 +227,3 @@ Common errors:
 - `Entity not found` → Wrong issue ID/identifier
 - `"parameter must not be empty"` (or similar on Agent Interaction API) → You sent an `action` activity without a `parameter` — convert to `thought` or fill in a real noun. See "Agent Interaction API — action vs thought" above.
 - Rate limited → Back off and retry after delay
-

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.