@synap-core/cli 1.10.0 → 1.12.2

package/skills/synap/from-intent.md

@@ -0,0 +1,142 @@
+## From intent — conductor for a new area of work
+
+Use this when the user states an **intent** to start or track something that may need structure (a project, domains, kinds, roles, deals-shaped things) — not when they only want to capture a fact into types that already exist (`synap` skill).
+
+This skill does **not** provision Company OS. That is `system/agent-os/skill` (install **domains** from templates). This skill decides **what the graph should be**, asks until that is clear, then loads the specialist skill for each write.
+
+Load: `system/synap/from-intent`.
+
+### 0. Orient first (firewall)
+
+Before proposing structure:
+
+1. `synap_orient` — pending review first; projects; workspaces.
+2. `synap_list_profiles` — kinds **and** roles (`profileKind`, `applicableKinds`, `parentProfileId`, `entityScope`).
+3. `synap_ask` — does this intent already live as a project or a cluster of entities?
+
+If a close project exists, **reuse it**. Do not mint a twin. Name-match is enough: if orient already lists a project whose description is this company or this commitment, that **is** the project. Ask "reuse «Launch The Architech»?" — do not invent «Architech Business Model» next to it: a business-model method on that project is a **track** on it (`synap_list_tracks` / `synap_start_track`), not a twin project.
+
+**Pending review first.** If `startHere.pendingReview.count > 0`, offer to walk the queue before any new structure. Unreviewed work looks missing and gets duplicated.
+
+4. `synap_start_session` — **name the unit of work before you build it.** Title + goal, nothing else; the session is the room the rest of this happens in, not a form to fill. Every write you make afterwards is attributed to it automatically, so the user can open ONE object and see the whole arc instead of loose proposals with no shared story. Reuse an open session that already covers this intent (`synap_list_sessions`) rather than starting a second one. If the intent is a single fact with no structure behind it, skip the session and use the `synap` skill instead — this whole conductor is the wrong door for that.
+
+**Propose its `criteria` — do not grade yourself without them.** Two to five binary, observable statements the person can validate or rewrite ("`list_profiles` returns the `grp-run` kind"), not "the pack is good". They may equally be written by the person; what is not allowed is neither. A session with no criteria leaves you nothing to report against but your own opinion, which is how "85% complete" gets said about work nobody can check. Criteria are declarable at `synap_start_session` (as `outcomes` with `kind: 'fact'`, or the older `criteria`) and upserted later with `synap_update_session` — a session created inside a plan carries `expectedOutputs`, not criteria, so set them on the session once it exists.
+
+**A discovered prerequisite is a blocking child, not a paragraph in the same session.** When the goal cannot be finished until infrastructure exists, start that infrastructure as its own session: `parentSessionId` of the goal session, plus `suspendedIntent` — one line naming what the goal was about to do. That pair links the child (`spawned_from`) and blocks the parent (`blocked_by` the child). Work the child. Do not keep building the parent goal beside it. The parent stays open and waits; when the child is validated and closed, the parent unblocks and `suspendedIntent` is what you resume. A child that is only a slice of the same goal passes `parentSessionId` alone and does not block the parent.
+
+### 1. Ask before you build (required)
+
+Do not install templates, define kinds, or create a project until you can answer these. Ask only what is still unknown — one short pass, not a wizard. Never a 7-step implementation plan in the first reply. What each word means (project, track, step, template, pack, role): `concepts`.
+
+| Question                                                                             | You are distinguishing                                                                  |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| What is the **commitment** (the thing we are driving toward over weeks)?             | **Project** (optional; gravity). Not a folder.                                          |
+| Which **lasting goals** will it pursue (grow the newsletter, win ten clients…)?      | **Tracks** — `synap_start_track`, no template; methods are playbooks sessions follow.   |
+| Which **new kinds of things** must be recorded that no workspace owns yet?           | **Workspaces** (domains). Four-test + template-first. Missing domain → load `agent-os`. |
+| What is the **thing** vs a **hat** vs a **relationship-with-a-life** vs a **stage**? | Kind vs **facet on any kind** vs deal-pattern kind vs status/view.                      |
+| What already exists that we can **extend**?                                          | `extend-first` — never a twin slug.                                                     |
+
+**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.
+
+Hats are **not** limited to people and companies. A role is a hat on **whatever kind** `applicableKinds` lists (`item`, `task`, `deal`, …). “This item is an X” is a facet, not a new kind, until X has its own independent life.
+
+### 2. Propose a MINIMAL graph — one question — ONE next write
+
+After orient, your first user-facing message is:
+
+1. **Reuse or not** — name the existing project(s) that already match. If none, say you would create one (human / capture-plan / ≥5 evidence). Stop if they must choose.
+2. **What already covers the intent** — existing workspaces (do not onboard an **empty** domain unless this session's goal needs data there _now_). Existing kinds/roles (extend-first).
+3. **Exactly one next write** you want confirmed. Examples of ONE: reuse+pin project lens; install one overlay template; widen one role; **or one connected PLAN** (below). Not: project + template + onboard Finance + declare all edges + playbook filed as five separate proposals.
+
+Then **wait**. After that write lands (`proposed` is success), the _next_ turn may offer the next one move.
+
+#### ONE write may be a whole connected PLAN
+
+`synap_capture` accepts `projects[]` / `sessions[]` / `documents[]` / `links[]` / `entities[]` / `relations[]` — and `skills[]` / `automations[]` / `rules[]` — in a **single call** that files **ONE proposal**. Steps reference each other by `ref`; ids exist only after approval. A plan carrying a session or project applies **all-or-none**, compensated if any step fails.
+
+This is the difference between a reviewer seeing one graph and deciding once, and seeing fourteen cards with no visible relationship. **Prefer the plan whenever the structure is connected.** It is not a 7-step sequence — it is one decision about one shape.
+
+**The trigger is countable, so count.** The moment you are about to make a second `create_*` call for objects that reference each other — a kind and the playbook that uses it, a project and its sessions, a skill and the automation that calls it — stop: that is ONE plan, not N proposals. This is the check that was missing when an agent filed fourteen.
+
+**Name what the work will produce.** Each `sessions[]` step takes `expectedOutputs` — the documents, entities and decisions this session owes. List them at plan time: the plan's own object list IS the expected outputs, so "done" is derivable from slots the person can see rather than announced as a percentage. Every slot filled means the work is finished **pending the person's review** — never silently closed.
+
+It also resolves ordering that separate proposals cannot: an `automations[]` step whose flow names a skill created by a `skills[]` step in the SAME call resolves, because the skill is materialized before the automation is validated. Filed separately, the second proposal fails — the first has not been approved yet.
+
+Refs, not ids. To change a pending plan, **revise it** (full updated operations, re-validated). Never file a second proposal pointing at items still pending in the first.
+
+**Budget is per proposal, not per object.** An agent has a cap on how many proposals may sit pending at once. Fourteen objects as fourteen proposals can exhaust it and get the next write refused; the same fourteen as one plan costs one slot. If a write is ever refused for the cap, that refusal carries a link to raise it — follow the link, do not retry the write. Retrying is worse than waiting: a refused write that you re-send through another door is how the same playbook ends up in the pod twice.
+
+Do **not** declare every provides/consumes/trigger edge in the opening. Edges are a later turn, and only for the pair this work actually reads.
+
+Do **not** invent CLI (`synap create project --evidenceEntityIds`, `synap marketplace install`, `synap declare workspace source`). Use the MCP/Hub tools this door actually exposes.
+
+Empty workspace ≠ broken. An empty Finance is fine until this intent needs a revenue number.
+
+### 2b. When the work needs a CAPABILITY (a verb an automation calls)
+
+A plan creates instruction skills, automations and rules. **A plan never installs a capability.** Installing one fetches a template from the Control Plane mid-apply, writes secrets and vault grants, and has no undo path — none of which belongs inside an all-or-none batch. Capability access is its own decision, on purpose.
+
+Walk this ladder instead. Every rung is a door that exists; do not invent one.
+
+| Situation                               | Do this                                                                                                                                                                                                               |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Not sure the verb exists                | `synap_list_capabilities` (a `query` reaches the folded builtin verbs too)                                                                                                                                            |
+| Verb exists but is **not enabled**      | **Just run it** — `synap_run_capability`. The refusal files ONE enable request covering your whole pack and hands it back as `enableProposal`, and tells you the action did NOT run. There is no enable tool to call. |
+| Verb is not installed                   | `market.search` to find it, then `market.install` — both builtin verbs through `synap_run_capability`. For an agent this ALWAYS files a `capability.install` proposal; that is success, not refusal.                  |
+| The tool does not exist at Synap at all | `tool.request` (builtin verb) — records a `tool_request` so the gap is visible instead of silently blocking you                                                                                                       |
+| Authoring a reusable PACK               | Declare the need as a package dependency (`relation: "require"`) rather than installing inside the pack                                                                                                               |
+
+**Author the automation LAST.** An automation whose `capability` node names a verb that is not in the catalog is rejected at author time (`capability_unknown_verbId`) — the write never lands, so there is nothing half-built to clean up. Get the verb enabled or installed first, then file the plan that uses it.
+
+A skill your plan creates IS resolvable in the same batch: the automation door looks a verb up by **skill name**, and skills materialize before automations. That is why a fact + a behaviour can ride in one proposal.
+
+### 2c. A lasting goal inside a project → a TRACK
+
+A **track** is a lasting intent with a goal inside ONE project ("Grow the newsletter", "Win the first ten clients"); a project runs several. It holds a `direction` (one line, in the person's words) and, only if the person names a number, a `kpi` `{ label, unit?, target }`. It lasts: it is paused or archived, never "finished" for hitting a number. Work in it is ordinary sessions filed into it. Definitions: `concepts`.
+
+**Asked to pursue a goal in a project** ("keep growing the newsletter in Synap"): `synap_list_tracks` for the project (already running? resume it) → none? `synap_start_track` with `projectId`, a `name`, the `direction` and any `kpi` the person named — no method needed. Then work: `synap_start_session` with `trackId`, one session per sitting, as many as it takes.
+
+| The user needs…                                  | Do this                                                                                                                |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| a **lasting goal** in an existing project        | `synap_list_tracks` (already running?) → `synap_start_track` (`name`, `direction`, optional `kpi`)                     |
+| one piece of work toward it                      | a **session** born in the track: `synap_start_session` (or `synap_run_playbook` for a session template) with `trackId` |
+| a repeatable way to do that work                 | a session template (`synap_create_playbook`, default scope) run with `trackId` — not a track method                    |
+| new **kinds of things** no workspace owns        | a workspace (four-test, `workspace-design`) — never to represent a track                                               |
+| a new long-lived commitment with its own gravity | a project — never a twin project for a track of an existing one                                                        |
+
+**A track steers; its sessions verify.** Report progress with `synap_update_track` `kpi: { current }`: a STATED value, stamped with when and by whom — never invent a measurement. Reaching the target nudges the person to re-aim it; never change the target yourself. While a track is active, its agent may work in the spaces its project links (`synap_project_use_workspace`); pausing it suspends that, archiving ends it. Pause, resume or archive it with `synap_set_track_status`. Track writes are governed: `proposed` is success. Installing a pack onto a project does **not** start tracks — start each one.
+
+**Legacy: tracks with stages.** A track started from a track template (`scope: "project"`, `playbookId` on `synap_start_track`) has re-enterable stages. Work a stage with `synap_start_stage_session` (`trackId`, optional `stageKey`); never `synap_advance_track` without the user — advancing returns an `offer` (show it, start it only on a yes). Do not create new track templates; a new track needs none.
+
+### 3. Which skill to load next
+
+| Need                                         | Skill                                                      |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| Schema: facet, overlay, child kind, new kind | `system/synap-schema/extend-first` then `extend-vs-create` |
+| Missing operational domain                   | `system/agent-os/skill`                                    |
+| Views / cards once the model exists          | `system/synap-ui/skill`                                    |
+| What a word means (the one glossary)         | `system/synap/concepts`                                    |
+| Lenses, gravity, sessions                    | `system/synap/lenses`                                      |
+| Four-test for a workspace                    | `system/synap/workspace-design`                            |
+| Index of everything                          | `catalog`                                                  |
+
+### Firewalls (never)
+
+- Twin **project**: orient already has this company/commitment under another name.
+- Twin kind/role whose **slug or display name** matches `list_profiles`.
+- A 7-step "right sequence" in the first confirm. One structural move per turn.
+- **Splitting one coherent structure into N proposals.** If the objects reference each other, they are ONE plan through `synap_capture`, not one `create_*` call each. N cards the reviewer must mentally re-join is the failure this conductor exists to prevent.
+- Building structure with no session open. The unit of work is named first (§0.4) or the work arrives as orphan proposals.
+- Grading yourself. "85% complete" against no criteria and no declared outputs is an opinion, not a status — propose criteria (§0.4) and expected outputs (§2) so the person can check the claim.
+- Onboard or fill an empty workspace "because it is empty."
+- Invent a workspace that fails the four-test.
+- Nested or twin projects, or a workspace, to represent a **goal or method** of an existing project. A lasting goal is a track; a repeatable method is a playbook a session or worker follows; one bounded piece of work is a session (`trackId`).
+- Invent CLI flags or tools this door does not list.
+- A second entity for a hat (`kind_mismatch` → **widen** the role’s `applicableKinds`, then `attach_facet`).
+- Company/person-only facets. If the hat belongs on `item` (or any kind), the role’s `applicableKinds` must include that kind.
+- CRM `deal` (pre-sale pipeline) as a generic price timeline. A commercial snapshot with its own life uses the **deal precedent** (own kind), not a twin `deal` slug and not JSON on the thing.
+- Encoding the pattern only as Knowledge and expecting every MCP agent to find it. Skills + this conductor are the all-pods path.
+
+### After it works
+
+Offer L4, one at a time: session → work template; cell → renderer; **project → pack** (a `suite`) (`synap_export_project_pack` / CLI `--from-project`). Export returns a thin suite **plus** full constituent workspace packages — publish constituents first, then the suite (CLI does both). Install with `projectName` (human) or `projectId` (agent) to mint/reuse a named engagement and stamp uses-edges. Optional `projectSurface` lands in `projects.settings.layout` (engagement UI). Not live entity rows. Never crystallize a guess. No `app` package type.

package/skills/synap/governance-rules.md

@@ -36,17 +36,17 @@ Changed: [field] [old value] → [new value]
 
 ```
 Context: User asked to track the Acme deal they mentioned in today's call.
-Intent:  Creates a deal entity for Acme at lead stage linked to Alice Johnson.
+Intent:  Creates a deal entity for Acme at draft stage linked to Alice Johnson.
 Links:   ent_person_alice_johnson, ent_company_acme
 ```
 
 **Example (update):**
 
 ```
-Context: User confirmed the Acme deal moved to proposal stage.
+Context: User confirmed the Acme proposal went out.
 Intent:  Advances the deal through the pipeline so it appears in the proposal view.
 Links:   ent_deal_acme, ent_person_alice_johnson
-Changed: dealStage lead → proposal
+Changed: commercialStage draft → proposed
 ```
 
 Rules:
@@ -59,6 +59,6 @@ Example response to the user:
 
 > I queued **Delete task "Q2 plan review"** for your review. Destructive actions need your approval. Open it: synap://open/proposal/prp_abc
 
-Auto-approved by default (for agent API keys): `entity.create`, `entity.update`, `document.create`, `relation.create`, `view.create`, `profile.create`, `property_def.create`, `channel.create`, `memory.*`, all reads. Destructive actions (`delete`, `archive`, `purge`) always propose in agent-owned workspaces.
+Auto-approved by default (for agent API keys): `entity.create`, `entity.update`, `document.create`, `relation.create`, `view.create`, `channel.create`, `memory.*`, all reads. META-MODEL writes (`profile.*`, `property_def.*` — new kinds, roles and fields) always propose: they are pod-wide and have no inert state to land in. Destructive actions (`delete`, `archive`, `purge`) always propose in agent-owned workspaces.
 
 For the full whitelist, agent-user semantics, and workspace overrides, read **`governance.md`**.

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.