@embeddables/cli 0.14.4 → 0.15.0-beta.0

package/.prompts/custom/build-funnel.md

@@ -2,7 +2,7 @@ We need to build the pages from the attached images. Please create a plan and hi
 
 Embeddable ID: <EMBEDDABLE_ID>
 
-Important: Always read the Embeddables CLI context before starting (e.g. @.cursor/rules/embeddables-cli.md, @.claude/embeddables-cli.md, @AGENTS.md, or @.agent/rules/embeddables-cli.md depending on your editor).
+Important: Always read the Embeddables CLI context before starting. The full guide is at @embeddables/AI-README.md. Your editor's rule file (e.g. @.cursor/rules/embeddables-cli.md, @.claude/CLAUDE.md, @AGENTS.md, or @.agent/rules/embeddables-cli.md) points to it with a summary of what it covers.
 
 [KEEP / REMOVE]
 Use the designs from the images but use the content from the attached document instead, and build out the pages based on that content. Therefore, when using the designs from the images, for each page just find the most relevant design for the page's content and design it based on that. However, don't be confined to the provided designs - just find the closest design and modify it to fit the content required.
@@ -17,6 +17,8 @@ Notes:
    a. `emojiIcon` with an emoji when there is an appropriate one (can be used in `imageUrl` in CustomButton, or `imageUrl` inside OptionSelector buttons)
    b. placeholder image: https://placehold.co/600x400?text=My+Text+To+Display if there is text in the image (can't be emojis), otherwise https://placehold.co/600x400 (but with the correct size specified in the URL in either case; can be used in `src` in MediaImage, `imageUrl` in CustomButton, or `imageUrl` inside OptionSelector buttons)
 
+Before finishing: **Review** your changes per the Embeddables CLI rules—especially the "When to Review (Required Checks)" section. Run `embeddables build` to verify compilation, then run `embeddables save` and review the JSON diff it shows before confirming.
+
 At the end of your work, include a short summary covering:
 
 - Decisions made – Any implementation choices where requirements, design, or instructions were not fully explicit.

package/.prompts/custom/carousel.md

@@ -0,0 +1,159 @@
+# Carousel / Swiper Implementation Guide
+
+When building a carousel or slider in an Embeddable, use **Swiper v11.2.10** loaded at runtime via CDN. No build tooling is required.
+
+## Pattern Overview
+
+1. **Page TSX structure** — A `Container` with child elements (each child becomes a slide)
+2. **Initialization action** — An action file that loads Swiper from CDN and initializes it on `outputs_onloadflow`
+3. **CSS** — Styles for the carousel container and optional prev/next navigation buttons
+4. **Optional** — Prev/next `CustomButton` components for navigation
+
+## 1. Page TSX Structure
+
+Structure your carousel as nested Containers:
+
+```tsx
+<Container id="comp_xxx" key="carousel_container" tags={["carousel_container"]}>
+  {/* Inner container — this becomes the Swiper container (identified by key) */}
+  <Container id="comp_yyy" key="my_carousel" tags={["carousel_inner"]}>
+    {/* Each direct child becomes a slide */}
+    <Container id="comp_1" key="slide_1" tags={["slide"]}>...</Container>
+    <Container id="comp_2" key="slide_2" tags={["slide"]}>...</Container>
+    <Container id="comp_3" key="slide_3" tags={["slide"]}>...</Container>
+  </Container>
+  {/* Optional prev/next buttons */}
+  <CustomButton id="comp_prev" key="carousel_prev" tags={["carousel_arrow", "left_arrow"]} text="" action="no-action" />
+  <CustomButton id="comp_next" key="carousel_next" tags={["carousel_arrow", "right_arrow"]} text="" action="no-action" />
+</Container>
+```
+
+- The **inner** `Container` (e.g. `key="my_carousel"`) is the one the action targets — it must have a unique `key`.
+- The action adds `swiper`, `swiper-wrapper`, and `swiper-slide` classes at runtime.
+- Slides can be any component: `Container`, `MediaImage`, `CustomHTML`, etc.
+
+## 2. Action File
+
+Create an action (e.g. `actions/swiper.js`) that:
+
+1. Loads Swiper CSS and JS from CDN
+2. Finds the container by `data-component-key-value` (the component `key`)
+3. Adds Swiper classes to the container and its children
+4. Initializes `new Swiper(container, options)` with optional navigation
+
+**Minimal template:**
+
+```javascript
+function output(userData) {
+  loadStylesheet("https://unpkg.com/swiper@11.2.10/swiper-bundle.min.css");
+  loadScript("https://unpkg.com/swiper@11.2.10/swiper-bundle.min.js", () => {
+    initCarousel({
+      containerKey: "my_carousel",      // key of the inner Container
+      prevKey: "carousel_prev",         // key of prev button (or null)
+      nextKey: "carousel_next",         // key of next button (or null)
+      slidesPerView: 1,
+      spaceBetween: 10,
+      loop: true,
+      breakpoints: {
+        1024: { slidesPerView: 3, spaceBetween: 24 },
+      },
+    });
+  });
+}
+
+function loadStylesheet(href) {
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = href;
+  document.head.appendChild(link);
+}
+
+function loadScript(src, callback) {
+  const script = document.createElement("script");
+  script.src = src;
+  script.onload = callback;
+  document.head.appendChild(script);
+}
+
+function getElementByKey(key) {
+  return document.querySelector(`[data-component-key-value="${key}"]`);
+}
+
+function initCarousel(options) {
+  const { containerKey, prevKey, nextKey, ...swiperOptions } = options;
+  const container = getElementByKey(containerKey);
+  if (!container) return;
+
+  const wrapper = container.firstElementChild;
+  if (!wrapper) return;
+
+  wrapper.classList.add("swiper-wrapper");
+  Array.from(wrapper.children).forEach(el => el.classList.add("swiper-slide"));
+  container.classList.add("swiper");
+
+  const nextBtn = nextKey ? getElementByKey(nextKey) : null;
+  const prevBtn = prevKey ? getElementByKey(prevKey) : null;
+
+  new Swiper(container, {
+    ...swiperOptions,
+    navigation: nextBtn && prevBtn ? { nextEl: nextBtn, prevEl: prevBtn } : {},
+  });
+}
+```
+
+**Wire the action** to `outputs_onloadflow` in `config.json` so it runs when the embeddable loads.
+
+## 3. CSS
+
+Add styles for the carousel layout and navigation buttons in `styles/index.css`:
+
+```css
+.Flow-Component.ComponentTag-carousel_container {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  position: relative;
+  justify-content: center;
+  height: fit-content;
+}
+
+.Flow-Component.ComponentTag-carousel_arrow {
+  width: 44px;
+  height: 44px;
+  z-index: 10;
+  position: absolute;
+  cursor: pointer;
+  background-size: contain;
+  background-position: center;
+  border-radius: 50%;
+}
+
+.Flow-Component.ComponentTag-left_arrow {
+  left: -72px;
+  /* background-image: url(...) for arrow icon */
+}
+
+.Flow-Component.ComponentTag-right_arrow {
+  right: -72px;
+  /* background-image: url(...) for arrow icon */
+}
+```
+
+Use breakpoints to adjust arrow position on mobile (e.g. overlay on the carousel).
+
+## 4. Swiper Options
+
+Swiper options are passed to `new Swiper(container, options)`. Common options:
+
+- `slidesPerView` — Number of visible slides
+- `spaceBetween` — Gap between slides (px)
+- `loop` — Infinite loop
+- `autoplay` — Auto-advance (object with `delay`, etc.)
+- `breakpoints` — Responsive overrides (see [Swiper API](https://swiperjs.com/swiper-api))
+
+## Key Points
+
+- **Swiper v11.2.10** is loaded at runtime via CDN — no npm install or build step.
+- Turn any `Container` with child elements into a carousel via an action that loads and initializes Swiper.
+- The container is identified by its component `key` (exposed as `data-component-key-value` in the DOM).
+- Do not add `swiper`, `swiper-wrapper`, or `swiper-slide` classes in TSX — the action adds them at runtime.

package/.prompts/embeddables-cli.md

@@ -20,6 +20,23 @@ The CLI transforms an Embeddable JSON into:
 - **JS files**: Computed fields and actions
 - **config.json**: Reduced JSON containing structure/metadata without file content
 
+## When to Review (Required Checks)
+
+Review is **required** in these situations. Do not skip these checks.
+
+| When (trigger) | Where to review | What to verify |
+| --- | --- | --- |
+| **Before running `embeddables save`** | The JSON diff shown by the save command | Confirm the diff matches your intended changes. Do not save without reviewing—unexpected additions, removals, or edits may indicate a compile or config error. |
+| **After modifying `config.json`** | `config.json` and any related React/JS files | Ensure `pages[]`, `computedFields`, `dataOutputs`, `breakpoints`, and other structure match the actual page files, computed-field files, and action files. IDs and keys must be consistent. |
+| **After adding or removing pages** | `config.json` → `pages[]` and `pages/{pageKey}.page.tsx` | Each page in `config.json` must have a matching `.page.tsx` file, and vice versa. |
+| **After adding or removing components** | Page React files and `config.json` | Component IDs and keys must be unique. Nested components need correct `parent_id`. |
+| **After adding or removing actions or computed fields** | `config.json` → `dataOutputs` / `computedFields` and `actions/` / `computed-fields/` | Each entry in config must have a matching JS file; each JS file must have a config entry. |
+| **After changing action triggers** | `config.json` (flow/page level) and component props (React) | `outputs_on*` fields must reference valid action IDs. Page-level triggers use arrays; flow-level can be string or array. |
+| **After modifying styles** | `styles/index.css` and the JSON diff from `embeddables save` | Confirm no unexpected selectors were added or removed; check that breakpoint names match `config.json`. |
+| **When debugging round-trip or compile issues** | `embeddables inspect --bypass-auth --id <embeddableId>` output | Run inspect to compare original vs rebuilt JSON and identify divergences. |
+
+**Summary**: A review is required whenever you add, remove, or modify pages, components, styles, actions, computed fields, or config. In those cases, review the affected files and the JSON diff before saving.
+
 ## Embeddable JSON Structure (Flow)
 
 The root Embeddable object (called `Flow`) is defined in `src/types-builder.ts`. Key properties:
@@ -413,6 +430,22 @@ NOTE: OptionSelectors are either dropdowns (`dropdown` is `true`, can use other
 Note: the component itself IS the button. There is no `button` element inside it.
 Note: button icons and checkboxes are before text in the button, unless you set the flex-direction to be row-reverse or column-reverse.
 
+**Making a CTA disabled until validation passes**: Use `needs_validation_passed` together with `validation_show_state`. Both props must be set — `needs_validation_passed` alone does not visually disable the button.
+
+```tsx
+<CustomButton
+  needs_validation_passed={true}
+  validation_show_state="disable"
+  {/* ... other props ... */}
+/>
+```
+
+- `needs_validation_passed={true}` — prevents the button action from firing until all validation on the page passes.
+- `validation_show_state` — controls how the button appears when validation has not yet passed:
+  - `"disable"` — button appears disabled (grayed out, not clickable). **Use this for the standard "disabled until valid" CTA pattern.**
+  - `"hide"` — button is hidden entirely until validation passes.
+  - `"always_show"` — button always appears enabled regardless of validation state (default behaviour; omit both props if this is what you want).
+
 | ElementType         | Element          | Condition                 | Notes                                                                                             |
 | ------------------- | ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
 | `ButtonTextWrapper` | `<div>`          | Always                    |                                                                                                   |
@@ -488,6 +521,8 @@ NOTE: there is also a reset icon button with the class `reset` - hide this if yo
 
 ## Computed Fields Structure
 
+> **Docs**: [Computed Fields](https://docs.embeddables.com/features/computed-fields) · [Custom Code](https://docs.embeddables.com/guides/custom-code)
+
 Computed fields are stored in `Flow.computedFields` and transform to JS files. The `ComputedField` type is defined in `src/types-builder.ts`.
 
 **Key Properties**:
@@ -500,28 +535,42 @@ Computed fields are stored in `Flow.computedFields` and transform to JS files. T
 
 **File Mapping**: `computed-fields/{key}.js` (e.g., `computed-fields/total_price.js`)
 
-**Code Structure**: The `code` property contains JavaScript that must include a function called `result`. The runtime passes a `context` object as the first argument:
+**Code Structure**: The `code` property contains JavaScript that must include a function called `result`. The runtime passes three arguments — `userData`, `helperFunctions`, and `triggerContext`:
 
 ```javascript
-function result(context) {
-  // Access user data via global userData object
+function result(userData, helperFunctions, triggerContext) {
   const price = userData.price || 0
   const quantity = userData.quantity || 0
 
-  // context.triggerContext is available (see Actions section for shape)
-  // context.trackCustomEvent(name, props) can track analytics events
+  // helperFunctions.trackCustomEvent(name, props) can track analytics events
+  // triggerContext contains metadata about what triggered this recalculation
 
   return price * quantity
 }
 ```
 
+**Function arguments**:
+
+| Argument | Description |
+| --- | --- |
+| `userData` | Object containing the User Data fields listed in **Inputs** (or all User Data when "Include full User Data" is enabled — see below). The computed field's own key is excluded to prevent circular references. |
+| `helperFunctions` | Object with helper utilities. Currently provides `trackCustomEvent(eventName, eventProps)` for analytics (see "Custom Event Tracking" below). |
+| `triggerContext` | Metadata about what triggered the recalculation (see "Trigger Context" below). For computed fields the shape differs slightly from actions — it describes which input changed rather than a UI event. |
+
+**Scope of `userData` and when it re-runs**:
+
+Computed fields can be configured (in the builder UI) to receive broader User Data, which affects both what's available inside `result(userData, …)` and when it re-runs:
+
+- **Include and watch full User Data** — `userData` contains the entire User Data object (excluding the computed field's own key). The field re-runs whenever *any* User Data value changes. Useful when a field needs access to everything or should update frequently.
+- **Include, but not watch full User Data** — `userData` contains the entire User Data object (excluding the computed field's own key), but the field only re-runs when the keys listed in **Inputs** or **Triggers** change. Useful when full access is needed but recalculation should be controlled.
+- **Default (neither option)** — `userData` contains only the keys listed in **Inputs**. The field re-runs when those keys (or any **Triggers**) change.
+
 **Important**:
 
+- **Always write at least `function result(userData)`, never `function result()`.** Omit trailing parameters you don't use: `result(userData)` if you only need user data, `result(userData, helperFunctions)` if you also need helpers, or `result(userData, helperFunctions, triggerContext)` if you need all three. You cannot skip a parameter to reach a later one (e.g. you must include `helperFunctions` to access `triggerContext`).
 - Computed fields can reference other computed fields via their keys in `inputs`
-- The function has access to a global `userData` object containing all user data
 - If `async` is true, the function can return a Promise
 - `input_triggers` specify additional keys that trigger recalculation
-- The `context` parameter provides `triggerContext` and `trackCustomEvent()` — same as actions (see "Trigger Context" and "Custom Event Tracking" under Actions)
 
 ## Actions Structure
 
@@ -536,19 +585,18 @@ Actions are stored in `Flow.dataOutputs` and transform to JS files. The `Action`
 
 **File Mapping**: `actions/{name}.js` (e.g., `actions/submit_form.js`)
 
-**Code Structure**: For `output: "custom"`, the `code` property contains JavaScript that must include a function called `output`. The runtime passes a `context` object as the first argument:
+**Code Structure**: For `output: "custom"`, the `code` property contains JavaScript that must include a function called `output`. The runtime passes three arguments — `userData`, `helperFunctions`, and `triggerContext`:
 
 ```javascript
-function output(context) {
-  // Access user data via global userData object
+function output(userData, helperFunctions, triggerContext) {
   const email = userData.email
   const name = userData.name
 
-  // context.triggerContext contains metadata about what fired this action (see below)
-  const trigger = context.triggerContext
+  // triggerContext contains metadata about what fired this action (see below)
+  const { triggerType, pageKey } = triggerContext || {}
 
-  // Track a custom analytics event (in-action usage)
-  context.trackCustomEvent('form_submitted', { email })
+  // Track a custom analytics event
+  helperFunctions.trackCustomEvent('form_submitted', { email })
 
   // Perform action (API call, data transformation, etc.)
   return {
@@ -558,11 +606,18 @@ function output(context) {
 }
 ```
 
+**Function arguments**:
+
+| Argument | Description |
+| --- | --- |
+| `userData` | Object containing all User Data at the time the action fires. |
+| `helperFunctions` | Object with helper utilities. Currently provides `trackCustomEvent(eventName, eventProps)` for analytics (see "Custom Event Tracking" below). |
+| `triggerContext` | Metadata about what triggered the action — see "Trigger Context" below. |
+
 **Important**:
 
+- **Always write at least `function output(userData)`, never `function output()`.** Omit trailing parameters you don't use: `output(userData)` if you only need user data, `output(userData, helperFunctions)` if you also need helpers, or `output(userData, helperFunctions, triggerContext)` if you need all three. You cannot skip a parameter to reach a later one (e.g. you must include `helperFunctions` to access `triggerContext`).
 - Actions are triggered by `outputs_on*` fields (see "Action Trigger Wiring" below) or programmatically
-- The function has access to a global `userData` object
-- The `context` parameter provides `triggerContext` and `trackCustomEvent` (see below)
 - For non-custom actions (airtable, hubspot, etc.), the action configuration is stored in config.json, not in the JS file
 
 ### Action Trigger Wiring (`outputs_on*` Fields)
@@ -585,12 +640,14 @@ These are top-level properties on the `Flow` object (stored in `config.json`):
 
 These are properties on `FlowPage` objects (stored in the page entry in `config.json`):
 
-| Field                     | Type                 | Fires when                                                 |
-| ------------------------- | -------------------- | ---------------------------------------------------------- |
-| `outputs_oncomplete`      | `string \| string[]` | The user completes this page (i.e. moves to the next page) |
-| `outputs_onload`          | `string \| string[]` | The page is loaded / navigated to                          |
-| `outputs_onopen_infobox`  | `string[]`           | An info box on this page is opened                         |
-| `outputs_onclose_infobox` | `string[]`           | An info box on this page is closed                         |
+| Field                     | Type       | Fires when                                                 |
+| ------------------------- | ---------- | ---------------------------------------------------------- |
+| `outputs_oncomplete`      | `string[]` | The user completes this page (i.e. moves to the next page) |
+| `outputs_onload`          | `string[]` | The page is loaded / navigated to                          |
+| `outputs_onopen_infobox`  | `string[]` | An info box on this page is opened                         |
+| `outputs_onclose_infobox` | `string[]` | An info box on this page is closed                         |
+
+**Note**: Page-level trigger fields must be arrays of action IDs. The runtime does not accept a single string for these fields.
 
 #### Component-Level Triggers
 
@@ -677,7 +734,9 @@ window.Savvy.triggerAction(embeddableId, actionId)
 
 ### Trigger Context (`triggerContext`)
 
-When the engine fires an action, it passes a `context` object to the `output(context)` function. `context.triggerContext` contains metadata about what triggered the action:
+`triggerContext` is the **third argument** passed to both `output(userData, helperFunctions, triggerContext)` and `result(userData, helperFunctions, triggerContext)`. It contains metadata about what triggered the action or computed field recalculation.
+
+**Action `triggerContext` fields**:
 
 | Field          | Type                  | Description                                                                                                                       |
 | -------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -690,8 +749,8 @@ When the engine fires an action, it passes a `context` object to the `output(con
 Example usage inside an action:
 
 ```javascript
-function output(context) {
-  const { triggerType, componentKey, pageKey } = context.triggerContext || {}
+function output(userData, helperFunctions, triggerContext) {
+  const { triggerType, componentKey, pageKey } = triggerContext || {}
 
   if (triggerType === 'oncomplete' && pageKey === 'checkout_page') {
     // Only run full submission on checkout page completion
@@ -703,7 +762,7 @@ function output(context) {
 }
 ```
 
-Computed fields also receive `context` in the `result(context)` function with the same `triggerContext` shape, which is useful for computed fields that need to behave differently based on what triggered their recalculation.
+**Computed field `triggerContext`**: Computed fields also receive `triggerContext` as the third argument. The shape differs from actions — it describes which input key changed rather than a UI event. This is useful for computed fields that need to behave differently based on what triggered their recalculation.
 
 ### Custom Event Tracking
 
@@ -711,14 +770,14 @@ Embeddables support tracking custom analytics events. There are two contexts whe
 
 #### 1. Inside Action or Computed Field Code (Runtime Context)
 
-Use `context.trackCustomEvent(eventName, eventProps)` inside `output()` or `result()` functions:
+Use `helperFunctions.trackCustomEvent(eventName, eventProps)` inside `output()` or `result()` functions:
 
 ```javascript
-function output(context) {
+function output(userData, helperFunctions, triggerContext) {
   const plan = userData.selected_plan
 
   // Track a custom event from within an action
-  context.trackCustomEvent('plan_selected', {
+  helperFunctions.trackCustomEvent('plan_selected', {
     plan: plan,
     price: userData.plan_price,
   })
@@ -744,10 +803,10 @@ window.Savvy.trackCustomEvent('flow_abc123', 'external_checkout_complete', {
 
 #### When to Use Which
 
-| Context                        | API                                                  | Use when                                                                                                                                             |
-| ------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Inside `output()` / `result()` | `context.trackCustomEvent(name, props)`              | Tracking events as part of action/computed field logic (e.g. after a form submission, when a computed value changes)                                 |
-| Host page JS                   | `window.Savvy.trackCustomEvent(flowId, name, props)` | Tracking events from outside the embeddable (e.g. after an external checkout, on a parent SPA route change, from a third-party integration callback) |
+| Context                        | API                                                           | Use when                                                                                                                                             |
+| ------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Inside `output()` / `result()` | `helperFunctions.trackCustomEvent(name, props)`               | Tracking events as part of action/computed field logic (e.g. after a form submission, when a computed value changes)                                 |
+| Host page JS                   | `window.Savvy.trackCustomEvent(flowId, name, props)`          | Tracking events from outside the embeddable (e.g. after an external checkout, on a parent SPA route change, from a third-party integration callback) |
 
 ## Conditions Structure
 
@@ -885,14 +944,12 @@ The `_docs` property (string only) documents non-obvious aspects of the embeddab
 ### JS Files (Computed Fields)
 
 - Location: `computed-fields/{key}.js`
-- Export: Function named `result` that returns computed value
-- Access: Global `userData` object available; `context` parameter provides `triggerContext` and `trackCustomEvent()`
+- Export: Function named `result` that returns computed value — signature is `result(userData)`, `result(userData, helperFunctions)`, or `result(userData, helperFunctions, triggerContext)` depending on which arguments are needed (include only the ones you use; trailing unused parameters can be omitted)
 
 ### JS Files (Actions)
 
 - Location: `actions/{name}.js`
-- Export: Function named `output` for custom actions
-- Access: Global `userData` object available; `context` parameter provides `triggerContext` and `trackCustomEvent()`
+- Export: Function named `output` for custom actions — signature is `output(userData)`, `output(userData, helperFunctions)`, or `output(userData, helperFunctions, triggerContext)` depending on which arguments are needed (include only the ones you use; trailing unused parameters can be omitted)
 
 ## Key Principles for Modifications
 
@@ -931,8 +988,20 @@ The `_docs` property (string only) documents non-obvious aspects of the embeddab
 
 13. **Asset URL Source of Truth**: If `assets.json` exists in the project root, use it as the first source for image/file URLs. Prefer matching by `flow_id` (or `flow_id: null` for project-level shared assets) and use `relativePath` when mapping local files to uploaded URLs. Always use the (uploaded) url property, not local relative paths, as the image src when building in React.
 
+14. **Review before save**: When any change is made (pages, components, styles, config, actions, computed fields), follow "When to Review (Required Checks)" above. Always review the JSON diff before running `embeddables save`.
+
 ## Common Patterns
 
+### Carousel / Swiper
+
+When you need to build a carousel or slider, **always consult the carousel implementation guide first** (injected by `embeddables init` into your AI rules directory).
+
+Key points:
+
+- Swiper v11.2.10 is loaded at runtime via CDN — no build tooling required.
+- Turn any `Container` with child elements into a carousel via an action file that loads and initializes Swiper.
+- The guide covers the full pattern: page TSX structure, the initialization action, CSS, and optional prev/next navigation buttons.
+
 ### Adding a New Page
 
 1. Create `pages/{pageKey}.page.tsx` with `'use client'` at the top and a default export.
@@ -959,14 +1028,14 @@ The `_docs` property (string only) documents non-obvious aspects of the embeddab
 ### Adding a Computed Field
 
 1. Create JS file: `computed-fields/{key}.js`
-2. Implement `result()` function
+2. Implement `result(userData, helperFunctions, triggerContext)` function — access input values via `userData`, use `helperFunctions.trackCustomEvent()` for analytics if needed
 3. Add metadata to config.json: `computedFields` array
 4. Specify `inputs` array for dependencies
 
 ### Adding an Action
 
 1. Create JS file: `actions/{name}.js`
-2. Implement `output(context)` function (for custom actions) — use `context.triggerContext` for trigger metadata and `context.trackCustomEvent()` for analytics
+2. Implement `output(userData, helperFunctions, triggerContext)` function (for custom actions) — access data via `userData`, use `triggerContext` for trigger metadata and `helperFunctions.trackCustomEvent()` for analytics
 3. Add metadata to config.json: `dataOutputs` array
 4. Configure action type and mappings in config.json
 5. Wire the action to a trigger: add the action's `id` to the appropriate `outputs_on*` field on the flow (config.json top-level), page (config.json pages entry), or component (React prop)
@@ -1050,9 +1119,14 @@ Add a `languages` prop to any component in your `.page.tsx` or `.location.tsx` f
 />
 ```
 
-### Adding Translations to OptionSelector Buttons
+### Adding Translations to OptionSelector
+
+For OptionSelector components, translations can be added both:
+
+- on the component itself (e.g., `label`, `placeholder`), and
+- on each **button** object (e.g., `text`, `description`).
 
-For OptionSelector components, translations are added on each **button** object (not on the component itself). Add a `languages` property inside each button definition. The `OptionSelectorButtonWithLanguages` type (not plain `OptionSelectorButton`) is required here since it includes the `languages` property:
+Add a `languages` property at the appropriate level for the attributes being translated. The `OptionSelectorButtonWithLanguages` type (not plain `OptionSelectorButton`) is required for button constants since it includes the `languages` property:
 
 ```tsx
 import { OptionSelector } from '@embeddables/cli/components'
@@ -1095,7 +1169,7 @@ Any text-based attribute on a component can be translated. Common translatable a
 | `RichTextMarkdown` | `text`                                                             |
 | `CustomButton`     | `text`, `description`                                              |
 | `InputBox`         | `label`, `placeholder`, `empty_invalid_message`                    |
-| `OptionSelector`   | `label` (on the component); `text`, `description` (on each button) |
+| `OptionSelector`   | `label`, `placeholder` (on the component); `text`, `description` (on each button) |
 | `MediaImage`       | `caption`, `alt_text`                                              |
 | `FileUpload`       | `label`                                                            |
 

package/.prompts/short-rule-body.md

@@ -0,0 +1,15 @@
+# Embeddables CLI
+
+**Before editing embeddables, read [embeddables/AI-README.md](embeddables/AI-README.md) for the full guide.**
+
+[embeddables/AI-README.md](embeddables/AI-README.md) is the single source of truth for working with Embeddables in this project. It covers:
+
+- **Overview** — how the CLI transforms Embeddable JSON into local React/CSS/JS files
+- **Embeddable Structure** — Flow, pages, components, styles, computed fields, actions
+- **Component Types** — all types, allowed props, and the registry
+- **File Layout** — pages/, global-components/, styles/, computed-fields/, actions/, config.json
+- **CLI Commands** — pull, dev, build, save, inspect, init, branch
+- **Compiler Pipeline** — forward (React → JSON) and reverse (JSON → React)
+- **AI & Agent Rules** — command safety, types as source of truth, no publish commands
+
+Re-inject this guide at any time by running `embeddables init` in your project root.

package/README.md

@@ -88,6 +88,48 @@ The project ID is stored in `embeddables.json` and enables interactive embeddabl
 
 Authenticate with your Embeddables account.
 
+**Interactive mode** (default):
+
+```bash
+embeddables login
+```
+
+Prompts for email, sends OTP, then prompts for the code.
+
+**Non-interactive mode** (for CI, automated environments, AI agents):
+
+```bash
+# Option 1: Token-based login (single step)
+embeddables login --token <your-token>
+
+# Option 2: OTP-based login (two steps)
+embeddables login --email <your-email>
+embeddables provide-otp --code <code-from-email>
+```
+
+Options:
+
+- `-t, --token <token>`: Use a token for non-interactive login (e.g. CI, cloud containers)
+- `-e, --email <email>`: Send OTP to email address (non-interactive, step 1 of 2)
+
+### `embeddables provide-otp`
+
+Complete non-interactive login by providing the OTP code received via email. This is step 2 of the non-interactive OTP login flow.
+
+```bash
+# First, request OTP
+embeddables login --email your@email.com
+
+# Then, provide the code from your email
+embeddables provide-otp --code 123456
+```
+
+Options:
+
+- `-c, --code <code>`: OTP code from email (required, 6-digit code)
+
+The OTP code expires after 10 minutes. If expired, run `embeddables login --email` again to request a new code.
+
 ### `embeddables logout`
 
 Clear stored authentication.
@@ -154,6 +196,58 @@ Options:
 - `-s, --skip-build`: Skip the build step and use existing compiled JSON from `.generated/embeddable.json`
 - `--from-version <number>`: Base version number (auto-detected from local config/files if not provided)
 
+### `embeddables dangerously-publish`
+
+Promote an **existing** saved version on the server to staging or production (same idea as the Builder: you pick a version, you don’t create a new one by default). **Use with caution** — this bypasses the normal review workflow. Requires login; production requires publisher/admin.
+
+You must specify exactly one of `--staging` or `--prod`. If you omit both, the command exits with an error.
+
+**Default (no `--save`)** — no new version is created:
+
+- The version to promote is resolved in this order: `--publish-version`, then `_version` in `embeddables/<id>/config.json`, then the highest version inferred from `.generated/` snapshot filenames.
+- The CLI calls the set-version-status API (main-line only; branch checkouts are rejected). The server still enforces rules (e.g. production only if that version is already on staging).
+
+**With `--save`** — build, upload a **new** saved version, then publish **that** new version:
+
+- Same build/upload flow as `embeddables save`; then promote to `--staging`, or to production with `--prod --via-staging` (**`--save --prod` without `--via-staging` is not allowed** — new versions must hit staging before production). The base version for the save is taken from `config.json` `_version` or `.generated/` snapshots (same as `embeddables save` without `--from-version`).
+- Use `--skip-build` to reuse `.generated/embeddable.json`.
+- Local snapshots after save are written as `embeddable-main@<version>.json` under `.generated/`.
+
+Options:
+
+- `-i, --id <id>`: Embeddable ID (will prompt from local embeddables if not provided)
+- `-l, --label <label>`: Label for the new version (**only with `--save`**)
+- `--skip-build`: Skip the build step (**only with `--save`**)
+- `--publish-version <number>`: Promote this version number instead of `config.json` `_version` (no new version unless `--save`)
+- `-p, --project-id <id>`: Project ID (will prompt if not configured)
+- `--save`: Build (unless skipped), create a new saved version on the server, then publish it
+- `--force`: Skip confirmation prompts on version conflicts (**when using `--save`**)
+- `--staging`: Publish to staging
+- `--prod`: Publish to production only (single API step; the version must **already** be on staging server-side)
+- `--via-staging`: With `--prod`, push to staging first, then production (for when the version is not on staging yet)
+
+Examples:
+
+```bash
+# Promote the version in config.json (_version) to staging (no new save)
+embeddables dangerously-publish --staging
+
+# Promote a specific existing version to staging
+embeddables dangerously-publish --staging --publish-version 42
+
+# Promote to production (version must already be staging on the server)
+embeddables dangerously-publish --prod
+
+# Production: staging first, then prod (e.g. version still SAVED)
+embeddables dangerously-publish --prod --via-staging
+
+# Build, save a new version, then publish that version to staging
+embeddables dangerously-publish --save --staging
+
+# Save, then staging and production (new version is not on staging yet)
+embeddables dangerously-publish --save --prod --via-staging
+```
+
 ### `embeddables dev`
 
 Start a dev server with hot reload. Proxies to the Engine; by default uses production (`https://engine.embeddables.com`). Use `--local` to point to a local engine.