feat: add guided first-run experience

Author: bx33661

README.md

@@ -28,33 +28,32 @@ Research state stays in a private `.omv/` workspace. The project is designed for
 
 **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and Node.js 20 or later.
 
-Install the CLI, then add the skills and agents to Claude Code:
+Install the CLI and add the skills and agents to Claude Code:
 
 ```sh
 npm install --global oh-my-vul
 omv setup
 ```
 
-Check the installation:
+From the root of the project you want to research, start a guided workspace:
 
 ```sh
-omv doctor
+omv start
 ```
 
-From the root of the project you want to research, initialize the private workspace and add it to `.gitignore`:
+`omv start` adds `.omv/` to `.gitignore`, detects local project metadata, and asks which vulnerability classes to investigate. To provide the scope non-interactively:
 
 ```sh
-omv workspace init --gitignore
+omv start --vuln xss,auth --no-interactive
 ```
 
 Open that project in Claude Code, then run:
 
 ```text
-/using-omv
 /omv
 ```
 
-`/using-omv` applies the evidence and review gates for the session. `/omv` is the main workspace entry point: it shows the active queue and recommends the next action.
+`/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.
 
 <details>
 <summary><strong>Installation options</strong></summary>
@@ -87,11 +86,11 @@ omv setup --scope project --dry-run
 ## The Workflow
 
 ```text
-/using-omv
-  -> apply evidence-before-claims rules for the session
+omv start
+  -> initialize private state and create the first research campaign
 
 /omv
-  -> start or resume a research campaign
+  -> resume the campaign with evidence-before-claims rules
 
 /omv-find
   -> discover and rank open-source audit targets
@@ -115,8 +114,8 @@ The review gate can send a finding back for more audit, reproduction, deduplicat
 
 | Goal | Command |
 |---|---|
-| Apply the research evidence gates | `/using-omv` |
-| Start, resume, or inspect work | `/omv`, `/omv next` |
+| Start a guided local research workspace | `omv start` |
+| Resume or inspect work with evidence gates | `/omv`, `omv` |
 | Find packages worth auditing | `/omv-find` |
 | Trace data flow and evaluate guards | `/omv-audit <id>` |
 | Guide a local reproduction | `/omv-repro <id>` |

README.zh-CN.md

@@ -28,33 +28,32 @@
 
 **环境要求：** [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、Node.js 20 或更高版本。
 
-全局安装 CLI，再把 skills 和 agents 装入 Claude Code：
+全局安装 CLI，并把 skills 和 agents 装入 Claude Code：
 
 ```sh
 npm install --global oh-my-vul
 omv setup
 ```
 
-检查安装状态：
+进入需要研究的项目根目录，启动引导式工作区：
 
 ```sh
-omv doctor
+omv start
 ```
 
-进入需要研究的项目根目录，初始化私有工作区并写入 `.gitignore`：
+`omv start` 会把 `.omv/` 写入 `.gitignore`、识别本地项目元数据，并询问准备研究的漏洞类型。也可以用非交互方式明确指定：
 
 ```sh
-omv workspace init --gitignore
+omv start --vuln xss,auth --no-interactive
 ```
 
 在该项目中打开 Claude Code，然后输入：
 
 ```text
-/using-omv
 /omv
 ```
 
-`/using-omv` 会启用证据与审查门槛；`/omv` 是工作区统一入口，用来查看正在处理的 finding 和下一步建议。
+`/omv` 会自动启用证据与审查门槛，并显示正在处理的 finding 和下一步建议。在 shell 中直接运行 `omv`，也会打开相同的上下文工作区视图。
 
 <details>
 <summary><strong>其他安装方式</strong></summary>
@@ -87,11 +86,11 @@ omv setup --scope project --dry-run
 ## 使用流程
 
 ```text
-/using-omv
-  -> 为本次研究启用“证据先于结论”的规则
+omv start
+  -> 初始化私有状态并创建第一个研究 Campaign
 
 /omv
-  -> 新建或继续一个研究 Campaign
+  -> 在“证据先于结论”的规则下继续 Campaign
 
 /omv-find
   -> 发现并排序值得审计的开源项目
@@ -115,8 +114,8 @@ omv setup --scope project --dry-run
 
 | 目标 | 命令 |
 |---|---|
-| 启用漏洞研究的证据门槛 | `/using-omv` |
-| 开始、继续或查看研究进度 | `/omv`、`/omv next` |
+| 启动引导式本地研究工作区 | `omv start` |
+| 在证据门槛下继续或查看进度 | `/omv`、`omv` |
 | 发现值得审计的开源包 | `/omv-find` |
 | 跟踪数据流并检查防护 | `/omv-audit <id>` |
 | 引导本地复现 | `/omv-repro <id>` |

skills/omv/SKILL.md

@@ -14,6 +14,7 @@ oh-my-vul local-first vulnerability research project manager for Claude Code.
 ```text
 /omv list                   — list all installed omv-* skills with one-line descriptions
 /omv dashboard              — show workspace, active workflow queue, and recent activity
+/omv start [flags]          — initialize the private workspace and first campaign
 /omv eval                   — run deterministic stable skill eval checks
 /omv first [flags]          — initialize a Campaign.v1 first-mile research plan
 /omv campaign              — list local research campaigns
@@ -78,6 +79,7 @@ When the user invokes campaign, workspace, lifecycle, repro scaffold, artifact c
 Use `omv help`, `omv help review`, `omv help findings`, `omv help repro`, or `omv help report` as the source of truth for exact CLI signatures. For direct aliases:
 
 - `/omv dashboard` -> `omv dashboard`
+- `/omv start ...` -> `omv start ...`
 - `/omv eval ...` -> `omv eval ...`
 - `/omv first ...` -> `omv first ...`
 - `/omv campaign ...` -> `omv campaign ...`
@@ -97,7 +99,7 @@ Use `omv help`, `omv help review`, `omv help findings`, `omv help repro`, or `om
 - `/omv restore <id>` -> `omv findings restore <id>`
 - `/omv findings ...` -> `omv findings ...`
 
-**If `omv` is not found on PATH**, output: "`omv` is not installed. Run: `npx oh-my-vul setup`"
+**If `omv` is not found on PATH**, output: "`omv` is not installed. Run: `npm install --global oh-my-vul && omv setup`"
 
 ### Subcommand reference
 
@@ -134,6 +136,7 @@ Use `omv help`, `omv help review`, `omv help findings`, `omv help repro`, or `om
 ## Workflow Overview
 
 ```
+omv start                      → private workspace + detected target + first campaign
 omv campaign init              → target, scope, priorities, generic lanes
 omv campaign surfaces propose  → attack-surface cards (pack × class)
 omv campaign surfaces select   → choose which hypotheses to pursue

skills/using-omv/SKILL.md

@@ -134,4 +134,4 @@ omv findings validate <id>
 omv review <id> --strict
 ```
 
-If `omv` is missing: `npx oh-my-vul setup` then re-check with `omv doctor`.
+If `omv` is missing: `npm install --global oh-my-vul && omv setup`, then re-check with `omv doctor`.

src/cli/__tests__/args.test.ts

@@ -94,6 +94,7 @@ test("CLI argument validation accepts UX flags and command help", () => {
   assert.equal(validateArgs(["doctor", "--strict"]).ok, true);
   assert.equal(validateArgs(["dashboard"]).ok, true);
   assert.equal(validateArgs(["dashboard", "--json"]).ok, true);
+  assert.equal(validateArgs(["start", "--id", "demo", "--vuln", "xss", "--no-interactive", "--json"]).ok, true);
   assert.equal(validateArgs(["eval"]).ok, true);
   assert.equal(validateArgs(["eval", "--json"]).ok, true);
   assert.equal(validateArgs(["eval", "--junit"]).ok, true);
@@ -113,6 +114,7 @@ test("CLI argument validation accepts UX flags and command help", () => {
   assert.equal(validateArgs(["setup", "--help"]).ok, true);
   assert.equal(validateArgs(["findings", "validate", "--help"]).ok, true);
   assert.equal(validateArgs(["help", "findings", "validate"]).ok, true);
+  assert.equal(validateArgs(["help", "--all"]).ok, true);
 });
 
 test("CLI argument validation enforces eval target and output format rules", () => {

src/cli/__tests__/commands.test.ts

@@ -32,16 +32,42 @@ test("compiled CLI renders help through the command router", () => {
   assert.equal(result.status, 0, result.stderr);
   assert.match(result.stdout, /oh-my-vul/);
   assert.match(result.stdout, /Usage:/);
-  assert.match(result.stdout, /omv findings workflow/);
+  assert.match(result.stdout, /omv start/);
+  assert.doesNotMatch(result.stdout, /omv submissions record/);
 });
 
-test("compiled CLI rejects an unknown command with actionable text and a non-zero exit", () => {
-  const result = runCli(["not-a-command"]);
+test("compiled CLI keeps the exhaustive command reference behind help --all", () => {
+  const result = runCli(["help", "--all"]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /omv submissions record/);
+  assert.match(result.stdout, /workspace init \[--gitignore\]/);
+});
+
+test("bare CLI is read-only before initialization and opens the dashboard afterward", async () => {
+  const projectRoot = await mkdtemp(join(tmpdir(), "omv-commands-entry-"));
+  try {
+    const welcome = runCli([], projectRoot);
+    assert.equal(welcome.status, 0, welcome.stderr);
+    assert.match(welcome.stdout, /omv start/);
+    assert.equal(existsSync(join(projectRoot, ".omv")), false);
+
+    await mkdir(join(projectRoot, ".omv"), { recursive: true });
+    const dashboard = runCli([], projectRoot);
+    assert.equal(dashboard.status, 0, dashboard.stderr);
+    assert.match(dashboard.stdout, /oh-my-vul dashboard/);
+  } finally {
+    await rm(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test("compiled CLI rejects an unknown command with focused suggestions and a non-zero exit", () => {
+  const result = runCli(["find"]);
 
   assert.equal(result.status, 1);
-  assert.match(result.stderr, /Unknown command: not-a-command/);
-  assert.match(result.stderr, /Valid commands:/);
-  assert.match(result.stdout, /Usage:/);
+  assert.match(result.stderr, /Unknown command: find/);
+  assert.match(result.stderr, /Did you mean:/);
+  assert.match(result.stderr, /\/omv-find/);
+  assert.doesNotMatch(result.stdout + result.stderr, /omv submissions record/);
 });
 
 test("dashboard human output uses the canonical workflow columns", async () => {
@@ -53,6 +79,7 @@ test("dashboard human output uses the canonical workflow columns", async () => {
     assert.equal(result.status, 0, result.stderr);
     assert.match(result.stdout, /\bverdict\b/);
     assert.match(result.stdout, /\bblocker\b/);
+    assert.match(result.stdout, /\b(?:CLI|CLAUDE)\b/);
   } finally {
     await rm(projectRoot, { recursive: true, force: true });
   }
@@ -67,12 +94,16 @@ test("dashboard JSON output is one parseable document with stable core fields",
     assert.equal(result.status, 0, result.stderr);
     const output = JSON.parse(result.stdout) as {
       status?: { root?: string; activeCount?: number };
-      workflow?: unknown[];
+      workflow?: Array<{ nextAction: string; action: { surface: string; command: string; reason: string } }>;
+      campaigns?: unknown[];
       activity?: unknown[];
     };
     assert.equal(output.status?.root, await realpath(join(projectRoot, ".omv")));
     assert.equal(output.status?.activeCount, 1);
     assert.equal(Array.isArray(output.workflow), true);
+    assert.equal(Array.isArray(output.campaigns), true);
+    assert.equal(output.workflow?.[0].nextAction, output.workflow?.[0].action.command);
+    assert.match(output.workflow?.[0].action.surface ?? "", /^(?:cli|claude)$/);
     assert.equal(Array.isArray(output.activity), true);
   } finally {
     await rm(projectRoot, { recursive: true, force: true });
@@ -92,6 +123,12 @@ test("compiled CLI runs the canonical Campaign workflow with stable JSON", async
     assert.equal(existsSync(initJson.yamlPath), true);
     assert.equal(existsSync(initJson.runbookPath), true);
 
+    const dashboard = runCli(["dashboard", "--json"], projectRoot);
+    assert.equal(dashboard.status, 0, dashboard.stderr);
+    const dashboardJson = JSON.parse(dashboard.stdout) as { campaigns: Array<{ id: string; nextAction: string }> };
+    assert.equal(dashboardJson.campaigns[0].id, "demo");
+    assert.match(dashboardJson.campaigns[0].nextAction, /^omv campaign/);
+
     const listed = runCli(["campaign", "--json"], projectRoot);
     assert.equal(listed.status, 0, listed.stderr);
     assert.deepEqual((JSON.parse(listed.stdout) as Array<{ id: string }>).map((item) => item.id), ["demo"]);
@@ -132,6 +169,72 @@ test("compiled first alias initializes and JSON never prompts for missing values
   }
 });
 
+test("compiled start detects npm context, initializes privacy state, and preserves campaign collisions", async () => {
+  const projectRoot = await mkdtemp(join(tmpdir(), "omv-commands-start-"));
+  try {
+    await writeFile(join(projectRoot, "package.json"), JSON.stringify({
+      name: "detected-package",
+      version: "1.2.3",
+      repository: { url: "https://example.test/detected-package.git" },
+    }), "utf-8");
+    const started = runCli(["start", "--id", "guided", "--vuln", "xss", "--no-interactive", "--json"], projectRoot);
+    assert.equal(started.status, 0, started.stderr);
+    const result = JSON.parse(started.stdout) as {
+      campaign: { campaign: { id: string; target: { name: string; version: string; ecosystem: string; source: string } } };
+    };
+    assert.deepEqual(result.campaign.campaign.target, {
+      name: "detected-package",
+      version: "1.2.3",
+      ecosystem: "npm",
+      source: "https://example.test/detected-package.git",
+    });
+    assert.equal(await readFile(join(projectRoot, ".gitignore"), "utf-8"), ".omv/\n");
+
+    const collision = runCli(["start", "--id", "guided", "--vuln", "ssrf", "--no-interactive"], projectRoot);
+    assert.equal(collision.status, 1);
+    assert.match(collision.stderr, /already exists/);
+    assert.match(await readFile(join(projectRoot, ".omv", "campaigns", "guided.yaml"), "utf-8"), /xss/);
+  } finally {
+    await rm(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test("compiled start detects non-npm manifests and honors explicit overrides", async () => {
+  const projectRoot = await mkdtemp(join(tmpdir(), "omv-commands-start-go-"));
+  try {
+    await writeFile(join(projectRoot, "go.mod"), "module example.test/demo\n", "utf-8");
+    const detected = runCli(["start", "--id", "go-demo", "--vuln", "ssrf", "--no-interactive", "--json"], projectRoot);
+    assert.equal(detected.status, 0, detected.stderr);
+    assert.equal((JSON.parse(detected.stdout) as { campaign: { campaign: { target: { ecosystem: string } } } }).campaign.campaign.target.ecosystem, "go");
+
+    const overridden = runCli([
+      "start", "--id", "override", "--target", "explicit", "--version", "9.0.0",
+      "--source", "local-source", "--ecosystem", "rust", "--vuln", "path-traversal",
+      "--no-interactive", "--json",
+    ], projectRoot);
+    assert.equal(overridden.status, 0, overridden.stderr);
+    assert.deepEqual(
+      (JSON.parse(overridden.stdout) as { campaign: { campaign: { target: unknown } } }).campaign.campaign.target,
+      { name: "explicit", version: "9.0.0", source: "local-source", ecosystem: "rust" },
+    );
+  } finally {
+    await rm(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test("compiled start never guesses vulnerability classes in non-interactive mode", async () => {
+  const projectRoot = await mkdtemp(join(tmpdir(), "omv-commands-start-missing-"));
+  try {
+    const result = runCli(["start", "--no-interactive", "--json"], projectRoot);
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /missing required fields: vulnerability classes/i);
+    assert.equal(existsSync(join(projectRoot, ".omv")), true);
+    assert.equal(existsSync(join(projectRoot, ".omv", "campaigns", `${projectRoot.split("/").pop()}.yaml`)), false);
+  } finally {
+    await rm(projectRoot, { recursive: true, force: true });
+  }
+});
+
 test("compiled CLI runs the SourceRef and report provenance workflow with stable JSON", async () => {
   const projectRoot = await projectWithFinding();
   try {

src/cli/__tests__/findings.test.ts

@@ -293,13 +293,22 @@ test("finding workflow recommends audit, repro, report, and archive next actions
       ["ready-report", "needs-repro", "needs-audit", "blocked"],
     );
     assert.equal(workflow.find((finding) => finding.id === "needs-audit")?.nextAction, "/omv-audit needs-audit");
+    assert.deepEqual(workflow.find((finding) => finding.id === "needs-audit")?.action, {
+      surface: "claude",
+      command: "/omv-audit needs-audit",
+      reason: "audit evidence still missing",
+    });
     assert.equal(workflow.find((finding) => finding.id === "needs-repro")?.nextAction, "/omv-repro needs-repro");
     assert.equal(workflow.find((finding) => finding.id === "ready-report")?.nextAction, "/omv-report ready-report");
     assert.equal(workflow.find((finding) => finding.id === "ready-report")?.priorityReason, "confirmed finding ready for report");
     assert.equal(
       workflow.find((finding) => finding.id === "blocked")?.nextAction,
       "omv findings archive blocked --reason blocked",
     );
+    assert.equal(workflow.find((finding) => finding.id === "blocked")?.action.surface, "cli");
+    for (const finding of workflow) {
+      assert.equal(finding.nextAction, finding.action.command);
+    }
   } finally {
     await rm(projectRoot, { recursive: true, force: true });
   }