frontpage-host 0.1.28 → 0.2.0

package/AGENTS.md

@@ -119,7 +119,7 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 ## Modules & articles
 
 - Forms: `data-fp-form` markup in pages + `frontpage modules` for enable/config. No submit JS / honeypot / `action`. Do not put a CRM webhook or token in HTML.
-- Connect-once modules: Store Stripe connect is `frontpage store connect`. `--no-open` for CI. `request-setup` remains valid when you want the **editor amber bar** instead. Payments and the store share one Stripe account — payments disconnect fails if the store still uses it. Auto-active modules (forms/callbar/…) need markup, not request-setup. Typed settings: `frontpage modules callbar|forms|booking|signups get|set` (forms set needs `--instance`; do not target `default`). Form destinations (HubSpot / Pipedrive / Privyr): connect once, then attach each form. `frontpage modules forms destinations|connect-destination|attach-destination|detach-destination|remove-destination --yes|request-destination-setup`. Token write is **admin**; `request-destination-setup` lights the editor amber bar (**editor** key). Do not use `request-setup forms` for a CRM (no-op). Connecting does not attach every form. Privyr: paste the Incoming Webhook URL from Automations → Lead Sources → Webhooks (`https://www.privyr.com/api/v1/incoming-leads/…`), not a token and not Outgoing Webhooks. HubSpot: Development → Keys → Service keys or Development → Legacy apps → Auth → Show token. Pipedrive: profile → Company settings → Personal preferences → API. Full docs: https://frontpage.host/developers/modules#forms-destinations. `frontpage modules <key>` prints that key's CLI usage (exit 2). Index: https://frontpage.host/developers/modules. Store: https://frontpage.host/developers/store
+- Connect-once modules: Store Stripe connect is `frontpage payments connect`. `--no-open` for CI. `request-setup` remains valid when you want the **editor amber bar** instead. Payments and Store share one Stripe account. Pause Payments through its availability action; generic module writes cannot bypass invoice/recurring stop rules. Auto-active modules (forms/callbar/…) need markup, not request-setup. Typed settings: `frontpage modules callbar|forms|booking|signups get|set` (forms set needs `--instance`; do not target `default`). Form destinations (HubSpot / Pipedrive / Privyr): connect once, then attach each form. `frontpage modules forms destinations|connect-destination|attach-destination|detach-destination|remove-destination --yes|request-destination-setup`. Token write is **admin**; `request-destination-setup` lights the editor amber bar (**editor** key). Do not use `request-setup forms` for a CRM (no-op). Connecting does not attach every form. Privyr: paste the Incoming Webhook URL from Automations → Lead Sources → Webhooks (`https://www.privyr.com/api/v1/incoming-leads/…`), not a token and not Outgoing Webhooks. HubSpot: Development → Keys → Service keys or Development → Legacy apps → Auth → Show token. Pipedrive: profile → Company settings → Personal preferences → API. Full docs: https://frontpage.host/developers/modules#forms-destinations. `frontpage modules <key>` prints that key's CLI usage (exit 2). Index: https://frontpage.host/developers/modules. Store: https://frontpage.host/developers/store
 - Google reviews: platform nodes only (`data-fp-google-reviews` / `data-fp-google-ask` + required `data-fp-requires="google_reviews"`). `data-layout` is `feed` (default), `badge`, or `link`. Never invent stars, quotes, a 1–10, or a Maps URL. Do not pick a Place ID via Autocomplete and do not write `placeId` through `modules config`. Owner-supplied Place ID / Maps URL: `frontpage modules google_reviews connect --place-id …` or `--maps-url …` (server resolves + seeds). Curation: `list-reviews`, `hide --id`, `show --id`, `set-stars`, `set-sort`, `set-weight`, `reset-weights`, `refresh`, `disconnect`. Usage: `frontpage modules google_reviews`. Docs: https://frontpage.host/developers/modules/google-reviews. Ask-widget scores: `frontpage inbox google_reviews`.
 - Articles: `frontpage articles …` for lifecycle; bodies via sync under `content/` or `articles content get|set`. Section landing is an owned `src/pages/<section>/index.astro`.
 - Migrate a folder into Articles: prefer `frontpage prompt "migrate … into articles"` — do not invent a mass delete+write migration.
@@ -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|payments|connect|status|disconnect`. 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). 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 store connect [--no-open]` opens Frontpage then Stripe. Checkout is store-wide (`settings set-checkout`); do not use leftover `items --checkout` to pick cart vs Pay now. 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). 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
 
@@ -256,3 +256,11 @@ frontpage doctor --json
 ## People groups, stages, rules, and imports
 
 Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `attachments`, `import`, and `company`. Use `frontpage mail campaign` for one-off group/stage/list audiences in Emails. Every editor action is available through these commands or `frontpage people workspace OPERATION --file payload.json`. Full operations and examples: [PEOPLE.md](./PEOPLE.md); public guide: https://frontpage.host/developers/people. Automated emails select a saved template or series. Campaigns use their own drafts.
+
+
+## Customer Inbox
+
+Internal, allowlisted sites only. Use `frontpage customer-inbox get|put|post RESOURCE`, stable write keys and current versions. Full guide: [CUSTOMER-INBOX.md](./CUSTOMER-INBOX.md). `export CONVERSATION_ID --out FILE` writes authorized paginated history and file metadata; `download FILE_ID --out FILE` downloads through a file grant. Outputs never overwrite existing files. `frontpage usage` reports shared site credits, mail and storage. Human owners may handle conversations; website agents use `manage_customer_inbox` for setup/settings/widget/internal knowledge only, never a human CLI key to read or join customer threads.
+
+
+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.

package/CUSTOMER-INBOX.md

@@ -0,0 +1,237 @@
+# Customer Inbox
+
+Customer Inbox uses the site's existing AI credits and storage allowance. It is available on internal plans and approved pilot sites. The support agent uses fixed GPT-6 Luna and bills AI usage at 10× raw provider cost. During human handling, customer messages use ordinary routing. Each authenticated owner email uses a small metered Luna Decisions call to keep private guidance, ownership controls and customer-facing replies distinct; the full support agent stays paused. UI and CLI controls need no intent call.
+
+Run `frontpage help customer-inbox`. Use the site's normal CLI key:
+
+```sh
+frontpage customer-inbox get status --site my-site
+frontpage customer-inbox get settings --site my-site
+frontpage customer-inbox put settings --file ./settings.json --request-key settings_revision_1 --site my-site
+```
+
+Reads use `get`. Writes use `put` or `post`, a UTF-8 JSON object file, and an 8–128 character request key. Reuse the same key and body after a failed or lost response. Changed bodies need new keys. The service rejects a key reused for a different request. Read current versions before changing records.
+
+## Setup and settings
+
+| Resource | Method | JSON body |
+| --- | --- | --- |
+| `status` | GET | None |
+| `activation` | PUT | `{"enabled":true}`; admin only |
+| `address` | GET | Returns the current address, domain and policy version |
+| `address` | PUT | `{"alias":"acme","policyVersion":"2026-10-13.1"}`; admin only |
+| `address` | POST | `{"retire":true}`; admin only |
+| `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 rollout switches remain off until pilot verification passes. 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`, `customer_update`, `notes_read`, `note_add`, `ask_owner`, `reply_customer`, `wait`, `finish`. Keep `wait` and `finish` enabled. 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.
+
+Aliases use 3–48 ASCII letters, numbers and single hyphens. The service normalizes case and checks collisions in one transaction. Reserved platform names and routing namespaces cannot be claimed. Retired addresses remain reserved; they never move to another site.
+
+## Internal knowledge and approved sources
+
+| Resource | Method | JSON body |
+| --- | --- | --- |
+| `knowledge` | GET | Recent notes; optional `?q=search` |
+| `knowledge/<id>` | GET | One full note |
+| `knowledge/<id>/history` | GET | Immutable revisions for that note |
+| `knowledge` | PUT | `{"title":"Evening visits","body":"Ask the owner before promising an evening visit.","expectedVersion":0,"reason":"Owner policy"}` |
+| `knowledge/<id>` | PUT | Current title/body, `expectedVersion`, `reason`, optional `locked` or `restoreVersion` |
+| `sources` | GET | Approved source records |
+| `sources` | PUT | `{"url":"https://example.com/help","enabled":true,"expectedVersion":0}`; fetches public text |
+
+Supply `body` on a source write to save an owner-approved excerpt instead of fetching. Published sources refresh when the agent reads a source older than 24 hours. The fetcher reuses Core's DNS-pinned public HTTP infrastructure, rejects private addresses, checks redirects and bounds content. Sources over 16000 text characters require an owner-approved excerpt. No scripts run. A source version/digest fences knowledge updates against a changed source.
+
+Knowledge search uses bounded literal keywords from natural-language queries and ranks notes by matched terms. Read the full matching note before updating it; update its current ID/version instead of creating a conflicting duplicate.
+
+Lock a knowledge note with `locked:true`. The support agent cannot change locked notes or locks. Restore an older note with `restoreVersion`; the service creates a new revision and preserves the old history. The agent can change only internal knowledge, using verified owner guidance or a current approved source. It cannot edit public pages or articles.
+
+## Human conversation handling
+
+| Resource | Method | JSON body |
+| --- | --- | --- |
+| `conversations` | GET | Paginated list; `?limit=50&after=<id>` |
+| `conversations/<id>` | GET | Thread and latest public message |
+| `conversations/<id>/messages` | GET | `?after=0&limit=50&audience=all`; viewers get public history only |
+| `conversations/<id>/routing` | GET | Current handler/version, People link and delivery states |
+| `conversations/<id>/reply` | POST | `{"text":"Tuesday at 6:30 works. Keep staffing private.","handlerVersion":0,"privateGuidance":true}` |
+| `conversations/<id>/control` | POST | `{"action":"takeover","handlerVersion":0}` or `{"action":"return","handlerVersion":1}` |
+| `conversations/<id>/reply` | POST | `{"text":"Your quote is ready.","handlerVersion":1}`; requires current owner control |
+| `files?messageId=<id>` | GET | Bound message files; editor/admin only |
+| `files/<id>` | GET | Short-lived download grant; editor/admin only |
+
+Private guidance stays in the same internal thread. The agent asks by a private email and stores its question in the history. Replying by email or UI gives context and leaves the agent responsible for the customer. The agent uses that context to answer and can update unlocked internal knowledge.
+
+General owner facts, such as support hours and standard policies, update related unlocked knowledge without an explicit save request. One-time customer exceptions and private staffing details stay in the conversation. The agent reads the full note and records verified evidence before changing it. Late private guidance can still update knowledge after the customer has an answer; that work cannot send a duplicate customer reply. Locks, manual handling, paused automation and work limits still apply.
+
+Search results contain previews. The support agent reads the complete matching note or approved source before deciding an answer is missing. A verified owner reply can provide lasting facts on a different topic from the customer's question; the same job processes those facts before replying or finishing. The worker verifies the message kind and owner identity. Customer text cannot claim that authority. A specific offer to one customer stays in that thread even when the same owner reply also contains a general policy.
+
+Email replies route through opaque, recipient-bound Reply-To addresses linked to the site, conversation, purpose, owner and handler version. These are local addresses on one domain, not a new subdomain per thread. Subjects and message text never select the customer thread. The service checks the exact verified sender, current owner membership, route and receiving-server DMARC proof before interpreting owner mail.
+
+Every owner email and its files enter private custody first. A Luna Decisions call reads the fresh text and bounded, labeled thread context to distinguish guidance, takeover, return, customer reply or unclear input. Use ordinary language to ask to handle the customer, or ask the agent to resume. Questions, quoted commands, negations and future conditions do not transfer control. UI/CLI `control` remains a typed, model-free action. No phrase whitelist controls ownership. A valid but uncertain control answer can use one bounded Luna tool-call fallback. It can choose only private guidance, takeover, return or unclear, with an exact fresh-text excerpt; it cannot authorize a customer reply. Both calls require current credits and distinct once-only receipts. Invalid responses, unknown paid calls and provider outages stay private rather than triggering another inference.
+
+Guidance keeps the agent responsible. Takeover sends the owner a separate customer-visible transcript; reply through that relay address so Inbox preserves the history. A customer-facing email creates a separate public message only after a settled decision and current owner-session check. The original intake remains private for audit. Mixed or uncertain input, unavailable inference and exhausted credits stay private with an attention notice. Retry recoverable budget/receipt pauses using the existing job operation; an unknown paid attempt is never inferred again. A fresh reply to the original guidance address can also request return, while stale customer-relay sessions cannot publish.
+
+Private owner help, customer relay and customer email use separate threading chains. Inbox stores Resend's actual Message-ID and sends In-Reply-To/References; it never invents provider message IDs. Missing metadata uses scoped reconciliation without another send. Mail clients still control their own grouping. Owners and customers do not share a CC help thread. If the owner already addressed the customer, Inbox records the canonical public reply but does not send a second customer email.
+
+Return checks current settings, site eligibility, unanswered work and site credits before support can resume. It cancels stale automatic work rather than replaying an old answer.
+
+Set `enabled:false` in settings to use manual handling for new conversations. The service binds that relay to the configured verified owner. Existing agent threads switch to manual handling on the next customer message or public owner reply. Re-enable the agent before returning a thread to it. Private guidance alone always stays private and never transfers control.
+
+Set `guidanceToMe:true` in a versioned settings update to bind the signed current owner's verified address. Arbitrary recipient addresses and user IDs remain forbidden. The service saves only the resolved owner identity, not this setup flag.
+
+## Security review and recovery
+
+| Resource | Method | JSON body |
+| --- | --- | --- |
+| `blocks` | GET | Site-scoped block evidence references; human editor/admin only |
+| `blocks/<id>/unblock` | POST | `{"version":1}` |
+| `jobs` | GET | Job state/reason and current `updatedAt` |
+| `jobs/<id>/resume` | POST | `{"updatedAt":"<current ISO time>"}` for recoverable budget, receipt, rate or service pauses |
+| `receipts` | GET | Held inbound mail; admin only |
+| `receipts/<id>` | POST | `{}` queues a held capture retry; admin/pilot only |
+
+Only a validated clear attack can create an automatic site-scoped block. Authenticated customer mail binds a verified email identity; unverified mail stays thread-scoped. Blocks never ban a People contact across sites or a shared IP. Unblock preserves evidence and does not replay the attack. Uncertain, malformed, refused or unavailable screening pauses the agent and leaves human handling available. Known blocks and rate/size checks stop work before another paid call.
+
+The fixed policy requires allow probability at least 0.90 and confidence at least 0.80, with no attack category. Automatic blocking requires malicious probability and confidence at least 0.98 and an attack category. Other results pause for human review; a review does not label the customer malicious. These are platform controls, not customer settings. Review email notices deduplicate per conversation and reason group per hour. Saved receipt retries wait at least 30 seconds so one failed receipt cannot monopolize recovery.
+
+Receipt recovery resubmits saved provider usage to the existing ledger. It never repeats inference. An interrupted request with unknown completion requires review. Resume cannot bypass screening, replay a blocked attack, or pretend unknown usage is zero. Exact input/output/cache/reasoning counts stay unchanged; the ledger records raw cost, fixed multiplier, customer debit, job/call/conversation references and immutable prices.
+
+## Website-agent management boundary
+
+The website agent uses `manage_customer_inbox` and `get_customer_inbox_docs`, with a signed manager principal bound to the owner run. It manages settings, tools, aliases and internal knowledge. It cannot read live threads or files, send messages, provide private guidance, take over/return, or review customer block evidence. Server checks enforce this even through indirect paths. Never give the website agent a human CLI/API key. Its manager tool uses no human keychain credential.
+
+The developer guide lives at `https://frontpage.host/developers/customer-inbox`. Changes to that site use the Frontpage CLI pull/push/deploy/publish process.
+
+## Owner workspace and widget
+
+Open `/workspace/sites/<siteId>/customer-inbox` on an approved internal site. The workspace uses the same versioned service operations as the CLI. Conversation rows show the latest public message. Customer messages, agent replies, owner replies, private guidance, notes and handling changes have distinct labels. Private guidance stays in the thread and does not transfer ownership.
+
+Use `frontpage customer-inbox get widget --site my-site` as a human admin to get the script URL, site ID and server-side app identity key. Install the returned script through the normal Frontpage CLI file workflow or your app's template:
+
+```html
+<script defer src="https://app.frontpage.host/customer-inbox/widget.js" data-site="SITE_UUID"></script>
+```
+
+The current scaffold and gateway already allow this HTTPS script and its requests. Installation uses their existing script support; it needs no gateway change, scaffold upgrade or fleet rebuild. The widget stays separate from the site bundle. It appears only when the service accepts that site's activation, rollout gates and approved origin.
+
+Update settings using the current `expectedVersion`:
+
+```json
+{
+  "expectedVersion": 4,
+  "value": {
+    "widget": {
+      "enabled": true,
+      "title": "Message our team",
+      "greeting": "How can we help?",
+      "color": "#7254d6",
+      "requireName": true,
+      "requireEmail": true,
+      "origins": ["https://my-site.frontpage.host", "https://app.example.com"]
+    },
+    "ownerCopies": false,
+    "helpRules": {
+      "humanRequest": true,
+      "missingAnswer": true,
+      "frustration": true,
+      "repeatedFailure": true
+    }
+  }
+}
+```
+
+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. 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.
+
+### Signed app identity
+
+Keep the `identityKey` returned by `widget` on your app server. Never include it in HTML, browser storage or a client bundle. Sign a short-lived assertion after authenticating your app user:
+
+```js
+import { createHmac } from "node:crypto";
+const now = Math.floor(Date.now() / 1000);
+const claims = {
+  siteId: process.env.INBOX_SITE_ID,
+  origin: "https://app.example.com",
+  subject: authenticatedUser.id,
+  email: authenticatedUser.email,
+  name: authenticatedUser.name,
+  iat: now,
+  exp: now + 120
+};
+const encoded = Buffer.from(JSON.stringify(claims)).toString("base64url");
+const identity = encoded + "." + createHmac("sha256", process.env.INBOX_IDENTITY_KEY)
+  .update(encoded).digest("hex");
+```
+
+The service verifies the signature, site, origin and expiry. Assertions can last at most five minutes. They grant customer identity only, never owner or manager authority. Every app-session request must include the current signed identity matching that session's subject and email. Put a server-rendered assertion in `data-identity`, or preferably provide `data-identity-url="/api/support-identity"`. That same-origin HTTPS endpoint authenticates the current app user and returns `{"identity":"<signed assertion>"}`. The widget refreshes it; after logout or account changes, old app sessions cannot be read without the matching identity. Anonymous widgets need no assertion. Each approved origin has its own visitor session; email continues the bound conversation.
+
+## Conversation state, exports and shared usage
+
+| Resource | Method | Body or behavior |
+| --- | --- | --- |
+| `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>/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.
+
+Export the full authorized history and file manifest, one JSON record per line:
+
+```sh
+frontpage customer-inbox export CONVERSATION_UUID --out ./conversation.jsonl --site my-site
+frontpage customer-inbox download FILE_UUID --out ./attachment.png --site my-site
+frontpage usage --site my-site --json
+```
+
+Export uses paginated reads rather than loading all messages into memory. Download uses an authorized file grant. Both commands refuse to overwrite an existing output file. Full private-history export and file access require human editor/admin authority. Viewers can read public history through the normal message resource.
+
+Inbox sends count in the site's existing email allowance. Provider-accepted send receipts settle that usage once, including private owner notifications and copies. AI calls debit the site's existing credit ledger at 10× cost, with token counts unchanged. Storage uses the existing Blob scanner and counts actual attachments, originals and previews; conversation text adds no separate meter.
+
+## File custody and cleanup
+
+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.
+
+
+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.
+
+`jobs/<id>` reads one human-visible recovery state. Retry only the documented recoverable pauses using its current `updatedAt`; invalid screening and unknown sends require human review. An unknown shared-media operation keeps its `claimId`, `claimAction` and `lifecycleVersion`. Operators verify live/archive byte hashes and the existing archive row before acknowledging the matching service-only `/media-finish` operation. Never clear a claim solely because time passed. These endpoints accept only the `inbox-media` service actor; owner keys and website managers cannot submit them.
+
+
+## Support agent tool contract
+
+The support agent has its own system prompt plus the versioned private business instructions. Tool calls stay in Inbox's tenant, conversation, handler, configuration and job context. All ten tools start enabled; `wait` and `finish` cannot be removed. A disabled tool fails at the server.
+
+| Tool | Inputs | Effect and limits |
+| --- | --- | --- |
+| `knowledge_read` | `query`, `id` or `sourceId` | Search internal notes or read complete approved evidence. |
+| `knowledge_update` | Optional `id`; `title`, `body`, `expectedVersion`, `reason`, `evidenceKind`, `evidenceId`; source `evidenceVersion` | Update unlocked internal facts from verified guidance in this thread or an approved source revision. One-off guidance stays in the conversation. No public editing. |
+| `customer_read` | None | Read only this thread's verified People contact. |
+| `customer_update` | `name`/`phone`, `evidenceMessageId` | Enrich from an explicit customer statement; cannot change identity or permission. |
+| `notes_read` | None | Read factual People notes for the bound contact. |
+| `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. |
+| `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. |
+
+Decisions screens malicious customer input and interprets authenticated owner-email intent. It never chooses IDs, recipients, permissions, business answers, support tools or knowledge changes. Owner intent uses bounded labeled context, one primary Luna call, at most one bounded same-Luna control fallback, and the same exact-token, raw-cost, 10× ledger receipt as support. Shared inference utilities provide the existing same-model credential/transport fallback; no expensive model substitution or customer model picker is added.
+
+The installed widget loads two public static scripts: `/customer-inbox/widget.js` and `/customer-inbox/view.js` on `https://app.frontpage.host`. The shared renderer contains no session, owner data or credentials. If your app sets a Content Security Policy, allow those script URLs and connections to `https://frontpage-inbox-api.fly.dev`; keep the existing widget origin and identity checks. Owner Inbox pages remain authenticated.
+
+## Live updates and email continuation
+
+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.
+
+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.

package/PAYMENTS.md

@@ -0,0 +1,334 @@
+# Payments reference
+
+Frontpage keeps one Stripe Express account per site. Store owns products, cart
+checkout, fulfillment, buyer service fees, receipt selection and orders. Payments
+owns Stripe setup, tax, payment activity, standalone Pay now and merchant invoices.
+Frontpage subscription billing stays separate.
+
+Use `frontpage help payments --json` for discoverable command help. Normal
+`--site`, authentication, `--json`, `--quiet` and exit-code rules apply. The API
+requires Scale, Enterprise or Internal CLI access. This does not remove product
+permissions or invoice entitlements.
+
+## Access and output
+
+| Operation | Minimum role | Additional rule |
+| --- | --- | --- |
+| Connection status | Viewer | Site membership |
+| Private activity, invoices, arrangements, tax and Pay now reads | Editor | Site membership |
+| Existing tax settings and registration writes | Editor | Explicit supplied jurisdiction/address and confirmation |
+| Stripe browser setup, payment availability, Pay now writes, invoice sends and billing links | Admin | Confirmation where specified |
+| New invoice, new arrangement or resume | Admin | Growth or higher and Payments ready |
+| Historical reads, refresh, void and future cancellation after downgrade | Existing role above | No new invoice entitlement required |
+
+All routes authorize the API-key owner against the requested site. A different
+site's record returns 404. Request fields cannot grant a role, change the trusted
+site or choose a connected account. JSON success uses the existing CLI envelope
+`{ "ok": true, "command": "payments", "data": { ... } }`. Failure uses the
+existing error envelope with request ID and exit code. Human mode prints the
+returned fields, including partial outcomes. A successful HTTP request does not
+mean a payment settled or an email arrived.
+
+## Setup, availability and history
+
+```sh
+frontpage payments status
+frontpage payments settings --json
+frontpage payments connect --no-open
+frontpage payments availability preview --json
+frontpage payments availability off --yes
+frontpage payments availability on --yes
+frontpage payments activity list --json
+frontpage payments activity get <record-uuid> --source order
+```
+
+Connect returns the existing signed-in admin browser URL. Without `--no-open`,
+human mode opens it. The CLI does not accept Stripe terms, finish onboarding or
+create another account to get around a restriction. Recheck `status` after the
+browser flow. Account existence or a return URL alone does not prove readiness.
+Currency comes from Stripe and is read-only.
+
+Payments off first blocks new charges, then stops recurring billing and voids
+unpaid issued invoices. It preserves paid history and the Express account. Review
+the counts with `availability preview`. `off` reads current counts before its
+confirmed write; a changed set returns 409. A bounded request may return
+`pause.complete:false`, remaining counts and failed record IDs. New charging stays
+blocked. Resolve errors and repeat `off`; do not turn Payments on while a pause is
+incomplete. A payment already processing may settle and keeps its real result.
+
+Turning Payments on rechecks Stripe readiness. It does not enable Store, restore
+void invoices, resume arrangements or collect missed periods. Store off affects
+only Store; it leaves standalone payments and billing running.
+
+Activity combines the latest 200 Store orders and 200 Pay now payments with up to
+100 invoices and 100 recurring arrangements each. `mayHaveMore` states when older
+records may exist. It preserves captured currencies, amounts and payment states.
+Recurring amounts are per-period amounts before tax. Use invoice/recurring list
+commands for their paginated history. Get an order/payment with its explicit
+source; equal IDs in different tables do not identify the same record.
+
+## Tax
+
+```sh
+frontpage payments tax get --json
+frontpage payments tax settings --file tax-settings.json --yes
+frontpage payments tax registrations list
+frontpage payments tax registrations add --country US --state CA --yes
+frontpage payments tax registrations end <tax-registration-id> --yes
+```
+
+Tax settings JSON contains `country`, `line1`, `city`, optional `state`, `postal`
+and an existing supported `taxCode`. GET returns current choices and registrations.
+Use the business's actual address and registrations. Frontpage does not choose
+jurisdictions or provide tax advice. End uses the exact registration ID returned
+by Stripe. These operations reuse current connected-account tax helpers. They do
+not expose Account Session secrets or a second tax calculator. An invoice preview
+blocks if tax settings cannot be confirmed; it does not silently drop tax.
+
+## Invoice input and review
+
+For an existing CRM person:
+
+```json
+{
+  "recipient": { "personId": "<crm-person-uuid>" },
+  "description": "Website maintenance",
+  "amountCents": 12500,
+  "kind": "once",
+  "collection": "manual",
+  "dueDays": 14
+}
+```
+
+To add or match a CRM customer when sending, replace `recipient` with:
+
+```json
+{
+  "name": "Customer name",
+  "email": "customer@example.com",
+  "address": {
+    "line1": "Customer billing street",
+    "city": "City",
+    "region": "CA",
+    "postal": "94080",
+    "country": "US"
+  }
+}
+```
+
+`address` also accepts `line2`. Supply a real billing address when automatic tax
+needs it. A CRM person must be visible and have a valid billing email. Inline
+matching stays within the site and does not grant marketing permission. Preview
+creates no CRM person, Stripe Customer, invoice, invitation or charge.
+
+Money fields use integer minor units in the account currency despite the existing
+`Cents` field names. USD 12500 means $125.00; JPY 12500 means ¥12500. The current
+amount range is 50 through 10,000,000 minor units. Description contains 1–500
+characters. `dueDays` is 7, 14 or 30; omitted means 7. A one-time invoice uses
+manual collection and cannot carry recurring date/cadence fields.
+
+```sh
+frontpage payments invoices preview --file invoice.json --json
+frontpage payments invoices send --file invoice.json \
+  --preview-hash <hash-from-preview> --operation-key <stable-uuid> --yes --json
+```
+
+Preview returns the normalized recipient/terms, currency, subtotal, tax, total,
+tax status and `previewHash`. When `billingContactChanged` is true, review the CRM email, name and address and pass `--confirm-billing-contact` to update the saved Stripe contact for future billing. This does not rewrite issued invoices or prior consent. Send repeats those exact terms and hash. It rechecks
+readiness and totals before finalization/delivery. Changed terms or totals return
+409. Common flags can replace simple JSON fields: `--person` or `--email` with
+`--name`, `--description`, `--amount-cents`, `--kind`, `--collection`, `--due-days`,
+`--cadence`, `--first-date`, `--time-zone`. Nested addresses use `--file`.
+
+The operation key contains 16–120 letters, digits, dots, colons, underscores or
+hyphens and starts with a letter/digit. A UUID is suitable. Preserve the same key
+and input after a timeout or uncertain result. Do not use a new key to force a
+send. Repeated requests return the same local/Stripe invoice rather than charging
+again. If Stripe's safe retry window has passed, reconcile the saved object first.
+
+## Invoice management
+
+```sh
+frontpage payments invoices list --limit 50 --offset 0 --json
+frontpage payments invoices list --arrangement <arrangement-uuid> --json
+frontpage payments invoices get <invoice-uuid>
+frontpage payments invoices refresh <invoice-uuid>
+frontpage payments invoices resend <invoice-uuid> --operation-key <stable-uuid> --yes
+frontpage payments invoices void <invoice-uuid> --yes
+```
+
+List accepts limit 1–100 and offset 0–100000; it returns `nextOffset` or null.
+Records include immutable recipient/terms, actual currency/subtotal/tax/total,
+paid/remaining amounts, due/issued/paid dates, Hosted Invoice Page/PDF, delivery
+and any last error. Expected platform fee and actual collected fee are separate.
+An unpaid invoice does not claim a collected fee. Source account/setup secrets
+and customer-access nonces are not returned.
+
+Resend only accepts an open invoice and uses its existing saved billing customer.
+It never creates a replacement invoice. Void requires confirmation and cannot
+restore an invoice after Stripe confirms it is void. A payment race preserves an
+actual paid result. An unsent draft's cancellation is recorded separately from
+Stripe's real draft state. There is no manual mark-paid, refund or raw charge API.
+
+Stripe sends invoice emails and hosts payment/recovery. `delivery:accepted` means
+the send API accepted the request, not that the email arrived or was opened.
+Stripe test mode may suppress email delivery; provider acceptance is the most
+that a test-mode report may claim.
+
+## Recurring manual invoices and autopay
+
+Use the same recipient, description, amount and due window. Set `kind:recurring`,
+`cadence`, `firstDate` and `timeZone`. Collection is `manual` or `autopay`.
+
+```json
+{
+  "recipient": { "personId": "<crm-person-uuid>" },
+  "description": "Monthly maintenance",
+  "amountCents": 12500,
+  "kind": "recurring",
+  "collection": "manual",
+  "cadence": "monthly",
+  "firstDate": "2026-12-01",
+  "timeZone": "America/Chicago",
+  "dueDays": 14
+}
+```
+
+Supported cadences are `weekly`, `fortnightly`, `monthly`, `quarterly`, `yearly`.
+The first date is YYYY-MM-DD in an explicit IANA zone. Billing begins at 09:00 in
+that zone. Choose a future date. Stripe owns later native calendar periods,
+including short months/leap years. No Frontpage recurring scheduler, backfill or
+proration is added.
+
+New recurring arrangements use Stripe's native platform fee: 2% of the invoice
+total, including tax, unless the existing server fee setting is zero. The saved
+arrangement freezes that server-controlled rate before billing starts. For
+example, a $100 invoice plus $9.88 tax has a $2.20 platform fee. The fee is
+deducted from the business's proceeds, not added as a customer surcharge.
+Stripe's own processing and Billing/Invoicing charges are separate. Store,
+Pay now and one-time invoice fee calculations keep their existing basis.
+Reconciliation records expected and actual fees; it does not set the fee or
+collect recurring payments. Stripe handles collection even if a webhook is late.
+
+```sh
+frontpage payments recurring preview --file recurring.json --json
+frontpage payments recurring create --file recurring.json \
+  --preview-hash <hash> --operation-key <stable-uuid> --yes
+frontpage payments recurring list --limit 50 --offset 0 --json
+frontpage payments recurring get <arrangement-uuid>
+frontpage payments recurring refresh <arrangement-uuid>
+frontpage payments recurring cancel <arrangement-uuid> --yes
+frontpage payments recurring resend-invitation <arrangement-uuid> \
+  --operation-key <stable-uuid> --yes
+```
+
+Manual collection creates a native future Stripe schedule. It does not issue an
+immediate first invoice. Stripe creates one invoice per period and emails the
+hosted payment link. Autopay create saves a pending authorization and sends an
+invitation. The customer reviews the amount, tax, cadence and first date, agrees,
+and finishes Stripe-hosted setup on the same connected account/customer. Only
+verified setup can start the schedule. A saved method, setup return query or owner
+flag alone never supplies consent. Setup itself is not a payment.
+
+Arrangement cancellation stops future billing without changing issued invoices
+or adding a final prorated charge. Payments off pauses arrangements by stopping
+their native future schedule. Only paused arrangements may resume. Preview the
+same recipient/amount/cadence/collection with a new future date, then:
+
+```sh
+frontpage payments recurring resume <paused-arrangement-uuid> \
+  --first-date 2026-12-01 --preview-hash <hash-from-preview> \
+  --operation-key <stable-uuid> --yes
+```
+
+Resume creates a linked future arrangement with no missed-period invoices. A
+second different resume request is refused. Autopay seeks fresh customer consent.
+Changed terms require cancellation and a new reviewed request; there is no hidden
+edit/proration action. Invitation resend applies only while awaiting authorization.
+It expires/replaces an unfinished old setup and keeps its own retry key.
+
+## Customer billing access
+
+```sh
+frontpage payments customers send-billing-link <customerMapId> \
+  --operation-key <stable-uuid> --yes
+frontpage payments customers billing-link <customerMapId> \
+  --operation-key <stable-uuid> --json
+```
+
+Use `customerMapId` from the site's invoice/arrangement. It is not a raw Stripe
+customer ID. Send uses the mapped customer's current saved Stripe billing email;
+the caller cannot choose another recipient. Links expire after 30 minutes. A raw
+returned link is sensitive: do not log/share it. The website agent only sends
+links; it cannot request raw customer access.
+
+Customer access needs no owner login. It stays scoped to site/account/customer
+and uses a small customer page plus the connected-account Stripe portal. The
+customer can pay an invoice, change the saved method, cancel future billing or
+choose manual payment for future invoices. These actions do not pay an existing
+balance, authorize another arrangement or expose Frontpage subscription billing.
+Authorization invitations expire after 24 hours; an expired link requires a new
+invitation. A completed authorization exposes Manage billing.
+
+## Standalone Pay now
+
+```sh
+frontpage payments buttons list --limit 50 --offset 0 --json
+frontpage payments buttons get consultation
+frontpage payments buttons create --id consultation --title Consultation --price-cents 5000
+frontpage payments buttons update consultation --price-cents 7500
+frontpage payments buttons update consultation --file button-details.json
+frontpage payments buttons archive consultation --yes
+```
+
+These reuse current item/variant pricing and visitor `/__pay`. Creation registers
+the exact ID atomically with the item in existing Store settings; it returns
+markup for an explicit `data-fp-pay` button. Existing standalone references come
+from the site's authorized markup. A Store card/CTA, no-shipping flag or old
+instant setting is not proof of Pay now ownership. No new button table or fleet
+conversion exists. Price updates are separate from detail updates. Open amount
+creation uses `--amount open --min-cents N` and a minimum variant price. Item IDs
+remain existing 2–40-character kebab IDs. Lists are bounded with `nextOffset`.
+
+## REST paths
+
+All paths below use `/api/v1/sites/{slug}/payments`. GET query fields match the
+documented filters. POST/PATCH fields match the reviewed domain inputs above.
+Financial consequences need `confirm:true`; stable retryable sends additionally
+need `operationKey`. This is a resource API, not arbitrary action dispatch.
+
+| Method | Resource | Result |
+| --- | --- | --- |
+| GET | `/status`, `/settings` | Safe current connection/readiness and read-only currency |
+| POST | `/connect` | Signed-in admin browser handoff |
+| GET / POST | `/availability` | Pause counts/hash or confirmed availability outcome |
+| GET | `/activity`, `/activity/{order\|payment}/{id}` | Current source-aware activity/detail |
+| GET | `/tax`, `/tax/registrations` | Existing tax state/options/registrations |
+| POST | `/tax/settings`, `/tax/registrations` | Existing tax settings/registration write |
+| POST | `/tax/registrations/{id}/end` | End the specified registration |
+| GET / POST | `/buttons` | List / create an explicit Pay now item |
+| GET / PATCH | `/buttons/{id}` | Read / update that explicit Pay now item |
+| POST | `/buttons/{id}/archive` | Confirmed archive |
+| POST | `/invoices/preview`, `/invoices/send` | Read-only review / send |
+| GET | `/invoices`, `/invoices/{id}` | Paginated invoices / detail |
+| POST | `/invoices/{id}/{refresh\|resend\|void}` | Reconcile, resend or confirmed void |
+| POST | `/recurring/preview`, `/recurring` | Read-only review / create request |
+| GET | `/recurring`, `/recurring/{id}` | Paginated arrangements / detail |
+| POST | `/recurring/{id}/{refresh\|cancel\|resume\|resend-invitation}` | Scoped lifecycle action |
+| POST | `/customers/{customerMapId}/{billing-link\|send-billing-link}` | Private customer access |
+
+Common failures: 400 invalid input/retired write; 401 no authentication; 403 role,
+CLI tier or product entitlement; 404 wrong site/record; 409 stale review, conflict,
+unfinished pause or unknown provider outcome; 429 existing rate limit; 503 missing
+rate-limit service, tax-read failure or provider failure. Keep the request ID when
+reporting a failure. Never retry a financial send with a new key just because an
+HTTP response was lost.
+
+## Breaking release
+
+Version 0.2.0 removes Store `connect/status/disconnect/payments`, writable currency
+and checkout mode from CLI/public API/agent contracts. Use `payments` for money
+operations. Store remains cart-only and keeps existing resource paths under
+`/shop`. Saved products/orders, Express accounts, current visitor hooks,
+`/__pay`, Connect webhooks and old browser callbacks remain intact. Old binaries
+may fail on retired endpoints; no compatibility alias or data conversion runs.