create-nextblock 0.15.5 → 0.15.9

package/templates/nextblock-template/components/commerce/PaymentReadinessBoundary.tsx

@@ -0,0 +1,32 @@
+import { getStoreReadiness } from '@nextblock-cms/ecommerce/server';
+import { PaymentReadinessProvider } from '@nextblock-cms/ecommerce/PaymentReadinessProvider';
+
+/**
+ * Supplies payment readiness to the buy controls beneath it.
+ *
+ * Deliberately NOT mounted in the root layout: readiness is only consulted by buy CTAs
+ * and the checkout, so a blog post or a landing page should not pay for the lookup. Each
+ * commerce block renderer wraps itself in this instead, which also means nested cases
+ * (a product grid inside a section) are covered without anyone having to walk the block
+ * tree looking for them.
+ *
+ * getStoreReadiness() is request-cached, so several of these on one page cost one read.
+ * Any failure yields no readiness at all, and the context default ("everything ready")
+ * keeps a working store working.
+ */
+export default async function PaymentReadinessBoundary({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  let readiness: { stripe: boolean; freemius: boolean } | null = null;
+
+  try {
+    const store = await getStoreReadiness();
+    readiness = { stripe: store.stripe.ready, freemius: store.freemius.ready };
+  } catch (error) {
+    console.error('[PaymentReadinessBoundary] Could not resolve payment readiness:', error);
+  }
+
+  return <PaymentReadinessProvider readiness={readiness}>{children}</PaymentReadinessProvider>;
+}

package/templates/nextblock-template/docs/05-DEVELOPER-GUIDE.md

@@ -7,8 +7,8 @@ setup helper in `tools/scripts/setup.mjs`.
 
 ### Prerequisites
 
-`npm run setup` is interactive and asks for credentials from three services, so
-create them first:
+Configuration happens in the browser, not the terminal — but the wizard asks for
+credentials from these services, so have them ready:
 
 1. **Supabase project** (https://supabase.com/dashboard) — Reference ID
    (Project Settings → General), connection string (Connect → Direct connection →
@@ -25,24 +25,30 @@ create them first:
 
 ```bash
 npm install
-npm run setup
-npx nx serve nextblock
+npm run setup            # prints the next steps — it asks nothing
+npx nx serve nextblock   # then open http://localhost:4200/setup
 ```
 
-What `npm run setup` does:
+`npm run setup` (`tools/scripts/setup.mjs`) is **informational only**. It writes
+no files, prompts for nothing, and touches no database — it just points you at
+the browser wizard. Terminal-based configuration was removed; everything below
+now happens in the **First-Boot Setup Wizard** at `/setup`:
 
-- creates `.env.local` from `.env.exemple` if needed
-- prompts for Supabase, Cloudflare R2, and SMTP details (all required)
-- writes `NEXT_PUBLIC_URL` and auto-generates `CRON_SECRET`,
-  `DRAFT_MODE_SECRET`, and `REVALIDATE_SECRET_TOKEN`
-- links the local Supabase CLI workdir to your project (`npm run db:link`)
-- applies the full schema baseline to the new database
-  (`npm run db:migrate:fresh`)
-- syncs hosted Supabase Auth — custom SMTP and branded email templates
-  (`npm run configure:supabase-auth`)
+- connecting Supabase and saving the credentials
+- applying the schema to the new database
+- configuring media storage (R2, or the connected Supabase project's storage)
+  and outbound email
+- creating the first administrator
 
-If you skip `npm run setup`, the misspelled root sample file `.env.exemple` is
-the reference template for manual environment setup.
+A fresh instance redirects every route to `/setup` until an admin exists, so you
+cannot miss it.
+
+> **Self-hosted Docker is the exception** — `npm run docker:setup` is a real,
+> one-command, non-interactive bootstrap that brings up the whole stack and
+> applies migrations. See [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md).
+
+If you would rather configure by hand, the root sample file `.env.example` is the
+reference template for a manual `.env.local`.
 
 ### First login
 
@@ -105,9 +111,9 @@ repo expects at least:
 - `SUPABASE_PROJECT_ID` for Supabase CLI migration tooling
 - `SUPABASE_ACCESS_TOKEN` for Supabase CLI linking
 - `POSTGRES_URL` or `DATABASE_URL` for SQL fallback paths and db tooling
-- `NEXT_PUBLIC_URL` — written by `npm run setup`
+- `NEXT_PUBLIC_URL` — set by the `/setup` wizard
 - `CRON_SECRET`, `DRAFT_MODE_SECRET`, `REVALIDATE_SECRET_TOKEN` — auto-generated
-  by `npm run setup`
+  by the `/setup` wizard
 
 > **Supabase key aliases.** The names above are the local-dev canon, but the app also
 > accepts the *new-style* names the hosted/Vercel Supabase Marketplace integration
@@ -120,7 +126,7 @@ repo expects at least:
 > production — when unset they are derived from the service-role key (see
 > `apps/nextblock/lib/app-secrets.ts`). See [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md).
 
-Captured by `npm run setup` and needed for a complete CMS:
+Captured by the `/setup` wizard and needed for a complete CMS:
 
 - R2 credentials for media storage. The app builds and serves without them, but
   uploads, image processing, and full-site backups return 500 until R2 is set.

package/templates/nextblock-template/docs/06-CLI-AND-SCAFFOLDING.md

@@ -87,7 +87,7 @@ It currently:
 - copies `apps/nextblock` into `templates/nextblock-template`
 - skips `node_modules`, `.next`, backups, and other generated folders
 - copies the root `docs/` folder into the template docs directory
-- copies `.env.example` or `.env.exemple`
+- copies `.env.example` (the legacy `.env.exemple` spelling is still accepted as a fallback)
 - rewrites imports for packaged library consumption
 - removes the copied `project.json`
 - syncs package versions

package/templates/nextblock-template/docs/08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md

@@ -75,7 +75,7 @@ Known incomplete or future work:
 | `libs/utils/src/lib/nextblock-packages.ts` | Package registry. Contains `cortex-ai` metadata and Freemius product/plan ids. |
 | `libs/cortex/src/lib/ai-config.ts` | Server-only Cortex AI constants and environment accessors. |
 | `libs/cortex/src/lib/ai-key-crypto.ts` | AES-256-GCM encryption/decryption helpers for stored OpenRouter BYOK keys. |
-| `.env.exemple` | Documents `FREEMIUS_AI_SANDBOX_KEY`, `OPENROUTER_API_KEY`, and `CORTEX_AI_ENCRYPTION_KEY`. |
+| `.env.example` | Documents `FREEMIUS_AI_SANDBOX_KEY`, `OPENROUTER_API_KEY`, and `CORTEX_AI_ENCRYPTION_KEY`. |
 | `libs/environment.d.ts` | Type declarations for Cortex AI environment variables. |
 
 ### Database and Sandbox
@@ -189,7 +189,7 @@ Current usage:
 
 ## Environment Variables
 
-Environment variables are documented in `.env.exemple` and typed in `libs/environment.d.ts`.
+Environment variables are documented in `.env.example` and typed in `libs/environment.d.ts`.
 
 ```txt
 FREEMIUS_AI_SANDBOX_KEY=

package/templates/nextblock-template/docs/12-VERCEL-DEPLOYMENT.md

@@ -20,12 +20,33 @@ have to type (see "No environment variables required" below). The only interacti
 Supabase integration's "create database" step, which can't be skipped because provisioning
 a Postgres DB requires choosing a region/plan.
 
-> **Why `stores`, not `integration-ids`?** The legacy `integration-ids=oac_…` parameter
-> triggers an OAuth integration that *creates* a Supabase project but leaves it
-> **disconnected** — it injects **no** environment variables into the Vercel project, so
-> the app boots unconfigured and you have to wire the keys up by hand. The modern `stores`
-> parameter is the native Marketplace path that actually **connects the store and injects
-> credentials before the build**. ([Vercel Deploy Button docs](https://vercel.com/docs/deploy-button/source))
+> **Why `stores`, not `integration-ids`?** Both parameters are current — neither is
+> deprecated — but they do different jobs, and only one of them provisions a database.
+>
+> **`integration-ids=oac_…`** ([docs](https://vercel.com/docs/deploy-button/integrations))
+> only forces an integration to be **installed and authorized before the project can be
+> imported** (up to three per project). Vercel's documentation makes no promise about
+> environment variables either way: whether credentials land in the project is a property
+> of that integration's own OAuth flow, not of the parameter. Supabase's flow does set
+> them — the `vercel/next.js` `with-supabase` example states that "all relevant environment
+> variables will be assigned to the project" after installation — so this route can work.
+> It just isn't Vercel guaranteeing it, and it says nothing about *when* they land.
+>
+> **`stores`** ([docs](https://vercel.com/docs/deploy-button/source)) is the native
+> Marketplace path: it creates the store **as part of the deployment** and creates the
+> environment variables for it. That timing is what NextBlock actually depends on — the
+> build-time migration hook needs `POSTGRES_URL` to exist *during* the first build, not
+> after it. See "Build configuration" below.
+>
+> The deciding evidence is Vercel's own Template Gallery entry for the Supabase Starter,
+> which ships the **exact `stores` payload** used above.
+>
+> **If you ever add an `integration-ids` fallback, the only correct Supabase value is
+> `oac_VqOgBHqhEoFTPzGkPd7L0iH6`** — confirmed in `supabase/supabase`'s own example READMEs
+> and in the Vercel record behind `vercel.com/templates/next.js/supabase`. A plausible
+> lookalike, `oac_VqOgBHqhvvqGe2YujqqiW0wo`, circulates in AI-generated snippets and is
+> **not a real integration id**; it shares only the first twelve characters. An unknown id
+> makes Vercel refuse the import outright, which breaks the deploy completely.
 
 ## Connect the database (Supabase integration)
 
@@ -88,9 +109,11 @@ imports the workspace libraries one level up, which a custom Root Directory woul
 
 ## No environment variables required
 
-A Deploy-Button URL can only carry variable **names**, never values — so secrets can
-never be pre-filled through it. Rather than make you paste random strings, NextBlock
-resolves everything in-app, and the button prompts for nothing:
+A Deploy-Button URL can carry environment variable **names** (`env`), and non-sensitive
+**default values** (`envDefaults`) — but never secrets: Vercel's own docs warn that the URL
+"is saved in the browser history, making it insecure" and to "never use default values for
+sensitive data like passwords, API keys, tokens, database credentials." NextBlock sidesteps
+the question entirely by resolving everything in-app, so the button prompts for nothing:
 
 - **`NEXT_PUBLIC_URL`** — optional. When unset the app falls back to Vercel's
   production URL (`VERCEL_PROJECT_PRODUCTION_URL` server-side /

package/templates/nextblock-template/docs/14-MESSAGES-INBOX.md

@@ -0,0 +1,309 @@
+# 14 · Messages — the unified inbox
+
+Everything a visitor sends the site arrives in one place: **CMS → Messages**
+(`/cms/messages`). Four sources feed it, and the admin can reply to all of them from
+there.
+
+The inbox is one *view* over **two storage models**, because the sources are genuinely
+different and flattening them would break something real.
+
+| Source | Table | Visibility | What a reply is |
+|---|---|---|---|
+| Product enquiry | `message_threads` + `thread_messages` | private | a private message, delivered via a tokenised link |
+| Contact form | `message_threads` + `thread_messages` | private | same |
+| Product review | `cms_interactions` | already public | a **public** reply under the review |
+| Post comment | `cms_interactions` | already public | a **public** reply under the comment |
+
+`app/cms/messages/loadInbox.ts` performs the merge in the read path and normalises both
+into an `InboxItem`. The detail pane branches on `item.kind`.
+
+## Why not one table
+
+`cms_interactions` cannot hold an enquiry, and the reasons are all enforced by the
+schema rather than by convention:
+
+- `user_id` is `NOT NULL` with a foreign key to `profiles` — every review and comment
+  belongs to a registered account. Enquiry senders are anonymous.
+- `check_product_or_post` requires *exactly one* of `product_id` / `post_id`. A contact
+  form targets neither.
+- Reviews and comments are readable by `anon` through an open `SELECT` policy once
+  approved. Enquiries carry visitor PII and have **no anon grant or policy at all**.
+- `update_product_ratings()` fires on every `cms_interactions` write.
+
+That last point is the sharp edge. The trigger aggregates
+`WHERE product_id = ? AND type='review' AND status='approved'`, so anything stored as an
+approved review moves the product's star average. **A staff reply is therefore stored as
+`type='comment'` with a NULL rating**, carrying the parent's target. That is not a
+workaround for convenience — `check_rating_only_for_review` is an exhaustive `OR` over
+`('review','comment')`, so a `review` row with a NULL rating is rejected outright, and
+adding a third enum value would violate the same constraint *and* hit PostgreSQL's rule
+that an enum value cannot be used in the transaction that added it (i.e. in one
+migration file). `cms_interactions_reply_check` pins the invariant in the schema.
+
+## The private lane
+
+`message_threads` is the spine; `thread_messages` holds the turns. Message *content* is
+append-only, enforced by a trigger that binds the service role too — only the delivery
+flags may change after insert. A consequence worth knowing: because the foreign key
+cascades and the trigger blocks `DELETE`, **a thread cannot be deleted**. "Delete" in
+the CMS means `status='closed'` plus a revoked token.
+
+### The visitor's token
+
+The only opaque credential this codebase issues to an anonymous person.
+
+- 32 bytes of `crypto.randomBytes`, prefixed `nbt_`. Guessing is infeasible by
+  keyspace, which matters because the GET has no rate limit.
+- Only `sha256` is stored, in `message_threads.token_hash` under a unique index. The
+  plaintext exists long enough to go into one email and is never written down.
+- **Minted on the first admin reply, never at submission.** A store with a hundred
+  unanswered enquiries has zero live credentials.
+- Rolling 90-day expiry, extended by each reply; revocable from the CMS.
+
+`/thread/[token]` exchanges the token for an **HttpOnly cookie** and redirects to a
+token-less `/thread`. This is the most important control in the feature: the app sends
+`Referrer-Policy: strict-origin-when-cross-origin`, so a token left in the address bar
+would travel in the `Referer` header of every same-origin navigation, and into history,
+screenshots and proxy logs.
+
+Every failure — expired, revoked, never existed — renders the *same* page. Distinguishing
+them would make the route an oracle.
+
+Reading the thread uses the service role **after** verifying the token in application
+code. No RLS policy here authenticates an anonymous caller by token, and none was
+invented; this matches how `/api/mcp` treats `mcp_access_tokens`.
+
+## Contact forms and `form_key`
+
+A form block used to store its destination in its own `content`. `FormBlockRenderer` is
+a `"use client"` component that receives that content wholesale, so **the address was
+serialized into the RSC payload of every page carrying a form** — published in the
+markup.
+
+Migration `00000000000027` moved every stored address into `form_endpoints` and left a
+`form_key` behind: an opaque handle that grants nothing and is safe to serialize. The
+migration walks three shapes, because a form nested in a section has no `blocks` row of
+its own:
+
+1. `blocks.content` where `block_type='form'`
+2. `blocks.content` where `block_type='section'` (`column_blocks`, `slides`)
+3. `content_drafts.blocks` / `product_drafts.blocks`
+
+`form_endpoints.fields` is a **server-side snapshot** of the field manifest, so
+notification emails and the inbox render labels the browser did not supply.
+
+`BlockRenderer` and `SectionBlockRenderer` also strip `recipient_email` defensively
+before handing content to the client — an import, a restored revision, or a fork that
+has not migrated can still produce one.
+
+## Delivery is best-effort; the row is the record
+
+`sendEmail` **throws** when SMTP is unconfigured, and a store that has not finished one
+piece of setup often has not finished the other. So every path writes first and notifies
+afterwards, inside `after()`. A failed send sets `email_delivered = false` and records
+`email_error`; the CMS shows "Not emailed" rather than pretending the owner was told.
+
+The visitor is still shown success, because from their side it *was* one.
+
+## Recipient resolution
+
+Contact forms: per-form `form_endpoints.recipient_email` → `site_settings.forms_contact`
+→ the seller-contact ladder (`lib/commerce/seller-contact.ts`: explicit store contact →
+invoice email → privacy support email → oldest ADMIN's auth email). The sandbox
+overrides everything.
+
+**The address is never sent to the browser.** The form posts a `form_key`; the server
+resolves the destination.
+
+## The reply link and `NEXT_PUBLIC_URL`
+
+`sendThreadNotice` refuses to send when the site URL was never configured, but happily
+sends a local URL you chose deliberately.
+
+`resolveSiteUrl()` falls back to `http://localhost:3000` when nothing is set, and a link
+to that is dead for anyone not sitting at the machine. What must never happen is the code
+*inventing* a localhost link because nothing was configured and mailing it to a customer.
+A deliberate local URL is different: that is how you test the round trip, and it works.
+
+So: honour an explicit choice, refuse an accidental default.
+
+- Testing locally: set `NEXT_PUBLIC_URL=http://localhost:3000` (or your dev port). The
+  link is sent and works on that machine; a warning is logged saying who can open it.
+- Production: set it to the public site URL. Vercel's project URL is picked up
+  automatically.
+- Unset: the notice is refused and the reason is recorded on the message.
+
+> An earlier version of this document blamed a `localhost` link for a quarantined
+> message. That was wrong — a probe carrying exactly such a link was delivered normally.
+> The real cause is below.
+
+## Mail threading: two conversations, two roots
+
+Outbound mail carries `In-Reply-To` and `References` pointing at a stable synthetic root,
+because a `Re:` subject with no threading headers is itself a forged-reply heuristic, and
+one consistent id per conversation groups the exchange in the recipient's client.
+
+**The owner's notifications and the visitor's notices use DIFFERENT roots**, and that
+separation is load-bearing:
+
+- owner: `<nb-thread-{id}-admin@{from-domain}>`
+- visitor: `<nb-thread-{id}-visitor@{from-domain}>`
+
+They are two different exchanges with two different people. Sharing one root makes a mail
+client fold them into a single conversation — and when an operator tests with their own
+address as both the admin *and* the enquiring visitor (the obvious way to try the
+feature), the reply is delivered, accepted, and then collapsed under the notification
+they already read. It looks precisely like the email never arrived.
+
+That symptom is a same-mailbox testing artifact, not a production fault: in real use the
+customer and the shop owner are different mailboxes. But the shared root was a genuine
+modelling error, and it is fixed.
+
+## Where a form's mail goes
+
+One rule, three rungs:
+
+1. The form's own `form_endpoints.recipient_email`, if someone set one.
+2. The site contact address from **CMS → Messages** (`site_settings.store_contact`).
+3. The **first admin account's** own login address.
+
+**A form has no address of its own by default**, and that is the intended state — since
+the messaging system arrived, an operator does not need to think about per-form routing
+at all. Submissions are stored as threads and answered in the CMS; the notification
+address is one site-wide setting. A per-form address exists only to route one particular
+form elsewhere — a careers form to HR, say.
+
+Because rung 3 always resolves on a provisioned install, a fresh site reaches a real
+human without configuring anything.
+
+The sandbox overrides all of it: `resolveFormRecipient` returns `SANDBOX_CONTACT_EMAIL`
+when `NEXT_PUBLIC_IS_SANDBOX` is set, so the hosted demo routes to the operator's inbox
+without storing an address anywhere.
+
+### Placeholder addresses count as unset
+
+The starter content used to ship a contact form addressed to `contact@example.com`, and
+migration 27 faithfully carried that into `form_endpoints`. Faithful was wrong:
+`example.com` is reserved by RFC 2606 so it can never be registered, which makes the
+address *guaranteed* undeliverable while looking like a real setting to every layer
+downstream. The visitor is thanked, the relay accepts, nobody is notified, nothing errors.
+An install ran that way without knowing.
+
+Migration 29 clears those to NULL, so they fall through to the ladder above.
+`lib/email/placeholder-address.ts` also treats the reserved domains (`example.com/.org/
+.net/.edu` and the `.example`, `.invalid`, `.test`, `.localhost`, `.local` suffixes) as
+unset at runtime, and `lib/cms/contact-reminder.ts` raises an ADMIN banner if one
+reappears — via an import, a restored revision, or someone typing it.
+
+The banner stays quiet when a form simply has no address, because that is now the correct
+configuration rather than an omission.
+
+## Subjects are per-conversation, and why that matters
+
+|  | contact form | product enquiry |
+|---|---|---|
+| **owner** | `Nicolas sent you a message [NRH-VWQOLB]` | `Nicolas asked about Brass Kettle [NRH-EMISCX]` |
+| **visitor** | `New Roots Herbal replied to your message [NRH-VWQOLB]` | `New Roots Herbal replied about Brass Kettle [NRH-EMISCX]` |
+
+`threadReference(threadId, siteName)` folds the first 32 bits of the thread id into six
+base36 characters and prefixes the site's initials — about 2.2 billion references, read as
+a ticket number rather than a hex dump.
+
+**There is no `Re:` anywhere.** The visitor's message was never an email, so a reply
+prefix is both a spam heuristic and a small lie; naming the site is what actually tells
+them who is writing. The `In-Reply-To` / `References` headers still group each
+conversation properly.
+
+The reference is not decoration. **Exchange derives its ConversationTopic from the
+subject, not from References**, so separating the References headers — necessary, and
+done — was not sufficient. With a constant subject, every enquiry a site ever receives
+collapses into one Outlook conversation, and anything applied to that conversation applies
+to all of them: a rule, a filter, or Ignore Conversation.
+
+A real install hit exactly this. Replies were accepted by the relay, accepted by Microsoft
+with `250 Queued mail for delivery`, and routed straight to Deleted Items, because a
+"Contact form" conversation had been ignored at some point. Nothing anywhere reported a
+fault. It was isolated by sending two messages with byte-identical bodies and different
+subjects: the unique subject arrived, `Re: Contact form` did not. When mail "doesn't
+arrive", that A/B is the first thing to run — not a theory.
+
+## Deliverability: accepted is not delivered
+
+A reply can be accepted by the relay, accepted by the recipient's server with
+`250 Queued mail for delivery`, appear in the inbox — and then be **removed from the
+mailbox minutes later**. Microsoft calls this ZAP (Zero-hour Auto Purge): threat intel
+updates after delivery and the message is retracted. There is no bounce and no SMTP
+error, so `email_delivered = true` is accurate and every log upstream reports success.
+
+**This is largely outside the application's control.** A strict corporate tenant can
+purge a transactional message on its overall shape — a reply-styled body carrying a
+quoted excerpt and a link to an opaque tokenised URL — and no rendering tested reliably
+survived one such tenant. An intermediate result suggesting that showing the destination
+URL was the deciding factor did not hold up against the real notice.
+
+What the application does do:
+
+**1. No secrecy language.** The message used to end "This link is personal to you —
+please don't forward it." A secret one-off link, a prominent button, and an instruction
+not to share it is a near-literal phishing template. The link's security comes from the
+token rotating on every reply, not from asking the recipient to keep a secret.
+
+**2. The destination is visible.** The call-to-action is a button, with the URL also
+printed as plain text beneath it. Good practice regardless, and it survives clients that
+strip styling.
+
+**3. There is a manual channel.** `createVisitorLink` mints a link and hands it to the
+admin without sending anything ("Copy visitor link" in the thread pane). When a
+recipient's filtering removes the mail, the conversation is still intact and the link is
+still obtainable — send it by whatever works.
+
+### Diagnosing it
+
+Send messages with **byte-identical bodies** differing in exactly one variable, and check
+the recipient's Deleted Items as well as the inbox. Reasoning from correlation produced
+five wrong answers here — a `localhost` link, spam filtering in general, a shared thread
+root, the subject line, and the secrecy phrase — each of which fitted the evidence and
+was killed by the next test.
+
+The send path logs what actually went out:
+
+```
+[messages] Reply on thread <id> handed to SMTP — to="…" replyTo="…" subject="…" link=tokenised
+```
+
+Start there. **Accepted by SMTP is not arrived, and arrived is not still there.** When a
+tenant is purging on shape, testing against a different provider (a personal Gmail, say)
+separates "the app is broken" from "this mailbox rejects this class of mail".
+
+## Rate limiting
+
+There is no shared rate limiter in this repo. Both public write paths throttle by
+counting recent rows for a masked IP, and both **fail closed**: an absent or unparseable
+`X-Forwarded-For` buckets under the literal `'unknown'` rather than skipping the check.
+Trusted platform headers (`x-vercel-forwarded-for`, `x-real-ip`) are preferred over
+`x-forwarded-for`, whose leftmost entry the client can write.
+
+## Files
+
+- `libs/db/src/supabase/migrations/00000000000027_message_threads.sql` — private lane, `form_endpoints`, the form-block data migration
+- `libs/db/src/supabase/migrations/00000000000028_interaction_replies.sql` — `parent_id`, the reply CHECK, and the indexes `cms_interactions` never had
+- `apps/nextblock/lib/messages/thread-token.ts` (+ `.test.ts`) — mint, parse, verify
+- `apps/nextblock/lib/messages/threads.ts` — thread creation, recipient resolution, both notification emails
+- `apps/nextblock/app/thread/**` — the visitor's page and the token-exchange route
+- `apps/nextblock/app/actions/threadActions.ts` — visitor replies
+- `apps/nextblock/app/cms/messages/**` — the inbox, its loader and its admin actions
+- `apps/nextblock/app/actions/interactions.ts` — `replyToInteraction`, the public lane
+- `apps/nextblock/components/StaffReplies.tsx` — nested public replies on the storefront
+
+`/cms/inquiries` and `/cms/interactions` are now redirects into the inbox; both were
+linked from notification emails and bookmarks, so neither was deleted.
+
+## Known gaps
+
+- Interactions have **no per-user read marker** anywhere in the schema, so the nav badge
+  counts "pending moderation". Two admins working the queue see the same number.
+- Public replies do not email the review/comment author. They have a reachable address,
+  but that would be the first time the platform emails a registered user about content
+  activity, with no preference to opt out of.
+- Visitors get no acknowledgement email at submission time — that would require minting
+  a token immediately, which is exactly the live-credential surface this design avoids.

package/templates/nextblock-template/docs/README.md

@@ -1,41 +1,42 @@
-# NextBlock CMS Documentation
-
-This folder is the source-of-truth reference set for the NextBlock monorepo.
-The numbered files are written from live code, routes, migrations, and shipped
-library surfaces rather than historical planning notes.
-
-## Start Here
-
-- Product and architecture overview: [01-PROJECT-OVERVIEW.md](./01-PROJECT-OVERVIEW.md)
-- Commerce capabilities: [02-ECOMMERCE-CAPABILITIES.md](./02-ECOMMERCE-CAPABILITIES.md)
-- CMS editor and block system: [03-CMS-AND-EDITOR.md](./03-CMS-AND-EDITOR.md)
-- Database, auth, and migrations: [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md)
-- Contributor workflow and local operations: [05-DEVELOPER-GUIDE.md](./05-DEVELOPER-GUIDE.md)
-- CLI and scaffolded project flow: [06-CLI-AND-SCAFFOLDING.md](./06-CLI-AND-SCAFFOLDING.md)
-- Block SDK and extensibility surface: [07-BLOCK-SDK-AND-EXTENSIBILITY.md](./07-BLOCK-SDK-AND-EXTENSIBILITY.md)
-- Cortex AI architecture: [08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md](./08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md)
-- Live draft (visual editing) mode: [09-LIVE-DRAFT-MODE.md](./09-LIVE-DRAFT-MODE.md)
-- Custom blocks (data-driven CRUD): [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)
-- Self-hosted local Docker stack: [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md)
-- One-click cloud deploy (Deploy to Vercel): [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md)
-- Updating an install (`npm run update`, upstream sync): [13-STAYING-UP-TO-DATE.md](./13-STAYING-UP-TO-DATE.md)
-
-## Audience Guide
-
-- New contributors: read `01`, then `04`, then `05`.
-- Commerce work: read `02`, then `04`.
-- Editor or page-builder work: read `03`, then `07`.
-- Custom block work: read `03`, then `10`.
-- AI / Cortex work: read `08`.
-- CLI or template work: read `06`.
-- Publishing the libraries / scaffold CLI: read `06`.
-- Running everything locally without cloud accounts: read `11`.
-- One-click cloud deploy and the browser setup wizard: read `12`.
-- Updating an existing install, whichever way it was created: read `13`.
-- AI agents: start with this index, then move directly to the subsystem file that
-  matches the task. Treat `apps/nextblock`, `libs/*`, and
-  `libs/db/src/supabase/migrations` as the final authority if a doc and code ever
-  disagree.
-- AI agents touching migrations must also read the root `AGENTS.md` note:
-  production/shared database changes are append-only and non-destructive by
-  default.
+# NextBlock CMS Documentation
+
+This folder is the source-of-truth reference set for the NextBlock monorepo.
+The numbered files are written from live code, routes, migrations, and shipped
+library surfaces rather than historical planning notes.
+
+## Start Here
+
+- Product and architecture overview: [01-PROJECT-OVERVIEW.md](./01-PROJECT-OVERVIEW.md)
+- Commerce capabilities: [02-ECOMMERCE-CAPABILITIES.md](./02-ECOMMERCE-CAPABILITIES.md)
+- CMS editor and block system: [03-CMS-AND-EDITOR.md](./03-CMS-AND-EDITOR.md)
+- Database, auth, and migrations: [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md)
+- Contributor workflow and local operations: [05-DEVELOPER-GUIDE.md](./05-DEVELOPER-GUIDE.md)
+- CLI and scaffolded project flow: [06-CLI-AND-SCAFFOLDING.md](./06-CLI-AND-SCAFFOLDING.md)
+- Block SDK and extensibility surface: [07-BLOCK-SDK-AND-EXTENSIBILITY.md](./07-BLOCK-SDK-AND-EXTENSIBILITY.md)
+- Cortex AI architecture: [08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md](./08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md)
+- Live draft (visual editing) mode: [09-LIVE-DRAFT-MODE.md](./09-LIVE-DRAFT-MODE.md)
+- Custom blocks (data-driven CRUD): [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)
+- Self-hosted local Docker stack: [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md)
+- One-click cloud deploy (Deploy to Vercel): [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md)
+- Updating an install (`npm run update`, upstream sync): [13-STAYING-UP-TO-DATE.md](./13-STAYING-UP-TO-DATE.md)
+- Messages inbox (enquiries, contact forms, reviews, comments): [14-MESSAGES-INBOX.md](./14-MESSAGES-INBOX.md)
+
+## Audience Guide
+
+- New contributors: read `01`, then `04`, then `05`.
+- Commerce work: read `02`, then `04`.
+- Editor or page-builder work: read `03`, then `07`.
+- Custom block work: read `03`, then `10`.
+- AI / Cortex work: read `08`.
+- CLI or template work: read `06`.
+- Publishing the libraries / scaffold CLI: read `06`.
+- Running everything locally without cloud accounts: read `11`.
+- One-click cloud deploy and the browser setup wizard: read `12`.
+- Updating an existing install, whichever way it was created: read `13`.
+- AI agents: start with this index, then move directly to the subsystem file that
+  matches the task. Treat `apps/nextblock`, `libs/*`, and
+  `libs/db/src/supabase/migrations` as the final authority if a doc and code ever
+  disagree.
+- AI agents touching migrations must also read the root `AGENTS.md` note:
+  production/shared database changes are append-only and non-destructive by
+  default.