@synap-core/cli 1.10.0 → 1.12.2

package/skills/synap-schema/SKILL.md

@@ -9,11 +9,13 @@ description: >
   schema", defining custom relations, setting up a profile for a specific domain
   (real estate, music production, research, fitness, cooking). Also triggers on:
   "do I already have a profile for X?", "what fields does <profile> have?",
-  extending an existing profile with workspace-specific overlay properties.
+  extending an existing profile with workspace-specific overlay properties,
+  widening a role so a hat fits another kind (any kind, not only person/company).
+  Prefer extend-first (system/synap-schema/extend-first) before define_kind.
   Do NOT use this skill for creating instances of existing types — the core
   `synap` skill handles that. This skill changes the SCHEMA, not the data.
 metadata:
-  openclaw:
+  synap:
     requires:
       env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
     primaryEnv: SYNAP_HUB_API_KEY
@@ -117,7 +119,7 @@ Read the response:
 
 ### Commonly seeded profiles (verify before using)
 
-Standard pods typically include: `note`, `task`, `project`, `event`, `person`, `contact`, `company`, `bookmark`, `website`, `article`, `capture`, `file`, `anchor`, `decision`, `question`, `research`
+Standard pods typically include: `note`, `task`, `event`, `person`, `contact`, `company`, `item`, `bookmark`, `website`, `article`, `capture`, `file`, `anchor`, `decision`, `question`, `research`. A **project is not a profile** — it is a row in `projects`. Roles (vendor, client, …) appear as `profileKind: role`.
 
 CRM workspaces additionally have: `deal`, `client` — but **only** when a CRM workspace was created.  
 Custom workspace templates (devplane, content, etc.) add their own profiles entirely.
@@ -130,7 +132,7 @@ Before creating a new profile: **does one of these already fit?** A podcast epis
 
 There are three moves, not two. Before extending or creating, ask whether the thing is really a **role** the entity plays rather than a new kind of entity at all — that's a facet, and it's the move people skip.
 
-**Kind + Facets, the rule:** one entity = one kind (`profiles.profileKind = 'kind'`). Roles the entity plays — client, partner, investor, prospect — are role-profiles (`profileKind = 'role'`, `applicableKinds[]`) attached via `entity_facets`: additive, workspace-lensed, NOT entities. A facet cascades with its parent entity; only promote a role to a full kind if it accrues its own independent life.
+**Kind + Facets, the rule:** one entity = one kind (`profiles.profileKind = 'kind'`). Roles are hats on **any** kind — not only person/company. A role-profile (`profileKind = 'role'`, `applicableKinds[]`) attaches via `entity_facets`: additive, workspace-lensed, NOT a second entity. `applicableKinds` NULL = any kind; a list **restricts**. “This item is an X” is a facet on `item` when X is a hat, not a new kind. Only promote a role to a full kind if it accrues its own independent life. Widen a role (`define_role` on the existing slug) when the hat fits a kind that is not yet in `applicableKinds`. See `extend-first.md`.
 
 **The litmus test:**
 
@@ -160,6 +162,38 @@ Prefer **inheritance** over new profiles when a system parent fits. `contact ext
 
 ---
 
+## Extend first — schema moves, in order
+
+Before `define_kind` or a new workspace, walk this list **top to bottom**. Stop at the first move that fits. Load from `system/synap-schema/extend-first`. The conductor for a fuzzy user intent is `system/synap/from-intent`.
+
+A **role (facet) is a hat on any entity kind**, not only person/company. `applicableKinds` is the allowlist (`NULL` = any kind). `kind_mismatch` means **widen the role**, not mint a sibling type.
+
+| #   | If the need is…                                                                              | Do this                                                                                                                                                       | Do not                                                                   |
+| --- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 1   | An instance of a kind you already have                                                       | `create_entity` / capture on that slug; search first                                                                                                          | A second kind with a similar name                                        |
+| 2   | A **hat** on an existing entity (“this item is an X”, “this company is a vendor”)            | `attach_facet`. If the role exists but not on this kind → **widen `applicableKinds`** (same slug, extra kinds) then attach                                    | A new kind or a second role slug (`seller` vs `vendor`)                  |
+| 3   | 1–3 extra fields in **one** domain                                                           | Workspace **overlay** property on the existing kind                                                                                                           | A forked kind in that workspace                                          |
+| 4   | A true **subtype** with its own fields and life                                              | Child kind: `define_kind` with `parentProfileSlug` of the closest parent                                                                                      | A disconnected top-level kind                                            |
+| 5   | A **relationship-with-a-life** (buyer × seller × price × stage, independent of either party) | Own kind (the **deal precedent**). New slug if CRM `deal` is a _sales pipeline_ and this is not that. Overlay if it **is** the same kind in another workspace | Twin slug `deal`; JSON arrays of prices on the thing; Finding-per-scrape |
+| 6   | A **stage** inside a domain                                                                  | Status field + view                                                                                                                                           | A workspace per stage                                                    |
+| 7   | A **domain** (owns kinds + own team + automations + stable)                                  | Four-test → `agent-os` / template                                                                                                                             | A workspace for a project, a hat, or a shopping list                     |
+| 8   | None of the above                                                                            | `define_kind` (pod-wide default)                                                                                                                              | Silent invent                                                            |
+
+Same **kind** across workspaces: **one profile**, overlays for extra fields, optional `entityScope: pod` (pod-admin) so instances are not trapped. Never a second profile with the same name.
+
+### Widen a role
+
+`synap_define_role` with an **existing** slug is slug-idempotent: extra `applicableKinds` are **merged** (widen only). Shrinking the allowlist is not this door.
+
+### Firewalls
+
+- `list_profiles` before every define.
+- Prefer attach / widen / overlay / parent over create.
+- One structural proposal at a time.
+- `proposed` is success.
+
+---
+
 ## Creating a new profile
 
 ```json
@@ -241,10 +275,22 @@ Overlays don't leak: workspace A can't see workspace B's overlay properties even
 
 Profiles have an `entityScope` that determines where entities of that type live:
 
-- `entityScope: "pod"` — entities are pod-wide, visible in every workspace the user can access. Good for people, companies, notes, articles — things that cross contexts.
-- `entityScope: "workspace"` — entities live in the workspace they were created in. Good for deals, files, workspace-specific artifacts.
+- `entityScope: "pod"` — entities are **pod-wide** (home `workspace_id = NULL`). Visible under ACL + role-as-lens facets — **not** exclusive to one app. Good for people, companies, notes, articles, knowledge/lessons — identity and memory that cross contexts.
+- `entityScope: "workspace"` — entities live in the workspace they were created in (process kinds). Good for deals, pipelines, workspace-specific artifacts.
+
+**Default is `pod`** (schema column default + write door). Only declare `entityScope: "workspace"` when the kind is a genuine process document that must not float pod-wide.
+
+### Pin ≠ exclusive prison
 
-Defaults to `workspace` if not set on the profile. The user can toggle this per profile in ProfileEditor Settings. If you're creating a profile for something clearly pod-wide (a person, a podcast the user follows, a book in their library), set `entityScope: "pod"` explicitly.
+Filing into a workspace sets a **home pin**, not exclusive ownership. Role facets make the same person visible in CRM (or Operations) without copying the row. Never treat workspace pin as a folder that traps identity.
+
+### Write pins (agents & capture)
+
+- **Omit** `workspaceId` for pod-scope kinds — server placement lands them pod-wide.
+- **Ambient / active workspace** is a **list lens** and optional process home, not a silent dump target.
+- Process kinds + explicit pin / routed domain home use `resolveKindWritePin` (one rule for capture, import, thought).
+
+If you're creating a profile for something clearly pod-wide (a person, a podcast, a book, a lesson), leave default pod or set `entityScope: "pod"` explicitly. Do **not** set workspace "to be safe" — that reintroduces folder-trap bugs.
 
 ---
 
@@ -265,7 +311,121 @@ 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).
+
+---
+
+## 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.
 
 ---
 
@@ -308,9 +468,11 @@ Defining a relation def is rarely worth it — `related_to` + a property usually
 2. **Declaring properties inline on the profile object.** Properties are separate rows; use `POST /property-defs`.
 3. **Using `string` for what should be `entity_id`.** If the field refers to another entity (host of a podcast), use `entity_id` + `targetProfileSlug` — enables auto-sync and link UX.
 4. **Using `array` of strings for tags.** Tags are a built-in concept; reuse the `tags` property on `note`/`project` instead of creating a parallel field.
-5. **Forgetting `entityScope`.** Defaults to `workspace`. If the thing is pod-wide (people, books, podcasts), set it explicitly.
+5. **Wrong `entityScope`.** Defaults to **`pod`**. Only set `entityScope: "workspace"` for process kinds (deals, pipelines). Do not pin people/knowledge to a workspace "to be safe."
 6. **Creating an overlay when a base property is wanted.** Overlays only appear in one workspace. If the user wants the field everywhere, don't set `overlay: true`.
-7. **Creating a custom profile when extension would work.** `client extends contact` is cleaner than a parallel `client` profile.
+7. **Creating a custom profile when extension would work.** Child kind (`parentProfileSlug`) or a **facet on any kind** is cleaner than a twin slug.
+8. **Treating facets as person/company-only.** A hat can sit on `item`, `task`, `deal`, …. `kind_mismatch` → widen `applicableKinds`, don't mint `seller` next to `vendor`.
+9. **Twin `deal` slug for a price timeline.** CRM `deal` is a sales pipeline. A commercial snapshot with its own life is the deal _precedent_ (own kind) or overlays on the same kind — never a second profile named deal.
 
 ---
 

package/skills/synap-schema/_order.txt

@@ -3,11 +3,13 @@ before-you-touch.md
 read-before-write.md
 discover-profiles.md
 extend-vs-create.md
+extend-first.md
 creating-profiles.md
 property-defs.md
 overlay-properties.md
 entity-scope.md
 relations.md
+intent-vocabulary-ssot.md
 worked-example.md
 common-mistakes.md
 more.md

package/skills/synap-schema/_skill.yaml

@@ -8,11 +8,13 @@ description: >
   schema", defining custom relations, setting up a profile for a specific domain
   (real estate, music production, research, fitness, cooking). Also triggers on:
   "do I already have a profile for X?", "what fields does <profile> have?",
-  extending an existing profile with workspace-specific overlay properties.
+  extending an existing profile with workspace-specific overlay properties,
+  widening a role so a hat fits another kind (any kind, not only person/company).
+  Prefer extend-first (system/synap-schema/extend-first) before define_kind.
   Do NOT use this skill for creating instances of existing types — the core
   `synap` skill handles that. This skill changes the SCHEMA, not the data.
 metadata:
-  openclaw:
+  synap:
     requires:
       env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
     primaryEnv: SYNAP_HUB_API_KEY

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

@@ -4,6 +4,8 @@
 2. **Declaring properties inline on the profile object.** Properties are separate rows; use `POST /property-defs`.
 3. **Using `string` for what should be `entity_id`.** If the field refers to another entity (host of a podcast), use `entity_id` + `targetProfileSlug` — enables auto-sync and link UX.
 4. **Using `array` of strings for tags.** Tags are a built-in concept; reuse the `tags` property on `note`/`project` instead of creating a parallel field.
-5. **Forgetting `entityScope`.** Defaults to `workspace`. If the thing is pod-wide (people, books, podcasts), set it explicitly.
+5. **Wrong `entityScope`.** Defaults to **`pod`**. Only set `entityScope: "workspace"` for process kinds (deals, pipelines). Do not pin people/knowledge to a workspace "to be safe."
 6. **Creating an overlay when a base property is wanted.** Overlays only appear in one workspace. If the user wants the field everywhere, don't set `overlay: true`.
-7. **Creating a custom profile when extension would work.** `client extends contact` is cleaner than a parallel `client` profile.
+7. **Creating a custom profile when extension would work.** Child kind (`parentProfileSlug`) or a **facet on any kind** is cleaner than a twin slug.
+8. **Treating facets as person/company-only.** A hat can sit on `item`, `task`, `deal`, …. `kind_mismatch` → widen `applicableKinds`, don't mint `seller` next to `vendor`.
+9. **Twin `deal` slug for a price timeline.** CRM `deal` is a sales pipeline. A commercial snapshot with its own life is the deal _precedent_ (own kind) or overlays on the same kind — never a second profile named deal.

package/skills/synap-schema/discover-profiles.md

@@ -16,7 +16,7 @@ Read the response:
 
 ### Commonly seeded profiles (verify before using)
 
-Standard pods typically include: `note`, `task`, `project`, `event`, `person`, `contact`, `company`, `bookmark`, `website`, `article`, `capture`, `file`, `anchor`, `decision`, `question`, `research`
+Standard pods typically include: `note`, `task`, `event`, `person`, `contact`, `company`, `item`, `bookmark`, `website`, `article`, `capture`, `file`, `anchor`, `decision`, `question`, `research`. A **project is not a profile** — it is a row in `projects`. Roles (vendor, client, …) appear as `profileKind: role`.
 
 CRM workspaces additionally have: `deal`, `client` — but **only** when a CRM workspace was created.  
 Custom workspace templates (devplane, content, etc.) add their own profiles entirely.

package/skills/synap-schema/entity-scope.md

@@ -2,7 +2,19 @@
 
 Profiles have an `entityScope` that determines where entities of that type live:
 
-- `entityScope: "pod"` — entities are pod-wide, visible in every workspace the user can access. Good for people, companies, notes, articles — things that cross contexts.
-- `entityScope: "workspace"` — entities live in the workspace they were created in. Good for deals, files, workspace-specific artifacts.
+- `entityScope: "pod"` — entities are **pod-wide** (home `workspace_id = NULL`). Visible under ACL + role-as-lens facets — **not** exclusive to one app. Good for people, companies, notes, articles, knowledge/lessons — identity and memory that cross contexts.
+- `entityScope: "workspace"` — entities live in the workspace they were created in (process kinds). Good for deals, pipelines, workspace-specific artifacts.
 
-Defaults to `workspace` if not set on the profile. The user can toggle this per profile in ProfileEditor Settings. If you're creating a profile for something clearly pod-wide (a person, a podcast the user follows, a book in their library), set `entityScope: "pod"` explicitly.
+**Default is `pod`** (schema column default + write door). Only declare `entityScope: "workspace"` when the kind is a genuine process document that must not float pod-wide.
+
+### Pin ≠ exclusive prison
+
+Filing into a workspace sets a **home pin**, not exclusive ownership. Role facets make the same person visible in CRM (or Operations) without copying the row. Never treat workspace pin as a folder that traps identity.
+
+### Write pins (agents & capture)
+
+- **Omit** `workspaceId` for pod-scope kinds — server placement lands them pod-wide.
+- **Ambient / active workspace** is a **list lens** and optional process home, not a silent dump target.
+- Process kinds + explicit pin / routed domain home use `resolveKindWritePin` (one rule for capture, import, thought).
+
+If you're creating a profile for something clearly pod-wide (a person, a podcast, a book, a lesson), leave default pod or set `entityScope: "pod"` explicitly. Do **not** set workspace "to be safe" — that reintroduces folder-trap bugs.

package/skills/synap-schema/extend-first.md

@@ -0,0 +1,29 @@
+## Extend first — schema moves, in order
+
+Before `define_kind` or a new workspace, walk this list **top to bottom**. Stop at the first move that fits. Load from `system/synap-schema/extend-first`. The conductor for a fuzzy user intent is `system/synap/from-intent`.
+
+A **role (facet) is a hat on any entity kind**, not only person/company. `applicableKinds` is the allowlist (`NULL` = any kind). `kind_mismatch` means **widen the role**, not mint a sibling type.
+
+| #   | If the need is…                                                                              | Do this                                                                                                                                                       | Do not                                                                   |
+| --- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 1   | An instance of a kind you already have                                                       | `create_entity` / capture on that slug; search first                                                                                                          | A second kind with a similar name                                        |
+| 2   | A **hat** on an existing entity (“this item is an X”, “this company is a vendor”)            | `attach_facet`. If the role exists but not on this kind → **widen `applicableKinds`** (same slug, extra kinds) then attach                                    | A new kind or a second role slug (`seller` vs `vendor`)                  |
+| 3   | 1–3 extra fields in **one** domain                                                           | Workspace **overlay** property on the existing kind                                                                                                           | A forked kind in that workspace                                          |
+| 4   | A true **subtype** with its own fields and life                                              | Child kind: `define_kind` with `parentProfileSlug` of the closest parent                                                                                      | A disconnected top-level kind                                            |
+| 5   | A **relationship-with-a-life** (buyer × seller × price × stage, independent of either party) | Own kind (the **deal precedent**). New slug if CRM `deal` is a _sales pipeline_ and this is not that. Overlay if it **is** the same kind in another workspace | Twin slug `deal`; JSON arrays of prices on the thing; Finding-per-scrape |
+| 6   | A **stage** inside a domain                                                                  | Status field + view                                                                                                                                           | A workspace per stage                                                    |
+| 7   | A **domain** (owns kinds + own team + automations + stable)                                  | Four-test → `agent-os` / template                                                                                                                             | A workspace for a project, a hat, or a shopping list                     |
+| 8   | None of the above                                                                            | `define_kind` (pod-wide default)                                                                                                                              | Silent invent                                                            |
+
+Same **kind** across workspaces: **one profile**, overlays for extra fields, optional `entityScope: pod` (pod-admin) so instances are not trapped. Never a second profile with the same name.
+
+### Widen a role
+
+`synap_define_role` with an **existing** slug is slug-idempotent: extra `applicableKinds` are **merged** (widen only). Shrinking the allowlist is not this door.
+
+### Firewalls
+
+- `list_profiles` before every define.
+- Prefer attach / widen / overlay / parent over create.
+- One structural proposal at a time.
+- `proposed` is success.

package/skills/synap-schema/extend-vs-create.md

@@ -2,7 +2,7 @@
 
 There are three moves, not two. Before extending or creating, ask whether the thing is really a **role** the entity plays rather than a new kind of entity at all — that's a facet, and it's the move people skip.
 
-**Kind + Facets, the rule:** one entity = one kind (`profiles.profileKind = 'kind'`). Roles the entity plays — client, partner, investor, prospect — are role-profiles (`profileKind = 'role'`, `applicableKinds[]`) attached via `entity_facets`: additive, workspace-lensed, NOT entities. A facet cascades with its parent entity; only promote a role to a full kind if it accrues its own independent life.
+**Kind + Facets, the rule:** one entity = one kind (`profiles.profileKind = 'kind'`). Roles are hats on **any** kind — not only person/company. A role-profile (`profileKind = 'role'`, `applicableKinds[]`) attaches via `entity_facets`: additive, workspace-lensed, NOT a second entity. `applicableKinds` NULL = any kind; a list **restricts**. “This item is an X” is a facet on `item` when X is a hat, not a new kind. Only promote a role to a full kind if it accrues its own independent life. Widen a role (`define_role` on the existing slug) when the hat fits a kind that is not yet in `applicableKinds`. See `extend-first.md`.
 
 **The litmus test:**
 

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