create-nextblock 0.17.0 → 0.17.2

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

@@ -178,11 +178,17 @@ Production rule:
 - Add a new forward-only `.sql` file under
   `libs/db/src/supabase/migrations` for each production schema/data change.
 - Use `npm run db:migrate:check` before `npm run db:migrate`.
-- If `db:migrate:check` lists historical baseline migrations such as
-  `00000000000000_setup_foundation_and_enums.sql` on an existing production database, do
-  not run `db:migrate` yet. Run `npm run db:migrate:repair-history:check`,
-  then `npm run db:migrate:repair-history`, then check again. The expected
-  result after repair is that only new unapplied migrations remain.
+- Migration files are named `GGNNN_<snake_name>.sql` (GG = squash generation, NNN =
+  sequence, contiguous). The next number is the highest sequence on disk + 1 in the same
+  generation; `db:migrate:check` prints it and fails on any other name shape. See
+  [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md) → "Migration Structure".
+- If `db:migrate:check` lists the generation baseline (`02001_baseline_schema.sql` …) as
+  pending on an existing database whose history is empty, do not run `db:migrate` yet.
+  Run `npm run db:migrate:repair-history:check`, then `npm run db:migrate:repair-history`,
+  then check again. If instead it shows retired 14-digit versions "recorded remotely with
+  no local file" beside the pending baseline, the database has not crossed the squash:
+  run `npm run db:migrate:repair-history:check -- --reconcile-squash`, then the same without
+  `:check`. The expected result after either repair is that only new unapplied migrations remain.
 - Do not use `npm run db:reset`, `npm run sandbox:reset`,
   `npm run db:migrate:fresh`, or `npm run db:push:sandbox` against production.
 
@@ -198,9 +204,10 @@ The migration-only script:
 - runs `supabase db push` without `--include-all`
 - never runs a reset, seed script, function deploy, or config push
 
-Because the migration set started as a squashed baseline, contributors should
-treat the existing baseline files as grouped domains. New production changes
-after the baseline should be appended as new migrations.
+The migration set is a squashed baseline (one generation at a time — see
+[04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md) → "Migration Structure"). Treat the
+baseline files as grouped domains and append every new production change as a new
+`GGNNN` migration; never edit the baseline or the catch-up.
 
 ## Sandbox Reset Operations
 

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

@@ -82,7 +82,7 @@ Known incomplete or future work:
 
 | File | Purpose |
 | --- | --- |
-| `libs/db/src/supabase/migrations/00000000000011_setup_cortex_ai_settings.sql` | RLS hardening for the sensitive `site_settings` Cortex AI key row. |
+| `libs/db/src/supabase/migrations/02003_baseline_security_and_grants.sql` (originally `00000000000011_setup_cortex_ai_settings`, folded in by the generation-2 squash) | RLS hardening for the sensitive `site_settings` Cortex AI key row. |
 | `apps/nextblock/app/api/cron/reset-sandbox/route.ts` | Sandbox reset route. Upserts active package activation for `cortex-ai` when `FREEMIUS_AI_SANDBOX_KEY` exists. |
 | `apps/nextblock/app/api/cron/reset-sandbox/sandboxResetSql.ts` | Generated SQL bundle that includes the Cortex AI migration. |
 
@@ -271,7 +271,7 @@ The value is a JSON envelope:
 }
 ```
 
-The migration `00000000000011_setup_cortex_ai_settings.sql` hardens RLS:
+The migration `libs/db/src/supabase/migrations/02003_baseline_security_and_grants.sql` (originally `00000000000011_setup_cortex_ai_settings`, folded in by the generation-2 squash) hardens RLS:
 
 - Public users can read non-sensitive site settings.
 - The sensitive Cortex AI key row is readable only by authenticated admins.
@@ -1061,7 +1061,7 @@ Cortex can insert real photos into pages at zero inference cost, and external im
 - In `libs/cortex/src/lib/ai-global-agent-tools.ts`; registered in `createCortexGlobalAgentTools`.
 - Input: `{ query: string, count?: 1-15 (default 6), orientation?: 'landscape'|'portrait'|'square' }`.
 - Key resolution: `resolveCortexAiStockPhotoProvider(supabase)` prefers an admin-stored, encrypted key in `site_settings` (`cortex_ai_pexels_api_key` / `cortex_ai_unsplash_access_key`, read via the service-role client), then falls back to the `PEXELS_API_KEY` / `UNSPLASH_ACCESS_KEY` env vars. Pexels wins when both exist. Returns a clear "not configured" message if neither is set. Both are free API keys.
-- The stored keys are protected by migration `00000000000012_cortex_ai_stock_photo_settings.sql`, which adds them to the `site_settings` sensitive-keys RLS group (admin-only read/write, never anon-readable), and encrypted with the same envelope as the OpenRouter BYOK key.
+- The stored keys are protected by migration `libs/db/src/supabase/migrations/02003_baseline_security_and_grants.sql` (originally `00000000000012_cortex_ai_stock_photo_settings`, folded in by the generation-2 squash), which adds them to the `site_settings` sensitive-keys RLS group (admin-only read/write, never anon-readable), and encrypted with the same envelope as the OpenRouter BYOK key.
 - **The model is told up front whether stock photos are available.** The global-agent route resolves the provider and injects it into the system prompt: available → "use search_stock_photos"; not configured → "do NOT call search_stock_photos; use gradient/theme backgrounds." So a missing key never wastes a tool call, and the keys are never mandatory — Cortex builds pages either way.
 - Admin UI: `/cms/settings/cortex-ai` has a Stock Photos card (save/clear Pexels + Unsplash keys, step-by-step, and why) via `saveStockPhotoKeysAction` / `clearStockPhotoKeysAction`.
 - Rate-limit fallback: `resolveCortexAiStockPhotoProviders` returns ALL configured providers ordered Pexels→Unsplash; `executeSearchStockPhotos` tries them in order, falling through to the next on error/HTTP 429/empty results, and returns `attemptedProviders`.
@@ -1106,7 +1106,7 @@ from inside the editor.
 | `apps/nextblock/app/cms/settings/cortex-ai/mcp-actions.ts` | Admin server actions: settings, mint, revoke. |
 | `apps/nextblock/app/cms/settings/cortex-ai/McpServerSettingsCard.tsx` | Settings UI + copy-paste client config. |
 | `apps/nextblock/app/cms/settings/cortex-ai/require-admin.ts` | Shared admin gate (also used by `actions.ts`). |
-| `libs/db/src/supabase/migrations/00000000000017_cortex_ai_mcp_server.sql` | `mcp_access_tokens` table + `cortex_ai_mcp_settings` RLS. |
+| `libs/db/src/supabase/migrations/02003_baseline_security_and_grants.sql` (originally `00000000000017_cortex_ai_mcp_server`, folded in by the generation-2 squash) | `mcp_access_tokens` table + `cortex_ai_mcp_settings` RLS. |
 
 ### Protocol decisions
 
@@ -1241,7 +1241,7 @@ tools cannot read token hashes or insert rows.
 ### Marketing surfaces that describe the MCP server
 
 Three seeded content rows sell the MCP story and are kept at 100/100 in the built-in SEO
-engine (`libs/utils/src/lib/seo`). Migration `00000000000037_reposition_marketing_and_cortex_mcp.sql`
+engine (`libs/utils/src/lib/seo`). Migration `libs/db/src/supabase/migrations/02004_baseline_seed.sql` (originally `00000000000037_reposition_marketing_and_cortex_mcp`, folded in by the generation-2 squash)
 owns them; the sandbox reset route (`enrichCortexAiProducts`) mirrors the product sections
 because it deletes and re-inserts product blocks after the SQL replay, so edit both together.
 

package/templates/nextblock-template/docs/10-CUSTOM-BLOCKS.md

@@ -25,7 +25,7 @@ revisions without special-casing.
 ## Data Model
 
 The table is created in
-`libs/db/src/supabase/migrations/00000000000023_setup_custom_block_definitions.sql`.
+`libs/db/src/supabase/migrations/02001_baseline_schema.sql` (originally `00000000000023_setup_custom_block_definitions`, folded in by the generation-2 squash).
 
 `public.custom_block_definitions`:
 

package/templates/nextblock-template/docs/11-SELF-HOSTED-DOCKER.md

@@ -103,7 +103,10 @@ Both named volumes persist your database and uploaded media across restarts.
 > `public._nextblock_docker_migrations` — a different tracker from the one every other
 > install uses), so applying the same SQL from the updater as well would run it through two
 > trackers. The updater refreshes the SQL on disk and hands the schema step to the stack.
-> Full details in [docs/13](./13-STAYING-UP-TO-DATE.md).
+> Full details in [docs/13](./13-STAYING-UP-TO-DATE.md). Migration squashes (new
+> `GG000`–`GG004` generations, see [docs/04](./04-DATABASE-AND-AUTH.md)) need nothing
+> extra here: the generation's catch-up file consults `public._nextblock_docker_migrations`
+> by file stem, so it replays only what this stack never applied.
 
 ### Ports (override with env vars)
 

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

@@ -167,15 +167,18 @@ the question entirely by resolving everything in-app, so the button prompts for
 
 ## Cron jobs and the Hobby plan
 
-`vercel.json` declares two crons (`/api/cron/reset-sandbox` at 03:00 and
-`/api/cron/sync-currencies` at 18:00). Vercel's **Hobby (free) tier allows up to 100
-cron jobs, each running at most once per day** — both jobs are daily, so they deploy
-fine on the free tier. (Hobby timing is approximate, ±59 min, which is irrelevant for
-daily jobs; only sub-daily schedules like `0 * * * *` are rejected on Hobby.)
-
-`reset-sandbox` only does work in sandbox mode — it returns 404 otherwise — so on a
-normal deploy it is a harmless no-op. Delete it from `vercel.json` if you'd rather not
-see it scheduled.
+`vercel.json` declares two crons: `/api/cron/reset-sandbox` **every 15 minutes**
+(`*/15 * * * *`) and `/api/cron/sync-currencies` daily at 18:00 UTC. The 15-minute
+schedule is what keeps the public sandbox at `cms.nextblock.dev` fresh; that project
+runs on **Vercel Pro**, which allows cron schedules down to once per minute with
+per-minute precision.
+
+Vercel’s **Hobby (free) tier only allows cron jobs that run at most once per day**
+(timing is approximate, ±59 min), and **a sub-daily schedule fails the deployment**
+outright. So on a Hobby project you must **delete the `reset-sandbox` entry from
+`vercel.json`** before deploying. Nothing is lost: `reset-sandbox` only does work in
+sandbox mode — it returns 404 otherwise — so on a normal deploy it is a harmless
+no-op anyway. `sync-currencies` is daily and deploys fine on Hobby.
 
 ## After deploy
 

package/templates/nextblock-template/docs/13-STAYING-UP-TO-DATE.md

@@ -278,6 +278,14 @@ types forward while leaving the schema behind — the app would then fail at run
   project → `node_modules/@nextblock-cms/db`), deduping by version, so even a user who only
   ran `npm install` gets the new SQL.
 
+> **Migration squashes.** Every so often the folder is squashed into a new *generation*
+> (`02000`–`02004`, then `02005+`; see [docs/04](./04-DATABASE-AND-AUTH.md) → "Migration
+> Structure"). An install crosses a squash with no manual step: the new generation's files
+> are simply pending, its `GG000_catchup_*` file replays only the retired migrations this
+> database never recorded, the baseline DDL is idempotent, and the seed skips any database
+> that already holds content. Retired files that linger in `<project>/supabase/migrations`
+> are harmless — they are already recorded, so nothing applies them twice.
+
 ### Build-time migrations
 
 A build-time hook ([`apps/nextblock/tools/build-migrate.mjs`](../apps/nextblock/tools/build-migrate.mjs))

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

@@ -285,8 +285,8 @@ Trusted platform headers (`x-vercel-forwarded-for`, `x-real-ip`) are preferred o
 
 ## 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
+- `libs/db/src/supabase/migrations/02001_baseline_schema.sql` (originally `00000000000027_message_threads`, folded in by the generation-2 squash) — private lane, `form_endpoints`, the form-block data migration
+- `libs/db/src/supabase/migrations/02001_baseline_schema.sql` (originally `00000000000028_interaction_replies`, folded in by the generation-2 squash) — `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