@synap-core/cli 1.8.0 → 1.11.0

package/skills/synap/_order.txt

@@ -0,0 +1,37 @@
+operating-mode.md
+reflexes.md
+escalation-ladder.md
+mental-model.md
+quick-reference.md
+lenses.md
+operating-mode-rules.md
+cli-operations.md
+scope.md
+work-flow.md
+linking-principle.md
+governance-rules.md
+capabilities.md
+writes.md
+document-embeds.md
+creative-loop.md
+graph-gardening.md
+next-action.md
+reading.md
+multi-entity-capture.md
+worked-examples.md
+crm.md
+common-mistakes.md
+inline-patterns.md
+focus-sessions.md
+automations.md
+diagnostics.md
+workspace-design.md
+workspace-edges.md
+more.md
+viewframe-cells.md
+authentication.md
+response-style.md
+recap.md
+showing.md
+user-model.md
+north-star.md

package/skills/synap/_skill.yaml

@@ -0,0 +1,24 @@
+name: synap
+description: >
+  Use this skill whenever the user wants to capture, remember, find, or structure
+  information in their Synap data pod. Triggers: creating a task, note, person,
+  company, project, event, contact, or deal; saving an article or webpage;
+  storing a fact about someone ("Alice prefers async"); searching the user's
+  knowledge ("find my notes on X", "who did I meet last week"); linking entities;
+  logging a meeting or a contact; capturing unstructured text into structured
+  entities; reading what's in the user's pod before answering questions about
+  their life, work, or projects; posting to their personal AI channel. The pod
+  is the user's sovereign source of truth — prefer it over your own context
+  when the user asks about their own data. Do NOT use this skill for extending
+  the schema (use synap-schema) or building dashboards and views (use synap-ui).
+metadata:
+  openclaw:
+    requires:
+      env: [SYNAP_HUB_API_KEY, SYNAP_POD_URL]
+      optional_env:
+        [SYNAP_WORKSPACE_ID, SYNAP_USER_ID, SYNAP_DEFAULT_CHANNEL_ID]
+    primaryEnv: SYNAP_HUB_API_KEY
+    homepage: https://synap.live
+    capabilities: [memory, knowledge-graph, channels]
+    os: [macos, linux, windows]
+    userInvocable: false

package/skills/synap/authentication.md

@@ -0,0 +1,10 @@
+## Authentication
+
+```
+Authorization: Bearer {SYNAP_HUB_API_KEY}
+X-Workspace-Id:  {workspaceId}            (optional; also pass in body/query)
+
+Scopes:
+  hub-protocol.read   → most GET endpoints
+  hub-protocol.write  → all writes AND GET /channels/personal
+```

package/skills/synap/automations.md

@@ -0,0 +1,264 @@
+# Automations
+
+Create workflow automations that trigger automatically based on events, schedules, or webhooks.
+
+## Automation Structure
+
+Every automation has:
+
+1. **Trigger** (exactly one) — what starts the automation
+2. **Steps** (one or more) — commands, conditions, delays, outputs connected in a flow
+
+## Trigger Types
+
+| Type      | Config                       | Example                              |
+| --------- | ---------------------------- | ------------------------------------ |
+| `event`   | `{ eventPattern, filters? }` | Entity created with specific profile |
+| `cron`    | `{ expression }`             | Daily at 9am: `"0 9 * * *"`          |
+| `webhook` | `{ webhookSubscriptionId }`  | External service sends data          |
+| `manual`  | `{}`                         | User-triggered from UI               |
+
+### Event Patterns
+
+Format: `{subjectType}.{action}.completed`
+
+Common patterns:
+
+- `entity.create.completed` — entity created and persisted
+- `entity.update.completed` — entity updated
+- `entity.delete.completed` — entity deleted
+- `document.create.completed` — document created
+- `document.update.completed` — document updated
+
+Filters narrow the event to specific conditions:
+
+```json
+{
+  "eventPattern": "entity.create.completed",
+  "filters": { "profileSlug": "task", "metadata.priority": "high" }
+}
+```
+
+### Cron Expressions
+
+Standard 5-field cron (minute hour day month weekday):
+
+- `"0 9 * * *"` — daily at 9am
+- `"0 9 * * MON"` — every Monday at 9am
+- `"*/30 * * * *"` — every 30 minutes
+- `"0 0 1 * *"` — first day of month at midnight
+
+## Step Types
+
+### command
+
+Execute an intelligence command. Reference by `commandId` or describe inline.
+
+```json
+{
+  "id": "extract",
+  "type": "command",
+  "data": {
+    "commandTitle": "Extract key entities",
+    "inputMapping": {
+      "content": "{{trigger.payload.entity.content}}",
+      "context": "{{trigger.payload.entity.name}}"
+    }
+  }
+}
+```
+
+**Input mapping** uses template syntax:
+
+- `{{trigger.payload.*}}` — data from the triggering event
+- `{{steps.<stepId>.output.*}}` — output from a prior step
+- `{{loop.item}}` — current item in a loop
+
+### condition
+
+Branch the flow based on a boolean expression.
+
+```json
+{
+  "id": "check-priority",
+  "type": "condition",
+  "data": {
+    "label": "High priority?",
+    "expression": "trigger.payload.entity.metadata.priority === 'high'",
+    "trueLabel": "Yes",
+    "falseLabel": "No"
+  }
+}
+```
+
+Conditions have two output handles: `yes` and `no`. Connect subsequent steps to the appropriate handle.
+
+### delay
+
+Wait before continuing.
+
+```json
+{
+  "id": "wait",
+  "type": "delay",
+  "data": { "duration": "5m", "label": "Cool down" }
+}
+```
+
+Supported durations: `30s`, `5m`, `1h`, `1d`, `1w`.
+
+### output
+
+Terminal action — the end result of the automation.
+
+```json
+{
+  "id": "notify",
+  "type": "output",
+  "data": {
+    "label": "Send notification",
+    "outputType": "notification",
+    "config": {
+      "message": "New high-priority task: {{trigger.payload.entity.name}}"
+    }
+  }
+}
+```
+
+Output types:
+
+- `notification` — in-app notification to the user
+- `entity_create` — create a new entity (config: `{ profileSlug, title, properties }`)
+- `entity_update` — update an existing entity (config: `{ entityId, properties }`)
+- `webhook` — POST to external URL (config: `{ url, headers?, body }`)
+- `channel_message` — post a message to a channel (config: `{ channelId, content }`)
+
+### loop
+
+Iterate over a collection from a prior step.
+
+```json
+{
+  "id": "for-each-result",
+  "type": "loop",
+  "data": {
+    "label": "For each search result",
+    "iteratorExpression": "steps.search.output.results",
+    "itemVariable": "item"
+  }
+}
+```
+
+Inside the loop, reference `{{loop.item}}` for the current element.
+
+## Connecting Steps
+
+Steps are connected via `dependsOn` (which step must complete first) and optional `conditionBranch` (which branch to follow from a condition).
+
+```json
+{
+  "steps": [
+    { "id": "check", "type": "condition", "data": {...} },
+    { "id": "notify-high", "type": "output", "data": {...}, "dependsOn": ["check"], "conditionBranch": "yes" },
+    { "id": "log-normal", "type": "output", "data": {...}, "dependsOn": ["check"], "conditionBranch": "no" }
+  ]
+}
+```
+
+## Discovering Commands
+
+Before creating automations with command steps, call `list_commands` to discover available intelligence commands in the workspace. Use the command `id` in the step's `commandId` field.
+
+If no suitable command exists, you can leave `commandId` empty and set `commandTitle` + `inputMapping` — the execution engine will use the title as a prompt template.
+
+## Vault References
+
+Automation configs that need secrets (API keys, auth tokens) should use vault references instead of hardcoded values:
+
+- `vault://secret-uuid` — resolves to the full secret value at runtime
+- `vault://secret-uuid/field-name` — resolves a specific field from a JSON secret
+
+Only server-encrypted secrets can be resolved by the automation engine. The user must store the credential in the vault first.
+
+## Best Practices
+
+1. **Keep it simple** — Start with trigger → command → output. Add complexity only when needed.
+2. **Name clearly** — Use descriptive labels: "When task created with high priority" not "Trigger 1".
+3. **One purpose** — Each automation should do one thing well. Compose multiple automations rather than building one complex flow.
+4. **Filter early** — Use trigger filters to avoid unnecessary execution. Don't use a condition step when a trigger filter suffices.
+5. **Test first** — Create automations as `draft` status. Let the user review the flow visualization before activating.
+
+## Example: Auto-archive completed tasks
+
+```json
+{
+  "name": "Auto-archive completed tasks",
+  "description": "When a task status changes to 'done', archive it after 24 hours",
+  "trigger": {
+    "type": "event",
+    "config": {
+      "eventPattern": "entity.update.completed",
+      "filters": { "profileSlug": "task", "metadata.status": "done" }
+    }
+  },
+  "steps": [
+    {
+      "id": "wait-24h",
+      "type": "delay",
+      "data": { "duration": "1d", "label": "Wait 24h" }
+    },
+    {
+      "id": "archive",
+      "type": "output",
+      "data": {
+        "label": "Archive task",
+        "outputType": "entity_update",
+        "config": {
+          "entityId": "{{trigger.payload.entity.id}}",
+          "properties": { "archived": true }
+        }
+      },
+      "dependsOn": ["wait-24h"]
+    }
+  ]
+}
+```
+
+## Example: Notify on high-priority tasks
+
+```json
+{
+  "name": "High-priority task alerts",
+  "description": "Send a notification when a high-priority task is created",
+  "trigger": {
+    "type": "event",
+    "config": {
+      "eventPattern": "entity.create.completed",
+      "filters": { "profileSlug": "task" }
+    }
+  },
+  "steps": [
+    {
+      "id": "check-priority",
+      "type": "condition",
+      "data": {
+        "label": "High priority?",
+        "expression": "trigger.payload.entity.metadata.priority === 'high'"
+      }
+    },
+    {
+      "id": "notify",
+      "type": "output",
+      "data": {
+        "label": "Alert: high-priority task",
+        "outputType": "notification",
+        "config": {
+          "message": "New urgent task: {{trigger.payload.entity.name}}"
+        }
+      },
+      "dependsOn": ["check-priority"],
+      "conditionBranch": "yes"
+    }
+  ]
+}
+```

package/skills/synap/capabilities.md

@@ -0,0 +1,107 @@
+# Capabilities — discover, run, and the when-blocked reflex
+
+Capabilities are the verbs a workspace's connected services and applied
+templates unlock — `gmail_send`, `gmail_search`, `calendar_create`,
+`drive_search`, and so on. They are the bridge between "I can talk about it"
+and "I can actually do it."
+
+## Discover: `list_capabilities`
+
+MCP: `synap_list_capabilities`. IS: `list_capabilities`. Takes
+`{ query, kind?, limit? }` (plus `workspaceId`).
+
+**Search first — never dump-and-eyeball.** A workspace can carry 100+
+capability entries; call with a `query` describing the action you're after
+("send email", "search calendar") and read the ranked, compact results. Don't
+fetch the unfiltered list and scan it yourself.
+
+Each entry carries:
+
+- `name` (the `verbId` you pass to `run_capability`), `label`, backing tool
+- `paramsSchema` — the shape `parameters` must satisfy; check it before calling
+- `enabled` — `true` means it will run right now. `false`/DRAFT means it's
+  installed but the user hasn't approved it yet (Settings → Capabilities)
+
+## Run: `run_capability`
+
+MCP: `synap_run_capability`. IS: `run_capability`. Pass `verbId` (or
+`skillId`) + `parameters` + `workspaceId`.
+
+```json
+{
+  "verbId": "gmail_send",
+  "parameters": { "to": "…", "subject": "…", "body": "…" },
+  "workspaceId": "{workspaceId}"
+}
+```
+
+Check `paramsSchema` from discovery before calling — a missing required
+parameter is refused, not guessed.
+
+**`proposed` is a normal outcome, not a failure.** A capability run can land
+as a proposal exactly like any other governed write (see `governance.md`):
+tell the user why, share the `reviewUrl`, and don't retry.
+
+**Provider results can be 200-with-error-body.** A successful HTTP call to
+Gmail/Calendar/Drive can still carry `result.success: false` +
+`result.error` — an auth expiry, a bad recipient, a quota limit. **Always
+check `result.success`/`result.error` in the response before telling the
+user the action worked.** A 200 status is not proof of success here.
+
+## The when-blocked reflex
+
+When you cannot do something the user asked for — no matching tool, a
+"not found" verb, "no connection", "not enabled" — do not fabricate a result
+and do not silently give up. Follow this order:
+
+1. **Search first.** `list_capabilities({ query })` for what the user actually
+   wants. Capabilities are added over time; don't assume today's tool list is
+   the ceiling.
+2. **Found but blocked?** If the verb exists but is DRAFT (not enabled) or its
+   backing connection is missing, tell the user exactly what to do and where:
+   "This needs Gmail connected — enable it in Settings → Capabilities" (or
+   the equivalent connect deep-link the error hands you). Don't attempt the
+   run again until they've acted.
+3. **Still nothing? Search the marketplace.** `market.search({query, kind?})`
+   over what could be _installed_ (capabilities, automations, workspace
+   templates, cells) — a cache read, not a live fetch, so it's always fast.
+4. **Found in the marketplace?** `market.install({slug, kind, version?})`. As
+   an agent this ALWAYS lands as a reviewable proposal — never auto-installs,
+   even with a grant on the verb itself. Share the `reviewUrl`; don't retry.
+5. **Truly nothing, anywhere?** That is escalation-ladder **L2 empty → L3**:
+   say precisely what's missing (the action, not "I can't"), offer to capture
+   the gap, and if the need is structural (new capability package, template,
+   automation), propose via marketplace/install or meta tools — never
+   dead-end and never fabricate a result.
+
+<!-- brief:start -->
+
+When blocked (ladder L2→L3): (1) `list_capabilities({query})` first — never
+assume today's list is the ceiling. (2) Found but DRAFT/no connection → tell
+the user exactly what to enable/connect and where; don't retry until they've
+acted. (3) Still nothing → `market.search({query, kind?})`; `market.install`
+on a hit always proposes for an agent. (4) Truly nothing → say precisely
+what's missing, offer to capture the gap or propose L3 structure — never
+fabricate, never silent give-up. Provider 200-with-error-body: always check
+`result.success`/`result.error` before claiming success.
+
+<!-- brief:end -->
+
+## Errors — what they mean, what to do next
+
+| You see roughly...                          | Meaning                                                                   | Next step                                                                       |
+| ------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| verb/skill "not found" in this workspace    | No capability by that name is registered here                             | `list_capabilities({query})`; if nothing, tell the user what's missing          |
+| capability "not approved" / DRAFT           | It exists but the user hasn't enabled it yet                              | Tell the user to enable it (Settings → Capabilities); don't retry               |
+| a required parameter is missing             | Your `parameters` didn't satisfy the verb's `paramsSchema`                | Re-check `paramsSchema` from discovery, fill the gap, retry once                |
+| no connection / credential for this service | The verb needs a connected account (Gmail, Calendar, …) that isn't set up | Hand the user the connect link; don't retry until connected                     |
+| `status: "proposed"`                        | Normal governed outcome — this run needs human approval                   | Share `summary` + `reviewUrl`; don't retry (see `governance.md`)                |
+| `status: "denied"`                          | Workspace policy blocked it outright                                      | Explain the reason; don't retry                                                 |
+| provider result with `success: false`       | The call reached the provider but the provider itself rejected it         | Read `result.error`; tell the user what actually happened, don't report success |
+
+## What NOT to do
+
+- Don't dump the full unfiltered capability list and eyeball it — search.
+- Don't retry a `proposed` or `denied` result as if it were a transient error.
+- Don't tell the user an action "worked" without checking `result.success`.
+- Don't invent a capability, verb, or connection that discovery didn't return.

package/skills/synap/capture.md

@@ -1,170 +1,78 @@
-# Capture pipeline — reference
+# Capture — the one write door
 
-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.
+`synap_capture` (CLI: `synap capture`) is THE door for writing what you learn into the pod. **Never classify your input first.** The payload is a _gradient_ — send as much structure as you already have, in ONE call. Precision comes from sending MORE structure in the SAME call, never from picking a different tool and never from a second "commit" step.
 
-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?"
-}
+text        → free prose; the AI structures it into the right entities (raw text kept as provenance)
+entities[]  → you already know the kind + fields
+entities[] + relations[]  → a graph; refs link things that don't exist yet, reviewed as ONE proposal
 ```
 
-**`tempId` is only valid within this response.** It's used to link proposals together before they have real entity IDs.
+There is no wrong door to pick, because there is one door. `text` alone is the old "capture"; `entities[]` is the old "rich create"; `entities[] + relations[]` is the composite graph. All three go through `synap_capture`.
 
-**`action` can be:**
+## One call → one receipt (no plan-and-commit)
 
-- `"create"` — new entity
-- `"update"` — existing entity found by title match; `existingEntityId` will be set
-- `"skip"` — duplicate already exists, nothing to do
+You are an agent, so a capture is **one call**. The backend derives that from your identity (agent key ⇒ agent mode) — you never pass a mode. Policy decides the terminal automatically:
 
-### 2. Execute (commit) after user confirmation
+- every op is safe/whitelisted → **auto-applied**
+- any op is destructive or non-whitelisted → the whole graph is **proposed** (atomic, all-or-nothing)
 
-Present the proposals to the user. Let them edit, remove, or add items. Then:
+It always returns the same receipt:
 
 ```json
-POST /api/hub/capture/execute
-{
-  "userId":      "{userId}",
-  "workspaceId": "{workspaceId}",
-  "entities":    [ /* edited proposals array */ ],
-  "relations":   [ /* edited relations array */ ]
-}
+{ "status": "applied" | "proposed" | "rejected",
+  "scope":  { "workspaceId": "…", "projectId": "…", "sessionId": "…" },
+  "writeReceipt": { … } }
 ```
 
-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"
-}
-```
+**`status: "proposed"` is SUCCESS**, not a failure — the write is queued for the user's review like a PR. Surface the `reviewUrl` and keep working. Never report "done" for a `proposed` result, and there is **no** separate step you must call after capture — the one call is the whole write.
 
-The executor goes through governance (see `governance.md`). Expect the same three `status` values.
+## capture vs create_entity
 
-## When to use the pipeline vs. manual CRUD
+- **`synap_create_entity`** — use ONLY when you already have exactly ONE fully-structured, typed entity (a known `profileSlug` + fields). Deterministic, direct.
+- **`synap_capture`** — everything else: unstructured text, several entities, a graph, or **when in doubt**. It handles the whole gradient; you don't have to decide "loose fact vs structured object."
 
-| 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 |
+## Worked examples
 
-Rule of thumb: **one intent, one call.** Multi-entity content, use the pipeline.
+```json
+// 1 — raw text (the AI structures it)
+{ "text": "Met Ada Lovelace of Acme at the conference — she owns their data platform and wants a demo in March." }
+
+// 2 — one structured entity with a long body
+{ "entities": [
+  { "profileSlug": "person", "title": "Ada Lovelace",
+    "properties": { "email": "ada@acme.com", "role": "Head of Data" },
+    "content": "## Notes\nOwns the data platform. Wants a March demo." }
+] }
+
+// 3 — a small graph (refs link entities that don't exist yet)
+{ "entities": [
+    { "ref": "p1", "profileSlug": "person",  "title": "Ada Lovelace", "properties": { "email": "ada@acme.com" } },
+    { "ref": "c1", "profileSlug": "company", "title": "Acme Corp",    "properties": { "website": "https://acme.com" } }
+  ],
+  "relations": [ { "sourceRef": "p1", "targetRef": "c1", "type": "works_at" } ] }
+```
 
-## Dedup within the pipeline
+## Dedup — strong signals only
 
-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.
+The dedup signals are the exact property keys `email`, `phone`, `website`, `linkedinUrl`, `twitterHandle`, `githubUsername`. Sending a URL under any other key (e.g. a bare `url`) is **not** a dedup signal and will duplicate the entity.
 
-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.
+A same-title hit in a _different_ kind is **advisory** (`crossKindCandidates`), never an auto-merge. So "no exact match" does **not** mean "safe to create" when advisory candidates come back — review them first. To link to something that already exists, give it a `ref` plus `existingEntityId`.
 
-## Presenting proposals to the user
+## Name-refs — never ask for a UUID
 
-A good UX turn:
+Reference an existing project by **name**, not id — the server resolves `{ project: { name: "Synap" } }` against the caller's own projects. Exact match ⇒ it files there; no match ⇒ it proposes/creates, never silently mis-files. Never ask the user for a UUID.
 
-> 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?
+## Placement — existing lenses only
 
-Keep the user in control. Don't auto-execute without confirmation unless the user explicitly told you to.
+Capture **never invents a workspace** (or other meta-structure) to "find a home". It routes into **existing** workspaces/projects/profiles — `synap orient` + `list_profiles` first when placement is ambiguous. Structure emerges progressively: capture into what exists; suggest a new profile only when the user repeatedly tracks a thing that fits none, and a view only once that profile has 3+ entities. Missing structure is an escalation-ladder L2→L3 conversation (discover, then propose), not a side effect of capture. `global: true` stores a pod-wide runbook (text lane only).
 
-## Edge cases
+## Rejection is a correct outcome — don't retry
 
-- **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.
+`status: "rejected"` means the door protected the graph on purpose. Read the `reason` and act, don't loop:
 
-## Followup question
+- **`already-known`** — a lone entity carrying nothing but identity signals that already resolve to an existing one. Its id is returned; re-send with content / extra properties / relations to **enrich** it instead.
+- **`no-durable-content`** — nothing storable was sent (empty / whitespace / punctuation-only). Don't call capture with zero substance.
+- **`structuring-unavailable`** — text lane only: the AI structurer is down. Tell the user and retry later.
 
-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.
+(There is no "recall-loop" rejection.)