Release 6.5.0

AGENTS.md

@@ -24,6 +24,8 @@ The `generate-changelog.ts` script reads `## Skipped PRs` to avoid re-adding man
 
 PRs for a release are discovered from the release commits (the `(#NNNN)` references between the previous release tag and this version's tag/branch), **not** from a GitHub milestone — so a forgotten milestone no longer drops entries. Run `yarn generate:changelog --version <v> --dry-run` to preview the PRs that would be included.
 
+**Upgrade guide custom steps:** `upgrade-guide.mdx` is regenerated from a template by the release workflows. Put release-specific steps between the `{/* custom-steps:start ... */}` and `{/* custom-steps:end */}` markers, before `<AdditionalNotes />`. `scripts/generate-upgrade-guide.ts` keeps that block and the page `id` on every run. Anything outside the markers is overwritten.
+
 **Review markers:** every generated entry gets an MDX comment beneath its `###` heading naming the PR author(s), e.g. `{/* REVIEW-PENDING @author — confirm this entry, then delete this line */}`. Each author must inspect their entry and delete that line. CI (`.github/workflows/check-release-notes.yml`, via `yarn check:changelog-review`) fails on any PR to master that still contains a `REVIEW-PENDING` marker, so release notes cannot be published until every entry is confirmed.
 
 ### Validation and Quality

docs/developer-docs/6.x/website-builder/custom-component.ai.txt

@@ -2,7 +2,7 @@ AI Context: Create Custom Component (website-builder/custom-component.mdx)
 
 Source of Information:
 1. /Users/adrian/dev/lw/content/lessons/website-builder/editor-components.mdx - Learn Webiny lesson
-2. @webiny/website-builder-nextjs SDK documentation
+2. @webiny/sdk-nextjs SDK (6.5; was @webiny/website-builder-nextjs in 6.4)
 3. Website Builder Next.js starter kit editor component examples
 
 Key Documentation Decisions:
@@ -23,11 +23,11 @@ Understanding Editor Components:
 - Two parts: React component + manifest (name, label, group, inputs)
 - React component receives inputs prop typed with ComponentProps<YourInputs>
 - Manifest tells editor what inputs to expose in sidebar
-- createComponent() combines React component with manifest
+- createWbComponent() combines React component with manifest (createComponent() is the same function, used by 6.4 projects)
 - editorComponents array registered with DocumentRenderer
 - Must be "use client" - SDK runs in browser, uses postMessage
 - Component names stored in page documents - stable identifiers
-- groups.ts registers component groups for palette organization
+- sdk/groups.ts exports a componentGroups array, passed to sdk.init() as wb.componentGroups (6.4 used registerComponentGroup() calls)
 - filter option can create catch-all groups
 
 Component Registration Pattern:
@@ -86,10 +86,10 @@ Related Documents:
 - website-builder/theme.mdx - Theme configuration
 
 Key Code Locations:
-- src/editorComponents/index.tsx - Component registration
-- src/editorComponents/[ComponentName].tsx - Individual components
-- src/contentSdk/groups.ts - Component group registration
-- @webiny/website-builder-nextjs - SDK exports
+- editorComponents/index.tsx - Component registration
+- editorComponents/[ComponentName].tsx - Individual components
+- sdk/groups.ts - Component group definitions
+- @webiny/sdk-nextjs - SDK exports
 
 Tone Guidelines:
 - Technical and practical - how-to guide format

docs/developer-docs/6.x/website-builder/custom-component.mdx

@@ -13,7 +13,7 @@ import bannerComponentRendered from "./assets/banner-component-rendered.png";
 
 - What editor components are and how they work
 - How to create a React component that receives editor inputs
-- How to register components with `createComponent()` and input types
+- How to register components with `createWbComponent()` and input types
 - How to organize components into groups in the editor palette
 
 </Alert>
@@ -37,19 +37,19 @@ An editor component has two parts:
 
 **The manifest** — Metadata that tells the editor about the component: its name, label, group, and what inputs (configurable props) it exposes to the editor sidebar.
 
-You combine both using `createComponent()` from `@webiny/website-builder-nextjs`, then add the result to the `editorComponents` array that you pass to `DocumentRenderer`.
+You combine both using `createWbComponent()` from `@webiny/sdk-nextjs`, then add the result to the `editorComponents` array that you pass to `DocumentRenderer`.
 
 ## The editorComponents Array
 
-The starter kit includes an `editorComponents` array in `src/editorComponents/index.tsx`:
+The starter kit includes an `editorComponents` array in `editorComponents/index.tsx`:
 
-```tsx src/editorComponents/index.tsx
+```tsx editorComponents/index.tsx
 "use client";
-import { createComponent } from "@webiny/website-builder-nextjs";
+import { createWbComponent } from "@webiny/sdk-nextjs";
 import { Hero1 } from "./Hero1";
 
 export const editorComponents = [
-  createComponent(Hero1, {
+  createWbComponent(Hero1, {
     name: "Webiny/Hero",
     label: "Hero #1",
     inputs: []
@@ -60,33 +60,35 @@ export const editorComponents = [
 Key points:
 
 - The file is marked `"use client"` — component registrations must run on the client because the SDK communicates with the editor via the browser.
-- `createComponent()` takes the React component as its first argument and the manifest as the second.
+- `createWbComponent()` takes the React component as its first argument and the manifest as the second. Projects upgraded from 6.4 may still call it `createComponent()`, which is the same function.
 - `name` is a namespaced string — use a consistent convention like `"YourNamespace/ComponentName"`. Component names are stored in page documents, so treat them as stable identifiers. Renaming a component breaks existing pages.
 - `inputs` defines the configurable props that appear in the editor sidebar. An empty array means no inputs.
 - `group` (optional) links the component to a named component group in the editor palette.
 
 ## Component Groups
 
-Component groups organize the editor's component palette into sections. They're registered in `src/contentSdk/groups.ts`:
+Component groups organize the editor's component palette into sections. The starter kit defines them in `sdk/groups.ts`:
 
-```typescript src/contentSdk/groups.ts
-import { registerComponentGroup, type ComponentManifest } from "@webiny/website-builder-nextjs";
+```typescript sdk/groups.ts
+import type { ComponentManifest, ComponentGroup } from "@webiny/sdk-nextjs";
 
-export const registerComponentGroups = () => {
-  registerComponentGroup({
+export const componentGroups: ComponentGroup[] = [
+  {
     name: "basic",
     label: "Basic",
     description: "Components for simple content creation"
-  });
-  registerComponentGroup({
+  },
+  {
     name: "custom",
     label: "Custom",
     description: "Assorted custom components",
     filter: (component: ComponentManifest) => !component.group
-  });
-};
+  }
+];
 ```
 
+`sdk/initializeSdk.ts` passes the array to the SDK as `wb.componentGroups` in the `sdk.init()` call.
+
 The `filter` option on the "custom" group is a catch-all: it collects any component that doesn't have an explicit `group` set in its manifest.
 
 ## Building a Custom Component
@@ -95,11 +97,11 @@ Let's build a **Banner** component—a full-width colored strip with a headline
 
 ### Create the React Component
 
-Create `src/editorComponents/Banner.tsx`:
+Create `editorComponents/Banner.tsx`:
 
-```tsx src/editorComponents/Banner.tsx
+```tsx editorComponents/Banner.tsx
 import React from "react";
-import { ComponentProps } from "@webiny/website-builder-nextjs";
+import { ComponentProps } from "@webiny/sdk-nextjs";
 
 interface BannerInputs {
   headline: string;
@@ -124,25 +126,25 @@ export function Banner({ inputs: { headline, ctaLabel, ctaUrl } }: ComponentProp
 }
 ```
 
-Always type your component with `ComponentProps<YourInputs>` from `@webiny/website-builder-nextjs`. Without it, TypeScript won't know the shape of the `inputs` prop.
+Always type your component with `ComponentProps<YourInputs>` from `@webiny/sdk-nextjs`. Without it, TypeScript won't know the shape of the `inputs` prop.
 
 ### Register the Component
 
-Add the Banner to `src/editorComponents/index.tsx`:
+Add the Banner to `editorComponents/index.tsx`:
 
-```tsx src/editorComponents/index.tsx
+```tsx editorComponents/index.tsx
 "use client";
-import { createComponent, createTextInput } from "@webiny/website-builder-nextjs";
+import { createWbComponent, createTextInput } from "@webiny/sdk-nextjs";
 import { Hero1 } from "./Hero1";
 import { Banner } from "./Banner";
 
 export const editorComponents = [
-  createComponent(Hero1, {
+  createWbComponent(Hero1, {
     name: "Webiny/Hero",
     label: "Hero #1",
     inputs: []
   }),
-  createComponent(Banner, {
+  createWbComponent(Banner, {
     name: "Custom/Banner",
     label: "Banner",
     inputs: [
@@ -209,19 +211,20 @@ The SDK exports a factory function for each input type:
 | `createLexicalInput`  | Rich text (Lexical editor)          |
 | `createFileInput`     | File / media picker                 |
 | `createSlotInput`     | Slot for nesting other components   |
+| `createContentEntryInput` | One or more Headless CMS entries, picked by hand or queried |
 
 ## Example: Select Input
 
 To add a color theme selector to the Banner component:
 
-```tsx src/editorComponents/index.tsx
+```tsx editorComponents/index.tsx
 import {
-  createComponent,
+  createWbComponent,
   createTextInput,
   createSelectInput
-} from "@webiny/website-builder-nextjs";
+} from "@webiny/sdk-nextjs";
 
-createComponent(Banner, {
+createWbComponent(Banner, {
   name: "Custom/Banner",
   label: "Banner",
   inputs: [
@@ -260,7 +263,7 @@ createComponent(Banner, {
 
 Update the Banner component to use the `colorTheme` input:
 
-```tsx src/editorComponents/Banner.tsx
+```tsx editorComponents/Banner.tsx
 interface BannerInputs {
   headline: string;
   colorTheme: "primary" | "secondary" | "success";

docs/developer-docs/6.x/website-builder/how-it-works.ai.txt

@@ -36,7 +36,7 @@ Unique Website Builder Architecture:
 - Webiny stores ONLY page structure (which components + inputs)
 - Communication via postMessage API (handled by SDK)
 - Two modes: editing (live connection) and rendering (API fetch)
-- Current OOTB support: Next.js via @webiny/website-builder-nextjs
+- Current OOTB support: Next.js via @webiny/sdk-nextjs (6.5+; 6.4 used @webiny/website-builder-nextjs, which sdk-nextjs now wraps)
 - Future: Additional framework SDKs planned
 
 What Webiny Stores:
@@ -53,7 +53,7 @@ What User's App Owns:
 - Complete control over frontend stack
 
 SDK Responsibilities:
-- @webiny/website-builder-nextjs package
+- @webiny/sdk-nextjs package
 - Editor Integration: postMessage communication during editing
 - Page Fetching: API calls to fetch published pages
 - Component Registration: utilities to register components for editor
@@ -88,7 +88,7 @@ Related Documents:
 - core-concepts/webiny-sdk.mdx - General SDK concepts
 
 Key Code Locations (Webiny source):
-- packages/website-builder-nextjs/ - Next.js SDK implementation
+- packages/sdk-nextjs/ - Next.js SDK entry point (wraps packages/website-builder-nextjs/ and packages/cms-nextjs/)
 - packages/api-website-builder/ - Backend API for page storage
 - packages/admin/src/website-builder/ - Editor UI in Admin
 

docs/developer-docs/6.x/website-builder/how-it-works.mdx

@@ -20,7 +20,7 @@ import webinyWebsiteBuilder from "./assets/webiny-website-builder.png";
 
 The Website Builder uses a unique architecture that separates content management from presentation. The editor runs in Webiny Admin and connects to your frontend app via an iframe. Your app owns all components and styles—Webiny only stores the page structure.
 
-Webiny currently provides out-of-the-box support for Next.js through the `@webiny/website-builder-nextjs` SDK. Support for additional frameworks is planned for future releases.
+Webiny currently provides out-of-the-box support for Next.js through the `@webiny/sdk-nextjs` SDK. Support for additional frameworks is planned for future releases.
 
 This approach ensures genuine WYSIWYG editing, no style conflicts, and full control over your frontend code.
 
@@ -35,7 +35,7 @@ The Website Builder consists of two separate parts:
   alt="Website Builder editor interface showing component palette, canvas, and inputs sidebar"
 />
 
-**Your Frontend App** - Your frontend application with the Website Builder SDK installed. Currently, Webiny provides the `@webiny/website-builder-nextjs` SDK for Next.js out-of-the-box. Your app contains all component code, styles, and rendering logic.
+**Your Frontend App** - Your frontend application with the Website Builder SDK installed. Currently, Webiny provides the `@webiny/sdk-nextjs` SDK for Next.js out-of-the-box. Your app contains all component code, styles, and rendering logic.
 
 ### How They Connect
 
@@ -118,7 +118,7 @@ The Website Builder SDK provides:
 
 **Rendering Utilities** - Helps render page components with the correct inputs and layout.
 
-Webiny currently provides the `@webiny/website-builder-nextjs` SDK for Next.js. The SDK is a thin layer that connects your app to Webiny without imposing constraints on your architecture.
+Webiny currently provides the `@webiny/sdk-nextjs` SDK for Next.js. The SDK is a thin layer that connects your app to Webiny without imposing constraints on your architecture.
 
 <Alert type="warning" title="Shared Runtime Environments Not Supported">
 

docs/developer-docs/6.x/website-builder/setup-nextjs.ai.txt

@@ -1,51 +1,48 @@
 AI Context: Setup Next.js Project (website-builder/setup-nextjs.mdx)
 
 Source of Information:
-1. /Users/adrian/dev/lw/content/lessons/website-builder/setting-up-website-builder.mdx - Learn Webiny lesson
-2. Website Builder Next.js starter kit documentation
-3. @webiny/website-builder-nextjs SDK documentation
+1. /Users/adrian/dev/lw/content/lessons/website-builder/setting-up-website-builder.mdx - Learn Webiny lesson (original basis)
+2. github.com/webiny/website-builder-nextjs, `starter-kit-6.5.x` branch - 6.5 starter kit
+3. webiny-js `release/6.5.0`: packages/sdk-nextjs, packages/frontend-settings (Configure Frontend dialog), packages/api-website-builder (NextjsConfig, ApiKeyInstaller)
 
 Key Documentation Decisions:
-1. Removed ChapterOverview component (Learn Webiny-specific)
-2. Removed Quiz component (Learn Webiny-specific)
-3. Removed course-style language ("In this lesson we'll...")
-4. Simplified Overview - now focuses on setup, not architecture explanation
-5. Added link to how-it-works.mdx for architecture explanation
-6. Removed redundant Architecture section (covered in how-it-works)
-7. Removed ASCII diagram - kept prose explanation where needed
-8. Removed step numbering in headings - used descriptive section names instead
-9. Removed images/screenshots - will add if needed later
-10. Changed "Step X" headings to descriptive names (Installation, Configuration, etc.)
-11. Removed detailed project structure FileTree - kept brief description
-12. Removed "See It Rendered" as separate section - integrated into "Create Your First Page"
-13. Kept all technical accuracy about SDK, API keys, environment variables
+1. Removed ChapterOverview and Quiz components (Learn Webiny-specific) and course-style language
+2. Overview focuses on setup. Architecture lives in how-it-works.mdx
+3. 6.5 rewrite: single `@webiny/sdk-nextjs` package, `NEXT_PUBLIC_WEBINY_*` env vars, root-level project layout
+4. 6.5 rewrite: clone uses `--branch starter-kit-6.5.x`, because each minor version has its own kit branch. Update the branch name for future minors.
+5. 6.5 rewrite: the kit's package.json doesn't list the SDK, so the page has an explicit `yarn add @webiny/sdk-nextjs@~6.5.0` step. Yarn because the kit ships a yarn.lock. The peer pins that made npm fail with ERESOLVE on 6.5.0-beta.0 were fixed in webiny-js #5776 (verified: plain `npm install` works on 6.5.0-beta.1), so the old peer-warning alert was removed.
+6. 6.5 rewrite: removed the configure-nextjs-menu, configure-nextjs-dialog and api-key-auto-created screenshots. They showed the old Support > Configure Next.js menu, the old env var names, and the old "Website Builder" key. Add new screenshots of Dev Tools > Configure Frontend and the "Frontend Integration" key when available.
+7. Upgrade and existing-app scenarios live in release-notes/6.5.0/upgrade-nextjs-frontend.mdx, next to the 6.5.0 upgrade guide. This page links there instead of covering them.
 
 Understanding Website Builder Setup:
-- Editor loads Next.js app in iframe during editing
-- Components and styles live entirely in Next.js project
+- Editor loads the Next.js app in an iframe during editing
+- Components and styles live entirely in the Next.js project
 - Webiny stores only page structure and component inputs
-- @webiny/website-builder-nextjs SDK handles editor ↔ app communication
-- Starter kit at github.com/webiny/website-builder-nextjs
-- SDK versions must match Webiny version
-- Three env vars needed: API_KEY, API_HOST, API_TENANT
-- API key auto-created by Website Builder (read-only)
-- Configure Next.js dialog in Admin provides all credentials
-- Catch-all route [[...slug]]/page.tsx renders all pages
+- @webiny/sdk-nextjs handles editor <-> app communication, page fetching, CMS content, and CMS live preview
+- SDK minor version must match the Webiny version
+- Env vars: NEXT_PUBLIC_WEBINY_API_KEY, _API_HOST, _API_TENANT, optional _ADMIN_HOST (used in the frame-ancestors CSP header)
+- Configure Frontend dialog (Dev Tools menu): Frontend Domain field (used by the WB editor and CMS live preview) plus a Next.js tab with env vars
+- "Frontend Integration" API key is auto-created per tenant, read-only (WB, CMS, languages)
+- Upgraded projects have the legacy "Website Builder" key. The dialog then shows NEXT_PUBLIC_WEBSITE_BUILDER_* names.
+- Catch-all route app/(site)/[[...slug]]/page.tsx renders pages
+- app/(site)/articles/ is a CMS rendering and live preview example
 - Preview API route enables draft mode for unpublished pages
 
 Related Documents:
 - website-builder/how-it-works.mdx - Architecture explanation (prerequisite reading)
+- release-notes/6.5.0/upgrade-nextjs-frontend.mdx - Upgrading 6.4 kits, adding the SDK to existing apps
 - website-builder/theme.mdx - Theme configuration (next step)
 - website-builder/custom-component.mdx - Creating components (next step)
+- headless-cms/live-preview.mdx - CMS live preview
 
 Key Code Locations:
-- github.com/webiny/website-builder-nextjs - Official starter kit
-- src/app/[[...slug]]/page.tsx - Page rendering
-- src/editorComponents/ - Component registration
-- src/contentSdk/ - SDK initialization
+- github.com/webiny/website-builder-nextjs/tree/starter-kit-6.5.x - Official starter kit
+- app/(site)/[[...slug]]/page.tsx - Page rendering
+- editorComponents/ - Component registration
+- sdk/ - SDK initialization
 
 Tone Guidelines:
-- Technical and practical - setup guide format
+- Technical and practical, setup guide format
 - Direct instructions without unnecessary narrative
 - Keep "Prerequisites" and "Next Steps" sections
 - Use code blocks for all commands and config