@synap-core/cli 1.10.0 → 1.12.2

package/skills/synap/mental-model.md

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

package/skills/synap/multi-entity-capture.md

@@ -1,10 +1,12 @@
 ## Multi-entity capture from free-form text
 
-When the user pastes a block of unstructured content (a meeting transcript, an email, a LinkedIn bio), use the capture pipeline instead of chaining manual creates:
+When the user pastes a block of unstructured content (a meeting transcript, an email, a LinkedIn bio) or when several related things come up at once, send it through the **one capture door** — `synap_capture` (CLI: `synap capture`). Don't chain manual creates, and don't run a two-step "structure then commit" dance.
+
+The payload is a gradient in a single call:
 
 ```
-POST /api/hub/capture/structure   → returns proposals + relations
-POST /api/hub/capture/execute     → commits (after user confirms)
+{ "text": "…paste the raw content…" }              → the AI structures it into entities
+{ "entities": [ … ], "relations": [ … ] }          → you supply the graph directly (refs link them)
 ```
 
-The pipeline extracts multiple entities with their relations in one LLM call. Read **`capture.md`** for the full flow.
+Everything lands as ONE reviewable proposal (or auto-applies when every op is safe), and you get back one receipt — `status: "applied" | "proposed" | "rejected"`. `proposed` is success: surface the review link. There is no separate commit step. Read **`capture.md`** for the full flow, dedup signals, name-refs, and reject reasons.

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

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

package/skills/synap/processes.md

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

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."
@@ -51,3 +51,23 @@
    ```
 
 3. If the user said why ("interesting for the onboarding project"), also create a relation to that project — never drop the reason as a plain comment, turn it into a link.
+
+### Example 4 — "Write up a strategic plan for the Q3 launch"
+
+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=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": "note",
+     "title": "Q3 launch strategic plan",
+     "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: "relates_to" }`.
+4. Confirm: "Plan captured and linked to Q3 launch." No upload, no `file` entity, no separate `synap_create_document` call.