@ziprack/sdk 0.2.0 → 0.3.0

package/dist/docs/mcp.md

@@ -0,0 +1,202 @@
+# 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. See below |
+| `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.
+
+`promote-version` takes `slug`, `version`, and for the [data cutover](publishing.md#the-data-cutover):
+
+| Argument | |
+|---|---|
+| `accept_data_loss` | Promote even though the new version's collections reject or drop existing records. Pass it only after the user has seen what would be lost. |
+| `keep_invalid` | With `accept_data_loss`, keep the records the new schema rejects instead of deleting them. |
+
+A refused cutover comes back as a validation error carrying the message and the plan's notes, so
+the agent can tell the user what would change. A version with data migrations is always refused:
+they run in the browser, so it must be promoted from the applet's page in the Rack.
+
+<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, or its data cutover needs a decision. In either case the response carries a
+  `warning` and the version stays installed but not current: approve it in the review queue, or
+  promote it with `promote-version` (or from the Rack, when it has migrations).
+- **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/protocol.md

@@ -7,6 +7,7 @@
 - [Streaming](#streaming)
 - [Events](#events)
 - [What the Shell Does](#what-the-shell-does)
+- [The Migration Runner](#the-migration-runner)
 
 <a name="when-you-need-this"></a>
 ## When You Need This
@@ -51,6 +52,10 @@ The applet announces readiness as early as it can; the host replies with the ful
 (see [Launch Data](sdk.md#launch-data)). Do not send capability calls before `rack:launch` arrives —
 queue them, as the SDK does.
 
+The core of the payload is `schema`, `actor`, `applet`, `capabilities`, `media` and `roles` — the
+participant's [roles](auth.md#roles) in this applet, as a list of names, sent whatever the manifest
+declares. Each declared capability adds its own key.
+
 <a name="calls-and-acks"></a>
 ## Calls and Acks
 
@@ -119,3 +124,40 @@ Knowing its behaviour explains timings you would otherwise find surprising:
   `/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.
+
+<a name="the-migration-runner"></a>
+## The Migration Runner
+
+A second, unrelated frame protocol, between the Rack's own UI and the page that runs a package's
+[data migrations](database.md#data-migrations) at promotion. No applet is involved: the parent is
+the Rack page promoting the version, the child is `GET /ziprack/migration-runner` (route
+`ziprack.migration-runner`), framed sandboxed (see [Security](security.md#the-migration-runner)).
+You need this only if you are building a Rack UI.
+
+Messages are plain objects, not `ziprack` envelopes. Everything the runner posts carries
+`ziprackMigrationRunner: true`; it accepts messages only from `window.parent`, and runs once per
+page load.
+
+```
+runner → parent  { ziprackMigrationRunner: true, type: "ready" }
+parent → runner  { type: "run", steps, collections, context, timeoutMs? }
+runner → parent  { ziprackMigrationRunner: true, type: "log", step, level, text }      … as it runs
+runner → parent  { ziprackMigrationRunner: true, type: "done", collections, ms }
+              or { ziprackMigrationRunner: true, type: "error", step, code, message, stack? }
+```
+
+| Field | |
+|---|---|
+| `steps` | `[{ name, direction: "up" \| "down", source }]`, in run order — the plan's steps from `GET …/cutover`. |
+| `collections` | `{ name: { scope, records } }` — `collections` from `GET …/cutover/data`. |
+| `context` | `{ applet, from, to }`: the slug and the outgoing and target version strings. |
+| `timeoutMs` | Per step. Default 30000. |
+| `level` | `meta`, `step`, `ok`, `fail`, `log`, `info`, `warn` or `error`. |
+| `code` | `missing_up`, `missing_down` (the migration has no such function), `threw`, `timeout`, `bad_result` (it returned something other than `{ collection: records[] }`). |
+
+Each step's source is imported as a module from a `blob:` URL and called with a copy of the
+records; a returned object replaces the collections it names. `done.collections` holds every
+collection, by name, as a list of records: pass it to `POST …/cutover/check` and then, with the
+plan's fingerprint and the logged lines, to `…/promote` as `db.records`, `db.fingerprint` and
+`db.log`. After an `error`, nothing is promoted. The runner also renders every line as a terminal,
+so the parent can show the frame itself as the log.

package/dist/docs/publishing.md

@@ -4,6 +4,7 @@
 - [Installing a Version](#installing-a-version)
 - [Capability Diff Review](#capability-diff-review)
 - [Promotion](#promotion)
+- [The Data Cutover](#the-data-cutover)
 - [The Review Queue](#the-review-queue)
 - [Retiring a Version](#retiring-a-version)
 - [The Audit Log](#the-audit-log)
@@ -27,12 +28,15 @@ php artisan ziprack:install dist-zip/my-applet-1.0.0.zip --activate   # install
 
 or `POST /ziprack/admin/versions/upload` with the zip.
 
-Installation validates the manifest against this Rack's capability set, records the version, runs
-each declared capability's `onInstall()` hook inside a transaction, and only then extracts files. A
-version arrives as `ready` but **not current**, unless it is the applet's first — there is nothing
-to review a first version against, so it is promoted automatically.
+Installation validates the manifest against this Rack's capability set, then, inside one
+transaction, records the version, extracts its files and runs each declared capability's
+`onInstall()` hook — after extraction, so a hook can read the package. `db@1` uses it to check seed
+files and migration names and to register collection names the applet has never had; it does not
+touch existing data. A failure anywhere rolls the transaction back and deletes the extracted
+directory. A version arrives as `ready` but **not current**, unless it is the applet's first —
+there is nothing to review a first version against, so it is promoted automatically.
 
-Once files are extracted the Rack resolves declared media (the oEmbed lookup) and, when
+Once installed the Rack resolves declared media (the oEmbed lookup) and, when
 `publishing.osv_lookup` is on, queues a batch of the SBOM's purls against OSV.dev. Findings attach
 to the version and surface in the review queue; they do not block the install.
 
@@ -74,9 +78,84 @@ php artisan ziprack:promote my-applet 1.1.0 --force    # approve the pending rev
 or `POST /ziprack/admin/applets/{applet}/versions/{version}/approve` followed by
 `…/promote`.
 
-Promotion is refused when the version is not `ready`, or when it has an unapproved capability
-addition — the error names exactly what was added. On success, `current_version_id` moves and each
-capability's `onPromote()` hook runs.
+Promotion is refused when the version is not `ready`, when it has an unapproved capability
+addition — the error names exactly what was added — or when carrying the applet's data over needs
+a decision (below). Otherwise the capabilities' promotion work and the move of `current_version_id`
+commit in one transaction, then each capability's `onPromote()` hook runs.
+
+<a name="the-data-cutover"></a>
+## The Data Cutover
+
+A version declaring `db@1` brings the applet's records over with it (see
+[Data Across Versions](database.md#data-across-versions)). The Rack plans the cutover first, and
+refuses with a reason while the plan needs a decision:
+
+| Reason | Means | To promote |
+|---|---|---|
+| `migration_required` | [Data migrations](database.md#data-migrations) have to run: the version's pending `up`s, or `down`s for applied migrations it lacks. | Promote from the Rack's UI, which runs them in the browser. |
+| `data_changed` | The data changed between planning the cutover (or running the migrations) and committing it. | Review the plan and promote again; run the migrations again. |
+| `version_changed` | Another promotion committed while this one was being prepared. | Review the new plan and promote again. |
+| `migration_invalid` | What the migrations returned does not fit the version. The plan carries the check. | Fix the migration and upload a new version. |
+| `data_loss` | No migration runs, and the new schema or quota rejects existing records, or a dropped collection holds records. | Confirm with `accept_data_loss`. |
+
+Over the admin API the refusal is a `409`:
+
+```json
+{
+    "message": "Version 2.0.0 changes collections that hold data. Review what changes and confirm.",
+    "reason": "data_loss",
+    "plan": {
+        "version": { "id": 12, "version": "2.0.0" },
+        "from": { "id": 9, "version": "1.4.0" },
+        "status": "confirm",
+        "needs_browser": false,
+        "rollback": false,
+        "steps": [],
+        "collections": [
+            {
+                "name": "questions", "scope": "applet", "change": "changed", "records": 240,
+                "diff": [{ "path": "difficulty", "change": "required_property_added", "detail": "New required property difficulty." }],
+                "invalid": 240, "invalid_samples": [{ "id": "…", "errors": { "difficulty": ["…"] } }],
+                "over_quota": 0, "seed": "skipped"
+            }
+        ],
+        "notes": [{ "level": "warning", "message": "240 of 240 records in [questions] do not match the new schema." }],
+        "fingerprint": "…"
+    }
+}
+```
+
+and the decision goes back in the promote body under `db`:
+
+| Key | |
+|---|---|
+| `accept_data_loss` | Confirm a `data_loss` plan. A JSON boolean; anything else is a `422`. |
+| `invalid` | `discard` (the default) deletes the records the new schema rejects; `keep` leaves them. |
+| `records`, `fingerprint`, `log` | A migrating version: what the migrations returned, by collection; the fingerprint of the data they ran on; the runner's log, kept with the snapshot. |
+
+`GET …/versions/{version}/cutover` returns the same plan without promoting, including each step's
+source. A Rack UI promoting a migrating version reads `…/cutover/data` (the records and their
+fingerprint), runs the steps in the [migration runner](protocol.md#the-migration-runner), checks the
+result with `POST …/cutover/check` (`{records}` → `{ok, errors, collections}`), then promotes with
+`db.records` and `db.fingerprint`. The server checks the records again inside the transaction.
+
+From the command line and over MCP a lossy plan can be confirmed but a migration cannot run:
+
+```sh
+php artisan ziprack:promote my-applet 2.0.0 --accept-data-loss
+php artisan ziprack:promote my-applet 2.0.0 --accept-data-loss --keep-invalid
+```
+
+Every cutover that changes data is preceded by a [snapshot](database.md#snapshots).
+
+**Uploading with activate.** `ziprack:install --activate`, an admin upload with `activate`, and
+MCP's `create-upload` with `activate: true` try the promotion straight after installing, with no
+cutover decision. If the cutover needs one, the version is installed but not current: the admin
+upload and the MCP upload answer `201` with a `warning` and `cutover: {reason, plan}`, and the
+command prints the refusal and exits non-zero. Promote it once the decision is made.
+
+A version that drops `db@1` still goes through the cutover: the applet's collections all count as
+removed, so promoting it needs the same confirmation as removing them one by one.
 
 What promotion means depends on pinning:
 

package/dist/docs/reporting.md

@@ -2,6 +2,7 @@
 
 - [Composition](#composition)
 - [The Admin API](#the-admin-api)
+- [Who May Do What](#who-may-do-what)
 - [Preview Runs](#preview-runs)
 - [The CSV Export](#the-csv-export)
 - [Metrics](#metrics)
@@ -31,7 +32,8 @@ GET /ziprack/admin/applets/{applet}/panels
 ```
 
 `panels` is the intersection of what the current version declares and what this Rack implements —
-render exactly those and nothing else.
+render exactly those and nothing else. It also contains `roles` when the current version declares
+any [roles](auth.md#roles), for the screen that assigns them.
 
 | Declared | Renders |
 |---|---|
@@ -46,7 +48,8 @@ render exactly those and nothing else.
 ## The Admin API
 
 All routes sit under `ziprack-admin.prefix` (default `/ziprack/admin`) behind `web`, `auth` and the
-`ziprack.admin` gate — which defaults to `$user->is_admin` and can be redefined by the deployment.
+`ziprack.use-admin` gate. Every route with an `{applet}`, including capability routes, also requires
+`ziprack.manage-applet` for that applet. See [Who May Do What](#who-may-do-what).
 
 | Route | Purpose |
 |---|---|
@@ -54,9 +57,10 @@ All routes sit under `ziprack-admin.prefix` (default `/ziprack/admin`) behind `w
 | `GET applets` · `POST applets` | List and create |
 | `GET applets/{applet}` · `PATCH applets/{applet}` | Show and update |
 | `GET applets/{applet}/panels` | What to render |
-| `POST versions/upload` · `POST applets/{applet}/versions` | Install a package |
+| `GET applets/{applet}/roles` · `PUT applets/{applet}/roles/{role}` | Declared roles and their assignments; replace one role's ([Roles](auth.md#rack-side)) |
+| `POST versions/upload` · `POST applets/{applet}/versions` | Install a package; with `activate`, a blocked promotion answers `201` with `warning` (and `cutover`) |
 | `GET applets/{applet}/versions/{version}` | Manifest, requires diff, SBOM, OSV findings, publisher |
-| `POST …/{version}/approve` · `…/promote` · `…/retire` | The publishing actions |
+| `POST …/{version}/approve` · `…/promote` · `…/retire` | The publishing actions. `promote` takes `force` and `db`, and answers `409` when the [data cutover](publishing.md#the-data-cutover) needs a decision |
 | `GET review-queue` | Everything awaiting a decision |
 | `GET participants` · `GET audit-log` | People and capability calls |
 
@@ -67,11 +71,50 @@ Capability packages add their own, and only when installed:
 | `GET applets/{applet}/overview` · `…/attempts` · `…/attempts/{attempt}` | `attempt` |
 | `GET applets/{applet}/attempts/{attempt}/statements` · `…/export.csv` · `…/metrics` | `activity` |
 | `GET applets/{applet}/collections` · `…/collections/{name}/records` | `db` |
+| `GET applets/{applet}/versions/{version}/cutover` · `…/cutover/data` · `POST …/cutover/check` | `db` — the cutover plan, the records migrations run on, a check of what they return |
+| `GET applets/{applet}/snapshots` · `POST …/snapshots` · `GET …/snapshots/{snapshot}/log` · `…/download` · `POST …/restore` | `db` — [snapshots](database.md#snapshots); a restore requires `confirm` set to the applet's slug |
 | `GET applets/{applet}/files` | `storage` |
 | `GET applets/{applet}/ai/spend` · `…/ai/calls` | `ai` |
 | `GET applets/{applet}/rooms` · `POST rooms` · `GET rooms/{room}` · `POST rooms/{room}/status` · `GET rooms/{room}/events` | `broadcast` |
 | `GET participants/{participant}/profile` · `PUT …` | `auth` |
 
+<a name="who-may-do-what"></a>
+## Who May Do What
+
+zipRACK asks, and the Rack answers. Every check goes through one contract,
+`ZipRack\Core\Contracts\AppletAccess`, with the applet in hand when there is one:
+
+| Ability | Gate | Asked for |
+|---|---|---|
+| `UseAdmin` | `ziprack.use-admin` | The admin API, the MCP server, personal MCP tokens |
+| `CreateApplet` | `ziprack.create-applet` | `POST applets`, `POST versions/upload`, an agent's upload without a slug |
+| `ManageApplet` | `ziprack.manage-applet` | Every `applets/{applet}` route — promoting, assigning roles, the cutover routes, taking and restoring snapshots; unpublished and `?preview` player launches |
+| `ReviewVersions` | `ziprack.review` | `GET review-queue`, approving, promoting with `force` past review |
+| `ViewRack` | `ziprack.view-rack` | `GET status`, `GET audit-log`, every participant, the `rack-status` tool |
+
+`scopeVisible()` narrows the applet list, the MCP tools' slug lookups and `list-applets` to what
+the user may see. An applet they may not see reads as not installed.
+
+The default binding, `AdminOnlyAccess`, answers every ability with the `ziprack.admin` gate
+(`$user->is_admin`), so a Rack that binds nothing, or only redefines that gate, behaves as before.
+A Rack with other roles binds its own:
+
+```php
+$this->app->singleton(AppletAccess::class, RackAppletAccess::class);
+```
+
+Applets have an **owner**, a morph like a version's publisher: whoever published the first
+version, or created the empty applet. `$applet->isOwnedBy($user)` is the usual basis for
+`ManageApplet`. A package whose slug already belongs to an applet the publisher cannot manage is
+refused, so an upload cannot land in someone else's applet.
+
+**Participants** are Rack-wide. A user with `ViewRack` sees all of them; anyone else sees the
+participants with audit-log entries on an applet they can see, through `GET participants` and the
+`auth` profile routes. `ZipRack\Core\Access\ParticipantVisibility` applies the rule.
+
+To react to publishing, listen for `ZipRack\Core\Events\VersionInstalled` (with the publisher),
+`VersionApproved` and `VersionPromoted`.
+
 <a name="preview-runs"></a>
 ## Preview Runs
 
@@ -87,6 +130,11 @@ returns **live attempts only** unless told otherwise:
 An unrecognised value falls back to `live` rather than erroring, so a stale bookmark cannot quietly
 turn preview data into a report.
 
+The `db@1` record browser (`…/collections` and `…/collections/{name}/records`) takes the same
+`?preview=` with the same default, and the collection `records` counts follow it. `ziprack_statements`
+and `ziprack_records` both carry an `is_preview` column set from the launch session, so preview data
+is saved, never mixed in, and easy to delete in one query when you want it gone.
+
 <a name="the-csv-export"></a>
 ## The CSV Export
 
@@ -144,3 +192,6 @@ The skeleton ships a reference admin over these endpoints. When you replace it:
 2. Render `db@1` record tables from the collection's declared JSON Schema — the schema is there
    precisely so the UI does not need per-applet knowledge.
 3. Treat the review queue as the landing page. It is where the decisions are.
+4. Show the cutover plan before promoting, and run migrations in the sandboxed
+   [migration runner](protocol.md#the-migration-runner). A Rack UI is the only place a version with
+   data migrations can be promoted.

package/dist/docs/sdk.md

@@ -64,8 +64,9 @@ interface LaunchData {
     applet: { slug: string; name: string; version: string };
     capabilities: string[];                  // as declared, e.g. ['auth@1', 'db@1']
     media: Record<string, MediaEmbed>;       // Rack-built player URLs by declared id
+    roles?: string[];                        // e.g. ['member', 'judge']; absent before Rack v1.8
 
-    auth?:      { user: LaunchUser };
+    auth?:      { user: LaunchUser; withheld?: string[] };
     attempt?:   { id, status, state, segment };
     activity?:  { activities: LaunchActivity[] };
     db?:        { collections: Array<{ name, scope }> };
@@ -75,9 +76,11 @@ interface LaunchData {
 }
 ```
 
-Each capability contributes its own key, and only when declared. The typed accessors read from the
-same payload, so `Rack.auth.user()`, `Rack.attempt.state()` and `Rack.activity.activities()` are
-synchronous and free.
+Each capability contributes its own key, and only when declared. `roles` is core and always
+present; read it through `Rack.auth.roles()`, `Rack.auth.hasRole(name)` and `Rack.auth.isGuest()`,
+which need no capability (see [Roles](auth.md#roles)). The typed accessors read from the same
+payload, so `Rack.auth.user()`, `Rack.auth.roles()`, `Rack.attempt.state()` and
+`Rack.activity.activities()` are synchronous and free.
 
 ```ts
 Rack.on('launch', (data) => render(data));   // fires immediately if already launched
@@ -178,6 +181,14 @@ Rack.mock.ai('score_pitch', (vars) => ({ clarity: 4, feedback: `Nice work on "${
 Rack.mock.resetAttempt();   // replay a completed attempt
 ```
 
+The mock participant is a `member` holding the manifest's `everyone` and `members` grants. Try
+other identities from the page URL:
+
+```
+http://localhost:5173/?ziprack-guest                         a guest, with the guests grants
+http://localhost:5173/?ziprack-roles=judge,applet-author     as if the Rack had assigned these
+```
+
 Mock mode also engages if a real Rack fails to answer `rack:launch` within `launchTimeoutMs`. That
 is a deliberate development convenience, and the console says so — if you see it in production,
 something is wrong with the shell, not with your applet.
@@ -214,6 +225,19 @@ it('records the answer and completes exactly once', async () => {
 | `host.attempt()`, `host.records(name)`, `host.files()` | Persisted state. |
 | `host.push(event)` | Push a `rack:event` in, as the Rack would, to drive broadcast handlers. |
 
+`new FakeHost(manifest, options)` takes the mock Rack's options. Those worth knowing:
+
+| Option | |
+|---|---|
+| `guest` | Launch as a guest: `guest` instead of `member`, and the `guests` grants. |
+| `roles` | Roles held on top of the grants, as if assigned. Any name, built-in ones included. |
+| `role` | The room role, `participant` or `facilitator`, instead of the one the assignment mode gives. |
+| `participantId`, `participantName` | The actor. |
+
+```ts
+const host = new FakeHost(manifest, { roles: ['judge'] });
+```
+
 <a name="leaving-the-applet"></a>
 ## Leaving the Applet