create-nextblock 0.15.5 → 0.15.8

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 /