autokap 1.6.2 → 1.6.4

package/assets/skill/SKILL.md

@@ -1,590 +0,0 @@
----
-name: autokap-preset
-description: >
-  Generate AutoKap capture programs — deterministic opcode sequences for automated
-  screenshot and clip 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: 2.3.0
----
-
-# AutoKap Preset Creation Skill
-
-## Mental Model
-
-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.
-
-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.
-
-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.).
-
-> **Compatibility note.** The dashboard prompts now embed a mini AutoKap mental-model so they remain useful for assistants that don't have this skill installed (Cursor without the bundle, Codex, Copilot, plain Claude Code). When this skill IS installed, **the rules below override anything that contradicts them in the inline mental-model** — the inline version is necessarily a summary.
-
-## When To Use This Skill
-
-- User wants to capture screenshots or clips 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
-
-## Before Generating Anything
-
-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.
-
-## Quick Workflow
-
-1. **Understand the capture goal** — What pages/states should be captured? Screenshot or clip? 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.
-
-## Bundled References
-
-Load these only when the request actually needs them:
-
-- **Opcode parameters** — [OPCODE-REFERENCE.md](OPCODE-REFERENCE.md)
-- **Mock data** — [references/mock-data.md](references/mock-data.md)
-- **Complete examples** — [references/examples.md](references/examples.md)
-- **Prompt charter** — [references/STANDARDS.md](references/STANDARDS.md) — defines the structure every dashboard-generated prompt now follows. Use it when authoring new prompts, when extending existing builders, or to understand why a copied prompt is shaped the way it is.
-
-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.
-
-## Adding `data-ak` Attributes
-
-For every element you interact with in the opcodes, add a `data-ak="descriptive-name"` attribute:
-
-```jsx
-// Before
-<button onClick={handleLogin}>Sign in</button>
-<input type="email" placeholder="Email" />
-
-// After
-<button data-ak="login-btn" onClick={handleLogin}>Sign in</button>
-<input data-ak="login-email" type="email" placeholder="Email" />
-```
-
-**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
-
-## ExecutionProgram Schema
-
-```typescript
-interface ExecutionProgram {
-  presetId: string;         // Unique slug (e.g. "homepage-hero")
-  programVersion: number;   // Always 1 for new programs
-  mediaMode: 'screenshot' | 'clip' | 'video';
-  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' | 'video';
-    cursorTheme?: 'minimal' | 'macos' | 'windows'; // Clip/video recordings. Default: 'minimal'
-    format?: {
-      clipFormat?: 'gif' | 'mp4' | 'both';      // Default: 'gif'
-      screenshotFormat?: 'png' | 'jpeg';          // Default: 'png'
-      // Video-only — required when mediaMode='video'.
-      // captureResolution must be 1920×1080; legacy 2560×1440 is normalized by AutoKap.
-      // captureFps defaults to 30; deliveryResolution defaults to 1920×1080.
-      captureResolution?: { width: number; height: number };
-      captureFps?: number;
-      deliveryResolution?: { width: number; height: number };
-    };
-    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 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
-}
-```
-
-## 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` | specific result / `any_change` | `"Enter"`, `"Escape"`, `"Tab"`, etc.; use `any_change` only when the key must visibly change state |
-| `WAIT_FOR` | yes* | `state` | `element_visible` | `"visible"` or `"attached"` (DOM only) |
-| `SLEEP` | no | `durationMs` (1..60000), `narrationTextByLocale?` | `always` | Pause N ms. Reserved for video narration anchors. Use `durationMs: 1` as a placeholder; AutoKap rewrites it during `autokap run` after generating TTS. |
-| `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 |
-| `DRAG` | yes | `toSelector?` / `toTarget?` / `offset?` | `element_visible` / `any_change` | Animated cursor A→B. Use `toSelector` for Kanban-style drops, `offset` for sliders / canvas |
-| `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` | `always` / matching `route_matches` | `urlPattern` is the source of truth |
-| `ASSERT_SURFACE` | no | `selectors[]`, `matchAll` | `always` / matching `element_visible` | `selectors` + `matchAll` are the source of truth |
-| `CAPTURE_SCREENSHOT` | no | `captureId`, `captureName`, `elementSelector?`, `outscale?` | `always` | `elementSelector` for element-level crop. `outscale` adds padding around the element (user-edited post-generation; omit by default) |
-| `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` | — | Verifier-backed state change after TYPE, CLICK, SELECT_OPTION, DOUBLE_CLICK, DRAG, etc.; no-op actions fail |
-| `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 inside a clip (between BEGIN_CLIP and END_CLIP) | Always CLICK the in-app element (sidebar Link, modal trigger button) or PRESS_KEY Escape to close modals. NAVIGATE is `page.goto` = full reload + white flash + cursor lost. See "Designing human-like clip programs" below for the patterns |
-| 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>` (sidebar, breadcrumb, card) to change route | NAVIGATE to the new URL mid-clip | NAVIGATE always calls Playwright's `page.goto` — a full HTTP navigation that destroys the document, wipes the cursor overlay, and shows a white flash. Even SPAs are forced into a hard reload. CLICK lets Next.js / React Router intercept and use prefetched `router.push` instead — no flash, cursor preserved |
-| **CLICK** on the modal's trigger button (e.g. `[data-ak-interact="new-preset-btn"]`) to open a modal | NAVIGATE to the modal's deep-link route | Most modals open via local React state, not URL navigation. The deep-link route exists for direct entry but forces a real reload — using the trigger button keeps the recording in one fluid take |
-| **PRESS_KEY** `"Escape"` to close a modal (or CLICK its close button) | NAVIGATE back to the previous URL | Radix/shadcn dialogs (the AutoKap dashboard convention) close on Escape and run their `onClose` handler — which usually does the SPA route change internally. NAVIGATE back triggers another full reload |
-| **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 — NEVER `NAVIGATE` inside a clip.** NAVIGATE = `page.goto()` = full document reload, white flash, cursor overlay destroyed. There is no exception, even when the destination is on the same origin or the framework supports SPA routing — Playwright doesn't use the framework router. Reach every destination through the actual UI element a real user would interact with:
-
-- **Page change** → `CLICK` on a `<Link>` (sidebar item, breadcrumb, card). If no Link points where you need to go, ask the user where the user-facing entry point is — don't invent a NAVIGATE workaround.
-- **Open a modal** → `CLICK` on its trigger button (annotate it with `data-ak-interact="..."`). Even if the modal also has a deep-link URL, the trigger is the smooth path.
-- **Close a modal** → `PRESS_KEY "Escape"` (or CLICK the close button if present). The modal's `onClose` handler does any required SPA route change for you.
-- **Reveal off-screen content** → `SCROLL` is still fine when there's no clickable anchor (long content sections, lists inside a container).
-
-If you find yourself wanting to write `NAVIGATE` between `BEGIN_CLIP` and `END_CLIP`, stop and reconsider — there is almost always an annotated UI element to CLICK instead. Add a `data-ak-interact` to the source if it's missing.
-
-## Demo Video Workflow
-
-For narrated demo videos (`mediaMode: "video"`), AutoKap captures a language/theme matrix:
-
-1. Use **one desktop target** at 1920x1080. Do not multiply demo videos by device.
-2. Generate one variant for every app locale x theme pair. Variant ids must be stable, for example `desktop-1920x1080-fr-dark`.
-3. Add `SET_LOCALE` and `SET_THEME` with `"$variant"` during setup when the app supports locale/theme switching.
-4. Put all recorded content inside `BEGIN_CLIP` / `END_CLIP`.
-5. Every narrated pause is a `SLEEP` with `stepId`, `durationMs: 1`, and `narrationTextByLocale`.
-
-Voice-over settings are row-based: each app locale maps to a spoken TTS locale and a voice in `narration_by_app_locale`. `narrationTextByLocale` is the source of truth for TTS text. It must include one entry for every spoken TTS locale used by those rows. AutoKap currently supports TTS for `en` and `fr`; unsupported TTS locales are rejected explicitly. Keep `narrationText` only as a legacy fallback for single-row demos.
-
-```json
-{
-  "kind": "SLEEP",
-  "stepId": "opening-hello",
-  "durationMs": 1,
-  "narrationTextByLocale": {
-    "en": "Hey, welcome — I'll show you the dashboard quickly.",
-    "fr": "Salut, bienvenue — je te montre rapidement le dashboard."
-  },
-  "description": "Narration anchor: opening greeting",
-  "postcondition": { "type": "always" },
-  "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false },
-  "timeoutMs": 65000,
-  "maxFailures": 1
-}
-```
-
-The server synthesizes TTS once per app-locale voice row, not once per theme. It rewrites every narrated `SLEEP.durationMs` to the maximum audio duration for that `stepId` across rows so the same runtime program can capture every variant.
-
-### 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:
-
-```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.
-
-```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" }, "..." : "..." }
-  ]
-}
-```
-
-## Recovery System Overview
-
-When an opcode fails, AutoKap tries 5 recovery strategies in order:
-
-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. Never rely on reload recovery inside a `BEGIN_CLIP` / `END_CLIP` recording window.
-
-## SET_LOCALE / SET_THEME: Method Selection
-
-**Investigate the app's i18n/theme mechanism first** by reading configuration files:
-
-| 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` | — | — |
-
-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.
-
-If the preset has only one locale and one theme, these opcodes are unnecessary.
-
-## Mock Data Injection
-
-Use mock data only when the capture would otherwise look empty or broken.
-
-Core rules:
-
-- 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:
-
-- [references/mock-data.md](references/mock-data.md)
-
-## Critical Rules
-
-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 `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.
-
-## 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
-{ "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 }
-```
-
-### Decision rule: do I need a login flow?
-
-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 `mockDataInjection`) and write it to a temporary file:
-
-```bash
-cat > /tmp/autokap-preset.json << 'EOF'
-{
-  "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
-
-- **`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"` or `"clip"`.
-- **`devLinksEnabled: true`** — enables endpoints on the dashboard.
-
-The server auto-syncs `langs`, `themes`, `targets`, and `viewports` from `program.variants` — you do NOT need to set these manually.
-
-### Step 2: Create the preset
-
-```bash
-npx autokap@latest preset create \
-  --project <project-id> \
-  --name "My preset" \
-  --config /tmp/autokap-preset.json
-```
-
-The command outputs **only the preset ID** to stdout. Capture it for the next steps:
-
-```bash
-PRESET_ID=$(npx autokap@latest preset create --project <project-id> --name "My preset" --config /tmp/autokap-preset.json)
-```
-
-### Step 3: Run the preset
-
-```bash
-npx autokap@latest run $PRESET_ID
-```
-
-### Step 4: Fetch dev link endpoints
-
-```bash
-npx autokap@latest endpoints list --preset $PRESET_ID
-```
-
-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..." }
-]
-```
-
-### 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
-npx autokap@latest preset info $PRESET_ID
-```
-
-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
-npx autokap@latest preset update <preset-id> --config /tmp/autokap-preset.json
-```
-
-Optional `--name` and `--description` flags to update metadata.
-
-### Deleting a preset
-
-```bash
-npx autokap@latest preset delete <preset-id>
-```
-
-### Anti-patterns (NEVER do these)
-
-| 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
-
-# Dry run: validate the opcode program end-to-end without capturing or
-# uploading anything (0 credits charged). Use this right after generating
-# or updating a preset to confirm navigation, clicks, and postconditions
-# work before spending credits on a real capture.
-autokap run <preset-id> --dry
-```
-
-## Complete Examples
-
-Use the examples reference for ready-made shapes of:
-
-- anonymous screenshot presets
-- authenticated screenshot presets
-- clip presets
-- mock-data-enabled presets
-
-Read:
-
-- [references/examples.md](references/examples.md)