@ziprack/sdk 0.2.0 → 0.2.1

package/dist/db/index.d.ts

@@ -14,7 +14,8 @@ export interface ListQuery {
 export interface RecordRow<T extends object = JsonObject> {
     id: string;
     data: T;
-    owner_id: number;
+    /** The participant who created it; null for records seeded from the package. */
+    owner_id: number | null;
     created_at: string;
     updated_at: string;
 }

package/dist/docs/README.md

@@ -39,11 +39,15 @@ These docs cover both halves. If you are building an applet, start with
 - [Security](security.md) — the sandbox, the CSP, the threats it does not cover
 - [Publishing](publishing.md) — install, capability diff, review queue, promotion, kill switch
 - [Reporting](reporting.md) — the admin API, CSV export, metrics
+- [Who may do what](reporting.md#who-may-do-what) — `AppletAccess`, abilities, applet owners
 - [Conformance](conformance.md) — proving a deployment is still a Rack
+- [The Rack MCP Server](mcp.md) — agents that read applet data and upload packages, over OAuth or minted tokens
 
 ## Extending
 
 - [Writing a Capability](extending.md) — the `Capability` interface, end to end
+- [Contributing MCP tools](mcp.md#contributing-tools) — `ProvidesMcpTools`
+- [Adding MCP tools from the Rack](mcp.md#adding-tools-from-the-rack) — `ToolRegistry`
 
 ---
 

package/dist/docs/activity.md

@@ -73,6 +73,10 @@ reads** — and fills `activity.type` from your manifest declaration. `progress(
 Verbs match `^[a-z][a-z0-9_.:-]*$`. `occurred_at` defaults to now, in ISO 8601; pass it yourself only
 when replaying something that genuinely happened earlier.
 
+A statement emitted while staff [preview](attempts.md#preview-runs) the applet is stored with
+`is_preview` set, with or without an attempt, so an audit trail can leave it out. The applet does
+nothing different.
+
 Read your own declarations when you need them:
 
 ```ts

package/dist/docs/attempts.md

@@ -110,7 +110,7 @@ GET /a/{slug}?preview=1      resume my open preview run
 GET /a/{slug}?preview=new    start a fresh one
 ```
 
-Both require the `ziprack.admin` ability. For anyone else the parameter is **ignored rather than
+Both require `ziprack.manage-applet` for the applet. For anyone else the parameter is **ignored rather than
 refused**, so a link pasted into a chat never dead-ends a participant on an error page.
 
 A preview run is a real attempt — same pinning, same statements, same records, same AI budget — but
@@ -133,8 +133,11 @@ The live attempt keeps `attempt_number` 1 for the lifetime of the applet; previe
 numbers above it. Starting a fresh preview never touches the live run, so you can hammer the preview
 button on an applet you have already completed for real without disturbing your own record of it.
 
-What preview does **not** do is partition capability storage. Statements and records belong to their
-attempt and follow it, but per-applet aggregates — [`ai@1`](ai.md) spend, the
+The preview comes from the launch, not the attempt, so it reaches capabilities that have no attempt
+at all. Statements and `db@1` records written during a preview carry their own `is_preview`, and the
+record browser hides them by default too (see [Reporting](reporting.md#preview-runs)).
+
+What preview does **not** do is partition every capability's storage. Per-applet aggregates — [`ai@1`](ai.md) spend, the
 [`storage@1`](storage.md) gallery — count preview activity like any other. Budget accordingly on a
 Rack where people preview a lot.
 

package/dist/docs/database.md

@@ -7,6 +7,7 @@
 - [Queries](#queries)
 - [Permissions](#permissions)
 - [Quotas](#quotas)
+- [Seeding](#seeding)
 - [How It Is Stored](#how-it-is-stored)
 
 <a name="introduction"></a>
@@ -53,6 +54,7 @@ uniform export that makes [statements](activity.md) valuable for a pile of untyp
 | `indexed` | Optional, max 8 paths. Each must be a scalar property declared in the schema. Dotted paths allowed. |
 | `quota` | Optional. `max_records`, `max_bytes` — ceilings you may lower, never raise. |
 | `permissions` | Optional. `update` and `delete`: `owner` (default), `members`, `facilitator`. |
+| `seed` | Optional, `applet` scope only. Path to a JSON file in the package. See [Seeding](#seeding). |
 
 <a name="scopes"></a>
 ## Scopes
@@ -90,7 +92,7 @@ Every call resolves to an `AckResult`. A record comes back as:
 interface RecordRow<T> {
     id: string;            // uuid
     data: T;
-    owner_id: number;      // the participant who created it
+    owner_id: number | null; // the participant who created it; null when seeded
     created_at: string;
     updated_at: string;
 }
@@ -156,20 +158,72 @@ Declared quotas are enforced server-side regardless of what the applet believes:
 Over quota, `create()` returns `quota_exceeded`. Handle it — a shared board hitting its cap during a
 live session is a real event, not a theoretical one.
 
+<a name="seeding"></a>
+## Seeding
+
+An `applet` collection can ship its initial records in the package. This is how you bring along a
+catalog, a question bank or any other data an existing app kept in a JSON file:
+
+```json
+{
+    "name": "products",
+    "scope": "applet",
+    "schema": { "type": "object", "properties": { "sku": { "type": "string" }, "title": { "type": "string" } } },
+    "indexed": ["sku"],
+    "seed": "data/products.json"
+}
+```
+
+The seed file is a JSON array of records, each one a document exactly as `create()` would take it:
+
+```json
+[
+    { "sku": "A-100", "title": "Starter kit" },
+    { "sku": "A-200", "title": "Refill pack" }
+]
+```
+
+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
+`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.
+
+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.
+- **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.
+- **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="how-it-is-stored"></a>
 ## How It Is Stored
 
 Worth knowing, because it explains the constraints above.
 
-Each collection gets its own MySQL table, created when the applet version installs. The document
-lives in a JSON column; every path in `indexed` becomes a **generated column with an index on it**.
-The declared schema is therefore also the index plan, which is what makes MySQL a good fit here
-rather than a compromise — the queryable paths are known at install time, so there is no need for
-containment queries over undeclared keys.
-
-**Installing a version is a schema-bearing operation.** Adding a collection creates a table; adding
-an indexed path adds a generated column; removing one drops it. Collections that no current manifest
-declares any more are left in place until you run:
+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
+`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
+the query plan: only `indexed` paths can be filtered or sorted, so there is no need for containment
+queries over undeclared keys.
+
+A record written while staff [preview](attempts.md#preview-runs) the applet is stored like any other,
+with `is_preview` set when it is created. The flag never changes after that, so a shared board keeps
+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:
 
 ```sh
 php artisan ziprack:db:prune

package/dist/docs/extending.md

@@ -60,7 +60,7 @@ 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. |
+| `onInstall()` / `onPromote()` / `onRetire()` | Version lifecycle hooks. `onInstall()` runs inside the install transaction, so row changes only. |
 | `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`. |
@@ -204,14 +204,19 @@ untrusted frame: it is the one place where over-sharing is silent.
 ```php
 public function onInstall(AppletVersion $version, ?AppletVersion $previous): void
 {
-    $this->installer->install($version, $previous);   // schema-bearing work belongs here
+    $this->installer->install($version, $previous);   // row changes only; no DDL
 }
 ```
 
 `onInstall()` runs inside the install transaction, with the previous current version for comparison
-— which is what lets `db@1` create, alter and drop generated columns as collections change between
+— 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.
 
+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="conformance-and-status"></a>
 ## Conformance and Status
 

package/dist/docs/installation.md

@@ -85,6 +85,7 @@ ones you will actually touch.
 | `asset_token_ttl_hours` | `6` | Lifetime of the signed package-asset token. |
 | `session_ttl_hours` | `6` | Lifetime of a launch session. |
 | `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. |
 | `publishing.require_sbom` | `true` | Refuse packages with no SBOM. |
 | `publishing.require_review_for_new_capabilities` | `true` | Block promotion until a widened `requires` is approved. |
@@ -102,7 +103,7 @@ ones you will actually touch.
 | `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` |
-| `ziprack-admin.php` | `prefix` (`ziprack/admin`), `middleware` (`web`, `auth`, `can:ziprack.admin`) |
+| `ziprack-admin.php` | `prefix` (`ziprack/admin`), `middleware` (`web`, `auth`, `can:ziprack.use-admin`) |
 
 Ceilings in these files are **hard**: a manifest asking for a larger quota or budget fails
 validation. Defaults apply when a manifest declares nothing.

package/dist/docs/manifest.md

@@ -72,7 +72,7 @@ declared is a validation error, and so is a section no installed capability owns
 | `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?}` |
+| `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?}` |
@@ -204,6 +204,7 @@ one message. The checks that catch people out:
 | `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/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)
@@ -46,7 +47,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 |
 |---|---|
@@ -72,6 +74,43 @@ Capability packages add their own, and only when installed:
 | `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; 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 +126,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
 

package/dist/docs/security.md

@@ -23,7 +23,7 @@ lean on the second where the first is what is needed.
 
 ```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"
         src="/ziprack/pkg/{token}/index.html"></iframe>
 ```
 
@@ -39,6 +39,26 @@ Communication is `postMessage` only, and the host honours a message solely when
 the applet's `contentWindow`. Origin is never compared, because an opaque origin makes comparison
 meaningless — a detail worth understanding before anyone "fixes" it.
 
+### Extending the frame's permissions
+
+The `allow` list above is the fixed base. A deployment may add features an applet needs, such as
+`microphone` for one that records audio:
+
+```php
+'player' => [
+    'frame_allow' => ['microphone'],   // ZIPRACK_PLAYER_FRAME_ALLOW=microphone
+],
+```
+
+Only bare feature names from `FramePermissions::GRANTABLE` are accepted: `microphone`, `camera`,
+`display-capture`, `geolocation`, `clipboard-read`, `screen-wake-lock`, `web-share` and `midi`. An
+origin list (`*`, `microphone *`, `microphone 'self'`) or an unknown name is dropped, so every
+feature keeps the default `'src'` allowlist and reaches the applet's frame alone.
+`FramePermissions::violations()` reports refused entries, and `ziprack:status` fails on them.
+
+The setting is Rack-wide: every applet on the Rack is offered the feature, and the browser still
+prompts the participant before granting it.
+
 <a name="the-content-security-policy"></a>
 ## The Content Security Policy
 
@@ -47,16 +67,22 @@ add approved hosts, never a bare scheme.
 
 | Directive | Value |
 |---|---|
-| `default-src` | `'self'` |
-| `script-src` | `'self' 'unsafe-inline' 'unsafe-eval' blob:` |
-| `style-src` | `'self' 'unsafe-inline'` + configured font CDNs |
-| `font-src` | `'self' data:` + configured font CDNs |
-| `img-src` | `'self' data: blob:` + deployment allowlist |
-| `media-src` | `'self' blob:` + deployment allowlist |
-| `connect-src` | `'self'` |
+| `default-src` | `'self'` + Rack origin |
+| `script-src` | `'self'` + Rack origin, `'unsafe-inline' 'unsafe-eval' blob:` |
+| `style-src` | `'self'` + Rack origin, `'unsafe-inline'` + configured font CDNs |
+| `font-src` | `'self'` + Rack origin, `data:` + configured font CDNs |
+| `img-src` | `'self'` + Rack origin, `data: blob:` + deployment allowlist |
+| `media-src` | `'self'` + Rack origin, `blob:` + deployment allowlist |
+| `connect-src` | `'self'` + Rack origin |
 | `frame-src` | the allowlisted media providers' player hosts, else `'none'` |
 | `frame-ancestors`, `base-uri`, `form-action` | `'self'` |
 
+**Rack origin** is the exact origin of `app.url` (scheme, host, non-default port), e.g.
+`https://rack.example.com`. It is listed because the applet frame's origin is opaque: Chrome resolves
+`'self'` against the URL the document came from, but Safari resolves it against the opaque origin and
+matches nothing, blocking the applet's own bundle. `APP_URL` must therefore be the origin the Rack is
+actually served from.
+
 **Why `img-src` matters more than it looks.** A hostile applet can exfiltrate anything it holds with
 a single tag:
 

package/dist/docs/ziprack-1-authoring.md

@@ -154,10 +154,10 @@ Rack all fail. `window.open` works. The entry document's CSP is:
 
 | Directive | Allowed |
 |---|---|
-| `script-src` | `'self' 'unsafe-inline' 'unsafe-eval' blob:` — bundle every dependency |
+| `script-src` | `'self'` + the Rack's origin, `'unsafe-inline' 'unsafe-eval' blob:` — bundle every dependency |
 | `style-src`, `font-src` | `'self'` + Bunny/Google fonts |
 | `img-src`, `media-src` | `'self' data: blob:` + the deployment's allowlist. **Not `https:`.** |
-| `connect-src` | `'self'` — no external APIs, no analytics |
+| `connect-src` | `'self'` + the Rack's origin — no external APIs, no analytics |
 | `frame-src` | Vimeo and YouTube players, via declared `media` only |
 
 Ship your images and media inside the zip. A persistent Rack bar sits above the frame and cannot be