@ziprack/sdk 0.1.2 → 0.2.1

package/dist/docs/manifest.md

@@ -0,0 +1,210 @@
+# The Manifest
+
+- [Introduction](#introduction)
+- [Core Fields](#core-fields)
+- [The Requires Block](#the-requires-block)
+- [Capability Sections](#capability-sections)
+- [A Complete Example](#a-complete-example)
+- [Validation Errors](#validation-errors)
+
+<a name="introduction"></a>
+## Introduction
+
+`manifest.json` sits at the root of the zip and is the applet's entire declaration of intent. It
+names the applet, states which capabilities it calls, and describes the shape of everything the Rack
+will need to validate, store, index, report on and render.
+
+**Declaration is mandatory, not advisory.** A call to a capability the manifest did not declare is
+refused at runtime with `undeclared_capability`. That is also what makes capability-diff review at
+upload meaningful: the manifest is a contract a reviewer can read.
+
+<a name="core-fields"></a>
+## Core Fields
+
+```json
+{
+    "schema": "ziprack/1",
+    "slug": "my-applet",
+    "name": "My Applet",
+    "version": "1.0.0",
+    "entry": "index.html",
+    "requires": { "capabilities": [], "profile": [] },
+    "media": []
+}
+```
+
+| Field | Rules |
+|---|---|
+| `schema` | Required. Exactly `ziprack/1`. |
+| `slug` | Required. `^[a-z0-9]+(-[a-z0-9]+)*$`, max 100. Becomes `/a/{slug}`. **Immutable.** |
+| `name` | Required, max 255. Shown to participants and admins. |
+| `version` | Required. `MAJOR.MINOR.PATCH` with optional `-prerelease`, max 50. Unique per applet. |
+| `entry` | Optional, default `index.html`. Relative, no `..`, ends in `.html`. |
+| `requires` | Required, even if empty. See below. |
+| `media` | Optional. See [Media](media.md). |
+
+Everything else at the top level belongs to a capability. A section whose owning capability is not
+declared is a validation error, and so is a section no installed capability owns.
+
+<a name="the-requires-block"></a>
+## The Requires Block
+
+```json
+"requires": {
+    "capabilities": ["auth@1", "attempt@1", "activity@1", "ai@1"],
+    "profile": ["display_name", "business_unit", "locale"]
+}
+```
+
+- Each capability reference matches `^[a-z][a-z0-9_]*@\d+$`. Declaring a capability twice is an
+  error, and so is declaring one this Rack does not implement — the error names what it does.
+- `profile` lists the attribute keys you want released, and requires `auth@1`. Keys match
+  `^[a-z][a-z0-9_]*$`. A key the deployment does not release is simply absent at launch;
+  [degrade gracefully](auth.md).
+- Declaring `attempt@1` has a side effect: it pins every participant to the version they started on.
+  See [Versioning](versioning.md#version-pinning).
+
+<a name="capability-sections"></a>
+## Capability Sections
+
+| Section | Capability | Shape |
+|---|---|---|
+| `segments[]` | `attempt@1` | `{key, label, values[{key,label}]}` — dimensions the admin filters by |
+| `activities[]` | `activity@1` | `{id, type, label, scale?, segment?, sequence?}` — required, at least one |
+| `reporting.metrics[]` | `activity@1` (+ `attempt@1`) | `{key, label, pre, post}` — pairs two declared activities |
+| `collections[]` | `db@1` | `{name, scope, schema, indexed?, quota?, permissions?, seed?}` |
+| `uploads[]` | `storage@1` | `{name, scope, mime[], max_bytes?, max_files?}` |
+| `prompts[]` | `ai@1` | `{id, mode, template, vars?, output_schema?, budget?, model?}` |
+| `broadcast` | `broadcast@1` | `{channels?, facilitator_events?}` |
+
+Each is specified in full on its capability's page. Two cross-cutting rules are worth stating here:
+
+**Scopes are declarations, not runtime choices.** `db@1` collections and `storage@1` uploads each
+declare a scope — `attempt`, `user`, `room` or `applet` — and an `attempt` scope requires
+`attempt@1` while a `room` scope requires `broadcast@1`. The scope answers, at declaration time,
+what happens to the data when an attempt completes.
+
+**Quotas and budgets are ceilings you may lower, not raise.** The deployment's config sets hard
+maxima; a manifest asking for more fails validation, and a manifest asking for nothing gets the
+deployment's defaults.
+
+<a name="a-complete-example"></a>
+## A Complete Example
+
+An applet exercising every capability at once. Most applets need three or four.
+
+```json
+{
+    "schema": "ziprack/1",
+    "slug": "team-summit",
+    "name": "Team Summit",
+    "version": "2.1.0",
+    "entry": "index.html",
+
+    "requires": {
+        "capabilities": ["auth@1", "attempt@1", "activity@1", "db@1", "storage@1", "ai@1", "broadcast@1"],
+        "profile": ["display_name", "business_unit", "locale"]
+    },
+
+    "media": [
+        { "id": "intro.welcome", "provider": "vimeo", "key": "912345678" },
+        { "id": "debrief.clip", "provider": "youtube", "key": "dQw4w9WgXcQ" }
+    ],
+
+    "segments": [
+        {
+            "key": "track",
+            "label": "Track",
+            "values": [
+                { "key": "rd", "label": "R&D" },
+                { "key": "commercial", "label": "Commercial" }
+            ]
+        }
+    ],
+
+    "activities": [
+        { "id": "intro.confidence", "type": "rating", "label": "How confident do you feel about the new operating model?", "scale": { "min": 1, "max": 6 }, "sequence": 1 },
+        { "id": "team.pitch", "type": "text", "label": "In one sentence, what is your team's pitch?", "segment": "track", "sequence": 2 },
+        { "id": "outro.confidence", "type": "rating", "label": "How confident do you feel about the new operating model?", "scale": { "min": 1, "max": 6 }, "sequence": 3 }
+    ],
+
+    "reporting": {
+        "metrics": [
+            { "key": "confidence", "label": "Confidence", "pre": "intro.confidence", "post": "outro.confidence" }
+        ]
+    },
+
+    "collections": [
+        {
+            "name": "ideas",
+            "scope": "room",
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "title":  { "type": "string", "maxLength": 120 },
+                    "body":   { "type": "string", "maxLength": 2000 },
+                    "status": { "type": "string", "enum": ["draft", "posted", "picked"] },
+                    "votes":  { "type": "integer", "minimum": 0 }
+                },
+                "required": ["title", "status"]
+            },
+            "indexed": ["status", "votes"],
+            "quota": { "max_records": 500, "max_bytes": 16384 },
+            "permissions": { "update": "owner", "delete": "facilitator" }
+        }
+    ],
+
+    "uploads": [
+        { "name": "artifacts", "scope": "room", "mime": ["image/png", "image/jpeg"], "max_bytes": 5242880, "max_files": 10 }
+    ],
+
+    "prompts": [
+        {
+            "id": "score_pitch",
+            "mode": "analysis",
+            "template": "Score this team pitch for clarity and specificity.\n\nPitch: {{pitch}}\nTrack: {{track}}",
+            "vars": {
+                "type": "object",
+                "properties": { "pitch": { "type": "string" }, "track": { "type": "string" } },
+                "required": ["pitch"]
+            },
+            "output_schema": {
+                "type": "object",
+                "properties": {
+                    "clarity":  { "type": "integer", "minimum": 1, "maximum": 5 },
+                    "feedback": { "type": "string" }
+                },
+                "required": ["clarity", "feedback"]
+            },
+            "budget": { "max_calls_per_attempt": 3, "max_output_tokens": 400 }
+        }
+    ],
+
+    "broadcast": {
+        "channels": ["main", "board"],
+        "facilitator_events": ["advance", "lock", "reveal"]
+    }
+}
+```
+
+<a name="validation-errors"></a>
+## Validation Errors
+
+The validator runs core rules first, then the rules of every declared capability, then cross-field
+checks. All errors are reported at once, keyed by manifest path, and the installer surfaces them as
+one message. The checks that catch people out:
+
+| Error | Cause |
+|---|---|
+| `Unknown manifest section [x]` | No installed capability owns that top-level key. |
+| `Manifest section [collections] requires the [db] capability` | The section is there; the declaration is not. |
+| `This Rack does not implement [db@1]. Implemented: …` | Wrong capability or wrong version for this deployment. |
+| `Activity references unknown segment [track]` | `activities[].segment` must name a declared segment key. |
+| `Metric references unknown activity [outro.x]` | `pre` and `post` must be declared activity ids. |
+| `reporting.metrics needs the attempt capability` | Metrics are computed over completed attempts. |
+| `A room-scoped collection requires the [broadcast] capability` | Scope implies capability. |
+| `Indexed path [votes] must be a string, integer, number or boolean property declared in the schema` | You can only index what you declared, and only scalars. |
+| `Only applet-scoped collections can be seeded` | A seed is shared reference data; see [Seeding](database.md#seeding). |
+| `Placeholder {{pitch}} is not declared in vars.properties` | Prompt templates and their `vars` schema must agree. |
+| `Analysis prompts need an output_schema of type object` | `mode: "analysis"` is structured output by definition. |
+| `The $room channel is reserved for the Rack` | Pick another channel name. |

package/dist/docs/mcp.md

@@ -0,0 +1,190 @@
+# The Rack MCP Server
+
+- [Introduction](#introduction)
+- [Installing](#installing)
+- [Connecting an Agent](#connecting-an-agent)
+- [Tools](#tools)
+- [Uploading a Package](#uploading-a-package)
+- [The Scaffold Skill](#the-scaffold-skill)
+- [Contributing Tools From a Capability](#contributing-tools)
+
+<a name="introduction"></a>
+## Introduction
+
+`ziprack/mcp` puts a [Model Context Protocol](https://modelcontextprotocol.io) server on the Rack,
+at `/ziprack/mcp`. An agent connected to it acts as one of the Rack's admins. It can list applets
+and their versions, read what participants produced, upload and promote packages, and fetch the
+skill that scaffolds a new applet.
+
+It is the Rack-side counterpart of the two authoring servers, which run locally with no Rack.
+`ziprack-mcp` serves the SDK docs and `ziprack-studio mcp` serves Studio blocks (see
+[The JavaScript SDK](sdk.md) and [zipRACK Studio](studio.md)).
+
+Agents authenticate in one of two ways. Clients that can complete a browser OAuth redirect use
+Passport OAuth, as claude.ai and Claude Code do. Clients such as Cursor, which only accept
+localhost redirects, use a minted token. Both kinds are Passport tokens with the `mcp:use` scope on
+the `api` guard. Every call needs `ziprack.use-admin`, and tools see only the applets the caller may
+see (see [Who May Do What](reporting.md#who-may-do-what)).
+
+<a name="installing"></a>
+## Installing
+
+The package is optional. A Rack without it never needs Passport.
+
+```sh
+composer require ziprack/mcp
+php artisan passport:install        # keys, migrations, and the personal access client
+```
+
+The Rack must do the rest itself, because a package can't impose it:
+
+- **API guard.** In `config/auth.php`, add
+  `'api' => ['driver' => 'passport', 'provider' => 'users']`.
+- **User model.** It uses `Laravel\Passport\HasApiTokens` and implements
+  `Laravel\Passport\Contracts\OAuthenticatable`.
+- **Consent screen.** Call `Passport::authorizationView(...)` to render your approve and deny page.
+  Post it with plain HTML forms, not Inertia visits: the redirect goes to the client's origin or
+  a custom scheme.
+- **Login redirect.** Add `AuthenticationException::redirectUsing(fn () => route('login'))`, so
+  that `/oauth/authorize` sends a signed-out admin to the login page rather than returning a 401.
+- **Custom schemes.** `php artisan vendor:publish --tag=mcp-config`, then set
+  `custom_schemes => ['claude', 'cursor', 'vscode']` in `config/mcp.php`.
+- **Optional client model.** Override `skipsAuthorization()` on a custom Passport client model so a
+  client that already holds a token isn't asked for consent again.
+
+`config/ziprack-mcp.php` is published with the `ziprack-config` tag:
+
+| Key | Default | |
+|---|---|---|
+| `enabled` | `true` | Register the endpoint, upload route and token routes |
+| `path` | `ziprack/mcp` | The endpoint |
+| `middleware` | `auth:api`, `mcp:use` scope, `can:ziprack.use-admin`, `throttle:60,1` | |
+| `oauth_routes` | `true` | laravel/mcp's discovery and dynamic client registration routes |
+| `token_ttl_days` | `30` | Lifetime of a minted token |
+| `upload_ttl_minutes` | `15` | Lifetime of a signed upload URL |
+
+<a name="connecting-an-agent"></a>
+## Connecting an Agent
+
+**Claude Code and claude.ai (OAuth).** Add the endpoint URL. The client discovers the
+authorization server from `/.well-known/oauth-protected-resource`, registers itself, and sends the
+admin to the consent screen.
+
+```sh
+claude mcp add --transport http my-rack https://rack.example.com/ziprack/mcp
+```
+
+**Cursor and other localhost-only clients (minted token).** Mint a token, either in the Rack's admin
+UI (backed by `GET|POST /ziprack/admin/mcp/tokens` and `DELETE /ziprack/admin/mcp/tokens/{id}`) or
+from the command line:
+
+```sh
+php artisan ziprack:mcp:token admin@example.com --name="Cursor laptop"
+php artisan ziprack:mcp:revoke admin@example.com --all
+```
+
+Then send the token as a bearer header:
+
+```json
+{ "mcpServers": { "my-rack": { "url": "https://rack.example.com/ziprack/mcp", "headers": { "Authorization": "Bearer <token>" } } } }
+```
+
+The plaintext is shown once. A token acts as the admin who minted it, and it stops working once that
+user is no longer an admin.
+
+<a name="tools"></a>
+## Tools
+
+| Tool | From | |
+|---|---|---|
+| `rack-status` | mcp | Format, implemented capabilities, health notes. Needs `ViewRack` |
+| `list-applets`, `get-applet`, `get-applet-version` | mcp | Applets, versions, review state, manifest |
+| `create-upload` | mcp | A signed upload URL (see below) |
+| `promote-version` | mcp | Make a version current. It cannot approve, so it cannot force |
+| `get-scaffold-skill` | mcp | The applet scaffold skill's files |
+| `list-attempts`, `get-attempt`, `attempt-overview` | attempt | |
+| `list-statements`, `applet-metrics` | activity | |
+| `list-collections`, `list-records` | db | |
+| `list-files` | storage | |
+| `ai-spend` | ai | |
+| `list-rooms`, `get-room` | broadcast | |
+
+Capability tools are only present when their capability package is installed.
+
+- **Same logic as the admin API.** Data tools run the same controller actions as the
+  [admin API](reporting.md), so filters, pagination and preview handling match what the admin UI
+  shows. Live data is the default; pass `preview: "preview"` or `preview: "all"` to include staff
+  preview runs.
+- **Audit log.** Writes (`mcp:upload`, `mcp:promote`) go to the audit log with the admin and the
+  OAuth client or token name they came through.
+
+<a name="uploading-a-package"></a>
+## Uploading a Package
+
+MCP has no binary arguments, and an agent can't push a 50 MB zip through its context. Instead,
+`create-upload` returns a signed, single-use URL with a ready-made `curl` command:
+
+```sh
+curl -sS -H 'Accept: application/json' -F 'package=@dist-zip/my-applet-1.1.0.zip' '<upload_url>'
+```
+
+The response is the installed version, in the same shape as `POST /ziprack/admin/versions/upload`.
+The rules in [Publishing](publishing.md) are unchanged.
+
+- **Default.** A later version installs as not current.
+- **With `activate: true`.** The version is promoted, unless it asks for capabilities that no admin
+  has approved yet. In that case the response carries a `warning` and the version waits in the
+  review queue.
+- **Reuse.** A used or expired URL answers `410`. Call `create-upload` again.
+
+<a name="the-scaffold-skill"></a>
+## The Scaffold Skill
+
+The canonical `ziprack-scaffold` skill lives in `packages/mcp/resources/skills/ziprack-scaffold/`.
+
+- **Tool.** `get-scaffold-skill` returns every file of the skill, keyed by path.
+- **Prompt.** `install-scaffold-skill` (with `agent: "claude"` or `"cursor"`) tells the agent to
+  write those files into `.claude/skills/` or `.cursor/skills/`.
+
+The skill scaffolds an applet on `@ziprack/sdk`, and its last step publishes that applet through
+`create-upload`.
+
+<a name="contributing-tools"></a>
+## Contributing Tools From a Capability
+
+A capability contributes tools the same way it contributes admin routes:
+
+1. Implement `ZipRack\Core\Capabilities\ProvidesMcpTools` on the capability class.
+2. Return tool class names from `mcpTools()`.
+3. Have each tool extend `ZipRack\Mcp\Tools\ZipRackTool`. It provides the helpers below.
+
+Helpers on `ZipRackTool`:
+
+| Helper | |
+|---|---|
+| `applet()` | Resolves the `slug` argument among the applets the caller may see |
+| `visibleApplets()` | A query of the applets the caller may see |
+| `owned()` | Loads a model that belongs to that applet |
+| `callAdmin()` | Runs your admin controller action in-process and returns its JSON |
+| `audit()` | Writes an audit-log row for a write |
+
+The tool classes only load when `ziprack/mcp` is installed, so list it under `suggest`, not
+`require`.
+
+A tool that only some users should have takes `#[RequiresAbility(Ability::ViewRack)]` (or any
+other ability). Everyone else is neither offered it nor able to call it. Tools that take a slug
+need nothing extra: `applet()` already sees only the caller's applets.
+
+<a name="adding-tools-from-the-rack"></a>
+## Adding Tools From the Rack
+
+The Rack can add tools of its own, for what only it knows about, such as its roles or its
+per-applet settings. Register them from a service provider:
+
+```php
+app(ZipRack\Mcp\ToolRegistry::class)->register(SetGuestAccess::class, ListMyApplets::class);
+```
+
+Rack tools extend `ZipRackTool` like any other, so they get the helpers above, the audit log and
+`#[RequiresAbility]`. A Rack tool with the same name (`#[Name('list-applets')]`) as a zipRACK or
+capability tool replaces it.

package/dist/docs/media.md

@@ -0,0 +1,85 @@
+# Media
+
+- [Introduction](#introduction)
+- [Declaring Media](#declaring-media)
+- [Rendering a Player](#rendering-a-player)
+- [Why the Rack Builds the URL](#why-the-rack-builds-the-url)
+- [Privacy Defaults](#privacy-defaults)
+
+<a name="introduction"></a>
+## Introduction
+
+Vimeo and YouTube embeds are a routine requirement, and they need no capability. What they do need
+is a declaration: the applet names a video by id, and the Rack builds the player URL.
+
+Everything else — your own images, audio and video — ships inside the zip and is referenced
+relatively. The CSP allows `img-src`/`media-src` of `'self' data: blob:` plus whatever hosts the
+deployment has allowlisted, and nothing else.
+
+<a name="declaring-media"></a>
+## Declaring Media
+
+```json
+"media": [
+    { "id": "corine.diagnosis", "provider": "vimeo",   "key": "912345678" },
+    { "id": "intro.welcome",    "provider": "youtube", "key": "dQw4w9WgXcQ" }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `id` | Required. `^[a-z0-9][a-z0-9_.:-]*$`, max 150, unique. |
+| `provider` | Required. Must be in the deployment's `ziprack.media.providers` — `vimeo`, `youtube`. |
+| `key` | Required. `^\d+$` for Vimeo, `^[\w-]{11}$` for YouTube. |
+
+Validation happens at upload, not at runtime, so a typo in a video id fails the package rather than
+the participant's session. Where `ziprack.media.resolve_oembed` is on, the Rack also performs the
+oEmbed lookup server-side at install and caches the title, thumbnail and duration.
+
+<a name="rendering-a-player"></a>
+## Rendering a Player
+
+```ts
+const url = Rack.media.embedUrl('corine.diagnosis');
+if (url) {
+    frame.src = url;
+}
+
+const embed = Rack.media.get('corine.diagnosis');
+embed?.meta?.title;        // cached oEmbed metadata, when resolved
+embed?.meta?.duration;
+
+Rack.media.all();          // every declared embed, by id
+```
+
+Both reads are synchronous — the embeds arrive in launch data.
+
+```html
+<iframe id="player" allow="autoplay; fullscreen; picture-in-picture; encrypted-media"></iframe>
+```
+
+The Rack sets a matching `allow` on the applet's own iframe. Permissions Policy has to be chained
+through both frames: if the outer frame does not carry it, your nested player silently loses
+autoplay and fullscreen, which is a genuinely hard bug to diagnose from inside the applet.
+
+Nested players inherit the applet's sandbox flags, so the player also runs with an opaque origin —
+no cookies, no storage of its own. Both providers' JS APIs are `postMessage`-driven, so they
+continue to work. A nested frame cannot talk to the Rack: the bridge checks `event.source`.
+
+<a name="why-the-rack-builds-the-url"></a>
+## Why the Rack Builds the URL
+
+Because a URL the applet controls is a channel the applet controls. An applet could otherwise encode
+data in a player URL — `player.vimeo.com/video/123?h=<something>` — and while that request lands in
+a provider's logs the attacker cannot read, the cleanest answer is to remove the path and query
+string from the applet's reach entirely. With declared media there is nothing to encode.
+
+It also buys back `connect-src 'self'`: the oEmbed lookup happens server-side at upload, so the
+applet never needs to talk to `vimeo.com` at runtime.
+
+<a name="privacy-defaults"></a>
+## Privacy Defaults
+
+The Rack builds YouTube URLs against `youtube-nocookie.com` and Vimeo URLs with `dnt=1`. For pharma
+and financial-services clients this is frequently procurement-gating rather than a nicety, and it is
+not configurable per applet.

package/dist/docs/protocol.md

@@ -0,0 +1,121 @@
+# The Bridge Protocol
+
+- [When You Need This](#when-you-need-this)
+- [The Envelope](#the-envelope)
+- [Handshake](#handshake)
+- [Calls and Acks](#calls-and-acks)
+- [Streaming](#streaming)
+- [Events](#events)
+- [What the Shell Does](#what-the-shell-does)
+
+<a name="when-you-need-this"></a>
+## When You Need This
+
+Almost never. Use [`@ziprack/sdk`](sdk.md) — it is the reference implementation of everything below,
+plus mock mode and a test host. This page exists for two cases: you are implementing the applet side
+in a language or runtime the SDK does not cover, and you are working on the Rack itself.
+
+<a name="the-envelope"></a>
+## The Envelope
+
+Every message in both directions is one JSON object:
+
+```json
+{ "ns": "ziprack", "v": 1, "type": "activity:statement", "requestId": "b1f0…", "payload": { } }
+```
+
+| Field | Rules |
+|---|---|
+| `ns` | Always `ziprack`. Anything else is ignored. |
+| `v` | Always `1`. Versioned with the format string, not with capabilities. |
+| `type` | `rack:*` for lifecycle, or `{capability}:{action}` matching `^[a-z][a-z0-9_]*:[a-z][a-z0-9_.]*$`. |
+| `requestId` | Present when you want an ack. The SDK uses `crypto.randomUUID()`. |
+| `payload` | Type-specific object. |
+
+The applet posts to `window.parent` with target origin `*`, because it has no origin of its own to
+assert. **The host trusts by `event.source`**: a message is honoured only when it came from the
+applet iframe's `contentWindow`. `event.origin` is never consulted — the applet's origin is opaque
+by design, so comparing it would be theatre. The same rule protects the applet in reverse: ignore
+any message whose source is not `window.parent`, which is what makes a nested Vimeo player unable to
+impersonate the Rack.
+
+<a name="handshake"></a>
+## Handshake
+
+```
+applet → host   { type: "rack:ready" }
+host   → applet { type: "rack:launch", payload: { …launch data… } }
+```
+
+The applet announces readiness as early as it can; the host replies with the full launch payload
+(see [Launch Data](sdk.md#launch-data)). Do not send capability calls before `rack:launch` arrives —
+queue them, as the SDK does.
+
+<a name="calls-and-acks"></a>
+## Calls and Acks
+
+```
+applet → host   { type: "db:create", requestId: "r1", payload: { collection: "ideas", data: {…} } }
+host   → applet { type: "rack:ack",  requestId: "r1", payload: { ok: true, data: { record: {…} } } }
+```
+
+An ack always carries the `requestId` it answers. On failure:
+
+```json
+{ "ok": false, "error": "quota_exceeded", "message": "Collection [ideas] is full (500 records)." }
+```
+
+Error codes are listed in [Acks and Errors](sdk.md#acks-and-errors) and are part of the contract:
+they do not change within `ziprack/1`.
+
+A message sent without a `requestId` is fire-and-forget — the host processes it and sends nothing
+back. `rack:eject` is the usual example.
+
+<a name="streaming"></a>
+## Streaming
+
+A streamed call receives multiple acks under one `requestId`:
+
+```json
+{ "ok": true, "partial": true, "delta": "Well, " }
+{ "ok": true, "partial": true, "delta": "that depends…" }
+{ "ok": true, "done": true, "data": { "message_id": "m_1", "text": "Well, that depends…", "usage": {…} } }
+```
+
+Only the terminal ack resolves the call; each partial resets the ack timeout. `ai:chat` is the only
+streaming surface in `ziprack/1`.
+
+<a name="events"></a>
+## Events
+
+Unsolicited messages from the host carry no `requestId`:
+
+```json
+{ "ns": "ziprack", "v": 1, "type": "rack:event",
+  "payload": { "event": "advance", "payload": { "step": 3 }, "channel": "main",
+               "from": { "participant_id": 42, "role": "facilitator" } } }
+```
+
+The reserved channel `$room` carries Rack-generated room events — `presence`, `state`, `role`,
+`status`. An applet cannot publish to it.
+
+<a name="what-the-shell-does"></a>
+## What the Shell Does
+
+Between the frame and the Rack sits the shell, a small script the Rack serves with the player page.
+Knowing its behaviour explains timings you would otherwise find surprising:
+
+- **Batching.** Calls are queued for up to 300 ms and posted together to
+  `POST /ziprack/s/{session}/messages`, maximum 50 per request. Acks come back in order and are
+  relayed individually.
+- **Coalescing.** Only the latest pending `attempt:state` survives a batch, so calling `setState()`
+  on every keystroke is safe.
+- **Retry.** A failed batch is retried once after 1 s; after that every message in it acks
+  `persist_failed`.
+- **Keepalive.** On page hide the pending batch flushes with `keepalive: true`.
+- **Files.** `storage:put` is intercepted and re-sent as multipart to
+  `POST /ziprack/s/{session}/files`; the `File` never travels as JSON.
+- **Streams.** When an ack carries `data.stream === true`, the shell opens an `EventSource` against
+  `/ziprack/s/{session}/stream/{requestId}` and relays each chunk as a partial ack.
+- **Completion.** A successful `attempt:complete` flips the Rack's own completion chrome — which is
+  why a completed attempt lands on its final screen rather than restarting.