@humanbased/crosscheck 0.15.0-beta.103 → 0.15.0-beta.145

package/get-started.md

@@ -9,8 +9,8 @@
 - [Prerequisites](#prerequisites)
 - [Install](#install)
 - [Environment variables](#environment-variables)
-- [Step 1 — Check your environment](#step-1--check-your-environment)
-- [Step 2 — Test with a single PR](#step-2--test-with-a-single-pr)
+- [Step 1 — Check your setup](#step-1--check-your-setup)
+- [Step 2 — Get one useful review](#step-2--get-one-useful-review)
 - [Step 3 — Choose a deployment mode](#step-3--choose-a-deployment-mode)
 - [Step 4 — Verify it's working](#step-4--verify-its-working)
 - [Commands](#commands)
@@ -34,7 +34,7 @@
 
 ## Prerequisites
 
-You need three CLIs installed and authenticated before crosscheck can run reviews.
+You need GitHub CLI and at least one authenticated AI reviewer CLI before crosscheck can run a one-shot review. Install both Claude Code and Codex only if you want cross-vendor review routing.
 
 ### Claude Code
 
@@ -143,40 +143,50 @@ export CROSSCHECK_WEBHOOK_SECRET=your-secret
 
 ---
 
-## Step 1 — Set up crosscheck
+## Step 1 — Check your setup
 
 ```bash
-crosscheck onboard
+crosscheck status
 ```
 
-`crosscheck onboard` is the recommended first step. It checks your CLIs, walks you through deployment mode, repo selection, review mode, and workflow pipeline, then writes a ready-to-use config — all in one session. See the [`crosscheck onboard`](#crosscheck-onboard) command reference for the full six-step walkthrough.
+`crosscheck status` prints the active config path, GitHub auth source, usable reviewer CLIs, webhook-secret handling, and current logs. A webhook secret is auto-managed for `watch` and `serve`, so it does not need to be set before a one-shot review.
 
-Once it completes, go straight to `crosscheck watch`. There is no separate init step required.
-
-> If you prefer to skip the wizard and configure manually, run `crosscheck init` to generate a starter config, then edit `~/.crosscheck/config.yml` directly.
+If you prefer to create a starter config without the full wizard:
 
----
+```bash
+crosscheck init
+```
 
-## Step 2 — Test with a single PR
+## Step 2 — Get one useful review
 
-Before running continuously, verify end-to-end with one PR:
+Before running continuously, verify end-to-end with one low-risk PR:
 
 ```bash
 crosscheck review https://github.com/owner/repo/pull/123 --reviewer codex
 ```
 
-This clones the PR branch, runs Codex review against the base branch, and posts a comment to the PR. If it completes without error, your setup is working.
-
-Try Claude as reviewer too:
+This clones the PR branch, runs Codex review against the base branch, and posts a comment to the PR. If Claude Code is your authenticated reviewer, use:
 
 ```bash
 crosscheck review https://github.com/owner/repo/pull/123 --reviewer claude
 ```
 
----
+If this step fails, fix the specific auth, clone, reviewer, or comment-posting error before enabling `watch` or `serve`.
 
 ## Step 3 — Choose a deployment mode
 
+After one-shot review works, run the guided setup:
+
+```bash
+crosscheck onboard
+```
+
+`crosscheck onboard` checks your CLIs, walks you through deployment mode, repo selection, review mode, workflow pipeline, and connection settings, then writes a ready-to-use config. See the [`crosscheck onboard`](#crosscheck-onboard) command reference for the full walkthrough.
+
+Once it completes, go straight to `crosscheck watch`. There is no separate init step required.
+
+> If you prefer to skip the wizard and configure manually, run `crosscheck init` to generate a starter config, then edit `~/.crosscheck/config.yml` directly.
+
 ### Personal vs team
 
 On first run, `crosscheck watch` (or `crosscheck serve`) will ask how you're using it:
@@ -344,7 +354,7 @@ crosscheck init
 crosscheck init --config /path/to/crosscheck.config.yml
 ```
 
-What it checks: `codex` CLI, `claude` CLI, `gh` CLI, `GITHUB_TOKEN`, `CROSSCHECK_WEBHOOK_SECRET`.
+What it checks: `codex` CLI, `claude` CLI, `gh` CLI, GitHub auth, and webhook-secret handling. The webhook secret is auto-managed at `~/.crosscheck/webhook-secret` for `watch` and `serve`.
 
 | Flag | Description |
 |---|---|
@@ -354,7 +364,7 @@ What it checks: `codex` CLI, `claude` CLI, `gh` CLI, `GITHUB_TOKEN`, `CROSSCHECK
 
 ### `crosscheck onboard`
 
-The recommended first-time setup command. Walks through seven steps interactively and writes a ready-to-use config.
+The recommended first-time setup command. Walks through ten steps interactively and writes a ready-to-use config.
 
 ```bash
 crosscheck onboard
@@ -364,7 +374,7 @@ crosscheck onboard --team         # force team mode for this session
 crosscheck onboard --reconfigure  # re-run setup even if config already exists
 ```
 
-**The seven steps:**
+**The ten steps:**
 
 **Step 1 — Environment check.** Verifies codex CLI, claude CLI, gh CLI, and GitHub token. At least one AI CLI must be authenticated; gh auth is always required. Prints ✓/✗ with fix hints.
 
@@ -378,7 +388,11 @@ crosscheck onboard --reconfigure  # re-run setup even if config already exists
 - `cross-vendor` — Claude reviews Codex PRs; Codex reviews Claude PRs (recommended when using both agents)
 - `single-vendor` — one AI reviews all PRs (default when only one CLI is installed)
 
-**Step 5 — Workflow pipeline.** Choose what happens after a review:
+**Step 5 — Primary author.** In personal cross-vendor mode, choose which agent usually authors your PRs so Crosscheck can route reviews to the other vendor.
+
+**Step 6 — Review quality.** Choose the speed/thoroughness tier for review prompts and reviewer timeouts.
+
+**Step 7 — Workflow pipeline.** Choose what happens after a review:
 
 ```
   [1] review only              — AI posts a comment; you handle fixes
@@ -388,11 +402,17 @@ crosscheck onboard --reconfigure  # re-run setup even if config already exists
 
 The `review → fix → re-check` option writes a `~/.crosscheck/workflow.yml` with all three pipeline steps configured.
 
-**Step 6 — Connection type.** Choose how GitHub webhooks reach your local server:
+**Step 8 — Fix -> recheck rounds.** When the full loop is selected, choose how many fix/recheck rounds Crosscheck can run before stopping.
+
+**Step 9 — Auto conflict-resolve.** Optionally add a merge-conflict resolution step before review.
+
+**Step 10 — Connection type.** Choose how GitHub webhooks reach your local server:
 - `localhost.run` — zero-config SSH tunnel; reconnects automatically, no install required *(default)*
 - `smee.io` — webhook relay; events queued while offline, stable channel URL (requires `npm install -g smee-client` and `tunnel.smee_channel` in config)
 
-**Step 7 — Review and write config.** Shows a summary of all choices and writes `~/.crosscheck/config.yml` (and `workflow.yml` if re-check was selected).
+**Step 11 — Git clone protocol.** Choose SSH or HTTPS for PR checkout.
+
+**Step 12 — Review and write config.** Shows a summary of all choices and writes `~/.crosscheck/config.yml` and `~/.crosscheck/workflow.yml`.
 
 ```
 crosscheck onboard
@@ -417,21 +437,45 @@ crosscheck onboard
   [1] cross-vendor  [2] single-vendor
   Choice [1]: 1
 
-  Step 5 — workflow pipeline
+  Step 5 — primary author
+  [1] Claude  [2] Codex  [3] both
+  Choice [3]: 3
+
+  Step 6 — review quality
+  [1] fast  [2] balanced  [3] thorough
+  Choice [2]: 2
+
+  Step 7 — workflow pipeline
   [1] review only  [2] review → fix  [3] review → fix → re-check
   Choice [2]: 3
 
-  Step 6 — connection type
+  Step 8 — fix → re-check rounds
+  [1] 1 round  [2] 2 rounds  [3] 3 rounds
+  Choice [1]: 1
+
+  Step 9 — auto conflict-resolve
+  [1] disabled  [2] enabled
+  Choice [1]: 1
+
+  Step 10 — connection type
   [1] localhost.run  [2] smee.io
   Choice [1]: 1
 
-  Step 7 — review and write config
+  Step 11 — git clone protocol
+  [1] SSH  [2] HTTPS
+  Choice [1]: 1
+
+  Step 12 — review and write config
   deployment   personal
   connection   localhost.run
+  clone        ssh
   orgs         humanbased-ai
   users        your-github-login (8 repos)
   mode         cross-vendor
+  quality      balanced
   pipeline     review-fix-recheck
+  max rounds   1
+  conflict-resolve  no
   config       ~/.crosscheck/config.yml
 
   ✓ config written to ~/.crosscheck/config.yml
@@ -484,7 +528,7 @@ crosscheck run https://github.com/owner/repo/pull/123 --crazy   # loop until APP
 crosscheck run https://github.com/owner/repo/pull/123 --halfcrazy
 ```
 
-The workflow executed is loaded from `.crosscheck/workflow.yml` in the repo root (if present) or falls back to the built-in default pipeline (review only). Use `crosscheck run` to test your full pipeline end-to-end against a real PR.
+The workflow executed is loaded from `.crosscheck/workflow.yml` in the operator repo root if present, then `~/.crosscheck/workflow.yml`, and otherwise falls back to the built-in default pipeline: review, then fix when the verdict is not `APPROVE`. Use `crosscheck run` to test your full pipeline end-to-end against a real PR.
 
 | Flag | Description |
 |---|---|
@@ -575,7 +619,7 @@ crosscheck watch
 - A posted review fires an `issue_comment` webhook → `watch` starts the fix step.
 - A fix commit fires a `synchronize` webhook → `watch` starts the recheck step.
 
-No second `kickass` run is needed. Once `kickass` kicks the first step, the pipeline advances on its own as long as `watch` is running. (Introduced in [#193](https://github.com/humanbased-ai/crosscheck/pull/193).)
+No second `kickass` run is needed. Once `kickass` kicks the first step, the pipeline advances on its own as long as `watch` is running. (Introduced in [#193](https://github.com/Motivation-Labs/crosscheck/pull/193).)
 
 ---
 
@@ -890,6 +934,8 @@ crosscheck stores its config in `~/.crosscheck/config.yml` by default — persis
 2. `./crosscheck.config.yml`
 3. `./.crosscheck.yml`
 
+If `~/.crosscheck/config.yml` exists, it wins over local project files. Pass `--config ./crosscheck.config.yml` when you deliberately want to test a project-local config.
+
 Run `crosscheck init` to generate `~/.crosscheck/config.yml` with all options documented.
 
 Logs are written to `~/.crosscheck/logs/YYYY-MM-DD.ndjson` and retained for 30 days by default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanbased/crosscheck",
-  "version": "0.15.0-beta.103",
+  "version": "0.15.0-beta.145",
   "description": "AI code review pipeline that turns agent-written PRs into merge-ready patches",
   "bin": {
     "crosscheck": "dist/cli.js",
@@ -16,6 +16,8 @@
     "README.zh.md",
     "get-started.md",
     "get-started.zh.md",
+    "docs/fixture-pr.md",
+    "docs/proof-demo.md",
     "assets"
   ],
   "engines": {
@@ -70,6 +72,6 @@
   "bugs": {
     "url": "https://github.com/humanbased-ai/crosscheck/issues"
   },
-  "author": "HumanBased AI",
+  "author": "Humanbased PTE LTD",
   "license": "MIT"
 }