@synap-core/cli 1.7.0 → 1.10.0

package/templates/automations/url-bookmark-capture.automation.json

@@ -0,0 +1,70 @@
+{
+  "name": "URL → Bookmark (inbound messages)",
+  "triggerType": "event",
+  "status": "active",
+  "triggerConfig": {
+    "eventPattern": "external_message.received.*",
+    "filters": { "provider": "discord" }
+  },
+  "flowDefinition": {
+    "nodes": [
+      {
+        "id": "trigger",
+        "type": "trigger",
+        "position": { "x": 0, "y": 0 },
+        "data": {
+          "triggerType": "event",
+          "label": "Inbound message",
+          "config": {
+            "eventPattern": "external_message.received.*",
+            "filters": { "provider": "discord" }
+          }
+        }
+      },
+      {
+        "id": "extract",
+        "type": "transform",
+        "position": { "x": 0, "y": 120 },
+        "data": {
+          "label": "Extract URLs",
+          "expression": "{{trigger.payload.data.content}} | url_extract"
+        }
+      },
+      {
+        "id": "url-loop",
+        "type": "loop",
+        "position": { "x": 0, "y": 240 },
+        "data": {
+          "label": "For each URL",
+          "iteratorExpression": "steps.extract.output.result",
+          "itemVariable": "url"
+        }
+      },
+      {
+        "id": "create-bookmark",
+        "type": "output",
+        "position": { "x": 0, "y": 360 },
+        "data": {
+          "label": "Create bookmark",
+          "outputType": "entity_create",
+          "config": {
+            "profileSlug": "bookmark",
+            "title": "{{loop.item}}",
+            "dedupeBy": "url",
+            "properties": {
+              "url": "{{loop.item}}",
+              "sourceMessageId": "{{trigger.payload.data.messageId}}",
+              "sourceChannelId": "{{trigger.payload.data.threadId}}"
+            }
+          }
+        }
+      }
+    ],
+    "edges": [
+      { "id": "e1", "source": "trigger", "target": "extract" },
+      { "id": "e2", "source": "extract", "target": "url-loop" },
+      { "id": "e3", "source": "url-loop", "target": "create-bookmark" }
+    ]
+  },
+  "metadata": { "source": "bridge-template" }
+}

package/templates/skills/README.md

@@ -0,0 +1,21 @@
+# CLI-bundled skills (`synap skill add bundled`)
+
+This directory must NOT hold hand-authored copies of the backend **SSOT** skills.
+The pod's baseline skills already reach every pod two other ways:
+
+- **Auto-seeded** on pod boot by `ensureSystemSkills()` (backend `skills/` → `system/*` rows).
+- Shipped as **Agent-Skills packages** by `scripts/sync-skills.sh` (→ `synap-cli/skills/`).
+
+Duplicating them here is what drifted (e.g. an old CRM `digesting-a-channel`), so the
+15 SSOT-covered skills were retired from this bundle.
+
+What remains here, and why:
+- **CLI/agent-runtime skills** (`coordinating-*`, `authoring-*`) — genuine runtime
+  concerns with no SSOT counterpart. Hand-authored; this is their home.
+- **Agency/domain skills** (`stellar-scf-grants-advisor` + its reference corpus,
+  `mapping-the-server`, `routing-to-channels`, `bookmark-enrichment`,
+  `reading-client-progress`) — these belong in the **CP capability templates** and
+  are applied via `/capabilities/apply` (see `bridge-setup` AGENCY plan). They stay
+  bundled here TEMPORARILY until CP gains reference-corpus support (`documents[]`/
+  `referenceDir`) so the stellar corpus survives the move. Do not add new SSOT-style
+  skills here.

package/templates/skills/authoring-automations/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: authoring-automations
+description: Authors a Synap Automation — the WHEN→THEN flow engine (triggers, nodes, data flow). Use whenever the user wants something to happen automatically: "every morning do X", "when a Y is created then Z", "poll this source and create entities", "fan out a list into records", "post to a channel when…", or asks to build/edit an automation flow. Also use when designing the trigger half of a playbook (the WHEN that fires a process).
+---
+
+# Authoring Automations
+
+A **Synap Automation** is a WHEN→THEN flow: a **trigger** fires, then a graph of **nodes** runs. It is how recurring work happens without a human in the loop. This skill encodes the VERIFIED capability matrix — the triggers, the nodes, the data-flow grammar, the canonical recipes, and the one firewall gotcha that will bite you.
+
+Read `reference/node-matrix.md` for the exhaustive per-node field reference. Keep flows small: trigger → a couple of steps. Don't over-engineer the first version.
+
+## The template format
+
+Automation templates live at `synap-backend/templates/automations/*.automation.json`:
+
+```jsonc
+{
+  "name": "URL → Bookmark (inbound messages)",
+  "triggerType": "event",
+  "status": "active",
+  "triggerConfig": { "eventPattern": "external_message.received.*", "filters": { "provider": "discord" } },
+  "flowDefinition": {
+    "nodes": [ /* each: { id, type, position, data } */ ],
+    "edges": [ /* each: { id, source, target } */ ]
+  },
+  "metadata": { "source": "bridge-template" }
+}
+```
+
+The canonical `url-bookmark-capture` shape is: **message trigger → transform (`url_extract`) → loop → entity_create (with `dedupeBy`)**. That is the reference for any "extract items from input, create one entity each" flow.
+
+## Triggers (4)
+
+| Trigger | Config | Fires when |
+|---|---|---|
+| `cron` | `{ expression: "0 9 * * *" }` | The pod-wide scheduler matches (it polls every minute, so minute granularity). |
+| `event` | `{ eventPattern: "entities.*" \| "focus_session.stage_changed.*" \| …, filters }` | A matching domain event is emitted. |
+| `webhook` | `{ webhookSubscriptionId }` | An inbound webhook hits the subscription. |
+| `manual` | — | A user/agent runs it on demand. |
+
+## Nodes (14)
+
+`trigger`, `command`, `condition`, `delay`, `output`, `loop`, `transform`, `fetch`, `query`, `switch`, `skill`, `capability`, `sub_automation`, `playbook_run`. Full fields in `reference/node-matrix.md`. The load-bearing ones:
+
+- **command** — free-form AI step via the Intelligence Service. Powerful but UNTYPED — strongly prefer a `skill` for structured extraction. A `command` feeding a `loop` is a best-effort fallback only (ship `status: "draft"` + a reliability caveat; see below).
+- **output** — the side-effect node. Subtypes: `entity_create` (`{ profileSlug, title, dedupeBy, properties }`; governed + empty/dup-guarded; **`dedupeBy` is a SINGLE key**), `entity_update`, `webhook` (POST to an arbitrary URL with vault headers), `notification`, `channel_message`.
+- **loop** — iterate an array (cap 100). Its iterator is resolved **RAW** (not stringified) so it works on real arrays.
+- **transform** — `uppercase` \| `lowercase` \| `json` \| `trim` \| `url_extract`.
+- **fetch** — HTTP (30s timeout, vault headers, auto-JSON-parses the body).
+- **skill** — run an IS skill (gated). The right tool for **structured extraction** (returns typed data).
+- **capability** — run a capability verb → resolves to a skill (gated).
+- **sub_automation** — call another automation (depth limit 5).
+- **playbook_run** — start a playbook from a flow.
+
+## Data flow grammar
+
+- `{{trigger.payload.x}}` — fields off the trigger event.
+- `{{steps.<nodeId>.output.x}}` — output of a prior node by id.
+- `{{loop.item}}` / `{{loop.index}}` — inside a loop body.
+
+**Lossy stringify gotcha:** `resolveTemplate` STRINGIFIES values — fine for strings, **lossy for objects/arrays**. Two paths resolve RAW instead: the **loop iterator** (`iteratorExpression`) and **transform** input. So: build arrays/objects with those raw-path nodes; use `{{…}}` interpolation only where a string is wanted.
+
+**Canonical fan-out:** a `skill` returns `{ items: [...] }` → `loop` over `steps.<skill>.output.items` → `entity_create` per `{{loop.item}}`. This is the backbone of every "source → many entities" automation.
+
+## The canonical "external source → calendar" recipe
+
+```
+cron (0 7 * * *)
+  → fetch (GET the source URL)
+  → skill (structured extraction → returns { events: [...] })
+  → loop (iterator: steps.extract.output.events)
+  → entity_create (profileSlug: "event", dedupeBy: "externalId", properties from {{loop.item}})
+```
+
+**Strongly prefer a skill for structured extraction.** A purpose-built `skill` (like `bookmark-enrichment`) returns typed, reliable structured data you can fan out — that is the path to reach for. A free-form `command` is NOT schema-typed; its IS task output shape is not guaranteed, so a `loop` over it is BEST-EFFORT and may resolve to `[]`. A `command → loop` is an explicit FALLBACK — use it only when no skill or JSON source exists, and when you do, ship the automation `status: "draft"` with a reliability caveat noting the output shape isn't guaranteed. Do not present command-based extraction as reliable.
+
+## THE FIREWALL GOTCHA (critical)
+
+**`channel_message` does NOT relay to Discord.** It only inserts an internal `messages` row. To reach Discord from an automation you must use a **`webhook` node → Discord webhook URL**.
+
+**BUT** that webhook path **bypasses the team-vs-client-comms firewall.** So:
+
+- Posting to an internal **team** channel via webhook: acceptable.
+- Posting to anything **client-linked** (a `client-comms` channel, mirrored to the client): **NEVER via an automation webhook.** It must go through the bridge's `proactive_post` / `route_to_channel` path, which enforces the firewall. An automation that webhooks into a client channel leaks bot activity to the client.
+
+When in doubt, route client-facing posts through the bridge, never an automation.
+
+## Authoring checklist
+
+1. Pick the **trigger** (cron / event / webhook / manual) and its config.
+2. Sketch the smallest node chain that does the job.
+3. For structured extraction → strongly prefer a `skill`. A `command → loop` is a best-effort fallback only — ship it `status: "draft"` with a reliability caveat (output shape not guaranteed; the loop may resolve `[]`).
+4. Fan out with `skill → loop → entity_create` + a `dedupeBy` key (idempotency).
+5. Reaching Discord? `webhook` node — and if the target is client-linked, route through the bridge instead.
+6. Write it as `{ name, triggerType, status, triggerConfig, flowDefinition: { nodes, edges }, metadata }`.

package/templates/skills/authoring-automations/reference/node-matrix.md

@@ -0,0 +1,49 @@
+# Automation node matrix (exhaustive)
+
+Every node is `{ id, type, position: {x,y}, data }`. Edges are `{ id, source, target }`. `data` shape varies by `type`.
+
+## Triggers (4)
+
+| triggerType | triggerConfig | Notes |
+|---|---|---|
+| `cron` | `{ expression: "0 9 * * *" }` | Pod-wide scheduler polls every minute → minute granularity, no sub-minute. |
+| `event` | `{ eventPattern, filters }` | Patterns: `entities.*`, `focus_session.stage_changed.*`, `external_message.received.*`, etc. `filters` narrows by payload fields (e.g. `{ provider: "discord" }`). |
+| `webhook` | `{ webhookSubscriptionId }` | Fires on inbound webhook delivery. |
+| `manual` | — | On-demand run by user/agent. |
+
+## Nodes (14)
+
+| type | Purpose | Key fields / config |
+|---|---|---|
+| `trigger` | Entry node mirroring the trigger | `{ triggerType, config }` |
+| `command` | Free-form AI step via IS | prompt; UNTYPED output — strongly prefer a `skill` for extraction. `command → loop` is a best-effort fallback only (ship `status: "draft"` + reliability caveat; output shape not guaranteed, loop may resolve `[]`) |
+| `condition` | Branch on a safe comparison | safe comparators (eq, neq, gt, lt, contains…); no arbitrary eval |
+| `delay` | Pause the flow | `5m` \| `1h` \| `1d` \| `1w` |
+| `output` | Side effects (see subtypes below) | `outputType` + `config` |
+| `loop` | Iterate an array | `iteratorExpression` (RAW path); cap **100**. `itemVariable` is currently IGNORED by the executor (it only binds `context.loop.item`) — reference items as `{{loop.item.*}}`, not the named var |
+| `transform` | String transform | `expression: "<raw path> \| op"`; ops: `uppercase`, `lowercase`, `json`, `trim`, `url_extract` |
+| `fetch` | HTTP request | URL, method, vault headers; 30s timeout; auto-JSON-parses body |
+| `query` | Read entities from the pod | profile + filter |
+| `switch` | Multi-way branch | cases on a value |
+| `skill` | Run an IS skill (gated) | skill name + args; returns STRUCTURED data — use for extraction |
+| `capability` | Run a capability verb → skill (gated) | verb resolves to a skill |
+| `sub_automation` | Call another automation | depth limit **5** |
+| `playbook_run` | Start a playbook | playbook ref + params/subject |
+
+## `output` subtypes
+
+| outputType | config | Notes |
+|---|---|---|
+| `entity_create` | `{ profileSlug, title, dedupeBy, properties }` | Governed (proposal-gated). Empty/duplicate guarded. **`dedupeBy` is a SINGLE key**, not a list. |
+| `entity_update` | target + properties | Governed. |
+| `webhook` | `{ url, method, headers, body }` | POST to ANY URL; headers can pull from the vault. The ONLY way to reach Discord from an automation. |
+| `notification` | message/target | In-app notification. |
+| `channel_message` | channel + content | Inserts an internal `messages` row ONLY. Does NOT relay to Discord/Telegram. |
+
+## Data-flow paths
+
+- `{{trigger.payload.x}}` — trigger event fields.
+- `{{steps.<nodeId>.output.x}}` — a prior node's output.
+- `{{loop.item}}`, `{{loop.index}}` — inside a loop body.
+
+**Resolution rule:** `{{…}}` interpolation goes through `resolveTemplate`, which STRINGIFIES (lossy for objects/arrays). The **loop `iteratorExpression`** and **transform `expression`** input resolve the path RAW — that is why looping over `steps.extract.output.events` works on the real array. Build/iterate structured data with those raw-path fields; reserve `{{…}}` for string slots.

package/templates/skills/authoring-capabilities/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: authoring-capabilities
+description: Authors a Synap Capability template — the delivery vehicle that bundles tools + skills + playbooks + automations into one applyable .capability.json. Use whenever the user wants to connect a service (OAuth or API key), package a reusable know-how/process pack, ship a new connector, or assemble several skills and a process into one installable bundle. This is the top of the authoring stack: pick the pack shape, then author the playbook (process) and automations (when) inside it.
+---
+
+# Authoring Capabilities
+
+A **Capability** is the delivery vehicle in Synap: a named container that bundles **tools** (connections), **skills** (know-how/code), **playbooks** (processes), and optionally **automations** (when), applied as one unit. This skill teaches the template file, the skill kinds, the connector shapes, and how to seed it. It is the top of the three-skill authoring stack — compose it with `authoring-playbooks` and `authoring-automations`.
+
+Read `reference/template-anatomy.md` for the full field reference and reference templates.
+
+## The file
+
+`synap-control-plane-api/src/seeds/capability-templates/<key>.capability.json`:
+
+```jsonc
+{
+  "key": "my-connector",
+  "name": "My Connector",
+  "description": "What this bundle gives an agent and when to use it.",
+  "params": [ /* { name, label, type, required?, default?, description } */ ],
+  "vault": [ /* secrets to encrypt */ ],
+  "tools": [ /* connectors */ ],
+  "skills": [ /* know-how + code */ ],
+  "playbooks": [ /* processes — REQUIRE a workspaceId at apply time */ ],
+  "automations": [ /* optional WHEN→THEN flows */ ]
+}
+```
+
+## Materialization order (idempotent)
+
+`createCapabilityFromDefinition()` applies parts in dependency order:
+
+1. **vault** — encrypt each secret → it becomes referenceable as `vault://<id>` by its `ref`.
+2. **tools** — created governed. A tool's `credentialRef` resolves: a `ref` name → `vault://<id>`, or `nango://<provider>` for OAuth. A tool's **verb catalog is DERIVED** from the skills that `requires` it.
+3. **skills** — created (instruction skills injected as prompt; code skills born `approved: false`).
+4. **playbooks** — created LAST among content; they **REQUIRE a `workspaceId`** (a playbook is workspace-scoped).
+5. **container** — the capability itself, with `member_of` links wiring all parts together.
+
+Re-applying is idempotent — existing parts are matched, not duplicated.
+
+## Skill kinds — pick the right one
+
+| `kind` | What it is | When to use |
+|---|---|---|
+| `instruction` | Markdown injected into the agent's prompt (the `code`/body field holds the text) | Pure know-how: methodology, rules, how to draft/classify. No execution, no connector calls. |
+| `code` | JS run in the IS isolate (sandboxed). Born `approved: false`. | Executable logic: fetch + transform + propose entities. Needs review before it runs. |
+| `provider` | Declarative `providerSpec` (HTTP), run **in-process Tier-1** — NOT via the IS. | A trusted, declarative HTTP verb (e.g. a provider call) that doesn't need the AI isolate. Lowest latency. |
+
+**`provider`-kind skills work only via the SEED-FILE path.** The inline Hub `POST /api/hub/capabilities/apply { definition }` route validates skills with a `SkillDefSchema` that accepts only `instruction` | `code` — so a `provider` skill passed inline is rejected. To ship a `provider` skill, seed it from a `<key>.capability.json` template (the seed path), not via an inline `definition`.
+
+## Connector shapes — Nango (OAuth) vs vault-generic (API key)
+
+| | Nango / OAuth | Vault-generic / API key |
+|---|---|---|
+| tool `kind` | `provider` | `api` |
+| `credentialRef` | `nango://<provider>` | a `ref` → `vault://<id>` |
+| `vault[]` | empty (Nango holds the token) | one entry (the API key) |
+| tool `config` | provider-defined | `{ baseUrl, auth: { in, name, prefix } }` |
+| Reference template | `nango-google.capability.json` | `generic-apikey.capability.json` |
+
+**Reference templates (the molds to clone):**
+- `nango-google` — Nango/OAuth connector.
+- `cal-com` — vault/API-key connector.
+- `agency-skills` — instruction-only pack + 2 playbooks. **The mold for a know-how + process pack.**
+- `generic-apikey` — the blueprint to clone for any new vault-backed connector.
+
+**Builtin `web_fetch` / `web_search` are always available** — no template needed just to read a URL.
+
+## Seeding the capability
+
+Two ways:
+
+- **Via the bridge:** add the key to `AGENCY_CAPABILITY_PLAN` in `synap-cli/src/commands/bridge-setup.ts`. Set `workspaceScoped: true` if it bundles playbooks (so the bridge applies it WITH a workspace).
+- **Directly:** `POST /api/hub/capabilities/apply` with `{ templateKey | definition, params, workspaceId }`.
+
+## How the three authoring skills compose
+
+A subagent given a plain goal ("build a process for X") works top-down:
+
+1. **authoring-capabilities** (this skill) → pick the pack shape and the connectors it needs (Nango? API key? instruction-only?).
+2. **authoring-playbooks** → design the process: ordered stages, subject, grants.
+3. **authoring-automations** → design the WHEN: the trigger(s) that fire the playbook and any fan-out flows.
+4. **Emit** the `.capability.json` (with `skills[]` + `playbooks[]`) plus any `*.automation.json`, then seed via the plan or `apply`.
+
+## Authoring checklist
+
+1. Choose the shape: connector (Nango/API key) or pure know-how/process pack.
+2. Declare `params` and `vault` (empty for Nango / instruction-only).
+3. Add `tools` with the right `credentialRef`; let verbs derive from skills' `requires`.
+4. Add `skills` — pick `instruction` / `code` / `provider` per skill.
+5. Add `playbooks` (remember: needs a workspaceId) and optional `automations`.
+6. Seed via `AGENCY_CAPABILITY_PLAN` (`workspaceScoped` matching whether it has playbooks) or `POST /api/hub/capabilities/apply`.

package/templates/skills/authoring-capabilities/reference/template-anatomy.md

@@ -0,0 +1,70 @@
+# Capability template anatomy
+
+File: `synap-control-plane-api/src/seeds/capability-templates/<key>.capability.json`. Top-level keys: `key`, `name`, `description`, `params`, `vault`, `tools`, `skills`, `playbooks`, `automations?`.
+
+## params
+
+```jsonc
+{ "name": "apiKey", "label": "API key", "type": "text", "required": true,
+  "default": "…", "description": "…" }
+```
+Param values are interpolated into the rest of the template as `{{paramName}}` (and `{{name}}` = the capability name). `type`: `text` | `number` | `entity` | `choice` | `boolean`.
+
+## vault
+
+```jsonc
+{ "ref": "apiKeySecret", "name": "{{name}} API key", "value": "{{apiKey}}",
+  "type": "api_key", "description": "…" }
+```
+Each entry is encrypted at apply time and becomes referenceable as `vault://<id>` via its `ref`. **Nango / instruction-only capabilities have an empty `vault[]`.**
+
+## tools
+
+```jsonc
+// vault-backed (API key)
+{ "name": "generic_api", "kind": "api", "credentialRef": "apiKeySecret",
+  "executor": "is-agent",
+  "config": { "baseUrl": "{{baseUrl}}",
+              "auth": { "in": "header", "name": "Authorization", "prefix": "Bearer " } } }
+
+// Nango (OAuth)
+{ "name": "gmail", "kind": "provider", "credentialRef": "nango://google-mail", ... }
+```
+- `credentialRef`: a vault `ref` (→ `vault://<id>`) OR `nango://<provider>`.
+- Tools are created **governed**.
+- A tool's **verb catalog is DERIVED** from the skills whose `requires` names that tool — you don't list verbs on the tool.
+
+## skills
+
+```jsonc
+{ "name": "draft-outreach", "kind": "instruction", "scope": "pod",
+  "description": "…", "requires": ["unipile_linkedin"],
+  "code": "# Markdown body injected into the agent's prompt …" }
+
+{ "name": "{{name}} fetch-and-propose", "kind": "code", "scope": "pod",
+  "requires": ["generic_api"], "executionMode": "async", "timeoutSeconds": 60,
+  "parameters": { "path": "string?" },
+  "code": "// JS statement body run in the IS isolate …" }
+```
+- `kind`: `instruction` (prompt text in `code`) | `code` (JS, born `approved:false`) | `provider` (declarative `providerSpec` HTTP, in-process Tier-1).
+- `requires`: the tool names the skill feeds into — this is what derives the tool's verb catalog and wires `member_of` links.
+- code skills: `propose.entity({ profileSlug, title, properties })` requires `title` (not `name`) and routes through `checkPermissionOrPropose`. `callProvider(toolName, method, path, body?)` is POSITIONAL; the dispatcher resolves the tool's credential server-side.
+
+## playbooks
+
+The `playbooks[]` array holds full playbook definitions (see the `authoring-playbooks` skill). They are materialized LAST and **REQUIRE a `workspaceId`** at apply time — that is why a capability bundling playbooks is seeded `workspaceScoped: true`.
+
+## automations (optional)
+
+The `automations[]` array can carry WHEN→THEN flows in the same `{ name, triggerType, status, triggerConfig, flowDefinition, metadata }` shape used by `synap-backend/templates/automations/*.automation.json` (see `authoring-automations`).
+
+## Reference templates (in the same directory)
+
+| Template | Shape | Clone it for |
+|---|---|---|
+| `nango-google.capability.json` | Nango/OAuth, empty vault | Any OAuth connector |
+| `cal-com.capability.json` | vault/API-key | A keyed HTTP service |
+| `generic-apikey.capability.json` | vault + one api tool + one code skill | The blueprint for a new vault connector |
+| `agency-skills.capability.json` | instruction-only skills + 2 playbooks | A know-how + process pack |
+
+Builtin `web_fetch` / `web_search` need no template — they are always available to agents.

package/templates/skills/authoring-playbooks/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: authoring-playbooks
+description: Authors a Synap Playbook — the session-template process object that turns a goal into ordered stages over a subject entity. Use whenever the user asks to create a playbook, build a process, design a workflow with stages, set up a "process for X", add or reorder stages, or define what an agent session should do step by step (e.g. "build me a client-onboarding process", "make a 3-stage research playbook", "add a review stage").
+---
+
+# Authoring Playbooks
+
+A **Playbook** is the process object in Synap: a reusable template for an AI working session. It declares a goal, the parameters that specialize it, the capabilities it is allowed to use, where it runs, what it should produce, and — first-class now — the **ordered stages** a subject moves through. When a playbook runs it instantiates a `focus_session` over a single **subject** entity, advancing one stage at a time.
+
+This skill teaches the data model, the live authoring path, the field reference, and the run lifecycle. Read `reference/stages-contract.md` before writing stages, and `reference/worked-example.md` for a full example.
+
+## The mental model (memorize this)
+
+```
+automation (WHEN, the trigger)
+   └─> playbook_run            (a process template, instantiated)
+          └─> over a SUBJECT entity   (subjectProfile resolves which one)
+                 └─> in a focus_session (the runtime instance)
+                        └─> currentStage = the one active stage key
+```
+
+- A playbook is a **template**. A `focus_session` is a **running instance** of it.
+- A subject is in **exactly ONE stage at a time** — `focus_sessions.currentStage` holds the active stage key.
+- An **automation** decides WHEN a playbook runs (its `flowAutomationId` wires the trigger). The playbook decides WHAT happens once running.
+- The session works **over a subject**: one `company`, one `deal`, one `person`, etc. — resolved through `subjectProfile`.
+
+## The LIVE authoring path (where playbooks actually ship)
+
+A playbook is **not** authored as a standalone file. It ships **inside a CapabilityDefinition's `playbooks[]` array**:
+
+1. Define it in the capability template: `synap-control-plane-api/src/seeds/capability-templates/<key>.capability.json`, under `"playbooks": [ ... ]`.
+2. It is materialized by `createCapabilityFromDefinition()` when the capability is applied via `POST /api/hub/capabilities/apply`. Playbooks REQUIRE a `workspaceId` at apply time.
+3. The Discord bridge seeds it by adding the capability key to `AGENCY_CAPABILITY_PLAN` in `synap-cli/src/commands/bridge-setup.ts` with `workspaceScoped: true` (the flag that tells the bridge this capability bundles playbooks, so it must be applied with a workspace).
+
+**GOTCHA — do not copy the vestigial file.** `synap-control-plane-api/templates/packs/deep-research.playbook.json` looks like a standalone playbook template but it is VESTIGIAL: its playbook-specific fields are dropped during materialization. Never copy it or treat it as the schema. The authoritative shape is the `playbooks[]` entry inside a `.capability.json`. For a real example **with ordered stages**, see `stellar-grant-client.capability.json` and `reference/worked-example.md` (note: `agency-skills.capability.json` bundles playbooks but their `stages` are `[]`, so it does not demo the stages contract).
+
+## Playbook field reference
+
+| Field | Type / shape | Meaning |
+|---|---|---|
+| `name` | string | Display name. |
+| `description` | string | What this process does and when it runs. |
+| `goalTemplate` | string with `@{arg:…}` grammar | The session's objective. Interpolate params with `@{arg:paramName}`. |
+| `params` | `{ name, label?, type, required?, description? }[]` | Inputs that specialize a run. `type`: `text` \| `number` \| `entity` \| `choice` \| `boolean`. |
+| `inputStrategy` | `{ kind, description? }` | What the session iterates over. `kind`: `none` \| `static` \| `rotating` \| `query`. |
+| `channelSpec` | `{ type, aiReactionMode? }` | Where it runs. `type`: `GROUP` \| `AGENT_COLLAB` \| `THREAD`. |
+| `expectedOutputs` | `{ kind, label }[]` | The deliverables a run should produce (drives the output checklist). `kind` is **loosely typed** — stick to the shared vocab `note` \| `document` \| `report` for consistency, though any string is accepted. |
+| `schedule` | `{ cron, enabled }` \| `null` | Optional recurring schedule. |
+| `executor` | enum | `is-agent` \| `external-agent` \| `hybrid` — who runs the session. |
+| `subjectProfile` | `{ profileSlug, filter? }` | The profile of the subject entity the session operates over. |
+| `flowAutomationId` | id | The automation whose trigger fires this playbook (the WHEN). **Set post-create by a separate mutation — NOT settable via the template.** |
+| `stages` | `PlaybookStage[]` (ordered) | The ordered process steps. See `reference/stages-contract.md`. |
+| `grants` | `CapabilityRef[]` (stage-level only) | Advisory capability hints surfaced to the agent. See below. |
+
+### grants — advisory capability hints (NOT enforcement)
+
+A `grant` is a `CapabilityRef`: `{ kind, id }` where `kind` is `tool` \| `skill` \| `command` and `id` names the capability. Two things to know before you rely on them:
+
+- **Top-level playbook `grants` are DROPPED.** They are not part of `PlaybookDefSchema` / playbook create, so a `grants` array at the playbook level is silently ignored during materialization. Declare grants on **stages** instead.
+- **Stage `grants` are stored as opaque JSON and are currently ADVISORY.** They are surfaced to the agent at runtime via `RunContext` (the is-agent executor lists a stage's grants in the kickoff prompt) but are **NOT resolved into enforcement `capability` / `link` rows** — nothing blocks the agent from using an ungranted capability, and nothing auto-wires a granted one. Hard enforcement is a documented FOLLOW-UP, not current behavior.
+
+Because of this, "granting" a skill at a stage really means **telling the agent to use that skill at that stage**. An `instruction` skill (e.g. `stellar-scf-grants-advisor`) is already available to the agent through the pod skill catalog + `load_skill` REGARDLESS of any grant — listing it in a stage's `grants` just points the agent at it as the stage's working methodology. Builtin `web_fetch` / `web_search` are always available and need no grant.
+
+## The STAGES contract (the new first-class field)
+
+Stages are **ordered** and drive the session's progression. Read `reference/stages-contract.md` for the full schema and event semantics. In brief:
+
+```jsonc
+"stages": [
+  {
+    "key": "scope",                       // stable id, referenced by currentStage
+    "name": "Scope",
+    "description": "Understand the client and their problem.",
+    "goal": "Produce a one-paragraph problem statement.",   // optional
+    "grants": [{ "kind": "skill", "id": "client-brief" }],  // optional, advisory hint (not enforced)
+    "expectedOutputs": [{ "kind": "note", "label": "Problem statement" }],
+    "suggestedTasks": ["Read the intake form", "List open questions"]
+  }
+]
+```
+
+- The running session tracks `focus_sessions.currentStage` (the active stage key).
+- Changing `currentStage` emits a **`focus_session.stage_changed`** event — automations can trigger on it (e.g. notify when a subject reaches "build").
+- **Empty `stages`** = legacy progress-only behavior (a single 0→100% bar, no stage events).
+
+## Run lifecycle
+
+1. **Start** — `playbooks.run` (tRPC) or `synap_start_session`. Instantiates a `focus_session` over the resolved subject, `currentStage` = first stage key.
+2. **Advance** — `synap_update_session`: set `currentStage` to move stages (emits `stage_changed`), update `progress`, `addOutput` / `completeOutput` as deliverables land.
+3. **Complete** — `synap_complete_session` when the goal is met.
+
+## Authoring checklist
+
+1. State the **goal** as a `goalTemplate` with `@{arg:…}` for anything parameterized.
+2. Define **params** (minimum needed to specialize a run).
+3. Pick the **subjectProfile** — what single entity is each run about?
+4. Write **ordered stages** — each with a clear `goal` and `expectedOutputs`. One subject, one active stage.
+5. Declare stage **grants** to point the agent at the skills/tools each stage should use (advisory hints, not an access gate; put them on stages, not the playbook level).
+6. Set **channelSpec**, **executor**, and (optionally) **schedule**.
+7. Place it in the capability template's `playbooks[]` and add the key to `AGENCY_CAPABILITY_PLAN` (`workspaceScoped: true`).
+
+See `reference/worked-example.md` for a complete 3-stage client-process playbook over a `company` subject.

package/templates/skills/authoring-playbooks/reference/stages-contract.md

@@ -0,0 +1,35 @@
+# PlaybookStage — the stages contract
+
+Stages are the first-class, ordered process steps of a playbook. They replaced the old "progress percentage only" model. A subject moving through a playbook is in **exactly one stage at a time**.
+
+## Schema
+
+```ts
+type PlaybookStage = {
+  key: string;                       // stable identifier; what currentStage holds. Required.
+  name: string;                      // human label. Required.
+  description?: string;              // what this stage is about
+  goal?: string;                     // the concrete objective of this stage
+  grants?: CapabilityRef[];          // advisory capability hints ({ kind: tool|skill|command, id }) — see note below
+  expectedOutputs?: ExpectedOutput[];// deliverables expected before advancing ({ kind, label }; kind loosely typed)
+  suggestedTasks?: string[];         // soft checklist the agent can turn into tasks
+};
+```
+
+- `key` is **stable** — `focus_sessions.currentStage` stores it, and `stage_changed` events carry it. Don't rename keys on a live playbook; add/deprecate instead.
+- Stages are **ordered** by their position in the `stages[]` array.
+- `grants` here are **advisory**: stored as opaque JSON and surfaced to the agent in the stage's kickoff prompt via `RunContext`, but NOT resolved into enforcement `capability` / `link` rows (hard enforcement is a documented follow-up). "Granting" a skill at a stage = telling the agent to use it there; the skill is already reachable via the pod skill catalog + `load_skill` regardless. Declare grants on stages, not at the playbook level — top-level playbook `grants` are dropped during materialization.
+
+## Runtime semantics
+
+- A `focus_session` starts with `currentStage` = the first stage's `key`.
+- Calling `synap_update_session` with a new `currentStage` advances (or moves back) the subject.
+- **Every change to `currentStage` emits a `focus_session.stage_changed` event.** Automations can subscribe with an event trigger on `focus_session.stage_changed.*` (optionally filtered by the new stage key) — this is how "when a deal reaches negotiation, notify the team" is wired.
+- **Empty `stages` array = legacy behavior**: the session tracks only a 0→100% `progress` value and emits no stage events.
+
+## Design rules
+
+- Keep stages **few and meaningful** (3–6 is typical). Each stage should represent a real change in what the agent is doing or waiting on.
+- Give every stage a `goal` and at least one `expectedOutput` so "done with this stage" is observable.
+- Use `suggestedTasks` for the soft checklist; use `expectedOutputs` for the hard deliverables that gate advancement. For `expectedOutputs[].kind`, keep to the shared (loosely typed) vocab `note` | `document` | `report`.
+- Stage `grants` point the agent at the right capability per stage — name the LinkedIn tool in the "outreach" stage, not the "scope" stage. Remember they are advisory hints, not an access gate.

package/templates/skills/authoring-playbooks/reference/worked-example.md

@@ -0,0 +1,64 @@
+# Worked example — a 3-stage client-process playbook
+
+Goal: a reusable process that takes a prospective `company`, scopes their problem, abstracts it into a buildable spec, and ships a first build. The subject is one `company` per run. Three ordered stages: **Scope → Abstract → Build**.
+
+This is a `playbooks[]` entry inside a `.capability.json` (NOT a standalone file).
+
+```jsonc
+{
+  "name": "Client Build Process",
+  "description": "Take a prospective company from raw problem to a shipped first build, one stage at a time.",
+  "goalTemplate": "Run @{arg:companyName} through scope → abstract → build. Produce a problem statement, a buildable spec, and a working first deliverable. Every write stays proposal-gated.",
+  "params": [
+    { "name": "companyName", "label": "Company", "type": "entity", "required": true,
+      "description": "The company this run is about (the subject)." }
+  ],
+  "subjectProfile": { "profileSlug": "company" },
+  "inputStrategy": { "kind": "none" },
+  "channelSpec": { "type": "AGENT_COLLAB", "aiReactionMode": "only_mentioned" },
+  "executor": "is-agent",
+  "schedule": null,
+  "expectedOutputs": [
+    { "kind": "note", "label": "Problem statement" },
+    { "kind": "document", "label": "Buildable spec" },
+    { "kind": "document", "label": "First build deliverable" }
+  ],
+  "stages": [
+    {
+      "key": "scope",
+      "name": "Scope",
+      "description": "Understand the company and the problem worth solving.",
+      "goal": "Produce a one-paragraph problem statement grounded in the company context.",
+      "grants": [{ "kind": "skill", "id": "client-brief" }],
+      "expectedOutputs": [{ "kind": "note", "label": "Problem statement" }],
+      "suggestedTasks": ["Assemble the client brief", "List the open questions", "Confirm the problem with the operator"]
+    },
+    {
+      "key": "abstract",
+      "name": "Abstract",
+      "description": "Turn the problem into a buildable specification.",
+      "goal": "Write a spec: scope, constraints, success criteria, and the smallest first deliverable.",
+      "expectedOutputs": [{ "kind": "document", "label": "Buildable spec" }],
+      "suggestedTasks": ["Draft the spec", "Define success criteria", "Get spec sign-off"]
+    },
+    {
+      "key": "build",
+      "name": "Build",
+      "description": "Ship the first deliverable against the spec.",
+      "goal": "Produce a working first build and link it to the company.",
+      "grants": [{ "kind": "tool", "id": "gdrive" }],
+      "expectedOutputs": [{ "kind": "document", "label": "First build deliverable" }],
+      "suggestedTasks": ["Build the first deliverable", "Link it to the company", "Hand off for review"]
+    }
+  ]
+}
+```
+
+## How a run flows
+
+1. Operator (or an automation via `flowAutomationId`) starts the playbook with `companyName` = a specific company. The `focus_session` opens with `currentStage = "scope"`.
+2. The agent works the **scope** stage, producing the problem-statement note. When done, `synap_update_session({ currentStage: "abstract" })` advances it — emitting `focus_session.stage_changed` (new stage `abstract`).
+3. An automation could trigger on `focus_session.stage_changed.*` filtered to `build` to post "X has reached the build stage" in the team channel.
+4. When the build deliverable lands and is linked, `synap_complete_session` closes the session.
+
+Note on `grants`: declare them on **stages**, not at the playbook level — top-level playbook `grants` are dropped during materialization. Stage `grants` are **advisory** (surfaced to the agent in the stage kickoff prompt, not resolved into enforcement rows — see the SKILL.md grants section). Keep the surface tight — only point at `gdrive` in the build stage where it is actually used, so the agent knows that is the stage's tool.