@synap-core/cli 1.12.2 → 1.13.0

package/skills/synap/work-model.md

@@ -8,16 +8,16 @@ A process is the life of a **thing**, not a script. A lead, a post or a feature
 
 ### The nouns
 
-| Noun                 | What it is                                                                          | Not                                  |
-| -------------------- | ----------------------------------------------------------------------------------- | ------------------------------------ |
-| **Project**          | a commitment, and a lens across spaces                                              | a method, a domain                   |
-| **Track** (optional) | a LASTING intent in one project: direction, instructions, goal; it turns workers on | a list of stages; it never completes |
-| **Thing**            | any entity: one kind, maybe roles, one status per kind or role                      | a second entity for a hat            |
-| **Session**          | the unit of work that closes: goal, criteria, room; one thing or a batch            | a "run" because it follows a method  |
+| Noun                | What it is                                                                                                            | Not                                 |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| **Project**         | a commitment, and a lens across spaces                                                                                | a method, a domain                  |
+| **Goal** (optional) | in one project (a _track_ in tools): direction, criteria, the workers it turns on; its judge closes it with a verdict | a list of stages                    |
+| **Thing**           | any entity: one kind, maybe roles, one status per kind or role                                                        | a second entity for a hat           |
+| **Session**         | the unit of work that closes: goal, criteria, room; one thing or a batch                                              | a "run" because it follows a method |
 
 Not nouns (nobody manages them as objects): a **pipeline** is a view of a lifecycle; a **worker** is configuration (a method + a trigger + a size); a **method** is a playbook a session may follow; a **check** is a recurring verification.
 
-How they relate: a project files things; each kind or role declares one **lifecycle** (its status list); its **pipeline** is computed (columns = the options in order); a status change fires **workers**, which start **sessions** carrying the project, the track and their **targets**; a session moves each thing's status through the door. **Hand-off is a role:** a won deal makes the party a client (attach the role); nothing is copied.
+How they relate: a project files things; each kind or role declares one **lifecycle** (its status list); its **pipeline** is computed (columns = the options in order); a status change fires **workers**, which start **sessions** carrying the project, the goal and their **targets**; a session moves each thing's status through the door. **Hand-off is a role:** a won deal makes the party a client (attach the role); nothing is copied.
 
 ### Three tenses of a thing
 
@@ -49,11 +49,25 @@ Every status change — your call, a board drag, a method's step, a sync — goe
 
 ### Workers
 
-A worker is a playbook **activator**, declared on the method and owned by the lifecycle: `on` = `created` · `enters_status` (+ `status`) · `count` (+ `status`, `min`: once N things wait) · `schedule` (+ `cron`) · `manual`; `size` = `per_thing` · `per_moment` (a count or schedule is always per batch); `mode` = `propose` (default) · `run`; `maxPendingApprovals` throttles it. It compiles into a governed rule the owner can pause; it fires once per thing per transition. A track or project **turns it on** for its scope; installs turn it on space-wide. Authoring: `processes`.
+A worker is a playbook **activator**, declared on the method and owned by the lifecycle: `on` = `created` · `enters_status` (+ `status`) · `count` (+ `status`, `min`: once N things wait) · `schedule` (+ `cron`) · `manual`; `size` = `per_thing` · `per_moment` (a count or schedule is always per batch); `mode` = `propose` (default) · `run`; `maxPendingApprovals` throttles it. It compiles into a governed rule the owner can pause; it fires once per thing per transition. A goal or project **turns it on** for its scope; installs turn it on space-wide. Authoring: `processes`.
 
-### Tracks
+### Goals (tracks)
 
-A track holds an owner, a direction, instructions, the workers it turns on, and a goal (stated, or measured as transitions into `done`). It has no stages and never completes: pause or archive it. Work in it = `start_session` + `trackId`. A thing may count for two tracks. Solo users may never need one: workers can run space-wide. Legacy: `start_stage_session` and `add_track_stage` serve old tracks started from a method; never `advance_track` without the user.
+A goal is a _track_ in every tool and field name (`start_track`, `trackId`) — say "goal" to the person; a session's one-line `goal` is its **Aim**. A goal holds an owner, a direction, instructions, the workers it turns on, and what done means (criteria, or a number measured as transitions into `done`). It has no stages. A goal can stay open as long as it matters, or finish: a person closes it with a verdict once its criteria are met (`set_track_status` `completed` + `verdict`; dropped = `archived`, with a `verdict` saying why). Your close is a proposal; a closed goal comes back only as a new version. Pause it while nobody should work on it. Work in it = `start_session` + `trackId`. A thing may count for two goals. Solo users may never need one: workers can run space-wide. Legacy: `start_stage_session` and `add_track_stage` serve old goals started from a method; never `advance_track` without the user.
+
+**Keep the pod current (every agent, every session)** — three rules, so the next agent picks your step up from the pod alone:
+
+1. **Attach the session to its goal.** `orient`'s `startHere.openGoals` and the start reply's `offers.goals` name the open goals; start with `trackId`, or file an open session with `update_session` `trackId` (a proposal for an agent). No goal fits: say so in the room, never invent one silently.
+2. **Record your PR as an outcome** the moment you open it: `update_session` `outcomes: [{ key: "pr-<repo>-<n>", kind: "pull_request", label: "<repo>#<n>", ref: { url: "<PR url>" } }]`. With no `sessionId`, the pod files it on the one open session this conversation started, and refuses with the list when there are several.
+3. **Close when your outcomes are met.** When every outcome is met the `update_session` reply carries `nudges.readyToClose`: grade with `evaluate_session`, then `complete_session`. A merged PR is not always the end of the work: if more remains, declare it instead.
+
+**The rest of the goal protocol** (`set_track_participant`, `reopen_track`, `convert_to_goal`, `update_track`):
+
+- **A delegate's commitment.** The owner or judge asks someone (`add`, role `delegate`, with a `commitment`). The delegate answers only their own: `accept`, `counter` (text = what they would commit to instead), `decline`, or later `report_impossible` (text = why). A report is not the goal's verdict: the owner or judge `acknowledge`s it and re-plans. Never answer for a person; adding yourself as a delegate commits you.
+- **Claims and the judge.** A session that passes a goal criterion CLAIMS it. Only the judge (the owner unless one is named) accepts or sends back a claim, and only the judge closes the goal. Never accept your own claim.
+- **Reopen = a new version.** A closed or dropped goal never moves back: `reopen_track` starts a new version linked to it, with the same people asked again.
+- **Make it a goal.** A goal, objective or OKR entity becomes a goal once with `convert_to_goal` (its key results become measured criteria). Offer it when the person treats such an entity as live work; never convert one twice.
+- **The loop** is OFF by default. When it is on (`update_track` `loop: { on: true, perWeek? }`), the goal proposes its next session while a required criterion is unmet, and a person approves each one. Your switch-on is always a proposal: the person turns it on. If it stops after two failures on one criterion, ask the owner to re-plan; do not switch it on again yourself.
 
 ### The homes: what each space makes, what is moving
 

package/skills/synap/workspace-design.md

@@ -1,6 +1,6 @@
 ## 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**, a **lasting goal** (track), or a **status**. Creating a workspace for one of those is the anti-pattern that fragments the graph. Decide first, then create. What each word means: `concepts` (the one glossary).
+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**, a **lasting goal** (a goal — `track` in tools), or a **status**. Creating a workspace for one of those is the anti-pattern that fragments the graph. Decide first, then create. What each word means: `concepts` (the one glossary).
 
 **One space per domain:** A space is a domain, installed once (Content, Brand, CRM…). A project is a filter across spaces. To make something “for project X”: file it into X inside the domain's space (`file_into_project`), and link X to the space (`project_use_workspace`). Never create a space named after a project, a brand or a client.
 
@@ -17,7 +17,7 @@ Before you create a workspace, run the decision rule. A workspace (an operationa
 | ----------------------------------------------------------- | ----------- | -------------------------------------- | ------------------------------------------- |
 | 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 **lasting goal** a project pursues (worked in sessions)   | **Track**   | `start_track` (no method needed)       | grow the newsletter, win ten clients        |
+| a **lasting goal** a project pursues (worked in sessions)   | **Goal**    | `start_track` (no method needed)       | grow the newsletter, win ten clients        |
 | a **stage/filter WITHIN a domain**                          | **Status**  | an option of the kind's lifecycle      | pipeline stage, "active"/"archived"         |
 
 ## The decision procedure (follow in order)
@@ -25,8 +25,8 @@ Before you create a workspace, run the decision rule. A workspace (an operationa
 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. One role per name, pod-wide: a role several workspaces use is ONE role, each workspace adding properties by overlay — never a per-workspace twin (`concepts`).
-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 lasting goal a project pursues** ("keep the content side of the launch going") → a **track**: `list_tracks`, else `start_track` (`name`, `direction`); work in it with `start_session` + `trackId`. Never a workspace, never a twin project.
+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` — a near-duplicate name is filed for the person to review, showing the existing project; (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 lasting goal a project pursues** ("keep the content side of the launch going") → a **goal**: `list_tracks`, else `start_track` (`name`, `direction`); work in it with `start_session` + `trackId`. Never a workspace, never a twin project.
 6. **If it's a stage inside a domain** → it is an option of the kind's or role's declared lifecycle, never a role and never a space. Its pipeline is computed from the lifecycle: open it, don't build one. A kind with no lifecycle yet gets a `status` property def (`create_property_def`).
 7. **Only if all four held** → **template first** (escalation ladder L3):
    `market.search({query, kind: "template"})` and propose install of a matching
@@ -36,7 +36,7 @@ Before you create a workspace, run the decision rule. A workspace (an operationa
 
 ## The CRM corollary — the load-bearing example
 
-Operational state — **prospect → client → delivered** — is a **FLOW across domains**, expressed as **facets + an engagement project** (its delivery runs as a track), NEVER as workspaces and NEVER by bolting delivery onto the identity domain.
+Operational state — **prospect → client → delivered** — is a **FLOW across domains**, expressed as **facets + an engagement project** (its delivery runs as a goal), 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`).

package/skills/synap/writes.md

@@ -14,10 +14,14 @@ several entities, or a graph — or **when in doubt** — use the capture door
 in the SAME call, never from picking a different tool or a second commit step.
 
 The difference that is NOT visible in either tool's description: `create_entity`
-writes one entity with per-entity governance and REJECTS a name collision unless
-`forceCreate`; capture-with-`entities[]` files ONE atomic proposal for the whole
-graph and DEDUP-MERGES instead of rejecting. Pick by whether you want a partial
-write to be possible, not by how structured your data feels.
+writes one entity with per-entity governance; capture-with-`entities[]` files ONE
+atomic proposal for the whole graph. Neither rejects a look-alike: a record (or
+one of your own pending proposals) of the same kind with the same name or
+identity makes the write a proposal carrying `duplicateCheck`, and the person
+decides (keep both, use the existing one, fill its empty fields). Only a strong
+identity (email, phone, url, handle, external id) links to the existing record
+on its own. Pick by whether you want a partial write to be possible, not by how
+structured your data feels.
 
 **Every title is linted.** Both doors return `titleLint` in the receipt when a
 title breaks the rubric (too long, cut off, status words, ids, a placeholder…);
@@ -98,6 +102,8 @@ the connection's lens). A kind another space needs: `synap_change_kind_scope`
 (`scope: "shared"` + `allowedWorkspaceIds`), never a twin kind. Records:
 `synap_move_entities`. All three are reviewed.
 
+**Removing one: `synap_delete_entity`** (`entityId`, optional `reasoning`). For an agent it is always a proposal — nothing is deleted until the person approves, and no rule can widen that. An approved delete hides the entity (its body is kept) and the person can undo it from the proposal. Do not retry a `proposed` answer.
+
 ### Authored text is content, not a `file`
 
 Something **you** author — a pitch deck, a strategic plan, a note body — is
@@ -120,7 +126,7 @@ You CAN store content you **hold** — you send it inline. Pick by what you have
 | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
 | **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)                        |
+| Only a **URL/link** (no bytes) — a Google Doc, a PDF url, an article                        | `synap_create_document` with **`url`**; `entityId` only for a thing with no body yet            | an external **reference** document (no bytes)                        |
 | A **large file** (over 10MB, up to 500MB video)                                             | `synap_request_upload` → PUT the bytes to `uploadUrl` → `synap_store_file({ uploadToken })`     | 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                | —                                                                    |
 
@@ -210,14 +216,15 @@ POST /api/hub/documents/{documentId}/patch
 
 Ops: `upsert_section {id, title, body}` (one section by id), `replace_text {old,
 new}` (`old` must match **exactly once**, else 400 with the count), `append
-{body}`, `replace_all {content}`. An agent's edit is filed as a proposal (a
+{body}`, `replace_all {content}`, `set_title {title}` (renames the document, a
+human name). An agent's edit is filed as a proposal (a
 governance rule may apply it directly); a person's section (`owner="human"`) is
 never changed and an embed is never dropped unless you pass
 `"allowRemovingEmbeds": true` (403 otherwise). A moved document answers 409 and
 nothing is written: read again. An applied or approved edit reaches open editors
 (`document:content-replaced`), so they reload instead of overwriting it. `PATCH /api/hub/documents/{id}` with `content` is the same door with
-one `replace_all` — it cannot rename (a `title` is refused with 400; to rename an
-entity's document, update the entity's title). MCP: `synap_update_document`;
+one `replace_all` — it cannot rename (a `title` is refused with 400; to rename the
+document, send a `set_title` op to `POST /api/hub/documents/{id}/patch`). MCP: `synap_update_document`;
 full syntax in `document-embeds.md`.
 
 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.
@@ -273,7 +280,7 @@ POST /api/hub/entities
 
 This creates a first-class decision entity linked to Project Eve. It shows up in traversals, can be superseded later (`supersededBy: newDecisionId`), and survives governance. Memory can't do any of that.
 
-**A decision the PERSON must make** — create it with `decisionStatus: "proposed"` and the pod asks them for you: pass `decisionOptions` (≤8 of `{label, value?, description?}`) and `recommendedOption` (an option's `value`, else its `label`); set `sourceSessionId` to keep the question in your session. Their answer UPDATES that decision — never create a second one. Every answered `confirm`/`choose` ask already files its decision (`slot.decisionId`): don't create one for it. A person-owned slot blocked on a decision is ANSWERED by them (Yes/No or a choice) — it is never closed by marking it done. **Before you recommend**, recall the user's past decisions (`synap_ask`, or find `decision` entities) so your pick follows their past choices.
+**A decision the PERSON must make** — create it with `decisionStatus: "proposed"` and the pod asks them for you: pass `decisionOptions` (≤8 of `{label, value?, description?}`) and `recommendedOption` (an option's `value`, else its `label`); set `sourceSessionId` to keep the question in your session. With no options the person sees its `title` with Accept / Reject, each saying what it does. So give it a short `title` (the decision itself, never "Decide: …") and a `summary` that says what the title does not. Only a decision YOU propose asks: a person's own proposed decision is their note, and the pod never asks them about it. Their answer UPDATES that decision — never create a second one. Every answered `confirm`/`choose` ask already files its decision (`slot.decisionId`): don't create one for it. A person-owned slot blocked on a decision is ANSWERED by them (Yes/No or a choice) — it is never closed by marking it done. **Before you recommend**, recall the user's past decisions (`synap_ask`, or find `decision` entities) so your pick follows their past choices.
 
 ### Post to the user's personal channel
 

package/skills/synap-app/SKILL.md

@@ -32,8 +32,8 @@ pod, and **every write is governed** (see `governance.md`).
 | 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` |
+| nothing yet, wants a full app fast | scaffold the base app (scaffolder not published yet) | `creating-the-base-app.md`, `install-commands.md` |
+| a server / script / CLI (no browser) | SDK with a session token, or the REST client with an API key | `using-the-sdk.md` |
 
 Both paths use the same underlying packages; only the amount of scaffolding differs.
 
@@ -41,9 +41,11 @@ Both paths use the same underlying packages; only the amount of scaffolding diff
 
 - `@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.
+- `@synap-core/sdk-realtime` — Socket.IO "something changed" events (`createRealtimeClient`).
+- `@synap-core/hub-rest-client` — zero-dep REST client for API-key holders (`HubRestClient`, `setupAgent`).
+
+Do not install `@synap-core/auth`: that package was retired, and its last npm
+release signs in through a pod route that no longer exists.
 
 Pin `@^1.0.0` on `sdk`/`react` so you never resolve an old, abandoned `0.x`.
 
@@ -53,13 +55,18 @@ Pin `@^1.0.0` on `sdk`/`react` so you never resolve an old, abandoned `0.x`.
    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`).
+3. **Non-browser clients (server/CLI/mobile) authenticate with a session token or
+   an API key**, never a cookie. An API key only works on the REST client and
+   realtime, not on the tRPC SDK. Browser apps use the Kratos session cookie.
 
 ## 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`.
+- **Self-host (free):** run the backend's `install.sh` (it installs Docker if
+  needed, fetches the release bundle, checks it against the release manifest's
+  sha256 and runs `synap install`); see the backend's `deploy/README.md`. It
+  also checks the manifest's signature: by default
+  (`SYNAP_RELEASE_VERIFY=warn`) it only warns and carries on when the signature
+  is missing or does not verify; `SYNAP_RELEASE_VERIFY=enforce` refuses.
 - **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
@@ -78,11 +85,17 @@ don't architect around a capability that isn't there.
 
 ## Scaffold a full app (recommended for a fresh start)
 
+> **Not published yet.** The scaffolder (`@synap-core/create-synap-app`) is not
+> on npm and the base template is not public, so `npx` returns 404 today. Use the
+> SDK path below until a release exists.
+
+Once published:
+
 ```bash
-npx create-synap-app my-app
+npx @synap-core/create-synap-app my-app
 ```
 
-Creates a Next.js + HeroUI project from the base template, with the SDK, auth,
+It 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.
 
@@ -98,24 +111,27 @@ 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
+# REST client for API-key holders (agents, scripts); also has setupAgent()
+npm install @synap-core/hub-rest-client
 ```
 
+Do not install `@synap-core/auth` (retired; its last release calls a removed pod
+route) or `@synap-core/auth-bootstrap` (not published).
+
 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
+# print this skill from your pod's skill knowledge base
+synap skill get synap-app
 
-# or wire a tool end-to-end (skills + MCP), any target
-synap connect --target=cursor        # or claude, …
+# or wire a tool end-to-end (skills + MCP)
+synap connect --target=cursor        # or claude-code, claude-desktop, codex, …
 ```
 
-Alternatively, the scaffolded project ships an `AGENTS.md` at its root — most AI
+Once the scaffolder is published, 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.
 
@@ -141,33 +157,41 @@ 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)
+  sessionToken: process.env.SYNAP_SESSION_TOKEN, // see auth below
   workspaceId: process.env.SYNAP_WORKSPACE_ID ?? "",
+  onAuthError: () => {/* 401: sign in again */},
 });
 
 // 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.
+// result.status may be "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.
+- **`sessionToken`** — an Ory Kratos session token from a Kratos API (native)
+  login flow, sent as `X-Session-Token`. The normal choice for servers, scripts,
+  CLIs and mobile.
+- **cookie fallback** — omit both; the client sends the ambient Kratos cookie
+  (`credentials: "include"`). Browser only.
+- **`apiKey`** — only the local-mode token of a desktop pod, sent as
+  `Authorization: Bearer`. `/trpc` refuses hub and user API keys
+  (keys starting with synap_hub_ or synap_user_), and `createSynapClient` throws if you pass
+  one. For an API key, use `@synap-core/hub-rest-client` (below).
+
+Other options: `extraHeaders`, and `onAuthError({ status, message })`, called on a
+401 (it also turns the pod's plain-JSON 401 body into a clean tRPC error).
+
+To mint an API key for a machine client, `setupAgent(podUrl, provisioningToken,
+agentType)` from `@synap-core/hub-rest-client` returns `{ hubApiKey, agentUserId,
+workspaceId }`. That key works with the REST client and the realtime client, not
+with `/trpc`.
 
 ## React — `@synap-core/react`
 
 ```tsx
-import { SynapProvider, useSynapContext } from "@synap-core/react";
+import { SynapProvider, useSynap, useEntities } from "@synap-core/react";
 
 function App() {
   return (
@@ -176,31 +200,73 @@ function App() {
     </SynapProvider>
   );
 }
+
+function Dashboard() {
+  const { data } = useEntities("note", { limit: 20 }); // thin data hook
+  const create = useSynap.entities.create.useMutation(); // raw tRPC hooks
+  // …
+}
 ```
 
-`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.
+`useSynap` is the tRPC React hook tree itself — write
+`useSynap.entities.list.useQuery(…)`, **not** `useSynap().entities…`: calling it
+returns `undefined` at runtime (some package docs still show the call form).
+
+`SynapProvider` takes every `createSynapClient` option (incl. `sessionToken` and
+`onAuthError`) plus an optional `queryClient` to share an existing TanStack Query
+client. Exports: `SynapProvider`, `useSynapContext` (`{ podUrl, workspaceId }`),
+`useSynap`, the data hooks `useEntity`, `useEntities`, `useLinks`, `useView`,
+and the `RouterInputs` / `RouterOutputs` types. React 18 or 19 is a peer
+dependency — the package 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
+const rt = createRealtimeClient({
+  url: podUrl,            // pod base URL; the client adds the /presence namespace
+  workspaceId,
+  sessionToken,           // a Kratos session token…
+  userId,                 // …and the identity id it belongs to (both required)
+  // or, as a service account: apiKey (scope realtime:observe), no userId
+  onInvalidate: (event) => {
+    // entity/relation changed — refetch, e.g.
+    queryClient.invalidateQueries({ queryKey: ["entities"] });
+  },
 });
+
+rt.connect();   // nothing connects until you call this
+// … later
+rt.disconnect();
 ```
 
-Websocket-only transport (credentials never ride a long-poll URL) and it refuses
-to send credentials over non-TLS unless you explicitly pass `allowInsecure`.
+- Callbacks (all options, no subscribe methods): `onInvalidate` (the
+  entity/relation-changing subset), `onEvent` (every known event, `{ name, data }`),
+  `onConnect`, `onDisconnect(reason)`, `onError(error)`.
+- The returned client has `connect()`, `disconnect()`, and read-only `connected`
+  and `state` (`"idle" | "connecting" | "connected" | "disconnected"`).
+- `SYNAP_EVENT_NAMES` lists the forwarded events; `ENTITY_INVALIDATING_EVENTS` is
+  the subset behind `onInvalidate`.
+- Websocket-only transport (credentials never ride a long-poll URL), and
+  `connect()` throws on a non-TLS URL unless you pass `allowInsecure: true`
+  (localhost dev only).
+
+**Version note.** `@synap-core/sdk-realtime@0.1.0` (the current npm release) sends
+every credential as `auth.token`. The pod reads `{ userId, token, workspaceId }`
+for a user and `{ apiKey, workspaceId }` for a service account, so on 0.1.0 a
+session token works only when you also pass `userId`, and an `apiKey` is always
+refused. The fix — correct handshake keys, plus an up-front throw for no
+credential, both credentials, or `sessionToken` without `userId` — lands in the
+first release after 0.1.0. Until then, authenticate realtime with
+`sessionToken` + `userId`.
 
 ## 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.
+- `@synap-core/sdk` (tRPC) — for apps signed in as a user. Typed, React hooks.
+- `@synap-core/hub-rest-client` (REST against `/api/hub/*`, zero-dep) — for
+  agents/CLIs/scripts holding an API key. `new HubRestClient({ podUrl, apiKey,
+  workspaceId })`. Carries agent verbs the tRPC surface has no first-class path
+  for (`ask`, `orient`, `discover`).
 
 ## Keep types fresh
 The SDK is typed by `@synap-core/api-types`, generated from the pod's live router.
@@ -217,11 +283,16 @@ mock mode — all pre-wired. You add your screens; the plumbing is done.
 
 ## Scaffold it
 
+> **Not published yet.** `@synap-core/create-synap-app` is not on npm and the
+> base template is not public, so this does not work today. Until a release
+> exists, build on the SDK directly (`using-the-sdk.md`). The rest of this page
+> describes the template as it will ship.
+
 ```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
+npx @synap-core/create-synap-app my-app
+cd my-app                    # the scaffolder seeds .env.local from env.example;
+                             # fill in your pod / control-plane URLs
+pnpm install && pnpm dev     # http://localhost:3010
 ```
 
 Develop with **no pod** by setting `NEXT_PUBLIC_BASE_MOCK_MODE=true`.
@@ -269,9 +340,9 @@ components/layout/
 
 ## 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.
+`/login` → Synap Cloud sign-in → optional TOTP → pod picker → session stored →
+`/home`. A pod can also be signed into directly through its own Kratos (the
+login screen's manual-login step). You don't build this; you theme it.
 
 ---
 
@@ -282,38 +353,49 @@ 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:
+Every governed mutation (`entities.create`, `entities.update`, `relations.create`, …)
+has one of three outcomes, decided **by the pod**, not by your app:
 
-| Outcome | Meaning | What your code should do |
+| Outcome | How it arrives | 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 |
+| applied | resolves with the procedure's own status (`"created"`, `"updated"`, …) | proceed |
+| proposed | resolves with `status: "proposed"`, `proposalId`, `reviewUrl`, `message` — queued for the pod owner's review (like a PR) | **surface the review — do NOT treat as failure, do NOT retry** |
+| denied | **rejects** with a tRPC `FORBIDDEN` error whose message is the reason | 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.
+- **A `proposed` result does not throw.** It is a successful response with a
+  status; only a denial throws.
 - **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;
+import { TRPCClientError } from "@trpc/client";
+
+try {
+  const res = await synap.entities.create.mutate(input);
+  if (res.status === "proposed") {
+    // tell the user "queued for review"; link res.reviewUrl / res.proposalId.
+    // res.entity is null — nothing exists until the proposal is approved.
+  } else {
+    // "created": res.id / res.entity are live
+  }
+} catch (err) {
+  if (err instanceof TRPCClientError && err.data?.code === "FORBIDDEN") {
+    // denied: show err.message; don't retry
+  } else throw err;
 }
 ```
 
 ## 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.
+`entities.create` takes no idempotency key. The pod dedups some repeats on its
+own — an identical agent-authored retry within a short window, and creates that
+match an existing entity by identity (a stable `externalId`, or identifying
+properties) — but neither covers every case. Never resend a `proposed` write,
+and when unsure, read back before re-creating.

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

@@ -7,11 +7,16 @@ mock mode — all pre-wired. You add your screens; the plumbing is done.
 
 ## Scaffold it
 
+> **Not published yet.** `@synap-core/create-synap-app` is not on npm and the
+> base template is not public, so this does not work today. Until a release
+> exists, build on the SDK directly (`using-the-sdk.md`). The rest of this page
+> describes the template as it will ship.
+
 ```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
+npx @synap-core/create-synap-app my-app
+cd my-app                    # the scaffolder seeds .env.local from env.example;
+                             # fill in your pod / control-plane URLs
+pnpm install && pnpm dev     # http://localhost:3010
 ```
 
 Develop with **no pod** by setting `NEXT_PUBLIC_BASE_MOCK_MODE=true`.
@@ -59,6 +64,6 @@ components/layout/
 
 ## 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.
+`/login` → Synap Cloud sign-in → optional TOTP → pod picker → session stored →
+`/home`. A pod can also be signed into directly through its own Kratos (the
+login screen's manual-login step). You don't build this; you theme it.

package/skills/synap-app/governance.md

@@ -5,38 +5,49 @@ 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:
+Every governed mutation (`entities.create`, `entities.update`, `relations.create`, …)
+has one of three outcomes, decided **by the pod**, not by your app:
 
-| Outcome | Meaning | What your code should do |
+| Outcome | How it arrives | 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 |
+| applied | resolves with the procedure's own status (`"created"`, `"updated"`, …) | proceed |
+| proposed | resolves with `status: "proposed"`, `proposalId`, `reviewUrl`, `message` — queued for the pod owner's review (like a PR) | **surface the review — do NOT treat as failure, do NOT retry** |
+| denied | **rejects** with a tRPC `FORBIDDEN` error whose message is the reason | 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.
+- **A `proposed` result does not throw.** It is a successful response with a
+  status; only a denial throws.
 - **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;
+import { TRPCClientError } from "@trpc/client";
+
+try {
+  const res = await synap.entities.create.mutate(input);
+  if (res.status === "proposed") {
+    // tell the user "queued for review"; link res.reviewUrl / res.proposalId.
+    // res.entity is null — nothing exists until the proposal is approved.
+  } else {
+    // "created": res.id / res.entity are live
+  }
+} catch (err) {
+  if (err instanceof TRPCClientError && err.data?.code === "FORBIDDEN") {
+    // denied: show err.message; don't retry
+  } else throw err;
 }
 ```
 
 ## 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.
+`entities.create` takes no idempotency key. The pod dedups some repeats on its
+own — an identical agent-authored retry within a short window, and creates that
+match an existing entity by identity (a stable `externalId`, or identifying
+properties) — but neither covers every case. Never resend a `proposed` write,
+and when unsure, read back before re-creating.