autokap 1.6.2 → 1.6.4

package/assets/skill/OPCODE-REFERENCE.md

@@ -1,625 +0,0 @@
-# AutoKap Opcode Reference
-
-Detailed parameter documentation for all 24 opcodes. For workflow, rules, and examples, see [SKILL.md](SKILL.md).
-
-## Common Fields (all opcodes)
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `kind` | string | yes | — | Opcode type (see sections below) |
-| `description` | string | yes | — | Human-readable description of this step |
-| `postcondition` | PostconditionSpec | yes | — | Condition that must hold after execution |
-| `recovery` | RecoveryPolicy | yes | — | Recovery behavior on failure |
-| `timeoutMs` | number | yes | 15000 | Max time (ms) including recovery |
-| `maxFailures` | number | yes | 3 | Max recovery attempts before fatal |
-
-### RecoveryPolicy
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `retries` | number (0-10) | 2 | Deterministic retry attempts |
-| `useSelectorMemory` | boolean | true | Try known-good selectors from previous runs |
-| `useAltInteraction` | boolean | true | Try keyboard/JS/coordinate click |
-| `allowReload` | boolean | false | Reload page and retry. **Use sparingly** — loses UI state (open modals, form data). Only safe after full page transitions. |
-| `allowHealer` | boolean | true | Allow LLM to rewrite the failing opcode as last resort |
-
-### SemanticTarget (optional on interaction opcodes)
-
-Fallback when CSS selector fails. The runtime resolves via Playwright semantic locators, then AKTree fuzzy matching.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `text` | string | Visible text content (substring match by default) |
-| `role` | string | ARIA role: `"button"`, `"link"`, `"textbox"`, `"checkbox"`, `"tab"`, `"menuitem"` |
-| `label` | string | `aria-label`, associated `<label>` text, or `title` attribute |
-| `near` | string | Nearby text for disambiguation (e.g. `"in the pricing section"`) |
-| `placeholder` | string | Input placeholder text |
-| `exact` | boolean | If `true`, match text exactly. Default: `false` (substring) |
-
-### PostconditionSpec
-
-| Field | Type | Used by | Description |
-|-------|------|---------|-------------|
-| `type` | string | all | One of the 8 postcondition types (see SKILL.md) |
-| `pattern` | string | `route_matches` | URL glob pattern (`*` = segment, `**` = any path) |
-| `selector` | string | `element_visible`, `element_absent`, `text_contains` | CSS selector to check |
-| `text` | string | `text_contains` | Expected text substring |
-| `threshold` | number (0-1) | `screenshot_stable` | Pixel diff tolerance. Default: `0.01` |
-| `waitMs` | number | all except `always` | Max polling time (ms). Default: `5000` |
-
-`any_change` is verifier-backed: the runtime must observe a URL, DOM, element state, overlay, or scroll change after the action. No-op actions fail.
-
----
-
-## NAVIGATE
-
-Navigate to a URL.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `url` | string | yes | Full URL to navigate to |
-
-**Can:** Load any URL, follow redirects, handle SPA route changes.
-**Cannot:** Open new tabs/windows. Use CLICK with `button: "middle"` for that.
-
-```json
-{ "kind": "NAVIGATE", "url": "https://app.example.com/pricing", "postcondition": { "type": "route_matches", "pattern": "/pricing" } }
-```
-
-## DISMISS_OVERLAYS
-
-Automatically dismisses cookie banners, newsletter popups, chat widgets, and age gates. Multi-pass: adapter dismissal, Escape key, close-button clicks (multilingual patterns).
-
-No additional parameters.
-
-**Can:** Handle common overlays in any language (en, fr, de, es, it patterns).
-**Cannot:** Dismiss overlays that require form input (e.g. age verification with date entry) or CAPTCHAs.
-
-```json
-{ "kind": "DISMISS_OVERLAYS", "postcondition": { "type": "overlay_dismissed" } }
-```
-
-## CLICK
-
-Click an element.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `selector` | string | yes | — | CSS selector (use `data-ak` attributes) |
-| `target` | SemanticTarget | no | — | Fallback for recovery chain |
-| `button` | `"right"` \| `"middle"` | no | left | `"right"` = context menu, `"middle"` = new tab |
-| `fingerprint` | string | no | — | AKTree fingerprint for fuzzy matching |
-| `selectorAlternates` | string[] | no | — | Alternative selectors tried in order |
-
-**Can:** Left/right/middle click, trigger navigation, open modals, toggle dropdowns.
-**Cannot:** Drag-and-drop, long-press, touch gestures.
-
-```json
-{ "kind": "CLICK", "selector": "[data-ak=\"pricing-btn\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"pricing-modal\"]", "waitMs": 5000 } }
-```
-
-## TYPE
-
-Type text into a form field.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `selector` | string | yes | — | CSS selector of the input/textarea |
-| `text` | string | yes | — | Text to type. Use `{{email}}` / `{{password}}` for credentials |
-| `clearFirst` | boolean | yes | true | Clear existing value before typing |
-| `target` | SemanticTarget | no | — | Fallback for recovery chain |
-| `fingerprint` | string | no | — | AKTree fingerprint |
-| `selectorAlternates` | string[] | no | — | Alternative selectors |
-
-**Can:** Type into text inputs, textareas, contenteditable elements. Clear existing values. Use credential placeholders.
-**Cannot:** Type into file inputs (use file upload instead). Paste from clipboard.
-
-```json
-{ "kind": "TYPE", "selector": "[data-ak=\"search-input\"]", "text": "dashboard", "clearFirst": true, "postcondition": { "type": "any_change" } }
-```
-
-## PRESS_KEY
-
-Press a keyboard key.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `key` | string | yes | Key name: `"Enter"`, `"Escape"`, `"Tab"`, `"ArrowDown"`, `"Backspace"`, etc. |
-
-**Can:** Submit forms (Enter), close modals (Escape), navigate focus (Tab), trigger keyboard shortcuts.
-**Cannot:** Key combinations (Ctrl+C, Cmd+V). For shortcuts, use the individual key name that Playwright supports.
-
-```json
-{ "kind": "PRESS_KEY", "key": "Enter", "postcondition": { "type": "any_change" } }
-```
-
-## WAIT_FOR
-
-Wait for an element to appear.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `selector` | string | no* | — | CSS selector to wait for |
-| `target` | SemanticTarget | no* | — | Semantic target to wait for |
-| `state` | `"visible"` \| `"attached"` | yes | — | `"visible"` = rendered and visible. `"attached"` = in DOM but may be hidden |
-
-*At least one of `selector` or `target` is required.
-
-**Can:** Wait for page content to load, modals to appear, dynamic elements to render.
-**Cannot:** Wait for network requests or API responses directly. Use `state: "attached"` for elements that exist in DOM but are initially hidden (e.g. lazy-loaded tabs).
-
-```json
-{ "kind": "WAIT_FOR", "selector": "[data-ak=\"dashboard\"]", "state": "visible", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"dashboard\"]", "waitMs": 10000 } }
-```
-
-## SLEEP
-
-Pause execution for a fixed duration. For demo videos, use SLEEP as an explicit narration anchor with `stepId`, `narrationTextByLocale`, and `durationMs: 1`. `autokap run` generates TTS once per app-locale voice row, measures the audio, and rewrites `durationMs` to the maximum duration for that `stepId` before executing the opcodes, so one runtime program works for every language/theme variant.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `durationMs` | integer (1..60000) | yes | — | How long to sleep, in milliseconds |
-| `narrationTextByLocale` | object `{ [locale]: string }` | video narration | — | Spoken text for every TTS locale used by `narration_by_app_locale`. Current TTS catalogue supports `en` and `fr`. |
-| `narrationText` | string | legacy single-row only | — | Backward-compatible fallback when only one TTS row is requested. Prefer `narrationTextByLocale`. |
-
-**Can:** Hold the runtime for a precise wall-clock duration without DOM polling.
-**Cannot:** React to a selector / postcondition — use `WAIT_FOR` for that.
-
-```json
-{ "kind": "SLEEP", "description": "Hold for narration on 'open-pricing'", "stepId": "open-pricing", "durationMs": 1, "narrationTextByLocale": { "en": "Let's open pricing and look at the plan structure.", "fr": "On ouvre les tarifs et on regarde la structure des offres." }, "postcondition": { "type": "always" }, "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false }, "timeoutMs": 65000, "maxFailures": 1 }
-```
-
-## SCROLL
-
-Scroll the page or scroll an element into view.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `direction` | `"up"` \| `"down"` \| `"left"` \| `"right"` | yes | — | Scroll direction |
-| `amount` | number | no | viewport height | Pixels to scroll |
-| `targetSelector` | string | no | — | CSS selector to scroll into view |
-| `target` | SemanticTarget | no | — | Semantic target to scroll into view |
-
-**Can:** Scroll page in any direction, scroll specific element into view, scroll by pixel amount.
-**Cannot:** Scroll inside a specific scrollable container (always scrolls the page). For nested scrollable areas, use CLICK to focus the container first.
-
-**Tip:** When `targetSelector` is provided, the runtime scrolls the element into view regardless of `direction`/`amount`. Use `direction` + `amount` for blind scrolling, `targetSelector` for precise positioning.
-
-```json
-{ "kind": "SCROLL", "direction": "down", "targetSelector": "[data-ak=\"pricing\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"pricing\"]" } }
-```
-
-## HOVER
-
-Hover over an element.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `selector` | string | yes | CSS selector |
-| `target` | SemanticTarget | no | Fallback for recovery chain |
-| `fingerprint` | string | no | AKTree fingerprint |
-| `selectorAlternates` | string[] | no | Alternative selectors |
-
-**Can:** Trigger tooltips, dropdown menus, CSS `:hover` states, hover cards.
-**Cannot:** Hover state persists only until the next interaction. If you need to capture a hover state, place CAPTURE_SCREENSHOT immediately after HOVER.
-
-```json
-{ "kind": "HOVER", "selector": "[data-ak=\"nav-products\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"products-dropdown\"]", "waitMs": 3000 } }
-```
-
-## SELECT_OPTION
-
-Select an option in a **native `<select>` element**.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `selector` | string | yes | CSS selector of the `<select>` element |
-| `optionLabel` | string | no* | Select by visible label text |
-| `optionValue` | string | no* | Select by `value` attribute |
-| `optionIndex` | number | no* | Select by zero-based index |
-| `target` | SemanticTarget | no | Fallback for recovery chain |
-| `fingerprint` | string | no | AKTree fingerprint |
-| `selectorAlternates` | string[] | no | Alternative selectors |
-
-*Exactly one of `optionLabel`, `optionValue`, or `optionIndex` must be provided. Prefer `optionLabel` for readability.
-
-**Can:** Select from native `<select>` dropdowns.
-**Cannot:** Select from custom dropdowns (Radix Select, Headless UI Listbox, MUI Select, cmdk). For custom dropdowns, use a CLICK + WAIT_FOR + CLICK sequence: click to open, wait for options, click the option.
-
-```json
-{ "kind": "SELECT_OPTION", "selector": "[data-ak=\"country-select\"]", "optionLabel": "France", "postcondition": { "type": "text_contains", "selector": "[data-ak=\"country-select\"]", "text": "France" } }
-```
-
-## CHECK
-
-Set a checkbox or toggle to a specific state.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `selector` | string | yes | CSS selector of the checkbox/toggle |
-| `checked` | boolean | yes | `true` = checked, `false` = unchecked |
-| `target` | SemanticTarget | no | Fallback for recovery chain |
-| `fingerprint` | string | no | AKTree fingerprint |
-| `selectorAlternates` | string[] | no | Alternative selectors |
-
-**Can:** Idempotently set checkbox state. Safer than CLICK because it sets the desired state directly without toggling.
-**Cannot:** Interact with custom toggle components that don't use native checkbox semantics. For those, use CLICK.
-
-```json
-{ "kind": "CHECK", "selector": "[data-ak=\"terms-checkbox\"]", "checked": true, "postcondition": { "type": "always" } }
-```
-
-## DOUBLE_CLICK
-
-Double-click an element.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `selector` | string | yes | CSS selector |
-| `target` | SemanticTarget | no | Fallback for recovery chain |
-| `fingerprint` | string | no | AKTree fingerprint |
-| `selectorAlternates` | string[] | no | Alternative selectors |
-
-**Can:** Trigger inline editing, text selection, and any UI that responds to `dblclick`.
-**Cannot:** Triple-click (select paragraph). Use TYPE with `clearFirst: true` to replace full text content instead.
-
-```json
-{ "kind": "DOUBLE_CLICK", "selector": "[data-ak=\"editable-title\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"title-editor\"]", "waitMs": 3000 } }
-```
-
-## DRAG
-
-Drag the source element from point A to point B with an animated cursor. In clip recordings the cursor overlay glides along a Bezier curve, shows a pressed state during the drag, and emits a drop pulse at the destination.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `selector` | string | yes | CSS selector of the source element (the one being dragged) |
-| `target` | SemanticTarget | no | Semantic fallback for the source |
-| `fingerprint` | string | no | AKTree fingerprint for the source |
-| `selectorAlternates` | string[] | no | Alternative source selectors |
-| `toSelector` | string | no* | CSS selector of the drop target element |
-| `toTarget` | SemanticTarget | no* | Semantic fallback for the drop target |
-| `toSelectorAlternates` | string[] | no | Alternative destination selectors |
-| `offset` | `{ dx: number, dy: number }` | no* | Pixel offset from the source center (use for sliders, canvas drawing, or any drop that isn't a DOM node) |
-
-*Provide EITHER `toSelector` / `toTarget` (element drag) OR `offset` (relative drag). Not both.
-
-**Can:** Element-to-element drag (Kanban columns, sortable lists), slider adjustments, canvas drawing, any interaction driven by mousedown + mousemove + mouseup. Works with native HTML5 drag, dnd-kit, react-dnd, Radix DnD primitives — `page.mouse.*` fires both mouse and pointer events.
-**Cannot:** Multi-touch gestures, drag between different browser windows, file drops (use a file input instead).
-
-```json
-{ "kind": "DRAG", "selector": "[data-ak=\"task-card-todo-1\"]", "toSelector": "[data-ak=\"column-in-progress\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"column-in-progress\"] [data-ak=\"task-card-todo-1\"]", "waitMs": 3000 } }
-```
-
-```json
-{ "kind": "DRAG", "selector": "[data-ak=\"volume-slider-thumb\"]", "offset": { "dx": 120, "dy": 0 }, "postcondition": { "type": "any_change" } }
-```
-
-## SET_LOCALE
-
-Set the application's locale/language for the current variant.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `locale` | string | yes | BCP-47 locale (e.g. `"fr"`, `"en-US"`). Use `"$variant"` for runtime substitution |
-| `method` | `"browser_context"` \| `"ui_interaction"` \| `"storage"` | yes | How to apply the locale |
-| `selector` | string | no | Element to click (for `ui_interaction` only) |
-| `storageHints` | StorageHint[] | no | Storage writes (for `storage` only) |
-
-**StorageHint:** `{ "storage": "localStorage" | "sessionStorage" | "cookie", "key": string, "value": string }`
-
-**Can:** Switch locale via storage writes (instant, reliable), browser context, or UI click.
-**Cannot:** Handle URL-based routing (e.g. `/fr/page`). For URL-based i18n, use NAVIGATE with the locale path.
-
-**Method decision tree:**
-- **next-intl** -> `method: "storage"`, `storage: "cookie"`, key: `"NEXT_LOCALE"`
-- **i18next / react-intl** -> `method: "storage"`, `storage: "localStorage"`, key: `"i18nextLng"`
-- **URL-based** (e.g. `/fr/page`) -> Use NAVIGATE instead
-- **Browser-level only** -> `method: "browser_context"`
-
-```json
-{ "kind": "SET_LOCALE", "locale": "$variant", "method": "storage", "storageHints": [{ "storage": "cookie", "key": "NEXT_LOCALE", "value": "$variant" }], "postcondition": { "type": "always" } }
-```
-
-## SET_THEME
-
-Set the application's color theme for the current variant.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `theme` | `"light"` \| `"dark"` \| `"$variant"` | yes | Target theme. Use `"$variant"` for runtime substitution |
-| `method` | `"color_scheme"` \| `"ui_interaction"` \| `"storage"` | yes | How to apply the theme |
-| `selector` | string | no | Element to click (for `ui_interaction` only) |
-| `storageHints` | StorageHint[] | no | Storage writes (for `storage` only) |
-
-**Can:** Switch theme via storage writes (instant, reliable), CSS `prefers-color-scheme`, or UI click.
-**Cannot:** Handle complex theme systems with more than light/dark (e.g. "system", "sepia"). For those, use `method: "storage"` with the exact value the app expects.
-
-**Method decision tree:**
-- **next-themes** -> `method: "storage"`, `storage: "localStorage"`, key: `"theme"`
-- **CSS only** (reads `prefers-color-scheme`) -> `method: "color_scheme"`
-- **Custom storage** -> `method: "storage"` with app-specific key
-
-```json
-{ "kind": "SET_THEME", "theme": "$variant", "method": "storage", "storageHints": [{ "storage": "localStorage", "key": "theme", "value": "$variant" }], "postcondition": { "type": "always" } }
-```
-
-## ASSERT_ROUTE
-
-Assert the current URL matches a pattern. Pure validation, no navigation.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `urlPattern` | string | yes | URL glob pattern (`*` = segment, `**` = any path) |
-
-**Can:** Validate the browser is on the expected page. Useful as a checkpoint before capture.
-**Cannot:** Navigate or change the URL. Use NAVIGATE for that.
-
-`urlPattern` is the assertion source of truth. Use `postcondition: { "type": "always" }` or repeat the same `route_matches` pattern.
-
-```json
-{ "kind": "ASSERT_ROUTE", "urlPattern": "/dashboard/**", "postcondition": { "type": "route_matches", "pattern": "/dashboard/**" } }
-```
-
-## ASSERT_SURFACE
-
-Assert that specific elements are visible on the page. Pure validation.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `selectors` | string[] | yes | — | CSS selectors that must be visible |
-| `matchAll` | boolean | yes | true | `true` = ALL must match, `false` = ANY one suffices |
-
-**Can:** Validate page state before capture. Confirm multiple elements are rendered.
-**Cannot:** Interact with elements or wait for them. Use WAIT_FOR for dynamic elements.
-
-`selectors` and `matchAll` are the assertion source of truth. Use `postcondition: { "type": "always" }` or an `element_visible` postcondition for one of the asserted selectors.
-
-```json
-{ "kind": "ASSERT_SURFACE", "selectors": ["[data-ak=\"header\"]", "[data-ak=\"sidebar\"]"], "matchAll": true, "postcondition": { "type": "always" } }
-```
-
-## CAPTURE_SCREENSHOT
-
-Capture a screenshot of the viewport or a specific element.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `captureId` | string | no | Stable identifier for Studio/dev links. Should match preset page/element id |
-| `captureName` | string | no | Human-readable label shown in Studio |
-| `elementSelector` | string | no | CSS selector for element-level capture (crops to element bounds) |
-| `outscale` | OutscaleConfig | no | Padding around the captured element (only applied with `elementSelector`). Typically set by the user post-generation. Omit by default. |
-
-**Can:** Full-page viewport capture, element-level capture (cropped), LLM verification (detects blank/error/loading/overlay states), alt text generation, favicon extraction.
-**Cannot:** Capture content below the fold in a single shot (use SCROLL first). Capture cross-origin iframe content.
-
-**Tip:** Without `elementSelector`, captures the full viewport. With `elementSelector`, captures only that element's bounding box — useful for component-level screenshots.
-
-**`outscale` shape:** all fields optional. `padding` is uniform (pixels). `paddingTop/Right/Bottom/Left` override per side. `paddingPercent` (0–100) scales with the element. `clampToViewport` (default `true`) prevents the crop from exceeding the document. `backgroundColor` fills any uncovered area.
-
-```json
-{ "kind": "CAPTURE_SCREENSHOT", "captureId": "dashboard-main", "captureName": "Dashboard", "elementSelector": "[data-ak=\"main-content\"]", "postcondition": { "type": "always" } }
-```
-
-```json
-{ "kind": "CAPTURE_SCREENSHOT", "captureName": "Pricing card", "elementSelector": "[data-ak=\"pricing\"]", "outscale": { "padding": 24 }, "postcondition": { "type": "always" } }
-```
-
-## BEGIN_CLIP
-
-Start recording a clip. All interactions between BEGIN_CLIP and END_CLIP are recorded.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `clipId` | string | no | Stable identifier for Studio/dev links. Should match preset clip id |
-| `clipName` | string | no | Human-readable label shown in Studio |
-
-**Can:** Record viewport interactions as a clip.
-**Cannot:** Record element-level clips (always full viewport). Record audio.
-
-```json
-{ "kind": "BEGIN_CLIP", "clipId": "open-modal-flow", "clipName": "Open modal", "postcondition": { "type": "always" } }
-```
-
-## END_CLIP
-
-Stop recording the clip. Must pair with a prior BEGIN_CLIP.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `clipId` | string | no | Must match the BEGIN_CLIP's `clipId` |
-| `clipName` | string | no | Must match the BEGIN_CLIP's `clipName` |
-
-**Can:** Finalize recording and produce GIF/MP4 artifact.
-**Cannot:** Trim or edit the recording. The full BEGIN_CLIP to END_CLIP duration is captured.
-
-```json
-{ "kind": "END_CLIP", "clipId": "open-modal-flow", "clipName": "Open modal", "postcondition": { "type": "always" } }
-```
-
-## CLONE_ELEMENT
-
-Duplicate a template element N times into a container. **Non-blocking** — if a selector misses, the opcode is skipped and the run continues.
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `sourceSelector` | string | yes | — | CSS selector of the element to clone |
-| `containerSelector` | string | yes | — | CSS selector of the container that receives the clones |
-| `count` | number (1-500) | yes | — | Number of clones to produce |
-| `removeSource` | boolean | no | false | If true, remove the template after cloning (template must be a child of the container) |
-
-**Can:** Duplicate any DOM node including its descendants and attributes. Optionally remove the source after cloning.
-**Cannot:** Clone content from cross-origin iframes. Clone the shadow tree of Web Components (only the host is cloned).
-
-**Soft-failure semantics:** Throws if `sourceSelector` or `containerSelector` is missing. The runner converts the throw into `status: "skipped"` and the variant continues.
-
-```json
-{ "kind": "CLONE_ELEMENT", "description": "Clone customer row 5 times", "sourceSelector": "[data-ak=\"customer-row\"]", "containerSelector": "[data-ak=\"customers-tbody\"]", "count": 5, "postcondition": { "type": "always" }, "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false }, "timeoutMs": 5000, "maxFailures": 1 }
-```
-
-## INJECT_MOCK_DATA
-
-Orchestrator opcode that fills a fillable region with mock data. Carries fields for **two complementary delivery mechanisms** and applies BOTH whenever they are wired:
-
-- **Clone**: clones a template DOM element N times into a container and writes each slot value into the cloned descendants. Provides instant visual feedback even before any state-driven re-render. Works for any container whose children are pure markup the runtime can mutate.
-- **Trigger**: writes the JSON-encoded `defaultValues` array into a hidden `<input>` the user's app exposed, then clicks a hidden trigger element via `element.click()`. The user's `onClick` handler reads the input, parses the JSON, and re-renders the widget through normal React/Vue/Svelte state updates. Survives any future re-renders that would clobber the cloned DOM, and works for libraries that own their DOM (Chart.js, Recharts, D3).
-
-The two mechanisms are independent and additive. **Wire both whenever possible** — clone for instant paint, trigger to survive re-renders. The runtime applies clone first, then trigger. The opcode is recorded as `applied` if AT LEAST ONE mechanism succeeds.
-
-The named group is looked up from `ExecutionProgram.mockDataGroups` (compiled from `PresetConfig.mockDataInjection.groups`). **Non-blocking** — if both mechanisms fail (or neither was wired), the opcode is recorded as `mockDataGroupResults[groupName] = "skipped"` and the run continues.
-
-### Common params
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `groupName` | string | yes | Name of the MockDataGroup to use (must exist in the preset's `mockDataInjection.groups`) |
-
-### Clone params (optional but typically populated)
-
-| Param | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `containerSelector` | string | conditional | — | CSS selector of the container that holds the cloned items. Required if any other clone field is present. |
-| `templateSelector` | string | no | first child of container | CSS selector of the element to clone (defaults to `${containerSelector} > *:first-child`) |
-| `count` | number (1-500) | no | `defaultValues.length` | Override the row count |
-| `removeTemplate` | boolean | no | `false` | If true, remove the template after cloning (use to replace empty-state placeholders) |
-| `slotMappings` | array of `{ slot, selector, attribute? }` | conditional | — | Maps each slot name to a target inside a cloned item. Required if `containerSelector` is present. |
-
-**`slotMappings` entry:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `slot` | string | yes | Name of a slot from the MockDataGroup |
-| `selector` | string | yes | CSS selector RELATIVE to the cloned item |
-| `attribute` | string | no | If present, write to `setAttribute(name, value)`. If absent, write to `textContent`. |
-
-The runtime tags each clone with `data-ak-mock-clone="<i>"` so slot selectors are addressed via the tag rather than `nth-child` math — robust against non-template siblings (placeholders, headers).
-
-### Trigger params (optional but typically populated)
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `inputSelector` | string | conditional | CSS selector of the hidden `<input>` / `<textarea>` / `<select>` that receives the JSON payload. Required if `triggerSelector` is present. Use `[data-ak-fill-input="<group>"]`. |
-| `triggerSelector` | string | conditional | CSS selector of the hidden trigger element AutoKap clicks programmatically. Required if `inputSelector` is present. Use `[data-ak-fill-trigger="<group>"]`. |
-
-The runtime serializes `defaultValues` as a JSON array (`JSON.stringify(group.defaultValues)`) and writes it into the input via the React-aware native value setter, then dispatches `input` and `change` events, then calls `triggerElement.click()` directly. The user's `onClick` handler is responsible for parsing and applying the data.
-
-### Validation
-
-At least one mechanism must be complete (clone = `containerSelector` + `slotMappings`; trigger = `inputSelector` + `triggerSelector`). Partial mechanisms are rejected at compile time.
-
-### Capabilities
-
-**Can:**
-- Apply both mechanisms additively for the same group, in a single opcode.
-- Populate tables, lists, card grids, badge rows, and any container with text or image-source values via the clone mechanism.
-- Re-render charts, maps, calendars, and any programmatic widget via the trigger mechanism, by asking the user's app to handle the seed data through normal state updates.
-
-**Cannot:**
-- Trigger mechanism cannot work without app-side cooperation (the assistant must add a hidden trigger + input + `onClick` handler to the user's source code). The handler must JSON.parse the input value and validate the shape defensively.
-- Clone mechanism cannot persist DOM mutations into React/Vue/Svelte state — on the next render the framework reconciles its virtual tree against the real DOM and overwrites the cloned children. (This is exactly why you should also wire the trigger mechanism — it routes the same data through state, so the next render preserves it.)
-
-### Soft-failure semantics
-
-Returns failure if the group is missing, has no `defaultValues`, the opcode declares neither mechanism, or both wired mechanisms fail at runtime. The runner converts failure into `status: "skipped"` and records `mockDataGroupResults[groupName] = "skipped"`. If at least one mechanism succeeds, the group is recorded as `"applied"` even if the other failed.
-
-### Example — Both mechanisms (recommended)
-
-```json
-{
-  "kind": "INJECT_MOCK_DATA",
-  "description": "Populate preset cards with mock data",
-  "groupName": "preset-cards",
-
-  "containerSelector": "[data-ak=\"preset-card-grid\"]",
-  "templateSelector": "[data-ak=\"preset-card-grid\"] > [data-ak=\"preset-card\"]",
-  "removeTemplate": true,
-  "slotMappings": [
-    { "slot": "title", "selector": "[data-ak=\"preset-card-title\"]" },
-    { "slot": "lastCapture", "selector": "[data-ak=\"preset-card-last-capture\"]" },
-    { "slot": "variantCount", "selector": "[data-ak=\"preset-card-variant-count\"]" },
-    { "slot": "creditCost", "selector": "[data-ak=\"preset-card-credit-cost\"]" },
-    { "slot": "typeBadge", "selector": "[data-ak=\"preset-card-type-badge\"]" }
-  ],
-
-  "inputSelector": "[data-ak-fill-input=\"preset-cards\"]",
-  "triggerSelector": "[data-ak-fill-trigger=\"preset-cards\"]",
-
-  "postcondition": { "type": "always" },
-  "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false },
-  "timeoutMs": 5000,
-  "maxFailures": 1
-}
-```
-
-### Example — Clone-only (static HTML, no app state)
-
-```json
-{
-  "kind": "INJECT_MOCK_DATA",
-  "description": "Populate static customers table",
-  "groupName": "customers-table",
-  "containerSelector": "[data-ak=\"customers-tbody\"]",
-  "templateSelector": "[data-ak=\"customers-tbody\"] > [data-ak=\"customer-row\"]",
-  "removeTemplate": true,
-  "slotMappings": [
-    { "slot": "name", "selector": "[data-ak=\"customer-name\"]" },
-    { "slot": "avatar", "selector": "[data-ak=\"customer-avatar\"]", "attribute": "src" }
-  ],
-  "postcondition": { "type": "always" },
-  "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false },
-  "timeoutMs": 5000,
-  "maxFailures": 1
-}
-```
-
-### Example — Trigger-only (pure D3 widget, no DOM template to clone)
-
-```json
-{
-  "kind": "INJECT_MOCK_DATA",
-  "description": "Seed revenue chart with mock data",
-  "groupName": "revenue-chart",
-  "inputSelector": "[data-ak-fill-input=\"revenue-chart\"]",
-  "triggerSelector": "[data-ak-fill-trigger=\"revenue-chart\"]",
-  "postcondition": { "type": "always" },
-  "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false },
-  "timeoutMs": 5000,
-  "maxFailures": 1
-}
-```
-
-## REMOVE_ELEMENT
-
-Remove all elements matching a CSS selector. **Non-blocking.**
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `selector` | string | yes | CSS selector — every match is removed |
-
-**Can:** Strip empty-state illustrations, debug banners, "powered by" footers, or any visual noise that would distract from the screenshot.
-**Cannot:** Remove an element from a parent that re-renders it via React state — the next render will recreate it.
-
-**Soft-failure semantics:** Throws if the selector matches zero elements. The runner converts the throw into `status: "skipped"`.
-
-```json
-{ "kind": "REMOVE_ELEMENT", "description": "Remove empty-state illustration", "selector": "[data-ak=\"empty-state\"]", "postcondition": { "type": "always" }, "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false }, "timeoutMs": 3000, "maxFailures": 1 }
-```
-
-## SET_ATTRIBUTE
-
-Set an attribute on the first matching element. **Non-blocking.**
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `selector` | string | yes | CSS selector of the target element (first match only) |
-| `attribute` | string | yes | Attribute name (e.g. `"src"`, `"href"`, `"data-state"`) |
-| `value` | string | yes | Attribute value |
-
-**Can:** Swap an `<img src>`, change a `data-*` flag to trigger CSS state, set `aria-*` for a11y previews, or override `href` on a link.
-**Cannot:** Trigger React state updates — only the DOM attribute changes. Replace `style` reliably (prefer setting a `class` or `data-*` and letting CSS handle the visual).
-
-**Soft-failure semantics:** Throws if the selector is unmatched. The runner converts the throw into `status: "skipped"`.
-
-```json
-{ "kind": "SET_ATTRIBUTE", "description": "Override hero image src", "selector": "[data-ak=\"hero-image\"]", "attribute": "src", "value": "https://picsum.photos/1200/600", "postcondition": { "type": "always" }, "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false }, "timeoutMs": 3000, "maxFailures": 1 }
-```

package/assets/skill/README.md

@@ -1,38 +0,0 @@
-# AutoKap Skill Packaging
-
-`assets/skill/` is the canonical source of truth for the AutoKap skill system.
-Edit files here first.
-
-## Packaging model
-
-- `SKILL.md` is the core preset contract and must stay short enough to remain
-  readable.
-- `references/*.md` holds longer mode-specific guidance and examples.
-- `src/skill-packaging.ts` compiles these sources into the outputs each agent
-  expects.
-
-## Agent parity rules
-
-- Codex installs a local bundle: `SKILL.md` plus companion files in
-  `references/`.
-- Claude Code, Cursor, Windsurf, Copilot, and the HTTP download endpoint use a
-  flattened single-file export generated from the same source.
-- The bundle and single-file exports must carry the same instructions. Change
-  semantics once in `assets/skill/`, then regenerate every output.
-
-## Maintenance rules
-
-1. Keep non-negotiable contract rules in `SKILL.md`.
-2. Move long examples or mode-specific detail into `references/*.md`.
-3. Do not hand-edit `package/assets/skill/`. It is a published mirror synced
-   from this directory.
-4. After editing skill assets, run `npm run sync:package` or any build path
-   that executes `scripts/sync-package-bundle.mjs`.
-5. Before merging, run:
-   - `npx vitest run src/skill-packaging.test.ts src/package-bundle.test.ts`
-   - `npx tsc --noEmit`
-
-## Published mirror
-
-`package/assets/skill/` must stay byte-for-byte aligned with this directory.
-Tests enforce that parity so the npm package and the repo sources cannot drift.