@synap-core/cli 1.7.0 → 1.10.0

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)

package/skills/synap/worked-examples.md

@@ -0,0 +1,53 @@
+## 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.

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.