@synap-core/cli 1.11.0 → 1.13.0

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

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

package/skills/synap/mental-model.md

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

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

@@ -1,6 +1,6 @@
 ## Synap-first operating mode
 
-> **MCP clients** (Claude Desktop, Raycast, OpenClaw with MCP): use `synap_*` tool names — they wrap auth and governance automatically. **REST / HTTP clients**: use the endpoints below.
+> **MCP clients** (Claude Desktop, Raycast, any agent with MCP): use `synap_*` tool names — they wrap auth and governance automatically. **REST / HTTP clients**: use the endpoints below.
 
 These five rules override default assistant behavior when connected to a Synap pod:
 
@@ -33,7 +33,7 @@ Before answering any question about the user's projects, tasks, contacts, decisi
 When the user shares a decision, task, meeting outcome, contact, or any durable information: save it. Don't ask "should I save this?" for obviously important information. Use:
 
 - entities for structured data (tasks, people, projects, decisions)
-- `remember_fact` / `POST /api/hub/memory` for preferences, context, loose facts
+- `synap_remember_fact` for preferences, context, loose facts (not `POST /api/hub/memory` — that door needs an unrestricted key)
 - documents for long-form notes (meeting notes, research, writeups)
 
 **4. Link everything**  

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
@@ -34,10 +38,11 @@ POST   /api/hub/relations         body: { userId, sourceEntityId, targetEntityId
 GET    /api/hub/entities?q=…&profileSlug=task&workspaceId=…
 GET    /api/hub/entities/{id}/connections?userId=…
 POST   /api/hub/knowledge/ask     body: { query, workspaceId?, limit? }   ← ONE read door, routes across substrates
-POST   /api/hub/memory            body: { userId, fact }
 GET    /api/hub/memory?userId=…&query=…
 ```
 
+A fact about the user: MCP `synap_remember_fact` (a governed write). `POST /api/hub/memory` acts for the whole owner, so it needs an unrestricted key — a restricted agent key (the AI preset) is refused.
+
 **Profile schemas are runtime-discovered — never hardcoded:**
 
 ```bash

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: 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.
+4. **Work in a session.** `start_session` or resume (playbook `templateId`); 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 (`Q-<id8>`); chat answer → `relay_answer`, words verbatim; PR = outcome `pr-<repo>-<n>` (`ref.url`); `evaluate_session`, close open asks, `complete_session`.
+5. **Never guess a project**: pin only what the user names (`set_*_focus`).
+6. **`proposed` is success**: keep going, never retry.
+7. **Discover before inventing**: `list_profiles` / `list_capabilities`; **extend** (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`.

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 goal.
+
+| 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,110 @@
+## 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                  |
+| **Goal** (optional) | in one project (a _track_ in tools): direction, criteria, the workers it turns on; its judge closes it with a verdict | a list of stages                    |
+| **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 goal 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 goal or project **turns it on** for its scope; installs turn it on space-wide. Authoring: `processes`.
+
+### Goals (tracks)
+
+A goal is a _track_ in every tool and field name (`start_track`, `trackId`) — say "goal" to the person; a session's one-line `goal` is its **Aim**. A goal holds an owner, a direction, instructions, the workers it turns on, and what done means (criteria, or a number measured as transitions into `done`). It has no stages. A goal can stay open as long as it matters, or finish: a person closes it with a verdict once its criteria are met (`set_track_status` `completed` + `verdict`; dropped = `archived`, with a `verdict` saying why). Your close is a proposal; a closed goal comes back only as a new version. Pause it while nobody should work on it. Work in it = `start_session` + `trackId`. A thing may count for two goals. Solo users may never need one: workers can run space-wide. Legacy: `start_stage_session` and `add_track_stage` serve old goals started from a method; never `advance_track` without the user.
+
+**Keep the pod current (every agent, every session)** — three rules, so the next agent picks your step up from the pod alone:
+
+1. **Attach the session to its goal.** `orient`'s `startHere.openGoals` and the start reply's `offers.goals` name the open goals; start with `trackId`, or file an open session with `update_session` `trackId` (a proposal for an agent). No goal fits: say so in the room, never invent one silently.
+2. **Record your PR as an outcome** the moment you open it: `update_session` `outcomes: [{ key: "pr-<repo>-<n>", kind: "pull_request", label: "<repo>#<n>", ref: { url: "<PR url>" } }]`. With no `sessionId`, the pod files it on the one open session this conversation started, and refuses with the list when there are several.
+3. **Close when your outcomes are met.** When every outcome is met the `update_session` reply carries `nudges.readyToClose`: grade with `evaluate_session`, then `complete_session`. A merged PR is not always the end of the work: if more remains, declare it instead.
+
+**The rest of the goal protocol** (`set_track_participant`, `reopen_track`, `convert_to_goal`, `update_track`):
+
+- **A delegate's commitment.** The owner or judge asks someone (`add`, role `delegate`, with a `commitment`). The delegate answers only their own: `accept`, `counter` (text = what they would commit to instead), `decline`, or later `report_impossible` (text = why). A report is not the goal's verdict: the owner or judge `acknowledge`s it and re-plans. Never answer for a person; adding yourself as a delegate commits you.
+- **Claims and the judge.** A session that passes a goal criterion CLAIMS it. Only the judge (the owner unless one is named) accepts or sends back a claim, and only the judge closes the goal. Never accept your own claim.
+- **Reopen = a new version.** A closed or dropped goal never moves back: `reopen_track` starts a new version linked to it, with the same people asked again.
+- **Make it a goal.** A goal, objective or OKR entity becomes a goal once with `convert_to_goal` (its key results become measured criteria). Offer it when the person treats such an entity as live work; never convert one twice.
+- **The loop** is OFF by default. When it is on (`update_track` `loop: { on: true, perWeek? }`), the goal proposes its next session while a required criterion is unmet, and a person approves each one. Your switch-on is always a proposal: the person turns it on. If it stops after two failures on one criterion, ask the owner to re-plan; do not switch it on again yourself.
+
+### 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.