@synap-core/cli 1.11.0 → 1.13.0

package/skills/synap/from-intent.md

@@ -0,0 +1,158 @@
+## 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`.
+
+### Classify first: which layer is this?
+
+Before the first write, name the layer in one word, then take its door. Most requests are not a new area at all, and the wrong layer is how a view gets faked as a note or a capability as a view. On a key that lists the starter tools only, `synap_load_skill` the group in brackets first.
+
+| Layer          | The user wants…                                                        | Door                                                                                                                                                          |
+| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **data**       | a thing remembered: a company, a note, a decision, a link between two  | `synap_capture` for messy input; `synap_create_entity` (`tools:data`) when the kind and fields are known. Never a note standing in for a view or a session.   |
+| **view**       | to SEE existing things: a list, a grouping, a board, a dashboard       | `synap_list_views` first, so you do not duplicate one; then `synap_create_view` (`tools:build`). Never copy records into a new space to show them.            |
+| **capability** | access beyond the graph: connect Gmail, send mail, search the live web | §2b: `synap_list_capabilities`, then run it or file its install. Never build a view to stand in for a capability.                                             |
+| **session**    | "I'm starting work on X": one bounded piece of work                    | `synap_start_session` with a one-line goal. Not a task.                                                                                                       |
+| **goal**       | a goal inside a project: "launch the new site" (a _track_)             | §2c: `synap_list_tracks`, else `synap_start_track` (both on every key). Not a project, not a pack, not a playbook.                                               |
+| **rule**       | a standing intent: "always…", "from now on…", "every Monday…"          | `synap_create_rule` (`tools:governance`) with the user's own words as `intent`; a trigger→steps reaction is `synap_create_automation` (`tools:capabilities`). |
+| **structure**  | a new area of work that needs kinds, spaces or a project               | the rest of this skill, from §0.                                                                                                                              |
+
+Two layers in one ask ("connect Gmail AND show my mail as a list"): name both and do two steps, capability first. Never fold a capability install into a view.
+
+### 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 **goal** 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, goal, 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…)?      | **Goals** — `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 goal inside a project → a GOAL (a track)
+
+A **goal** is a _track_ in every tool and field name (`synap_start_track`, `trackId`) — say "goal" to the person, never "track". It lives inside ONE project ("Launch the new site", "Win the first ten clients"); a project runs several. A goal that FINISHES holds an `endState` (what done looks like, a short paragraph in the person's words) and **2 to 5 `criteria`** — binary checks, each with how it is checked: measured (evidence a run posts), judged by a person, handed over, or decided by an outside party. A goal kept open as long as it matters ("keep the newsletter growing") has no criteria: it steers by a `direction` (one line) and, only if the person names a number, a `kpi` `{ label, unit?, target }`. Propose its `workKind` (project, operation, investigation…) and `uncertainty`; the person confirms them. Its judge (the owner unless someone else is named, `synap_set_track_participant`) accepts what runs claim and closes it with a verdict — hitting a number never closes it. Work in it is ordinary sessions filed into it. Definitions: `concepts`.
+
+**Asked to pursue a goal in a project** ("launch the new site in Synap"): `synap_list_tracks` for the project (already running? resume it) → none? Propose the end state and 2–5 criteria in one line each and let the person correct them, then `synap_start_track` with `projectId`, `name`, `endState`, `criteria` (and `workKind`, `uncertainty`) — no method needed. Leave criteria out only when the person describes something to keep doing, not something to finish. Then work: `synap_start_session` with `trackId`, one session per sitting, carrying the criteria it works on (same `key`), as many as it takes.
+
+| The user needs…                                  | Do this                                                                                                                                 |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| a **goal** in an existing project                | `synap_list_tracks` (already running?) → `synap_start_track` (`name`, `endState`, 2–5 `criteria`; lasting: `direction`, optional `kpi`) |
+| one piece of work toward it                      | a **session** born in the goal: `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 goal method                                      |
+| new **kinds of things** no workspace owns        | a workspace (four-test, `workspace-design`) — never to represent a goal                                                                 |
+| a new long-lived commitment with its own gravity | a project — never a twin project for a goal of an existing one                                                                          |
+
+**A goal steers; its sessions verify.** A session that passes a criterion CLAIMS it; the judge accepts or sends it back — never accept your own claim. Report a lasting goal's number 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 or close the goal; never change the target or close the goal yourself. While a goal is active, its agent may work in the spaces its project links (`synap_project_use_workspace`); pausing it suspends that, closing or dropping it ends it. Pause, resume, close (`completed` + a `verdict`) or drop (`archived`, with a `verdict` saying why) it with `synap_set_track_status`; your close is a proposal the person approves. Goal writes are governed: `proposed` is success. Installing a pack onto a project does **not** start goals — start each one.
+
+**Legacy: goals with steps.** A goal started from a goal 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 goal templates; a new goal 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 goal (`synap_start_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,29 +36,29 @@ 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:
 
 - One sentence per field. No padding.
 - `Links` must reference real entity IDs or slugs visible in the current context — not descriptions like "the related project".
-- **"Agent requires proposal for all write operations."** is never acceptable as a `reasoning` value. That is an internal governance message, not agent reasoning. Write it and the proposal is meaningless to the reviewer.
+- The pod's own governance sentence (for example "This agent asks before every change.") is never acceptable as a `reasoning` value. It says why a person must review, not why you made the change. Write it and the proposal is meaningless to the reviewer.
 
 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, goal, 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 **goal** (a _track_ in every tool and field name — say "goal" to the person), never a child project or a workspace; a bounded piece of work is a **session** (`trackId` when it belongs to a goal). 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.
-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.
+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 a near-duplicate name is filed for the person to review, showing the existing project.
 
 **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 none for it) → offer a **goal**: _"This project has no goal 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 goal 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
 
@@ -122,8 +122,9 @@ GET /api/hub/graph/traverse?entityId={id}&maxDepth=2
 
 ## Common mistakes
 
-- **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.
+- **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). A near-duplicate project name is filed for review with the existing project shown to the person, 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.