@synap-core/cli 1.8.0 → 1.10.0

package/skills/synap/_order.txt

@@ -0,0 +1,37 @@
+operating-mode.md
+reflexes.md
+escalation-ladder.md
+mental-model.md
+quick-reference.md
+lenses.md
+operating-mode-rules.md
+cli-operations.md
+scope.md
+work-flow.md
+linking-principle.md
+governance-rules.md
+capabilities.md
+writes.md
+document-embeds.md
+creative-loop.md
+graph-gardening.md
+next-action.md
+reading.md
+multi-entity-capture.md
+worked-examples.md
+crm.md
+common-mistakes.md
+inline-patterns.md
+focus-sessions.md
+automations.md
+diagnostics.md
+workspace-design.md
+workspace-edges.md
+more.md
+viewframe-cells.md
+authentication.md
+response-style.md
+recap.md
+showing.md
+user-model.md
+north-star.md

package/skills/synap/_skill.yaml

@@ -0,0 +1,24 @@
+name: synap
+description: >
+  Use this skill whenever the user wants to capture, remember, find, or structure
+  information in their Synap data pod. Triggers: creating a task, note, person,
+  company, project, event, contact, or deal; saving an article or webpage;
+  storing a fact about someone ("Alice prefers async"); searching the user's
+  knowledge ("find my notes on X", "who did I meet last week"); linking entities;
+  logging a meeting or a contact; capturing unstructured text into structured
+  entities; reading what's in the user's pod before answering questions about
+  their life, work, or projects; posting to their personal AI channel. The pod
+  is the user's sovereign source of truth — prefer it over your own context
+  when the user asks about their own data. Do NOT use this skill for extending
+  the schema (use synap-schema) or building dashboards and views (use synap-ui).
+metadata:
+  openclaw:
+    requires:
+      env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
+      optional_env:
+        [SYNAP_WORKSPACE_ID, SYNAP_USER_ID, SYNAP_DEFAULT_CHANNEL_ID]
+    primaryEnv: SYNAP_HUB_API_KEY
+    homepage: https://synap.live
+    capabilities: [memory, knowledge-graph, channels]
+    os: [macos, linux, windows]
+    userInvocable: false

package/skills/synap/authentication.md

@@ -0,0 +1,10 @@
+## Authentication
+
+```
+Authorization: Bearer {SYNAP_HUB_API_KEY}
+X-Workspace-Id:  {workspaceId}            (optional; also pass in body/query)
+
+Scopes:
+  hub-protocol.read   → most GET endpoints
+  hub-protocol.write  → all writes AND GET /channels/personal
+```

package/skills/synap/automations.md

@@ -0,0 +1,264 @@
+# 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"
+    }
+  ]
+}
+```

package/skills/synap/capabilities.md

@@ -0,0 +1,107 @@
+# 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.

package/skills/synap/capture.md

@@ -119,6 +119,14 @@ Response:
 
 The executor goes through governance (see `governance.md`). Expect the same three `status` values.
 
+## Placement — existing lenses only
+
+Capture **never invents a workspace** (or other meta-structure) to "find a home"
+for extracted entities. Route into **existing** workspaces/projects/profiles the
+user already has — orient + list_profiles first when placement is ambiguous.
+Structure emerges progressively: capture into what exists; suggest a new profile only when the user repeatedly tracks a thing that fits none, and a view only once that profile has 3+ entities — never impose schema upfront. Missing structure is an escalation-ladder L2→L3 conversation (discover, then
+propose), not a side effect of capture. See `reflexes.md` / `escalation-ladder.md`.
+
 ## When to use the pipeline vs. manual CRUD
 
 | Situation                                                        | Use                                                 |
@@ -133,6 +141,8 @@ The executor goes through governance (see `governance.md`). Expect the same thre
 
 Rule of thumb: **one intent, one call.** Multi-entity content, use the pipeline.
 
+**Degrade path (MCP `synap_capture`, the single-call door):** when the structuring pipeline fails or finds nothing to extract, it degrades to a single flat note carrying the raw text verbatim — it never drops the input. Use `synap_capture` only for genuinely unstructured input where you don't yet know the entities; if you already know the exact profileSlug and field values, call `synap_create_entity` instead (deterministic, direct write, no degrade path).
+
 ## Dedup within the pipeline
 
 The pipeline does its own duplicate check per entity (by title + profileSlug within workspace). When it finds a match, `action` becomes `"update"` with `existingEntityId` set, so the real entity is updated in place, not duplicated.

package/skills/synap/cli-operations.md

@@ -0,0 +1,107 @@
+## 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 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>               # 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:**
+
+```bash
+synap orient --json
+# Returns: userId, podUrl, workspaces[{id, name, slug}]
+# Never hardcode workspace IDs — discover them here.
+```
+
+**Ask (the one read verb — routes across all substrates):**
+
+```bash
+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:**
+
+```bash
+synap list workspaces --json
+synap list entities --workspace=<id> --json
+synap list entities --profile=task --workspace=<id> --json
+synap get entity <id> --json
+```
+
+**Capturing a decision (the AI structures — it never `note`s):**
+
+```bash
+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
+# 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
+
+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"
+
+# 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
+
+# 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
+```
+
+The bare-ID form calls `GET /api/hub/resolve/:id` to determine the type before dispatching. Use this when you don't know what type a UUID is — `synap open <id>` always works.
+
+**Write:**
+
+```bash
+synap create entity --profile=note --name="Meeting notes" --workspace=<id> --json
+synap set entity <id> --props='{"status":"done"}' --json
+```
+
+**Multi-agent:** If `SYNAP_AGENT` env var is set, the CLI uses that named identity's API key from `~/.synap/config.json` instead of the default pod credentials. Use `synap agents list` to see configured identities.
+
+**Rules:**
+
+- 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 ask` is the one read verb — it routes keyword + semantic + procedural automatically; you never choose a search backend.
+
+---

package/skills/synap/common-mistakes.md

@@ -0,0 +1,12 @@
+## 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.
+3. **Using the deprecated `type` field.** Always `profileSlug`.
+4. **Treating `"proposed"` as an error.** It's a governance queue.
+5. **Forcing `source` to bypass governance.** Governance is determined by the agent user + whitelist, not by `source`. Don't set it.
+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.

package/skills/synap/creative-loop.md

@@ -0,0 +1,43 @@
+## 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.