README: rewrite around the v0.2.x flow

The README was written before workspace separation, suggest-roles, JSON
sidecar emission, config auto-pickup, and --assume-untagged shipped. The
quickstart section in particular described an outdated three-step flow
that didn't reflect what the tool actually does today.

Restructured to walk users through the real flow:

1. Workspace setup (once): `init-judge` installs both bundled subagents.
2. Configure roles (once per target): `suggest-roles --apply` writes
   directly into the workspace's ai_dev.yaml.
3. Run analyses (every time): `analyze TARGET --judge claude-cli`.
   Config auto-loads, JSON sidecar auto-emits.
4. Handle missing trailers via `--assume-untagged`.

Other additions:

- Full CLI reference table (every command + every analyze flag) so users
  can find the right knob without spelunking through --help output.
- JSON output structure section documenting the schema for downstream
  consumers (Claude Cowork report generators, custom dashboards).
- Optional providers section noting that anthropic-api/openai/ollama are
  stubbed at v0.2.
- Updated workspace layout diagram to show the new files
  (roles-architect.md, ai_dev.yaml.bak from --apply, etc.).

No code changes. Verified all relative links in the README still resolve.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: denn-gubsky

README.md

@@ -2,107 +2,174 @@
 
 > Measure how much AI co-programming actually accelerates software delivery — on any git repo.
 
-`ai-dev-effectiveness` reads your git history, detects which commits were co-authored by AI coding agents (Claude, Copilot, Cursor, Codex, Aider, …), and produces an interactive HTML report comparing your real delivery against a hypothetical traditional team. It triangulates three independent estimators — top-down specialist roles, bottom-up per-commit formulas, and an AI-judge that reads each diff — so the productivity multipliers are credible, not just plausible.
+`ai-dev-effectiveness` reads your git history, detects which commits were co-authored by AI coding agents (Claude, Copilot, Cursor, Codex, Aider, …), and produces an interactive HTML report (and a structured JSON sidecar) comparing your real delivery against a hypothetical traditional team. It triangulates three independent estimators — top-down specialist roles, bottom-up per-commit formulas, and an AI judge that reads each diff — so the productivity multipliers are credible, not just plausible.
 
 ## Quickstart
 
 ```bash
+# Install (macOS):
+brew install pipx && pipx ensurepath
 pipx install git+https://github.com/denn-gubsky/ai-dev-effectiveness
 
-# Pick a folder you'll run analyses from. NOT one of your project repos.
+# Pick a folder DEDICATED to running analyses — NOT one of your project repos.
 mkdir -p ~/dev-effectiveness && cd ~/dev-effectiveness
 
-# Once: install the bundled judge subagent into THIS workspace.
+# One-time: install the bundled subagents (effort-judge + roles-architect).
 ai-dev-effectiveness init-judge
 
-# Now analyze any repo you want. Reports go to ./<target_basename>/.
-ai-dev-effectiveness analyze /path/to/your/repo
+# One-time per target: have Claude survey the repo and propose specialist roles.
+ai-dev-effectiveness suggest-roles ~/work/your-repo --apply
+
+# Every run: just go. Config auto-loads, JSON sidecar emits by default.
+ai-dev-effectiveness analyze ~/work/your-repo --judge claude-cli
 open ./your-repo/effectiveness-report.html
 ```
 
-The analyzer **never writes inside the target repo** — the bundled subagent, the judgment cache, and all reports live in your local workspace. Each target gets its own subfolder so you can compare repos side by side.
+That's the full happy-path. Each step is explained below.
+
+The analyzer **never writes inside the target repo** — bundled subagents, the judgment cache, and all reports live in your workspace. Each target gets its own subfolder so you can compare repos side by side.
 
 ## What it measures
 
-Three independent productivity multipliers:
+Three independent productivity multipliers triangulating the same question:
 
 1. **Top-down** — what would a traditional specialist team need? Person-months by role.
 2. **Bottom-up** — per-commit effort using language-weighted formulas (base hours + per-LOC rate).
 3. **AI judge** — Claude reads each diff and emits a calibrated estimate via the bundled subagent.
 
-When all three agree within 2x, the multiplier is defensible. When they diverge, the report flags it.
+When all three agree within 2×, the multiplier is defensible. When they diverge, the report flags it.
+
+## End-to-end flow
+
+### 1. Workspace setup (once)
+
+```bash
+mkdir -p ~/dev-effectiveness && cd ~/dev-effectiveness
+ai-dev-effectiveness init-judge
+```
+
+This installs both bundled subagents into `~/dev-effectiveness/.claude/agents/` (`effort-judge` for the per-commit AI judge, `roles-architect` for proposing specialist roles) plus a `settings.recommended.json` with the optional [ast-index](https://github.com/defendend/Claude-ast-index-search) MCP snippet.
+
+### 2. Configure roles for each target (once per repo)
+
+```bash
+ai-dev-effectiveness suggest-roles ~/work/your-repo --apply
+```
+
+The `roles-architect` subagent surveys your codebase, identifies natural domain clusters, and writes calibrated specialist roles directly into `~/dev-effectiveness/ai_dev.yaml`. Takes 60–180 seconds, uses your existing Claude subscription, no diffs leave your machine. The original config (if any) is backed up as `ai_dev.yaml.bak`.
+
+If you'd rather inspect the YAML before applying, drop `--apply` to print to stdout, or use `--out roles.yaml` to write to a file.
+
+You can also write roles by hand — see [Configuring specialist roles](#configuring-specialist-roles) below.
+
+### 3. Run analyses (every time)
 
-## Optional: AI judge for diff-aware estimates
+```bash
+ai-dev-effectiveness analyze ~/work/your-repo --judge claude-cli
+```
+
+What happens:
+
+- **Workspace config auto-pickup** — `<workspace>/ai_dev.yaml` is loaded automatically; you only need `--config` for non-standard paths.
+- **`ast-index rebuild`** runs against the target if `ast-index` is on `PATH`.
+- **Stratified sampling** of ~30–50 commits across (domain × size_bucket) for the judge.
+- **Reports written** to `<workspace>/<target_basename>/`:
+  - `effectiveness-report.html` — interactive Plotly dashboard
+  - `effectiveness-report.json` — structured AI-readable analysis
+
+The JSON contains everything needed for downstream report generation (Claude Cowork, custom dashboards, etc.) — three estimators side-by-side, cost comparison, per-agent / per-author / per-domain / per-package breakdowns, and an audit sample of judge rationales.
+
+### 4. When trailers are missing
+
+Real-world git histories often under-report AI assistance — GitHub squash-merges strip Co-Authored-By trailers, and some workflows commit without invoking the AI tool's commit flow. If you know your project was AI-paired but trailer detection looks too low:
 
 ```bash
-cd ~/dev-effectiveness          # the workspace where init-judge ran
-ai-dev-effectiveness analyze /path/to/your/repo --judge claude-cli
+ai-dev-effectiveness analyze ~/work/your-repo \
+    --assume-untagged "Claude Opus" \
+    --judge claude-cli
 ```
 
-The judge uses your existing Claude Code CLI session — no API key, no metered billing, no diffs leaving your machine. If you have [ast-index](https://github.com/defendend/Claude-ast-index-search) on your `PATH`, the analyzer runs `ast-index rebuild` against the target before the judge starts so the bundled subagent can use `mcp__ast-index__*` tools for symbol-level lookups (much faster than grep-then-read for "find callers of this function").
+Every untagged non-merge commit gets attributed to the named agent. Merge commits stay un-attributed (they don't represent direct authorship). Persist the choice in `ai_dev.yaml`:
 
-Other providers (opt-in): `--judge anthropic-api` (separate API key), `--judge openai`, `--judge ollama` (local model).
+```yaml
+agents:
+  assume_untagged: "Claude Opus"
+```
 
-Disable ast-index for a run: `--no-ast-index`.
+Run `ai-dev-effectiveness list-agents` to see valid agent names.
 
 ## Workspace layout
 
 ```
 ~/dev-effectiveness/                      # your analyzer workspace
 ├── .claude/
-│   ├── agents/effort-judge.md           # ← installed by `init-judge`
+│   ├── agents/effort-judge.md           # bundled by init-judge
+│   ├── agents/roles-architect.md
 │   ├── skills/effort-estimation/SKILL.md
 │   └── settings.recommended.json
-├── ai_dev.yaml                          # optional: custom config (init-config)
-├── repo-a/                              # output for one analyzed target
+├── ai_dev.yaml                          # auto-loaded by `analyze`
+├── ai_dev.yaml.bak                      # written by `suggest-roles --apply`
+├── your-repo/
 │   ├── effectiveness-report.html
-│   ├── effectiveness-report.json
-│   └── .ai-dev-effectiveness-cache/
-└── repo-b/                              # another target's outputs
+│   ├── effectiveness-report.json        # auto-emitted by default
+│   └── .ai-dev-effectiveness-cache/     # location-stable judge cache
+└── another-repo/
     └── ...
 ```
 
-Useful flags:
+## CLI reference
 
-- `--workspace PATH` — override the analyzer workspace (default: `$PWD`).
-- `--out-dir PATH` — override where this run's reports go.
-- `--judge-dry-run` — show what the judge would do (sample size, cost, paths) without invoking it.
+| Command | Purpose |
+|---|---|
+| `init-judge [WORKSPACE]` | Install bundled subagents into workspace's `.claude/`. |
+| `init-config [--out PATH]` | Drop a starter `ai_dev.yaml` template. |
+| `suggest-roles TARGET [--apply]` | Survey TARGET and propose specialist roles. With `--apply`, write directly into workspace's `ai_dev.yaml`. |
+| `list-agents` | Print the built-in AI-agent signature registry. |
+| `validate-config FILE` | Schema-check an `ai_dev.yaml` without running. |
+| `analyze TARGET [flags]` | Run the analysis. |
 
-## Case study
+Useful `analyze` flags:
+
+| Flag | Effect |
+|---|---|
+| `--judge claude-cli` | Enable the AI judge using your Claude subscription. |
+| `--judge-dry-run` | Show what the judge would do (sample size, paths) without running it. |
+| `--judge-all` | Judge every commit instead of stratified sampling. |
+| `--assume-untagged "Claude Opus"` | Attribute untagged non-merge commits to a named agent. |
+| `--workspace PATH` | Override the workspace (default `$PWD`). |
+| `--out-dir PATH` | Override report destination (cache stays at the default location). |
+| `--format html\|json\|both` | Output formats. Default `both` writes HTML + JSON. |
+| `--no-ast-index` | Skip the `ast-index rebuild` step. |
+| `--config FILE` | Use a non-standard config path (otherwise auto-picked). |
+
+## Optional providers
 
-[`examples/robotics-case-study/`](examples/robotics-case-study/) — anonymized analysis of a real 117K-LOC robotics project built by 1 dev + Claude over 10 months. Use it to see what a credible report looks like and to calibrate your own results.
+The default AI judge uses your Claude Code CLI subscription (no API key, no metered billing, no diffs leaving your machine). Other providers exist for users who'd rather pay metered:
 
-## Customize
+- `--judge anthropic-api` — uses `ANTHROPIC_API_KEY` env var
+- `--judge openai` — uses `OPENAI_API_KEY` env var
+- `--judge ollama` — local model via Ollama (privacy-preserving)
+- `--judge stub` — deterministic, used in CI tests
 
-- `ai-dev-effectiveness init-config` — drops `ai_dev.yaml` into your workspace.
-- Define your specialist roles, effort constants, agent signatures.
+The `anthropic-api`, `openai`, and `ollama` providers are stubbed at v0.2 and will ship in a follow-up release.
+
+## Case study
+
+[`examples/robotics-case-study/`](examples/robotics-case-study/) — anonymized analysis of a real 117K-LOC ROS2 robotics project built by 1 dev + Claude over 10 months. Use it to see what a credible report looks like and to calibrate your own results.
 
 ## Configuring specialist roles
 
-The top-down half of the analysis answers "what would a traditional team need?"
-by summing your declared specialist roles. Without roles, the report skips the
-top-down chart and the three-way reconciliation falls to two-way (formula +
-judge only). Adding even three or four roles makes the comparison defensible.
+The top-down half of the analysis answers "what would a traditional team need?" by summing your declared specialist roles. Without roles, the top-down chart is skipped and the three-way reconciliation falls to two-way (bottom-up + judge only).
 
-### Option A — let Claude propose the roles
+### Option A — let Claude propose them
 
 ```bash
-cd ~/dev-effectiveness
-ai-dev-effectiveness suggest-roles /path/to/your/repo
+ai-dev-effectiveness suggest-roles ~/work/your-repo --apply
 ```
 
-Surveys the target codebase via a bundled Claude Code subagent
-(`roles-architect`), identifies natural domain clusters, and prints a YAML
-snippet ready to paste under your `ai_dev.yaml` `roles:` key. Uses your
-existing Claude subscription (no API key, no diffs leaving your machine).
-Takes 60-180 seconds. Edit the result freely — the agent provides a starting
-point grounded in your actual file layout, not the final word.
-
-### Option B — write the roles yourself
+Writes roles directly into your workspace's `ai_dev.yaml`. Drop `--apply` to print to stdout for inspection first.
 
-Each role describes the slice of the codebase one specialist would own and
-how many person-months a senior engineer (working without AI assistance)
-would need to deliver it. Schema:
+### Option B — write them by hand
 
 ```yaml
 roles:
@@ -123,23 +190,42 @@ How to estimate `pm_low` / `pm_high`:
 | Glue / config / IaC                       | 20-30              |
 | ML training / distributed systems         | 15-25 (incl. ramp) |
 
-`pm = loc / (rate_per_day * 22 days_per_month)`. Use the lower rate for
-`pm_high`, the higher rate for `pm_low`. The notebook averages the range to
-produce the headline multiplier — wider spread = more uncertainty.
-
-### A worked example
+`pm = loc / (rate_per_day × 22 working_days_per_month)`. Use the lower rate for `pm_high`, the higher rate for `pm_low`. The tool averages the range — wider spread = more uncertainty.
+
+[`examples/robotics-case-study/ai_dev.yaml`](examples/robotics-case-study/ai_dev.yaml) is a worked example covering a multi-domain ROS2 / CUDA / ML project.
+
+## JSON output structure
+
+```jsonc
+{
+  "tool": "ai-dev-effectiveness",
+  "version": "0.2.0",
+  "generated_at": "2026-05-05T...",
+  "project": { "name": "...", "team_size": 1, ... },
+  "headline": { "n_commits": 68, "n_ai_assisted": 56, "loc_total": 22277, ... },
+  "estimators": {
+    "top_down":  { "roles": [...], "total_pm_mid": 23, "multiplier": 230 },
+    "bottom_up": { "total_traditional_hours": 863, "multiplier": 10.8 },
+    "judge":     { "total_human_hours": ..., "multiplier": 2.13, ... }
+  },
+  "cost_comparison": { "traditional_cost_usd": 404800, "savings_multiplier": 227 },
+  "by_agent":    [...],
+  "by_author":   [...],
+  "by_domain":   [...],
+  "by_package":  [...],
+  "by_complexity": [...],
+  "author_agent_matrix": [...],
+  "judge_samples": [...],   // up to 15 judged commits with rationale
+  "weekly":      [...]
+}
+```
 
-[`examples/robotics-case-study/ai_dev.yaml`](examples/robotics-case-study/ai_dev.yaml)
-is the actual config used to produce the case-study report — six roles
-covering a multi-domain ROS2 / CUDA / ML / depth-vision project. Use it as a
-template if your project has similar shape; otherwise let `suggest-roles`
-generate one tailored to your codebase.
+Every section a Claude Cowork report generator (or your own dashboard) needs to author a credible productivity narrative.
 
 ## Documentation
 
-- [`docs/REPRODUCTION_GUIDE.md`](docs/REPRODUCTION_GUIDE.md) — full step-by-step
-  walkthrough (legacy from the original notebook, covers manual notebook usage).
-- [`docs/config-reference.md`](docs/config-reference.md) — every YAML field documented.
+- [`docs/REPRODUCTION_GUIDE.md`](docs/REPRODUCTION_GUIDE.md) — full first-run walkthrough including troubleshooting.
+- [`docs/config-reference.md`](docs/config-reference.md) — every YAML field documented with type, default, and meaning.
 
 ## License