@cmssy/cli 11.6.0 → 11.8.0

package/assets/init/astro/src/cmssy/editor.tsx

@@ -1,9 +1,6 @@
 "use client";
 import { CmssyLazyEditor } from "@cmssy/react/client";
 
-// The edit bridge is a client island: the editor talks to the page over
-// postMessage, and that protocol lives in @cmssy/core - not in React and not in
-// Next. That is why the same bridge works here.
 export default function CmssyEditor(props: Record<string, unknown>) {
   return <CmssyLazyEditor {...(props as never)} load={() => import("./blocks")} />;
 }

package/assets/init/astro/src/cmssy/hero.tsx

@@ -1,7 +1,5 @@
 import { fields, type BlockProps } from "@cmssy/react";
 
-// The schema lives next to the component that reads it, and types it. Rename a
-// field here and this file stops compiling - it cannot render an empty block.
 export const heroProps = {
   title: fields.text({ label: "Title", required: true }),
   subtitle: fields.text({ label: "Subtitle" }),

package/assets/init/astro/src/cmssy/layout-slot.tsx

@@ -13,27 +13,11 @@ export interface LayoutSlotProps {
   locale: string;
   defaultLocale: string;
   enabledLocales: string[];
-  /** Set on a VERIFIED editor request; the loader reports it as `isEdit`. */
   edit?: { editorOrigin: string | string[] };
-  /**
-   * The editor's block data, both halves, straight from the loader. Without
-   * `resolvedContent` the canvas shows a relation field as the raw ids it
-   * stores - the site looks right and the editor cannot fill the header.
-   */
   data?: Record<string, unknown>;
   resolvedContent?: Record<string, Record<string, unknown>>;
 }
 
-/**
- * The header and footer, which are layout blocks rather than markup you own.
- *
- * A React island: Astro renders it on the server for visitors (no client JS),
- * and with `client:load` on the edit route, where the bridge needs the browser.
- *
- * Two renders, one per mode, and the difference is the point: server-rendered
- * for visitors, and through the edit bridge for the editor. A header still
- * server-rendered in edit mode is one the editor can select and cannot fill.
- */
 export default function LayoutSlot({
   groups,
   position,

package/assets/init/astro/src/cmssy.config.ts

@@ -1,7 +1,5 @@
 import { defineCmssyConfig } from "@cmssy/astro";
 
-// Pass the env raw: a `?? ""` fallback turns a missing variable into an empty
-// one, and the error then surfaces somewhere unrelated.
 export const cmssy = defineCmssyConfig({
   org: process.env.CMSSY_ORG_SLUG,
   workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,

package/assets/init/astro/src/components/Blocks.tsx

@@ -2,10 +2,6 @@ import { CmssyBlock, buildBlockMap, buildBlockContext } from "@cmssy/react";
 import type { CmssyPageData } from "@cmssy/core";
 import { blocks } from "../cmssy/blocks";
 
-/**
- * The public page: React blocks rendered on the server by Astro, with no client
- * JS at all. The visitor gets HTML; the framework stays out of the render path.
- */
 export function Blocks({
   page,
   locale,

package/assets/init/astro/src/middleware.ts

@@ -1,6 +1,4 @@
 import { cmssyMiddleware } from "@cmssy/astro";
 import { cmssy } from "./cmssy.config";
 
-// The whole adapter. It resolves the language, routes a verified editor request
-// to /cmssy-edit, and applies the CSP that lets the admin frame this site.
 export const onRequest = cmssyMiddleware(cmssy);

package/assets/init/astro/src/pages/[...path].astro

@@ -7,8 +7,6 @@ import LayoutSlot from "../cmssy/layout-slot";
 
 export const prerender = false;
 
-// `blocks` is what lets the loader resolve the editor's layout data. Drop it
-// and the site still renders - the editor just cannot fill the header.
 const { page, layouts, locale, defaultLocale, enabledLocales } = await loadCmssyPage(
   cmssy,
   Astro.request,

package/assets/init/astro/src/pages/cmssy-edit/[...path].astro

@@ -5,12 +5,8 @@ import { blocks } from "../../cmssy/blocks";
 import CmssyEditor from "../../cmssy/editor";
 import LayoutSlot from "../../cmssy/layout-slot";
 
-// The editor iframe lands here (the middleware rewrites verified requests). It
-// must be dynamic: a prerendered page never sees the query string.
 export const prerender = false;
 
-// `blocks` is what resolves the editor's layout data. Without it the editor
-// can select the header and not fill it, and a relation field shows raw ids.
 const { page, layouts, locale, defaultLocale, enabledLocales, editorData } =
   await loadCmssyPage(cmssy, Astro.request, Astro.url, { blocks });
 const editorOrigin = resolveEditorOrigin(cmssy.editorOrigin);

package/assets/init/next/app/[[...path]]/page.tsx

@@ -10,11 +10,6 @@ type PageProps = {
   searchParams: Promise<Record<string, string | string[] | undefined>>;
 };
 
-// Three lines that decide whether this site is cached at all. Without
-// generateStaticParams a catch-all is rendered on demand every time and
-// `revalidate` is ignored - the build prints a blank Revalidate column, which is
-// the only warning you get. `dynamicParams` keeps pages published after the
-// build working: first request renders them, and they cache from then on.
 export const revalidate = 3600;
 export const dynamicParams = true;
 
@@ -24,10 +19,6 @@ export function generateStaticParams() {
 
 const CmssyPage = createCmssyPage(cmssy, blocks, { editor: CmssyEditor });
 
-// The header and footer are layout blocks. They are mounted here rather than in
-// app/layout.tsx because this route knows its path, and the language prefix in
-// that path is what says which language to render them in - reading it from the
-// request header instead would make every page dynamic.
 export default async function Page(props: PageProps) {
   const { path } = await props.params;
   const slot = (position: "header" | "footer") => (

package/assets/init/next/app/cmssy-edit/[[...path]]/page.tsx

@@ -8,11 +8,6 @@ import { blocks } from "@/cmssy/blocks";
 import { CmssyEditor } from "@/cmssy/editor";
 import { EditableLayout } from "@/cmssy/editable-layout";
 
-// The route the middleware rewrites a verified editor request onto. The public
-// pages stay static, and a static page never sees the query string that would
-// put it in edit mode - which is why the editor needs a route of its own.
-//
-// Delete this file and the editor preview goes blank.
 export const dynamic = "force-dynamic";
 
 type PageProps = {
@@ -24,15 +19,9 @@ const CmssyEditPage = createCmssyEditPage(cmssy, blocks, {
   editor: CmssyEditor,
 });
 
-// The same chrome the public route renders - the editor frames THIS page, so a
-// header missing here is a header missing in the editor.
 export default async function EditPage(props: PageProps) {
   const { path } = await props.params;
 
-  // Not a hard `true`: this route is reachable directly, and only the proxy's
-  // verified rewrite sets the edit header. Hard-coding it would fetch layouts
-  // with the draft secret for anyone who typed the URL. Reading a header costs
-  // nothing here - the route is force-dynamic either way.
   const editMode = await isCmssyEditMode();
 
   const slot = (position: "header" | "footer") => (

package/assets/init/next/blocks/hero/Hero.tsx

@@ -1,7 +1,5 @@
 import { fields, type BlockProps } from "@cmssy/react";
 
-// The schema lives next to the component that reads it, and types it. Rename a
-// field here and this file stops compiling - it cannot render an empty block.
 export const heroProps = {
   heading: fields.text({ label: "Heading", required: true }),
   text: fields.textarea({ label: "Text" }),

package/assets/init/next/blocks/hero/block.ts

@@ -6,12 +6,4 @@ export const heroBlock = defineBlock({
   label: "Hero",
   component: Hero,
   props: heroProps,
-  // A loader runs SERVER-SIDE before the block renders, so a block can read data
-  // (products, posts) the same way a page can. Import it dynamically: it may
-  // touch the cmssy config, which must never reach the browser.
-  //
-  // loader: async () => {
-  //   const { loadPosts } = await import("./load-posts");
-  //   return { posts: await loadPosts() };
-  // },
 });

package/assets/init/next/cmssy/blocks.ts

@@ -1,5 +1,3 @@
 import { heroBlock } from "@/blocks/hero/block";
 
-// Every block your app renders. The editor loads this list lazily; the server
-// renders from it directly.
 export const blocks = [heroBlock];

package/assets/init/next/cmssy/editable-layout.tsx

@@ -5,8 +5,6 @@ import {
   type CmssyLazyLayoutProps,
 } from "@cmssy/react/client";
 
-// Mounts the layout blocks through the edit bridge, so the header and the footer
-// are editable in the editor rather than markup it can select and cannot fill.
 export function EditableLayout(props: Omit<CmssyLazyLayoutProps, "load">) {
   return <CmssyLazyLayout {...props} load={() => import("./blocks")} />;
 }

package/assets/init/next/cmssy/editor.tsx

@@ -3,8 +3,6 @@
 import { CmssyLazyEditor } from "@cmssy/react/client";
 import type { CmssyEditorProps } from "@cmssy/next";
 
-// The block registry is loaded lazily ON THE CLIENT, so block loaders - which
-// run server-side and read the config - never reach the browser bundle.
 export function CmssyEditor(props: CmssyEditorProps) {
   return <CmssyLazyEditor {...props} load={() => import("./blocks")} />;
 }

package/assets/init/next/cmssy.config.ts

@@ -1,12 +1,5 @@
 import { defineCmssyConfig } from "@cmssy/next";
 
-// Pass process.env raw: defineCmssyConfig validates at startup and names any
-// variable you are missing. A `?? ""` fallback would hide that, and the error
-// would surface later, somewhere unrelated.
-//
-// This module reads server env. Never import a VALUE from it (or from a module
-// that imports it) in a "use client" component - types are erased, values drag
-// process.env into the browser bundle.
 export const cmssy = defineCmssyConfig({
   org: process.env.CMSSY_ORG_SLUG,
   workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,

package/assets/init/next/proxy.ts

@@ -1,13 +1,8 @@
 import { createCmssyProxy } from "@cmssy/next/middleware";
 import { cmssy } from "@/cmssy.config";
 
-// Resolves the language, sends verified editor traffic to /cmssy-edit (carrying
-// that language and the edit flag), and lets the cmssy admin frame this site.
-// The order matters, which is why it lives in the preset and not here.
 export const proxy = createCmssyProxy(cmssy);
 
-// Next parses this at compile time, so the matcher has to be a literal - an
-// imported constant is rejected. Skips Next internals, API routes and files.
 export const config = {
   matcher: ["/((?!_next/|api/|.*\\..*).*)"],
 };

package/assets/init/next/services/pages.ts

@@ -1,9 +1,6 @@
 import { createCmssyClient } from "@cmssy/core";
 import { cmssy } from "@/cmssy.config";
 
-// Your query, in your repo. The SDK does not mirror the graph - it gives you a
-// client and gets out of the way, so adding a field here is your call and not a
-// release of ours.
 const PUBLISHED_PAGES = `query PublishedPages($workspaceSlug: String!) {
   public {
     page {
@@ -27,24 +24,12 @@ const client = createCmssyClient({
   workspaceSlug: cmssy.workspaceSlug,
 });
 
-/**
- * The paths to prerender, as `generateStaticParams` wants them.
- *
- * A catch-all route with no params generated is served on demand and cached by
- * nothing, whatever `revalidate` says - so this function is what makes the
- * route cacheable at all, not an optimisation on top of it.
- */
 export async function publishedPaths(): Promise<{ path: string[] }[]> {
   const data = await client.query<PublishedPages>(
     PUBLISHED_PAGES,
     { workspaceSlug: cmssy.workspaceSlug },
     {
-      // `public` routes through the org-scoped delivery path. Without it the
-      // request lands on the base endpoint, where an unauthenticated workspace
-      // lookup is by slug alone - across every org.
       public: true,
-      // A build reads this once. A single 429 from the delivery API would fail
-      // the whole deploy, so retry - it is a read, nothing to double-apply.
       retry: {},
     },
   );

package/assets/init/remix/app/cmssy/editor.tsx

@@ -1,8 +1,6 @@
 import { CmssyLazyEditor } from "@cmssy/react/client";
 import type { CmssyPageData } from "@cmssy/core";
 
-// The edit bridge: the editor talks to the page over postMessage, and that
-// protocol lives in @cmssy/core - not in React and not in a framework.
 export function CmssyEditor(props: {
   page: CmssyPageData | null;
   locale: string;

package/assets/init/remix/app/cmssy/hero.tsx

@@ -1,7 +1,5 @@
 import { fields, type BlockProps } from "@cmssy/react";
 
-// The schema lives next to the component that reads it, and types it. Rename a
-// field here and this file stops compiling - it cannot render an empty block.
 export const heroProps = {
   title: fields.text({ label: "Title", required: true }),
   subtitle: fields.text({ label: "Subtitle" }),

package/assets/init/remix/app/cmssy/layout-slot.tsx

@@ -13,24 +13,11 @@ export interface LayoutSlotProps {
   locale: string;
   defaultLocale: string;
   enabledLocales: string[];
-  /** Set on a VERIFIED editor request; the loader reports it as `isEdit`. */
   edit?: { editorOrigin: string | string[] };
-  /**
-   * The editor's block data, both halves, straight from the loader. Without
-   * `resolvedContent` the canvas shows a relation field as the raw ids it
-   * stores - the site looks right and the editor cannot fill the header.
-   */
   data?: Record<string, unknown>;
   resolvedContent?: Record<string, Record<string, unknown>>;
 }
 
-/**
- * The header and footer, which are layout blocks rather than markup you own.
- *
- * Two renders, one per mode, and the difference is the point: server-rendered
- * for visitors, and through the edit bridge for the editor. A header still
- * server-rendered in edit mode is one the editor can select and cannot fill.
- */
 export function LayoutSlot({
   groups,
   position,

package/assets/init/remix/app/routes/page.tsx

@@ -6,12 +6,8 @@ import { CmssyEditor } from "../cmssy/editor";
 import { LayoutSlot } from "../cmssy/layout-slot";
 import type { Route } from "./+types/page";
 
-// `blocks` is what lets the loader resolve the editor's layout data. Drop it
-// and the site still renders - the editor just cannot fill the header.
 export const loader = createCmssyLoader(cmssy, { blocks });
 
-// Without these the admin cannot frame the site, and the editor shows an empty
-// box with no error anywhere.
 export const headers = createCmssyHeaders(cmssy);
 
 export default function CmssyPage({ loaderData }: Route.ComponentProps) {
@@ -31,8 +27,6 @@ export default function CmssyPage({ loaderData }: Route.ComponentProps) {
     return <div dangerouslySetInnerHTML={{ __html: diagnostics }} />;
   }
 
-  // A verified editor request renders the same page through the edit bridge.
-  // No separate route: a React Router page always sees its query string.
   const slot = (position: "header" | "footer") => (
     <LayoutSlot
       groups={layouts}

package/assets/init/remix/app/routes.ts

@@ -1,7 +1,5 @@
 import { type RouteConfig, index, route } from "@react-router/dev/routes";
 
-// The splat does not match "/", so the homepage needs its own entry - it is the
-// same route module, mounted twice.
 export default [
   index("routes/page.tsx"),
   route("*", "routes/page.tsx", { id: "cmssy-catch-all" }),

package/assets/init/remix/cmssy.config.ts

@@ -1,7 +1,5 @@
 import { defineCmssyConfig } from "@cmssy/remix";
 
-// Pass the env raw: a `?? ""` fallback turns a missing variable into an empty
-// one, and the error then surfaces somewhere unrelated.
 export const cmssy = defineCmssyConfig({
   org: process.env.CMSSY_ORG_SLUG,
   workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,

package/dist/index.js

@@ -163,19 +163,63 @@ var FRAMEWORKS = [
     detect: ["next"],
     dependencies: ["@cmssy/next", "@cmssy/react", "@cmssy/core"],
     files: [
-      "cmssy.config.ts",
-      "proxy.ts",
-      "services/pages.ts",
-      "cmssy/blocks.ts",
-      "cmssy/editor.tsx",
-      "cmssy/editable-layout.tsx",
-      "blocks/hero/block.ts",
-      "blocks/hero/Hero.tsx",
-      "app/[[...path]]/layout.tsx",
-      "app/[[...path]]/page.tsx",
-      "app/cmssy-edit/[[...path]]/layout.tsx",
-      "app/cmssy-edit/[[...path]]/page.tsx",
-      "app/api/draft/route.ts"
+      {
+        path: "cmssy.config.ts",
+        purpose: "reads server env and validates it at startup; server-only, never import a value from it in a client component"
+      },
+      {
+        path: "proxy.ts",
+        purpose: "resolves the language, rewrites verified editor traffic to /cmssy-edit, lets the admin frame the site; its matcher must stay a literal"
+      },
+      {
+        path: "services/pages.ts",
+        purpose: "your delivery queries, in your repo; generateStaticParams lives here and is what makes the catch-all cacheable at all"
+      },
+      {
+        path: "cmssy/blocks.ts",
+        purpose: "every block the app renders - the server renders from this list, the editor loads it lazily"
+      },
+      {
+        path: "cmssy/editor.tsx",
+        purpose: "loads the block registry on the client, so server-side block loaders never reach the browser bundle"
+      },
+      {
+        path: "cmssy/editable-layout.tsx",
+        purpose: "mounts header and footer through the edit bridge; without it the editor can select them and cannot fill them"
+      },
+      {
+        path: "blocks/hero/block.ts",
+        purpose: "an example block: schema beside the component that reads it (loaders: docs/building-blocks/server-loaders.md)"
+      },
+      {
+        path: "blocks/hero/Hero.tsx",
+        purpose: "its component - renaming a schema field stops this compiling"
+      },
+      {
+        path: "app/[[...path]]/layout.tsx",
+        purpose: "the public root layout; <html lang> comes from the route, so put your global CSS and metadata here"
+      },
+      {
+        path: "app/[[...path]]/page.tsx",
+        purpose: "the public catch-all: generateStaticParams plus dynamicParams decide whether this site is cached at all"
+      },
+      {
+        path: "app/cmssy-edit/[[...path]]/layout.tsx",
+        purpose: "the editor's root layout - a separate root, so CSS and metadata have to be repeated here"
+      },
+      {
+        path: "app/cmssy-edit/[[...path]]/page.tsx",
+        purpose: "the route the proxy rewrites a verified editor request onto; delete it and the editor preview goes blank"
+      },
+      {
+        path: "app/api/draft/route.ts",
+        purpose: "draft preview without the editor - enters draft mode for a verified secret"
+      }
+    ],
+    warnings: [
+      'pass process.env values raw into defineCmssyConfig - a `?? ""` fallback turns a missing variable into an empty one and the error surfaces somewhere unrelated',
+      "the two root layouts are separate: global CSS or metadata added to one and not the other shows up as an editor preview with no styles",
+      "a page without generateStaticParams renders on demand and ignores revalidate; the build's blank Revalidate column is the only warning you get"
     ]
   },
   {
@@ -185,15 +229,46 @@ var FRAMEWORKS = [
     detect: ["astro"],
     dependencies: ["@cmssy/astro", "@cmssy/react", "@cmssy/core"],
     files: [
-      "src/cmssy.config.ts",
-      "src/middleware.ts",
-      "src/cmssy/blocks.ts",
-      "src/cmssy/editor.tsx",
-      "src/cmssy/layout-slot.tsx",
-      "src/cmssy/hero.tsx",
-      "src/components/Blocks.tsx",
-      "src/pages/[...path].astro",
-      "src/pages/cmssy-edit/[...path].astro"
+      {
+        path: "src/cmssy.config.ts",
+        purpose: "reads env and validates it at startup; pass the values raw so a missing one is named here"
+      },
+      {
+        path: "src/middleware.ts",
+        purpose: "the whole adapter: resolves the language, rewrites verified editor requests to /cmssy-edit, applies the framing CSP"
+      },
+      {
+        path: "src/cmssy/blocks.ts",
+        purpose: "every block the app renders"
+      },
+      {
+        path: "src/cmssy/editor.tsx",
+        purpose: "the edit bridge as a client island - the postMessage protocol lives in @cmssy/core, which is why it works outside React frameworks"
+      },
+      {
+        path: "src/cmssy/layout-slot.tsx",
+        purpose: "header and footer: server-rendered for visitors, through the edit bridge on the edit route; resolvedContent is what stops a relation field showing raw ids"
+      },
+      {
+        path: "src/cmssy/hero.tsx",
+        purpose: "an example block - schema beside the component that reads it"
+      },
+      {
+        path: "src/components/Blocks.tsx",
+        purpose: "renders React blocks on the server with no client JS - the visitor gets HTML"
+      },
+      {
+        path: "src/pages/[...path].astro",
+        purpose: "the public catch-all; its `blocks` prop is what lets the loader resolve the editor's layout data"
+      },
+      {
+        path: "src/pages/cmssy-edit/[...path].astro",
+        purpose: "where the editor iframe lands - must stay dynamic, because a prerendered page never sees the query string"
+      }
+    ],
+    warnings: [
+      'pass env values raw into defineCmssyConfig - a `?? ""` fallback hides a missing variable until it breaks somewhere unrelated',
+      "the `blocks` prop on both page routes is not decoration: without it the site still renders and the editor can select a header it cannot fill"
     ]
   },
   {
@@ -203,14 +278,42 @@ var FRAMEWORKS = [
     detect: ["react-router", "@react-router/dev", "@remix-run/react"],
     dependencies: ["@cmssy/remix", "@cmssy/react", "@cmssy/core"],
     files: [
-      "cmssy.config.ts",
-      "app/root.tsx",
-      "app/routes.ts",
-      "app/cmssy/blocks.ts",
-      "app/cmssy/editor.tsx",
-      "app/cmssy/layout-slot.tsx",
-      "app/cmssy/hero.tsx",
-      "app/routes/page.tsx"
+      {
+        path: "cmssy.config.ts",
+        purpose: "reads env and validates it at startup; pass the values raw so a missing one is named here"
+      },
+      {
+        path: "app/root.tsx",
+        purpose: "the root layout - <html lang> comes from useCmssyLocale(), so a prefixed URL declares the language it renders"
+      },
+      {
+        path: "app/routes.ts",
+        purpose: 'mounts the page module twice: the splat does not match "/", so the homepage needs its own entry'
+      },
+      {
+        path: "app/cmssy/blocks.ts",
+        purpose: "every block the app renders"
+      },
+      {
+        path: "app/cmssy/editor.tsx",
+        purpose: "the edit bridge - the postMessage protocol lives in @cmssy/core, not in the framework"
+      },
+      {
+        path: "app/cmssy/layout-slot.tsx",
+        purpose: "header and footer: server-rendered for visitors, through the edit bridge for the editor; resolvedContent is what stops a relation field showing raw ids"
+      },
+      {
+        path: "app/cmssy/hero.tsx",
+        purpose: "an example block - schema beside the component that reads it"
+      },
+      {
+        path: "app/routes/page.tsx",
+        purpose: "one route for both modes - a React Router page always sees its query string, so there is no separate edit route; its headers are what let the admin frame the site"
+      }
+    ],
+    warnings: [
+      'pass env values raw into defineCmssyConfig - a `?? ""` fallback hides a missing variable until it breaks somewhere unrelated',
+      "the route's `blocks` prop and its CSP headers are load-bearing: drop either and the site renders while the editor shows an empty box with no error"
     ]
   }
 ];
@@ -511,10 +614,15 @@ var CLI_PACKAGE_JSON = fileURLToPath(
 function frameworkFiles(framework, root) {
   const srcPrefix = framework.name === "next" ? nextSrcPrefix(root) : "";
   const files = [
-    { asset: "env.example", target: ".env.example" },
-    ...framework.files.map((path) => ({
+    {
+      asset: "env.example",
+      target: ".env.example",
+      purpose: "the variables the config reads - copy it to .env.local and fill them in"
+    },
+    ...framework.files.map(({ path, purpose }) => ({
       asset: path,
-      target: framework.name === "next" ? `${srcPrefix}${path}` : path
+      target: framework.name === "next" ? `${srcPrefix}${path}` : path,
+      purpose
     }))
   ];
   if (framework.name === "next" && existingFile(root, `${srcPrefix}app/layout`)) {
@@ -648,6 +756,7 @@ function runInit(options, deps) {
       copyFileSync(join3(ASSETS_DIR, framework.name, file.asset), target);
       written.push(file.target);
       log(formatResult({ status: "ok", message: `wrote ${file.target}` }));
+      log(`    ${file.purpose}`);
     }
     const added = addDependencies(root, pkg, framework);
     if (added.length > 0) {
@@ -666,6 +775,10 @@ function runInit(options, deps) {
       `${written.length} file${written.length === 1 ? "" : "s"} written, ${skipped.length} skipped.`
     );
     log("");
+    log("What not to break:");
+    for (const warning of framework.warnings) log(`  - ${warning}`);
+    log("  full wiring, and what each file is doing: docs/wiring.md");
+    log("");
     log("Next steps:");
     let step = 1;
     if (added.length > 0) log(`  ${step++}. ${detectInstallCommand(root)}`);
@@ -1237,8 +1350,6 @@ function generateOperationsFile() {
     ""
   ].join("\n");
   const documents = CMSSY_DELIVERY_OPERATIONS.map(
-    // A newline in `purpose` would emit bare prose into the document and break
-    // parsing for every consumer.
     (operation) => `# ${operation.purpose.replace(/\s+/g, " ").trim()}
 ${operation.document}`
   ).join("\n\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmssy/cli",
-  "version": "11.6.0",
+  "version": "11.8.0",
   "description": "The cmssy CLI: `cmssy init` wires cmssy into an existing Next.js, Astro or React Router app; `cmssy link` connects it to a workspace and verifies the editor wiring.",
   "keywords": [
     "cmssy",
@@ -27,7 +27,7 @@
     "assets"
   ],
   "dependencies": {
-    "@cmssy/core": "11.6.0"
+    "@cmssy/core": "11.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",