# Sensory Experience agent manual

Version 1.0.0. The application is a browser-based event workspace with a shared, authenticated API. The Administrator prepares bookings, inventory, accounting and staff access. Hosts run assigned events. Participants report their own sensory experience.

## Discover and authenticate

Read `/api/openapi` for the OpenAPI 3.1 contract. Connect a compatible MCP client to `/api/mcp` using Streamable HTTP and a bearer credential. The server supports protocol versions 2025-03-26 and 2025-06-18; it is stateless and does not provide an SSE stream. Read `/api/auth/status` to discover your role, environment and whether email or Google sign-in is configured.

An administrator creates each agent in Staff & agents, selects its role and event assignments, then issues an individual credential. Send `Authorization: Bearer <credential>`. Credentials expire after 90 days and can be rotated or revoked immediately. Do not borrow a person's session or pass credentials in URLs. Protect participant recovery links as credentials too. Browser sign-in uses single-use, 15-minute links and HttpOnly sessions. Optional Google sign-in only admits already-invited staff.

## Permissions

- Administrators manage all events, templates, stock and the manual accounting ledger.
- Hosts access only assigned events, including operational edits, paper answers, corrections, templates, reveals and presentations. Accounting and unrelated customer records are excluded from their studio response.
- Participant agents are assigned to one existing participant in one event. Use `/api/event` with the agent credential; the server resolves the assigned workbook. Do not send another participant's token or create an artificial person in a live event.
- Human administrators manage staff and credentials. Agents must not create their own access grants. Ask a human to perform the reviewed change through Staff & agents.

## Environment boundaries

Read `mode` before any operation. Practice and live run on separate Workers with different databases, buckets, staff sessions and credentials. Simulated answers are explicitly labeled and are permitted only in practice. A live event may contain agent-assisted responses only when they reflect what a real person reported. Never invent tasting answers for a real event.

A human administrator may export `/api/templates` and deliberately import its content in the other environment. Exported content omits answers, financial records, quantities, credentials and photos. Imported stock starts at zero. Upload and verify package photographs in the destination environment before using the panel live.

## Administrator workflow

1. Read `/api/studio` for current records and IDs.
2. Create an event with `newEvent`; edit details using `saveEvent` and the complete event data returned by the server. Prices are manual. Deposit is 25% with a $150 minimum, capped at the event price; the balance is due 10 days before the event.
3. Maintain actual inventory with `stock`, add or edit panel content with `savePanel`, and reserve stock by confirming a booking. Event panel changes and shared template changes are distinct operations (`template: true` changes a template).
4. Upload and accept readable package images; attach agreements using `document`. Verify ingredient and allergen text against the purchased products.
5. Record completed income, expenses, refunds or credits using `entry`. These are ledger records, not transfers of money. No payment processor is enabled.
6. Complete preparation checks with `check`, then mark the event `ready`. Live panels cannot open before readiness is complete.
7. Assign hosts through a human administrator in Staff & agents.

## Host workflow

Open panels in workbook order using `panel` with `index` and `command: open`. Use `closePrevious: true` to close the previous panel. `close` locks answers; `reopen` permits further answers. `reveal` reveals product identities and locks answers. An authorized host or host agent may reveal without an additional human approval. Presentation changes use `screen`, with a kind of `welcome`, `panel`, `reveal` or `results`, a panel index, a result metric, message and timer timestamp.

`end` makes the workbook read-only and begins 30-day participant review access. Retain the underlying records. `paperJoin` and `paperAnswer` allow paper workbooks to be entered afterward. `usage` records used, wasted and returned quantities; the quantities must add up to the packed amount. Reusable equipment is returned; lost or damaged units are waste.

Use `correctAnswer` for a real participant's correction, with `participantId`, `itemId`, `answer`, `reason` and, for an agent, `requestedBy` identifying the authorized human host. The audit record preserves the old and new answer and identifies both the executing agent and requesting host. Descriptor arrays replace the descriptor selection: to add “Savory,” read the current answer, append it without duplication and submit the complete revised array. Ask for clarification if this exceeds three descriptors. Never silently drop another descriptor.

## Participant workflow

Human guests join using the event QR link and a name or nickname; email is optional. The response contains a private recovery token. Send it as `X-Participant-Token` to read or update the workbook. Participant agents use their assigned bearer identity instead.

Wait until the host opens a panel. Answer items in order, using `answer` with `itemId` and an answer object. Liking and intensity are optional integer scores from 1 to 7. Choose up to three descriptors; the shared library is suggested vocabulary, and a short custom descriptor is valid. Preserve the participant's own words. Most panel-specific scores range from 1 to 5; Peak timing accepts a short timing description. Use `{ "skip": true }` to skip an item. Skips do not contribute to item averages. Questions may remain blank. A panel's closed state and the event's ended state are enforced by the server.

`flavorprint` saves the final reflective questions. After the event, personal notes and the results actually presented remain available for 30 days. Ingredient information and package photographs remain available during blind tasting even if the packaging reveals identity.

## Approvals, retries and conflicts

Supply a stable `Idempotency-Key` header (up to 120 characters) for every agent write to the studio or participant API. Reuse the key only for an exact retry of the same payload. A different payload with the same key receives HTTP 409. Generate a new key for a new action.

Agent financial ledger changes and deletion of panels return HTTP 202 with `approvalRequired`, `approvalId` and no applied business change. A human administrator reviews the exact payload in History. After approval, retry the same action with `approvalId` and the original idempotency key. Approval is tied to the actor and exact payload and can be consumed once. Access grants and credential changes require a human administrator directly.

Validation failures are HTTP 400; missing authentication is 401; forbidden roles or assignments are 403; expired participant access is 410; oversized requests are 413; rate limits are 429. Re-read the latest event after a conflict. Never retry a rejected or altered financial request as if it had been approved. Concurrent successful changes and their audit entries are committed together.

## Upload protocol

POST raw JPEG, PNG, WebP or PDF bytes to `/api/upload?eventId=<id>` with the file's `Content-Type`, URL-encoded `X-File-Name`, and your authentication. Maximum upload is 20 MB; images must be at most 100 megapixels. Images are resized and converted on the server to JPEG, targeting roughly 1 MB while preserving readability. Orientation is handled by the image transformation service. The original bytes are never stored.

The response includes `key`, `previewUrl`, `size`, `originalSize` and `needsReview`. If review is required, inspect the protected JPEG preview, then POST JSON `{ "action": "accept", "key": "..." }` to `/api/upload`. If it is unreadable, use `discard` instead and provide a better source. Do not attach an unaccepted image to inventory or a panel. Only accepted images are available through event packaging links. Unaccepted previews are cleaned up after 24 hours. PDFs remain documents.

## Deferred integrations

Payments are manual. No checkout, card collection, automatic charge or processor refund is implemented. Future providers must implement the provider-neutral interface in the source; event and ledger IDs remain independent of provider identifiers.

Email delivery and optional Google sign-in become available when configured with the business's credentials. Customer booking and payment emails remain disabled. A host may send participant review links, and a participant may request their own link when email is connected. Do not describe unconfigured integrations as working.

### Inventory package photos

Administrators can upload inventory photos without an `eventId`. After reviewing and accepting each image, send `action: "stock"` with the complete inventory record, a `photos` array of up to 20 distinct accepted image keys, and optional `photoLabels` mapping those keys to side labels (maximum 80 characters each). Use labels such as Front, Back, Left side, Right side, Top, Bottom, Ingredients or Date / lot code. An older stock update that omits `photos` keeps the saved gallery; an explicit empty array removes its attachments. PDFs cannot be package photos.

To reuse inventory photos in a template or event, copy the desired keys and labels into the panel item’s `photos` and `photoLabels` before `savePanel`. Hosts can read accepted inventory photos and use them in authorized panels but cannot edit inventory. Copying is explicit; later inventory changes do not alter saved panel copies. Removing a reference keeps files used elsewhere. Template export excludes both photo references and labels.