@synap-core/cli 1.8.0 → 1.11.0

package/skills/synap-ui/ai-companion.md

@@ -0,0 +1,27 @@
+## AI Companion integration
+
+When you create views or entities for the user inside the AI Companion, **always emit inline pattern chips** at the end of your reply so the user can jump directly to what you built.
+
+```
+// After creating a kanban view with ID "abc123":
+"Created your tasks pipeline → [[view:abc123|Active Tasks]] · [[open:side|view:abc123]]"
+
+// After creating a workspace (home bento view ID "def456"):
+"Workspace ready — [[open:main|view:def456|Home Dashboard]]"
+
+// After creating an entity (e.g. a new project):
+"Project created → [[entity:proj_789|Q3 Launch]]"
+```
+
+### Special cell keys (browser-native)
+
+These cell keys are registered in the browser app but may not appear in `GET /api/hub/widget-definitions` (they are Electron-native, not server-seeded):
+
+| Cell key        | Where              | Notes                                                        |
+| --------------- | ------------------ | ------------------------------------------------------------ |
+| `ai-companion`  | Browser sidebar    | The Companion chat panel itself — don't embed in bentos      |
+| `iframe-widget` | Bento blocks       | Sandboxed iframe for custom embeds; requires `src` in config |
+| `entity-detail` | Side panel / modal | Generic entity detail renderer — always available            |
+| `entity-list`   | Bento / views      | List of entities for a given profile                         |
+
+**Rule:** If a cell key is not in `GET /api/hub/widget-definitions`, do NOT reference it in bento config unless it is one of the four browser-native keys above. Unknown keys will silently fail to render.

package/skills/synap-ui/arranging-bento.md

@@ -0,0 +1,8 @@
+## Arranging a bento after creation
+
+```json
+POST /api/hub/views/{bentoViewId}/arrange
+{ "userId": "{userId}", "blocks": [ /* full new blocks array */ ] }
+```
+
+`bento.arrange` is auto-approved by default. Safe to run without hesitation when the user rearranges or adds widgets.

package/skills/synap-ui/before-you-build.md

@@ -0,0 +1,20 @@
+## Before you build anything
+
+Always inventory. Never hallucinate view types, widget kinds, or profiles.
+
+```
+GET /api/hub/manifest
+  → static capability map: view types, bento block kinds, inline patterns, browser-native cells
+    (call once per session — no DB queries, safe to cache)
+
+GET /api/hub/profiles?userId={userId}&workspaceId={workspaceId}
+  → what data exists
+
+GET /api/hub/widget-definitions?workspaceId={workspaceId}
+  → [{ kind, category, label, description, configSchema, supportedContexts }]
+
+GET /api/hub/views?userId={userId}&workspaceId={workspaceId}
+  → [{ id, name, type, profileSlug, config }]
+```
+
+Widget definitions are the source of truth for which cells are installed and how to configure them. **Never guess cell kinds.** If a cell doesn't appear in the registry, don't reference it (unless it's a browser-native cell from the manifest).

package/skills/synap-ui/bento-layouts.md

@@ -0,0 +1,35 @@
+## Bento layouts
+
+A bento is a 12-column react-grid-layout. Blocks reference **cells** by kind.
+
+```json
+POST /api/hub/views            // a bento is just a view with type="bento"
+{
+  "userId":      "{userId}",
+  "workspaceId": "{workspaceId}",
+  "name":        "Content Creation Home",
+  "type":        "bento",
+  "config": {
+    "blocks": [
+      { "id": "b1", "kind": "view",   "viewId":     "<kanbanId>",
+        "layout": { "x": 0, "y": 0, "w": 8, "h": 4 } },
+      { "id": "b2", "kind": "entity", "entityId":   "ent_current_project",
+        "layout": { "x": 8, "y": 0, "w": 4, "h": 4 } },
+      { "id": "b3", "kind": "widget", "widgetKind": "quick-access",
+        "layout": { "x": 0, "y": 4, "w": 6, "h": 2 },
+        "config": { "items": [ … ] } },
+      { "id": "b4", "kind": "widget", "widgetKind": "stat-card",
+        "layout": { "x": 6, "y": 4, "w": 6, "h": 2 },
+        "config": { "metric": "entities_created_this_week" } }
+    ]
+  }
+}
+```
+
+Block kinds:
+
+- `view` — embeds a saved view by `viewId`
+- `entity` — renders an entity card for a specific `entityId`
+- `widget` — renders a registered cell by `widgetKind` with `config`
+
+Full widget catalog in **`widget-catalog.md`**. Layout patterns in **`bento-recipes.md`**.

package/skills/synap-ui/common-mistakes.md

@@ -0,0 +1,10 @@
+## Common mistakes — UI generation
+
+1. **Creating a workspace without asking.** Always propose + confirm. Workspaces are too big to auto-commit.
+2. **Guessing widget kinds.** Always `GET /widget-definitions` first. A `kind` that isn't in the registry won't render.
+3. **Reinventing views.** Check existing views first — a kanban for tasks probably exists.
+4. **Creating a new profile when UI is the real need.** Don't create `client` profile for a "contacts who are clients" view — just create a filtered view on `contact`.
+5. **Putting unrelated data in one bento.** A bento tells a story ("my week", "this project", "content pipeline"). Kitchen-sink bentos overwhelm the user.
+6. **Ignoring color/icon.** Profiles and workspaces both take `uiHints.icon` and `uiHints.color` — set them. Untitled gray workspaces feel like a bug.
+7. **Hardcoding config for view types you haven't checked.** Each view type's `config` shape is different. Get an example from `/views` first.
+8. **Forgetting entityScope implications.** A view on a pod-scope profile (`note`) will show entities from every workspace the user can access — filter appropriately if you want workspace-local results.

package/skills/synap-ui/creating-views.md

@@ -0,0 +1,26 @@
+## Creating a view
+
+```json
+POST /api/hub/views
+{
+  "userId":      "{userId}",
+  "workspaceId": "{workspaceId}",
+  "name":        "Active Tasks by Project",
+  "type":        "kanban",
+  "profileSlug": "task",
+  "config": {
+    "groupBy":  { "property": "projectId" },
+    "columns":  [
+      { "slug": "title" },
+      { "slug": "priority" },
+      { "slug": "dueDate" }
+    ],
+    "filters":  [
+      { "property": "status", "op": "in", "value": ["todo", "in-progress"] }
+    ],
+    "sort":     [{ "property": "priority", "direction": "desc" }]
+  }
+}
+```
+
+The `config` shape varies by view type — kanban needs `groupBy`, calendar needs a date property, gallery needs an image property. When in doubt, fetch an existing view of the same type first and mirror its structure.

package/skills/synap-ui/four-builds.md

@@ -0,0 +1,24 @@
+## Four things you can build
+
+1. **Views** — named queries + rendering config over entities of a given profile. Kanban of tasks, gallery of articles, calendar of events.
+2. **Bento dashboards** — 12-col grid compositions of cells (view-cards, entity-cards, widgets). The Home dashboard is a bento. Workspace landing pages are bentos.
+3. **Workspaces** — full lenses with profiles, views, a bento, and seed entities. The biggest building block.
+4. **New cell types** (Capability B) — AI can define entirely new rendering cells when no existing widget covers the need. Cells run in a sandboxed iframe. Pod-global cells (no `workspaceId`) are available immediately in all workspaces without a proposal step.
+
+   ```json
+   POST /api/hub/cells/define
+   {
+     "name":           "Burndown Chart",
+     "rendererSource": "<!DOCTYPE html>…</html>",
+     "typeKey":        "burndown-chart",
+     "description":    "Sprint burndown over task completions",
+     "defaultSize":    { "w": 8, "h": 6 },
+     "deps": {
+       "recharts": "2.12.0"
+     }
+   }
+   ```
+
+   - `deps` pins npm packages for the esm.sh import map. Keys are npm package names; values are version strings. Max 30 entries. React 19 is always available — never put it in `deps`.
+   - Always `GET /api/hub/widget-definitions` first — if a cell already covers the need, use it. New cell definitions are permanent; only create when genuinely novel.
+   - For the full in-frame query/mutate/shell-actions API see the `synap` skill's **ViewFrame Cells** section (or load `synap-ui:SKILL` via `GET /api/hub/skills/system?sections=synap-ui:SKILL`).

package/skills/synap-ui/more.md

@@ -0,0 +1,7 @@
+## When you need more — UI generation
+
+- Full per-view-type `config` shapes → **`view-types.md`**
+- Complete widget/cell catalog + configSchemas → **`widget-catalog.md`**
+- Ready-to-reuse bento layouts for common use cases → **`bento-recipes.md`**
+- Creating the underlying data → use core **`synap`** skill
+- Extending profiles with new fields before building views → use **`synap-schema`** skill

package/skills/synap-ui/proposing-vs-extending.md

@@ -0,0 +1,11 @@
+## Proposing vs. extending
+
+Before proposing a new workspace, ask: does one of the user's existing workspaces fit? A "Content" workspace and a "Writing" workspace are the same lens. Adding a view to the existing workspace is almost always better than creating a new one.
+
+Create new when:
+
+- The user explicitly asks for it ("new workspace for…")
+- The data and access patterns are genuinely orthogonal to existing workspaces
+- A different team/collaborator set makes sense
+
+Otherwise: add a view, add a bento block, add properties — don't multiply workspaces.

package/skills/synap-ui/view-list.md

@@ -0,0 +1,24 @@
+## View types (16 total, 12 implemented)
+
+Pick one that matches the data's shape AND the user's intent:
+
+| Type             | Implemented | When it fits                                               |
+| ---------------- | ----------- | ---------------------------------------------------------- |
+| `table`          | yes         | Dense data, many columns, sort/filter heavy                |
+| `list`           | yes         | Scan-friendly, compact rows (tasks, notes)                 |
+| `grid`           | yes         | Card grid, medium density                                  |
+| `gallery`        | yes         | Image-forward cards (articles, bookmarks, products)        |
+| `kanban`         | yes         | Status pipelines (tasks by status, deals by stage)         |
+| `matrix`         | yes         | 2-axis grid (priority × urgency, effort × impact)          |
+| `masonry`/`feed` | yes         | Pinterest-style, mixed-size cards; default for Library     |
+| `calendar`       | yes         | Date-indexed data (events, tasks by dueDate)               |
+| `flow`           | yes         | Node-edge diagrams (automations, mind maps)                |
+| `bento`          | yes         | Mixed composition (a dashboard-in-view)                    |
+| `branch_tree`    | yes         | Hierarchical data (project → subtasks, threads → branches) |
+| `whiteboard`     | yes         | Free-form canvas                                           |
+| `timeline`       | no          | (Defer)                                                    |
+| `graph`          | no          | (Defer)                                                    |
+| `gantt`          | no          | (Defer)                                                    |
+| `mindmap`        | no          | (Defer)                                                    |
+
+Decision: the data has statuses → `kanban`. Dates → `calendar`. Many columns → `table`. Mixed types → `masonry` or `bento`. Full reference in **`view-types.md`**.

package/skills/synap-ui/views.md

@@ -0,0 +1,3 @@
+# Synap — UI generation
+
+You build the surfaces the user sees: views over their data, bento dashboards, full workspaces tuned for a domain. The core rule: **emergent complexity.** A workspace is a lens; a view is a lens; a bento is a composition of lenses. Everything renders through the cell system, nothing is hardcoded.

package/skills/synap-ui/worked-example.md

@@ -0,0 +1,18 @@
+## Worked example — "Make me a CRM"
+
+1. Inventory. User already has `person`, `contact`, `company`, `deal`, `event` profiles (all system).
+2. No new profiles needed. The CRM is a **lens**, not new data.
+3. Propose (before committing):
+   - Workspace name: "CRM"
+   - Views:
+     - `Deals Pipeline` — kanban on `deal`, groupBy `stage`
+     - `Contacts` — table on `contact`, columns: name, role, company, lastInteraction
+     - `Companies` — gallery on `company` (logo-forward)
+     - `Upcoming Meetings` — calendar on `event`, filter `relatedToContact`
+   - Bento:
+     - Top: `deals pipeline` view (8 cols × 4 rows)
+     - Side: `stat-card` — "Deals in pipeline: $X" (4 cols × 2 rows)
+     - Side: `stat-card` — "Meetings this week: N" (4 cols × 2 rows)
+     - Bottom: `recent-activity` widget (12 cols × 3 rows)
+4. Show to user. Confirm.
+5. Commit via `POST /workspaces`.

package/skills/synap-ui/workspaces.md

@@ -0,0 +1,47 @@
+## Creating or proposing a workspace
+
+**Always ask before creating.** Workspaces are big objects with profiles, views, members, bento, and seed data. Commit only after user confirms.
+
+The canonical flow:
+
+1. **Assemble a proposal** (no API call yet):
+
+   ```js
+   const proposal = {
+     name: "Content Creation",
+     description: "Draft, review, and publish articles",
+     icon: "pen-tool",
+     color: "purple",
+     profiles: [                 // reuse system profiles by slug OR include custom ones
+       { slug: "article", reuse: true },
+       { slug: "draft",   displayName: "Draft", parentSlug: "article",
+         properties: [
+           { slug: "status", valueType: "string", constraints: { enum: ["idea","writing","review","published"] }, uiHints: { displayAs: "status" } },
+           { slug: "wordCount", valueType: "number" },
+           { slug: "publishDate", valueType: "date" }
+         ]
+       }
+     ],
+     views: [
+       { name: "Pipeline", type: "kanban", profileSlug: "draft",
+         config: { groupBy: { property: "status" } } },
+       { name: "Published", type: "gallery", profileSlug: "article",
+         config: { filters: [{ property: "status", op: "eq", value: "published" }] } }
+     ],
+     bento: { blocks: [ … ] },
+     seedEntities: []            // optional
+   }
+   ```
+
+2. **Show it to the user**. Compact, readable. "Here's what I'd create — 2 profiles, 2 views, a bento. Ship it?"
+
+3. **On yes**, commit through `/api/hub/workspaces`:
+
+   ```json
+   POST /api/hub/workspaces
+   { "userId": "{userId}", "proposal": { /* the object above */ } }
+   ```
+
+   This goes through governance — `workspace.create` is **always** proposal-gated even for agents (see `../synap/governance.md`). Expect `status: "proposed"` and tell the user they'll see it in Proposals.
+
+4. **On no**, don't commit. Offer to adjust.

package/templates/automations/bookmark-enrichment.automation.json

@@ -0,0 +1,44 @@
+{
+  "name": "Bookmark Enrichment (auto)",
+  "triggerType": "event",
+  "status": "active",
+  "triggerConfig": {
+    "eventPattern": "entity.create.completed",
+    "filters": { "profileSlug": "bookmark" }
+  },
+  "flowDefinition": {
+    "nodes": [
+      {
+        "id": "trigger",
+        "type": "trigger",
+        "position": { "x": 0, "y": 0 },
+        "data": {
+          "triggerType": "event",
+          "label": "Bookmark created",
+          "config": {
+            "eventPattern": "entity.create.completed",
+            "filters": { "profileSlug": "bookmark" }
+          }
+        }
+      },
+      {
+        "id": "enrich",
+        "type": "skill",
+        "position": { "x": 0, "y": 120 },
+        "data": {
+          "label": "Bookmark Enrichment",
+          "skillName": "bookmark-enrichment",
+          "skillTitle": "Bookmark Enrichment",
+          "inputMapping": {
+            "entityId": "{{trigger.payload.subjectId}}"
+          }
+        }
+      }
+    ],
+    "edges": [{ "id": "e1", "source": "trigger", "target": "enrich" }]
+  },
+  "metadata": {
+    "source": "bridge-template",
+    "note": "The skill node carries `skillName`; the CLI seed command resolves it to the live `skillId` at install time (GET /skills by name)."
+  }
+}

package/templates/automations/mail-feed.automation.json

@@ -0,0 +1,86 @@
+{
+  "name": "Mail feed → Discord (AI-triaged)",
+  "triggerType": "cron",
+  "status": "draft",
+  "triggerConfig": { "expression": "0 */2 * * *" },
+  "flowDefinition": {
+    "nodes": [
+      {
+        "id": "trigger",
+        "type": "trigger",
+        "position": { "x": 0, "y": 0 },
+        "data": {
+          "triggerType": "cron",
+          "label": "Every 2 hours",
+          "config": { "expression": "0 */2 * * *" }
+        }
+      },
+      {
+        "id": "fetch-mail",
+        "type": "capability",
+        "position": { "x": 0, "y": 120 },
+        "data": {
+          "label": "Search Gmail (source verb)",
+          "verbId": "gmail_search",
+          "inputMapping": { "query": "newer_than:2d", "maxResults": "25" },
+          "connectionSelector": { "connectionId": "" }
+        }
+      },
+      {
+        "id": "triage",
+        "type": "capability",
+        "position": { "x": 0, "y": 240 },
+        "data": {
+          "label": "AI triage (batch classifier verb)",
+          "verbId": "ai.triage",
+          "inputMapping": { "emails": "{{steps.fetch-mail.output.results}}" }
+        }
+      },
+      {
+        "id": "relevant-loop",
+        "type": "loop",
+        "position": { "x": 0, "y": 360 },
+        "data": {
+          "label": "For each relevant email",
+          "iteratorExpression": "steps.triage.output.results",
+          "itemVariable": "email"
+        }
+      },
+      {
+        "id": "post-to-feed",
+        "type": "output",
+        "position": { "x": 0, "y": 480 },
+        "data": {
+          "label": "Post to the Discord-bound feed channel",
+          "outputType": "channel_message",
+          "config": {
+            "channelId": "<discord-bound team feed channel id>",
+            "content": "**{{loop.item.subject}}** — _{{loop.item.category}}_\n{{loop.item.summary}}",
+            "channelType": "proactive",
+            "metadata": {
+              "proactiveType": "mail-feed",
+              "gmailId": "{{loop.item.id}}"
+            }
+          }
+        }
+      }
+    ],
+    "edges": [
+      { "id": "e1", "source": "trigger", "target": "fetch-mail" },
+      { "id": "e2", "source": "fetch-mail", "target": "triage" },
+      { "id": "e3", "source": "triage", "target": "relevant-loop" },
+      { "id": "e4", "source": "relevant-loop", "target": "post-to-feed" }
+    ]
+  },
+  "metadata": {
+    "source": "feed-template",
+    "purpose": "CANONICAL example of the North Star: a FEED is an AUTOMATION that composes capability verbs. Cron → gmail_search (source verb) → AI triage (classifier verb) → loop → post relevant items to a Discord-bound feed channel. Replaces the bespoke run-mail-feed.ts worker with pure config.",
+    "prerequisites": [
+      "Wave 1 (SHIPPED): the `capability` node dispatches gmail_search (declarative) + any verb through executeCapability.",
+      "verb `ai.triage`: a batch email classifier verb must be seeded (today this is the mail_triage IS route; roadmap folds it into a verb). Until then, swap the triage node for a `command` node (IS task) or point verbId at the seeded classifier.",
+      "a connected Google account (nango-google) + set connectionSelector.connectionId to pin the mailbox.",
+      "a Discord-bound `branchPurpose:'team'` feed channel — put its id in the post node (or use channelType:'proactive' for the user's feed).",
+      "PER-ITEM filtering/AI inside the loop needs automation Wave 2 (loop body currently allows `output` only — this template does BATCH triage OUTSIDE the loop and posts via an `output.channel_message` node INSIDE the loop, which IS loop-allowed today)."
+    ]
+  }
+}

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 }`.