frontpage-host 0.2.9 → 0.2.11

package/AGENTS.md

@@ -56,7 +56,7 @@ frontpage whoami --json
 frontpage doctor --json
 ```
 
-- Keys are minted only in the Frontpage UI (profile → Developers). Prefix `fp_live_`.
+- Keys are minted only in the Frontpage UI (Workspace → account menu → Developers). Prefix `fp_live_`.
 - Keys act as the minting user on **every** site they can access. Treat like passwords.
 - `PUBLIC_CLI_ENABLED` is server-side; the CLI cannot turn it on. Bare “not found” on `/api/v1/me` usually means the flag is off (exit 5).
 
@@ -266,8 +266,14 @@ Scale and internal sites, after owner activation. No pilot allowlist. Use `front
 Payments, invoices and recurring billing: see packaged [PAYMENTS.md](./PAYMENTS.md), `frontpage help payments`, and https://frontpage.host/developers/payments. Version 0.2.0 removes writable currency, Store checkout mode and Store-owned money commands; Store stays cart-only. Preview/review before sends; keep stable operation keys on retries. Autopay requires the customer’s own verified authorization.
 
 
-Offerings own every standalone Pay now payment. Use `frontpage payments buttons list|get|create|update|archive|restore`; create the saved offering before adding its returned `data-fp-pay` markup. Supports `--receipt-template-id UUID`, `--default-receipt`, `--active true|false`, combined price/details updates and JSON payloads. Archive deletes from active checkout but preserves history. The website agent uses the same service automatically for ordinary payment-button requests. Store stays cart-only; invoices stay saved customer-addressed records. Full instructions: PAYMENTS.md and https://frontpage.host/developers/payments.
+Offerings own every standalone Pay now payment. Use `frontpage payments buttons list|get|create|update|archive|restore|receipt-preview`; create the saved offering before adding its returned `data-fp-pay` markup. Supports `--receipt-template-id UUID`, `--default-receipt`, `--active true|false`, combined price/details updates and JSON payloads. Archive deletes from active checkout but preserves history. The website agent uses the same service automatically for ordinary payment-button requests. Store stays cart-only; invoices stay saved customer-addressed records. Create/update/restore return setup.status and the existing Stripe handoff, without enabling Store or overriding Payments off. Preview a bound receipt with buttons receipt-preview; it never sends or charges. Digital delivery uses approved file links in the saved purchase receipt; keep the offering inactive until resources are ready. Full instructions: PAYMENTS.md and https://frontpage.host/developers/payments.
 
 Currency is owned by Payments and read by Store, Offerings and invoices. Offering create/get/update responses include exact receiptVariables. For custom confirmations, declare those names with existing mail template commands, attach receiptTemplateId, and verify both records. Only include expressly selected answers; keep private answers excluded. Forms still use input-name tokens and confirmTemplateId.
 
 Customer Inbox setup: enable website chat through Inbox settings; Frontpage public sites load it without a file edit or publish. Other websites use the explicit widget snippet. `get website` reports managed addresses/public availability. Website knowledge is default-on, read-only public retrieval; `websiteKnowledge.enabled:false` disables it. Source toggles, attention filtering and receipt cursors use the documented versioned resources.
+
+Customer Inbox team guidance: administrators may set `guidanceEmail` through the versioned settings write. The owner toolbar has the same setting. Teammates reply as the configured mailbox; no teammate account or separate mailbox activation is needed. Do not set it to the public Inbox address. Conversation management uses close/reopen; do not use read/trash/restore.
+
+## Emails workspace workflows
+
+See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.

package/CUSTOMER-INBOX.md

@@ -24,9 +24,9 @@ Reads use `get`. Writes use `put` or `post`, a UTF-8 JSON object file, and an 8
 | `settings` | GET | Returns `version`, `value`, fixed model and multiplier |
 | `settings` | PUT | `{"expectedVersion":0,"value":{"instructions":"Ask me if unsure."}}` |
 
-Setup binds private guidance to the verified owner who requested it. That identity comes from Core, never model/customer fields. The agent manages new conversations by default after setup; the platform's Inbox switches control transport and automation independently of site activation. Set `value.enabled:false` for manual handling. Settings changes cancel stale automatic jobs and queued automatic sends.
+Setup defaults private guidance to the verified administrator who requested it. An administrator can set `value.guidanceEmail` to a team mailbox, such as `support@example.com`; no separate activation link or teammate Frontpage account is required. Teammates reply as that exact mailbox. Private routes and receiving authentication still protect replies. Changing the destination revokes old private routes and cancels queued mail to them. `guidanceToMe:true` restores your verified account email. The destination cannot be the Inbox’s own public support alias. The agent manages new conversations by default after setup; the platform's Inbox switches control transport and automation independently of site activation. Set `value.enabled:false` for manual handling. Settings changes cancel stale automatic jobs and queued automatic sends.
 
-Settings allow `enabled`, `instructions`, `tools`, `maxSteps` (1–12), `maxOutputTokens` (256–2400), and `maxInputBytes` (4000–64000). Supported tools: `knowledge_read`, `knowledge_update`, `customer_read`, `verify_customer`, `customer_update`, `notes_read`, `note_add`, `ask_owner`, `reply_customer`, `wait`, `finish`. Keep `wait` and `finish` enabled. Mailbox verification remains available whenever customer-data tools are enabled; it cannot be bypassed by settings. Defaults: 8 steps, 1200 output tokens per call, 32000 bytes of public text. Model, billing multiplier and recipients are not caller-selectable fields. The worker also enforces platform concurrency, deadlines and input limits.
+Settings allow `enabled`, `instructions`, `tools`, `maxSteps` (1–12), `maxOutputTokens` (256–2400), and `maxInputBytes` (4000–64000). Supported tools: `knowledge_read`, `knowledge_update`, `customer_read`, `verify_customer`, `customer_update`, `notes_read`, `note_add`, `ask_owner`, `reply_customer`, `wait`, `finish`. Keep `wait` and `finish` enabled. Mailbox verification remains available whenever customer-data tools are enabled; it cannot be bypassed by settings. Defaults: 8 steps, 1200 output tokens per call, 32000 bytes of public text. Model and billing multiplier are fixed. Only an administrator can choose the private guidance mailbox; the support agent cannot choose recipients. The worker also enforces platform concurrency, deadlines and input limits.
 
 `maxContextTokens` (12000–96000, default 32000) sets a conservative per-call input plus output allowance. UTF-8 text bytes, tool definitions, instructions, transcript and image capacity count toward admission; exact provider tokens still determine billing. Optional older history and preloaded notes drop first. Essential evidence is never clipped: if it cannot fit, the job pauses for review. History stays stored without a lifetime message-count stop. The agent receives up to 40 recent messages plus required current input and owner guidance, and can retrieve older messages in bounded pages under its existing `knowledge_read` grant.
 
@@ -83,7 +83,7 @@ Lock a knowledge note with `locked:true`. Neither the support agent nor the owne
 | `files?messageId=<id>` | GET | Bound message files; editor/admin only |
 | `files/<id>` | GET | Short-lived download grant; editor/admin only |
 
-One verified customer has one continuous thread per site, across direct email, replies and verified website chat. Email subject changes do not create new cases after identity is proven. Fresh mail to the public alias remains provisional until confirmation, even when From and DMARC match an existing customer. Recipient-bound secret reply routes continue the established thread. Typed email, display names and subjects never authorize merging or history access. Closing reopens that same thread on the next message; Trash needs owner restoration. Inbox joins retained history without moving messages, files or paid receipts. Old conversation links and recipient-bound reply addresses resolve to the current thread. Public chat includes customer-visible email replies and excludes owner guidance and notes.
+One verified customer has one continuous thread per site, across direct email, replies and verified website chat. Email subject changes do not create new cases after identity is proven. Fresh mail to the public alias remains provisional until confirmation, even when From and DMARC match an existing customer. Recipient-bound secret reply routes continue the established thread. Typed email, display names and subjects never authorize merging or history access. Closing reopens that same thread on the next message. Legacy trashed threads can be reopened from Closed. Inbox joins retained history without moving messages, files or paid receipts. Old conversation links and recipient-bound reply addresses resolve to the current thread. Public chat includes customer-visible email replies and excludes owner guidance and notes.
 
 Use `timeline=true` for combined history. Its opaque `nextCursor` is a message ID, not a sequence or offset; pass it unchanged as `after` or `before`. `latest=true` returns the latest bounded page, and `before=<cursor>` loads older messages. A cursor must belong to that conversation and audience. Sequence-based reads without `timeline=true` remain available for the root segment; use the combined timeline for every linked segment. The CLI export follows the complete combined timeline. The widget opens the latest 50 public messages and offers **Load earlier messages**, so a returning customer does not wait for years of history to download. The support agent's `history_read` tool likewise follows its returned `nextBefore` message ID.
 
@@ -272,7 +272,7 @@ Update settings using the current `expectedVersion`:
 }
 ```
 
-Use exact HTTPS origins without paths or credentials. This controls cross-origin browser access, not owner permissions. Required intake fields collect details; they do not prove email ownership. The customer must confirm the emailed link before email continuation or authenticated People access. A persistent verification card explains that public business questions can continue while private customer/account data stay locked. The branded HTML email uses the shared transactional renderer and its Confirm email button opens app.frontpage.host/customer-inbox/confirm. GET never consumes a proof; an explicit same-origin POST reaches Inbox through a signed server bridge. Confirmation rotates the visitor credential. Recovery uses a new email proof and returns no history based on a typed address alone.
+Use exact HTTPS origins without paths or credentials. This controls cross-origin browser access, not owner permissions. Required intake fields collect details; they do not prove email ownership. The customer must confirm the emailed link before email continuation or authenticated People access. A compact verification prompt appears only while confirmation needs action. Public business questions can continue while private customer/account data stay locked. After confirmation, the widget removes the prompt and enables email follow-up automatically; there is no separate continuation switch. The branded HTML email uses the shared transactional renderer and its Confirm email button opens app.frontpage.host/customer-inbox/confirm. GET never consumes a proof; an explicit same-origin POST reaches Inbox through a signed server bridge. Confirmation rotates the visitor credential. Recovery uses a new email proof and returns no history based on a typed address alone.
 
 The agent reads help rules in its support prompt and uses `ask_owner`. Work caps remain server-enforced. Owner copies are private emails of future agent replies. Replying gives private guidance unless the owner explicitly requests takeover. Neither copies nor guidance put owner and customer on a shared CC thread.
 
@@ -316,11 +316,10 @@ Use `frontpage-host` 0.2.2 or later to export every linked history segment throu
 | `conversations?state=active` | GET | Open threads; also `closed`, `trash` or `all` |
 | `conversations/<id>/messages?latest=true&limit=50&audience=all` | GET | Latest page in message order |
 | `conversations/<id>/messages?before=<sequence>&limit=50&audience=all` | GET | Earlier page; do not combine with `after` or `latest` |
-| `conversations/<id>/state` | POST | `{"action":"close","expectedVersion":0}`; actions: `close`, `reopen`, `trash`, `restore`, `read` |
-| `conversations/<id>/state` | POST | Mark read with current state version and `"sequence":42` |
+| `conversations/<id>/state` | POST | `{"action":"close","expectedVersion":0}`; actions: `close`, `reopen` |
 | `conversations/<id>/revoke-sessions` | POST | `{}`; revoke existing visitor credentials |
 
-Trash retains history and file references. Restore reopens the thread; it does not erase prior handling decisions. State writes reject stale versions. Closing cancels queued sends and refuses unresolved provider outcomes. New customer input reopens a closed thread; trashed threads require owner restoration. Visitor revocation also disables recovery of that session.
+Close retains history and file references. Reopen does not erase prior handling decisions. State writes reject stale versions. Closing cancels queued sends and refuses unresolved provider outcomes. New customer input reopens a closed thread. Legacy trashed threads appear under Closed and can be reopened there. Visitor revocation also disables recovery of that session.
 
 Export the full authorized history and file manifest, one JSON record per line:
 
@@ -338,7 +337,7 @@ Inbox sends count in the site's existing email allowance. Provider-accepted send
 
 Email capture keeps the original MIME message, attachments and provider receipt. Email and chat image uploads keep the original file and a smaller agent preview. Repeated upload/message receipts retain the same file/message IDs. Validated raster customer images up to 12 megapixels use the existing public bucket. Larger or undecodable files remain downloadable and require human review. Other files and private mail originals use authenticated downloads over encrypted bytes in that same bucket. No Blob firewall changes or separate bucket are part of this release.
 
-The existing backup process enumerates the whole bucket. The existing reaper scans Inbox files in bounded pages and asks Inbox for exact retained references; it does not read message bodies. Unknown reference results protect Inbox files while legacy cleanup continues. Live history, Trash, capture holds and original/preview links retain their files. The existing archive/restore/purge coordinator claims a file in Inbox before changing bytes. A claim blocks new links and remains held after an unknown outcome. Accepted email custody, message links, Trash and capture holds protect files; abandoned chat uploads can follow the existing grace/archive rules. Unknown file records stay protected. Site finalization freezes Inbox writes before moving its bytes through the same archive process. Broader shared-reaper performance work remains a later phase.
+The existing backup process enumerates the whole bucket. The existing reaper scans Inbox files in bounded pages and asks Inbox for exact retained references; it does not read message bodies. Unknown reference results protect Inbox files while legacy cleanup continues. Live and closed history, legacy Trash, capture holds and original/preview links retain their files. The existing archive/restore/purge coordinator claims a file in Inbox before changing bytes. A claim blocks new links and remains held after an unknown outcome. Accepted email custody, message links, closed/legacy trashed conversations and capture holds protect files; abandoned chat uploads can follow the existing grace/archive rules. Unknown file records stay protected. Site finalization freezes Inbox writes before moving its bytes through the same archive process. Broader shared-reaper performance work remains a later phase.
 
 
 On app logout or account change, call `window.dispatchEvent(new Event("frontpage-inbox:reset"))`. This clears the displayed history, stored chat credential and pending input. The next request fetches a fresh assertion from `data-identity-url`; authenticated app sessions require the same current app identity on every request. Do not use a long-lived static assertion for an app with account switching. Verification returns to the same origin and the stored page path. Query strings and arbitrary redirect URLs are not accepted.
@@ -360,7 +359,7 @@ The support agent has its own system prompt plus the versioned private business
 | `customer_update` | `name`/`phone`, `evidenceMessageId` | Enrich from an explicit customer statement; cannot change identity or permission. |
 | `notes_read` | Optional `before` | Read only this verified customer's factual People notes, 25 per page. |
 | `note_add` | `text` | Save a private factual action note in People, with an idempotent receipt. Do not store hidden reasoning. |
-| `ask_owner` | `question` | Save the private question in the thread, email the verified configured owner and pause. Guidance does not take over. |
+| `ask_owner` | `question` | Save the private question in the thread, email the administrator-authorized guidance mailbox and pause. Guidance does not take over. |
 | `reply_customer` | `text` | Save a public answer and queue email to the bound verified customer when available. Never choose recipients. |
 | `wait` | `reason` | Pause safely without sending. |
 | `finish` | None | Complete this bounded job. |
@@ -375,6 +374,92 @@ The installed widget loads two public static scripts: `/customer-inbox/widget.js
 
 The workspace uses a short authenticated stream through its cookie bridge; the installed widget uses authenticated fetch with its existing visitor/app-identity headers. Streams carry empty invalidation hints, never message text, private counters, recipients or file metadata. Clients re-read their authorized history/status. One restricted Postgres listener per Inbox process wakes the existing outbox publisher and fans out hints. Notifications are best-effort; durable rows, leases, recovery scans and receipt reconciliation remain authoritative. Disconnected clients refresh and use bounded fallback polling. No token enters a stream URL, and each short stream reauthorizes on reconnect.
 
-A new unverified chat with an email requests a generic verification email automatically. It does not send private history or assume that typing an address proves identity. The owner can still answer in chat while the visitor verifies. Confirmation rotates the session and binds future public replies to that email; if the latest customer input already has an unsent public answer, Inbox queues that one answer once. It does not mail a backlog or an answer that predates a newer customer question. Verified replies mirror to email whether the page is open or closed; no presence-tracking service is needed.
+A new unverified chat with an email requests a generic verification email automatically. It does not send private history or assume that typing an address proves identity. The owner can still answer in chat while the visitor verifies. Confirmation rotates the session and binds future public replies to that email; if the latest customer input already has an unsent public answer, Inbox queues that one answer once. It does not mail a backlog or an answer that predates a newer customer question. Browser replies enter the existing mail outbox with a 30-second grace period. The open, visible widget acknowledges public replies in its transcript viewport using its current verified session. This cancels only that customer’s queued, unattempted follow-up email; the reply stays in history and still counts as answered. Hidden/minimized chat, lost connections and failed acknowledgments leave email queued. The existing publisher sends it after the grace period, normally on its next sweep (up to about 15 seconds later, plus provider time). Direct inbound-email replies keep immediate delivery. No extra continuation switch or presence service is required. A late read cannot cancel an already attempted or uncertain send; retries keep the same provider identity and accounting receipt.
 
 The workspace shows customer name/email first, latest public message in each row, and a copyable reference in conversation details. Conversation list and history scroll independently inside a bounded viewport. Settings use shared workspace controls and a presentation-only preview built from the same renderer as the installed widget. Preview changes send no email or model request. Internal note history/locks/revert stay on the note's own page.
+
+
+## Shared team guidance
+
+Read settings and use the returned version. This example assumes `version: 3`:
+
+```json
+{"expectedVersion":3,"value":{"guidanceEmail":"support@example.com"}}
+```
+
+```bash
+frontpage customer-inbox put settings --file ./team-guidance.json --request-key team_guidance_01
+frontpage customer-inbox get settings
+```
+
+The settings response has `version: 4`, `value.guidanceOwnerEmail: "support@example.com"`, and the authorizing administrator in `value.guidanceOwnerId`. Other settings remain unchanged. Repeating the exact write with the same key does not apply it twice. A stale version with a new key returns `settings_changed`. Editors cannot change the mailbox. This is the private team destination, distinct from the public address customers email.
+
+When the agent asks for help, anyone with shared-mailbox access can reply as `support@example.com`. Guidance remains private and keeps the agent handling the customer. An explicit takeover request changes handling; the customer relay stays within Inbox. Replies from an unrelated address or a revoked private route cannot act as team guidance. The audit records the actual sending mailbox; a shared sender does not identify the individual teammate.
+
+## Simple conversation management
+
+Use Open and Closed. Close preserves history; a later customer message reopens the same conversation. Legacy trashed conversations appear under Closed and can be reopened. Mark read and Trash are no longer supported management actions.
+
+```json
+{"action":"close","expectedVersion":2}
+```
+
+```bash
+frontpage customer-inbox post conversations/CONVERSATION_ID/state --file ./close.json --request-key close_conversation_01
+```
+
+Read the conversation’s current `stateVersion` first. The response increments it and sets `closedAt`; reopening clears `closedAt` and any legacy trash marker. Closing does not transfer handling or delete messages. Take over before sending a human customer reply; private guidance does not take over.
+
+## Setup and knowledge behavior
+
+Claim the public support address before relying on account confirmation, owner guidance or email replies. General browser chat can work without it. Missing setup returns `address_required`; the widget explains that account confirmation is unavailable and keeps customer data locked. Finish setup, then retry the saved request from Inbox.
+
+The support agent receives a dedicated system prompt, private business instructions, bounded conversation context and permitted tool schemas. It reads saved business notes with `knowledge_read`, live public pages with `website_search` / `website_read`, and saved approved webpage snapshots with `knowledge_read {sourceId}`. Search excerpts require a complete read before relying on them. Website search does not create internal notes. Only separate server-authorized learning from team guidance or approved source revisions may update unlocked shared knowledge. Customer assertions never authorize those writes.
+
+
+## Compact chat and workspace controls
+
+- The chat header says “We’ll reply here, or email you if you’re away.” Confirmed
+  email needs no permanent success banner. The file and send buttons use icons
+  with accessible labels; Enter sends and Shift+Enter adds a line. The message
+  input grows within a fixed bound. Selected files can be removed before sending.
+- Before a support address exists, Chat & settings shows **Set up your support
+  email** and **Create support address**. After assignment, it shows the active
+  address, its site, **Copy address**, and **Change address**. The replacement
+  form opens only after Change. Saving a replacement stops new mail to the old
+  alias; it does not delete conversation history. Reserved aliases stay protected.
+- While the agent handles a conversation, the composer offers **Guide your agent**
+  and **Private note**. After takeover it offers **Reply to customer** and
+  **Private note**. Guidance, public reply and note drafts have separate keys;
+  changing control never makes a private draft public. A hand marks **Take over**;
+  the return arrow marks **Return to agent**. Only the current owner can send a
+  manual public reply. Existing API/CLI guidance and control operations remain available.
+
+### Widget read acknowledgment
+
+The installed widget uses this automatically; owners do not need to call it.
+The endpoint accepts only the current origin-bound verified browser credential
+(and a current app identity assertion when the session belongs to an app).
+
+```http
+POST /chat/sites/<site-id>/seen
+Origin: https://your-approved-website.example
+Authorization: Bearer <verified-visitor-session>
+Idempotency-Key: seen_<unique-request-key>
+Content-Type: application/json
+
+{"messageIds":["11111111-1111-4111-8111-111111111111"]}
+```
+
+```json
+{"acknowledged":true}
+```
+
+Use one to fifty unique public message IDs from this customer’s conversation.
+The session, site, origin, current email, app binding and public audience must
+match. A typed but unverified email returns `verification_required`; a foreign
+conversation or private message returns `message_unavailable`. Mixed valid and
+invalid IDs change nothing. Retries are harmless. This endpoint neither exposes
+message content nor changes ownership, knowledge, model work or charges. Canceled
+follow-ups show **Seen in chat · email not needed** in the workspace. If the request
+fails, normal email delivery remains the fallback.

package/MAIL.md

@@ -0,0 +1,85 @@
+# Emails: authoring, recipients and delivery
+
+Use `frontpage help mail --json` for command discovery. The existing CLI binary and API namespace stay in place. Site roles and the CLI plan gate still apply. A viewer can read; an editor or owner can change email settings and content. These commands never grant platform admin rights or change a platform kill switch.
+
+## Save an email and its series together
+
+`frontpage mail save --file save.json --site YOUR_SITE --json` calls `POST /api/v1/sites/YOUR_SITE/mail/save`.
+
+```json
+{
+  "requestKey": "a-stable-key-for-this-save",
+  "document": {
+    "kind": "template",
+    "name": "Welcome",
+    "subject": "Welcome, {{first_name}}",
+    "preheader": "Here is your next step.",
+    "blocks": [{ "type": "paragraph", "text": "Thanks for joining us." }],
+    "variables": []
+  },
+  "series": { "name": "Welcome series", "steps": [] },
+  "append": true,
+  "delayMinutes": 1440
+}
+```
+
+This creates a shared template and an Off series with one step. It sends nothing and enrolls no one. The first step always has zero delay. Later step delays accept integer minutes from 0 through 525600; a series has at most 12 steps.
+
+For an existing record, supply `id` and `expectedUpdatedAt` from `mail template get` / `mail email get` / `mail series get`. To edit an existing shared template from a series, send both the complete `document` and complete pending `series` in one save, omitting `append`. **Save & return saves both**, including pending names, steps, removals and waits. To add a new step, send a new template plus the source series and `append:true`.
+
+The response reports `complete:true` and the saved records. Keep the exact payload and requestKey after a lost response. Repeating it returns the saved IDs without adding another template or step. Do not reuse a key for different content. A 409 means the saved version changed: retain the draft, read the current records, review the changes, and use a new key for the revised save. A failed transaction saves neither half. Subject, preview text, name and valid content are required. Saving never activates a series or sends email. Queued emails keep their saved content.
+
+The workspace's Back button returns to the source series and keeps unfinished work. A test sends only to the signed-in account in the workspace, and does not complete a step task. CLI test recipients remain explicit and subject to the existing test restrictions.
+
+## Campaign recipients
+
+Include `audience` with a one_off document in the same `mail save` request. Supported keys are `personIds`, `groupIds`, `stageIds`, `filters`, and `addresses`. Use `audience:null` to clear the saved selection. Addresses normalize to lower case. Saving addresses never creates CRM people or records consent. Recipient-only edits count as changes and save with the campaign.
+
+For an audience-only change, the existing `mail campaign audience --id DOCUMENT_ID --file audience.json` remains supported. Its JSON is `{"audience":{"personIds":["PERSON_ID"]}}`, or `{"audience":null}` to clear. Saved selection is intent; final send review resolves groups and filters again, checks permission and delivery restrictions, and freezes the actual recipients and content. Started campaigns cannot be edited or sent twice with a new key. Read `PEOPLE.md` for preview/send review and stable send keys.
+
+## People directory and enrollment
+
+```bash
+frontpage mail people --sort newest --page 1 --site YOUR_SITE --json
+frontpage mail people --q alex --source signup --availability eligible --sort name --page 1 --site YOUR_SITE --json
+frontpage mail people --selected PERSON_ID,OTHER_PERSON_ID --selected-only --page 1 --site YOUR_SITE --json
+```
+
+Sort values: `newest`, `oldest`, `name`. Added order uses the CRM record's added date, not recent activity or the first historical event. Source values: form, booking, signup, payment, order. Availability: all, eligible, restricted. The response includes 20 rows per numbered page, total, added date, source and availability. Every query stays inside the authorized site. Search and availability apply before paging.
+
+Use existing `frontpage people workspace series.preview --file preview.json` then `series.enrol --file batch.json` for reviewed CRM enrollment. Preview input: `{ "seriesId":"SERIES_ID", "personIds":["PERSON_ID"] }`. Each returned batch contains personIds and reviewToken; commit with those fields, seriesId and a stable requestKey. Reuse each batch's key after a network error. Receipts preserve partial outcomes. Enrollment saves immediately and never requires Save series afterward. Existing enrollment is deduplicated across all states; completed/cancelled people do not restart.
+
+- **Off:** eligible people wait at step 1. Enrollment creates no queued message, first-template snapshot, due date or allowance reservation. No sender readiness or send meter is needed to record waiting people.
+- **On:** the first email becomes ready, subject to normal permission, sender, kill switch, send window and allowance checks.
+- **Turning Off:** pending series messages stop before provider handoff. A message already accepted by the provider cannot be recalled.
+- **Turning On again:** new waiting people begin at step 1. Started people resume their next unsent step with its saved due date; an overdue step can send on the next pass. Each later wait starts after successful provider acceptance. Off time never skips a new person's first email or causes all later steps to send at once.
+
+`mail series activate SERIES_ID` sets status active (On); `mail series pause SERIES_ID` sets paused (Off). Stored draft and paused both display Off. `mail series get/list` includes enrolledCount (waiting + current in progress/paused; excludes completed/cancelled) and waitingCount. `mail enrolments list` shows progress; cancel remains available while Off. The direct `mail send series` command also enrolls while Off and returns accepted enrollment IDs with no sends. Empty sends is not a delivery claim.
+
+Selections with IDs use a read-only `POST /api/v1/sites/YOUR_SITE/mail/people` body to avoid URL limits. Ordinary directory queries use GET. Both call the same scoped query; neither writes CRM records.
+
+## Settings and suppressions
+
+```bash
+frontpage mail settings set --header-align center --window-start 540 --window-end 1020 --hourly-cap 100 --site YOUR_SITE
+frontpage mail settings set --file settings.json --site YOUR_SITE --json
+```
+
+The settings JSON accepts exactly replyTo, postalLine, fromName, timezone, sendWindowStart, sendWindowEnd, hourlyCap and headerAlign. Omitted fields stay unchanged. Null clears replyTo, postalLine, fromName or hourlyCap. Window values are integer minutes after midnight (0–1439), hourlyCap is null or 1–1000, timezone is an IANA time zone, and headerAlign is left/center/right. A business postal address is still required for actual marketing sends. `--hourly-cap null` clears that cap. A settings save, content edit, read, cancellation or switch Off does not depend on the send meter.
+
+`mail suppress list|add|rm` uses the existing site suppression service. Adding stops that site's marketing campaigns/series and cancels active enrollments. Transactional receipts and support replies follow separate rules. Removing a suppression does not restore consent, resubscribe someone or restart cancelled series.
+
+## Sent history
+
+```bash
+frontpage mail sends list --q alex --status delivered --type campaign --page 1 --limit 20 --site YOUR_SITE --json
+frontpage mail sends get SEND_ID --site YOUR_SITE --json
+```
+
+Types: campaign, series, confirmation, template, test, inline. Search matches recipient/subject across all permitted rows. Status uses the stored ledger value (pending/claimed are queued). Count and numbered pages use the same site/filter scope, ordered by creation time then ID. Existing cursor pagination remains available; use either cursor or page. `createdAt` is queue creation, not delivery time. Details expose saved content, current status/error, attempts and source availability; preview sender/brand details use current settings. Deleted source records do not delete history. No resend/requeue action is added.
+
+## Internal agent parity
+
+The owner agent uses the same services through save_mail_editor, get_mail_people, get_mail_send, update_mail_series, set_mail_series_steps, set_mail_settings and the existing send/preview/enrollment tools. remove_mail_suppression matches the CLI's existing authorized removal. Discuss and Build register the same Email capabilities. Tool schemas and runtime instructions describe complete saves, Off enrollment, waiting/resume timing, all settings/null resets, history filters and retry handling. The agent never takes site authority from model input.
+
+Hosted developer guides and article bodies must be updated through the supported Frontpage CLI, using current base revisions. Never edit a customer site's Git branch or invent a second API version for this cutover.

package/PAYMENTS.md

@@ -467,3 +467,44 @@ payment count, and average payment, grouped by currency. Gross is before fees an
 refunds. Schedules are not received money. Metrics cover the full recorded period,
 not only the capped Activity rows. Dates use verified successful-payment times;
 older records without proof show that the date is unavailable.
+
+
+## Standalone setup and digital download receipts
+
+An Offering is a standalone payment. Creating, updating or restoring it requests
+Payments setup if needed. The shared response includes `checkout:"standalone"`,
+`requiresFulfillment:false`, the saved `button`, and `setup.status` plus the existing
+signed-in owner Stripe handoff. Store availability, shipping and pickup do not gate
+an Offering. Payments off stays off. A saved `button.active:false` is a draft;
+accepting payments requires both an active Offering and `setup.status.ready:true`.
+`get` reports the same readiness under `payment`. A repeated create with the same
+ID returns 409; read that ID and update it rather than creating another payment.
+
+For an e-book, consultation resource or other download, reuse uploaded files or
+owner-approved URLs. One combined file or several files can work. Add those links
+to an Emails template, attach it using `--receipt-template-id`, and preview it:
+
+```bash
+frontpage payments buttons create --id digital-bundle --title "E-book + workbook" --price-cents 2500 --active false --json
+frontpage payments buttons update digital-bundle --receipt-template-id TEMPLATE_UUID --json
+frontpage payments buttons receipt-preview digital-bundle --json
+frontpage payments buttons update digital-bundle --active true --json
+```
+
+`receipt-preview` requires CLI 0.2.10 or later. The other commands work in earlier
+versions. The owner must supply the real file links before enabling the Offering.
+A thank-you-only template does not deliver a download. Public uploaded links can
+be forwarded; this workflow does not create buyer-only or expiring downloads or
+native email attachments. Never manually send a receipt or subscribe the buyer to
+marketing. Verified payment triggers the existing receipt job and send limits.
+
+The preview endpoint is `POST /api/v1/sites/{slug}/payments/buttons/{id}/receipt-preview`.
+It requires editor access and accepts optional sample values in
+`{"vars":{"buyer_name":"Casey"}}`. Values must use the Offering's returned
+`receiptVariables`, with strings up to 32,000 characters. Excluded private answers
+cannot be supplied. No customer lookup, send or charge occurs. The response is
+`{"preview":true,"receipt":"custom","itemId":"digital-bundle","receiptTemplateId":"…","subject":"…","html":"…","text":"…"}`.
+With no custom template it returns `receipt:"stock"` and explains the standard
+purchase receipt; it does not fabricate a custom preview. Purchase previews use
+the actual transactional renderer. Marketing's postal-address requirement remains
+in place for marketing sends; its preview warning does not block purchase receipts.

package/PEOPLE.md

@@ -235,7 +235,7 @@ The simple editor offers Purchases, Activity, and Contact details. Existing adva
 | set\_follow\_up            | minutes                         | Set a follow-up after this many minutes.                        |
 | clear\_follow\_up          | —                               | Clear the person’s follow-up.                                   |
 | send\_template             | templateId                      | Send a saved template if eligible.                              |
-| start\_series              | seriesId                        | Start an active series with saved steps.                        |
+| start\_series              | seriesId                        | Enroll in a saved series. Off waits at step 1; On starts sending.                        |
 | cancel\_series             | seriesId                        | Stop this group’s enrollment; requires a group/stage trigger.   |
 
 A rule accepts 1–10 actions. Add/remove/move actions target manual groups; automatic groups use conditions and owner exceptions. `fromStageIds` prevents a late event from resetting someone who has moved further through the funnel.
@@ -301,7 +301,7 @@ Timed rules use minutes: 2880 is two days. They run through the worker, not a br
 
 ## Attach an email to a group or stage
 
-Use one action, **Attach an email**, then choose a saved email template or an active series. An attachment creates a normal editable rule on group entry or stage entry. Campaigns are one-off emails and cannot be selected for automation.
+Use one action, **Attach an email**, then choose a saved email template or a series with saved steps. An Off series enrolls people waiting at step 1; turning it On starts them. An attachment creates a normal editable rule on group entry or stage entry. Campaigns are one-off emails and cannot be selected for automation.
 
 Save a reusable template as `welcome.json`:
 
@@ -645,6 +645,6 @@ frontpage people workspace series.preview --site YOUR_SITE --data '{"seriesId":"
 
 To enrol, copy each returned batch's `personIds` and `reviewToken` into `series.enrol`, adding `seriesId` and a unique stable `requestKey`. Preview returns batches of five; the service accepts at most 25 per request. Reuse the original payload and key after a lost response. Results distinguish enrolled, already enrolled, skipped and failed. A new preview uses new keys. Never enrol or send without the user's explicit instruction.
 
-Manual series starts use selected person IDs, an active series and the normal queue. Confirmation queues its first email; saved delays schedule later steps. The review lists permission exclusions and remaining allowance. It never activates a paused series or restarts an existing enrolment, including one bound to a person whose email changed. Delivery rechecks saved restrictions. Contact groups and permission stay unchanged.
+Manual series enrollment uses selected person IDs and saved steps. Off records real enrollment waiting at step 1, without a send, snapshot, timer or allowance reservation; no second Save series is needed. On starts the first email subject to sender, permission, send window and allowance checks. Turning On resumes existing people at their next unsent step with its due date intact; later waits start after successful sends. Review returns status, exclusions and nullable remainingAllowance (null while Off). It never activates a series or restarts existing, completed or cancelled enrollment, including a person whose email changed. Delivery rechecks saved restrictions. Contact groups and permission stay unchanged. Campaign recipient intent also supports explicit addresses and null to clear; saving never sends or grants consent.
 
 People supplies first-name and unsubscribe values. If content uses order, booking or other caller-only variables, edit the independent campaign or choose another series. Do not invent values or send empty required context.

package/README.md

@@ -18,7 +18,7 @@ Requires Node.js ≥ 20.
 
 ## 60-second path
 
-1. In the Frontpage editor: profile menu → **Developers** → create an API key (`fp_live_…`).
+1. In Workspace: account menu → **Developers** → create an API key (`fp_live_…`).
 2. `frontpage login` (or `frontpage login "$FRONTPAGE_API_KEY"`).
 3. `frontpage sites` — note the **subdomain** (not a custom domain).
 4. `mkdir my-site && cd my-site && frontpage use <subdomain>`
@@ -90,3 +90,7 @@ frontpage store items get camp-hat --site my-site --json
 ```
 
 A whole stock count of `0` means sold out; `unlimited` sends JSON null. Omit stock on update to keep it. To rename existing option types, pass an `optionNames` list with the same number of names through `items update --file`. To return to one default SKU, pass `{"optionNames":[]}`. The existing first live variant supplies the regular price, sale price (including no sale), and stock (including unlimited). Inspect the live variants first and read back the result; other live variants are archived. Use `variants add` to turn options on. Do not recreate the product.
+
+## Emails workspace workflows
+
+See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.

package/dist/commands/login.js

@@ -18,7 +18,7 @@ export async function runLogin(args) {
         return EXIT_USAGE;
     }
     if (!secret.startsWith("fp_live_")) {
-        console.error("Key should start with fp_live_. Create one in Developers (profile menu).");
+        console.error("Key should start with fp_live_. Create one in Developers (Workspace account menu).");
         return EXIT_USAGE;
     }
     await setApiKey(secret);

package/dist/commands/mail.js

@@ -4,12 +4,13 @@ import { resolveSlug } from "../site.js";
 import { CliHttpError, EXIT_OK, EXIT_USAGE, exitCodeForError, v1Delete, v1Get, v1Patch, v1Post, v1Put, } from "../http/client.js";
 import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.js";
 import { emitErr, emitOk, isJson } from "../runtime.js";
-const USAGE = "Usage: frontpage mail settings|email|template|series|send|sends|enrolments|suppress … [--site <slug>] [--json]";
+const USAGE = "Usage: frontpage mail settings|email|template|series|save|people|send|sends|enrolments|suppress … [--site <slug>] [--json]";
 const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function requireId(work, kind) {
     const fromFlag = takeFlag(work, "--id");
     const positional = work.find((a) => !a.startsWith("-"));
-    const raw = fromFlag ?? (positional ? work.splice(work.indexOf(positional), 1)[0] : undefined);
+    const raw = fromFlag ??
+        (positional ? work.splice(work.indexOf(positional), 1)[0] : undefined);
     if (!raw || !ID_RE.test(raw)) {
         throw new CliHttpError(`${kind} not found.`, EXIT_USAGE, 404, "not_found");
     }
@@ -35,7 +36,10 @@ function parseVars(pairs) {
     return vars;
 }
 function parseRecipients(work) {
-    const tos = takeAll(work, "--to").flatMap((v) => v.split(",").map((s) => s.trim()).filter(Boolean));
+    const tos = takeAll(work, "--to").flatMap((v) => v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean));
     const name = takeFlag(work, "--name");
     const vars = parseVars(takeAll(work, "--var"));
     if (tos.length === 0) {
@@ -83,6 +87,45 @@ export async function runMail(args) {
         if (group === "campaign")
             return await runCampaign(slug, rest.slice(1));
         const base = `/api/v1/sites/${encodeURIComponent(slug)}/mail`;
+        if (group === "save") {
+            const work = rest.slice(1), file = takeFlag(work, "--file");
+            assertNoUnknownFlags(work, "mail");
+            if (!file)
+                throw new CliHttpError("Use mail save --file save.json. Keep its requestKey and payload unchanged for retries.", EXIT_USAGE, 0, "bad_request");
+            const data = await v1Post(`${base}/save`, await readJsonFile(file));
+            if (isJson())
+                emitOk("mail", data);
+            else
+                console.log("Email and series changes saved.");
+            return EXIT_OK;
+        }
+        if (group === "people") {
+            const work = rest.slice(1), params = new URLSearchParams();
+            for (const flag of [
+                "q",
+                "source",
+                "sort",
+                "availability",
+                "page",
+                "selected",
+            ]) {
+                const value = takeFlag(work, `--${flag}`);
+                if (value !== undefined)
+                    params.set(flag, value);
+            }
+            if (hasFlag(work, "--selected-only"))
+                params.set("selectedOnly", "true");
+            assertNoUnknownFlags(work, "mail");
+            const data = params.has("selected")
+                ? await v1Post(`${base}/people`, Object.fromEntries(params))
+                : await v1Get(`${base}/people?${params}`);
+            if (isJson())
+                emitOk("mail", data);
+            else
+                for (const p of (data.people ?? []))
+                    console.log(`${p.id}  ${p.email ?? ""}  ${p.eligible ? "eligible" : "restricted"}`);
+            return EXIT_OK;
+        }
         if (group === "settings") {
             const sub = rest[1] ?? "get";
             const work = rest.slice(2);
@@ -102,12 +145,29 @@ export async function runMail(args) {
                 const replyTo = takeFlag(work, "--reply-to");
                 const fromName = takeFlag(work, "--from-name");
                 const timezone = takeFlag(work, "--timezone");
+                const file = takeFlag(work, "--file"), headerAlign = takeFlag(work, "--header-align"), start = takeFlag(work, "--window-start"), end = takeFlag(work, "--window-end"), cap = takeFlag(work, "--hourly-cap");
+                const extra = file ? await readJsonFile(file) : {};
+                if (headerAlign !== undefined)
+                    extra.headerAlign = headerAlign;
+                if (start !== undefined)
+                    extra.sendWindowStart = Number(start);
+                if (end !== undefined)
+                    extra.sendWindowEnd = Number(end);
+                if (cap !== undefined) {
+                    if (cap !== "null" &&
+                        (!Number.isInteger(Number(cap)) ||
+                            Number(cap) < 1 ||
+                            Number(cap) > 1000))
+                        throw new CliHttpError("Hourly cap must be an integer from 1 to 1000, or null.", EXIT_USAGE, 0, "bad_request");
+                    extra.hourlyCap = cap === "null" ? null : Number(cap);
+                }
                 assertNoUnknownFlags(work, "mail");
                 const data = await v1Patch(`${base}/settings`, {
-                    postalLine: postal,
-                    replyTo,
-                    fromName,
-                    timezone,
+                    ...extra,
+                    ...(postal !== undefined ? { postalLine: postal } : {}),
+                    ...(replyTo !== undefined ? { replyTo } : {}),
+                    ...(fromName !== undefined ? { fromName } : {}),
+                    ...(timezone !== undefined ? { timezone } : {}),
                 });
                 if (isJson())
                     emitOk("mail", data);
@@ -222,7 +282,8 @@ export async function runMail(args) {
                 if (isJson())
                     emitOk("mail", data);
                 else
-                    console.log((data.preview ?? {}).subject ?? "Preview ready.");
+                    console.log((data.preview ?? {}).subject ??
+                        "Preview ready.");
                 return EXIT_OK;
             }
         }
@@ -256,7 +317,9 @@ export async function runMail(args) {
                 assertNoUnknownFlags(work, "mail");
                 if (!name)
                     throw new CliHttpError("Usage: frontpage mail series create --name …", EXIT_USAGE, 0, "bad_request");
-                const data = await v1Post(`${base}/series`, { name });
+                const data = await v1Post(`${base}/series`, {
+                    name,
+                });
                 if (isJson())
                     emitOk("mail", data);
                 else
@@ -310,7 +373,11 @@ export async function runMail(args) {
                 let steps = [];
                 if (file) {
                     const body = await readJsonFile(file);
-                    steps = Array.isArray(body.steps) ? body.steps : Array.isArray(body) ? body : [];
+                    steps = Array.isArray(body.steps)
+                        ? body.steps
+                        : Array.isArray(body)
+                            ? body
+                            : [];
                 }
                 else {
                     steps = stepFlags.map(parseStepFlag);
@@ -350,8 +417,14 @@ export async function runMail(args) {
                 const id = requireId(restKind, kind === "series" ? "Series" : "Document");
                 const recipients = parseRecipients(restKind);
                 assertNoUnknownFlags(restKind, "mail");
-                const path = kind === "series" ? `${base}/series/${id}/send` : `${base}/${kind === "email" ? "emails" : "templates"}/${id}/send`;
-                const data = await v1Post(path, { recipients, wait, test });
+                const path = kind === "series"
+                    ? `${base}/series/${id}/send`
+                    : `${base}/${kind === "email" ? "emails" : "templates"}/${id}/send`;
+                const data = await v1Post(path, {
+                    recipients,
+                    wait,
+                    test,
+                });
                 if (isJson())
                     emitOk("mail", data);
                 else
@@ -365,10 +438,16 @@ export async function runMail(args) {
             const work = rest.slice(2);
             if (sub === "list") {
                 const batchId = takeFlag(work, "--batch");
+                const filters = new URLSearchParams();
+                for (const flag of ["q", "status", "type", "page"]) {
+                    const value = takeFlag(work, `--${flag}`);
+                    if (value !== undefined)
+                        filters.set(flag, value);
+                }
                 const limit = takeFlag(work, "--limit");
                 const cursor = takeFlag(work, "--cursor");
                 assertNoUnknownFlags(work, "mail");
-                const params = new URLSearchParams();
+                const params = filters;
                 if (batchId)
                     params.set("batchId", batchId);
                 if (limit)
@@ -402,8 +481,13 @@ export async function runMail(args) {
             const work = rest.slice(2);
             if (sub === "list") {
                 const seriesId = takeFlag(work, "--series");
-                assertNoUnknownFlags(work, "mail");
                 const params = new URLSearchParams();
+                for (const name of ["q", "offset", "limit"]) {
+                    const value = takeFlag(work, `--${name}`);
+                    if (value !== undefined)
+                        params.set(name, value);
+                }
+                assertNoUnknownFlags(work, "mail");
                 if (seriesId)
                     params.set("seriesId", seriesId);
                 const qs = params.toString();
@@ -437,7 +521,8 @@ export async function runMail(args) {
                 if (isJson())
                     emitOk("mail", data);
                 else {
-                    const rows = data.suppressions ?? [];
+                    const rows = data.suppressions ??
+                        [];
                     for (const row of rows)
                         console.log(`${row.email ?? ""}  ${row.reason ?? ""}`);
                 }

package/dist/commands/payments.js

@@ -185,6 +185,11 @@ export async function runPayments(args) {
                 method = "PATCH";
                 body = await payload(work);
             }
+            else if (sub === "receipt-preview") {
+                path = `buttons/${idOf(work)}/receipt-preview`;
+                method = "POST";
+                body = await payload(work);
+            }
             else if (sub === "archive" || sub === "restore") {
                 path = `buttons/${idOf(work)}/${sub}`;
                 method = "POST";
@@ -192,7 +197,7 @@ export async function runPayments(args) {
                 confirm(body, sub === "restore" ? "Restore this offering" : "Delete this offering from new payments");
             }
             else
-                usage("Use payments buttons list|get|create|update|archive|restore.");
+                usage("Use payments buttons list|get|create|update|archive|restore|receipt-preview.");
         }
         else if (group === "activity") {
             const sub = work.shift() ?? "list";

package/dist/completions/generate.js

@@ -28,6 +28,7 @@ _frontpage_completions() {
     people) COMPREPLY=( $(compgen -W "list get add set note rm-note follow-up hide unhide" -- "\${cur}") ) ;;
     routines) COMPREPLY=( $(compgen -W "list get add set pause resume rm run runs" -- "\${cur}") ) ;;
     buttons) COMPREPLY=( $(compgen -W "list get create update archive restore" -- "\${cur}") ) ;;
+    mail) COMPREPLY=( $(compgen -W "save people campaign settings email template series send sends enrolments suppress --file --q --status --type --page --limit --cursor --source --sort --availability --selected --selected-only --offset --header-align --window-start --window-end --hourly-cap --site --json" -- "\${cur}") ) ;;
     payments) COMPREPLY=( $(compgen -W "status settings connect availability activity buttons tax invoices recurring customers --file --operation-key --preview-hash --person --email --description --amount-cents --cadence --first-date --time-zone --due-days --no-open --site --json --yes" -- "\${cur}") ) ;;
     store) COMPREPLY=( $(compgen -W "items variants categories settings orders import" -- "\${cur}") ) ;;
     modules)
@@ -74,6 +75,7 @@ _frontpage() {
         analytics) _values 'subcommand' dashboard summary query funnel timeseries compare sql ;;
         people) _values 'subcommand' list get add set note rm-note follow-up hide unhide ;;
         routines) _values 'subcommand' list get add set pause resume rm run runs ;;
+        mail) _values 'subcommand' save people campaign settings email template series send sends enrolments suppress ;;
         buttons) _values 'subcommand' list get create update archive restore ;;
         payments) _values 'subcommand' status settings connect availability activity buttons tax invoices recurring customers ;;
         store) _values 'subcommand' items variants categories settings orders import ;;
@@ -114,6 +116,7 @@ export function generateFishCompletion() {
         `complete -c frontpage -n "__fish_seen_subcommand_from analytics" -a "dashboard summary query funnel timeseries compare sql"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from people" -a "list get add set note rm-note follow-up hide unhide"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from routines" -a "list get add set pause resume rm run runs"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from mail" -a "save people campaign settings email template series send sends enrolments suppress"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from buttons" -a "list get create update archive restore"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from payments" -a "status settings connect availability activity buttons tax invoices recurring customers"
 complete -c frontpage -n "__fish_seen_subcommand_from store" -a "items variants categories settings orders import"`,

package/dist/registry.js

@@ -38,9 +38,9 @@ export const COMMANDS = [
         summary: "Save an API key to the OS keychain",
         usage: "frontpage login [api-key]",
         topics: ["auth"],
-        examples: ['frontpage login', 'frontpage login "$FRONTPAGE_API_KEY"'],
+        examples: ["frontpage login", 'frontpage login "$FRONTPAGE_API_KEY"'],
         flags: [
-            "FRONTPAGE_API_KEY env overrides keychain after login for that process"
+            "FRONTPAGE_API_KEY env overrides keychain after login for that process",
         ],
         seeAlso: ["whoami", "doctor", "logout"],
     },
@@ -71,7 +71,7 @@ export const COMMANDS = [
         topics: ["auth", "sync"],
         examples: ["frontpage use arbiter"],
         dangers: [
-            "Clears baseCommitSha when switching sites — run pull again before push"
+            "Clears baseCommitSha when switching sites — run pull again before push",
         ],
         seeAlso: ["link", "pull", "status"],
     },
@@ -207,7 +207,7 @@ export const COMMANDS = [
         examples: [
             "frontpage open",
             "frontpage open /updates",
-            "frontpage open --path /pricing"
+            "frontpage open --path /pricing",
         ],
         flags: [
             "Optional site-relative path appended to https://<slug>.frontpage.host",
@@ -424,14 +424,14 @@ export const COMMANDS = [
             "frontpage customer-inbox get settings",
             "frontpage customer-inbox put settings --file ./inbox-settings.json --request-key settings_revision_1",
             "frontpage customer-inbox get conversations",
-            "frontpage customer-inbox get knowledge"
+            "frontpage customer-inbox get knowledge",
         ],
         flags: [
             "Internal plans and the site pilot apply",
             "Writes require a stable --request-key and a JSON file; reuse both on retries",
             "Human CLI access can guide, take over and reply; website-agent tools have management scope only",
             "Luna and 10× AI billing are fixed",
-            "Full request examples: CUSTOMER-INBOX.md"
+            "Full request examples: CUSTOMER-INBOX.md",
         ],
         seeAlso: ["people", "usage"],
     },
@@ -449,7 +449,7 @@ export const COMMANDS = [
         topics: ["content"],
         examples: [
             "frontpage routines list",
-            "frontpage routines add --cadence weekly --weekdays tue,thu,fri --hours 8am,12pm,4pm --timezone America/Chicago --name \"Weekday check\" --prompt \"Review new form submissions and reply to each customer.\"",
+            'frontpage routines add --cadence weekly --weekdays tue,thu,fri --hours 8am,12pm,4pm --timezone America/Chicago --name "Weekday check" --prompt "Review new form submissions and reply to each customer."',
             "frontpage routines pause <id>",
             "frontpage routines resume <id>",
             "frontpage routines run <id>",
@@ -480,8 +480,8 @@ export const COMMANDS = [
             "frontpage people list",
             "frontpage people add --email alex@example.com --name Alex",
             "frontpage people set <id> --status working",
-            "frontpage people set <id> --line1 \"12 Main\" --city Austin --region TX --postal 78701 --country US",
-            "frontpage people note <id> --body \"Called them\"",
+            'frontpage people set <id> --line1 "12 Main" --city Austin --region TX --postal 78701 --country US',
+            'frontpage people note <id> --body "Called them"',
             "frontpage people follow-up <id> --at 2026-09-12T00:00:00Z",
             "frontpage people hide <id>",
             "frontpage people tag <id> --add vip",
@@ -549,7 +549,7 @@ export const COMMANDS = [
             "status; settings; connect [--no-open]. Connect returns an existing signed-in admin browser handoff; it never accepts Stripe terms or completes onboarding.",
             "availability preview|on|off. off reads affected counts before confirmed pause/void; a partial response stays off and requires another off request. on never resumes stopped billing or restores void invoices.",
             "activity list|get <id> --source order|payment. invoices and recurring have separate get commands. Source IDs never collide.",
-            "buttons list [--limit 1..100 --offset N --archived true]; get|create|update|archive|restore. These manage Offerings. Create uses --id, --title, --price-cents, optional --amount open --min-cents. Create/update support --description, --active true|false, --receipt-template-id UUID or --default-receipt, and --file. Price, details and template save together. Archive deletes from new payments while retaining history; archive/restore require --yes. Only registered Offerings authorize Pay now; page markup and Store flags never do.",
+            "buttons list [--limit 1..100 --offset N --archived true]; get|create|update|archive|restore|receipt-preview. These manage Offerings. receipt-preview <id> [--file samples.json] renders the attached purchase receipt without sending or charging; samples.json can contain sample receipt variables under vars. Create uses --id, --title, --price-cents, optional --amount open --min-cents. Create/update support --description, --active true|false, --receipt-template-id UUID or --default-receipt, and --file. Price, details and template save together. Archive deletes from new payments while retaining history; archive/restore require --yes. Saves request Payments setup when needed and return setup.status; they never enable Store or override Payments off. Only registered Offerings authorize Pay now; page markup and Store flags never do.",
             "Offering create/get/update JSON includes receiptVariables. Use exact names in existing mail templates, then attach --receipt-template-id. Included answers expose answer_<customizationId>; private answers are excluded. Currency is owned by Payments, not Store.",
             "tax get; tax settings --file <file> --yes; tax registrations list|add --country US --state CA --yes|end <id> --yes. Supply the business's actual tax registrations. No automatic tax advice or raw Account Session secrets.",
             "invoices preview|send --file <file>; list [--limit 1..100 --offset N --arrangement <id>]; get|refresh|resend|void <id>. send/resend need --operation-key; send needs --preview-hash; financial writes require --yes in scripts.",
@@ -573,10 +573,10 @@ export const COMMANDS = [
     {
         name: "mail",
         summary: "Emails: campaign drafts, People audiences, templates, series, and sends",
-        usage: "frontpage mail settings|email|template|series|campaign|send|sends|enrolments|suppress … [--site <slug>] [--json]",
+        usage: "frontpage mail save|people|settings|email|template|series|campaign|send|sends|enrolments|suppress … [--site <slug>] [--json]",
         topics: ["content"],
         examples: [
-            "frontpage mail settings set --postal \"100 Main St\" --reply-to you@example.com",
+            'frontpage mail settings set --postal "100 Main St" --reply-to you@example.com',
             "frontpage mail email create --file draft.json --name Hours",
             "frontpage mail send --file email.json --to ada@example.com --wait",
             "frontpage mail send template <id> --to ada@example.com --var first_name=Ada",
@@ -584,6 +584,11 @@ export const COMMANDS = [
             "frontpage mail suppress add --email bounce@example.com",
         ],
         flags: [
+            "save --file save.json: one retry-safe email/series save; existing records need expectedUpdatedAt. See MAIL.md.",
+            "people --q --source --sort newest|oldest|name --availability all|eligible|restricted --page --selected --selected-only.",
+            "settings set --file settings.json supports all eight fields and null resets; --header-align, --window-start, --window-end, --hourly-cap null|1..1000.",
+            "sends list --q --status --type campaign|series|confirmation|template|test|inline --page 1 --limit 20.",
+            "Series status active means On; paused/draft mean Off. Enrollment while Off waits at step 1, without sending. Existing people resume their next unsent step.",
             "campaign preview|audience|send|get. --id DRAFT_ID, --file audience.json ({audience:{groupIds|stageIds|personIds|filters}}). send requires --request-key; reuse it after a network error. Templates/series are for automation; campaigns have separate drafts. See PEOPLE.md.",
             "email list is unsent drafts only. Sent one-offs are mail sends list",
             "send --file is an inline one-off (no saved document)",
@@ -617,10 +622,10 @@ export const COMMANDS = [
         examples: [
             "frontpage seo get /",
             "frontpage seo get --path /updates",
-            "frontpage seo set --path / --title \"Home\"",
+            'frontpage seo set --path / --title "Home"',
         ],
         flags: [
-            "get accepts positional path or --path (flag wins); unknown leftover flags fail closed"
+            "get accepts positional path or --path (flag wins); unknown leftover flags fail closed",
         ],
     },
     {
@@ -694,7 +699,7 @@ export const TOPICS = {
   # Binary is: frontpage
   # Do NOT install the unrelated npm package named "frontpage"
 
-  1. Create a key: Frontpage editor → profile → Developers (fp_live_…)
+  1. Create a key: Workspace → account menu → Developers (fp_live_…)
   2. frontpage login               # or: frontpage login "$FRONTPAGE_API_KEY"
   3. frontpage sites               # use the subdomain column
   4. mkdir work && cd work && frontpage use <subdomain>
@@ -712,7 +717,7 @@ export const TOPICS = {
   Agents: read AGENTS.md + frontpage help site-building; use --json for structured I/O.
   More: frontpage help auth | sync | site-building | agent | content | history | isolation | exit-codes`,
     auth: `Authentication
-  1. Create a key in the Frontpage editor: profile menu → Developers
+  1. Create a key in Workspace: account menu → Developers
   2. frontpage login
   3. frontpage sites
   4. frontpage use <subdomain>   (e.g. asimov-press, not a custom domain)
@@ -838,7 +843,7 @@ export const TOPICS = {
   # Store catalog + live storefront: https://frontpage.host/developers/store
   # Integer cents only. $49.99 is 4999. stock --add/--remove are signed delta.
   # Markup: data-fp-store-grid / data-fp-store-product / data-fp-cart. One item.astro, not one file per product.
-  frontpage mail settings|email|template|series|send|sends|enrolments|suppress
+  frontpage mail save|people|settings|email|template|series|send|sends|enrolments|suppress
   frontpage seo get [/path|--path /path] | seo set --path /
   frontpage redirects list|set|rm --from /old --to /new
   frontpage articles list|content|create-section|create-article|set-draft|…

package/llms.txt

@@ -42,8 +42,12 @@ Customer Inbox (Scale and internal sites): CUSTOMER-INBOX.md. Settings, widget,
 Payments, invoices and recurring billing: see packaged [PAYMENTS.md](./PAYMENTS.md), `frontpage help payments`, and https://frontpage.host/developers/payments. Version 0.2.0 removes writable currency, Store checkout mode and Store-owned money commands; Store stays cart-only. Preview/review before sends; keep stable operation keys on retries. Autopay requires the customer’s own verified authorization.
 
 
-Offerings own every standalone Pay now payment. Use `frontpage payments buttons list|get|create|update|archive|restore`; create the saved offering before adding its returned `data-fp-pay` markup. Supports `--receipt-template-id UUID`, `--default-receipt`, `--active true|false`, combined price/details updates and JSON payloads. Archive deletes from active checkout but preserves history. The website agent uses the same service automatically for ordinary payment-button requests. Store stays cart-only; invoices stay saved customer-addressed records. Full instructions: PAYMENTS.md and https://frontpage.host/developers/payments.
+Offerings own every standalone Pay now payment. Use `frontpage payments buttons list|get|create|update|archive|restore|receipt-preview`; create the saved offering before adding its returned `data-fp-pay` markup. Supports `--receipt-template-id UUID`, `--default-receipt`, `--active true|false`, combined price/details updates and JSON payloads. Archive deletes from active checkout but preserves history. The website agent uses the same service automatically for ordinary payment-button requests. Store stays cart-only; invoices stay saved customer-addressed records. Create/update/restore return setup.status and the existing Stripe handoff, without enabling Store or overriding Payments off. Preview a bound receipt with buttons receipt-preview; it never sends or charges. Digital delivery uses approved file links in the saved purchase receipt; keep the offering inactive until resources are ready. Full instructions: PAYMENTS.md and https://frontpage.host/developers/payments.
 
 Payments owns Stripe currency. Read Offering receiptVariables before creating a confirmation template; attach it through Payments. Forms use submitted input names. Full receipt contract: PAYMENTS.md.
 
 Customer Inbox: Frontpage website chat uses one settings toggle, no website edit/publish. get website shows public availability/managed addresses. websiteKnowledge.enabled controls default-on support website reads; no source or private-preview access. Source-ID toggles, attention filtering and held receipt pagination are supported. See CUSTOMER-INBOX.md.
+
+## Emails workspace workflows
+
+See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontpage-host",
-  "version": "0.2.9",
-  "description": "Frontpage CLI — manage your site from the terminal",
+  "version": "0.2.11",
+  "description": "Frontpage CLI \u2014 manage your site from the terminal",
   "type": "module",
   "bin": {
     "frontpage": "dist/bin.js"
@@ -12,6 +12,7 @@
     "AGENTS.md",
     "llms.txt",
     "PEOPLE.md",
+    "MAIL.md",
     "CUSTOMER-INBOX.md",
     "PAYMENTS.md"
   ],