feat: prepare cross-platform v1.0 release

Author: bx33661

.github/workflows/validate.yml

@@ -9,22 +9,21 @@ permissions:
 
 jobs:
   quality:
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
           cache: "npm"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
       - name: Install dependencies
         run: npm ci
       - name: Validate project
-        run: npm run validate
-      - name: Check golden invalid-flags eval
-        run: python3 skills/omv-find/scripts/check_output.py --eval-id 26 --output skills/omv-find/evals/golden/invalid-flags.md
-      - name: Check omv-report blocked handoff golden eval
-        run: python3 skills/omv-report/scripts/check_output.py --eval-id 4 --output skills/omv-report/evals/golden/blocked-handoff.md
-      - name: Check omv-report OSV golden eval
-        run: python3 skills/omv-report/scripts/check_output.py --eval-id 5 --output skills/omv-report/evals/golden/osv-prototype-pollution.json
-      - name: Check omv-report duplicate CNA golden eval
-        run: python3 skills/omv-report/scripts/check_output.py --eval-id 7 --output skills/omv-report/evals/golden/duplicate-cna-warning.md
+        run: npm run release:check

.gitignore

@@ -1,7 +1,7 @@
 # oh-my-vul state directory — findings, context snapshots, logs
 .omv/
 
-# Project-scoped Codex installs created by `omv setup --scope project`
+# Local Codex/OpenSpec scaffolding (consumer projects may commit selected skills)
 .codex/
 
 # Local assistant scaffolding and nested worktrees
@@ -15,7 +15,6 @@ oh-my-claudecode/
 # Maintainer / agent / release engineering docs (local only — not for GitHub)
 openspec/
 /SPEC.md
-/AGENTS.md
 /CLAUDE.md
 /DEVELOPMENT.md
 /RELEASE.md
@@ -40,6 +39,3 @@ __pycache__/
 .idea/
 *.swp
 *.swo
-.omv/repro/
-.omv/reports/
-.omv/archive/

AGENTS.md

@@ -0,0 +1,38 @@
+# Repository Guidance
+
+## Purpose
+
+`oh-my-vul` is a local-first, evidence-driven vulnerability research CLI and Skill collection. Keep research passive and reproduction local. Never weaken evidence gates to make a finding appear report-ready.
+
+## Layout
+
+- `src/cli/`: TypeScript CLI, domain workflows, renderers, and Ink TUI.
+- `src/cli/__tests__/`: Node test runner coverage for CLI and TUI behavior.
+- `skills/`: Canonical distributable Skills and their references, scripts, contracts, and evals.
+- `agents/`: Claude Code-specific optional subagent definitions.
+- `contracts/` and `shared/`: Canonical schemas and assets synchronized into Skills.
+- `scripts/`: metadata, asset, packaging, and release validation.
+- `openspec/`: local design artifacts; do not archive a change unless explicitly requested.
+
+## Development
+
+- Runtime baseline: Node.js 22 or later.
+- Install dependencies with `npm install`.
+- Use `npm run typecheck` for a fast TypeScript check.
+- Use `npm run build && npm test` for implementation changes.
+- Use `npm run release:check` before release-facing handoff.
+- Run `npm run sync-assets` after changing canonical shared assets.
+- Run `npm run sync-metadata` after changing package or registry metadata.
+
+## Conventions
+
+- Preserve deterministic JSON and non-TTY output. Ink must remain TTY-only.
+- Keep `.omv/` research state private and out of source control.
+- Use sanitized `demo-*`, `example-*`, or `fixture-*` data in tests and docs.
+- Treat `unknown` as a valid evidence state; do not infer exploitability or observed results.
+- Keep Codex and Claude Code setup paths isolated. Codex uses `.agents/skills`; Claude Code uses `.claude/skills` and optional `.claude/agents`.
+- Update tests, user documentation, and `CHANGELOG.md` when behavior is user-visible.
+
+## Completion
+
+A change is complete when relevant tests pass, generated assets and metadata are synchronized, `git diff --check` is clean, and release-facing changes pass `npm run release:check`.

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+- Added Windows as a validated platform with Python 3 runtime discovery, shell-independent Node test execution, cross-platform Skill packaging and LOC estimation, and an Ubuntu/Windows CI matrix. Claude Code remains the default platform when `--platform` is omitted.
+- Reduced install overhead by replacing the static `boxen` and `cli-table3` output layer with the built-in responsive renderer, removing 21 packages from a clean npm install.
+- Improved first-run setup with automatic platform-scoped health verification, explicit restart and Skill invocation guidance, compact install paths, accurate dry-run labels, and clearer download/upgrade documentation.
+
+## v1.0.0 - 2026-07-11
+
+- Froze the 1.0 CLI compatibility surface: workflow-first public help, grouped advanced automation commands, Skill-managed primitives hidden from public catalogs, and canonical `start`, `dashboard`, and `review` workflows replacing redundant wrappers.
+- Froze the remaining 1.0 compatibility boundaries with root-only Node package exports, inventoried runtime/type exports, required-field JSON contracts for every public automation command, parser-aware `.omv` contract versioning, and package-to-installed-Skill content drift checks.
+- Removed the pre-1.0 `first`, `workspace init`, `findings workflow`, `findings doctor`, `findings open`, and permanent `findings delete` routes with focused migration errors.
+- Removed the undocumented experimental `omv-mcp` executable and its custom line-delimited JSON protocol before the 1.0 compatibility boundary.
+- Added first-class Codex setup, doctor, and uninstall support using official `~/.agents/skills` and `.agents/skills` discovery paths, with platform-specific manifests and repository guidance in `AGENTS.md`.
+- Raised the runtime baseline to Node.js 22 and added an Ink 7 / React 19 interactive research workspace.
+- Bare `omv` now opens the responsive workspace in a real TTY; `omv tui` is the explicit entry, while `omv dashboard`, `--no-tui`, pipes, CI, and JSON remain deterministic plain output.
+- Added keyboard workflow navigation, live filtering, evidence-first finding inspection, action-surface guidance, help, refresh, narrow-terminal layouts, and an interactive guided start flow.
+- Hardened detail refresh/error recovery, explicit plain-mode routing, and terminal layouts down to a bounded 52x16 minimum.
+- Expanded the TUI with Overview, Findings, Campaign, and Activity views; Summary/Evidence/Threat/History detail tabs; structured filters; and a read-only command palette.
+- Added V3 full-width wrapped finding and Activity-event detail with scrolling and range indicators, plus paged access to the latest 200 Activity entries.
+
 ## v0.10.1 - npx package binary alias
 
 - Register `oh-my-vul` as a package bin alias for `omv`, so `npx oh-my-vul setup` works. Previously only `omv` / `omv-mcp` were exported, which made npx report "could not determine executable to run".

README.md

@@ -2,7 +2,7 @@
 
 # oh-my-vul
 
-**Evidence-first vulnerability research for Claude Code.**
+**Evidence-first vulnerability research for Codex and Claude Code.**
 
 Plan the research, trace the evidence, reproduce locally, and turn confirmed findings into review-ready reports.
 
@@ -16,7 +16,7 @@ Plan the research, trace the evidence, reproduce locally, and turn confirmed fin
 
 ---
 
-`oh-my-vul` combines Claude Code skills with a local CLI to make open-source vulnerability research repeatable:
+`oh-my-vul` combines agent skills with a local CLI to make open-source vulnerability research repeatable in Codex and Claude Code:
 
 - **Start with a clear scope.** Campaigns and attack-surface cards turn a broad target into focused research questions.
 - **Keep claims tied to evidence.** Findings record the tested version, source, sink, guards, reproduction, and remaining unknowns.
@@ -26,15 +26,17 @@ Research state stays in a private `.omv/` workspace. The project is designed for
 
 ## Quick Start
 
-**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and Node.js 20 or later.
+**Requirements:** [Codex](https://developers.openai.com/codex/) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Node.js 22 or later, and Python 3 for bundled Skill helpers. Windows, Linux, and macOS are supported; on Windows, use a modern Windows Terminal or PowerShell for the Ink workspace.
 
-Install the CLI and add the skills and agents to Claude Code:
+Install the CLI and add the skills to Codex:
 
 ```sh
-npm install --global oh-my-vul
-omv setup
+npm install --global oh-my-vul@latest
+omv setup --platform codex
 ```
 
+`setup` prints the destination and immediately verifies the completed install. Once every check passes, restart Codex and invoke `$omv`. Codex installs user skills under `~/.agents/skills`. For Claude Code, run `omv setup --platform claude-code`, restart it, and invoke `/omv`. Claude Code remains the backward-compatible default platform.
+
 From the root of the project you want to research, start a guided workspace:
 
 ```sh
@@ -47,42 +49,111 @@ omv start
 omv start --vuln xss,auth --no-interactive
 ```
 
-Open that project in Claude Code, then run:
+Open that project in Codex, then invoke the Skill (or choose it from `/skills`):
 
 ```text
-/omv
+$omv
 ```
 
-`/omv` applies the evidence and review gates, shows the active queue, and recommends the next action. From the shell, bare `omv` opens the same contextual workspace view.
+Claude Code users invoke `/omv`. The Skill applies the evidence and review gates, shows the active queue, and recommends the next action. From an interactive terminal, bare `omv` opens the Ink research workspace.
+
+## Interactive Workspace
+
+Run `omv` or `omv tui` in a terminal to browse the priority queue and inspect evidence without leaving the shell:
+
+```text
+Tab / 1-4    Cycle or jump to Overview, Findings, Campaign, and Activity
+↑/↓ or j/k   Move through findings
+/            Search by id, package, status, vulnerability, or action
+f            Filter by lifecycle status and action surface
+Enter        Switch queue/detail on narrow terminals
+[ / ]        Switch Summary, Evidence, Threat, and History detail tabs
+Space        Expand the selected finding or Activity event full-width
+PgUp/PgDn    Page through expanded detail or Activity history
+g / G        Jump to the first or last available line
+:            Open the read-only command palette
+a            Explain the selected CLI or agent action
+r            Refresh local workspace state
+?            Show keyboard help
+q            Quit and restore the previous terminal screen
+```
+
+The Findings view keeps the priority queue and splits local detail into Summary, Evidence, Threat, and History. Compact and split views may abbreviate text to preserve layout; press `Space` to open complete logical fields full-width, wrapped to the current terminal, with a visible line range and scrolling. Overview highlights current scope and next priority, Campaign shows lane counts and deterministic next actions, and Activity pages through the latest 200 local lifecycle changes. Activity rows are selectable and `Space` reveals the complete event reason, transition, and path. Structured filters compose with text search. The command palette navigates and performs local UI actions only.
+
+The workspace is read-only: it displays commands but never executes research commands or agent skill invocations. Use `omv dashboard` for deterministic plain output, or `omv --no-tui` / `omv tui --no-tui` to disable interactive rendering. JSON commands and piped output never start Ink. Terminals below 52 columns or 16 rows show a bounded resize prompt instead of an overflowing workspace.
 
 <details>
 <summary><strong>Installation options</strong></summary>
 
+Download and preview the install without writing Skills:
+
+```sh
+npx --yes oh-my-vul@latest setup --scope user --platform codex --dry-run
+```
+
 Install only for the current project:
 
 ```sh
-omv setup --scope project
+omv setup --scope project --platform codex
 ```
 
 Upgrade the package, then refresh a user-level or project-level install:
 
 ```sh
 npm install --global oh-my-vul@latest
 # Choose the scope you use:
-omv setup --scope user --force
-omv setup --scope project --force
+omv setup --scope user --platform codex --force
+omv setup --scope project --platform codex --force
 ```
 
+Every real `setup` now runs the matching platform and scope health check automatically. Run `omv doctor --strict --platform codex` separately only when diagnosing installation drift.
+
 Preview either scope without writing files:
 
 ```sh
 # Choose the scope you use:
-omv setup --scope user --dry-run
-omv setup --scope project --dry-run
+omv setup --scope user --platform codex --dry-run
+omv setup --scope project --platform codex --dry-run
 ```
 
+Replace `codex` with `claude-code` for a Claude Code installation. The two platforms use separate directories and manifests, so both can be installed safely. If a global npm install reports a permissions error, fix npm's user-level prefix instead of installing this package with `sudo`.
+
 </details>
 
+## 1.0 CLI Compatibility
+
+The 1.x public CLI has two stable tiers:
+
+- **Core workflow:** `omv`, `start`, `dashboard`, `review`, `setup`, `uninstall`, `doctor`, `version`, and `help`.
+- **Advanced automation:** public `campaign`, `findings`, `workspace`, `radar`, `dedup`, `disclose`, `submissions`, and `config` commands listed by `omv help --all`.
+
+Documented arguments, exit behavior, and `--json` output from those public commands follow SemVer compatibility within 1.x. Artifact scaffolding and diagnostics invoked by bundled Skills (`campaign surfaces/seed`, `eval`, `request`, `repro`, `sources`, `report`, `threat-map`, and `verification`) are deterministic but Skill-managed; use the versions installed from the same package release.
+
+For JSON automation, [contracts/cli-json.v1.json](contracts/cli-json.v1.json) lists every public JSON form, its result kind, required typed fields, and gate behavior. Existing listed fields keep their type and meaning throughout 1.x; commands may add fields. Validation and readiness commands may return a complete diagnostic JSON document with a non-zero exit when a documented gate is not met.
+
+The supported Node API is the package root only:
+
+```js
+import { listFindings, reviewFinding, setup } from "oh-my-vul";
+```
+
+Deep imports such as `oh-my-vul/dist/cli/*` are private implementation details and are blocked by the package export map. The exact runtime and type allowlist lives in [contracts/node-api.v1.json](contracts/node-api.v1.json).
+
+Versioned `.omv` formats follow [the contract compatibility policy](contracts/README.md) and the inventory in [contracts/artifact-contracts.v1.json](contracts/artifact-contracts.v1.json). Closed contracts require a new major for any field-set change; extensible contracts permit optional additions only when supported readers and writers remain compatible. Package upgrades never rewrite private research data solely to update a schema.
+
+CLI and bundled Skills are release-coupled. Run `omv doctor --platform codex` or `omv doctor --platform claude-code` after an upgrade; content or version drift is repaired explicitly with the scoped `omv setup ... --force` command printed by doctor.
+
+The 1.0 surface replaces earlier redundant commands:
+
+| Removed before 1.0 | Canonical command |
+|---|---|
+| `omv first` | `omv start` or `omv campaign init` |
+| `omv workspace init` | `omv start` |
+| `omv findings workflow` | `omv dashboard` |
+| `omv findings doctor <id>` | `omv review <id>` |
+| `omv findings open <id>` | `omv findings show <id>` |
+| `omv findings delete <id>` | `omv findings archive <id> --reason <reason>` |
+
 ## The Workflow
 
 ```text