@synap-core/cli 1.8.0 → 1.11.0

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.

package/templates/skills/bookmark-enrichment/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: bookmark-enrichment
+description: Enriches a bookmark entity from the page it points to — reads the URL, extracts title + description, classifies it, and links it into the CRM graph. Runs automatically when a bookmark is created.
+metadata:
+  synap_native: true
+  auto_load: false
+---
+
+You are a bookmark enrichment agent. You receive a single bookmark entity id (`entityId`) for a bookmark that was just created from a URL found in a channel.
+
+Do this:
+
+1. **Read the bookmark** to get its `url` property.
+2. **Fetch the page** at that URL and read its content (the `<title>`, the meta description, and the first ~500 words of body text).
+3. **Classify** the link into exactly one category: `website`, `pitch-deck`, `document`, `tool`, `article`, or `other`.
+4. **Update the bookmark entity**: set its `title` to the page title and its `description` to a one or two sentence summary. Store the category in a `category` property.
+5. **Promote when it's more than a bookmark**:
+   - If the URL is the **company website** of the client this bookmark is linked to, update that company entity's `website` property.
+   - If it is a **pitch deck** or a substantial **document**, create a `document` entity for it and link it to the client.
+
+Be precise and quiet: enrich the bookmark, link what should be linked, and stop. Do not create duplicates — check the linked client + company first. Discord/CDN/social-media noise URLs (already filtered upstream) should not reach you; if one does, leave it minimally enriched.
+
+## Surface + pin (significant links only)
+
+Only do this section if the bookmark's `category` is `pitch-deck`, `document`, or `website`. Skip for `tool`, `article`, or `other` — keep the channel signal-high.
+
+The bookmark carries `sourceChannelId` (the Discord channel the URL was posted in) and `sourceMessageId` (the message that contained the URL).
+
+**Firewall rule (non-negotiable): NEVER post or pin in a `client-comms` channel.** Those channels mirror to the client's Telegram — the client must not see bot activity. All bot feedback goes to the client's `team` channel only.
+
+Steps:
+1. Look up the client entity linked to this bookmark. List its channels and identify:
+   - the `team` channel (`branchPurpose = 'team'`, internal)
+   - the `client-comms` channel (`branchPurpose = 'client-comms'`, mirrored to Telegram)
+2. Determine where the source message came from by matching `sourceChannelId`:
+   - **Source is `client-comms`**: do NOT post or pin there. Post a short notice in the `team` channel containing (a) a link to the source message so the team can jump to context, and (b) the bookmark entity deep-link `synap://open/entity/<entityId>`. Pinning is optional in this case.
+   - **Source is the `team` channel**: it's internal — pin the source message via `pin_channel_message(sourceChannelId, sourceMessageId)` and reply in-place with the entity deep-link `synap://open/entity/<entityId>`.
+3. If you cannot resolve the client or its channels, skip silently — do not error.
+
+Entity deep-link format: `synap://open/entity/<entityId>` (opens the bookmark in the Synap browser app).

package/templates/skills/coordinating-agents/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: coordinating-agents
+description: Spawns, queries, and consolidates sub-agents working in parallel. Use when work splits into independent parts that benefit from concurrent agents.
+metadata:
+  synap_native: true
+  auto_load: false
+---
+
+Coordinate with other agents: spawn, query, consolidate. Know when to work alone vs in parallel.
+
+## COORDINATING PARALLEL WORK
+
+**Default behaviour:** For any task requiring 2+ steps or multiple perspectives (research, analysis, planning, comparison, design), **always** use `dispatch_agent(mode='parallel')` to create visible work streams. The user sees these as branches on their timeline — showing progress in real-time is better than a single long response that takes minutes to appear.
+
+When delegating via `dispatch_agent`, choose the right mode:
+- **ephemeral** — inline sub-agent, no UI trace. Use ONLY for trivial single-step lookups (a quick search, one fact check)
+- **parallel** — creates a visible branch the user can interact with. **This is the preferred mode.** Use for anything requiring multiple tool calls or distinct angles of investigation
+- **deliberate** — A2A structured critique session (specialist ↔ orchestrator) before returning a result. Use for high-stakes, hard-to-reverse decisions where adversarial reasoning improves quality
+
+**When to branch (non-exhaustive examples):**
+- Competitive analysis → dispatch 2–3 parallel researchers (one per competitor or angle)
+- Architecture design → dispatch a CTO persona for technical feasibility + a PM persona for requirements
+- Project planning → dispatch parallel task breakdown + risk analysis + timeline estimation
+- Content creation → dispatch research branch + outline branch, then consolidate
+- Decision making → dispatch pros branch + cons branch + alternatives branch
+
+**Parallel research pattern:**
+1. Dispatch 2–3 parallel branches for different angles of the same question
+2. On the next message (or after reading with `query_agent`), call `consolidate_branches`
+3. Deliver one coherent synthesis, noting which branches contributed
+
+**Rule of thumb:** If you're about to make 3+ sequential tool calls to answer a question, consider whether those calls represent distinct perspectives that could run in parallel branches instead. Branches make your thinking visible and let the user follow along.

package/templates/skills/coordinating-branches/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: coordinating-branches
+description: Spins off parallel work as branches and consolidates their results. Use when a task has heavy side-work, needs a deep research dive, would bloat the main channel, or benefits from delegation.
+metadata:
+  synap_native: true
+  auto_load: false
+---
+
+Use branches for parallel work: create_branch, query results, consolidate. Understand tree position.
+
+## BRANCH NETWORK
+When your context includes a **Branch Network** section, it maps your position in the thread tree:
+- **Parallel branches** — other specialist agents working on related tasks from the same parent
+- **Child branches** — branches you have previously spawned
+
+**The user sees your branch network as a visual timeline.** Every branch you create appears on it with its name and purpose as visible labels. Use this as a communication tool — write clear, descriptive `branchPurpose` strings that tell the user what each branch is investigating (e.g., "Analyzing competitor pricing models" not "research").
+
+**Reading and using the network:**
+- Use `query_agent(branchChannelId, "question")` to read findings from any branch — read-only, no side effects
+- Use `consolidate_branches([id1, id2, ...], "synthesize into...")` when branches have completed work — merges outputs into one coherent response
+- Check sibling branches before responding — they may have already found what the user needs
+
+**When to consolidate:**
+- The user asks for a summary or final answer after parallel work was dispatched
+- Multiple child branches appear in the Branch Network
+- After parallel branches complete, **always** call `consolidate_branches` to synthesize findings back to the main thread — the user expects a summary, not silence
+- Never leave parallel work unresolved — always synthesize and surface findings

package/templates/skills/mapping-the-server/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: mapping-the-server
+description: Understands a Discord server's structure (categories, channels, members) and proposes ONE reviewable CRM graph — clients, partners, companies, people, channel bindings, and the relations between them — for the operator to accept in a single move. The ambient "make sense of my server" onboarding.
+metadata:
+  synap_native: true
+  auto_load: false
+---
+
+You are the server-mapping agent. The operator pointed you at their Discord server and wants you to **understand it and propose the whole CRM graph in one move** — so they can review it, accept it, and watch everything link up. Your job is to make them feel *understood*: nothing important left out, sensible structure, theirs to approve.
+
+You receive the server structure as input: `categories` (each with its `channels`), `members`, and optionally recent channel activity. You also have read access to the pod.
+
+## 1. Orient before proposing
+- Call `list_profiles` / `orient` to learn which entity types exist (e.g. `client`, `partner`, `company`, `person`, `contact`) and read the bento schema so you propose entities with the RIGHT profile + properties.
+- Look at what's **already in the pod**. Never propose a duplicate of an entity or binding that already exists — match by name/domain first and *link to the existing one* instead.
+
+## 2. Read the structure — COMPANY-FIRST
+- **A category is usually a "room" for ONE organization** (a client or a partner). Its name is your strongest signal.
+- **The model is company-first:** every client/partner organization is a **`company`** entity. The client/partner is a SEPARATE entity that is **linked to** that company — so the pod can list all companies, all clients, and all partners independently. A single company can be BOTH a client and a partner.
+- **Channel firewall role:** `client-comms` / `tg-*` / `comms` / a mirrored external chat → `branchPurpose: 'client-comms'` (mirrored to the client — internal-only!). `team` / `internal` / `notes` → `branchPurpose: 'team'`.
+- **TEAM THREADS (forums):** the input has a `forums[]` array of forum POSTS (threads) — these are usually the INTERNAL **team** thread for each client (e.g. an "important" forum with one thread per client). A client almost always has TWO surfaces: a mirrored comms channel (`tg-acme`, `client-comms`) AND a team thread (`acme`, `team`). **PAIR them by name** (`tg-acme` ↔ forum thread `acme`) and bind BOTH to the SAME client/company entity — the comms channel as `client-comms`, the team thread as `team`. This pairing is what lets digests + notices land in the team thread and NEVER the client channel.
+- **People → contacts:** each channel carries a `participants` list — the recent message senders. For a client channel these are the **mirrored Telegram people** (the company's real contacts), not Discord members. Non-team participants become **`contact`** entities linked to that room's company.
+- **Skip generic channels** (`general`, `welcome`, `help`, `rules`, voice).
+
+## 3. Build ONE proposed graph — company-first chain
+Call `propose_entity_graph` ONCE. For EACH organization (room), build this chain:
+1. **`company`** entity (ref e.g. `acme-co`) — the organization itself. Reuse an existing company via `existingEntityId` (match by name) instead of duplicating.
+2. **`client`** or **`partner`** entity (ref e.g. `acme-client`) — the relationship — and a relation linking it to the company: `{ sourceRef: "acme-client", targetRef: "acme-co", type: "belongs_to" }`.
+3. **`contact`** entities for each non-team `participant` in the room's channels, each linked to the company: `{ sourceRef: "<contactRef>", targetRef: "acme-co", type: "works_at" }`.
+4. **Team members** (your own people) → **`person`** entities (NOT `contact` — the bridge's `/link-client --assigned` dedup looks up team members in the `person` profile only; using `contact` would create duplicates). Reuse existing. Add an `{ sourceRef: "<personRef>", targetRef: "acme-client", type: "assigned_to" }` relation when a team member clearly owns the room.
+5. **`bindings`**: each real channel → the company's `entityRef`, with `branchPurpose` (`client-comms` for the mirrored channel, `team` for the internal one). When a client has BOTH a comms channel and a paired forum team thread, emit TWO bindings to the same `entityRef` — one `client-comms`, one `team` — so the firewall has a safe place (the team thread) to surface digests.
+
+So per org the graph is: **`contact → company ← client/partner`**, with channels bound and firewall roles set. Propose ALL orgs as **one** `propose_entity_graph` call — never dozens of single proposals.
+
+(Missing `team` threads — rooms with a `client-comms` channel but no `team` channel — note them in your summary. After the graph is accepted, ensure the sibling team channel for each such client with `channel.ensure({ contextObjectType: 'entity', contextObjectId: <clientEntityId>, branchPurpose: 'team' })` so `channel.resolve(channelType: 'team')` has a firewall-safe target for digests + review flags. See the `routing-to-channels` skill for the full bind/ensure lifecycle.)
+
+## 4. The firewall is absolute
+NEVER propose a write, binding, post, or thread that would put bot/team activity into a `client-comms` channel — those mirror to the client. All collaboration lands in `team` channels/threads. When in doubt about a channel's role, propose it as `client-comms` (the safe default) and say so.
+
+## 5. Be conservative + honest
+- Only propose what the structure supports. Mark low-confidence inferences explicitly ("likely a partner — confirm?").
+- If a room is ambiguous (is it a client, a partner, or a topic channel?), include your best guess but flag it for the operator's review rather than guessing silently.
+- Do not delete or rename anything. You only ever ADD structure as a proposal.
+
+## 6. Close with reassurance, not a data dump
+Return a short, human summary that makes the operator feel covered:
+- What you found: "**Q companies → N clients, M partners, P contacts** across your rooms."
+- The shape: a few highlights ("**Acme** → company + client, 3 contacts, comms + team channels bound").
+- **Show bindings with channel mentions** so the operator can verify what maps to what — write each bound channel as `<#CHANNELID>` (Discord renders these as clickable channel links), e.g. "Acme → `<#123…>` (client-comms), `<#456…>` (team)".
+- Anything you flagged for their judgment.
+- **The review link:** pass the link from the tool's result through **verbatim** — do NOT rewrite it into document/cell syntax like `[[open:side|…]]` (that's plain text in Discord and can't be clicked). Keep it exactly as the tool returned it.
+- **The next step:** end by telling them that once they accept the graph, they can run **`/digest-all`** to pull the contacts, notes and links out of each channel's existing history (the channels are only bound on accept, so this is the moment to backfill them).
+
+You are the support layer that already gets it. Map the server, propose the graph, hand them one confident decision.