@synap-core/cli 1.12.2 → 1.13.0

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, …
+# 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

package/skills/synap-app/using-the-sdk.md

@@ -7,33 +7,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 (
@@ -42,31 +50,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.

package/skills/synap-schema/SKILL.md

@@ -315,7 +315,7 @@ Defining a relation def is rarely worth it — `relates_to` + a property usually
 
 ---
 
-## The intent vocabulary — one SSOT, three mirrors
+## The intent vocabulary — one SSOT, two mirrors
 
 **What a capability DOES** — `send_message`, `generate_media`, `publish_post`,
 `delegate_agent_task` — is the
@@ -346,15 +346,17 @@ This is why every code-side copy is a **mirror** and not the source. A slug that
 none of the existing rows leaves `intent` UNSET; the vocabulary is deliberately not
 open for developers to mint (cf. W3C Web Intents, abandoned partly for that reason).
 
-### The three mirrors, and why each one must exist
+### The two mirrors, and why each one must exist
 
-There are exactly **three**. A fourth was deleted in 2026-10-01 (see below).
+There are exactly **two**. Two more were removed: `AbstractVerb` in
+`@synap/playbooks` (deleted 2026-10-01, see below), and the pod's own
+`ABSTRACT_VERBS` copy (collapsed 2026-10-26 — `@synap/database` now depends on
+`@synap-core/types`, so it re-exports mirror 1 under that name).
 
-| #   | Where                                                                                                                             | Kind                              | Why it cannot import the SSOT                                                                                                                                                                                                                                |
-| --- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 1   | `synap-backend/packages/database/src/schema/tools.ts` — `ABSTRACT_VERBS`                                                          | runtime, the 0283 SEED union (13) | `@synap-core/types` **devDepends on** `@synap/database`. A reverse import is a build cycle — the same constraint that forces `GUIDELINE_SCOPE_ORDER` to be mirrored.                                                                                         |
-| 2   | `synap-backend/packages/types/src/capability-intents/` — `ABSTRACT_INTENTS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS`            | runtime, published leaf           | Same cycle, other direction. It is a **leaf subpath** (`@synap-core/types/capability-intents`) rather than the `./` barrel because the barrel re-exports `@synap/database` types and a VALUE import from a barrel crashes Hermes (relay ships React Native). |
-| 3   | `synap-control-plane-api/src/seeds/capability-intent-vocabulary.ts` — `ABSTRACT_VERBS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS` | runtime, the CP catalog seeder    | The control plane is a **separate deploy target with its own `pnpm-lock.yaml`**. It resolves neither `@synap-core/types` nor the pod's packages (verified: `require.resolve('@synap-core/types')` → `MODULE_NOT_FOUND`).                                     |
+| #   | Where                                                                                                                             | Kind                           | Why it cannot import the SSOT                                                                                                                                                                                             |
+| --- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `synap-backend/packages/types/src/capability-intents/` — `ABSTRACT_INTENTS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS`            | runtime, published leaf        | The SSOT is SQL rows; a TypeScript list is a mirror by construction. The pod reads it too: `ABSTRACT_VERBS` in `packages/database/src/schema/tools.ts` is this `ABSTRACT_INTENTS`, re-exported (the 0283 SEED union, 13). |
+| 2   | `synap-control-plane-api/src/seeds/capability-intent-vocabulary.ts` — `ABSTRACT_VERBS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS` | runtime, the CP catalog seeder | The control plane is a **separate deploy target with its own `pnpm-lock.yaml`**. It resolves neither `@synap-core/types` nor the pod's packages (verified: `require.resolve('@synap-core/types')` → `MODULE_NOT_FOUND`).  |
 
 Consumed by: `@synap/api` (`intent-registry`, `create-from-definition`,
 `schemas/playbook-definition.ts`), `synap-app/packages/workspace-templates`
@@ -377,7 +379,7 @@ Search for this chapter by the field you are holding, not by the word "intent":
 All four are validated against this ONE vocabulary, so a workspace and a playbook
 cannot be spelled from two different lists.
 
-### THE FOURTH MIRROR WAS DELETED — do not re-add it
+### THE PLAYBOOKS MIRROR WAS DELETED — do not re-add it
 
 `AbstractVerb` in `@synap/playbooks/src/index.ts` was a TYPE-only mirror of all 13
 slugs. It was **stale** (no `publish_post`) and **dead** — a whole-repo scan across
@@ -396,18 +398,16 @@ a package that consumes nothing would go stale in the one direction that is invi
    `INSERT INTO "capability_intents" ("slug", "effect", "statement") VALUES (...) ON CONFLICT ("slug") DO NOTHING;`
    `effect` ∈ `read|write|act`. Never `drizzle-kit generate` — hand-write it, and mirror it into
    `0000_baseline_schema.sql` if it adds a table or column.
-2. **Add it to mirror 1** — `ABSTRACT_VERBS` in `packages/database/src/schema/tools.ts`,
-   **only if it is a SEED slug**. A post-seed row does not belong there (that is what
-   `publish_post` / `REGISTERED_EXTRAS` is for).
-   Post-seed rows today: `publish_post` (0284, write) and `delegate_agent_task`
-   (0314, act — every verb of an external-agent binding, `tools.config.agentBinding`:
-   start / send / status / cancel).
-3. **Add it to mirror 2** — `ABSTRACT_INTENTS` or `REGISTERED_EXTRAS` in
-   `packages/types/src/capability-intents/index.ts`. Then **`cd packages/types && pnpm build`** —
+2. **Add it to mirror 1** — `ABSTRACT_INTENTS` (a SEED slug) or `REGISTERED_EXTRAS`
+   (a post-seed row) in `packages/types/src/capability-intents/index.ts`. The pod's
+   `ABSTRACT_VERBS` is `ABSTRACT_INTENTS`, so it follows. Then **`cd packages/types && pnpm build`** —
    consumers typecheck against the built `dist/`, so a skipped rebuild makes your gate lie.
-4. **Add it to mirror 3** — the same two lists in the control plane's
+   Post-seed rows today: `publish_post` (0284, write), `delegate_agent_task`
+   (0314, act — every verb of an external-agent binding, `tools.config.agentBinding`:
+   start / send / status / cancel) and `read_webpage` (0329).
+3. **Add it to mirror 2** — the same two lists in the control plane's
    `capability-intent-vocabulary.ts`.
-5. **Update the arity floors** — `SEED_SLUG_ARITY` / `EXTRA_SLUG_ARITY` in
+4. **Update the arity floors** — `SEED_SLUG_ARITY` / `EXTRA_SLUG_ARITY` in
    `packages/api/src/__tripwires__/intent-vocabulary-one-ssot.tripwire.test.ts`.
    These are the ONE place you must edit by hand, and the build stops until you do.
 
@@ -416,8 +416,8 @@ from the migration SQL, so it is a red build — never a divergence nobody notic
 
 ### What can still go wrong
 
-- **A mirror can be added.** Nothing structurally prevents a fifth copy; the tripwire
-  only polices the names it knows. This is why step 5 exists as a hand-edit floor.
+- **A mirror can be added.** Nothing structurally prevents a third copy; the tripwire
+  only polices the names it knows. This is why step 4 exists as a hand-edit floor.
 - **A guard proves SAMENESS, never CORRECTNESS.** If every mirror and the migration agree
   on a slug that should not exist, all four guards stay green. The vocabulary's MEANING is
   reviewed by a human, not derived.

package/skills/synap-schema/intent-vocabulary-ssot.md

@@ -1,4 +1,4 @@
-## The intent vocabulary — one SSOT, three mirrors
+## The intent vocabulary — one SSOT, two mirrors
 
 **What a capability DOES** — `send_message`, `generate_media`, `publish_post`,
 `delegate_agent_task` — is the
@@ -29,15 +29,17 @@ This is why every code-side copy is a **mirror** and not the source. A slug that
 none of the existing rows leaves `intent` UNSET; the vocabulary is deliberately not
 open for developers to mint (cf. W3C Web Intents, abandoned partly for that reason).
 
-### The three mirrors, and why each one must exist
+### The two mirrors, and why each one must exist
 
-There are exactly **three**. A fourth was deleted in 2026-10-01 (see below).
+There are exactly **two**. Two more were removed: `AbstractVerb` in
+`@synap/playbooks` (deleted 2026-10-01, see below), and the pod's own
+`ABSTRACT_VERBS` copy (collapsed 2026-10-26 — `@synap/database` now depends on
+`@synap-core/types`, so it re-exports mirror 1 under that name).
 
-| #   | Where                                                                                                                             | Kind                              | Why it cannot import the SSOT                                                                                                                                                                                                                                |
-| --- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 1   | `synap-backend/packages/database/src/schema/tools.ts` — `ABSTRACT_VERBS`                                                          | runtime, the 0283 SEED union (13) | `@synap-core/types` **devDepends on** `@synap/database`. A reverse import is a build cycle — the same constraint that forces `GUIDELINE_SCOPE_ORDER` to be mirrored.                                                                                         |
-| 2   | `synap-backend/packages/types/src/capability-intents/` — `ABSTRACT_INTENTS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS`            | runtime, published leaf           | Same cycle, other direction. It is a **leaf subpath** (`@synap-core/types/capability-intents`) rather than the `./` barrel because the barrel re-exports `@synap/database` types and a VALUE import from a barrel crashes Hermes (relay ships React Native). |
-| 3   | `synap-control-plane-api/src/seeds/capability-intent-vocabulary.ts` — `ABSTRACT_VERBS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS` | runtime, the CP catalog seeder    | The control plane is a **separate deploy target with its own `pnpm-lock.yaml`**. It resolves neither `@synap-core/types` nor the pod's packages (verified: `require.resolve('@synap-core/types')` → `MODULE_NOT_FOUND`).                                     |
+| #   | Where                                                                                                                             | Kind                           | Why it cannot import the SSOT                                                                                                                                                                                             |
+| --- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `synap-backend/packages/types/src/capability-intents/` — `ABSTRACT_INTENTS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS`            | runtime, published leaf        | The SSOT is SQL rows; a TypeScript list is a mirror by construction. The pod reads it too: `ABSTRACT_VERBS` in `packages/database/src/schema/tools.ts` is this `ABSTRACT_INTENTS`, re-exported (the 0283 SEED union, 13). |
+| 2   | `synap-control-plane-api/src/seeds/capability-intent-vocabulary.ts` — `ABSTRACT_VERBS`, `REGISTERED_EXTRAS`, `CAPABILITY_INTENTS` | runtime, the CP catalog seeder | The control plane is a **separate deploy target with its own `pnpm-lock.yaml`**. It resolves neither `@synap-core/types` nor the pod's packages (verified: `require.resolve('@synap-core/types')` → `MODULE_NOT_FOUND`).  |
 
 Consumed by: `@synap/api` (`intent-registry`, `create-from-definition`,
 `schemas/playbook-definition.ts`), `synap-app/packages/workspace-templates`
@@ -60,7 +62,7 @@ Search for this chapter by the field you are holding, not by the word "intent":
 All four are validated against this ONE vocabulary, so a workspace and a playbook
 cannot be spelled from two different lists.
 
-### THE FOURTH MIRROR WAS DELETED — do not re-add it
+### THE PLAYBOOKS MIRROR WAS DELETED — do not re-add it
 
 `AbstractVerb` in `@synap/playbooks/src/index.ts` was a TYPE-only mirror of all 13
 slugs. It was **stale** (no `publish_post`) and **dead** — a whole-repo scan across
@@ -79,18 +81,16 @@ a package that consumes nothing would go stale in the one direction that is invi
    `INSERT INTO "capability_intents" ("slug", "effect", "statement") VALUES (...) ON CONFLICT ("slug") DO NOTHING;`
    `effect` ∈ `read|write|act`. Never `drizzle-kit generate` — hand-write it, and mirror it into
    `0000_baseline_schema.sql` if it adds a table or column.
-2. **Add it to mirror 1** — `ABSTRACT_VERBS` in `packages/database/src/schema/tools.ts`,
-   **only if it is a SEED slug**. A post-seed row does not belong there (that is what
-   `publish_post` / `REGISTERED_EXTRAS` is for).
-   Post-seed rows today: `publish_post` (0284, write) and `delegate_agent_task`
-   (0314, act — every verb of an external-agent binding, `tools.config.agentBinding`:
-   start / send / status / cancel).
-3. **Add it to mirror 2** — `ABSTRACT_INTENTS` or `REGISTERED_EXTRAS` in
-   `packages/types/src/capability-intents/index.ts`. Then **`cd packages/types && pnpm build`** —
+2. **Add it to mirror 1** — `ABSTRACT_INTENTS` (a SEED slug) or `REGISTERED_EXTRAS`
+   (a post-seed row) in `packages/types/src/capability-intents/index.ts`. The pod's
+   `ABSTRACT_VERBS` is `ABSTRACT_INTENTS`, so it follows. Then **`cd packages/types && pnpm build`** —
    consumers typecheck against the built `dist/`, so a skipped rebuild makes your gate lie.
-4. **Add it to mirror 3** — the same two lists in the control plane's
+   Post-seed rows today: `publish_post` (0284, write), `delegate_agent_task`
+   (0314, act — every verb of an external-agent binding, `tools.config.agentBinding`:
+   start / send / status / cancel) and `read_webpage` (0329).
+3. **Add it to mirror 2** — the same two lists in the control plane's
    `capability-intent-vocabulary.ts`.
-5. **Update the arity floors** — `SEED_SLUG_ARITY` / `EXTRA_SLUG_ARITY` in
+4. **Update the arity floors** — `SEED_SLUG_ARITY` / `EXTRA_SLUG_ARITY` in
    `packages/api/src/__tripwires__/intent-vocabulary-one-ssot.tripwire.test.ts`.
    These are the ONE place you must edit by hand, and the build stops until you do.
 
@@ -99,8 +99,8 @@ from the migration SQL, so it is a red build — never a divergence nobody notic
 
 ### What can still go wrong
 
-- **A mirror can be added.** Nothing structurally prevents a fifth copy; the tripwire
-  only polices the names it knows. This is why step 5 exists as a hand-edit floor.
+- **A mirror can be added.** Nothing structurally prevents a third copy; the tripwire
+  only polices the names it knows. This is why step 4 exists as a hand-edit floor.
 - **A guard proves SAMENESS, never CORRECTNESS.** If every mirror and the migration agree
   on a slug that should not exist, all four guards stay green. The vocabulary's MEANING is
   reviewed by a human, not derived.

package/templates/box/runner.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""The synap box runner: the only program the box template starts on boot.
+
+It holds no credential. It fetches its job from the provisioner by the
+provisioner's address on the isolated bridge, installs the declared packages
+(setup phase: the egress proxy lets only the package registries through),
+tells the provisioner it is done installing (run phase: only the declared
+hosts), runs the script as the unprivileged user `box` with /in and /out,
+streams the log back, uploads /out and reports the exit code.
+
+The provisioner, not this program, enforces the wall clock: it destroys the box.
+Python stdlib only (Debian 12's python3), so the template needs nothing else to
+run it. Contract with the provisioner: synap-cli src/lib/box/job-server.ts.
+"""
+
+import json
+import os
+import pwd
+import subprocess
+import sys
+import threading
+import time
+import urllib.parse
+import urllib.request
+
+BASE = os.environ.get("SYNAP_BOX_PROVISIONER", "http://10.20.0.1:8790")
+PROXY = os.environ.get("SYNAP_BOX_PROXY", "http://10.20.0.1:3128")
+WORK, IN, OUT = "/work", "/in", "/out"
+USER = "box"
+MAX_OUT_FILES = 20
+
+# The job server is on the bridge: never through the proxy.
+_direct = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+def call(method, path, body=None, ctype="application/json", timeout=60):
+    data = body if isinstance(body, (bytes, type(None))) else json.dumps(body).encode()
+    req = urllib.request.Request(BASE + path, data=data, method=method)
+    if data is not None:
+        req.add_header("Content-Type", ctype)
+    with _direct.open(req, timeout=timeout) as res:
+        raw = res.read()
+        return json.loads(raw) if raw and res.headers.get("content-type", "").startswith("application/json") else None
+
+
+def fetch_job():
+    # The box may boot before the provisioner registers its address: retry.
+    deadline = time.time() + 180
+    while True:
+        try:
+            return call("GET", "/job")
+        except Exception as err:  # noqa: BLE001
+            if time.time() > deadline:
+                raise SystemExit(f"no job from {BASE}: {err}")
+            time.sleep(2)
+
+
+class LogPump:
+    """Batches output and POSTs it to /log about twice a second."""
+
+    def __init__(self):
+        self.buf = bytearray()
+        self.lock = threading.Lock()
+        self.stop = threading.Event()
+        self.thread = threading.Thread(target=self._loop, daemon=True)
+        self.thread.start()
+
+    def write(self, data):
+        with self.lock:
+            self.buf += data
+
+    def _flush(self):
+        with self.lock:
+            chunk, self.buf = bytes(self.buf), bytearray()
+        if chunk:
+            try:
+                call("POST", "/log", chunk, "application/octet-stream")
+            except Exception:  # noqa: BLE001 - a lost log chunk must not kill the run
+                pass
+
+    def _loop(self):
+        while not self.stop.wait(0.5):
+            self._flush()
+
+    def close(self):
+        self.stop.set()
+        self.thread.join()
+        self._flush()
+
+
+def demote(user):
+    pw = pwd.getpwnam(user)
+
+    def run_as():
+        os.setgroups([])
+        os.setgid(pw.pw_gid)
+        os.setuid(pw.pw_uid)
+
+    return run_as, pw
+
+
+def run(cmd, env, pump):
+    """Run cmd as the box user; its stdout+stderr go to the log. Returns the exit code."""
+    pre, pw = demote(USER)
+    pump.write(("$ " + " ".join(cmd) + "\n").encode())
+    proc = subprocess.Popen(
+        cmd, cwd=WORK, env={**env, "HOME": pw.pw_dir, "USER": USER},
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, preexec_fn=pre,
+    )
+    for chunk in iter(lambda: proc.stdout.read1(65536), b""):
+        pump.write(chunk)
+    return proc.wait()
+
+
+def installed(job, env):
+    try:
+        if job["language"] == "python":
+            out = subprocess.run(
+                ["uv", "pip", "list", "--python", f"{WORK}/.venv/bin/python", "--format", "json"],
+                cwd=WORK, env=env, capture_output=True, timeout=60,
+            ).stdout
+            return [{"name": p["name"], "version": p["version"], "manager": "pip"} for p in json.loads(out or b"[]")]
+        out = subprocess.run(
+            ["pnpm", "list", "--json", "--depth", "0"], cwd=WORK, env=env, capture_output=True, timeout=60,
+        ).stdout
+        deps = (json.loads(out or b"[{}]") or [{}])[0].get("dependencies", {}) or {}
+        return [{"name": n, "version": d.get("version", ""), "manager": "npm"} for n, d in deps.items()]
+    except Exception:  # noqa: BLE001 - the list is evidence, not the verdict
+        return []
+
+
+def upload_out(pump):
+    sent = 0
+    for root, _dirs, files in os.walk(OUT):
+        for name in sorted(files):
+            full = os.path.join(root, name)
+            if os.path.islink(full) or not os.path.isfile(full):
+                continue
+            rel = os.path.relpath(full, OUT)
+            if sent >= MAX_OUT_FILES:
+                pump.write(f"\n[synap box] /out/{rel} skipped: at most {MAX_OUT_FILES} files\n".encode())
+                continue
+            try:
+                with open(full, "rb") as fh:
+                    call("PUT", "/out/" + urllib.parse.quote(rel), fh.read(), "application/octet-stream", timeout=600)
+                sent += 1
+            except Exception as err:  # noqa: BLE001
+                pump.write(f"\n[synap box] /out/{rel} not uploaded: {err}\n".encode())
+
+
+def main():
+    job = fetch_job()
+    pump = LogPump()
+    for d in (WORK, IN, OUT):
+        os.makedirs(d, exist_ok=True)
+    pw = pwd.getpwnam(USER)
+    for d in (WORK, OUT):
+        os.chown(d, pw.pw_uid, pw.pw_gid)
+
+    entry = os.path.normpath(job["entrypoint"])
+    if entry.startswith("..") or os.path.isabs(entry):
+        raise SystemExit(f"bad entrypoint {job['entrypoint']!r}")
+    os.makedirs(os.path.dirname(os.path.join(WORK, entry)), exist_ok=True)
+    with open(os.path.join(WORK, entry), "w") as fh:
+        fh.write(job["code"])
+    os.chown(os.path.join(WORK, entry), pw.pw_uid, pw.pw_gid)
+    with open(os.path.join(IN, "parameters.json"), "w") as fh:
+        json.dump(job.get("parameters"), fh)
+
+    env = {
+        "PATH": "/usr/local/bin:/usr/bin:/bin",
+        "LANG": "C.UTF-8",
+        "HTTP_PROXY": PROXY, "HTTPS_PROXY": PROXY, "http_proxy": PROXY, "https_proxy": PROXY,
+        "npm_config_proxy": PROXY, "npm_config_https_proxy": PROXY,
+        # Node's own fetch ignores HTTP(S)_PROXY unless told (Node >= 22.21 / 24).
+        "NODE_USE_ENV_PROXY": "1",
+        "UV_CACHE_DIR": f"{WORK}/.cache/uv", "npm_config_cache": f"{WORK}/.cache/npm",
+        "SYNAP_PARAMETERS_FILE": f"{IN}/parameters.json", "SYNAP_OUT_DIR": OUT,
+    }
+    pkgs = job.get("packages") or []
+    if job["language"] == "python":
+        code = run(["uv", "venv", f"{WORK}/.venv"], env, pump)
+        if code == 0 and pkgs:
+            code = run(["uv", "pip", "install", "--python", f"{WORK}/.venv/bin/python",
+                        *[f"{p['name']}=={p['version']}" for p in pkgs]], env, pump)
+        cmd = [f"{WORK}/.venv/bin/python", entry]
+    else:
+        with open(os.path.join(WORK, "package.json"), "w") as fh:
+            json.dump({"private": True}, fh)
+        os.chown(os.path.join(WORK, "package.json"), pw.pw_uid, pw.pw_gid)
+        code = run(["pnpm", "add", *[f"{p['name']}@{p['version']}" for p in pkgs]], env, pump) if pkgs else 0
+        cmd = ["node", entry]
+
+    call("POST", "/phase", {"phase": "run"})
+    if code == 0:
+        code = run(cmd, env, pump)
+    else:
+        pump.write(f"\n[synap box] packages did not install (exit {code}); the script was not run\n".encode())
+
+    upload_out(pump)
+    pump.close()
+    call("POST", "/done", {"exitCode": code, "installedPackages": installed(job, env)})
+
+
+if __name__ == "__main__":
+    sys.exit(main())