@synap-core/cli 1.8.0 → 1.11.0

package/skills/synap/worked-examples.md

@@ -0,0 +1,74 @@
+## Worked examples
+
+### Example 1 — "Remind me to send the proposal to Acme on Friday"
+
+1. Search for the Acme entity: `GET /entities?q=Acme&profileSlug=company` → got `ent_acme`
+2. Search for an existing task: `GET /entities?q=proposal&profileSlug=task&workspaceId=…` → none
+3. Create the task with links:
+
+   ```json
+   POST /api/hub/entities
+   { "userId": "{userId}", "workspaceId": "{wsId}",
+     "profileSlug": "task",
+     "title": "Send proposal to Acme",
+     "properties": {
+       "status": "todo", "priority": "high",
+       "dueDate": "2026-04-24"
+     }
+   }
+   ```
+
+4. Link to Acme (Acme is not an entity_id property on task — use Way 2):
+
+   ```json
+   POST /api/hub/relations
+   { "userId": "{userId}",
+     "sourceEntityId": "ent_new_task",
+     "targetEntityId": "ent_acme",
+     "type": "related_to" }
+   ```
+
+5. Confirm: "Task created and linked to Acme, due Friday."
+
+### Example 2 — "Who's Sarah at Acme?"
+
+1. Search person: `GET /entities?q=Sarah&profileSlug=person` → `ent_sarah`
+2. Pull her connections: `GET /entities/ent_sarah/connections` → company=Acme, 3 recent emails, 1 meeting
+3. Answer from the returned data, not from your own context.
+
+### Example 3 — "Save this article for later: https://…"
+
+1. Search for existing bookmark: `GET /entities?q=<url>&profileSlug=article` → none
+2. Create an article entity:
+
+   ```json
+   POST /api/hub/entities
+   { "userId": "{userId}", "workspaceId": "{wsId}",
+     "profileSlug": "article",
+     "title": "<page title>",
+     "properties": { "url": "<url>", "domain": "<host>" }
+   }
+   ```
+
+3. If the user said why ("interesting for the onboarding project"), also create a relation to that project — never drop the reason as a plain comment, turn it into a link.
+
+### Example 4 — "Write up a strategic plan for the Q3 launch"
+
+You are authoring this text yourself — it is not a file you have. Don't create
+a `file`/`document`-kind entity and stuff the Markdown into it.
+
+1. Search for an existing plan: `GET /entities?q=Q3 launch&profileSlug=knowledge&workspaceId=…` → none
+2. Create a CONTENT-kind entity carrying the plan as `content` (the doc auto-materializes):
+
+   ```json
+   POST /api/hub/entities
+   { "userId": "{userId}", "workspaceId": "{wsId}",
+     "profileSlug": "knowledge",
+     "title": "Q3 launch strategic plan",
+     "properties": { "ek_type": "reference" },
+     "content": "# Q3 Launch Plan\n\n## Goals\n…\n\n## Timeline\n…"
+   }
+   ```
+
+3. Link it to the relevant project: `POST /api/hub/relations` `{ sourceEntityId: "ent_new_plan", targetEntityId: "ent_project_q3", type: "related_to" }`.
+4. Confirm: "Plan captured and linked to Q3 launch." No upload, no `file` entity, no separate `synap_create_document` call.

package/skills/synap/workspace-design.md

@@ -0,0 +1,45 @@
+## Workspace design — is this concern a WORKSPACE, or something smaller?
+
+Before you create a workspace, run the decision rule. A workspace (an operational **domain**) is the heaviest structure in the pod — it owns kinds, confers roles, carries its own team and automations. Most new concerns are NOT domains; they are a **hat**, an **initiative**, or a **stage**. Creating a workspace for one of those is the anti-pattern that fragments the graph. Decide first, then create.
+
+## The decision rule — a concern earns a workspace ONLY if ALL FOUR hold
+
+1. **Owns kinds** — it is source-of-truth for a noun nothing else owns (CRM owns `person`/`company`; Operations owns `engagement`/`deliverable`). If it only _reads_ or _annotates_ another domain's kinds, it is not a domain.
+2. **Own team** — a distinct set of operators/collaborators works it (separation of _who_, not just _what_).
+3. **Native automations/tools** — it runs behavior its neighbors don't (its own capabilities, playbooks, triggers).
+4. **Stable** — it persists across clients and campaigns. If it is per-client or per-campaign, it is time-bound, not a domain.
+
+**All four, or it is not a workspace.** Then fork it to the right lighter structure:
+
+| If the concern is…                                          | It is a…       | Substrate                              | Example                                     |
+| ----------------------------------------------------------- | -------------- | -------------------------------------- | ------------------------------------------- |
+| a **role/hat** an existing entity wears in a domain         | **Facet**      | `attach_facet` (`profileKind: "role"`) | `client`, `sponsor`, `prospect`, `investor` |
+| a **cross-cutting, time-bound initiative** spanning domains | **Project**    | `create_project` (a lens)              | a campaign, an engagement, a launch         |
+| a **stage/filter WITHIN a domain**                          | **State/View** | a `status` property def + a view       | pipeline stage, "active"/"archived"         |
+
+## The decision procedure (follow in order)
+
+1. **Name the source-of-truth noun.** What kind would this workspace _own_ that no existing workspace owns? Run `list_profiles` — if the noun already lives in another domain, you have a facet or a project, not a domain. STOP.
+2. **Test all four conditions.** Owns kinds AND own team AND native automations AND stable. Any one fails → fork below.
+3. **If it's a hat** (a status/role on an entity that already exists elsewhere) → resolve the entity, `attach_facet`. Never a workspace, never a second entity.
+4. **If it's time-bound work across domains** → `create_project` and set it as the lens; the work files into it from whatever workspace holds the data. **A project is a COMMITMENT WITH GRAVITY** — a real initiative that ties work together (a campaign, an engagement, a client, a launch). Tasks, plans, repos, themes, and topics are **entities**, never projects. Before you create one: (a) **search existing projects first** (`synap orient` / `GET /api/hub/projects`) and prefer **linking into an existing project** via `belongs_to_project` — near-duplicate names are rejected with the existing candidates; (b) an agent-created project must cite **≥5 existing entities** that would belong to it as `evidenceEntityIds` — the backend rejects a project with no gravity and tells you to store it as an entity or reuse an existing project instead; (c) **never create a project for the pod owner's own company** — the company _is_ the pod, not a project inside it.
+5. **If it's a stage inside a domain** → add a `status` property def (`create_property_def`) and a view; don't split the stage into its own space.
+6. **Only if all four held** → **template first** (escalation ladder L3):
+   `market.search({query, kind: "template"})` and propose install of a matching
+   template before freehand `create_workspace`. Freehand create is last resort
+   and always proposed — a deliberate move, offer it to the user (see
+   `lenses.md`). Then declare how it lives in the graph (see `workspace-edges.md`).
+
+## The CRM corollary — the load-bearing example
+
+Operational state — **prospect → client → delivered** — is a **FLOW across domains**, expressed as **facets + a triggered project**, NEVER as workspaces and NEVER by bolting delivery onto the identity domain.
+
+- CRM = **who** (owns `person`/`company`, confers the `lead`/`client` facets).
+- Operations = **what we do for them** (owns `engagement`/`contract`/`deliverable`).
+- The bridge: attaching the `client` facet in CRM **triggers** an engagement project in Operations (see the _triggers_ edge in `workspace-edges.md`).
+
+Bolting delivery-ops onto CRM was the anti-pattern: it made one workspace own two unrelated source-of-truth concerns and blurred _who_ the entity is with _what work_ is happening. Split by ownership; bridge by facet + trigger.
+
+## Why this matters
+
+A workspace is a boundary; a facet/project/state is a connection. Boundaries fragment the graph — they should be rare and earned. When you catch yourself about to create a workspace, check the four conditions: nine times out of ten the honest answer is a facet on an entity that already exists, a project that spans what's already there, or a status field on a kind you already own.

package/skills/synap/workspace-edges.md

@@ -0,0 +1,49 @@
+## Workspace edges — how a domain LIVES IN THE GRAPH
+
+A workspace is never an island. Before you create one (or reason about an existing one), map its **edges**: what it consumes, what it provides, what it triggers, what subject it shares, what spans it. Domains are wired together by a small, fixed taxonomy — and each edge type maps to a specific substrate. Knowing the taxonomy is what lets you reason about a new domain's _position_ instead of dropping it in disconnected.
+
+> The two graphs are orthogonal. This is the **data-flow graph** (what reads/writes/triggers what) — the one we model. The **org graph** (who owns/operates a domain) is workspace membership only. "Comms contains Marketing" is org; the _data_ edge is "Marketing **consumes** Comms' brand." Keep them separate so a team reorg never rewires the data graph.
+
+## The four edge types (and their substrate)
+
+| Edge                    | Meaning                                          | Direction | Substrate                                                     | Example                                               |
+| ----------------------- | ------------------------------------------------ | --------- | ------------------------------------------------------------- | ----------------------------------------------------- |
+| **Provides / Consumes** | a domain _reads_ another's data (read redirect)  | A ← B     | `defaultSources` / `sourceRoles` on the consuming workspace   | Content **consumes** Comms' voice/ICP                 |
+| **Triggers**            | an event in A causes _work written_ into B       | A ⇒ B     | automation + `resolveWorkspacePlacement` (run-in-A → write-B) | a `client` facet in CRM ⇒ an engagement in Operations |
+| **Shares subject**      | the same atom wears a different facet per domain | A ⟷ B     | `entity_facets` (one entity, per-domain roles)                | one company is `lead` in CRM, `client` in Ops         |
+| **Spans**               | a time-bound initiative crosses domains          | A—B—C     | `projects` (a cross-cutting lens)                             | one campaign spans Marketing + Content + Social       |
+
+Read the whole graph as: **Provides/Consumes** = the read wiring · **Triggers** = the write/event wiring · **Shares subject** = shared identity · **Spans** = shared initiative.
+
+## Reason about position BEFORE you create
+
+When `workspace-design.md`'s rule says "yes, this is a domain," don't stop at creating it — place it in the graph:
+
+1. **What does it consume?** Which existing domains' data does it read? Those become its `defaultSources` (provides/consumes edges).
+2. **What does it provide?** Which domains will read _its_ output? (Declared on the consumer's side, but know the answer.)
+3. **What does it trigger — and what triggers it?** Which facet/event in a neighbor should spin up work here, or here into a neighbor? That's the automation + placement wiring (Wave 2 processor behavior).
+4. **What subject does it share?** Which atoms already exist elsewhere that this domain will confer a new facet on? (Resolve identity first, `attach_facet` — never a duplicate.)
+5. **What projects span it?** Which cross-cutting initiatives will pull its data alongside other domains'?
+
+A domain that consumes nothing and provides nothing is a smell — re-check the decision rule; it may be a facet or a project after all.
+
+## Declaring provides/consumes on an existing workspace
+
+Edges used to be settable only at template-authoring time or through the tRPC UI. The agnostic door for setting them on a live workspace is the governed MCP tool **`synap_declare_workspace_source`** (Hub REST: `PATCH /workspaces/:id/source-edges`): it merges `defaultSources` / `sourceRoles` on an existing workspace so the generic edge-resolver can redirect its reads to the providing domain, and it materializes the `feeds` link the placement ladder reads.
+
+- Use it when a domain should start reading another's data (e.g. point Marketing at Comms for brand/ICP).
+- It is a **governed write** — a `{ status: "proposed", proposalId }` response is NORMAL, not an error. Because declaring an edge rewires where the pod's cross-workspace reads land, it goes through review: when you (an agent) call it, it is **proposed for a human to approve**, and the edge only goes live on approval (the `workspace/declare_source` proposal executor then runs the same merge). Tell the user it's **proposed for review** and share the review link — don't claim the edge is already live. (An operator calling it directly with their own authority applies immediately and gets `{ status: "updated" }`.)
+- Setting the edge is what makes cross-workspace reads resolve generically, instead of each domain re-deriving its sources by hand.
+
+## The reference wiring (worked example)
+
+The 6-domain reference enterprise, read as edges:
+
+- **Communication** owns voice/narrative/ICP/assets — _provides_ → Marketing, Content.
+- **Content** owns asset/carousel/video — _consumes_ Comms; _provides_ → Social, Marketing.
+- **Marketing** owns campaign/funnel — _consumes_ Comms + Content; _provides_ brief → Social; ⇒ _triggers_ leads → CRM.
+- **Social** owns channel/post/schedule — _consumes_ Content + Marketing; _provides_ signals → Marketing/CRM.
+- **CRM** owns person/company, confers `lead`/`client` — _consumes_ Social signals; `client` facet ⇒ _triggers_ → Operations.
+- **Operations** owns engagement/contract/deliverable — _consumes_ CRM; delivery proof ⇒ _feeds_ → Content/Marketing.
+
+Every arrow above is one of the four edge types. That is the whole model: name the arrows, pick the substrate, wire it — then the domain is a citizen of the graph, not an island.

package/skills/synap/writes.md

@@ -0,0 +1,213 @@
+## Core writes
+
+**Two write doors, one gradient.** `create_entity` is for exactly ONE
+fully-structured, typed entity you already have. For anything unstructured,
+several entities, or a graph — or **when in doubt** — use the capture door
+(`synap_capture`, see `capture.md`): precision comes from sending more structure
+in the SAME call, never from picking a different tool or a second commit step.
+
+### Create an entity (one exact typed entity)
+
+Before this call, use `/discover?userId=…&profileSlugs=<kind>` to read the
+real fields, required/default values, constraints and reference targets. Omit
+`workspaceId` for the pod/base schema and normal profile placement; pass it
+only when the user or routing decision explicitly selected that workspace.
+
+```json
+POST /api/hub/entities
+{
+  "userId": "{userId}",
+  "profileSlug": "task",          // from /discover — never guess
+  "title": "Weekly team sync",
+  "description": "Recurring planning sync",
+  "properties": { "status": "todo", "dueDate": "2026-07-21" },
+  "content": "# Agenda\n- Priorities\n- Risks",
+  "projectId": "{existingProjectId}",
+  "source": "agent"
+}
+```
+
+The response has legacy `status`/`id` fields plus `writeReceipt`:
+`pending`/`proposed` means a proposal exists and no entity is live yet;
+`applied` means the reported direct write completed; `partial` means a follow-up
+(for example a facet) failed after the entity applied. **A `proposed`/`pending`
+receipt is a governed success, not an error** — surface its `reviewUrl`, never
+claim completion, and only enrich again when the receipt identifies a real
+missing fact.
+
+For several entities, creation-time roles/facets, or relations that need one
+review, send the whole graph through the capture door (`synap_capture` with
+`entities[]` + `relations[]`) instead of sequencing independent creates. It is
+ONE governed call: policy auto-applies when every op is safe, otherwise the
+whole graph is proposed (atomic). There is no separate commit step.
+
+**Name-refs, not UUIDs.** Reference an existing project by name — the server
+resolves it against the caller's own projects (exact match files there; no match
+proposes, never mis-files). Never ask the user for a UUID.
+
+**Dedup is advisory across kinds.** Strong signals (`email`/`phone`/`website` —
+not a bare `url`) dedup within a kind; a same-title hit in a _different_ kind
+comes back as an advisory candidate, never an auto-merge. "No exact match" is not
+"safe to create" when advisory candidates are returned — review them first.
+
+### Update an entity
+
+```json
+PATCH /api/hub/entities/{entityId}
+{ "userId": "{userId}", "title": "…", "properties": { "status": "done" } }
+```
+
+**Properties are deep-merged — send only the keys you want to change.** An update with `{ "status": "done" }` leaves all other properties untouched. You never need to re-send the full properties object.
+
+### Authored text is content, not a `file`
+
+Something **you** author — a pitch deck, a strategic plan, a note body — is
+**never** a `file`- or `document`-kind entity. Create it as the right CONTENT
+kind (`note`, `knowledge`, or a fitting domain kind) with `content` set to the
+Markdown body; Synap **auto-materializes** that `content` into a real
+versioned document behind the scenes (`entities WHERE documentId = ?`) — no
+upload step needed. `file` is reserved for real uploaded bytes you actually
+have (the upload door / `synap upload`) — an agent has no filesystem, so it
+rarely touches `file` at all. Reach for `synap_create_document` /
+`POST /api/hub/documents` directly only for a standalone rich document that
+isn't itself a title-worthy entity (see below) — never as a substitute for an
+entity's `content`.
+
+### "I want to add a real FILE" — the decision tree
+
+You CAN store content you **hold** — you send it inline. Pick by what you have:
+
+| You have…                                                                                   | Do this                                                                                         | Result                                                               |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Content in hand** — a report/CSV/image/PDF/etc. you generated or received (text or bytes) | **`synap_store_file`** (`content` for text, `contentBase64` for binary) + `mimeType`/`filename` | a `file` entity, content stored **as-is, never read** (≤10MB inline) |
+| Text you're **authoring as a note/idea** (not "a file") — a plan, a thought                 | `synap_create_entity` with `content` (a content kind)                                           | body auto-becomes a document — NOT a `file`                          |
+| Only a **URL/link** (no bytes) — a Google Doc, a PDF url, an article                        | `synap_create_document` with **`url`**, or attach via `entityId`                                | an external **reference** document (no bytes)                        |
+| A **large file on a local disk** you don't hold in context                                  | the CLI `synap upload <path>` (streams it) — an agent can't send bytes it doesn't have          | a `file` entity backed by stored bytes                               |
+| Only a file's **name**, nothing else                                                        | you **cannot** invent it — ask the human/client to provide the content or a link                | —                                                                    |
+
+**Store ≠ analyze.** `synap_store_file` / `synap_create_document` store content
+**deterministically — the file is NEVER read by an LLM.** Only fetch a document
+and reason over it when the user explicitly says "read/analyze this file."
+
+**Do NOT over-structure a file request.** "Store this file" / "how do I add this
+file" is ONE intent → at most one stored file (plus, only if asked, a linking
+relation). Never inflate it into a task + note + placeholder-file scaffold, and
+never dump the request text into a note and call it done.
+
+### Create a document (attach to an entity)
+
+```json
+POST /api/hub/documents
+{
+  "userId": "{userId}",
+  "workspaceId": "{workspaceId}",
+  "title": "Meeting notes — 2026-04-20",
+  "content": "# Attendees\n- …\n\n# Decisions\n- …",
+  "type": "markdown",              // "markdown" | "html" | "text" | "code"
+  "entityId": "ent_event_..."      // attach to an entity for context
+}
+```
+
+`type: "html"` stores self-contained HTML. The browser renders it via the `html-doc` cell in a sandboxed iframe. Use for AI-generated reports, rich visualisations, custom charts, or anything beyond markdown.
+
+**Full HTML cell workflow** (AI → visible custom UI in any bento):
+
+```json
+// 1. Create the HTML document
+POST /api/hub/documents
+{ "userId": "{userId}", "workspaceId": "{workspaceId}",
+  "title": "Q2 Revenue Report", "type": "html",
+  "content": "<!DOCTYPE html><html>…</html>",
+  "entityId": "ent_project_..." }
+// → { "document": { "id": "doc_abc" }, ... }
+
+// 2. Place the html-doc cell in any bento view
+POST /api/hub/views/{bentoViewId}/arrange
+{ "userId": "{userId}", "workspaceId": "{workspaceId}",
+  "widgets": [
+    { "id": "b1", "kind": "html-doc", "config": { "documentId": "doc_abc" },
+      "layout": { "x": 0, "y": 0, "w": 8, "h": 6 } }
+  ] }
+
+// 3. Update the HTML (cell auto-refreshes)
+PATCH /api/hub/documents/doc_abc
+{ "userId": "{userId}", "content": "<!DOCTYPE html>…updated…</html>" }
+```
+
+The iframe uses `sandbox="allow-scripts"` — scripts run but have no same-origin access to the parent app. The HTML is fully isolated.
+
+### Update a document (title and/or content)
+
+```json
+PATCH /api/hub/documents/{documentId}
+{
+  "userId": "{userId}",
+  "title": "Updated title",          // optional
+  "content": "# Full replacement\n…" // full string — not a diff
+}
+```
+
+Content is a **full replacement**, not a patch. Fetch the current content first if you want to append: `GET /api/hub/documents/{id}?userId={userId}` → `.content`, append, then PATCH.
+
+The reverse lookup is `entities WHERE documentId = ?`. Always attach the document to a meaningful entity (the meeting event, the project, the person) — a floating document is another orphan.
+
+### Remember a fact about the user — use sparingly
+
+A fact _about the user_ goes through `remember_fact` (CLI: `synap capture --type
+observation`). It writes a governed `user_observation` — not an ungoverned
+throwaway row: a fact the user explicitly stated auto-approves; a fact you
+inferred returns `proposed` (normal — surface the review link). Because it's a
+real entity it's addressable, linkable and revertible.
+
+**Use it only for loose, unstructured, hard-to-title facts about the user** — a
+stated preference, a throwaway detail. Everything with a title-worthy noun or
+something to link to is an ENTITY through the capture door, not an observation.
+
+**The test:** if the user later asked "show me all X," could a loose observation
+answer? It can only keyword-match — it has no structure. So:
+
+| Input                                                   | Use                                                             |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| "User prefers async communication"                      | observation — it's a preference                                 |
+| "Garage code is 4321"                                   | observation — throwaway fact                                    |
+| "Should we use LangGraph or CrewAI for Eve?"            | **entity `question`** — substantive inquiry, start of flow      |
+| "Here's what I found comparing LangGraph and CrewAI…"   | **entity `research`** — investigation with sources + conclusion |
+| "We decided to use LangGraph over OpenClaude's native…" | **entity `decision`** — has title, rationale, project           |
+| "Key insight: tasks need better retry logic"            | **entity `note` with tag "insight"** + link to project          |
+| "John is now head of engineering at Acme"               | **update `contact` entity** — that's a property change          |
+| "Launch date moved to May 15"                           | **update `project` entity** — change the startDate              |
+| "Action item from meeting: ship MVP by Friday"          | **entity `task`** linked to the `event` (meeting)               |
+| "Agreed with Sarah: we'll split backend & frontend"     | **entity `decision`** linked to Sarah + the project             |
+
+**Rule of thumb:** if it has a title-worthy noun OR context to link to (a project, a person, a meeting) OR a lifecycle (status/supersession) — it's an entity through the capture door, not an observation. A user observation is the fallback, not the default.
+
+**For decisions specifically** — use the `decision` system profile:
+
+```json
+POST /api/hub/entities
+{
+  "userId": "{userId}",
+  "profileSlug": "decision",
+  "title": "Use LangGraph orchestrator over OpenClaude native",
+  "properties": {
+    "decisionStatus": "accepted",
+    "decidedAt": "2026-04-20",
+    "summary": "Dedicated orchestrator service; OpenClaude CLI as UX",
+    "rationale": "Separates the Orchestration Brain (LangGraph) from the UX (OpenClaude CLI).",
+    "alternatives": "Standardize entirely on OpenClaude's multi-agent logic.",
+    "projectId": "ent_project_eve"
+  }
+}
+```
+
+This creates a first-class decision entity linked to Project Eve. It shows up in traversals, can be superseded later (`supersededBy: newDecisionId`), and survives governance. Memory can't do any of that.
+
+### Post to the user's personal channel
+
+```
+GET  /api/hub/channels/personal?userId={userId}&workspaceId={workspaceId}
+       → { id, name, … }       (get-or-create, needs hub-protocol.write scope)
+
+POST /api/hub/threads/{threadId}/messages
+       { "userId": "{userId}", "role": "user", "content": "…" }
+```