create-nextblock 0.16.4 → 0.17.1

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/07-BLOCK-SDK-AND-EXTENSIBILITY.md

@@ -1,146 +1,146 @@
-# 07 Block SDK and Extensibility
-
-## What the SDK Is
-
-`libs/sdk` is the typed contract for block-style extensibility. It is much
-smaller than the in-app block registry because it defines an external authoring
-interface, not the full CMS implementation.
-
-The main export is:
-
-- `@nextblock-cms/sdk`
-
-## Current SDK Surface
-
-`libs/sdk/src/lib/sdk.ts` currently exports the following core types:
-
-- `BlockContentSchema`
-- `BlockData<TSchema>`
-- `BlockProps<TSchema>`
-- `BlockEditorProps<TSchema>`
-- `BlockConfig<TSchema>`
-- `LucideIcon`
-
-## Contract Shape
-
-### Schema
-
-Every block is defined around a Zod object schema:
-
-```ts
-type BlockContentSchema = z.ZodObject<any>;
-```
-
-The runtime content type is inferred from that schema through `BlockData`.
-
-### Renderer contract
-
-The public rendering contract is:
-
-- `content`
-- optional `className`
-- `isInEditor`
-- `languageKey`
-
-### Editor contract
-
-The editing contract is:
-
-- `content`
-- `block`
-- `onChange`
-
-### Registration contract
-
-A block registration object currently requires:
-
-- `type`
-- `label`
-- optional `icon`
-- `schema`
-- `initialContent`
-- `RendererComponent`
-- `EditorComponent`
-
-## Relationship to the App Block Registry
-
-The app already has an internal registry in
-`apps/nextblock/lib/blocks/blockRegistry.ts`.
-
-That registry is richer than the SDK because it also includes:
-
-- filename-based editor loading
-- filename-based renderer loading
-- CMS-specific helper metadata
-- in-repo block defaults for built-in block types
-
-The important distinction is:
-
-- `libs/sdk` defines the reusable contract
-- `apps/nextblock/lib/blocks/blockRegistry.ts` defines the current built-in
-  implementation
-
-They are related, but they are not the same file or the same level of
-abstraction.
-
-## Current Built-In Extensibility Pattern
-
-Today, adding a built-in block to the app usually means updating:
-
-- the app block registry
-- a CMS editor component
-- a front-end renderer component
-- any supporting schemas or helpers
-
-The existing registry already exposes enough information to support:
-
-- runtime validation
-- default content generation
-- block label lookup
-- block picker rendering
-
-## Commerce-Aware Extensibility
-
-The built-in block registry already contains ecommerce-aware blocks:
-
-- `product_grid`
-- `featured_product`
-- `cart`
-- `checkout`
-- `product_details`
-
-That means the current extensibility surface is not limited to editorial
-content. It already supports block types that render premium commerce
-components.
-
-## Data-Driven Custom Blocks
-
-There is now a third extensibility path that needs no code deploy at all.
-Editors can define block types at runtime from the CMS; each definition is a
-`custom_block_definitions` row (typed fields plus a recursive layout schema)
-rendered on the public site by a dynamic layout engine rather than a compiled
-React component.
-
-So the extensibility surface has three layers:
-
-- **Code-defined built-ins** — the app block registry plus React
-  editor/renderer files. Most flexible, requires a deploy.
-- **The typed SDK contract** (`libs/sdk`) — a small, typed authoring interface
-  for reusable or external blocks.
-- **Data-defined custom blocks** (`custom_block_definitions`) — full CRUD from
-  the CMS, no deploy, rendered from stored JSONB.
-
-Custom blocks are documented in detail in
-[10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md).
-
-## Practical Guidance
-
-- If you are building or refactoring built-in CMS blocks, start with the app
-  registry and editor/renderer files.
-- If you are shaping an external or reusable authoring contract, start with
-  `libs/sdk`.
-- If you need both, keep the SDK contract small and typed, and let the app
-  registry stay responsible for CMS-specific loading behavior.
-- If you want editors to create block types without a deploy, reach for
-  data-driven custom blocks (`custom_block_definitions`) instead of either of
-  the above.
+# 07 Block SDK and Extensibility
+
+## What the SDK Is
+
+`libs/sdk` is the typed contract for block-style extensibility. It is much
+smaller than the in-app block registry because it defines an external authoring
+interface, not the full CMS implementation.
+
+The main export is:
+
+- `@nextblock-cms/sdk`
+
+## Current SDK Surface
+
+`libs/sdk/src/lib/sdk.ts` currently exports the following core types:
+
+- `BlockContentSchema`
+- `BlockData<TSchema>`
+- `BlockProps<TSchema>`
+- `BlockEditorProps<TSchema>`
+- `BlockConfig<TSchema>`
+- `LucideIcon`
+
+## Contract Shape
+
+### Schema
+
+Every block is defined around a Zod object schema:
+
+```ts
+type BlockContentSchema = z.ZodObject<any>;
+```
+
+The runtime content type is inferred from that schema through `BlockData`.
+
+### Renderer contract
+
+The public rendering contract is:
+
+- `content`
+- optional `className`
+- `isInEditor`
+- `languageKey`
+
+### Editor contract
+
+The editing contract is:
+
+- `content`
+- `block`
+- `onChange`
+
+### Registration contract
+
+A block registration object currently requires:
+
+- `type`
+- `label`
+- optional `icon`
+- `schema`
+- `initialContent`
+- `RendererComponent`
+- `EditorComponent`
+
+## Relationship to the App Block Registry
+
+The app already has an internal registry in
+`apps/nextblock/lib/blocks/blockRegistry.ts`.
+
+That registry is richer than the SDK because it also includes:
+
+- filename-based editor loading
+- filename-based renderer loading
+- CMS-specific helper metadata
+- in-repo block defaults for built-in block types
+
+The important distinction is:
+
+- `libs/sdk` defines the reusable contract
+- `apps/nextblock/lib/blocks/blockRegistry.ts` defines the current built-in
+  implementation
+
+They are related, but they are not the same file or the same level of
+abstraction.
+
+## Current Built-In Extensibility Pattern
+
+Today, adding a built-in block to the app usually means updating:
+
+- the app block registry
+- a CMS editor component
+- a front-end renderer component
+- any supporting schemas or helpers
+
+The existing registry already exposes enough information to support:
+
+- runtime validation
+- default content generation
+- block label lookup
+- block picker rendering
+
+## Commerce-Aware Extensibility
+
+The built-in block registry already contains ecommerce-aware blocks:
+
+- `product_grid`
+- `featured_product`
+- `cart`
+- `checkout`
+- `product_details`
+
+That means the current extensibility surface is not limited to editorial
+content. It already supports block types that render premium commerce
+components.
+
+## Data-Driven Custom Blocks
+
+There is now a third extensibility path that needs no code deploy at all.
+Editors can define block types at runtime from the CMS; each definition is a
+`custom_block_definitions` row (typed fields plus a recursive layout schema)
+rendered on the public site by a dynamic layout engine rather than a compiled
+React component.
+
+So the extensibility surface has three layers:
+
+- **Code-defined built-ins** — the app block registry plus React
+  editor/renderer files. Most flexible, requires a deploy.
+- **The typed SDK contract** (`libs/sdk`) — a small, typed authoring interface
+  for reusable or external blocks.
+- **Data-defined custom blocks** (`custom_block_definitions`) — full CRUD from
+  the CMS, no deploy, rendered from stored JSONB.
+
+Custom blocks are documented in detail in
+[10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md).
+
+## Practical Guidance
+
+- If you are building or refactoring built-in CMS blocks, start with the app
+  registry and editor/renderer files.
+- If you are shaping an external or reusable authoring contract, start with
+  `libs/sdk`.
+- If you need both, keep the SDK contract small and typed, and let the app
+  registry stay responsible for CMS-specific loading behavior.
+- If you want editors to create block types without a deploy, reach for
+  data-driven custom blocks (`custom_block_definitions`) instead of either of
+  the above.

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
 
@@ -1238,6 +1238,25 @@ now carries `PROTECTED_SITE_SETTING_KEYS`, redacted on read and refused on write
 `mcp_access_tokens` is deliberately **absent** from `tableConfigs`, so the generic DB
 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 `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.
+
+| Surface | Focus keyphrase (type it into the audit panel; it is not persisted) | Body format |
+| :-- | :-- | :-- |
+| Home page `home` (EN) — hero, "why" (seven-row prototype-tools-vs-NextBlock chart + pricing tiles), "how MCP works", Cortex promo sections | `AI website builder CMS` | styled HTML in `section` → `text` blocks; 040 added the chart, 041 put the pricing message on every section: CMS free forever, Cortex AI (in-editor AI + MCP server) is the one paid license with a 30-day no-card trial, "deploy to Vercel in one click, up in ten minutes" |
+| Product `nextblock-cortex-ai-cortex-ai-license` (EN) | `Cortex AI MCP server` | styled HTML in five `section` blocks; title "NextBlock™ Cortex AI MCP Server & AI Editor License" (041 — never "copilot", the product is Cortex AI) |
+| Post `cortex-ai-mcp-connection-guide` (EN) | `connect Claude to NextBlock CMS` | styled HTML in one `text` block: comparison chart, a CSS/HTML flow diagram (four cards, `not-prose`), terminal panels; 037 seeded a plain Tiptap doc, 038 replaced it with a rasterised diagram, 041 replaced that with the CSS version and retired the media row |
+| Articles page `articles` (EN + FR) | none set (grades 100 without; EN also 100 with `NextBlock Journal`) | short hero + `posts_grid` + a "What the journal covers" section with four topic cards below the grid (041 moved the ~300-word essay out of the hero) |
+| Posts `how-nextblock-works` / `comment-nextblock-fonctionne` | none set (both grade 100) | styled HTML; 042 replaced the `extensibility.webp` figure with a CSS/HTML architecture diagram (core hub with the site logo, four spokes, three panels, stack strip, tagline) built inside the text block — the image file and media row stay because the sandbox reset registers it as a core asset |
+
+The copy names only the five contract tools above plus the real transport and auth rules
+(Streamable HTTP, bearer tokens, localhost trust in development, Live Draft staging). If any
+of those change, the product page and the guide are the two places that go stale.
+
 ## Advanced Agent Settings
 
 The global agent's model limits are admin-tunable from `/cms/settings/cortex-ai` (collapsible "Advanced settings"), stored as a non-secret JSON `site_settings` row `cortex_ai_agent_settings` and read by the route via `resolveCortexAiAgentSettings(supabase)` (defaults + clamping in `normalizeCortexAiAgentSettings`, `libs/cortex/src/lib/ai-config.ts`):