autokap 1.0.6 → 1.0.8

package/assets/skill/SKILL.md

@@ -1,575 +1,560 @@
 ---
 name: autokap-preset
-description: Generate AutoKap preset configurations for automated screenshot, clip, and video capture of web applications
+description: >
+  Generate AutoKap capture programs — deterministic opcode sequences for automated
+  screenshot, clip, and interactive demo capture of web apps. Use when: creating or updating presets,
+  adding data-ak attributes for capture automation, or debugging failed capture programs.
 metadata:
   author: AutoKap
-  version: 1.0.0
+  version: 2.3.0
 ---
 
 # AutoKap Preset Creation Skill
 
-## What is AutoKap
+## Mental Model
 
-AutoKap is a screenshot and video capture automation platform. It uses an AI agent inside a headless browser (Playwright) to navigate web applications and capture screenshots, clips (short animated GIFs/MP4s), or demo videos.
+AutoKap is **not** a freeform runtime navigation agent. Your job is to inspect the user's codebase, add stable selectors where needed, and generate a **deterministic program** (a JSON sequence of browser opcodes) that the AutoKap CLI executes locally via Playwright.
 
-A **preset** defines what to capture: which pages, which viewports/devices, which languages and themes, and how to navigate to the right state. A single preset can generate dozens of assets — one per combination of (page x target x language x theme).
+Normal navigation and interaction stay deterministic. Runtime AI is limited to narrow fallback tasks such as overlay dismissal fallback, capture verification, alt text generation, and the last-resort healer. Do **not** design flows that depend on an LLM improvising navigation at runtime.
 
-## Your Task
+This installed skill is the **source of truth** for the AutoKap contract: opcode schema, login rules, variant handling, persistence, and validation. The copied prompt from the AutoKap dashboard is only the **preset-specific brief** (project URL, variants, template goal, mock data guidance, etc.).
 
-You are being asked to create one or more AutoKap presets for the user's project. Your job is to:
+## When To Use This Skill
 
-1. **Analyze the project** — look at the codebase (routes, pages, components, UI structure) to understand what the application looks like and how it's organized
-2. **Generate a complete preset configuration** in JSON format that AutoKap can import directly
-3. **Write precise navigation prompts** — the capture agent sees a screenshot + accessibility tree and follows your instructions to reach the right page state
+- User wants to capture screenshots, clips, or interactive demos of their web app
+- User asks to create or update an AutoKap preset
+- User needs `data-ak` attributes added to UI elements for capture
+- User is debugging a failed capture program
 
-You know this project intimately. Use that knowledge to write prompts that are specific to the actual UI — reference real navigation elements, real page routes, real UI components.
+## Before Generating Anything
 
-### Variants (CRITICAL)
+1. **Inspect the codebase first** — Read the relevant routes, layouts, auth checks, theme/locale system, and the components you may need to tag. Do not start by guessing opcodes.
+2. **Decide whether auth is required** — If any target route is protected, the program must begin with the canonical login flow. Never assume the user is already logged in.
+3. **Understand how locale and theme really work** — Prefer storage-based `SET_LOCALE` / `SET_THEME` with `"$variant"` when the app supports it. If the app uses URL-based locale routing, reflect that in `NAVIGATE`.
+4. **Understand the UI states** — Know which conditions make modals, dropdowns, tabs, tables, empty states, or dashboards appear before you write selectors or opcodes.
+5. **Use planning mode if the assistant supports it** — Make a short plan before editing code or generating the program.
+6. **Ask clarifying questions when navigation is ambiguous** — If the codebase or prompt does not clearly reveal how to reach a state, ask instead of inventing UI details.
+7. **Do not break the one-shot flow** — When CLI access is available, persist the preset so the user can run `autokap run <preset-id>` immediately. Manual JSON output is a fallback, not the default.
 
-The prompt will include a "Variants" section specifying the exact `langs`, `themes`, and `targets` to use. **You MUST copy these values exactly into the preset config** — do not change, add, or remove any value. The user has already chosen their desired languages, themes, and device viewports. Your job is only to write the capture prompts (what to navigate to, what to capture).
+## Quick Workflow
 
-**Targets and mockupOptions**: The targets include `viewport`, `deviceFrame`, and `mockupOptions` (orientation, status bar, dock, safe areas, etc.) that the user has specifically configured. Copy each target object exactly as-is into the preset's `targets` array. Do not modify `mockupOptions` — if the user chose landscape orientation, keep landscape. If they configured a status bar, keep it.
+1. **Understand the capture goal** — What pages/states should be captured? Screenshot, clip, or interactive demo? Which viewports, locales, themes, and mockups matter?
+2. **Inspect the implementation** — Confirm routes, auth, theme, locale, and any dynamic UI state in the codebase.
+3. **Add `data-ak` attributes** — Tag every element the opcodes must interact with using stable selectors.
+4. **Choose media mode and variants** — Set `mediaMode` and define the exact viewport/locale/theme combinations.
+5. **Generate the `ExecutionProgram`** — Write deterministic opcodes and explicit postconditions.
+6. **Persist the preset** — Prefer `autokap preset create|update` so the program lives inside `config.program`.
+7. **Validate it** — Run the recommended checks and at least one real `autokap run <preset-id>` before considering the work done.
+8. **Integrate dev links** — Run `autokap preset info <preset-id>` and use the structured output to wire endpoint URLs into the codebase (`<img>`, `<video>`, `<iframe>`, or component props). This is part of the one-shot flow — do not stop after validation.
 
-If the variants include multiple languages, you must provide `langInstructions` based on how the app actually switches language (look at the i18n setup in the code).
-If the variants include both light and dark themes, you must provide `themeInstructions` based on the actual theme toggle mechanism in the code.
+## Bundled References
 
----
+Load these only when the request actually needs them:
 
-## PresetConfig Schema
+- **Opcode parameters** — [OPCODE-REFERENCE.md](OPCODE-REFERENCE.md)
+- **Interactive demos** — [references/interactive-demo.md](references/interactive-demo.md)
+- **Mock data** — [references/mock-data.md](references/mock-data.md)
+- **Complete examples** — [references/examples.md](references/examples.md)
 
-The output must conform to this TypeScript schema. All fields are documented below.
+Keep the core `SKILL.md` for the non-negotiable contract. Reach for the
+references only after you know which mode or advanced feature the user needs.
 
-```typescript
-/** Top-level preset object for import */
-interface PresetImport {
-  name: string;        // Display name (e.g. "Homepage Hero", "Pricing Page")
-  description: string; // What this preset captures and why
-  config: PresetConfig;
-}
+## Adding `data-ak` Attributes
 
-/** The full preset configuration */
-type PresetConfig = {
-  /** The application URL (root URL of the project) */
-  url?: string;
-
-  /**
-   * Main capture prompt — natural language instructions for the agent.
-   * Ignored when `pages` is defined (each page has its own prompt).
-   */
-  prompt: string;
-
-  /** Device/viewport targets for capture */
-  targets: CaptureTarget[];
-
-  /** Output resolution multiplier. Default: 2 */
-  outputScale?: number;
-
-  /** Languages to capture. E.g. ["en", "fr", "de"] */
-  langs: string[];
-
-  /** Themes to capture */
-  themes: Array<"light" | "dark">;
-
-  /** Max agent iterations before giving up. Default: 60 */
-  maxIterations: number;
-
-  /**
-   * How to switch language in the UI.
-   * Must describe actual UI controls, not abstract instructions.
-   * Example: "Click the language dropdown in the footer and select the target language"
-   * If the app uses URL-based locale (e.g. /fr/pricing), say so.
-   */
-  langInstructions?: string;
-
-  /**
-   * How to switch theme in the UI.
-   * Must describe actual UI controls.
-   * Example: "Click the sun/moon icon in the top-right header to toggle dark mode"
-   */
-  themeInstructions?: string;
-
-  /** General navigation instructions applied to ALL captures (prepended to each page prompt) */
-  navigationInstructions?: string;
-
-  /**
-   * Login credentials. The agent handles login automatically before running page prompts.
-   * Only email/password auth is supported. OAuth, SSO, MFA, magic links are NOT supported.
-   */
-  credentials?: {
-    loginUrl?: string;  // Login page URL
-    email?: string;
-    password?: string;
-  };
+For every element you interact with in the opcodes, add a `data-ak="descriptive-name"` attribute:
 
-  /**
-   * Named capture pages — each page runs its own agent session with its own prompt.
-   * When defined, the top-level `prompt` field is ignored.
-   * CRITICAL: Each page runs independently with NO memory of other pages.
-   */
-  pages?: CapturePage[];
-
-  /**
-   * Isolated UI elements to extract from captured pages.
-   * Each element is cropped from the full page capture.
-   */
-  elements?: IsolatedElement[];
-
-  /**
-   * Network interception: replace API responses with LLM-generated mock data.
-   * Useful for showing populated UIs without real data.
-   */
-  mockData?: MockDataConfig;
-
-  /** Capture mode. Default: "screenshot" */
-  captureMode?: "screenshot" | "clip" | "video";
-
-  /** Clip definitions (when captureMode === "clip") */
-  clips?: ClipDefinition[];
-
-  /** Clip export options */
-  clipOptions?: ClipOptions;
-};
-
-interface CaptureTarget {
-  /** Unique identifier for this target */
-  id: string;
-  /** Display label */
-  label: string;
-  /** Browser viewport dimensions */
-  viewport: { width: number; height: number };
-  /**
-   * Optional device frame for mockup rendering.
-   * Available frames: "iphone-16-pro", "ipad-pro-11-m4", "ipad-air-m4",
-   *                   "macbook-air-13", "macbook-pro-16"
-   */
-  deviceFrame?: string;
-  /** Mockup rendering options */
-  mockupOptions?: MockupOptions;
-}
+```jsx
+// Before
+<button onClick={handleLogin}>Sign in</button>
+<input type="email" placeholder="Email" />
 
-interface MockupOptions {
-  orientation?: "portrait" | "landscape";
-  outputScale?: number;
-  showStatusBar?: boolean;
-  statusBar?: StatusBarConfig;
-  showDock?: boolean;        // Mac only
-  dockScale?: number;        // Mac only
-  dockMode?: "integrated" | "only-app"; // Mac only
-}
+// After
+<button data-ak="login-btn" onClick={handleLogin}>Sign in</button>
+<input data-ak="login-email" type="email" placeholder="Email" />
+```
 
-interface StatusBarConfig {
-  time?: string;
-  signalStrength?: number;
-  wifiStrength?: number;
-  batteryLevel?: number;
-  batteryCharging?: boolean;
-  colorScheme?: "light" | "dark";
-  autoLocale?: boolean; // Auto-adapt status bar to capture language (default: true)
-}
+**Rules:**
+- Use kebab-case: `login-btn`, `pricing-table`, `theme-toggle`
+- Add ONLY to elements that opcodes interact with
+- For dynamic lists, add `data-ak` to the container AND item template:
+  ```jsx
+  <ul data-ak="project-list">
+    {projects.map(p => <li data-ak="project-item" key={p.id}>{p.name}</li>)}
+  </ul>
+  ```
+  Target: `[data-ak="project-list"] [data-ak="project-item"]:nth-child(2)`
+- Zero runtime cost and no security implications
 
-interface CapturePage {
-  /**
-   * Unique slug identifier. MUST match: /^[a-z0-9_-]+$/
-   * Use descriptive slugs: "pricing", "dashboard-overview", "settings-billing"
-   * AVOID generic slugs: "main", "page1", "page2", "screen1"
-   */
-  id: string;
-  /** Display name shown in the UI */
-  name: string;
-  /**
-   * Navigation prompt for the agent to reach this page/state.
-   * MUST be self-contained — the agent has NO memory of other pages.
-   * Include: where to navigate, what to click, what state to reach.
-   */
-  prompt: string;
-  /** Optional URL override if this page is at a different URL than the preset root */
-  url?: string;
-}
+## ExecutionProgram Schema
 
-interface IsolatedElement {
-  /** Element name (used in output filenames) */
-  name: string;
-  /**
-   * Description of the DOM element to crop.
-   * Must be visually identifiable — the agent matches against what it sees.
-   * GOOD: "The pricing table with 3 plan columns"
-   * GOOD: "The blue CTA button in the hero section"
-   * BAD: "The main content" (too vague)
-   */
-  description: string;
-  /** Source page id — when the preset has multiple pages, specify which page this element belongs to */
-  sourcePageId?: string;
-  /** Outscale config for padding around the element */
-  outscale?: OutscaleConfig;
+```typescript
+interface ExecutionProgram {
+  presetId: string;         // Unique slug (e.g. "homepage-hero")
+  programVersion: number;   // Always 1 for new programs
+  mediaMode: 'screenshot' | 'clip' | 'dom';
+  baseUrl: string;          // Root URL of the application
+  variants: VariantSpec[];  // Viewport/locale/theme combinations
+  preconditions: {
+    // Auth bootstrap auto-adapts to whatever is configured on the preset.
+    // If the preset has stored auth cookies, the runtime injects them into
+    // the browser context. If it has stored credentials (email/password), they
+    // are substituted into {{email}}/{{password}}/{{loginUrl}} placeholders
+    // inside opcodes — the program performs the UI login itself.
+    // If neither is set, the run is anonymous. Both can coexist.
+    credentialsId?: string; // Optional metadata pointer
+  };
+  steps: ExecutionOpcode[];
+  artifactPlan: {
+    mediaMode: 'screenshot' | 'clip' | 'dom';
+    cursorTheme?: 'minimal' | 'macos' | 'windows'; // Clip only. Default: 'minimal'
+    format?: {
+      clipFormat?: 'gif' | 'mp4' | 'both';      // Default: 'gif'
+      screenshotFormat?: 'png' | 'jpeg';          // Default: 'png'
+    };
+    applyMockup?: boolean;     // Apply device frame mockup
+    applyStatusBar?: boolean;  // Add status bar to mockup
+  };
+  compileFingerprint: string;    // e.g. "v1-homepage"
+  variantFingerprint?: string;   // "langs:en,fr|themes:dark,light"
+  compiledAt: string;            // ISO timestamp
+  compiledWith?: string;         // "ai-assistant"
 }
 
-interface OutscaleConfig {
-  /** Uniform padding on all 4 sides (pixels) */
-  padding?: number;
-  paddingTop?: number;
-  paddingRight?: number;
-  paddingBottom?: number;
-  paddingLeft?: number;
-  /** Percentage-based padding relative to element dimensions (0-100) */
-  paddingPercent?: number;
-  /** Background fill color. Default: transparent */
-  backgroundColor?: string;
+interface VariantSpec {
+  id: string;                // e.g. "desktop-en-light"
+  viewport: { width: number; height: number };
+  deviceScaleFactor?: number;
+  locale?: string;           // BCP-47 (e.g. "en", "fr")
+  theme?: 'light' | 'dark';
+  targetId?: string;         // Stable preset target id (e.g. "desktop")
+  targetLabel?: string;      // Human-readable label (e.g. "Desktop")
+  deviceFrame?: string;      // e.g. "iphone-16-pro" for mockup
 }
+```
 
-interface MockDataConfig {
-  enabled: boolean;
-  /**
-   * Specific description of what data to generate.
-   * GOOD: "5 customer invoices with amounts between $50-500, mix of paid/pending/overdue statuses"
-   * BAD: "Some sample data"
-   */
-  description: string;
-  /** Explicitly target specific API endpoints to mock */
-  endpoints?: { url: string; method?: string }[];
-}
+## Opcode Quick Reference
+
+24 opcodes available. For full parameter documentation, see [OPCODE-REFERENCE.md](OPCODE-REFERENCE.md).
+
+| Kind | Selector? | Key Params | Typical Postcondition | Notes |
+|------|-----------|-----------|----------------------|-------|
+| `NAVIGATE` | no | `url` | `route_matches` | Always first step |
+| `DISMISS_OVERLAYS` | no | — | `overlay_dismissed` | Always after NAVIGATE |
+| `CLICK` | yes | `button?` | `element_visible` / `route_matches` | Postcondition = what CHANGED |
+| `TYPE` | yes | `text`, `clearFirst` | `any_change` | `{{email}}` / `{{password}}` for creds |
+| `PRESS_KEY` | no | `key` | `any_change` | `"Enter"`, `"Escape"`, `"Tab"`, etc. |
+| `WAIT_FOR` | yes* | `state` | `element_visible` | `"visible"` or `"attached"` (DOM only) |
+| `SCROLL` | no | `direction`, `targetSelector?`, `amount?` | `element_visible` | Use `targetSelector` for precise scroll |
+| `HOVER` | yes | — | `element_visible` | Capture immediately after for hover state |
+| `SELECT_OPTION` | yes | `optionLabel` / `optionValue` / `optionIndex` | `text_contains` | **Native `<select>` only.** Custom dropdowns: use CLICK sequence |
+| `CHECK` | yes | `checked` | `always` | Idempotent. Safer than CLICK for checkboxes |
+| `DOUBLE_CLICK` | yes | — | `element_visible` / `any_change` | Inline editing, text selection |
+| `SET_LOCALE` | no | `locale`, `method`, `storageHints?` | `always` | Use `"$variant"`. Prefer `method: "storage"` |
+| `SET_THEME` | no | `theme`, `method`, `storageHints?` | `always` | Use `"$variant"`. Prefer `method: "storage"` |
+| `ASSERT_ROUTE` | no | `urlPattern` | `route_matches` | Validation checkpoint |
+| `ASSERT_SURFACE` | no | `selectors[]`, `matchAll` | `always` | Validation checkpoint |
+| `CAPTURE_SCREENSHOT` | no | `captureId`, `captureName`, `elementSelector?` | `always` | `elementSelector` for element-level crop |
+| `CAPTURE_DOM` | no | `stateName`, `selector?` | `always` | Interactive Demo state — see [Interactive Demo Workflow](#interactive-demo-workflow). `mediaMode: "dom"` only. Add `selector` to capture a focused subtree instead of the whole page. |
+| `CAPTURE_FRAGMENT` | yes | `fragmentName`, `parentState`, `selector`, `variantName?`, `triggerSelector?`, `mountStrategy?` | `always` | Interactive Demo fragment (modal/popover/dropdown/local subtree) — see [Fragments](#fragments-and-local-interactions). Mounted on top of `parentState` by the player. Capture the same fragment under multiple `variantName`s to enable in-place swap (e.g. background colour change). |
+| `BEGIN_CLIP` | no | `clipId`, `clipName` | `always` | Start recording |
+| `END_CLIP` | no | `clipId`, `clipName` | `always` | Stop recording. Same `clipId` as BEGIN_CLIP |
+| `CLONE_ELEMENT` | yes | `sourceSelector`, `containerSelector`, `count` | `always` | **Non-blocking.** Duplicate a template element N times |
+| `INJECT_MOCK_DATA` | yes | `groupName` + clone fields and/or trigger fields | `always` | **Non-blocking.** Apply both clone (instant visual) AND trigger (survives re-renders) whenever possible |
+| `REMOVE_ELEMENT` | yes | `selector` | `always` | **Non-blocking.** Remove empty-state placeholders / unwanted nodes |
+| `SET_ATTRIBUTE` | yes | `attribute`, `value` | `always` | **Non-blocking.** Set attribute (e.g. `src` on an `<img>`) |
+
+*WAIT_FOR requires `selector` or semantic `target`.
+
+## Postcondition Types
+
+| Type | Fields | When to use |
+|------|--------|-------------|
+| `route_matches` | `pattern` | After NAVIGATE, CLICK that changes page |
+| `element_visible` | `selector`, `waitMs?` | After CLICK/HOVER that opens modal/dropdown/tooltip |
+| `element_absent` | `selector` | After CLICK that closes modal |
+| `text_contains` | `selector`, `text` | After TYPE, SELECT_OPTION |
+| `overlay_dismissed` | — | After DISMISS_OVERLAYS |
+| `screenshot_stable` | `threshold?` (0-1), `waitMs?` | Before CAPTURE_SCREENSHOT when page has animations |
+| `any_change` | — | After TYPE, PRESS_KEY, DOUBLE_CLICK (soft check) |
+| `always` | — | CAPTURE_SCREENSHOT, SET_LOCALE, SET_THEME, CHECK, BEGIN/END_CLIP |
+
+## What Presets Can and Cannot Do
+
+### Capabilities
+
+- **Multi-viewport**: desktop, tablet, mobile in a single program
+- **Multi-locale**: switch languages via SET_LOCALE with `"$variant"` placeholder
+- **Multi-theme**: switch light/dark via SET_THEME with `"$variant"` placeholder
+- **Authenticated flows**: login via TYPE with `{{email}}`/`{{password}}` credential placeholders
+- **Element-level capture**: crop screenshot to a specific component with `elementSelector`
+- **Clips**: record interactions as GIF, MP4, or both via BEGIN_CLIP/END_CLIP
+- **Device mockups**: wrap screenshots in device frames (`applyMockup: true`)
+- **Status bars**: add device status bar to mockups (`applyStatusBar: true`)
+- **Hover states**: capture tooltips, dropdown menus via HOVER + CAPTURE_SCREENSHOT
+- **Scroll-to-element**: scroll specific sections into view with SCROLL
+- **Right-click menus**: context menus via CLICK with `button: "right"`
+- **Native selects**: option selection via SELECT_OPTION
+- **Checkboxes/toggles**: idempotent state control via CHECK
+
+### Limitations
+
+- **No file uploads**: native OS file dialogs cannot be automated
+- **No complex drag-and-drop**: simple clicks only, no drag gestures
+- **No multi-tab workflows**: single page context per execution
+- **No native OS dialogs**: print, save-as, permission prompts are inaccessible
+- **No CAPTCHAs**: cannot solve CAPTCHAs or bot detection challenges
+- **No real-time dynamic data**: data that changes between runs produces inconsistent captures
+- **No cross-origin iframes**: cannot interact with content from different origins
+- **No browser extensions**: extension UIs are not accessible via Playwright
+
+## Anti-Patterns
+
+| Do NOT | Do instead |
+|--------|-----------|
+| Use SELECT_OPTION for custom dropdowns (Radix, Headless UI, MUI) | CLICK to open + WAIT_FOR options + CLICK the option |
+| Use CLICK for checkboxes | CHECK (idempotent, sets state directly) |
+| Omit postconditions | Every opcode needs a postcondition describing the expected result |
+| Hardcode locale/theme values in SET_LOCALE/SET_THEME | Use `"$variant"` — runtime substitutes the current variant's value |
+| Use `method: "ui_interaction"` for locale/theme | Use `method: "storage"` — instant, reliable, no UI dependency |
+| Tell the user to save a local `program.json` file | Persist the preset via CLI; only output full JSON as a fallback if the CLI/server write fails |
+| Guess CSS selectors | Add `data-ak` attributes to the code first |
+| Skip WAIT_FOR after page transitions | Add WAIT_FOR with `waitMs: 10000` after login, navigation, modal open |
+| Use NAVIGATE or SCROLL inside a clip to reach a clickable target | CLICK the link/button — cursor animates to it naturally |
+| Skip `cursorTheme` in clip `artifactPlan` | Set `cursorTheme: "macos"` or `"windows"` for polished recordings |
+
+## Clip Workflow
+
+For recording video clips of interactions:
+
+1. Set `mediaMode: "clip"` on the program
+2. Set `artifactPlan.format.clipFormat` to `"gif"`, `"mp4"`, or `"both"`
+3. Set `artifactPlan.cursorTheme` to `"minimal"`, `"macos"`, or `"windows"` (default: `"minimal"`)
+4. Put navigation and setup steps **before** BEGIN_CLIP (they won't be recorded)
+5. Place `BEGIN_CLIP` with a `clipId` and `clipName` to start recording
+6. All interaction steps between BEGIN_CLIP and END_CLIP are recorded
+7. Place `END_CLIP` with the **same `clipId`** to stop recording
+
+### Cursor animation (automatic)
+
+During clip recording, the runtime automatically animates a visible cursor with **cubic Bézier curves** for every CLICK, HOVER, TYPE, CHECK, DOUBLE_CLICK, and SCROLL opcode. The cursor moves smoothly (350–900 ms depending on distance), with randomized control points and micro-jitter to look human. You do **not** need to script cursor movement yourself — just emit the right interaction opcodes and the runtime handles the animation.
+
+### Designing human-like clip programs
+
+Because the cursor is visible during recording, **how** you reach a target matters as much as reaching it:
+
+| Do | Don't | Why |
+|---|---|---|
+| **CLICK** on a nav link / anchor to scroll to a section | SCROLL blindly then capture | The cursor animates to the link before clicking — the viewer sees intentional navigation |
+| **CLICK** on an in-page link to change route | NAVIGATE to the new URL mid-clip | NAVIGATE is an instant browser jump with no cursor motion — it looks like a cut, not a flow |
+| **HOVER** → pause → **CLICK** for important interactions | CLICK without HOVER | HOVER gives the viewer time to see where the cursor is heading and creates anticipation |
+| Keep the clip short and focused (5–15 interactions) | Record an entire user journey in one clip | Long clips lose the viewer. Split into multiple clips if needed |
+| Place WAIT_FOR after CLICK that triggers a route change | Immediately interact after navigation | Gives the page time to render and the viewer time to register the new state |
+| Add a `screenshot_stable` WAIT_FOR before BEGIN_CLIP when DISMISS_OVERLAYS precedes it | Start recording immediately after DISMISS_OVERLAYS | Overlay dismiss animations (fade-out, slide) bleed into the first frames of the clip |
+
+**Rule of thumb:** inside a clip, never use NAVIGATE or SCROLL to reach content that the user would normally reach by clicking a link or button. Use CLICK on that element instead — the cursor animation makes the transition visible and human-like.
+
+SCROLL is still appropriate for:
+- Scrolling down a long page to reveal below-the-fold content when there is no clickable anchor
+- Scrolling inside a container or list
+
+### Clean start: wait for visual stability before recording
+
+When `DISMISS_OVERLAYS` runs shortly before `BEGIN_CLIP`, overlay dismiss animations (fade-out, slide-away) can bleed into the first frames of the clip. Add a `screenshot_stable` WAIT_FOR between them so the page is visually settled before recording begins:
 
-interface ClipDefinition {
-  /** Unique slug identifier */
-  id: string;
-  /** Display name */
-  name: string;
-  /**
-   * What to record — the interaction the clip captures.
-   * When navigationScript is also provided, this describes ONLY the recording phase.
-   */
-  script: string;
-  /**
-   * Optional: navigation instructions to reach the page BEFORE recording starts.
-   * When provided, the navigation agent follows these to reach the page,
-   * then the recording system executes `script`.
-   */
-  navigationScript?: string;
-  /** Optional URL override */
-  url?: string;
-  /** Seconds to freeze the last frame before GIF loops. 0-10. Default: 0 */
-  holdLastFrameSec?: number;
-}
+```json
+{ "kind": "WAIT_FOR", "description": "Wait for page to be visually stable", "selector": "[data-ak=\"main-content\"]", "state": "visible", "postcondition": { "type": "screenshot_stable", "threshold": 0.01, "waitMs": 3000 }, "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false }, "timeoutMs": 5000, "maxFailures": 1 }
+```
+
+Place this step **after** DISMISS_OVERLAYS + any content WAIT_FOR, and **immediately before** BEGIN_CLIP.
 
-interface ClipOptions {
-  /** Output format. Default: "gif" */
-  format?: "gif" | "mp4" | "both";
-  /** Max duration in seconds. Default: 8 */
-  maxDurationSec?: number;
-  /** GIF framerate. Default: 15 */
-  gifFps?: number;
-  /** GIF max width in pixels. Default: 800 */
-  gifMaxWidth?: number;
-  /** Show cursor animation. Default: true */
-  showCursor?: boolean;
-  /** Whether to loop GIF. Default: true */
-  loop?: boolean;
+```json
+{
+  "steps": [
+    { "kind": "NAVIGATE", "url": "https://app.example.com", "..." : "..." },
+    { "kind": "DISMISS_OVERLAYS", "..." : "..." },
+    { "kind": "WAIT_FOR", "selector": "[data-ak=\"dashboard\"]", "state": "visible", "..." : "..." },
+    { "kind": "WAIT_FOR", "description": "Let overlays finish animating", "selector": "[data-ak=\"dashboard\"]", "state": "visible", "postcondition": { "type": "screenshot_stable", "threshold": 0.01, "waitMs": 3000 }, "..." : "..." },
+    { "kind": "BEGIN_CLIP", "clipId": "add-project", "clipName": "Add project", "postcondition": { "type": "always" }, "..." : "..." },
+    { "kind": "CLICK", "selector": "[data-ak=\"add-project-btn\"]", "..." : "..." },
+    { "kind": "TYPE", "selector": "[data-ak=\"project-name\"]", "text": "My Project", "clearFirst": true, "..." : "..." },
+    { "kind": "CLICK", "selector": "[data-ak=\"save-btn\"]", "..." : "..." },
+    { "kind": "END_CLIP", "clipId": "add-project", "clipName": "Add project", "postcondition": { "type": "always" }, "..." : "..." }
+  ]
 }
 ```
 
----
+## Interactive Demo Workflow
 
-## Best Practices (Critical)
-
-### Prompt Writing
-The capture agent's success rate depends heavily on prompt quality. Write prompts with **strong navigation hints**:
-
-- **Add location references**: "in the left sidebar", "in the top-right header", "via the navigation bar"
-- **Use visual anchors**: "the blue button labeled 'Save'", "the table with column headers Name/Status/Date"
-- **Specify end-state**: what should be visible when the screenshot is taken
-- **Keep it concise**: 1-3 sentences. The agent handles micro-steps on its own
-
-**Bad prompt**: "Go to settings"
-**Good prompt**: "Navigate to the Settings page via the gear icon in the left sidebar. Show the 'General' tab with all form fields visible."
-
-### Named Pages
-- Each page runs as a **separate, independent agent session** with NO memory between pages
-- Page prompts must be **self-contained** — include all navigation steps from the root URL
-- If page B requires authentication, configure `credentials` in the preset — don't describe login steps in the prompt
-- Use **descriptive page IDs** as slugs: `pricing`, `dashboard-analytics`, `user-settings`
-- NEVER use generic IDs: `main`, `page1`, `page2`, `screen1`
-
-### Isolated Elements
-- Descriptions must reference **visually identifiable** DOM landmarks
-- Good: "The hero section containing the main heading and CTA button"
-- Bad: "The main content area"
-- Always specify `sourcePageId` when the preset has multiple pages
-
-### Theme & Language Instructions
-- Must describe **actual UI controls**, not abstract actions
-- Good: "Click the moon/sun toggle icon in the top-right corner of the header"
-- Bad: "Switch to dark mode"
-- If the app uses URL-based locales (e.g. `/fr/pricing`), mention it explicitly
-
-### Mock Data
-- Descriptions must be **specific enough for deterministic generation**
-- Include: number of items, value ranges, status distributions, data types
-- Good: "10 user accounts with realistic names, emails, roles (3 admin, 5 member, 2 viewer), last active dates within the past 30 days"
-- Bad: "Some users"
-
-### Credentials
-- Only email/password authentication is supported
-- OAuth, SSO, MFA, and magic links are NOT supported
-- When credentials are configured, the agent handles login automatically — do NOT repeat login steps in prompts
-- If a page requires auth but no credentials are configured, the capture will fail
-
-### What the Agent CANNOT Do
-- Upload files or handle file inputs
-- Handle OAuth, SSO, MFA, magic link auth
-- Type into non-auth, non-search fields (no form submissions that create data)
-- Delete or modify persistent data
-- Navigate outside the target domain
-- Remember state between separate page runs
+Interactive demos are advanced and should only be used when the user wants a
+clickable DOM-based experience, not static screenshots or a clip.
 
----
+Key rules:
 
-## Common Targets
+- center the capture around the feature loop, not the whole app
+- use `CAPTURE_DOM` for base states
+- use `CAPTURE_FRAGMENT` for local overlays and subtree swaps
+- add authored markers such as `data-ak-interact`, `data-ak-fragment`,
+  `data-ak-model`, and `data-ak-template`
+- prefer fragments / bindings / model-driven reconstruction before custom
+  interaction `code`
 
-Here are standard target configurations you can use:
+Read the full reference before generating an interactive demo:
 
-```json
-// Desktop (no device frame)
-{ "id": "desktop-1440x900", "label": "Desktop 1440x900", "viewport": { "width": 1440, "height": 900 } }
+- [references/interactive-demo.md](references/interactive-demo.md)
 
-// MacBook Air 13"
-{ "id": "macbook-air-13", "label": "MacBook Air 13\"", "viewport": { "width": 1440, "height": 900 }, "deviceFrame": "macbook-air-13", "mockupOptions": { "outputScale": 2 } }
+## Recovery System Overview
 
-// iPhone 16 Pro (portrait)
-{ "id": "iphone-16-pro", "label": "iPhone 16 Pro", "viewport": { "width": 402, "height": 778 }, "deviceFrame": "iphone-16-pro", "mockupOptions": { "orientation": "portrait", "outputScale": 2 } }
+When an opcode fails, AutoKap tries 5 recovery strategies in order:
 
-// iPad Pro 11" (landscape)
-{ "id": "ipad-pro-11", "label": "iPad Pro 11\" Landscape", "viewport": { "width": 1210, "height": 802 }, "deviceFrame": "ipad-pro-11-m4", "mockupOptions": { "orientation": "landscape", "outputScale": 2 } }
-```
+1. **Deterministic retry** — Same opcode, fresh page observation. Exponential backoff (500ms, 1000ms...).
+2. **Selector memory** — Tries known-good selectors from previous successful runs stored in Supabase.
+3. **Alternative interaction** — Keyboard (Tab+Enter), JS dispatch, coordinate-based click.
+4. **Targeted reload** — Reloads the page and retries. **Loses UI state** (open modals, form data).
+5. **LLM Healer** — AI analyzes the page screenshot and AKTree, then rewrites the failing opcode. Max 3 invocations per run.
 
----
+**Guidance:** Keep `allowReload: false` for most steps (it loses state). Set `allowReload: true` only for the first NAVIGATE or after full page transitions where UI state is expendable.
 
-## Output Format
+## SET_LOCALE / SET_THEME: Method Selection
 
-### Option 1: JSON Output (copy-paste)
+**Investigate the app's i18n/theme mechanism first** by reading configuration files:
 
-Output the preset as a JSON object. The user will paste this into AutoKap's import dialog.
+| Framework | Opcode | Method | Storage | Key |
+|-----------|--------|--------|---------|-----|
+| next-intl | SET_LOCALE | `storage` | `cookie` | `NEXT_LOCALE` |
+| i18next / react-intl | SET_LOCALE | `storage` | `localStorage` | `i18nextLng` |
+| URL-based (e.g. `/fr/page`) | NAVIGATE | — | — | Use locale in URL path |
+| Browser-level only | SET_LOCALE | `browser_context` | — | — |
+| next-themes | SET_THEME | `storage` | `localStorage` | `theme` |
+| CSS `prefers-color-scheme` | SET_THEME | `color_scheme` | — | — |
 
-```json
-{
-  "name": "Preset Name",
-  "description": "What this preset captures",
-  "config": {
-    "prompt": "...",
-    "targets": [...],
-    "langs": ["en"],
-    "themes": ["light"],
-    "maxIterations": 60,
-    "outputScale": 2
-  }
-}
-```
+Place SET_LOCALE/SET_THEME **after NAVIGATE + DISMISS_OVERLAYS** but **before WAIT_FOR or CAPTURE_SCREENSHOT**. The runtime reloads the page after applying storage-based changes.
 
-For multiple presets, output a JSON array:
-```json
-[
-  { "name": "...", "description": "...", "config": { ... } },
-  { "name": "...", "description": "...", "config": { ... } }
-]
-```
+If the preset has only one locale and one theme, these opcodes are unnecessary.
 
-### Option 2: Direct API Creation
+## Mock Data Injection
 
-If an API key and project ID are provided in the prompt, create the preset directly via the AutoKap API:
+Use mock data only when the capture would otherwise look empty or broken.
 
-```bash
-curl -X POST "https://app.autokap.com/api/v1/presets" \
-  -H "Authorization: Bearer YOUR_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "project_id": "YOUR_PROJECT_ID",
-    "name": "Preset Name",
-    "description": "What this preset captures",
-    "config": { ... }
-  }'
-```
+Core rules:
 
-When both an API key and project ID are available, prefer the API method for a seamless experience. Fall back to JSON output if the API call fails.
+- wire both delivery mechanisms whenever possible: clone + hidden trigger/input
+- every variable UI element must become a slot
+- add `data-ak` markers to the template, container, variable children, and
+  hidden receivers
+- declare `mockDataInjection.groups` at the top level of the preset config
+- place `INJECT_MOCK_DATA` after `WAIT_FOR` and before `CAPTURE_SCREENSHOT`
+- keep the opcode non-blocking with `postcondition: { type: "always" }`
 
----
+Read the full reference before adding mock data:
 
-## Examples
+- [references/mock-data.md](references/mock-data.md)
 
-### Example 1: Simple Homepage Screenshot
+## Critical Rules
 
-```json
-{
-  "name": "Homepage Hero",
-  "description": "Above-the-fold hero section of the landing page",
-  "config": {
-    "prompt": "Navigate to the homepage. Wait for the hero section to fully load including any animations and images. The page should show the main heading, subheading, and CTA button.",
-    "targets": [
-      { "id": "desktop-1440x900", "label": "Desktop 1440x900", "viewport": { "width": 1440, "height": 900 } }
-    ],
-    "langs": ["en"],
-    "themes": ["light"],
-    "maxIterations": 60,
-    "outputScale": 2
-  }
-}
-```
+1. **Always start with `NAVIGATE` + `DISMISS_OVERLAYS`**
+2. **Every CLICK/TYPE uses a `data-ak` selector** — add the attribute to the code first
+3. **Never guess selectors** — if the element doesn't have a stable selector, add `data-ak` to it
+4. **CLICK postconditions describe the result**, not the action (what changed, not what was clicked)
+5. **Add `WAIT_FOR` after page transitions** (login, route change, modal open)
+6. **Set `waitMs: 10000`** on postconditions involving async transitions
+7. **Persist the preset via the CLI — the program lives INSIDE `config.program`**, not in a separate file. After generating the program JSON, write the full config to a temp file and run `autokap preset create` or `autokap preset update` so the saved preset contains `program: { ...the full ExecutionProgram... }` plus any `interactiveDemo` / `mockDataInjection` blocks. The user MUST be able to run `autokap run <preset-id>` afterwards with no `--program` flag and no extra files. **Never tell the user to save the JSON to a local file**, never suggest `--program <file>` as the normal run path. The CLI fetches the program from the server.
+8. **Use `captureId`/`clipId`** on CAPTURE_SCREENSHOT/BEGIN_CLIP for Studio and dev links to work. Always set `"devLinksEnabled": true` in the preset config when creating via API so endpoints are visible on the dashboard
+9. **Mock data opcodes are non-blocking** — they log a warning and continue if selectors miss; always pair them with `recovery: { retries: 0, ... }` and `postcondition: { type: "always" }`
+10. **Hardcode the login URL — never use `{{loginUrl}}`.** The login URL is just another navigation. You generate the entire program, so you know which path the app's login lives at — write it directly (`https://app.example.com/login`, `http://localhost:3000/login`, etc.). The `{{loginUrl}}` placeholder is **deprecated** and produces broken navigations when the user hasn't filled the optional `loginUrl` credential field. `{{email}}` and `{{password}}` placeholders for `TYPE` opcodes are still correct and required (those are sensitive secrets the user fills in).
+11. **Capturing an auth-protected route requires a login flow at the START of the program.** Do NOT assume the user is "already logged in". Before any opcode that hits a route behind authentication, emit the canonical login sequence (see "Login flow" below). Skipping this is the #1 cause of "preset runs but never reaches the dashboard" failures.
 
-### Example 2: Multi-Page Preset with Themes
+## Login flow
+
+If **any** of the captures or DOM states in the program lives on an auth-protected route, the program MUST start with this canonical login sequence — placed BEFORE the first capture/state-bearing NAVIGATE.
 
 ```json
-{
-  "name": "Marketing Pages",
-  "description": "Key marketing pages in light and dark mode",
-  "config": {
-    "targets": [
-      { "id": "desktop-1440x900", "label": "Desktop 1440x900", "viewport": { "width": 1440, "height": 900 } }
-    ],
-    "langs": ["en"],
-    "themes": ["light", "dark"],
-    "themeInstructions": "Click the sun/moon toggle icon in the top-right corner of the header navigation bar to switch between light and dark mode.",
-    "maxIterations": 60,
-    "outputScale": 2,
-    "prompt": "",
-    "pages": [
-      {
-        "id": "homepage",
-        "name": "Homepage",
-        "prompt": "Navigate to the homepage at /. Wait for the hero section to load completely with all images. The page should display the main value proposition heading and the 'Get Started' CTA button."
-      },
-      {
-        "id": "pricing",
-        "name": "Pricing Page",
-        "prompt": "Navigate to /pricing. Wait for the pricing cards to load. The page should show all plan tiers (Free, Pro, Enterprise) with their prices and feature lists visible. Select the 'Annual' billing toggle if available."
-      },
-      {
-        "id": "features",
-        "name": "Features Page",
-        "prompt": "Navigate to /features. Wait for the feature grid to fully render. The page should show the feature cards with icons and descriptions."
-      }
-    ]
-  }
-}
+{ "kind": "NAVIGATE", "description": "Open login page", "url": "https://app.example.com/login", "postcondition": { "type": "route_matches", "pattern": "/login" }, "recovery": { "retries": 2, "useSelectorMemory": true, "useAltInteraction": true, "allowReload": true, "allowHealer": true }, "timeoutMs": 20000, "maxFailures": 3 },
+{ "kind": "DISMISS_OVERLAYS", "description": "Dismiss any overlays on login", "postcondition": { "type": "overlay_dismissed" }, "recovery": { "retries": 2, "useSelectorMemory": true, "useAltInteraction": true, "allowReload": false, "allowHealer": true }, "timeoutMs": 5000, "maxFailures": 3 },
+{ "kind": "WAIT_FOR", "description": "Wait for the login email input", "selector": "[data-ak=\"login-email\"]", "state": "visible", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"login-email\"]", "waitMs": 5000 }, "recovery": { "retries": 2, "useSelectorMemory": true, "useAltInteraction": true, "allowReload": false, "allowHealer": true }, "timeoutMs": 10000, "maxFailures": 3 },
+{ "kind": "TYPE", "description": "Enter login email", "selector": "[data-ak=\"login-email\"]", "text": "{{email}}", "clearFirst": true, "postcondition": { "type": "any_change" }, "recovery": { "retries": 2, "useSelectorMemory": true, "useAltInteraction": true, "allowReload": false, "allowHealer": true }, "timeoutMs": 10000, "maxFailures": 3 },
+{ "kind": "TYPE", "description": "Enter login password", "selector": "[data-ak=\"login-password\"]", "text": "{{password}}", "clearFirst": true, "postcondition": { "type": "any_change" }, "recovery": { "retries": 2, "useSelectorMemory": true, "useAltInteraction": true, "allowReload": false, "allowHealer": true }, "timeoutMs": 10000, "maxFailures": 3 },
+{ "kind": "CLICK", "description": "Submit the login form", "selector": "[data-ak=\"login-submit\"]", "postcondition": { "type": "route_matches", "pattern": "/dashboard**", "waitMs": 10000 }, "recovery": { "retries": 2, "useSelectorMemory": true, "useAltInteraction": true, "allowReload": false, "allowHealer": true }, "timeoutMs": 15000, "maxFailures": 3 }
 ```
 
-### Example 3: Clip (Animated GIF) Preset
+### Decision rule: do I need a login flow?
 
-```json
+Walk through the routes you're about to capture:
+
+| Route shape | Login flow needed? |
+|---|---|
+| `/`, `/pricing`, `/blog/*`, `/docs/*` (marketing / public) | **No** |
+| `/dashboard`, `/projects/*`, `/settings`, `/admin/*` (anything behind a guard) | **Yes** |
+| `/login`, `/signup`, `/forgot-password` (the auth pages themselves) | **No** (you're already there) |
+| Mixed (some public, some private) | **Yes** if at least one is private — emit the login sequence first, then NAVIGATE to each route |
+
+When in doubt: **inspect the route's component file** for auth checks (`useSession`, `redirect()`, middleware, layout-level auth wrapper, server-side `getServerSession`, etc.). If you find any, emit the login flow.
+
+### Anti-patterns
+
+| Don't | Why |
+|---|---|
+| `{ "kind": "NAVIGATE", "url": "{{loginUrl}}" }` | Deprecated placeholder. The user often leaves `loginUrl` empty (it's optional), and the substitution produces an empty string that crashes Playwright. Hardcode the URL. |
+| Skip the login flow because "the user runs locally and is already logged in" | Playwright launches a fresh browser context with no cookies. Sessions never carry over. |
+| Capture a private route with no preceding login sequence | You'll capture the login screen (or a 401 page) instead of the actual dashboard. |
+| Place login steps in the middle of the program after a public capture | The first NAVIGATE to a private route fails with a 401/redirect before login runs. Login goes FIRST. |
+| Use `{{loginUrl}}` in any example or doc you write into chat | Reinforces the broken pattern. Always hardcode. |
+
+## How to persist the preset
+
+The user expects a **one-shot flow**: copy prompt → paste → assistant does the work → user runs `autokap run <preset-id>`. **Never break this flow.**
+
+Use the AutoKap CLI commands to create, update, and query presets. The CLI reads the stored CLI key from `~/.autokap/config.json` automatically — **do NOT read the key yourself or build raw HTTP requests as the normal path**.
+
+### Step 1: Write the config JSON to a temp file
+
+Build the full config object (with `program`, `pages`, and optionally `interactiveDemo`/`mockDataInjection`) and write it to a temporary file:
+
+```bash
+cat > /tmp/autokap-preset.json << 'EOF'
 {
-  "name": "Dashboard Demo Clip",
-  "description": "Short animated GIF showing the dashboard interaction",
-  "config": {
-    "captureMode": "clip",
-    "targets": [
-      { "id": "desktop-1440x900", "label": "Desktop 1440x900", "viewport": { "width": 1440, "height": 900 } }
-    ],
-    "langs": ["en"],
-    "themes": ["light"],
-    "maxIterations": 60,
-    "outputScale": 2,
-    "prompt": "",
-    "clips": [
-      {
-        "id": "dashboard-filter",
-        "name": "Dashboard Filter Demo",
-        "navigationScript": "Navigate to /dashboard. Wait for the analytics charts to fully load and display data.",
-        "script": "Click the 'Date Range' dropdown in the top-right of the dashboard. Select 'Last 30 days'. Wait for the charts to update with the new data range.",
-        "holdLastFrameSec": 2
-      }
-    ],
-    "clipOptions": {
-      "format": "gif",
-      "maxDurationSec": 8,
-      "gifMaxWidth": 800,
-      "showCursor": true,
-      "loop": true
-    }
+  "captureMode": "screenshot",
+  "devLinksEnabled": true,
+  "pages": [
+    { "id": "dashboard", "name": "Dashboard" },
+    { "id": "settings", "name": "Settings" }
+  ],
+  "program": {
+    "presetId": "my-preset",
+    "programVersion": 1,
+    "mediaMode": "screenshot",
+    "baseUrl": "https://app.example.com",
+    "variants": [ { "id": "desktop-en-light", "viewport": { "width": 1440, "height": 900 }, "locale": "en", "theme": "light", "targetId": "desktop", "targetLabel": "Desktop" } ],
+    "preconditions": {},
+    "steps": [ { "kind": "NAVIGATE", "..." : "..." } ],
+    "artifactPlan": { "mediaMode": "screenshot" },
+    "compileFingerprint": "v1-my-preset",
+    "compiledAt": "2026-04-11T00:00:00.000Z",
+    "compiledWith": "ai-assistant"
   }
 }
+EOF
 ```
 
----
+#### Config requirements
 
-## Integration Endpoints API
+- **`pages`** — one entry per `CAPTURE_SCREENSHOT` opcode (`{ "id": "<captureId>", "name": "<captureName>" }`). Drives endpoint (dev link) creation. **Screenshot presets only.**
+- **`clips`** — one entry per `BEGIN_CLIP`/`END_CLIP` pair (`{ "id": "<clipId>", "name": "<clipName>" }`). Drives endpoint and Studio slot creation. **Clip presets only.** Do NOT put clip entries in `pages` — the server treats `pages` as screenshots.
+- **`program`** — the full `ExecutionProgram` with `steps`, `variants`, `artifactPlan`, etc.
+- **`captureMode`** — `"screenshot"`, `"clip"`, or `"interactive_demo"`.
+- **`devLinksEnabled: true`** — enables endpoints on the dashboard.
 
-After creating presets and running captures, you can create **integration endpoints** — stable public URLs that serve your assets. Each endpoint maps to a specific capture (page, element, or clip) and supports dynamic variant selection via query parameters (`lang`, `theme`, `target`).
+The server auto-syncs `langs`, `themes`, `targets`, and `viewports` from `program.variants` — you do NOT need to set these manually.
 
-### Create all endpoints for a preset
+### Step 2: Create the preset
 
 ```bash
-curl -X POST https://autokap.com/api/v1/endpoints \
-  -H "Authorization: Bearer $API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{ "preset_id": "PRESET_ID" }'
+npx autokap@latest preset create \
+  --project <project-id> \
+  --name "My preset" \
+  --config /tmp/autokap-preset.json
 ```
 
-This creates an endpoint for every page, isolated element, and clip defined in the preset. Existing endpoints are skipped (no duplicates).
+The command outputs **only the preset ID** to stdout. Capture it for the next steps:
 
-Response:
-```json
-{
-  "created": [{ "id": "abc123...", "label": "Homepage", "preset_id": "...", "asset_type": "screenshot" }],
-  "skipped": 0
-}
+```bash
+PRESET_ID=$(npx autokap@latest preset create --project <project-id> --name "My preset" --config /tmp/autokap-preset.json)
 ```
 
-### Create endpoints for a composition
+### Step 3: Run the preset
 
 ```bash
-curl -X POST https://autokap.com/api/v1/endpoints \
-  -H "Authorization: Bearer $API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{ "composition_id": "COMPOSITION_ID" }'
+npx autokap@latest run $PRESET_ID
 ```
 
-### List endpoints
+### Step 4: Fetch dev link endpoints
 
 ```bash
-# By preset
-curl "https://autokap.com/api/v1/endpoints?preset_id=PRESET_ID" \
-  -H "Authorization: Bearer $API_KEY"
+npx autokap@latest endpoints list --preset $PRESET_ID
+```
 
-# By project
-curl "https://autokap.com/api/v1/endpoints?project_id=PROJECT_ID" \
-  -H "Authorization: Bearer $API_KEY"
+Outputs JSON with endpoint IDs and public asset URLs:
+```json
+[
+  { "id": "abc123...", "capture_name": "dashboard", "label": "Dashboard", "url": "https://app.example.com/api/v1/assets/abc123..." }
+]
 ```
 
-### Update endpoint label
+### Step 5: Integrate dev links into the codebase
+
+After the run succeeds, wire the endpoints into the user's code. **This is part of the one-shot flow** — do not stop at validation.
+
+First, get the structured integration info:
 
 ```bash
-curl -X PATCH https://autokap.com/api/v1/endpoints/ENDPOINT_ID \
-  -H "Authorization: Bearer $API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{ "label": "New Label" }'
+npx autokap@latest preset info $PRESET_ID
 ```
 
-### Delete an endpoint
+This returns JSON with all endpoints, their URLs, asset types, available variants (langs, themes, targets with device slugs), and per-type URL parameters.
+
+Then, use the output to embed the links in the appropriate places in the codebase:
+
+- **Screenshots** → `<img src="{url}?lang=en&theme=light&format=webp" alt="..." loading="lazy" />`
+- **Clips** → `<img src="{url}" alt="..." loading="lazy" />` (GIF, default) or `<video src="{url}?format=mp4" autoplay loop muted playsinline />`
+- **Interactive demos** → `<iframe src="{embed_url}" style="width: 100%; border: none; aspect-ratio: 16/9;" allow="clipboard-write" loading="lazy"></iframe>`
+- **Compositions** → `<img src="{url}?format=webp" alt="..." loading="lazy" />`
+
+Where to embed depends on what the user asked for (README, landing page, docs, component props, etc.). **Ask the user if the target location is ambiguous.**
+
+Append variant query params (`lang`, `theme`, `target`) based on context — for example, match the page locale, or use the user's preferred theme. If uncertain, use the first variant from the `preset info` output as default.
+
+### Updating an existing preset
 
 ```bash
-curl -X DELETE https://autokap.com/api/v1/endpoints/ENDPOINT_ID \
-  -H "Authorization: Bearer $API_KEY"
+npx autokap@latest preset update <preset-id> --config /tmp/autokap-preset.json
 ```
 
-### Export endpoints
+Optional `--name` and `--description` flags to update metadata.
 
-```bash
-# JSON export
-curl "https://autokap.com/api/v1/endpoints/export?preset_id=PRESET_ID" \
-  -H "Authorization: Bearer $API_KEY"
+### Deleting a preset
 
-# CSV export
-curl "https://autokap.com/api/v1/endpoints/export?preset_id=PRESET_ID&format=csv" \
-  -H "Authorization: Bearer $API_KEY"
+```bash
+npx autokap@latest preset delete <preset-id>
 ```
 
-### Serve an asset
+### Anti-patterns (NEVER do these)
 
-Assets are served publicly without authentication:
+| Don't | Why |
+|---|---|
+| Read `~/.autokap/config.json` and make raw `fetch`/`curl` calls | The CLI handles auth automatically. Raw HTTP calls are fragile and expose the key. |
+| Tell the user to save the program to a local JSON and pass `--program` | Defeats the one-shot flow. The user expected the AI to handle persistence. |
+| Create the preset without `config.program` | The CLI then has nothing to run; the dashboard shows "No capture program". |
+| Create the preset without `config.pages` (for screenshot presets) | No dev link endpoints will be created. |
+| Put clip entries in `config.pages` instead of `config.clips` | The server treats `pages` as screenshots. Clips won't appear in Studio or get endpoints. |
+| Create a clip preset without `config.clips` | No clip endpoints or Studio slots will be created. |
+| Output the program as a code block "for the user to copy" | Forces a manual step. Use the CLI instead. |
 
+### Fallback (when the CLI is genuinely unavailable)
+
+If the CLI command fails, output the full config JSON as a code block and tell the user to import it via the dashboard. Make it clear this is a recovery path, not the normal one.
+
+## Running
+
+```bash
+# Run a preset (the program lives in preset.config.program — no --program flag):
+autokap run <preset-id>
+
+# Watch the browser execute:
+autokap run <preset-id> --headed
+
+# Save the artifacts to a local directory in addition to uploading them:
+autokap run <preset-id> --output ./screenshots
 ```
-https://autokap.com/api/v1/assets/ENDPOINT_ID?lang=en&theme=dark&target=desktop
-```
 
-Query parameters: `lang`, `theme`, `target`, `w` (width), `quality`, `format` (png/webp).
+## Complete Examples
+
+Use the examples reference for ready-made shapes of:
+
+- anonymous screenshot presets
+- authenticated screenshot presets
+- clip presets
+- interactive demo presets
+- mock-data-enabled presets
 
-### Required API scopes
+Read:
 
-- `endpoints:read` — list, get, and export endpoints
-- `endpoints:write` — create, update, and delete endpoints
+- [references/examples.md](references/examples.md)