@puckeditor/cli 0.24.0-canary.301a0304

package/dist/docs/api-reference/theming/fields.md

@@ -0,0 +1,70 @@
+# Fields
+
+Use the following CSS properties for theming Puck's fields.
+
+```css
+.Container {
+  --puck-field-radius: 32px;
+  --puck-field-color-border: transparent;
+  --puck-field-color-bg: #f0f0f0;
+}
+```
+
+## CSS properties
+
+Defaults shown as `var(--puck-...)` reference [global tokens](/docs/api-reference/theming/global). See [computed values](/docs/api-reference/theming/computed-values#fields) for the values they resolve to.
+
+These apply to every field type; the sections below cover tokens specific to individual fields.
+
+The `-hover` and `-active` variants only affect controls that respond to interaction, like selects, radio options, and array buttons. Plain text inputs change their border on hover, not their background.
+
+| Token                                | Default                                                        | Description                       |
+| ------------------------------------ | -------------------------------------------------------------- | --------------------------------- |
+| `--puck-field-color-surface`         | `var(--puck-color-surface)`                                    | Object / array body background    |
+| `--puck-field-color-bg`              | `var(--puck-color-surface)`                                    | Field control background          |
+| `--puck-field-color-bg-hover`        | `var(--puck-color-interactive-soft-hover)`                     | Control background on hover       |
+| `--puck-field-color-bg-active`       | `var(--puck-color-interactive-soft)`                           | Active or selected background     |
+| `--puck-field-color-text`            | `var(--puck-color-text)`                                       | Text color                        |
+| `--puck-field-color-text-hover`      | `var(--puck-field-color-text)`                                 | Text color on hover               |
+| `--puck-field-color-text-active`     | `var(--puck-color-interactive)`                                | Selected state text color         |
+| `--puck-field-color-border`          | `var(--puck-color-border)`                                     | Border color                      |
+| `--puck-field-color-border-hover`    | `var(--puck-color-border-hover)`                               | Border color on hover / focus     |
+| `--puck-field-color-border-focus`    | `var(--puck-color-focus-ring)`                                 | Focus ring color                  |
+| `--puck-field-color-border-dragging` | `var(--puck-color-selection-border)`                           | Border color while dragging       |
+| `--puck-field-color-bg-disabled`     | `var(--puck-color-surface-muted)`                              | Disabled control background       |
+| `--puck-field-color-border-disabled` | `var(--puck-color-border)`                                     | Disabled border color             |
+| `--puck-field-color-text-disabled`   | `var(--puck-color-text-secondary)`                             | Disabled text color               |
+| `--puck-field-border-width`          | `var(--puck-border-width-regular)`                             | Border width                      |
+| `--puck-field-radius`                | `var(--puck-radius-m)`                                         | Border radius                     |
+| `--puck-field-font-size`             | `var(--puck-font-size-xxs)`                                    | Font size                         |
+| `--puck-field-space-x`               | `calc(var(--puck-space-4) - var(--puck-border-width-regular))` | Horizontal padding                |
+| `--puck-field-space-y`               | `var(--puck-space-3)`                                          | Vertical padding                  |
+| `--puck-field-space-surface-x`       | `calc(var(--puck-space-4) - var(--puck-border-width-regular))` | Object / array horizontal padding |
+| `--puck-field-space-surface-y`       | `var(--puck-space-4)`                                          | Object / array vertical padding   |
+| `--puck-field-label-color-text`      | `var(--puck-color-text-secondary)`                             | Label text color                  |
+| `--puck-field-label-space-y`         | `var(--puck-space-3)`                                          | Label bottom spacing              |
+| `--puck-field-label-font-size`       | `var(--puck-font-size-xxs)`                                    | Label font size                   |
+| `--puck-field-label-font-weight`     | `var(--puck-font-weight-semibold)`                             | Label font weight                 |
+| `--puck-field-label-color-icon`      | `var(--puck-color-text-subtle)`                                | Label icon color                  |
+
+### Array
+
+| Token                               | Default                         | Description           |
+| ----------------------------------- | ------------------------------- | --------------------- |
+| `--puck-field-array-add-color-icon` | `var(--puck-color-interactive)` | Add button icon color |
+
+### Rich Text
+
+| Token                                        | Default                            | Description                |
+| -------------------------------------------- | ---------------------------------- | -------------------------- |
+| `--puck-field-richtext-menu-color-bg`        | `var(--puck-color-surface-subtle)` | Toolbar background         |
+| `--puck-field-richtext-menu-color-separator` | `var(--puck-color-border-muted)`   | Toolbar group separator    |
+| `--puck-field-richtext-menu-space-x`         | `6px`                              | Toolbar horizontal padding |
+| `--puck-field-richtext-menu-space-y`         | `6px`                              | Toolbar vertical padding   |
+
+### External
+
+| Token                                     | Default                            | Description              |
+| ----------------------------------------- | ---------------------------------- | ------------------------ |
+| `--puck-field-external-detach-color-bg`   | `var(--puck-color-surface-subtle)` | Detach button background |
+| `--puck-field-external-detach-color-text` | `var(--puck-color-text-muted)`     | Detach button text color |

package/dist/docs/api-reference/theming/global.md

@@ -0,0 +1,127 @@
+# Global theming
+
+CSS properties for theming the entire Puck user interface.
+
+```css
+.Container {
+  --puck-color-interactive: #0f5fff;
+  --puck-color-focus-ring: #3b82f6;
+}
+```
+
+## Colors
+
+| Token                                     | Default                                                     | Used for                                            |
+| ----------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------- |
+| `--puck-color-surface`                    | #ffffff                                      | Panel, field and menu backgrounds                   |
+| `--puck-color-surface-muted`              | #f5f5f5                                      | Canvas and disabled field backgrounds               |
+| `--puck-color-surface-subtle`             | #fafafa                                      | App layout, sidebar and toolbar backgrounds         |
+| `--puck-color-surface-inverse`            | #181818                                      | Action bar background                               |
+| `--puck-color-border`                     | #dcdcdc                                      | Default borders and dividers                        |
+| `--puck-color-border-hover`               | #767676                                      | Input border on hover and focus                     |
+| `--puck-color-border-muted`               | #efefef                                      | Subtle dividers and separators                      |
+| `--puck-color-border-inverse`             | #767676                                      | Separators on inverse surfaces                      |
+| `--puck-color-text`                       | #000000                                      | Default body and field text                         |
+| `--puck-color-text-secondary`             | #5a5a5a                                      | Field labels and disabled field text                |
+| `--puck-color-text-muted`                 | #767676                                      | Drawer categories, drag handles and zone labels     |
+| `--puck-color-text-subtle`                | #ababab                                      | Disabled icons, loaders and helper text             |
+| `--puck-color-text-inverse`               | #ffffff                                      | Text on inverse and primary surfaces                |
+| `--puck-color-interactive`                | #0158ad                                      | Primary actions, links and active states            |
+| `--puck-color-interactive-hover`          | #014292                                      | Links and primary button hover                      |
+| `--puck-color-interactive-active`         | #002c77                                      | Links and primary button active                     |
+| `--puck-color-interactive-subtle`         | #e7eef7                                      | Active plugin bar, category and outline backgrounds |
+| `--puck-color-interactive-soft`           | #f3f6fb                                      | Secondary button and selected item backgrounds      |
+| `--puck-color-interactive-soft-hover`     | #f7faff                                      | Row and item hover backgrounds                      |
+| `--puck-color-interactive-neutral-hover`  | #efefef                                      | Icon button hover background                        |
+| `--puck-color-interactive-inverse-hover`  | #6499cf                                      | Interactive hover color on inverse surfaces         |
+| `--puck-color-interactive-inverse-active` | #88b0da                                      | Interactive active color on inverse surfaces        |
+| `--puck-color-focus-ring`                 | #3479be                                      | Keyboard focus outlines                             |
+| `--puck-color-selection-bg`               | color-mix(in srgb, #cfdff0 30%, transparent) | Slot, drop zone and selected overlay background     |
+| `--puck-color-selection-border`           | #abc7e5                                      | Selected and drop zone outline borders              |
+| `--puck-color-line-placeholder`           | #6499cf                                      | Drag-and-drop insertion line                        |
+| `--puck-color-highlight`                  | #d89aba                                      | Accent color scale step, not currently consumed     |
+| `--puck-color-bg-disabled`                | #ababab                                      | Disabled button background                          |
+| `--puck-color-text-disabled`              | #404040                                      | Disabled button text                                |
+| `--puck-color-overlay-backdrop`           | color-mix(in srgb, #000000 75%, transparent) | Modal backdrop                                      |
+
+## Opacity
+
+| Token                         | Default | Used for                 |
+| ----------------------------- | ------- | ------------------------ |
+| `--puck-opacity-text-inverse` | `0.75`  | Action bar label opacity |
+
+## Spacing
+
+| Token                        | Default               | Used for                                        |
+| ---------------------------- | --------------------- | ----------------------------------------------- |
+| `--puck-space-1`             | `4px`                 | Small gaps, padding and margins throughout      |
+| `--puck-space-2`             | `8px`                 | Medium spacing in buttons, plugin bar and menus |
+| `--puck-space-3`             | `12px`                | Default field padding and drawer items          |
+| `--puck-space-4`             | `16px`                | Large panel, section and field padding          |
+| `--puck-space-5`             | `24px`                | External input panels and slot indicator height |
+| `--puck-space-chrome-gutter` | `var(--puck-space-4)` | Header and canvas gutter padding                |
+
+## Radius
+
+| Token                 | Default | Used for                                            |
+| --------------------- | ------- | --------------------------------------------------- |
+| `--puck-radius-none`  | `0`     | Square-cornered plugin bar tabs and button variants |
+| `--puck-radius-xs`    | `2px`   | Breadcrumb and sidebar section hover chips          |
+| `--puck-radius-s`     | `3px`   | Radius scale step, not currently consumed           |
+| `--puck-radius-m`     | `4px`   | Default radius for buttons, fields and controls     |
+| `--puck-radius-l`     | `8px`   | Action bar, modal and select dropdown               |
+| `--puck-radius-pill`  | `30px`  | Viewport size control buttons                       |
+| `--puck-radius-round` | `100%`  | Loader spinner ring                                 |
+
+## Border Width
+
+| Token                          | Default | Used for                                   |
+| ------------------------------ | ------- | ------------------------------------------ |
+| `--puck-border-width-hairline` | `0.5px` | Action bar and rich text menu dividers     |
+| `--puck-border-width-regular`  | `1px`   | Default borders and outlines across UI     |
+| `--puck-border-width-focus`    | `2px`   | Focus ring outlines and drop zone outlines |
+| `--puck-border-width-strong`   | `4px`   | Plugin bar active tab and accent borders   |
+
+## Motion
+
+| Token                    | Default       | Used for                                       |
+| ------------------------ | ------------- | ---------------------------------------------- |
+| `--puck-duration-fast`   | `50ms`        | Hover and focus transitions across UI controls |
+| `--puck-duration-medium` | `150ms`       | Layout, sidebar and slot resize transitions    |
+| `--puck-duration-slow`   | `250ms`       | Canvas fade-in transition                      |
+| `--puck-ease-exit`       | `ease-in`     | Easing for most hover and collapse transitions |
+| `--puck-ease-emphasized` | `ease-in-out` | Easing for viewport controls slide             |
+| `--puck-ease-entrance`   | `ease-out`    | Easing for canvas and sidebar entrance         |
+
+## Typography
+
+| Token                           | Default                                                                                                                              | Used for                                    |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
+| `--puck-font-family`            | `Inter, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica Neue, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol` | Default editor UI font family               |
+| `--puck-font-family-monospaced` | `ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, "DejaVu Sans Mono", monospace`                                   | Header path display and outline font        |
+| `--puck-font-weight-regular`    | `400`                                                                                                                                | Default button font weight                  |
+| `--puck-font-weight-medium`     | `500`                                                                                                                                | Active fields, labels and action bar        |
+| `--puck-font-weight-semibold`   | `600`                                                                                                                                | Field labels, plugin bar items and headers  |
+| `--puck-font-weight-bold`       | `700`                                                                                                                                | Heading component text                      |
+| `--puck-font-weight-heavy`      | `800`                                                                                                                                | Largest heading variant                     |
+| `--puck-letter-spacing-ui`      | `0.05ch`                                                                                                                             | Button label letter spacing                 |
+| `--puck-letter-spacing-heading` | `0.08ch`                                                                                                                             | Largest heading letter spacing              |
+| `--puck-space-m-unitless`       | `24`                                                                                                                                 | Referenced by line-height calculations only |
+
+## Icon Size
+
+| Token                 | Default | Used for                                                  |
+| --------------------- | ------- | --------------------------------------------------------- |
+| `--puck-icon-size-xs` | `14px`  | Outline layer and zone icons                              |
+| `--puck-icon-size-s`  | `16px`  | Action bar, inline control and outline caret/action icons |
+| `--puck-icon-size-m`  | `18px`  | Select, rich text menu and collapse-all icons             |
+| `--puck-icon-size-l`  | `24px`  | Icon size scale step, not currently consumed              |
+
+## Functional
+
+| Token                             | Default                    | Used for                                                    |
+| --------------------------------- | -------------------------- | ----------------------------------------------------------- |
+| `--puck-slot-min-empty-height`    | `128px`                    | Minimum height of empty slots                               |
+| `--puck-line-placeholder-width`   | `2px`                      | Drag-and-drop insertion line thickness (canvas and outline) |
+| `--puck-user-sidebar-left-width`  | `186px–320px (responsive)` | User override for left sidebar width                        |
+| `--puck-user-sidebar-right-width` | `186px–320px (responsive)` | User override for right sidebar width                       |

package/dist/docs/api-reference/theming/header.md

@@ -0,0 +1,19 @@
+# Header
+
+Use the following CSS properties for theming the editor header.
+
+```css
+.Container {
+  --puck-header-color-bg: #1e293b;
+  --puck-header-color-text: #f8fafc;
+}
+```
+
+## CSS properties
+
+Defaults shown as `var(--puck-...)` reference [global tokens](/docs/api-reference/theming/global). See [computed values](/docs/api-reference/theming/computed-values#header) for the values they resolve to.
+
+| Token                      | Default                     | Description      |
+| -------------------------- | --------------------------- | ---------------- |
+| `--puck-header-color-bg`   | `var(--puck-color-surface)` | Background color |
+| `--puck-header-color-text` | `var(--puck-color-text)`    | Text color       |

package/dist/docs/api-reference/theming/icon-button.md

@@ -0,0 +1,28 @@
+# Icon button
+
+Use the following CSS properties for theming Puck's icon buttons.
+
+```css
+.Container {
+  --puck-iconbutton-radius: 9999px;
+  --puck-iconbutton-color-icon: #1f2937;
+  --puck-iconbutton-color-bg-hover: #eef2ff;
+  --puck-iconbutton-space: 16px;
+}
+```
+
+## CSS properties
+
+Defaults shown as `var(--puck-...)` reference [global tokens](/docs/api-reference/theming/global). See [computed values](/docs/api-reference/theming/computed-values#icon-button) for the values they resolve to.
+
+| Token                                   | Default                                       | Description             |
+| --------------------------------------- | --------------------------------------------- | ----------------------- |
+| `--puck-iconbutton-radius`              | `var(--puck-radius-m)`                        | Border radius           |
+| `--puck-iconbutton-space`               | `var(--puck-space-1)`                         | Padding                 |
+| `--puck-iconbutton-color-bg`            | `transparent`                                 | Background color        |
+| `--puck-iconbutton-color-bg-hover`      | `var(--puck-color-interactive-neutral-hover)` | Background on hover     |
+| `--puck-iconbutton-color-bg-active`     | `var(--puck-color-interactive-soft)`          | Background when pressed |
+| `--puck-iconbutton-color-icon`          | `currentColor`                                | Icon color              |
+| `--puck-iconbutton-color-icon-hover`    | `var(--puck-color-interactive)`               | Icon color on hover     |
+| `--puck-iconbutton-color-icon-active`   | `var(--puck-color-interactive)`               | Icon color when active  |
+| `--puck-iconbutton-color-icon-disabled` | `var(--puck-color-text-subtle)`               | Disabled icon color     |

package/dist/docs/api-reference/theming/outline.md

@@ -0,0 +1,35 @@
+# Outline
+
+Use the following CSS properties for theming the outline (layers) panel.
+
+```css
+.Container {
+  --puck-outline-color-bg-selected: #f0f0f0;
+  --puck-outline-color-border-selected: #b947ff;
+}
+```
+
+## CSS properties
+
+Defaults shown as `var(--puck-...)` reference [global tokens](/docs/api-reference/theming/global). See [computed values](/docs/api-reference/theming/computed-values#outline) for the values they resolve to.
+
+| Token                                  | Default                                  | Description                              |
+| -------------------------------------- | ---------------------------------------- | ---------------------------------------- |
+| `--puck-outline-color-text`            | `var(--puck-color-text-secondary)`       | Layer label text color                   |
+| `--puck-outline-color-text-hover`      | `var(--puck-color-interactive)`          | Zone label color when targeted by a drag |
+| `--puck-outline-color-text-helper`     | `var(--puck-color-text-subtle)`          | Empty-zone helper text color             |
+| `--puck-outline-color-icon`            | `var(--puck-color-text-subtle)`          | Layer icon color                         |
+| `--puck-outline-color-bg-hover`        | `var(--puck-color-interactive-soft)`     | Layer background on hover                |
+| `--puck-outline-color-border-hover`    | `var(--puck-color-interactive-subtle)`   | Layer border color on hover              |
+| `--puck-outline-color-bg-selected`     | `var(--puck-color-interactive-subtle)`   | Selected layer background                |
+| `--puck-outline-color-border-selected` | `var(--puck-color-selection-border)`     | Selected layer border color              |
+| `--puck-outline-color-drop-indicator`  | `var(--puck-color-line-placeholder)`     | Drag-and-drop line indicator color       |
+| `--puck-outline-border-width`          | `var(--puck-border-width-regular)`       | Layer border width                       |
+| `--puck-outline-radius`                | `var(--puck-radius-m)`                   | Layer border radius                      |
+| `--puck-outline-font-size`             | `var(--puck-font-size-xxxs)`             | Layer label font size                    |
+| `--puck-outline-font-family`           | `var(--puck-font-family-monospaced)`     | Layer tree font family                   |
+| `--puck-outline-icon-size`             | `var(--puck-icon-size-xs)`               | Layer and zone icon size                 |
+| `--puck-outline-action-size`           | `var(--puck-icon-size-s)`                | Expand caret and row action icon size    |
+| `--puck-outline-space-indent`          | `var(--puck-space-3)`                    | Indentation per nesting level            |
+| `--puck-outline-zone-color-text`       | `var(--puck-color-text-muted)`           | Nested-zone label and icon color         |
+| `--puck-outline-zone-font-size`        | `calc(var(--puck-font-size-xxxs) * 0.9)` | Nested-zone label font size              |

package/dist/docs/api-reference/theming/plugin-bar.md

@@ -0,0 +1,24 @@
+# Plugin bar
+
+Use the following CSS properties for theming the plugin bar.
+
+```css
+.Container {
+  --puck-pluginbar-color-bg: #1e293b;
+  --puck-pluginbar-color-text: #94a3b8;
+  --puck-pluginbar-color-text-selected: #f8fafc;
+}
+```
+
+## CSS properties
+
+Defaults shown as `var(--puck-...)` reference [global tokens](/docs/api-reference/theming/global). See [computed values](/docs/api-reference/theming/computed-values#plugin-bar) for the values they resolve to.
+
+| Token                                  | Default                              | Description              |
+| -------------------------------------- | ------------------------------------ | ------------------------ |
+| `--puck-pluginbar-color-bg`            | `var(--puck-color-surface-subtle)`   | Background color         |
+| `--puck-pluginbar-color-bg-hover`      | `var(--puck-color-interactive-soft)` | Tab background on hover  |
+| `--puck-pluginbar-color-text`          | `var(--puck-color-text-secondary)`   | Item text color          |
+| `--puck-pluginbar-color-text-hover`    | `var(--puck-color-interactive)`      | Item text color on hover |
+| `--puck-pluginbar-color-text-selected` | `var(--puck-color-interactive)`      | Selected item text color |
+| `--puck-pluginbar-font-size`           | `var(--puck-font-size-xxxs)`         | Item font size           |

package/dist/docs/api-reference/theming/sidebar.md

@@ -0,0 +1,19 @@
+# Sidebar
+
+Use the following CSS properties for theming the left and right sidebar panels.
+
+```css
+.Container {
+  --puck-sidebar-left-color-bg: #f5f5f7;
+  --puck-sidebar-right-color-bg: #ffffff;
+}
+```
+
+## CSS properties
+
+Defaults shown as `var(--puck-...)` reference [global tokens](/docs/api-reference/theming/global). See [computed values](/docs/api-reference/theming/computed-values#sidebar) for the values they resolve to.
+
+| Token                           | Default                            | Description            |
+| ------------------------------- | ---------------------------------- | ---------------------- |
+| `--puck-sidebar-left-color-bg`  | `var(--puck-color-surface-subtle)` | Left panel background  |
+| `--puck-sidebar-right-color-bg` | `var(--puck-color-surface)`        | Right panel background |

package/dist/docs/api-reference/theming/slot.md

@@ -0,0 +1,27 @@
+# Slot
+
+Use the following CSS properties for theming slots (drop zones) and the components dragged within them.
+
+```css
+.Container {
+  --puck-slot-color-bg: #fff2ee;
+  --puck-slot-color-border: #f6ab3b;
+}
+```
+
+## CSS properties
+
+Defaults shown as `var(--puck-...)` reference [global tokens](/docs/api-reference/theming/global). See [computed values](/docs/api-reference/theming/computed-values#slot) for the values they resolve to.
+
+| Token                                         | Default                              | Description                           |
+| --------------------------------------------- | ------------------------------------ | ------------------------------------- |
+| `--puck-slot-color-bg`                        | `var(--puck-color-selection-bg)`     | Drop zone background when active      |
+| `--puck-slot-color-border`                    | `var(--puck-color-selection-border)` | Drop zone outline color               |
+| `--puck-slot-border-width`                    | `var(--puck-border-width-focus)`     | Drop zone outline width               |
+| `--puck-slot-border-style`                    | `dashed`                             | Drop zone outline style               |
+| `--puck-slot-component-color-overlay`         | `var(--puck-color-selection-bg)`     | Component overlay background on hover |
+| `--puck-slot-component-color-overlay-border`  | `var(--puck-color-selection-border)` | Component overlay outline             |
+| `--puck-slot-component-border-width`          | `var(--puck-border-width-focus)`     | Component overlay outline width       |
+| `--puck-slot-component-color-border-selected` | `var(--puck-color-selection-border)` | Selected component overlay outline    |
+| `--puck-slot-component-color-placeholder`     | #6499cf               | Drag placeholder background           |
+| `--puck-slot-component-color-border-dragging` | #cfdff0               | Outline while dragging component      |

package/dist/docs/cli.md

@@ -0,0 +1,201 @@
+# CLI
+
+The Puck CLI sets up Puck and [Puck Cloud](https://cloud.puckeditor.com) in a new or existing app. It's built for coding agents, and works interactively for humans.
+
+```sh
+npx @puckeditor/cli init
+```
+
+`init` inspects your project and makes the smallest set of changes needed to reach a working Puck app, with Puck AI if you choose it:
+
+- **No app yet**: creates a Next.js, React Router, TanStack Start, vinext, Vite or Astro app, or a Hono or Express server, from the Puck [recipes](https://github.com/puckeditor/puck#recipes)
+- **App without Puck**: installs `@puckeditor/core` and adds an editor at `/edit`
+- **Puck without Puck AI** (when you choose it): installs `@puckeditor/cloud-client` and `@puckeditor/plugin-ai`, adds the `/api/puck` route and the Puck AI plugin, and connects your Puck Cloud account
+- **Already set up**: verifies the setup and changes nothing
+
+With Puck AI, the only manual step is logging in to Puck Cloud and approving the connection in your browser. When it's done, the CLI starts your dev server and opens the editor.
+
+Puck AI is optional. It's the editor plugin that uses Puck Cloud as its backend, so choosing it sets up Puck Cloud too. `init` asks whether to add it; pass `--ai` or `--no-ai` to choose up front.
+
+## Supported projects
+
+- Next.js 15+ using the App Router (`app/` or `src/app/`)
+- React Router 7+ in framework mode
+- [TanStack Start](https://tanstack.com/start) 1.x
+- [vinext](https://github.com/cloudflare/vinext) using the App Router
+- [Vite](https://vite.dev) React apps (see [Vite and Astro](#vite-and-astro))
+- [Astro](https://astro.build) 7+ (see [Vite and Astro](#vite-and-astro))
+- [Hono](https://hono.dev) and [Express](https://expressjs.com) servers (see [Servers](#servers))
+- npm, pnpm, Yarn and Bun, including workspaces
+- TypeScript projects
+
+When the CLI can't safely change something, like an existing `middleware.ts`, it leaves the file alone and tells you exactly what to add.
+
+## Vite and Astro
+
+A Vite app, or an Astro site without a server adapter, has nowhere to save pages or run Puck Cloud. The CLI asks where that server comes from. Agents get a `choose_backend` action; pass `--backend` to choose up front:
+
+- `--backend add`: in Vite, adds a Hono server in `server/`, run by Vite in development with `@hono/vite-dev-server` and by `npm start` in production. In Astro, runs `astro add node` so pages and API routes are served on demand
+- `--backend external --backend-url <url>`: proxies `/api` to a server that runs elsewhere, e.g. a [Hono or Express server](#servers) set up by the CLI. Puck Cloud and `PUCK_API_KEY` live on that server
+- `--backend none`: saves pages in the browser's `localStorage`. Puck AI isn't available without a server
+
+In Vite, the editor opens at any URL ending in `/edit`: `<PuckRoot>` wraps your app in `src/main.tsx` and renders the editor instead. Render published pages with `<PuckPage path={...} />` wherever your app renders pages.
+
+In Astro with an adapter, `src/pages/[...puckPath].astro` renders the editor at `/edit` URLs and published pages everywhere else, on the server. Without one, the editor is a static page at `/edit?path=/your/page`. The CLI runs `astro add react` when React isn't set up yet.
+
+## Servers
+
+In a Hono or Express project, the CLI sets up the APIs a Puck editor in another app talks to:
+
+- `/api/pages`: loads (`GET ?path=/about`) and saves (`POST { path, data }`) pages, in `src/puck/pages.ts`
+- `/api/puck/*`: the Puck Cloud route for Puck AI, in `src/puck/cloud.ts`, when you choose Puck AI
+
+It mounts both on your app before it starts serving, so your own middleware runs first. Node doesn't load `.env` files, so the CLI adds `--env-file-if-exists=.env.local` to a `tsx` or `node` dev script. Bun loads `.env.local` itself. On Cloudflare Workers, put `PUCK_API_KEY` in `.dev.vars` instead.
+
+Add the Puck AI plugin in the app with the editor. If that app runs on another origin, proxy `/api` to the server in development, or pass `host` to `createAiPlugin`.
+
+## For coding agents
+
+Run with `--yes --json`. The CLI never prompts, and prints exactly one JSON document to stdout.
+
+```sh
+npx @puckeditor/cli init --yes --json
+```
+
+When `status` is `action_required`, nothing has been changed yet. Show each entry in `actions` to the developer, then run its `rerun` command. Without `--ai` or `--no-ai`, the first run returns a `choose_ai` action, so the developer can decide whether to add Puck AI. With `--ai`, the first run asks the developer to log in:
+
+```json
+{
+  "status": "action_required",
+  "message": "Puck Cloud login required. No changes have been made yet.",
+  "actions": [
+    {
+      "type": "browser_login",
+      "url": "https://cloud.puckeditor.com/cli/connect#code=BCDF-GHJK",
+      "userCode": "BCDF-GHJK",
+      "rerun": "npx @puckeditor/cli init --yes --json --ai"
+    }
+  ]
+}
+```
+
+After the developer approves, the same command completes the setup:
+
+```json
+{
+  "status": "success",
+  "project": { "framework": "next", "packageManager": "pnpm" },
+  "puck": { "installed": true, "configured": true },
+  "cloud": { "configured": true, "verified": "remote" },
+  "ai": { "installed": true, "configured": true },
+  "filesModified": [".env.local", "app/api/puck/[...all]/route.ts"]
+}
+```
+
+Start with `npx @puckeditor/cli status --json` to see what's already set up and which command to run next.
+
+### Statuses
+
+| Status            | Meaning                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------- |
+| `success`         | The project is set up. `changed` is `false` if there was nothing to do.                 |
+| `action_required` | Input or approval is needed. Nothing was changed. Complete `actions`, then run `rerun`. |
+| `partial`         | Changes were applied, but some `actions` must be completed by hand.                     |
+| `error`           | Something went wrong. See `error.code` and `error.message`.                             |
+
+### Actions
+
+| Type                       | What to do                                                                                                                           |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `browser_login`            | Ask the developer to open `url`, confirm `userCode` and approve                                                                      |
+| `provide_api_key`          | Ask for a Puck API key, then re-run with `PUCK_API_KEY` set                                                                          |
+| `confirm_plan`             | Review `plan.steps`, then re-run with `--yes`                                                                                        |
+| `choose_ai`                | Ask the developer, then re-run `init` with `--ai` or `--no-ai`                                                                       |
+| `choose_backend`           | Ask the developer, then re-run with `--backend add`, `--backend external --backend-url <url>` or `--backend none`                    |
+| `choose_framework`         | Re-run `init` with `--framework` and one of `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
+| `provide_app_name`         | Re-run `init` with `--name <name>`                                                                                                   |
+| `choose_workspace_package` | Re-run with `--workspace <dir>` for one of `choices`                                                                                 |
+| `manual_edit`              | Apply `snippet` to `file` as described in `instructions`                                                                             |
+| `set_environment_variable` | Set `PUCK_API_KEY` wherever the app runs                                                                                             |
+
+### Exit codes
+
+| Code | Meaning                              |
+| ---- | ------------------------------------ |
+| 0    | Success                              |
+| 2    | Invalid arguments or API key         |
+| 3    | Unsupported or ambiguous project     |
+| 4    | File conflict                        |
+| 5    | Package manager failure              |
+| 6    | `doctor` found problems              |
+| 7    | Puck Cloud couldn't complete a login |
+| 10   | Action required                      |
+| 11   | Partially set up                     |
+
+### Reading the docs
+
+The CLI includes these docs as markdown, matching its release. Use the version of the CLI that matches the project's `@puckeditor/core`:
+
+```sh
+npx @puckeditor/cli docs ls                          # every page
+npx @puckeditor/cli docs find "dynamic fields"       # find pages by title or heading
+npx @puckeditor/cli docs grep resolveData            # search page content
+npx @puckeditor/cli docs cat api-reference/fields/text
+```
+
+The latest docs are indexed at [llms.txt](https://puckeditor.com/llms.txt), and any page is available as markdown by adding `.md` to its URL. Agents with skill support can also install the [Puck skill](https://github.com/puckeditor/skills):
+
+```sh
+npx skills add puckeditor/skills --skill puck
+```
+
+## Commands
+
+| Command      | Description                                                        |
+| ------------ | ------------------------------------------------------------------ |
+| `init`       | Set up Puck, optionally with Puck AI, creating an app if needed    |
+| `add editor` | Add the Puck editor                                                |
+| `add cloud`  | Connect Puck Cloud (adds the editor first if needed)               |
+| `add ai`     | Add the Puck AI plugin (adds Puck Cloud first if needed)           |
+| `status`     | Show what's installed and configured                               |
+| `doctor`     | Diagnose problems and suggest fixes. Never makes changes           |
+| `docs`       | Read these docs: `ls`, `cat <page>`, `find <query>`, `grep <text>` |
+
+## Flags
+
+| Flag                       | Description                                                                                                       |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `--json`                   | Machine-readable output                                                                                           |
+| `--yes`, `-y`              | Apply the plan without prompting                                                                                  |
+| `--dry-run`                | Show the plan without changing anything or logging in                                                             |
+| `--cwd <path>`             | Run against another directory                                                                                     |
+| `--workspace <name\|dir>`  | Choose an app when running from a monorepo root                                                                   |
+| `--api-key <key>`          | Use an existing API key instead of logging in                                                                     |
+| `--no-env-write`           | Don't write `PUCK_API_KEY` to a file                                                                              |
+| `--ai`                     | Also set up Puck AI and Puck Cloud (`init`)                                                                       |
+| `--no-ai`                  | Set up the editor only, without asking about Puck AI (`init`)                                                     |
+| `--backend <choice>`       | Where a Vite app's server comes from: `add`, `external` or `none`                                                 |
+| `--backend-url <url>`      | The server for `--backend external`                                                                               |
+| `--wait`                   | Wait for login approval instead of returning `action_required`                                                    |
+| `--framework <name>`       | Framework for a new app: `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
+| `--name <name>`            | Directory for a new app                                                                                           |
+| `--package-manager <name>` | Override the detected package manager                                                                             |
+| `--offline`                | Skip the Puck Cloud connection check (`doctor`)                                                                   |
+
+## API keys
+
+The CLI writes `PUCK_API_KEY` to `.env.local`, and makes sure it's ignored by git. If a key already exists in `.env.development.local`, it's updated there instead. Keys are never written to `.env`, and never printed.
+
+To use an existing key, prefer the environment over `--api-key`, which is visible in your shell history:
+
+```sh
+PUCK_API_KEY=your-key npx @puckeditor/cli add cloud --yes
+```
+
+Remember to set `PUCK_API_KEY` in your production environment too. `react-router-serve` and Cloudflare Workers don't load `.env` files; on Workers, use `wrangler secret put PUCK_API_KEY`.
+
+The `/api/puck` route and the editor are public by default. Add authentication before deploying.
+
+## Puck AI
+
+`init` and `add ai` add the Puck AI plugin to the editor, allow design mode in the `/api/puck` route, and wrap your config with `withDynamicConfig` so components designed by Puck AI render on your pages. If your editor has been customised, the CLI leaves it alone and prints the code to add.

package/dist/docs/extending-puck/composition.md

@@ -0,0 +1,54 @@
+# Composition
+
+Puck uses compositional patterns enable completely custom editor interfaces. [See an example](https://demo.puckeditor.com/custom-ui/edit/).
+
+## Using composition
+
+Composition can be achieved by providing [`children`](/docs/api-reference/components/puck#children) to the [`<Puck>` component](/docs/api-reference/components/puck):
+
+```tsx
+import { Puck } from "@puckeditor/core";
+
+export function Editor() {
+  return (
+    <Puck>
+      <div
+        style={{ display: "grid", gridTemplateColumns: "1fr 2fr", gridGap: 16 }}
+      >
+        <div>
+          {/* Render the drag-and-drop preview */}
+          <Puck.Preview />
+        </div>
+        <div>
+          {/* Render the component list */}
+          <Puck.Components />
+        </div>
+      </div>
+    </Puck>
+  );
+}
+```
+
+## Compositional components
+
+Puck exposes its core components, allowing you to compose them together to create new layouts:
+
+- [`<Puck.Components>`](/docs/api-reference/components/puck-components) - A draggable list of components.
+- [`<Puck.Fields>`](/docs/api-reference/components/puck-fields) - The fields for the currently selected item.
+- [`<Puck.Outline>`](/docs/api-reference/components/puck-outline) - An interactive outline.
+- [`<Puck.Preview>`](/docs/api-reference/components/puck-preview) - A drag-and-drop preview.
+
+The internal UI for these components can also be changed by implementing [UI overrides](/docs/extending-puck/ui-overrides) or [theming](/docs/extending-puck/theming).
+
+### Helper components
+
+Puck also exposes helper components for even deeper customization:
+
+- [`<Drawer>`](/docs/api-reference/components/drawer) - A reference list of items that can be dragged into a droppable area, normally `<Puck.Preview>`.
+- [`<Drawer.Item>`](/docs/api-reference/components/drawer-item) - An item that can be dragged from a `<Drawer>`.
+- [`<FieldLabel>`](/docs/api-reference/components/field-label) - A styled label for creating inputs.
+
+## Further reading
+
+- [Internal Puck API](/docs/extending-puck/internal-puck-api)
+- [UI overrides](/docs/extending-puck/ui-overrides)