@desplega.ai/agent-swarm 1.91.0 → 1.92.1

package/templates/skills/desloppify/content.md

@@ -1,6 +1,6 @@
 # desloppify — Code-health scan workflow (swarm edition)
 
-`desloppify` is a multi-language codebase health scanner (peteromallet/desloppify). This skill is the swarm-adapted SKILL.md: it codifies the **install recipe with the tree-sitter pin**, the surface-only **scan → status → next → triage** workflow we run for repos like `agent-swarm`, and the **publish-to-agent-fs** step so humans (Eze) can see the findings.
+`desloppify` is a multi-language codebase health scanner (peteromallet/desloppify). This skill is the swarm-adapted SKILL.md: it codifies the **install recipe with the tree-sitter pin**, the surface-only **scan → status → next → triage** workflow for code-health scans, and the **publish-to-agent-fs** step so humans can see the findings.
 
 > **Default mode for swarm workers: surface-only.** Run Phase 1 + early Phase 2, publish a memo to agent-fs, stop. Do **not** run Phase 3 (queue-grinding refactors) unless the task explicitly asks.
 
@@ -8,7 +8,7 @@
 
 - A task asks you to run desloppify, do a code-health scan, get a health score, or surface debt themes on a repo.
 - A task references `peteromallet/desloppify` or the upstream `docs/SKILL.md`.
-- You need to triage tech debt on a TS / Python / multi-lang repo (agent-swarm, landing, agent-swarm-landing, desplega-ai, etc.).
+- You need to triage tech debt on a TS / Python / multi-lang repo.
 
 If the task is "fix this one bug" or "rename X" → not this skill. Desloppify is for batch debt-surfacing, not point fixes.
 
@@ -28,7 +28,7 @@ pipx runpip desloppify show tree-sitter-language-pack | grep Version
 
 ## Step 2 — Install (first run only)
 
-Use `pipx`. This is the working recipe verified in PR #463 (Dockerfile.worker) and across multiple sprite smokes:
+Use `pipx`. This keeps the scanner isolated from the project environment:
 
 ```bash
 pipx install 'desloppify[full]==0.9.15'
@@ -39,7 +39,7 @@ pipx runpip desloppify show tree-sitter-language-pack | grep Version
 # → must show 1.6.2 (or another <1.8)
 ```
 
-**Why the pin:** `tree-sitter-language-pack` 1.8.0 has an ABI mismatch with `tree-sitter` that crashes desloppify in `cohesion.py:52` → `extractors.py:90` with a `TypeError`. Upstream fix is [peteromallet/desloppify#605](https://github.com/peteromallet/desloppify/pull/605) — open, unmerged. Until that ships, we cap locally. (See task `616b4bba-43de-40b5-af3b-4e219b622218` for the full repro.)
+**Why the pin:** some `tree-sitter-language-pack` 1.8.x builds have ABI mismatches with `tree-sitter` that crash scans during language extraction. Until the installed scanner version is known to work with newer language-pack releases, cap it below 1.8.
 
 If `pipx` isn't installed: `python3 -m pip install --user pipx && python3 -m pipx ensurepath` and start a new shell. If `pipx install` fails with build errors, jump to **Sprite escape hatch** below.
 
@@ -94,11 +94,11 @@ What to capture for the memo:
 
 ## Step 6 — Publish findings to agent-fs
 
-Save the scan memo so Eze and the swarm can see it. Use the shared org (`648a5f3c-35c8-4f11-8673-b89de52cd6bd`) and namespace the path under your own agent ID:
+Save the scan memo somewhere durable so operators can review it. If your deployment uses agent-fs, write it under your own agent namespace:
 
 ```bash
 DATE=$(date +%Y-%m-%d)
-agent-fs --org 648a5f3c-35c8-4f11-8673-b89de52cd6bd write \
+agent-fs --org <org-id> write \
   thoughts/$AGENT_ID/research/$DATE-desloppify-<repo>-scan.md \
   --content "$(cat <<'EOF'
 # desloppify scan — <repo> @ <SHA>
@@ -160,7 +160,7 @@ sprite exec -s desloppify-scan -- bash -c '
   pipx install "desloppify[full]==0.9.15"
   pipx inject --force desloppify "tree-sitter-language-pack<1.8"
   pipx runpip desloppify show tree-sitter-language-pack | grep Version
-  git clone --depth=1 https://github.com/desplega-ai/<repo>.git /tmp/repo
+  git clone --depth=1 https://github.com/<owner>/<repo>.git /tmp/repo
   cd /tmp/repo
   desloppify scan --path .
   desloppify status
@@ -191,11 +191,10 @@ desloppify status
 desloppify next --count 15
 
 # Publish + report
-agent-fs --org 648a5f3c-35c8-4f11-8673-b89de52cd6bd write thoughts/$AGENT_ID/research/$(date +%F)-desloppify-<repo>-scan.md --content "..." -m "scan memo"
+agent-fs --org <org-id> write thoughts/$AGENT_ID/research/$(date +%F)-desloppify-<repo>-scan.md --content "..." -m "scan memo"
 # slack-reply on the originating thread
 ```
 
 ## Upstream reference
 
 Full Phase 3 / review workflow / plan commands are in the upstream SKILL.md: <https://github.com/peteromallet/desloppify/blob/main/docs/SKILL.md>. Reach for it when you're explicitly asked to grind the queue (rare). Default swarm mode stops after the memo + Slack reply.
-

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
-