@ziprack/sdk 0.2.1 → 0.4.0

package/dist/docs/database.md

@@ -8,7 +8,11 @@
 - [Permissions](#permissions)
 - [Quotas](#quotas)
 - [Seeding](#seeding)
+- [Data Across Versions](#data-across-versions)
+- [Data Migrations](#data-migrations)
+- [Snapshots](#snapshots)
 - [How It Is Stored](#how-it-is-stored)
+- [Rack Side](#rack-side)
 
 <a name="introduction"></a>
 ## Introduction
@@ -67,11 +71,19 @@ what happens to it when an attempt ends.
 | `attempt` | One attempt | **Frozen when the attempt completes**, alongside `state` | `attempt@1` |
 | `user` | One participant | Outlives any attempt | — |
 | `room` | Everyone in the room | The room | `broadcast@1` |
-| `applet` | Everyone on this applet version | The version. Read-mostly: seed data, shared catalogs | — |
+| `applet` | Everyone using the applet, on every version | The applet. Carries over every promotion. Seed data, shared catalogs | — |
 
 A session that has no attempt or no room cannot touch a collection scoped to one; the call is
 refused with `forbidden` rather than silently falling back to something else.
 
+`user`, `room` and `applet` records belong to the applet, not to a version, so they are still there
+after you promote a new one — see [Data Across Versions](#data-across-versions). `attempt` records
+stay with their attempt, and so with the version it ran on.
+
+A session reads and writes a collection through the definition of the version it launched on. An
+attempt pinned to an earlier version keeps that version's schema, indexes and quota until it
+completes, even after a later version changed them.
+
 <a name="reading-and-writing"></a>
 ## Reading and Writing
 
@@ -183,33 +195,230 @@ The seed file is a JSON array of records, each one a document exactly as `create
 ]
 ```
 
-The installer loads it when the version is installed, inside the same transaction, and holds every
-record to the rules a write would face: it must be an object, it must match the schema, it must fit
+The seed is **checked at install and loaded at promotion**. At install the Rack holds every record
+to the rules a write would face: it must be an object, it must match the schema, it must fit
 `max_bytes`, and the file must fit `max_records`. One bad record refuses the whole package, and the
 error names the record's index and the failing path. A package with a bad seed never installs.
 
+When the version is promoted, the seed loads into the collection **only if its live dataset is
+empty**. A seed is the starting data, never a reset: once the applet has records, a later version's
+seed file is not loaded, even if it changed. The promotion plan says so. To change records that
+already exist, ship a [data migration](#data-migrations).
+
 Things to know:
 
 - **Only `applet` scope.** No room, participant or attempt exists at install, so nothing else has
   a scope to seed into.
-- **Every version gets its own copy.** `applet` records belong to the version, so each version
-  loads its own seed file. Records written to the previous version stay with that version.
+- **Loaded once, then the data is yours.** Records carry over every promotion. If the collection is
+  emptied (preview records do not count), the next promotion loads the seed again.
 - **Seeded records have no owner.** `owner_id` is `null`, so under the default `owner` permission
   participants can read them but cannot change them. Declare `members` or `facilitator` if they
   should be editable.
-- **No `RecordChanged` events.** Nobody is listening to a version that has not launched yet.
+- **No `RecordChanged` events.** The seed loads inside the promotion, before any session runs the
+  new version.
 - **The quota still applies.** A seed is capped at 5000 records (`max_records_per_scope`), and so
   is everything later written to that scope.
 - **Not in the mock Rack.** The SDK's `MockRack` does not load seed files. In local development,
   create the records from your dev harness.
 
+<a name="data-across-versions"></a>
+## Data Across Versions
+
+Promoting a version carries the applet's data over to it. `user`, `room` and `applet` records are
+kept and checked against the new version's collections; `attempt` records are left alone, in the
+shape their attempt wrote them. Nothing about your data changes at install: a new version's
+collections are checked, and names the applet has never had are registered empty, but the live
+version keeps reading what it always read until promotion.
+
+At promotion the Rack plans the cutover. For each declared collection it works out whether it is
+`added`, `removed`, `restored`, `changed` or `unchanged`, describes the structural diff (a new
+required property, a narrowed enum, a changed quota), and — when no migration runs — validates
+every existing record against the new schema and quota. A promotion that would leave records the
+new version rejects, strand a collection that holds records, or roll migrations back is not done
+silently: it is refused until someone confirms, and the refusal carries the plan. See
+[Promotion](publishing.md#promotion) for how that looks from the admin API, the CLI and MCP.
+
+| The new version… | What happens at promotion |
+|---|---|
+| Changes nothing about its collections | Promotes. Records are untouched; no snapshot is taken. |
+| Makes a compatible change: a new optional property, a wider enum, a new index, a new collection | Promotes. Existing records validate, so they carry over as they are. A snapshot is taken first when a collection holding records changed. New collections start empty, or with their seed. |
+| Ships a [migration](#data-migrations) that has not run on this applet | Must be promoted from the Rack's UI, which runs the migrations in the browser, checks the result, then commits it. The CLI and MCP refuse it (`migration_required`). |
+| Makes an incompatible change with no migration | Refused with `data_loss`, naming how many records the new schema rejects, with samples. Once confirmed, rejected records are deleted (`invalid: discard`, the default) or kept as they are (`keep`). A kept record fails validation on its next update until it is fixed. |
+| Drops a collection that holds records | Refused with `data_loss`. Once confirmed, the collection is set aside with its records; `ziprack:db:prune` deletes them. A later version that declares it again gets them back. |
+| Changes a collection's `scope` | Refused **at install**: `Collection [x] cannot change scope from [room] to [applet]; use a new collection name.` A migration cannot move records between scopes either. |
+| Lowers `max_records` below what a scope holds, or `max_bytes` below a record's size | Refused with `data_loss`. Once confirmed, oversize records count as rejected; a scope over its new record quota keeps its records but refuses `create()` with `quota_exceeded` until it is back under. |
+| Ships a changed seed file for a collection that has records | Promotes. The seed is not loaded, and the plan notes it. Use a migration. |
+| Is an earlier version that lacks migrations already run (a rollback) | Those migrations run `down`, newest first, from the source the Rack stored when they ran up — in the browser, like any migration, and flagged as a rollback. A migration with no `down` stops it; restore the [snapshot](#snapshots) taken before it ran instead. An earlier version with no migrations involved is treated like any other change. |
+| Is the applet's first | Nothing to carry over. Its migrations are recorded as applied without running, and the seed loads. |
+
+Uploading without activating changes nothing about the data; the plan is made when someone
+promotes. An upload *with* activate tries the promotion, and if the cutover needs a decision the
+version stays installed but not current.
+
+Two more rules apply to every cutover:
+
+- **Preview records are dropped where shapes change.** A cutover that runs migrations deletes every
+  [preview](attempts.md#preview-runs) record of the applet; one that does not deletes the preview
+  records of the collections whose definition changed. Migrations never see preview records.
+- **Pinned attempts keep the old shape.** An in-progress attempt on the outgoing version reads and
+  writes `user`, `room` and `applet` records through that version's definition until it completes.
+  After a cutover that reshapes them, it can still write records in the old shape. If your applet is
+  pinned, write code that tolerates both, or reshape only what in-progress attempts do not write.
+
+<a name="data-migrations"></a>
+## Data Migrations
+
+When a new version needs existing records in a new shape — a renamed property, a split collection,
+a value back-filled from another — ship a data migration. A migration is an ES module in a
+`migrations/` directory at the zip root:
+
+```
+my-applet-2.0.0.zip
+├── manifest.json
+├── migrations/
+│   ├── 2026_09_01_090000_add_difficulty.js
+│   └── 2026_10_09_120000_split_archived_ideas.js
+└── …
+```
+
+| Rule | |
+|---|---|
+| Name | `YYYY_MM_DD_HHMMSS_name.js` (or `.mjs`), lowercase, directly inside `migrations/`. Anything else refuses the package at install. |
+| Order | Name order. The timestamp prefix is the order. |
+| Cumulative | **Keep every migration you have ever shipped.** The Rack runs the ones this applet has not run yet, so any earlier version can be brought forward. |
+| Self-contained | Each file is imported on its own, with no network. Do not import other files or packages. The starter copies `migrations/` into the zip as written, unbundled. |
+| Exports | `up(db, ctx)`, and `down(db, ctx)` if the change can be undone. Either as named exports or on the default export. |
+
+```js
+// migrations/2026_09_01_090000_add_difficulty.js
+export function up(db, ctx) {
+    for (const question of db.questions) {
+        question.data.difficulty ??= 'medium';
+    }
+    ctx.log(`set a difficulty on ${db.questions.length} questions`);
+}
+
+export function down(db) {
+    for (const question of db.questions) {
+        delete question.data.difficulty;
+    }
+}
+```
+
+`db` holds the applet's carried records, by collection name: every `user`, `room` and `applet`
+collection, including ones the outgoing version no longer declares. A record is:
+
+```ts
+interface MigrationRecord {
+    id: string;
+    scope_id: number;          // the room or participant; 0 for applet scope
+    owner_id: number | null;
+    data: object;              // the document, as create() took it
+    created_at: string;
+    updated_at: string;
+}
+```
+
+Mutate it in place, or return `{ collection: records[] }` for the collections you replace. A
+collection you return replaces that collection; one you leave out is kept unchanged, so its records
+must already fit the target version.
+
+```js
+// migrations/2026_10_09_120000_split_archived_ideas.js
+export default {
+    up(db) {
+        return {
+            ideas: db.ideas.filter((idea) => idea.data.status !== 'archived'),
+            archived_ideas: db.ideas.filter((idea) => idea.data.status === 'archived'),
+        };
+    },
+
+    down(db) {
+        return { ideas: [...db.ideas, ...db.archived_ideas] };
+    },
+};
+```
+
+A record that appears under another collection's name moves there, keeping its id. To add a record,
+leave out `id`; it is given a new one. A collection the target version does not declare cannot be
+written to: returning it is ignored.
+
+`ctx` is `{ direction, applet, from, to, scopes, log }`: `'up'` or `'down'`, the applet slug, the
+outgoing and target version strings (`from` is `null` when nothing was current), each collection's
+scope by name, and `log(...)` for lines kept with the snapshot. `console.log`, `info`, `warn` and
+`error` are captured the same way.
+
+**The Rack checks what comes back.** Every record the cutover leaves in place, returned or kept,
+must match the target version's schema and fit its quota. A record cannot change its `scope_id` or `owner_id`, and can move only to
+a collection with the same scope. A new record in a `user` or `room` collection needs the
+`scope_id` of a participant or room that already has records, and its `owner_id` must be `null` or
+someone who already owns one. Records missing from a returned collection are deleted. If any check
+fails, nothing is written and the errors name the collection, the record and the problem. These are
+checks on structure, not on which participant's values end up in which record: migrations see every
+scope's data and are [privileged code](security.md#the-migration-runner).
+
+Migrations run in the browser of whoever promotes, in a sandboxed frame with no network access
+(see [Security](security.md#the-migration-runner)), one after another, 30 seconds each by default.
+A migration that throws, times out, lacks the function it needs, or returns anything other than
+`{ collection: records[] }` stops the run, and nothing is written. If the applet's data changes
+while they run, the promotion is refused with `data_changed` and they run again.
+
+The Rack keeps a ledger of which migrations have run on each applet, with each one's source. Going
+forward, pending `up`s run in name order. Promoting a version that lacks some applied migrations
+runs their `down`s in reverse, from the stored source, so a rollback works even after a later
+package dropped the file. A migration with no `down` cannot be rolled back; the Rack says so, and
+you restore the snapshot taken before it ran.
+
+`attempt` records are never passed in: they stay in the shape their attempt wrote them. Preview
+records are not passed in either.
+
+Migrations are plain functions over plain arrays, so test them like any other: import the module,
+call `up` on a fixture, assert on the result. The mock Rack does not run them.
+
+<a name="snapshots"></a>
+## Snapshots
+
+Before every cutover that changes data, the Rack copies the applet's entire dataset: every record
+in every collection and scope, preview and set-aside ones included, the collection registry, the
+migration ledger and the applet's [role](auth.md#roles) assignments. The copy is written before the
+promotion's transaction opens and marked applied if the cutover commits, so a migration that
+wrecks the data can always be undone.
+
+The transaction then locks the applet's collections, which holds record writes off until it
+commits, and checks the data is still what the cutover was planned and snapshotted from. A write
+that landed in between refuses the promotion with `data_changed`, before anything is deleted, so a
+cutover never removes a record its snapshot does not hold. Likewise, a promotion refuses with
+`version_changed` if another one committed while it was being prepared.
+
+Snapshots are also taken before every restore, so a restore can itself be undone, and on request:
+
+```sh
+php artisan ziprack:db:snapshot my-applet
+php artisan ziprack:db:snapshots my-applet               # list them, with ids
+php artisan ziprack:db:restore my-applet 42 --force
+```
+
+A restore replaces all of the applet's records, its collection registry, its ledger and its role
+assignments with the snapshot's, then makes the version that was current when it was taken current
+again, if that version is still `ready`. The file's sha256 is checked first; a snapshot that does
+not match is not restored.
+
+The file is gzipped NDJSON: a header line (`format: ziprack-snapshot/1`, with the registry, the
+ledger, role assignments and record counts), then one line per record. It is stored at
+`ziprack/snapshots/{slug}/…ndjson.gz` on `ziprack-db.snapshots.disk`, which defaults to
+`ziprack.disk`. **That disk must be persistent** — S3 in production, like packages.
+
+The newest `ziprack-db.snapshots.keep` (10) are kept per applet, and never at the expense of the
+newest one taken before a cutover.
+
 <a name="how-it-is-stored"></a>
 ## How It Is Stored
 
 Worth knowing, because it explains the constraints above.
 
 Every collection's records live in one shared `ziprack_records` table, created by a migration and
-keyed by collection and scope. The document lives in a JSON column; filters and ordering on an
+keyed by collection and scope — the attempt, participant or room id, or `0` for `applet` scope.
+The document lives in a JSON column; filters and ordering on an
 `indexed` path read that path out of the JSON, typed from the declared schema so numbers compare as
 numbers. Every query is narrowed by an index on `(collection_id, scope_id)` first, and the quota caps
 a scope's records, so that read is always over a small, bounded set. The declared schema is still
@@ -221,10 +430,44 @@ with `is_preview` set when it is created. The flag never changes after that, so
 the flag of whoever wrote each card. Applets never see it; it exists for the admin, which leaves
 preview records out unless asked.
 
-**Installing a version never changes the database schema.** Adding a collection or an indexed path
-only writes rows, so the install stays one transaction on every database. Collections that no
-current manifest declares any more keep their records until you run:
+**Installing or promoting a version never changes the database schema.** Adding a collection or an
+indexed path only writes rows, so both stay one transaction on every database. The collection
+registry follows the current version: promotion updates each definition and sets aside the
+collections the new version no longer declares. They keep their records until you run:
 
 ```sh
 php artisan ziprack:db:prune
+php artisan ziprack:db:prune --stranded    # also the rows described below
+```
+
+**Upgrading from a Rack before v1.8.** Applet-scoped records used to belong to the version that
+wrote them, so every upgrade started from an empty dataset. A migration re-keys the current
+version's rows to the applet; earlier versions' rows are left where they were, unreachable. Bring
+one version's rows back into the live dataset, or delete them all:
+
+```sh
+php artisan ziprack:db:recover my-applet 1.2.0 [collection] [--replace] [--force]
+php artisan ziprack:db:prune --stranded
 ```
+
+`recover` adds to the live records (`--replace` deletes those first), reports how many recovered
+records the current schema rejects, and takes a snapshot before it changes anything.
+
+<a name="rack-side"></a>
+## Rack Side
+
+| Command | Does |
+|---|---|
+| `ziprack:db:prune [--stranded] [--force]` | Delete set-aside collections and their records; with `--stranded`, pre-v1.8 applet rows too. |
+| `ziprack:db:recover {slug} {version} [collection] [--replace] [--force]` | Bring an earlier version's stranded applet-scoped records back. |
+| `ziprack:db:snapshot {slug}` · `ziprack:db:snapshots {slug}` | Take a snapshot; list them. |
+| `ziprack:db:restore {slug} {snapshot} [--force]` | Replace the applet's data with a snapshot. |
+
+The admin API routes — the record browser, the cutover plan and check, snapshots — are listed in
+[Reporting](reporting.md#the-admin-api).
+
+A Rack that lets its operators edit records uses `ZipRack\Db\RecordAdmin`: `create()` (into an
+`applet` collection only, since every other scope belongs to a participant, room or attempt),
+`update()`, `setField()` across many records, all or none, and `delete()`. Every write is checked
+against the schema and quota exactly as an applet's write is, and fires the same `RecordChanged`
+event, with a `null` participant, so a live room sees the edit.

package/dist/docs/extending.md

@@ -7,6 +7,8 @@
 - [Message Handlers](#message-handlers)
 - [Launch Payload](#launch-payload)
 - [Install Hooks](#install-hooks)
+- [Promotion Hooks](#promotion-hooks)
+- [Rack Roles](#rack-roles)
 - [Conformance and Status](#conformance-and-status)
 - [The SDK Side](#the-sdk-side)
 
@@ -60,7 +62,8 @@ class SurveyCapability extends AbstractCapability
 | `validateManifest()` | Cross-field checks; add errors to the validator. |
 | `messageHandlers()` | `type => handler class`. |
 | `launchPayload()` | What to merge into `rack:launch` under this capability's id. |
-| `onInstall()` / `onPromote()` / `onRetire()` | Version lifecycle hooks. `onInstall()` runs inside the install transaction, so row changes only. |
+| `onInstall()` / `onPromote()` / `onRetire()` | Version lifecycle hooks. `onInstall()` runs inside the install transaction, after extraction, so row changes only. `onPromote()` runs after the promotion commits. |
+| `preparePromotion()` | Only with `ParticipatesInPromotion`: carry state over when the current version changes, or refuse. See [Promotion Hooks](#promotion-hooks). |
 | `adminRoutes()` | Headless admin routes, registered only when `ziprack/admin` is installed. |
 | `conformanceTests()` | Checks contributed to the conformance suite. |
 | `statusChecks()` | Warnings for `ziprack:status` and `/ziprack/health`. |
@@ -208,15 +211,78 @@ public function onInstall(AppletVersion $version, ?AppletVersion $previous): voi
 }
 ```
 
-`onInstall()` runs inside the install transaction, with the previous current version for comparison
-— which is what lets `db@1` register, update and orphan collections as they change between
-versions. If it throws, the whole installation rolls back and extracted files are removed.
+`onInstall()` runs inside the install transaction, after the package is extracted, with the
+previous current version for comparison. It can read the package's files from
+`$version->storage_path` on `ziprack.disk` — which is how `db@1` checks seed files and migration
+names. Keep it to checking and to rows the live version cannot see: the version is not current yet,
+so anything that changes what running sessions read belongs in [promotion](#promotion-hooks). If it
+throws, the whole installation rolls back and extracted files are removed; throw a
+`PackageInstallException` to give the uploader a message.
 
 Keep it to row changes. `CREATE`, `ALTER` and `DROP` commit any open transaction on MySQL and
 MariaDB, which breaks the install and lets the conformance suite's data escape its rollback. If a
 capability needs tables, ship them as migrations; the conformance suite fails any check that commits
 its transaction.
 
+<a name="promotion-hooks"></a>
+## Promotion Hooks
+
+A capability that holds per-applet state which has to follow the current version — `db@1` and its
+records — implements `ZipRack\Core\Contracts\ParticipatesInPromotion`:
+
+```php
+use ZipRack\Core\Contracts\ParticipatesInPromotion;
+
+class SurveyCapability extends AbstractCapability implements ParticipatesInPromotion
+{
+    public function preparePromotion(AppletVersion $version, ?AppletVersion $outgoing, array $input): ?Closure
+    {
+        $plan = $this->planner->plan($version, $outgoing);
+
+        if ($plan->losesAnswers() && ! ($input['accept_loss'] ?? false)) {
+            throw new PromotionBlockedException('Version '.$version->version.' drops surveys that have answers.');
+        }
+
+        return fn () => $this->planner->apply($plan);   // inside the promotion transaction
+    }
+}
+```
+
+`PromoteVersion::handle($version, $force, $input)` calls it on every capability the *target*
+version declares, whenever the current version actually changes, forwards or back:
+
+1. `preparePromotion()` runs **before** the transaction opens, so slow or file-writing work — `db@1`
+   writes its snapshot here — stays out of it. Throw a `PromotionBlockedException` to refuse.
+2. The closures it returned run **inside** the promotion transaction, before `current_version_id`
+   moves. Row changes only, for the same DDL reason as `onInstall()`.
+3. After the commit, `onPromote()` runs.
+
+`$input` is this capability's share of the promotion input, keyed by its id: the admin API's
+promote body passes `db: {…}` to `db@1`. A refusal that carries something the caller should show
+extends `PromotionBlockedException`; `db@1` throws `ZipRack\Core\Installer\DataCutoverRequired`,
+with a `reason` and the plan as `details()`, which the admin API turns into a `409`.
+
+<a name="rack-roles"></a>
+## Rack Roles
+
+An applet's declared [roles](auth.md#roles) can be assigned to everyone holding one of the Rack's
+own roles. zipRACK asks the Rack what those are through `ZipRack\Core\Contracts\RackRoles`:
+
+```php
+interface RackRoles
+{
+    /** @return array<string, string> key => label */
+    public function all(): array;
+
+    /** @return list<string> keys */
+    public function of(Authenticatable $user): array;
+}
+```
+
+The default, `GateRackRoles`, has one role, `administrator`, from the `ziprack.admin` gate. A Rack
+with authors, facilitators or departments binds its own, the same way it binds
+[`AppletAccess`](reporting.md#who-may-do-what).
+
 <a name="conformance-and-status"></a>
 ## Conformance and Status
 

package/dist/docs/installation.md

@@ -84,6 +84,7 @@ ones you will actually touch.
 | `allowed_extensions` | static list | Anything else rejects the whole upload. |
 | `asset_token_ttl_hours` | `6` | Lifetime of the signed package-asset token. |
 | `session_ttl_hours` | `6` | Lifetime of a launch session. |
+| `session_cookie` | `ziprack_launch` | HttpOnly cookie that binds launch sessions to the browser that launched them. |
 | `csp.img_hosts`, `csp.media_hosts` | `[]` | Per-deployment allowlist. A bare scheme is rejected. |
 | `player.frame_allow` | `[]` | Features added to the applet iframe's `allow` list, e.g. `microphone`. Bare names from a fixed set only. |
 | `media.providers` | `['vimeo','youtube']` | Drives `frame-src` and manifest validation. |
@@ -99,7 +100,7 @@ ones you will actually touch.
 |---|---|
 | `ziprack-auth.php` | `releasable` — the single place a deployment answers "what can applets see about our people"; `claim_map` |
 | `ziprack-attempt.php` | `max_state_bytes` (64 KB), `max_segment_keys` (20) |
-| `ziprack-db.php` | `max_records_per_scope` (5000), `max_record_bytes` (64 KB), `max_indexed_paths` (8), `list_limit` (100) |
+| `ziprack-db.php` | `max_records_per_scope` (5000), `max_record_bytes` (64 KB), `max_indexed_paths` (8), `list_limit` (100), `snapshots.disk` (`ziprack.disk`; must be persistent), `snapshots.keep` (10) |
 | `ziprack-storage.php` | `disk`, `max_bytes_cap` (50 MB), `url_ttl_minutes` (10), `scanner` (`null` \| `clamav`) |
 | `ziprack-ai.php` | `provider`, `models.analysis`, `models.chat`, `allowed_models`, the whole `budget` block |
 | `ziprack-broadcast.php` | `join_prefix`, `facilitator_grace_seconds` (60), `presence_window_seconds` (45), `max_event_bytes` |
@@ -122,11 +123,14 @@ validation. Defaults apply when a manifest declares nothing.
 | `GET /ziprack/f/{file}` | Signed, short-lived download of a stored file (`storage`). |
 | `POST /ziprack/s/{session}/broadcast/auth` | Rack-side WebSocket channel authentication (`broadcast`). |
 | `GET /ziprack/health` | Fleet visibility: format, core version, capabilities, warnings. |
+| `GET /ziprack/migration-runner` | The no-network page a Rack UI frames, sandboxed, to run [data migrations](database.md#data-migrations) at promotion. |
 | `GET /r/{code}` | Join a room by code (`broadcast`). |
 | `*` `/ziprack/admin/*` | The headless admin API (`ziprack/admin`). |
 
-Session routes are deliberately stateless: token in the path, no session cookie, no CSRF, rate
-limited by `ziprack.routes.session_rate_limit`.
+Session routes run without the `web` group: no Laravel session, no CSRF, rate limited by
+`ziprack.routes.session_rate_limit`. Each request needs the token in the path **and** the
+`ziprack_launch` cookie the player set when it issued that token, so a token copied out of the page
+or an access log is refused from any other browser.
 
 <a name="participants-and-guests"></a>
 ## Participants and Guests
@@ -172,8 +176,8 @@ the deployment owns. A Rack can add an approved image host; it cannot reintroduc
 
 | Command | Does |
 |---|---|
-| `ziprack:install {zip} [--applet=] [--activate]` | Install a package as a new version. |
-| `ziprack:promote {slug} {version} [--force]` | Make a version current. `--force` also approves a pending capability review. |
+| `ziprack:install {zip} [--slug=] [--activate] [--force]` | Install a package as a new version; `--slug` installs into that existing applet. `--activate` promotes it, `--force` past a pending capability review. |
+| `ziprack:promote {slug} {version} [--force] [--accept-data-loss] [--keep-invalid]` | Make a version current. `--force` also approves a pending capability review; `--accept-data-loss` confirms a [data cutover](publishing.md#the-data-cutover) that rejects or drops records, and `--keep-invalid` keeps rejected records instead of deleting them. |
 | `ziprack:retire {slug} {version}` | Kill switch: the version can no longer be launched. |
 | `ziprack:status [--json]` | Format, core version, installed capabilities, warnings. |
 | `ziprack:conformance [--json]` | Verify this Rack honours `ziprack/1`. |
@@ -182,5 +186,9 @@ the deployment owns. A Rack can add an approved image host; it cannot reintroduc
 | `ziprack:roster:import {csv}` | Import profile attributes by email. |
 | `ziprack:room:create {slug} [--name=] [--mode=] [--roster=]` | Create a room and print its join code. |
 | `ziprack:rooms:tick` | Vacate and reassign dropped facilitators. **Schedule every minute.** |
-| `ziprack:db:prune [--force]` | Drop tables of collections no current manifest declares. |
+| `ziprack:db:prune [--stranded] [--force]` | Delete collections no current manifest declares, and their records. `--stranded` also deletes applet-scoped rows earlier versions left behind before v1.8. |
+| `ziprack:db:recover {slug} {version} [collection] [--replace] [--force]` | Bring those stranded rows back into the live dataset. |
+| `ziprack:db:snapshot {slug}` · `ziprack:db:snapshots {slug}` | Snapshot an applet's data; list its snapshots. |
+| `ziprack:db:restore {slug} {snapshot} [--force]` | Replace an applet's data with a snapshot and make that version current again. |
+| `ziprack:mcp:token {email} [--name=]` · `ziprack:mcp:revoke {email} [token] [--all]` | Mint and revoke [MCP](mcp.md) tokens. |
 | `ziprack:response-analysis [--applet=] [--force]` | Regenerate admin AI summaries. **Schedule every few hours.** |

package/dist/docs/introduction.md

@@ -40,7 +40,7 @@ The iframe is rendered with:
 
 ```html
 <iframe sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
-        allow="autoplay; fullscreen; picture-in-picture; encrypted-media">
+        allow="autoplay; fullscreen; picture-in-picture; encrypted-media; clipboard-write">
 ```
 
 Note the absence of `allow-same-origin`. The applet document has an **opaque origin**: no cookies,
@@ -72,11 +72,12 @@ ever cross the boundary.
 | **Applet** | One experience or app, identified by an immutable `slug`. Has many versions. | core |
 | **Version** | One uploaded zip. Immutable. Exactly one is current. | core |
 | **Participant** | The person in front of the applet, resolved from the Rack's own users (or a guest cookie). | core |
+| **Role** | A name the participant holds in an applet: built in (`member`, `guest`, `applet-author`, `rack-administrator`) or declared by the manifest and assigned by the Rack. Sent at launch. | core |
 | **Attempt** | One participant's run. Holds `status`, `state`, `segment`. Pinned to the version it started on. | `attempt@1` |
 | **Statement** | Append-only record: actor did verb on activity with result. The audit trail and the uniform export. | `activity@1` |
-| **Record** | A mutable row in a declared collection, at a declared scope. Working state. | `db@1` |
+| **Record** | A mutable row in a declared collection, at a declared scope. Working state that carries over to new versions. | `db@1` |
 | **Stored file** | A participant upload, addressable only once scanned clean. | `storage@1` |
-| **Room** | A shared session: an applet version plus its members, each `participant` or `facilitator`. | `broadcast@1` |
+| **Room** | A shared session: an applet plus its members, each `participant` or `facilitator`. | `broadcast@1` |
 | **Profile attribute** | A Rack-owned fact about the participant, released only if requested and permitted. | `auth@1` |
 
 Statements and records coexist because they answer different questions. A statement is *what
@@ -103,8 +104,9 @@ any call the manifest did not declare.
 Capability versions are independent of the format string and of the Composer package version. See
 [Versioning](versioning.md).
 
-Two things need no capability: [declared media](media.md) (`Rack.media.embedUrl(id)`) and
-`Rack.eject()`, which asks the Rack to leave the applet.
+Three things need no capability: [declared media](media.md) (`Rack.media.embedUrl(id)`),
+[roles](auth.md#roles) (`Rack.auth.hasRole(name)`), and `Rack.eject()`, which asks the Rack to
+leave the applet.
 
 <a name="what-ziprack-is-not"></a>
 ## What zipRACK Is Not

package/dist/docs/manifest.md

@@ -3,6 +3,7 @@
 - [Introduction](#introduction)
 - [Core Fields](#core-fields)
 - [The Requires Block](#the-requires-block)
+- [Roles](#roles)
 - [Capability Sections](#capability-sections)
 - [A Complete Example](#a-complete-example)
 - [Validation Errors](#validation-errors)
@@ -42,6 +43,7 @@ upload meaningful: the manifest is a contract a reviewer can read.
 | `entry` | Optional, default `index.html`. Relative, no `..`, ends in `.html`. |
 | `requires` | Required, even if empty. See below. |
 | `media` | Optional. See [Media](media.md). |
+| `roles` | Optional. The applet's own roles. See [Roles](#roles). |
 
 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.
@@ -64,6 +66,28 @@ declared is a validation error, and so is a section no installed capability owns
 - 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="roles"></a>
+## Roles
+
+```json
+"roles": [
+    { "name": "dungeon-master", "label": "Dungeon Master", "description": "Runs the session." },
+    { "name": "spectator", "grant": "guests" }
+]
+```
+
+A core key, so it needs no capability. Every launch tells the applet which roles the participant
+holds; the Rack decides who holds them. See [Roles](auth.md#roles) for how they resolve.
+
+| Field | Rules |
+|---|---|
+| `name` | Required. Lowercase words joined by hyphens, `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`, max 40, unique. Not one of the built-in roles: `rack-administrator`, `applet-author`, `member`, `guest`. |
+| `label` | Optional, max 60. Shown to whoever assigns the role. Defaults to `name`. |
+| `description` | Optional, max 255. |
+| `grant` | Optional. Who holds it before anyone is assigned: `everyone`, `members`, `guests` or `assigned` (the default — nobody). |
+
+At most 20 roles.
+
 <a name="capability-sections"></a>
 ## Capability Sections
 
@@ -74,7 +98,8 @@ declared is a validation error, and so is a section no installed capability owns
 | `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?}` |
+| `prompts[]` | `ai@1` | `{id, mode, template, vars?, output_schema?, budget?, model?, knowledge?}` |
+| `knowledge[]` | `ai@1` | `{id, source?, label?, fields?}` |
 | `broadcast` | `broadcast@1` | `{channels?, facilitator_events?}` |
 
 Each is specified in full on its capability's page. Two cross-cutting rules are worth stating here:
@@ -111,6 +136,10 @@ An applet exercising every capability at once. Most applets need three or four.
         { "id": "debrief.clip", "provider": "youtube", "key": "dQw4w9WgXcQ" }
     ],
 
+    "roles": [
+        { "name": "judge", "label": "Judge", "description": "Scores the final pitches." }
+    ],
+
     "segments": [
         {
             "key": "track",
@@ -205,6 +234,10 @@ one message. The checks that catch people out:
 | `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). |
+| `Role names are lowercase words joined by hyphens, like "dungeon-master".` | `roles[].name` has capitals, underscores or spaces. |
+| `Role [guest] is one every Rack provides …; it cannot be declared.` | `rack-administrator`, `applet-author`, `member` and `guest` are built in. |
+| `Duplicate role [judge].` | Role names are unique. |
+| `A role's grant is one of everyone, members, guests or assigned.` | Any other `grant`. |
 | `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

@@ -100,13 +100,16 @@ user is no longer an admin.
 | `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 |
+| `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-knowledge`, `search-knowledge` | ai | Knowledge slots, documents, label counts; try retrieval as a prompt would |
+| `get-knowledge-prep-skill` | ai | The agent skill that prepares decks, PDFs and transcripts as tagged JSONL locally, validates them and loads them |
+| `create-knowledge-upload`, `delete-knowledge-document` | ai | Load a document into a slot via a signed URL; delete one. Need `ziprack.ai.load-knowledge` |
 | `list-rooms`, `get-room` | broadcast | |
 
 Capability tools are only present when their capability package is installed.
@@ -118,6 +121,17 @@ Capability tools are only present when their capability package is installed.
 - **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
 
@@ -133,8 +147,9 @@ 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.
+  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>