@synap-core/cli 1.8.0 → 1.10.0

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,38 @@
+# 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.
+
+## 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`.

package/skills/synap/escalation-ladder.md

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

package/skills/synap/focus-sessions.md

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

package/skills/synap/governance-rules.md

@@ -0,0 +1,64 @@
+## Writing — governance in one paragraph
+
+Every write returns a `status` field:
+
+```
+"approved"  → done, use { id }
+"proposed"  → queued for user approval; response also carries { proposalId, summary, reasoning, reviewPath, reviewUrl } — surface the link
+"denied"    → blocked, explain reason to user
+```
+
+**`"proposed"` is not an error.** It's the governance system queueing your change. When you get it:
+
+1. Tell the user exactly what was queued — use the `summary` field **verbatim**. Don't paraphrase.
+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: 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`**.

package/skills/synap/governance.md

@@ -16,7 +16,7 @@ Every write endpoint returns a `status` field. Handle all three.
   "summary":    "Delete task \"Q2 plan review\"",
   "reasoning":  "Destructive actions require your approval",
   "reviewPath": "/proposals/prp_…",
-  "reviewUrl":  "https://studio.synap.live/proposals/prp_…",
+  "reviewUrl":  "synap://open/proposal/prp_…",
   "message":    "…"
 }
   → Queued for user review. Surface `summary` + `reviewUrl` to the user; do not retry.
@@ -145,15 +145,15 @@ When a write is proposed, surface three things to the user: what was queued, why
 ```
 good: "I queued **Delete task \"Q2 plan review\"** for your review.
        Destructive actions need your approval.
-       https://studio.synap.live/proposals/prp_abc"
+       synap://open/proposal/prp_abc"
 
 good: "I queued **Create entity \"Acme Corp\"** for your review.
-       https://studio.synap.live/proposals/prp_def"
+       synap://open/proposal/prp_def"
 
 good: "Queued 3 changes for your review — I'll post the links after each:
-       1. https://studio.synap.live/proposals/prp_1 — Delete task "X"
-       2. https://studio.synap.live/proposals/prp_2 — Delete task "Y"
-       3. https://studio.synap.live/proposals/prp_3 — Delete task "Z""
+       1. synap://open/proposal/prp_1 — Delete task "X"
+       2. synap://open/proposal/prp_2 — Delete task "Y"
+       3. synap://open/proposal/prp_3 — Delete task "Z""
 
 bad:  "Error: write was not approved."
 bad:  "Something needs your attention in Synap."        ← too vague

package/skills/synap/graph-gardening.md

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

package/skills/synap/inline-patterns.md

@@ -0,0 +1,38 @@
+## AI Inline Patterns — reference entities in your replies
+
+When the user is interacting with Synap's AI Companion (the in-browser chat panel), you can embed **inline chips** directly in your reply text. These render as clickable buttons the user can tap to open entities, views, or documents without leaving the conversation.
+
+### Syntax
+
+| Pattern                      | Renders as                  | Effect                            |
+| ---------------------------- | --------------------------- | --------------------------------- |
+| `[[entity:UUID\|Name]]`      | Purple entity chip          | Opens entity detail in side panel |
+| `[[view:UUID\|Name]]`        | Blue view chip              | Opens view                        |
+| `[[open:side\|view:UUID]]`   | Amber "Open in side" button | Opens view in side panel          |
+| `[[open:main\|view:UUID]]`   | Amber "Open" button         | Opens view in main panel          |
+| `[[open:side\|entity:UUID]]` | Amber "Open in side" button | Opens entity in side panel        |
+| `[[run:UUID\|Label]]`        | Green "Run" button          | Navigates to automation entity    |
+| `[[doc:UUID\|Name]]`         | Gray doc chip               | Opens document                    |
+
+### Rules
+
+- **Always use real IDs.** Never hallucinate UUIDs. Only emit patterns for entities/views you just created or retrieved via Hub Protocol.
+- **Emit after creation.** When you create a view or entity, immediately reference it: `"Created your pipeline → [[view:abc123|Active Tasks]]"`
+- **Prefer side panel.** Use `[[open:side|view:UUID]]` so the user keeps their current context.
+- **Only in Companion replies.** These patterns are silently ignored in non-companion channels, documents, and memory. Do not use them there.
+- **Combine with prose.** Don't lead with a chip — embed it naturally: `"Here are your open deals → [[view:xyz|Deals Pipeline]] · [[open:side|view:xyz]]"`
+
+### Proposals
+
+There is no `[[open:…|proposal:…]]` chip — `open`'s `resourceType` only accepts
+`entity`, `view`, `doc`, `cell`, `channel`. A proposal is not one of those, so
+never invent that form.
+
+When a write returns `status: "proposed"`, the response also carries a
+`reviewUrl` (a full Synap Studio URL). Surface it as a plain markdown link, and
+add one sentence explaining why the write was proposed instead of auto-applied:
+
+> Queued the task deletion for your review — destructive actions always need approval: [Review proposal](https://pod.example.com/proposals/prp_abc)
+
+`"proposed"` is normal, not an error — don't apologize for it or wait for the
+user to approve before continuing the conversation.

package/skills/synap/lenses.md

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