@synap-core/cli 1.8.0 → 1.11.0

package/skills/synap/SKILL.md

@@ -35,6 +35,131 @@ You are connected to a **Synap Data Pod** at `{SYNAP_POD_URL}`. All requests use
 
 Your job is to turn unstructured input into a **connected** knowledge graph. Isolated entities are anti-value. Every entity you create should link to at least one other entity.
 
+---
+
+## Reflexes — the two habits, every session
+
+> Canonical source — MCP instructions and other surfaces derive from this file.
+
+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):
+
+- **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.
+
+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
+
+---
+
+# Escalation ladder — discover → invent under proposal → crystallize after proof
+
+The always-on brief lives in `reflexes.md`. This file is the full HOW when you need more than the corner-of-your-head reminder.
+
+## Why it exists
+
+Agents fail in two ways: (1) dead-end ("I can't do that") when the substrate could express the need after discovery or a proposed meta change, and (2) silent invent (minting workspaces/profiles/views without checking what already exists). The ladder is the habit that prevents both. Soft teaching only — no hard tool filtering by tier.
+
+## Levels
+
+### L0 — Reflexes (always)
+
+Recall before non-trivial work (`synap_ask` / search). Capture durable learning after. Treat `"proposed"` as success-in-review, not an error. Orient once per session.
+
+### L1 — OPERATE on data
+
+Default mode: work with what already exists.
+
+- Capture free text, create/update entities, link, attach **known** facets
+- Start/update sessions when the work is a unit with a deliverable
+- Prefer existing profiles, views, capabilities, playbooks over inventing structure
+
+### L2 — DISCOVER before invent
+
+When the tool list or current schema doesn't express the need — **search before minting**:
+
+1. `list_profiles` / `list_views` / `list_capabilities({query})` in the active lenses
+2. `market.search({query, kind?})` over `capability` | `template` | `automation` | `cell`
+3. Load the relevant skill (`load_skill` / discover_tools) if the HOW is unclear
+
+Only if L2 returns empty for the real need do you climb to L3.
+
+### L3 — MUTATE the meta-model (proposal-gated)
+
+Extend the substrate so the need becomes expressible. Always governed — expect `"proposed"`.
+
+| Need               | Prefer               | Tool sketch                                                                             |
+| ------------------ | -------------------- | --------------------------------------------------------------------------------------- |
+| Role/hat missing   | Existing role attach | `define_role` only after `list_profiles` empty for that role                            |
+| Field missing      | Existing property    | `create_property_def`                                                                   |
+| Kind missing       | Closest parent kind  | `create_profile` (extend, don't fork)                                                   |
+| View missing       | Existing view        | `list_views` first, then `create_view` (recovery or proactive)                          |
+| Domain missing     | **Template**         | `market.search(kind:template)` → install/propose **before** freehand `create_workspace` |
+| Capability missing | Marketplace          | `market.install` (always proposes for agents)                                           |
+
+**Template-before-workspace (hard rule in teaching):** new operational domains start as marketplace templates when one fits. Freehand workspace creation is last resort after the four workspace-design conditions hold (`workspace-design.md`). Capture never invents a workspace — placement only routes into existing lenses.
+
+### L4 — CRYSTALLIZE after proof
+
+After a one-off has succeeded and is clearly repeatable:
+
+- Session that worked → `promote_session_to_playbook`
+- Cell that presents well for a type/slot → `promote_cell_to_renderer`
+- Repeatable process authored deliberately → `create_playbook`
+
+Never crystallize a speculative or failed one-off. One structural suggestion at a time; if speculative, ask first (`creative-loop.md`).
+
+## Decision gates (cheat sheet)
+
+```
+Can I do it with existing data/tools?
+  yes → L1
+  no  → L2 discover
+         found → use / install (propose) / enable
+         empty → L3 propose meta change (never silent invent)
+Did a one-off just succeed and will recur?
+  yes → offer L4 (question if speculative)
+  no  → leave it as a one-off
+```
+
+Blocked path: **never** invent silently; **never** stop at a dead-end error — climb L2→L3 and propose. Success path: one clear structural nudge, not a cascade of schema changes.
+
+---
+
 ## Mental model
 
 Synap is a typed knowledge graph. **Reading is one verb (`synap ask`) — it routes for you.** Writing is where you must pick the right lane: the destination is decided by the **KIND** of knowledge, not by whichever workspace happens to be active.
@@ -43,6 +168,8 @@ 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_.
+
 | 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)              |
@@ -51,17 +178,22 @@ Ask yourself: _who does this knowledge serve?_ **There is no private AI scratchp
 
 > **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.
 
+> **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"`):
+>
+> - **`stored`** → it's **live now**, recallable via `synap ask`.
+> - **`proposed`** → queued for the human's review, **like a git PR — not a failure, not a block.** Keep working: compose a whole graph of proposed changes in one session (reference the proposed entities, link them, add more) — they're staged together and go live when the human approves the batch. The only thing to remember: it's _under review_, so don't tell the user it's already applied. (Inferences about the user and writes to real workspaces are gated by design — expected, normal.)
+
 > **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.
 
 ### 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
 
@@ -74,12 +206,15 @@ Ask yourself: _who does this knowledge serve?_ **There is no private AI scratchp
 | `research`         | pod       | AI             | Investigation with sources + conclusion                                                                                                                                                                                                       |
 | `question`         | pod       | human + AI     | Open inquiry, closed when a decision answers it                                                                                                                                                                                               |
 
+---
+
 ## Quick reference — 90% of tasks in 30 lines
 
 ```bash
 # CLI (preferred — auth automatic, --json = clean output)
-synap orient --json                                    # discover userId + workspaces
-synap use <workspace-name-or-id>                       # set active workspace
+synap orient --json                                    # discover userId + workspaces + projects
+synap lens                                             # where am I? workspace + project + session (this Claude session)
+synap use <workspace-name-or-id>                       # focus a workspace (this session)
 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
@@ -101,7 +236,7 @@ or `recall` — `ask` is the door.)
 
 ```bash
 # REST (when no Bash access)
-POST   /api/hub/entities          body: { userId, workspaceId?, profileSlug, title, properties }
+POST   /api/hub/entities          body: { userId, workspaceId?, profileSlug, title, description?, properties?, content?, projectId?, facets?, source? }
 PATCH  /api/hub/entities/{id}     body: { userId, properties }   ← deep-merges, send only changed keys
 POST   /api/hub/documents         body: { userId, workspaceId?, title, content, entityId? }
 PATCH  /api/hub/documents/{id}    body: { userId, title?, content? }   ← full content replacement
@@ -121,11 +256,13 @@ synap discover --profiles --json # CLI: profiles only
 ```
 
 ```
-GET /api/hub/discover?userId={userId}&workspaceId={workspaceId}
-→ { profiles: [{ slug, displayName, scope, properties: [{ slug, type, options? }], createCommand }], commands: {...} }
+GET /api/hub/discover?userId={userId}&profileSlugs=task
+→ { profiles: [{ slug, displayName, scope, properties: [{ slug, type, required, defaultValue?, constraints?, targetProfileSlug? }], createCommand }], commands: {...} }
 ```
 
-Call this once at session start. The response includes every system profile and any custom workspace profiles the user has created, each with its full property schema. Use `createCommand` per profile as a copy-paste template. Do not rely on a static property list — it will drift.
+Call the summary tier once at session start, then load only the profile schemas
+needed for a write. Omit `workspaceId` for base/pod schema; add it only to see
+that workspace's overlays. Do not rely on a static property list — it will drift.
 
 **Load more detail on demand** (`GET /api/hub/skills/system?sections=<id>`):
 
@@ -139,13 +276,56 @@ Call this once at session start. The response includes every system profile and
 | `synap-ui:widget-catalog` | Available widget kinds and their configSchema          |
 | `synap-schema:SKILL`      | Creating custom profiles or property definitions       |
 
+---
+
+## Lenses — where you are vs. what you can reach
+
+You don't work "inside a workspace" the way you'd work inside a folder. You operate **across the whole pod**, and you **focus** through up to three composable lenses. **Lenses narrow; they never silo.** Omitting them is legal and common — that's pod-wide.
+
+| Lens          | What it is                                                                                                                                           | How to set (this session)                        |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| **Project**   | a **company or initiative** — the thing that ties the work together (Synap, a client, a launch). The lens you usually _organize by_.                 | `synap project use <id>` / `clear`               |
+| **Workspace** | an **operational domain** — where data lives (Foundation, CRM, Marketing, Finance, Builder). How the work is separated; the default home for writes. | `synap use <name-or-id>`                         |
+| **Session**   | the **work room** for the current goal (holds goal, deliverables, progress)                                                                          | `synap session start --goal "…"` / `attach <id>` |
+
+**How they compose — this is the whole model:**
+
+- A **project spans workspaces**: one company/initiative has a Foundation, a CRM, a Marketing, a Finance… each a different operational lens on the _same_ project.
+- A **workspace spans projects**: the Marketing workspace can hold work for several clients/projects at once.
+- **Membership is per-entity, filed on write.** An entity belongs to a project because it was created/filed **under the project lens** — not because its workspace is "in" the project (there is no workspace→project link). So **set the project lens before writing** work that belongs to an initiative, and it composes into that project from any workspace.
+- Compose either way, or both. That's why they're lenses, not folders: **workspaces exist so that development, finance, marketing, and operations don't pile into one undifferentiated place** — they're the separation that makes the work legible.
+
+- **The connection is pod-wide by design.** Your MCP/CLI link is _not_ welded to a workspace — reads default pod-wide, writes default to a sensible workspace. Pass a lens to narrow a single call; the lens is a focus, not a fence.
+- **These are per-Claude-session.** Two concurrent Claude sessions can sit on different projects/workspaces/sessions without colliding. `synap use` here rebinds **this** session only.
+- **Inspect anytime:** `synap lens` → the project + workspace + session this session resolves to.
+
+### The "am I in the right place?" reflex
+
+**Before the FIRST write of a new unit of work**, check your lens and orient if you're unsure:
+
+1. `synap lens` — am I scoped where this work belongs?
+2. If unsure what exists → `synap orient` — it returns a **light lens map**: the projects and the workspaces (names + ids), so you see the shape without a data dump. Never guess IDs. Drill into a workspace's profiles or a project's contents only when you actually need them.
+3. **Connect or create:** if the right project / workspace / session doesn't exist yet, create it. A **session is the normal per-task move**. Creating a **workspace (a new operational domain) is a deliberate, expected move as the work grows** — not something to avoid. A **project, though, is a COMMITMENT WITH GRAVITY**: search existing projects first (`synap orient`) and prefer **linking into an existing one** via `belongs_to_project`. Only create a new project for a real initiative that ties work together — never for a task, plan, repo, or theme (those are entities), and **never for the pod owner's own company** (the company _is_ the pod, not a project inside it). An agent-created project must cite **≥5 existing entities** as evidence or the backend rejects it, and near-duplicate names are rejected with the existing candidates.
+
+**Don't re-orient mid-flow.** Once you've oriented and you're in a run of related writes, keep going — re-check only when you **start a new piece of work** or switch domains. The reflex guards the _start_ of work, not every call.
+
+### Notice a missing domain — and offer it
+
+Because workspaces are how a company separates its operations, a project is sometimes **missing an operational domain it clearly needs**. If the conversation is squarely about an area — sales, content, finance, hiring, ops — and the active project has **no workspace for it**, say so **once, at the end, in one line**, and offer to set it up:
+
+> _"This project doesn't have a Marketing workspace yet — want me to spin one up and capture the essentials?"_
+
+If they say yes, provision that **one** domain and run its onboarding interview **with the project lens active** (so its entities file into the project) (see the `agent-os` skill — it handles both the whole-company setup and adding a single domain to an existing project). **Offer, don't auto-build.** One nudge per response, and only when the gap is real — never a checklist of everything the project "could" have. **If the user has already declined a domain (this session or before), drop it — don't re-offer.**
+
+---
+
 ## 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.
 
 These five rules override default assistant behavior when connected to a Synap pod:
 
-**1. Orient before acting**  
+**1. Orient before acting** _(and check your lens — see "am I in the right place?" above)_  
 Run `scripts/orient.sh` or call these endpoints at the start of every session — before searching, before creating, before answering any question about the user's data:
 
 ```
@@ -185,17 +365,21 @@ Facts about the user — preferences, team, working style, recurring context —
 
 Properties with `valueType: "entity_id"` are typed links to other entities — see **Linking** below.
 
+---
+
 ## CLI Data Operations (Bash tool)
 
 When Claude Code (or any agent with Bash access) is using this skill, prefer the `synap` CLI over raw HTTP calls — auth is automatic, output is clean JSON, no spinners in `--json` mode.
 
 **Session context — set once, never repeat:**
 
-The CLI reads the active pod and workspace from `~/.synap/config.json`. Set context once at the start of a session; all subsequent commands inherit it automatically. Do NOT pass `--pod-url`, `--api-key`, or `--workspace` on every command.
+The CLI inherits your pod + lens automatically; set them once and every later command picks them up. Do NOT pass `--pod-url`, `--api-key`, or `--workspace` on every command. Inside a Claude session, `synap use` / `synap project use` bind **this session's lens** (`~/.synap/lenses/<session_id>.json`) — so concurrent sessions stay independent; outside one, they set the global default (`~/.synap/config.json`).
 
 ```bash
 synap pods use <profile-name>          # switch active pod
-synap use <workspace-id>               # switch active workspace (captures land here — it IS the domain)
+synap use <workspace-id>               # focus a workspace (this session) — captures land here; it IS the domain
+synap project use <id>                 # add the project lens (composable)
+synap lens                             # inspect: workspace + project + session this session resolves to
 ```
 
 **Always orient first:**
@@ -260,6 +444,19 @@ synap ask "hono routing gotcha" --json
 `synap capture --type` writes a typed **`knowledge`** entity in the **active workspace** (the Work lane); `ek_type` (gotcha|lesson|decision|reference) discriminates the kind — **one store, type tags, not a residual dump**. It's workspace-scoped, so the active workspace supplies the domain — a Builder gotcha ≠ a marketing one (there is no `engineering_knowledge`). Add **`--global`** to write a pod-wide cross-cutting runbook to `knowledge_keys` instead. A formal **decision RECORD** (rationale, alternatives, superseded-by lifecycle) is a different artifact — use smart `synap capture "<free text>"` or `synap create entity --profile=decision`. Retrieve everything with `synap ask`.
 Use `capture` for anything worth remembering across sessions and projects.
 
+**Open (the one display door):**
+
+```bash
+synap open <id>                               # resolves type automatically, opens in browser
+synap open entity <id>                        # open entity detail
+synap open proposal <id>                      # open proposal review
+synap open view <id>                          # open a view
+synap open cell <typeKey>                     # open a registered cell by typeKey
+synap open document <id>                      # open a document
+```
+
+The bare-ID form calls `GET /api/hub/resolve/:id` to determine the type before dispatching. Use this when you don't know what type a UUID is — `synap open <id>` always works.
+
 **Write:**
 
 ```bash
@@ -278,6 +475,8 @@ synap set entity <id> --props='{"status":"done"}' --json
 
 ---
 
+---
+
 ## Scope — default pod-wide
 
 **Default: pod-wide.** 13 of 17 system profiles (`note`, `task`, `project`, `event`, `person`, `contact`, `company`, `bookmark`, `article`, `website`, `decision`, `question`, `research`) are pod-scoped — entities you create show up in _every_ workspace the user owns. The backend handles this automatically when the profile is pod-scoped: you don't need to pass `workspaceId`.
@@ -292,6 +491,8 @@ synap set entity <id> --props='{"status":"done"}' --json
 
 When you do scope to a workspace, pass `workspaceId` in the create body — the backend respects it. Never pass `workspaceId: null` explicitly to force pod-wide; the profile's `entityScope` decides.
 
+---
+
 ## The work flow — question → research → decision → action
 
 AI-assisted work has a shape. When the user is actually _thinking about something_, it flows through four structural nodes. Each is a first-class entity. None of these are optional "nice-to-have" labels — they're the graph that makes the work _durable_ and transferrable between AIs.
@@ -400,11 +601,13 @@ User: _"I'm trying to figure out whether we should build our own orchestrator or
 
 Don't interrupt the conversation to ask "should I log this as a question?" — just do it and add a one-line trailer at the end of your response:
 
-> (Logged as question on Project Eve. Review: https://studio.synap.live/proposals/…)
+> (Logged as question on Project Eve. Review: synap://open/proposal/…)
 
 If the creation was auto-approved (entity.create is on the whitelist), there's no proposal; just show a link to the entity:
 
-> (Logged as question → https://studio.synap.live/entities/ent_question_1)
+> (Logged as question → synap://open/entity/ent_question_1)
+
+---
 
 ## Linking — the core principle
 
@@ -442,8 +645,12 @@ POST /api/hub/relations
 }
 ```
 
+**Link entities you reference back to the thread.** When your reply cites an entity or document, connect it to the current conversation with `link_entity_to_thread` / `link_document_to_thread` — one line of why ("linking this because it's directly relevant to what you're building"). It should feel like keeping notes, not running a pipeline.
+
 For auto-sync mapping, conventional relation types, and edge cases, read **`linking.md`**.
 
+---
+
 ## Writing — governance in one paragraph
 
 Every write returns a `status` field:
@@ -503,27 +710,176 @@ Rules:
 
 Example response to the user:
 
-> I queued **Delete task "Q2 plan review"** for your review. Destructive actions need your approval. Open it: https://studio.synap.live/proposals/prp_abc
+> I queued **Delete task "Q2 plan review"** for your review. Destructive actions need your approval. Open it: synap://open/proposal/prp_abc
 
 Auto-approved by default (for agent API keys): `entity.create`, `entity.update`, `document.create`, `relation.create`, `view.create`, `profile.create`, `property_def.create`, `channel.create`, `memory.*`, all reads. Destructive actions (`delete`, `archive`, `purge`) always propose in agent-owned workspaces.
 
 For the full whitelist, agent-user semantics, and workspace overrides, read **`governance.md`**.
 
+---
+
+# Capabilities — discover, run, and the when-blocked reflex
+
+Capabilities are the verbs a workspace's connected services and applied
+templates unlock — `gmail_send`, `gmail_search`, `calendar_create`,
+`drive_search`, and so on. They are the bridge between "I can talk about it"
+and "I can actually do it."
+
+## Discover: `list_capabilities`
+
+MCP: `synap_list_capabilities`. IS: `list_capabilities`. Takes
+`{ query, kind?, limit? }` (plus `workspaceId`).
+
+**Search first — never dump-and-eyeball.** A workspace can carry 100+
+capability entries; call with a `query` describing the action you're after
+("send email", "search calendar") and read the ranked, compact results. Don't
+fetch the unfiltered list and scan it yourself.
+
+Each entry carries:
+
+- `name` (the `verbId` you pass to `run_capability`), `label`, backing tool
+- `paramsSchema` — the shape `parameters` must satisfy; check it before calling
+- `enabled` — `true` means it will run right now. `false`/DRAFT means it's
+  installed but the user hasn't approved it yet (Settings → Capabilities)
+
+## Run: `run_capability`
+
+MCP: `synap_run_capability`. IS: `run_capability`. Pass `verbId` (or
+`skillId`) + `parameters` + `workspaceId`.
+
+```json
+{
+  "verbId": "gmail_send",
+  "parameters": { "to": "…", "subject": "…", "body": "…" },
+  "workspaceId": "{workspaceId}"
+}
+```
+
+Check `paramsSchema` from discovery before calling — a missing required
+parameter is refused, not guessed.
+
+**`proposed` is a normal outcome, not a failure.** A capability run can land
+as a proposal exactly like any other governed write (see `governance.md`):
+tell the user why, share the `reviewUrl`, and don't retry.
+
+**Provider results can be 200-with-error-body.** A successful HTTP call to
+Gmail/Calendar/Drive can still carry `result.success: false` +
+`result.error` — an auth expiry, a bad recipient, a quota limit. **Always
+check `result.success`/`result.error` in the response before telling the
+user the action worked.** A 200 status is not proof of success here.
+
+## The when-blocked reflex
+
+When you cannot do something the user asked for — no matching tool, a
+"not found" verb, "no connection", "not enabled" — do not fabricate a result
+and do not silently give up. Follow this order:
+
+1. **Search first.** `list_capabilities({ query })` for what the user actually
+   wants. Capabilities are added over time; don't assume today's tool list is
+   the ceiling.
+2. **Found but blocked?** If the verb exists but is DRAFT (not enabled) or its
+   backing connection is missing, tell the user exactly what to do and where:
+   "This needs Gmail connected — enable it in Settings → Capabilities" (or
+   the equivalent connect deep-link the error hands you). Don't attempt the
+   run again until they've acted.
+3. **Still nothing? Search the marketplace.** `market.search({query, kind?})`
+   over what could be _installed_ (capabilities, automations, workspace
+   templates, cells) — a cache read, not a live fetch, so it's always fast.
+4. **Found in the marketplace?** `market.install({slug, kind, version?})`. As
+   an agent this ALWAYS lands as a reviewable proposal — never auto-installs,
+   even with a grant on the verb itself. Share the `reviewUrl`; don't retry.
+5. **Truly nothing, anywhere?** That is escalation-ladder **L2 empty → L3**:
+   say precisely what's missing (the action, not "I can't"), offer to capture
+   the gap, and if the need is structural (new capability package, template,
+   automation), propose via marketplace/install or meta tools — never
+   dead-end and never fabricate a result.
+
+<!-- brief:start -->
+
+When blocked (ladder L2→L3): (1) `list_capabilities({query})` first — never
+assume today's list is the ceiling. (2) Found but DRAFT/no connection → tell
+the user exactly what to enable/connect and where; don't retry until they've
+acted. (3) Still nothing → `market.search({query, kind?})`; `market.install`
+on a hit always proposes for an agent. (4) Truly nothing → say precisely
+what's missing, offer to capture the gap or propose L3 structure — never
+fabricate, never silent give-up. Provider 200-with-error-body: always check
+`result.success`/`result.error` before claiming success.
+
+<!-- brief:end -->
+
+## Errors — what they mean, what to do next
+
+| You see roughly...                          | Meaning                                                                   | Next step                                                                       |
+| ------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| verb/skill "not found" in this workspace    | No capability by that name is registered here                             | `list_capabilities({query})`; if nothing, tell the user what's missing          |
+| capability "not approved" / DRAFT           | It exists but the user hasn't enabled it yet                              | Tell the user to enable it (Settings → Capabilities); don't retry               |
+| a required parameter is missing             | Your `parameters` didn't satisfy the verb's `paramsSchema`                | Re-check `paramsSchema` from discovery, fill the gap, retry once                |
+| no connection / credential for this service | The verb needs a connected account (Gmail, Calendar, …) that isn't set up | Hand the user the connect link; don't retry until connected                     |
+| `status: "proposed"`                        | Normal governed outcome — this run needs human approval                   | Share `summary` + `reviewUrl`; don't retry (see `governance.md`)                |
+| `status: "denied"`                          | Workspace policy blocked it outright                                      | Explain the reason; don't retry                                                 |
+| provider result with `success: false`       | The call reached the provider but the provider itself rejected it         | Read `result.error`; tell the user what actually happened, don't report success |
+
+## What NOT to do
+
+- Don't dump the full unfiltered capability list and eyeball it — search.
+- Don't retry a `proposed` or `denied` result as if it were a transient error.
+- Don't tell the user an action "worked" without checking `result.success`.
+- Don't invent a capability, verb, or connection that discovery didn't return.
+
+---
+
 ## Core writes
 
-### Create an entity (always with links)
+**Two write doors, one gradient.** `create_entity` is for exactly ONE
+fully-structured, typed entity you already have. For anything unstructured,
+several entities, or a graph — or **when in doubt** — use the capture door
+(`synap_capture`, see `capture.md`): precision comes from sending more structure
+in the SAME call, never from picking a different tool or a second commit step.
+
+### Create an entity (one exact typed entity)
+
+Before this call, use `/discover?userId=…&profileSlugs=<kind>` to read the
+real fields, required/default values, constraints and reference targets. Omit
+`workspaceId` for the pod/base schema and normal profile placement; pass it
+only when the user or routing decision explicitly selected that workspace.
 
 ```json
 POST /api/hub/entities
 {
   "userId": "{userId}",
-  "workspaceId": "{workspaceId}",
-  "profileSlug": "task",          // from /profiles — never guess
+  "profileSlug": "task",          // from /discover — never guess
   "title": "Weekly team sync",
-  "properties": { "status": "todo", "projectId": "ent_..." }
+  "description": "Recurring planning sync",
+  "properties": { "status": "todo", "dueDate": "2026-07-21" },
+  "content": "# Agenda\n- Priorities\n- Risks",
+  "projectId": "{existingProjectId}",
+  "source": "agent"
 }
 ```
 
+The response has legacy `status`/`id` fields plus `writeReceipt`:
+`pending`/`proposed` means a proposal exists and no entity is live yet;
+`applied` means the reported direct write completed; `partial` means a follow-up
+(for example a facet) failed after the entity applied. **A `proposed`/`pending`
+receipt is a governed success, not an error** — surface its `reviewUrl`, never
+claim completion, and only enrich again when the receipt identifies a real
+missing fact.
+
+For several entities, creation-time roles/facets, or relations that need one
+review, send the whole graph through the capture door (`synap_capture` with
+`entities[]` + `relations[]`) instead of sequencing independent creates. It is
+ONE governed call: policy auto-applies when every op is safe, otherwise the
+whole graph is proposed (atomic). There is no separate commit step.
+
+**Name-refs, not UUIDs.** Reference an existing project by name — the server
+resolves it against the caller's own projects (exact match files there; no match
+proposes, never mis-files). Never ask the user for a UUID.
+
+**Dedup is advisory across kinds.** Strong signals (`email`/`phone`/`website` —
+not a bare `url`) dedup within a kind; a same-title hit in a _different_ kind
+comes back as an advisory candidate, never an auto-merge. "No exact match" is not
+"safe to create" when advisory candidates are returned — review them first.
+
 ### Update an entity
 
 ```json
@@ -533,6 +889,41 @@ PATCH /api/hub/entities/{entityId}
 
 **Properties are deep-merged — send only the keys you want to change.** An update with `{ "status": "done" }` leaves all other properties untouched. You never need to re-send the full properties object.
 
+### Authored text is content, not a `file`
+
+Something **you** author — a pitch deck, a strategic plan, a note body — is
+**never** a `file`- or `document`-kind entity. Create it as the right CONTENT
+kind (`note`, `knowledge`, or a fitting domain kind) with `content` set to the
+Markdown body; Synap **auto-materializes** that `content` into a real
+versioned document behind the scenes (`entities WHERE documentId = ?`) — no
+upload step needed. `file` is reserved for real uploaded bytes you actually
+have (the upload door / `synap upload`) — an agent has no filesystem, so it
+rarely touches `file` at all. Reach for `synap_create_document` /
+`POST /api/hub/documents` directly only for a standalone rich document that
+isn't itself a title-worthy entity (see below) — never as a substitute for an
+entity's `content`.
+
+### "I want to add a real FILE" — the decision tree
+
+You CAN store content you **hold** — you send it inline. Pick by what you have:
+
+| You have…                                                                                   | Do this                                                                                         | Result                                                               |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Content in hand** — a report/CSV/image/PDF/etc. you generated or received (text or bytes) | **`synap_store_file`** (`content` for text, `contentBase64` for binary) + `mimeType`/`filename` | a `file` entity, content stored **as-is, never read** (≤10MB inline) |
+| Text you're **authoring as a note/idea** (not "a file") — a plan, a thought                 | `synap_create_entity` with `content` (a content kind)                                           | body auto-becomes a document — NOT a `file`                          |
+| Only a **URL/link** (no bytes) — a Google Doc, a PDF url, an article                        | `synap_create_document` with **`url`**, or attach via `entityId`                                | an external **reference** document (no bytes)                        |
+| A **large file on a local disk** you don't hold in context                                  | the CLI `synap upload <path>` (streams it) — an agent can't send bytes it doesn't have          | a `file` entity backed by stored bytes                               |
+| Only a file's **name**, nothing else                                                        | you **cannot** invent it — ask the human/client to provide the content or a link                | —                                                                    |
+
+**Store ≠ analyze.** `synap_store_file` / `synap_create_document` store content
+**deterministically — the file is NEVER read by an LLM.** Only fetch a document
+and reason over it when the user explicitly says "read/analyze this file."
+
+**Do NOT over-structure a file request.** "Store this file" / "how do I add this
+file" is ONE intent → at most one stored file (plus, only if asked, a linking
+relation). Never inflate it into a task + note + placeholder-file scaffold, and
+never dump the request text into a note and call it done.
+
 ### Create a document (attach to an entity)
 
 ```json
@@ -590,21 +981,25 @@ Content is a **full replacement**, not a patch. Fetch the current content first
 
 The reverse lookup is `entities WHERE documentId = ?`. Always attach the document to a meaningful entity (the meeting event, the project, the person) — a floating document is another orphan.
 
-### Store a fact (memory) — use sparingly
+### Remember a fact about the user — use sparingly
 
-```json
-POST /api/hub/memory
-{ "userId": "{userId}", "fact": "User prefers async communication over meetings" }
-```
+A fact _about the user_ goes through `remember_fact` (CLI: `synap capture --type
+observation`). It writes a governed `user_observation` — not an ungoverned
+throwaway row: a fact the user explicitly stated auto-approves; a fact you
+inferred returns `proposed` (normal — surface the review link). Because it's a
+real entity it's addressable, linkable and revertible.
 
-Always auto-approved. **Memory is for loose, unstructured, hard-to-title facts only.** The seductive thing about memory is it has zero friction — no dedup, no linking, no proposals. That makes it easy to misuse.
+**Use it only for loose, unstructured, hard-to-title facts about the user** — a
+stated preference, a throwaway detail. Everything with a title-worthy noun or
+something to link to is an ENTITY through the capture door, not an observation.
 
-**The test:** if the user later asked "show me all X," can memory answer? Memory can only keyword-match — it has no structure. So:
+**The test:** if the user later asked "show me all X," could a loose observation
+answer? It can only keyword-match — it has no structure. So:
 
 | Input                                                   | Use                                                             |
 | ------------------------------------------------------- | --------------------------------------------------------------- |
-| "User prefers async communication"                      | memory — it's a preference                                      |
-| "Garage code is 4321"                                   | memory — throwaway fact                                         |
+| "User prefers async communication"                      | observation — it's a preference                                 |
+| "Garage code is 4321"                                   | observation — throwaway fact                                    |
 | "Should we use LangGraph or CrewAI for Eve?"            | **entity `question`** — substantive inquiry, start of flow      |
 | "Here's what I found comparing LangGraph and CrewAI…"   | **entity `research`** — investigation with sources + conclusion |
 | "We decided to use LangGraph over OpenClaude's native…" | **entity `decision`** — has title, rationale, project           |
@@ -614,7 +1009,7 @@ Always auto-approved. **Memory is for loose, unstructured, hard-to-title facts o
 | "Action item from meeting: ship MVP by Friday"          | **entity `task`** linked to the `event` (meeting)               |
 | "Agreed with Sarah: we'll split backend & frontend"     | **entity `decision`** linked to Sarah + the project             |
 
-**Rule of thumb:** if it has a title-worthy noun OR context to link to (a project, a person, a meeting) OR a lifecycle (status/supersession) — it's an entity, not memory. Memory is the fallback, not the default.
+**Rule of thumb:** if it has a title-worthy noun OR context to link to (a project, a person, a meeting) OR a lifecycle (status/supersession) — it's an entity through the capture door, not an observation. A user observation is the fallback, not the default.
 
 **For decisions specifically** — use the `decision` system profile:
 
@@ -647,6 +1042,244 @@ POST /api/hub/threads/{threadId}/messages
        { "userId": "{userId}", "role": "user", "content": "…" }
 ```
 
+---
+
+## Document embeds — live entities/views/cells inside markdown
+
+Documents (`type: "markdown"`) can embed **live, rendering** Synap objects inline, not
+just links. The browser's markdown engine parses a small set of remark **container
+directives** and swaps them for real components — an entity card, a view, or a cell
+— wherever they appear in the prose.
+
+**This is a DOCUMENTS-only mechanism.** It is unrelated to the `[[kind:id|label]]`
+inline chips described in `inline-patterns.md` — those render **only** in Companion
+chat replies. Never put a `:::synap-*` directive in a chat reply, and never put a
+`[[…]]` chip in a document's `content`. Different surface, different grammar.
+
+### Syntax
+
+<!-- brief:start -->
+
+A container directive: three colons, the directive name, `{attrs}` on the opening
+line, three colons alone on the closing line.
+
+```
+:::synap-entity{id="ent_abc123"}
+:::
+```
+
+| Directive      | Required attrs                                | Optional attrs | Renders                                           |
+| -------------- | --------------------------------------------- | -------------- | ------------------------------------------------- |
+| `synap-entity` | `id` (entity UUID)                            | —              | Compact entity card (`__entity-block` cell)       |
+| `synap-view`   | `viewId` (view UUID)                          | —              | Embedded, read-only view (`__embedded-view` cell) |
+| `synap-cell`   | `instanceId` **OR** (`cellKey` + `cellProps`) | —              | A persisted cell instance, or an inline cell ref  |
+
+Only real IDs from prior tool results — never invent one. This is a
+DOCUMENTS-only grammar: never use it in a chat reply, and never use a
+`[[kind:id|label]]` chip inside a document's `content`.
+
+<!-- brief:end -->
+
+For `synap-cell`: an explicit `instanceId` always wins if present — it renders a
+persisted cell instance from `/api/hub/cells`. Otherwise the pair `cellKey` +
+`cellProps` builds an inline ref (`cellRefFromLegacy`). `cellProps` is a JSON string,
+e.g. `cellProps='{"profileSlug":"task"}'`.
+
+When you write a document's `content` directly (via `synap_create_document` /
+`POST /api/hub/documents`), you're writing raw markdown text — quote `cellProps`'
+JSON with single quotes (`cellProps='{"profileSlug":"task"}'`) so the inner `"`
+characters don't collide with the directive's own `key="value"` quoting; the
+markdown renderer (remark-directive) parses this directly, no escaping needed.
+
+One caveat: if a human later opens the document in the rich-text editor, its
+Tiptap round-trip serializer re-emits every directive as `key="value"` and
+**drops any attribute value containing `"` or `}`** (it would otherwise corrupt
+the directive) — so an inline `cellProps` blob can be silently lost on the next
+editor save. For a cell you expect to survive editing, create it first
+(`synap_create_cell` / `POST /api/hub/cells`) and embed it by `instanceId`
+instead of inlining `cellProps`.
+
+### Rules
+
+- **Only real IDs from prior tool results.** Never invent an entity/view/instance
+  ID. Create or look it up first (`synap_create_entity`, `synap_get_entities`,
+  `synap_create_view`, `synap_create_cell`), then embed the ID you got back.
+- **Embeds are for DOCUMENTS.** The `[[…]]` inline chips are for Companion chat
+  replies. Do not mix the two grammars across surfaces.
+- **Embed vs. link:** embed when the reader benefits from seeing the live
+  object in place — a stat card inside a report, the linked meeting entity inside
+  meeting notes, a pipeline view inside a status update. Link (`entities WHERE
+documentId = ?` attachment, or a plain reference to the ID) when you just need
+  traceability and the reader doesn't need to see it rendered inline — most
+  documents should still be _attached_ to one entity (see `writes.md`) regardless
+  of whether they also embed others inline.
+- A directive with a missing/invalid required attribute renders a visible error
+  block in the browser (`Error: View ID is required` / `Error: Cell type is
+required`) — always double-check the ID before writing the directive.
+
+### Worked example 1 — meeting notes embedding the meeting entity
+
+```json
+POST /api/hub/documents
+{
+  "userId": "{userId}",
+  "workspaceId": "{workspaceId}",
+  "title": "Meeting notes — 2026-07-12",
+  "type": "markdown",
+  "entityId": "ent_event_kickoff",
+  "content": "# Kickoff meeting\n\n:::synap-entity{id=\"ent_event_kickoff\"}\n:::\n\n## Decisions\n- Ship the pilot by August 1\n\n## Action items\n- [ ] Draft the rollout plan"
+}
+```
+
+The event entity renders as a live card at the top of the notes — attendees,
+time, status stay current even if the entity changes later.
+
+### Worked example 2 — status report embedding a pipeline view
+
+```json
+POST /api/hub/documents
+{
+  "userId": "{userId}",
+  "workspaceId": "{workspaceId}",
+  "title": "Weekly deals update",
+  "type": "markdown",
+  "entityId": "ent_project_eve",
+  "content": "# Weekly update\n\nThree deals moved to negotiating this week.\n\n:::synap-view{viewId=\"view_deals_pipeline\"}\n:::\n\nSee the board above for the live state."
+}
+```
+
+### Worked example 3 — report embedding an inline stat cell
+
+```json
+POST /api/hub/documents
+{
+  "userId": "{userId}",
+  "workspaceId": "{workspaceId}",
+  "title": "Q2 task summary",
+  "type": "markdown",
+  "entityId": "ent_project_eve",
+  "content": "# Q2 summary\n\n:::synap-cell{cellKey=\"stat-card\" cellProps='{\"profileSlug\":\"task\"}'}\n:::\n\nOpen tasks are trending down."
+}
+```
+
+Note the mixed quoting: the directive's own attribute values use double quotes
+(`cellKey="stat-card"`), so the outer `cellProps` value uses single quotes to hold
+its JSON — the JSON itself must not contain any `"` once flattened into the
+attribute string, or the serializer will drop it. When in doubt, prefer a
+persisted `instanceId` over inline `cellProps`.
+
+---
+
+## The Creative Loop — do once, then crystallize to reusable config
+
+The core rhythm of real work in Synap: **do the thing once by hand, then crystallize what worked into reusable configuration.** You author; the user curates. Every crystallization is governed — a `proposed` result is the normal, successful outcome, never an error.
+
+The loop has three moves that compound. Each takes a one-off act and, if it's worth repeating, turns it into standing structure:
+
+| Do-once (author)                        | → Crystallize (curate)              | Tool                          |
+| --------------------------------------- | ----------------------------------- | ----------------------------- |
+| Work a multi-step goal in a **session** | → a **playbook** (the process)      | `promote_session_to_playbook` |
+| Show a result in a **cell**             | → a **renderer** for an entity type | `promote_cell_to_renderer`    |
+
+### 1. Open a session for real work
+
+When the task is a unit of work with a deliverable — research, a build, an investigation, a sprint — and there's no active session, **`start_session`** with a clear `goal` and `expectedOutputs`. The session is the spine that accrues results (see the focus-sessions skill). Don't open one for a one-shot lookup or a casual reply.
+
+### 2. Create a cell to REPORT — don't dump data into chat
+
+When you have something to _show_ the user — a list of leads, a summary, a comparison, a chart — author a **cell** with `create_cell` instead of pasting rows into the message.
+
+- **Declare the data intent in `rendererSource`; do NOT pre-fetch.** Cells use a dynamic data-binding SDK: you describe what the cell needs (e.g. "the open leads in this workspace"), and the runtime binds the live data at render time. Never fetch rows yourself and inline them — that snapshot goes stale and defeats the cell.
+- Keep one cell to one job. A good, focused cell is the raw material for the next move.
+
+### 3. Promote a good cell to a renderer — recurring presentation
+
+When a cell is a _good, recurring way to present a whole entity type or step_ — e.g. every `bookmark`'s detail view, every `lead`'s list row — promote it with `promote_cell_to_renderer`:
+
+- Pick the `profileSlug` (the entity type), the `slot` (`list` | `detail` | `dashboard`), and the `cellKey` from `create_cell`.
+- This is **governed**: for you it returns `{ status: "proposed", proposalId }`. That is the point — you author the renderer, the user reviews and curates it before it becomes every entity's view. Surface the proposal plainly ("I've proposed this as the detail view for bookmarks — review it when you like"), don't treat it as a failure.
+- Use `scope: "pod"` only when the presentation should apply in every workspace; default to workspace scope.
+
+### 4. Promote a finished session to a playbook — recurring process
+
+When the session is done **and the work was a repeatable process** (not a one-off), promote it with `promote_session_to_playbook({ sessionId })`. This captures the goal, tasks, expected outputs, and steps as a reusable session template — so next time the process starts pre-built instead of from scratch.
+
+- Do this at the _end_, once the promised outputs are produced and verified.
+- Judge repeatability honestly: a bespoke, never-again investigation is not a playbook. A "weekly competitor scan" or "new-client onboarding" is.
+- Governed like the others — `promoted` (applied) or `proposed` (awaiting review) are both normal.
+
+### The symmetry
+
+Sessions and cells are the two things you _do_; playbooks and renderers are the two things you _keep_. The instinct to build: **first do it once concretely, watch it work, then offer to crystallize it** — and let the user decide what becomes standing config. Never crystallize speculatively before the one-off has proven itself.
+
+This is escalation ladder **L4**: crystallize only after proof. Blocked/missing structure climbs L2→L3 first (`escalation-ladder.md`); L4 is the success path, not a substitute for discovery.
+
+---
+
+## Garden the graph — writes tell you their impact (the circling of action)
+
+A write is no longer blind. When you create or update an entity, the response tells you what it did to the graph — **READ it and act**, so the graph stays connected instead of accumulating isolated, duplicated nodes.
+
+**On create**, the response carries a `resolution` block:
+
+- `existingSameProfile` — an entity with this exact name ALREADY exists as the same profile. Prefer **updating** it (`synap set entity <id>` · `PATCH /api/hub/entities/:id` · `update_entity`) over creating a duplicate.
+- `autoConnected` — same-name entities of a DIFFERENT profile are facets of one real thing, and the system has already woven them together with a `same_subject` relation. Acknowledge it; add a more specific relation if the real relationship is narrower than "same subject".
+- `suggestions` — entities worth linking. Create the relations that genuinely apply (`synap create relation` · `POST /api/hub/relations` · `create_relation`).
+
+**On update**, the response carries an `impact` block — the entity's immediate relation neighbors. Read it and resolve secondary effects: supersede a now-stale entity, update its dependents, re-link.
+
+**The circling of action** for any structural write (updating the vision, the architecture, a decision record, a codebase map):
+
+1. **Write** — the response shows collisions + connections; don't ignore it.
+2. **If it already exists** (`existingSameProfile`) → update it, don't duplicate.
+3. **The same-name facets are auto-woven** (`autoConnected`) → extend the links where the relationship is more specific than `same_subject`.
+4. **Act on `suggestions`** → link what genuinely relates.
+5. **On update** → resolve the `impact` neighbors (supersede / update / re-link).
+
+The principle: **more data is better when it is structured.** The graph now helps you keep it structured — never leave an entity isolated, never blindly overwrite. (Matching is exact-name today; it will deepen over time — so still link deliberately when you know two things relate but their names differ.)
+
+---
+
+## Decide the next action — advance the goal, don't just answer
+
+You are an adjunct, not a reply box. A good assistant doesn't wait to be told the next step — after you answer, you ask **what is the highest-leverage next move toward the goal, and should I make it now?** — then you make it. Proactivity is this habit, run every turn; it is not a tone.
+
+### The session is the spine of real work
+
+A **focus session** is a goal-bound work room. It holds the goal, the promised outputs (deliverables), the tools/skills in play, and what's been produced so far — so it answers both _"where am I"_ and _"what am I working toward"_. Operate it with the triplet:
+
+| Move                      | CLI                                      | REST                                        | IS tool          |
+| ------------------------- | ---------------------------------------- | ------------------------------------------- | ---------------- |
+| open a session            | `synap session start --goal "…"`         | `POST /api/hub/focus-sessions`              | `start_session`  |
+| read it                   | `synap session get <id>`                 | `GET /api/hub/focus-sessions/:id`           | `get_session`    |
+| see active ones           | `synap session list`                     | `GET /api/hub/focus-sessions?status=active` | `list_sessions`  |
+| record progress / outputs | `synap session update <id> --progress N` | `PATCH /api/hub/focus-sessions/:id`         | `update_session` |
+
+- If you're already in a session (or a `## Active Session` block is in your context) → that's your frame. Read its goal and the gap between _promised outputs_ and _what's produced_, and pursue that gap.
+- If the user's intent is a **unit of work with a deliverable** (research, a plan, a build, an investigation) and no session is active → **open one** with a clear goal + expected outputs, so the work has a spine that accrues results. Don't open a session for a one-shot lookup or a casual reply.
+
+### Decide ONE move, then make it
+
+Pick the single highest-leverage next action toward the goal — not a checklist: answer · capture/structure what was said · create a task · link entities · advance or produce a promised deliverable · update the session's progress · propose an automation for a repeating pattern.
+
+**Spin off a branch / sub-agent** when there's side-work that advances the goal but would **bloat the main channel** — e.g. "go find best practices for X", a deep research dive, a parallel investigation. Keep the main thread clean and let the branch do the heavy lifting and report back. Judge by complexity + channel hygiene, not by a fixed category.
+
+**Land it through governance — act, don't just suggest.** When the move is clear, _make_ it: create the task, the research entity, the branch, the link, the session update. Every write passes through governance — it either auto-applies (safe, whitelisted writes) or becomes a one-click review. Either way, making the move is the safe path. Don't downgrade a clear next action into "you might want to…". Say _why_ in one line, then act.
+
+**Reflect back into the session.** When work lands, update the session's progress and link what you produced — so the next turn reads a richer state and the loop compounds.
+
+**Know when to stop.** When the promised outputs are produced and verified, the goal is done — say so and stop. Surface a _real_ next move when there is one; stay quiet when there isn't. Never manufacture busywork to seem active.
+
+### The nudge vs. propose line
+
+A concrete next action toward a _known_ goal → propose it (gated). A _speculative_ restructuring the user hasn't asked for (a new profile, a new view, splitting a workspace) → raise it as a question and let them decide.
+
+### If you are a coding / terminal agent working _in_ a repo
+
+Same habit, one addition: before you finish a piece of work, ask **"what's the next action, and what belongs in Synap?"** A decision you made, a gotcha you hit, a follow-up the work revealed, a task it spun off — capture it (`synap capture` / `synap note` / a task) and, when the work is a real unit, track it in a session. The point of the second brain is that the _next_ agent (or you, tomorrow) starts from what this turn learned instead of re-deriving it.
+
+---
+
 ## Reading
 
 **Start with `ask` — the one routed read door.** It classifies the question and
@@ -687,18 +1320,26 @@ GET /api/hub/graph/traverse?entityId={id}&maxDepth=2&workspaceId={id}
 GET /api/hub/memory?userId={userId}&query={keywords}
 ```
 
+**Never claim absence without searching this turn.** Asked "what do you know about X", "is there an X", "anything on X" — you MUST `ask`/`search_unified` for X first (and `list_entities` on the matching profile for "how many / list all X"). Only after a search returns nothing may you say "I didn't find anything matching X" — never assert "X does not exist." A just-created entity is searchable within seconds, so a confident "nothing exists" without a search this turn is a hard failure.
+
 No SQL joins. The graph is the join.
 
+---
+
 ## 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.
+
+---
 
 ## Worked examples
 
@@ -754,6 +1395,29 @@ The pipeline extracts multiple entities with their relations in one LLM call. Re
 
 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=knowledge&workspaceId=…` → none
+2. Create a CONTENT-kind entity carrying the plan as `content` (the doc auto-materializes):
+
+   ```json
+   POST /api/hub/entities
+   { "userId": "{userId}", "workspaceId": "{wsId}",
+     "profileSlug": "knowledge",
+     "title": "Q3 launch strategic plan",
+     "properties": { "ek_type": "reference" },
+     "content": "# Q3 Launch Plan\n\n## Goals\n…\n\n## Timeline\n…"
+   }
+   ```
+
+3. Link it to the relevant project: `POST /api/hub/relations` `{ sourceEntityId: "ent_new_plan", targetEntityId: "ent_project_q3", type: "related_to" }`.
+4. Confirm: "Plan captured and linked to Q3 launch." No upload, no `file` entity, no separate `synap_create_document` call.
+
+---
+
 ## CRM Workspaces — 4-Entity Model
 
 Some workspaces use a CRM data structure with four entities: `person` and `company` (identity records), `deal` (pipeline record), and `client` (post-win relationship marker). Understand this pattern when proposing lead captures, deal updates, or campaign membership.
@@ -860,7 +1524,21 @@ POST /api/hub/relations
 
 This model enables renewals (new deal linking to existing client), multi-stakeholder deals (multiple `linked_to_deal` relations per deal), campaigns with mixed entity types (persons + companies + deals as members), and clean churn tracking. It matches Synap's core pattern: entities + relations = graph.
 
-## Common mistakes
+## Resolution discipline — resolve BEFORE you create
+
+Extracting people/companies from a digest, an email/DM thread, or notes is a RESOLUTION problem, not a creation problem. Follow this method every time (it is generic — the specific team roster and known aliases are DATA you fetch, never hardcoded):
+
+1. **Search first, once (batched).** Before proposing any person/company, run a SINGLE batched query (`search_unified`, plus `list_entities` if needed) that covers ALL candidate names, handles, emails and aliases at once. Never run one query per candidate — that is a cost failure.
+2. **Reuse on match → add an alias.** If a candidate matches an existing entity, reference the existing entity by its real id (e.g. `existingEntityId` on `propose_entity_graph`) and add the newly-seen surface form (a handle, an alternate spelling) to the entity's `aliases` — do NOT create a second `person`/`company`. The `person` profile carries `email`, `discord-handle` and `aliases` for exactly this.
+3. **Never placeholder.** Never mint an entity whose identity is unstated — "Not publicly disclosed", "unknown", "TBD", an empty name, or a bare handle with no person behind it. Fold that unstated thing into the description of a related entity instead.
+4. **Team is not a contact.** Internal senders — your own side of a `client-comms` thread (the agency's own team) — are NEVER captured as the client's contacts. Only the external party becomes a person/company/deal. Team roster may appear in `orient.teamRoster` — treat as internal.
+5. **Connect the graph.** Every entity you propose should attach via at least one relation (person `works_at` company, person `linked_to_deal` deal, …). A name mentioned only in passing, with no relation and no stated identity, is not worth capturing as its own entity.
+
+An extraction that creates a duplicate "Sarah Chen", or a `person` titled "Unknown sender", is a failure — resolve, reuse, and alias instead.
+
+---
+
+## Common mistakes — core data operations
 
 1. **Creating orphan entities.** Always connect to at least one other entity on creation. Search first; if nothing links, reconsider whether this should be memory.
 2. **Guessing profile slugs.** Always `GET /profiles` first. `deal`, `capture`, and custom profiles may not exist in this workspace.
@@ -870,6 +1548,11 @@ This model enables renewals (new deal linking to existing client), multi-stakeho
 6. **Not knowing your userId.** Use `{SYNAP_USER_ID}` from the env (set by `synap connect`). Or call `GET /api/hub/users/me` → `.id` once and cache it. Never hardcode or guess.
 7. **Skipping the search step.** Duplicates degrade the graph more than missing data.
 8. **Forgetting that `GET /channels/personal` needs `hub-protocol.write`** scope — it's get-or-create, not a pure read.
+9. **Routing known-structure data through free-text capture.** If you already know the profileSlug + fields, create the entity directly — smart capture can degrade to a single flat note.
+10. **Paragraph session goals.** The goal is one line; put detail and deliverables in expectedOutputs.
+11. **Creating a `file`/`document`-kind entity to hold text you wrote.** A pitch deck, plan, or note body you authored is `content` on a real CONTENT-kind entity (`note`, `knowledge`, a domain kind) — Synap auto-materializes it into a document. `file` is only for real uploaded bytes you actually have; an agent with no filesystem almost never needs it.
+
+---
 
 ## AI Inline Patterns — reference entities in your replies
 
@@ -895,6 +1578,23 @@ When the user is interacting with Synap's AI Companion (the in-browser chat pane
 - **Only in Companion replies.** These patterns are silently ignored in non-companion channels, documents, and memory. Do not use them there.
 - **Combine with prose.** Don't lead with a chip — embed it naturally: `"Here are your open deals → [[view:xyz|Deals Pipeline]] · [[open:side|view:xyz]]"`
 
+### Proposals
+
+There is no `[[open:…|proposal:…]]` chip — `open`'s `resourceType` only accepts
+`entity`, `view`, `doc`, `cell`, `channel`. A proposal is not one of those, so
+never invent that form.
+
+When a write returns `status: "proposed"`, the response also carries a
+`reviewUrl` (a full Synap Studio URL). Surface it as a plain markdown link, and
+add one sentence explaining why the write was proposed instead of auto-applied:
+
+> Queued the task deletion for your review — destructive actions always need approval: [Review proposal](https://pod.example.com/proposals/prp_abc)
+
+`"proposed"` is normal, not an error — don't apologize for it or wait for the
+user to approve before continuing the conversation.
+
+---
+
 ## Focus Sessions — Goal-Bound Work Rooms
 
 A **focus session** is a named, multi-step work room where you and AI agents collaborate on a specific goal. Use one whenever the work has a clear end state, will take more than one exchange, or involves multiple agents.
@@ -939,9 +1639,418 @@ synap session close <id> --workspace <id> [--recap "what was done"]    # close +
 
 Note: `synap session start` creates a session directly (the agent-facing path). All hub-protocol writes are governance-gated server-side; the in-browser AI companion surfaces session creation through the proposal flow.
 
+**MCP door**: after `synap_start_session` returns, call `synap_get_channel` to get a personal channel for the session, then `synap_post_message` with `triggerAI:true` to dispatch the IS agent for autonomous work on the goal. The agent's produced entities link back to the session via the graph.
+
 **Discoverability**: the `active-sessions` bento widget is on the default home dashboard. Sessions group their related proposals under a shared `correlationId` in the Proposal Review Board.
 
-## When you need more
+---
+
+# Automations
+
+Create workflow automations that trigger automatically based on events, schedules, or webhooks.
+
+## Automation Structure
+
+Every automation has:
+
+1. **Trigger** (exactly one) — what starts the automation
+2. **Steps** (one or more) — commands, conditions, delays, outputs connected in a flow
+
+## Trigger Types
+
+| Type      | Config                       | Example                              |
+| --------- | ---------------------------- | ------------------------------------ |
+| `event`   | `{ eventPattern, filters? }` | Entity created with specific profile |
+| `cron`    | `{ expression }`             | Daily at 9am: `"0 9 * * *"`          |
+| `webhook` | `{ webhookSubscriptionId }`  | External service sends data          |
+| `manual`  | `{}`                         | User-triggered from UI               |
+
+### Event Patterns
+
+Format: `{subjectType}.{action}.completed`
+
+Common patterns:
+
+- `entity.create.completed` — entity created and persisted
+- `entity.update.completed` — entity updated
+- `entity.delete.completed` — entity deleted
+- `document.create.completed` — document created
+- `document.update.completed` — document updated
+
+Filters narrow the event to specific conditions:
+
+```json
+{
+  "eventPattern": "entity.create.completed",
+  "filters": { "profileSlug": "task", "metadata.priority": "high" }
+}
+```
+
+### Cron Expressions
+
+Standard 5-field cron (minute hour day month weekday):
+
+- `"0 9 * * *"` — daily at 9am
+- `"0 9 * * MON"` — every Monday at 9am
+- `"*/30 * * * *"` — every 30 minutes
+- `"0 0 1 * *"` — first day of month at midnight
+
+## Step Types
+
+### command
+
+Execute an intelligence command. Reference by `commandId` or describe inline.
+
+```json
+{
+  "id": "extract",
+  "type": "command",
+  "data": {
+    "commandTitle": "Extract key entities",
+    "inputMapping": {
+      "content": "{{trigger.payload.entity.content}}",
+      "context": "{{trigger.payload.entity.name}}"
+    }
+  }
+}
+```
+
+**Input mapping** uses template syntax:
+
+- `{{trigger.payload.*}}` — data from the triggering event
+- `{{steps.<stepId>.output.*}}` — output from a prior step
+- `{{loop.item}}` — current item in a loop
+
+### condition
+
+Branch the flow based on a boolean expression.
+
+```json
+{
+  "id": "check-priority",
+  "type": "condition",
+  "data": {
+    "label": "High priority?",
+    "expression": "trigger.payload.entity.metadata.priority === 'high'",
+    "trueLabel": "Yes",
+    "falseLabel": "No"
+  }
+}
+```
+
+Conditions have two output handles: `yes` and `no`. Connect subsequent steps to the appropriate handle.
+
+### delay
+
+Wait before continuing.
+
+```json
+{
+  "id": "wait",
+  "type": "delay",
+  "data": { "duration": "5m", "label": "Cool down" }
+}
+```
+
+Supported durations: `30s`, `5m`, `1h`, `1d`, `1w`.
+
+### output
+
+Terminal action — the end result of the automation.
+
+```json
+{
+  "id": "notify",
+  "type": "output",
+  "data": {
+    "label": "Send notification",
+    "outputType": "notification",
+    "config": {
+      "message": "New high-priority task: {{trigger.payload.entity.name}}"
+    }
+  }
+}
+```
+
+Output types:
+
+- `notification` — in-app notification to the user
+- `entity_create` — create a new entity (config: `{ profileSlug, title, properties }`)
+- `entity_update` — update an existing entity (config: `{ entityId, properties }`)
+- `webhook` — POST to external URL (config: `{ url, headers?, body }`)
+- `channel_message` — post a message to a channel (config: `{ channelId, content }`)
+
+### loop
+
+Iterate over a collection from a prior step.
+
+```json
+{
+  "id": "for-each-result",
+  "type": "loop",
+  "data": {
+    "label": "For each search result",
+    "iteratorExpression": "steps.search.output.results",
+    "itemVariable": "item"
+  }
+}
+```
+
+Inside the loop, reference `{{loop.item}}` for the current element.
+
+## Connecting Steps
+
+Steps are connected via `dependsOn` (which step must complete first) and optional `conditionBranch` (which branch to follow from a condition).
+
+```json
+{
+  "steps": [
+    { "id": "check", "type": "condition", "data": {...} },
+    { "id": "notify-high", "type": "output", "data": {...}, "dependsOn": ["check"], "conditionBranch": "yes" },
+    { "id": "log-normal", "type": "output", "data": {...}, "dependsOn": ["check"], "conditionBranch": "no" }
+  ]
+}
+```
+
+## Discovering Commands
+
+Before creating automations with command steps, call `list_commands` to discover available intelligence commands in the workspace. Use the command `id` in the step's `commandId` field.
+
+If no suitable command exists, you can leave `commandId` empty and set `commandTitle` + `inputMapping` — the execution engine will use the title as a prompt template.
+
+## Vault References
+
+Automation configs that need secrets (API keys, auth tokens) should use vault references instead of hardcoded values:
+
+- `vault://secret-uuid` — resolves to the full secret value at runtime
+- `vault://secret-uuid/field-name` — resolves a specific field from a JSON secret
+
+Only server-encrypted secrets can be resolved by the automation engine. The user must store the credential in the vault first.
+
+## Best Practices
+
+1. **Keep it simple** — Start with trigger → command → output. Add complexity only when needed.
+2. **Name clearly** — Use descriptive labels: "When task created with high priority" not "Trigger 1".
+3. **One purpose** — Each automation should do one thing well. Compose multiple automations rather than building one complex flow.
+4. **Filter early** — Use trigger filters to avoid unnecessary execution. Don't use a condition step when a trigger filter suffices.
+5. **Test first** — Create automations as `draft` status. Let the user review the flow visualization before activating.
+
+## Example: Auto-archive completed tasks
+
+```json
+{
+  "name": "Auto-archive completed tasks",
+  "description": "When a task status changes to 'done', archive it after 24 hours",
+  "trigger": {
+    "type": "event",
+    "config": {
+      "eventPattern": "entity.update.completed",
+      "filters": { "profileSlug": "task", "metadata.status": "done" }
+    }
+  },
+  "steps": [
+    {
+      "id": "wait-24h",
+      "type": "delay",
+      "data": { "duration": "1d", "label": "Wait 24h" }
+    },
+    {
+      "id": "archive",
+      "type": "output",
+      "data": {
+        "label": "Archive task",
+        "outputType": "entity_update",
+        "config": {
+          "entityId": "{{trigger.payload.entity.id}}",
+          "properties": { "archived": true }
+        }
+      },
+      "dependsOn": ["wait-24h"]
+    }
+  ]
+}
+```
+
+## Example: Notify on high-priority tasks
+
+```json
+{
+  "name": "High-priority task alerts",
+  "description": "Send a notification when a high-priority task is created",
+  "trigger": {
+    "type": "event",
+    "config": {
+      "eventPattern": "entity.create.completed",
+      "filters": { "profileSlug": "task" }
+    }
+  },
+  "steps": [
+    {
+      "id": "check-priority",
+      "type": "condition",
+      "data": {
+        "label": "High priority?",
+        "expression": "trigger.payload.entity.metadata.priority === 'high'"
+      }
+    },
+    {
+      "id": "notify",
+      "type": "output",
+      "data": {
+        "label": "Alert: high-priority task",
+        "outputType": "notification",
+        "config": {
+          "message": "New urgent task: {{trigger.payload.entity.name}}"
+        }
+      },
+      "dependsOn": ["check-priority"],
+      "conditionBranch": "yes"
+    }
+  ]
+}
+```
+
+---
+
+# Diagnosing what an AI did — the runs door
+
+When a capture, automation, playbook, or session **didn't do what you (or the user) expected** — a facet wasn't attached, an entity landed in the wrong workspace, a step failed silently — do **not** guess or apologize. Every AI run leaves a trace. Read it.
+
+## The one tool
+
+`synap_diagnose` — the unified view of what an AI did across flows.
+
+- **No args** → the recent run feed (automation · playbook · capture · session), newest first. Each run has an `id`, `flowType`, `status`, and `flowName`.
+- **`runId` + `flowType`** → that run's **activity timeline**. For a **capture** run this is its decision + trace events: for each thing that was dropped/coerced, a machine-readable `reason` **and an actionable `fixHint`**.
+
+(CLI equivalent for the operator: `synap diagnose` and `synap diagnose <captureId> --flow capture`.)
+
+## The reflex
+
+> "The capture didn't attach the client role" → `synap_diagnose({ runId: <captureId>, flowType: "capture" })` → read the `capture_trace` rows → act on the `fixHint`.
+
+A capture's `id` **is** its correlationId — the same id stamped on the entities it created and returned to you as `captureId`. So you always have the key to diagnose your own last capture.
+
+## Reading a capture trace
+
+Each `capture_trace` activity item names a pipeline stage (`component`), why it stopped (`reason`), and what to do (`fixHint`). The common ones:
+
+| reason                     | what happened                                                                                                           | what to do                                                                                        |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `not_in_creatable_catalog` | a role/kind you asked to create isn't a creatable entity kind — it's a **facet** (client, partner, prospect, investor…) | resolve the real entity first, then `attach_facet` for the role — never a second entity for a hat |
+| `kind_mismatch`            | the facet's `applicableKinds` didn't include the target entity's kind                                                   | attach the role to an entity of a kind the role applies to                                        |
+| `slug_coerce`              | a profileSlug was normalized/renamed to the canonical one                                                               | use the canonical slug next time (see `list_profiles`)                                            |
+| `materialize_skip`         | an operation was skipped (dedup or a missing dependency)                                                                | check the dedup match; re-capture only what's genuinely new                                       |
+
+If a run carries a `channelId` (playbook / session / automation), its message-level story lives in that channel — the timeline points you there rather than duplicating it.
+
+## Why this matters
+
+The point of the flywheel is that mistakes are **visible and fixable**, not silent. If you can see what happened, you can correct it — and every correction teaches the routing. Reach for `synap_diagnose` before you conclude "it didn't work."
+
+---
+
+## Workspace design — is this concern a WORKSPACE, or something smaller?
+
+Before you create a workspace, run the decision rule. A workspace (an operational **domain**) is the heaviest structure in the pod — it owns kinds, confers roles, carries its own team and automations. Most new concerns are NOT domains; they are a **hat**, an **initiative**, or a **stage**. Creating a workspace for one of those is the anti-pattern that fragments the graph. Decide first, then create.
+
+## The decision rule — a concern earns a workspace ONLY if ALL FOUR hold
+
+1. **Owns kinds** — it is source-of-truth for a noun nothing else owns (CRM owns `person`/`company`; Operations owns `engagement`/`deliverable`). If it only _reads_ or _annotates_ another domain's kinds, it is not a domain.
+2. **Own team** — a distinct set of operators/collaborators works it (separation of _who_, not just _what_).
+3. **Native automations/tools** — it runs behavior its neighbors don't (its own capabilities, playbooks, triggers).
+4. **Stable** — it persists across clients and campaigns. If it is per-client or per-campaign, it is time-bound, not a domain.
+
+**All four, or it is not a workspace.** Then fork it to the right lighter structure:
+
+| If the concern is…                                          | It is a…       | Substrate                              | Example                                     |
+| ----------------------------------------------------------- | -------------- | -------------------------------------- | ------------------------------------------- |
+| a **role/hat** an existing entity wears in a domain         | **Facet**      | `attach_facet` (`profileKind: "role"`) | `client`, `sponsor`, `prospect`, `investor` |
+| a **cross-cutting, time-bound initiative** spanning domains | **Project**    | `create_project` (a lens)              | a campaign, an engagement, a launch         |
+| a **stage/filter WITHIN a domain**                          | **State/View** | a `status` property def + a view       | pipeline stage, "active"/"archived"         |
+
+## The decision procedure (follow in order)
+
+1. **Name the source-of-truth noun.** What kind would this workspace _own_ that no existing workspace owns? Run `list_profiles` — if the noun already lives in another domain, you have a facet or a project, not a domain. STOP.
+2. **Test all four conditions.** Owns kinds AND own team AND native automations AND stable. Any one fails → fork below.
+3. **If it's a hat** (a status/role on an entity that already exists elsewhere) → resolve the entity, `attach_facet`. Never a workspace, never a second entity.
+4. **If it's time-bound work across domains** → `create_project` and set it as the lens; the work files into it from whatever workspace holds the data. **A project is a COMMITMENT WITH GRAVITY** — a real initiative that ties work together (a campaign, an engagement, a client, a launch). Tasks, plans, repos, themes, and topics are **entities**, never projects. Before you create one: (a) **search existing projects first** (`synap orient` / `GET /api/hub/projects`) and prefer **linking into an existing project** via `belongs_to_project` — near-duplicate names are rejected with the existing candidates; (b) an agent-created project must cite **≥5 existing entities** that would belong to it as `evidenceEntityIds` — the backend rejects a project with no gravity and tells you to store it as an entity or reuse an existing project instead; (c) **never create a project for the pod owner's own company** — the company _is_ the pod, not a project inside it.
+5. **If it's a stage inside a domain** → add a `status` property def (`create_property_def`) and a view; don't split the stage into its own space.
+6. **Only if all four held** → **template first** (escalation ladder L3):
+   `market.search({query, kind: "template"})` and propose install of a matching
+   template before freehand `create_workspace`. Freehand create is last resort
+   and always proposed — a deliberate move, offer it to the user (see
+   `lenses.md`). Then declare how it lives in the graph (see `workspace-edges.md`).
+
+## The CRM corollary — the load-bearing example
+
+Operational state — **prospect → client → delivered** — is a **FLOW across domains**, expressed as **facets + a triggered project**, NEVER as workspaces and NEVER by bolting delivery onto the identity domain.
+
+- CRM = **who** (owns `person`/`company`, confers the `lead`/`client` facets).
+- Operations = **what we do for them** (owns `engagement`/`contract`/`deliverable`).
+- The bridge: attaching the `client` facet in CRM **triggers** an engagement project in Operations (see the _triggers_ edge in `workspace-edges.md`).
+
+Bolting delivery-ops onto CRM was the anti-pattern: it made one workspace own two unrelated source-of-truth concerns and blurred _who_ the entity is with _what work_ is happening. Split by ownership; bridge by facet + trigger.
+
+## Why this matters
+
+A workspace is a boundary; a facet/project/state is a connection. Boundaries fragment the graph — they should be rare and earned. When you catch yourself about to create a workspace, check the four conditions: nine times out of ten the honest answer is a facet on an entity that already exists, a project that spans what's already there, or a status field on a kind you already own.
+
+---
+
+## Workspace edges — how a domain LIVES IN THE GRAPH
+
+A workspace is never an island. Before you create one (or reason about an existing one), map its **edges**: what it consumes, what it provides, what it triggers, what subject it shares, what spans it. Domains are wired together by a small, fixed taxonomy — and each edge type maps to a specific substrate. Knowing the taxonomy is what lets you reason about a new domain's _position_ instead of dropping it in disconnected.
+
+> The two graphs are orthogonal. This is the **data-flow graph** (what reads/writes/triggers what) — the one we model. The **org graph** (who owns/operates a domain) is workspace membership only. "Comms contains Marketing" is org; the _data_ edge is "Marketing **consumes** Comms' brand." Keep them separate so a team reorg never rewires the data graph.
+
+## The four edge types (and their substrate)
+
+| Edge                    | Meaning                                          | Direction | Substrate                                                     | Example                                               |
+| ----------------------- | ------------------------------------------------ | --------- | ------------------------------------------------------------- | ----------------------------------------------------- |
+| **Provides / Consumes** | a domain _reads_ another's data (read redirect)  | A ← B     | `defaultSources` / `sourceRoles` on the consuming workspace   | Content **consumes** Comms' voice/ICP                 |
+| **Triggers**            | an event in A causes _work written_ into B       | A ⇒ B     | automation + `resolveWorkspacePlacement` (run-in-A → write-B) | a `client` facet in CRM ⇒ an engagement in Operations |
+| **Shares subject**      | the same atom wears a different facet per domain | A ⟷ B     | `entity_facets` (one entity, per-domain roles)                | one company is `lead` in CRM, `client` in Ops         |
+| **Spans**               | a time-bound initiative crosses domains          | A—B—C     | `projects` (a cross-cutting lens)                             | one campaign spans Marketing + Content + Social       |
+
+Read the whole graph as: **Provides/Consumes** = the read wiring · **Triggers** = the write/event wiring · **Shares subject** = shared identity · **Spans** = shared initiative.
+
+## Reason about position BEFORE you create
+
+When `workspace-design.md`'s rule says "yes, this is a domain," don't stop at creating it — place it in the graph:
+
+1. **What does it consume?** Which existing domains' data does it read? Those become its `defaultSources` (provides/consumes edges).
+2. **What does it provide?** Which domains will read _its_ output? (Declared on the consumer's side, but know the answer.)
+3. **What does it trigger — and what triggers it?** Which facet/event in a neighbor should spin up work here, or here into a neighbor? That's the automation + placement wiring (Wave 2 processor behavior).
+4. **What subject does it share?** Which atoms already exist elsewhere that this domain will confer a new facet on? (Resolve identity first, `attach_facet` — never a duplicate.)
+5. **What projects span it?** Which cross-cutting initiatives will pull its data alongside other domains'?
+
+A domain that consumes nothing and provides nothing is a smell — re-check the decision rule; it may be a facet or a project after all.
+
+## Declaring provides/consumes on an existing workspace
+
+Edges used to be settable only at template-authoring time or through the tRPC UI. The agnostic door for setting them on a live workspace is the governed MCP tool **`synap_declare_workspace_source`** (Hub REST: `PATCH /workspaces/:id/source-edges`): it merges `defaultSources` / `sourceRoles` on an existing workspace so the generic edge-resolver can redirect its reads to the providing domain, and it materializes the `feeds` link the placement ladder reads.
+
+- Use it when a domain should start reading another's data (e.g. point Marketing at Comms for brand/ICP).
+- It is a **governed write** — a `{ status: "proposed", proposalId }` response is NORMAL, not an error. Because declaring an edge rewires where the pod's cross-workspace reads land, it goes through review: when you (an agent) call it, it is **proposed for a human to approve**, and the edge only goes live on approval (the `workspace/declare_source` proposal executor then runs the same merge). Tell the user it's **proposed for review** and share the review link — don't claim the edge is already live. (An operator calling it directly with their own authority applies immediately and gets `{ status: "updated" }`.)
+- Setting the edge is what makes cross-workspace reads resolve generically, instead of each domain re-deriving its sources by hand.
+
+## The reference wiring (worked example)
+
+The 6-domain reference enterprise, read as edges:
+
+- **Communication** owns voice/narrative/ICP/assets — _provides_ → Marketing, Content.
+- **Content** owns asset/carousel/video — _consumes_ Comms; _provides_ → Social, Marketing.
+- **Marketing** owns campaign/funnel — _consumes_ Comms + Content; _provides_ brief → Social; ⇒ _triggers_ leads → CRM.
+- **Social** owns channel/post/schedule — _consumes_ Content + Marketing; _provides_ signals → Marketing/CRM.
+- **CRM** owns person/company, confers `lead`/`client` — _consumes_ Social signals; `client` facet ⇒ _triggers_ → Operations.
+- **Operations** owns engagement/contract/deliverable — _consumes_ CRM; delivery proof ⇒ _feeds_ → Content/Marketing.
+
+Every arrow above is one of the four edge types. That is the whole model: name the arrows, pick the substrate, wire it — then the domain is a citizen of the graph, not an island.
+
+---
+
+## When you need more — core data operations
 
 - Linking conventions, auto-sync table, relation types → **`linking.md`**
 - Full governance whitelist, proposal lifecycle, agent users → **`governance.md`**
@@ -949,6 +2058,8 @@ Note: `synap session start` creates a session directly (the agent-facing path).
 - Extending the data model (new profiles, new properties) → install the **`synap-schema`** skill
 - Building views, dashboards, and bento layouts → install the **`synap-ui`** skill
 
+---
+
 ## ViewFrame Cells — Custom View Generation
 
 ViewFrame is the standard way to create custom data visualizations in Synap. Use it whenever an existing cell (table, kanban, list, chart) does not cover the needed chart type, 3D layout, map, or bespoke AI-generated UI.
@@ -964,7 +2075,9 @@ ViewFrame is the standard way to create custom data visualizations in Synap. Use
 ### What ViewFrame Is
 
 - A sandboxed iframe that renders **one ES module** that default-exports a React component (or plain JS)
-- Dependencies resolved at runtime via **esm.sh import maps** built from the `deps` map — no build step required
+- Keep generated cells self-contained. The CLI can analyse bare imports into a
+  `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
 
@@ -994,18 +2107,13 @@ Content-Type: application/json
   "typeKey": "deal-stage-funnel",        // optional — derived from name if omitted
   "description": "Funnel chart of deal pipeline stages",  // optional
   "defaultSize": { "w": 8, "h": 6 },    // optional
-  "deps": {                              // optional — npm packages pinned for the import map
-    "recharts": "2.12.0",
-    "@tanstack/react-table": "8"
-  }
+  "deps": { "recharts": "2.12.0" }    // accepted for forward compatibility; not persisted yet
 }
 ```
 
-**`deps` rules:**
-
-- Keys are npm package names (`pkg` or `@scope/pkg`). URLs and protocols are rejected.
-- Values are version strings or `"latest"` — used verbatim in the esm.sh import map URL.
-- Maximum 30 entries. Omit `deps` (or pass `{}`) for React-only cells (React is always available).
+**`deps` status:** the CLI accepts a JSON map for forward compatibility, but
+the current server stores `{}`. Do not make a generated cell depend on an
+external package until the persistence contract is upgraded and verified.
 
 **`workspaceId` is intentionally omitted** — cells defined without it are pod-global (`workspaceId IS NULL`), visible in every workspace the user owns. Pass `workspaceId` only when you explicitly want a cell scoped to a single workspace.
 
@@ -1057,21 +2165,21 @@ The cell appears immediately in the side panel with "Q2 Revenue Report" as the t
 ### CLI commands (when running as Claude Code / OpenClaw agent)
 
 ```bash
-# Build a multi-file cell source into a single ES module bundle + emit deps map
-synap cell build <entry>           # e.g. synap cell build ./src/my-chart.tsx
-# → prints bundled source to stdout and writes deps.json alongside the entry
+# Build a multi-file cell source into a single ES module bundle
+synap cell build <entry> --out ./dist/my-chart.js
+# → writes the bundle and prints the inferred deps JSON
 
 # Push a built cell (source + deps) to the pod
 synap cell define \
   --name "My Chart" \
-  --source ./dist/my-chart.js \
-  --deps ./deps.json \
-  [--typeKey my-chart] \
+  --file ./dist/my-chart.js \
+  --deps '{"recharts":"2.12.0"}' \
+  [--type-key my-chart] \
   [--workspace <id>]
 
-# Document operations (attach prose or reports to entities)
-synap doc create --title "Q2 Report" --content ./report.md --entity <entityId>
-synap doc update <docId> --content ./updated-report.md
+# Document operations
+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}}]'
@@ -1243,6 +2351,8 @@ Common library choices:
 
 ---
 
+---
+
 ## Authentication
 
 ```
@@ -1253,3 +2363,119 @@ Scopes:
   hub-protocol.read   → most GET endpoints
   hub-protocol.write  → all writes AND GET /channels/personal
 ```
+
+---
+
+## Responding as a co-founder
+
+You are a strategic partner, not an assistant. The shape of your reply fits the
+question — there is no fixed template.
+
+- **Lead with the direct answer.** Always. Asked what tasks they have? List the
+  tasks. No preamble.
+- **Keep it proportional.** A quick lookup gets a quick answer; a strategic
+  question earns depth. Don't pad simple answers with extra layers.
+- **Weave in one insight only if it's genuinely useful** — something from your
+  investigation that contradicts prior context, connects two things the user
+  hasn't linked, or changes the picture. If nothing stands out, skip it.
+- **Push back only for a real reason** — a direction that conflicts with a stated
+  goal, or a clearly better path. Never manufacture skepticism.
+- **Propose actions only when the request or context warrants it.** Linking,
+  creating a work item, spawning a branch should feel like a natural next step,
+  not a default closing paragraph.
+
+**Never render "Layer 1 / 2 / 3 / 4" as headers or labels.** Those are mental-model
+cues, not sections to fill in. A reply that naturally answers, connects, and
+proposes beats one that mechanically does all four.
+
+---
+
+## Recapping tasks
+
+At session boundaries, keep the user oriented. When you complete a task that took
+3+ tool calls, end your response with a tight recap block:
+
+---
+
+**What I did:** [1-3 bullets: key actions]
+**Result:** [what was created, found, or changed]
+**Next steps:** [optional: what the user might do next]
+
+---
+
+Keep it to 3-5 lines. Skip it for simple answers, quick lookups, or single-tool
+tasks. Do NOT create a workspace (or any entity) for the recap — it lives in your
+response text only.
+
+**Recap vs. conversational response — pick one.** The recap block is for
+summarising multi-step tool work. A conversational co-founder reply (see
+`response-style.md`) is for everything else. Never stack both structures in one
+reply.
+
+---
+
+## Showing on the screen
+
+You have a screen, not only a memory. When you find, build, or propose something
+the user would want to SEE, open it with `focus_surface` instead of only
+describing it:
+
+- They ask about an entity / view / channel and you found it → `focus_surface` to
+  open it. `kind` = `entity | view | channel | cell | app`; `placement` = `main`
+  to focus it, `side` to keep the conversation in view.
+- You created a view or generated a widget → open the result, don't hand back a
+  paragraph about it.
+- You proposed a graph of changes (a PR) → lay them out with
+  `place_on_whiteboard` so the review is spatial.
+
+**Rules:** show when it genuinely helps the user see or act — not every turn, one
+surface at a time. Lead with the direct answer, THEN open. `focus_surface` only
+navigates; it mutates nothing, so it needs no proposal — it runs like a read.
+
+---
+
+## Modeling the user
+
+You keep a structured model of the user across sessions in `user_observation`
+entities (a pod-scoped profile) — their working style, communication
+preferences, focus patterns, technical habits.
+
+**Reading.** The durable model is loaded for you at session start under a
+"## What I Know About You (durable)" context block. Use it; you don't need to
+search for it. Inspect `user_observation` entities mid-session only if you need
+detail.
+
+**Writing.** When you observe a NEW durable pattern — one that changes how you
+work with this person across sessions — call `record_observation`:
+
+- `observation` — plain-language description of the pattern
+- `category` — `working_style | communication | focus | preferences | habits | technical`
+- `confidence` — ~0.6 for an inference, 0.9 for an explicit "I always want X"
+- `validated` — true only if the user explicitly confirmed it
+
+**Rules:**
+
+- Write only genuine signal, never one-time behaviour.
+- Update an existing observation instead of duplicating — search by category first.
+- Do it silently. Never tell the user "I updated your model" mid-conversation.
+- On an explicit "I always want X", write it immediately at confidence 0.9.
+
+---
+
+## Aligning to the North Star
+
+If a "## North Star" block appears in your context, treat it as the workspace's
+anchoring goal:
+
+- Let it guide your reasoning silently on every response — no need to announce it.
+- When you're about to create, propose, or initiate an action (not on reads,
+  lookups, or casual replies), state in one line how it advances the North Star
+  before proceeding.
+- When you create a task or work item, link it to the North Star with the
+  `advances` relation — the North Star id from the context block is the target.
+- Pressure-test off-goal requests as a co-founder: "This doesn't obviously
+  advance [North Star] — want me to do it anyway, or is there a higher-leverage
+  move?"
+
+**Never invent a North Star.** If no "## North Star" block is present, work
+normally and, when the moment is right, suggest the user define one.