@ziprack/sdk 0.1.1 → 0.2.0

package/dist/docs/database.md

@@ -0,0 +1,176 @@
+# Database — `db@1`
+
+- [Introduction](#introduction)
+- [Declaring Collections](#declaring-collections)
+- [Scopes](#scopes)
+- [Reading and Writing](#reading-and-writing)
+- [Queries](#queries)
+- [Permissions](#permissions)
+- [Quotas](#quotas)
+- [How It Is Stored](#how-it-is-stored)
+
+<a name="introduction"></a>
+## Introduction
+
+`db@1` gives an applet CRUD over records in collections it declared, at a scope it declared. This is
+working state: ideas on a board, a team roster, a saved layout, a shared catalog.
+
+Records are mutable and arbitrarily shaped, which is exactly why **a JSON Schema is required, not
+optional**. The schema is what the Rack validates writes against, what the admin renders and exports
+records from, and what the installer derives indexes from. Without it, `db@1` would trade the
+uniform export that makes [statements](activity.md) valuable for a pile of untyped JSON.
+
+<a name="declaring-collections"></a>
+## Declaring Collections
+
+```json
+"collections": [
+    {
+        "name": "ideas",
+        "scope": "room",
+        "schema": {
+            "type": "object",
+            "properties": {
+                "title":  { "type": "string", "maxLength": 120 },
+                "body":   { "type": "string", "maxLength": 2000 },
+                "status": { "type": "string", "enum": ["draft", "posted", "picked"] },
+                "votes":  { "type": "integer", "minimum": 0 }
+            },
+            "required": ["title", "status"]
+        },
+        "indexed": ["status", "votes"],
+        "quota": { "max_records": 500, "max_bytes": 16384 },
+        "permissions": { "update": "owner", "delete": "facilitator" }
+    }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `name` | Required. `^[a-z][a-z0-9_]*$`, max 40, unique. |
+| `scope` | Required. `attempt`, `user`, `room` or `applet`. |
+| `schema` | Required. JSON Schema, `type: "object"`. |
+| `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`. |
+
+<a name="scopes"></a>
+## Scopes
+
+The scope answers, at declaration time, the otherwise ambiguous question of who shares a record and
+what happens to it when an attempt ends.
+
+| Scope | Shared by | Lifetime | Requires |
+|---|---|---|---|
+| `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 | — |
+
+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.
+
+<a name="reading-and-writing"></a>
+## Reading and Writing
+
+```ts
+const ideas = Rack.db.collection<Idea>('ideas');
+
+const created = await ideas.create({ title, status: 'draft', votes: 0 });
+const idea    = await ideas.get(created.data.record.id);
+
+await ideas.update(id, { status: 'posted' });          // merges by default
+await ideas.update(id, next, { merge: false });        // replaces the document
+await ideas.delete(id);
+```
+
+Every call resolves to an `AckResult`. A record comes back as:
+
+```ts
+interface RecordRow<T> {
+    id: string;            // uuid
+    data: T;
+    owner_id: number;      // the participant who created it
+    created_at: string;
+    updated_at: string;
+}
+```
+
+Writes are validated against the declared schema **after** the merge, so a partial update that would
+produce an invalid document is refused with `validation` and `details` naming the offending path.
+
+<a name="queries"></a>
+## Queries
+
+```ts
+const { data } = await ideas.list({
+    where: [['status', '=', 'posted'], ['votes', '>=', 3]],
+    orderBy: 'votes',
+    direction: 'desc',
+    limit: 50,
+});
+
+data.records;      // RecordRow<Idea>[]
+data.nextCursor;   // pass back as { cursor } for the next page
+```
+
+```ts
+const { data } = await ideas.count({ where: [['status', '=', 'draft']] });
+```
+
+Operators: `=`, `!=`, `<`, `<=`, `>`, `>=`, `in`.
+
+**Filtering and ordering work only on `indexed` paths.** That is not a limitation the SDK could hide
+— it reflects how the data is actually stored (see below). Decide your query paths when you declare
+the collection, and if you find yourself wanting a ninth index, the shape is probably wrong.
+
+The page size caps at 100 (`ziprack-db.list_limit`). Lists are always scoped: you cannot read
+another room's records, another participant's `user` records, or another attempt's records, because
+the scope id is resolved from the session, never from your payload.
+
+<a name="permissions"></a>
+## Permissions
+
+Reads are scoped; writes are also owned. By default only the creator may update or delete a record.
+
+| Value | Who may |
+|---|---|
+| `owner` | The participant who created it. The default. |
+| `members` | Anyone who can see it — everyone in the room, for a `room` collection. |
+| `facilitator` | The owner, plus whoever currently holds the facilitator role. |
+
+Moderation of a shared board is `"delete": "facilitator"`. A genuinely collaborative document is
+`"update": "members"`. Anything stricter than `owner` does not exist, because scope already decides
+visibility.
+
+<a name="quotas"></a>
+## Quotas
+
+Declared quotas are enforced server-side regardless of what the applet believes:
+
+| Limit | Default | Hard ceiling |
+|---|---|---|
+| `max_records` per scope | 500 | 5000 (`ziprack-db.max_records_per_scope`) |
+| `max_bytes` per record | 16 KB | 64 KB (`ziprack-db.max_record_bytes`) |
+
+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="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:
+
+```sh
+php artisan ziprack:db:prune
+```

package/dist/docs/extending.md

@@ -0,0 +1,256 @@
+# Writing a Capability
+
+- [When to Add One](#when-to-add-one)
+- [The Capability Interface](#the-capability-interface)
+- [Registering It](#registering-it)
+- [Manifest Rules](#manifest-rules)
+- [Message Handlers](#message-handlers)
+- [Launch Payload](#launch-payload)
+- [Install Hooks](#install-hooks)
+- [Conformance and Status](#conformance-and-status)
+- [The SDK Side](#the-sdk-side)
+
+<a name="when-to-add-one"></a>
+## When to Add One
+
+A capability is one applet-facing surface: a set of message types, a manifest section, a slice of the
+launch payload, and the server-side service behind them. `ziprack/db` and `ziprack/ai` are both
+exactly this shape.
+
+Before adding one, apply the framework's own test:
+
+> If a capability requires an applet author to reason about device identity, transport, or
+> deployment topology, it does not belong in zipRACK.
+
+And check it is not already expressible. A great many ideas reduce to `db@1` with a different
+collection, or to `broadcast@1` with a different event name. The value of seven surfaces is that
+there are seven.
+
+<a name="the-capability-interface"></a>
+## The Capability Interface
+
+One package, one `Capability`. Extend `AbstractCapability` and override only what you need — every
+method has a sensible no-op default.
+
+```php
+namespace ZipRack\Survey;
+
+use ZipRack\Core\Capabilities\AbstractCapability;
+
+class SurveyCapability extends AbstractCapability
+{
+    public function id(): string
+    {
+        return 'survey';                    // ^[a-z][a-z0-9_]*$
+    }
+
+    public function versions(): array
+    {
+        return [1];                         // may implement several at once: [1, 2]
+    }
+}
+```
+
+| Method | Purpose |
+|---|---|
+| `id()` | The name in manifests and message types: `survey`, `survey:submit`. |
+| `versions()` | Capability versions this package implements. Metadata, independent of package semver. |
+| `manifestSections()` | Top-level manifest keys this capability owns. |
+| `manifestRules()` | Laravel rules for those sections. |
+| `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. |
+| `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`. |
+
+<a name="registering-it"></a>
+## Registering It
+
+```php
+class SurveyServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->mergeConfigFrom(__DIR__.'/../config/ziprack-survey.php', 'ziprack-survey');
+    }
+
+    public function boot(): void
+    {
+        $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
+
+        ZipRack::register($this->app->make(SurveyCapability::class));
+
+        if ($this->app->runningInConsole()) {
+            $this->publishes([
+                __DIR__.'/../config/ziprack-survey.php' => config_path('ziprack-survey.php'),
+            ], 'ziprack-config');
+        }
+    }
+}
+```
+
+Migrations load; they are never published. Config publishes; it is meant to diverge. That split is
+[not negotiable](installation.md#publishable-and-non-publishable) — it is what keeps the fleet
+uniform.
+
+The registry is built from installed providers, so installing the package *is* declaring the
+capability. There is no separate list to fall out of sync.
+
+<a name="manifest-rules"></a>
+## Manifest Rules
+
+```php
+public function manifestSections(): array
+{
+    return ['surveys'];
+}
+
+public function manifestRules(): array
+{
+    return [
+        'surveys' => ['required', 'array', 'min:1'],
+        'surveys.*.id' => ['required', 'string', 'max:100', 'regex:/^[a-z][a-z0-9_.-]*$/'],
+        'surveys.*.questions' => ['required', 'array', 'min:1'],
+    ];
+}
+
+public function validateManifest(array $data, Validator $validator): void
+{
+    $ids = [];
+    foreach ($data['surveys'] ?? [] as $index => $survey) {
+        if (isset($ids[$survey['id'] ?? null])) {
+            $validator->errors()->add("surveys.{$index}.id", "Duplicate survey id [{$survey['id']}].");
+        }
+        $ids[$survey['id'] ?? ''] = true;
+    }
+}
+```
+
+The core validator enforces the section/capability relationship for you: a manifest containing
+`surveys` without declaring `survey@1` fails, and so does one declaring a section no installed
+capability owns.
+
+Three conventions worth keeping: uniqueness errors name the duplicate, a section that depends on
+another capability says so explicitly (`"A room-scoped X requires the [broadcast] capability"`), and
+anything with a quota takes its ceiling from config rather than hard-coding it.
+
+<a name="message-handlers"></a>
+## Message Handlers
+
+```php
+public function messageHandlers(): array
+{
+    return ['survey:submit' => SubmitSurvey::class];
+}
+```
+
+```php
+class SubmitSurvey implements MessageHandler
+{
+    public function rules(MessageContext $context): array
+    {
+        return [
+            'survey' => ['required', 'string', 'max:100'],
+            'answers' => ['required', 'array'],
+        ];
+    }
+
+    public function handle(MessageContext $context, array $payload): Ack
+    {
+        $survey = SurveyManifest::of($context->manifest())->find($payload['survey'])
+            ?? throw MessageException::notFound("Survey [{$payload['survey']}] is not declared.");
+
+        // $context->participant, $context->version, $context->attribute('attempt_id'|'room_id')
+
+        return Ack::ok(['id' => $id]);
+    }
+}
+```
+
+The dispatcher has already checked that the manifest declares your capability at a version this Rack
+implements, and has already validated the payload against `rules()` — a handler never sees an
+invalid payload or an undeclared call.
+
+Throw `MessageException::forbidden() / notFound() / quota() / completed() / conflict()` for expected
+failures; anything else is reported and acks `persist_failed`. Never leak an internal message into
+an ack.
+
+Message types must match `^[a-z][a-z0-9_]*:[a-z][a-z0-9_.]*$` and are namespaced by your capability
+id. Everything the applet may influence about scope comes from `MessageContext`, never from the
+payload — that is how a room-scoped write cannot address another room.
+
+<a name="launch-payload"></a>
+## Launch Payload
+
+```php
+public function launchPayload(LaunchContext $context): ?array
+{
+    return ['surveys' => SurveyManifest::of($context->manifest())->summaries()];
+}
+```
+
+Merged under your capability id, so the applet reads `launch.survey.surveys`. Return `null` to
+contribute nothing. Use `$context->remember(key, fn)` to share a resolved model with your message
+handlers rather than querying twice.
+
+Send what the applet needs to render its first frame, and nothing more. Launch data crosses into an
+untrusted frame: it is the one place where over-sharing is silent.
+
+<a name="install-hooks"></a>
+## Install Hooks
+
+```php
+public function onInstall(AppletVersion $version, ?AppletVersion $previous): void
+{
+    $this->installer->install($version, $previous);   // schema-bearing work belongs here
+}
+```
+
+`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
+versions. If it throws, the whole installation rolls back and extracted files are removed.
+
+<a name="conformance-and-status"></a>
+## Conformance and Status
+
+```php
+public function conformanceTests(): array
+{
+    return [SurveyAnswersAreImmutable::class];
+}
+
+public function statusChecks(): array
+{
+    return $this->configured() ? [] : [[
+        'level' => 'warning',
+        'message' => 'survey@1 has no store configured; submissions are discarded.',
+    ]];
+}
+```
+
+A conformance check is a class with `name()` and `run(Fixture $fixture)`, failing by throwing. Write
+one per invariant the capability promises an applet author — not one per method.
+
+<a name="the-sdk-side"></a>
+## The SDK Side
+
+A capability is only half-built until `@ziprack/sdk` can call it. Add a module under
+`sdk/src/{capability}/`, take a `Link` in the constructor, and expose it on `RackClient`:
+
+```ts
+export class SurveyApi {
+    public constructor(private readonly link: Link) {}
+
+    public submit(survey: string, answers: JsonObject): Promise<AckResult<{ id: string }>> {
+        return this.link.send('survey:submit', { survey, answers });
+    }
+}
+```
+
+Then implement it in `MockRack` as well. **A capability with no mock is a capability applet authors
+cannot develop against**, and standalone development is the property the framework most depends on —
+losing it costs more than the capability is worth.
+
+Bump the capability version only when this surface changes. Refactors below it are free.

package/dist/docs/installation.md

@@ -0,0 +1,185 @@
+# Installation
+
+- [Composing a Rack](#composing-a-rack)
+- [The Deployment Skeleton](#the-deployment-skeleton)
+- [Configuration](#configuration)
+- [Routes](#routes)
+- [Participants and Guests](#participants-and-guests)
+- [Publishable and Non-Publishable](#publishable-and-non-publishable)
+- [Console Commands](#console-commands)
+
+<a name="composing-a-rack"></a>
+## Composing a Rack
+
+**A deployment's `composer.json` is its capability declaration.** The capability registry is built
+by iterating installed service providers, so it cannot disagree with what is actually installed.
+
+```json
+"require": {
+    "ziprack/core": "^1.0",
+    "ziprack/auth": "^1.0",
+    "ziprack/attempt": "^1.0",
+    "ziprack/activity": "^1.0",
+    "ziprack/db": "^1.0",
+    "ziprack/ai": "^1.0",
+    "ziprack/broadcast": "^1.0",
+    "ziprack/storage": "^1.0",
+    "ziprack/admin": "^1.0"
+},
+"require-dev": {
+    "ziprack/conformance": "^1.0"
+}
+```
+
+Remove `ziprack/db` and an applet requesting `db@1` is refused at upload with a message naming what
+this Rack does implement. Drop `ziprack/broadcast` and there is no Reverb dependency, no WebSocket
+port and no room tables — a smaller attack surface, not just a smaller install.
+
+`ziprack/core` is mandatory; every capability package requires it. `ziprack/admin` is optional and
+headless: it ships JSON endpoints and export services, never pages. `ziprack/conformance` is a dev
+dependency that belongs in CI.
+
+Packages resolve from private VCS repositories:
+
+```json
+"repositories": [
+    { "type": "vcs", "url": "git@github.com:Collective-Next/ziprack-core.git" },
+    { "type": "vcs", "url": "git@github.com:Collective-Next/ziprack-attempt.git" }
+]
+```
+
+Inside the monorepo they resolve from `../packages/*` path repositories instead, so changes are
+testable without tagging.
+
+<a name="the-deployment-skeleton"></a>
+## The Deployment Skeleton
+
+`skeleton/` is a Laravel application template cloned once per engagement and then owned by that
+engagement. It holds what is *meant* to diverge: branding, environment, the deployment pipeline, the
+admin UI, and the capability list.
+
+```sh
+cp .env.example .env && php artisan key:generate
+php artisan migrate --seed
+npm install && npm run build
+php artisan ziprack:install path/to/applet-1.0.0.zip --activate
+php artisan ziprack:conformance
+```
+
+Migrations ship inside the packages and load through `loadMigrationsFrom()`; they are never
+published, because schema must be identical on every Rack.
+
+<a name="configuration"></a>
+## Configuration
+
+Each package publishes one config file. The defaults are production-safe; the values below are the
+ones you will actually touch.
+
+### `config/ziprack.php`
+
+| Key | Default | Notes |
+|---|---|---|
+| `disk` | `local` | Where packages are extracted. Must not be publicly served. |
+| `max_upload_mb` | `50` | Package size cap. |
+| `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. |
+| `csp.img_hosts`, `csp.media_hosts` | `[]` | Per-deployment allowlist. A bare scheme is rejected. |
+| `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. |
+| `publishing.osv_lookup` | `true` | Batch the SBOM's purls against OSV.dev after install. |
+| `audit.enabled` | `true` | Per-applet audit log of capability calls. |
+| `health_token` | `null` | Bearer token for `/ziprack/health`. |
+
+### Capability configs
+
+| File | Notable keys |
+|---|---|
+| `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-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`) |
+
+Ceilings in these files are **hard**: a manifest asking for a larger quota or budget fails
+validation. Defaults apply when a manifest declares nothing.
+
+<a name="routes"></a>
+## Routes
+
+| Route | Purpose |
+|---|---|
+| `GET /a/{applet}` | The player: chrome plus the sandboxed iframe. Middleware from `ziprack.routes.middleware.player`, default `['web','auth']`. |
+| `GET /ziprack/pkg/{token}/{path}` | Package assets, streamed with the contract's headers and CSP. Token-authenticated, stateless. |
+| `GET /ziprack/assets/{file}` | The shell bundles (`shell.js`, `shell-broadcast.js`, `sdk.js`). |
+| `POST /ziprack/s/{session}/messages` | The one door every capability call goes through. Batched, max 50 per request. |
+| `GET /ziprack/s/{session}/stream/{requestId}` | Server-sent events for streamed acks (`ai:chat`). |
+| `POST /ziprack/s/{session}/files` | Multipart upload target for `storage:put` (`storage`). |
+| `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 /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`.
+
+<a name="participants-and-guests"></a>
+## Participants and Guests
+
+By default the player sits behind `auth` and each authenticated user maps to a `Participant`.
+Light group activities often have no identity source, so a Rack may enable guests:
+
+```
+ZIPRACK_GUESTS=true
+```
+
+and drop `auth` from the player middleware. An unauthenticated visitor then gets a cookie-keyed
+participant, which is enough for `opt_in` and `first_in` rooms. `roster` rooms and any applet
+declaring `auth@1` still need real users.
+
+To resolve participants differently — SSO subject, an LTI launch, an external roster — bind
+`ZipRack\Core\Contracts\ParticipantResolver` in a service provider.
+
+<a name="publishable-and-non-publishable"></a>
+## Publishable and Non-Publishable
+
+Every publishable file is a place the fleet can drift, so the split is deliberate.
+
+**Publishable — meant to diverge:** config files, the player chrome and holding views
+(`resources/views/vendor/ziprack`), translations, notification templates.
+
+**Never publishable — these are the contract:**
+
+| Artifact | Why |
+|---|---|
+| Migrations | Schema must be identical everywhere. |
+| `ManifestValidator` | An applet must validate the same way on every Rack, or portability is fiction. |
+| `PackageInstaller` file rules | Traversal, symlink and extension checks are security code. |
+| Bridge and envelope handling | The `event.source` trust check is the whole boundary. |
+| `ContentSecurityPolicy` | Directives are fixed; only the host allowlist is configurable. |
+| `CapabilityRegistry` and dispatch | The runtime rejection of undeclared calls. |
+
+Where deployments genuinely need to vary, the variation is configuration the core reads — not code
+the deployment owns. A Rack can add an approved image host; it cannot reintroduce `https:`.
+
+<a name="console-commands"></a>
+## Console Commands
+
+| 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: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`. |
+| `ziprack:conformance:install` | Publish a test that runs the suite inside the deployment's own Pest run. |
+| `ziprack:profile:set {email} {key} {value}` | Set one profile attribute. |
+| `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:response-analysis [--applet=] [--force]` | Regenerate admin AI summaries. **Schedule every few hours.** |