create-freeholder 0.0.0-bootstrap.0 → 0.2.0-beta.2

package/dist/template/deploy/commerce-payments.md

@@ -0,0 +1,226 @@
+<!-- Copyright (C) 2026 Tony Aly -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Commerce payment providers
+
+This is the C5.06-C5.07 provider checkpoint over Freeholder's one money spine.
+Manual, Stripe, PayPal, Square, Mollie, Razorpay, Paystack, and Flutterwave
+never write a parallel balance: a checkout or owner-attested offline receipt
+creates one `Payment`, and every refund creates one `Refund` against the same
+immutable invoice.
+
+## Choose a provider
+
+Set `adapters.payments` in `freeholder.config.ts` to `manual`, `stripe`,
+`paypal`, `square`, `mollie`, `razorpay`, `paystack`, or `flutterwave`. A fresh
+instance selects `manual`; it can record cash, cheque, bank transfer, or a card
+processed in a separate terminal without any credential or network call.
+In-person collection at a location is `/admin/pos`: cash settles immediately;
+Stripe Terminal and tap-to-pay create a `card_present` PaymentIntent and wait
+on the reader or the existing Stripe webhook.
+Offline settlement and refund services require an authorized invoicing manager
+and step-up authentication where the actor has a step-up policy.
+
+Stripe requires:
+
+```dotenv
+STRIPE_SECRET_KEY=sk_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+Point its Workbench webhook endpoint at:
+
+```text
+${APP_URL}/api/payments/webhooks/stripe
+```
+
+The adapter pins the known-compatible `2026-02-25.clover` API version. During
+endpoint-secret rotation, put the retiring secret in
+`STRIPE_WEBHOOK_SECRET_PREVIOUS`; remove it after Stripe's rotation window.
+The handler accepts any valid `v1` signature, requires the exact raw body, and
+rejects signed timestamps more than five minutes from receipt. Stripe's
+official guidance requires raw-body verification and describes timestamped
+replay protection: <https://docs.stripe.com/webhooks>. Hosted Checkout and
+future-use consent follow the official Checkout contract:
+<https://docs.stripe.com/api/checkout/sessions/create>.
+
+PayPal requires:
+
+```dotenv
+PAYPAL_CLIENT_ID=...
+PAYPAL_CLIENT_SECRET=...
+PAYPAL_WEBHOOK_ID=...
+PAYPAL_ENVIRONMENT=sandbox # change to live only after sandbox proof
+```
+
+Point its REST-app webhook at:
+
+```text
+${APP_URL}/api/payments/webhooks/paypal
+```
+
+Freeholder posts the exact parsed event plus all PayPal transmission headers to
+PayPal's `verify-webhook-signature` endpoint before touching the database. It
+does not download a provider-supplied certificate and therefore adds no webhook
+SSRF surface. PayPal's verification contract is documented at
+<https://developer.paypal.com/docs/api/webhooks/v1/>. Orders and capture follow
+Orders v2 (<https://developer.paypal.com/docs/api/orders/v2/>); saved methods
+follow PayPal's provider-hosted consent/vault flow
+(<https://developer.paypal.com/docs/checkout/save-payment-methods/>).
+
+Square requires `SQUARE_ACCESS_TOKEN`, `SQUARE_LOCATION_ID`,
+`SQUARE_WEBHOOK_SIGNATURE_KEY`, and `SQUARE_ENVIRONMENT`. Register the exact
+`/api/payments/webhooks/square` URL because Square signs the notification URL
+concatenated with the untouched body. Freeholder uses the current Payment Links
+API and tracks its order through Payment/Refund webhooks. The retiring
+signature key may temporarily live in `SQUARE_WEBHOOK_SIGNATURE_KEY_PREVIOUS`.
+See Square's [Payment Links](https://developer.squareup.com/docs/checkout-api)
+and [webhook validation](https://developer.squareup.com/docs/webhooks/step3validate)
+contracts.
+
+Mollie requires `MOLLIE_API_KEY`. Each payment carries
+`/api/payments/webhooks/mollie` as its classic webhook URL. Classic callbacks
+contain only a `tr_...` identifier; Freeholder fetches the full payment through
+the authenticated Mollie API before normalizing any state, so a forged public
+POST cannot settle money. `MOLLIE_WEBHOOK_SECRET` and its previous value are
+needed only if next-generation signed events share this endpoint. This follows
+Mollie's [classic webhook security model](https://docs.mollie.com/reference/webhooks)
+and [next-generation signature contract](https://docs.mollie.com/reference/webhooks-new).
+
+Razorpay requires `RAZORPAY_KEY_ID`, `RAZORPAY_KEY_SECRET`, and
+`RAZORPAY_WEBHOOK_SECRET`. Freeholder checks for an existing Payment Link by
+its deterministic, 40-character reference before creating one, because
+Razorpay rejects duplicate references instead of accepting a create
+idempotency header. Register `/api/payments/webhooks/razorpay`; exact raw bytes
+are verified against the current or retiring webhook secret. Payment Link,
+refund, and dispute events converge into the shared ledger. See the official
+[Payment Links API](https://razorpay.com/docs/api/payments/payment-links/) and
+[webhook validation guide](https://razorpay.com/docs/webhooks/validate-test/).
+
+Paystack requires `PAYSTACK_SECRET_KEY`, which authenticates API calls and the
+SHA-512 `x-paystack-signature`. Register `/api/payments/webhooks/paystack`.
+Freeholder initializes and verifies unique transaction references and never
+coerces potentially large Paystack transaction identifiers into unsafe
+JavaScript numbers. See Paystack's [Transaction API](https://paystack.com/docs/api/transaction/)
+and [webhook contract](https://paystack.com/docs/payments/webhooks/).
+
+Flutterwave requires `FLUTTERWAVE_SECRET_KEY` and the dashboard secret hash as
+`FLUTTERWAVE_WEBHOOK_SECRET`. Register `/api/payments/webhooks/flutterwave` and
+enable retries. A valid HMAC is necessary but not sufficient for settlement:
+Freeholder also verifies the transaction by its merchant reference and compares
+status, amount, currency, and provider transaction ID. See Flutterwave's
+[Standard checkout](https://developer.flutterwave.com/v3.0/docs/flutterwave-standard-1),
+[webhook](https://developer.flutterwave.com/docs/webhooks), and
+[verification](https://developer.flutterwave.com/v3.0/reference/verify-transaction-with-tx_ref)
+contracts.
+
+`platform.doctor` reports whether the selected provider has both its API and
+authenticated-feedback settings. Doctor never creates a checkout or moves
+money.
+
+## Runtime contract
+
+- `invoicing.listPaymentProviders` returns readiness, capabilities, methods,
+  and whether a provider is selected. It never returns a secret.
+- `invoicing.beginPaymentCheckout` creates the ledger attempt and provider
+  session under the same idempotency key. Success and cancellation URLs must
+  remain on `APP_URL`, preventing an authenticated caller from turning a
+  checkout into an open redirect.
+- `invoicing.completePaymentCheckout` captures an approved PayPal order or
+  rechecks the selected provider's hosted checkout. The public cart/customer
+  choreography belongs to C5.21; current callers are scoped API/MCP/admin
+  clients.
+- `invoicing.submitProviderRefund` reserves the amount in Freeholder first,
+  submits one idempotent provider refund, then starts or settles the existing
+  refund state machine.
+- `invoicing.recordOfflinePayment` and `recordOfflineRefund` require a plain-
+  language owner evidence note and accept an external statement/reference.
+- masked saved-method listings expose brand/label/last four/expiry only. The
+  provider token and provider-customer reference stay internal. Revocation
+  removes the provider token before marking the local evidence revoked. Only
+  Stripe and PayPal advertise this behavior; the other adapters reject a save
+  request rather than pretending their theoretical vault products are wired.
+- disputes retain amount, currency, provider occurrence time, reason, evidence
+  deadline, and open/won/lost state. Older provider events cannot move a dispute
+  backward.
+- `invoicing.reconcilePaymentProviders` reports unsettled attempts, open
+  disputes, unreconciled payout deposits, unmatched provider balance lines,
+  and authenticated event receipts. Stripe and Square signed payout webhooks
+  converge automatically; every hosted provider can also ingest statement
+  observations and gross/fee/net lines through the identical service contract.
+- `invoicing.reconcileProviderPayout` refuses pending/failed deposits, mixed
+  provider or currency lines, reused provider transactions, and any line set
+  whose exact signed net does not equal the bank deposit. Reconciliation is
+  therefore evidence, not a checkbox.
+
+Hosted provider calls occur inside an idempotent service transaction. Stripe,
+PayPal, Square, and Mollie receive their documented request-idempotency value;
+Razorpay uses a deterministic reference and retrieves an existing link before
+create. Paystack and Flutterwave receive a deterministic unique transaction
+reference, preventing a second settlement from matching the invoice. Their
+hosted-checkout APIs do not document a way to recover a lost checkout URL from
+an idempotency key, so an HTTP-response-loss incident can require recheck or
+operator reconciliation instead of blind creation. Paystack and Flutterwave
+also do not document provider-side refund replay under a caller key; after a
+committed local refund Freeholder returns the existing row, but an ambiguous
+provider-response failure must be reconciled before retry. The eventual webhook
+remains authoritative for asynchronous settlement.
+
+## Webhook threat and failure behavior
+
+The HTTP boundary caps announced and actual bodies at 1 MiB, lower-cases header
+names, retains exact bytes for verification, and stores only a SHA-256 digest
+plus the normalized event receipt. Raw bodies, payer payloads, signatures, and
+credentials are never persisted.
+
+Receipts are unique on `(provider, provider_event_id)`. A duplicate returns
+success without applying money twice. Different events for the same payment,
+method, or dispute are serialized by transaction locks and provider occurrence
+time. Authenticated amount or currency disagreement refuses settlement. An
+event that arrives before its idempotent checkout transaction commits receives
+`503` plus `Retry-After`, so the provider retries it instead of Freeholder
+silently acknowledging unmatched money.
+
+Stripe intentionally does not make `payment_intent.payment_failed` terminal:
+Checkout can reuse that PaymentIntent after a customer corrects a declined
+method. Terminal async session failure/expiry owns failure. PayPal capture
+decline/denial is terminal. Provider success can never overpay an invoice; the
+existing invoice advisory lock refuses a competing settlement.
+
+## Sandbox acceptance
+
+Before live credentials:
+
+1. Apply migrations through `0047_fantastic_miss_america.sql` and run
+   `platform.doctor`.
+2. Create and issue a small invoice through the generated invoicing API.
+3. Create a sandbox checkout with a unique idempotency key. Retry the same
+   request and confirm the payment/session IDs do not change.
+4. Complete one immediate and one delayed/failed test payment; resend the same
+   webhook and confirm one receipt and one balance movement.
+5. Submit a partial refund, resend its webhook, and confirm the refund and
+   invoice remain balanced.
+6. For Stripe/PayPal, exercise a saved-method add/remove event. For Stripe,
+   Razorpay, or another adapter that advertises disputes, exercise a dispute.
+   Confirm capability-false operations are refused and masked data is all the
+   list service returns.
+7. Send a forged signature, stale Stripe timestamp, oversized body, mismatched
+   amount/currency, and an event before its payment exists. Expect refusal and
+   no ledger mutation.
+8. Import or receive one payout, record its charge/refund/fee lines, refuse an
+   intentionally mismatched selection, then reconcile the exact net. Confirm
+   the admin payment console surfaces unmatched lines and unreconciled payouts.
+
+Repeat the checklist for each provider an instance plans to enable. The
+repository tests use deterministic mocked provider HTTP only. They never make a
+real, billable, sandbox, or live provider request.
+
+## Rollback
+
+C5.08 migration `0047_fantastic_miss_america.sql` is additive except for safely
+widening `money_state_events_subject_valid` to admit plans and payouts. The
+previous image continues to read invoices, payments, and refunds and ignores
+the advanced tables. Roll back the image normally. Do not drop balance,
+allocation, fee, or payout evidence during an incident. Disable hosted checkout
+by selecting `manual`, retain webhook endpoints until outstanding attempts and
+payouts settle, and reconcile before removing credentials.

package/dist/template/deploy/content-security-policy.md

@@ -0,0 +1,84 @@
+# Content Security Policy
+
+Freeholder sends a fresh nonce-based Content Security Policy on every HTML
+request. The same policy is forwarded to Next for framework rendering and sent
+to the browser for enforcement, so framework scripts and Freeholder's small
+handwritten inline elements receive the one-request nonce.
+
+The policy does not apply to API, media, privacy-artifact, sitemap or ordinary
+file responses. Those routes set their own content type, caching and download
+controls and are not executable documents.
+
+## Enforced boundary
+
+The document policy starts from `default-src 'self'` and denies plugins,
+inline script attributes and unexpected embedding. In production it also
+upgrades insecure subrequests. Its deliberate exceptions are narrow:
+
+- `script-src` uses a nonce and `strict-dynamic`; development alone permits
+  `unsafe-eval` for the Next development runtime. Inline script is never
+  broadly allowed.
+- `style-src` requires the nonce for style elements. `style-src-attr` permits
+  inline values because React uses bounded style attributes for crop anchors
+  and visual bars.
+- `/preview` and its descendants permit only same-origin frame ancestors, so
+  the editor can embed its canvas. Every other page denies framing.
+- S3 media origins are available to images and media only when S3 is the active
+  storage adapter. Direct S3 connections are available only under `/admin`,
+  where multipart uploads run.
+- Same-origin frames and workers remain available to the application. Objects
+  are denied and forms may submit only to the instance.
+
+## Third-party creatives
+
+Set `CSP_THIRD_PARTY_ORIGINS` to a comma- or space-separated list of exact HTTPS
+origins, for example:
+
+```env
+CSP_THIRD_PARTY_ORIGINS=https://creative.example https://player.example
+```
+
+Paths, credentials and wildcards are rejected. HTTP is accepted only for a
+localhost development origin. Declaring an origin does not activate it: the
+browser must separately carry `fh_tc=granted`, the explicit third-party
+creative consent state. Analytics consent never grants this permission.
+
+Future creative renderers must read `x-nonce` from the request and apply it to
+every script element they create. The configured host remains in the policy as
+a fallback for older CSP implementations, while `strict-dynamic` browsers
+authorize the nonce rather than trusting an entire host.
+
+## Violation reports
+
+Browsers send legacy CSP reports and Reporting API batches to
+`/api/security/csp-report`. Intake is limited to 64 KiB, 20 reports per request
+and a global 5,000-request minute. It accepts reports only for the instance
+origin and never derives or stores an IP address.
+
+Raw reports do not reach the database. The collector discards user agents,
+referrers, query strings, fragments, script samples, original policies and raw
+payloads. Entity IDs and opaque path segments are redacted; cross-origin URLs
+are reduced to origins. Equivalent normalized reports share a SHA-256
+fingerprint and occurrence count. At most 10,000 unique fingerprints are kept,
+their expiry slides for 30 days, and `core.pruneCspViolations` removes expired
+evidence daily at 04:59.
+
+Owners can review the last seven days under **Admin → Health → Content security
+reports**. An empty card is normal. When a report appears, use its directive,
+redacted document route and blocked origin to reproduce the page in a browser;
+do not broaden the policy before identifying the resource. A blocked expected
+creative usually means its exact origin is absent, consent was not granted, or
+the renderer omitted the request nonce.
+
+## Verification checklist
+
+1. Open a public page, an admin page and the editor preview in a real browser;
+   confirm there are no CSP errors and the preview remains interactive.
+2. Upload an asset through an S3-backed instance and confirm multipart requests
+   to the configured endpoint succeed only from an admin route.
+3. Configure a test creative origin. Confirm it is absent without `fh_tc`, then
+   grant consent and confirm a nonce-bearing creative can load.
+4. Deliberately request a blocked script, then confirm a redacted, deduplicated
+   entry appears on Health without its query string or browser identity.
+5. Confirm an expired row is removed by the scheduled prune job and that backup
+   retention does not preserve security diagnostics longer than policy allows.

package/dist/template/deploy/contribute.md

@@ -0,0 +1,37 @@
+# Contribution channel
+
+The instance can file a bug, feature request or question with the project.
+Nothing is sent until `contribute.submit` runs. The daily update check is a
+separate, identity-free GET and is not this path.
+
+## Spoke (every instance)
+
+- `contribute.getSettings` / `contribute.updateSettings` — `hubUrl` defaults
+  to `https://freeholder.ai`. An empty URL files locally only.
+- `contribute.submit` writes a local row. If the hub is this instance, the
+  row is `received`. Otherwise a `contribute.deliver` job POSTs
+  `/api/v1/contribute.ingest`.
+- Agents need an explicit `contribute.*` scope. `contacts.*` is not enough.
+- An optional doctor snapshot is stored only when the caller attaches one.
+  Secrets in that snapshot are redacted.
+
+## Hub (off by default, except freeholder.ai)
+
+Turn ingest on with `contribute.setHubEnabled({ enabled: true })` or the
+**Accept reports as a hub** button. Until then `contribute.ingest` is 404.
+If this instance's `APP_URL` host is `freeholder.ai`, ingest defaults on.
+
+A determination is POSTed back to the speaking instance as
+`contribute.recordStatus` using the reply token the spoke issued. The spoke
+updates its local row and notifies staff. There is no instance census.
+
+Rotate `receiveSecret` (step-up) if spokes should HMAC their deliveries
+with the same scheme as outbound webhooks. Unsigned public ingest remains
+rate-limited.
+
+Security-kind reports are refused. Use `SECURITY.md`.
+
+## Determinations
+
+`contribute.determine` may cite a `C#.##` checklist id. It never edits
+`MASTER.md`. Product work still lands in §43 in a later PR.

package/dist/template/deploy/customer-locales.md

@@ -0,0 +1,82 @@
+# Customer locale operations
+
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+
+Freeholder uses one locale contract for every customer surface. Public and
+anonymous portal requests follow an explicit URL prefix; after customer
+sign-in, the linked `Contact.preferred_locale` wins; a missing or disabled
+preference falls back to the business default. The default locale is
+unprefixed and every other enabled locale uses `/<locale>/...`.
+
+## Configure and verify languages
+
+The business default must also be present in its enabled locale list. Adding a
+locale makes it available in public and portal choosers; it does not silently
+machine-translate owner content.
+
+For each enabled non-default locale:
+
+1. Open **Admin → Chrome** and choose **Add _language_** for the header and
+   footer. Freeholder copies the source block tree into an independent,
+   owner-editable locale row.
+2. Translate owner-authored navigation labels and footer copy, then preview
+   the exact locale before saving.
+3. Review page translations in **Admin → Translations**. Only reviewed page
+   translations are advertised through `hreflang`; missing content falls back
+   to the source page rather than producing a partial 404.
+4. Visit the default and prefixed public URLs. Follow brand, navigation,
+   button, location and form-submit paths and confirm the selected locale is
+   retained.
+
+If a translated chrome row is still missing, the complete source header or
+footer is rendered as a fallback. It never disappears around a translated
+page. The setup seed and migration add the locale chooser as a real CMS block,
+so an owner can place and style it with the rest of the chrome.
+
+## Portal, templates and notifications
+
+Anonymous portal language links change the URL, not the Contact. A stored
+Contact preference still wins for the magic-link template. On first use, when
+no preference exists, the selected enabled locale is held only on the
+short-lived hashed-token row; it becomes the Contact preference after the
+customer proves control by consuming that token. Merely knowing somebody's
+email therefore cannot rewrite their profile. The link carries the same prefix
+through the scanner-safe confirmation screen.
+
+After sign-in, choosing a language updates the linked Contact through the
+audited service layer and records `contact.localeChanged` on the timeline. The
+next portal render, customer template and notification uses that fact.
+Disabled or malformed stored tags never escape onto a customer surface.
+
+Notifications snapshot the resolved locale beside the title, body and action
+link. Catalog-key messages render before commit; email boilerplate, occurrence
+copy and digest subject/introduction render from that snapshot. Digests group
+by recipient and locale, so a preference change cannot mix two languages in
+one message. Literal owner-authored content remains literal and is not
+pretended to be translated.
+
+## Migration and rollback
+
+`0034_furry_ozymandias.sql` and `0035_slim_wiccan.sql` are additive. They add
+notification/digest locale snapshots and the short-lived magic-link locale
+handoff, backfill existing notifications from an enabled Contact preference or
+the business default, and append a locale chooser only to header block trees
+that do not already contain one. They do not overwrite an existing chooser or
+create hidden layout markup.
+
+The previous application image ignores the added columns and the recognized
+`locales` block type already existed before this migration, so N-1 remains
+read/write compatible after forward migration. Rollback is an image swap; do
+not remove the columns or rewrite section JSON merely to disable a locale.
+
+Verification after deploy:
+
+1. Run migrations and `pnpm doctor`.
+2. Open one non-default public page and the customer login route with its
+   prefix; neither portal request should create analytics visitor cookies.
+3. Send a magic link to a test Contact with a non-default preference and
+   inspect the language and prefixed URL at the development/approved test sink.
+4. Create a test Contact notification and verify its `locale`, localized
+   action path, delivery row and digest row without exposing message bodies in
+   production logs.

package/dist/template/deploy/customer-surfaces-2026-10-07.md

@@ -0,0 +1,90 @@
+<!-- Copyright (C) 2026 Tony Aly; SPDX-License-Identifier: Apache-2.0 -->
+# Customer surfaces — 2026-10-07
+
+This change implements the five gaps identified in the public-site audit.
+It does not declare Freeholder stable. MASTER.md §43 remains the acceptance authority.
+
+| Surface | Customer entry | Owner controls | Shared service boundary |
+| --- | --- | --- | --- |
+| Blog | /blog | /admin/blog, then the existing visual page editor | cms.listBlogPosts, CMS create/update/publish |
+| Booking | /book and /embed/booking | Catalog service offerings, price rules, calendars, booking audiences | catalog.publicBookingQuote, catalog.bookService, catalog.moveMyBooking |
+| Newsletters | /newsletters | /admin/newsletters; /admin/settings#mail | broadcasts.start/sendNext/tick, mail.readiness, mail outbox and signed delivery feedback |
+| Memberships | /memberships | /admin/subscriptions, catalogue prices and payment provider | subscriptions.publicPlans/join/mine, canonical invoice checkout, invoice.paid activation |
+| Client portal | /portal | Existing owner records and document shares | portal.myRecord/actOnMyRecord, documents.myDownload |
+
+## Configuration and promises
+
+Customer sign-in requires a delivering transactional mail route. Newsletter
+campaigns require a verified active default bulk sender, provider credentials
+and authenticated delivery feedback. The readiness check uses the same route
+selection as sending, including connected mailboxes. Failure leaves drafts and
+recipient ledgers intact. SMTP/HTTP test doubles prove software behavior; they
+do not prove external delivery or inbox placement.
+
+Public booking requires an active public service, priced default variant,
+allowed full/deposit payment rule, calendar availability and a matching booking
+audience. Reservation resolves the signed-in contact; callers cannot supply
+another contact, duration, resource set or invoice amount. Current prices and
+terms are hashed and rechecked. Calendar locks serialize primary and resource
+claims; a retry key is scoped to the customer and accepted promise. Deposits use
+the shared payment plan, invoice and ledger. Requested bookings still follow
+the owner's existing confirmation, intake and waiver rules. Cancellation
+records the policy outcome; refunds remain an owner money operation.
+
+Membership signup requires an active public priced product and plan. Paid
+signups are paused with paused grants until their first invoice is fully paid.
+Retries reuse the signup. A cancelled pending signup cannot activate, and its
+invoice no longer offers customer checkout. Recurring payment-method consent
+is explicit; only consented provider evidence is stored. A durable sweep recovers
+activation and future provider schedules. New customers starting a trial that
+requires a saved card still need the business to arrange that method; this is
+shown as unavailable rather than granting an unverified trial. Live recurring
+settlement remains C11.05.
+
+Private client document versions mark their assets private, including existing
+versions in the additive migration. That flag survives archiving, revocation,
+and disabling the documents module. Generic media routes cannot bypass share
+expiry, revocation, login or download limits. Unrelated public asset downloads
+retain their existing behavior. Portal lists and record responses contain no
+quote, booking or document bearer credentials, provider references or staff notes.
+The image resolver also checks the private flag before minting original or
+rendition URLs. The regression starts with public image/object controls, attaches
+them as client documents, and then proves anonymous and customer preview denial,
+owner library authorization and refusal of the original object's known key.
+
+## Verification
+
+Automated evidence is in tests/modules/customer-surfaces.test.ts,
+tests/browser/customer-surfaces.spec.ts, tests/modules/broadcasts.test.ts,
+tests/core/newsletters.test.ts, tests/core/payment-adapters.test.ts and the
+existing membership/document/portal suites. Browser fixtures are disposable
+customer sessions; they are not claims of delivered mail or real card settlement.
+
+Local verification on 2026-10-07 used disposable PostgreSQL 16 databases, clean
+migrations through 0022, and the production standalone build:
+
+- Both browser journeys passed; Axe passed in light and dark themes. The owner
+  created and published a blog post. A verified customer booked, rescheduled and
+  cancelled an appointment, joined a membership, saw pending-payment access and
+  cancelled. An anonymous customer API request was refused.
+- All ten customer-surface service tests and eight SDK tests passed. These cover
+  published-versus-draft privacy, reviewed translations, stale booking terms,
+  slot contention, retry identity, deposit billing, ownership, quote acceptance,
+  private document access and one-use email proof.
+- Both newsletter archive/consent/merge cases and all twenty broadcast cases
+  passed. All eleven subscription-billing cases
+  passed across the regression runs, including verified first-payment consent,
+  exact saved-method binding, refusal of an unrelated card and compensation when
+  cancellation races provider schedule creation.
+- Production build, TypeScript, ESLint, licensing, plan consistency, service
+  composition, registry inventory and F-matrix checks passed. The dependency
+  audit is clean after updating Next.js, Sharp and shell-quote to patched versions.
+
+The database tests stage mail and use payment-provider test doubles. The first
+temporary database run exceeded its container memory limit; the container was
+adjusted and affected cases rerun. No production database was used for fixtures.
+Required GitHub CI, merge and hosted deployment are recorded separately in the PR.
+
+Production and playground mail/payment provider acceptance, independent security
+review, and the deferred trial setup above remain explicit open work. Do not
+check those acceptance items from mocked or ledger-only runs.

package/dist/template/deploy/customization-seams.md

@@ -0,0 +1,18 @@
+# Customization seams
+
+An update is only safe if Freeholder knows which parts of a running instance
+belong to the owner. Those seams are:
+
+| Seam | Holds | Survives an image swap because |
+|---|---|---|
+| Database | Pages, settings, media records, every business row | Structure is data |
+| Plugins | Owner and third-party code under `plugins/` | Installed artifacts, never merged into core |
+| Configuration | `freeholder.config.ts` and `.env` | Instance choices, loaded at boot — the `.ts` file is absent from standalone images |
+| Uploads | Object storage (`FREEHOLDER_STORAGE` over `adapters.storage`) | The container is disposable |
+
+Core (`src/`, `app/`, `packages/`, `db/`, `scripts/`) is replaceable. Editing
+those files on a live server is not a supported customization. Doctor reports
+it as `update.coreFiles`, and `platform.inspectSeams` lists the paths.
+
+This is the contract that later update apply/rollback work (C10.02–C10.11)
+depends on. It is not a claim that unattended self-update is already running.

package/dist/template/deploy/demo-scenarios.md

@@ -0,0 +1,96 @@
+# Deterministic demo scenarios
+
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+
+Freeholder demo scenarios are versioned product definitions, not disposable
+database scripts. An owner reaches them at **Admin -> Demo scenarios** and can
+load, reload, reset or purge a scenario in one action. Every action goes
+through the normal service registry, transaction, permission and audit path.
+
+`seed.current-modules` remains the small CMS and Forms conformance foundation.
+Complete journeys ship as `seed.creator`, `seed.service-business`, `seed.shop`
+and `seed.everything`. Each is assembled only from module fixture contributions
+— contacts, location, sitting, inbox, page, form, print, gallery, quote, overdue
+invoice and a saved revenue view — in English, French and Spanish, visibly
+marked `[Demo]`, with a guided day-in-the-life and one-action load/reload/reset/purge.
+
+## Lifecycle and isolation
+
+Only one demo run may be active. Its definition key/version, selected locale,
+generation and timestamps live in `demo_scenario_runs`. Every fixture record
+is mapped by run, generation, contribution key/version, stable fixture key,
+subject type and exact subject ID in `demo_records`.
+
+- **Load** is idempotent. Loading the same active key/version/locale verifies
+  the existing outcomes and does not create another copy.
+- **Reload** purges the current generation, verifies cleanup, advances the
+  generation and loads the same run again.
+- **Reset** purges the active run, marks it purged and creates a fresh run in
+  the selected locale.
+- **Purge** passes only stored provenance to each owning module, requires every
+  handler to account for every record, verifies that the declared outcomes no
+  longer exist, and marks the run purged.
+
+The whole multi-module lifecycle is one database transaction. If a later
+fixture conflicts, earlier fixture writes, provenance and the run row roll
+back together. An untracked record is never adopted merely because its slug or
+name resembles demo data. Purged provenance remains as lifecycle history;
+ordinary business records remain untouched.
+
+## Manifest contribution contract
+
+A module or plugin exposes an `onboarding` loader in its module manifest. The
+loaded module default-exports four typed arrays:
+
+- `targets`: real internal hrefs, optional selectors, module dependencies and
+  capabilities;
+- `guidance`: versioned capability-filtered guidance flows;
+- `scenarios`: versioned presets, pinned fixture versions, locales,
+  prerequisites, expected tour and status;
+- `fixtures`: stable record declarations, locale variants, expected outcomes,
+  dependencies and service names for load, purge and verify.
+
+Keys and handler services must stay inside the contributor's namespace. A
+scenario pins every fixture version and must include all of its modules,
+capabilities and locales. Expected outcomes must point at declared targets.
+Load, purge and verify handlers are ordinary services, but they refuse calls
+unless the run identity and supplied records match active stored provenance.
+
+Never edit a shipped definition in place. Add a higher definition or fixture
+version. Startup persists registered definitions idempotently and refuses a
+key/version whose stored meaning differs.
+
+The conformance harness in `src/core/onboarding/registry.ts` is available to
+plugin development and CI. It rejects missing dependencies or handler
+services, foreign namespaces, unpinned/missing fixtures, capability gaps,
+undeclared outcomes and stale route/selector inventories. The hostile-plugin
+tests demonstrate each refusal.
+
+## Migration and rollback
+
+Migrations `0041_red_zeigeist.sql` and `0042_worthless_naoko.sql` add the three
+normalized tables, lifecycle constraints, definition foreign key and the
+built-in version-1 scenario. They are additive. Run migrations before starting
+the new image.
+
+The previous image ignores these tables, so rollback is an image swap. Leave
+the tables in place. Before uninstalling a plugin or module that owns an active
+fixture, purge or reset the active scenario while its handlers are still
+available.
+
+## Post-deploy verification
+
+1. Sign in as the owner and open **Admin -> Demo scenarios**. Confirm the
+   current-module scenario and the four complete journeys are listed.
+2. Load **Creator day** in English. Confirm marked contacts, a studio, a sitting,
+   an inbox thread, a page, a form, a print, a gallery, a quote, an overdue
+   invoice and a revenue view appear at the linked admin targets.
+3. Load it again and confirm no duplicate appears. Use **Reload** and confirm
+   the displayed generation advances.
+4. Select French or Spanish and use **Reset fresh**. Confirm the marked fixture
+   copy changes locale and generation returns to one on a new run.
+5. Create an ordinary page or form, then use **Purge demo**. Confirm the marked
+   fixtures disappear and the ordinary records remain.
+6. Run `pnpm test`, `pnpm test:browser`, the schema compatibility gate and the
+   ownership restore drill for a release candidate.

package/dist/template/deploy/digitalocean-app/.env.example

@@ -0,0 +1,15 @@
+# Copyright (C) 2026 Tony Aly
+# SPDX-License-Identifier: Apache-2.0
+DATABASE_URL=
+# Independent random secret required for first owner setup (32+ characters).
+BOOTSTRAP_SECRET=
+SESSION_SECRET=
+CREDENTIAL_KEY=
+APP_URL=https://example.ondigitalocean.app
+FREEHOLDER_STORAGE=s3
+S3_BUCKET=
+S3_ENDPOINT=
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+S3_REGION=
+S3_ADDRESSING_STYLE=path