frontpage-host 0.2.8 → 0.2.10

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).
 
@@ -129,7 +129,7 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
 - People CRM: `frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|tag|export`. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget. List export is CSV (not a one-person legal dump). Full guide: https://frontpage.host/developers/people
 - Routines: `frontpage routines list|get|add|set|pause|resume|rm|run|runs`. One routine can hold several hours and several days. `8am,12pm,4pm` on `tue,thu,fri` stores hours `[8, 12, 16]` and weekdays `[2, 4, 5]`. Ask for an IANA timezone. Do not guess UTC. Full guide: https://frontpage.host/developers/routines
-- Store catalog: `frontpage store items|variants|categories|settings|orders|import`. Integer cents only (`$49.99` is `4999`). `--price-cents` is the usual cost. Optional `--discount-cents` is the sale the buyer pays (must be lower). End a sale with `frontpage store variants update <itemId> --id <variantId> --clear-discount`. This sends discountPriceCents: null and keeps the regular price. Omit both sale flags on update to preserve the current sale. Do not combine --clear-discount with --discount-cents; 0 means free, not removal. Read the item back to verify. Create a category before assigning it. Photos are a site path `/__media/uploads/<this-slug>/…` or an HTTPS URL already saved on this site. `frontpage payments connect [--no-open]` opens Frontpage then Stripe. Store always uses Add to cart. Use Payments for standalone Pay now and invoices. Service fee is `settings set-checkout-fee`. The cart starts hidden. Product pages are the default: unless they said they do not want product pages, write one `src/pages/products/item.astro` (or shop) with `data-fp-store-product`. If they said no, skip that file and do not bind `href` or `url`. Description is a small markdown subset; product-page bind is `<div data-fp-store-bind="description">`. Every store control carries `data-fp-requires="store"`. Do not bake titles or prices. Full guide: https://frontpage.host/developers/store
+- Store catalog: `frontpage store items|variants|categories|settings|orders|import`. Integer cents only (`$49.99` is `4999`). `--price-cents` is the usual cost. Optional `--discount-cents` is the sale the buyer pays (must be lower). End a sale with `frontpage store variants update <itemId> --id <variantId> --clear-discount`. This sends discountPriceCents: null and keeps the regular price. Omit both sale flags on update to preserve the current sale. Do not combine --clear-discount with --discount-cents; 0 means free, not removal. Read the item back to verify. Stock: use --stock unlimited on variants update or items stock --set unlimited; zero is sold out. Omit stock on update to preserve it. Rename option types or return to one SKU with items update --file, preserving the surviving variant’s regular price, sale and stock. Create a category before assigning it. Photos are a site path `/__media/uploads/<this-slug>/…` or an HTTPS URL already saved on this site. `frontpage payments connect [--no-open]` opens Frontpage then Stripe. Store always uses Add to cart. Use Payments for standalone Pay now and invoices. Service fee is `settings set-checkout-fee`. The cart starts hidden. Product pages are the default: unless they said they do not want product pages, write one `src/pages/products/item.astro` (or shop) with `data-fp-store-product`. If they said no, skip that file and do not bind `href` or `url`. Description is a small markdown subset; product-page bind is `<div data-fp-store-bind="description">`. Every store control carries `data-fp-requires="store"`. Do not bake titles or prices. Full guide: https://frontpage.host/developers/store
 
 ## Agent prompt loop
 
@@ -266,8 +266,10 @@ 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.

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/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/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>`
@@ -77,3 +77,16 @@ frontpage store items get camp-hat --site my-site --json
 ```
 
 `--price-cents` sets the regular price. `--discount-cents` sets a lower sale price. `--clear-discount` removes the sale and keeps the regular price; it sends `discountPriceCents: null`. Omit both sale flags on update to keep the current sale. Do not combine them. A sale price of `0` means free, not sale removal. Repeat for each live variant when ending a sale across the catalog. Store prices update live; a page publish or banner removal does not clear discounts.
+
+
+### Store inventory and product options
+
+CLI 0.2.9 adds `items update --file`; explicit flags override file values.
+
+```bash
+frontpage store variants update camp-hat --id default --stock unlimited --site my-site
+frontpage store items stock camp-hat --set unlimited --site my-site
+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.

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/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/commands/shop.js

@@ -275,6 +275,7 @@ export async function runShop(args) {
             }
             if (sub === "update") {
                 const itemId = requireShopId(work);
+                const file = takeFlag(work, "--file");
                 const title = takeFlag(work, "--title");
                 const description = takeFlag(work, "--description");
                 const amount = takeFlag(work, "--amount");
@@ -284,7 +285,13 @@ export async function runShop(args) {
                 const categories = parseCsv(takeFlag(work, "--categories"));
                 const images = parseUrls(work);
                 assertNoUnknownFlags(work, "store");
-                const body = {};
+                const body = file ? await readJsonFile(file) : {};
+                if (file) {
+                    const allowed = new Set(["title", "description", "images", "checkout", "amount", "minCents", "requiresShipping", "extraShippingCents", "active", "optionNames", "categories", "categorySlugs", "customizations"]);
+                    const unknown = Object.keys(body).filter(key => !allowed.has(key));
+                    if (unknown.length)
+                        throw new CliHttpError(`Unsupported items update file field: ${unknown.join(", ")}. Use variant commands for SKU changes.`, EXIT_USAGE, 0, "bad_request");
+                }
                 if (title !== undefined)
                     body.title = title;
                 if (description !== undefined)

package/dist/registry.js

@@ -520,6 +520,7 @@ export const COMMANDS = [
             "variants update <itemId> --id <variantId> --clear-discount ends a sale and preserves the regular price. --discount-cents sets a sale; omit both on update to preserve it. The flags cannot be combined. 0 means free, not removal. Verify with items get. Prices update live.",
             "Descriptions use a small markdown subset. Bind data-fp-store-bind=description for the full product story; do not bake titles, prices or images into the page. Store is cart-only; use Payments for explicit Pay now.",
             "items stock uses --add/--remove as a signed delta, or --set/--unlimited. Never combine these verbs. Product pages use data-fp-store-product and the platform cart templates. Store prices read the shared currency owned by Payments.",
+            "variants update --stock unlimited or items stock --set unlimited restores unlimited stock; 0 means sold out; omit stock on update to preserve it. items update --file supports optionNames: same-length rename or [] to return to one SKU, preserving the first live variant price/sale/stock. Read items get before and after.",
             "variants add|update|archive|restore; categories list|create|rename|archive. Create categories before assigning their slugs.",
             "settings get|set-fulfillment|set-checkout-fee|set-receipt|availability get|on|off. Fee mode flat uses --cents; percent uses --bps (250 is 2.5%). Receipt takes --template <id> or --stock. Availability requires admin and --yes in scripts.",
             "orders list|get; import explicitly reads the existing site product files. No fleet import or data conversion occurs.",
@@ -548,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.",
@@ -693,7 +694,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>
@@ -711,7 +712,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)

package/llms.txt

@@ -18,7 +18,7 @@
 - Redirects: frontpage redirects list|set|rm — HTTP 301/308, instant, not a file; revert does not undo; do not fake with Astro.redirect / meta refresh
 - People CRM: frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|tag|export. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget. List export is CSV. Unknown leftover flags fail closed. Guide: https://frontpage.host/developers/people
 - Routines: frontpage routines list|get|add|set|pause|resume|rm|run|runs. Several hours and several days are one routine. 8am,12pm,4pm and tue,thu,fri store hours [8, 12, 16] and weekdays [2, 4, 5]. Timezone is IANA. Do not guess UTC. Guide: https://frontpage.host/developers/routines
-- Store catalog: frontpage store items|variants|categories|settings|orders|import. Integer cents only ($49.99 is 4999). --price-cents is the usual cost. Optional --discount-cents is the sale the buyer pays (must be lower). End a sale with `frontpage store variants update <itemId> --id <variantId> --clear-discount`. This sends discountPriceCents: null and keeps the regular price. Omit both sale flags on update to preserve the current sale. Do not combine --clear-discount with --discount-cents; 0 means free, not removal. Read the item back to verify. Create a category before assigning it. Photos are /__media/uploads/<this-slug>/… or an HTTPS URL already saved on this site. frontpage payments connect [--no-open] opens Frontpage then Stripe. Store is cart-only; currency comes from Stripe and cannot be set. Use frontpage payments for standalone Pay now and invoices. Service fee is settings set-checkout-fee. The cart starts hidden. Product pages are the default: unless they said they do not want product pages, write one src/pages/products/item.astro (or shop) with data-fp-store-product. If they said no, skip that file and do not bind href or url. Description is a small markdown subset; product-page bind is <div data-fp-store-bind="description">. Every store control carries data-fp-requires="store". Leave data-fp-store-variants empty. Do not bake titles or prices. Guide: https://frontpage.host/developers/store
+- Store catalog: frontpage store items|variants|categories|settings|orders|import. Integer cents only ($49.99 is 4999). --price-cents is the usual cost. Optional --discount-cents is the sale the buyer pays (must be lower). End a sale with `frontpage store variants update <itemId> --id <variantId> --clear-discount`. This sends discountPriceCents: null and keeps the regular price. Omit both sale flags on update to preserve the current sale. Do not combine --clear-discount with --discount-cents; 0 means free, not removal. Read the item back to verify. Stock: use --stock unlimited on variants update or items stock --set unlimited; zero is sold out. Omit stock on update to preserve it. Rename option types or return to one SKU with items update --file, preserving the surviving variant’s regular price, sale and stock. Create a category before assigning it. Photos are /__media/uploads/<this-slug>/… or an HTTPS URL already saved on this site. frontpage payments connect [--no-open] opens Frontpage then Stripe. Store is cart-only; currency comes from Stripe and cannot be set. Use frontpage payments for standalone Pay now and invoices. Service fee is settings set-checkout-fee. The cart starts hidden. Product pages are the default: unless they said they do not want product pages, write one src/pages/products/item.astro (or shop) with data-fp-store-product. If they said no, skip that file and do not bind href or url. Description is a small markdown subset; product-page bind is <div data-fp-store-bind="description">. Every store control carries data-fp-requires="store". Leave data-fp-store-variants empty. Do not bake titles or prices. Guide: https://frontpage.host/developers/store
 - Analytics funnel: --steps JSON array or comma paths (/, /pricing); bad JSON → Invalid JSON for --steps
 - Modules: unknown key errors list Known: …; mailing list module key is signups (not subscribe)
 - Errors: --json API envelopes include requestId when the server returned one; local validation omits requestId/httpStatus; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait = agent idle + tip compile ready (fail-closed / compile timeout → exit 2); push --wait and publish --wait wait for GET /deploy ready
@@ -42,7 +42,7 @@ 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {