@synap-core/cli 1.11.0 → 1.12.2

package/skills/synap/quick-reference.md

@@ -8,11 +8,15 @@ synap use <workspace-name-or-id>                       # focus a workspace (this
 synap create entity --profile=task --name="…" --props='{"status":"todo","priority":"high"}' --json
 synap set entity <id> --props='{"status":"done"}' --json  # merge-patch (only changed keys)
 synap ask "your question" --json                       # THE read verb — routes to the right store(s) + shows which answered
-synap capture --type=lesson --claim="…" --json         # Work lane (default) — domain knowledge → active workspace
+synap create entity --profile=knowledge --name="…" --props='{"knowledgeForm":"fact|caution|convention","ek_claim":"…"}' --content="…" --json
 synap capture --global --type=reference --claim="…" --json  # Global lane — pod-wide cross-cutting runbook (knowledge_keys)
 synap observe write "…" --json                          # User lane — durable user model (inferences proposed)
 ```
 
+**Titles:** ≤ 80 characters, the lasting thing, no status words, ids or "…"; the
+receipt's `titleLint` says what to rewrite. Rules + what counts as knowledge:
+`synap_load_skill("system/synap/writing-titles")`.
+
 **The canonical verbs:** `ask` (read) · `capture` (structured write — pick a lane:
 Work default / `--global` / `observe` for User) · `orient` (bootstrap). `note` exists
 for the HUMAN's raw "dump now, structure later" inbox — **the AI always `capture`s

package/skills/synap/reading.md

@@ -7,11 +7,13 @@ the low-level doors below only when you deliberately want a single substrate or
 specific shape (a graph traversal, a typed-entity filter, an entity's neighborhood).
 
 ```
-# THE read door — routes across semantic / procedural / episodic, tells you which answered
+# THE read door — routes across semantic / procedural / episodic / library, tells you which answered
 POST /api/hub/knowledge/ask   body: { query, workspaceId?, limit? }
   → { query, routedTo: [...], primary, answers: [{ substrate, items, status }], degraded, understanding, verdict }
 ```
 
+A link the person kept is in their Library: `ask` finds it (a `library` block — title, source URL, a snippet of what was read, who read it; `degraded: ["library"]` means the Library could not be read, never "nothing kept"). To read any URL use the `read_webpage` intent (builtin `web.read`).
+
 Low-level doors (`ask` routes to these — graph-based, not semantic; type filter →
 relations → neighborhood):
 

package/skills/synap/reflexes.md

@@ -1,46 +1,16 @@
-## Reflexes — the two habits, every session
+## Reflexes — what holds on every door
 
-> Canonical source — MCP instructions and other surfaces derive from this file.
+> Canonical source — the MCP `instructions` field is derived from this file and composed with live grounding under ONE 2 KB budget (pinned by `instructions-budget.test.ts`). Most important first. Depth belongs in a skill, never here.
 
-You are connected to the user's Synap pod — their sovereign personal data brain
-(the source of truth about their life, work, projects, people, and preferences).
-Two reflexes hold on every session, on every door (MCP, IS, CLI, HTTP):
+The user's Synap pod: their source of truth. Tool names below are stems; your door may prefix them (`pod__ask`).
 
-- **Recall — BEFORE any non-trivial task.** Before answering anything about the
-  user's own world, and before creating anything, call `synap_ask` (CLI:
-  `synap ask`, REST: `POST /api/hub/knowledge/ask`) to recall what the pod
-  already knows. Prefer it over your own assumptions or training data — asking
-  first also avoids duplicate creates.
-- **Capture — AFTER you learn something durable.** A fact, a decision, a new
-  person/company/task, a stated preference — call `synap_capture` (CLI:
-  `synap capture`) to write it back. Don't wait to be asked; this is how the
-  second brain grows.
+1. **Recall first.** Before answering or creating, `ask`.
+2. **Capture after.** A durable fact, decision, person, task: `capture`; about the user: `remember_fact`. No private scratchpad.
+3. **Orient once.** `orient`: pending review (raise first), open sessions, kinds.
+4. **Work in a session.** `start_session` or resume (playbook `templateId`); a lasting goal = TRACK: `list_tracks`, else `start_track`; work in it = `start_session` + `trackId`; 2-5 `criteria`; status moves carry `expectedStatus`; person-only: `owner:'human'` slot + `blockedReason` + `ask` (confirm/choose with 1 `recommended`/form/act/provide), then `wait_for_answer` if listed; post progress, questions and results in its room (`post_message` to `session.channelId`); your own chat may repeat them; `evaluate_session` before `complete_session`.
+5. **Never guess a project.** Pin only what the user names (`set_workspace_focus`, `set_project_focus`).
+6. **`proposed` is success**: keep going, never retry.
+7. **Discover before inventing.** `list_profiles` / `list_capabilities` before defining a kind, role, space. **Extend first** (facet, overlay, parent); never a twin.
+8. **One space per domain**; projects filter it (`file_into_project`, `project_use_workspace`).
 
-Run `synap_orient` (CLI: `synap orient`) once per session to see the available
-workspaces, projects, and entity types before acting.
-
-**Writes are governed: a `"proposed"` response is normal, never an error.** It
-means the write is queued for the user's review — like a PR, not a failure. Keep
-working; see `writes.md` for the full governance contract and `inline-patterns.md`
-for how to surface a proposal's review link in a Companion reply.
-
-**No private scratchpad.** Everything you learn goes into the shared graph, not a hidden note. Capture a proven tool-fact into `knowledge` immediately; PROMOTE it into a curated skill only once it's proven reusable — a skill is a versioned artifact (one capability, when-to-use + do/don't), never an append-anything log.
-
-## Escalation ladder (keep in a corner of your head)
-
-You can always escalate — never dead-end on "I can't." Full detail: `escalation-ladder.md`.
-
-- **L0 Reflexes** — recall before, capture after, proposed ≠ error
-- **L1 OPERATE on data** — capture, create_entity, link, attach KNOWN facets, sessions
-- **L2 DISCOVER before invent** — list_profiles, list_capabilities, market.search (capability|template|automation|cell)
-- **L3 MUTATE meta-model (proposal-gated)** — only if L2 empty for the need:
-  define_role, create_property_def/profile, create_view, create_workspace, market.install.
-  **Template FIRST for new domains:** market.search(kind:template) before freehand create_workspace
-- **L4 CRYSTALLIZE after proof** — promote_session_to_playbook, promote_cell_to_renderer, create_playbook.
-  Never crystallize a one-off that hasn't succeeded once
-
-**Gates:**
-
-- Blocked / can't express need → L2 then L3 propose (never dead-end error; never silent invent)
-- Success / repeatable pattern → one structural suggestion (question first if speculative)
-- Capture placement routes to EXISTING lenses only — never invent a workspace from capture
+Depth: `load_skill` `system/synap/concepts`, `work-model`, `focus-sessions`, `from-intent`, `escalation-ladder`, `writes`, `catalog`.

package/skills/synap/viewframe-cells.md

@@ -10,6 +10,12 @@ ViewFrame is the standard way to create custom data visualizations in Synap. Use
 | User asks for a specific chart type, map, 3D scene, or custom layout   | Generate a ViewFrame widget   |
 | User says "show X as a [funnel / heatmap / treemap / scatter / globe]" | Generate a ViewFrame widget   |
 
+### Default vs. generated — never the reflex, always the explicit ask
+
+Every kind already renders as a familiar, kind-shaped card — its built-in `entity-card` (small block) / `entity-detail` (full page) / `entity-profile` (dashboard) renderer. That built-in is the DEFAULT for everyone, including brand-new user-defined kinds (which get an automatic card built from the schema — no generation needed). **Never generate a frame renderer as a kind's default presentation.** Generate one ONLY when the user explicitly asks for a custom look — a specific chart type, a redesigned card, a bespoke layout — and bind it PER KIND (one profile's one renderer slot), never as a blanket replacement for every kind. The sandbox's egress holes (see Security below) are still open, so treat "generate a view/card" as a deliberate, scoped request, not something to reach for by default.
+
+After binding, tell the user where the result lives: **"⋯ → Customize display"** on that kind's page (Renderer Studio itself now lives in Builder mode / Settings, not a designer mode you build). That is the one place a human reverts it or picks something else — never invent a second, agent-only way to switch it back.
+
 ### What ViewFrame Is
 
 - A sandboxed iframe that renders **one ES module** that default-exports a React component (or plain JS)
@@ -17,7 +23,7 @@ ViewFrame is the standard way to create custom data visualizations in Synap. Use
   `deps` map, but the current Hub `cells/define` persistence path does not yet
   retain that map, so external runtime dependencies are not a reliable contract.
 - The host injects a `SynapWidget` bridge for data access and shell actions
-- Security: `sandbox="allow-scripts allow-modals allow-popups"`, no `allow-same-origin`, no cookies, no pod token
+- Security: `sandbox="allow-scripts allow-modals"` — no `allow-popups`, no `allow-same-origin`, no cookies, no pod token
 
 ### Authoring contract
 
@@ -32,7 +38,7 @@ A ViewFrame cell is **one self-contained ES module** (inline in `rendererSource`
 
 **Use `POST /api/hub/cells/define` — this is the canonical Hub Protocol path for AI-generated cells.**
 
-It is idempotent (upserts on typeKey), pod-global by default (no workspaceId needed), and immediately available across all of the user's workspaces without any proposal step.
+It is idempotent (upserts on typeKey) and pod-global by default (no workspaceId needed). **It IS governed for agent callers** — `POST /cells/define` runs `checkPermissionOrPropose({ resource: "cell", action: "define", trustLevel: "generated" })`; a `status: "proposed"` response is the normal outcome for AI-generated renderer source, not an error — surface `reviewUrl` and keep going. Only an operator-initiated define auto-applies.
 
 ```
 POST /api/hub/cells/define
@@ -100,7 +106,7 @@ The cell appears immediately in the side panel with "Q2 Revenue Report" as the t
 
 > **Note:** `POST /api/hub/widget-definitions` (tRPC path) still works but is the internal/admin path. Use `POST /api/hub/cells/define` for all agent-generated cells.
 
-### CLI commands (when running as Claude Code / OpenClaw agent)
+### CLI commands (when running as Claude Code or another terminal agent)
 
 ```bash
 # Build a multi-file cell source into a single ES module bundle
@@ -120,7 +126,7 @@ synap doc create --title "Q2 Report" --file ./report.md
 synap doc update <docId> --file ./updated-report.md
 
 # Arrange widgets on an existing bento view
-synap view arrange <viewId> --blocks '[{"id":"b1","kind":"widget","widgetKind":"generated:my-chart","layout":{"x":0,"y":0,"w":8,"h":6}}]'
+echo '[{"key":"generated:my-chart","x":0,"y":0,"w":8,"h":6}]' | synap view arrange <viewId>
 ```
 
 ### The SynapWidget Bridge (inside the iframe)
@@ -157,6 +163,33 @@ SynapWidget.onInit(async ({ config, context }) => {
 
 All `query()` calls return a Promise. Entity shape: `{ id, title, profileSlug, properties, createdAt, … }`.
 
+#### Intent reads (a kind's pipeline, goal, needs-you, sessions)
+
+The same reads a kind's own page makes, so a frame can be that kind's dashboard. The host stamps the lens (the active space and project); a `workspaceId` / `projectId` you pass is ignored. `trackId` narrows to one track.
+
+| Operation              | Params                                                                                                | Returns                                                                                                                                                                                                                              |
+| ---------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `lifecycle.board`      | `profileSlug` (required), `trackId`, `windowDays`, `firstN`, `column` + `cursor`, `limit`, `workedBy` | `{ lifecycle: { profileSlug, property, options }, columns: [{ key, category, count, stuck, items: [{ id, name, status, since, stuck, workedBy? }] }], live, total, doneWindowed, lostWindowed, suggestedShape, window, nextCursor }` |
+| `lifecycle.throughput` | `profileSlug`, `trackId`, `bucket` (`day` · `week` · `month`), `count`                                | `{ bucket, since, buckets: [{ bucketStart, done, lost }] }`, oldest first, zeros included                                                                                                                                            |
+| `attention.needsYou`   | `profileSlug`, `trackId`, `limit`                                                                     | `{ signals: [{ id, kind, title, count, occurredAt, target }] }`                                                                                                                                                                      |
+| `attention.count`      | `profileSlug`, `trackId`                                                                              | `{ needsYou, decisions, blocked, review, captures, truncated, … }`                                                                                                                                                                   |
+| `sessions.list`        | `profileSlug` (its things) or `entityId` (one thing), `status`, `kind` (default `work`), `limit`      | `[{ id, title, goal, status, currentStage, progress, startedAt, … }]`                                                                                                                                                                |
+
+```js
+const board = await SynapWidget.query("lifecycle.board", {
+  profileSlug: "post",
+  firstN: 5,
+});
+if (board?.error) return showError(board.error); // 404 = unknown kind, 412 = no lifecycle
+const month = await SynapWidget.query("lifecycle.throughput", {
+  profileSlug: "post",
+  bucket: "month",
+  count: 1,
+});
+```
+
+A failed read returns `{ error }`. Show it as a failure, never as an empty board. Moves still go through `update_entity` (the lifecycle property), so the status door and governance apply.
+
 #### Mutations (governance-gated — return `{ status: "approved" | "proposed" | "denied" }`)
 
 ```js
@@ -182,7 +215,7 @@ await SynapWidget.mutate("delete_entity", { id: "uuid" });
 await SynapWidget.mutate("create_relation", {
   sourceEntityId: "uuid-a",
   targetEntityId: "uuid-b",
-  type: "related_to",
+  type: "relates_to",
 });
 ```
 

package/skills/synap/work-flow.md

@@ -77,7 +77,7 @@ User: _"I'm trying to figure out whether we should build our own orchestrator or
      } }
    ```
 
-4. When the user picks, create a decision linked to the question:
+4. When the user picked through an answered `confirm`/`choose` ask, the pod ALREADY filed the decision (`slot.decisionId`) — link that one, never create a twin. Picked in plain chat? Create it yourself, linked to the question:
 
    ```json
    POST /api/hub/entities

package/skills/synap/work-model.md

@@ -0,0 +1,96 @@
+## Work model — how work is shaped on a pod
+
+Load this before you plan, start or run work, or author a process. The long form is the pod document "The Synap work model" (36878a70-6cbb-4122-8bfa-288fdbd65218); the words are in `concepts`.
+
+### Why
+
+A process is the life of a **thing**, not a script. A lead, a post or a feature has ONE status. Boards, workers, sessions, goals and history read that status or move it through ONE door. So "when a post enters Review, run the review" is one rule, "how many leads reached Qualified this month" is a count, and a person and an agent can work the same thing without overwriting each other. Before, each playbook kept its own stages and status field, and the same fact lived in three places.
+
+### The nouns
+
+| Noun                 | What it is                                                                          | Not                                  |
+| -------------------- | ----------------------------------------------------------------------------------- | ------------------------------------ |
+| **Project**          | a commitment, and a lens across spaces                                              | a method, a domain                   |
+| **Track** (optional) | a LASTING intent in one project: direction, instructions, goal; it turns workers on | a list of stages; it never completes |
+| **Thing**            | any entity: one kind, maybe roles, one status per kind or role                      | a second entity for a hat            |
+| **Session**          | the unit of work that closes: goal, criteria, room; one thing or a batch            | a "run" because it follows a method  |
+
+Not nouns (nobody manages them as objects): a **pipeline** is a view of a lifecycle; a **worker** is configuration (a method + a trigger + a size); a **method** is a playbook a session may follow; a **check** is a recurring verification.
+
+How they relate: a project files things; each kind or role declares one **lifecycle** (its status list); its **pipeline** is computed (columns = the options in order); a status change fires **workers**, which start **sessions** carrying the project, the track and their **targets**; a session moves each thing's status through the door. **Hand-off is a role:** a won deal makes the party a client (attach the role); nothing is copied.
+
+### Three tenses of a thing
+
+- **Past = history.** Every status change is one transition event: from, to, who, which session, why.
+- **Present = status.** One value per kind or role, in its own column.
+- **Future = agenda.** Tasks and events linked to the thing, with an owner. _(Planned, wave 4.)_
+
+### Five categories
+
+Every lifecycle option has one fixed category: `open · active · paused · done · lost`. Names are free; rules read the category. An agent moving a thing into `done` or `lost` proposes by default; an option marked `humanOnly` is never set by an agent. A space may ADD options; it never renames, removes or recategorises one.
+
+### The one door
+
+Every status change — your call, a board drag, a method's step, a sync — goes through `moveStatus`. As an agent: a kind's status = `update_entity` with the lifecycle property set to the new value AND, over MCP, `expectedStatus` = the status you saw (the in-app `update_entity` has no `expectedStatus` yet; the door still checks the lifecycle); a role's status = `update_facet` `status` where your tools list it (the in-app agent; MCP has no role-status tool yet).
+
+- `conflict` (with the current status) is normal: someone moved it; re-read and decide again. A person's move always wins.
+- `proposed` is success (a done/lost move, or governance said review).
+- A refusal naming the valid options means the value is not in the declared lifecycle: pick one of them.
+  Never invent a status, never keep your own stage field.
+
+### Session size
+
+- **Per thing** when each item needs its own thinking: a post, a feature, a deal in negotiation.
+- **Per batch** when items are interchangeable: one session for "find 10 leads today" or "today's follow-ups".
+- A session's **step is its subject's status**: move the thing, the step follows.
+- **Set the subject.** A session about one thing names it: `subjectEntityId` on `start_session`, or on `update_session` the moment the thing exists (a batch names its things as targets). A session on no thing shows on the homes as "No thing yet · attach one", outside every pipeline.
+- Following a method does not turn your session into a run; it stays your work and still shows in the method's runs.
+- **Targets get a result each**: a worker session holds its things as targets. Your own move of a target marks it `done`; someone else's move marks it `skipped`; targets left at close are `skipped`. Put the outcome on each thing, not only in a summary.
+
+### Workers
+
+A worker is a playbook **activator**, declared on the method and owned by the lifecycle: `on` = `created` · `enters_status` (+ `status`) · `count` (+ `status`, `min`: once N things wait) · `schedule` (+ `cron`) · `manual`; `size` = `per_thing` · `per_moment` (a count or schedule is always per batch); `mode` = `propose` (default) · `run`; `maxPendingApprovals` throttles it. It compiles into a governed rule the owner can pause; it fires once per thing per transition. A track or project **turns it on** for its scope; installs turn it on space-wide. Authoring: `processes`.
+
+### Tracks
+
+A track holds an owner, a direction, instructions, the workers it turns on, and a goal (stated, or measured as transitions into `done`). It has no stages and never completes: pause or archive it. Work in it = `start_session` + `trackId`. A thing may count for two tracks. Solo users may never need one: workers can run space-wide. Legacy: `start_stage_session` and `add_track_stage` serve old tracks started from a method; never `advance_track` without the user.
+
+### The homes: what each space makes, what is moving
+
+Home, a space and a project read the work through two reads (the same answer every app shows):
+
+- `lifecycle.home` (Hub `GET /api/hub/lifecycle/home?projectId=`): every space you see with its intent and, per kind it produces, the pipeline in one line, needs-you, being-worked and one headline thing.
+- `lifecycle.moving` (Hub `GET /api/hub/lifecycle/moving?workspaceId=&projectId=&limit=`): the things with open work on them, the work under each (asks you first), and `unattached`, the open sessions on no thing.
+
+Read them to answer "what is going on" before you list sessions one by one.
+
+### A kind's dashboard
+
+A kind with a lifecycle has its own page: the board, Needs you, the sessions on its things. To give it a custom Dashboard ("make this my Posts dashboard"), `create_cell` a frame over the bridge's intent reads (`lifecycle.board`, `lifecycle.throughput`, `attention.needsYou`, `attention.count`, `sessions.list`), then `promote_cell_to_renderer` with `slot: "dashboard"` (the `entity-profile` content kind). Recipe: `synap-ui`; params and shapes: `viewframe-cells`.
+
+### Rules of thumb
+
+1. Find the thing before creating one: resolve identity, then attach a role — never a twin.
+2. Status changes go through the door, with `expectedStatus`.
+3. Never invent a status or a second status field; the lifecycle is declared on the profile (`list_profiles`).
+4. Size the session from the work: per thing or per batch.
+5. Results go on the things, not only in prose.
+6. `proposed` is success. Commitments (publish, send, sign, spend) are a person's call.
+
+### Applied: content (Content OS)
+
+- Thing = a **post**. Lifecycle `post-status`: Idea (open) · Briefed · Scripted · In Draft · Review · Scheduled (active) · Published (done) · Archived (lost, human-only).
+- Nothing publishes itself: a move to Published is a proposal the person approves on the preview.
+- Pipeline = the Posts board, filtered by project or campaign.
+- Workers: **Draft** (per thing, enters Briefed) · **Review prep** (per thing, enters Review, ends by proposing the publish date) · **Ideas** (per batch, weekly, creates posts at Idea). Today the catalog ships them as Produce Content (enters Briefed), Repurpose (enters Published) and Plan Next Content (weekly, off by default).
+- "The next posts" = read the pipeline: gaps per pillar, posts waiting per status.
+
+### Applied: leads and deals (CRM)
+
+- **Lead** = a role for qualification only, `leadStage`: new · researching · outreach (open) · engaged · qualified · nurturing (active) · converted (done) · disqualified (lost, human-only).
+- **Deal** = the sale, `commercialStage`, created only at hand-off. A **won** deal attaches the client role to the party.
+- A Cal.com booking makes the attendee a lead at `engaged` and records the call as an event; it never creates a deal and never moves a lead backwards.
+
+### Point another AI here
+
+Every door can load this: `load_skill system/synap/work-model`. To make a space carry it, put a one-line pointer in the space brief (`update_space_brief`, `purpose` or `framing`, 240 characters each): in-app agents and worker sessions read the brief every turn, MCP agents when they `orient`. To steer a session in flight, post the pointer in its room. A document attached to a session reaches an agent as a title only, so it does not teach.

package/skills/synap/worked-examples.md

@@ -25,7 +25,7 @@
    { "userId": "{userId}",
      "sourceEntityId": "ent_new_task",
      "targetEntityId": "ent_acme",
-     "type": "related_to" }
+     "type": "relates_to" }
    ```
 
 5. Confirm: "Task created and linked to Acme, due Friday."
@@ -57,18 +57,17 @@
 You are authoring this text yourself — it is not a file you have. Don't create
 a `file`/`document`-kind entity and stuff the Markdown into it.
 
-1. Search for an existing plan: `GET /entities?q=Q3 launch&profileSlug=knowledge&workspaceId=…` → none
+1. Search for an existing plan: `GET /entities?q=Q3 launch&profileSlug=note&workspaceId=…` → none
 2. Create a CONTENT-kind entity carrying the plan as `content` (the doc auto-materializes):
 
    ```json
    POST /api/hub/entities
    { "userId": "{userId}", "workspaceId": "{wsId}",
-     "profileSlug": "knowledge",
+     "profileSlug": "note",
      "title": "Q3 launch strategic plan",
-     "properties": { "ek_type": "reference" },
      "content": "# Q3 Launch Plan\n\n## Goals\n…\n\n## Timeline\n…"
    }
    ```
 
-3. Link it to the relevant project: `POST /api/hub/relations` `{ sourceEntityId: "ent_new_plan", targetEntityId: "ent_project_q3", type: "related_to" }`.
+3. Link it to the relevant project: `POST /api/hub/relations` `{ sourceEntityId: "ent_new_plan", targetEntityId: "ent_project_q3", type: "relates_to" }`.
 4. Confirm: "Plan captured and linked to Q3 launch." No upload, no `file` entity, no separate `synap_create_document` call.

package/skills/synap/workspace-design.md

@@ -1,6 +1,8 @@
 ## Workspace design — is this concern a WORKSPACE, or something smaller?
 
-Before you create a workspace, run the decision rule. A workspace (an operational **domain**) is the heaviest structure in the pod — it owns kinds, confers roles, carries its own team and automations. Most new concerns are NOT domains; they are a **hat**, an **initiative**, or a **stage**. Creating a workspace for one of those is the anti-pattern that fragments the graph. Decide first, then create.
+Before you create a workspace, run the decision rule. A workspace (an operational **domain**) is the heaviest structure in the pod — it owns kinds, confers roles, carries its own team and automations. Most new concerns are NOT domains; they are a **hat**, an **initiative**, a **lasting goal** (track), or a **status**. Creating a workspace for one of those is the anti-pattern that fragments the graph. Decide first, then create. What each word means: `concepts` (the one glossary).
+
+**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.
 
 ## The decision rule — a concern earns a workspace ONLY if ALL FOUR hold
 
@@ -11,20 +13,22 @@ Before you create a workspace, run the decision rule. A workspace (an operationa
 
 **All four, or it is not a workspace.** Then fork it to the right lighter structure:
 
-| If the concern is…                                          | It is a…       | Substrate                              | Example                                     |
-| ----------------------------------------------------------- | -------------- | -------------------------------------- | ------------------------------------------- |
-| a **role/hat** an existing entity wears in a domain         | **Facet**      | `attach_facet` (`profileKind: "role"`) | `client`, `sponsor`, `prospect`, `investor` |
-| a **cross-cutting, time-bound initiative** spanning domains | **Project**    | `create_project` (a lens)              | a campaign, an engagement, a launch         |
-| a **stage/filter WITHIN a domain**                          | **State/View** | a `status` property def + a view       | pipeline stage, "active"/"archived"         |
+| If the concern is…                                          | It is a…    | Substrate                              | Example                                     |
+| ----------------------------------------------------------- | ----------- | -------------------------------------- | ------------------------------------------- |
+| a **role/hat** an existing entity wears in a domain         | **Facet**   | `attach_facet` (`profileKind: "role"`) | `client`, `sponsor`, `prospect`, `investor` |
+| a **cross-cutting, time-bound initiative** spanning domains | **Project** | `create_project` (a lens)              | a campaign, an engagement, a launch         |
+| a **lasting goal** a project pursues (worked in sessions)   | **Track**   | `start_track` (no method needed)       | grow the newsletter, win ten clients        |
+| a **stage/filter WITHIN a domain**                          | **Status**  | an option of the kind's lifecycle      | pipeline stage, "active"/"archived"         |
 
 ## The decision procedure (follow in order)
 
 1. **Name the source-of-truth noun.** What kind would this workspace _own_ that no existing workspace owns? Run `list_profiles` — if the noun already lives in another domain, you have a facet or a project, not a domain. STOP.
 2. **Test all four conditions.** Owns kinds AND own team AND native automations AND stable. Any one fails → fork below.
-3. **If it's a hat** (a status/role on an entity that already exists elsewhere) → resolve the entity, `attach_facet`. Never a workspace, never a second entity.
+3. **If it's a hat** (a status/role on an entity that already exists elsewhere) → resolve the entity, `attach_facet`. Never a workspace, never a second entity. One role per name, pod-wide: a role several workspaces use is ONE role, each workspace adding properties by overlay — never a per-workspace twin (`concepts`).
 4. **If it's time-bound work across domains** → `create_project` and set it as the lens; the work files into it from whatever workspace holds the data. **A project is a COMMITMENT WITH GRAVITY** — a real initiative that ties work together (a campaign, an engagement, a client, a launch). Tasks, plans, repos, themes, and topics are **entities**, never projects. Before you create one: (a) **search existing projects first** (`synap orient` / `GET /api/hub/projects`) and prefer **linking into an existing project** via `belongs_to_project` — near-duplicate names are rejected with the existing candidates; (b) an agent-created project must cite **≥5 existing entities** that would belong to it as `evidenceEntityIds` — the backend rejects a project with no gravity and tells you to store it as an entity or reuse an existing project instead; (c) **never create a project for the pod owner's own company** — the company _is_ the pod, not a project inside it.
-5. **If it's a stage inside a domain** → add a `status` property def (`create_property_def`) and a view; don't split the stage into its own space.
-6. **Only if all four held** → **template first** (escalation ladder L3):
+5. **If it's a lasting goal a project pursues** ("keep the content side of the launch going") → a **track**: `list_tracks`, else `start_track` (`name`, `direction`); work in it with `start_session` + `trackId`. Never a workspace, never a twin project.
+6. **If it's a stage inside a domain** → it is an option of the kind's or role's declared lifecycle, never a role and never a space. Its pipeline is computed from the lifecycle: open it, don't build one. A kind with no lifecycle yet gets a `status` property def (`create_property_def`).
+7. **Only if all four held** → **template first** (escalation ladder L3):
    `market.search({query, kind: "template"})` and propose install of a matching
    template before freehand `create_workspace`. Freehand create is last resort
    and always proposed — a deliberate move, offer it to the user (see
@@ -32,7 +36,7 @@ Before you create a workspace, run the decision rule. A workspace (an operationa
 
 ## The CRM corollary — the load-bearing example
 
-Operational state — **prospect → client → delivered** — is a **FLOW across domains**, expressed as **facets + a triggered project**, NEVER as workspaces and NEVER by bolting delivery onto the identity domain.
+Operational state — **prospect → client → delivered** — is a **FLOW across domains**, expressed as **facets + an engagement project** (its delivery runs as a track), NEVER as workspaces and NEVER by bolting delivery onto the identity domain.
 
 - CRM = **who** (owns `person`/`company`, confers the `lead`/`client` facets).
 - Operations = **what we do for them** (owns `engagement`/`contract`/`deliverable`).

package/skills/synap/writes.md

@@ -1,11 +1,29 @@
 ## Core writes
 
-**Two write doors, one gradient.** `create_entity` is for exactly ONE
+> **Scope of this page.** It covers writes that produce ENTITY-shaped data.
+> There are ~30 other write tools (sessions, capabilities, automations, cells,
+> playbooks, views, channels…) that this page does not orient across — reach for
+> `synap_list_capabilities` / the escalation ladder for those. If you are about
+> to pick a tool and the choice feels ambiguous, that ambiguity is real: the
+> tools below differ in ATOMICITY and COLLISION policy, not just in shape.
+
+**Two entity-write doors, one gradient.** `create_entity` is for exactly ONE
 fully-structured, typed entity you already have. For anything unstructured,
 several entities, or a graph — or **when in doubt** — use the capture door
 (`synap_capture`, see `capture.md`): precision comes from sending more structure
 in the SAME call, never from picking a different tool or a second commit step.
 
+The difference that is NOT visible in either tool's description: `create_entity`
+writes one entity with per-entity governance and REJECTS a name collision unless
+`forceCreate`; capture-with-`entities[]` files ONE atomic proposal for the whole
+graph and DEDUP-MERGES instead of rejecting. Pick by whether you want a partial
+write to be possible, not by how structured your data feels.
+
+**Every title is linted.** Both doors return `titleLint` in the receipt when a
+title breaks the rubric (too long, cut off, status words, ids, a placeholder…);
+the title is stored as sent, so rewrite it. Over 200 characters the write is
+refused. Title rules and what counts as knowledge: `writing-titles.md`.
+
 ### Create an entity (one exact typed entity)
 
 Before this call, use `/discover?userId=…&profileSlugs=<kind>` to read the
@@ -31,9 +49,10 @@ The response has legacy `status`/`id` fields plus `writeReceipt`:
 `pending`/`proposed` means a proposal exists and no entity is live yet;
 `applied` means the reported direct write completed; `partial` means a follow-up
 (for example a facet) failed after the entity applied. **A `proposed`/`pending`
-receipt is a governed success, not an error** — surface its `reviewUrl`, never
-claim completion, and only enrich again when the receipt identifies a real
-missing fact.
+receipt is a governed success, not an error** — you MUST surface its
+`reviewUrl` as a clickable markdown link in the same reply (see
+`inline-patterns.md`), never claim completion, and only enrich again when the
+receipt identifies a real missing fact.
 
 For several entities, creation-time roles/facets, or relations that need one
 review, send the whole graph through the capture door (`synap_capture` with
@@ -59,6 +78,26 @@ PATCH /api/hub/entities/{entityId}
 
 **Properties are deep-merged — send only the keys you want to change.** An update with `{ "status": "done" }` leaves all other properties untouched. You never need to re-send the full properties object.
 
+**Many changes → ONE call: `synap_update_entities`** (up to 500 items
+`{id, patch, expected?}`; Hub: `POST /api/hub/entities/batch-update`). Never
+script a loop of single updates, and never apply a change set over Hub REST with
+a user key. Governance is per item: some apply now, the rest ride ONE review for
+the person; the answer lists `applied` / `proposed` / `denied` / `skipped` — a
+partial result is normal. Send `validate: true` first to see each verdict without
+writing, and an `idempotencyKey` so a retry never acts twice.
+
+**A write blocked on a space join is KEPT.** When you write into a space your
+agent has not joined (`synap_orient` marks it `joined: false`), the answer is
+`proposed` with `proposalType: "join"`, `deferred: true` and a `ref`: the write
+rides the join request and is replayed for you once it is approved. Do not
+resend it, and do not retry it into another space.
+
+**Moving, not recreating.** A session into another space:
+`synap_update_session` with `moveToWorkspaceId` (never `workspaceId` — that is
+the connection's lens). A kind another space needs: `synap_change_kind_scope`
+(`scope: "shared"` + `allowedWorkspaceIds`), never a twin kind. Records:
+`synap_move_entities`. All three are reviewed.
+
 ### Authored text is content, not a `file`
 
 Something **you** author — a pitch deck, a strategic plan, a note body — is
@@ -67,8 +106,8 @@ kind (`note`, `knowledge`, or a fitting domain kind) with `content` set to the
 Markdown body; Synap **auto-materializes** that `content` into a real
 versioned document behind the scenes (`entities WHERE documentId = ?`) — no
 upload step needed. `file` is reserved for real uploaded bytes you actually
-have (the upload door / `synap upload`) — an agent has no filesystem, so it
-rarely touches `file` at all. Reach for `synap_create_document` /
+have (`synap_store_file`; over 10MB `synap_request_upload`) — authored text
+never becomes a `file`. Reach for `synap_create_document` /
 `POST /api/hub/documents` directly only for a standalone rich document that
 isn't itself a title-worthy entity (see below) — never as a substitute for an
 entity's `content`.
@@ -82,9 +121,18 @@ You CAN store content you **hold** — you send it inline. Pick by what you have
 | **Content in hand** — a report/CSV/image/PDF/etc. you generated or received (text or bytes) | **`synap_store_file`** (`content` for text, `contentBase64` for binary) + `mimeType`/`filename` | a `file` entity, content stored **as-is, never read** (≤10MB inline) |
 | Text you're **authoring as a note/idea** (not "a file") — a plan, a thought                 | `synap_create_entity` with `content` (a content kind)                                           | body auto-becomes a document — NOT a `file`                          |
 | Only a **URL/link** (no bytes) — a Google Doc, a PDF url, an article                        | `synap_create_document` with **`url`**, or attach via `entityId`                                | an external **reference** document (no bytes)                        |
-| A **large file on a local disk** you don't hold in context                                  | the CLI `synap upload <path>` (streams it) — an agent can't send bytes it doesn't have          | a `file` entity backed by stored bytes                               |
+| A **large file** (over 10MB, up to 500MB video)                                             | `synap_request_upload` → PUT the bytes to `uploadUrl` → `synap_store_file({ uploadToken })`     | a `file` entity backed by stored bytes                               |
 | Only a file's **name**, nothing else                                                        | you **cannot** invent it — ask the human/client to provide the content or a link                | —                                                                    |
 
+**A typed thing with a file → the KIND first, the bytes on it.** When a kind
+exists for the thing (a logo is a `brand-asset`, not a `file`; check the space
+brief or `synap_list_profiles`): (1) resolve-or-create that entity
+(`synap_ask`, then `synap_create_entity`); (2) `synap_store_file` with
+`attachToEntityId` = its id (`content` for SVG/text, `contentBase64` for
+binary, ≤10MB inline; larger: `synap_request_upload`, then `uploadToken`); (3) link it /
+`synap_file_into_project` if asked. A `proposed` create has no live id yet —
+attach after approval. A bare `file` is only for bytes with no kind.
+
 **Store ≠ analyze.** `synap_store_file` / `synap_create_document` store content
 **deterministically — the file is NEVER read by an LLM.** Only fetch a document
 and reason over it when the user explicitly says "read/analyze this file."
@@ -106,11 +154,19 @@ POST /api/hub/documents
   "type": "markdown",              // "markdown" | "html" | "text" | "code"
   "entityId": "ent_event_..."      // attach to an entity for context
 }
+// → { "id": "doc_abc", "documentId": "doc_abc", "status": "created", "ackState": "applied",
+//     "attached": { "entityId": "ent_event_...", "documentId": "doc_abc", "status": "updated" } }
 ```
 
+`attached` reports the attach outcome: it is a governed entity update, so it can
+be `proposed`, and it is `skipped` (with a `reason`) while the document itself is
+awaiting review. Other optional fields: `url` (an https link — creates a reference
+document with no stored bytes), `idempotencyKey` (a retry with the same key returns
+the prior document), `expectedLabel` (the session-output slot it fulfils).
+
 `type: "html"` stores self-contained HTML. The browser renders it via the `html-doc` cell in a sandboxed iframe. Use for AI-generated reports, rich visualisations, custom charts, or anything beyond markdown.
 
-**Full HTML cell workflow** (AI → visible custom UI in any bento):
+**HTML document workflow:**
 
 ```json
 // 1. Create the HTML document
@@ -119,35 +175,50 @@ POST /api/hub/documents
   "title": "Q2 Revenue Report", "type": "html",
   "content": "<!DOCTYPE html><html>…</html>",
   "entityId": "ent_project_..." }
-// → { "document": { "id": "doc_abc" }, ... }
+// → { "id": "doc_abc", "documentId": "doc_abc", "status": "created", ... }
 
-// 2. Place the html-doc cell in any bento view
-POST /api/hub/views/{bentoViewId}/arrange
-{ "userId": "{userId}", "workspaceId": "{workspaceId}",
-  "widgets": [
-    { "id": "b1", "kind": "html-doc", "config": { "documentId": "doc_abc" },
-      "layout": { "x": 0, "y": 0, "w": 8, "h": 6 } }
-  ] }
-
-// 3. Update the HTML (cell auto-refreshes)
+// 2. Replace the HTML (read it first: GET → `revision`)
 PATCH /api/hub/documents/doc_abc
-{ "userId": "{userId}", "content": "<!DOCTYPE html>…updated…</html>" }
+{ "userId": "{userId}", "content": "<!DOCTYPE html>…updated…</html>", "baseRevision": 3 }
+// → a pending proposal; readers see the new HTML only once it is approved
 ```
 
+`html-doc` is **not** an agent-placeable bento widget: `arrange` rejects it. The
+document renders where it is opened (the Files app, or the entity it is attached
+to). For HTML you want to embed elsewhere, create an HTML cell instance
+(`POST /api/hub/cell-instances/html`) and embed it by `instanceId`.
+
 The iframe uses `sandbox="allow-scripts"` — scripts run but have no same-origin access to the parent app. The HTML is fully isolated.
 
-### Update a document (title and/or content)
+### Update a document's content (a patch, reviewed)
+
+Change the part you mean, not the whole body. Read it first —
+`GET /api/hub/documents/{id}?userId={userId}` → `content`, `revision`,
+`sections` (id + owner) — then:
 
 ```json
-PATCH /api/hub/documents/{documentId}
+POST /api/hub/documents/{documentId}/patch
 {
   "userId": "{userId}",
-  "title": "Updated title",          // optional
-  "content": "# Full replacement\n…" // full string — not a diff
+  "baseRevision": 3,
+  "ops": [
+    { "op": "replace_text", "old": "ships on Friday", "new": "ships on Monday" },
+    { "op": "upsert_section", "id": "risks", "title": "Risks", "body": "None yet." }
+  ]
 }
 ```
 
-Content is a **full replacement**, not a patch. Fetch the current content first if you want to append: `GET /api/hub/documents/{id}?userId={userId}` → `.content`, append, then PATCH.
+Ops: `upsert_section {id, title, body}` (one section by id), `replace_text {old,
+new}` (`old` must match **exactly once**, else 400 with the count), `append
+{body}`, `replace_all {content}`. An agent's edit is filed as a proposal (a
+governance rule may apply it directly); a person's section (`owner="human"`) is
+never changed and an embed is never dropped unless you pass
+`"allowRemovingEmbeds": true` (403 otherwise). A moved document answers 409 and
+nothing is written: read again. An applied or approved edit reaches open editors
+(`document:content-replaced`), so they reload instead of overwriting it. `PATCH /api/hub/documents/{id}` with `content` is the same door with
+one `replace_all` — it cannot rename (a `title` is refused with 400; to rename an
+entity's document, update the entity's title). MCP: `synap_update_document`;
+full syntax in `document-embeds.md`.
 
 The reverse lookup is `entities WHERE documentId = ?`. Always attach the document to a meaningful entity (the meeting event, the project, the person) — a floating document is another orphan.
 
@@ -202,6 +273,8 @@ POST /api/hub/entities
 
 This creates a first-class decision entity linked to Project Eve. It shows up in traversals, can be superseded later (`supersededBy: newDecisionId`), and survives governance. Memory can't do any of that.
 
+**A decision the PERSON must make** — create it with `decisionStatus: "proposed"` and the pod asks them for you: pass `decisionOptions` (≤8 of `{label, value?, description?}`) and `recommendedOption` (an option's `value`, else its `label`); set `sourceSessionId` to keep the question in your session. Their answer UPDATES that decision — never create a second one. Every answered `confirm`/`choose` ask already files its decision (`slot.decisionId`): don't create one for it. A person-owned slot blocked on a decision is ANSWERED by them (Yes/No or a choice) — it is never closed by marking it done. **Before you recommend**, recall the user's past decisions (`synap_ask`, or find `decision` entities) so your pick follows their past choices.
+
 ### Post to the user's personal channel
 
 ```