docs: add strategy comparison tables and improve new_user onboarding

README.md

@@ -256,9 +256,12 @@ Reviews are `.deepreview` config files placed anywhere in your project, scoped t
 **Teams own their own rules.** The security team puts a `.deepreview` in `src/auth/`, the platform team in `infrastructure/`, the docs team in `docs/`. Each file is independent and scoped to its directory.
 
 **Smart file grouping.** Three review strategies control what each reviewer sees:
-- **`individual`** — one review per file (best for per-file linting and style checks)
-- **`matches_together`** — all matched files reviewed as a group (best for cross-file consistency)
-- **`all_changed_files`** — a tripwire: if any sensitive file changes, the reviewer sees _every_ changed file in the branch (best for security audits)
+
+| Strategy | Reviewer sees | Best for |
+|----------|--------------|----------|
+| `individual` | One file at a time | Per-file linting, style checks |
+| `matches_together` | All matched files together | Cross-file consistency, migration safety |
+| `all_changed_files` | _Every_ changed file in the branch (tripwire) | Security audits, broad impact analysis |
 
 **Pass caching.** When a review passes, it's marked as clean. It won't re-run until one of its reviewed files actually changes — so reviews stay fast even as your rule set grows.
 

README_REVIEWS.md

@@ -123,6 +123,12 @@ DeepSchema-generated reviews automatically populate `reference_files` from the s
 
 The `strategy` field controls how matched files are grouped into review tasks.
 
+| Strategy | Reviewer sees | Best for |
+|----------|--------------|----------|
+| `individual` | One file at a time | Per-file linting, style checks |
+| `matches_together` | All matched files together | Cross-file consistency, migration safety |
+| `all_changed_files` | _Every_ changed file in the changeset (tripwire) | Security audits, broad impact analysis |
+
 ### `individual` — One review per file
 
 Each changed file that matches the rule gets its own review task. The reviewing agent sees only that one file.

plugins/claude/skills/new_user/SKILL.md

@@ -20,9 +20,19 @@ The DeepWork MCP server requires `uv` (specifically `uvx`). Check if it is insta
 command -v uv
 ```
 
-**If `uv` is NOT found**, install it:
+**If `uv` is NOT found**, install it.
 
-- On macOS/Linux:
+On macOS, warn the user first:
+
+> **Heads up**: when `uv` installs its Python runtime and resolves packages, macOS may pop up permission dialogs for Photos, Dropbox, or other locations outside this project. This happens because the installer briefly scans system paths. These are safe to **deny** — just click "Don't Allow" on any that appear.
+
+Then install `uv`. Check if `brew` is available first (`command -v brew`):
+
+- If `brew` is available:
+  ```bash
+  brew install uv
+  ```
+- Otherwise, on macOS/Linux:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
@@ -31,12 +41,24 @@ command -v uv
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   ```
 
-After installing, verify it works:
+After installing, check if `uv` is on the current PATH:
+
+```bash
+command -v uv
+```
+
+If `uv` is still not found (the installer adds it to shell config but the current shell doesn't have it yet), tell the user:
+
+> `uv` was installed but isn't available in this shell session yet. Please exit Claude (type `/exit`), close this terminal, open a new terminal in the same directory, and run `claude -c` to resume where we left off.
+
+Stop here — do not proceed. The user will come back in a new session.
+
+If `uv` is found, verify it works:
 ```bash
 uv --version
 ```
 
-If `uv` was just installed, set `UV_WAS_INSTALLED=true` (you will need this later).
+Set `UV_WAS_INSTALLED=true` (you will need this later).
 
 #### 0b. Reload if `uv` was just installed
 
@@ -64,12 +86,6 @@ Call `get_workflows` (using the `mcp__plugin_deepwork_deepwork__get_workflows` t
 
 Stop the onboarding if the server is not reachable — continuing without it will just produce more confusing errors.
 
-#### 0e. macOS note (macOS only)
-
-If the platform is macOS, briefly mention:
-
-> **Heads up**: during reviews or workflows that scan files, macOS may pop up permission dialogs for Photos, Dropbox, or other locations outside this project. These are safe to **deny** — DeepWork only needs access to your project directory and the review will still complete fine.
-
 ### 1. GitHub star (optional)
 
 Check if the `gh` CLI is installed by running `which gh`.

src/deepwork/standard_jobs/deepwork_reviews/deepreview_reference.md

@@ -29,9 +29,12 @@ rule_name:
   rules (e.g. `__pycache__/`, `node_modules/`, `.env`) are excluded automatically,
   so they don't need to be listed here.
 - **strategy**: How to batch reviews:
-  - `individual`: One review per matched file
-  - `matches_together`: All matched files reviewed together
-  - `all_changed_files`: All changed files (not just matched ones) reviewed together
+
+  | Strategy | Reviewer sees | Best for |
+  |----------|--------------|----------|
+  | `individual` | One file at a time | Per-file linting, style checks |
+  | `matches_together` | All matched files together | Cross-file consistency, migration safety |
+  | `all_changed_files` | _Every_ changed file (tripwire) | Security audits, broad impact analysis |
 - **additional_context.unchanged_matching_files**: When true, the reviewer gets files
   matching include patterns even if they didn't change in this PR. Critical for
   document freshness checks — lets the reviewer see the doc even when only source