@neta-art/cohub 8.20.1 → 8.21.1

package/README.md

@@ -231,122 +231,11 @@ An **App** (previously *Work*) is a published, shareable web page hosted by
 Cohub. When a viewer opens an App, it runs inside a Cohub-managed runtime that
 provides short-lived access tokens — no API keys required.
 
-These runtime-only APIs are available **exclusively inside a published App**:
-
-- `client.context()` — returns App identity, App home Space identity, the current
-  viewer, permissions, optional invocation identifiers, and the current shell
-  location (`context.shell`). A new chat background has `shell.surface:
-  "background"` with the hosting Space in `shell.space` (`session` / `turn` are
-  null); `invocation.spaceId` is the same Space for compatibility.
-  Returns `null` outside an App runtime. `client.app.onContextChanged()` pushes
-  fresh state.
-- `client.auth.authorize({ target, scopes, reason?, alwaysAsk?, fallback? })`
-  — requests consent for an account, a specific Space, or a viewer-picked
-  Space. Silent when a grant covers the scopes. Returns the actual target,
-  how it was resolved, and the authoritative grant; see the
-  [authorization contract](../../docs/app-authorization.md).
-  `client.auth.request()` / `requestSpace()` / `requestCreateSpace()` remain
-  available for older Apps.
-- `client.context().permissions.viewerGrants` — render the viewer's current
-  per-space grants. Grant management uses an account-authenticated client or
-  the CLI; an App session cannot manage its own grants.
-- `client.app.commerce.*` — entitlement checks, credit consumption,
-  purchases.
-- `client.app.realtime.*` — temporary rooms, typed events, presence, and
-  membership.
-
-### Quick start (inside an App)
+The App runtime APIs — `client.context()`, `client.auth.authorize()`, app
+scopes and viewer grants, realtime rooms, callable surface, composer context,
+commerce, and App Actions — are documented in one place:
 
-```ts
-// Browsers don't inject ENV — pass it explicitly.
-const client = createCohubClient({ env: "prod" });
-
-const ctx = await client.context();
-if (!ctx?.app?.id) throw new Error("Not inside a published app.");
-
-const sourceSessionId = ctx.invocation?.sessionId ?? null;
-// `shell.space` is the current Cohub location. `app.homeSpace` is the App's
-// owning Space. A new chat background also has `invocation.spaceId`.
-const spaceId = ctx.shell?.space?.id ?? ctx.invocation?.spaceId ?? ctx.app.homeSpace?.id;
-const space = client.space(spaceId);
-
-// Request viewer grants from a user gesture (button click)
-const consent = await client.auth.authorize({
-  target: { kind: "space", spaceId },
-  scopes: ["session.prompt.fullaccess", "generation.create"],
-  reason: "This app sends prompts and generates images.",
-});
-if (consent.status !== "granted") return;
-// Act on the granted target, which may differ from the request.
-const activeSpace = consent.target.kind === "space"
-  ? client.space(consent.target.spaceId)
-  : space;
-```
-
-### The permission model (critical)
-
-An app's effective permission for one Space is the union of **two grant
-sources** — either one is enough:
-
-- **App scopes** (no consent): eight bounded scopes — `space.view`,
-  `session.view`, `file.view`, `file.edit`, `taskrun.view`,
-  `session.prompt.readonly`, `session.prompt.fullaccess`, `command.execute` —
-  granted at publish time via `appScopes`, applying only to the app's own
-  Space.
-- **Viewer grants** (consent-required): any permission the viewer holds, on
-  any Space they choose — one grant per Space, valid 14 days, re-validated
-  against the viewer's live access on every request. Includes scopes beyond
-  the eight app scopes, such as `generation.create` and the account-level
-  `user.*` scopes.
-
-**They never substitute for each other's halves.** `session.prompt.fullaccess`
-lets you send a prompt but does NOT let you read the reply — that needs
-`session.view`. `generation.create` lets you create a generation task, but
-polling its result needs `taskrun.view`.
-
-Render grant state from `ctx.permissions.viewerGrants`; act through
-`auth.authorize()` (silent when covered). `allowedViewerScopes` is deprecated —
-viewer grants are no longer gated by the app configuration.
-
-### Realtime rooms
-
-App runtime rooms are generic, temporary event channels. The SDK does not
-know the App's business events; define their names and payload types in the
-App itself.
-
-```ts
-type Events = {
-  "shared.state.updated": { value: number };
-  "activity.submitted": { itemId: string };
-};
-
-const room = await client.app.realtime.createRoom<Events>({
-  code: "TEAM-ALPHA", // optional; generated when omitted
-  maxParticipants: 64,
-  expiresInSeconds: 2 * 60 * 60,
-});
-
-const stop = room.subscribe("shared.state.updated", (event) => {
-  console.log(event.sequence, event.data.value, event.self);
-});
-
-await room.publish("shared.state.updated", { value: 42 });
-await room.setPresence({ status: "active" });
-await room.leave();
-stop();
-```
-
-`expiresInSeconds` is an absolute lifetime from server-side room creation. It
-never extends on publish, presence, or heartbeat. The maximum lifetime is
-24 hours. Room events are live and ordered while connected, with publish ACKs
-and sequence-gap detection; events missed during a disconnect are not replayed.
-
-For high-frequency traffic such as input frames, `room.send(type, data)` skips
-the per-event ACK that would otherwise cap throughput at one round trip per
-event; failures surface through `room.onSendError`. Every connection is its own
-participant by default; create the room with `seatPerUser: true` to give each
-viewer a single seat instead.
+**[App development](https://cohub.live/docs/developers/apps)**
 
-For the complete API-to-scope mapping, initialization recipe, capability
-recipes, a full working example, and a pitfalls checklist, see the
-**[App Runtime Guide](./docs/app-runtime-guide.md)**.
+Runtime APIs only work inside a published App; local pages get `null` from
+`context()`.