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

package/dist/template/deploy/spec-reconciliation.md

@@ -0,0 +1,188 @@
+<!--
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Spec reconciliation — §§1–42 vs schema, services, UI
+
+*MASTER.md C11.16. Reconciled 2026-09-13 against parent `2b14cbe`;
+re-reconciled 2026-10-04 against `04c27ca5` after the storefront, editor,
+playground and milestone-checkout changes. Historical 2026-09-28 evidence: C3.13 closed by the live
+Paradise Comms acceptance, C11.08 closed by the live Tier-1 restore drill,
+C11.11 closed on its archived reference-target evidence, the mobile-app rows
+re-cast as v2-deferred per §43.18, and C3.24 (native storefront parity)
+was recorded as the then-remaining product item. C3.24–C3.26 and C2.25 have
+since closed; the 2026-10-05 acceptance audit reopens C6.11 (paid tickets),
+C11.05 (provider settlement) and C11.08 (Tier-1 object-byte migration); their former status is updated below. Independent review and
+real provider acceptance remain open.*
+
+C11.16 requires that every affirmative capability in §§1–42 either has a
+completed checklist item, is listed here as remaining work with an open
+checklist id, or is struck from the spec in the same change. This file is that historical
+mapping table. It is not C11.17 and it does not claim DONE. The project audit
+reopened C11.16: naming unfinished features is useful, but does not satisfy
+its requirement that every affirmative feature have a completed checklist
+item. Some original “Built” labels below mean presence in the tree, not
+verified operational completeness. Current evidence is in MASTER.md §43 and
+`security/project-audit-2026-09-13.md`.
+
+**Method.** Section headings in `MASTER.md` were read against:
+
+- schema: every `pgTable` in `src/` and `plugins/` (343 tables)
+- services: registry names (`defineService` / orchestrators)
+- UI: `app/(admin)/admin/**/page.tsx` (136), `app/portal/**/page.tsx` (20),
+  public catch-all `app/(public)/[[...slug]]`, embed/capture/gift/community
+  routes, `apps/mobile`
+
+Checked C-items are the delivery evidence; unchecked C-items are remaining.
+Anti-roadmap rows are refusals, not leftovers. Reconciliation updates since
+2026-09-13 are noted in the rows and the remaining-work table below; the
+2026-09-13 baseline is preserved in git history.
+
+## How to read the table
+
+| Status | Meaning |
+|---|---|
+| Built | Affirmative claim exists in schema, services and a human surface, with a checked C-item |
+| Built (service) | Schema + services exist; F04 is a named existing screen or an explicit N/A on the C-item |
+| Remaining | Affirmative, not complete; named open C-item |
+| Deferred to v2 | Owner-deferred per §43.18; the obligation survives verbatim to v2 and is not v1 remaining work |
+| Struck | Wording in §§1–42 over-claimed; narrowed in this change |
+| Doctrine | Architecture / refusal / historical rationale, not a feature to ship |
+
+## §§1–42
+
+| § | Title | What exists | Status | Remaining or struck |
+|---|---|---|---|---|
+| 1 | Why Freeholder | Pitch, Apache-2.0, contribute channel, demo fixture. Recipes in `deploy/`. | Built | Struck: `/docs/deploy` path (actual `deploy/`). |
+| 2 | Architectural principles | Single-tenant, monolith, contact spine, invoice convergence, adapters, first-party analytics, service layer, SSR SEO, i18n, one database. | Doctrine + built | None as leftover features. |
+| 3 | Module map | Core + commerce + services + content + growth + platform folders exist as `src/core`, `src/modules/*`, `plugins/*`. Admin shell, CRM, inbox, automations, portal, reporting, API, MCP all present. | Built | Struck: `[v2: auto-clip]` on social; tax line is the `none` seam, not named vendors. Folder names in the tree are conceptual (catalog owns orders; scheduling owns booking; newsletters owns email-marketing). |
+| 4.1 | Identity & access | `roles`, `role_grants`, `users`, `sessions`, `login_security_events`, `staff_invitations`, `customer_magic_links`, `contacts`, `organizations`, `timeline_events`. `/admin/roles`, `/admin/invitations`, `/security`, `/admin/contacts`. | Built | C1.01–C1.08. |
+| 4.2 | Catalog | Products, variants, options, attributes, media (incl. GLB/glTF/USDZ), relations, bundles, service offerings, price lists/breaks, customer groups, inventory ledger, back-in-stock, suppliers/POs, digital deliveries, rental terms, passes. `/admin/products`, inventory, procurement, price-lists. | Built | **Struck `LicenseKey` and `DigitalFulfillment` sibling fields** (`license_template_id`, `watermark_policy`). Grants are `digital_deliveries` tokens (C5.19). |
+| 4.3 | Money | Orders, quotes, contracts, invoices, payments, subscriptions, content unlocks, tips, coupons, gift cards, affiliate program/code/commission. `/admin/orders`, quotes, agreements, invoices, payments, promotions, referrals. | Built | **Struck Stripe Connect as a DONE payout adapter.** C9.10 ships manual/CSV batches. Live hosted settlement remains honesty on C11.05, not a claimed hop. |
+| 4.4 | Time | Calendars, memberships, rules/exceptions, busy blocks, bookings, participants, waitlist, reminders, cancellation policies, audiences. `/admin/calendar(s)`, appointments, waitlist. ICS + Google/Microsoft writeback. | Built | **Struck `BookingSeries`.** Recurring is not a first-class RRULE entity; each occurrence is a `Booking`. ICS import does not expand `RRULE` (`src/core/ics.ts`). |
+| 4.5 | Media & galleries | Assets, capture sessions, galleries, selections, access logs, documents/versions/shares, projects/outcomes/media/collections/testimonials. `/admin/media`, galleries, documents, projects. | Built | C1.12–C1.29, C8.01–C8.08, C8.13. |
+| 4.6 | Content, forms, SEO | CMS pages/posts/revisions, forms/submissions, redirects, help articles/categories. Catch-all public route. `/admin/pages`, forms, redirects. | Built | **Struck `SeoSetting` as a table.** Sitewide SEO lives on `business_profile` + CMS page SEO jsonb + `redirects`. |
+| 4.7 | Growth | Broadcasts (not a separate `EmailCampaign` table), reviews, social accounts/packages/variants/publications, analytics events. `/admin/newsletters`, social, traffic. | Built | Table names differ (`broadcasts`, `mail_deliveries`); the capability is C9.04–C9.06, C9.24–C9.27, C8.09, C1.18. |
+| 4.8 | Platform | API keys, webhooks, audit log, release notes, module settings, guidance, demo scenarios, contributions. `/admin/plugins`, contribute, demos, guidance, updates, health. | Built | **Struck dedicated public `/changelog` route.** Instance notes are `/admin/updates`; a CMS page can reprint them. Agent-mandatory release notes remain. |
+| 4.9 | Internationalization | `business_profile` locales/currency/timezone/units; `entity_translations`; en/fr/es catalogs; locale-prefixed public URLs; hreflang/sitemaps. `/admin/translations`. | Built | **Struck `LocaleSetting` / `CurrencySetting` / `FxRate` tables and `adapters/fx`.** Those fields live on `business_profile`. Auto-FX display stays off (§8). Charges never auto-convert. |
+| 4.10 | Locations & NAP | `business_locations`, `opening_hours`, `service_areas`; location pages via CMS. `/admin/locations`. | Built | C2.21 feeds, C9.27 GBP hours. |
+| 4.11 | Shipping | Zones, methods, rate bands, boxes, fulfillments, delivery windows, RMAs. `/admin/shipping`, fulfillment, returns. Carrier family is `adapters/carrier/none`. | Built | Live carrier labels/rates are the seam, not a shipped UPS/ShipStation adapter (C5.18 honesty). |
+| 4.12 | Tax | Categories, zones, rates, registrations, exemptions, tax lines. `/admin/invoices/tax`. `adapters/tax/none` plus built-in templates (CA/EU/UK/US/AU/NZ). | Built | **Struck named Stripe Tax / Avalara / TaxJar implementations as DONE**, including the leftover “replacement family” sentence. The contract is C5.01; the arithmetic is the templates (C5.02–C5.04). |
+| 4.13 | Loyalty & referrals | Programs, accounts, points ledger, tiers, rewards, attribution, invitations, payout batches/lines. `/admin/loyalty`, referrals. | Built | C9.09–C9.12. Payout `method` is manual; `provider` is not a shipped adapter (see 4.3). |
+| 4.14 | Messaging | Conversations, messages, deliveries, numbers, windows, keywords, SMS Twilio, site chat. `/admin/inbox`, messaging. Voice/video is the plugin. | Built | C7.08–C7.15. C3.13 closed 2026-09-28: the Paradise Comms adapter, webhooks, owner-storage import and provider-confirmed erasure ran live against production paradisemodern.com (`deploy/c313-live-acceptance-2026-09-28.md`). |
+| 4.15 | Subscriptions & paywalls | Plans, subscriptions, entitlements, grants, pass balances, paywalls, meters, dunning. `/admin/subscriptions`, paywalls. Portal self-service. | Built | **Live Stripe/PayPal settlement remaining honesty (C11.05), not a claimed hop.** |
+| 4.16 | Ads | Sizes, slots, advertisers, campaigns, creatives, stats, ads.txt. `/admin/ads`. | Built | C9.17–C9.20. |
+| 4.17 | Runs | `runs`, `run_steps`, `run_approvals`, `run_spend` shared by agents and automations. `/admin/work`, automations. | Built | C4.02, C9.02. |
+| 5 | SEO layer | SSR catch-all, schema.org JSON-LD, hreflang, sitemaps, llms.txt, robots, IndexNow, OG, product/location feeds. `scripts/seo-gate.mjs`, public-gates. | Built | C2.20–C2.22, C1.18. |
+| 6 | Cross-module flows | C11.01–C11.07 journeys prove the compounding paths with adapter doubles. | Built | Live provider sessions/charges not claimed. |
+| 7 | Original v1 slice | Historical dependency rationale. Subscriptions, gift cards, PayPal, voice/video plugins all later shipped. | Doctrine | Not a live backlog. Auto-clip struck (see §3). |
+| 8 | Design decisions | Custom fields jsonb, multi-currency without auto-FX, tax templates, en/fr/es/ar, logical CSS, hreflang in core. | Built | Arabic RTL catalog shipped 2026-09-16 (C11.12 closed); `dir` derives from the locale's script. |
+| 9 | Stack | Next App Router, strict TS, Drizzle, Postgres, pg-boss, S3 adapter, Tailwind, ICU, Zod, hand-rolled sessions. | Built | Lucia is the pattern, not a dependency. |
+| 10 | Repository layout | Matches the tree with the as-implemented notes in MASTER. Packages: sdk, create-freeholder, templates, mobile-app, cli, plugin-kit. | Built | Struck `adapters/fx`. Public routing is the catch-all, not per-section files. |
+| 11 | Module contract | `defineModule` manifests, tables, services, events. Modules do not import each other. | Built | C3.08–C3.12. |
+| 12 | Adapter contract | Payments (Stripe, PayPal, manual, Square, Mollie, Razorpay, Paystack, Flutterwave), mail (Gmail/Outlook/Resend/Postmark/SES/SMTP), storage, SMS Twilio, AI, agent, POS Stripe/manual, social, tax/carrier/calendar `none`. | Built | **Struck Mercado Pago as in-plan.** C5.07 shipped the four named “after 1.0” adapters. Accounting is export shapes (C9.32), not an adapter family. |
+| 13 | Setup wizard | `/setup` country/locale/currency/timezone, owner, modules, demo. | Built | C1.24–C1.25. |
+| 14 | Replit-first deploy | `.replit`, `replit.nix`, `create-freeholder`, `env.ts`, doctor, ownership export. | Built | Struck MIT on the scaffolder (Apache-2.0, C0.10 / §22). |
+| 15 | Quality gates | typecheck, lint, tests, SEO, i18n, money, service-layer, changelog, a11y, upgrade, schema-compat, autofill, perf harness. | Built | C11.11 closed 2026-09-28: all thirteen §15.1 budgets pass on the reference target with archived evidence (`deploy/perf-reference-run-2026-09-27.log`, summary in `deploy/performance-measurements.md`). Upgrade gate needs published images. |
+| 16 | Agent conventions | CLAUDE.md, one C-item per change, DCO, changesets. | Built | C0.08, C0.12. |
+| 17 | Configuration | `freeholder.config.ts`, env Zod, doctor. | Built | C3.16 recipes. |
+| 18 | Recipe anatomy | Six recipe directories with README / env / infra / verify. | Built | C3.16–C3.17. |
+| 19 | Support tiers | Tier-1 vs community labelled in recipes. | Built | C3.16. |
+| 20 | Replit recipe | `deploy/replit/`. | Built | C3.16. |
+| 21 | DigitalOcean | App Platform + droplet recipes. | Built | C3.16, C10.10. |
+| 22 | create-freeholder | `packages/create-freeholder`, Apache-2.0. | Built | C3.14. |
+| 23 | Migration matrix | Ownership export + `scripts/ownership-drill.mjs --all-pairs`. | Built; acceptance incomplete | C11.08 was reopened because the 2026-09-28 two-droplet drill had no source object bytes. Actual same-host S3 byte transfer and signed host update/rollback passed on 2026-10-05; the complete cross-target final-candidate journey remains open (`deploy/stable-acceptance-2026-10-05.md`). |
+| 24 | Plugins: the design bet | `src/core/plugins`, `packages/plugin-kit`, isolate, first-party plugins under `plugins/`. | Built | C3.08–C3.13. |
+| 25 | Plugin DX | Scaffolding, fixture instance, contract tests, `packages/plugin-kit`. | Built | C3.12. |
+| 26 | Trust model | Signed install, capability isolation, hostile-plugin refusals. | Built | C3.10–C3.11. |
+| 27 | Federated registries | Local/community/verified/private registries. | Built | C3.11. |
+| 28 | Living platform contract | OpenAPI, SDK, MCP, `llms.txt` generated from the registry. | Built | C3.01–C3.07. |
+| 29 | Ecosystem | First-party plugins teach the API by existing. | Built | C3.13 gift/print/community/voice-video/marketplace (closed 2026-09-28). |
+| 30 | CRM depth | Pipelines, tasks, notes, segments, scoring, saved views, imports, newsletters, templates. `/admin/pipeline`, tasks, segments, scoring, newsletters. | Built | C7.01–C7.07, C9.04–C9.06. |
+| 31 | Front-site assistant | Grounded assistant, guardrails, corpus. `/admin/assistant`, public block. | Built | C9.21–C9.23. |
+| 32 | Universal editor | Block editor, sections, templates, layouts, tokens, experiments, email-safe output. `/admin/pages`, sections, templates, design, experiments. | Built | C2.01–C2.23. |
+| 33 | Social hub | OAuth, ingest, composer, GBP, publication calendar. `/admin/social`. | Built | C9.24–C9.27, C9.31. Auto-clip struck. |
+| 34 | Sharing DNA | Share targets, tracked links, gallery partner, quote partner, product/gift share, embeds. `/admin/sharing`, embed routes. | Built | C9.28–C9.29, C9.34–C9.36. |
+| 35 | React Native app | `packages/mobile-app`, `apps/mobile`, screen contracts, push tokens, private cache, companion/capture code, `freeholder-app init`, store/CI gates. | Deferred to v2 | Owner decision 2026-09-15 (§43.18): C10.17, C10.18, C10.25, C10.26, C10.27, C10.28 and C10.30 defer to v2 with obligations verbatim. C10.15 init and C10.16 store/CI gates are checked. Signed store binaries still need EAS credentials. |
+| 36 | Mined roadmap | Core absorptions and first-party plugins match C3.13 / C5–C9. Anti-roadmap held. Autofill gate §36.1 / §15.10. | Built | Anti-roadmap is exclusion, not leftover. C3.24–C3.26 closed 2026-09-29 (`deploy/c324-storefront-parity-2026-09-29.md`): native storefront parity against Shopify-core capability (owner decision 2026-09-27); the importer is a migration bridge. |
+| 37 | Self-building instance | Builder content + code lanes, MCP, `/source`, budgets, approvals. `/admin/builder`. | Built | C4.19–C4.22. GitHub PR delivery still needs a connected repo (C11.06 honesty). |
+| 38 | Day-one surface | Demos, guidance, capture, services, calendars, catalog, shipping/tax, passes, loyalty, SMS, subscriptions, ads, time, POS, projects, galleries, SEO, CRM, automations, reporting, roles, export, help, waivers, updates. | Built except named leftovers | In-person Terminal is adapter representation (C5.24), not a claimed live reader. 3D/AR is accepted media roles (C5.11), not a storefront AR viewer. |
+| 39 | Staying current | Channels, signed feed, checks, preflight, apply/rollback, N-1, policy, fork lane, targets, admin/CLI/MCP. `/admin/updates`. | Built | C10.01–C10.11, C10.19–C10.22. |
+| 40 | Agent orchestration | Connections, workers, tasks, runs, approvals, spend, playbooks, pause/kill. `/admin/work`. | Built | C4.01–C4.10, C4.23. |
+| 41 | Connected accounts | OAuth, encrypted credentials, calendar/mail grants, busy union. `/admin/settings` connections. | Built | C4.10–C4.13, C4.18. Live Google/Microsoft sessions not claimed (C11.07). |
+| 42 | Briefing | Briefings, contributions, preferences, playbook schedules. `/admin/briefing`. | Built | C4.14–C4.17. |
+
+## Struck in this change (were affirmative, are not built, had no open C-item)
+
+These are removed from §§1–42 so C11.16 is not papering over them:
+
+1. **`BookingSeries`** as a required entity — occurrences are `Booking` rows.
+2. **`LicenseKey`** and `DigitalFulfillment` sibling fields (`license_template_id`, `watermark_policy`) — digital access is `digital_deliveries`.
+3. **Stripe Connect / payout-provider adapter as DONE** — C9.10 CSV/manual is the shipped path. `PayoutBatch.method` is `manual`.
+4. **Social auto-clip as a v2 DONE feature** — C9.26 ships reviewed variants; auto-clip is not in the plan.
+5. **Dedicated public `/changelog` route** — `/admin/updates` is the instance log.
+6. **`LocaleSetting` / `CurrencySetting` / `FxRate` tables and `adapters/fx`** — profile columns; no auto-FX.
+7. **`SeoSetting` table** — redirects + profile + page SEO.
+8. **`/docs/deploy`** — `deploy/`.
+9. **MIT on `create-freeholder`** — Apache-2.0.
+10. **Mercado Pago as in-plan** — not a C-item; C5.07's four adapters shipped.
+11. **Named Stripe Tax / Avalara / TaxJar implementations** — tax `none` + templates. §4.12's leftover “replacement family” sentence, and §3's “Stripe Tax et al” seam label, now match.
+
+## Remaining affirmative work (open checklist items)
+
+These stay in the spec. They are why C11.17 cannot be checked.
+
+| Item | What is still true |
+|---|---|
+| Native storefront parity | Closed: C3.24–C3.26, capability mapping and native commerce journeys in `deploy/c324-storefront-parity-2026-09-29.md`. The Shopify importer remains a migration bridge. |
+| Device evidence | Not v1 remaining work: owner decision 2026-09-15 (§43.18) defers C10.17, C10.18, C10.25, C10.26, C10.27, C10.28 and C10.30 to v2 with obligations verbatim. C10.15 init and C10.16 store/CI gates are checked. |
+| Independent security review | C11.10 — packet at `security/independent-review-packet.md` is not a signed review. |
+| Live settlement | C11.05 remaining honesty. Manual/offline and adapter doubles are what journeys run. Hosted Stripe/PayPal charges are not claimed. |
+| C11.08 Tier-1 restore | Reopened 2026-10-05: the prior drill had no source object bytes. The isolated HTTP restore in `deploy/stable-acceptance-2026-10-05.md` proves one real uploaded object and page on local storage, not the Tier-1 S3 migration and final candidate upgrade/rollback. Historical 2026-09-28 database proof: the live restore drill (`deploy/c11-08-restore-summary.md` + dated drill log): real export → provision a second droplet from the recipe → `pg_restore` into an empty database → verify before cutover; target re-export matched the source on 366/374 tables with every owned total exact, `pnpm doctor` 16 ok / 14 warn / 0 fail, seeded public page served through the target's Caddy. Fresh demo + WordPress/generic import + local signed apply/rollback predate it (2026-09-12). |
+| C11.11 large seed | Closed 2026-09-28 on the 2026-09-27 reference-target acceptance run: all thirteen §15.1 budgets pass on the provisioned `freeholder-ref` droplet against the verified medium dataset — public render 203ms p95 (274ms on-box), LCP 432ms p75, INP 16ms p75, CLS 0.00064, admin 732/661ms p95, search 499ms p95, report 544ms p95, editor first paint 488ms p95, keystroke→preview 119.8ms raw at the harness floor, queue 1,219ms p95, migration chain 49.1s, cold boot 7.81s p95. Every raw sample archived in `deploy/perf-reference-run-2026-09-27.log`; summary and honest caveats in `deploy/performance-measurements.md`. The spec-reconciliation gate was re-aimed with this check: C11.11 moved from "must stay unchecked" to "must be checked" (`tests/core/spec-reconciliation.test.ts`), the same way C11.08's check arrived the same day. |
+| C11.12 leftovers | Closed 2026-09-16: `locales/ar.json` ships the complete Arabic catalog (i18n-gate enforced, AI-drafted pending native review); the real-browser suite proves `html[lang=ar][dir=rtl]` with axe in both themes, keyboard loop and 320px reflow on admin, storefront and portal; populated contact/invoice/product/appointment detail forms and ten more owner screens carry the same pass. |
+| C11.14 leftovers | `search.query` covers registered live sources; other titled contact-attached stores (orders, subscriptions, remaining SEARCH_TABLE_OPT_OUTS) stay per-list. Per-record restore now covers note/task trash, media/product restoration, merge-undo, the instance drill and trash/restore/purge for pages, forms, popups, segments and saved views (`deploy/record-trash.md`, `tests/core/record-trash-families.test.ts`); money ledgers, append-only evidence, credentials and never-deleted families are named not-applicable. Retention is a bounded per-kind policy registry + `core.applyRetention` job (privacy holds honoured; consent/audit/accounting opted out), not a TTL column on every table. |
+| C11.15 | Closed 2026-09-16 by `deploy/doc-claim-mapping.md` + `tests/core/doc-claim-mapping.test.ts`: every affirmative §§1–42 claim is mapped to passing evidence or struck in the same change; the mapping gate refuses unmapped claims, unresolved paths and stale strike text. |
+| C6.11 paid events | Free registration, capacity locking and check-in are implemented; `events.register` refuses paid tickets. Canonical invoice/settlement, held seats, expiry/refunds and paid check-in are remaining product work. The MASTER item is reopened. |
+| C11.16 | Re-reconciled 2026-10-04 against `04c27ca5`: storefront/editor closures recorded, but independent review and provider acceptance remain unverified. Its box stays open pending final evidence reconciliation. |
+| C11.17 | Unsigned. Owner must sign the §43.1 record after the clean-room suite. |
+
+## Anti-roadmap (correctly not built)
+
+Multi-tenancy, payroll, full bookkeeping and tax filing, multi-level referrals, warehouse/WMS depth, a general mail client, core voice/video implementations, third-party surveillance as core, page-builder lock-in formats, dropshipping marketplaces, crypto payments, raw card data.
+
+Marketplace channel sync and gated communities are first-party plugins (C3.13), not core.
+
+## C11.17 clean-room suite (command list)
+
+Run from the repository root. This is the suite the owner signs; this change
+runs whatever the worktree can run (no Docker images, no second Tier-1 host,
+no physical device).
+
+| Command | What it proves | This worktree 2026-09-13 |
+|---|---|---|
+| `pnpm plan:check` | §43 ids, evidence, proofs, current focus | ran: 297 IDs, 269 checked, 28 open |
+| `pnpm exec tsc --noEmit` | types, including C11.02 `onHand` narrowing | ran: clean |
+| `node scripts/license-headers.mjs` | SPDX | ran: clean |
+| `node scripts/changelog-gate.mjs` | changeset + CHANGELOG version | ran: clean |
+| `pnpm exec vitest run tests/core/spec-reconciliation.test.ts tests/core/plan-gate.test.ts tests/core/changelog-output.test.ts` | recon + plan + changelog output | ran: clean |
+| `pnpm gates` | tsc, lint, license, changelog, plan, contract suites | **not green:** lint is red on pre-existing `messaging` schema imports, pipeline `toFixed`, work-form literals; contract suites fail `mobile-private-cache` (C10.30 tsconfig, no `TEST_DATABASE_URL`) |
+| `pnpm test` | Vitest unit/service/db suite | skipped: `TEST_DATABASE_URL` unset |
+| `pnpm test:journeys` | Playwright C11 + journeys | skipped: no app/db |
+| `pnpm test:a11y` | Playwright axe | skipped: no app/db |
+| `pnpm ownership:drill` | §23 pair matrix | skipped: no `psql` |
+| `bash scripts/upgrade-gate.sh` | §39.9 previous-image upgrade | skipped: no Docker, no `PREVIOUS_IMAGE` |
+| `bash scripts/public-gates.sh` | SEO crawl of seeded image | skipped: no Docker |
+
+A green local `plan:check` is not C11.17. Journeys, ownership-drill and
+upgrade-gate belong on CI or a signed owner run. Do not treat this table as
+DONE.
+
+## What this file does not claim
+
+- Product DONE.
+- Independent security review.
+- Live payment-provider settlement.
+- Native store submission or a physical-device walkthrough.
+- That every F04 screen has been axe-walked in this worktree.

package/dist/template/deploy/stable-acceptance-2026-10-05.md

@@ -0,0 +1,168 @@
+<!--
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+-->
+# Stable release preparation evidence — 2026-10-05
+
+This is evidence for MASTER.md C11.08/C11.16/C11.17. Stable is unpublished;
+C11.10 has no independent reviewer and the owner signature remains unsigned.
+
+## Fresh image and actual object restore
+
+Baseline source: `04c27ca5f251164e9d385b1cd05449f341119262`, signed main image
+`ghcr.io/campdenman/freeholder@sha256:597aa25d4fb5fc20ff79501e60ed8f7434e775023b6800432ea7b96013c627dd`.
+The disposable fixture used PostgreSQL 16 and private loopback HTTP ports on the
+existing DigitalOcean host. The database, credentials and storage directories
+were separate from production and the public playground.
+
+Eight HTTP acceptance assertions passed:
+
+1. Missing/incorrect independent bootstrap secret refused (401).
+2. Correct bootstrap created the first owner (201), issuing session/CSRF cookies.
+3. A second owner claim refused (409).
+4. Session-bearing business-profile mutation without CSRF refused (403).
+5. Real TOTP enrollment and confirmation succeeded, issuing recovery codes.
+6. First-boot business setup completed and locked.
+7. A two-block page published and served its expected text over HTTP.
+8. Multipart upload stored and served an actual PNG with identical original bytes.
+
+The source app was stopped before `pg_dump -Fc` and media archive creation,
+then restarted. The database archive was restored with `pg_restore` into a
+second empty database; actual media files were restored into a separate
+private directory. A second instance using the same immutable image returned
+healthy status, the published page (200), and the uploaded original (200).
+
+| Artifact | SHA-256 |
+| --- | --- |
+| Database archive | `39453e47c6acf5963c6513b3abad05dfb296dff651f725a25d3a04ebf12d093f` |
+| Media archive | `ff7f75ed2b1ca8eff7182327c2f1736f6fbf8a31bdcf643f264f6039bc68abfa` |
+| Uploaded and restored original PNG | `3cfe4d361cf37dd566bca35f3f2ef96510bd07d9beb01f4e77592f9d616a50dd` |
+
+This is an isolated **local-storage** image rehearsal. It establishes recovery
+of actual object bytes, unlike the old metadata-only fixture. It does not
+establish cross-target Tier-1 S3 transfer or the final candidate's upgrade and
+failed-update rollback. The baseline predates this round's security/release
+repairs. No real payment provider was configured or charged.
+
+## Package and release preparation
+
+`pnpm packages:verify` built, packed, installed and exercised all seven workspace
+packages outside the workspace. Six packages belong to the public v1 publisher;
+the mobile package remains deferred. This proves packed artifacts, not public
+registry installation. The release contract gate passed 347 tests in 37 files;
+focused database-backed release/feed/fork checks passed 50 tests in five files.
+The release PR and security PR both passed their full protected PR CI runs.
+Merge-queue/main runs are separate required gates before deployment.
+
+The npm CLI subsequently authenticated as `campdenman`; `npm org ls freeholder`
+confirmed that account is the `@freeholder` organization owner. The namespace
+currently contains no packages. All seven proposed `0.2.0-beta.1` artifacts also
+passed the packed install/usage gate, and eleven version/publication integrity
+assertions passed. This beta preparation is private and unpublished; it does not
+close public registry acceptance or imply the owner chose that release channel.
+
+The existing workflow still requires `NPM_TOKEN`; no repository publishing token
+or package trusted publisher has been configured. npm's current publishing rules
+require publishing authentication beyond account login. The authenticated account
+and local pack test are separate from a successful authenticated public publish.
+No credential is included in this record.
+
+## Actual S3 object transfer and signed host update
+
+A disposable SeaweedFS 4.48 S3-compatible server used fresh fixture-only access
+credentials, separate `release-source` and `release-target` buckets and private
+storage on the existing host. Its immutable image was
+`chrislusf/seaweedfs@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d`.
+Production media/backup buckets and credentials were not used by this test.
+
+The real HTTP bootstrap/publish/upload journey ran against a fresh S3-backed
+source. With its app stopped, `pg_dump -Fc` produced archive SHA-256
+`102c567224a3c5e68f123951f0361fda532ee6371fd2fc3881f836feef844fa7`.
+`ownership-export.mjs` exported 377 tables, 785 rows and one actual media asset.
+`media-transfer.mjs` copied and verified one object (68 bytes) between the two
+buckets. A second empty database was restored with `pg_restore --exit-on-error`;
+the target app returned healthy status, the published page and the original PNG
+with SHA-256 `3cfe4d361cf37dd566bca35f3f2ef96510bd07d9beb01f4e77592f9d616a50dd`.
+This proves actual S3 API transfer and object recovery on an isolated same-host
+fixture; it is not managed storage or a different physical Tier-1 host.
+
+The exact merged source `449fe0efe3867f3e08ee4505980be62e1dd8c009` passed main
+[CI run 37281161334](https://github.com/CampDenman/freeholder/actions/runs/37281161334)
+and [image publication 37283078916](https://github.com/CampDenman/freeholder/actions/runs/37283078916).
+The deployment tool verified provenance and resolved the Linux amd64 image to
+`ghcr.io/campdenman/freeholder@sha256:cac139fca13101e5e614adf84b030c8777106914e71de4f6c961569324d80495`.
+
+A separate app/db/Caddy Compose installation restored that S3 database and used
+the target fixture bucket. The real `scripts/docker-updater.py` host executor
+verified the candidate's exact main-workflow cosign identity and forward ancestry,
+backed up the database, restored a shadow instance and checked schema/journal,
+worker readiness and HTTP smoke routes. It reported `schemaChanged: false`.
+
+A test-only subclass injected one explicit failure after the candidate's real
+live-container smoke succeeded. During cutover the Caddy endpoint returned 503.
+The executor recorded `rolled_back`, restored the previous immutable image and
+independently verified health and smoke routes before reopening traffic. This
+exercises actual container/proxy recovery; it does not test migration-changing
+rollback, because this candidate has no schema change.
+
+A second unmodified executor run completed the same signed upgrade successfully.
+After traffic reopened, the restored page and the S3 original were served over
+HTTP with identical content and SHA-256; workers were ready. C11.08 stays open
+for the complete normative cross-target/candidate acceptance journey.
+
+## Outstanding findings reflected in MASTER
+
+- C6.11: paid event admission is explicitly refused. No invoice/settlement/seat-hold
+  flow exists. Free registration and capacity locking do not close this gap.
+- C11.05: manual/mocked entitlement journeys passed; actual configured provider
+  checkout, signed webhook settlement and subscription lifecycle remain unverified.
+- C11.08: same-host S3 object transfer/recovery and the signed edge-image host
+  update/failed-cutover rollback passed. The complete cross-target final-candidate
+  journey remains open; the older two-droplet drill had no source object bytes.
+- C11.10: independent review remains unchecked at the owner's request.
+- C11.16/C11.17: reconciliation, final clean-room acceptance and owner signature
+  remain open. The publisher must refuse a final stable tag while these are open.
+
+## Newly reported mobile dependencies
+
+GitHub reports two high alerts in `apps/mobile/package-lock.json`: node-forge
+1.4.0 (alert #6) and braces 3.0.3 (alert #7). The root pnpm workspace excludes
+`apps/mobile`; a clean root audit does not clear these alerts. Mobile lock entries
+are not marked development-only. node-forge is reached by `@expo/cli` and
+`@expo/code-signing-certificates`; braces is reached by micromatch. This describes
+the dependency graph, not a completed runtime reachability review.
+
+The reviewed [node-forge advisory](https://github.com/advisories/GHSA-86w9-cpqp-85rv)
+and [braces advisory](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm) list no
+patched version as of this check. Mobile remains v2-deferred. Neither alert was
+dismissed or waived; review exposure, follow upstream repairs, and retest before
+shipping mobile. These dependencies are separate from the v1 server's audited
+pnpm graph.
+
+## Production and playground deployment
+
+The production recipe deployed the verified `449fe0ef` immutable image above.
+It uploaded the database archive and checksum before changing the image pin,
+then reported schema readiness and public health success. `freeholder.ai`
+returned 200 with 1,519 services and all 87 mounted workers ready; `www` resolved
+to the canonical HTTPS health URL. The homepage returned 200 and contained no
+“Built by WeVibeSites” branding.
+
+The playground's independent image pin was updated to the same digest and its
+fixed Compose reset recipe recreated only the playground app/database. The
+production environment was not copied. Public demo health returned 200 with
+1,519 services, ready workers, zero failed jobs and zero dead letters.
+
+A real Chromium browser on `demo.freeholder.ai` entered as a visitor, created a
+page, added a heading, waited for Saved, published it and read the public text.
+It reopened the editor, changed the words, waited for Saved, clicked Publish
+changes and read the new public text. The button completed and no false
+“This page changed after you opened it” conflict appeared. The same visitor's
+invitation, mail test and upload-staging API calls each returned 403.
+
+These checks exercise the running deployment and a disposable demo page; they
+are separate from the full protected browser CI suite. The demo was reset after
+the mutation proof. A browser carrying the old session was redirected to the
+playground entry, the test page returned 404, and a fresh visitor could enter
+the reseeded admin. Eight documentation/reconciliation assertions and the plan
+and license gates passed for this evidence update.

package/dist/template/deploy/update-admin.md

@@ -0,0 +1,83 @@
+<!--
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# The update screen
+
+*MASTER.md §39.10, checklist item C10.20.* Lives at `/admin/updates`.
+
+§39.10 asks for *"a status line that is never ambiguous… with the notes and one
+button."* This is that screen — and it is where a debt gets paid.
+
+## The debt
+
+C10.01 through C10.11 each shipped with their **F04** recorded as a Doctor
+check, *"not a new admin screen (C10.11)"*. Eleven items deferred their human
+surface to one checklist line. An owner cannot be expected to run `doctor` in
+a terminal to find out they are two security releases behind, so everything
+those items built is visible here.
+
+| Item | What it put on this screen |
+|---|---|
+| C10.01 | the customization seams, via the fork panel's owned-vs-core split |
+| C10.02 | the release channel selector |
+| C10.03 | the signed-feed list, and an **Unverified signature** pill |
+| C10.04 | last-checked time and *Check for updates now* |
+| C10.05 | *Run preflight* |
+| C10.06 | run history, snapshots, release notes |
+| C10.07 | the schema-breaking pill |
+| C10.08 | the whole policy editor and the pause switch |
+| C10.09 | the fork panel and *Open an upstream merge pull request* |
+| C10.10 | what updating and rolling back mean on each target |
+| C10.11 | the status line itself, and the rollback horizon |
+
+## Sections
+
+**Status line.** Tone follows posture: `behind-security` is danger,
+`behind` is accent, `unknown` is warning, `current` is success. `unknown` is
+shown rather than hidden — an instance that has never completed a check has
+not been told it is safe.
+
+**This instance.** Version, channel, last checked, deploy target and the
+earliest version still reachable by rollback (§39.11). If no deploy target is
+declared, a warning says plainly that applying an update will migrate and
+smoke but swap nothing — because it will otherwise look like it worked.
+
+**Update available.** The notes link and the one button. Applying carries a
+typed confirmation: it cuts a live site over to a new build, and §39's
+argument is that this is safe *because* it is deliberate, snapshotted and
+reversible — not because it is easy to trigger by accident.
+
+**What the signed feed offered.** Each cached release with its CVSS, whether it
+breaks schema, whether its signature verified, and a per-row reason saying
+whether it can be applied from this version.
+
+**Policy.** Channel, auto-apply level, the nights and start time (stated in the
+business timezone), drain, snapshot retention and notification channels. Pause
+and resume are the same save with one field changed, not a second write path —
+two ways to change `pausedUntil` is two places for pruning and validation to
+diverge.
+
+**Targets.** All six Tier-1 recipes, their strategy, what their rollback needs
+and what cutover costs. An owner leaving automatic updates on overnight should
+know that Replit means minutes of rebuild and a droplet means seconds.
+
+**Fork lane.** Only when this instance is a git checkout. Drift, missing
+security releases, how many diverging files are the owner's (upstream will not
+overwrite them) and how many are core (they may conflict).
+
+**History.** Every run this instance has attempted, kept forever, with its
+trigger and outcome, plus the release notes drafted along the way.
+
+## Design and access
+
+Every action goes through the same services the CLI (C10.21) and MCP (C10.22)
+call — the admin is a caller, never a shortcut. The screen requires the
+`platform` module grant. Each action is its own form with its own pending
+state: applying an update and saving a policy are days apart in consequence,
+and one submit button that could mean either is how an owner cuts over a live
+site while trying to change a checkbox.
+
+Colours come from semantic tokens only, so the screen ships in light and dark,
+and `/admin/updates` is in the real-browser accessibility sweep.

package/dist/template/deploy/update-apply.md

@@ -0,0 +1,48 @@
+# Apply and roll back
+
+Automatic `platform.applyUpdate` and `platform.rollbackUpdate` are unavailable.
+The separate opt-in [Docker host executor](docker-selfhost/docker-updater/README.md) (C10.31)
+provides owner-requested and scheduled image updates only when a restored-backup
+rehearsal proves the database schema and migration journal remain unchanged; an
+explicit `allow_schema_changes` opt-in admits migration-changing candidates
+whose rollback restores the write-free cutover backup. The sibling
+[host updater](host-updater.md) (C10.06) gives the remaining hosting targets a
+verified executor: digest-pinned immutable artifacts, a backup hook that must
+produce a real file, health checks, and independently re-verified rollback.
+Everything else still uses the manual procedure below.
+The previous implementation did not create recoverable backups, execute
+migrations or verify a candidate deployment, and could report a successful
+rollback after rollback failed. It has been removed (C10.06/C10.10/C11.10).
+Preflight without a signed feed fails its authenticity check.
+
+For an operator-managed update:
+
+1. Schedule maintenance and stop writes. Record the currently running image's
+   immutable digest and retain the exact deployment configuration.
+2. Create a PostgreSQL custom-format backup using `pg_dump --format=custom`,
+   protect it like production data, and restore it into a separate database with
+   `pg_restore`. Verify records and application access there. Back up configuration
+   and follow the object-store backup policy too; a database dump excludes media.
+3. Verify the release signature and provenance, and pin the candidate as
+   `ghcr.io/campdenman/freeholder@sha256:<verified digest>`. Test its migrations
+   against the restored database and exercise the site's enabled workflows.
+4. Deploy the pinned candidate using the target's operator tooling. Run its real
+   migrations and verify health, login, content and enabled business workflows
+   against the candidate before reopening traffic. Retain the backup and old image.
+5. If verification fails, keep maintenance enabled. An image swap back is safe
+   only when the previous build can read the migrated schema. Otherwise restore
+   the tested backup and compatible configuration, accounting for any writes
+   accepted since the backup. Verify recovery before reopening traffic.
+
+For Docker self-host and Droplet, `FREEHOLDER_IMAGE` controls the deployed image.
+Set `PREVIOUS_FREEHOLDER_IMAGE` to the recorded immutable digest before invoking
+an operator rollback. Missing pins now fail instead of silently selecting edge.
+Cloud recipes require equivalent immutable deployment artifacts and recovery
+verification through their provider tooling.
+
+`platform.listUpdateRuns` remains available for historical inspection. Legacy
+snapshot fingerprints contain no recoverable row data and must not be used as
+restore points. Unattended updates exist again only as these independently
+verified host executors: start each with its operator schedule disabled, prove
+the refusal and recovery paths on your installation, and only then enable the
+daily schedule.

package/dist/template/deploy/update-checks.md

@@ -0,0 +1,27 @@
+# Daily update checks
+
+This instance checks for updates once a day. The check reads public release metadata and GETs its signed
+static feed. It sends no instance identifier and reports nothing upstream.
+
+Checking is on unless `FREEHOLDER_UPDATE_CHECK=off`. Turn it off if you would
+rather watch a mailing list. Filing a bug or a patch is `contribute.submit`;
+that write is not this check.
+
+The default endpoint is GitHub’s public release list:
+
+`https://api.github.com/repos/CampDenman/freeholder/releases`
+
+The updater selects the most recently published version carrying `releases.json`,
+including a beta, then GETs that tag’s asset from the fixed upstream repository.
+The feed must verify against embedded keys before channel/version selection.
+A newer beta feed retains signed history; stable policy still refuses edge releases.
+This works before the first stable release, when GitHub’s `/latest` is unavailable.
+
+Override with `FREEHOLDER_UPDATE_FEED_URL` if you pin a mirror. The URL must
+be a public http(s) origin and must not carry query parameters.
+
+Jitter is a deterministic 15-minute UTC slot derived from this instance's
+`APP_URL`, used only locally so a fleet does not stampede one endpoint. The
+URL is not sent with the request.
+
+This is not unattended self-update. Applying a release is C10.06.

package/dist/template/deploy/update-escalation.md

@@ -0,0 +1,71 @@
+<!--
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# The security escalation, and update tools for agents
+
+*MASTER.md §39.10, checklist item C10.22.*
+
+§39.10's fourth surface: *"a security release outstanding beyond a set period
+escalates to a notification, because silence must not be indistinguishable
+from safety."*
+
+That last clause is the whole design. Every other part of the updater is
+something an owner has to go and look at — a screen, a CLI, a tool an agent
+calls. This is the one part that comes and finds them, because the failure mode
+of an updater is not a wrong answer. It is nobody asking the question for three
+months.
+
+## Severity sets the clock
+
+| Band | CVSS | Escalates after |
+|---|---|---|
+| critical | 9.0+ | 24 hours |
+| high | 7.0–8.9 | 48 hours |
+| medium | 4.0–6.9 | 96 hours |
+| low | below 4.0 | 168 hours |
+
+Treating a 2.1 like a 9.8 is how an owner learns to archive these unread — at
+which point the escalation has made things worse than silence, not better.
+
+The notification is `critical` priority for everything but the low band, so it
+escapes a digest. A CVSS 9 release that waits for the weekly summary has not
+been escalated, it has been filed.
+
+## What it will and will not do
+
+- **It names the worst overdue release**, not the oldest one on the list.
+- **It ignores unscored releases.** A release with no CVSS is news, not
+  exposure.
+- **It escalates once a day at most.** The idempotency key is bucketed by
+  version and day, so the hourly job does not nag — and a *newer* security
+  release still gets its own alarm rather than being swallowed by an earlier
+  one's dedupe.
+- **It keeps escalating while updates are paused.** §39.6 lets an owner turn
+  automatic applying off. It does not let the platform stop saying they are
+  exposed — that sentence is what made pausing a safe thing to offer.
+- **It goes to owners**, not staff: applying an update needs the `platform`
+  grant, so telling anyone else would be telling somebody who cannot act.
+
+Job: `core.escalateSecurityUpdates`, hourly.
+Topic: `platform.securityUpdate`, linking to `/admin/updates`.
+
+## Update tools for agents
+
+Every update service is an MCP tool, generated from the registry like the rest
+of the platform (§28.3) — so *"am I up to date?"* and *"apply security updates
+tonight"* are things an owner can say to their own assistant.
+
+**Reading status and applying an update are separate scopes**, as §39.10
+requires. API-key scopes are per service name or per family:
+
+| Scope | Can |
+|---|---|
+| `platform.updateStatus` | read status only |
+| `platform.applyUpdate` | apply, and nothing else |
+| `platform.*` | everything the platform family exposes |
+
+A monitoring key scoped `platform.updateStatus` cannot cut a site over. That is
+enforced by `permits()` and pinned in
+`tests/core/update-escalation.test.ts`, not left to convention.

package/dist/template/deploy/update-policy.md

@@ -0,0 +1,20 @@
+# Update policy
+
+Defaults are for the owner who never opens this screen: **security updates
+apply automatically**, in a night window in the business timezone, with drain
+and snapshots. Feature updates wait for approval.
+
+| Field | Default |
+|---|---|
+| channel | `security` |
+| apply | `security` |
+| window | Tue–Thu 03:00–05:00 in the business timezone |
+| drain | on |
+| keep_snapshots | 5 |
+
+Outside the window the updater skips rather than forcing a cutover. Pause with
+`pausedUntil`. `channel: off` is the runtime off path; `FREEHOLDER_UPDATE_CHECK=off`
+is the deploy-time one.
+
+`platform.getUpdatePolicy`, `platform.saveUpdatePolicy` and
+`platform.evaluateUpdatePolicy` are the services. Admin UI is C10.11.