@synap-core/cli 1.11.0 → 1.12.2

package/skills/synap-schema/intent-vocabulary-ssot.md

@@ -0,0 +1,111 @@
+## The intent vocabulary — one SSOT, three mirrors
+
+**What a capability DOES** — `send_message`, `generate_media`, `publish_post`,
+`delegate_agent_task` — is the
+ROUTING axis over the verb catalog. A verb's id is vendor-keyed (`gmail_send`,
+`unipile_send_message`); its `intent` says what it MEANS, so an agent can ask for
+"send a message" without already knowing the vendor.
+
+An intent is **routing only, never authorization**. It resolves to a concrete verb id
+BEFORE the governance gate, which then decides on the verb exactly as it did before.
+
+### THE SOURCE OF TRUTH IS A TABLE, NOT A UNION
+
+The SSOT is the pod's **`capability_intents` table**. Slugs live in ROWS, not in a
+TypeScript union:
+
+```sql
+SELECT slug, effect, statement FROM capability_intents ORDER BY slug;
+```
+
+| Column      | Meaning                                                   |
+| ----------- | --------------------------------------------------------- |
+| `slug`      | the seat. `^[a-z][a-z0-9_]{0,63}$` (a CHECK constraint)   |
+| `effect`    | CLOSED axis a rule may key on: `read` \| `write` \| `act` |
+| `statement` | the human sentence                                        |
+| `synonyms`  | for FINDING a row, never for identity                     |
+
+This is why every code-side copy is a **mirror** and not the source. A slug that fits
+none of the existing rows leaves `intent` UNSET; the vocabulary is deliberately not
+open for developers to mint (cf. W3C Web Intents, abandoned partly for that reason).
+
+### The three mirrors, and why each one must exist
+
+There are exactly **three**. A fourth was deleted in 2026-10-01 (see below).
+
+| #   | Where                                                                                                                             | Kind                              | Why it cannot import the SSOT                                                                                                                                                                                                                                |
+| --- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1   | `synap-backend/packages/database/src/schema/tools.ts` — `ABSTRACT_VERBS`                                                          | runtime, the 0283 SEED union (13) | `@synap-core/types` **devDepends on** `@synap/database`. A reverse import is a build cycle — the same constraint that forces `GUIDELINE_SCOPE_ORDER` to be mirrored.                                                                                         |
+| 2   | `synap-backend/packages/types/src/capability-intents/` — `ABSTRACT_INTENTS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS`            | runtime, published leaf           | Same cycle, other direction. It is a **leaf subpath** (`@synap-core/types/capability-intents`) rather than the `./` barrel because the barrel re-exports `@synap/database` types and a VALUE import from a barrel crashes Hermes (relay ships React Native). |
+| 3   | `synap-control-plane-api/src/seeds/capability-intent-vocabulary.ts` — `ABSTRACT_VERBS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS` | runtime, the CP catalog seeder    | The control plane is a **separate deploy target with its own `pnpm-lock.yaml`**. It resolves neither `@synap-core/types` nor the pod's packages (verified: `require.resolve('@synap-core/types')` → `MODULE_NOT_FOUND`).                                     |
+
+Consumed by: `@synap/api` (`intent-registry`, `create-from-definition`,
+`schemas/playbook-definition.ts`), `synap-app/packages/workspace-templates`
+(`validate.ts` — the `taskIntents` check), and the CP's `seed-capability-templates.ts`
+(only the insert-only bootstrap of an empty CP — official capabilities are authored in
+the catalog, `synap-app/packages/workspace-templates/capabilities/`, and published with
+`synap catalog publish --official`).
+
+### Which field on which surface
+
+Search for this chapter by the field you are holding, not by the word "intent":
+
+| Field             | Lives on                                                           | Means                                                                           |
+| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `intent`          | a **skill** in a capability definition; a `ToolVerb` catalog entry | what ONE verb does                                                              |
+| `provides`        | a **capability template**                                          | every intent the whole PACK serves — must equal the `intent` its skills declare |
+| `taskIntents`     | a **workspace template**                                           | what the SPACE needs the pod to be able to do                                   |
+| `requiredIntents` | a **playbook**                                                     | what the PROCESS needs the pod to be able to do                                 |
+
+All four are validated against this ONE vocabulary, so a workspace and a playbook
+cannot be spelled from two different lists.
+
+### THE FOURTH MIRROR WAS DELETED — do not re-add it
+
+`AbstractVerb` in `@synap/playbooks/src/index.ts` was a TYPE-only mirror of all 13
+slugs. It was **stale** (no `publish_post`) and **dead** — a whole-repo scan across
+every repo, `src/`, `dist/`, and generated `.d.ts` found **zero importers**.
+
+A mirror nothing imports and nothing checks is not a mirror: it is a comment that
+looks like a contract. `packages/playbooks/src/required-intents.test.ts` now refuses
+`AbstractVerb`, `ABSTRACT_INTENTS`, or `REGISTERED_EXTRAS` being re-declared there.
+
+`ToolVerb.intent` is `string`, not a closed union, and must stay that way: a union in
+a package that consumes nothing would go stale in the one direction that is invisible.
+
+### Adding a slug — the exact steps
+
+1. **Write the migration.** A new numbered `.sql` in `synap-backend/packages/database/migrations/`,
+   `INSERT INTO "capability_intents" ("slug", "effect", "statement") VALUES (...) ON CONFLICT ("slug") DO NOTHING;`
+   `effect` ∈ `read|write|act`. Never `drizzle-kit generate` — hand-write it, and mirror it into
+   `0000_baseline_schema.sql` if it adds a table or column.
+2. **Add it to mirror 1** — `ABSTRACT_VERBS` in `packages/database/src/schema/tools.ts`,
+   **only if it is a SEED slug**. A post-seed row does not belong there (that is what
+   `publish_post` / `REGISTERED_EXTRAS` is for).
+   Post-seed rows today: `publish_post` (0284, write) and `delegate_agent_task`
+   (0314, act — every verb of an external-agent binding, `tools.config.agentBinding`:
+   start / send / status / cancel).
+3. **Add it to mirror 2** — `ABSTRACT_INTENTS` or `REGISTERED_EXTRAS` in
+   `packages/types/src/capability-intents/index.ts`. Then **`cd packages/types && pnpm build`** —
+   consumers typecheck against the built `dist/`, so a skipped rebuild makes your gate lie.
+4. **Add it to mirror 3** — the same two lists in the control plane's
+   `capability-intent-vocabulary.ts`.
+5. **Update the arity floors** — `SEED_SLUG_ARITY` / `EXTRA_SLUG_ARITY` in
+   `packages/api/src/__tripwires__/intent-vocabulary-one-ssot.tripwire.test.ts`.
+   These are the ONE place you must edit by hand, and the build stops until you do.
+
+A slug in the table but missing from a mirror is **not silent**: every guard re-derives
+from the migration SQL, so it is a red build — never a divergence nobody notices.
+
+### What can still go wrong
+
+- **A mirror can be added.** Nothing structurally prevents a fifth copy; the tripwire
+  only polices the names it knows. This is why step 5 exists as a hand-edit floor.
+- **A guard proves SAMENESS, never CORRECTNESS.** If every mirror and the migration agree
+  on a slug that should not exist, all four guards stay green. The vocabulary's MEANING is
+  reviewed by a human, not derived.
+- **A new migration file is not auto-scanned.** Each parity guard lists its migration
+  filenames. A slug added in `0295_…sql` is invisible to all of them until that list is
+  extended — so extending it is part of step 1, not a follow-up.
+- **`@synap-core/types` is published.** Mirror 2 ships to npm; changing it without a
+  version bump leaves consumers on the old vocabulary.

package/skills/synap-schema/property-types.md

@@ -74,7 +74,7 @@ Set `includeTime: true` for datetime; false for date-only. Don't store durations
 }
 ```
 
-**Always set `targetProfileSlug`** (or `targetProfileSlugs: [...]` for multi-target). Without it, UI can't render a picker and auto-sync defaults to `related_to`.
+**Always set `targetProfileSlug`** (or `targetProfileSlugs: [...]` for multi-target). Without it, UI can't render a picker. Setting it does not create an edge: auto-sync writes a relation only when the property def is mapped to a relation def (`relationDefId`); an unmapped `entity_id` property creates no relation and has no default type.
 
 For linking to users (workspace members), use:
 

package/skills/synap-schema/relations.md

@@ -15,4 +15,4 @@ POST /api/hub/relation-defs
 }
 ```
 
-Defining a relation def is rarely worth it — `related_to` + a property usually suffices. Only create one when the relationship is semantic enough that UI should treat it specially (e.g., show "mentored by Jane" on a person's profile card).
+Defining a relation def is rarely worth it — `relates_to` + a property usually suffices. Only create one when the relationship is semantic enough that UI should treat it specially (e.g., show "mentored by Jane" on a person's profile card).

package/skills/synap-ui/SKILL.md

@@ -14,7 +14,7 @@ description: >
   to the user before committing — workspaces are lenses on data, not silos,
   and the user decides when a new lens is warranted.
 metadata:
-  openclaw:
+  synap:
     requires:
       env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
     primaryEnv: SYNAP_HUB_API_KEY
@@ -77,6 +77,11 @@ Widget definitions are the source of truth for which cells are installed and how
    - `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`).
+   - **"Make this my Posts dashboard"** = a cell bound to the kind's `dashboard` slot, not a new workspace:
+     1. `create_cell` a frame that reads what the kind's own page reads, through the bridge's intent reads: `lifecycle.board`, `lifecycle.throughput`, `attention.needsYou`, `attention.count`, `sessions.list` (params and shapes: `synap` skill, ViewFrame Cells → "Intent reads"). Never pre-fetch rows into the source.
+     2. `promote_cell_to_renderer({ profileSlug: "post", slot: "dashboard", cellKey })`. `dashboard` is the `entity-profile` content kind. It is governed, so `proposed` is success.
+     - On a kind with a lifecycle the cell fills the **Dashboard** tab and the Pipeline tab stays the board (its moves and card frame are the kind's). On a kind without one, the cell is the page.
+     - A saved view can take the same slot from the app (Keep → Become renderer of… → Whole profile dashboard). Any view type renders there.
 
 ---
 
@@ -150,15 +155,15 @@ POST /api/hub/views            // a bento is just a view with 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" } }
+        "pos": { "x": 0, "y": 0, "w": 8, "h": 4 } },
+      { "id": "b2", "kind": "entity", "entityId":   "<entityId>",
+        "pos": { "x": 8, "y": 0, "w": 4, "h": 4 } },
+      { "id": "b3", "kind": "widget", "widgetType": "quick-access",
+        "pos": { "x": 0, "y": 4, "w": 6, "h": 2 },
+        "config": {} },
+      { "id": "b4", "kind": "widget", "widgetType": "stat-card",
+        "pos": { "x": 6, "y": 4, "w": 6, "h": 2 },
+        "config": { "profileSlug": "note", "label": "Notes this week", "timePeriod": "week" } }
     ]
   }
 }
@@ -168,7 +173,7 @@ 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`
+- `widget` — renders a catalog cell by `widgetType` (a key from `synap_list_widgets`) with `config`; `pos` places every block
 
 Full widget catalog in **`widget-catalog.md`**. Layout patterns in **`bento-recipes.md`**.
 
@@ -268,6 +273,8 @@ POST /api/hub/views/{bentoViewId}/arrange
 
 `bento.arrange` is auto-approved by default. Safe to run without hesitation when the user rearranges or adds widgets.
 
+Call `synap_list_widgets` first. Only place keys from that list. `stat-card` needs `profileSlug`. `view` / `view-table` need a saved `viewId`. `entity-count` is a legacy alias of `stat-card` — prefer `stat-card`.
+
 ---
 
 ## Common mistakes — UI generation
@@ -292,7 +299,7 @@ When you create views or entities for the user inside the AI Companion, **always
 "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]]"
+"Space ready — [[open:main|view:def456|Home Dashboard]]"
 
 // After creating an entity (e.g. a new project):
 "Project created → [[entity:proj_789|Q3 Launch]]"

package/skills/synap-ui/_skill.yaml

@@ -13,7 +13,7 @@ description: >
   to the user before committing — workspaces are lenses on data, not silos,
   and the user decides when a new lens is warranted.
 metadata:
-  openclaw:
+  synap:
     requires:
       env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
     primaryEnv: SYNAP_HUB_API_KEY

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

@@ -7,7 +7,7 @@ When you create views or entities for the user inside the AI Companion, **always
 "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]]"
+"Space ready — [[open:main|view:def456|Home Dashboard]]"
 
 // After creating an entity (e.g. a new project):
 "Project created → [[entity:proj_789|Q3 Launch]]"

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

@@ -6,3 +6,5 @@ POST /api/hub/views/{bentoViewId}/arrange
 ```
 
 `bento.arrange` is auto-approved by default. Safe to run without hesitation when the user rearranges or adds widgets.
+
+Call `synap_list_widgets` first. Only place keys from that list. `stat-card` needs `profileSlug`. `view` / `view-table` need a saved `viewId`. `entity-count` is a legacy alias of `stat-card` — prefer `stat-card`.

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

@@ -12,15 +12,15 @@ POST /api/hub/views            // a bento is just a view with 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" } }
+        "pos": { "x": 0, "y": 0, "w": 8, "h": 4 } },
+      { "id": "b2", "kind": "entity", "entityId":   "<entityId>",
+        "pos": { "x": 8, "y": 0, "w": 4, "h": 4 } },
+      { "id": "b3", "kind": "widget", "widgetType": "quick-access",
+        "pos": { "x": 0, "y": 4, "w": 6, "h": 2 },
+        "config": {} },
+      { "id": "b4", "kind": "widget", "widgetType": "stat-card",
+        "pos": { "x": 6, "y": 4, "w": 6, "h": 2 },
+        "config": { "profileSlug": "note", "label": "Notes this week", "timePeriod": "week" } }
     ]
   }
 }
@@ -30,6 +30,6 @@ 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`
+- `widget` — renders a catalog cell by `widgetType` (a key from `synap_list_widgets`) with `config`; `pos` places every block
 
 Full widget catalog in **`widget-catalog.md`**. Layout patterns in **`bento-recipes.md`**.