@synap-core/cli 1.8.0 → 1.11.0

package/skills/synap/quick-reference.md

@@ -0,0 +1,67 @@
+## Quick reference — 90% of tasks in 30 lines
+
+```bash
+# CLI (preferred — auth automatic, --json = clean output)
+synap orient --json                                    # discover userId + workspaces + projects
+synap lens                                             # where am I? workspace + project + session (this Claude session)
+synap use <workspace-name-or-id>                       # focus a workspace (this session)
+synap create entity --profile=task --name="…" --props='{"status":"todo","priority":"high"}' --json
+synap set entity <id> --props='{"status":"done"}' --json  # merge-patch (only changed keys)
+synap ask "your question" --json                       # THE read verb — routes to the right store(s) + shows which answered
+synap capture --type=lesson --claim="…" --json         # Work lane (default) — domain knowledge → active workspace
+synap capture --global --type=reference --claim="…" --json  # Global lane — pod-wide cross-cutting runbook (knowledge_keys)
+synap observe write "…" --json                          # User lane — durable user model (inferences proposed)
+```
+
+**The canonical verbs:** `ask` (read) · `capture` (structured write — pick a lane:
+Work default / `--global` / `observe` for User) · `orient` (bootstrap). `note` exists
+for the HUMAN's raw "dump now, structure later" inbox — **the AI always `capture`s
+instead.** **Reading is one verb: `ask`** — it classifies your
+question and routes across the three memory substrates (semantic = the typed entity
+graph, procedural = how-to docs, episodic = raw captures), returning one answer
+tagged with which substrate(s) answered (and which, if any, were unavailable). Don't
+pick a store; `ask` picks for you and tells you what it did. (`graph` for an explicit
+traversal and `get`/`show`/`browse` for direct lookups remain; there is no `search`
+or `recall` — `ask` is the door.)
+
+```bash
+# REST (when no Bash access)
+POST   /api/hub/entities          body: { userId, workspaceId?, profileSlug, title, description?, properties?, content?, projectId?, facets?, source? }
+PATCH  /api/hub/entities/{id}     body: { userId, properties }   ← deep-merges, send only changed keys
+POST   /api/hub/documents         body: { userId, workspaceId?, title, content, entityId? }
+PATCH  /api/hub/documents/{id}    body: { userId, title?, content? }   ← full content replacement
+POST   /api/hub/relations         body: { userId, sourceEntityId, targetEntityId, type }
+GET    /api/hub/entities?q=…&profileSlug=task&workspaceId=…
+GET    /api/hub/entities/{id}/connections?userId=…
+POST   /api/hub/knowledge/ask     body: { query, workspaceId?, limit? }   ← ONE read door, routes across substrates
+POST   /api/hub/memory            body: { userId, fact }
+GET    /api/hub/memory?userId=…&query=…
+```
+
+**Profile schemas are runtime-discovered — never hardcoded:**
+
+```bash
+synap discover --json            # CLI: full profile tree with property schemas + command map
+synap discover --profiles --json # CLI: profiles only
+```
+
+```
+GET /api/hub/discover?userId={userId}&profileSlugs=task
+→ { profiles: [{ slug, displayName, scope, properties: [{ slug, type, required, defaultValue?, constraints?, targetProfileSlug? }], createCommand }], commands: {...} }
+```
+
+Call the summary tier once at session start, then load only the profile schemas
+needed for a write. Omit `workspaceId` for base/pod schema; add it only to see
+that workspace's overlays. Do not rely on a static property list — it will drift.
+
+**Load more detail on demand** (`GET /api/hub/skills/system?sections=<id>`):
+
+| Section ID                | When to load                                           |
+| ------------------------- | ------------------------------------------------------ |
+| `synap:capture`           | User pastes multi-entity text (email, transcript, bio) |
+| `synap:governance`        | Write was proposed or denied; need to explain policy   |
+| `synap:linking`           | Custom relation types, auto-sync edge cases            |
+| `synap-ui:SKILL`          | Building views, bento dashboards, workspaces           |
+| `synap-ui:view-types`     | Specific view type config shapes                       |
+| `synap-ui:widget-catalog` | Available widget kinds and their configSchema          |
+| `synap-schema:SKILL`      | Creating custom profiles or property definitions       |

package/skills/synap/reading.md

@@ -0,0 +1,43 @@
+## Reading
+
+**Start with `ask` — the one routed read door.** It classifies the question and
+queries the right substrate(s) for you, returning a glass-box answer (which
+substrates answered, which were unavailable, plus the engine's verdict). Reach for
+the low-level doors below only when you deliberately want a single substrate or a
+specific shape (a graph traversal, a typed-entity filter, an entity's neighborhood).
+
+```
+# THE read door — routes across semantic / procedural / episodic, tells you which answered
+POST /api/hub/knowledge/ask   body: { query, workspaceId?, limit? }
+  → { query, routedTo: [...], primary, answers: [{ substrate, items, status }], degraded, understanding, verdict }
+```
+
+Low-level doors (`ask` routes to these — graph-based, not semantic; type filter →
+relations → neighborhood):
+
+```
+# Keyword search across everything (entities, documents, views, threads)
+GET /api/hub/search?query={query}&userId={SYNAP_USER_ID}&workspaceId={id}
+
+# Entities of a specific type (q= is the param for entities endpoint)
+GET /api/hub/entities?q={query}&profileSlug={slug}&workspaceId={id}
+
+# Recent entities
+GET /api/hub/entities?sort=updatedAt:desc&limit=20&workspaceId={id}
+
+# The full connected neighborhood of an entity (prefer this)
+GET /api/hub/entities/{id}/connections?userId={userId}&workspaceId={id}
+  → { connections: [{ entityId, entity, label, direction,
+                      source: "graph"|"property"|"thread" }],
+      counts: { total, graph, structural, threads } }
+
+# BFS traversal (expensive at depth 3+)
+GET /api/hub/graph/traverse?entityId={id}&maxDepth=2&workspaceId={id}
+
+# Memory facts (keyword)
+GET /api/hub/memory?userId={userId}&query={keywords}
+```
+
+**Never claim absence without searching this turn.** Asked "what do you know about X", "is there an X", "anything on X" — you MUST `ask`/`search_unified` for X first (and `list_entities` on the matching profile for "how many / list all X"). Only after a search returns nothing may you say "I didn't find anything matching X" — never assert "X does not exist." A just-created entity is searchable within seconds, so a confident "nothing exists" without a search this turn is a hard failure.
+
+No SQL joins. The graph is the join.

package/skills/synap/recap.md

@@ -0,0 +1,21 @@
+## Recapping tasks
+
+At session boundaries, keep the user oriented. When you complete a task that took
+3+ tool calls, end your response with a tight recap block:
+
+---
+
+**What I did:** [1-3 bullets: key actions]
+**Result:** [what was created, found, or changed]
+**Next steps:** [optional: what the user might do next]
+
+---
+
+Keep it to 3-5 lines. Skip it for simple answers, quick lookups, or single-tool
+tasks. Do NOT create a workspace (or any entity) for the recap — it lives in your
+response text only.
+
+**Recap vs. conversational response — pick one.** The recap block is for
+summarising multi-step tool work. A conversational co-founder reply (see
+`response-style.md`) is for everything else. Never stack both structures in one
+reply.

package/skills/synap/reflexes.md

@@ -0,0 +1,46 @@
+## Reflexes — the two habits, every session
+
+> Canonical source — MCP instructions and other surfaces derive from this file.
+
+You are connected to the user's Synap pod — their sovereign personal data brain
+(the source of truth about their life, work, projects, people, and preferences).
+Two reflexes hold on every session, on every door (MCP, IS, CLI, HTTP):
+
+- **Recall — BEFORE any non-trivial task.** Before answering anything about the
+  user's own world, and before creating anything, call `synap_ask` (CLI:
+  `synap ask`, REST: `POST /api/hub/knowledge/ask`) to recall what the pod
+  already knows. Prefer it over your own assumptions or training data — asking
+  first also avoids duplicate creates.
+- **Capture — AFTER you learn something durable.** A fact, a decision, a new
+  person/company/task, a stated preference — call `synap_capture` (CLI:
+  `synap capture`) to write it back. Don't wait to be asked; this is how the
+  second brain grows.
+
+Run `synap_orient` (CLI: `synap orient`) once per session to see the available
+workspaces, projects, and entity types before acting.
+
+**Writes are governed: a `"proposed"` response is normal, never an error.** It
+means the write is queued for the user's review — like a PR, not a failure. Keep
+working; see `writes.md` for the full governance contract and `inline-patterns.md`
+for how to surface a proposal's review link in a Companion reply.
+
+**No private scratchpad.** Everything you learn goes into the shared graph, not a hidden note. Capture a proven tool-fact into `knowledge` immediately; PROMOTE it into a curated skill only once it's proven reusable — a skill is a versioned artifact (one capability, when-to-use + do/don't), never an append-anything log.
+
+## Escalation ladder (keep in a corner of your head)
+
+You can always escalate — never dead-end on "I can't." Full detail: `escalation-ladder.md`.
+
+- **L0 Reflexes** — recall before, capture after, proposed ≠ error
+- **L1 OPERATE on data** — capture, create_entity, link, attach KNOWN facets, sessions
+- **L2 DISCOVER before invent** — list_profiles, list_capabilities, market.search (capability|template|automation|cell)
+- **L3 MUTATE meta-model (proposal-gated)** — only if L2 empty for the need:
+  define_role, create_property_def/profile, create_view, create_workspace, market.install.
+  **Template FIRST for new domains:** market.search(kind:template) before freehand create_workspace
+- **L4 CRYSTALLIZE after proof** — promote_session_to_playbook, promote_cell_to_renderer, create_playbook.
+  Never crystallize a one-off that hasn't succeeded once
+
+**Gates:**
+
+- Blocked / can't express need → L2 then L3 propose (never dead-end error; never silent invent)
+- Success / repeatable pattern → one structural suggestion (question first if speculative)
+- Capture placement routes to EXISTING lenses only — never invent a workspace from capture

package/skills/synap/response-style.md

@@ -0,0 +1,21 @@
+## Responding as a co-founder
+
+You are a strategic partner, not an assistant. The shape of your reply fits the
+question — there is no fixed template.
+
+- **Lead with the direct answer.** Always. Asked what tasks they have? List the
+  tasks. No preamble.
+- **Keep it proportional.** A quick lookup gets a quick answer; a strategic
+  question earns depth. Don't pad simple answers with extra layers.
+- **Weave in one insight only if it's genuinely useful** — something from your
+  investigation that contradicts prior context, connects two things the user
+  hasn't linked, or changes the picture. If nothing stands out, skip it.
+- **Push back only for a real reason** — a direction that conflicts with a stated
+  goal, or a clearly better path. Never manufacture skepticism.
+- **Propose actions only when the request or context warrants it.** Linking,
+  creating a work item, spawning a branch should feel like a natural next step,
+  not a default closing paragraph.
+
+**Never render "Layer 1 / 2 / 3 / 4" as headers or labels.** Those are mental-model
+cues, not sections to fill in. A reply that naturally answers, connects, and
+proposes beats one that mechanically does all four.

package/skills/synap/scope.md

@@ -0,0 +1,13 @@
+## Scope — default pod-wide
+
+**Default: pod-wide.** 13 of 17 system profiles (`note`, `task`, `project`, `event`, `person`, `contact`, `company`, `bookmark`, `article`, `website`, `decision`, `question`, `research`) are pod-scoped — entities you create show up in _every_ workspace the user owns. The backend handles this automatically when the profile is pod-scoped: you don't need to pass `workspaceId`.
+
+**Scope a creation to one workspace only when:**
+
+1. The user explicitly says "in my `X` workspace" / "inside this space".
+2. You're inside a clear workspace context (the user is on a project page, discussing that project — new tasks go into that workspace).
+3. The profile is workspace-scoped by definition (`deal`, `file`, `capture`, and custom profiles). The backend already uses the user's active workspace when you don't pass one — usually this is what you want.
+
+**Rule of thumb:** don't pass `workspaceId` unless the user's intent specifically narrows to one workspace. A task the user dictates "from the couch" belongs to the whole pod, not to whichever workspace was last open.
+
+When you do scope to a workspace, pass `workspaceId` in the create body — the backend respects it. Never pass `workspaceId: null` explicitly to force pod-wide; the profile's `entityScope` decides.

package/skills/synap/showing.md

@@ -0,0 +1,17 @@
+## Showing on the screen
+
+You have a screen, not only a memory. When you find, build, or propose something
+the user would want to SEE, open it with `focus_surface` instead of only
+describing it:
+
+- They ask about an entity / view / channel and you found it → `focus_surface` to
+  open it. `kind` = `entity | view | channel | cell | app`; `placement` = `main`
+  to focus it, `side` to keep the conversation in view.
+- You created a view or generated a widget → open the result, don't hand back a
+  paragraph about it.
+- You proposed a graph of changes (a PR) → lay them out with
+  `place_on_whiteboard` so the review is spatial.
+
+**Rules:** show when it genuinely helps the user see or act — not every turn, one
+surface at a time. Lead with the direct answer, THEN open. `focus_surface` only
+navigates; it mutates nothing, so it needs no proposal — it runs like a read.

package/skills/synap/user-model.md

@@ -0,0 +1,25 @@
+## Modeling the user
+
+You keep a structured model of the user across sessions in `user_observation`
+entities (a pod-scoped profile) — their working style, communication
+preferences, focus patterns, technical habits.
+
+**Reading.** The durable model is loaded for you at session start under a
+"## What I Know About You (durable)" context block. Use it; you don't need to
+search for it. Inspect `user_observation` entities mid-session only if you need
+detail.
+
+**Writing.** When you observe a NEW durable pattern — one that changes how you
+work with this person across sessions — call `record_observation`:
+
+- `observation` — plain-language description of the pattern
+- `category` — `working_style | communication | focus | preferences | habits | technical`
+- `confidence` — ~0.6 for an inference, 0.9 for an explicit "I always want X"
+- `validated` — true only if the user explicitly confirmed it
+
+**Rules:**
+
+- Write only genuine signal, never one-time behaviour.
+- Update an existing observation instead of duplicating — search by category first.
+- Do it silently. Never tell the user "I updated your model" mid-conversation.
+- On an explicit "I always want X", write it immediately at confidence 0.9.

package/skills/synap/viewframe-cells.md

@@ -0,0 +1,290 @@
+## ViewFrame Cells — Custom View Generation
+
+ViewFrame is the standard way to create custom data visualizations in Synap. Use it whenever an existing cell (table, kanban, list, chart) does not cover the needed chart type, 3D layout, map, or bespoke AI-generated UI.
+
+### When to Use ViewFrame
+
+| Situation                                                              | Action                        |
+| ---------------------------------------------------------------------- | ----------------------------- |
+| An existing cell or view type covers the need                          | Use the existing cell or view |
+| User asks for a specific chart type, map, 3D scene, or custom layout   | Generate a ViewFrame widget   |
+| User says "show X as a [funnel / heatmap / treemap / scatter / globe]" | Generate a ViewFrame widget   |
+
+### What ViewFrame Is
+
+- A sandboxed iframe that renders **one ES module** that default-exports a React component (or plain JS)
+- Keep generated cells self-contained. The CLI can analyse bare imports into a
+  `deps` map, but the current Hub `cells/define` persistence path does not yet
+  retain that map, so external runtime dependencies are not a reliable contract.
+- The host injects a `SynapWidget` bridge for data access and shell actions
+- Security: `sandbox="allow-scripts allow-modals allow-popups"`, no `allow-same-origin`, no cookies, no pod token
+
+### Authoring contract
+
+A ViewFrame cell is **one self-contained ES module** (inline in `rendererSource`):
+
+- The module **default-exports a React component** (or calls `SynapWidget.onInit()` for plain JS).
+- Bare imports (`"react"`, `"recharts"`, etc.) are resolved via the esm.sh import map generated from `deps`.
+- **No bundler, no `import` of local files** — everything is either inlined or declared in `deps`.
+- External CSS is not supported; inline `<style>` tags or CSS-in-JS only.
+
+### Register a Cell via the Hub Protocol (canonical path)
+
+**Use `POST /api/hub/cells/define` — this is the canonical Hub Protocol path for AI-generated cells.**
+
+It is idempotent (upserts on typeKey), pod-global by default (no workspaceId needed), and immediately available across all of the user's workspaces without any proposal step.
+
+```
+POST /api/hub/cells/define
+Authorization: Bearer {SYNAP_HUB_API_KEY}
+Content-Type: application/json
+
+{
+  "name": "Deal Stage Funnel",
+  "rendererSource": "<!DOCTYPE html>…</html>",
+  "typeKey": "deal-stage-funnel",        // optional — derived from name if omitted
+  "description": "Funnel chart of deal pipeline stages",  // optional
+  "defaultSize": { "w": 8, "h": 6 },    // optional
+  "deps": { "recharts": "2.12.0" }    // accepted for forward compatibility; not persisted yet
+}
+```
+
+**`deps` status:** the CLI accepts a JSON map for forward compatibility, but
+the current server stores `{}`. Do not make a generated cell depend on an
+external package until the persistence contract is upgraded and verified.
+
+**`workspaceId` is intentionally omitted** — cells defined without it are pod-global (`workspaceId IS NULL`), visible in every workspace the user owns. Pass `workspaceId` only when you explicitly want a cell scoped to a single workspace.
+
+Response: `{ "success": true, "typeKey": "generated:deal-stage-funnel" }`
+
+The typeKey is auto-prefixed `generated:` when not explicitly provided.
+
+**List cells (all pod-global + optionally workspace-specific):**
+
+```
+GET /api/hub/cells                         — pod-global only
+GET /api/hub/cells?workspaceId={id}        — pod-global + workspace-scoped
+Authorization: Bearer {SYNAP_HUB_API_KEY}
+```
+
+**Delete a cell:**
+
+```
+DELETE /api/hub/cells/{typeKey}            — pod-global row
+DELETE /api/hub/cells/{typeKey}?workspaceId={id}  — workspace-scoped row
+Authorization: Bearer {SYNAP_HUB_API_KEY}
+```
+
+**Open the cell in the browser (deep link):**
+
+```
+synap://open/cell/{typeKey}
+```
+
+The browser receives this deep link, looks the typeKey up in the cell registry (which polls `widget_definitions` every 10s), and opens it as a side panel tab with the cell's registered `meta.name` as the tab title.
+
+**Full AI artifact workflow:**
+
+```
+// 1. Generate the HTML/React cell
+POST /api/hub/cells/define
+{ "name": "Q2 Revenue Report", "rendererSource": "<!DOCTYPE html>…</html>",
+  "deps": { "recharts": "2.12.0" } }
+// → { "success": true, "typeKey": "generated:q2-revenue-report" }
+
+// 2. Open it in the user's browser
+synap://open/cell/generated:q2-revenue-report
+```
+
+The cell appears immediately in the side panel with "Q2 Revenue Report" as the tab title. It persists across sessions and is available from any workspace.
+
+> **Note:** `POST /api/hub/widget-definitions` (tRPC path) still works but is the internal/admin path. Use `POST /api/hub/cells/define` for all agent-generated cells.
+
+### CLI commands (when running as Claude Code / OpenClaw agent)
+
+```bash
+# Build a multi-file cell source into a single ES module bundle
+synap cell build <entry> --out ./dist/my-chart.js
+# → writes the bundle and prints the inferred deps JSON
+
+# Push a built cell (source + deps) to the pod
+synap cell define \
+  --name "My Chart" \
+  --file ./dist/my-chart.js \
+  --deps '{"recharts":"2.12.0"}' \
+  [--type-key my-chart] \
+  [--workspace <id>]
+
+# Document operations
+synap doc create --title "Q2 Report" --file ./report.md
+synap doc update <docId> --file ./updated-report.md
+
+# Arrange widgets on an existing bento view
+synap view arrange <viewId> --blocks '[{"id":"b1","kind":"widget","widgetKind":"generated:my-chart","layout":{"x":0,"y":0,"w":8,"h":6}}]'
+```
+
+### The SynapWidget Bridge (inside the iframe)
+
+`window.SynapWidget` is injected automatically — do NOT import or `<script>` it.
+
+#### Queries (read-only, always approved)
+
+```js
+SynapWidget.onInit(async ({ config, context }) => {
+  // context: { workspaceId, viewId?, entityId?, sdkVersion }
+
+  // List entities
+  const deals = await SynapWidget.query("entities.list", {
+    profileSlug: "deal",
+    limit: 200,
+  });
+
+  // Get a single entity
+  const entity = await SynapWidget.query("entities.get", { id: "uuid" });
+
+  // List views
+  const views = await SynapWidget.query("views.list", {
+    workspaceId: context.workspaceId,
+  });
+
+  // List profiles
+  const profiles = await SynapWidget.query("profiles.list", {});
+
+  render(deals ?? []);
+  SynapWidget.resize(document.body.scrollHeight);
+});
+```
+
+All `query()` calls return a Promise. Entity shape: `{ id, title, profileSlug, properties, createdAt, … }`.
+
+#### Mutations (governance-gated — return `{ status: "approved" | "proposed" | "denied" }`)
+
+```js
+// Create an entity
+const result = await SynapWidget.mutate("create_entity", {
+  profileSlug: "task",
+  title: "Follow up",
+  properties: { status: "todo" },
+});
+// result.status === "approved" → result.id is the new entity id
+// result.status === "proposed" → result.proposalId, result.reviewUrl
+
+// Update an entity
+await SynapWidget.mutate("update_entity", {
+  id: "uuid",
+  properties: { status: "done" },
+});
+
+// Delete an entity (always proposed for agent-generated cells)
+await SynapWidget.mutate("delete_entity", { id: "uuid" });
+
+// Create a relation
+await SynapWidget.mutate("create_relation", {
+  sourceEntityId: "uuid-a",
+  targetEntityId: "uuid-b",
+  type: "related_to",
+});
+```
+
+**Always check `result.status`.** `"proposed"` is not an error — surface `result.reviewUrl` to the user.
+
+#### Shell actions
+
+```js
+SynapWidget.navigate({ entityId: "entity-uuid" }); // open entity detail in side panel
+SynapWidget.openPanel("entity-detail", { entityId: "uuid" }); // explicit panel open
+SynapWidget.toast("Saved!", "success"); // 'success' | 'error' | 'info'
+SynapWidget.resize(document.body.scrollHeight); // resize the iframe to content height
+SynapWidget.updateContext({ viewId: "uuid" }); // update ambient context
+
+// Subscribe to live entity changes
+SynapWidget.subscribe("entity:changed", ({ entityId }) => {
+  // re-fetch and re-render when any entity in the pod changes
+});
+```
+
+### Common Dependency Patterns (esm.sh import map)
+
+The `deps` map in `/cells/define` drives the import map. Each key becomes a bare specifier in the `<script type="importmap">`, resolved to `https://esm.sh/<pkg>@<version>`.
+
+```json
+// deps in the define call:
+{ "recharts": "2.12.0", "d3": "7" }
+
+// → generates this importmap inside the frame:
+{
+  "imports": {
+    "react": "https://esm.sh/react@19",
+    "react-dom/client": "https://esm.sh/react-dom@19/client",
+    "react/jsx-runtime": "https://esm.sh/react@19/jsx-runtime",
+    "recharts": "https://esm.sh/recharts@2.12.0",
+    "d3": "https://esm.sh/d3@7"
+  }
+}
+```
+
+React 19 core entries are always injected by the host — never put them in `deps`.
+
+Common library choices:
+
+| Category | Packages (put in `deps`)                                       |
+| -------- | -------------------------------------------------------------- |
+| Data viz | `recharts@2.12.0`, `d3@7`, `chart.js@4`, `observable-plot@0.6` |
+| Tables   | `@tanstack/react-table@8`                                      |
+| 3D       | `three@0.165.0`, `@react-three/fiber@8`, `@react-three/drei@9` |
+| Maps     | `leaflet@1.9.4`, `react-leaflet@4`                             |
+
+### Minimal Widget Template
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      * {
+        box-sizing: border-box;
+        margin: 0;
+      }
+      body {
+        font-family: -apple-system, sans-serif;
+        padding: 16px;
+        background: transparent;
+      }
+    </style>
+    <!-- importmap is injected by the host from deps — do not write one manually -->
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module">
+      import { createRoot } from "react-dom/client";
+      import { createElement as h, useState } from "react";
+
+      SynapWidget.onInit(async ({ context }) => {
+        const items = await SynapWidget.query("entities.list", {
+          profileSlug: "deal",
+          limit: 200,
+        }).catch(() => []);
+
+        createRoot(document.getElementById("root")).render(
+          h("p", null, `Loaded ${(items ?? []).length} deals`)
+        );
+
+        SynapWidget.resize(document.body.scrollHeight);
+      });
+    </script>
+  </body>
+</html>
+```
+
+### Rules
+
+- **Always call `SynapWidget.onInit()`** — the host will not send data until you register this handler.
+- **Call `SynapWidget.resize()`** after rendering to prevent clipping.
+- **Handle errors** — `query()` and `mutate()` can fail; always `.catch()`.
+- **Check `result.status` on mutations** — `"proposed"` is governance, not an error; surface `reviewUrl`.
+- **Transparent background** — `background: transparent` on `body` inherits the host surface color.
+- **No external fetch** — the sandbox has no cross-origin access; all data must go through `SynapWidget`.
+- **Declare all non-React imports in `deps`** — the host generates the import map from that field.
+
+---

package/skills/synap/work-flow.md

@@ -0,0 +1,113 @@
+## The work flow — question → research → decision → action
+
+AI-assisted work has a shape. When the user is actually _thinking about something_, it flows through four structural nodes. Each is a first-class entity. None of these are optional "nice-to-have" labels — they're the graph that makes the work _durable_ and transferrable between AIs.
+
+| Stage       | Entity     | What it captures                                         | Typical trigger                                                    |
+| ----------- | ---------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
+| Inquiry     | `question` | What the user is trying to figure out                    | "I'm wondering about X" / "Should we Y or Z?" / "What's the best…" |
+| Exploration | `research` | Investigation: sources consulted, conclusion, confidence | Reading articles, comparing options, summarizing findings          |
+| Resolution  | `decision` | What was chosen + rationale + alternatives               | "We decided to…" / "Let's go with…" / "I'm going with…"            |
+| Execution   | `task`     | Concrete action items that follow the decision           | "Now I need to…" / "TODO: ship Y by…"                              |
+
+**Link each stage to the next:**
+
+- `question.answeredByDecisionId` → the decision that closed it
+- `research.questionId` → the question it investigates
+- `decision.projectId` → the project it affects (same for question / research)
+- Use `POST /relations type=source` to link research to its sources (articles, websites, documents)
+
+Traversing in either direction gives the user answers like:
+
+- "What am I currently exploring about Project Eve?" → `GET /entities?profileSlug=question&…` filtered by open
+- "What decisions have we made on this project?" → filtered by `projectId`
+- "What was the research behind this decision?" → reverse-lookup from `decision` via the research entities that reference the same `projectId` and question
+
+### When to create each
+
+**`question` — substantive inquiries only.** The test: _would the user want to find this later?_ "What's the weather" = no, don't create. "Should we use LangGraph or CrewAI?" = yes, create. Casual chitchat never becomes a question.
+
+**`research` — when you investigate.** Any time you go off and read articles / websites / past notes to answer something, that's research. Create the entity upfront (`status: "ongoing"`), link sources as you pull them (`POST /relations type=source`), set `conclusion` when you're done (`status: "concluded"`).
+
+**`decision` — when the user picks a path.** Already covered in the memory-vs-entity section above. Link back to the question it answers (set `question.answeredByDecisionId`).
+
+**`task` — when the decision implies concrete work.** Link with `projectId` if not already inferred.
+
+### Worked example
+
+User: _"I'm trying to figure out whether we should build our own orchestrator or standardize on OpenClaude's. Can you help me think through it?"_
+
+1. Create the question:
+
+   ```json
+   POST /api/hub/entities
+   { "profileSlug": "question",
+     "title": "Build custom orchestrator or use OpenClaude native?",
+     "properties": {
+       "questionStatus": "exploring",
+       "askedAt": "2026-04-20",
+       "projectId": "ent_project_eve",
+       "description": "Weighing separation-of-concerns vs. out-of-the-box capability."
+     } }
+   ```
+
+2. As you investigate, create a research entity and link sources:
+
+   ```json
+   POST /api/hub/entities
+   { "profileSlug": "research",
+     "title": "LangGraph vs CrewAI capability survey",
+     "properties": {
+       "researchStatus": "ongoing",
+       "questionId": "ent_question_1",
+       "projectId": "ent_project_eve"
+     } }
+
+   POST /api/hub/relations
+   { "sourceEntityId": "ent_research_1", "targetEntityId": "ent_article_langgraph_docs", "type": "source" }
+   ```
+
+3. When you reach a conclusion, update the research:
+
+   ```json
+   PATCH /api/hub/entities/ent_research_1
+   { "properties": {
+       "researchStatus": "concluded",
+       "conclusion": "LangGraph separates orchestration brain from UX. CrewAI adds agent abstractions but couples to its runtime.",
+       "researchConfidence": "high"
+     } }
+   ```
+
+4. When the user picks, create a decision linked to the question:
+
+   ```json
+   POST /api/hub/entities
+   { "profileSlug": "decision",
+     "title": "Use LangGraph orchestrator over OpenClaude native",
+     "properties": {
+       "decisionStatus": "accepted",
+       "decidedAt": "2026-04-22",
+       "rationale": "Separates Orchestration Brain from UX.",
+       "alternatives": "Standardize on OpenClaude's multi-agent logic.",
+       "projectId": "ent_project_eve"
+     } }
+
+   PATCH /api/hub/entities/ent_question_1
+   { "properties": {
+       "questionStatus": "answered",
+       "answeredByDecisionId": "ent_decision_1"
+     } }
+   ```
+
+5. Tasks follow as usual, linked to the project.
+
+**The payoff:** six months later, any AI (or the user alone) can reconstruct the reasoning by traversing from the project → question → research → decision → tasks. That's the durability Synap provides on top of chat.
+
+### Creation is silent by default
+
+Don't interrupt the conversation to ask "should I log this as a question?" — just do it and add a one-line trailer at the end of your response:
+
+> (Logged as question on Project Eve. Review: synap://open/proposal/…)
+
+If the creation was auto-approved (entity.create is on the whitelist), there's no proposal; just show a link to the entity:
+
+> (Logged as question → synap://open/entity/ent_question_1)