camox 0.43.0 → 0.45.0

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

@@ -9,15 +9,15 @@ When asked to add a section, also place an instance after dev-server discovery u
 Use one `.tsx` file per block in `src/blocks/`, a named `block` export (not default), a named function component, and Tailwind styling.
 
 ```tsx
-import { Type, createBlock } from "camox/createBlock";
+import { createBlock } from "camox/createBlock";
 
 const myBlock = createBlock({
   id: "my-block",
   title: "My Block",
   description: "A page introduction with an editable heading.",
-  content: {
-    title: Type.String({ default: "Welcome" }),
-  },
+  content: (field) => ({
+    title: field.string({ default: "Welcome" }),
+  }),
   component: MyBlockComponent,
   toMarkdown: (c) => [`# ${c.title}`],
 });
@@ -33,34 +33,33 @@ function MyBlockComponent() {
 export { myBlock as block };
 ```
 
-For DOM listeners, scrolling, scripts, or widgets, read [DOM integrations](dom-integrations.md). Preview DOM lives in an iframe; use `getElementContext` from `camox/dom`, not component-global `window` or `document`.
+For DOM listeners, scrolling, scripts, widgets, or JavaScript-driven animation, read [DOM integrations](dom-integrations.md). Preview DOM lives in an iframe; use `getElementContext` from `camox/dom`, not component-global `window` or `document`.
 
 ## The `createBlock` options
 
-| Option        | Required | Description                                                                                   |
-| ------------- | -------- | --------------------------------------------------------------------------------------------- |
-| `id`          | yes      | Unique kebab-case identifier matching the filename without extension.                         |
-| `title`       | yes      | CMS display name.                                                                             |
-| `description` | yes      | Agent guidance on placement, expected content, and tone.                                      |
-| `content`     | yes      | Field names mapped to `Type.*` schemas for editable content.                                  |
-| `settings`    | no       | Settings-panel fields; only `Type.Enum` and `Type.Boolean`.                                   |
-| `layoutOnly`  | no       | If true, restricts placement to layouts and hides the type from the add-block picker.         |
-| `synced`      | no       | Defaults to false. Shares content/settings across instances within an environment; see below. |
-| `component`   | yes      | Named React function component.                                                               |
-| `toMarkdown`  | yes      | `(c, s) => [...]` markdown builder; see below.                                                |
+| Option        | Required | Description                                                                                  |
+| ------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `id`          | yes      | Unique kebab-case identifier matching the filename without extension.                        |
+| `title`       | yes      | CMS display name.                                                                            |
+| `description` | yes      | Agent guidance on placement, expected content, and tone.                                     |
+| `content`     | yes      | `(field) => ({ ... })`: field names mapped to `field.*` builders for editable content.       |
+| `settings`    | no       | `(setting) => ({ ... })`: settings-panel options; only `setting.enum` and `setting.boolean`. |
+| `layoutOnly`  | no       | If true, restricts placement to layouts and hides the type from the add-block picker.        |
+| `synced`      | no       | Defaults to false. Shares content/settings across placements; see below.                     |
+| `component`   | yes      | Named React function component.                                                              |
+| `toMarkdown`  | yes      | `(c, s) => [...]` markdown builder; see below.                                               |
 
 ## Synced blocks (`synced`, optional)
 
-`synced: true` shares content and settings, including nested repeater items and their settings, across every instance of the block **type** within one environment. Dev and production remain independent. Synced blocks have purple editor highlights.
+`synced: true` shares content and settings, including nested repeatable items and their settings, across every placement of the block **definition**. Like any content, the shared content is changed in a draft and reaches Live when the draft is published. Synced blocks have purple editor highlights.
 
 For shared navbar/footer data across layouts, use `layoutOnly: true, synced: true`. These flags are independent: synced blocks can also be ordinary page-content blocks.
 
-- Editing any instance updates the shared draft everywhere. New instances reuse existing data rather than resetting to defaults.
-- Position, placement, and deletion remain per instance; deleting one placement leaves the others.
-- Publishing a page or layout containing the block publishes shared data for all live instances. Unpublished drafts do not leak into live.
-- Enabling syncing on an existing type applies the oldest instance's data to all instances. Disabling it leaves independently editable copies.
+- Editing any placement updates the shared content everywhere. New placements reuse existing data rather than resetting to defaults.
+- Position, layout slot, and deletion remain per placement; deleting one placement leaves the others.
+- Enabling syncing on an existing type applies the oldest placement's data to all placements. Disabling it leaves independently editable copies.
 
-## Markdown Template (`toMarkdown`)
+## Markdown Representation (`toMarkdown`)
 
 Required on blocks and repeaters. Receives typed proxies `c` (content) and `s` (settings); returns entries joined with `\n\n` for AI summaries and SEO. Lines whose referenced fields are all empty, or whose condition is false, are omitted.
 
@@ -101,14 +100,14 @@ Only Boolean/Enum settings support these conditionals. A repeater's `s` refers t
 
 ## Content Field Types
 
-Import `Type` from `"camox/createBlock"`. Supply defaults for scalar fields; images/files get automatic placeholders, lists use `defaultItems`, and repeaters use their item schemas and bounds.
+`content` and a repeater's `content` receive a `field` builder; `settings` receive a `setting` builder. Each builder only offers what its context accepts: `field` has no `enum` or `boolean`, and `setting` has nothing else. Supply defaults for scalar fields; images/files get automatic placeholders (empty images paint with the stylesheet's `--camox-placeholder` and `--camox-placeholder-ink`), lists use `defaultItems`, and repeaters use their item schemas and bounds.
 
-### Type.String
+### field.string
 
 Inline-editable text supporting formatting and links while remaining a string. See [Field styling](field-styling.md) for formatting syntax and appearance customization.
 
 ```tsx
-Type.String({
+field.string({
   default: "Hello world",
   title: "Heading", // Optional label
   maxLength: 280, // Optional
@@ -117,25 +116,54 @@ Type.String({
 });
 ```
 
-### Type.Boolean and Type.Enum
+### field.icon
 
-Use in `settings` for configuration or `content` for editable values. Enum defaults must match an option key.
+Choose one Iconify collection in Vite config:
+
+```ts
+camox({ projectId: "01a15fff-627b-7fa1-938b-93ab659c1acc", icons: "lucide" });
+```
+
+Declare a non-nullable icon with a required, prefixed default, then render inline SVG:
+
+```tsx
+// In content:
+icon: field.icon({ default: "lucide:zap", title: "Icon" })
+
+// In the component (also supported as <item.Icon> inside repeaters):
+<block.Icon name="icon" className="size-6 text-brand" />
+<block.Icon name="icon" aria-label="Fast" />
+```
+
+Icons are decorative unless given `aria-label` or `aria-labelledby`. Clicking an icon in preview opens the searchable collection picker. Values remain namespaced strings; editors cannot select another collection or an empty value.
+
+Run `pnpm exec camox typegen` **before TypeScript checking in CI**, for example `camox typegen && tsc --noEmit`. This resolves Vite config without starting a server or requiring Camox login. It generates `src/camox/icons.gen.d.ts`; ensure your tsconfig includes it. Dev and build regenerate it automatically. Generation requires network access to the pinned Iconify snapshot.
+
+Camox resolves selected SVGs from that same versioned snapshot and serves them through its API. Server rendering preloads selected/default SVGs into hydration data; no visitor requests to Iconify and no rebuild is needed when content changes. Only the editor fetches collection metadata and picker previews, not a whole SVG catalog.
+
+Collection licenses still apply. SVG responses retain author/license attribution. Include any copyright notices, license text, or attribution required by your chosen collection in your site's distributed notices; Iconify does not relicense the icons. Changing collections or migrating existing icon values is not supported in v1.
+
+### setting.boolean and setting.enum
+
+Settings only: configuration choices are never block or repeater content. Enum defaults must match an option key.
 
 ```tsx
-Type.Boolean({ default: false, title: "Show background" });
-Type.Enum({
+settings: (setting) => ({
+  showBackground: setting.boolean({ default: false, title: "Show background" }),
+  alignment: setting.enum({
   default: "left",
-  options: { left: "Left", center: "Center", right: "Right" },
-  title: "Alignment",
-});
+    options: { left: "Left", center: "Center", right: "Right" },
+    title: "Alignment",
+  }),
+}),
 ```
 
-### Type.Link
+### field.link
 
 Text, destination, and new-tab toggle. Curated page links store page IDs; singleton links store fixed URLs using the existing `type: "external"` representation, which also supports site-relative URLs: `{ type: "external", href: "/pokedex", text: "Pokédex", newTab: false }`. Both page kinds appear in Studio's destination picker. Inline `[Pokédex](/pokedex)` links stay in the current tab.
 
 ```tsx
-Type.Link({
+field.link({
   default: { text: "Learn more", href: "/", newTab: false },
   title: "CTA",
 });
@@ -146,38 +174,50 @@ Type.Link({
 Files support MIME filtering. Render each type with its matching helper; asset lists are **not** repeaters.
 
 ```tsx
-Type.Image({ title: "Cover photo" });
-Type.ImageList({ defaultItems: 6, title: "Gallery images" });
-Type.File({ accept: ["application/pdf"], title: "PDF Document" });
-Type.FileList({ accept: ["application/pdf"], defaultItems: 0, title: "Documents" });
+field.image({ title: "Cover photo" });
+field.imageList({ defaultItems: 6, title: "Gallery images" });
+field.file({ accept: ["application/pdf"], title: "PDF Document" });
+field.fileList({ accept: ["application/pdf"], defaultItems: 0, title: "Documents" });
 ```
 
-### Type.Embed
+### field.embed
 
 A URL validated against a regex. A nonmatching default throws at definition time.
 
 ```tsx
-Type.Embed({
+field.embed({
   pattern: "https:\\/\\/(www\\.)?(youtube\\.com|youtu\\.be)\\/.+",
   default: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
   title: "YouTube URL",
 });
 ```
 
-### Type.Repeater
+### field.artifact
+
+A sandboxed web page stored as content, for bespoke visuals and widgets. Read [Artifacts](artifacts.md) before declaring one.
+
+```tsx
+field.artifact({ size: "fill", title: "Hero visual" });
+field.artifact({ size: "fill", data: ["headline", "variant"] }); // shares sibling fields and settings
+```
+
+### field.repeater
 
 Structured items with their own content, optional settings, and required `toMarkdown`. `minItems` must be at least 1; repeaters cannot be empty. Nest repeaters in an item's `content` when needed.
 
 ```tsx
-Type.Repeater({
-  content: {
-    name: Type.String({ default: "Feature" }),
-    description: Type.String({ default: "Description" }),
-  },
+field.repeater({
+  content: (field) => ({
+    name: field.string({ default: "Feature" }),
+    description: field.string({ default: "Description" }),
+  }),
+  settings: (setting) => ({
+    highlighted: setting.boolean({ default: false, title: "Highlighted" }),
+  }),
   minItems: 1,
   maxItems: 10,
   title: "Features",
-  toMarkdown: (c) => [`### ${c.name}`, c.description],
+  toMarkdown: (c, s) => [`### ${c.name}`, s.highlighted(c.description)],
 });
 ```
 
@@ -192,7 +232,7 @@ Field renderers receive `(props, data)`:
 
 ### Strings — `block.Field`
 
-`name` must select a `Type.String` field. `props.children` contains Camox's rendered inline markup.
+`name` must select a `field.string` field. `props.children` contains Camox's rendered inline markup.
 
 ```tsx
 <myBlock.Field name="title">{(props) => <h1 {...props} />}</myBlock.Field>
@@ -206,7 +246,7 @@ For `textStyle` and `linkStyle`, read [Field styling](field-styling.md).
 
 ### Links — `block.Link`
 
-Use `Link` from `camox/navigation`, not `<a>`, for client-side internal navigation. `props` supplies `to`, `target`, and `rel`; raw `data` exposes `{ text, href, newTab }`.
+Use `Link` from `camox/navigation`, not `<a>`, for client-side internal navigation. `props` supplies `to`, `target`, and `rel`; raw `data` exposes `{ text, href, newTab }`. Render link fields as they come; a path written in code goes through `useLocalizedHref` (see [Localization](localization.md#internal-links-stay-in-the-locale)).
 
 ```tsx
 import { Link } from "camox/navigation";
@@ -228,12 +268,15 @@ import { Link } from "camox/navigation";
 
 ### Repeaters — `block.Repeater`
 
-The callback receives an item-scoped API with the same `.Field`, `.Link`, `.Image`, `.File`, `.Embed`, `.ImageList`, `.FileList`, and `.Repeater` methods.
+The callback signature is `(item, index) => ReactNode`:
+
+- `item` is an item-scoped API with the same `.Field`, `.Link`, `.Image`, `.File`, `.Embed`, `.Artifact`, `.ImageList`, `.FileList`, and `.Repeater` methods.
+- `index` is the item's zero-based position in the current repeater. Use it for position-based behavior such as first-item styling, numbering, or matching tabs to panels without comparing editable text. It changes when items are reordered or removed; it is not a stable item ID.
 
 ```tsx
 <myBlock.Repeater name="features">
-  {(item) => (
-    <div>
+  {(item, index) => (
+    <div className={index === 0 ? "featured" : undefined}>
       <item.Field name="name">{(props) => <h3 {...props} />}</item.Field>
       <item.Field name="description">{(props) => <p {...props} />}</item.Field>
     </div>
@@ -241,7 +284,7 @@ The callback receives an item-scoped API with the same `.Field`, `.Link`, `.Imag
 </myBlock.Repeater>
 ```
 
-Nested repeaters use the item-scoped `.Repeater`:
+Nested repeaters use the item-scoped `.Repeater` with the same `(item, index)` callback signature. Each index is local to its repeater, so the inner index starts at `0` for each parent item. Omit the index parameter when it is not needed:
 
 ```tsx
 <footer.Repeater name="columns">
@@ -265,7 +308,7 @@ Use the matching helper, **not `block.Repeater`**. Its `(props, data)` callback
 
 ### Settings — `block.useSetting`
 
-Read settings inside the component with `myBlock.useSetting("theme")`.
+Read settings inside the component with `myBlock.useSetting("name")`. For example, `myBlock.useSetting("scheme")` returns the color scheme an editor picked in the block's "Color scheme" setting.
 
 ### Detached rendering — `block.Detached`
 
@@ -274,7 +317,7 @@ Renders outside the block's DOM container for fixed/floating elements. Spread it
 ```tsx
 <myBlock.Detached>
   {(props) => (
-    <div {...props} className="fixed top-0 left-0 right-0 z-50">
+    <div {...props} className="fixed top-0 right-0 left-0 z-50">
       {/* floating content */}
     </div>
   )}

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

@@ -1,6 +1,6 @@
 # Camox CLI common guidance
 
-Use the Camox CLI for CRUD operations on Pages, Block instances, Layout assignments, metadata, drafts, and published content. Use the code references instead when changing Block Definitions or Layout Definitions in `src/blocks/` or `src/layouts/`.
+Use the Camox CLI for CRUD operations on Pages, Blocks, Layout assignments, and metadata. Use the code references instead when changing Block Definitions or Layout Definitions in `src/blocks/` or `src/layouts/`.
 
 If a change should be visible without a code deployment, it is usually a CLI content operation. Some requests require both code and CLI work: define the new type first, wait for the dev server to discover it, then create or assign its content through the CLI.
 
@@ -26,13 +26,25 @@ Before a write, verify the relevant subcommand's `--help` unless already checked
 
 Use root or group help only to discover unfamiliar commands. Reuse verified help within the session; recheck if the installed version changes. Installed help overrides these examples—do not guess commands or flags.
 
-## Draft-first workflow
+## Dev-first workflow
 
-By default, reads and writes operate on the draft in the current developer's isolated dev Environment. Make content changes in draft, summarize them for review, and publish only after the user asks or approves.
+Every command reads and writes the current developer's development draft, never Live. Make content changes there and summarize them for review; they reach Live only when the draft is published (see [CLI Publishing](cli-publishing.md)). Don't publish unless the user asks.
 
-- Omit `--live` while editing. `--live` only reads the published snapshot.
-- Omit `--production` unless the user explicitly asks to operate on the production Environment.
-- Publishing a draft and replicating an Environment are different operations. Read the Environment reference before using `env push` or `env pull`.
+- If a command fails with "run the site locally first", the development draft doesn't exist yet: the dev server creates it on its first sync after `camox login`.
+
+## Verify changes in a browser
+
+CLI credentials and browser sessions are separate. A fresh browser isn't signed in, even when CLI writes succeeded.
+
+1. Start the app's dev server and check `{{CAMOX_CMD}} preview --help`.
+2. Generate a handoff for the page you changed:
+   `{{CAMOX_CMD}} preview --url http://localhost:3000/about --json`
+   (Use the actual port; add `--cwd apps/site` in a monorepo.)
+3. Open the returned `url` in your verification browser, not a separate default browser.
+4. Wait for `[data-camox-preview="ready"]`. Its text identifies the project and the development draft; the server has loaded authenticated content. `[data-camox-preview="error"]` means verification failed, not that the write failed.
+5. Inspect the changed content.
+
+The URL is a single-use sign-in credential valid for three minutes. Do not share, commit, or include it in reports. Generate a new URL if expired or consumed. Only loopback HTTP(S) destinations are supported; previewing a deployed site is intentionally unsupported. The SDK must support this handoff: if the ready marker never appears, check the installed SDK version rather than assuming the write failed. A project or backend mismatch requires correcting `--cwd` or `--url` (or restarting a dev server running under another account).
 
 ## Write grounded content
 

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

@@ -1,8 +1,8 @@
 # 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.
+Read [cli-common.md](cli-common.md) first for `{{CAMOX_CMD}}`, help verification, and the dev-first workflow.
 
-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).
+Use these commands for Pages, metadata, Layout assignments, Blocks and their Content, and review. 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
 
@@ -10,29 +10,33 @@ Use these commands for Pages, metadata, Layout assignments, Block instances and
 
 ```sh
 {{CAMOX_CMD}} layouts list
-{{CAMOX_CMD}} pages create --path-segment about --layout-id 39
+{{CAMOX_CMD}} pages create --path-segment about --layout-id default
 ```
 
+`--layout-id` takes a Layout's name, the `layoutId` listed by `layouts list`.
+
 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
+{{CAMOX_CMD}} pages set-seo --path /about --meta-title "About us" --meta-description "Meet the team."
+{{CAMOX_CMD}} pages set-seo --id <PAGE_UUID> --meta-description ""
+{{CAMOX_CMD}} pages set-seo --id <PAGE_UUID> --ai-seo on
+{{CAMOX_CMD}} pages set-seo --id <PAGE_UUID> --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.
+`set-seo` accepts exactly one of `--id` or `--path` and requires at least one of
+`--meta-title`, `--meta-description` or `--ai-seo`. The meta title and
+description are one group: writing either field makes both manual, keeping the
+current value of the other, and cannot be combined with `--ai-seo on`.
+`--ai-seo off` keeps current metadata as manual; `--ai-seo on` schedules
+asynchronous generation, so read the Page again to inspect results. An empty
+meta title blocks publishing.
 
-Metadata edits affect only the draft, even with `--production`. Read published
-metadata with `pages get --live`; publish only after user approval.
+Metadata edits apply right away in the development draft. Read metadata
+with `pages get`.
 
 ## Blocks
 
@@ -45,13 +49,41 @@ Look up the Page before creating or moving Blocks so you have its `id`, current
 {{CAMOX_CMD}} blocks describe --type hero
 ```
 
+### Find shared navigation and footer Blocks
+
+`pages get` returns page-owned Blocks, not the Layout's shared shell. Inspect
+the Layout to discover navigation, footer, and other layout-owned block IDs:
+
+```sh
+{{CAMOX_CMD}} layouts list
+{{CAMOX_CMD}} layouts get --layout-id default
+{{CAMOX_CMD}} blocks get --id <BLOCK_UUID>
+{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{"title": "Updated title"}'
+```
+
+Pass the Layout's name, the `layoutId` from `layouts list` (also the Page's
+`layoutId`), to `layouts get --layout-id`. The response
+includes `blocks` with `id`, `type`, `slot`, and Content, plus
+`layout.beforeBlockIds` and `layout.afterBlockIds`. Pass a Block's `id` to
+`blocks get` and `blocks edit`; do not use the Layout ID or Block type.
+Inspect the Block's schema and current Content before editing, and preserve
+repeatable items as described below.
+
+Keep `--project` and `--cwd` consistent across the discovery and editing
+commands. Shared shell edits affect every Page using that Layout,
+and synced Block types can share Content across Layouts.
+
 ### Create and position a Block
 
 ```sh
-{{CAMOX_CMD}} blocks create --page-id 25 --type hero --content '{...}' --position first
+{{CAMOX_CMD}} blocks create --page-id <PAGE_UUID> --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.
+Creation initializes omitted Content and Settings fields from the Block definition's defaults, including when `--content '{}'` is supplied. Explicit values are not replaced by defaults and must satisfy the field's JSON Schema; defaults do not merge into a supplied Link object. Omitted Repeaters initialize their default item count (or minimum count) with item defaults. Supplied arrays use exactly those items and must satisfy `minItems`/`maxItems`; `[]` is accepted only when the minimum allows it. Asset placeholders are not stored. Existing synced Block data still takes precedence for synced types.
+
+Content and Settings writes are validated server-side against the development draft's definitions before mutation. Validation errors include field paths. String fields contain Markdown strings (not rich-text JSON objects); Embed fields contain strings matching their pattern. Assets use managed `{ "_fileId": "<file UUIDv7>" }` references, with asset lists stored as arrays of references. Asset normalization drops hydrated URL metadata and converts placeholders to null.
+
+Updates validate only submitted fields, so unrelated historical invalid values do not prevent an edit. New records validate after defaults are applied. Unknown properties follow the schema's `additionalProperties` policy (allowed when unspecified); missing definitions retain legacy permissive behavior. Saved snapshots are not retroactively migrated or revalidated when restored.
 
 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.
 
@@ -74,74 +106,76 @@ 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"}'
+{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{"headline": "New headline"}'
 ```
 
-### Edit repeatable Content safely
+### Set string fields from files
 
-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:
+Use `--field-file <NAME>=<PATH>` on `blocks create` and `blocks edit` to set a top-level string field to a file's raw contents, without escaping it into JSON. It suits long Markdown and [Artifact](artifacts.md) sources. Repeat the flag to set several fields. It merges with `--content`; when both set the same field, the file wins. On `blocks create`, pass `--content`, `--field-file`, or both.
 
 ```sh
-{{CAMOX_CMD}} blocks get --id 99
-
-{{CAMOX_CMD}} blocks edit --id 99 --content '{
-  "items": [
-    {"_itemId": 401},
-    {"_itemId": 402, "answer": "Updated answer."},
-    {"_itemId": 403}
-  ]
-}'
+{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{"title": "Orbit"}' --field-file source=./orbit.html
 ```
 
-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
-```
+Every file is read before anything is written, so a missing or unreadable file fails the command without changing anything.
 
-`blocks get-many` returns the same bundle shape as `blocks get`, in requested-id order.
+To build an Artifact source, loop until it renders correctly:
 
-## Review and publishing
+1. Write the source to a local file, such as `./orbit.html`.
+2. Push it with `blocks edit --id <ID> --field-file <NAME>=./orbit.html` (or `blocks create` for a new Block).
+3. Check the rendered page with `{{CAMOX_CMD}} preview`, following [CLI common guidance](cli-common.md).
+4. Edit the file and push again.
 
-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)).
+### Edit repeatable Content safely
 
-### Review draft and live state
+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}} 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
+{{CAMOX_CMD}} blocks get --id <BLOCK_UUID>
 
-```sh
-{{CAMOX_CMD}} pages publish --path /pricing
+{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{
+  "items": [
+    {"_itemId": "<ITEM_UUID_1>"},
+    {"_itemId": "<ITEM_UUID_2>", "answer": "Updated answer."},
+    {"_itemId": "<ITEM_UUID_3>"}
+  ]
+}'
 ```
 
-`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:
+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}} pages publish --path /pricing --no-layout
+{{CAMOX_CMD}} blocks get-many --id <BLOCK_UUID> --id <BLOCK_UUID> --id <BLOCK_UUID>
 ```
 
-Publish only after the user asks or approves, not automatically after editing a draft.
-
-### Unpublish or discard drafts
+`blocks get-many` returns the same bundle shape as `blocks get`, in requested-id order.
 
-Remove a Page from live without deleting its draft:
+## Locales
 
 ```sh
-{{CAMOX_CMD}} pages unpublish --path /pricing
+{{CAMOX_CMD}} locales list
+{{CAMOX_CMD}} locales add --tag de
+{{CAMOX_CMD}} pages get --path /pricing --locale de
+{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{"title":"Hallo"}' --locale de
+{{CAMOX_CMD}} locales remove --tag de
 ```
 
-Reset a draft to its current live snapshot without changing live:
+Locales are content: adding or removing one changes the development draft, and
+publishing puts the change on Live. Adding a locale gives every Page, Block,
+repeatable item, synced Block and collection record a copy in it, keeping its
+id, which Camox translates in the background. Every later change to the default
+locale is translated into every other locale of the draft; edits made with
+`--locale` aren't translated anywhere. `pages`,
+`blocks edit/get/create/move/delete` and `layouts get` take `--locale <TAG>` to
+read or write that copy; without it they act on the default locale. Removing a locale deletes its content from Live for good once
+published. `locales set-default-tag --tag en-GB` corrects the default locale's
+tag, only while it's the only locale.
+
+## Review
 
 ```sh
-{{CAMOX_CMD}} pages discard-changes --path /pricing
+{{CAMOX_CMD}} pages get --path /pricing
+{{CAMOX_CMD}} blocks get --id <BLOCK_UUID>
 ```
 
-Both commands accept exactly one of `--id` or `--path`. Discarding fails if the Page has never been published.
+Reads return the content of the development draft, which shows Live wherever it changes nothing. Every edit lands in the development draft right away and reaches Live only when the draft is published (see [CLI Publishing](cli-publishing.md)).

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

@@ -0,0 +1,26 @@
+# Publishing with the Camox CLI
+
+Read [cli-common.md](cli-common.md) first for `{{CAMOX_CMD}}`, help verification, and the dev-first workflow.
+
+Every command works in the current developer's development draft. Its changes reach Live, the public site, only when the draft is published. Agents in parallel worktrees share their developer's development draft, so publishing or discarding it covers all of their changes.
+
+Don't publish or discard unless the user asks you to.
+
+```sh
+{{CAMOX_CMD}} status                   # whether the development draft exists, and how many changes it holds
+{{CAMOX_CMD}} publish                  # what publishing would do, with a token
+{{CAMOX_CMD}} publish --confirm TOKEN  # publish the whole draft to Live
+{{CAMOX_CMD}} discard --yes            # empty the development draft; Live is untouched
+```
+
+`publish` lists, in order:
+
+- **Blockers**: problems to fix in the draft before it can be published, such as an empty required reference or a page without a meta title. Definitions that differ from Live's are blockers too: local code changed a block, layout, or collection, and only a release can ship it to Live. Don't try to fix those through content; tell the user a release is needed.
+- **Conflicts**: content Live changed or deleted since the draft changed it, with who published it and when. Publishing overwrites Live's version.
+- **Lost changes**: changes publishing drops because what they belong to is gone.
+- **Warnings**: the same problems already on Live. They don't block.
+- **Changes**: everything the draft creates, changes, or deletes.
+
+Show the user the list, especially conflicts and lost changes, and get their confirmation before passing the token to `publish --confirm`. If Live changed since the list was printed, nothing is published: the command prints the new list with a new token and fails with `CONFLICTS_CHANGED`. Review the new list with the user before confirming again.
+
+After publishing, the development draft stays open and empty. `discard` empties it without publishing and can't be undone; it requires `--yes` when not run in a terminal.

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

@@ -37,6 +37,33 @@ function 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).
 
+## Pausing JavaScript-driven animation
+
+The studio Canvas shows many pages at once and pauses the previews nobody is looking at. Camox pauses their CSS animations, transitions and media itself, but cannot stop JavaScript running in your block: WebGL shaders, `<canvas>` drawing, `requestAnimationFrame` loops or animation libraries. Use `usePreviewPaused` from `camox/dom` with a ref to an element the component renders, and stop that work while it returns true. It is always false outside Camox preview.
+
+```tsx
+import { usePreviewPaused } from "camox/dom";
+import { useEffect, useRef } from "react";
+
+function Shader() {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const paused = usePreviewPaused(canvas);
+
+  useEffect(() => {
+    if (paused) return;
+    let frame = requestAnimationFrame(function draw(time) {
+      // Draw a frame of the shader at `time`.
+      frame = requestAnimationFrame(draw);
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [paused]);
+
+  return <canvas ref={canvas} />;
+}
+```
+
+The element must render together with the component calling the hook, not conditionally later.
+
 ## 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.