@synap-core/cli 1.7.0 → 1.10.0

package/skills/synap/SKILL.md

@@ -35,41 +35,215 @@ 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. Six layers you need:
+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.
+
+### Where to write what — the three lanes (decide by KIND)
+
+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)              |
+| **is GLOBAL truth** — a best-practice / runbook / how-to that holds across ALL projects                                         | **Global**           | pod-wide procedural `knowledge_keys` (`synap capture --global --type … [--key ns:slug]`) | reviewed for shared truth                                                                                  |
+| **is about the USER** — how they work/talk/decide, their preferences, their life                                                | **User**             | pod-wide `user_observation` (`synap observe write` / `record_observation` tool)          | inferences are **proposed** (you review); explicit "I always X" auto-saves — never model the user silently |
+
+> **Why this matters:** writing to the wrong lane degrades the graph. A gotcha you learned about the **current project** is **Work** (the active workspace — its domain). A best-practice that holds **everywhere** is **Global** (`--global`, pod-wide). A fact about **how the user works** is **User** (pod-wide, inferences proposed). `synap capture` echoes which lane + governance it used; check it.
+
+> **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               |
-| **Memory**    | Atomic facts, no structure                     | Preferences, context, ephemeral notes                    |
 | **Threads**   | Channel conversations, optional entity context | Posting to the user's personal AI channel                |
 | **Proposals** | Writes queued for human approval               | Governance for some mutations (not an error — see below) |
 
+### Key profiles for AI use
+
+| Profile slug       | Scope     | Who writes     | Purpose                                                                                                                                                                                                                                       |
+| ------------------ | --------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `note`             | pod       | **human only** | The human's raw "dump now, structure later" inbox. **The AI never writes a note** — structuring into a lane is its job; use `capture` instead.                                                                                                |
+| `knowledge`        | workspace | AI             | Validated gotchas/lessons/decisions — the **Work lane** (default `synap capture --type`; ek_type/ek_claim/ek_why). DOMAIN = the workspace (a Builder gotcha ≠ a marketing one). Cross-project runbooks go to `knowledge_keys` via `--global`. |
+| `user_observation` | pod       | AI only        | Durable user model — habits, communication style, preferences                                                                                                                                                                                 |
+| `decision`         | pod       | human + AI     | Architectural decisions with rationale                                                                                                                                                                                                        |
+| `research`         | pod       | AI             | Investigation with sources + conclusion                                                                                                                                                                                                       |
+| `question`         | pod       | human + AI     | Open inquiry, closed when a decision answers it                                                                                                                                                                                               |
+
+---
+
 ## 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 search "query" --json
-synap remember "fact about the user" --json
-synap recall "query" --json
+synap ask "your question" --json                       # THE read verb — routes to the right store(s) + shows which answered
+synap capture --type=lesson --claim="…" --json         # Work lane (default) — domain knowledge → active workspace
+synap capture --global --type=reference --claim="…" --json  # Global lane — pod-wide cross-cutting runbook (knowledge_keys)
+synap observe write "…" --json                          # User lane — durable user model (inferences proposed)
 ```
 
+**The canonical verbs:** `ask` (read) · `capture` (structured write — pick a lane:
+Work default / `--global` / `observe` for User) · `orient` (bootstrap). `note` exists
+for the HUMAN's raw "dump now, structure later" inbox — **the AI always `capture`s
+instead.** **Reading is one verb: `ask`** — it classifies your
+question and routes across the three memory substrates (semantic = the typed entity
+graph, procedural = how-to docs, episodic = raw captures), returning one answer
+tagged with which substrate(s) answered (and which, if any, were unavailable). Don't
+pick a store; `ask` picks for you and tells you what it did. (`graph` for an explicit
+traversal and `get`/`show`/`browse` for direct lookups remain; there is no `search`
+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
 POST   /api/hub/relations         body: { userId, sourceEntityId, targetEntityId, type }
 GET    /api/hub/entities?q=…&profileSlug=task&workspaceId=…
 GET    /api/hub/entities/{id}/connections?userId=…
+POST   /api/hub/knowledge/ask     body: { query, workspaceId?, limit? }   ← ONE read door, routes across substrates
 POST   /api/hub/memory            body: { userId, fact }
 GET    /api/hub/memory?userId=…&query=…
 ```
@@ -82,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>`):
 
@@ -100,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:
 
 ```
@@ -128,8 +347,8 @@ GET /api/hub/discover?userId={userId}&workspaceId={workspaceId}
 `scope: "workspace"` = scoped to one workspace (deal, file, capture, custom profiles).  
 Each profile includes its full property schema. Use `createCommand` as a template.
 
-**2. Search before answering**  
-Before answering any question about the user's projects, tasks, contacts, decisions, or anything they might have captured — search Synap first. Do not answer from your training or context window when Synap may have the authoritative answer.
+**2. Ask before answering**  
+Before answering any question about the user's projects, tasks, contacts, decisions, or anything they might have captured — `ask` Synap first (`synap ask "…"` / `POST /api/hub/knowledge/ask`). It routes across all three memory substrates in one call. Do not answer from your training or context window when Synap may have the authoritative answer.
 
 **3. Save proactively — without waiting to be asked**  
 When the user shares a decision, task, meeting outcome, contact, or any durable information: save it. Don't ask "should I save this?" for obviously important information. Use:
@@ -146,18 +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
-synap workspace provision-agent --json # provision your agent workspace + auto-sets it active
+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:**
@@ -168,14 +390,14 @@ synap orient --json
 # Never hardcode workspace IDs — discover them here.
 ```
 
-**Search (Typesense-powered, cross-collection):**
+**Ask (the one read verb — routes across all substrates):**
 
 ```bash
-synap search "project ideas" --json
-synap search "Antoine" --type=entity --workspace=<id> --json
-synap search "meeting notes" --type=doc --limit=5 --json
-# Omit --workspace to search pod-wide. Include it to scope to one workspace.
-# Use search for name/keyword queries. For semantic/conceptual search, use Hub Protocol memory endpoints.
+synap ask "project ideas" --json
+synap ask "what did Antoine decide about auth" --workspace=<id> --json
+synap ask "how do I deploy the backend" --json   # routes to procedural how-to docs
+# Omit --workspace for pod-wide; include it to scope to one workspace.
+# `ask` classifies intent and unions the right substrate(s) — it replaces search/recall.
 ```
 
 **Read entities:**
@@ -187,17 +409,19 @@ synap list entities --profile=task --workspace=<id> --json
 synap get entity <id> --json
 ```
 
-**Episodic memory (session facts, loose context):**
+**Capturing a decision (the AI structures — it never `note`s):**
 
 ```bash
-synap remember "Key decision: use Typesense for search" --json
-synap recall "Typesense" --limit=5 --json
+synap capture --type decision --claim "Use Typesense for entity search" --json
+# Retrieve later with the one read verb: synap ask "Typesense decision"
 ```
 
+> `synap note` is the HUMAN's raw "dump now, structure later" inbox. As the AI, always `capture` into a lane — structuring is your job.
+
 **Structured knowledge (durable, typed, searchable — preferred for engineering learnings):**
 
 ```bash
-# Capture a gotcha, lesson, decision, or reference into your agent workspace
+# Work lane (default): a domain gotcha/lesson/decision → knowledge entity in the ACTIVE workspace
 synap capture --type gotcha --claim "Hono static routes must come before /:id" \
   --why "First-match routing; dynamic routes eat static ones" \
   --tags "repo:synap-backend,layer:routing" --json
@@ -205,17 +429,33 @@ synap capture --type gotcha --claim "Hono static routes must come before /:id" \
 synap capture --type lesson --claim "code-read ≠ runtime-true for library APIs" \
   --evidence "tldraw 2.4.6 binding API changed silently from props.start.boundShapeId"
 
-# Recall across your knowledge base with full-text search
-synap recall "hono routing" --structured --json
-synap recall "tldraw" --structured --type gotcha --json
+# A quick decision-note is a typed knowledge entry (ek_type=decision):
+synap capture --type decision --claim "Use Typesense for entity search" \
+  --why "pgvector deferred to V1; Typesense ships now" --json
 
-# Prerequisite (run once): provision your agent workspace and set it active
-synap workspace provision-agent --json
+# Global lane: a runbook/best-practice that holds across ALL projects → pod-wide knowledge_keys
+synap capture --global --type reference --claim "Always fix the canonical path, never a workaround" \
+  --key "principle:root-cause" --json
+
+# Retrieve any of it later with the one read verb (it spans every lane):
+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
 ```
 
-`synap capture` / `synap recall --structured` uses the `engineering_knowledge` entity profile.
-`synap remember` / `synap recall` (without `--structured`) uses the ephemeral `/memory` store.
-Use structured knowledge for anything worth remembering across sessions and projects.
+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:**
 
@@ -231,7 +471,9 @@ synap set entity <id> --props='{"status":"done"}' --json
 - Always use `--json` when calling from code — clean stdout, no spinners, machine-parseable
 - Run `synap orient` first to discover workspace IDs — never hardcode them
 - Omit `--workspace` to operate pod-wide; include it to scope to a specific workspace
-- `synap search` is Typesense (fast keyword/name search). Semantic search → Hub Protocol `GET /api/hub/memory?query=…`
+- `synap ask` is the one read verb — it routes keyword + semantic + procedural automatically; you never choose a search backend.
+
+---
 
 ---
 
@@ -249,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.
@@ -357,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
 
@@ -399,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:
@@ -417,29 +667,201 @@ Every write returns a `status` field:
 2. Give them the link to review — `reviewUrl` opens the proposal in Synap Studio. Show the link as-is.
 3. Move on with the conversation. Don't wait or poll.
 
+### The `reasoning` field — required, structured, contextual
+
+Every write call (create, update, delete) must include a `reasoning` field. This is what the governance reviewer reads to understand your decision. It is **not optional**.
+
+Use this exact structure:
+
+```
+Context: [what the user said or what event triggered this write — one sentence]
+Intent:  [what this entity or change accomplishes — one sentence]
+Links:   [actual entity IDs or slugs this relates to, e.g. "ent_abc, ent_xyz"]
+```
+
+For updates, add:
+
+```
+Changed: [field] [old value] → [new value]
+```
+
+**Example (create):**
+
+```
+Context: User asked to track the Acme deal they mentioned in today's call.
+Intent:  Creates a deal entity for Acme at lead stage linked to Alice Johnson.
+Links:   ent_person_alice_johnson, ent_company_acme
+```
+
+**Example (update):**
+
+```
+Context: User confirmed the Acme deal moved to proposal stage.
+Intent:  Advances the deal through the pipeline so it appears in the proposal view.
+Links:   ent_deal_acme, ent_person_alice_johnson
+Changed: dealStage lead → proposal
+```
+
+Rules:
+
+- One sentence per field. No padding.
+- `Links` must reference real entity IDs or slugs visible in the current context — not descriptions like "the related project".
+- **"Agent requires proposal for all write operations."** is never acceptable as a `reasoning` value. That is an internal governance message, not agent reasoning. Write it and the proposal is meaningless to the reviewer.
+
 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)
+### Create an entity (schema-first, complete intent)
+
+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` means a proposal exists and no entity is live; `applied` means the
+reported direct write completed; `partial` means a follow-up (for example a
+facet) failed after the entity applied. Never claim completion from `pending`,
+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, submit one `POST /api/hub/capture/graph` plan instead of sequencing
+independent creates. It returns a pending receipt and materializes on human
+approval.
+
 ### Update an entity
 
 ```json
@@ -563,9 +985,260 @@ 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
 
-Graph-based, not semantic. Type filter → relations → neighborhood.
+**Start with `ask` — the one routed read door.** It classifies the question and
+queries the right substrate(s) for you, returning a glass-box answer (which
+substrates answered, which were unavailable, plus the engine's verdict). Reach for
+the low-level doors below only when you deliberately want a single substrate or a
+specific shape (a graph traversal, a typed-entity filter, an entity's neighborhood).
+
+```
+# THE read door — routes across semantic / procedural / episodic, tells you which answered
+POST /api/hub/knowledge/ask   body: { query, workspaceId?, limit? }
+  → { query, routedTo: [...], primary, answers: [{ substrate, items, status }], degraded, understanding, verdict }
+```
+
+Low-level doors (`ask` routes to these — graph-based, not semantic; type filter →
+relations → neighborhood):
 
 ```
 # Keyword search across everything (entities, documents, views, threads)
@@ -590,8 +1263,12 @@ 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:
@@ -603,6 +1280,8 @@ POST /api/hub/capture/execute     → commits (after user confirms)
 
 The pipeline extracts multiple entities with their relations in one LLM call. Read **`capture.md`** for the full flow.
 
+---
+
 ## Worked examples
 
 ### Example 1 — "Remind me to send the proposal to Acme on Friday"
@@ -657,6 +1336,8 @@ 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.
 
+---
+
 ## 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.
@@ -763,7 +1444,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.
@@ -773,6 +1468,10 @@ 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.
+
+---
 
 ## AI Inline Patterns — reference entities in your replies
 
@@ -798,13 +1497,487 @@ 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]]"`
 
-## When you need more
+### Proposals
 
-- Linking conventions, auto-sync table, relation types → **`linking.md`**
-- Full governance whitelist, proposal lifecycle, agent users → **`governance.md`**
-- Unstructured capture pipeline → **`capture.md`**
-- Extending the data model (new profiles, new properties) → install the **`synap-schema`** skill
-- Building views, dashboards, and bento layouts → install the **`synap-ui`** skill
+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.
+
+**When to propose a session** (via the proposal system — always ask first):
+
+- Research with 5+ sources → decision memo
+- Lead generation sprint → qualified list + outreach drafts
+- Incident investigation → postmortem doc
+- Data import → structured knowledge base
+- Any task you'd naturally call "a project" rather than "a question"
+
+**How the AI proposes a session:**
+
+```
+create_proposal with targetType: "focus_session"
+→ user reviews goal + rationale + expected outputs in ProposalReviewBoard
+→ on approval, session is created in focus_sessions table
+→ AI updates progress (0→100) via PATCH /api/hub/focus-sessions/:id { workspaceId, progress: N }
+→ session auto-surfaces in the Active Sessions bento widget on the user's home
+```
+
+**Session templates** (pass as `templateId`):
+`research-room` · `lead-sprint` · `decision-memo` · `import-cleanup` · `incident-room` · `campaign-intel`
+
+**Hub Protocol REST** (for IS → backend; always include `workspaceId`):
+
+- `POST /api/hub/focus-sessions` — create (include `correlationId` for idempotency)
+- `GET /api/hub/focus-sessions/:id?workspaceId=<id>` — read
+- `PATCH /api/hub/focus-sessions/:id` — update `{ workspaceId, progress, status, goal, agentIds }`
+
+**CLI** (use when running as Claude Code / OpenClaw agent):
+
+```bash
+synap session start --goal "<goal>" [--workspace <id>]                 # create + start a session
+synap session list [--workspace <id>] [--status active|paused|closed]  # list sessions
+synap session get <id> [--workspace <id>]                               # read a session
+synap session update <id> --workspace <id> --progress 50               # report progress
+synap session update <id> --workspace <id> --status paused             # pause
+synap session close <id> --workspace <id> [--recap "what was done"]    # close + recap
+```
+
+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.
+
+---
+
+# 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`**
+- Unstructured capture pipeline → **`capture.md`**
+- 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
 
@@ -820,87 +1993,222 @@ ViewFrame is the standard way to create custom data visualizations in Synap. Use
 
 ### What ViewFrame Is
 
-- A sandboxed iframe that renders any ES module (React component or plain JS module)
-- Dependencies resolved at runtime via **esm.sh import maps** — no build step
-- The host injects a `SynapWidget` bridge for data access (same postMessage protocol as iframe widgets)
+- A sandboxed iframe that renders **one ES module** that default-exports a React component (or plain JS)
+- 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
 
-### Register a Widget via the Hub Protocol
+### Authoring contract
 
-List installed widgets:
+A ViewFrame cell is **one self-contained ES module** (inline in `rendererSource`):
 
-```
-GET /api/hub/widget-definitions?workspaceId={workspaceId}
-Authorization: Bearer {SYNAP_HUB_API_KEY}
-```
+- The module **default-exports a React component** (or calls `SynapWidget.onInit()` for plain JS).
+- Bare imports (`"react"`, `"recharts"`, etc.) are resolved via the esm.sh import map generated from `deps`.
+- **No bundler, no `import` of local files** — everything is either inlined or declared in `deps`.
+- External CSS is not supported; inline `<style>` tags or CSS-in-JS only.
 
-Install a new ViewFrame widget (creates a proposal for user review):
+### Register a Cell via the Hub Protocol (canonical path)
+
+**Use `POST /api/hub/cells/define` — this is the canonical Hub Protocol path for AI-generated cells.**
+
+It is idempotent (upserts on typeKey), pod-global by default (no workspaceId needed), and immediately available across all of the user's workspaces without any proposal step.
 
 ```
-POST /api/hub/widget-definitions
+POST /api/hub/cells/define
 Authorization: Bearer {SYNAP_HUB_API_KEY}
 Content-Type: application/json
 
 {
-  "userId": "{SYNAP_USER_ID}",
-  "workspaceId": "{workspaceId}",
-  "typeKey": "deal-stage-funnel",
   "name": "Deal Stage Funnel",
-  "description": "Funnel chart of deal pipeline stages",
-  "rendererType": "iframe",
-  "rendererSource": "<full HTML document — see template below>",
-  "defaultSize": { "w": 8, "h": 6 },
-  "category": "visualization"
+  "rendererSource": "<!DOCTYPE html>…</html>",
+  "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": { "recharts": "2.12.0" }    // accepted for forward compatibility; not persisted yet
 }
 ```
 
-`typeKey` must be kebab-case matching `/^[a-z][a-z0-9-]+$/`. Use a descriptive name specific to the widget's content.
+**`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.
+
+Response: `{ "success": true, "typeKey": "generated:deal-stage-funnel" }`
+
+The typeKey is auto-prefixed `generated:` when not explicitly provided.
+
+**List cells (all pod-global + optionally workspace-specific):**
+
+```
+GET /api/hub/cells                         — pod-global only
+GET /api/hub/cells?workspaceId={id}        — pod-global + workspace-scoped
+Authorization: Bearer {SYNAP_HUB_API_KEY}
+```
+
+**Delete a cell:**
+
+```
+DELETE /api/hub/cells/{typeKey}            — pod-global row
+DELETE /api/hub/cells/{typeKey}?workspaceId={id}  — workspace-scoped row
+Authorization: Bearer {SYNAP_HUB_API_KEY}
+```
+
+**Open the cell in the browser (deep link):**
+
+```
+synap://open/cell/{typeKey}
+```
+
+The browser receives this deep link, looks the typeKey up in the cell registry (which polls `widget_definitions` every 10s), and opens it as a side panel tab with the cell's registered `meta.name` as the tab title.
+
+**Full AI artifact workflow:**
+
+```
+// 1. Generate the HTML/React cell
+POST /api/hub/cells/define
+{ "name": "Q2 Revenue Report", "rendererSource": "<!DOCTYPE html>…</html>",
+  "deps": { "recharts": "2.12.0" } }
+// → { "success": true, "typeKey": "generated:q2-revenue-report" }
+
+// 2. Open it in the user's browser
+synap://open/cell/generated:q2-revenue-report
+```
+
+The cell appears immediately in the side panel with "Q2 Revenue Report" as the tab title. It persists across sessions and is available from any workspace.
+
+> **Note:** `POST /api/hub/widget-definitions` (tRPC path) still works but is the internal/admin path. Use `POST /api/hub/cells/define` for all agent-generated cells.
 
-The response carries `status: "ok"` (installed immediately) or `status: "proposed"` (queued for user review — surface `reviewUrl` to the user).
+### CLI commands (when running as Claude Code / OpenClaw agent)
+
+```bash
+# 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" \
+  --file ./dist/my-chart.js \
+  --deps '{"recharts":"2.12.0"}' \
+  [--type-key my-chart] \
+  [--workspace <id>]
+
+# 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}}]'
+```
 
 ### The SynapWidget Bridge (inside the iframe)
 
 `window.SynapWidget` is injected automatically — do NOT import or `<script>` it.
 
+#### Queries (read-only, always approved)
+
 ```js
 SynapWidget.onInit(async ({ config, context }) => {
   // context: { workspaceId, viewId?, entityId?, sdkVersion }
-  const items = await SynapWidget.query("list_entities", {
-    profileSlug: "deal", // or 'task', 'person', 'company', any custom slug
+
+  // List entities
+  const deals = await SynapWidget.query("entities.list", {
+    profileSlug: "deal",
     limit: 200,
   });
-  render(items ?? []);
+
+  // Get a single entity
+  const entity = await SynapWidget.query("entities.get", { id: "uuid" });
+
+  // List views
+  const views = await SynapWidget.query("views.list", {
+    workspaceId: context.workspaceId,
+  });
+
+  // List profiles
+  const profiles = await SynapWidget.query("profiles.list", {});
+
+  render(deals ?? []);
   SynapWidget.resize(document.body.scrollHeight);
 });
 ```
 
 All `query()` calls return a Promise. Entity shape: `{ id, title, profileSlug, properties, createdAt, … }`.
 
-Navigation and notifications:
+#### Mutations (governance-gated — return `{ status: "approved" | "proposed" | "denied" }`)
 
 ```js
-SynapWidget.navigate({ entityId: "entity-uuid" }); // opens entity detail
-SynapWidget.toast("Done!", "success"); // 'success' | 'error' | 'info'
+// Create an entity
+const result = await SynapWidget.mutate("create_entity", {
+  profileSlug: "task",
+  title: "Follow up",
+  properties: { status: "todo" },
+});
+// result.status === "approved" → result.id is the new entity id
+// result.status === "proposed" → result.proposalId, result.reviewUrl
+
+// Update an entity
+await SynapWidget.mutate("update_entity", {
+  id: "uuid",
+  properties: { status: "done" },
+});
+
+// Delete an entity (always proposed for agent-generated cells)
+await SynapWidget.mutate("delete_entity", { id: "uuid" });
+
+// Create a relation
+await SynapWidget.mutate("create_relation", {
+  sourceEntityId: "uuid-a",
+  targetEntityId: "uuid-b",
+  type: "related_to",
+});
+```
+
+**Always check `result.status`.** `"proposed"` is not an error — surface `result.reviewUrl` to the user.
+
+#### Shell actions
+
+```js
+SynapWidget.navigate({ entityId: "entity-uuid" }); // open entity detail in side panel
+SynapWidget.openPanel("entity-detail", { entityId: "uuid" }); // explicit panel open
+SynapWidget.toast("Saved!", "success"); // 'success' | 'error' | 'info'
+SynapWidget.resize(document.body.scrollHeight); // resize the iframe to content height
+SynapWidget.updateContext({ viewId: "uuid" }); // update ambient context
+
+// Subscribe to live entity changes
+SynapWidget.subscribe("entity:changed", ({ entityId }) => {
+  // re-fetch and re-render when any entity in the pod changes
+});
 ```
 
 ### Common Dependency Patterns (esm.sh import map)
 
-```html
-<script type="importmap">
-  {
-    "imports": {
-      "react": "https://esm.sh/react@19",
-      "react-dom/client": "https://esm.sh/react-dom@19/client",
-      "react/jsx-runtime": "https://esm.sh/react@19/jsx-runtime",
-      "recharts": "https://esm.sh/recharts@2.12.0"
-    }
+The `deps` map in `/cells/define` drives the import map. Each key becomes a bare specifier in the `<script type="importmap">`, resolved to `https://esm.sh/<pkg>@<version>`.
+
+```json
+// deps in the define call:
+{ "recharts": "2.12.0", "d3": "7" }
+
+// → generates this importmap inside the frame:
+{
+  "imports": {
+    "react": "https://esm.sh/react@19",
+    "react-dom/client": "https://esm.sh/react-dom@19/client",
+    "react/jsx-runtime": "https://esm.sh/react@19/jsx-runtime",
+    "recharts": "https://esm.sh/recharts@2.12.0",
+    "d3": "https://esm.sh/d3@7"
   }
-</script>
+}
 ```
 
+React 19 core entries are always injected by the host — never put them in `deps`.
+
 Common library choices:
 
-| Category | Packages                                                       |
+| Category | Packages (put in `deps`)                                       |
 | -------- | -------------------------------------------------------------- |
 | Data viz | `recharts@2.12.0`, `d3@7`, `chart.js@4`, `observable-plot@0.6` |
 | Tables   | `@tanstack/react-table@8`                                      |
@@ -925,30 +2233,23 @@ Common library choices:
         background: transparent;
       }
     </style>
-    <script type="importmap">
-      {
-        "imports": {
-          "react": "https://esm.sh/react@19",
-          "react-dom/client": "https://esm.sh/react-dom@19/client",
-          "react/jsx-runtime": "https://esm.sh/react@19/jsx-runtime"
-        }
-      }
-    </script>
+    <!-- importmap is injected by the host from deps — do not write one manually -->
   </head>
   <body>
     <div id="root"></div>
     <script type="module">
       import { createRoot } from "react-dom/client";
+      import { createElement as h, useState } from "react";
 
       SynapWidget.onInit(async ({ context }) => {
-        const items = await SynapWidget.query("list_entities", {
+        const items = await SynapWidget.query("entities.list", {
           profileSlug: "deal",
           limit: 200,
         }).catch(() => []);
 
-        // Build your UI here. Plain DOM or React both work.
-        document.getElementById("root").textContent =
-          `Loaded ${(items ?? []).length} deals`;
+        createRoot(document.getElementById("root")).render(
+          h("p", null, `Loaded ${(items ?? []).length} deals`)
+        );
 
         SynapWidget.resize(document.body.scrollHeight);
       });
@@ -961,10 +2262,13 @@ Common library choices:
 
 - **Always call `SynapWidget.onInit()`** — the host will not send data until you register this handler.
 - **Call `SynapWidget.resize()`** after rendering to prevent clipping.
-- **Handle errors** — `query()` can fail; always `.catch()`.
+- **Handle errors** — `query()` and `mutate()` can fail; always `.catch()`.
+- **Check `result.status` on mutations** — `"proposed"` is governance, not an error; surface `reviewUrl`.
 - **Transparent background** — `background: transparent` on `body` inherits the host surface color.
 - **No external fetch** — the sandbox has no cross-origin access; all data must go through `SynapWidget`.
-- **Inline all styles** — no external CSS imports; CDN JS via import map is fine.
+- **Declare all non-React imports in `deps`** — the host generates the import map from that field.
+
+---
 
 ---
 
@@ -978,3 +2282,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.