@synap-core/cli 1.2.0 → 1.5.0

package/skills/synap/capture.md

@@ -0,0 +1,170 @@
+# Capture pipeline — reference
+
+Use the capture pipeline when the user pastes a block of unstructured text (email, meeting transcript, LinkedIn bio, article, screenshot of a whiteboard) and you need to extract multiple entities with their relations.
+
+Chaining manual `POST /entities` + `POST /relations` for this is wasteful — the pipeline extracts everything in one server-side LLM call and returns proposals you can review before committing.
+
+## Two-step flow
+
+### 1. Structure the text
+
+```json
+POST /api/hub/capture/structure
+{
+  "userId":      "{userId}",
+  "workspaceId": "{workspaceId}",
+  "text":        "Had lunch with Sarah Chen from Acme Corp today. \
+                  She's leading their Series B and asked me to send \
+                  our sales deck by Friday. Mentioned her VP Engineering \
+                  Tom Walker also wants a demo.",
+  "context":     { "source": "chat", "channelId": "ch_…" },  // optional
+  "profileSlugs": ["person", "company", "task", "event"]     // optional filter
+}
+```
+
+Response:
+
+```json
+{
+  "proposals": [
+    {
+      "tempId": "t1",
+      "profileSlug": "person",
+      "title": "Sarah Chen",
+      "properties": { "companyId": "t2" },
+      "action": "create"
+    },
+    {
+      "tempId": "t2",
+      "profileSlug": "company",
+      "title": "Acme Corp",
+      "properties": {},
+      "action": "create"
+    },
+    {
+      "tempId": "t3",
+      "profileSlug": "person",
+      "title": "Tom Walker",
+      "properties": { "role": "VP Engineering", "companyId": "t2" },
+      "action": "create"
+    },
+    {
+      "tempId": "t4",
+      "profileSlug": "task",
+      "title": "Send sales deck to Sarah",
+      "properties": {
+        "status": "todo",
+        "dueDate": "2026-04-24",
+        "assignee": null
+      },
+      "action": "create"
+    },
+    {
+      "tempId": "t5",
+      "profileSlug": "event",
+      "title": "Lunch with Sarah",
+      "properties": { "startDate": "2026-04-20", "attendees": ["t1"] },
+      "action": "create"
+    }
+  ],
+  "relations": [
+    {
+      "sourceTempId": "t4",
+      "targetTempId": "t1",
+      "relationType": "for_person"
+    },
+    {
+      "sourceTempId": "t4",
+      "targetTempId": "t5",
+      "relationType": "from_meeting"
+    }
+  ],
+  "followUp": "Should I also schedule a reminder to follow up with Tom?"
+}
+```
+
+**`tempId` is only valid within this response.** It's used to link proposals together before they have real entity IDs.
+
+**`action` can be:**
+
+- `"create"` — new entity
+- `"update"` — existing entity found by title match; `existingEntityId` will be set
+- `"skip"` — duplicate already exists, nothing to do
+
+### 2. Execute (commit) after user confirmation
+
+Present the proposals to the user. Let them edit, remove, or add items. Then:
+
+```json
+POST /api/hub/capture/execute
+{
+  "userId":      "{userId}",
+  "workspaceId": "{workspaceId}",
+  "entities":    [ /* edited proposals array */ ],
+  "relations":   [ /* edited relations array */ ]
+}
+```
+
+Response:
+
+```json
+{
+  "created":  [{ "tempId": "t1", "entityId": "ent_real_1" }, …],
+  "updated":  [{ "tempId": "t2", "entityId": "ent_existing" }, …],
+  "skipped":  [{ "tempId": "t5", "reason": "duplicate" }],
+  "relations": { "created": 2, "failed": 0 },
+  "status":   "approved"
+}
+```
+
+The executor goes through governance (see `governance.md`). Expect the same three `status` values.
+
+## When to use the pipeline vs. manual CRUD
+
+| Situation                                                        | Use                                                 |
+| ---------------------------------------------------------------- | --------------------------------------------------- |
+| User pastes a chunk of text with multiple people/companies/tasks | Pipeline                                            |
+| User says "create a task to call Sarah at 3pm"                   | Manual create (1 entity)                            |
+| User forwards an email                                           | Pipeline                                            |
+| User asks "remind me to X"                                       | Manual create                                       |
+| OCR'd screenshot, meeting transcript, article body               | Pipeline                                            |
+| User edits an existing entity                                    | Manual PATCH                                        |
+| User wants to save a webpage they're on                          | Manual create (article) + optional capture for body |
+
+Rule of thumb: **one intent, one call.** Multi-entity content, use the pipeline.
+
+## Dedup within the pipeline
+
+The pipeline does its own duplicate check per entity (by title + profileSlug within workspace). When it finds a match, `action` becomes `"update"` with `existingEntityId` set, so the real entity is updated in place, not duplicated.
+
+You can still prefix with a manual search if you want to show the user "I found 3 existing people that might match" before running capture. But the pipeline alone is usually good enough.
+
+## Presenting proposals to the user
+
+A good UX turn:
+
+> I picked up **5 things** from that paste:
+>
+> - **Sarah Chen** — person at Acme Corp (new)
+> - **Acme Corp** — company (new)
+> - **Tom Walker** — person at Acme (new)
+> - **Task**: Send sales deck to Sarah, due Friday
+> - **Event**: Lunch with Sarah today
+>
+> Plus 2 connections: task → Sarah, task → lunch.
+>
+> Ship it?
+
+Keep the user in control. Don't auto-execute without confirmation unless the user explicitly told you to.
+
+## Edge cases
+
+- **Empty text → empty proposals.** Don't call execute with zero entities.
+- **Ambiguous references ("he", "they").** The pipeline will often return null properties. Prompt the user to clarify before executing.
+- **Dates.** Always absolute in responses (ISO 8601). If the input says "Friday," the pipeline resolves it against today.
+- **Custom profiles.** If you want the pipeline to consider custom profiles, pass `profileSlugs` in the request. Otherwise it defaults to system profiles only.
+- **Rate limits.** 20 captures/hour per user. If you hit the limit, fall back to manual CRUD.
+
+## Followup question
+
+The response includes a `followUp` field — a single sentence question the pipeline thinks is worth asking next. Surface it to the user verbatim. It's a cheap way to deepen capture without extra prompts.

package/skills/synap/governance.md

@@ -0,0 +1,206 @@
+# Governance — reference
+
+Synap queues some agent writes for human approval. This file covers what triggers a proposal, the auto-approve whitelist, how to handle each response status, and agent-user semantics.
+
+## Response statuses
+
+Every write endpoint returns a `status` field. Handle all three.
+
+```json
+{ "status": "approved", "id": "ent_…", "message": "…" }
+  → The write committed. Use { id } normally.
+
+{
+  "status":     "proposed",
+  "proposalId": "prp_…",
+  "summary":    "Delete task \"Q2 plan review\"",
+  "reasoning":  "Destructive actions require your approval",
+  "reviewPath": "/proposals/prp_…",
+  "reviewUrl":  "https://studio.synap.live/proposals/prp_…",
+  "message":    "…"
+}
+  → Queued for user review. Surface `summary` + `reviewUrl` to the user; do not retry.
+
+{ "status": "denied", "reason": "…" }
+  → Policy blocked the write. Explain the reason. Do not retry.
+```
+
+**`"proposed"` is not an error.** If your retry logic treats it as one, the system will create duplicate proposals.
+
+## What triggers a proposal
+
+Two independent factors:
+
+### 1. Agent identity
+
+Agent identity is determined by the API key. An agent-owned Hub API key (created via `POST /api/hub/setup/agent`) automatically attributes all requests to the agent user — no `agentUserId` field is needed in request bodies. The middleware resolves the agent from the key and tags writes with `source: "agent"`.
+
+If the key belongs to a human user (personal API key), writes go through unless the workspace has `aiGovernance.forceProposals = true`.
+
+### 2. Action type
+
+The auto-approve whitelist is a list of `subjectType.action` pairs. For example `entity.create`, `document.read`, `view.create`.
+
+## Default auto-approve whitelist
+
+Agents can perform these actions directly without a proposal:
+
+**Reads** (always, no gating):
+
+- `search.*`
+- `entity.read`, `document.read`, `relation.read`
+- `memory.recall`
+- `context.*`
+- `filesystem.read`
+
+**Writes** (auto-approved by default):
+
+- `entity.create`, `entity.update`
+- `relation.create`
+- `document.create`
+- `memory.store` (always auto-approved, never proposed)
+- `view.create`
+- `profile.create`, `profile.update`
+- `property_def.create`, `property_def.update`
+- `channel.create`
+- `bento.arrange`
+- `filesystem.write_workspace` (OpenClaw sandbox only)
+
+**Proposal-gated** (always require approval when done by agents):
+
+- `entity.delete`, `entity.archive`, `entity.purge`
+- `view.update`, `view.delete`
+- `profile.delete`
+- `property_def.delete`
+- `workspace.create`, `workspace.update`, `workspace.delete`
+
+## Destructive action override
+
+In **agent-owned workspaces** (workspaces where the owner is an agent user, not a human), destructive actions (`delete`, `archive`, `purge`) **always propose** even if they appear in the whitelist. This prevents an agent from wiping its own workspace without human sign-off.
+
+## Workspace overrides
+
+Each workspace has an `aiGovernance` settings object that can:
+
+- **Replace the whitelist entirely** (`aiGovernance.autoApproveFor = ["entity.read", "search.*"]`) — this becomes the full allowed list; defaults no longer apply
+- **Switch to agent-owned mode** (`settings.governanceMode = "agent-owned"`) — destructive actions (delete/archive/purge) always propose regardless of whitelist
+- **Change who approves** (`aiGovernance.proposalApprovalPolicy = "admins_only" | "any_editor" | "owner_and_admins"`)
+
+Don't try to infer the workspace's policy — either check explicitly (see "Runtime introspection" below) or just write and handle whatever `status` comes back.
+
+## Don't set `source` manually
+
+`source` is set by the backend based on the auth context. Setting it manually in the request body is ignored. If your API key has an agentUserId, writes are tagged `source: "agent"` automatically.
+
+## The proposal lifecycle
+
+When a write is proposed:
+
+1. A row is created in the `proposals` table: `{ id, proposal, request, status: "pending" }`.
+2. A notification is sent to the workspace admins.
+3. The `proposed` response is returned to you with `proposalId`.
+4. A human reviews in Synap's Proposals page, approves or rejects.
+5. On approve: the request is replayed with proper permissions. On reject: the write is discarded.
+
+You do not poll or wait. The user's experience is asynchronous.
+
+## Agent users
+
+An agent user is a pod-wide user with `agentMetadata.writesRequireProposal` set. Created by `POST /api/hub/setup/agent`. Each agent user has:
+
+- `agentType`: a free-form string (`"claude-code"`, `"openclaw"`, `"raycast"`, `"custom"`)
+- `agentMetadata`: arbitrary JSON for config
+- Hub API keys scoped to `hub-protocol.read` + `hub-protocol.write` + `mcp.*`
+
+The `agentUserId` on a Hub API key binds all writes done with that key to the agent user. Multiple keys can share one agent user.
+
+## `userId` in request bodies
+
+For every write that takes `userId`, pass the **human user's ID**. The agent identity is derived automatically from the API key — do not pass `agentUserId` in the body. Both IDs are tracked internally: the human appears in `createdBy`, the agent appears in `performedBy`.
+
+```json
+POST /api/hub/entities
+{
+  "userId":      "usr_antoine",    // the human user (from SYNAP_USER_ID)
+  "workspaceId": "ws_…",
+  "profileSlug": "task",
+  …
+}
+```
+
+If you pass the API key owner (often a system account) as `userId`, the entity appears in no one's feed. Always pass the real human user's ID.
+
+## Handling proposed writes gracefully
+
+When a write is proposed, surface three things to the user: what was queued, why, and how to act on it. The response carries everything you need — don't invent paraphrases.
+
+**The formula:**
+
+```
+"I queued **{summary}** for your review. {reasoning}. Review: {reviewUrl}"
+```
+
+**Concrete examples:**
+
+```
+good: "I queued **Delete task \"Q2 plan review\"** for your review.
+       Destructive actions need your approval.
+       https://studio.synap.live/proposals/prp_abc"
+
+good: "I queued **Create entity \"Acme Corp\"** for your review.
+       https://studio.synap.live/proposals/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""
+
+bad:  "Error: write was not approved."
+bad:  "Something needs your attention in Synap."        ← too vague
+bad:  "I tried to delete that but I'm not sure it worked." ← sounds like a failure
+```
+
+**Rules:**
+
+- Use the `summary` field **verbatim**, in bold. It's already short and human-readable.
+- Include `reviewUrl` as a raw URL — let the client render it as a link.
+- One line of chat per proposal. Don't bury the link in a paragraph.
+- If the user asks "can you just do it?" — tell them no, it's queued; they can open the link to approve.
+- **Don't wait or poll.** Move on with the conversation. The user approves in their own time; you'll see the effect when they ask you to read the data again.
+
+**When multiple writes in one turn produce multiple proposals:** list them, one line each, with their links. Don't aggregate into a single "some stuff was queued" message.
+
+**Clients without rich link rendering** (plain terminals, voice, SMS-style interfaces): still say the URL — the user can copy-paste it. Even if they can't click, they know where to go.
+
+## Runtime introspection (preferred over hardcoded rules)
+
+When you need to know the actual policy for a workspace — e.g., to tell the user "I can create entities directly, but deleting them will need your approval" — call:
+
+```
+GET /api/hub/workspaces/{workspaceId}/governance
+
+→ {
+    workspaceId: "ws_…",
+    effective: {
+      autoApproveFor: [           // the actual whitelist at this workspace
+        "entity.create", "entity.update", "relation.create", "document.create",
+        "view.create", "profile.create", "property_def.create", "memory.*", …
+      ],
+      governanceMode: "default" | "agent-owned",
+      proposalApprovalPolicy: "owner_and_admins" | "any_editor" | "admins_only",
+      destructiveAlwaysPropose: false,   // true when governanceMode === "agent-owned"
+      destructiveActions: ["delete", "archive", "purge"]
+    },
+    source: "workspace" | "default",     // where `autoApproveFor` came from
+    defaults: {
+      autoApproveFor: [ /* the backend default list, for comparison */ ]
+    }
+  }
+```
+
+An action is auto-approved when:
+
+- it matches an entry in `effective.autoApproveFor` (exact match or `subject.*` glob), AND
+- it is NOT in `destructiveActions` when `destructiveAlwaysPropose` is true
+
+Prefer this endpoint over the tables in this file — they snapshot the default at the time of writing and don't reflect workspace customization.

package/skills/synap/linking.md

@@ -0,0 +1,128 @@
+# Linking — reference
+
+Two mechanisms connect entities in Synap. This file covers when to use which, auto-sync behaviour, and relation conventions.
+
+## Auto-sync table (ENTITY_ID properties → relations)
+
+When a profile property has `valueType: "entity_id"`, setting it on entity creation or update automatically writes a row in the `relations` table. No second call needed.
+
+Known system-profile auto-syncs:
+
+| Profile  | Property    | Target profile | Auto-relation type   |
+| -------- | ----------- | -------------- | -------------------- |
+| task     | `projectId` | project        | `belongs_to_project` |
+| task     | `assignee`  | person         | `assigned_to`        |
+| contact  | `companyId` | company        | `works_at`           |
+| deal     | `contactId` | contact        | `deal_for`           |
+| deal     | `companyId` | company        | `deal_with`          |
+| document | `entityId`  | (any)          | `attached_to`        |
+| anchor   | `channelId` | (channel)      | `anchored_in`        |
+
+Custom profiles: if you created a property with `valueType: "entity_id"`, the auto-sync kicks in, but the relation type defaults to `related_to` unless the profile defines a `relationDefinition`. When precision matters, create the relation explicitly (Way 2) with a specific `type`.
+
+**Do not trust this table to stay current.** Always verify with `GET /api/hub/profiles` — the returned profile includes `properties[].valueType` and `properties[].targetProfileSlug`. Any property with `valueType: "entity_id"` is an auto-sync candidate.
+
+## Way 1 — set the property
+
+```json
+POST /api/hub/entities
+{
+  "userId": "{userId}",
+  "workspaceId": "{workspaceId}",
+  "profileSlug": "task",
+  "title": "Finalize Q2 plan",
+  "properties": {
+    "projectId": "ent_project_q2",   // one call, two rows written
+    "assignee":  "usr_antoine"
+  }
+}
+```
+
+After this single call, these all work:
+
+```
+GET /entities/ent_project_q2/connections  → task appears
+GET /relations?entityId=ent_project_q2     → belongs_to_project row appears
+GET /graph/traverse?entityId=ent_project_q2 → task included as node
+```
+
+Use Way 1 whenever a matching entity_id property exists on the profile. It is cheaper and semantically typed.
+
+## Way 2 — explicit relations
+
+For:
+
+- Links between two already-existing entities (after creation)
+- Custom connections where no entity_id property exists
+- Cross-type links not captured by the schema (e.g., task → document, entity → bookmark)
+- Links involving custom profiles without a relationDefinition
+
+```json
+POST /api/hub/relations
+{
+  "userId":        "{userId}",
+  "workspaceId":   "{workspaceId}",
+  "sourceEntityId": "ent_source",
+  "targetEntityId": "ent_target",
+  "type":          "references"
+}
+```
+
+## Conventional relation types
+
+String-typed, case-insensitive by convention. Use these first before inventing new ones — workspace UI often renders known types specially.
+
+| Type           | Direction       | When                                              |
+| -------------- | --------------- | ------------------------------------------------- |
+| `related_to`   | bidirectional   | Generic association, no stronger label fits       |
+| `parent_of`    | source → target | Hierarchy (project parent of sub-project)         |
+| `child_of`     | source → target | Hierarchy (inverse of parent_of)                  |
+| `belongs_to`   | source → target | Membership                                        |
+| `authored_by`  | source → target | Note/document authored by a person                |
+| `depends_on`   | source → target | Task blocked by another task, project needs input |
+| `references`   | source → target | Task references a document, note cites an article |
+| `mentions`     | source → target | Entity mentioned within another entity            |
+| `works_with`   | bidirectional   | People who collaborate                            |
+| `part_of`      | source → target | Component relationship                            |
+| `from_meeting` | source → target | Any entity extracted from a meeting/event         |
+| `anchored_in`  | source → target | Anchor (pinned chat message) in a channel         |
+
+If none fits, invent a snake_case verb. Keep it short and symmetric with existing verbs. Don't create `related-to-this-specific-thing` — prefer a generic `related_to` plus a more specific property or document.
+
+## Decision table
+
+| Situation                                              | Use                                    |
+| ------------------------------------------------------ | -------------------------------------- |
+| Profile has matching `valueType: "entity_id"` property | Way 1 — set the property               |
+| Linking two already-existing entities                  | Way 2 — create a relation              |
+| Custom connection, no matching property                | Way 2                                  |
+| Unsure whether a property exists                       | `GET /profiles` first                  |
+| Linking a document to its parent entity                | Use `entityId` on the document (Way 1) |
+| Multi-party link (entity A ↔ entity B ↔ entity C)      | Two relations, both Way 2              |
+
+## Reading the graph
+
+```
+# The complete picture — graph relations + property-derived links + thread refs
+GET /api/hub/entities/{id}/connections
+  → { connections: [{ entityId, entity, label, direction,
+                      source: "graph"|"property"|"thread" }] }
+
+# Raw graph relations only
+GET /api/hub/relations?entityId={id}
+
+# BFS neighborhood
+GET /api/hub/graph/traverse?entityId={id}&maxDepth=2
+  → { nodes: Entity[], edges: Relation[] }
+```
+
+**Prefer `/entities/{id}/connections`** when you want "everything connected to X" — it unifies property-derived links (which the raw relations table doesn't always surface for custom profiles) with graph relations and thread anchors.
+
+`/graph/traverse` is best for "what's in the 2-hop neighborhood of this entity" — good for context gathering, but expensive at `maxDepth ≥ 3`.
+
+## Common mistakes
+
+- **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.
+- **Inverting direction.** Source is "the thing doing the action or owning the relationship." `task depends_on task` means the source is blocked by the target. Check twice.

package/skills/synap/scripts/orient.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Orient: fetch identity, workspaces, and profiles in one deterministic shot.
+# Requires: SYNAP_HUB_API_KEY, SYNAP_POD_URL.
+# Output: single JSON object { user, workspaces, profiles }.
+# Exit codes: 0 ok, 1 env missing, 2 HTTP failure.
+
+set -euo pipefail
+
+: "${SYNAP_HUB_API_KEY:?SYNAP_HUB_API_KEY not set}"
+: "${SYNAP_POD_URL:?SYNAP_POD_URL not set}"
+
+H="Authorization: Bearer $SYNAP_HUB_API_KEY"
+POD="${SYNAP_POD_URL%/}"
+
+user=$(curl -fsS -H "$H" "$POD/api/hub/users/me") || { echo "users/me failed" >&2; exit 2; }
+user_id=$(printf '%s' "$user" | sed -n 's/.*"id":"\([^"]*\)".*/\1/p' | head -n1)
+
+workspaces=$(curl -fsS -H "$H" "$POD/api/hub/workspaces") || { echo "workspaces failed" >&2; exit 2; }
+ws_id="${SYNAP_WORKSPACE_ID:-}"
+if [ -z "$ws_id" ]; then
+  ws_id=$(printf '%s' "$workspaces" | sed -n 's/.*"id":"\([^"]*\)".*/\1/p' | head -n1)
+fi
+
+profiles=$(curl -fsS -H "$H" "$POD/api/hub/profiles?userId=$user_id&workspaceId=$ws_id") \
+  || { echo "profiles failed" >&2; exit 2; }
+
+printf '{"user":%s,"workspaces":%s,"workspaceId":"%s","profiles":%s}\n' \
+  "$user" "$workspaces" "$ws_id" "$profiles"