@synap-core/cli 1.11.0 → 1.13.0

package/skills/synap-market/install.md

@@ -6,7 +6,7 @@
 synap market install crm                        # install as a new workspace
 synap market install crm --dry-run               # preview: would-create / reuse / conflicts, writes nothing
 synap market install crm --onto <workspaceId>     # reconcile ONTO an existing workspace (additive)
-synap market install crm --project <id>           # tag seeded entities to a project (install stays pod-wide)
+synap market install crm --project <id>           # link the installed workspace(s) to an EXISTING project (id only)
 ```
 
 Installs are **workspace-first**: a `workspace`/`template` package spins up
@@ -14,6 +14,8 @@ Installs are **workspace-first**: a `workspace`/`template` package spins up
 automation, cell) route you to the right surface (`synap capability add`,
 etc.) rather than being force-fit into a workspace install.
 
+**One space per domain:** A space is a domain, installed once (Content, Brand, CRM…). A project is a filter across spaces. To make something “for project X”: file it into X inside the domain's space (`file_into_project`), and link X to the space (`project_use_workspace`). Never create a space named after a project, a brand or a client. Reinstalling reuses the live space. A template is installed **once per pod**, and a space name is held by **one** active space — whoever owns it, human or agent alike: a second copy is refused (`409` — `status: "exists"` + the space to use, or `WORKSPACE_IDENTITY_CONFLICT` naming the space that holds it). There are no named copies: `--as <name>` / `instanceName` answers `400`, and a package with no `_meta.slug` (and no `--onto` target) answers `400` instead of minting a second space.
+
 ## Pod verb — `market.install` (MCP / agent / automation)
 
 ```json
@@ -37,6 +39,59 @@ never treat a non-"installed" response as failure:
 they can approve it — don't retry, don't report it as a failure. See
 `governance-and-catalog.md`.
 
+## Project packs — a suite of workspaces, linked to a project
+
+A **project** is a cross-cutting lens over workspaces, not a package kind. A
+"project pack" is a **suite**: an ordinary `workspace`-category package tagged
+`suite`, whose `dependencies[]` **`require`** each constituent workspace package
+(never `compose` — re-applying must not duplicate workspaces). Installing a
+suite installs every constituent workspace (idempotent: reused if present).
+
+**Author one from a live project** — never hand-write the suite:
+
+```bash
+synap market publish --from-project <projectId>   # publishes the constituents first, then the thin suite
+```
+
+(Agent door: `export_project_pack` returns `{ definition, constituents }` —
+publish the constituents before the suite so every `require` resolves.)
+
+**Install onto a project.** The install never needs to know why the project
+exists — it installs the workspaces and LINKS them (a `project --uses-->
+workspace` edge per workspace, plus seeded entities filed into the project):
+
+```bash
+synap market install <suite-slug> --project <projectId>   # EXISTING project id only; errors if not found
+```
+
+The CLI has no flag that creates a project. Create the project first:
+
+- **A human**: in the app, or by passing `projectName` on the Hub door
+  `POST /api/hub/packages/apply` (mints or reuses by exact name).
+- **An agent**: `create_project` requires `evidenceEntityIds` — at least 5
+  existing entities that belong to it — or it is REJECTED (not proposed).
+  Without that evidence, ask the human to create the project, then install with
+  its id.
+- **An agent calling `market.install` with `projectName`**: the install becomes
+  a proposal that carries the name, and when a human approves it the project is
+  minted. The approval is the consent — say so when you propose it.
+
+Two packs on one project = install each with the same `--project <id>`. Each
+lands its own workspaces; both link to the project. Only ONE `compose`
+dependency is allowed per package, at every level.
+
+**The brief comes with the workspaces.** A workspace package's `onboarding` is
+the space's BRIEF — steady state (`purpose`, `framing`, `expertise`, `anchors`,
+`fetch`) plus its onboarding mode (`goal`, `collect`, `openingQuestions`,
+`doneWhen`) — stored on that workspace's `settings.onboarding`; the package's
+top-level `rules[]` install as the space's rules. A template update reaches an
+installed space without overwriting what its owner edited (conflicts are
+reported), and `synap_update_space_brief` proposes a change. The `onboard` skill runs the
+interview when a lens is empty; for a project spanning several workspaces it
+sets up one workspace's slice at a time, each entity filed into the project.
+There is no project-level recipe — the recipe always lives on a workspace. A
+journey completes by itself once the lens holds real data.
+
 ## Idempotency by kind
 
 - **capability** — natural key is `(name, workspaceId)`; installing twice
@@ -47,6 +102,29 @@ they can approve it — don't retry, don't report it as a failure. See
 - **automation** — pre-checked by `(name, workspace)` before creating.
 - **cell** — keyed by `(typeKey, workspaceId)`.
 
+## Template updates — where a space stands, and whose step it is
+
+Read it with MCP `synap_template_health` (or `synap templates` in a terminal).
+Each space's row says what is left to do; act on these fields, not on
+`drifted` alone (`drifted: true` means "there is a step", not "apply now"):
+
+| Field | Means | Your move |
+|---|---|---|
+| `state: "active"`, `drifted: true` | a newer version is out | the update path below |
+| `state: "awaiting-approval"` + `awaitingApproval: [ids]` | the last update filed proposals | point the person to them; **do not re-apply** |
+| `state: "partial"` / `"layer-2-not-run"` / `"failed"` | the last update did not finish | `synap templates update <slug>` finishes it |
+| `pendingDataChanges: {count, sentences, needsPodAdmin}` | the update changes existing data and waits for a **person** to agree | tell them the sentences; they run `synap templates update <slug>` themselves (a pod owner/admin when `needsPodAdmin`) |
+| `updateProposal: {id}` | an update of this space is already proposed | point the person to that proposal; **never file another** |
+| `applyWarning` | the pod's one sentence for what is left | relay it as is |
+
+The update path is `synap templates update <slug>` (the person's door). Run
+with an agent key it becomes a proposal the person approves. **Agreeing to data
+changes is never an agent's**: the door answers `409
+DATA_CHANGES_NEED_CONSENT` with `needsPerson: true` for any agent, whatever it
+lists in `acceptDataChanges`. The version stamp (`settings.template.version`) is
+written only when an update converged, so a space never reads "up to date" over
+an update that did not land.
+
 ## Locked / tier-gated packages
 
 A package can declare a `requiredTier`. Installing one your account's plan

package/skills/synap-market/overview.md

@@ -1,10 +1,78 @@
 # Marketplace & templates on Synap
 
-The marketplace is Synap's **package layer**: workspace templates, capabilities,
-automations, and cells — anything that can be installed into a pod rather than
-hand-built. It lives in the Control Plane (CP) catalog and is discoverable and
-installable from any door: the `synap` CLI, MCP (`run_capability`), or the Hub
-REST API (`/api/hub/capabilities/execute`).
+Synap is **configuration-first**: a feature is _stored, user-editable config_
+published to one catalog and installed through shared substrate — not hardcoded in
+the pod backend. The marketplace is that **package layer**, and the catalog
+(`synap_packages`) is **kind-agnostic** — one door serves every kind:
+
+| Kind                      | Configures                                                       | Standalone install (via `applyMarketInstall`)      |
+| ------------------------- | ---------------------------------------------------------------- | -------------------------------------------------- |
+| **workspace**             | a whole domain (profiles + views + bento + its caps/automations) | ✅ `createWorkspaceFromDefinitionIdempotent`       |
+| **capability**            | a credentialed tool pack (+ embedded skills/playbooks)           | ✅ `createCapabilityFromDefinition`                |
+| **cell**                  | a renderer — the code that draws an entity/widget                | ✅ `installCellFromDefinition` (needs a cache row) |
+| **view**                  | a saved view/layout                                              | ✅ `viewsRouter.create` (needs a `workspaceId`)    |
+| **skill**                 | agent know-how                                                   | ✅ `skillsRouter.create` (pod-wide if no ws)       |
+| **workflow / automation** | a WHEN→ACTION flow                                               | ✅ `automationsRouter.create` into acting ws       |
+
+**All six kinds install standalone today** through the ONE apply core
+`applyMarketInstall` (`services/capabilities/marketplace-install.ts`) — the same
+governed door `market.install` and the `capability.install` proposal executor share,
+each reusing the kind's _governed_ router caller (zero duplicated insert logic). The
+remaining gaps are NOT install: (1) **private-package sync is unauthenticated**, so a
+private package can't reach a pod yet (see `governance-and-catalog.md` / RC4); (2)
+standalone **view / skill / automation stamp no source-link**, so they don't self-heal
+via reconcile the way workspace/capability do. (Subscription-`tier` gating is a
+separate axis — see `governance-and-catalog.md`.)
+
+**Words** (template, pack, workspace/work/track/rule template) are defined once
+in the `synap` skill's `concepts` topic. In short: a template's kind is DERIVED
+from its content (a playbook with `scope: "project"` is a track template, the
+default `scope: "session"` a work template), never declared.
+
+**A pack is not a seventh kind.** Today it ships as a **suite**: a `workspace`
+package tagged `suite` that `require`s its constituent workspaces, built from a
+live project with `synap market publish --from-project <id>`, and installed
+with `--project <id>` to link every workspace to that project. See
+`install.md` → "Project packs". The model it is moving to: a pack lists the
+workspace templates it depends on and installs the missing ones, and never
+creates a workspace of its own.
+
+It lives in the Control Plane (CP) catalog and is discoverable and installable from
+any door: the `synap` CLI, MCP (`market_search` / `run_capability`), or the Hub REST
+API. **Everything that is config, not code, can be a template** — workspaces, entity
+profiles/views, renderers (cells), capabilities, skills, automations.
+
+## The authoring order — bottom-up, ALWAYS
+
+Everything installable is a **standalone package**, and packages form a graph: a
+bigger one **declares `dependencies[]`** on smaller ones, and the pod installs the
+missing ones in the same governed pass. So author from the SMALLEST piece up:
+
+1. **Basic objects** — entity types (profiles), **skills**, capabilities, cells,
+   views, workflow/automations. Each is publishable on its OWN and is useful before
+   any container exists. A skill package is one skill: its documentation or code.
+2. **Containers** — a **space** (a `workspace` template) that declares
+   `dependencies[]` on the basic objects it needs, and activates its skills with a
+   `skills:` block.
+3. **Compositions** — a **project / suite** ("truck") that `require`s the spaces.
+
+Publish the small pieces FIRST, then the space, then install. Nothing in the chain
+waits on a container.
+
+**The two verbs are different, and confusing them is the classic mistake:**
+
+- `dependencies[]` = what gets **INSTALLED** — the pod materialises the package if
+  it is not already there (idempotent; a second pass reports `found`).
+- `skills:` inside a template = what gets **LINKED** to that space, and in which
+  mode (`always` / `on-demand`). It names a skill some `dependencies[]` entry —
+  usually its own — already installed. Declaring the link without the dependency
+  installs cleanly and links NOTHING.
+
+**Never inline what is already a package.** Copying a skill's text into a template,
+or re-declaring a profile set that ships as a dependency, forks the thing and stops
+it converging. Depend on it; let the install bring it. And **never** seed a skill
+into the backend (`skills/synap/…`) to make a template resolve — that directory is
+not the marketplace. Publish it as a package.
 
 ## The two reflexes
 
@@ -40,7 +108,7 @@ REST API (`/api/hub/capabilities/execute`).
 The CLI's browse filter (`market --type`) uses
 `workspace|capability|skill|workflow|view|cell`; the pod-native install verb
 (`market.install`) and its catalog use the narrower
-`capability|automation|template|cell` (workspace ≡ template there). Match
+`capability|automation|template|cell` (`template` there means a workspace template). Match
 whichever surface you're calling.
 
 ## Visibility

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, two 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 two mirrors, and why each one must exist
+
+There are exactly **two**. Two more were removed: `AbstractVerb` in
+`@synap/playbooks` (deleted 2026-10-01, see below), and the pod's own
+`ABSTRACT_VERBS` copy (collapsed 2026-10-26 — `@synap/database` now depends on
+`@synap-core/types`, so it re-exports mirror 1 under that name).
+
+| #   | Where                                                                                                                             | Kind                           | Why it cannot import the SSOT                                                                                                                                                                                             |
+| --- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `synap-backend/packages/types/src/capability-intents/` — `ABSTRACT_INTENTS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS`            | runtime, published leaf        | The SSOT is SQL rows; a TypeScript list is a mirror by construction. The pod reads it too: `ABSTRACT_VERBS` in `packages/database/src/schema/tools.ts` is this `ABSTRACT_INTENTS`, re-exported (the 0283 SEED union, 13). |
+| 2   | `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 PLAYBOOKS 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_INTENTS` (a SEED slug) or `REGISTERED_EXTRAS`
+   (a post-seed row) in `packages/types/src/capability-intents/index.ts`. The pod's
+   `ABSTRACT_VERBS` is `ABSTRACT_INTENTS`, so it follows. Then **`cd packages/types && pnpm build`** —
+   consumers typecheck against the built `dist/`, so a skipped rebuild makes your gate lie.
+   Post-seed rows today: `publish_post` (0284, write), `delegate_agent_task`
+   (0314, act — every verb of an external-agent binding, `tools.config.agentBinding`:
+   start / send / status / cancel) and `read_webpage` (0329).
+3. **Add it to mirror 2** — the same two lists in the control plane's
+   `capability-intent-vocabulary.ts`.
+4. **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 third copy; the tripwire
+  only polices the names it knows. This is why step 4 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:**