@synap-core/cli 1.8.0 → 1.11.0

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,13 @@
+## 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.
+11. **Creating a `file`/`document`-kind entity to hold text you wrote.** A pitch deck, plan, or note body you authored is `content` on a real CONTENT-kind entity (`note`, `knowledge`, a domain kind) — Synap auto-materializes it into a document. `file` is only for real uploaded bytes you actually have; an agent with no filesystem almost never needs it.

package/skills/synap/content-os.md

@@ -0,0 +1,83 @@
+## Content OS — the editorial model
+
+Some workspaces run an editorial engine: `pillar`, `post`, `platform`, `newsletter`, plus the reused `campaign` and `sponsor`. Content OS is a **derived lens**, not a silo — the journey it can reason about is a function of what else exists in the pod. Understand this before proposing posts, pillars, or a content plan.
+
+**The editorial core:**
+
+- **`pillar`** — a recurring theme the audience knows the operator for. Two to four, not twelve. `pillar-status` (Active, Developing, Paused, Retired), `pillar-goal`, `pillar-formats`, `posting-frequency`.
+- **`post`** — the atomic unit. `post-status` moves Idea → Briefed → In Draft → Review → Scheduled → Published → Archived. Plus `post-format`, `post-platform`, `publish-date`, `post-hook`, `post-cta`; measured by `engagement-score` and `post-reach`.
+- **`platform`** — a publishing account (social, newsletter publication, podcast). Carries its own cadence and audience metrics.
+- **`newsletter`** — one issue of the owned channel. `newsletter-status`, `newsletter-pillar`.
+- **`campaign`** and **`sponsor`** — reused from marketing / foundation, not owned here.
+
+**The journey layer (optional, additive):**
+
+- **`journey-stage`** — where a reader is. Each stage names the belief it installs, the doubt it dissolves, and the action that advances them. Unordered _tagging_.
+- **`series`** — an ordered curriculum, prerequisite-bearing: chapter by chapter.
+- **`offer`** — the thing being sold. Owned by the `foundation` workspace, pod-wide. **Frequently absent — see the degradation rule.**
+
+A post joins these through `post-stage`, `post-series`, `post-offer`; a repurposed post points at its source with `derived-from`.
+
+**Two axes, both optional, composable:** CURRICULUM (`series` — ordered, "which chapter is this?") and AUDIENCE STAGE (`journey-stage` — an unordered tag, "where is the reader?"). A post carries at most one of each. With neither, Content OS still works exactly as a post tracker — that is a valid end state, not an incomplete one.
+
+## The degradation rule — check before you assume
+
+Read the world before you reason about it: `list_profiles` tells you the vocabulary actually provisioned, and the `## Pod Domains` block in your context tells you which domains exist.
+
+- **No offer-bearing domain, no `offer` entities** → the journey is pure audience-building. **Do NOT invent commerce.** No CTA to a product that does not exist, no fabricated `offer`, no "book a call" the operator never mentioned. Reason on the curriculum and stage axes and stop there.
+- **`foundation` exists** → bind pillars to its real `audience`, `pain-point` and `positioning` entities rather than inventing personas. A pillar aimed at a persona you made up is worse than a pillar with no audience named.
+- **`journey-stage` / `series` / `offer` absent from `list_profiles`** → this pod runs the plain editorial model. Do not reference those slugs at all.
+
+Absence is information, not a hole to fill.
+
+## Pillars before posts
+
+A creator known for two to four themes compounds; one posting about everything stays noise. If the operator hands you a dozen post ideas but cannot name the themes underneath, surface THAT before filling the calendar. Every post you propose hangs off a pillar — `post-pillar` plus a `belongs_to_pillar` relation. An unpillared post is drift.
+
+## AI behavior — placing a post on the journey
+
+When the operator describes a content idea, propose the post WITH its placement — never a bare title:
+
+```json
+POST /api/hub/entities
+{ "userId": "{userId}", "workspaceId": "{wsId}",
+  "profileSlug": "post",
+  "title": "Why your pricing page loses the sale",
+  "properties": {
+    "post-status": "Idea",
+    "post-format": "Article",
+    "post-platform": "LinkedIn",
+    "post-pillar": "ent_pillar_positioning",
+    "post-stage": "ent_stage_evaluating"
+  }
+}
+
+POST /api/hub/relations
+{ "userId": "{userId}",
+  "sourceEntityId": "ent_post_pricing",
+  "targetEntityId": "ent_pillar_positioning",
+  "type": "belongs_to_pillar"
+}
+```
+
+Omit `post-stage` when no `journey-stage` exists, and omit `post-offer` when no `offer` exists. An empty commercial field is correct; a fabricated one is a defect. Use `derived-from` when the post is a repurpose of an existing one — one idea legitimately becomes a thread, a video, and a newsletter section.
+
+## Gap analysis — proposing the next piece
+
+"What should I write next" is an audit, not a brainstorm:
+
+1. **Read the corpus** — one batched `list_entities` pass over `post` and `pillar`. Never one call per post; that is a cost failure.
+2. **Map it** — each post to its pillar × its stage (or its place in a series). Build the grid before judging it.
+3. **Find the holes** — a pillar with nothing at the earliest stage; a stage every pillar skips; a series that stops mid-curriculum; a pillar whose last post is months old.
+4. **Propose the hole, not a topic** — "Pillar X has nothing that removes the pricing objection" beats "here are ten content ideas". Name the pillar, the stage, the belief to install, and the format.
+5. **Ground it** — a proposed post cites the pillar it serves and, when `foundation` exists, the real `audience` or `pain-point` entity it answers. Otherwise it is a guess dressed as a plan.
+
+Rank gaps by what the operator is actually known for, not what they wish they were known for.
+
+## Resolution discipline — resolve BEFORE you create
+
+Standard resolve-before-create applies (search once, batched, before proposing anything). Domain-specific matching keys: **platforms** resolve on handle or URL, **offers** on name, **pillars** on theme. Never placeholder — no pillar named "General", no `platform` for an account the operator doesn't have, no `offer` invented so a post has something to sell. Every post you propose attaches to at least a pillar; a post with no pillar and no stage is a note, not content.
+
+## Kind vs facets, and governed writes
+
+`sponsor` is a role-profile (`profileKind: role`) — per ENTITY MODEL, resolve the real company first, then `attach_facet`; a sponsoring company is never a second entity, and graph links attach to the parent, not the facet.

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.

package/skills/synap/crm.md

@@ -0,0 +1,117 @@
+## 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.
+
+**The model:**
+
+- **`person` + `company`** — Identity only, no sales state. Persist across deals.
+- **`deal`** — Pipeline record with `dealStage` property (lead, contacted, qualifying, proposal, negotiating, won, lost, inactive). Represents what people often call a "lead" (when stage=lead). Linked to person/company via `linked_to_deal` relation.
+- **`client`** — Post-win relationship marker. Created automatically when deal transitions to stage=won. Status: active, paused, or churned. Linked via `is_client` (party → client) and `produced_by_deal` (deal → client).
+- **`journey`** — Documents anchored to a deal (not a person). Linked via `has_journey`.
+
+**AI behavior — lead capture:**
+
+When the user describes a lead (inbound person, prospect, or company lead), propose the full bundle:
+
+1. Create `person` entity (if not exists) with email, role, company name
+2. Create `company` entity (if not exists)
+3. Create `deal` entity with `dealStage: "lead"` and `estimatedValue` (if known)
+4. Create `linked_to_deal` relation connecting person/company to deal
+
+Never create a person with a sales-state flag. The deal is the lead container.
+
+```json
+POST /api/hub/entities
+{ "userId": "{userId}", "workspaceId": "{wsId}",
+  "profileSlug": "person",
+  "title": "Alice Johnson",
+  "properties": { "email": "alice@acme.com", "role": "VP Engineering" }
+}
+
+POST /api/hub/entities
+{ "userId": "{userId}", "workspaceId": "{wsId}",
+  "profileSlug": "deal",
+  "title": "Acme prospect",
+  "properties": { "dealStage": "lead", "estimatedValue": 50000 }
+}
+
+POST /api/hub/relations
+{ "userId": "{userId}",
+  "sourceEntityId": "ent_person_alice",
+  "targetEntityId": "ent_deal_acme",
+  "type": "linked_to_deal"
+}
+```
+
+**AI behavior — moving deals to won:**
+
+When a deal transitions to `dealStage: "won"`, also propose client creation if not yet linked:
+
+```json
+PATCH /api/hub/entities/ent_deal_acme
+{ "properties": { "dealStage": "won" } }
+
+POST /api/hub/entities
+{ "userId": "{userId}", "workspaceId": "{wsId}",
+  "profileSlug": "client",
+  "title": "Acme (active)",
+  "properties": { "clientStatus": "active" }
+}
+
+POST /api/hub/relations
+{ "userId": "{userId}",
+  "sourceEntityId": "ent_person_alice",
+  "targetEntityId": "ent_client_acme",
+  "type": "is_client"
+}
+
+POST /api/hub/relations
+{ "userId": "{userId}",
+  "sourceEntityId": "ent_deal_acme",
+  "targetEntityId": "ent_client_acme",
+  "type": "produced_by_deal"
+}
+```
+
+**AI behavior — campaign membership:**
+
+When the user describes campaign members (segment for outreach, tracking, or automation), use polymorphic `member_of` relations. Members can be persons, companies, or deals:
+
+```json
+POST /api/hub/relations
+{ "userId": "{userId}",
+  "sourceEntityId": "ent_person_alice",
+  "targetEntityId": "ent_campaign_enterprise",
+  "type": "member_of"
+}
+
+// Same relation type, different entity type
+POST /api/hub/relations
+{ "userId": "{userId}",
+  "sourceEntityId": "ent_deal_acme",
+  "targetEntityId": "ent_campaign_enterprise",
+  "type": "member_of"
+}
+```
+
+**Property names:**
+
+- `dealStage` (not `crmStatus` or `status`) — values: lead, contacted, qualifying, proposal, negotiating, won, lost, inactive
+- `clientStatus` (post-win only) — values: active, paused, churned
+- Identities (person, company) carry no sales state
+
+**Why separate identity from state:**
+
+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.
+
+## 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.

package/skills/synap/diagnostics.md

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

package/skills/synap/digesting-a-channel.md

@@ -0,0 +1,63 @@
+# digesting-a-channel
+
+You are digesting a chat channel — reading a window of human messages and deciding what, if anything, is worth the team's attention. You are an ADVISOR, not a bookkeeper. Surface signal; do not log every message into the database.
+
+## What a digest is for
+
+Read the whole window, then answer one question: **what here genuinely matters to the team?** A decision that got made, an ask with a deadline, a new opportunity, a link worth keeping, a task someone implicitly took on, a shift in a live piece of work. Most channel chatter is noise — greetings, banter, thinking-out-loud. If nothing rises above noise, say so and stop. An honest "nothing to surface" beats a wall of manufactured entities.
+
+## Structure signal into whatever shape actually fits
+
+Do NOT assume this channel is a CRM. Do NOT reach for a contacts/notes/links template by reflex. Look at the signal and pick the Synap shape that truly matches it:
+
+- an **idea** or **decision** — a direction the team settled on, an ask, a scope change
+- a **website / link / resource** worth keeping
+- a **deal** or **partner** — a real new opportunity or relationship (only if that is genuinely what surfaced)
+- a **task** — a concrete next action someone owns, with a due date if one was stated
+- an **advancement on a workflow / playbook** — a stage moved or a step completed on work already live in the pod
+
+`list_profiles` first when you are unsure what shapes exist. Match the signal to the shape; never force the signal into a shape you had already decided on.
+
+## Resolve identity before you create
+
+Every person, company, deal, or resource you are about to propose may already exist. Resolve first, create only what is new. Match on STRONG signals — email, phone, url, handle — not a fuzzy name. Run ONE batched search over all candidates, reuse on match (add the newly-seen handle or spelling as an alias), and mint an entity only for something genuinely absent. The full resolve → reuse → alias discipline in `crm.md` applies here verbatim.
+
+## When the channel is UNBOUND — classify it and PROPOSE a bind
+
+A channel that is **not yet bound to any entity** (no `contextObjectId`, no `branchPurpose`) is a different job from a normal digest. Before you mine it for signal, answer a prior question: **what IS this channel, and which entity does it belong to?** This is the "I think #acme is a client — link it?" affordance.
+
+Work it in this order — identity FIRST, classification, then propose:
+
+1. **Read the window + the channel NAME.** The name (`acme`, `weex-partnership`, `general`, `eng-team`) is often the strongest single signal; the messages confirm or correct it. Who posts, what they talk about, whether it reads client-facing or internal.
+2. **Resolve the entity FIRST — do NOT mint a duplicate.** Match the channel to something that already exists in the pod on STRONG signals — the name, a domain/email/url mentioned, a handle — using `resolve_identity` / a batched search. Only if nothing genuinely matches do you consider a new entity, and even then propose the entity through the normal capture door, never a throwaway. The whole point of binding is to point the channel at the REAL thing; binding to a fabricated duplicate is worse than not binding at all.
+3. **Classify what the channel is** — pick the one that fits:
+   - **client** — a client-facing channel (mixes their people and ours). Suggests `branchPurpose: "client-comms"`.
+   - **partner** — a partner/vendor relationship channel. Suggests `branchPurpose` like `"partner"` (or leave to the human).
+   - **internal team** — everyone here is OUR team; ops/eng/planning. Suggests `branchPurpose: "team"`.
+   - **project** — work-scoped, cross-cutting. Suggests a project-oriented purpose (or `"team"` if internal).
+4. **Emit ONE governed bind proposal** with `propose_channel_bind` — `channelId` (the Synap channel UUID), the resolved `contextObjectId`, and your suggested `branchPurpose` + a one-line `reasoning`. The result comes back `proposed`: that is the system working. You do not bind — the operator confirms.
+
+### The firewall — the one rule you never bend
+
+`branchPurpose: "client-comms"` is **irreversible**. Once a channel is client-comms the backend refuses to reclassify it. So:
+
+- **Only suggest `client-comms` when you are confident the channel is client-facing.** A `general`, `random`, or internal team channel must NEVER be proposed as client-comms — misfiling an internal room as client comms is exactly the mistake the firewall exists to prevent.
+- **When the side is unclear, OMIT `branchPurpose`** and let the human choose on approval. An unbound bind with the purpose left open is fine; a wrong client-comms bind is not.
+- You always PROPOSE. There is no path here where you silently set client-comms. The human owns that decision by approving.
+
+Auto-binding on strong identity signals lives elsewhere; **from this skill you always propose.**
+
+## Role-aware people guard (read this twice)
+
+WHO is in the channel changes what a person IS. Get this wrong and you propose your own teammates as leads.
+
+- **Internal channel** (`branchPurpose` = `team`): every human here is OUR teammate. Never propose a teammate as a client, lead, prospect, or contact. Surface what they DECIDED or COMMITTED to — not who they are.
+- **Client channel** (`branchPurpose` = `client…`): the channel mixes client-side people with our own team who also post there. Separate the two. Only genuine client-side people become the client company's contacts; our teammates in the thread stay teammates and are never attached to the client.
+
+When a person's side is unclear, ask or leave them out — do not guess a client relationship into existence.
+
+## Output
+
+Return a short, scannable digest: the few things worth attention, each with your advice or a status read ("decided X", "Y is waiting on you", "this deal moved to negotiating"). Lead with what matters most; skip the exhaustive recap.
+
+Everything you propose goes through governance — you PROPOSE, you do not force. A `proposed` result is the system working, not a failure. If nothing crossed the bar, a one-line "nothing worth capturing from this window" is the correct and complete answer.

package/skills/synap/document-embeds.md

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