create-nextblock 0.10.2 → 0.10.4

package/templates/nextblock-template/app/setup/SetupWizard.tsx

@@ -35,14 +35,6 @@ export interface StoragePrefill {
   secretAccessKey: string;
 }
 
-interface SmtpPrefill {
-  host: string;
-  port: string;
-  user: string;
-  fromEmail: string;
-  fromName: string;
-}
-
 export interface SupabaseEnvDetected {
   NEXT_PUBLIC_SUPABASE_URL: boolean;
   SUPABASE_URL: boolean;
@@ -58,20 +50,19 @@ interface Props {
   writable: boolean;
   siteUrl: string;
   storagePrefill: StoragePrefill;
-  smtpPrefill: SmtpPrefill;
-  turnstilePrefill: { siteKey: string };
   /** Which Supabase env vars the running deployment can actually see (read-only channels). */
   supabaseEnvDetected: SupabaseEnvDetected;
 }
 
-type StepId = 'connection' | 'storage' | 'email' | 'bot' | 'signups' | 'admin';
+// Email (SMTP), bot protection, and sign-up policy are no longer collected here — they
+// moved to the CMS (Settings → Configuration) and are nudged from the dashboard onboarding
+// checklist. A fresh install only needs the database connection, media storage, and the
+// first administrator account.
+type StepId = 'connection' | 'storage' | 'admin';
 
 const STEP_TITLES: Record<StepId, string> = {
   connection: 'Database connection',
   storage: 'Media storage',
-  email: 'Email (SMTP)',
-  bot: 'Bot protection',
-  signups: 'Sign-ups',
   admin: 'Administrator account',
 };
 
@@ -89,8 +80,6 @@ export default function SetupWizard({
   writable,
   siteUrl,
   storagePrefill,
-  smtpPrefill,
-  turnstilePrefill,
   supabaseEnvDetected,
 }: Props) {
   const [isPending, startTransition] = useTransition();
@@ -110,15 +99,8 @@ export default function SetupWizard({
   // "Start from a clean database" — only offered/honored on a local fresh install.
   const [resetFirst, setResetFirst] = useState(true);
 
-  // Storage / SMTP / bot / signups / admin.
+  // Storage / admin.
   const [storage, setStorage] = useState(storagePrefill);
-  const [smtp, setSmtp] = useState({ ...smtpPrefill, pass: '' });
-  const [turnstileEnabled, setTurnstileEnabled] = useState(false);
-  const [turnstile, setTurnstile] = useState({
-    siteKey: turnstilePrefill.siteKey,
-    secretKey: '',
-  });
-  const [autoAccept, setAutoAccept] = useState(false); // off by default (defense-in-depth)
   const [admin, setAdmin] = useState({ email: '', password: '', fullName: '' });
 
   const steps = useMemo<StepId[]>(() => {
@@ -131,7 +113,7 @@ export default function SetupWizard({
     if (channel !== 'vercel') {
       list.push('storage');
     }
-    list.push('email', 'bot', 'signups', 'admin');
+    list.push('admin');
     return list;
   }, [configured, channel]);
 
@@ -205,12 +187,6 @@ export default function SetupWizard({
       // (baseUrl only differs if a channel prefilled a separate custom domain).
       put('NEXT_PUBLIC_R2_PUBLIC_URL', storage.publicUrl);
       put('NEXT_PUBLIC_R2_BASE_URL', storage.baseUrl || storage.publicUrl);
-      put('SMTP_HOST', smtp.host);
-      put('SMTP_PORT', smtp.port);
-      put('SMTP_USER', smtp.user);
-      put('SMTP_PASS', smtp.pass);
-      put('SMTP_FROM_EMAIL', smtp.fromEmail);
-      put('SMTP_FROM_NAME', smtp.fromName);
     }
 
     setMessage(null);
@@ -218,12 +194,8 @@ export default function SetupWizard({
     startTransition(async () => {
       const result = await completeSetup({
         admin,
-        autoAcceptSignups: autoAccept,
         envValues,
         resetFirst: resetFirst && writable,
-        turnstile: turnstileEnabled
-          ? { provider: 'turnstile', siteKey: turnstile.siteKey, secretKey: turnstile.secretKey }
-          : { provider: 'none', siteKey: '', secretKey: '' },
       });
 
       if (!result.ok) {
@@ -400,122 +372,6 @@ export default function SetupWizard({
             <StorageStep storage={storage} setStorage={setStorage} channel={channel} />
           )}
 
-          {current === 'email' && (
-            <div className="space-y-4">
-              {channel === 'docker' && (
-                <p className="text-xs text-muted-foreground">
-                  Docker auto-confirms sign-ups when SMTP is not configured, so this is optional.
-                </p>
-              )}
-              <div className="grid gap-4 sm:grid-cols-2">
-                <Field label="SMTP host" htmlFor="smtpHost">
-                  <Input
-                    id="smtpHost"
-                    value={smtp.host}
-                    onChange={(e) => setSmtp({ ...smtp, host: e.target.value })}
-                  />
-                </Field>
-                <Field label="Port" htmlFor="smtpPort">
-                  <Input
-                    id="smtpPort"
-                    value={smtp.port}
-                    onChange={(e) => setSmtp({ ...smtp, port: e.target.value })}
-                  />
-                </Field>
-                <Field label="Username" htmlFor="smtpUser">
-                  <Input
-                    id="smtpUser"
-                    value={smtp.user}
-                    onChange={(e) => setSmtp({ ...smtp, user: e.target.value })}
-                  />
-                </Field>
-                <Field label="Password" htmlFor="smtpPass">
-                  <Input
-                    id="smtpPass"
-                    type="password"
-                    value={smtp.pass}
-                    onChange={(e) => setSmtp({ ...smtp, pass: e.target.value })}
-                  />
-                </Field>
-                <Field label="From email" htmlFor="smtpFromEmail">
-                  <Input
-                    id="smtpFromEmail"
-                    value={smtp.fromEmail}
-                    onChange={(e) => setSmtp({ ...smtp, fromEmail: e.target.value })}
-                  />
-                </Field>
-                <Field label="From name" htmlFor="smtpFromName">
-                  <Input
-                    id="smtpFromName"
-                    value={smtp.fromName}
-                    onChange={(e) => setSmtp({ ...smtp, fromName: e.target.value })}
-                  />
-                </Field>
-              </div>
-              {!writable && channel !== 'docker' && (
-                <p className="text-xs text-muted-foreground">
-                  On this platform, set SMTP_* as environment variables in your hosting dashboard.
-                </p>
-              )}
-            </div>
-          )}
-
-          {current === 'bot' && (
-            <div className="space-y-4">
-              <label className="flex items-start gap-3">
-                <Checkbox
-                  checked={turnstileEnabled}
-                  onCheckedChange={(c) => setTurnstileEnabled(c === true)}
-                  className="mt-1"
-                />
-                <span className="text-sm">
-                  <span className="font-medium">Enable Cloudflare Turnstile</span>
-                  <span className="block text-xs text-muted-foreground">
-                    Protects sign-up / sign-in forms. Stored securely in the database.
-                  </span>
-                </span>
-              </label>
-              {turnstileEnabled && (
-                <div className="grid gap-4 sm:grid-cols-2">
-                  <Field label="Site key" htmlFor="tsSite">
-                    <Input
-                      id="tsSite"
-                      value={turnstile.siteKey}
-                      onChange={(e) => setTurnstile({ ...turnstile, siteKey: e.target.value })}
-                    />
-                  </Field>
-                  <Field label="Secret key" htmlFor="tsSecret">
-                    <Input
-                      id="tsSecret"
-                      type="password"
-                      value={turnstile.secretKey}
-                      onChange={(e) => setTurnstile({ ...turnstile, secretKey: e.target.value })}
-                    />
-                  </Field>
-                </div>
-              )}
-            </div>
-          )}
-
-          {current === 'signups' && (
-            <label className="flex items-start gap-3">
-              <Checkbox
-                checked={autoAccept}
-                onCheckedChange={(c) => setAutoAccept(c === true)}
-                className="mt-1"
-              />
-              <span className="text-sm">
-                <span className="font-medium">
-                  Auto-approve local registrations (skip outbound email verification)
-                </span>
-                <span className="block text-xs text-muted-foreground">
-                  New sign-ups become active immediately, even without SMTP configured. Convenient
-                  for local / self-hosted use; leave off for public production sites.
-                </span>
-              </span>
-            </label>
-          )}
-
           {current === 'admin' && (
             <div className="space-y-4">
               <Field label="Full name" htmlFor="adminName">
@@ -546,6 +402,13 @@ export default function SetupWizard({
                 verification email needed). Finishing also applies the database schema and saved
                 settings, so it can take up to a minute.
               </p>
+              <Alert className="py-2 px-4">
+                <AlertDescription className="text-xs">
+                  Next, your dashboard will guide you through finishing setup — branding, copyright,
+                  email (SMTP), payment providers, and bot protection are all configured there, no
+                  environment variables required.
+                </AlertDescription>
+              </Alert>
 
               {writable && (
                 <label className="flex items-start gap-3 rounded-lg border p-3">
@@ -606,14 +469,8 @@ function stepDescription(step: StepId, channel: DeployChannel): string {
         : channel === 'vercel'
           ? 'Using Supabase Storage (S3-compatible) for media.'
           : 'Bring your own Cloudflare R2 bucket for media storage.';
-    case 'email':
-      return 'Optional. Used for verification emails, password resets, and 2FA codes.';
-    case 'bot':
-      return 'Optional. Add Cloudflare Turnstile to your auth forms.';
-    case 'signups':
-      return 'Choose how new public registrations are handled.';
     case 'admin':
-      return 'Create the first administrator account.';
+      return 'Create the first administrator account — the last step. Email, payments, branding, and the rest are configured from your dashboard.';
     default:
       return '';
   }

package/templates/nextblock-template/app/setup/page.tsx

@@ -91,14 +91,6 @@ export default async function SetupPage() {
       writable={isLocalWritableEnv()}
       siteUrl={process.env.NEXT_PUBLIC_URL ?? ''}
       storagePrefill={buildStoragePrefill(channel, supabaseUrl)}
-      smtpPrefill={{
-        host: process.env.SMTP_HOST ?? '',
-        port: process.env.SMTP_PORT ?? '465',
-        user: process.env.SMTP_USER ?? '',
-        fromEmail: process.env.SMTP_FROM_EMAIL ?? '',
-        fromName: process.env.SMTP_FROM_NAME ?? '',
-      }}
-      turnstilePrefill={{ siteKey: process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY ?? '' }}
       supabaseEnvDetected={{
         NEXT_PUBLIC_SUPABASE_URL: Boolean(process.env.NEXT_PUBLIC_SUPABASE_URL),
         SUPABASE_URL: Boolean(process.env.SUPABASE_URL),

package/templates/nextblock-template/components/AppShell.tsx

@@ -3,7 +3,6 @@
 import type { Database } from '@nextblock-cms/db';
 import { cn } from '@nextblock-cms/utils';
 import { usePathname } from 'next/navigation';
-import Link from 'next/link';
 import { createContext, useContext, useMemo, type ReactNode } from 'react';
 import Header from './Header';
 import FooterNavigation from './FooterNavigation';
@@ -148,12 +147,6 @@ export function AppShell({
                   )}
                 <div className="flex flex-row items-center gap-4">
                   <p className="text-muted-foreground">{copyrightText}</p>
-                  <Link href="/privacy-policy" className="hover:underline">
-                    Privacy Policy
-                  </Link>
-                  <Link href="/terms-of-service" className="hover:underline">
-                    Terms of Service
-                  </Link>
                   <ThemeSwitcher />
                 </div>
               </div>

package/templates/nextblock-template/components/BlockRenderer.tsx

@@ -17,6 +17,7 @@ import ClientTextBlockRenderer from "./blocks/renderers/ClientTextBlockRenderer"
 import { getCachedCustomBlockDefinitionBySlug } from "../lib/custom-block-definitions";
 import { CachedDynamicLayoutEngine } from "./renderers/CachedDynamicLayoutEngine";
 import { resolveBlockRelations } from "../lib/resolve-block-relations";
+import { substitutePrivacyMergeTags } from "../lib/privacy/contact-emails";
 
 const ECOMMERCE_BLOCK_TYPES = new Set([
   "product_grid",
@@ -143,9 +144,16 @@ async function renderLoadedBlock({
 
   // Keep common LCP-adjacent text blocks out of the dynamic renderer manifest.
   if (block.block_type === 'text') {
+    // Top-level text blocks bypass the server TextBlockRenderer, so resolve any
+    // merge tags (e.g. {{privacy_email}} on the Privacy/Terms pages) here.
+    const textContent = block.content as { html_content?: string } | null;
+    const rawHtml = typeof textContent?.html_content === 'string' ? textContent.html_content : '';
+    const html = rawHtml.includes('{{')
+      ? await substitutePrivacyMergeTags(rawHtml)
+      : rawHtml;
     return (
       <ClientTextBlockRenderer
-        content={block.content as any}
+        content={{ ...(textContent as any), html_content: html }}
         languageId={languageId}
         visualEditAttributes={visualEditAttributes}
       />

package/templates/nextblock-template/components/DeferredGoogleAnalytics.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { useEffect, useState, type ComponentType } from "react";
+
+interface DeferredGoogleAnalyticsProps {
+  gaId?: string;
+  nonce?: string;
+}
+
+const interactionEvents: Array<keyof WindowEventMap> = [
+  "pointerdown",
+  "keydown",
+  "scroll",
+  "touchstart",
+];
+
+type GoogleAnalyticsComponent = ComponentType<{
+  gaId: string;
+  nonce?: string;
+}>;
+
+export function DeferredGoogleAnalytics({
+  gaId,
+  nonce,
+}: DeferredGoogleAnalyticsProps) {
+  const [GoogleAnalytics, setGoogleAnalytics] =
+    useState<GoogleAnalyticsComponent | null>(null);
+
+  useEffect(() => {
+    if (!gaId) {
+      return;
+    }
+
+    let isMounted = true;
+
+    function removeListeners() {
+      interactionEvents.forEach((eventName) => {
+        window.removeEventListener(eventName, enableGa);
+      });
+    }
+
+    function enableGa() {
+      removeListeners();
+
+      void import("@next/third-parties/google").then(({ GoogleAnalytics }) => {
+        if (isMounted) {
+          setGoogleAnalytics(() => GoogleAnalytics as GoogleAnalyticsComponent);
+        }
+      });
+    }
+
+    interactionEvents.forEach((eventName) => {
+      window.addEventListener(eventName, enableGa, {
+        once: true,
+        passive: true,
+      });
+    });
+
+    return () => {
+      isMounted = false;
+      removeListeners();
+    };
+  }, [gaId]);
+
+  if (!gaId || !GoogleAnalytics) {
+    return null;
+  }
+
+  return <GoogleAnalytics gaId={gaId} nonce={nonce} />;
+}

package/templates/nextblock-template/components/blocks/renderers/TextBlockRenderer.tsx

@@ -2,17 +2,18 @@ import React from "react";
 import { headers } from 'next/headers';
 import ClientTextBlockRenderer from "./ClientTextBlockRenderer";
 import type { VisualEditAttributes } from "../../../lib/visual-editing/types";
+import { substitutePrivacyMergeTags } from "../../../lib/privacy/contact-emails";
 
 export type TextBlockContent = {
     html_content?: string;
 };
 
-interface TextBlockRendererProps {
-  content: TextBlockContent;
-  languageId: number;
-  visualEditAttributes?: VisualEditAttributes;
-  renderContext?: 'prose' | 'section';
-}
+interface TextBlockRendererProps {
+  content: TextBlockContent;
+  languageId: number;
+  visualEditAttributes?: VisualEditAttributes;
+  renderContext?: 'prose' | 'section';
+}
 
 function addNonceToInlineScripts(html: string, nonce: string): string {
   if (!html || !nonce) return html || '';
@@ -24,23 +25,27 @@ function addNonceToInlineScripts(html: string, nonce: string): string {
 }
 
 const TextBlockRenderer: React.FC<TextBlockRendererProps> = async ({
-  content,
-  languageId,
-  visualEditAttributes,
-  renderContext = 'prose',
-}) => {
+  content,
+  languageId,
+  visualEditAttributes,
+  renderContext = 'prose',
+}) => {
   const hdrs = await headers();
   const nonce = hdrs.get('x-nonce') || '';
-  const htmlWithNonce = content.html_content ? addNonceToInlineScripts(content.html_content, nonce) : '';
+  let html = content.html_content || '';
+  if (html.includes('{{')) {
+    html = await substitutePrivacyMergeTags(html);
+  }
+  const htmlWithNonce = html ? addNonceToInlineScripts(html, nonce) : '';
   const patchedContent = { ...content, html_content: htmlWithNonce };
   return (
-    <ClientTextBlockRenderer
-      content={patchedContent}
-      languageId={languageId}
-      visualEditAttributes={visualEditAttributes}
-      renderContext={renderContext}
-    />
-  );
-};
+    <ClientTextBlockRenderer
+      content={patchedContent}
+      languageId={languageId}
+      visualEditAttributes={visualEditAttributes}
+      renderContext={renderContext}
+    />
+  );
+};
 
 export default TextBlockRenderer;

package/templates/nextblock-template/components/privacy/ConsentGatedAnalytics.tsx

@@ -5,10 +5,12 @@
 // shows zero analytics bytes, preserving the Lighthouse budget.
 import { useEffect, useRef, useState } from 'react';
 import { DeferredGoogleTagManager } from '../DeferredGoogleTagManager';
+import { DeferredGoogleAnalytics } from '../DeferredGoogleAnalytics';
 import { CONSENT_CHANGE_EVENT, readConsent } from '../../lib/privacy/consent-client';
 
 interface ConsentGatedAnalyticsProps {
   gtmId?: string;
+  gaMeasurementId?: string;
   customScripts?: string;
   nonce?: string;
 }
@@ -29,6 +31,7 @@ function injectCustomScripts(markup: string, nonce?: string) {
 
 export function ConsentGatedAnalytics({
   gtmId,
+  gaMeasurementId,
   customScripts,
   nonce,
 }: ConsentGatedAnalyticsProps) {
@@ -54,6 +57,14 @@ export function ConsentGatedAnalytics({
     }
   }, [analyticsAllowed, customScripts, nonce]);
 
-  if (!analyticsAllowed || !gtmId) return null;
-  return <DeferredGoogleTagManager gtmId={gtmId} nonce={nonce} />;
+  if (!analyticsAllowed) return null;
+  if (!gtmId && !gaMeasurementId) return null;
+  return (
+    <>
+      {gtmId && <DeferredGoogleTagManager gtmId={gtmId} nonce={nonce} />}
+      {gaMeasurementId && (
+        <DeferredGoogleAnalytics gaId={gaMeasurementId} nonce={nonce} />
+      )}
+    </>
+  );
 }

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

@@ -109,6 +109,17 @@ repo expects at least:
 - `CRON_SECRET`, `DRAFT_MODE_SECRET`, `REVALIDATE_SECRET_TOKEN` — auto-generated
   by `npm run setup`
 
+> **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
+> injects: `SUPABASE_URL` (non-prefixed), `SUPABASE_PUBLISHABLE_KEY` /
+> `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (anon-equivalent), and `SUPABASE_SECRET_KEY`
+> (service-role-equivalent). Resolution lives in `apps/nextblock/lib/setup/env-status.ts`
+> (`resolveSupabaseUrl` / `resolveSupabaseAnonKey` / `resolveSupabaseServiceKey`); read
+> Supabase env through those (or the same inline alias chain in published libs) rather
+> than a single raw name. `DRAFT_MODE_SECRET` / `REVALIDATE_SECRET_TOKEN` are optional in
+> 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:
 
 - R2 credentials for media storage. The app builds and serves without them, but

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

@@ -115,11 +115,62 @@ package activation state.
 
 ## Publishing and Release Notes
 
-Inside the monorepo, CLI release work is still tied to the source workspace:
-
-- library builds and publishes happen from the workspace
-- template sync happens before CLI packaging
-- the CLI package itself is versioned in `apps/create-nextblock/package.json`
-
-If a generated project looks stale, check the sync script and template output
-before assuming the source app is missing the feature.
+A generated project installs the libraries from **npm**, so a feature only reaches
+scaffolds after the libs are republished. (The monorepo's own Vercel deploy builds the
+libs from source, so it sees changes immediately — only `npm create` scaffolds need a
+republish.)
+
+### Release commands
+
+- `npm run release:all -- <version>` — build **and publish every package** at one
+  synchronized version, in dependency order: `utils → ui → sdk → db → editor → ecom`,
+  then `release-cli.js` (which stamps the root + template + `create-nextblock`, re-syncs
+  the template, and publishes the CLI). Pass an explicit semver (e.g. `0.10.2`);
+  `--dry-run` prints the plan only.
+- `npm run build:<lib>` (`build:utils|ui|db|editor|sdk|ecom`) and
+  `node tools/scripts/release-lib.js <lib> <version>` — build + publish a **single** lib
+  (`<lib>` is the nx project name, so use `ecommerce`, which maps to the published
+  `@nextblock-cms/ecom`). `npx nx build <lib>` only *compiles*, it does not publish.
+
+### npm 2FA / OTP (and capturing a log)
+
+Publishing requires a one-time password if the npm account has 2FA. **Piping the command
+output breaks the interactive OTP prompt** — `npm run release:all -- … 2>&1 | Tee-Object …`
+(or `| tee`) fails with `npm error code EOTP` because npm no longer has a TTY. Either:
+
+- set an npm **Automation** token (`npm config set //registry.npmjs.org/:_authToken …`),
+  which bypasses 2FA — then piping to a log file is fine; or
+- capture with PowerShell `Start-Transcript -Path release.log; npm run release:all -- … ;
+  Stop-Transcript`, which records the session while npm keeps its terminal.
+
+`release:all` has no "already published" guard: if it dies partway, re-running the same
+version re-publishes from the top and 403s on the first already-published lib. Finish a
+partial release by running the **remaining** libs individually
+(`node tools/scripts/release-lib.js <lib> <version>` … then `release-cli.js <version>`),
+or bump to a fresh version and re-run the whole thing.
+
+### Library build gotchas (dts / tsconfig)
+
+Each lib emits its `.d.ts` via `vite-plugin-dts` running tsc on `tsconfig.lib.json`. When a
+lib imports a sibling (`ui`/`db` import `utils`; `ecom` imports all), how you wire the
+tsconfig decides whether the build log is clean:
+
+- A **composite** lib (`ui`, `db` — `db` inherits it) must **list the imported sibling's
+  sources in `include`** (e.g. `"../utils/src/**/*.ts"`) and keep `"references": []`.
+  Mirror `libs/editor`, which always built clean this way. A composite project
+  `reference` to the sibling triggers `TS6305` ("output not built" — vite never produces
+  the `tsc -b` out-tsc output); empty `references` *without* the `include` triggers
+  `TS6307` ("file not listed"). Both are non-fatal log noise but should stay at zero.
+- A **non-composite** lib (`ecom`, which extends `tsconfig.base.json`) just needs
+  `"references": []` — no `include` of siblings.
+- A **strict** lib (`db`/`sdk` set `noPropertyAccessFromIndexSignature`) compiles the
+  sibling's *source* under its strict rules, so `libs/utils` must stay strict-clean
+  (bracket-access undeclared keys, e.g. `process.env['R2_BUCKET_NAME']`).
+
+`vite-plugin-dts` `entryRoot: 'src'` keeps emission to the lib's own `src`, so listing
+sibling sources does **not** leak their `.d.ts` into the tarball. The published `bin` path
+in `apps/create-nextblock/package.json` should have **no leading `./`** (`bin/…`, not
+`./bin/…`) or npm "auto-corrects" it with a publish warning.
+
+If a generated project looks stale, check the sync script and template output (and whether
+the libs were actually republished) before assuming the source app is missing the feature.

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

@@ -17,6 +17,7 @@ library surfaces rather than historical planning notes.
 - 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)
 
 ## Audience Guide
 
@@ -26,7 +27,9 @@ library surfaces rather than historical planning notes.
 - 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`.
 - 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