frontpage-host 0.1.29 → 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
 
@@ -261,3 +261,6 @@ 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.

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:
 
@@ -64,9 +64,19 @@ 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.
 
-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.
+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.
 
@@ -214,4 +224,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,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.

package/README.md

@@ -60,3 +60,6 @@ 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.

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>;