camox 0.22.0 → 0.24.0

package/skills/camox-block/SKILL.md

@@ -78,7 +78,8 @@ toMarkdown: (c) => [`# ${c.title}`, c.description, c.cta];
 - **Image**: `![alt](filename)`
 - **File**: `[filename](url)`
 - **Embed**: raw URL string
-- **RepeatableItem**: each item rendered via its own `toMarkdown` (if set on the RepeatableItem options), items joined with `\n\n`
+- **Repeater**: each item rendered via its own `toMarkdown` (if set on the Repeater options), items joined with `\n\n`
+- **ImageList / FileList**: each asset rendered as a markdown bullet
 - **Boolean/Enum**: raw string value
 
 Lines where ALL referenced fields resolve to empty are omitted from output.
@@ -98,13 +99,13 @@ createBlock({
   content: { ... },
 })
 
-// Statistics — RepeatableItem with its own toMarkdown
+// Statistics — Repeater with its own toMarkdown
 createBlock({
   toMarkdown: (c) => [`## ${c.subtitle}`, c.description, c.statistics],
   content: {
     subtitle: Type.String({ default: "..." }),
     description: Type.String({ default: "..." }),
-    statistics: Type.RepeatableItem({
+    statistics: Type.Repeater({
       content: {
         number: Type.String({ default: "100M+" }),
         label: Type.String({ default: "pages served" }),
@@ -142,7 +143,7 @@ toMarkdown: (c, s) => [
 ];
 ```
 
-Only `Type.Boolean` and `Type.Enum` settings can be used this way — trying to reference any other setting is a type error. On a `RepeatableItem`'s own `toMarkdown`, `s` refers to the item's own `settings` (not the parent block's).
+Only `Type.Boolean` and `Type.Enum` settings can be used this way — trying to reference any other setting is a type error. On a `Repeater`'s own `toMarkdown`, `s` refers to the item's own `settings` (not the parent block's).
 
 ## Content Field Types
 
@@ -197,31 +198,38 @@ Type.Link({
 
 ### Type.Image
 
-A single image, or a flat array of images.
+A single image — render with `block.Image`.
 
 ```tsx
-// Single image — render with block.Image
 Type.Image({ title: "Cover photo" });
+```
+
+### Type.ImageList
+
+A flat array of images — render with `block.ImageList` (NOT `block.Repeater`).
 
-// Multiple images — render with block.MultipleAssets (NOT block.Repeater)
-Type.Image({ multiple: true, defaultItems: 6, title: "Gallery images" });
+```tsx
+Type.ImageList({ defaultItems: 6, title: "Gallery images" });
 ```
 
 ### Type.File
 
-A file upload, with MIME type filtering.
+A single file upload, with MIME type filtering — render with `block.File`.
 
 ```tsx
-// Single file — render with block.File
 Type.File({
   accept: ["application/pdf"],
   title: "PDF Document",
 });
+```
 
-// Multiple files — render with block.MultipleAssets (NOT block.Repeater)
-Type.File({
+### Type.FileList
+
+A flat array of files — render with `block.FileList` (NOT `block.Repeater`).
+
+```tsx
+Type.FileList({
   accept: ["application/pdf"],
-  multiple: true,
   defaultItems: 0,
   title: "Documents",
 });
@@ -241,12 +249,12 @@ Type.Embed({
 
 The `default` must match the `pattern` — an error is thrown at definition time otherwise.
 
-### Type.RepeatableItem
+### Type.Repeater
 
 An array of structured items. Each item is an object with its own fields. This is how you create lists of things (testimonials, features, stats, links...).
 
 ```tsx
-Type.RepeatableItem({
+Type.Repeater({
   content: {
     name: Type.String({ default: "Feature" }),
     description: Type.String({ default: "Description" }),
@@ -258,15 +266,15 @@ Type.RepeatableItem({
 });
 ```
 
-The `toMarkdown` option on RepeatableItem defines how each item is rendered as markdown when the parent block's `toMarkdown` references this field. It is required, same as on the block itself.
+The `toMarkdown` option on Repeater defines how each item is rendered as markdown when the parent block's `toMarkdown` references this field. It is required, same as on the block itself.
 
-Repeatable items can be nested — an item can contain another RepeatableItem:
+Repeaters can be nested — an item can contain another Repeater:
 
 ```tsx
-columns: Type.RepeatableItem({
+columns: Type.Repeater({
   content: {
     title: Type.String({ default: "Column" }),
-    links: Type.RepeatableItem({
+    links: Type.Repeater({
       content: {
         link: Type.Link({ default: { text: "Link", href: "#", newTab: false } }),
       },
@@ -359,7 +367,7 @@ The optional second argument `data` exposes raw values `{ text, href, newTab }`
 </myBlock.Embed>
 ```
 
-### Rendering RepeatableItem fields — `block.Repeater`
+### Rendering Repeater fields — `block.Repeater`
 
 ```tsx
 <myBlock.Repeater name="features">
@@ -372,7 +380,7 @@ The optional second argument `data` exposes raw values `{ text, href, newTab }`
 </myBlock.Repeater>
 ```
 
-Inside a Repeater, the `item` callback argument exposes the same `.Field`, `.Link`, `.Image`, `.File`, `.Embed`, `.MultipleAssets`, and `.Repeater` methods — scoped to that item. This is how nested repeaters work too:
+Inside a Repeater, the `item` callback argument exposes the same `.Field`, `.Link`, `.Image`, `.File`, `.Embed`, `.ImageList`, `.FileList`, and `.Repeater` methods — scoped to that item. This is how nested repeaters work too:
 
 ```tsx
 <footer.Repeater name="columns">
@@ -384,27 +392,27 @@ Inside a Repeater, the `item` callback argument exposes the same `.Field`, `.Lin
 </footer.Repeater>
 ```
 
-### Multiple images / files — `block.MultipleAssets`
+### Image and File lists — `block.ImageList` / `block.FileList`
 
-For `Type.Image({ multiple: true })` or `Type.File({ multiple: true })`, use `MultipleAssets` (NOT `Repeater`). The render-prop is the same shape as `block.Image` / `block.File` — `(props, data) => …` — invoked once per asset:
+For `Type.ImageList` use `block.ImageList`; for `Type.FileList` use `block.FileList` (NOT `block.Repeater`). The render-prop is the same shape as `block.Image` / `block.File` — `(props, data) => …` — invoked once per asset:
 
 ```tsx
 // Top-level
-<gallery.MultipleAssets name="images">
+<gallery.ImageList name="images">
   {(props) => <img {...props} className="rounded-lg" />}
-</gallery.MultipleAssets>
+</gallery.ImageList>
 
-// Nested inside a Type.RepeatableItem
+// Nested inside a Type.Repeater
 <paragraphGrid.Repeater name="paragraphs">
   {(item) => (
-    <item.MultipleAssets name="logos">
+    <item.ImageList name="logos">
       {(props) => <img {...props} className="size-10 object-contain" />}
-    </item.MultipleAssets>
+    </item.ImageList>
   )}
 </paragraphGrid.Repeater>
 ```
 
-`Repeater` is only for `Type.RepeatableItem` arrays. Trying to use `Repeater` on a `Type.Image`/`File` with `multiple: true` is a TypeScript error.
+`Repeater` is only for `Type.Repeater` arrays. Trying to use `Repeater` on an `ImageList` / `FileList` is a TypeScript error.
 
 ### Reading settings — `block.useSetting`
 
@@ -439,6 +447,6 @@ Renders content outside the block's DOM container. Useful for fixed/floating ele
 5. **Description is for the AI.** Write the `description` as guidance for an LLM — explain when to use this block, what kind of content it's for, and where it fits on a page.
 6. **`toMarkdown` is required.** Every block must define how its content renders as markdown. Use the builder function `(c) => [...]` and reference content fields via `c.fieldName`.
 7. **Settings = Enum and Boolean only.** Keep settings simple. Use `content` for everything the user edits inline.
-8. **RepeatableItem minItems >= 1.** You can't have an empty repeatable — there's always at least one item.
+8. **Repeater minItems >= 1.** You can't have an empty repeater — there's always at least one item.
 9. **Import path is `"camox/createBlock"`.** Both `Type` and `createBlock` come from this import.
 10. **Use Tailwind CSS for styling.** All example blocks use Tailwind utility classes. Follow the same patterns: `container mx-auto px-4` for centered content, responsive breakpoints, etc.

package/skills/camox-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: camox-cli
-description: "How to read or modify the website's content (pages and the sections inside them) via the Camox CLI. This is a Camox-powered site, so any request about its content — even when phrased generically — is a Camox operation. Use this skill whenever the user wants to add, remove, rename, reorder, or change anything visible on the site: a new page or route, a section / hero / footer / etc., the title or wording shown to visitors, what appears at a URL, the SEO title or social-share preview, the structure shared across pages, etc. Trigger broadly — on phrases like 'add a page', 'put a hero at the top', 'change the headline', 'move this section', 'what's on /about', 'fix the meta title', 'rename this route', 'why does this show up on every page' — and on similar requests even when the user doesn't say 'page', 'block', 'layout', 'CMS', 'Camox', or 'CLI'. When in doubt and the request touches site content, load this skill."
+description: "How to read or modify the website's content (pages and the sections inside them) via the Camox CLI. This is a Camox-powered site, so any request about its content — even when phrased generically — is a Camox operation. Use this skill whenever the user wants to add, remove, rename, reorder, or change anything visible on the site: a new page or route, a section / hero / footer / etc., the title or wording shown to visitors, what appears at a URL, the SEO title or social-share preview, the structure shared across pages, etc. Also covers promoting or syncing content between the dev and production environments (push to prod, pull from prod, check whether the two envs are in sync). Trigger broadly — on phrases like 'add a page', 'put a hero at the top', 'change the headline', 'move this section', 'what's on /about', 'fix the meta title', 'rename this route', 'why does this show up on every page', 'push to production', 'promote my changes to prod', 'pull from production', 'sync dev with prod' — and on similar requests even when the user doesn't say 'page', 'block', 'layout', 'environment', 'CMS', 'Camox', or 'CLI'. When in doubt and the request touches site content or the dev/prod split, load this skill."
 ---
 
 # Using the Camox CLI
@@ -92,6 +92,24 @@ See **Block positioning** below for the full set of options.
 # Use --parent-page-id <ID> to nest the page under another route.
 ```
 
+### Promote dev to production (or pull production back into dev)
+
+The `env` group replicates content in bulk between your dev environment and production — the same two operations the studio's environment menu exposes. Use this when the user wants to publish a batch of dev changes all at once, or wipe dev and start from the live site.
+
+```sh
+# Inspect both directions before committing. Shows whether push/pull are
+# currently safe, and lists any block-definition / layout divergences if not.
+{{CAMOX_CMD}} env check
+
+# Overwrite production with your dev environment.
+{{CAMOX_CMD}} env push --yes
+
+# Overwrite your dev environment with production.
+{{CAMOX_CMD}} env pull --yes
+```
+
+`--yes` (or `-y`) is required on `push` / `pull` — both replace every page, block, and file in the target environment and the change cannot be undone. See **Environments: dev vs production** below for when to use this vs the per-command `--production` flag.
+
 ## Block positioning
 
 `blocks create` and `blocks move` accept the same set of positioning flags. **Pass at most one** — combining them is rejected. `move` requires one (use `--position last` to send a block to the end); `create` defaults to appending at the end if you pass none.
@@ -107,11 +125,15 @@ See **Block positioning** below for the full set of options.
 
 Prefer the high-level flags (`--position`, `--after-id`, `--before-id`) — they read naturally and don't require you to know the fractional-index format. The `--after-position` / `--before-position` flags exist for cases where you already have a key in hand (e.g. piping output between commands).
 
-## The `--production` flag
+## Environments: dev vs production
+
+Every project has two environments: a per-user, isolated **dev** environment that the local dev server reads from, and the shared **production** environment that serves the live site. The CLI gives you two ways to interact with the split — pick the right one for what the user is asking.
 
-By default, every command runs against the **dev environment** — a per-user, isolated copy of the CMS that the dev server reads from. Changes you make here do not affect the live site, so dev is the safe place to experiment.
+### Per-command: the `--production` flag
 
-Pass `--production` to target the **live CMS** instead:
+By default, every command runs against the dev environment. Changes you make here do not affect the live site, so dev is the safe place to experiment.
+
+Pass `--production` to target the live CMS instead, one command at a time:
 
 ```sh
 {{CAMOX_CMD}} pages list --production
@@ -120,6 +142,20 @@ Pass `--production` to target the **live CMS** instead:
 
 Only use `--production` when the user has explicitly asked to operate on live content. For everything else — exploration, tentative edits, anything you'd want to be able to throw away — stay on the default dev environment.
 
+### Bulk replication: the `env` group
+
+When the user wants to **promote a batch of dev changes to production** (or do the inverse — wipe dev and start from production), use the env group instead of running many commands with `--production`:
+
+```sh
+{{CAMOX_CMD}} env check        # report compatibility of both push and pull
+{{CAMOX_CMD}} env push --yes   # overwrite production with dev
+{{CAMOX_CMD}} env pull --yes   # overwrite dev with production
+```
+
+`env check` returns `{ push: { compatible, reasons }, pull: { compatible, reasons } }`. The `reasons` array is empty when that direction is safe; otherwise each entry names a divergence (a block type or layout that exists in one env but not the other, or a block-definition schema mismatch). Fix the divergence first — replicate will refuse with `FAILED_PRECONDITION` and the same reasons in `data.reasons` if you don't.
+
+`env push` and `env pull` require `--yes` (or `-y`) because they replace the target environment's entire content. Without it the command refuses and prints what it would have done.
+
 ## Don't write slop — build understanding first
 
 Anything you create with this CLI ends up on a real website read by real people. **Never invent generic filler copy** ("Welcome to our amazing platform", "Lorem ipsum"-grade headlines, plausible-sounding-but-fabricated stats, made-up testimonials, fake company names). That kind of content is worse than nothing — it ships, it gets indexed, and the user has to clean it up.