oh-my-codex-pennix 0.18.13

package/skills/visual-ralph/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: visual-ralph
+description: "Visual Ralph orchestration for frontend UI from generated references, static references, or live URL targets, using $ralph with built-in visual verdict and pixel-diff evidence until the implementation matches and leaves a reproducible design system."
+---
+
+# Visual Ralph Skill
+
+Use this skill when the user wants Codex to build or restyle frontend UI through a Visual Ralph loop: an approved generated reference, static reference, or live URL-derived baseline becomes the target, Ralph implements, and Visual Verdict drives measured iteration rather than subjective description alone.
+
+## Purpose
+
+Create a measured frontend delivery loop from either a generated reference, a static reference, or a live URL:
+
+`user description / live URL -> approved visual reference -> $ralph implementation -> Visual Ralph verdict + pixel diff -> reproducible design system`.
+
+For live URL cloning requests, Visual Ralph owns the migrated `$web-clone` use case. Do not route new URL-driven website cloning work to `$web-clone`; preserve the URL, viewport, fidelity requirements, and interaction notes inside the Visual Ralph loop.
+
+This is an orchestration skill. It composes existing skills and must not add runtime commands, dependencies, or app-specific assumptions by itself.
+
+## Use when
+
+- The user describes a desired web/app UI and wants implementation, not just design advice.
+- The user provides a live URL and wants a visual implementation or clone through measured Visual Verdict iteration.
+- A generated raster mockup/reference image would make the target clearer.
+- The task needs pixel-level visual iteration with a pass/fail threshold.
+- The final result should leave reusable design tokens/components, not only a one-off screenshot match.
+
+## Do not use when
+
+- The user only wants repo-wide design guidance, product/design context, or a DESIGN.md source of truth; use `$design` or a designer lane.
+- The task is a non-visual backend/API implementation with no UI reference target.
+- The user already supplied a final static reference image and only needs comparison/fixes; hand directly to `$ralph` with Visual Ralph verdict guidance.
+- The requested output is a deterministic SVG/vector/code-native asset rather than a raster reference.
+
+## Workflow
+
+### 1. Ground the target repo
+
+Before stack-specific choices, inspect local evidence:
+- package manager and scripts,
+- frontend framework and routing structure,
+- styling system and design-token conventions,
+- screenshot/test tooling,
+- existing components that should be reused.
+
+Do not hardcode React, Vue, Tailwind, Playwright, or any other stack unless the repository evidence supports it.
+
+### 2. Establish the visual reference
+
+For live URL requests, capture or document the URL-derived reference inside the Visual Ralph artifacts and carry forward viewport, content-state, and interaction constraints. Do not invoke `$web-clone`; that standalone skill is hard-deprecated.
+
+Live URL reference artifacts must include:
+- source URL and permission/scope note,
+- viewport(s), route/state, and any seed/login assumptions,
+- captured baseline screenshot path or documented capture command/tool,
+- interaction parity notes for visible controls,
+- known exclusions such as backend/API/auth, personalized data, multi-page crawling, and third-party widget parity.
+
+For generated UI concepts, use `$imagegen` to produce the reference from the user's UI description.
+
+Prompt requirements:
+- classify as `ui-mockup`, unless another imagegen taxonomy is clearly better,
+- include viewport/aspect ratio and intended surface,
+- specify layout, hierarchy, typography direction, color mood, and any exact text,
+- forbid logos/watermarks/unrequested brand marks,
+- ask imagegen to avoid impossible UI details or unreadable text.
+
+When running under OMX CLI/runtime and a generated reference is part of an active Ralph-style loop, queue a continuation checkpoint before invoking the built-in image tool:
+
+```bash
+omx imagegen continuation <session-id> --artifact <slug-or-filename> --generated-dir "$CODEX_HOME/generated_images/<session>" --work-dir ".omx/artifacts/visual-ralph/<slug>"
+```
+
+This helper records `.omx/state/sessions/<session>/imagegen-pending.json` and uses the existing Stop-hook follow-up queue. It exists because built-in image generation may have to end the assistant turn immediately; the next Stop checkpoint should resume artifact recovery, copy the generated image into the workspace, and run the required visual QA/verdict gate instead of relying on a manual `$ralph` re-prompt.
+
+For project-bound implementation, copy the approved reference into the workspace, for example under `.omx/artifacts/visual-ralph/<slug>/reference.png`. Never leave the implementation reference only in `$CODEX_HOME/generated_images/...`.
+
+### 3. Require explicit user approval
+
+Stop after reference generation or URL-derived reference capture and ask the user to approve one reference image/state or request a targeted regeneration/capture adjustment.
+
+Before approval:
+- do not start frontend implementation,
+- do not invoke `$ralph`,
+- do not treat a rough image as final.
+
+After approval, the confirmed image or URL-derived baseline becomes the visual source of truth. Major design pivots, replacing the reference, or changing the design direction require an explicit user request.
+
+### 4. Hand off to `$ralph` for implementation
+
+Invoke `$ralph` with:
+- the approved reference image path or URL-derived baseline artifact,
+- source URL, viewport(s), content state, and interaction parity notes for live URL tasks,
+- the user description,
+- the detected repo/frontend context,
+- exact screenshot command/viewport requirements,
+- the completion checklist below.
+
+Ralph may iterate autonomously after approval. It should edit code, run the app, capture screenshots, and keep improving until the approved reference is matched or a real blocker exists.
+
+### 5. Use Visual Ralph verdict before every next edit
+
+For each visual iteration:
+1. Capture the current generated screenshot with recorded viewport/state.
+2. Run the Visual Ralph verdict step comparing the approved reference and generated screenshot. Use the `vision` agent for image understanding when needed.
+3. Treat the JSON verdict as authoritative.
+4. If `score < 90`, convert `differences[]` and `suggestions[]` into the next edit plan.
+5. Rerun before the next edit.
+
+Required verdict shape: `score`, `verdict`, `category_match`, `differences[]`, `suggestions[]`, and `reasoning`.
+
+### 6. Use pixel diff only as secondary debug evidence
+
+When mismatch diagnosis is hard, generate a pixel diff or pixelmatch overlay to locate hotspots. Pixel diff does not replace the Visual Ralph verdict; it only helps translate visual hotspots into concrete edits.
+
+Record final diff evidence with the reference/screenshot artifacts so the result can be audited.
+
+### 7. Build a reproducible design system
+
+The implementation is incomplete unless the visual match is encoded in repo-native reusable artifacts. Depending on the project, this may mean CSS variables, theme tokens, Tailwind config, component variants, Storybook stories, updates that align with DESIGN.md, or existing equivalents.
+
+Capture at least the applicable:
+- colors,
+- spacing scale,
+- typography scale/weights,
+- radii,
+- shadows/elevation,
+- important component variants and states.
+
+Prefer existing token/component patterns. Do not introduce a new design-system layer if the repo already has one that can be extended.
+
+## Completion checklist
+
+Do not declare done until all are true:
+- Approved reference image or URL-derived reference artifact is saved in the workspace.
+- Screenshot reproduction command, viewport, route, seed/state, and output paths are documented.
+- Visual Ralph verdict final score is `>= 90` against the approved reference.
+- Pixel diff or overlay evidence is recorded as secondary debug evidence.
+- Design-system tokens/components are repo-native and reusable.
+- Build/lint/test or the repo's equivalent verification passes.
+- No unapproved major design pivot occurred after reference approval.
+- Remaining visual differences, if any, are explicitly documented with rationale.
+
+## Handoff template
+
+```text
+$ralph "Implement the approved frontend reference.
+Reference: <workspace-reference-image-or-url-derived-artifact>
+Source URL (if URL-derived): <url and permission/scope note>
+Viewport/content state: <viewport, route/state, seed/login assumptions>
+Interaction parity notes: <visible controls and known exclusions>
+Route/surface: <route or component>
+Screenshot command: <command and viewport>
+Use the Visual Ralph verdict step before every next edit; pass threshold score >= 90.
+Use pixel diff only as secondary debug evidence.
+Extract reusable design tokens/components for colors, spacing, typography, radii, shadows, and key variants.
+Run build/lint/test before completion.
+Do not make major design pivots unless explicitly requested."
+```
+
+Task: {{ARGUMENTS}}

package/skills/visual-verdict/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: visual-verdict
+description: Visual Verdict deprecated skill
+---
+
+# Visual Verdict deprecated
+
+Hard-deprecated. Do not invoke or route this skill. Use `$visual-ralph` directly; visual verdict scoring is part of that workflow.
+
+Task: {{ARGUMENTS}}

package/skills/web-clone/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: web-clone
+description: Web Clone deprecated shim
+---
+
+# Web Clone deprecated
+
+Hard-deprecated. Do not invoke or route this skill. Use `$visual-ralph` directly for live-URL visual implementation and visual QA workflows.
+
+<Do_Not_Use_When>
+- User only has screenshot references without a live URL — use `$visual-verdict` directly
+- User wants to modify, redesign, or "improve" the site — use standard implementation flow
+- Target requires authentication, payment flows, or backend API parity — out of scope for v1
+- Multi-page / multi-route deep cloning — v1 handles single-page scope only
+</Do_Not_Use_When>
+
+<Scope_Limits>
+**v1 scope**: Single page clone of the provided URL.
+
+Included:
+- Layout structure (header, nav, content areas, sidebar, footer)
+- Typography (font families, sizes, weights, line heights)
+- Colors, spacing, borders, border-radius
+- Core interactions: navigation links, buttons, form elements, dropdowns, modals, toggles
+- Responsive hints from the extracted layout (flexbox/grid patterns)
+
+Excluded:
+- Backend API integration or data fetching
+- Authentication flows or protected content
+- Dynamic/personalized content (user-specific data)
+- Multi-page crawling or route graph cloning
+- Third-party widget functionality (maps, embeds, chat widgets)
+- Image/asset replication (use placeholders for external images)
+
+**Legal notice**: Only clone sites you own or have explicit permission to replicate. Respect copyright and trademarks.
+</Scope_Limits>
+
+<Prerequisites>
+Playwright MCP server must be available for browser automation.
+
+2. If no browser tools are found, instruct the user:
+   ```
+   Playwright MCP is required. Configure it:
+   codex mcp add playwright npx "@playwright/mcp@latest"
+   ```
+3. Required tools: `browser_navigate`, `browser_snapshot`, `browser_take_screenshot`, `browser_evaluate`, `browser_wait_for`. Optional: `browser_click`, `browser_network_requests`.
+</Prerequisites>
+
+<Inputs>
+- `target_url` (required): The URL to clone
+- `output_dir` (optional, default: current working directory): Where to generate the clone project
+- `tech_stack` (optional, inferred from project context): HTML/CSS/JS, React, Vue, Svelte, etc.
+</Inputs>
+
+<Tool_Usage>
+- If no browser tools are found, stop immediately and instruct the user to configure Playwright MCP.
+- Use `browser_snapshot` (accessibility tree) for structural understanding — it is far more token-efficient than screenshots.
+- Use `browser_take_screenshot` only when visual verification is needed (Pass 1 baseline, Pass 4 comparison).
+- Use `browser_evaluate` for DOM/style extraction — pass the scripts from this skill EXACTLY as written (do not modify them).
+- If running within ralph, use `state_write` / `state_read` for web-clone state persistence between iterations.
+- Skip Codex consultation for straightforward extraction; use it only if verification repeatedly fails on the same issue.
+</Tool_Usage>
+
+<State_Management>
+Persist extraction and progress data so the pipeline can resume if interrupted.
+
+- **After Pass 1 completes**: Write extraction summary to `.omx/state/{scope}/web-clone-extraction.json` containing:
+  - `target_url`, `extracted_at` timestamp
+  - `screenshot_path` (path to `target-full.png`)
+  - `landmark_count` (number of nav, main, footer, form elements)
+  - `interactive_count` (number of detected interactive elements)
+  - `extraction_size_kb` (approximate size of DOM extraction data)
+- **After each Pass 4 verification**: Append the composite verdict to `.omx/state/{scope}/web-clone-verdicts.json`.
+- **When running within ralph**: Also persist the `visual` portion of the composite verdict to `.omx/state/{scope}/ralph-progress.json` for ralph compatibility, mapping `visual.score` → top-level `score` and `visual.verdict` → top-level `verdict`.
+- **On completion or failure**: Write final status with `completed_at` or `failed_at` timestamp.
+</State_Management>
+
+<Context_Budget>
+Pass 1 extraction can produce very large data. Apply these limits proactively:
+
+- **DOM tree**: If the serialized JSON exceeds ~30KB, reduce `depth` parameter from 8 to 4 and re-extract. Focus on top-level structure.
+- **Accessibility snapshot**: If it exceeds ~20KB, this is normal for complex pages. Summarize key landmarks rather than keeping the full tree.
+- **Interactive elements**: Cap at 50 elements. If more exist, keep only visible ones (`isVisible: true`).
+- **Total extraction context**: Aim for under 60KB combined. If exceeded, prioritize: screenshot > accessibility snapshot > interactive elements > DOM styles.
+- **Image tokens**: Full-page screenshots are expensive. Take one baseline in Pass 1 and one comparison in Pass 4. Do not take screenshots between iterations unless debugging a specific region.
+</Context_Budget>
+
+<Steps>
+
+## Pass 1 — Extract
+
+Capture the target page's structure, styles, interactions, and visual baseline.
+
+1. **Navigate**: `browser_navigate` to `target_url`.
+2. **Wait for render**: `browser_wait_for` with appropriate condition (network idle or timeout of 5s) to ensure full render including lazy-loaded content.
+3. **Accessibility snapshot**: `browser_snapshot` — captures the semantic tree (roles, names, values, interactive states). This is your primary structural reference.
+4. **Full-page screenshot**: `browser_take_screenshot` with `fullPage: true` — save as reference baseline `target-full.png`.
+5. **DOM + computed styles**: `browser_evaluate` with the following script. **COPY THIS SCRIPT EXACTLY — do not modify it**:
+   ```javascript
+   (() => {
+     const walk = (el, depth = 0) => {
+       if (depth > 8 || !el.tagName) return null;
+       const cs = window.getComputedStyle(el);
+       return {
+         tag: el.tagName.toLowerCase(),
+         id: el.id || undefined,
+         classes: [...el.classList].slice(0, 5),
+         styles: {
+           display: cs.display, position: cs.position,
+           width: cs.width, height: cs.height,
+           padding: cs.padding, margin: cs.margin,
+           fontSize: cs.fontSize, fontFamily: cs.fontFamily,
+           fontWeight: cs.fontWeight, lineHeight: cs.lineHeight,
+           color: cs.color, backgroundColor: cs.backgroundColor,
+           border: cs.border, borderRadius: cs.borderRadius,
+           flexDirection: cs.flexDirection, justifyContent: cs.justifyContent,
+           alignItems: cs.alignItems, gap: cs.gap,
+           gridTemplateColumns: cs.gridTemplateColumns,
+         },
+         text: el.childNodes.length === 1 && el.childNodes[0].nodeType === 3
+           ? el.textContent?.trim().slice(0, 100) : undefined,
+         children: [...el.children].map(c => walk(c, depth + 1)).filter(Boolean),
+       };
+     };
+     return walk(document.body);
+   })()
+   ```
+6. **Interactive elements**: `browser_evaluate` to catalog all interactable elements. **COPY THIS SCRIPT EXACTLY — do not modify it**:
+   ```javascript
+   (() => {
+     const results = [];
+     document.querySelectorAll(
+       'button, a[href], input, select, textarea, [role="button"], ' +
+       '[onclick], [aria-haspopup], [aria-expanded], details, dialog'
+     ).forEach(el => {
+       results.push({
+         tag: el.tagName.toLowerCase(),
+         type: el.type || el.getAttribute('role') || 'interactive',
+         text: (el.textContent || '').trim().slice(0, 80),
+         href: el.href || undefined,
+         ariaLabel: el.getAttribute('aria-label') || undefined,
+         isVisible: el.offsetParent !== null,
+       });
+     });
+     return results;
+   })()
+   ```
+7. **Network patterns** (optional): `browser_network_requests` — note XHR/fetch calls for reference. Do not attempt to replicate backends.
+
+Keep all extraction results in working memory for Pass 2.
+
+## Pass 2 — Build Plan
+
+Analyze extraction results and decompose into a component plan.
+
+1. **Identify page regions**: From DOM tree + accessibility snapshot, identify major sections:
+   - Navigation bar / header
+   - Hero / banner section
+   - Main content area(s)
+   - Sidebar (if present)
+   - Footer
+   - Overlay elements (modals, drawers)
+
+2. **Map components**: For each region, define:
+   - Component name and responsibility
+   - Key style properties (from computed styles)
+   - Content summary (headings, text, images)
+   - Child components if nested
+
+3. **Create interaction map**: From interactive elements list:
+   - Navigation links → anchor tags with `href`
+   - Form elements → proper `<form>` with inputs, labels, validation
+   - Buttons → click handlers (toggle, submit, navigate)
+   - Dropdowns/modals → show/hide toggle with transitions
+   - Accordions/tabs → state-based visibility
+
+4. **Extract design tokens**: Identify recurring values:
+   - Color palette (primary, secondary, background, text colors)
+   - Font stack (families, size scale, weight scale)
+   - Spacing scale (padding/margin patterns)
+   - Border radius values
+
+5. **Define file structure**:
+   ```
+   {output_dir}/
+   ├── index.html          (or App.tsx / App.vue)
+   ├── styles/
+   │   ├── globals.css      (reset + tokens)
+   │   └── components.css   (or scoped styles)
+   ├── scripts/
+   │   └── interactions.js  (toggle, modal, dropdown logic)
+   └── assets/              (placeholder images)
+   ```
+   Adapt to `tech_stack` if specified (React components, Vue SFCs, etc.).
+
+## Pass 3 — Generate Clone
+
+Implement the clone from the plan. Work component-by-component.
+
+1. **Scaffold**: Create the directory structure and base files.
+2. **Design tokens first**: Implement CSS custom properties or Tailwind config from extracted tokens.
+3. **Layout shell**: Build the page-level layout matching the original's flexbox/grid structure.
+4. **Components**: Implement each region top-down:
+   - Match DOM structure from extraction (semantic tags, landmark roles)
+   - Apply computed styles — prioritize layout properties, then typography, then decorative
+   - Use actual extracted text content; use placeholder `<img>` for external images
+5. **Interactions**: Wire up detected behaviors:
+   - Navigation: working `<a>` tags (to `#` anchors or stubs for v1)
+   - Forms: proper structure with `<label>`, input types, placeholder text
+   - Toggles: JavaScript for dropdowns, modals, accordions
+   - Hover/focus states: CSS transitions matching original behavior
+6. **Responsive**: If the original uses responsive breakpoints (detectable from media queries in computed styles or from viewport behavior), add basic responsive rules.
+
+## Pass 4 — Verify
+
+Compare the clone against the original across three dimensions.
+
+1. **Serve the clone**: Start a local server for the generated project:
+   ```bash
+   npx serve {output_dir} -l 3456 --no-clipboard
+   ```
+   If `npx serve` is unavailable, fall back to: `python3 -m http.server 3456 -d {output_dir}`.
+   The clone will be accessible at `http://localhost:3456`.
+2. **Visual verification**:
+   - Navigate to the clone with Playwright: `browser_navigate` to clone URL.
+   - Take full-page screenshot of clone.
+   - Run `$visual-verdict` with: `reference_images=["target-full.png"]`, `generated_screenshot="clone-full.png"`, `category_hint="web-clone"`.
+   - The visual portion of the verdict feeds directly into the composite verdict below.
+   - Visual pass threshold: **score >= 85**.
+
+3. **Structural verification**: Compare landmark counts:
+   - Count `<nav>`, `<main>`, `<footer>`, `<form>`, `<button>`, `<a>` in both original and clone.
+   - Structure passes when all major landmarks exist (missing landmarks = fail).
+
+4. **Functional spot-check**: Test 2–3 detected interactions via Playwright:
+   - Click a navigation link → verify URL change or scroll behavior
+   - Toggle a dropdown/modal → verify visibility change
+   - Interact with a form field → verify it accepts input
+   - Use `browser_click` and `browser_snapshot` to verify state changes.
+
+5. **Emit composite verdict**:
+
+```json
+{
+  "visual": {
+    "score": 82,
+    "verdict": "revise",
+    "category_match": true,
+    "differences": ["Header spacing tighter than original"],
+    "suggestions": ["Increase nav gap to 24px"]
+  },
+  "functional": {
+    "tested": 3,
+    "passed": 2,
+    "failures": ["Dropdown does not open on click"]
+  },
+  "structure": {
+    "landmark_match": true,
+    "missing": [],
+    "extra": []
+  },
+  "overall_verdict": "revise",
+  "priority_fixes": [
+    "Fix dropdown toggle interaction",
+    "Increase header nav spacing"
+  ]
+}
+```
+
+## Pass 5 — Iterate
+
+Fix highest-impact issues and re-verify.
+
+1. **Prioritize fixes** by impact: layout > interactions > spacing > typography > colors.
+2. **Apply targeted edits**: Fix only the issues listed in `priority_fixes`. Do not refactor working code.
+3. **Re-verify**: Repeat Pass 4.
+4. **Loop**: Continue until `overall_verdict` is `pass` OR max **5 iterations** reached.
+5. **Final report**: Summarize what was successfully cloned, any remaining differences, and elements that could not be replicated.
+
+</Steps>
+
+<Output_Contract>
+After each verification pass, emit a **composite web-clone verdict** JSON:
+
+```json
+{
+  "visual": {
+    "score": 0,
+    "verdict": "revise",
+    "category_match": false,
+    "differences": ["..."],
+    "suggestions": ["..."],
+    "reasoning": "short explanation"
+  },
+  "functional": {
+    "tested": 0,
+    "passed": 0,
+    "failures": ["..."]
+  },
+  "structure": {
+    "landmark_match": false,
+    "missing": ["..."],
+    "extra": ["..."]
+  },
+  "overall_verdict": "revise",
+  "priority_fixes": ["..."]
+}
+```
+
+Rules:
+- `visual` follows the `VisualVerdict` shape from `$visual-verdict`
+- `functional.tested/passed` are counts; `failures` list specific interaction failures
+- `structure.landmark_match` is `true` when all major HTML landmarks (nav, main, footer, forms) are present
+- `overall_verdict`: `pass` when visual.score >= 85 AND functional.failures is empty AND structure.landmark_match is true
+- `priority_fixes`: ordered by impact, drives the next iteration
+</Output_Contract>
+
+<Iteration_Thresholds>
+- **Visual pass**: score >= 85
+- **Functional pass**: zero failures on tested interactions
+- **Structure pass**: all major landmarks present
+- **Overall pass**: all three dimensions pass
+- **Max iterations**: 5 (report best achieved result if threshold not met)
+</Iteration_Thresholds>
+
+<Error_Handling>
+- **Playwright MCP unavailable**: Stop. Instruct user to configure it. Do not attempt to clone without browser tools.
+- **Page fails to load**: Report the URL and HTTP status. Suggest the user verify the URL is accessible.
+- **browser_evaluate returns empty**: The page may use heavy client-side rendering. Wait longer (`browser_wait_for` with extended timeout) and retry once.
+- **Visual score stuck below threshold after 3 iterations**: Report the current state as best-effort. List the unresolved differences for the user.
+- **Extraction data too large for context**: Truncate deep DOM branches (depth > 6). Focus on top-level structure and defer nested details to iteration fixes.
+</Error_Handling>
+
+<Example>
+**User**: "Clone https://news.ycombinator.com"
+
+**Pass 1**: Navigate to HN. Extract: table-based layout, orange (#ff6600) nav bar, story list with links + points + comments, footer. Screenshot saved.
+
+**Pass 2**: Regions: nav bar (logo + links), story table (30 rows × title + meta), footer. Tokens: orange #ff6600, gray #828282, Verdana font, 10pt base. Interaction map: story links (external), comment links, "more" pagination.
+
+**Pass 3**: Generate index.html with HN-style table layout, CSS matching extracted colors/fonts, working `<a>` tags for stories.
+
+**Pass 4**: Visual score=78 (font size off, spacing between stories too tight). Functional 2/2 (links work). Structure match=true.
+
+**Pass 5 iteration 1**: Fix font to Verdana 10pt, increase row padding → score=88. Functional 2/2. Structure match. → `overall_verdict: pass`. Done.
+</Example>
+
+<Final_Checklist>
+- [ ] Pass 1 extraction completed and summarized (screenshot + accessibility tree + DOM styles + interactions)
+- [ ] Pass 2 component plan created with file structure
+- [ ] Pass 3 clone generated and files written to `output_dir`
+- [ ] Clone serves locally without errors
+- [ ] Pass 4 composite verdict emitted with all three dimensions
+- [ ] `overall_verdict` is `pass`, or max 5 iterations reached with best-effort report
+- [ ] When in ralph: visual verdict persisted to `ralph-progress.json`
+- [ ] Extraction summary persisted to `web-clone-extraction.json`
+</Final_Checklist>

package/skills/wiki/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: wiki
+description: Persistent markdown project wiki stored under repository omx_wiki with keyword search and lifecycle capture
+triggers: ["wiki add", "wiki lint", "wiki query", "wiki read", "wiki delete"]
+---
+
+# Wiki
+
+Persistent, self-maintained markdown knowledge base for project and session knowledge.
+
+## Operations
+
+### Ingest
+```bash
+omx wiki wiki_ingest --input '{"title":"Auth Architecture","content":"...","tags":["auth","architecture"],"category":"architecture"}' --json
+```
+
+### Query
+```bash
+omx wiki wiki_query --input '{"query":"authentication","tags":["auth"],"category":"architecture"}' --json
+```
+
+### Lint
+```bash
+omx wiki wiki_lint --json
+```
+
+### Quick Add
+```bash
+omx wiki wiki_add --input '{"title":"Page Title","content":"...","tags":["tag1"],"category":"decision"}' --json
+```
+
+### List / Read / Delete
+```bash
+omx wiki wiki_list --json
+omx wiki wiki_read --input '{"page":"auth-architecture"}' --json
+omx wiki wiki_delete --input '{"page":"outdated-page"}' --json
+omx wiki wiki_refresh --json
+```
+
+## Categories
+`architecture`, `decision`, `pattern`, `debugging`, `environment`, `session-log`, `reference`, `convention`
+
+## Storage
+- Pages: `omx_wiki/*.md`
+- Index: `omx_wiki/index.md`
+- Log: `omx_wiki/log.md`
+
+## Cross-References
+Use `[[page-name]]` wiki-link syntax to create cross-references between pages.
+
+## Auto-Capture
+At session end, discoveries can be captured as `session-log-*` pages. Configure via `wiki.autoCapture` in `.omx-config.json`.
+
+## Hard Constraints
+- No vector embeddings — query uses keyword + tag matching only
+- Wiki files are repository project knowledge under `omx_wiki/`; legacy `.omx/wiki/` is read-only compatibility input when no canonical wiki exists