@go-labs-sg/rsvp 0.17.0 → 1.1.0

package/README.md

@@ -85,6 +85,48 @@ The installed command uses the same portable Bun launcher as the other Go Labs C
 
 Global administrators can update another account's global role from the web user manager or with `rsvp user role update --allow-state-change --target <user-id> --payload '{"userId":"<user-id>","role":"admin"}'`. Administrators cannot remove their own global admin role.
 
+## Personal seating drafts
+
+`event seating draft get`, `save`, `preview`, and `publish` use the same server-owned
+personal draft as Assign Guests. Resume it on another authenticated device; drafts
+are isolated by event and signed-in owner. Do not pass an owner ID. Stored changes
+contain only `registrationAttendeeId`, `fromSeatId` (the first live source, nullable)
+and `toSeatId` (nullable to unseat). Stage does not book seats, acquire holds or send
+email. Preview reports fresh conflicts and grant-scoped guest details.
+
+Guest reads are live by default. Add `--include-draft` (or JSON `includeDraft: true`)
+to `event seating guests list` or `count` to apply only your saved draft before
+seating filters, facets and pagination. `--include-draft=false` keeps live results.
+Draft-mode cursors bind the saved version; restart pagination after a draft save.
+The Assign guests page always reads this personal-draft view.
+
+```sh
+rsvp event seating draft get --organization-id org_123 --event-id evt_123 --ack-sensitive-data
+rsvp event seating draft save --allow-state-change --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","expectedVersion":0,"changes":[{"registrationAttendeeId":"att_123","fromSeatId":null,"toSeatId":"seat_123"}]}'
+rsvp event seating draft preview --organization-id org_123 --event-id evt_123 \
+  --expected-version 1 --ack-sensitive-data
+rsvp event seating draft publish --organization-id org_123 --event-id evt_123 \
+  --expected-version 1 --request-id 123e4567-e89b-42d3-a456-426614174000 \
+  --reason 'Seat the confirmed guest' --allow-state-change --target evt_123
+```
+
+Save and Publish require the latest `expectedVersion`. A successful Publish applies
+all changed guests atomically and clears only that version of your draft. Resolve
+preview issues before publishing; conflicts leave all bookings and the draft intact.
+For an unknown outcome, retry the same UUID `requestId`, version, reason and email
+choice: the durable receipt returns the previous counts without sending again or
+clearing a newer draft. A different intent needs a new request ID. Email defaults
+off. To opt in, use `--allow-email` and a full JSON payload including organizationId,
+eventId, expectedVersion, requestId, reason and `sendSeatChangeEmail: true`. Do not
+combine `--payload` with command-local version/reason/request flags;
+the server additionally requires notice permission and enabled recipient policy.
+Preview counts recipient registrations, not guests. On realtime-enabled servers,
+free new targets require validated per-registration holds at Publish, supplied as
+`seatHolds: [{registrationId, holds: [{seatMapId, clientId, holdToken}]}]` in the
+payload. Acquire these through the existing organizer hold-token flow; Stage never
+holds seats. Swaps and cycles of changed live sources do not require free-seat holds.
+
 ## Command safety
 
 Argument-parsing errors use a safe command label and never echo option values,
@@ -125,6 +167,37 @@ key to clear the image. The public event guide reuses both assets. Campaign
 HTML can link to the guide with `{{eventDetailsUrl}}`; `{{eventUrl}}` still
 points to the registration page.
 
+The optional event footer is one image shown at the bottom of the registration
+and confirmation pages; events without one show no footer. Use
+`event footer upload create` for the upload URL and key, upload the image
+(PNG, JPG, WebP, or GIF up to 10 MB; SVG is not accepted), then save it with
+`event footer update`. `variant` defaults to `DESKTOP`; send `MOBILE` to set a
+separate image for screens under 640px. When only one variant is set it is used
+on every screen size. A null `footerImageKey` clears that variant.
+
+```sh
+rsvp event footer update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","footerImageKey":"rsvp/events/evt_123/footers/<uuid>.png","variant":"MOBILE","version":7}'
+```
+
+Instead of one image, the footer can show separate logos scrolling across the
+page. Upload each logo with `event footer upload create`, then save the mode
+and the ordered list with `event footer logos update`. Each logo needs a
+`name` (also its alt text); `heading` (for example "Supported by"), a smaller
+`label` (for example "Principal partners") and an `https://` `url` are optional.
+Adjacent logos with the same heading appear together under it. Up to 30 logos.
+`footerMode` `IMAGE` switches back to the single image; both modes keep their
+uploads.
+
+```sh
+rsvp event footer logos update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","footerMode":"LOGOS","logos":[{"imageKey":"rsvp/events/evt_123/footers/<uuid>.png","name":"FARM","heading":"Produced by","url":"https://www.farm.sg"}],"version":8}'
+```
+
 For a read-only registration-journey diagnosis, inspect the event, draft,
 published versions, and event-owned resources together:
 
@@ -135,6 +208,76 @@ rsvp event flow versions list --organization-id org_123 --event-id evt_123
 rsvp event flow resources get --organization-id org_123 --event-id evt_123
 ```
 
+### Registration-flow admission policy
+
+`event flow draft get` returns normalized legacy invitation forms as
+`authentication.mode: "EMAIL_OTP"` with `definition.admissionPolicy: "ROSTER_ONLY"`.
+Carry that independent policy through `event flow draft save`, `event flow publish`,
+and `event flow version activate`; none of those operations silently opens signup.
+The participant-safe `event flow published get` admission manifest also reports
+`admissionPolicy` (`OPEN` for modern definitions without an explicit policy).
+
+Save the complete returned definition with its current `expectedRevision`.
+Omitting `admissionPolicy` preserves the stored draft/publication policy for older
+clients. To intentionally broaden admission, explicitly set it to `"OPEN"` in the
+modern email-auth definition, save, then publish; this remains subject to event
+permissions, audience restrictions, and email-domain policy for new attendees.
+Existing eligible roster attendees keep their existing eligibility rules.
+
+```sh
+rsvp event flow draft get --payload '{"organizationId":"org_123","eventId":"evt_123","flowId":"flow_123"}'
+# Save the complete JSON definition and expectedRevision in flow-draft.json.
+# Keep admissionPolicy: "ROSTER_ONLY" unless the organiser approves open signup.
+rsvp event flow draft save --allow-state-change --target evt_123 --payload "$(cat flow-draft.json)"
+rsvp event flow publish --allow-state-change --target evt_123 --payload '{"organizationId":"org_123","eventId":"evt_123","flowId":"flow_123","expectedDraftRevision":2}'
+rsvp event flow version activate --allow-state-change --target evt_123 --payload '{"organizationId":"org_123","eventId":"evt_123","flowId":"flow_123","flowVersionId":"version_123"}'
+```
+
+Replace illustrative IDs and revisions with current readback values. Deploy API
+policy enforcement before clients; an old API does not understand this field.
+No authentication, consent flags, command names, or credential protocol changes.
+
+### Registration-flow date-limit messages
+
+`DATE` and `DATETIME` custom fields accept optional
+`field.validation.minDateMessage` and `maxDateMessage`: trimmed, non-empty plain
+text of at most 500 characters. Each replaces only its corresponding out-of-range
+explanation. Inclusive `minDate`/`maxDate` bounds, malformed-date errors and
+required-field errors are unchanged; omitted messages keep the existing defaults.
+
+An illustrative DOB validation object is:
+
+```json
+{
+  "maxDate": "2008-01-01",
+  "maxDateMessage": "You must be at least 18 to register for this event."
+}
+```
+
+Age wording is organizer-authored, not a dynamic age rule. Choose the cutoff for
+the event; do not reuse the illustrative date blindly.
+
+Read the full current definition/revision using `event flow draft get`, edit the
+intended field, then pass the complete definition to `event flow preview` and
+`event flow draft save --allow-state-change --target <eventId> --payload <JSON>`.
+Preview/save payloads include `organizationId`, `eventId`, optional `flowId`, and
+`definition`; save also requires `expectedRevision`. Publish separately using
+`event flow publish --allow-state-change --target <eventId> --payload <JSON>` with
+`expectedDraftRevision`. Read back the saved definition with `event flow draft get`
+and verify its compiled participant projection using the authenticated organizer
+`event flow preview` command. Use `event flow versions list` to check immutable
+version/publication identity; `event flow published get` provides public admission
+and publication metadata in normal CLI execution, not the full participant fields.
+It has no participant-session forwarding; the API returns `flow.participant` as
+`null` without matching participant access. Verify the actual published date limits
+and messages through the event's registration flow with a valid participant
+session.
+
+Existing commands forward the definition unchanged to the authenticated shared
+API; no new flags or CLI-only validation are needed. Deploy matching API/web
+support before saving these keys via the CLI; older APIs strip unrecognized
+message keys. No event or published version is updated automatically.
+
 ### Registration-flow image upload lifecycle
 
 Registration-flow images are **named, event-local assets**. Create one with an
@@ -175,6 +318,180 @@ protocol. Reference the finalized asset from the appropriate form choice, then
 save and publish the flow separately when the complete draft is approved.
 
 
+## Stripe payments and external refunds
+
+`payment checkout create` uses the same server-enforced finite reservation policy
+as the web app. New Checkout sessions exclude known slow-settling methods while
+retaining dynamic immediate methods such as cards and PayNow. Existing sessions
+and late-success safeguards are unchanged.
+
+`payment event list` reports completed refund totals including separately
+recorded, verified refunds issued outside RSVP. Pending/failed provider refunds
+do not count, and an external refund never consumes an unrelated app refund
+request. `payment refund` still requires the existing financial/external-write
+gates and original account binding. `payment exception list` remains the place
+to inspect unresolved payment exceptions. Existing command inputs and gates are
+unchanged. `payment refund recover` checks an existing local or external refund
+adjustment through its stored provider reference; it never creates a new refund:
+
+```sh
+rsvp payment refund recover \
+  --ack-sensitive-data --allow-external-write --allow-financial-write \
+  --allow-state-change --target adjustment_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","paymentAttemptId":"attempt_123","adjustmentId":"adjustment_123"}'
+```
+
+The organization/event/attempt and adjustment must belong together, and the
+caller must retain payment-adjustment permission through the provider lookup;
+current actor authority and event lifecycle are rechecked transactionally before
+any financial or audit writes. Repeated checks reconcile the
+same adjustment safely; a missing provider reference requires separate operator
+reconciliation, not a new key or refund request.
+
+### Tax configuration and breakdowns
+
+`payment configure` accepts optional `tax` JSON. Use `{"mode":"NONE"}` for
+no tax. `INCLUSIVE` extracts tax from the configured price; `EXCLUSIVE` adds
+tax to it. Both taxable modes require a trimmed `label` (1–50 characters), an
+integer `rateBasisPoints` from 0 to 10000, and explicit `donationTaxable`.
+**100 basis points = 1%.** The example below is illustrative, not a recommended
+rate or a decision about whether donations are taxable.
+
+Read the current policy and `configurationVersion` before configuring, and
+replace the IDs, version, amounts and tax settings for the intended event:
+
+```sh
+rsvp payment event get --allow-financial-write \
+  --payload '{"organizationId":"org_123","eventId":"evt_123"}'
+
+rsvp payment configure \
+  --allow-external-write --allow-financial-write --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","eventVersion":7,"enabled":true,"currency":"SGD","amountMinor":1000,"pricingMode":"PER_REGISTRATION","donationMaximumMinor":500,"checkoutExpiryMinutes":30,"reservationPolicy":"HOLD_UNTIL_EXPIRY","tax":{"mode":"EXCLUSIVE","rateBasisPoints":900,"label":"Tax","donationTaxable":false}}'
+```
+
+This is a complete configuration write, not a tax-only patch: preserve the
+intended payment policy and credential selection. Add `flowId` for a named
+form override; `useEventDefaults: true` makes that form inherit the event policy,
+including tax. Omitted tax remains compatible with legacy no-tax configuration.
+Read `payment event get` back with the same scope to verify the saved policy.
+
+`payment mine get` exposes the attempt's saved tax quote and subtotal/tax/final
+total. `payment event list` exposes each attempt's original `quote` plus
+`refundBreakdown` (cumulative refunded subtotal, tax and total). Pending refunds
+are not confirmed refunded amounts. These are payment breakdowns, not statutory
+tax invoices. Organizers choose applicable settings; configuration does not
+establish legal approval or activate an event. Deploy matching API/web/CLI
+support before using these fields.
+
+### Pending Stripe connection preparation
+
+Organization managers can persist separate named Sandbox and Live connections
+without either secret. Generate one webhook UUID for each request, keep it for
+retries, and replace all illustrative IDs below:
+
+```sh
+rsvp stripe credential prepare \
+  --allow-external-write --allow-state-change --target org_123 \
+  --payload '{"organizationId":"org_123","name":"Client Sandbox","livemode":false,"webhookSourceId":"9dd0ba39-b55e-4e65-aa3e-d08242c45b8f"}'
+
+rsvp stripe credential preparation list \
+  --payload '{"organizationId":"org_123"}'
+```
+
+The response includes the saved preparation ID, webhook path, environment,
+endpoint API version and required events. Confirm the deployment/hosting origin
+before constructing the full client URL. Pending records survive reload but are
+not usable payment credentials or defaults and cannot verify webhooks. Pending
+names are also protected from legacy credential creation and rename operations;
+unreserved names remain supported.
+
+Prefer **Complete setup** in the encrypted integrations UI for secret entry.
+For approved private automation, `stripe credential complete` calls the same
+API with `organizationId`, the unchanged `name`, saved `preparationId` and
+`webhookSourceId`, plus `secretKey` and `webhookSecret`. It requires
+`--allow-external-write --allow-state-change --target <organizationId>`.
+Both restricted `rk_` and secret `sk_` server keys are supported. Never place
+secrets in chat, payment payloads, committed files, or shared shell history.
+The complete command returns only public credential metadata.
+
+Then `stripe credential test` takes `organizationId` and `credentialId` with
+`--allow-external-write --allow-state-change --target <credentialId>`.
+Its bounded account/Balance/Checkout/PaymentIntent/Refund reads verify the
+prepared mode and read access, not write permission or webhook delivery. Only a
+tested usable connection can be selected for payments; perform a separate sandbox
+payment and webhook acceptance check before launch. These commands use the
+normal authenticated API and never bypass organization-management permission.
+
+Deploy with the schema/client and webhook prerequisites in
+[the application guide](../../../apps/rsvp/README.md#refunds). Local generated
+clients can be refreshed with `bun db:generate`; that is not a database push or
+proof of deployed schema state.
+
+## Lucky Draw check-in cutoff
+
+The event manager can save an optional cutoff in **Check-in → Settings → Lucky
+draw eligibility**, in the event's configured timezone. The API stores an absolute
+ISO timestamp with an explicit offset (`Z` or `±HH:MM`), not a browser-local time.
+There is no fixed cutoff or 8 PM default. Unconfigured events return
+`luckyDrawEligibility.cutoffAt: null`; malformed stored values also return `null`
+rather than being interpreted in the browser's timezone.
+
+Read the event first:
+
+```sh
+rsvp event get --organization-id org_123 --event-id evt_123
+```
+
+Copy its current `configurationVersion` into the setup payload's `version`.
+Replace all example IDs, version `7`, and the illustrative timestamp below with
+values for the intended event; the date, time, and offset are not defaults:
+
+```sh
+rsvp event setup step update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","version":7,"section":"LUCKY_DRAW","cutoffAt":"2030-06-15T13:30:00+02:00"}'
+```
+
+To clear the cutoff, read the event again and use its fresh version with
+`cutoffAt: null` (not a blank string):
+
+```sh
+rsvp event setup step update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","version":7,"section":"LUCKY_DRAW","cutoffAt":null}'
+```
+
+Both writes require `event.manage`, the explicit state-change acknowledgement,
+and a `--target` matching the payload's `eventId`. A stale version returns
+`CONFLICT`: fetch the event, review the latest settings, then retry with its
+current version rather than replaying an old payload. Read the event back after
+a successful write to verify the cutoff and configuration version.
+
+This configuration step only stores the cutoff and preserves unrelated event
+metadata. It does not choose eligible people, apply category/exclusion rules,
+import a draw roster, or reconcile prizes/vouchers. Deploy the updated API before
+saving the new setup section; no database schema migration is required.
+
+### Registration card copy
+
+`section: "PUBLIC_PAGE"` replaces the event's saved landing-page card copy.
+Omit a text key to use the default wording; set a `show…` flag to `false` to
+hide that notice. Read the event first and use its current version:
+
+```sh
+rsvp event setup step update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","version":7,"section":"PUBLIC_PAGE","publicPage":{"registrationTitle":"NELBD Quest Registration","deadlineLabel":"Register by","responseUpdateNotice":"You may return to update your registration details before the timing stated above.","accessNotice":"Continue to complete the registration for both team members.","registrationActionLabel":"Register now"}}'
+```
+
+Limits: title 120, description 500, deadline label 60, response-update notice
+300, access notice 500 and button label 100 characters. It requires
+`event.manage`; no database migration is required.
+
 ## Per-form confirmation presentation
 
 In the form builder's **Flow settings → Confirmation and check-in pass**, set
@@ -218,21 +535,37 @@ No database schema migration or attendee backfill is required.
 
 ## Administrator registration for an invitee
 
-Inspect the invitee's active registration form and current registration version
-before submitting. The context includes the published flow definition, invitee,
-and existing registration (if any):
+Organizers can register someone on their behalf at any time, including after
+registration has closed. This is the same action as the **Register invitee**
+page under People. Look the person up first. Pass `inviteeId` for someone on
+the invitee list, or `person` with their details. The response includes the
+published flow definition, the invitee, `isExistingInvitee`, any existing
+registration, `archivedRegistrationId`, `canAddInvitee` and
+`canOverrideCapacity`:
 
 ```sh
 rsvp event flow admin registration context get \
   --ack-sensitive-data \
   --payload '{"organizationId":"org_123","eventId":"evt_123","inviteeId":"invitee_123"}'
+
+rsvp event flow admin registration context get \
+  --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","person":{"email":"ava@example.com","employeeId":"E1042","audienceTierId":null}}'
 ```
 
+A `person` lookup matches an invitee with the same email (on the invitee or
+their account) or the same employee ID. If the email and employee ID belong to
+two different invitees, the lookup is refused. When nothing matches,
+`isExistingInvitee` is `false`, and the context previews the form and seats
+that a new invitee in the given audience tier would get. If
+`archivedRegistrationId` is set, restore that registration instead (`people
+registration restore`), which keeps the existing QR code.
+
 Use the returned `flowVersionId` and `expectedRegistrationVersion` in the
-submission. Set `expectedOutcomeId` to the outcome selected by the answers in
-the published definition, and provide answers keyed by each field's `outputKey`.
-A new UUID `idempotencyKey` identifies this submission. The audit reason records
-why an administrator submitted on the invitee's behalf.
+submission. Set `expectedOutcomeId` to the outcome selected by the answers, and
+key the answers by each field's `outputKey`. A new UUID `idempotencyKey`
+identifies the submission. The audit reason records why an organizer submitted
+on the person's behalf. Give exactly one of `inviteeId` or `newInvitee`:
 
 ```sh
 rsvp event flow admin registration submit \
@@ -240,14 +573,42 @@ rsvp event flow admin registration submit \
   --allow-state-change \
   --target invitee_123 \
   --payload '{"organizationId":"org_123","eventId":"evt_123","inviteeId":"invitee_123","flowVersionId":"flow_version_123","answers":{"attendance":"ATTENDING"},"expectedOutcomeId":"attending","expectedRegistrationVersion":0,"idempotencyKey":"9dd0ba39-b55e-4e65-aa3e-d08242c45b8f","auditReason":"Recorded response by phone"}'
+
+rsvp event flow admin registration submit \
+  --ack-sensitive-data \
+  --allow-state-change \
+  --target ava@example.com \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","newInvitee":{"displayName":"Ava Tan","email":"ava@example.com","employeeId":"E1042","audienceTierId":null},"flowVersionId":"flow_version_123","answers":{"attendance":"ATTENDING"},"expectedOutcomeId":"attending","expectedRegistrationVersion":0,"idempotencyKey":"3f0c5a4e-2a43-4d8b-9a59-6d0e8f5b8a11","auditReason":"Late addition approved by the client","sendConfirmation":true}'
 ```
 
+With `newInvitee`, the target is the email. Matching uses the same identity
+rules as roster import and admission: email case and Gmail dot/`+alias`
+spellings are ignored, and so is employee ID case. If an invitee already matches
+the details, that invitee is registered. Otherwise a new invitee is added to the
+list and registered in the same transaction. Adding someone new needs the
+`roster.manage` permission. Invitees who declined can be registered; anyone
+with an active registration is changed through `people registration update`
+instead, and archived registrations go through restore.
+
+Optional fields:
+
+- `sendConfirmation` (default `true`): set it to `false` to skip the
+  participant confirmation email with the QR code.
+  The result's `confirmationQueued` says whether the email was actually queued:
+  it is `false` when the form's email settings send no confirmation for this
+  registration, even if `sendConfirmation` is `true`.
+- `overCapacityReason` (10–500 characters): registers the person even when the
+  event is full. This needs the `capacity.override` permission (event and
+  organization admins). The reason is recorded in the activity log. Without it,
+  a full event returns a conflict with `eventAtCapacity: true` in the error
+  data. Menu (dish) capacity is still enforced.
+- `consentOverrideReason`: required when the flow has a consent step. It
+  records the organizer's reason in the audit trail; it does not record
+  attendee consent or a signature.
+
 Replace the example answer key and value with those required by the returned
-definition. If the flow requires a consent override, include a nonempty
-`consentOverrideReason` in the submission payload. The override records the
-administrator's reason in the audit trail; it does not record attendee consent
-or a signature. A stale registration version or flow version is rejected; fetch
-the context again before retrying with a new idempotency key.
+definition. A stale registration version or flow version is rejected; fetch the
+context again before retrying with a new idempotency key.
 
 Create an immutable menu version with an explicit mutation acknowledgement. The
 target is the event ID in the payload:
@@ -302,40 +663,24 @@ rsvp check-in by-reference \
 
 High-impact payment and retention commands remain protected by their matching financial, deletion, external-write, and sensitive-data gates. The API always re-evaluates the authenticated user's current Registration role, organization membership, event assignment, and resource permissions.
 
-## Operational report exports
-
-`export request` accepts `format: "XLSX"` (the default when omitted) or `"CSV"`.
-Use `filters.view` to name the population rather than relying on a dataset label:
+## Registration master list export
 
-- RSVP: `MASTER` (all invitees, grouped employee/guest responses; default),
-  `CURRENT` (current response rows per person), `HISTORY` (all registration
-  records, not every edit revision), or `CLIENT_REGISTRATION` (current completed
-  employee/guest responses, including declines; excludes nonrespondents/drafts).
-  The client XLSX has **Attending**, **Not Attending**, **Master**, and **Metadata**
-  sheets; its CSV contains Master data only. Guest staff/department fields
-  describe the host, while menu and dietary answers remain person-scoped.
-- SEATING: `CURRENT` (active bookings; default) or `HISTORY` (active and released).
-- ATTENDANCE: `CURRENT` (expected people; default) or `CHECKED_IN` (expected people
-  with a check-in that has not been undone), or `ALL_INVITEES` (roster invitees,
-  including nonrespondents/declines, plus current guests). Registered, submitted,
-  attending, and active check-in states remain separate. None defines draw
-  eligibility.
-
-Form, registration-status and submission-date filters apply only to RSVP.
-Other datasets do not accept `view`. These combinations are validated by the API.
+`export request` queues the single **Registration master list** Excel workbook
+(one **Master List** sheet; question columns follow the event's form). The
+payload is `organizationId`, `eventId` and an audit `reason`; the old `dataset`,
+`format` and `filters` fields are ignored. See the RSVP app README for columns.
 
 ```sh
 rsvp export request \
   --ack-sensitive-data \
   --allow-state-change \
   --target evt_123 \
-  --payload '{"organizationId":"org_123","eventId":"evt_123","dataset":"RSVP","format":"XLSX","filters":{"view":"MASTER"},"reason":"Organizer master list"}'
+  --payload '{"organizationId":"org_123","eventId":"evt_123","reason":"Organizer master list"}'
 ```
 
 Use `export list` to check the requester-scoped job, then `export download` for
-its current authorized download URL. For the client workbook, replace `MASTER`
-in the example with `CLIENT_REGISTRATION`. For the all-invitee attendance report,
-set `dataset` to `ATTENDANCE` and `filters.view` to `ALL_INVITEES`.
+its current authorized download URL. `event registrations export` and
+`event check-ins export` were removed; use `export request` instead.
 
 Operational check-in accepts `ATTENDING` and legacy `SUBMITTED`; roster/detail,
 manual/QR/reference entry, `report overview`, and `event people overview` use that same
@@ -343,9 +688,8 @@ population. Non-operational statuses remain excluded, and permissions, payment
 gates, duplicate protection, and undo behavior are unchanged. The web panel's
 realtime connection and manual refresh controls do not add a CLI subscription.
 
-Deploy matching API and export-worker versions before requesting the new views;
-old servers/workers do not understand them. Existing CLI commands pass the JSON
-payload to the shared typed API, so no new command or client-only rules are needed.
+Deploy matching API and export-worker versions together; an old worker would build the retired
+registration-records report for master-list jobs.
 
 ## Seating updates
 
@@ -374,15 +718,38 @@ Deploy the matching API and worker before using these commands from an updated
 CLI. They retain browser authentication, event permissions and sensitive-field
 grants; the CLI does not implement separate seating rules.
 
+`event seating swap` refuses invalid swaps using first/second selected-attendee
+labels, never attendee names. This applies even when the caller can view identity
+fields: reseating permission alone is not identity access. Notice failures retain
+their API error code but do not forward attendee names or nested private details;
+the entire swap rolls back if its requested notices cannot be queued. A notice
+precondition refusal can be retried without the optional notice. Input/output
+schemas, acknowledgement gates and seating/payment rules are unchanged.
+
 ```sh
 rsvp event seating live get --ack-sensitive-data \
   --payload '{"organizationId":"org_123","eventId":"evt_123"}'
+rsvp event seating guests list --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","seatMapId":"map_123","seating":"UNSEATED","sort":"GROUP","limit":25}'
+rsvp event seating guests count --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","seatMapId":"map_123","seating":"UNSEATED"}'
 rsvp event seating occupants list --ack-sensitive-data \
   --payload '{"organizationId":"org_123","eventId":"evt_123","seatMapId":"map_123","categoryValue":"finance","limit":25,"cursor":0}'
 rsvp people registration edit get --ack-sensitive-data \
   --payload '{"organizationId":"org_123","eventId":"evt_123","registrationId":"reg_123"}'
 ```
 
+`event seating category colors get` returns only the configured category
+colour of each booked seat (for example job function) and the legend for one
+seat map, which is what the live map paints without opening the occupant
+workspace. It needs `seating.view` and registration view access, and respects
+sensitive-field access to the configured field:
+
+```sh
+rsvp event seating category colors get --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","seatMapId":"map_123"}'
+```
+
 Occupants supports optional `tableId`, `department`, `categoryValue` and `query`
 filters. `categoryValue` is the canonical (trimmed, case-normalized) value
 returned by the occupant response's category legend; it is not an arbitrary
@@ -438,12 +805,88 @@ notice is queued in the move's database transaction, so the move and notice
 request commit together or not at all; this additionally requires
 `--allow-email`. It is rejected alongside identity, contact or response edits.
 
+To swap two seated people, use `event seating swap`. Give each attendee's
+`registrationAttendeeId` with the `seatId` they hold now, plus a `reason`. Both
+seats change in one transaction, so neither is free for anyone else in between.
+If either person has moved since you looked, the swap is refused; list the
+occupants again and retry. Each person must be attending or submitted with no
+payment pending, and each seat must be allowed for the other person's audience
+tier, form and published seat map. `--target` is either attendee ID:
+
+```sh
+rsvp event seating swap \
+  --ack-sensitive-data \
+  --allow-state-change \
+  --target attendee_a \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","attendees":[{"registrationAttendeeId":"attendee_a","seatId":"seat_1"},{"registrationAttendeeId":"attendee_b","seatId":"seat_2"}],"reason":"Client asked to seat them with their team"}'
+```
+
+Add `"seatChangeNotice":{"idempotencyKey":"<uuid>"}` and `--allow-email` to
+queue a seat-change notice for each registration involved. Use
+`event seating occupants list` to find attendee and seat IDs. Swaps need the
+`seating.reseat` permission; notices also need `confirmation.resend`.
+
 ```sh
 rsvp people registration update \
   --ack-sensitive-data --allow-state-change --allow-email --target reg_123 \
   --payload '{"organizationId":"org_123","eventId":"evt_123","registrationId":"reg_123","expectedVersion":4,"reason":"Moved to finance table","seats":[{"registrationAttendeeId":"att_1","seatId":"seat_9"},{"registrationAttendeeId":"att_2","seatId":"seat_2"}],"seatChangeNotice":{"idempotencyKey":"4d68a320-013d-43c7-bfcc-d1126827d8c5"}}'
 ```
 
+### Unarchive for a fresh response versus attending Restore
+
+`people registration unarchive` forwards the permissioned, audited
+`event.bulkManageRegistrations` RESTORE operation. Supply 1–100 unique
+`registrations`, each with its current `expectedVersion` (positive integer), and
+an audit `reason` (3–500 characters after trimming). `action` defaults to
+`RESTORE` when omitted; any other action is rejected. The approval target is
+exactly the payload's **event ID**, not an individual registration ID.
+
+```sh
+rsvp people registration unarchive \
+  --allow-state-change --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","reason":"Allow a fresh response","registrations":[{"id":"reg_123","expectedVersion":6}]}'
+```
+
+Unarchive clears the archive marker and lets an eligible cancelled nonattending
+invitee return to `IMPORTED` for a fresh response. The server checks current
+permissions, revisions, eligibility and settled financial state; the CLI does
+not interpret cancelled history or make eligibility decisions. Historical
+registration/payment records remain history, and the old cancelled
+registration and QR code are **not reinstated**. Seats, capacity, session
+selections and waitlist entries are not recovered. A fresh submission uses the
+normal flow and current checks, with new payment and credentials where required.
+Unarchive cannot shortcut attending recovery. The result's
+`readmittedInviteeCount` reports invitees reopened for a fresh response;
+`changedCount` and `releasedAttendeeCount` retain their existing meanings.
+
+`people registration restore` instead reinstates a cancelled or archived
+**attending registration**, with its existing identity/payment/QR subject to the
+server's restoration checks. It is not Unarchive and does not start a fresh response.
+Read it first with `people registration edit get` and `"mode":"RESTORE"` to see
+eligible seats and each attendee's previous seat. Supply `expectedVersion`, an
+audit `reason`, and a seat for every attendee who had one; the server claims
+capacity, books the seats and rejects full events, re-registered invitees and
+unresolved or refunded payments. A full event is rejected unless
+`overCapacityReason` (10–500 characters) is given, which needs the
+`capacity.override` permission (event and org admins); the override and reason
+are recorded in the activity log. Menu (dish) capacity is still enforced and
+cannot be overridden. While an event is over capacity, declines and smaller
+parties, payments confirmed while their hold is still live, and unexpired
+waitlist offers (up to the offered party size) still go through. A payment
+confirmed after its hold lapsed gets the normal capacity check and goes to
+review if the place was reused. The current limit can be saved unchanged; any
+new limit must be at least the confirmed count. The existing QR code works
+again. Add
+`confirmation` (with `--allow-email`) to queue the participant confirmation.
+Session selections cancelled by archiving are not restored; the response
+reports `droppedSessionSelections`.
+
+```sh
+rsvp people registration restore \
+  --ack-sensitive-data --allow-state-change --allow-email --target reg_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","registrationId":"reg_123","expectedVersion":6,"reason":"Archived by mistake","seats":[{"registrationAttendeeId":"att_1","seatId":"seat_9"}],"confirmation":{"idempotencyKey":"4d68a320-013d-43c7-bfcc-d1126827d8c5"}}'
+```
+
 A separate manual notice for an already committed revision remains available:
 
 ```sh
@@ -556,3 +999,27 @@ email, external-write, and state-change effect approvals. It creates a workspace
 awaiting owner acceptance and sends a 48-hour first-owner invitation. The internal
 provisioner does not receive customer organization membership. The response
 reports invitation delivery failure so the invitation can be resent safely.
+
+### Assign guests rail reads
+
+`event seating guests list` includes unarchived, confirmed attendees (legacy
+`ATTENDING` and current `SUBMITTED`), including guests with no active seat. An
+active booking on any layout counts as seated. Groups are registration parties.
+Both reads require `seating.view` and `rsvp.view`; names/search/name sorting and
+dietary filters/labels additionally require their sensitive-data grants.
+
+Shared filters: `seating` (`UNSEATED`, `SEATED`, `ALL`), `query` (max 120),
+`audienceTierId`, `registrationId`, `dietaryTag`, `guestKind` (`ALL`, `HOST`,
+`GUEST`). List adds `limit` (1–100; default 25), `sort` (`GROUP`, `NAME`), opaque
+`cursor`, and `direction` (`forward`, `backward`). Backward requires a cursor.
+The response is `{items,pageInfo}`; use its `nextCursor`/`previousCursor`, not a
+row ID. Cursors are bound to filters, ordering, scope and sensitive grants; a
+changed context requires restarting the list. Deleted cursor anchor rows do not
+break paging. Offset `page`/`perPage` and unknown keys are rejected.
+
+`event seating guests count` rejects paging/sort keys. It returns the matching
+count, seating-tab counts (ignore their own seating filter), tier counts (ignore
+their own tier filter), dietary choices (ignore their own dietary filter), and
+permission flags. Facets expose at most 100 choices with truncation flags; tier
+counts stream compact registration aggregates in bounded reads, without a hard
+registration-count ceiling. Rail page rows are never loaded event-wide.