@synap-core/cli 1.11.0 → 1.13.0

package/skills/synap-app/SKILL.md

@@ -10,7 +10,7 @@ description: >
   "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:
+  synap:
     requires:
       env: []
     optional_env: [SYNAP_POD_URL, SYNAP_WORKSPACE_ID]
@@ -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, openclaw, …
+# 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/_skill.yaml

@@ -9,7 +9,7 @@ description: >
   "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:
+  synap:
     requires:
       env: []
     optional_env: [SYNAP_POD_URL, SYNAP_WORKSPACE_ID]

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.

package/skills/synap-app/install-commands.md

@@ -2,11 +2,17 @@
 
 ## 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.
 
@@ -22,24 +28,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, openclaw, …
+# 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.
 

package/skills/synap-app/overview.md

@@ -9,8 +9,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.
 
@@ -18,9 +18,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`.
 
@@ -30,13 +32,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