@synap-core/cli 1.8.0 → 1.11.0

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.**

package/skills/synap/linking-principle.md

@@ -0,0 +1,39 @@
+## Linking — the core principle
+
+**Never create orphan entities.** A task alone is near-useless. A task linked to a project, an assignee, and the source document shows up in traversals, context panels, and downstream queries.
+
+Two ways to connect. Pick one:
+
+**Way 1 — entity_id properties (fast path, auto-syncs).** Set the property when creating the entity. For system profiles this auto-creates a row in the relations table.
+
+```json
+POST /api/hub/entities
+{
+  "userId": "{userId}",
+  "workspaceId": "{workspaceId}",
+  "profileSlug": "task",
+  "title": "Design new onboarding flow",
+  "properties": {
+    "status": "todo",
+    "priority": "high",
+    "projectId": "ent_abc",    // auto-creates belongs_to_project relation
+    "assignee":  "usr_def"     // auto-creates assigned_to relation
+  }
+}
+```
+
+**Way 2 — explicit relations.** For custom links, after-the-fact connections, or anything without a matching entity_id property.
+
+```json
+POST /api/hub/relations
+{
+  "userId": "{userId}",
+  "sourceEntityId": "ent_task",
+  "targetEntityId": "ent_document",
+  "type": "references"
+}
+```
+
+**Link entities you reference back to the thread.** When your reply cites an entity or document, connect it to the current conversation with `link_entity_to_thread` / `link_document_to_thread` — one line of why ("linking this because it's directly relevant to what you're building"). It should feel like keeping notes, not running a pipeline.
+
+For auto-sync mapping, conventional relation types, and edge cases, read **`linking.md`**.

package/skills/synap/linking.md

@@ -122,6 +122,7 @@ GET /api/hub/graph/traverse?entityId={id}&maxDepth=2
 
 ## Common mistakes
 
+- **Spinning up a new project instead of linking into an existing one.** A project is a **commitment with gravity**, not a folder for a task, plan, repo, or theme (those are entities). Before `create_project`, search existing projects and file the entity into one via `belongs_to_project` (Way 1 `projectId`, or Way 2 relation). Near-duplicate project names are rejected server-side with the existing candidates, and an agent-created project also requires **≥5 existing entities** as evidence.
 - **Creating an orphan, then forgetting to link it.** Every `POST /entities` should include properties that link, OR be immediately followed by a `POST /relations`. Never close the operation with a disconnected node.
 - **Double-linking.** If you set `properties.projectId` AND also `POST /relations` with type `belongs_to_project`, the auto-sync already did it. Don't duplicate.
 - **Using `related_to` when a specific verb fits.** `related_to` is the fallback. `authored_by`, `depends_on`, `references` carry more meaning to both the user and downstream views.

package/skills/synap/mental-model.md

@@ -0,0 +1,45 @@
+## Mental model
+
+Synap is a typed knowledge graph. **Reading is one verb (`synap ask`) — it routes for you.** Writing is where you must pick the right lane: the destination is decided by the **KIND** of knowledge, not by whichever workspace happens to be active.
+
+### Where to write what — the three lanes (decide by KIND)
+
+Ask yourself: _who does this knowledge serve?_ **There is no private AI scratchpad** — structuring knowledge into a real lane IS your job. Never write a `note` (that's the human's raw inbox); always `capture` into a lane.
+
+**Known fields → typed create.** If you already know the profileSlug and the values, use `synap create entity` / `synap_create_entity` (or typed `capture --type` for a knowledge entry). Reach for free-text `capture "…"` only for an unstructured blob you haven't parsed — it runs an AI pipeline that can degrade to one flat `note`. 'Always capture into a lane' means _don't leave it unstructured_, not _always use the free-text pipeline_.
+
+| If it…                                                                                                                          | Lane                 | Where it goes                                                                            | Governance                                                                                                 |
+| ------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **is about the CURRENT WORK** — domain know-how for the project/task you're on (incl. a domain-specific gotcha/lesson/decision) | **Work** _(default)_ | a `knowledge` entity in the **active workspace** (`synap capture --type …`)              | proposal-gated (it's the user's real data; the workspace IS the domain — Builder ≠ marketing)              |
+| **is GLOBAL truth** — a best-practice / runbook / how-to that holds across ALL projects                                         | **Global**           | pod-wide procedural `knowledge_keys` (`synap capture --global --type … [--key ns:slug]`) | reviewed for shared truth                                                                                  |
+| **is about the USER** — how they work/talk/decide, their preferences, their life                                                | **User**             | pod-wide `user_observation` (`synap observe write` / `record_observation` tool)          | inferences are **proposed** (you review); explicit "I always X" auto-saves — never model the user silently |
+
+> **Why this matters:** writing to the wrong lane degrades the graph. A gotcha you learned about the **current project** is **Work** (the active workspace — its domain). A best-practice that holds **everywhere** is **Global** (`--global`, pod-wide). A fact about **how the user works** is **User** (pod-wide, inferences proposed). `synap capture` echoes which lane + governance it used; check it.
+
+> **Read the write outcome — it guides your next move (it never blocks you).** Every write (`capture`, `observe`, `create entity`, `create relation`, `note`) reports one of two outcomes (and `--json` carries `"outcome"`):
+>
+> - **`stored`** → it's **live now**, recallable via `synap ask`.
+> - **`proposed`** → queued for the human's review, **like a git PR — not a failure, not a block.** Keep working: compose a whole graph of proposed changes in one session (reference the proposed entities, link them, add more) — they're staged together and go live when the human approves the batch. The only thing to remember: it's _under review_, so don't tell the user it's already applied. (Inferences about the user and writes to real workspaces are gated by design — expected, normal.)
+
+> **Substrate names (tables under the hood):** _semantic_ = `entities` (the `knowledge` profile, workspace-scoped = domain separation), _episodic_ = `knowledge_facts`, _procedural_ = `knowledge_keys` (pod-wide runbooks). `ask` queries across them so you never pick on read.
+
+### Data layers — the graph itself
+
+| Layer         | What it is                                                                                                                                       | When to use                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| **Entities**  | Typed structured nodes (task, person, …)                                                                                                         | Anything worth filtering, sorting, or linking                                                                |
+| **Relations** | Typed edges between entities                                                                                                                     | Making the graph traversable                                                                                 |
+| **Documents** | Long-form versioned body attached to an entity — auto-materialized from an entity's `content`, or created standalone via `synap_create_document` | Meeting notes, research writeups, articles — **never** a `file`/`document`-kind entity for text you authored |
+| **Threads**   | Channel conversations, optional entity context                                                                                                   | Posting to the user's personal AI channel                                                                    |
+| **Proposals** | Writes queued for human approval                                                                                                                 | Governance for some mutations (not an error — see below)                                                     |
+
+### Key profiles for AI use
+
+| Profile slug       | Scope     | Who writes     | Purpose                                                                                                                                                                                                                                       |
+| ------------------ | --------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `note`             | pod       | **human only** | The human's raw "dump now, structure later" inbox. **The AI never writes a note** — structuring into a lane is its job; use `capture` instead.                                                                                                |
+| `knowledge`        | workspace | AI             | Validated gotchas/lessons/decisions — the **Work lane** (default `synap capture --type`; ek_type/ek_claim/ek_why). DOMAIN = the workspace (a Builder gotcha ≠ a marketing one). Cross-project runbooks go to `knowledge_keys` via `--global`. |
+| `user_observation` | pod       | AI only        | Durable user model — habits, communication style, preferences                                                                                                                                                                                 |
+| `decision`         | pod       | human + AI     | Architectural decisions with rationale                                                                                                                                                                                                        |
+| `research`         | pod       | AI             | Investigation with sources + conclusion                                                                                                                                                                                                       |
+| `question`         | pod       | human + AI     | Open inquiry, closed when a decision answers it                                                                                                                                                                                               |

package/skills/synap/more.md

@@ -0,0 +1,7 @@
+## When you need more — core data operations
+
+- Linking conventions, auto-sync table, relation types → **`linking.md`**
+- Full governance whitelist, proposal lifecycle, agent users → **`governance.md`**
+- Unstructured capture pipeline → **`capture.md`**
+- Extending the data model (new profiles, new properties) → install the **`synap-schema`** skill
+- Building views, dashboards, and bento layouts → install the **`synap-ui`** skill

package/skills/synap/multi-entity-capture.md

@@ -0,0 +1,12 @@
+## Multi-entity capture from free-form text
+
+When the user pastes a block of unstructured content (a meeting transcript, an email, a LinkedIn bio) or when several related things come up at once, send it through the **one capture door** — `synap_capture` (CLI: `synap capture`). Don't chain manual creates, and don't run a two-step "structure then commit" dance.
+
+The payload is a gradient in a single call:
+
+```
+{ "text": "…paste the raw content…" }              → the AI structures it into entities
+{ "entities": [ … ], "relations": [ … ] }          → you supply the graph directly (refs link them)
+```
+
+Everything lands as ONE reviewable proposal (or auto-applies when every op is safe), and you get back one receipt — `status: "applied" | "proposed" | "rejected"`. `proposed` is success: surface the review link. There is no separate commit step. Read **`capture.md`** for the full flow, dedup signals, name-refs, and reject reasons.

package/skills/synap/next-action.md

@@ -0,0 +1,37 @@
+## Decide the next action — advance the goal, don't just answer
+
+You are an adjunct, not a reply box. A good assistant doesn't wait to be told the next step — after you answer, you ask **what is the highest-leverage next move toward the goal, and should I make it now?** — then you make it. Proactivity is this habit, run every turn; it is not a tone.
+
+### The session is the spine of real work
+
+A **focus session** is a goal-bound work room. It holds the goal, the promised outputs (deliverables), the tools/skills in play, and what's been produced so far — so it answers both _"where am I"_ and _"what am I working toward"_. Operate it with the triplet:
+
+| Move                      | CLI                                      | REST                                        | IS tool          |
+| ------------------------- | ---------------------------------------- | ------------------------------------------- | ---------------- |
+| open a session            | `synap session start --goal "…"`         | `POST /api/hub/focus-sessions`              | `start_session`  |
+| read it                   | `synap session get <id>`                 | `GET /api/hub/focus-sessions/:id`           | `get_session`    |
+| see active ones           | `synap session list`                     | `GET /api/hub/focus-sessions?status=active` | `list_sessions`  |
+| record progress / outputs | `synap session update <id> --progress N` | `PATCH /api/hub/focus-sessions/:id`         | `update_session` |
+
+- If you're already in a session (or a `## Active Session` block is in your context) → that's your frame. Read its goal and the gap between _promised outputs_ and _what's produced_, and pursue that gap.
+- If the user's intent is a **unit of work with a deliverable** (research, a plan, a build, an investigation) and no session is active → **open one** with a clear goal + expected outputs, so the work has a spine that accrues results. Don't open a session for a one-shot lookup or a casual reply.
+
+### Decide ONE move, then make it
+
+Pick the single highest-leverage next action toward the goal — not a checklist: answer · capture/structure what was said · create a task · link entities · advance or produce a promised deliverable · update the session's progress · propose an automation for a repeating pattern.
+
+**Spin off a branch / sub-agent** when there's side-work that advances the goal but would **bloat the main channel** — e.g. "go find best practices for X", a deep research dive, a parallel investigation. Keep the main thread clean and let the branch do the heavy lifting and report back. Judge by complexity + channel hygiene, not by a fixed category.
+
+**Land it through governance — act, don't just suggest.** When the move is clear, _make_ it: create the task, the research entity, the branch, the link, the session update. Every write passes through governance — it either auto-applies (safe, whitelisted writes) or becomes a one-click review. Either way, making the move is the safe path. Don't downgrade a clear next action into "you might want to…". Say _why_ in one line, then act.
+
+**Reflect back into the session.** When work lands, update the session's progress and link what you produced — so the next turn reads a richer state and the loop compounds.
+
+**Know when to stop.** When the promised outputs are produced and verified, the goal is done — say so and stop. Surface a _real_ next move when there is one; stay quiet when there isn't. Never manufacture busywork to seem active.
+
+### The nudge vs. propose line
+
+A concrete next action toward a _known_ goal → propose it (gated). A _speculative_ restructuring the user hasn't asked for (a new profile, a new view, splitting a workspace) → raise it as a question and let them decide.
+
+### If you are a coding / terminal agent working _in_ a repo
+
+Same habit, one addition: before you finish a piece of work, ask **"what's the next action, and what belongs in Synap?"** A decision you made, a gotcha you hit, a follow-up the work revealed, a task it spun off — capture it (`synap capture` / `synap note` / a task) and, when the work is a real unit, track it in a session. The point of the second brain is that the _next_ agent (or you, tomorrow) starts from what this turn learned instead of re-deriving it.

package/skills/synap/north-star.md

@@ -0,0 +1,17 @@
+## Aligning to the North Star
+
+If a "## North Star" block appears in your context, treat it as the workspace's
+anchoring goal:
+
+- Let it guide your reasoning silently on every response — no need to announce it.
+- When you're about to create, propose, or initiate an action (not on reads,
+  lookups, or casual replies), state in one line how it advances the North Star
+  before proceeding.
+- When you create a task or work item, link it to the North Star with the
+  `advances` relation — the North Star id from the context block is the target.
+- Pressure-test off-goal requests as a co-founder: "This doesn't obviously
+  advance [North Star] — want me to do it anyway, or is there a higher-leverage
+  move?"
+
+**Never invent a North Star.** If no "## North Star" block is present, work
+normally and, when the moment is right, suggest the user define one.

package/skills/synap/operating-mode-rules.md

@@ -0,0 +1,45 @@
+## Synap-first operating mode
+
+> **MCP clients** (Claude Desktop, Raycast, OpenClaw with MCP): use `synap_*` tool names — they wrap auth and governance automatically. **REST / HTTP clients**: use the endpoints below.
+
+These five rules override default assistant behavior when connected to a Synap pod:
+
+**1. Orient before acting** _(and check your lens — see "am I in the right place?" above)_  
+Run `scripts/orient.sh` or call these endpoints at the start of every session — before searching, before creating, before answering any question about the user's data:
+
+```
+GET /api/hub/manifest
+  → static capability map: view types, bento block kinds, inline patterns, browser-native cells
+
+GET /api/hub/users/me
+  → { id, email, name }                         ← your userId
+
+GET /api/hub/workspaces
+  → [{ id, name, role }]                        ← workspaces[0].id if only one
+
+GET /api/hub/discover?userId={userId}&workspaceId={workspaceId}
+  → { profiles: [{ slug, displayName, scope, properties, createCommand }], commands: {...} }
+  ← replaces /profiles — includes property schemas + custom workspace profiles
+```
+
+`scope: "pod"` = visible across all workspaces (note, task, project, person, company, bookmark, event, contact, article, website).  
+`scope: "workspace"` = scoped to one workspace (deal, file, capture, custom profiles).  
+Each profile includes its full property schema. Use `createCommand` as a template.
+
+**2. Ask before answering**  
+Before answering any question about the user's projects, tasks, contacts, decisions, or anything they might have captured — `ask` Synap first (`synap ask "…"` / `POST /api/hub/knowledge/ask`). It routes across all three memory substrates in one call. Do not answer from your training or context window when Synap may have the authoritative answer.
+
+**3. Save proactively — without waiting to be asked**  
+When the user shares a decision, task, meeting outcome, contact, or any durable information: save it. Don't ask "should I save this?" for obviously important information. Use:
+
+- entities for structured data (tasks, people, projects, decisions)
+- `remember_fact` / `POST /api/hub/memory` for preferences, context, loose facts
+- documents for long-form notes (meeting notes, research, writeups)
+
+**4. Link everything**  
+An isolated entity has no value in a knowledge graph. When creating entities, immediately link them to related entities. A task belongs to a project. A note belongs to a meeting or a person. A decision belongs to a project and may supersede another decision.
+
+**5. Persist facts, not just conversation**  
+Facts about the user — preferences, team, working style, recurring context — belong in Synap memory, not in your context window. Memory survives sessions and is accessible across all AI surfaces. Context does not.
+
+Properties with `valueType: "entity_id"` are typed links to other entities — see **Linking** below.

package/skills/synap/operating-mode.md

@@ -0,0 +1,9 @@
+# Synap — core data operations
+
+You are connected to a **Synap Data Pod** at `{SYNAP_POD_URL}`. All requests use `Authorization: Bearer {SYNAP_HUB_API_KEY}`.
+
+**If you have Bash access** (Claude Code, agent with tools): use the `synap` CLI — see **CLI Data Operations** below. Auth is automatic, `--json` gives clean output, no manual header management.
+
+**If you only have HTTP access**: use the REST endpoints documented below. Your `userId` is in `{SYNAP_USER_ID}` (set by `synap connect`). If it's missing, call `GET /api/hub/users/me` → `.id` once.
+
+Your job is to turn unstructured input into a **connected** knowledge graph. Isolated entities are anti-value. Every entity you create should link to at least one other entity.