create-nextblock 0.16.3 → 0.17.0

package/templates/nextblock-template/docs/04-DATABASE-AND-AUTH.md

@@ -183,6 +183,17 @@ Every file is fully idempotent. Existing databases already have versions
 `000`–`003` recorded, so both appliers skip the baseline — it only runs on a
 fresh/empty database.
 
+Seed *data-fix* migrations (the `seed_seo_*` series, `reposition_marketing_*`) must scope
+every UPDATE by **content signature and parent** (`WHERE page_id = v_home AND content::text
+LIKE '%Blazing-Fast%'`), never by a numeric `blocks.id`. `blocks`, `pages` and `posts` ids
+are identity columns, so any install that created or deleted a row since the baseline has
+different ids from the one the migration was written against — including the sandbox, which
+re-creates rows on every reset. `00000000000035` keyed its product-block updates by id and,
+on drifted installs, wrote French Commerce Pro copy over the home-page Live Demo promo and
+over the first block of the French install guide; `00000000000037` carries the
+signature-scoped repair. Signature guards also make a migration idempotent for free: once
+the copy is replaced, the guard no longer matches.
+
 `00000000000004` was the first migration appended after that re-baseline, not the
 one still to be written — the folder has grown well past it. **To find the next
 number, list `libs/db/src/supabase/migrations` and take the one after the highest

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

@@ -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 `00000000000037_reposition_marketing_and_cortex_mcp.sql`
+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`):