@synap-core/cli 1.11.0 → 1.12.2

package/skills/synap/governance.md

@@ -60,18 +60,20 @@ Agents can perform these actions directly without a proposal:
 - `document.create`
 - `memory.store` (always auto-approved, never proposed)
 - `view.create`
-- `profile.create`, `profile.update`
-- `property_def.create`, `property_def.update`
 - `channel.create`
 - `bento.arrange`
-- `filesystem.write_workspace` (OpenClaw sandbox only)
+- `filesystem.write_workspace` (agent sandbox only)
 
 **Proposal-gated** (always require approval when done by agents):
 
 - `entity.delete`, `entity.archive`, `entity.purge`
 - `view.update`, `view.delete`
-- `profile.delete`
-- `property_def.delete`
+- `profile.create`, `profile.update`, `profile.delete` — META-MODEL. A kind/role
+  is pod-wide (`entityScope` defaults to `'pod'`), so it changes what the pod IS
+  in every workspace. Unlike `automation.create` (auto-approved but landing
+  INERT as a draft), profiles have no inert state, so they propose.
+- `property_def.create`, `property_def.update`, `property_def.delete` — a base
+  property def (`workspace_id` NULL) extends a shared kind for every workspace.
 - `workspace.create`, `workspace.update`, `workspace.delete`
 
 ## Destructive action override
@@ -108,7 +110,7 @@ You do not poll or wait. The user's experience is asynchronous.
 
 An agent user is a pod-wide user with `agentMetadata.writesRequireProposal` set. Created by `POST /api/hub/setup/agent`. Each agent user has:
 
-- `agentType`: a free-form string (`"claude-code"`, `"openclaw"`, `"raycast"`, `"custom"`)
+- `agentType`: a free-form string (`"claude-code"`, `"codex"`, `"raycast"`, `"custom"`)
 - `agentMetadata`: arbitrary JSON for config
 - Hub API keys scoped to `hub-protocol.read` + `hub-protocol.write` + `mcp.*`
 
@@ -184,7 +186,8 @@ GET /api/hub/workspaces/{workspaceId}/governance
     effective: {
       autoApproveFor: [           // the actual whitelist at this workspace
         "entity.create", "entity.update", "relation.create", "document.create",
-        "view.create", "profile.create", "property_def.create", "memory.*", …
+        "view.create", "memory.*", …   // NOT profile.create / property_def.create —
+        // meta-model writes propose (see "Proposal-gated" above)
       ],
       governanceMode: "default" | "agent-owned",
       proposalApprovalPolicy: "owner_and_admins" | "any_editor" | "admins_only",

package/skills/synap/hand-off.md

@@ -0,0 +1,33 @@
+## Hand work to an agent on the person's computer
+
+The person says "start this on my devbox", "have my Mac's Claude Code do it", "give this session to Codex". You find the agent, hand it the work through a session, follow the session's room, and report back. You never run their machine yourself: an agent they connected there (`synap worker`, Claude Code, Codex) picks the work up.
+
+**1. Find it — `synap_list_agents`.** One read: `computers[]` (the person's own) and `agents[]`, each with `computer`, `canTakeYourWork` (else `whyNot`), `live`, `paused`, `lastSeenAt`, and `handOff`: what YOUR hand-off would do right now (`direct`, `asks_you`, `blocked` + `handOffReason`). Ready agents come first.
+
+- **Match the person's words against computer names first** ("my devbox" → the computer named `devbox`, any case), **then agent names and types** ("Codex", "claude-code"). Take the agents on that computer that can take the work.
+- **Two or more fit → ask the person** which one, by name ("Claude Code on devbox, or Codex on devbox?"). Never pick for them.
+- **None fits → say so.** "I see no agent on a computer called devbox" plus what you do see. Never hand it to a different machine silently.
+- **`paused: true` → say it is paused** and that a person must resume it (Settings › Agents). Do not hand it off.
+- **`live: false` → say when it was last seen** (`lastSeenAt`) and that it picks the work up the next time it checks in. Hand off only if the person still wants it.
+- **`canTakeYourWork: false`** — `whyNot` says why: `not_owned` (another person's agent: it would never see this work), `wrong_reach` (the pod's own agent: it answers in rooms, it never picks work up), `paused`.
+
+**2. Hand it — through a session.** The session's roster is how work reaches an agent.
+
+- New work: `synap_start_session` with a `title`, a one-sentence `goal`, 2–5 `criteria` the person can check, and `agentIds: [agentUserId]`.
+- Work in flight ("this session"): `synap_update_session` with `addAgentId: agentUserId`.
+- Read the reply. `handOffs[].status` (start) or `handOff.status` (update): `granted` = on the roster now; `proposed` = waiting for the person's approval; `denied` = say the `reason` as given.
+- **`asks_you` / `proposed`: the person approves the hand-off first.** Tell them plainly: "approve the hand-off on your phone", with the `reviewUrl` from the reply. It is success, do not retry. Then wait: `synap_get_session` until the agent is on its roster (or `synap_wait_for_answer` if you also asked them something), and go on to step 3.
+- **`blocked` / `denied`: say why, in the reason's words.** Never retry it as is. One case the list cannot predict: your own proposal limit ("Agent proposal limit reached") — the reply carries a link to raise it; pass that to the person.
+
+**3. Follow the room.** Everything the agent says lands in the session's room (`session.channelId`). Read it with `synap_get_thread_context { threadId: channelId }`; read the session's outcomes with `synap_get_session`. A `synap worker` on that computer follows this protocol:
+
+- It checks for handed sessions about every 30 seconds and starts ONE run of Claude Code per session, in its working folder.
+- It **claims** the session in the room in one line: picked up, and what it will do first.
+- It works on a branch (`devbox/<session>-<slug>`, in a git worktree). It never pushes to main and never deploys.
+- It **asks** with a room message starting `QUESTION:`. Kind `update` = you, the orchestrating AI, can answer; kind `question` = a decision only the person can make (the person is notified). It waits up to 30 minutes, reading the room every minute, and takes the FIRST reply posted after its question. No reply: it states its assumption and continues, or stops and says what is blocked.
+- It **reports** in the room (what changed, branch, commit, files) and records deliverables against the session's outcomes. It does not close the session; the owner does.
+- **Any room message posted after its run ended, by anyone but the agent, wakes it again** in the same conversation (up to 20 times). That is how an answer reaches it after it stopped. So post in the room only what you want it to act on.
+
+Answer a `QUESTION:` of kind `update` yourself with `synap_post_message` to the room. Leave kind `question` to the person, or ask them and relay their answer.
+
+**4. Report back.** Tell the person, in a few lines: which agent on which computer took it, whether it is on the roster or waiting for their approval, what the agent reported (result, branch, commit), and anything it asked that only they can answer. Point them at the session to review and close it.

package/skills/synap/inline-patterns.md

@@ -8,6 +8,7 @@ When the user is interacting with Synap's AI Companion (the in-browser chat pane
 | ---------------------------- | --------------------------- | --------------------------------- |
 | `[[entity:UUID\|Name]]`      | Purple entity chip          | Opens entity detail in side panel |
 | `[[view:UUID\|Name]]`        | Blue view chip              | Opens view                        |
+| `[[view:UUID]]`              | View chip, named for you    | Same; the label is optional       |
 | `[[open:side\|view:UUID]]`   | Amber "Open in side" button | Opens view in side panel          |
 | `[[open:main\|view:UUID]]`   | Amber "Open" button         | Opens view in main panel          |
 | `[[open:side\|entity:UUID]]` | Amber "Open in side" button | Opens entity in side panel        |
@@ -16,10 +17,11 @@ When the user is interacting with Synap's AI Companion (the in-browser chat pane
 
 ### Rules
 
+- **The label is optional.** `[[kind:UUID]]` is valid: in a document the chip shows the object's current name; in chat, where nothing looks it up, it reads as its kind ("View"). So in a chat reply, write the name you know: `[[view:UUID|Active Tasks]]`. A chip never shows the raw id.
 - **Always use real IDs.** Never hallucinate UUIDs. Only emit patterns for entities/views you just created or retrieved via Hub Protocol.
 - **Emit after creation.** When you create a view or entity, immediately reference it: `"Created your pipeline → [[view:abc123|Active Tasks]]"`
 - **Prefer side panel.** Use `[[open:side|view:UUID]]` so the user keeps their current context.
-- **Only in Companion replies.** These patterns are silently ignored in non-companion channels, documents, and memory. Do not use them there.
+- **Companion replies and documents.** In a document, `[[entity:…|…]]` / `[[view:…|…]]` render as chips and the editor keeps them (`document-embeds.md`); the `[[open:…]]` / `[[run:…]]` commands are chat-only. Other channels and memory ignore them.
 - **Combine with prose.** Don't lead with a chip — embed it naturally: `"Here are your open deals → [[view:xyz|Deals Pipeline]] · [[open:side|view:xyz]]"`
 
 ### Proposals
@@ -28,11 +30,17 @@ There is no `[[open:…|proposal:…]]` chip — `open`'s `resourceType` only ac
 `entity`, `view`, `doc`, `cell`, `channel`. A proposal is not one of those, so
 never invent that form.
 
-When a write returns `status: "proposed"`, the response also carries a
-`reviewUrl` (a full Synap Studio URL). Surface it as a plain markdown link, and
-add one sentence explaining why the write was proposed instead of auto-applied:
+When a write returns `status: "proposed"` (or any per-op outcome carrying a
+`reviewUrl` — `writeReceipt.reviewUrl`, `perm.reviewUrl`, a capability run's
+`kind: "proposed"`), the response also carries that `reviewUrl` (a real,
+resolvable `${PUBLIC_URL}/open/<id>` link — never invented). **Surfacing it is
+MANDATORY, not optional:** every reply that reports a proposed write MUST
+include the link as a plain markdown link, plus one sentence explaining why it
+was proposed instead of auto-applied:
 
-> Queued the task deletion for your review — destructive actions always need approval: [Review proposal](https://pod.example.com/proposals/prp_abc)
+> Queued the task deletion for your review — destructive actions always need approval: [Review proposal](https://pod.example.com/open/prp_abc)
 
-`"proposed"` is normal, not an error — don't apologize for it or wait for the
-user to approve before continuing the conversation.
+A reply that only says "I've proposed that for review" with no link is
+incomplete — the user has no way to act on it. `"proposed"` is normal, not an
+error — don't apologize for it or wait for the user to approve before
+continuing the conversation.

package/skills/synap/lenses.md

@@ -2,18 +2,35 @@
 
 You don't work "inside a workspace" the way you'd work inside a folder. You operate **across the whole pod**, and you **focus** through up to three composable lenses. **Lenses narrow; they never silo.** Omitting them is legal and common — that's pod-wide.
 
-| Lens          | What it is                                                                                                                                           | How to set (this session)                        |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| **Project**   | a **company or initiative** — the thing that ties the work together (Synap, a client, a launch). The lens you usually _organize by_.                 | `synap project use <id>` / `clear`               |
-| **Workspace** | an **operational domain** — where data lives (Foundation, CRM, Marketing, Finance, Builder). How the work is separated; the default home for writes. | `synap use <name-or-id>`                         |
-| **Session**   | the **work room** for the current goal (holds goal, deliverables, progress)                                                                          | `synap session start --goal "…"` / `attach <id>` |
+Tool names below are stems; your door may prefix them.
 
-**How they compose — this is the whole model:**
+What each word means (workspace, project, track, step, work): `concepts` — the one glossary. This file is only about scoping.
 
-- A **project spans workspaces**: one company/initiative has a Foundation, a CRM, a Marketing, a Finance… each a different operational lens on the _same_ project.
-- A **workspace spans projects**: the Marketing workspace can hold work for several clients/projects at once.
-- **Membership is per-entity, filed on write.** An entity belongs to a project because it was created/filed **under the project lens** — not because its workspace is "in" the project (there is no workspace→project link). So **set the project lens before writing** work that belongs to an initiative, and it composes into that project from any workspace.
-- Compose either way, or both. That's why they're lenses, not folders: **workspaces exist so that development, finance, marketing, and operations don't pile into one undifferentiated place** — they're the separation that makes the work legible.
+| Lens          | Scopes                                                     | Set it (MCP / CLI)                                                 |
+| ------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
+| **Workspace** | a domain; a thing lives in exactly ONE; default write home | `set_workspace_focus` / `synap use <name-or-id>`                   |
+| **Project**   | a commitment across workspaces; a thing can be in several  | `set_project_focus` or `projectId` / `synap project use <id>`      |
+| **Session**   | the work room for the current goal; pass its id on writes  | `start_session` / `synap session start --goal "…"` / `attach <id>` |
+
+**The project rule (one rule, every door):** a project is set ONLY when the user names it — declare it with `set_project_focus`, or pass `projectId` on the write. Filing into a project shares entities and documents with its members (a session is shared only through its room, never by filing), so never infer one from content, and never let a session decide it: a write without a `sessionId` is grouped into YOUR session — the one you started, else one opened for you, never another client's — and that door-picked session never sets the project. When nobody named a project, leave it unset. Guessing a workspace is merely untidy; guessing a project is not.
+
+**One space per domain — the lens rule (every door):** 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. A second space from a template whose domain already has a live space is refused for an agent (`status: "exists"` + the space to use); a person may still create one, with the same note.
+
+**Reads:** pod-wide by default; find by name, id or role, and pass `workspaceId` / `projectId` only to narrow a list.
+
+**Writes:** name the kind (profile slug) and, when known, the roles as facets. Omit `workspaceId` unless you are deliberately pinning a domain — the server places the write from installed profile metadata. Never invent a workspace name. Focus sticks for the session; an explicit `workspaceId` / `projectId` on one call overrides it for that call.
+
+**Empty domains:** a workspace holding 0 entities is a scaffold — prefer an active one unless the user names it (`orient` lists active domains; `detail:'full'` shows every one).
+
+**Where the kinds are:** `orient` names the kinds in use, most-used first; the profile-listing tool lists every kind and role. A kind's property schema (fields, enums, required): over MCP, `get_entity` on any existing entity of that kind returns it as `effectiveProperties`; over HTTP, `GET /api/hub/discover?profileSlugs=<slug>`; CLI `synap discover`. A write that breaks the schema is rejected with the valid fields quoted.
+
+**The space brief — what a space is FOR, and what it KNOWS.** PIN a space and the pod hands you its **brief**: `purpose` + `persona` (what it is for), `keyKinds` (the kinds it holds), `rules`, `playbooks`, `anchors`, and — the one that changes how you work — **`skills`**: the agent know-how the space ACTIVATES, each `{ slug, mode, when? }`. Reach it by passing a `workspaceId` to `orient` (an unpinned orient carries NO brief — it is space-scoped), or by `set_workspace_focus`; its reply carries the same brief. **Read the mode:** `mode: 'always'` is in effect for every task in this space — `load_skill` its slug before you work; `mode: 'on-demand'` means load it when the task matches its `when`. A space's skills are the pod telling you _this domain has a way of doing things_ — honour them rather than improvising. Pin the space the moment you are about to work in one.
+
+**How they compose** (definitions: `concepts`):
+
+- A **project spans workspaces** and a **workspace spans projects**.
+- **Membership is per-entity, filed on write.** An entity belongs to a project because it was written **under that project lens** (`belongs_to_project`) — that is the data ACL/filing edge. Separately, provisioning with a `projectId` also stamps **`project --uses--> workspace`**: an INDEX of domains the engagement runs through. That index is **not** an ACL and does **not** replace entity filing — set the project lens before writing work so entities compose into the project from any workspace.
+- A lasting goal inside a project is a **track**, never a child project or a workspace; a bounded piece of work is a **session** (`trackId` when it belongs to a track). There are no nested projects.
 
 - **The connection is pod-wide by design.** Your MCP/CLI link is _not_ welded to a workspace — reads default pod-wide, writes default to a sensible workspace. Pass a lens to narrow a single call; the lens is a focus, not a fence.
 - **These are per-Claude-session.** Two concurrent Claude sessions can sit on different projects/workspaces/sessions without colliding. `synap use` here rebinds **this** session only.
@@ -24,15 +41,16 @@ You don't work "inside a workspace" the way you'd work inside a folder. You oper
 **Before the FIRST write of a new unit of work**, check your lens and orient if you're unsure:
 
 1. `synap lens` — am I scoped where this work belongs?
-2. If unsure what exists → `synap orient` — it returns a **light lens map**: the projects and the workspaces (names + ids), so you see the shape without a data dump. Never guess IDs. Drill into a workspace's profiles or a project's contents only when you actually need them.
+2. If unsure what exists → `synap orient` — it returns the **briefing**: pending review, open sessions, the kinds in use, then the projects and workspaces (names + ids), without a data dump. Never guess IDs. Drill into a workspace's profiles or a project's contents only when you actually need them.
 3. **Connect or create:** if the right project / workspace / session doesn't exist yet, create it. A **session is the normal per-task move**. Creating a **workspace (a new operational domain) is a deliberate, expected move as the work grows** — not something to avoid. A **project, though, is a COMMITMENT WITH GRAVITY**: search existing projects first (`synap orient`) and prefer **linking into an existing one** via `belongs_to_project`. Only create a new project for a real initiative that ties work together — never for a task, plan, repo, or theme (those are entities), and **never for the pod owner's own company** (the company _is_ the pod, not a project inside it). An agent-created project must cite **≥5 existing entities** as evidence or the backend rejects it, and near-duplicate names are rejected with the existing candidates.
 
 **Don't re-orient mid-flow.** Once you've oriented and you're in a run of related writes, keep going — re-check only when you **start a new piece of work** or switch domains. The reflex guards the _start_ of work, not every call.
 
-### Notice a missing domain — and offer it
+### Notice a missing method or domain — and offer it
 
-Because workspaces are how a company separates its operations, a project is sometimes **missing an operational domain it clearly needs**. If the conversation is squarely about an area — sales, content, finance, hiring, ops — and the active project has **no workspace for it**, say so **once, at the end, in one line**, and offer to set it up:
+A project sometimes clearly needs something it lacks. Tell the two apart first:
 
-> _"This project doesn't have a Marketing workspace yet — want me to spin one up and capture the essentials?"_
+- **A lasting goal is missing** (the talk keeps returning to a goal — growing the newsletter, landing clients… — and `list_tracks` shows no track for it) → offer a **track**: _"This project has no track for the newsletter yet — want me to start one?"_ Then `start_track` with a `name` and `direction`; no method needed.
+- **A domain is missing** (new kinds of things must be recorded that no workspace owns — e.g. you are logging deals and there is no CRM) → offer a **workspace**, provisioned with the project lens active (see the `agent-os` skill). Never a workspace to stand for a method.
 
-If they say yes, provision that **one** domain and run its onboarding interview **with the project lens active** (so its entities file into the project) (see the `agent-os` skill — it handles both the whole-company setup and adding a single domain to an existing project). **Offer, don't auto-build.** One nudge per response, and only when the gap is real — never a checklist of everything the project "could" have. **If the user has already declined a domain (this session or before), drop it — don't re-offer.**
+Say it **once, at the end, in one line**. **Offer, don't auto-build.** One nudge per response, only when the gap is real — never a checklist of everything the project "could" have. **If the user has already declined it (this session or before), drop it — don't re-offer.**

package/skills/synap/linking.md

@@ -8,17 +8,14 @@ When a profile property has `valueType: "entity_id"`, setting it on entity creat
 
 Known system-profile auto-syncs:
 
-| Profile  | Property    | Target profile | Auto-relation type   |
-| -------- | ----------- | -------------- | -------------------- |
-| task     | `projectId` | project        | `belongs_to_project` |
-| task     | `assignee`  | person         | `assigned_to`        |
-| contact  | `companyId` | company        | `works_at`           |
-| deal     | `contactId` | contact        | `deal_for`           |
-| deal     | `companyId` | company        | `deal_with`          |
-| document | `entityId`  | (any)          | `attached_to`        |
-| anchor   | `channelId` | (channel)      | `anchored_in`        |
-
-Custom profiles: if you created a property with `valueType: "entity_id"`, the auto-sync kicks in, but the relation type defaults to `related_to` unless the profile defines a `relationDefinition`. When precision matters, create the relation explicitly (Way 2) with a specific `type`.
+| Profile | Property    | Target profile | Auto-relation type   |
+| ------- | ----------- | -------------- | -------------------- |
+| task    | `projectId` | project        | `belongs_to_project` |
+| task    | `assignee`  | person         | `assigned_to`        |
+| contact | `companyId` | company        | `works_at`           |
+| deal    | `contactId` | contact        | `deal_for`           |
+
+Custom profiles: an `entity_id` property does NOT create an edge on its own. Auto-sync writes a relation only when the property def is mapped to a relation def (its `relationDefId`), and the edge then takes THAT def's slug. An unmapped `entity_id` property stores the id and creates no relation at all — there is no default or fallback type. When you need the edge, create it explicitly (Way 2) with an existing relation-def slug; `synap_list_profiles` returns them under `relationTypes`.
 
 **Do not trust this table to stay current.** Always verify with `GET /api/hub/profiles` — the returned profile includes `properties[].valueType` and `properties[].targetProfileSlug`. Any property with `valueType: "entity_id"` is an auto-sync candidate.
 
@@ -68,37 +65,40 @@ POST /api/hub/relations
 }
 ```
 
-## Conventional relation types
-
-String-typed, case-insensitive by convention. Use these first before inventing new ones — workspace UI often renders known types specially.
-
-| Type           | Direction       | When                                              |
-| -------------- | --------------- | ------------------------------------------------- |
-| `related_to`   | bidirectional   | Generic association, no stronger label fits       |
-| `parent_of`    | source → target | Hierarchy (project parent of sub-project)         |
-| `child_of`     | source → target | Hierarchy (inverse of parent_of)                  |
-| `belongs_to`   | source → target | Membership                                        |
-| `authored_by`  | source → target | Note/document authored by a person                |
-| `depends_on`   | source → target | Task blocked by another task, project needs input |
-| `references`   | source → target | Task references a document, note cites an article |
-| `mentions`     | source → target | Entity mentioned within another entity            |
-| `works_with`   | bidirectional   | People who collaborate                            |
-| `part_of`      | source → target | Component relationship                            |
-| `from_meeting` | source → target | Any entity extracted from a meeting/event         |
-| `anchored_in`  | source → target | Anchor (pinned chat message) in a channel         |
-
-If none fits, invent a snake_case verb. Keep it short and symmetric with existing verbs. Don't create `related-to-this-specific-thing` — prefer a generic `related_to` plus a more specific property or document.
+## Relation types — use the pod's, never invent one
+
+A relation's `type` must be the slug of a relation definition the pod has. `synap_list_profiles` returns them under `relationTypes` (custom ones a workspace added included) — read it before linking. The defaults every pod ships:
+
+| Type                                        | Direction       | When                                                                                                                                                                                      |
+| ------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `relates_to`                                | bidirectional   | Generic association, when no stronger type fits                                                                                                                                           |
+| `references`                                | source → target | A task references a document, a note cites an article                                                                                                                                     |
+| `mentions`                                  | source → target | One entity is mentioned within another's content                                                                                                                                          |
+| `links_to`                                  | source → target | A hyperlink or explicit pointer                                                                                                                                                           |
+| `parent_of`                                 | source → target | Entity hierarchy (a kind instance of another). Not nested projects — those do not exist. A method in a project is a track; a unit of work is a session.                                   |
+| `belongs_to_project`                        | source → target | An entity filed into a project (prefer the `projectId` property — Way 1)                                                                                                                  |
+| `assigned_to`                               | source → target | A task/project assigned to a person                                                                                                                                                       |
+| `created_by`                                | source → target | A note/document authored or created by a person                                                                                                                                           |
+| `blocks` / `depends_on`                     | source → target | A DEPENDENCY: the source blocks / waits on the target. Dependencies are becoming ONE `blocked_by` edge across kinds (session · entity · track); these two slugs are its entity-side names |
+| `tagged_with`                               | source → target | Categorization by a tag entity                                                                                                                                                            |
+| `attended_by`                               | source → target | An event's participant                                                                                                                                                                    |
+| `works_at` · `works_on` · `affiliated_with` | source → target | A person and an organization / a project they contribute to / an affiliation                                                                                                              |
+| `knows` · `met_at` · `discussed_with`       | person → target | People who know each other / where they met / who they talked with                                                                                                                        |
+| `deal_for`                                  | source → target | A sales deal for a contact                                                                                                                                                                |
+| `has_skill`                                 | source → target | A person's skill                                                                                                                                                                          |
+
+**No fitting type? Do not invent one.** A slug that is not a relation definition is refused or lands as a link nobody can read. Use `relates_to` plus a more specific property or document, or — if the relationship recurs and deserves a name — propose a new relation definition (it is a schema change, reviewed like one).
 
 ## Decision table
 
-| Situation                                              | Use                                    |
-| ------------------------------------------------------ | -------------------------------------- |
-| Profile has matching `valueType: "entity_id"` property | Way 1 — set the property               |
-| Linking two already-existing entities                  | Way 2 — create a relation              |
-| Custom connection, no matching property                | Way 2                                  |
-| Unsure whether a property exists                       | `GET /profiles` first                  |
-| Linking a document to its parent entity                | Use `entityId` on the document (Way 1) |
-| Multi-party link (entity A ↔ entity B ↔ entity C)      | Two relations, both Way 2              |
+| Situation                                              | Use                       |
+| ------------------------------------------------------ | ------------------------- |
+| Profile has matching `valueType: "entity_id"` property | Way 1 — set the property  |
+| Linking two already-existing entities                  | Way 2 — create a relation |
+| Custom connection, no matching property                | Way 2                     |
+| Unsure whether a property exists                       | `GET /profiles` first     |
+| Linking a document to the entity it is about           | Way 2 — `references`      |
+| Multi-party link (entity A ↔ entity B ↔ entity C)      | Two relations, both Way 2 |
 
 ## Reading the graph
 
@@ -125,5 +125,6 @@ GET /api/hub/graph/traverse?entityId={id}&maxDepth=2
 - **Spinning up a new project instead of linking into an existing one.** A project is a **commitment with gravity**, not a folder for a task, plan, repo, or theme (those are entities). Before `create_project`, search existing projects and file the entity into one via `belongs_to_project` (Way 1 `projectId`, or Way 2 relation). Near-duplicate project names are rejected server-side with the existing candidates, and an agent-created project also requires **≥5 existing entities** as evidence.
 - **Creating an orphan, then forgetting to link it.** Every `POST /entities` should include properties that link, OR be immediately followed by a `POST /relations`. Never close the operation with a disconnected node.
 - **Double-linking.** If you set `properties.projectId` AND also `POST /relations` with type `belongs_to_project`, the auto-sync already did it. Don't duplicate.
-- **Using `related_to` when a specific verb fits.** `related_to` is the fallback. `authored_by`, `depends_on`, `references` carry more meaning to both the user and downstream views.
+- **Using `relates_to` when a specific type fits.** `relates_to` is the fallback. `created_by`, `depends_on`, `references` carry more meaning to both the user and downstream views.
+- **Inventing a relation type.** `child_of`, `belongs_to`, `authored_by`, `part_of`, `works_with` are NOT relation types here — use `parent_of` (from the parent), `belongs_to_project`, `created_by`, `parent_of` / `relates_to`, `knows`. Check `relationTypes` first.
 - **Inverting direction.** Source is "the thing doing the action or owning the relationship." `task depends_on task` means the source is blocked by the target. Check twice.

package/skills/synap/mcp-remote-servers.md

@@ -0,0 +1,64 @@
+# Remote MCP servers — how a pod registers, approves and governs them
+
+Load this before you suggest connecting an external MCP server to a pod, or when a server's tools do not
+show up. Every claim here is read from the code: the `mcp_servers` table
+(`packages/database/src/schema/mcp-servers.ts`), the settings door (`routers/mcp-servers.ts`), the
+capability installer (`services/capabilities/create-from-definition.ts`) and the IS adapter.
+
+### The row
+
+One row per server in `mcp_servers`, scoped to a space (`workspaceId`) or pod-wide (null). `slug` is
+lowercase `a-z0-9-`, unique per space; the IS names each tool `mcp_<slug>_<tool>`, so a space's server
+overrides a pod-wide one with the same slug.
+
+| Field        | Meaning                                                                                    |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| `transport`  | `http` (needs `url`) or `stdio` (needs `command` + `args`, runs on the IS host)            |
+| `auth`       | http only: `{ credentialRef: "vault://<id>", header: "Authorization", prefix: "Bearer " }` |
+| `toolPolicy` | `{ default: "governed" or "inline", inline: ["tool_a", …] }`; absent = governed            |
+| `approved`   | false by default; the supply-chain gate                                                    |
+| `enabled`    | the owner's on/off switch                                                                  |
+
+### Secrets never sit on the row
+
+`auth.credentialRef` points at a vault secret. The pod resolves it server-side on every call (never
+cached), sends it to the IS as a header, and the agent never sees it. If it cannot be resolved for the
+acting user or agent, the server is skipped and its tools simply do not appear: check the vault grant
+before you blame the server.
+
+### Governed by default
+
+- A **governed** tool is never called directly: the IS routes it through the pod (`mcp://<slug>`),
+  where the capability gate runs it or files a proposal. For an agent, `proposed` is success.
+- An **inline** tool is called directly by the IS. Declare `default: "inline"` only for a server that
+  exposes nothing but reads; for a mixed server, list its read tools in `inline`.
+- No policy at all means governed. This is deliberate and fail-closed.
+
+### Approval, and when it resets
+
+- Tools reach an agent only when the server is **approved AND enabled** (and, in a channel that keeps
+  its own MCP list, only the servers that channel opted into). The list is cached for 30 seconds.
+- In the space settings, tab MCP Servers: a space **owner or admin** adds, edits or deletes a server; only the space
+  **owner** approves it; a pod-wide server needs a pod admin to add or edit.
+- Editing `url`, `command`, `args`, `env` or `transport` in the settings **resets approval** (compared by
+  value, so a rename or an enabled toggle does not). Re-approve after re-pointing a server.
+- A capability (catalog or `market.install`) may declare `mcpServers[]` with `auth` and `toolPolicy`;
+  this is the only door that sets those two today (the settings form does not). Its install is the trust
+  decision: it may ship `approved: true`. Re-applying it converges url, auth and policy to the
+  template and only ever promotes approval, never revokes it.
+
+### As an agent
+
+You have no tool that registers a server. Propose it: a capability that declares the server (installed
+through `market.install`, which files a proposal), or ask the person to add it in the space settings (MCP Servers). Never
+ask for the secret in chat; it goes in the vault.
+
+### Network: who must reach the URL
+
+The **IS** opens the connection, not your machine. A `url` must be reachable from where the pod's IS runs.
+
+**An unauthenticated dev MCP is never registered on a public URL.** Storybook's `/mcp`
+(`http://localhost:6006/mcp`) and similar dev servers have no auth: reach them only over a private
+network or a tunnel the IS is on (an SSH tunnel to a dev pod), keep them bound to loopback otherwise,
+and prefer a static artifact (Storybook's `/manifests/components.json`) for agents on a remote pod. If
+a server would need to be public to be reached, it needs `auth` first.

package/skills/synap/mental-model.md

@@ -6,15 +6,15 @@ Synap is a typed knowledge graph. **Reading is one verb (`synap ask`) — it rou
 
 Ask yourself: _who does this knowledge serve?_ **There is no private AI scratchpad** — structuring knowledge into a real lane IS your job. Never write a `note` (that's the human's raw inbox); always `capture` into a lane.
 
-**Known fields → typed create.** If you already know the profileSlug and the values, use `synap create entity` / `synap_create_entity` (or typed `capture --type` for a knowledge entry). Reach for free-text `capture "…"` only for an unstructured blob you haven't parsed — it runs an AI pipeline that can degrade to one flat `note`. 'Always capture into a lane' means _don't leave it unstructured_, not _always use the free-text pipeline_.
+**Known fields → typed create.** If you already know the profileSlug and values, use `synap create entity` / `synap_create_entity`. Reach for free-text `capture "…"` only for an unstructured blob you haven't parsed — it runs an AI pipeline that can degrade to one flat `note`. 'Always capture into a lane' means _don't leave it unstructured_, not _always use the free-text pipeline_.
 
-| If it…                                                                                                                          | Lane                 | Where it goes                                                                            | Governance                                                                                                 |
-| ------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| **is about the CURRENT WORK** — domain know-how for the project/task you're on (incl. a domain-specific gotcha/lesson/decision) | **Work** _(default)_ | a `knowledge` entity in the **active workspace** (`synap capture --type …`)              | proposal-gated (it's the user's real data; the workspace IS the domain — Builder ≠ marketing)              |
-| **is GLOBAL truth** — a best-practice / runbook / how-to that holds across ALL projects                                         | **Global**           | pod-wide procedural `knowledge_keys` (`synap capture --global --type … [--key ns:slug]`) | reviewed for shared truth                                                                                  |
-| **is about the USER** — how they work/talk/decide, their preferences, their life                                                | **User**             | pod-wide `user_observation` (`synap observe write` / `record_observation` tool)          | inferences are **proposed** (you review); explicit "I always X" auto-saves — never model the user silently |
+| If it…                                                                                        | Lane                 | Where it goes                                                                                                     | Governance                                                                                                 |
+| --------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **is about the CURRENT WORK** — a reusable conclusion or caveat in the project/task you're on | **Work** _(default)_ | a `knowledge` entity through server-derived Work placement (pin with `--workspace` only when you know the domain) | proposal-gated (it's the user's real data; the workspace IS the domain — Builder ≠ marketing)              |
+| **is GLOBAL truth** — a best-practice / runbook / how-to that holds across ALL projects       | **Global**           | pod-wide procedural `knowledge_keys` (`synap capture --global --type … [--key ns:slug]`)                          | reviewed for shared truth                                                                                  |
+| **is about the USER** — how they work/talk/decide, their preferences, their life              | **User**             | pod-wide `user_observation` (`synap observe write` / `record_observation` tool)                                   | inferences are **proposed** (you review); explicit "I always X" auto-saves — never model the user silently |
 
-> **Why this matters:** writing to the wrong lane degrades the graph. A gotcha you learned about the **current project** is **Work** (the active workspace — its domain). A best-practice that holds **everywhere** is **Global** (`--global`, pod-wide). A fact about **how the user works** is **User** (pod-wide, inferences proposed). `synap capture` echoes which lane + governance it used; check it.
+> **Why this matters:** writing to the wrong lane degrades the graph. A caution you learned about the **current project** is **Work** (let the server route it, or pin the known domain explicitly). A best-practice that holds **everywhere** is **Global** (`--global`, pod-wide). A fact about **how the user works** is **User** (pod-wide, inferences proposed). `synap capture` echoes which lane + governance it used; check it.
 
 > **Read the write outcome — it guides your next move (it never blocks you).** Every write (`capture`, `observe`, `create entity`, `create relation`, `note`) reports one of two outcomes (and `--json` carries `"outcome"`):
 >
@@ -23,6 +23,8 @@ Ask yourself: _who does this knowledge serve?_ **There is no private AI scratchp
 
 > **Substrate names (tables under the hood):** _semantic_ = `entities` (the `knowledge` profile, workspace-scoped = domain separation), _episodic_ = `knowledge_facts`, _procedural_ = `knowledge_keys` (pod-wide runbooks). `ask` queries across them so you never pick on read.
 
+**Facets (roles)** are hats on **any kind** (`applicableKinds`), not only person/company. “This item is an X” is `attach_facet`, not a new kind, until X has its own life. Widen the role when `kind_mismatch`. See `from-intent` + `extend-first`. What role, workspace, project, track and template mean: `concepts` (the one glossary).
+
 ### Data layers — the graph itself
 
 | Layer         | What it is                                                                                                                                       | When to use                                                                                                  |
@@ -35,11 +37,11 @@ Ask yourself: _who does this knowledge serve?_ **There is no private AI scratchp
 
 ### Key profiles for AI use
 
-| Profile slug       | Scope     | Who writes     | Purpose                                                                                                                                                                                                                                       |
-| ------------------ | --------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `note`             | pod       | **human only** | The human's raw "dump now, structure later" inbox. **The AI never writes a note** — structuring into a lane is its job; use `capture` instead.                                                                                                |
-| `knowledge`        | workspace | AI             | Validated gotchas/lessons/decisions — the **Work lane** (default `synap capture --type`; ek_type/ek_claim/ek_why). DOMAIN = the workspace (a Builder gotcha ≠ a marketing one). Cross-project runbooks go to `knowledge_keys` via `--global`. |
-| `user_observation` | pod       | AI only        | Durable user model — habits, communication style, preferences                                                                                                                                                                                 |
-| `decision`         | pod       | human + AI     | Architectural decisions with rationale                                                                                                                                                                                                        |
-| `research`         | pod       | AI             | Investigation with sources + conclusion                                                                                                                                                                                                       |
-| `question`         | pod       | human + AI     | Open inquiry, closed when a decision answers it                                                                                                                                                                                               |
+| Profile slug       | Scope     | Who writes     | Purpose                                                                                                                                                                                                                                                                                                                        |
+| ------------------ | --------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `note`             | pod       | **human only** | The human's raw "dump now, structure later" inbox. **The AI never writes a note** — structuring into a lane is its job; use `capture` instead.                                                                                                                                                                                 |
+| `knowledge`        | workspace | AI             | Reusable **Insights** and **Cautions** — one required `knowledgeForm`; an optional `ek_claim` is only a compact summary and long form belongs in the linked Markdown document. Decisions and sources remain linked first-class entities. DOMAIN = the workspace. Cross-project runbooks go to `knowledge_keys` via `--global`. |
+| `user_observation` | pod       | AI only        | Durable user model — habits, communication style, preferences                                                                                                                                                                                                                                                                  |
+| `decision`         | pod       | human + AI     | Architectural decisions with rationale                                                                                                                                                                                                                                                                                         |
+| `research`         | pod       | AI             | Investigation with sources + conclusion                                                                                                                                                                                                                                                                                        |
+| `question`         | pod       | human + AI     | Open inquiry, closed when a decision answers it                                                                                                                                                                                                                                                                                |

package/skills/synap/operating-mode-rules.md

@@ -1,6 +1,6 @@
 ## Synap-first operating mode
 
-> **MCP clients** (Claude Desktop, Raycast, OpenClaw with MCP): use `synap_*` tool names — they wrap auth and governance automatically. **REST / HTTP clients**: use the endpoints below.
+> **MCP clients** (Claude Desktop, Raycast, any agent with MCP): use `synap_*` tool names — they wrap auth and governance automatically. **REST / HTTP clients**: use the endpoints below.
 
 These five rules override default assistant behavior when connected to a Synap pod:
 

package/skills/synap/processes.md

@@ -0,0 +1,118 @@
+# Processes — a playbook that follows a kind's lifecycle
+
+<!-- brief:start -->
+
+A process = `synap_create_playbook` with `subjectProfileSlug`; it FOLLOWS the
+lifecycle the kind or role declares (omit `statusProperty`, or name that same
+property). Each stage's `subjectStatus` is an EXISTING option of it (read it
+with `synap_list_profiles` first — never invent one); `gate: {kind: 'human'}` at
+every commitment, `onFail: {toStage}` for rework; typed `expectedOutputs`
+(`kind`, `label`, `relationToSubject`); workers = `activators` (`on`, `size`,
+default `mode: 'propose'`). What you create is POD-LOCAL, never an official
+template.
+
+<!-- brief:end -->
+
+## Writing a process (a playbook that follows a kind's lifecycle)
+
+The status belongs to the **kind or role**, never to a playbook. Its profile declares the lifecycle ONCE, in its
+template:
+
+```yaml
+lifecycle:
+  property: post-status
+  options:
+    - { key: Idea, category: open }
+    - { key: Published, category: done }
+    - { key: Archived, category: lost, humanOnly: true }
+```
+
+Every option has one category (`open · active · paused · done · lost`); rules read the category, names stay free.
+`humanOnly` marks an option no agent sets; an agent's move into `done` or `lost` proposes. Every move goes through
+the one status door (`moveStatus`; an agent sends `update_entity` with `expectedStatus`).
+
+A playbook that works that lifecycle is a **process**: it FOLLOWS it. Its stages name options of it, its workers
+start on it, and a person decides at the moments that commit the business. It never keeps a second status field.
+The reference is Content OS "Produce Content" (`synap-app/packages/workspace-templates/src/content-os.yaml`).
+
+**Official vs pod-local.** An official template or capability lives ONLY in the catalog
+(`synap-app/packages/workspace-templates/`, by kind) and is published with
+`synap catalog publish --official` (CI on main). A playbook, kind or automation an agent creates on a pod
+(`synap_create_playbook`, `synap_define_kind`, …) is **pod-local**: it never reaches the catalog. To make it
+official, write it into the catalog file and publish.
+
+| Field                           | Where             | Rule                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `subjectProfile.profileSlug`    | playbook          | The kind or role the process works.                                                                                                                                                                                                                                                                                                                                                                          |
+| `subjectProfile.statusProperty` | playbook          | Omit it: the pod follows the profile's declared lifecycle. If you name it, name that same property. A status worker on a role with no declared lifecycle is refused.                                                                                                                                                                                                                                         |
+| `stages[].subjectStatus`        | stage             | Entering the stage moves the subject to this option, through the door. Must be an **existing option** of the lifecycle — never invent one.                                                                                                                                                                                                                                                                   |
+| `stages[].gate`                 | stage             | `{kind: human}` at every commitment: send to a client, sign, pay, publish, won/lost, anything irreversible. `{kind: check}` only where the stage's own criteria can be verified. A gated stage writes its status only when the gate passes. A check gate judges the stage being LEFT, so never use it to guard an irreversible status.                                                                       |
+| `stages[].onFail`               | stage             | `{toStage: <key>}` — where a rejected gate sends the run (rework loop).                                                                                                                                                                                                                                                                                                                                      |
+| `stages[].criteria`             | stage             | 2–5 binary statements; `check.kind` evidence (cheapest) · capability · judge · human.                                                                                                                                                                                                                                                                                                                        |
+| `expectedOutputs[]`             | stage or playbook | What the step must produce: `kind` + `label` + `relationToSubject` (an existing relation slug, or `none`). The UI shows what was produced from this.                                                                                                                                                                                                                                                         |
+| `activators[]` (workers)        | playbook          | `on`: `created` · `enters_status` (+ `status`) · `count` (+ `status`, `min` ≥ 2) · `schedule` (+ `cron`, UTC) · `manual`. `size`: `per_thing` (default) · `per_moment` (count and schedule always are). `mode`: `propose` (default) · `run` only when cheap and safe. `maxPendingApprovals` (default 20) throttles. Compiled to a governed rule the owner can pause; it fires once per thing per transition. |
+| `humanOnlyStatuses`             | playbook          | Legacy: the options no stage owns. Mark a person-only option `humanOnly` on the lifecycle instead; while `statusProperty` is set, `synap catalog validate` still checks that stages and this list cover every option.                                                                                                                                                                                        |
+| `goalTemplate`                  | playbook          | Placeholders are `{paramName}`. Never `@{arg:…}` (read-only legacy).                                                                                                                                                                                                                                                                                                                                         |
+| `params`                        | playbook          | The subject is a `type: entity` param. A required param left unanswered becomes a question owed by the person, not an empty string.                                                                                                                                                                                                                                                                          |
+
+Human moments use an `ask` on an owed slot: `confirm` / `choose` (one `recommended`) / `form` / `act` / `provide`
+(connection, file or secret through the vault). Never ask for a secret in a form.
+
+Validation: `synap catalog validate` (process contract, goal grammar, lifecycle coverage ratchet — the count of
+lifecycle kinds with no process may only go down).
+
+## Declaring it over MCP
+
+`synap_create_playbook` takes the contract as-is. Before calling it, read the
+subject kind (`synap_list_profiles`) and copy the options of its lifecycle
+property exactly. Over MCP you cannot declare or change a lifecycle; it comes
+with the kind's template.
+
+```json
+{
+  "name": "Draft a post",
+  "goalTemplate": "Draft {post}",
+  "params": [{ "name": "post", "type": "entity", "required": true }],
+  "subjectProfileSlug": "post",
+  "activators": [
+    {
+      "on": "enters_status",
+      "status": "Briefed",
+      "size": "per_thing",
+      "mode": "propose"
+    }
+  ],
+  "stages": [
+    {
+      "key": "draft",
+      "name": "Draft",
+      "category": "started",
+      "subjectStatus": "In Draft",
+      "expectedOutputs": [
+        {
+          "kind": "document",
+          "label": "Draft",
+          "relationToSubject": "made_for"
+        }
+      ]
+    },
+    {
+      "key": "review",
+      "name": "Review",
+      "category": "started",
+      "subjectStatus": "Review",
+      "gate": { "kind": "human" },
+      "onFail": { "toStage": "draft" }
+    }
+  ]
+}
+```
+
+These are the Content OS post options; use the ones the kind really has. A
+batch worker looks like `{ "on": "schedule", "cron": "0 8 * * 1", "status":
+"Idea", "mode": "propose" }` (one session over every post in Idea, weekly) or
+`{ "on": "count", "status": "Review", "min": 5, "mode": "propose" }`.
+An agent call lands as a proposal (`status: "proposed"` is success). The
+playbook lives on this pod only; to make it an official template, a developer
+writes it into the catalog and publishes it with
+`synap catalog publish --official`.