Harden CLI with request preflight, dashboard UX, and project assets

Adds omv request/config commands, expands args validation, improves
setup --project mode, and includes logo assets. Updates README with
full skill table and quick-start for request preflight.

Author: bx33661

.gitignore

@@ -31,3 +31,6 @@ __pycache__/
 .idea/
 *.swp
 *.swo
+.omv/repro/
+.omv/reports/
+.omv/archive/

README.md

@@ -35,13 +35,15 @@
 | **Passive intelligence** | `/omv-radar` and `/omv-dedup` track watchlist changes and duplicate advisory risk. |
 | **Report drafting** | `/omv-report` generates review-friendly advisory drafts from validated findings. |
 | **Disclosure lifecycle** | `/omv-disclose`, `/omv-critic`, and `omv submissions ...` cover pre-submit review and post-submit tracking. |
+| **Request reliability** | `omv request ...` classifies rate limits, request refusals, source health, and cached metadata fetches. |
 | **CLI management** | `omv dashboard`, `omv doctor`, and `omv findings ...` keep local state inspectable. |
 
 ## Quick Start
 
 ```sh
 npx oh-my-vul setup
 omv doctor
+omv request preflight
 ```
 
 If `omv` is not on your `PATH`, use npx:
@@ -159,6 +161,23 @@ csrf xxe sql ssti sandbox redirect upload crypto infoleak
 
 `/omv-find` should return evidence-backed candidates: repository, registry identity, maintenance signal, code-size estimate, **source -> sink -> guard** notes, and local audit next steps.
 
+## Request Reliability
+
+`/omv-find` often needs public registry metadata, GitHub metadata, raw source files, and source archives. Those sources can be rate-limited, bot-blocked, missing, or temporarily unavailable. Use the TypeScript request broker before or during request-heavy research:
+
+```sh
+omv request preflight
+omv request preflight --json --refresh
+omv request fetch https://registry.npmjs.org/markdown-it --json
+omv request fetch https://api.github.com/repos/owner/repo --accept application/json --refresh
+```
+
+The broker writes cache entries under `.omv/cache/http/`, redacts sensitive response headers, and returns structured `failure.reason`, `rateLimit`, `expiresAt`, and `recommendation` fields. GitHub API requests automatically use `GITHUB_TOKEN` or `GH_TOKEN` when present.
+
+Common failure reasons are `rate_limited`, `auth_required`, `bot_blocked_or_forbidden`, `not_found`, `network_timeout`, `network_error`, `upstream_error`, and `invalid_url`. Treat these as research-state signals: keep affected fields unverified, prefer registry/source archive fallbacks, and avoid repeatedly retrying blocked URLs.
+
+See [docs/request-broker.md](docs/request-broker.md) for the full request broker behavior, JSON contract, cache policy, and Playwright evaluation.
+
 ## Evidence Ledger
 
 Project-local research state lives in `.omv/findings/`. These files are gitignored by default because they may contain private research notes.
@@ -268,6 +287,8 @@ omv dedup demo-traversal --confirm --existing-cve none --notes "searched NVD, GH
 | Document | Purpose |
 |---|---|
 | [README.zh-CN.md](README.zh-CN.md) | Chinese project guide. |
+| [docs/request-broker.md](docs/request-broker.md) | Request broker usage, failure classes, cache behavior, and Playwright evaluation. |
+| [docs/request-broker.zh-CN.md](docs/request-broker.zh-CN.md) | Chinese request broker guide. |
 | [docs/vulnerability-research-best-practices.zh-CN.md](docs/vulnerability-research-best-practices.zh-CN.md) | Chinese best-practices guide for vulnerability research with this project. |
 | [docs/examples/demo-finding-flow.md](docs/examples/demo-finding-flow.md) | Sanitized end-to-end finding workflow example. |
 | [docs/roadmap-0.8.md](docs/roadmap-0.8.md) | Planned `v0.8` CLI improvements. |

README.zh-CN.md

@@ -33,13 +33,15 @@
 | **深度审计** | `/omv-audit` 用 source -> sink -> guard 证明或否定候选漏洞。 |
 | **本地复现** | `/omv-repro` 记录用户真实本地观测和复现材料。 |
 | **报告生成** | `/omv-report` 从 validated finding 生成审稿友好的报告草稿。 |
+| **请求可靠性** | `omv request ...` 识别限流、拒绝、来源健康和缓存元数据请求。 |
 | **CLI 管理** | `omv dashboard`、`omv doctor`、`omv findings ...` 管理本地状态。 |
 
 ## 快速开始
 
 ```sh
 npx oh-my-vul setup
 omv doctor
+omv request preflight
 ```
 
 如果没有全局安装 `omv`，用 npx 临时运行：
@@ -115,6 +117,10 @@ omv version --json
 | `omv-audit` | `/omv-audit` | 深入审计候选 finding，补齐 Evidence.v1 证据字段 |
 | `omv-repro` | `/omv-repro` | 引导本地复现，记录真实 observed_result |
 | `omv-report` | `/omv-report` | 从 confirmed finding 生成 VulDB/CVE/GHSA/OSV 报告草稿 |
+| `omv-radar` | `/omv-radar` | 被动 watchlist 情报，刷新 advisory/release 信号 |
+| `omv-dedup` | `/omv-dedup` | 去重分析，生成 NVD/GHSA/OSV/生态查询并更新 Evidence.v1 |
+| `omv-disclose` | `/omv-disclose` | 负责任披露生命周期辅助，包括时间线和沟通草稿 |
+| `omv-critic` | `/omv-critic` | 提交前反向审稿，找出可能被 CNA 或平台拒绝的原因 |
 
 ## 发现审计目标
 
@@ -144,6 +150,23 @@ csrf xxe sql ssti sandbox redirect upload crypto infoleak
 
 `/omv-find` 应输出带证据的候选结果，包括仓库、注册表身份、维护活跃度、代码规模估计、**source -> sink -> guard** 笔记和下一步本地审计建议。
 
+## 请求可靠性
+
+`/omv-find` 经常要读取公开 registry 元数据、GitHub 元数据、raw 源码文件和源码归档。这些来源可能限流、拒绝、路径不存在或临时不可用。请求密集型研究前，先用 TypeScript request broker 检查来源健康：
+
+```sh
+omv request preflight
+omv request preflight --json --refresh
+omv request fetch https://registry.npmjs.org/markdown-it --json
+omv request fetch https://api.github.com/repos/owner/repo --accept application/json --refresh
+```
+
+broker 会把缓存写入 `.omv/cache/http/`，脱敏响应头，并输出结构化 `failure.reason`、`rateLimit`、`expiresAt` 和 `recommendation`。如果环境里有 `GITHUB_TOKEN` 或 `GH_TOKEN`，GitHub API 请求会自动使用 token。
+
+常见失败分类包括 `rate_limited`、`auth_required`、`bot_blocked_or_forbidden`、`not_found`、`network_timeout`、`network_error`、`upstream_error` 和 `invalid_url`。这些分类应作为研究状态信号：相关字段保持未确认，优先使用 registry/source archive fallback，不要反复重试已经被拒绝的 URL。
+
+完整行为、JSON 字段、缓存策略和 Playwright 评估见 [docs/request-broker.zh-CN.md](docs/request-broker.zh-CN.md)。
+
 ## Evidence 账本
 
 项目本地研究状态保存在 `.omv/findings/`。这些文件默认应视为私有研究记录，不应直接发布。
@@ -218,6 +241,9 @@ omv findings promote demo-traversal --status blocked
 
 | 文档 | 用途 |
 |---|---|
+| [README.md](README.md) | 英文项目指南 |
+| [docs/request-broker.zh-CN.md](docs/request-broker.zh-CN.md) | 请求代理、失败分类、缓存和 Playwright 评估 |
+| [docs/request-broker.md](docs/request-broker.md) | 英文 request broker 指南 |
 | [docs/vulnerability-research-best-practices.zh-CN.md](docs/vulnerability-research-best-practices.zh-CN.md) | 使用本项目做漏洞研究的最佳实践 |
 | [docs/examples/demo-finding-flow.md](docs/examples/demo-finding-flow.md) | 脱敏的端到端 finding 工作流示例 |
 | [docs/roadmap-0.8.md](docs/roadmap-0.8.md) | `v0.8` CLI 改进计划 |

assets/logo-candidates/oh-my-vul-logo-refined-a.png

@@ -85,6 +85,15 @@
 
 候选不是漏洞。只有当 source、sink、guard 和可复现影响都成立时，才可能进入 confirmed。
 
+如果 finder 过程中大量请求被拒绝、限流或超时，先检查请求来源健康：
+
+```sh
+omv request preflight
+omv request fetch https://api.github.com/repos/owner/repo --accept application/json --json
+```
+
+把 `failure.reason`、`rateLimit` 和 `recommendation` 当成研究状态处理。比如 GitHub API `rate_limited` 时，优先使用 registry 元数据、npm/PyPI source archive 或已有缓存，不要反复请求同一个被拒绝的 URL。完整请求代理说明见 [request-broker.zh-CN.md](request-broker.zh-CN.md)。
+
 ## 3. 建立 Evidence 文件
 
 为值得继续审计的候选建立本地证据文件：
@@ -352,6 +361,7 @@ PoC 只是证据之一。还需要版本边界、根因、影响、去重、CVSS
 npx oh-my-vul setup
 omv doctor
 omv dashboard
+omv request preflight
 ```
 
 找目标：

assets/logo-candidates/oh-my-vul-logo-refined-b.png

@@ -25,6 +25,7 @@
     "dist/index.js",
     "registry.yaml",
     "contracts/evidence.v1.yaml",
+    "contracts/candidate-list.v1.yaml",
     "contracts/submission.v1.yaml",
     "contracts/threat-map.v1.yaml",
     "docs/vulnerability-research-best-practices.zh-CN.md",
@@ -39,8 +40,11 @@
     "skills/omv-critic/SKILL.md",
     "shared/scripts/collect_metadata.py",
     "shared/scripts/estimate_loc.sh",
+    "shared/scripts/http_client.py",
     "shared/scripts/resolve_source_path.py",
     "shared/references/patterns/npm.md",
+    "shared/references/research-radar.md",
+    "shared/references/pattern-packs.md",
 }
 
 REQUIRED_PREFIXES = {