camox 0.43.0 → 0.45.0

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

@@ -4,7 +4,7 @@ Use this reference to customize inline text, links, and highlights on an existin
 
 ## String formatting
 
-String fields support inline formatting in both editing and published output: `**bold**`, `*italic*` (or `_italic_`), `***bold italic***`, `<u>underlined</u>`, `<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.
+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
 
@@ -14,7 +14,7 @@ Spread the field's render-prop `props` onto the element to preserve inline editi
 <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):
+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). Utilities below, such as `text-brand`, are examples; use the ones the project's Theme defines:
 
 ```tsx
 <myBlock.Field
@@ -31,20 +31,20 @@ Camox owns inline markup so editing and published output have the same appearanc
       };
     }
     return {
-      className: bold ? "text-primary" : undefined,
+      className: bold ? "text-brand" : undefined,
       style: bold && italic ? { letterSpacing: "0.02em" } : undefined,
     };
   }}
   linkStyle={({ external }) => ({
-    className: external ? "text-blue-600" : "text-primary font-medium",
+    className: external ? "text-ink-muted" : "text-brand font-medium",
   })}
 >
   {(props) => <p {...props} />}
 </myBlock.Field>
 ```
 
-- `textStyle` receives `{ bold, italic, underline, 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.
+- `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, underline: 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, underline, highlight color) use inline styles; use `style` to override those defaults rather than competing utility classes.
+- 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 website's `--camox-highlight` 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

@@ -12,9 +12,9 @@ Use one `.tsx` file per layout in `src/layouts/`, a named `layout` or `Layout` e
 
 ```tsx
 import { createLayout } from "camox/createLayout";
-import { block as navbarBlock } from "../blocks/navbar";
+
 import { block as footerBlock } from "../blocks/footer";
-import { block as heroBlock } from "../blocks/hero";
+import { block as navbarBlock } from "../blocks/navbar";
 
 const myLayout = createLayout({
   id: "my-layout",
@@ -23,7 +23,7 @@ const myLayout = createLayout({
   blocks: {
     before: [navbarBlock],
     after: [footerBlock],
-    initial: [heroBlock],
+    initial: [() => import("../blocks/hero")],
   },
   component: MyLayoutComponent,
   buildMetaTitle: ({ pageMetaTitle, projectName }) => `${pageMetaTitle} | ${projectName}`,
@@ -44,26 +44,28 @@ export { myLayout as layout };
 
 ## The `createLayout` options
 
-| 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.               |
+| 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 layout slot rules below.                                               |
+| `component`            | yes      | Named function component receiving `{ children }`.                                                                           |
+| `buildMetaTitle`       | yes      | `({ pageMetaTitle, projectName, pageFullPath }) => string` for the browser title.                                            |
+| `buildMetaDescription` | no       | `({ pageMetaDescription, projectName, pageFullPath }) => string \| undefined`. Without it, the editor's description is used. |
+| `buildOgImage`         | no       | `({ title, description, projectName }) => JSX` for a sharing image.                                                          |
 
-## Block Placement — `before`, `after`, and `initial`
+## Layout Slots — `before`, `after`, and `initial`
 
 - `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.
+- For identical navbar/footer content across layouts, also set `synced: true`. `layoutOnly` restricts a block to layout slots; it does not enable syncing. See [Synced blocks](block-definitions.md#synced-blocks-synced-optional) for sharing and existing-placement behavior.
 
 ## Initial Blocks — `blocks.initial` (optional)
 
 `initial` seeds the homepage at project creation, using block defaults in array order. It does not populate existing Pages.
 
+- List each block as an import of its module, `() => import("../blocks/hero")`, never a statically imported block. Layouts load on every page, so a static import would ship the block to every visitor.
 - 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.

package/skills/camox/references/localization.md

@@ -0,0 +1,56 @@
+# Localization in code
+
+A project publishes in one or more locales, added and removed as content, never in code. The default locale's pages sit at unprefixed paths (`/pricing`); every other locale's sit under its lowercase tag (`/de/preise`). Camox translates everything in blocks and records, writes `<html lang>`, `hreflang` alternates and the combined sitemap itself. Code only has to keep text in blocks and links in the locale.
+
+## Visible text lives in blocks
+
+Every text a visitor can read is block content, layout blocks included: navbar and footer labels, a singleton's heading, a "Back to articles" link, a record page's "Written by". Camox translates block content; it never translates JSX. Put the text in a `layoutOnly` block placed in the layout's `before` or `after` slots, or in a field of the block that shows it. JSX keeps only structure, styling and data a loader returns.
+
+## Internal links stay in the locale
+
+Write root-relative paths without a locale prefix, and pass them through `useLocalizedHref` from `camox/navigation`. On a `de` page, `/articles` becomes `/de/articles`; on a default-locale page it stays `/articles`. External URLs, `#anchors` and `mailto:` links come back as is.
+
+```tsx
+import { Link, useLocalizedHref } from "camox/navigation";
+
+function BackToArticles({ children }: { children: React.ReactNode }) {
+  const localized = useLocalizedHref();
+  return <Link to={localized("/articles")}>{children}</Link>;
+}
+```
+
+Link fields and `camox:page:` text links already resolve per locale: render them as they come. The locale's prefix comes from the helper alone, so a `/de` written into code or content links German visitors to `/de/de/...` and English visitors to German.
+
+## Locale switcher
+
+`useAlternates()` returns the current page in every locale it exists in, the current one included, as `{ locale, href, label }`. `label` is the locale's name in its own language (`Deutsch`, `français`), from `Intl.DisplayNames`; capitalize it with CSS if the design needs it. A locale the page was removed from isn't listed, so the switcher never links to a 404. `useLocale()` returns the current locale's tag, such as `de`.
+
+```tsx
+import { Link, useAlternates, useLocale } from "camox/navigation";
+
+function LocaleSwitcher() {
+  const current = useLocale();
+  const alternates = useAlternates();
+  if (alternates.length < 2) return null;
+  return (
+    <nav aria-label="Language">
+      {alternates.map(({ locale, href, label }) => (
+        <Link key={locale} to={href} hrefLang={locale} aria-current={locale === current}>
+          {label}
+        </Link>
+      ))}
+    </nav>
+  );
+}
+```
+
+## Loaders
+
+A singleton or derived layout's `loader` receives `locale`, the page's locale tag. Use it to fetch localized data when the data source has it. Camox renders what a loader returns as it is and never translates it. Route patterns aren't localized: `routes` lists the same paths for every locale, and `/de/pokemon/pikachu` renders the `pokemon.$name` layout in German.
+
+```tsx
+loader: async ({ params, locale }) => ({
+  kind: "data",
+  data: await loadPokemon(params.name, { language: locale }),
+}),
+```

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

@@ -5,7 +5,7 @@ Use this reference for code-owned pages in `src/layouts/`. For editor-created pa
 - **`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.
+All editable content lives in blocks. Layouts do not expose editable `content` schemas or `.Field` helpers; [record pages](#record-pages) render their collection record through `layout.Item`. Read [Block Definitions](block-definitions.md) when creating or changing those blocks.
 
 ## Singleton pages
 
@@ -13,13 +13,14 @@ Declare a singleton in `src/layouts/pokedex.tsx`. The file identity defines `/po
 
 ```tsx
 import { createLayout } from "camox/createLayout";
+
+import { block as footerBlock } from "../blocks/footer";
 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";
+import { loadPokemon } from "../lib/pokemon";
 
-export const Layout = createLayout("pokedex")({
+export const layout = createLayout("pokedex")({
   kind: "singleton",
   title: "Pokédex",
   description: "The code-owned Pokémon directory.",
@@ -27,41 +28,158 @@ export const Layout = createLayout("pokedex")({
     before: [navbarBlock, pokedexIntroBlock],
     after: [footerBlock],
   },
-  loader: () => loadPokemon(),
-  component: PokedexPage,
+  loader: async () => ({ kind: "data", data: await loadPokemon() }),
+  // After the loader: these callbacks' `data` is inferred from it.
   buildMetaTitle: ({ pageMetaTitle }) => pageMetaTitle,
+  toMarkdown: ({ data }) => [`${data.length} Pokémon`, data.map((p) => `- ${p.name}`).join("\n")],
+  component: PokedexPage,
 });
 
 function PokedexPage() {
-  const pokemon = Layout.useData();
+  const pokemon = layout.useData();
   return (
     <>
-      <Layout.BeforeBlocks />
+      <layout.BeforeBlocks />
       <main>
         <PokemonBrowser pokemon={pokemon} />
       </main>
-      <Layout.AfterBlocks />
+      <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`.
+- `loader` is optional. Return `{ kind: "data", data }`, synchronously or asynchronously. `layout.useData()` infers and returns the unwrapped `data`, not the envelope. It runs server-side for document requests and client navigation; the entire envelope travels through JSON to hydration. Keep data JSON-serializable (no functions, symbols, BigInt, or cyclic objects). Without a loader, `useData()` returns `undefined`. The loader also receives `locale`, the page's locale tag; Camox renders its data untranslated (see [Localization](localization.md#loaders)).
 - 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.
+- 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 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.
+- Studio lists singletons as directly navigable pages with block editing, 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 pages appear in the sitemap only when their layout declares `routes` (see [Route discovery](#route-discovery)).
 - 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.
+- The route renders the current editable blocks.
 - 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.
+- See [Metadata and Markdown](#metadata-and-markdown) for page titles, descriptions, and the page's Markdown Representation.
 
 ## 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.
+Use the same file-based form with `kind: "derived"`, for example `createLayout("pokemon.$name")`. Its required `loader: ({ params }) => ...` receives typed `params.name` and returns `{ kind: "data", data }`. Read its unwrapped data 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.
+
+### Route discovery
+
+A derived layout can list the pages it renders with an optional `routes` function, a sibling of `loader`:
+
+```tsx
+export const Layout = createLayout("pokemon.$name")({
+  kind: "derived",
+  // Other options omitted.
+  loader: async ({ params }) => ({ kind: "data", data: await loadPokemon(params.name) }),
+  routes: async () => ({
+    data: (await listPokemon()).map((pokemon) => ({ params: { name: pokemon.name } })),
+  }),
+});
+```
+
+- Return `{ data: [{ params }] }`, synchronously or asynchronously. `params` is typed from the file identity: `pokemon.$name` needs exactly `{ name: string }`. Return raw values; Camox builds and encodes the URL (`mr mime` becomes `/pokemon/mr%20mime`).
+- Only derived layouts accept `routes`; singletons and curated layouts are a type error.
+- The runtime sitemap lists every discovered page, without `<lastmod>`. The Canvas previews the layout's first discovered page until a path is chosen.
+- Entries may carry an optional `target` naming the collection record they render (see [Record pages](#record-pages)).
+- An invalid entry (missing, extra or empty params, or a value containing `/`) or a throwing `routes` makes `/sitemap.xml` respond 500 with a message naming the layout, rather than silently omitting pages.
+- `routes` lists pages; it does not authorize them. The loader still validates every request, and URLs left out of `routes` keep rendering. A curated page at a discovered URL still takes precedence and may be listed twice.
+- `routes` returns every page at once.
+- `loader` receives `{ params, context }` and `routes` receives `{ context }`. `context` is an opaque request context: ignore it, or pass it through unchanged to Camox helpers. The sitemap and Markdown always get live content; HTML and Studio navigation follow the editor's session.
+
+### Record pages
+
+A **Record Page** renders one collection record, found by one of its fields. Spread `collection.pages({ by, param })` into a derived layout instead of writing `loader` and `routes`:
+
+```tsx
+import { createLayout } from "camox/createLayout";
+
+import { collection as articles } from "../collections/articles";
+
+export const Layout = createLayout("articles.$slug")({
+  kind: "derived",
+  title: "Article",
+  description: "One article, found by its slug.",
+  blocks: { before: [navbarBlock], after: [footerBlock] },
+  ...articles.pages({ by: "slug", param: "slug" }),
+  buildMetaTitle: ({ item, projectName }) => `${item.title} | ${projectName}`,
+  buildMetaDescription: ({ item }) => item.excerpt || undefined,
+  toMarkdown: ({ item }) => [`# ${item.title}`, `By ${item.author.name}`, item.body],
+  component: ArticlePage,
+});
+
+function ArticlePage() {
+  return (
+    <Layout.Item>
+      {(article) => (
+        <article>
+          <article.Field name="title">{(props) => <h1 {...props} />}</article.Field>
+          <article.Reference name="author">
+            {(author) => <author.Field name="name">{(props) => <p {...props} />}</author.Field>}
+          </article.Reference>
+          <article.Field name="body">{(props) => <p {...props} />}</article.Field>
+        </article>
+      )}
+    </Layout.Item>
+  );
+}
+```
+
+- `by` names a String field of the collection; any other field is a type error. `param` names the route parameter holding its value; a layout whose route lacks it fails to type-check.
+- The loader finds the record whose `by` field's plain text equals the param: the draft value for a signed-in editor previewing, the published value for everyone else. A draft-only record is reachable in preview at its draft value; a never-published or unknown value answers 404. Records whose value is empty or contains `/` never get a page.
+- Several records sharing a value in the same source is a server error naming the collection, field, value and records. Camox does not enforce uniqueness: keep the field unique.
+- The loader returns a `collection-item` envelope, `{ kind: "collection-item", collectionId, data: { id, content } }`, typed as `LayoutCollectionItemResult` from `camox/createLayout`. `layout.useData()` returns the unwrapped record, `{ id, content }`. Camox rejects an envelope naming an unregistered collection or a malformed record id.
+- `routes` lists one entry per record that can have a page, in the request's source: the sitemap lists published records only, even when an editor asks, while the Canvas previews a signed-in editor's first record, draft-only records included. Each entry is `{ params, target: { kind: "collection-item", collectionId, id } }`; `target` names the record independently of its current value. Records whose value is empty or contains `/` are left out. Several records sharing a value fail discovery, so `/sitemap.xml` responds 500 naming the layout and the records. An empty collection returns `{ data: [] }`, and the Canvas asks for a path.
+- `layout.Item` renders the page's record with the same typed scope as a block's `Reference`: `Field`, `Image`, `File`, `Embed`, `ImageList`, `FileList`, `Reference` and `ReferenceList`, plus `id` and `label`. Field names are checked against the collection. The record is the first hop: `Reference` and `ReferenceList` render the records it links, which link nothing further. Prefer it to `useData()`, whose `content` holds stored values (String fields may be rich-text state).
+- `layout.Item` exists only when every return of the loader is a record of one collection. On a loader that may return external data or records of several collections, using it is a type error. At runtime it renders nothing when the result isn't a record.
+- In Studio, editors edit record page fields in place, like a referenced record's: purple overlays, selection, and the record's fields in the sidebar. Edits change the shared record everywhere it appears.
+- `toMarkdown` also receives `item`, the same Markdown builder as a reference list's `toMarkdown`: interpolate fields (`item.title`, `item.author.name`, `item.cover`) and Camox fills them with the live record, rich text included. `data` stays the raw record. Markdown always shows live content, whoever asks.
+- `buildMetaTitle` and `buildMetaDescription` also receive `item`: the record's String fields as plain text.
+- To wrap the helper, pass the whole loader input through, `context` included, and return the envelope unchanged. Type it as the helper's loader (`ReturnType<typeof articlePages.loader>`) to keep `layout.Item` and `item` typed:
+
+```tsx
+const articlePages = articles.pages({ by: "slug", param: "slug" });
+// …
+loader: async (input) => {
+  const result = await articlePages.loader(input);
+  return result;
+},
+routes: articlePages.routes,
+```
+
+## Migrating existing loaders
+
+This is a breaking loader contract: replace `return pokemon` with `return { kind: "data", data: pokemon }`. For asynchronous data, await the payload inside the envelope: `return { kind: "data", data: await loadPokemon() }`, not a promise in `data`. Components using `layout.useData()` do not change. Existing layouts without loaders do not change.
+
+For an explicit return annotation, import `type LayoutLoaderResult` from `camox/createLayout` and use `Promise<LayoutLoaderResult<Pokemon>>` instead of `Promise<Pokemon>`. Inline loaders infer their payload automatically. Standalone loader functions can use `LayoutLoaderResult<Pokemon>` (or `satisfies LayoutLoaderResult<Pokemon>`) to keep `kind` a literal rather than a widened string. Wrappers are ordinary functions returning the same envelope; no attached properties or discovery phase are involved.
+
+The playground's `/pokedex`, `/pokemon/pikachu`, and `/pokemon-types/electric` are working external-data examples, and both derived layouts declare `routes`, so `/sitemap.xml` lists every Pokémon and type. Load a URL directly, follow a Pokémon/type link, and refresh: `useData()` receives the same payload in server rendering, navigation, and hydration. Search and “Show more” still run on client state. A nonexistent Pokémon still returns 404; a PokéAPI failure is still a server error.
+
+`kind: "data"` does not make external data editable. For collection records, use [Record pages](#record-pages).
+
+## Metadata and Markdown
+
+Singleton and derived pages get the same head as curated pages: title, description, `og:*` tags, the `/og` image, and the favicon. They have no editor metadata, so the callbacks receive the loader's unwrapped `data` and the route `params` instead:
+
+```tsx
+export const Layout = createLayout("pokemon.$name")({
+  kind: "derived",
+  // Other options omitted.
+  loader: async ({ params }) => ({ kind: "data", data: await loadPokemon(params.name) }),
+  buildMetaTitle: ({ data, pageMetaTitle }) => `${data.name} – ${pageMetaTitle}`,
+  buildMetaDescription: ({ data }) => `${data.name} is a ${data.types.join("/")} type Pokémon.`,
+  toMarkdown: ({ data, params }) => [`# ${data.name}`, `Types: ${data.types.join(", ")}`],
+});
+```
+
+- **Put `loader` before `buildMetaTitle`, `buildMetaDescription`, and `toMarkdown`.** TypeScript infers their `data` from the loader only in that order. Otherwise the loader is inferred as `never` and fails to type-check.
+- `buildMetaTitle` receives `pageMetaTitle` (the layout's `title` on these pages), `projectName`, `pageFullPath`, `data`, and `params`. The `/og` image shows its result.
+- `buildMetaDescription` is optional; without it these pages have no description.
+- `toMarkdown` returns the page's Markdown Representation as a list of strings. Empty strings are dropped and the rest joined with blank lines. A request with `Accept: text/markdown` gets YAML front matter (the `title` and `description` the head shows, and the page's `url`), then the live before-block Markdown, then this output, then the live after-block Markdown. Curated pages' Markdown opens with the same front matter. Without `toMarkdown`, the page answers HTML only. `throw notFound()` in the loader answers 404. Curated layouts cannot declare `toMarkdown`: their Markdown comes from their blocks.
+- The playground's Pokémon, Pokémon type, and Pokédex layouts declare these. Try `curl -H "Accept: text/markdown" http://localhost:3000/pokemon/pikachu`.
 
 ## File and component conventions
 

package/skills/camox-expand/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: camox-expand
+description: Expand a Camox project's Block Definitions ahead of need by finding jobs they can't do yet, proposing new blocks and Settings, and building the approved ones. Use when asked to add more blocks or prepare blocks before a launch.
+---
+
+# Camox Expand
+
+Work in an existing Camox project. Grow its Block Definitions so editors can do more with content changes alone. Every addition fills a real **gap**: a job the current Block Definitions can't do, or can only do in a shape or visual treatment the site already repeats. Each one must keep the site's own design.
+
+## 1. Ask about what's next
+
+Ask the operator one question: what is being launched or published next? Use the answer to rank gaps. If they have nothing planned, the other evidence decides.
+
+## 2. Inventory the Block Definitions
+
+Read every Block Definition in `src/blocks/`. For each one, note its job, content shape, visual treatment, and Settings. Also look at the rendered site to learn its design language. You're done when you can say which jobs each block does and how two blocks for the same job differ.
+
+## 3. Find gaps
+
+Collect evidence in this order:
+
+1. **Upcoming needs** from the operator's answer.
+2. **The jobs checklist.** Compare [Jobs](references/jobs.md) with the Block Definitions. A job counts as covered only when an existing block, or an existing block with a Setting, does it well.
+3. **The source site**, when the project was migrated from one. Look for sections and page types that `camoxify-progress.md` or the current Pages don't reproduce.
+4. **Competitors' sites**, only when the site's category is clear. Take the jobs their pages and sections do, and leave their designs and copy alone. Every suggestion is designed in the site's own visual language.
+
+Decide between a new block and a Setting with Camoxify's "Reuse before creating" rule in [Inspect and decompose](../camoxify/SKILL.md#inspect-and-decompose).
+
+You're done when every evidence source that applies has been checked, every job in the checklist is marked covered or a gap, and every gap is marked as a new block or a Setting.
+
+## 4. Propose and wait for approval
+
+List the suggestions in the chat. Each one has:
+
+- its **job**,
+- its **kind**: new block, or new Setting on an existing block,
+- the **closest existing block**,
+- a **text wireframe** for a new block, or a **before/after sketch** for a new Setting, in a fenced code block so it renders in any harness.
+
+```text
+Logo wall (new block). Job: social proof. Closest: feature-grid
++----------------------------------------------+
+|        Trusted by teams shipping daily        |
+|  [logo]  [logo]  [logo]  [logo]  [logo]       |
++----------------------------------------------+
+```
+
+Stop suggesting when the next idea would be filler; there is no target count. Then wait. The operator approves, cuts items, or asks for more or fewer. Revise until they approve a list. Nothing is built before that.
+
+## 5. Build the approved list
+
+Make only these kinds of change:
+
+- **New Block Definitions**, following [Block Definitions](../camox/references/block-definitions.md), [Localized code](../camox/SKILL.md#localized-code) (every visible text in fields, internal links through `useLocalizedHref` without a locale prefix), and Camoxify's rules on [styling](../camoxify/SKILL.md#use-the-existing-styling-stack), [genericity and default content](../camoxify/SKILL.md#keep-definitions-generic), [repeaters](../camoxify/SKILL.md#model-repetition-not-a-fixed-screenshot), [Settings](../camoxify/SKILL.md#use-settings-for-constrained-choices), and [formatted text](../camoxify/SKILL.md#keep-formatted-text-in-one-field).
+- **New Settings on existing Block Definitions**, with defaults that leave current rendering unchanged. Existing content schemas stay exactly as they are. Before editing the block, capture it in the Block Catalog at desktop and mobile, opened at `/camox/blocks/<id>` on the running dev server; step 6 compares against this capture.
+- **Description edits.** A new block's `description` says when to choose it over its siblings. Edit the siblings' descriptions so each one names what sets it apart, and the Agent can choose between them.
+
+New blocks live only in code and the Block Catalog. Leave Pages, layouts, and publishing alone, and create no temporary Pages. This rules out new Layout-only Blocks: the Block Catalog never shows them, and they only sync once a layout uses them. An existing Layout-only Block that gains a Setting has no Block Catalog page either, so capture and check it on a Page whose layout uses it.
+
+## 6. Verify
+
+Finish with a Block Catalog link to each new block, so the operator and the product marketing team can review them live. Delete any block the operator rejects, along with any description changes made only for it.
+
+The run is complete when:
+
+- every approved item is built, and every rejected one is deleted,
+- the project's `check` script passes, and so does `vp lint --type-aware --type-check`, since `vp check` skips type errors unless the project's Vite config sets `lint.options.typeCheck`,
+- every new block renders correctly with its default content at desktop and mobile in the Block Catalog at `/camox/blocks/<id>`,
+- every existing block that gained a Setting renders the same as its capture with default Settings.

package/skills/camox-expand/references/jobs.md

@@ -0,0 +1,39 @@
+# Jobs
+
+Jobs that marketing pages and sections commonly do. Each entry describes what the content achieves for the visitor, never how it looks. Design every block for a job in the site's own visual language.
+
+## Section jobs
+
+- **Introduction**: say what the product or page is and who it is for.
+- **Explanation**: show how the product works or what a feature does.
+- **Benefits**: turn features into outcomes for the visitor.
+- **Social proof**: show that others use and trust the product, through customers, quotes, numbers, ratings, or press.
+- **Credibility**: back claims with certifications, security, compliance, or awards.
+- **Objection handling**: answer the doubts that stop a visitor from acting, such as questions, risks, or "why not the alternative".
+- **Comparison**: set the product against alternatives, plans, or the status quo.
+- **Pricing**: say what it costs and what each option includes.
+- **Conversion**: ask the visitor to act, such as sign up, buy, book, or download.
+- **Lead capture**: collect contact details in exchange for something.
+- **Demonstration**: let the visitor see the product working, through media, a demo, or an interactive sample.
+- **Process**: walk through the steps to get started or to get a result.
+- **Integration**: show what the product connects to.
+- **Team and story**: introduce the people and the reasons behind the product.
+- **Announcement**: flag something new or time-limited.
+- **Navigation aid**: help visitors find related pages, resources, or the next step.
+- **Long-form reading**: carry an article, guide, or document.
+
+## Page jobs
+
+- **Launch page**: present a new product or feature.
+- **Comparison page**: argue for the product against a named alternative.
+- **Customer story**: tell one customer's problem, solution, and results.
+- **Use-case or industry page**: speak to one audience or problem.
+- **Pricing page**: let visitors choose a plan.
+- **Event registration**: get visitors to sign up for a webinar, meetup, or conference.
+- **Changelog**: record what changed and when.
+- **Resource or download page**: offer a guide, report, or template.
+- **Integration page**: explain one integration.
+- **About page**: explain who is behind the product.
+- **Careers page**: attract applicants.
+- **Contact page**: route visitors to the right channel.
+- **Legal page**: carry terms, privacy, or policy text.

package/skills/camoxify/SKILL.md

@@ -7,6 +7,14 @@ description: Turn an existing website, screenshot, or design into an editable Ca
 
 Work in the existing Camox project; project creation and authentication are onboarding prerequisites. Match the reference while making the result reusable and easy to edit.
 
+## Scope the run
+
+Take the scope from the request. A first run usually covers the shell and the homepage; a later run may cover the whole site, reusing what earlier runs built.
+
+For multi-page runs, build the page list before coding: read the sitemap (`/sitemap.xml`, or the one named in `/robots.txt`) and follow navigation and footer links. Group pages that share one structure, such as blog posts, case studies, or docs articles, into a **page family**: one layout and set of blocks, built and verified on a representative page, then repeated for the rest through the CLI. Confirm the list and its families with the user before building.
+
+Track progress in `camoxify-progress.md` at the project root: one line per page with its status (pending, built, populated, verified) and any new definitions it introduced. Update it as each page advances. When resuming, start from that file and the project's current definitions.
+
 ## Inspect and decompose
 
 Inspect the source URL with available browsing tools, or use the supplied screenshot/design. If the URL is inaccessible, ask for screenshots. Check multiple pages and viewport sizes when available; don't infer a whole site's structure from one crop.
@@ -16,23 +24,47 @@ For URL references, use a browser when available to explore interactive states:
 Before coding, map the reference to:
 
 - **Layout:** the consistent shell across pages, such as navigation and footer. Editable shell content still lives in blocks, placed by the layout.
-- **Page blocks:** independently useful sections such as a hero, feature grid, testimonials, or pricing. Reuse existing definitions where they fit. Avoid both a monolithic page block and separate blocks for every heading or card.
+- **Page blocks:** independently useful sections such as a hero, feature grid, testimonials, or pricing. Avoid both a monolithic page block and separate blocks for every heading or card.
+
+Reuse before creating. When a section matches an existing definition's content shape and visual treatment, use it, adding a setting for a small variation. Create a new definition when the visual treatment or the content shape is meaningfully different; distinct designs for the same job keep pages varied. A new definition's `description` says when to choose it over similar existing blocks.
+
 - **Fields and repeaters:** editable content within each section, grouped by meaning rather than visual position.
+- **Artifacts:** bespoke visuals found on the reference, such as animated illustrations, 3D scenes, or one-off interactive widgets. Recreate each as an artifact source on a `field.artifact` of the block around it, not as a one-off block. Read [Artifacts](../camox/references/artifacts.md).
 
 Read [Block Definitions](../camox/references/block-definitions.md) and, when creating or changing a shell, [Layout Definitions](../camox/references/layout-definitions.md).
 
+## Use the existing styling stack
+
+Learn the project's **Theme** before styling: read its main stylesheet, the CSS file that imports Tailwind. Its tokens and the comments beside them say what each color, font, text size, radius and spacing is for, and which **Color Schemes** a block can switch to. Take each token's meaning from its comment, not from its name.
+
+Reuse the project's **Components**, such as its button or card, and compose or extend them to match the reference. Build a new Component only when none fits.
+
+Style through the Theme's utilities rather than raw colors or stock palette classes, so a rebrand stays one stylesheet edit. To match the reference's colors, fonts and radii, change the Theme's values in the stylesheet; when the reference needs a role the Theme lacks, add a token there with a comment explaining it.
+
+If the reference uses another styling system, recreate its appearance and behavior with the project's Components and Tailwind utilities; do not copy or introduce the reference's styling dependencies.
+
+Express layout, spacing, typography, colors, responsive behavior, and interactive states through Tailwind and the project's Components. Do not install other styling libraries or add separate stylesheets or inline styles.
+
 ## Keep definitions generic
 
 Block names, schemas, rendering, and **default content** must work on other pages. Use `feature-grid`, not `acme-homepage-features`. Defaults are neutral examples, not the reference's copy, links, assets, or item data.
 
 Apply reference-specific content **only to instances through the CLI**, never by changing definition defaults or hardcoding it in JSX.
 
+Keep the result translatable, following [Localized code](../camox/SKILL.md#localized-code): every visible text in the shell, navigation and footer included, lives in blocks, and internal links go through `useLocalizedHref`, written without a locale prefix.
+
 ## Model repetition, not a fixed screenshot
 
-Use `Type.Repeater` for every repeated content structure: lists, rows, columns, tables, carousels, navigation items, and cards. Never use `field1`, `field2`, etc., or hardcoded content arrays. Nest repeaters for structures such as footer columns containing links or table rows containing cells.
+Use `field.repeater` for every repeated content structure: lists, rows, columns, tables, carousels, navigation items, and cards. Never use `field1`, `field2`, etc., or hardcoded content arrays. Nest repeaters for structures such as footer columns containing links or table rows containing cells.
 
 Choose bounds from real constraints, not the number of items visible in the reference. Many sibling fields are a code smell: look for repeated groups or separate sections. Model enough flexibility to add, remove, reorder, and rewrite content without code changes; don't expose every CSS value as a field.
 
+## Use settings for constrained choices
+
+Before adding a `content` field, ask whether the editor is writing free-form content or choosing from known options. For configuration choices such as alignment, theme, size, or variant, use `settings` with `setting.enum`. For on/off choices such as showing a background or enabling autoplay, use `settings` with `setting.boolean`.
+
+Do not model these choices as `content` fields using `field.string`, even if rendering code could interpret strings such as `"left"`, `"dark"`, or `"true"`. Editors should choose a valid option or toggle a setting, not type a magic string. Reserve `content`'s `field.string` for genuinely free-form text, such as headings and descriptions. Enum defaults must match an option key.
+
 ## Keep formatted text in one field
 
 Use inline formatting and `textStyle`, including highlights, instead of fields such as `headingStart`, `coloredWord`, and `headingEnd`. Editors should be able to move the emphasis by editing content alone. Read [Field styling](../camox/references/field-styling.md).
@@ -50,3 +82,7 @@ Use inline formatting and `textStyle`, including highlights, instead of fields s
 Follow the [Camox CLI workflow](../camox/SKILL.md#content-and-cli) to assign layouts, place blocks, and populate content, including shared navigation/footer content. Don't publish unless asked.
 
 Compare the rendered site with the reference at desktop and mobile sizes. Verify that fields remain editable and that longer text and different repeater counts still work. Fix the reusable implementation, not just the one captured arrangement.
+
+In multi-page runs, give this full check to every page that introduced or changed a definition, and to each page family's representative page. Compare the remaining pages with their source at desktop size. The run is complete when every page in `camoxify-progress.md` is verified.
+
+Once the run is complete, suggest running `camox-expand` to build blocks for jobs the site will need next.