frontpage-host 0.1.29 → 0.2.1

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
 
@@ -261,3 +261,9 @@ Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `att
 ## 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.
+
+
+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.

package/CUSTOMER-INBOX.md

@@ -1,6 +1,6 @@
 # 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. Human handling does not call a model for each message.
+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:
 
@@ -28,6 +28,12 @@ Setup binds private guidance to the verified owner who requested it. That identi
 
 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.
 
+`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.
+
+`reviewAfterReplies` (0–200, default 0/off) and `reviewWindowHours` (1–168, default 24) request private owner guidance after that many recent automated replies since the last guidance. Pending requests deduplicate. This is a rolling work control, not a cap on returning customers or retained history.
+
+Customer replies commit before optional knowledge, People enrichment and notes. The same durable jobs table carries separate internal maintenance with the same credits, exact receipts and 10× pricing. It cannot send messages, request owner help, change ownership or edit public content. The workspace shows unfinished internal work separately and offers the existing safe retry controls for recoverable failures. Identical note content does not create another revision.
+
 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
@@ -64,9 +70,21 @@ Lock a knowledge note with `locked:true`. The support agent cannot change locked
 
 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.
 
-Email replies route through opaque, recipient-bound Reply-To addresses linked to the site, conversation, purpose, owner and handler version. Subjects and message text never choose a customer thread. The service checks current owner membership and sender authentication before accepting private owner mail. To take over by email, reply only `Take over this conversation`. The owner receives the customer-visible history and replies through Inbox. If history exceeds the email limit, the notification links to the full paginated history/export; it never claims a shortened transcript is complete. To return control, reply only `Agent, take it from here`. Mixed or unclear handoff text stays private for review. Customer and owner addresses are never added to a shared CC thread by Inbox.
+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.
+
+Shared knowledge must remain useful and true for other customers when the current customer, order and case are removed. Individual delivery estimates, arrangements and fee waivers stay in that conversation or its bound People contact's factual notes. A “customer-specific” disclaimer does not make them shared business policy. Maintenance can finish successfully without writing any knowledge.
+
+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 agent answers the customer first, then separate internal maintenance processes lasting facts. 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.
 
-Manual customer/owner exchanges use ordinary routing code. No support inference runs for every manual message. Returning control checks only eligible unanswered input and suppresses stale automatic sends.
+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.
 
@@ -160,6 +178,10 @@ const identity = encoded + "." + createHmac("sha256", process.env.INBOX_IDENTITY
 
 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.
 
+Browser access lasts 30 days from creation or successful email verification/recovery. Verification links last one hour and work once; confirming rotates the credential. The widget retains access in that browser's storage and keeps it through temporary network failures. Returning browsers with valid access reopen their history automatically. When access is missing, the ordinary **Continue** and email-confirmation flow can reconnect an empty replacement session to the latest open conversation with a matching verified email on that same website origin. A typed email alone never restores history. Nonempty conversations remain separate; revoked access and authenticated app identities cannot use this path. The developer recovery endpoint remains available, but customers do not need a separate Recover workflow. Email continuation uses an inline email field. An empty unverified saved session with an email requests confirmation automatically; a stable receipt prevents reloads from sending duplicate emails.
+
+The same conversation's customer-visible email and chat messages load together, including owner replies relayed through Inbox. They stay stored after browser access expires. Private guidance, internal notes and system notices never enter that public history. Recovery restores access to the saved conversation rather than starting its history over.
+
 ## Conversation state, exports and shared usage
 
 | Resource | Method | Body or behavior |
@@ -199,11 +221,12 @@ On app logout or account change, call `window.dispatchEvent(new Event("frontpage
 
 ## 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.
+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 configurable tool grants 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. |
+| `history_read` | `before`, optional `query` | Retrieve up to ten older eligible messages in the assigned conversation under the `knowledge_read` grant; bounded to 6000 text characters. |
 | `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. |
@@ -214,4 +237,14 @@ The support agent has its own system prompt plus the versioned private business
 | `wait` | `reason` | Pause safely without sending. |
 | `finish` | None | Complete this bounded job. |
 
-Decisions screens malicious input only. It never chooses customer recipients, business answers, tools, owner handling or knowledge changes. Shared inference utilities provide the existing same-model credential/transport fallback; no expensive model substitution or customer model picker is added.
+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,411 @@
+# 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. Only saved, explicitly registered
+Offerings authorize standalone payments; page markup never establishes ownership. 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, details, questions and receipt selection save together. 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.
+
+
+## Offerings: the required object behind Pay now
+
+Every website Pay now payment must reference a registered Offering. Website markup, a price attribute, a Store item's instant flag, and direct checkout requests cannot create or authorize a payment. Store carts and saved invoices retain their own platform-owned flows. The existing `payments buttons` commands manage Offerings through the same service as the workspace and website agent.
+
+```bash
+frontpage payments buttons list
+frontpage payments buttons create --id consultation --title "Initial consultation" --price-cents 10000
+frontpage payments buttons get consultation
+frontpage payments buttons update consultation --title "Consultation" --price-cents 12500 --active true
+frontpage payments buttons update consultation --receipt-template-id TEMPLATE_UUID
+frontpage payments buttons update consultation --default-receipt
+frontpage payments buttons update consultation --active false
+frontpage payments buttons archive consultation --yes
+frontpage payments buttons list --archived true
+frontpage payments buttons restore consultation --yes
+```
+
+`--file payload.json` supports the same fields. `--receipt-template-id` and `--default-receipt` are mutually exclusive. A template must be a saved Emails template owned by the same site. Price, details and template choice save together. Archive is deletion from new checkout: buttons stop taking payments, history remains, and restore can bring the offering back. Do not delete financial history. For a customer-chosen amount, create with `--amount open --min-cents 100 --price-cents 100` (integer minor units in the account currency).
+
+Create/get/update return the saved object; create/update also return bound markup:
+
+```html
+<button data-fp-pay="consultation" data-fp-requires="pay">Pay now <span data-fp-pay-bind="price"></span></button>
+```
+
+The platform loads the saved price, minimum and availability. Do not put a fixed charge in `data-amount`, build a card form, call Stripe directly or substitute a Store item ID. A deleted, paused, unregistered or wrong-site offering cannot charge. Existing connected Stripe onboarding, payment readiness, tax, fees and currency rules still apply. Saved templates send confirmations only after verified payment, subject to current email limits; they do not subscribe a payer to marketing.
+
+The website agent can do this automatically from a normal request such as “add a $100 consultation button”: it finds/reuses or creates the offering and then writes its bound markup. The owner does not have to visit Payments or know any object IDs. Ask for a missing essential business fact, such as an unknown price, rather than invent a fixed charge.
+
+Payments Activity uses Customer, Type, Status, Amount and Date. Date is a verified payment timestamp; unpaid invoices and recurring schedules have no payment date. Historic records without a verified timestamp remain unknown. Summary counts cover the full scoped records even when the recent activity view is capped.
+
+## Customer details on Offerings
+
+Use the existing buttons create/update commands with `--file offering.json`.
+The same service powers the workspace and agent. For example:
+
+```json
+{
+  "title": "Home consultation",
+  "priceCents": 10000,
+  "customizations": [
+    { "customizationId": "job-address", "label": "Property address", "kind": "address", "required": true },
+    { "customizationId": "contact", "label": "Preferred contact", "kind": "choice", "values": ["Phone", "Email"] },
+    { "customizationId": "instructions", "label": "Access instructions", "kind": "textarea", "maxLength": 1000, "includeInReceipt": false }
+  ]
+}
+```
+
+```sh
+frontpage payments buttons update consultation --file offering.json --json
+frontpage payments buttons get consultation --json
+frontpage payments activity get ORDER_UUID --source order --json
+```
+
+At most eight questions. Supported kinds: text (max 200 characters), textarea
+(max 2000), choice (max 20 values), checkbox, email, phone, number, date and
+address. Text supports maxLength; number supports min/max. Required checkboxes
+need an affirmative check. Offering choices require explicit selection. Dates
+use YYYY-MM-DD and express a preference, not a confirmed booking. An address
+question collects a service address; Store owns shipping and Stripe owns billing
+addresses. Fields cannot change the saved price, fees or currency.
+
+Stable customizationId values survive renames and reordering. Replacing the
+customizations array edits future checkouts; completed payments retain captured
+labels, types and answers. Offering answers default out of confirmations; opt in
+per field with includeInReceipt:true. Read captured answers through activity get.
+Do not put intake answers in page markup, URL parameters or Stripe product names.
+The standard payment drawer renders the saved questions; an unrelated form does
+not automatically join its submission to a payment.
+
+## Payments drawer design
+
+Offerings work without Store markup. The platform supplies a Payments drawer for buyer-chosen amounts and saved questions; fixed payments without questions proceed to Stripe Checkout. Never add a Cart button or Store drawer for an Offering.
+
+For custom appearance, include one shared `<template data-fp-payment-drawer>` using the required panel, title, close, amount, fields, error and confirm hooks documented by the Payments agent module. Style it with normal site CSS and payment-specific variables. Keep dynamic questions in the saved Offering, not in page HTML. UI, CLI and agent question edits appear on the next opening without republishing. Template/style edits use normal website publishing. Payments never changes the Store cart or its saved delivery choices.

package/README.md

@@ -60,3 +60,9 @@ See [AGENTS.md](./AGENTS.md) and [llms.txt](./llms.txt) in this package.
 ## 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.
+
+
+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.

package/dist/argv.d.ts

@@ -10,3 +10,5 @@ export declare function looksLikeFlag(token: string): boolean;
  * caller also checks them.
  */
 export declare function assertNoUnknownFlags(rest: string[], command: string): void;
+/** Required value for new command parsers; keep existing parsers unchanged. */
+export declare function takeFlagValue(rest: string[], name: string): string | undefined;

package/dist/argv.js

@@ -46,3 +46,11 @@ export function assertNoUnknownFlags(rest, command) {
         return;
     throw new CliHttpError(`Unknown flag: ${unknown}. Run: frontpage help ${command}`, EXIT_USAGE, 0, "bad_request");
 }
+/** Required value for new command parsers; keep existing parsers unchanged. */
+export function takeFlagValue(rest, name) {
+    const present = rest.some(token => token === name || token.startsWith(`${name}=`));
+    const value = takeFlag(rest, name);
+    if (present && (!value || looksLikeFlag(value)))
+        throw new CliHttpError(`${name} requires a value.`, EXIT_USAGE, 0, "bad_request");
+    return value;
+}

package/dist/bin.js

@@ -32,6 +32,7 @@ import { runRedirects } from "./commands/redirects.js";
 import { runPeople } from "./commands/people.js";
 import { runRoutines } from "./commands/routines.js";
 import { runShop } from "./commands/shop.js";
+import { runPayments } from "./commands/payments.js";
 import { runMail } from "./commands/mail.js";
 import { runArticles } from "./commands/articles.js";
 import { runSettings } from "./commands/settings.js";
@@ -63,6 +64,8 @@ async function main() {
         return runHelp([cmd, ...args]);
     }
     switch (cmd) {
+        case "payments":
+            return runPayments(args);
         case "login":
             return runLogin(args);
         case "logout":

package/dist/commands/payments.d.ts

@@ -0,0 +1 @@
+export declare function runPayments(args: string[]): Promise<number>;