@synap-core/cli 1.10.0 → 1.11.0

package/skills/synap/digesting-a-channel.md

@@ -22,6 +22,31 @@ Do NOT assume this channel is a CRM. Do NOT reach for a contacts/notes/links tem
 
 Every person, company, deal, or resource you are about to propose may already exist. Resolve first, create only what is new. Match on STRONG signals — email, phone, url, handle — not a fuzzy name. Run ONE batched search over all candidates, reuse on match (add the newly-seen handle or spelling as an alias), and mint an entity only for something genuinely absent. The full resolve → reuse → alias discipline in `crm.md` applies here verbatim.
 
+## When the channel is UNBOUND — classify it and PROPOSE a bind
+
+A channel that is **not yet bound to any entity** (no `contextObjectId`, no `branchPurpose`) is a different job from a normal digest. Before you mine it for signal, answer a prior question: **what IS this channel, and which entity does it belong to?** This is the "I think #acme is a client — link it?" affordance.
+
+Work it in this order — identity FIRST, classification, then propose:
+
+1. **Read the window + the channel NAME.** The name (`acme`, `weex-partnership`, `general`, `eng-team`) is often the strongest single signal; the messages confirm or correct it. Who posts, what they talk about, whether it reads client-facing or internal.
+2. **Resolve the entity FIRST — do NOT mint a duplicate.** Match the channel to something that already exists in the pod on STRONG signals — the name, a domain/email/url mentioned, a handle — using `resolve_identity` / a batched search. Only if nothing genuinely matches do you consider a new entity, and even then propose the entity through the normal capture door, never a throwaway. The whole point of binding is to point the channel at the REAL thing; binding to a fabricated duplicate is worse than not binding at all.
+3. **Classify what the channel is** — pick the one that fits:
+   - **client** — a client-facing channel (mixes their people and ours). Suggests `branchPurpose: "client-comms"`.
+   - **partner** — a partner/vendor relationship channel. Suggests `branchPurpose` like `"partner"` (or leave to the human).
+   - **internal team** — everyone here is OUR team; ops/eng/planning. Suggests `branchPurpose: "team"`.
+   - **project** — work-scoped, cross-cutting. Suggests a project-oriented purpose (or `"team"` if internal).
+4. **Emit ONE governed bind proposal** with `propose_channel_bind` — `channelId` (the Synap channel UUID), the resolved `contextObjectId`, and your suggested `branchPurpose` + a one-line `reasoning`. The result comes back `proposed`: that is the system working. You do not bind — the operator confirms.
+
+### The firewall — the one rule you never bend
+
+`branchPurpose: "client-comms"` is **irreversible**. Once a channel is client-comms the backend refuses to reclassify it. So:
+
+- **Only suggest `client-comms` when you are confident the channel is client-facing.** A `general`, `random`, or internal team channel must NEVER be proposed as client-comms — misfiling an internal room as client comms is exactly the mistake the firewall exists to prevent.
+- **When the side is unclear, OMIT `branchPurpose`** and let the human choose on approval. An unbound bind with the purpose left open is fine; a wrong client-comms bind is not.
+- You always PROPOSE. There is no path here where you silently set client-comms. The human owns that decision by approving.
+
+Auto-binding on strong identity signals lives elsewhere; **from this skill you always propose.**
+
 ## Role-aware people guard (read this twice)
 
 WHO is in the channel changes what a person IS. Get this wrong and you propose your own teammates as leads.

package/skills/synap/mental-model.md

@@ -25,13 +25,13 @@ Ask yourself: _who does this knowledge serve?_ **There is no private AI scratchp
 
 ### Data layers — the graph itself
 
-| Layer         | What it is                                     | When to use                                              |
-| ------------- | ---------------------------------------------- | -------------------------------------------------------- |
-| **Entities**  | Typed structured nodes (task, person, …)       | Anything worth filtering, sorting, or linking            |
-| **Relations** | Typed edges between entities                   | Making the graph traversable                             |
-| **Documents** | Long-form markdown attached to an entity       | Meeting notes, research writeups, articles               |
-| **Threads**   | Channel conversations, optional entity context | Posting to the user's personal AI channel                |
-| **Proposals** | Writes queued for human approval               | Governance for some mutations (not an error — see below) |
+| Layer         | What it is                                                                                                                                       | When to use                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| **Entities**  | Typed structured nodes (task, person, …)                                                                                                         | Anything worth filtering, sorting, or linking                                                                |
+| **Relations** | Typed edges between entities                                                                                                                     | Making the graph traversable                                                                                 |
+| **Documents** | Long-form versioned body attached to an entity — auto-materialized from an entity's `content`, or created standalone via `synap_create_document` | Meeting notes, research writeups, articles — **never** a `file`/`document`-kind entity for text you authored |
+| **Threads**   | Channel conversations, optional entity context                                                                                                   | Posting to the user's personal AI channel                                                                    |
+| **Proposals** | Writes queued for human approval                                                                                                                 | Governance for some mutations (not an error — see below)                                                     |
 
 ### Key profiles for AI use
 

package/skills/synap/multi-entity-capture.md

@@ -1,10 +1,12 @@
 ## Multi-entity capture from free-form text
 
-When the user pastes a block of unstructured content (a meeting transcript, an email, a LinkedIn bio), use the capture pipeline instead of chaining manual creates:
+When the user pastes a block of unstructured content (a meeting transcript, an email, a LinkedIn bio) or when several related things come up at once, send it through the **one capture door** — `synap_capture` (CLI: `synap capture`). Don't chain manual creates, and don't run a two-step "structure then commit" dance.
+
+The payload is a gradient in a single call:
 
 ```
-POST /api/hub/capture/structure   → returns proposals + relations
-POST /api/hub/capture/execute     → commits (after user confirms)
+{ "text": "…paste the raw content…" }              → the AI structures it into entities
+{ "entities": [ … ], "relations": [ … ] }          → you supply the graph directly (refs link them)
 ```
 
-The pipeline extracts multiple entities with their relations in one LLM call. Read **`capture.md`** for the full flow.
+Everything lands as ONE reviewable proposal (or auto-applies when every op is safe), and you get back one receipt — `status: "applied" | "proposed" | "rejected"`. `proposed` is success: surface the review link. There is no separate commit step. Read **`capture.md`** for the full flow, dedup signals, name-refs, and reject reasons.

package/skills/synap/worked-examples.md

@@ -51,3 +51,24 @@
    ```
 
 3. If the user said why ("interesting for the onboarding project"), also create a relation to that project — never drop the reason as a plain comment, turn it into a link.
+
+### Example 4 — "Write up a strategic plan for the Q3 launch"
+
+You are authoring this text yourself — it is not a file you have. Don't create
+a `file`/`document`-kind entity and stuff the Markdown into it.
+
+1. Search for an existing plan: `GET /entities?q=Q3 launch&profileSlug=knowledge&workspaceId=…` → none
+2. Create a CONTENT-kind entity carrying the plan as `content` (the doc auto-materializes):
+
+   ```json
+   POST /api/hub/entities
+   { "userId": "{userId}", "workspaceId": "{wsId}",
+     "profileSlug": "knowledge",
+     "title": "Q3 launch strategic plan",
+     "properties": { "ek_type": "reference" },
+     "content": "# Q3 Launch Plan\n\n## Goals\n…\n\n## Timeline\n…"
+   }
+   ```
+
+3. Link it to the relevant project: `POST /api/hub/relations` `{ sourceEntityId: "ent_new_plan", targetEntityId: "ent_project_q3", type: "related_to" }`.
+4. Confirm: "Plan captured and linked to Q3 launch." No upload, no `file` entity, no separate `synap_create_document` call.

package/skills/synap/writes.md

@@ -1,6 +1,12 @@
 ## Core writes
 
-### Create an entity (schema-first, complete intent)
+**Two write doors, one gradient.** `create_entity` is for exactly ONE
+fully-structured, typed entity you already have. For anything unstructured,
+several entities, or a graph — or **when in doubt** — use the capture door
+(`synap_capture`, see `capture.md`): precision comes from sending more structure
+in the SAME call, never from picking a different tool or a second commit step.
+
+### Create an entity (one exact typed entity)
 
 Before this call, use `/discover?userId=…&profileSlugs=<kind>` to read the
 real fields, required/default values, constraints and reference targets. Omit
@@ -22,15 +28,27 @@ POST /api/hub/entities
 ```
 
 The response has legacy `status`/`id` fields plus `writeReceipt`:
-`pending` means a proposal exists and no entity is live; `applied` means the
-reported direct write completed; `partial` means a follow-up (for example a
-facet) failed after the entity applied. Never claim completion from `pending`,
-and only enrich again when the receipt identifies a real missing fact.
+`pending`/`proposed` means a proposal exists and no entity is live yet;
+`applied` means the reported direct write completed; `partial` means a follow-up
+(for example a facet) failed after the entity applied. **A `proposed`/`pending`
+receipt is a governed success, not an error** — surface its `reviewUrl`, never
+claim completion, and only enrich again when the receipt identifies a real
+missing fact.
 
 For several entities, creation-time roles/facets, or relations that need one
-review, submit one `POST /api/hub/capture/graph` plan instead of sequencing
-independent creates. It returns a pending receipt and materializes on human
-approval.
+review, send the whole graph through the capture door (`synap_capture` with
+`entities[]` + `relations[]`) instead of sequencing independent creates. It is
+ONE governed call: policy auto-applies when every op is safe, otherwise the
+whole graph is proposed (atomic). There is no separate commit step.
+
+**Name-refs, not UUIDs.** Reference an existing project by name — the server
+resolves it against the caller's own projects (exact match files there; no match
+proposes, never mis-files). Never ask the user for a UUID.
+
+**Dedup is advisory across kinds.** Strong signals (`email`/`phone`/`website` —
+not a bare `url`) dedup within a kind; a same-title hit in a _different_ kind
+comes back as an advisory candidate, never an auto-merge. "No exact match" is not
+"safe to create" when advisory candidates are returned — review them first.
 
 ### Update an entity
 
@@ -41,6 +59,41 @@ PATCH /api/hub/entities/{entityId}
 
 **Properties are deep-merged — send only the keys you want to change.** An update with `{ "status": "done" }` leaves all other properties untouched. You never need to re-send the full properties object.
 
+### Authored text is content, not a `file`
+
+Something **you** author — a pitch deck, a strategic plan, a note body — is
+**never** a `file`- or `document`-kind entity. Create it as the right CONTENT
+kind (`note`, `knowledge`, or a fitting domain kind) with `content` set to the
+Markdown body; Synap **auto-materializes** that `content` into a real
+versioned document behind the scenes (`entities WHERE documentId = ?`) — no
+upload step needed. `file` is reserved for real uploaded bytes you actually
+have (the upload door / `synap upload`) — an agent has no filesystem, so it
+rarely touches `file` at all. Reach for `synap_create_document` /
+`POST /api/hub/documents` directly only for a standalone rich document that
+isn't itself a title-worthy entity (see below) — never as a substitute for an
+entity's `content`.
+
+### "I want to add a real FILE" — the decision tree
+
+You CAN store content you **hold** — you send it inline. Pick by what you have:
+
+| You have…                                                                                   | Do this                                                                                         | Result                                                               |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Content in hand** — a report/CSV/image/PDF/etc. you generated or received (text or bytes) | **`synap_store_file`** (`content` for text, `contentBase64` for binary) + `mimeType`/`filename` | a `file` entity, content stored **as-is, never read** (≤10MB inline) |
+| Text you're **authoring as a note/idea** (not "a file") — a plan, a thought                 | `synap_create_entity` with `content` (a content kind)                                           | body auto-becomes a document — NOT a `file`                          |
+| Only a **URL/link** (no bytes) — a Google Doc, a PDF url, an article                        | `synap_create_document` with **`url`**, or attach via `entityId`                                | an external **reference** document (no bytes)                        |
+| A **large file on a local disk** you don't hold in context                                  | the CLI `synap upload <path>` (streams it) — an agent can't send bytes it doesn't have          | a `file` entity backed by stored bytes                               |
+| Only a file's **name**, nothing else                                                        | you **cannot** invent it — ask the human/client to provide the content or a link                | —                                                                    |
+
+**Store ≠ analyze.** `synap_store_file` / `synap_create_document` store content
+**deterministically — the file is NEVER read by an LLM.** Only fetch a document
+and reason over it when the user explicitly says "read/analyze this file."
+
+**Do NOT over-structure a file request.** "Store this file" / "how do I add this
+file" is ONE intent → at most one stored file (plus, only if asked, a linking
+relation). Never inflate it into a task + note + placeholder-file scaffold, and
+never dump the request text into a note and call it done.
+
 ### Create a document (attach to an entity)
 
 ```json
@@ -98,21 +151,25 @@ Content is a **full replacement**, not a patch. Fetch the current content first
 
 The reverse lookup is `entities WHERE documentId = ?`. Always attach the document to a meaningful entity (the meeting event, the project, the person) — a floating document is another orphan.
 
-### Store a fact (memory) — use sparingly
+### Remember a fact about the user — use sparingly
 
-```json
-POST /api/hub/memory
-{ "userId": "{userId}", "fact": "User prefers async communication over meetings" }
-```
+A fact _about the user_ goes through `remember_fact` (CLI: `synap capture --type
+observation`). It writes a governed `user_observation` — not an ungoverned
+throwaway row: a fact the user explicitly stated auto-approves; a fact you
+inferred returns `proposed` (normal — surface the review link). Because it's a
+real entity it's addressable, linkable and revertible.
 
-Always auto-approved. **Memory is for loose, unstructured, hard-to-title facts only.** The seductive thing about memory is it has zero friction — no dedup, no linking, no proposals. That makes it easy to misuse.
+**Use it only for loose, unstructured, hard-to-title facts about the user** — a
+stated preference, a throwaway detail. Everything with a title-worthy noun or
+something to link to is an ENTITY through the capture door, not an observation.
 
-**The test:** if the user later asked "show me all X," can memory answer? Memory can only keyword-match — it has no structure. So:
+**The test:** if the user later asked "show me all X," could a loose observation
+answer? It can only keyword-match — it has no structure. So:
 
 | Input                                                   | Use                                                             |
 | ------------------------------------------------------- | --------------------------------------------------------------- |
-| "User prefers async communication"                      | memory — it's a preference                                      |
-| "Garage code is 4321"                                   | memory — throwaway fact                                         |
+| "User prefers async communication"                      | observation — it's a preference                                 |
+| "Garage code is 4321"                                   | observation — throwaway fact                                    |
 | "Should we use LangGraph or CrewAI for Eve?"            | **entity `question`** — substantive inquiry, start of flow      |
 | "Here's what I found comparing LangGraph and CrewAI…"   | **entity `research`** — investigation with sources + conclusion |
 | "We decided to use LangGraph over OpenClaude's native…" | **entity `decision`** — has title, rationale, project           |
@@ -122,7 +179,7 @@ Always auto-approved. **Memory is for loose, unstructured, hard-to-title facts o
 | "Action item from meeting: ship MVP by Friday"          | **entity `task`** linked to the `event` (meeting)               |
 | "Agreed with Sarah: we'll split backend & frontend"     | **entity `decision`** linked to Sarah + the project             |
 
-**Rule of thumb:** if it has a title-worthy noun OR context to link to (a project, a person, a meeting) OR a lifecycle (status/supersession) — it's an entity, not memory. Memory is the fallback, not the default.
+**Rule of thumb:** if it has a title-worthy noun OR context to link to (a project, a person, a meeting) OR a lifecycle (status/supersession) — it's an entity through the capture door, not an observation. A user observation is the fallback, not the default.
 
 **For decisions specifically** — use the `decision` system profile:
 

package/skills/synap-app/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: synap-app
+description: >
+  Use this skill when the user wants to BUILD THEIR OWN APP on top of Synap — a
+  personal project or a product — using Synap as the backend (auth, typed data
+  API, realtime). Two paths: add the SDK (@synap-core/sdk) to an existing app,
+  or scaffold the opinionated Next.js + HeroUI base app (npx create-synap-app).
+  Triggers: "build an app on Synap", "use Synap as my backend", "scaffold a
+  Synap project", "add the Synap SDK", "connect my app to my pod",
+  "npx create-synap-app". NOT the `synap` skill (capture/recall in a pod) nor
+  `synap-ui` (views inside the pod's own UI) — this is about writing app CODE.
+metadata:
+  openclaw:
+    requires:
+      env: []
+    optional_env: [SYNAP_POD_URL, SYNAP_WORKSPACE_ID]
+    primaryEnv: null
+    homepage: https://synap.live
+    capabilities: [sdk, scaffold, auth, realtime]
+    os: [macos, linux, windows]
+    userInvocable: true
+---
+
+# Building an app on Synap
+
+Synap is a sovereign data pod with a complete, typed API. You build an app on it
+the same way you'd build on any backend — except the backend is the user's own
+pod, and **every write is governed** (see `governance.md`).
+
+## Decide the path first
+
+| The user has… | Do this | Read |
+|---|---|---|
+| an existing app (any framework) | add the SDK | `using-the-sdk.md`, `install-commands.md` |
+| nothing yet, wants a full app fast | scaffold the base app | `creating-the-base-app.md`, `install-commands.md` |
+| a server / script / CLI (no browser) | SDK with a session token or API key | `using-the-sdk.md` |
+
+Both paths use the same underlying packages; only the amount of scaffolding differs.
+
+## The packages (all published under `@synap-core/*`)
+
+- `@synap-core/sdk` — typed tRPC client. `createSynapClient({ podUrl, ... })`. **The one you almost always want.**
+- `@synap-core/react` — React/TanStack-Query bindings (`SynapProvider`, hooks).
+- `@synap-core/sdk-realtime` — Socket.IO presence/live-updates (`createRealtimeClient`).
+- `@synap-core/auth` — sign-in orchestration (Synap Cloud + pod handshake), framework-agnostic.
+- `@synap-core/auth-bootstrap` — zero-dep server helpers (`setupAgent`, `handshake`) for machine clients.
+
+Pin `@^1.0.0` on `sdk`/`react` so you never resolve an old, abandoned `0.x`.
+
+## The three rules that trip people up
+
+1. **A write can come back `"proposed"` — that is SUCCESS, not an error.** It means
+   the change is queued for the pod owner's review (like a PR). Surface the review,
+   don't retry. Full contract: `governance.md`.
+2. **The pod URL has no `/trpc` suffix and no trailing slash.** The SDK appends `/trpc`.
+3. **Non-browser clients (server/CLI/mobile) authenticate with a token or API key**,
+   never a cookie. Browser apps use the Synap Cloud sign-in flow (`@synap-core/auth`).
+
+## Get a pod to build against
+
+- **Self-host (free):** `git clone` the backend, `docker compose up -d` (run its
+  `install.sh` to generate secrets). Pod answers on `:4000`.
+- **Managed (paid):** sign up at synap.live and provision a pod.
+
+You can develop the base app with **no pod at all** using its mock mode
+(`NEXT_PUBLIC_BASE_MOCK_MODE=true`).
+
+## Honest scope
+
+Building on the user's OWN pod is fully supported today. Building a **multi-tenant
+commercial app** where *other* people connect *their* pods is **not yet supported**
+— per-app data scoping is still being built. If the user asks for that, say so;
+don't architect around a capability that isn't there.
+
+---
+
+# Install & scaffold commands
+
+## Scaffold a full app (recommended for a fresh start)
+
+```bash
+npx create-synap-app my-app
+```
+
+Creates a Next.js + HeroUI project from the base template, with the SDK, auth,
+app shell, command palette, realtime, and mock mode pre-wired. It also drops an
+`AGENTS.md` into the project so your AI coding tool knows how to work with it.
+
+## Add the SDK to an existing app
+
+```bash
+# npm
+npm install @synap-core/sdk@^1.0.0
+
+# with React bindings
+npm install @synap-core/sdk@^1.0.0 @synap-core/react@^1.0.0
+
+# realtime
+npm install @synap-core/sdk-realtime
+
+# auth (browser sign-in) or auth-bootstrap (server credential bootstrap)
+npm install @synap-core/auth        # or @synap-core/auth-bootstrap
+```
+
+Pin `@^1.0.0` on `sdk`/`react`. **Do not** install unpinned `@synap-core/sdk` —
+older `0.x` versions on the registry are a different, abandoned package.
+
+## Get this knowledge into your AI coding tool
+
+```bash
+# add the app-creation skill (this skill) to a connected AI tool
+synap skills get synap-app
+
+# or wire a tool end-to-end (skills + MCP), any target
+synap connect --target=cursor        # or claude, openclaw, …
+```
+
+Alternatively, the scaffolded project ships an `AGENTS.md` at its root — most AI
+coding tools read it automatically, so a freshly-scaffolded app teaches the AI
+how to build on it with zero extra setup.
+
+## Verify an install actually works
+
+Publishing bugs have shipped uninstallable Synap packages before. After adding a
+package, confirm it resolves in a clean directory:
+
+```bash
+mkdir /tmp/synap-check && cd /tmp/synap-check && npm init -y
+npm install @synap-core/sdk@^1.0.0
+node -e "console.log(typeof require('@synap-core/sdk').createSynapClient)"  # → function
+```
+
+---
+
+# Using the SDK
+
+## Vanilla / TypeScript / server / CLI — `@synap-core/sdk`
+
+```ts
+import { createSynapClient } from "@synap-core/sdk";
+
+const synap = createSynapClient({
+  podUrl: "https://pod.example.com", // NO trailing slash, NO /trpc suffix
+  apiKey: process.env.SYNAP_API_KEY, // or sessionToken (see auth below)
+  workspaceId: process.env.SYNAP_WORKSPACE_ID ?? "",
+});
+
+// It's a typed tRPC client — full autocomplete over every router.
+const me = await synap.users.me.query();
+const entities = await synap.entities.list.query({ /* filter */ });
+const result = await synap.entities.create.mutate({ /* ... */ });
+// result may be { status: "proposed", ... } — that is success. See governance.md.
+```
+
+### Auth modes (pick ONE)
+- **`apiKey`** — a Bearer key generated in the workspace's developer settings.
+  Best for servers, scripts, CLIs.
+- **`sessionToken`** — an Ory Kratos session token, sent as `X-Session-Token`.
+  Best for non-browser clients that completed a sign-in.
+- **cookie fallback** — omit both; the client uses the ambient Kratos cookie.
+  Browser, same-origin only.
+
+For machine clients that need to bootstrap a credential, use
+`@synap-core/auth-bootstrap` (`setupAgent(provisioningToken)` → API key,
+`handshake(jwt)` → session token). Zero-dependency, safe in edge/serverless.
+
+## React — `@synap-core/react`
+
+```tsx
+import { SynapProvider, useSynapContext } from "@synap-core/react";
+
+function App() {
+  return (
+    <SynapProvider podUrl={podUrl} sessionToken={token} workspaceId={ws}>
+      <Dashboard />
+    </SynapProvider>
+  );
+}
+```
+
+`SynapProvider` honours every `createSynapClient` option, incl. `sessionToken`
+and `onAuthError` (a 401 handler). `react` is a peer of your app's React — it
+does not bundle its own.
+
+## Realtime — `@synap-core/sdk-realtime`
+
+```ts
+import { createRealtimeClient } from "@synap-core/sdk-realtime";
+
+const rt = createRealtimeClient({ podUrl, sessionToken });
+const stop = rt.onInvalidate((target) => {
+  // e.g. refetch the affected query
+});
+```
+
+Websocket-only transport (credentials never ride a long-poll URL) and it refuses
+to send credentials over non-TLS unless you explicitly pass `allowInsecure`.
+
+## Two transports, on purpose
+- `@synap-core/sdk` (tRPC) — for apps. Typed, hooks, realtime.
+- `@synap-core/hub-rest-client` (REST, zero-dep) — for agents/CLIs/scripts. Carries
+  agent verbs the tRPC surface has no first-class path for (`ask`, `orient`,
+  `discover`). Use it when you want a dependency-free REST client, not a full app.
+
+## Keep types fresh
+The SDK is typed by `@synap-core/api-types`, generated from the pod's live router.
+If the pod adds a procedure and you don't see it, bump `@synap-core/api-types`.
+
+---
+
+# Creating the base app
+
+The base app is an opinionated, batteries-included starter: **Next.js 16 (App
+Router) + React 19 + HeroUI + Tailwind**, with auth (incl. TOTP), an app shell
+(tabs + slide-in right panel), a Cmd+K command palette, a realtime bridge, and a
+mock mode — all pre-wired. You add your screens; the plumbing is done.
+
+## Scaffold it
+
+```bash
+npx create-synap-app my-app
+cd my-app
+cp .env.example .env.local   # fill in your pod / control-plane URLs
+pnpm dev                     # http://localhost:3010
+```
+
+Develop with **no pod** by setting `NEXT_PUBLIC_BASE_MOCK_MODE=true`.
+
+## What's where
+
+```
+app/
+  layout.tsx        Root layout → ClientProviders (client-only, see below)
+  ClientProviders   Loads the provider tree with { ssr: false } (REQUIRED — see rule 1)
+  providers.tsx     The real provider stack (auth, tRPC, realtime, palette)
+  (app)/home        Your home screen — replace this
+  login/ onboarding First-run + auth screens
+lib/
+  registerAll.ts    Boot hook — registers cells/views (override in your app)
+  auth.ts mockMode  Session + mock helpers
+components/layout/
+  AppShell          Root layout primitive — pass your sidebar as `leftNav`
+```
+
+## Four rules that keep the build green (all Next 16 / Turbopack specifics)
+
+1. **The provider tree must load client-only.** `app/ClientProviders.tsx` does
+   `dynamic(() => import("./providers"), { ssr: false })`. base's provider tree
+   pulls a dep that touches `window` at module scope, which crashes a server
+   render. base is a client app shell — there is nothing to server-render — so
+   this is correct, not a hack. Keep it.
+2. **`config.matcher` in `middleware.ts` must be an inline literal**, not a value
+   read from a helper — Next's static analyzer can't parse an expression there.
+3. **In `globals.css`, `@import` must come before the `@tailwind` directives.**
+   Turbopack enforces the CSS spec strictly.
+4. **Build with Turbopack (the default) — do NOT pass `--webpack`.** In Next 16
+   the legacy `--webpack` flag silently produces nothing (exit 0, no output). If
+   you add a webpack alias, port it to `turbopack.resolveAlias` in `next.config.ts`.
+
+## Deriving your own app
+
+1. Rename the namespaced storage keys (`base:session`, `base-workspace`, …) so
+   two Synap apps don't share state in one browser. The README lists every key.
+2. Replace `app/(app)/home/page.tsx` with your dashboard.
+3. Pass your sidebar: `<AppShell leftNav={<MySidebar />}>`.
+4. Register app-specific Cmd+K commands with `useRegisterCommand([...])`.
+5. Register only the cells you need in `lib/registerAll.ts` (a lean template
+   registers fewer than the full set).
+
+## Auth flow (already wired)
+
+`/login` → Synap Cloud sign-in (email + password or magic link) → optional TOTP →
+pod picker → handshake → session stored → `/home`. Self-hosted pods fall back to
+the pod's own Kratos at `/login?mode=kratos`. You don't build this; you theme it.
+
+---
+
+# Governance — `"proposed"` is success, not an error
+
+This is the single most important thing to get right when writing code that
+mutates a Synap pod.
+
+## The contract
+
+Every mutation (`entities.create`, `entities.update`, `relations.create`, …)
+resolves to one of three outcomes, decided **by the pod**, not by your app:
+
+| Outcome | Meaning | What your code should do |
+|---|---|---|
+| `approved` | applied immediately | proceed |
+| `proposed` | queued for the pod owner's review (like a PR) | **surface the review — do NOT treat as failure, do NOT retry** |
+| `denied` | the principal may not do this | show why; do not retry blindly |
+
+## Why it matters for your code
+
+- **Never treat `proposed` as an error.** It is the normal, healthy path for any
+  write that governance decides a human should see first. Retrying a `proposed`
+  write creates duplicates.
+- **Never `try/catch` a `proposed` as if it threw.** It's a successful response
+  with a status, not an exception.
+- **Surface the review link/id** so the user can approve it. An unreviewed
+  proposal is not yet in the graph — it won't show up in reads until approved.
+
+## Pattern
+
+```ts
+const res = await synap.entities.create.mutate(input);
+switch (res.status) {
+  case "approved": /* it's live */ break;
+  case "proposed": /* tell the user: "queued for review" + show res.proposalId */ break;
+  case "denied":   /* show res.reason; don't retry */ break;
+}
+```
+
+## Idempotency
+
+If you must retry a create after a network error, pass an idempotency key where
+the API accepts one — a `proposed` write that you retry without one will
+duplicate on approval. When unsure, read back before re-creating.

package/skills/synap-app/_order.txt

@@ -0,0 +1,5 @@
+overview.md
+install-commands.md
+using-the-sdk.md
+creating-the-base-app.md
+governance.md

package/skills/synap-app/_skill.yaml

@@ -0,0 +1,20 @@
+name: synap-app
+description: >
+  Use this skill when the user wants to BUILD THEIR OWN APP on top of Synap — a
+  personal project or a product — using Synap as the backend (auth, typed data
+  API, realtime). Two paths: add the SDK (@synap-core/sdk) to an existing app,
+  or scaffold the opinionated Next.js + HeroUI base app (npx create-synap-app).
+  Triggers: "build an app on Synap", "use Synap as my backend", "scaffold a
+  Synap project", "add the Synap SDK", "connect my app to my pod",
+  "npx create-synap-app". NOT the `synap` skill (capture/recall in a pod) nor
+  `synap-ui` (views inside the pod's own UI) — this is about writing app CODE.
+metadata:
+  openclaw:
+    requires:
+      env: []
+    optional_env: [SYNAP_POD_URL, SYNAP_WORKSPACE_ID]
+    primaryEnv: null
+    homepage: https://synap.live
+    capabilities: [sdk, scaffold, auth, realtime]
+    os: [macos, linux, windows]
+    userInvocable: true

package/skills/synap-app/creating-the-base-app.md

@@ -0,0 +1,64 @@
+# Creating the base app
+
+The base app is an opinionated, batteries-included starter: **Next.js 16 (App
+Router) + React 19 + HeroUI + Tailwind**, with auth (incl. TOTP), an app shell
+(tabs + slide-in right panel), a Cmd+K command palette, a realtime bridge, and a
+mock mode — all pre-wired. You add your screens; the plumbing is done.
+
+## Scaffold it
+
+```bash
+npx create-synap-app my-app
+cd my-app
+cp .env.example .env.local   # fill in your pod / control-plane URLs
+pnpm dev                     # http://localhost:3010
+```
+
+Develop with **no pod** by setting `NEXT_PUBLIC_BASE_MOCK_MODE=true`.
+
+## What's where
+
+```
+app/
+  layout.tsx        Root layout → ClientProviders (client-only, see below)
+  ClientProviders   Loads the provider tree with { ssr: false } (REQUIRED — see rule 1)
+  providers.tsx     The real provider stack (auth, tRPC, realtime, palette)
+  (app)/home        Your home screen — replace this
+  login/ onboarding First-run + auth screens
+lib/
+  registerAll.ts    Boot hook — registers cells/views (override in your app)
+  auth.ts mockMode  Session + mock helpers
+components/layout/
+  AppShell          Root layout primitive — pass your sidebar as `leftNav`
+```
+
+## Four rules that keep the build green (all Next 16 / Turbopack specifics)
+
+1. **The provider tree must load client-only.** `app/ClientProviders.tsx` does
+   `dynamic(() => import("./providers"), { ssr: false })`. base's provider tree
+   pulls a dep that touches `window` at module scope, which crashes a server
+   render. base is a client app shell — there is nothing to server-render — so
+   this is correct, not a hack. Keep it.
+2. **`config.matcher` in `middleware.ts` must be an inline literal**, not a value
+   read from a helper — Next's static analyzer can't parse an expression there.
+3. **In `globals.css`, `@import` must come before the `@tailwind` directives.**
+   Turbopack enforces the CSS spec strictly.
+4. **Build with Turbopack (the default) — do NOT pass `--webpack`.** In Next 16
+   the legacy `--webpack` flag silently produces nothing (exit 0, no output). If
+   you add a webpack alias, port it to `turbopack.resolveAlias` in `next.config.ts`.
+
+## Deriving your own app
+
+1. Rename the namespaced storage keys (`base:session`, `base-workspace`, …) so
+   two Synap apps don't share state in one browser. The README lists every key.
+2. Replace `app/(app)/home/page.tsx` with your dashboard.
+3. Pass your sidebar: `<AppShell leftNav={<MySidebar />}>`.
+4. Register app-specific Cmd+K commands with `useRegisterCommand([...])`.
+5. Register only the cells you need in `lib/registerAll.ts` (a lean template
+   registers fewer than the full set).
+
+## Auth flow (already wired)
+
+`/login` → Synap Cloud sign-in (email + password or magic link) → optional TOTP →
+pod picker → handshake → session stored → `/home`. Self-hosted pods fall back to
+the pod's own Kratos at `/login?mode=kratos`. You don't build this; you theme it.