camox 0.42.0 → 0.44.0

package/skills/camox/references/cli-content.md

@@ -0,0 +1,158 @@
+# Managing Pages and Blocks with the Camox CLI
+
+Read [cli-common.md](cli-common.md) first for `{{CAMOX_CMD}}`, help verification, and draft-first rules.
+
+Use these commands for Pages, metadata, Layout assignments, Block instances and their Content, draft review, and publishing. To change Block schemas or rendering, read [Block Definitions](block-definitions.md); to create or change Layout Definitions, follow the code-definition routing in [the Camox skill](../SKILL.md).
+
+## Pages
+
+### Create a Page with an existing Layout
+
+```sh
+{{CAMOX_CMD}} layouts list
+{{CAMOX_CMD}} pages create --path-segment about --layout-id 39
+```
+
+Use `--parent-page-id <ID>` to nest the Page under another Page.
+
+### Read and edit SEO metadata
+
+```sh
+{{CAMOX_CMD}} pages get --path /about
+{{CAMOX_CMD}} pages update --path /about --meta-title "About us" --meta-description "Meet the team."
+{{CAMOX_CMD}} pages update --id 25 --meta-description ""
+{{CAMOX_CMD}} pages update --id 25 --ai-seo on
+{{CAMOX_CMD}} pages update --id 25 --ai-seo off
+```
+
+Updates accept exactly one of `--id` or `--path` and require at least one update
+field. Omitted fields are preserved; an empty string clears a metadata field.
+Setting either metadata field disables automatic SEO for both fields and cannot
+be combined with `--ai-seo on`. Disabling AI preserves current metadata; enabling
+it schedules asynchronous generation, so read the Page again to inspect results.
+
+Metadata edits affect only the draft, even with `--production`. Read published
+metadata with `pages get --live`; publish only after user approval.
+
+## Comments
+
+List a Page's comments, then use a returned comment `id` to resolve one on that same Page:
+
+```sh
+{{CAMOX_CMD}} comments list --page-id 25
+{{CAMOX_CMD}} comments resolve --page-id 25 --id <COMMENT_UUID>
+```
+
+`--page-id` is the numeric Page ID (find it with `pages get --path /about`); `--id` is the comment's UUID, not a Block or Page ID. Resolution changes the comment's status, not the Page's draft or published content. Check `comments resolve --help` before writing, per [CLI common guidance](cli-common.md). Use `--json` for structured output; `--project`, `--production`, and `--cwd` select the same project, environment, and working directory as other CLI commands.
+
+## Blocks
+
+### Inspect before changing
+
+Look up the Page before creating or moving Blocks so you have its `id`, current Blocks, and any sibling ids. Describe the Block type before constructing Content:
+
+```sh
+{{CAMOX_CMD}} pages get --path /
+{{CAMOX_CMD}} blocks describe --type hero
+```
+
+### Create and position a Block
+
+```sh
+{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}' --position first
+```
+
+Creation initializes omitted Content and Settings fields from the Block definition's defaults, including when `--content '{}'` is supplied. Explicit field values—including `""`, `null`, `false`, and `[]`—are preserved; defaults do not merge into a supplied Link object. Omitted Repeaters initialize their default item count (or minimum count) with item defaults; supplying an array uses exactly those items, and `[]` creates none. Asset placeholders are not stored. Existing synced Block data still takes precedence for synced types.
+
+Supply reference-specific copy, links, assets, and items directly as instance Content. Definition defaults should remain neutral, reusable examples—not a way to populate a reference site.
+
+`blocks create` and `blocks move` accept the same positioning flags. Pass at most one:
+
+| Flag                      | Meaning                                         |
+| ------------------------- | ----------------------------------------------- |
+| `--position first`        | Put the Block first.                            |
+| `--position last`         | Put the Block last; this is the create default. |
+| `--after-id <ID>`         | Put it immediately after a sibling Block.       |
+| `--before-id <ID>`        | Put it immediately before a sibling Block.      |
+| `--after-position <KEY>`  | Insert after a known fractional-index key.      |
+| `--before-position <KEY>` | Insert before a known fractional-index key.     |
+
+Prefer `--position`, `--after-id`, and `--before-id`. A move requires one positioning flag.
+
+### Edit Block Content
+
+Content patches merge ordinary fields, so send only fields that should change:
+
+```sh
+{{CAMOX_CMD}} pages get --path /pricing
+{{CAMOX_CMD}} blocks edit --id 314 --content '{"headline": "New headline"}'
+```
+
+### Edit repeatable Content safely
+
+A repeatable field's array is replacement-shaped: omitting an existing item deletes it and cascades to its file references, settings, and nested items. Fetch the Block, preserve every existing item with `_itemId`, and add changes only to the intended entries:
+
+```sh
+{{CAMOX_CMD}} blocks get --id 99
+
+{{CAMOX_CMD}} blocks edit --id 99 --content '{
+  "items": [
+    {"_itemId": 401},
+    {"_itemId": 402, "answer": "Updated answer."},
+    {"_itemId": 403}
+  ]
+}'
+```
+
+The response's `repeatableItems` contains each item's `id`, `fieldName`, `parentItemId`, and Content. Use the same `_itemId` pattern recursively for nested repeatables. Fetch multiple Blocks together when useful:
+
+```sh
+{{CAMOX_CMD}} blocks get-many --id 99 --id 100 --id 101
+```
+
+`blocks get-many` returns the same bundle shape as `blocks get`, in requested-id order.
+
+## Review and publishing
+
+For curated page-content blocks, publish or discard changes at the Page level. Layout-owned blocks use layout publishing; curated Page publishing includes its Layout by default, as described below. Singleton and derived routes have no curated Page record: use layout publishing, not `pages publish` (see [Routed layouts](routed-layouts.md)).
+
+### Review draft and live state
+
+```sh
+{{CAMOX_CMD}} pages get --path /pricing        # draft
+{{CAMOX_CMD}} pages get --path /pricing --live # published snapshot
+{{CAMOX_CMD}} blocks get --id 314              # draft
+{{CAMOX_CMD}} blocks get --id 314 --live       # published snapshot
+```
+
+Live reads fail when the Page or Block has never been published. `--live` is not a write target and does not publish anything.
+
+### Publish after approval
+
+```sh
+{{CAMOX_CMD}} pages publish --path /pricing
+```
+
+`pages publish` accepts exactly one of `--id` or `--path`. It publishes the Page's current draft and, by default, its Layout. Publishing the Layout is a no-op when it has no pending changes. Use `--no-layout` only when the user explicitly does not want pending Layout changes published with the Page:
+
+```sh
+{{CAMOX_CMD}} pages publish --path /pricing --no-layout
+```
+
+Publish only after the user asks or approves, not automatically after editing a draft.
+
+### Unpublish or discard drafts
+
+Remove a Page from live without deleting its draft:
+
+```sh
+{{CAMOX_CMD}} pages unpublish --path /pricing
+```
+
+Reset a draft to its current live snapshot without changing live:
+
+```sh
+{{CAMOX_CMD}} pages discard-changes --path /pricing
+```
+
+Both commands accept exactly one of `--id` or `--path`. Discarding fails if the Page has never been published.

package/skills/camox/references/cli-environments.md

@@ -1,6 +1,6 @@
 # Managing Environments with the Camox CLI
 
-Read [cli-common.md](cli-common.md) first. Replace `{{CAMOX_CMD}}` as described there and verify commands with `--help`.
+Read [cli-common.md](cli-common.md) first for `{{CAMOX_CMD}}`, help verification, and draft-first rules.
 
 Every Project has an isolated dev Environment for each developer and a shared production Environment. Each Environment independently contains draft and live sources.
 

package/skills/camox/references/dom-integrations.md

@@ -0,0 +1,93 @@
+# DOM integrations in preview and published pages
+
+Use this reference for block DOM listeners, scrolling, browser scripts, and third-party widgets. It can be read independently of [Block Definitions](block-definitions.md); read that reference only if also changing the block schema or field rendering API.
+
+**Do not use component-global `window` or `document` to target a block's DOM.** Camox preview (including block thumbnails) renders blocks into an iframe through a React portal, but component code executes in the editor's JavaScript realm. Global scroll listeners observe the editor; scripts appended to the global document load there instead of beside your block.
+
+Use `getElementContext` from `camox/dom` inside an effect or event handler, passing a rendered element. It returns `{ window, document }` from the element's `ownerDocument` and `defaultView`, or `null` for a missing element or a document without a window. It never falls back to globals, requires no provider, and works in regular rendering too. Don't access DOM APIs during SSR.
+
+## Scroll listeners
+
+```tsx
+import { getElementContext } from "camox/dom";
+import { useEffect, useRef, useState } from "react";
+
+function Header() {
+  const root = useRef<HTMLElement>(null);
+  const [scrolled, setScrolled] = useState(false);
+
+  useEffect(() => {
+    const context = getElementContext(root.current);
+    if (!context) return;
+
+    const { window } = context;
+    const onScroll = () => setScrolled(window.scrollY > 40);
+    onScroll();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, []);
+
+  return (
+    <header ref={root} data-scrolled={scrolled}>
+      Navigation
+    </header>
+  );
+}
+```
+
+Read viewport dimensions, query elements, and attach resize listeners through the same context. If the root is conditionally mounted or replaced, rerun setup for the new element (for example, store it using a callback ref and include it in the effect dependencies).
+
+## Third-party scripts and widgets
+
+Resolve context from the widget container, create scripts with `context.document.createElement("script")`, and append them to `context.document.head`. Initialize the SDK exposed on `context.window`, not the editor global. Deduplicate script loading **per document**, not with one module-global promise: preview, thumbnails, and the ordinary page can each have their own SDK instance.
+
+For example, a script loader owned by your integration can use:
+
+```ts
+const loads = new WeakMap<Document, Map<string, Promise<void>>>();
+
+function loadScript(document: Document, src: string): Promise<void> {
+  let scripts = loads.get(document);
+  if (!scripts) {
+    scripts = new Map();
+    loads.set(document, scripts);
+  }
+  const existing = scripts.get(src);
+  if (existing) return existing;
+
+  const script = document.createElement("script");
+  script.src = src;
+  script.async = true;
+  const loaded = new Promise<void>((resolve, reject) => {
+    script.onload = () => resolve();
+    script.onerror = () => {
+      scripts.delete(src);
+      script.remove();
+      reject(new Error(`Failed to load ${src}`));
+    };
+  });
+  scripts.set(src, loaded);
+  document.head.appendChild(script);
+  return loaded;
+}
+```
+
+In the component's effect, await loading before initializing the widget against the rendered container. Handle load errors, ignore completion after cleanup, and destroy the widget instance on unmount using its SDK's teardown API. Keep a shared script when other blocks may still use it. Avoid duplicate initialization across remounts and React Strict Mode.
+
+**Resolving the right window does not move your JavaScript objects into its realm.** Some SDKs use `instanceof Object` or similar constructor checks. Cal, for example, can reject configuration created by the editor even when its script loaded in the correct iframe. For JSON-compatible configuration only, construct a target-realm copy:
+
+```ts
+const context = getElementContext(root.current);
+if (!context) return;
+
+const config = context.window.JSON.parse(
+  JSON.stringify({
+    layout: "month_view",
+    useSlotsViewOnSmallScreen: "true",
+    theme: "dark",
+  }),
+);
+// Pass config to the Cal instance loaded on context.window.
+```
+
+This is not a general cloning solution: functions, DOM nodes, SDK instances, circular structures, and other non-JSON values need SDK-specific handling. Libraries that capture globals at import time are not automatically fixed by this helper. Test DOM integrations in both authenticated preview and regular page rendering.

package/skills/camox/references/field-styling.md

@@ -0,0 +1,50 @@
+# Inline field formatting and styling
+
+Use this reference to customize inline text, links, and highlights on an existing `block.Field` or `item.Field`. Read [Block Definitions](block-definitions.md) only if also changing the block schema or other field rendering APIs.
+
+## String formatting
+
+String fields support inline formatting in both editing and published output: `**bold**`, `*italic*` (or `_italic_`), `***bold italic***`, `<s>strikethrough</s>`, `<highlight>highlight text</highlight>`, and text links like `[label](https://example.com)` or internal page links inserted by the editor. Highlight can contain other formatting, links, and line breaks. Content remains a string. The editor uses explicit `<strong>` and `<em>` tags when Markdown delimiters cannot represent a selection losslessly (for example, formatting that includes leading/trailing whitespace). These are built-in formatting tags, not arbitrary HTML.
+
+## Rendering and appearance
+
+Spread the field's render-prop `props` onto the element to preserve inline editing. `props.children` contains the rendered content:
+
+```tsx
+<myBlock.Field name="title">{(props) => <h1 {...props} />}</myBlock.Field>
+```
+
+Camox owns inline markup so editing and published output have the same appearance. Customize appearance with `textStyle` and `linkStyle` (these replace the old `components` prop):
+
+```tsx
+<myBlock.Field
+  name="description"
+  textStyle={({ bold, italic, highlight }) => {
+    if (highlight) {
+      return {
+        style: {
+          backgroundImage: "linear-gradient(to right, orange, deeppink)",
+          backgroundClip: "text",
+          WebkitBackgroundClip: "text",
+          WebkitTextFillColor: "transparent",
+        },
+      };
+    }
+    return {
+      className: bold ? "text-primary" : undefined,
+      style: bold && italic ? { letterSpacing: "0.02em" } : undefined,
+    };
+  }}
+  linkStyle={({ external }) => ({
+    className: external ? "text-blue-600" : "text-primary font-medium",
+  })}
+>
+  {(props) => <p {...props} />}
+</myBlock.Field>
+```
+
+- `textStyle` receives `{ bold, italic, strikethrough, highlight }` and returns `{ className?, style? }` or `undefined`. For text runs, `highlight` is false and the other flags describe explicit content formatting, not inherited heading styles. Unmarked text keeps its parent's typography.
+- `linkStyle` receives `{ target, href, external, pageId }` and returns the same appearance-only object. Links are underlined by default; override `style.textDecorationLine` to change that.
+- Camox also calls `textStyle` once for each shared highlight wrapper with `{ highlight: true, bold: false, italic: false, strikethrough: false }`. That result styles the whole range; its children receive their own text-run calls. `highlight` identifies the wrapper being styled, not whether a run is inside a highlight. This keeps one continuous background when bold/italic formatting changes within the range. Highlights default to the site's `--primary` text color, falling back to `currentColor`. Return a custom `style.color` to change it, or use a clipped background with transparent text fill to render a gradient, as shown above.
+- Styles apply to inline children; the outer element's `className` stays on that element and is inherited normally. Explicit formatting defaults (combined italic, strikethrough, highlight color) use inline styles; use `style` to override those defaults rather than competing utility classes.
+- These props accept appearance only, never replacement elements, children, or event handlers. They also work on `item.Field` inside repeaters. The sidebar editor shows default formatting; field-specific styles apply on the page.

package/skills/camox/references/layout-definitions.md

@@ -1,14 +1,14 @@
-# Creating Camox Layout Definitions
+# Creating Camox Curated Layout Definitions
 
-A layout wraps pages in shared structure — a navbar at the top, a footer at the bottom, consistent styling. Each page in the CMS is assigned a layout. This skill covers creating layout **definitions** — the template that describes which blocks surround page content and how to render them.
+A curated layout (`kind: "curated"`, the default) is a reusable shell for editor-created pages, with before/after blocks and page-content `children`. For code-owned singleton pages or derived routes, read [Routed layouts](routed-layouts.md) instead.
 
-## After defining the layout: assign it when requested
+All editable content lives in blocks; layouts have no editable `content` schema or `.Field` helpers.
 
-A definition only adds a new Layout to the catalog — it doesn't apply it to any Page, and existing Pages keep their current Layout. If the user wanted "the about Page to use the new marketing Layout" or "all docs Pages to use this Layout", follow the umbrella skill's CLI routing to update the relevant Pages after the dev server has picked up the definition. Don't stop after the definition unless the user explicitly requested only a reusable Layout Definition.
+Defining a layout does not assign it to existing Pages. When assignment is requested, wait for dev-server discovery, then follow the [CLI workflow](../SKILL.md#content-and-cli).
 
 ## Quick Start
 
-A layout file lives in the app's `src/layouts/` folder, is a `.tsx` file, and exports `layout`:
+Use one `.tsx` file per layout in `src/layouts/`, a named `layout` or `Layout` export (not default), a named function component, and Tailwind styling.
 
 ```tsx
 import { createLayout } from "camox/createLayout";
@@ -17,13 +17,13 @@ import { block as footerBlock } from "../blocks/footer";
 import { block as heroBlock } from "../blocks/hero";
 
 const myLayout = createLayout({
-  id: "my-layout", // Must match filename (kebab-case)
-  title: "My Layout", // Human-readable name
-  description: "When to use this layout",
+  id: "my-layout",
+  title: "My Layout",
+  description: "Marketing pages with shared navigation and footer.",
   blocks: {
-    before: [navbarBlock], // Blocks rendered before page content
-    after: [footerBlock], // Blocks rendered after page content
-    initial: [heroBlock], // Blocks to pre-populate on the homepage
+    before: [navbarBlock],
+    after: [footerBlock],
+    initial: [heroBlock],
   },
   component: MyLayoutComponent,
   buildMetaTitle: ({ pageMetaTitle, projectName }) => `${pageMetaTitle} | ${projectName}`,
@@ -44,115 +44,33 @@ export { myLayout as layout };
 
 ## The `createLayout` options
 
-| Option           | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`             | yes      | Unique kebab-case identifier. Must match the filename without extension.                                                                                                                                                                                                                                                                                                                                                          |
-| `title`          | yes      | Display name shown in the CMS UI.                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `description`    | yes      | Tells the CMS user (or AI agent) when to pick this layout. Write it as guidance — explain what kind of pages this layout suits.                                                                                                                                                                                                                                                                                                   |
-| `blocks`         | yes      | An object with `before`, `after`, and optional `initial` arrays. `before` blocks (must be `layoutOnly: true`) render above the page content, `after` blocks (must be `layoutOnly: true`) render below it, and `initial` blocks (must NOT be `layoutOnly: true`) pre-populate the homepage. See [Block Placement](#block-placement--before-after-and-initial) and [Initial Blocks](#initial-blocks--blocksinitial-optional) below. |
-| `component`      | yes      | A named React function component that renders the layout shell. Receives `{ children }` — the page content.                                                                                                                                                                                                                                                                                                                       |
-| `buildMetaTitle` | yes      | A function that builds the `<title>` tag. Receives `{ pageMetaTitle, projectName, pageFullPath }` and returns a string.                                                                                                                                                                                                                                                                                                           |
-| `buildOgImage`   | no       | A function that returns a JSX element for generating Open Graph images. Receives `{ title, description, projectName }`.                                                                                                                                                                                                                                                                                                           |
+| Option           | Required | Description                                                                       |
+| ---------------- | -------- | --------------------------------------------------------------------------------- |
+| `id`             | yes      | Unique kebab-case identifier matching the filename without extension.             |
+| `title`          | yes      | CMS display name.                                                                 |
+| `description`    | yes      | Guidance for users and agents on which pages suit this layout.                    |
+| `blocks`         | yes      | `before`, `after`, and optional `initial` arrays; see placement rules below.      |
+| `component`      | yes      | Named function component receiving `{ children }`.                                |
+| `buildMetaTitle` | yes      | `({ pageMetaTitle, projectName, pageFullPath }) => string` for the browser title. |
+| `buildOgImage`   | no       | `({ title, description, projectName }) => JSX` for a sharing image.               |
 
 ## Block Placement — `before`, `after`, and `initial`
 
-The `blocks` object groups every block that belongs to this layout into three slots:
-
-- **`before`**: rendered above the page content (navbars, banners, announcements)
-- **`after`**: rendered below the page content (footers, cookie bars)
-- **`initial`** (optional): pre-populated on the homepage when a project is first created — see the dedicated section below
-
-The blocks in `before` and `after` **must** be marked with `layoutOnly: true` in their block definition — the `createLayout` type rejects non-layout-only blocks in those slots, since layout blocks shouldn't appear in the page-content "add block" picker. Conversely, `initial` accepts only blocks where `layoutOnly` is omitted or `false` — it's for page content, not chrome.
-
-```tsx
-blocks: {
-  before: [navbarBlock, announcementBlock],
-  after: [footerBlock],
-}
-```
-
-For a navbar or footer whose content must stay identical **across different layouts**, also set `synced: true` in its `createBlock` options. `layoutOnly: true` alone only restricts placement; each layout otherwise has independent data. Synced blocks share content, settings, and repeaters and appear purple in the editor. See [Synced blocks](block-definitions.md#synced-blocks-synced-optional).
-
-You can have multiple blocks in either group, or leave one empty:
-
-```tsx
-blocks: {
-  before: [navbarBlock],
-  after: [],  // No blocks after page content
-}
-```
-
-## The Layout Component
-
-The component is a named React function that receives `{ children }` and renders the overall page structure. Inside it, use the layout constant's two slot components — `BeforeBlocks` and `AfterBlocks` — to place all of the `before` and `after` blocks, in the order you declared them in the `blocks` config.
-
-```tsx
-function MyLayoutComponent({ children }: { children: React.ReactNode }) {
-  return (
-    <main className="flex min-h-screen flex-col">
-      <myLayout.BeforeBlocks />
-      <div className="flex-1">{children}</div>
-      <myLayout.AfterBlocks />
-    </main>
-  );
-}
-```
-
-You don't list individual blocks in the component — `<myLayout.BeforeBlocks />` renders every block in `blocks.before` in order, and `<myLayout.AfterBlocks />` does the same for `blocks.after`. To reorder or add blocks, edit the `blocks` config; the component doesn't need to change.
-
-The component controls the HTML structure — you decide how to wrap and position the `BeforeBlocks` / `AfterBlocks` slots and the page content. Use Tailwind CSS for styling.
-
-## Meta Title — `buildMetaTitle`
-
-Controls how the browser tab title is built. Receives three parameters:
-
-- `pageMetaTitle` — the title set on the individual page
-- `projectName` — the site/project name
-- `pageFullPath` — the full URL path of the page
-
-Common patterns:
-
-```tsx
-// "Page Title | Site Name" (most common for content pages)
-buildMetaTitle: ({ pageMetaTitle, projectName }) =>
-  `${pageMetaTitle} | ${projectName}`,
-
-// "Site Name | Page Title" (common for landing/home pages)
-buildMetaTitle: ({ pageMetaTitle, projectName }) =>
-  `${projectName} | ${pageMetaTitle}`,
-
-// Just the page title
-buildMetaTitle: ({ pageMetaTitle }) => pageMetaTitle,
-```
+- `before` and `after` require blocks with `layoutOnly: true`. Either array may be empty.
+- Render groups with `<myLayout.BeforeBlocks />` and `<myLayout.AfterBlocks />`, not individual blocks. Array order controls rendering order; edit the config to add or reorder blocks.
+- For identical navbar/footer content across layouts, also set `synced: true`. `layoutOnly` restricts placement; it does not enable syncing. See [Synced blocks](block-definitions.md#synced-blocks-synced-optional) for publishing and existing-instance behavior.
 
 ## Initial Blocks — `blocks.initial` (optional)
 
-When a project is first set up, Camox creates a homepage automatically. The `blocks.initial` option lets you specify which blocks (and in what order) should be pre-populated on that page. Each block is created with its default content from the block definition.
+`initial` seeds the homepage at project creation, using block defaults in array order. It does not populate existing Pages.
 
-```tsx
-import { block as heroBlock } from "../blocks/hero";
-import { block as statisticsBlock } from "../blocks/statistics";
-
-const myLayout = createLayout({
-  // ...
-  blocks: {
-    before: [navbarBlock],
-    after: [footerBlock],
-    initial: [heroBlock, statisticsBlock],
-  },
-});
-```
-
-- **Only non-layout blocks.** Blocks here must NOT be `layoutOnly: true` — the type system enforces it. Layout blocks (`before`/`after`) are created separately as part of the layout itself.
-- **At most one layout per app can define `blocks.initial`.** If multiple layouts define it, the app will crash with a clear error at startup. This is enforced in `createApp`.
-- **Order matters.** The blocks appear on the homepage in the order listed.
-- **If no layout defines `blocks.initial`**, Camox still creates an empty homepage using the first available layout (with its layout blocks like navbar/footer), but no page blocks are added.
+- Accepts only blocks with `layoutOnly` omitted or `false`.
+- At most one layout per app may define `initial`; multiple definitions cause a startup error.
+- Without `initial`, Camox seeds an empty homepage using the first curated layout. Apps with only singleton/derived layouts do not seed a curated homepage.
 
 ## OG Image — `buildOgImage` (optional)
 
-Generates an Open Graph image (the preview shown when sharing links on social media). The function returns a JSX element that gets rendered as a 1200x630 image.
-
-The JSX here uses **inline styles only** (no Tailwind) because it's rendered by an image generation engine, not a browser. Use `display: "flex"` for layout.
+Returns JSX rendered as a 1200×630 image. Use **inline styles, not Tailwind**, and `display: "flex"` for layout: this runs in an image-generation engine, not a browser.
 
 ```tsx
 buildOgImage: ({ title, description, projectName }) => (
@@ -160,49 +78,17 @@ buildOgImage: ({ title, description, projectName }) => (
     style={{
       display: "flex",
       flexDirection: "column",
-      justifyContent: "center",
-      alignItems: "flex-start",
       width: "100%",
       height: "100%",
+      padding: 60,
       backgroundColor: "#09090b",
-      padding: "60px 80px",
+      color: "#fafafa",
       fontFamily: "sans-serif",
     }}
   >
-    {projectName && (
-      <div style={{ fontSize: 24, color: "#a1a1aa", marginBottom: 24 }}>
-        {projectName}
-      </div>
-    )}
-    <div
-      style={{
-        fontSize: 64,
-        fontWeight: 700,
-        color: "#fafafa",
-        lineHeight: 1.2,
-        marginBottom: 24,
-      }}
-    >
-      {title}
-    </div>
-    {description && (
-      <div style={{ fontSize: 28, color: "#a1a1aa", lineHeight: 1.5 }}>
-        {description}
-      </div>
-    )}
+    {projectName && <div style={{ fontSize: 24 }}>{projectName}</div>}
+    <div style={{ fontSize: 64 }}>{title}</div>
+    {description && <div style={{ fontSize: 28 }}>{description}</div>}
   </div>
 ),
 ```
-
-## Rules and Conventions
-
-1. **File = one layout.** One `.tsx` file per layout in `src/layouts/`. The `id` must match the filename (without `.tsx`).
-2. **Named export as `layout`.** Always: `export { myVar as layout }`. Not a default export.
-3. **Named function component.** Use `function MyComponent()`, not an arrow function. Reference it in `createLayout` before its declaration is fine (hoisting).
-4. **Import path is `"camox/createLayout"`.** The `createLayout` function comes from this import.
-5. **Import blocks from `"../blocks/filename"`.** Layout blocks are imported from the blocks directory. Import the named `block` export.
-6. **Use Tailwind CSS for the component.** Style the layout shell with Tailwind utility classes. The OG image function uses inline styles instead.
-7. **Render groups, not individual blocks.** The component places `<layout.BeforeBlocks />` and `<layout.AfterBlocks />` — each renders every block in its group, in declared order. Don't reference blocks individually by name.
-8. **`buildMetaTitle` is required.** Every layout must define how page titles are constructed.
-9. **Description guides layout selection.** Write the `description` to help CMS users choose the right layout for their page — explain what types of pages it's suited for.
-10. **Layout blocks must use `layoutOnly: true`.** Blocks placed in `blocks.before` or `blocks.after` must be defined with `layoutOnly: true` (enforced by the `createLayout` type). Blocks placed in `blocks.initial` must NOT be `layoutOnly: true`.

package/skills/camox/references/routed-layouts.md

@@ -0,0 +1,71 @@
+# Singleton pages and derived routes
+
+Use this reference for code-owned pages in `src/layouts/`. For editor-created pages with a reusable shell and page-content `children`, read [Layout Definitions](layout-definitions.md) instead.
+
+- **`singleton`**: one code-owned page at a fixed file-defined URL. Editors change its blocks, not its existence, URL, or structure.
+- **`derived`**: code-owned routes resolved through a required server-side loader, typically using file parameters such as `$name`.
+
+All editable content lives in blocks. Layouts do not expose editable `content` schemas or `.Field` helpers. Read [Block Definitions](block-definitions.md) when creating or changing those blocks.
+
+## Singleton pages
+
+Declare a singleton in `src/layouts/pokedex.tsx`. The file identity defines `/pokedex`; `guide.pokedex.tsx` defines `/guide/pokedex`. Singleton identities must contain only literal word/hyphen segments separated by dots—no `$params`. The file plugin maintains the identity and registers the definition.
+
+```tsx
+import { createLayout } from "camox/createLayout";
+import { block as navbarBlock } from "../blocks/navbar";
+import { block as pokedexIntroBlock } from "../blocks/pokedex-intro";
+import { block as footerBlock } from "../blocks/footer";
+import { loadPokemon } from "../lib/pokemon";
+import { PokemonBrowser } from "../components/pokemon-browser";
+
+export const Layout = createLayout("pokedex")({
+  kind: "singleton",
+  title: "Pokédex",
+  description: "The code-owned Pokémon directory.",
+  blocks: {
+    before: [navbarBlock, pokedexIntroBlock],
+    after: [footerBlock],
+  },
+  loader: () => loadPokemon(),
+  component: PokedexPage,
+  buildMetaTitle: ({ pageMetaTitle }) => pageMetaTitle,
+});
+
+function PokedexPage() {
+  const pokemon = Layout.useData();
+  return (
+    <>
+      <Layout.BeforeBlocks />
+      <main>
+        <PokemonBrowser pokemon={pokemon} />
+      </main>
+      <Layout.AfterBlocks />
+    </>
+  );
+}
+```
+
+- `loader` is optional. Its awaited result is inferred by `Layout.useData()`. It runs server-side for document requests and client navigation; return JSON-serializable data. Without a loader, `useData()` returns `undefined`.
+- Before/after blocks must be `layoutOnly: true`. Put editable headings, introductions, and other bespoke content in these blocks; keep structural application UI in the component. See [Block Definitions](block-definitions.md).
+- For a navbar or footer whose content must stay identical across different layouts, also set `synced: true` in its `createBlock` options. `layoutOnly: true` alone only restricts placement. See [Synced blocks](block-definitions.md#synced-blocks-synced-optional) for sharing and publishing behavior.
+- No `children` slot or `blocks.initial`: editors do not compose or create these pages.
+- No curated page record is created. Do not use the pages CLI to create, duplicate, move, or assign a singleton.
+- Studio lists singletons as directly navigable pages with block editing and layout publishing, without deletion or URL/layout controls. They also appear in link destination pickers (including inline text links), “Go to page” actions, and the runtime sitemap. Derived route families are not enumerated.
+- Singleton links are saved as fixed internal URLs, not synthetic database page IDs: link fields use `{ type: "external", href: "/pokedex", text: "Pokédex", newTab: false }` (the existing URL representation), while inline text uses `[Pokédex](/pokedex)`. Renaming a code-owned URL requires updating links or adding a redirect. Curated-page links retain their page-ID references.
+- Curated-only mutation surfaces, such as page-parent selectors and the pages record API/CLI, remain separate from the navigable destination list.
+- Publishing exposes the current editable blocks. Unpublishing removes those published blocks, **not** the route or code-rendered UI. Synced blocks retain their existing shared publishing behavior.
+- Code deployment controls route existence. Removing the definition and syncing releases its reserved URL. Existing curated URL collisions or layouts still assigned to curated pages must be resolved explicitly before sync can succeed.
+- Curated pages cannot claim singleton URLs or use singleton/derived layouts. Literal singleton routes take precedence over parameterized derived routes.
+- Current routed-page HTML titles use the definition's `title`; the required `buildMetaTitle` option is retained for API compatibility, but routed-page metadata callbacks are not yet applied.
+
+## Derived routes
+
+Use the same file-based form with `kind: "derived"`, for example `createLayout("pokemon.$name")`. Its required `loader: ({ params }) => ...` receives typed `params.name`. Read its result through `Layout.useData()`. Use `throw notFound()` (imported from `camox/createLayout`) for a missing record; other loader errors remain server errors. Like singletons, derived routes have before/after blocks but no page-owned `children` or `blocks.initial`. Unlike singletons, curated URLs retain precedence over derived routes.
+
+## File and component conventions
+
+- One `.tsx` file per layout in `src/layouts/`; the identity passed to `createLayout("file-id")` must match the filename without `.tsx`.
+- Use a named `Layout` or `layout` export, not a default export.
+- Use a named function component and Tailwind CSS for the layout shell.
+- Render `<Layout.BeforeBlocks />` and `<Layout.AfterBlocks />` to place the configured groups in order, rather than rendering individual blocks by name.