@better-vibe/branch-narrator 1.0.0 → 1.2.1

package/README.md

@@ -1,95 +1,250 @@
 # branch-narrator
 
-A local-first CLI that reads `git diff` and generates structured **PR descriptions** (Markdown) and **machine-readable facts** (JSON).
+[![npm version](https://img.shields.io/npm/v/@better-vibe/branch-narrator)](https://www.npmjs.com/package/@better-vibe/branch-narrator)
+[![CI](https://github.com/@better-vibe/branch-narrator/actions/workflows/ci.yml/badge.svg)](https://github.com/@better-vibe/branch-narrator/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-## Features
+A local-first, deterministic CLI that analyzes `git diff` and provides
+structured context for AI coding agents and human code review.
 
-- **Heuristics-only**: No LLM calls, no network calls. Fully deterministic and grounded in git diff.
-- **Agent-grade reliability**: JSON outputs are deterministic, parseable, and pipe-safe (e.g., `branch-narrator facts | jq .`). Global `--quiet` and `--debug` flags control diagnostics.
-- **Risk Analysis**: Framework-agnostic security and quality risk scoring (0-100) with evidence-backed flags.
-- **SvelteKit-aware**: Detects routes, layouts, endpoints, and HTTP methods.
-- **React Router support**: Detects route changes in React apps (JSX `<Route>` and data routers like `createBrowserRouter`).
-- **Supabase integration**: Scans migrations for destructive SQL patterns.
-- **Environment variable detection**: Finds `process.env`, SvelteKit `$env` imports, Vite `import.meta.env`, React App `REACT_APP_*`, and Next.js `NEXT_PUBLIC_*`.
-- **Cloudflare detection**: Detects wrangler config and CI changes.
-- **Dependency analysis**: Tracks package.json changes with semver impact.
-- **CI/CD security**: Detects workflow permission changes, pull_request_target, remote script execution.
-- **Infrastructure changes**: Tracks Dockerfile, Terraform, and Kubernetes manifest changes.
-
-## Installation
+## Quick Start
 
 ```bash
-bun add -D branch-narrator
+# Install as dev dependency (recommended)
+bun add -D @better-vibe/branch-narrator
 # or
-npm install -D branch-narrator
+npm install -D @better-vibe/branch-narrator
+
+# Or install globally
+npm install -g @better-vibe/branch-narrator
+
+# Or run without installing
+npx @better-vibe/branch-narrator facts --pretty
 ```
 
-## Common Use Cases
+### Common Commands
 
-### For AI Agents
-Agents need grounded, hallucination-free context to work effectively. `branch-narrator` provides the "ground truth" of what actually changed in the codebase.
-- **Context Gathering**: Use `facts` to get a structured JSON summary of changes (routes, dependencies, risks) to understand the "what" before generating code.
-- **Diff Understanding**: Use `dump-diff` to get a clean, token-optimized git diff that handles exclusions smartly (ignoring lockfiles, minified files, etc.).
-- **Self-Verification**: Use `zoom` to verify specific findings or check if a requested change (e.g., "add a route") was actually implemented correctly.
+```bash
+# Generate a PR description for current changes
+branch-narrator pr-body
 
-### For Developers
-Streamline your daily workflow without context switching.
-- **Fast Code Review**: Run `branch-narrator pretty` to see a high-level summary of your uncommitted changes in the terminal.
-- **PR Descriptions**: Generate a consistent, comprehensive PR description with `branch-narrator pr-body` and pipe it directly to `gh pr create` or your clipboard.
+# Structured JSON facts for automation
+branch-narrator facts --pretty
 
-### For CI/CD Pipelines
-Automate quality and security checks.
-- **Risk Gating**: Use `branch-narrator risk-report --fail-on-score 60` in your CI pipeline to automatically block merges that introduce high-risk changes (like destructive migrations or dangerous permissions) until they are reviewed.
+# Risk report for review
+branch-narrator risk-report --format md
 
-## Usage
+# Prompt-ready diff with smart filtering
+branch-narrator dump-diff --out .ai/diff.txt
 
-### Global Flags
+# Save workspace snapshot for agent iteration
+branch-narrator snap save "before-refactor"
 
-All commands support the following global flags:
+# SARIF output for GitHub Code Scanning
+branch-narrator facts --format sarif --out results.sarif
 
-```bash
-# Suppress non-fatal diagnostic output (warnings, info messages)
-branch-narrator --quiet facts
+# Compare changes since last run (delta mode)
+branch-narrator facts --since .ai/baseline.json
+```
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Why branch-narrator](#why-branch-narrator)
+- [Key Capabilities](#key-capabilities)
+- [Documentation](#documentation)
+- [CLI Reference](#cli-reference)
+- [CI/CD Integration](#cicd-integration)
+- [Programmatic API](#programmatic-api)
+- [Example Output](#example-output)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Requirements](#requirements)
+- [License](#license)
+
+## Why branch-narrator
+
+- Deterministic and offline: no LLMs, no network calls.
+- Evidence-based output: summaries and risk flags are tied to diff evidence.
+- Profile-aware analysis across frameworks and libraries.
+- Output for humans (Markdown) and automation (JSON/SARIF).
+
+## Key Capabilities
+
+### Output Formats
+- **Markdown PR descriptions** (`pr-body`) with consistent sections.
+- **JSON facts** (`facts`) for pipelines and automation.
+- **Prompt-ready diffs** (`dump-diff`) with smart filtering for AI context windows.
+- **SARIF output** (`--format sarif`) for GitHub Code Scanning integration.
+- **Risk scoring** (`risk-report`) with evidence-backed flags and categories.
+- **Workspace snapshots** (`snap`) for saving and comparing workspace state.
+
+### Analysis Features
+- Route and API change detection for SvelteKit, Next.js App Router, React Router,
+  Vue/Nuxt, and Astro.
+- Dependency and package surface analysis (semver impact, exports, lockfile
+  mismatches).
+- Environment variables, security-sensitive files, CI workflows, and
+  infrastructure changes.
+- Migration safety checks (Supabase migrations and SQL risk patterns).
+
+### Agent Workflows
+- **Delta mode** (`--since`) for comparing runs and tracking changes over time.
+- **Stable IDs** for deterministic finding/flag references across runs.
+- **Snapshot workflows** (`snap`) for saving and restoring workspace state.
+- **Drill-down** (`zoom`) for detailed context on specific findings or flags.
+- **AI assistant integration** (`integrate`) to generate provider rules for
+  Cursor, Claude, Jules, and OpenCode.
+
+## Documentation
+
+Start with the docs index: [`docs/README.md`](docs/README.md). The `docs/`
+folder is the source of truth for detailed technical documentation.
+
+Key sections:
+
+- Product overview and roadmap: [`docs/01-product/`](docs/01-product/)
+- CLI commands and options: [`docs/05-cli/`](docs/05-cli/)
+- Analyzer catalog: [`docs/03-analyzers/`](docs/03-analyzers/)
+- Profiles and detection: [`docs/07-profiles/`](docs/07-profiles/)
+- Rendering formats and risk scoring: [`docs/08-rendering/`](docs/08-rendering/)
+- Stable IDs and traceability: [`docs/09-stable-ids/`](docs/09-stable-ids/)
+- Snapshots: [`docs/10-snapshots/`](docs/10-snapshots/)
+- Delta mode: [`docs/11-delta-mode/`](docs/11-delta-mode/)
+- Development guides: [`docs/06-development/`](docs/06-development/)
+
+See [`CHANGELOG.md`](CHANGELOG.md) for version history and release notes.
+
+## CLI Reference
+
+### Global behavior
+
+- JSON outputs (`facts`, `risk-report --format json`, `dump-diff --format json`)
+  write diagnostics to stderr so stdout is parse-safe.
+- `--quiet` suppresses non-fatal diagnostics; `--debug` enables timing and
+  detector logs.
+- `DEBUG=1` prints stack traces for debugging.
+
+### Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--quiet` | Suppress non-fatal diagnostics (warnings, info) |
+| `--debug` | Print debug diagnostics to stderr |
+
+### Diff modes
+
+| Mode | Description | Git Command |
+|------|-------------|-------------|
+| `unstaged` | Working tree vs index + untracked files (default) | `git diff` + `git ls-files --others` |
+| `branch` | Compare base ref to head ref | `git diff base..head` |
+| `staged` | Index vs HEAD (staged changes) | `git diff --staged` |
+| `all` | All changes vs HEAD (staged + unstaged + untracked) | `git diff HEAD` + `git ls-files --others` |
+
+### Profiles
+
+Use `--profile <name>` to override auto-detection.
+
+| Profile | Description | Auto-detect signals |
+|---------|-------------|--------------------|
+| `auto` | Default profile selection | Framework detection fallback |
+| `sveltekit` | SvelteKit fullstack apps | `src/routes/` or `@sveltejs/kit` |
+| `next` | Next.js App Router apps | `next` dependency + `app/` or `src/app/` |
+| `react` | React apps using React Router | `react` + `react-router` |
+| `vue` | Vue/Nuxt apps | `nuxt` or `vue` + `pages/` |
+| `astro` | Astro projects | `astro` dependency or `astro.config.*` |
+| `stencil` | StencilJS projects | `@stencil/core` or `stencil.config.*` |
+| `library` | npm packages/libraries | `exports`, `publishConfig`, `bin`, `private: false` |
 
-# Show debug diagnostics on stderr (timings, detector counts, etc.)
-branch-narrator --debug risk-report
+### Commands
 
-# Combine flags (--quiet overrides --debug)
-branch-narrator --quiet --debug facts
+#### pretty
+
+Display a colorized summary of changes in the terminal.
+
+```bash
+branch-narrator pretty [options]
 ```
 
-**Note:** In JSON mode (`facts`, `risk-report --format json`, `dump-diff --format json`), all diagnostic output goes to stderr to ensure stdout contains only valid JSON. This makes the output safe for piping to `jq` or other JSON parsers.
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
+| `--base <ref>` | auto-detected | Base git reference (branch mode only) |
+| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
+| `--profile <name>` | `auto` | Profile: `auto`, `sveltekit`, `next`, `react`, `vue`, `astro`, `stencil`, `library` |
 
-### Preview Changes (for Humans)
+Examples:
 
 ```bash
-# Colorized summary of unstaged changes (default)
+# Review unstaged changes (default)
 branch-narrator pretty
 
-# Compare specific branches
+# Compare branches
 branch-narrator pretty --mode branch --base develop --head feature/auth
 
-# Review all uncommitted changes (staged + unstaged + untracked)
+# Review all uncommitted changes
 branch-narrator pretty --mode all
 ```
 
-### Generate PR Description
+#### pr-body
+
+Generate a raw Markdown PR description.
+
+```bash
+branch-narrator pr-body [options]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
+| `--base <ref>` | auto-detected | Base git reference (branch mode only) |
+| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
+| `-u, --uncommitted` | `false` | Deprecated: use `--mode unstaged` |
+| `--profile <name>` | `auto` | Profile: `auto`, `sveltekit`, `next`, `react`, `vue`, `astro`, `stencil`, `library` |
+| `--interactive` | `false` | Prompt for context and test notes |
+
+Examples:
 
 ```bash
 # Analyze unstaged changes (default)
 branch-narrator pr-body
 
 # Compare branches for PR
-branch-narrator pr-body --mode branch --base develop --head feature/my-feature
+branch-narrator pr-body --mode branch --base develop --head feature/auth
 
 # Interactive mode (prompts for context)
 branch-narrator pr-body --interactive
+```
 
-# Pipe to clipboard (macOS)
-branch-narrator pr-body | pbcopy
+#### facts
+
+Output JSON findings for programmatic use.
+
+```bash
+branch-narrator facts [options]
 ```
 
-### Generate JSON Facts (Agent-Grade)
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
+| `--base <ref>` | auto-detected | Base git reference (branch mode only) |
+| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
+| `--profile <name>` | `auto` | Profile: `auto`, `sveltekit`, `next`, `react`, `vue`, `astro`, `stencil`, `library` |
+| `--format <type>` | `json` | Output format: `json`, `sarif` |
+| `--pretty` | `false` | Pretty-print JSON with 2-space indentation |
+| `--redact` | `false` | Redact obvious secrets in evidence |
+| `--exclude <glob>` | (none) | Exclude files matching glob (repeatable) |
+| `--include <glob>` | (none) | Include only files matching glob (repeatable) |
+| `--max-file-bytes <n>` | `1048576` | Max file size to analyze |
+| `--max-diff-bytes <n>` | `5242880` | Max diff size to analyze |
+| `--max-findings <n>` | (none) | Max findings to include |
+| `--out <path>` | (stdout) | Write output to file |
+| `--no-timestamp` | `false` | Omit `generatedAt` for deterministic output |
+| `--since <path>` | (none) | Compare current output to a previous JSON file |
+| `--since-strict` | `false` | Exit with code 1 on scope mismatch |
+| `--test-parity` | `false` | Enable test parity checks |
+
+Examples:
 
 ```bash
 # Analyze unstaged changes (default)
@@ -101,620 +256,390 @@ branch-narrator facts --mode branch --base develop --head feature/auth
 # Pretty-printed JSON
 branch-narrator facts --pretty
 
-# Redact secrets in evidence excerpts
-branch-narrator facts --redact
-
-# Limit output
-branch-narrator facts --max-findings 50
-
-# Filter files
-branch-narrator facts --exclude "**/test/**" --include "src/**"
-
-# Parse with jq
-branch-narrator facts | jq '.risk.level'
-branch-narrator facts | jq '.categories[] | select(.id == "database")'
-branch-narrator facts | jq '.actions[] | select(.blocking == true)'
+# SARIF output for code scanning
+branch-narrator facts --format sarif --out branch-narrator.sarif
 
-# Delta mode: compare to previous run
+# Delta mode
 branch-narrator facts --out .ai/baseline.json
-# ... make changes ...
 branch-narrator facts --since .ai/baseline.json --pretty
 ```
 
-### Generate SARIF Output (for CI/Code Scanning)
+SARIF output details (rule mappings, schema, limitations) are documented in
+[`docs/08-rendering/sarif.md`](docs/08-rendering/sarif.md).
+Delta mode details are documented in
+[`docs/11-delta-mode/11-delta-mode.md`](docs/11-delta-mode/11-delta-mode.md).
 
-[SARIF (Static Analysis Results Interchange Format)](https://sarifweb.azurewebsites.net/) is a standardized JSON format for static analysis tools. Use `--format sarif` to output findings in a format compatible with GitHub Code Scanning and other SARIF consumers.
+#### dump-diff
 
-```bash
-# Generate SARIF output for GitHub Code Scanning
-branch-narrator facts --mode branch --base main --head HEAD --format sarif
-
-# Save to file for upload
-branch-narrator facts --format sarif --out branch-narrator.sarif
+Output a prompt-ready git diff with smart exclusions.
 
-# Pretty-printed SARIF
-branch-narrator facts --format sarif --pretty
+```bash
+branch-narrator dump-diff [options]
 ```
 
-For detailed technical documentation on the SARIF renderer—including the output schema, rule mappings (BNR001–BNR006), how line number tracking works, and known limitations—see [`docs/08-rendering/sarif.md`](docs/08-rendering/sarif.md).
-
-**SARIF Rule Mapping:**
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
+| `--base <ref>` | auto-detected | Base git reference (branch mode only) |
+| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
+| `--no-untracked` | (off) | Exclude untracked files (non-branch modes) |
+| `--out <path>` | stdout | Write output to file |
+| `--format <type>` | `text` | Output format: `text`, `md`, `json` |
+| `--unified <n>` | `0` | Lines of unified context |
+| `--include <glob>` | (none) | Include only matching files (repeatable) |
+| `--exclude <glob>` | (none) | Additional exclusion globs |
+| `--max-chars <n>` | (none) | Chunk output if it exceeds this size |
+| `--chunk-dir <path>` | `.ai/diff-chunks` | Directory for chunk files |
+| `--name <prefix>` | `diff` | Chunk file name prefix |
+| `--dry-run` | `false` | Preview what would be included/excluded |
+| `--name-only` | `false` | Output only file list (no diff content) |
+| `--stat` | `false` | Output file statistics |
+| `--patch-for <path>` | (none) | Output diff for a specific file only |
+| `--pretty` | `false` | Pretty-print JSON with 2-space indentation |
+| `--no-timestamp` | `false` | Omit `generatedAt` for deterministic output |
 
-The following findings are mapped to stable SARIF rules:
+Notes:
 
-- **BNR001**: Dangerous SQL in migration (DROP, TRUNCATE, ALTER TYPE, etc.) - `error`
-- **BNR002**: Non-destructive migration changed - `warning`
-- **BNR003**: Major version bump in critical dependencies (@sveltejs/kit, svelte, vite, react, next) - `warning`
-- **BNR004**: New environment variable reference detected - `warning`
-- **BNR005**: Cloudflare configuration changed - `note`
-- **BNR006**: API endpoint changed (added/modified/deleted) - `note`
+- `--name-only`, `--stat`, and `--patch-for` are mutually exclusive.
+- Default exclusions include lockfiles, build artifacts, sourcemaps, and
+  minified files (see docs for the full list).
 
-**GitHub Actions Example:**
+Examples:
 
-```yaml
-name: Code Scanning
+```bash
+# Output unstaged changes to stdout (default)
+branch-narrator dump-diff
 
-on:
-  pull_request:
-    branches: [main]
+# Compare branches for PR
+branch-narrator dump-diff --mode branch --base main --head feature/auth --out .ai/diff.txt
 
-jobs:
-  analyze:
-    runs-on: ubuntu-latest
-    permissions:
-      security-events: write
-      contents: read
+# Chunk large diffs
+branch-narrator dump-diff --max-chars 25000 --chunk-dir .ai/diff-chunks
 
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Fetch full history for diff analysis
+# JSON output with metadata
+branch-narrator dump-diff --format json --pretty --out .ai/diff.json
+```
 
-      - name: Install branch-narrator
-        run: npm install -g @better-vibe/branch-narrator
+#### risk-report
 
-      - name: Generate SARIF
-        run: |
-          branch-narrator facts \
-            --mode branch \
-            --base ${{ github.event.pull_request.base.sha }} \
-            --head ${{ github.event.pull_request.head.sha }} \
-            --format sarif \
-            --out branch-narrator.sarif
+Analyze diffs and emit a risk score with evidence-backed flags.
 
-      - name: Upload SARIF to GitHub
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: branch-narrator.sarif
-          category: branch-narrator
+```bash
+branch-narrator risk-report [options]
 ```
 
-**Limitations:**
-- SARIF output is deterministic and based on heuristics only (no LLM calls)
-- Line numbers are included when evidence is based on added diff lines
-- Not all finding types are mapped to SARIF rules (see mapping above for covered types)
-- No autofix suggestions in MVP (SARIF `fixes` field not populated)
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
+| `--base <ref>` | auto-detected | Base git reference (branch mode only) |
+| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
+| `--format <type>` | `json` | Output format: `json`, `md`, `text` |
+| `--out <path>` | (stdout) | Write output to file |
+| `--fail-on-score <n>` | (none) | Exit with code 2 if risk score >= threshold |
+| `--only <categories>` | (all) | Only include these categories (comma-separated) |
+| `--exclude <categories>` | (none) | Exclude these categories (comma-separated) |
+| `--max-evidence-lines <n>` | `5` | Max evidence lines per flag |
+| `--redact` | `false` | Redact secret values in evidence |
+| `--explain-score` | `false` | Include score breakdown |
+| `--pretty` | `false` | Pretty-print JSON with 2-space indentation |
+| `--no-timestamp` | `false` | Omit `generatedAt` for deterministic output |
+| `--since <path>` | (none) | Compare current output to a previous JSON file |
+| `--since-strict` | `false` | Exit with code 1 on scope mismatch |
+| `--test-parity` | `false` | Enable test parity checks |
+
+Risk levels:
+
+- `low` (0-20)
+- `moderate` (21-40)
+- `elevated` (41-60)
+- `high` (61-80)
+- `critical` (81-100)
 
-### Risk Report (General-Purpose Security & Quality Analysis)
+Examples:
 
 ```bash
 # Analyze unstaged changes (default)
 branch-narrator risk-report
 
-# Compare branches for PR
-branch-narrator risk-report --mode branch --base develop --head feature/auth
-
 # Markdown format for human review
 branch-narrator risk-report --format md
 
-# Text format for terminal
-branch-narrator risk-report --format text
-
 # Fail CI if risk score >= threshold
 branch-narrator risk-report --fail-on-score 50
 
-# Focus on specific categories
-branch-narrator risk-report --only security,deps,db
-
-# Exclude certain categories
-branch-narrator risk-report --exclude tests,churn
-
-# Show score breakdown
-branch-narrator risk-report --explain-score
-
-# Redact secrets in evidence
-branch-narrator risk-report --redact
-
-# Limit evidence lines per flag
-branch-narrator risk-report --max-evidence-lines 3
-
-# Write to file
-branch-narrator risk-report --format md --out .ai/risk-report.md
-
-# Parse with jq
-branch-narrator risk-report | jq '.riskScore'
-branch-narrator risk-report | jq '.flags[] | select(.category == "security")'
-branch-narrator risk-report | jq '.categoryScores.db'
-
-# Delta mode: track risk improvement
+# Delta mode
 branch-narrator risk-report --out .ai/baseline-risk.json
-# ... make changes ...
 branch-narrator risk-report --since .ai/baseline-risk.json --pretty
-# Shows: risk score change, added/removed/changed flags
-```
-
-**Risk Categories:**
-- `security`: Workflow permissions, pull_request_target, remote script execution
-- `ci`: CI/CD pipeline configuration changes
-- `deps`: New dependencies, major version bumps, lockfile inconsistencies
-- `db`: Database migrations, destructive SQL, schema changes
-- `infra`: Dockerfile, Terraform, Kubernetes manifests
-- `api`: OpenAPI, GraphQL, Protocol Buffer schema changes
-- `tests`: Test coverage gaps, test file changes
-- `churn`: Large changesets (>50 files or >1500 lines)
-
-**Risk Levels:** (based on 0-100 score)
-- `low` (0-20): Minimal risk, safe to merge
-- `moderate` (21-40): Some risk, review recommended
-- `elevated` (41-60): Moderate risk, careful review needed
-- `high` (61-80): High risk, thorough review required
-- `critical` (81-100): Critical risk, requires security review
-
-**Output Schema (v1.0):**
-- `schemaVersion`: Schema version identifier
-- `generatedAt`: ISO timestamp
-- `git`: Git metadata (base, head, range, isDirty)
-- `profile`: Detected project profile with confidence
-- `stats`: File change statistics
-- `filters`: Applied filtering configuration
-- `summary`: High-level summary with highlights
-- `categories`: Findings aggregated by category with risk weights
-- `risk`: Structured risk score with factors and evidence
-- `findings`: Detailed findings array (typed discriminated union)
-- `actions`: Actionable recommendations (blocking/non-blocking)
-- `skippedFiles`: Files excluded from analysis with reasons
-- `warnings`: Any warnings encountered during analysis
-
-**Example categories output:**
-```json
-{
-  "categories": [
-    {
-      "id": "database",
-      "count": 2,
-      "riskWeight": 45,
-      "topEvidence": [
-        {
-          "file": "supabase/migrations/002_users.sql",
-          "excerpt": "DROP TABLE IF EXISTS old_users;"
-        }
-      ]
-    }
-  ]
-}
 ```
 
-### Dump Diff for AI Agents
-
-```bash
-# Output unstaged changes (default)
-branch-narrator dump-diff
-
-# Write to file
-branch-narrator dump-diff --out .ai/diff.txt
-
-# Compare branches for PR
-branch-narrator dump-diff --mode branch --base main --head feature/auth --out .ai/diff.txt
-
-# Staged changes only (index vs HEAD)
-branch-narrator dump-diff --mode staged --format md --out .ai/staged.md
-
-# All changes since HEAD (staged + unstaged + untracked)
-branch-narrator dump-diff --mode all --out .ai/all-changes.txt
+Risk scoring details are documented in
+[`docs/08-rendering/risk-scoring.md`](docs/08-rendering/risk-scoring.md).
 
-# Exclude untracked files
-branch-narrator dump-diff --mode all --no-untracked --out .ai/diff.txt
+#### zoom
 
-# Chunk large diffs for context windows
-branch-narrator dump-diff --max-chars 25000 --chunk-dir .ai/diff-chunks
-
-# JSON format with metadata
-branch-narrator dump-diff --format json --out .ai/diff.json
+Zoom into a specific finding or risk flag for detailed context.
 
-# Include only specific files
-branch-narrator dump-diff --include "src/**" --include "tests/**"
+```bash
+branch-narrator zoom [options]
 ```
 
-### Zoom Command
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--finding <id>` | (none) | Finding ID to zoom into |
+| `--flag <id>` | (none) | Flag ID to zoom into |
+| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
+| `--base <ref>` | auto-detected | Base git reference (branch mode only) |
+| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
+| `--profile <name>` | `auto` | Profile: `auto`, `sveltekit`, `next`, `react`, `vue`, `astro`, `stencil`, `library` |
+| `--format <type>` | `json` | Output format: `json`, `md`, `text` |
+| `--unified <n>` | `3` | Lines of unified context |
+| `--no-patch` | `false` | Exclude patch context (evidence only) |
+| `--max-evidence-lines <n>` | `8` | Max evidence excerpt lines |
+| `--redact` | `false` | Redact obvious secret values |
+| `--out <path>` | stdout | Write output to file |
+| `--pretty` | `false` | Pretty-print JSON with 2-space indentation |
+| `--no-timestamp` | `false` | Omit `generatedAt` for deterministic output |
 
-Drill down into a specific finding or risk flag to get detailed, isolated context. Useful for AI agents to verify specific issues or changes without processing the entire diff.
+Examples:
 
 ```bash
-# Zoom into a specific finding by ID (from 'facts' output)
-branch-narrator zoom --finding finding-123
-
-# Zoom into a risk flag by ID (from 'risk-report' output)
-branch-narrator zoom --flag flag-456
-
-# Output as Markdown (default is markdown, can be json or text)
-branch-narrator zoom --finding finding-123 --format md
+# Zoom into a finding
+branch-narrator zoom --finding finding.env-var#abc123
 
-# Get JSON output for machine parsing
-branch-narrator zoom --flag flag-456 --format json --pretty
+# Zoom into a risk flag
+branch-narrator zoom --flag flag.db.destructive_sql#def456 --format md
 
-# Exclude patch context (show only evidence metadata)
-branch-narrator zoom --finding finding-123 --no-patch
-
-# Adjust context lines
-branch-narrator zoom --finding finding-123 --unified 5
+# Zoom without patch context
+branch-narrator zoom --finding finding.dependency-change#c0ffee --no-patch
 ```
 
-### AI Agent Integration
+#### integrate
 
-Generate provider-specific rules for AI coding assistants (Cursor, Jules, etc.).
+Generate provider-specific rules for AI coding assistants.
 
 ```bash
-# Generate Cursor rules
-branch-narrator integrate cursor
-
-# Generate Jules rules
-branch-narrator integrate jules
-
-# Preview what would be created without writing files
-branch-narrator integrate cursor --dry-run
-
-# Overwrite existing rule files
-branch-narrator integrate cursor --force
+branch-narrator integrate [target] [options]
 ```
 
-**What it does:**
-- Creates provider-specific rule files (e.g., `.cursor/rules/branch-narrator.md`)
-- Instructs the AI on when and how to use `branch-narrator` commands
-- Provides consistent workflows for PR descriptions and analysis
-
-**Why use this:**
-- AI assistants will automatically read these rules when working in your repository
-- Ensures the AI uses branch-narrator to ground PR descriptions in actual git diffs instead of guessing
-- Provides consistent PR description templates across your team
-
-**Exit codes:**
-- `0`: Success
-- `1`: Expected failure (unknown target, files exist without --force, etc.)
-
-## CLI Commands
-
-### `pretty` Command
-
-Display a colorized summary of changes in the terminal.
+Options:
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
-| `--base <ref>` | auto-detected | Base git reference (branch mode only; auto-detected from remote HEAD, falls back to `main`) |
-| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
-| `--profile <name>` | `auto` | Profile: `auto`, `sveltekit`, `stencil`, `next`, or `react` |
-
-### `pr-body` Command
-
-Generate a raw Markdown PR description.
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
-| `--base <ref>` | auto-detected | Base git reference (branch mode only; auto-detected from remote HEAD, falls back to `main`) |
-| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
-| `-u, --uncommitted` | `false` | **[DEPRECATED]** Use `--mode unstaged` instead |
-| `--profile <name>` | `auto` | Profile: `auto`, `sveltekit`, `stencil`, `next`, or `react` |
-| `--interactive` | `false` | Prompt for additional context |
+| `--dry-run` | `false` | Preview without writing files |
+| `--force` | `false` | Overwrite existing files |
 
-### `facts` Command
+Targets:
 
-Output JSON findings for programmatic use.
+- `cursor` -> `.cursor/rules/branch-narrator.md` and `.cursor/rules/pr-description.md`
+- `jules` -> `AGENTS.md`
+- `claude` -> `CLAUDE.md`
+- `jules-rules` -> `.jules/rules/branch-narrator.md`
+- `opencode` -> `OPENCODE.md` / `.opencode/branch-narrator.md`
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
-| `--base <ref>` | auto-detected | Base git reference (branch mode only; auto-detected from remote HEAD, falls back to `main`) |
-| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
-| `--profile <name>` | `auto` | Profile: `auto`, `sveltekit`, `stencil`, `next`, or `react` |
+When `target` is omitted, `integrate` auto-detects existing guide locations and
+applies matching integrations.
 
-### `dump-diff` Command
+Examples:
 
-Output prompt-ready git diff with smart exclusions. Designed for AI agents.
+```bash
+branch-narrator integrate cursor
+branch-narrator integrate --dry-run
+branch-narrator integrate opencode --force
+```
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
-| `--base <ref>` | auto-detected | Base git reference (branch mode only; auto-detected from remote HEAD, falls back to `main`) |
-| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
-| `--no-untracked` | (off) | Exclude untracked files (non-branch modes) |
-| `--out <path>` | stdout | Write output to file |
-| `--format <type>` | `text` | Format: `text`, `md`, or `json` |
-| `--unified <n>` | `0` | Lines of unified context |
-| `--include <glob>` | (none) | Include only matching files |
-| `--exclude <glob>` | (none) | Additional exclusion globs |
-| `--max-chars <n>` | (none) | Chunk if output exceeds size |
-| `--chunk-dir <path>` | `.ai/diff-chunks` | Directory for chunks |
-| `--name <prefix>` | `diff` | Chunk file prefix |
-| `--dry-run` | `false` | Preview without writing |
+#### snap
 
-**Modes:**
-- `unstaged` (default): Working tree vs index (uncommitted changes)
-- `branch`: Compare `--base` to `--head` refs
-- `staged`: Index vs HEAD (staged changes)
-- `all`: Working tree vs HEAD (all uncommitted changes)
+Manage local workspace snapshots.
 
-**Default exclusions:** lockfiles, `.d.ts`, logs, `dist/`, `build/`, `.svelte-kit/`, `.next/`, minified files, sourcemaps, binaries.
+```bash
+branch-narrator snap <subcommand> [options]
+```
 
-### `integrate` Command
+Subcommands:
 
-Generate provider-specific rules for AI coding assistants.
+- `snap save [label]` -- Save a snapshot.
+  - Options: `--out <path>`
+- `snap list` -- List snapshots.
+  - Options: `--pretty`
+- `snap show <snapshotId>` -- Show snapshot details.
+  - Options: `--pretty`
+- `snap diff <idA> <idB>` -- Compare two snapshots.
+  - Options: `--pretty`
+- `snap restore <snapshotId>` -- Restore workspace to a snapshot.
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `<target>` | (required) | Integration target: `cursor`, `jules` |
-| `--dry-run` | `false` | Preview what would be written without creating files |
-| `--force` | `false` | Overwrite existing files |
+Snapshots are stored under `.branch-narrator/`. Add it to `.gitignore` to keep
+snapshots local.
 
-**Supported targets:**
-- `cursor`: Generates `.cursor/rules/branch-narrator.md` and `.cursor/rules/pr-description.md`
-- `jules`: Generates `AGENTS.md` in the repository root with Branch Narrator rules for Jules
+Examples:
 
-**Behavior:**
-- Creates rules directory if it doesn't exist
-- Fails with exit code 1 if files already exist (use `--force` to overwrite)
-- Outputs exact file paths and contents in `--dry-run` mode
+```bash
+# Save a snapshot
+branch-narrator snap save "before-refactor"
 
-### `risk-report` Command
+# Compare two snapshots
+branch-narrator snap diff abc123def456 def456abc789 --pretty
+```
 
-Analyze git diff and emit a risk score (0-100) with evidence-backed flags. Framework-agnostic security and quality analysis.
+### Exit Codes
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--mode <type>` | `unstaged` | Diff mode: `branch`, `unstaged`, `staged`, `all` |
-| `--base <ref>` | auto-detected | Base git reference (branch mode only; auto-detected from remote HEAD, falls back to `main`) |
-| `--head <ref>` | `HEAD` | Head git reference (branch mode only) |
-| `--format <type>` | `json` | Output format: `json`, `md`, or `text` |
-| `--out <path>` | stdout | Write output to file |
-| `--fail-on-score <n>` | (none) | Exit with code 2 if risk score >= threshold |
-| `--only <categories>` | (none) | Only include these categories (comma-separated) |
-| `--exclude <categories>` | (none) | Exclude these categories (comma-separated) |
-| `--max-evidence-lines <n>` | `5` | Max evidence lines per flag |
-| `--redact` | `false` | Redact secret values in evidence |
-| `--explain-score` | `false` | Include score breakdown in output |
-
-**Output Schema (v1.0):**
-- `schemaVersion`: "1.0"
-- `range`: { base, head }
-- `riskScore`: 0-100 computed score
-- `riskLevel`: "low" | "moderate" | "elevated" | "high" | "critical"
-- `categoryScores`: Scores per category (0-100)
-- `flags`: Array of risk flags with evidence
-- `skippedFiles`: Files excluded from analysis
-- `scoreBreakdown`: (optional) Score computation details
-
-**Exit Codes:**
 | Code | Description |
 |------|-------------|
 | `0` | Success |
-| `1` | Expected errors (not a git repo, invalid refs, etc.) |
-| `2` | Risk score >= `--fail-on-score` threshold |
-
-### `zoom` Command
-
-Zoom into a specific finding or flag for detailed context.
+| `1` | Expected failures (not a git repo, invalid refs) |
+| `2` | Risk score threshold exceeded (`risk-report --fail-on-score`) |
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--finding <id>` | (optional) | Finding ID to zoom into (mutually exclusive with `--flag`) |
-| `--flag <id>` | (optional) | Flag ID to zoom into (mutually exclusive with `--finding`) |
-| `--format <type>` | `md` | Output format: `json`, `md`, `text` |
-| `--no-patch` | `false` | Exclude patch context, only show evidence |
-| `--unified <n>` | `3` | Lines of unified context for patch hunks |
-| `--max-evidence-lines <n>` | `8` | Max evidence excerpt lines to show |
-| `--redact` | `false` | Redact obvious secret values |
-| `--out <path>` | stdout | Write output to file |
+## CI/CD Integration
 
-## Sample Output
+### GitHub Actions with SARIF
 
-### Markdown PR Body
+Upload findings to GitHub Code Scanning:
 
-```markdown
-## Summary
+```yaml
+name: Code Analysis
 
-- 5 file(s) changed
-- 2 file(s) added
-- 1 new route(s)
-- Database migrations detected
+on:
+  pull_request:
+    branches: [main]
 
-## Routes / API
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-| Route | Type | Change | Methods |
-|-------|------|--------|---------|
-| `/dashboard` | page | added | - |
-| `/api/users` | endpoint | added | GET, POST |
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
 
-## Database (Supabase)
+      - name: Install branch-narrator
+        run: npm install -g @better-vibe/branch-narrator
 
-**Risk Level:** 🟡 MEDIUM
+      - name: Generate SARIF report
+        run: branch-narrator facts --mode branch --base origin/main --format sarif --out results.sarif
 
-**Files:**
-- `supabase/migrations/20240101_add_users.sql`
+      - name: Upload SARIF to GitHub
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+```
 
-## Config / Env
+### Risk Gate
 
-| Variable | Status | Evidence |
-|----------|--------|----------|
-| `PUBLIC_API_URL` | added | src/lib/config.ts |
-| `DATABASE_URL` | added | src/hooks.server.ts |
+Fail CI if risk score exceeds threshold:
 
-## Dependencies
+```yaml
+- name: Check risk score
+  run: branch-narrator risk-report --mode branch --base origin/main --fail-on-score 60
+```
 
-### Production
+## Programmatic API
 
-| Package | From | To | Impact |
-|---------|------|-----|--------|
-| `@sveltejs/kit` | ^1.0.0 | ^2.0.0 | major |
+Use branch-narrator as a library for custom integrations:
 
-## Suggested Test Plan
+```typescript
+import {
+  collectChangeSet,
+  getProfile,
+  resolveProfileName,
+  runAnalyzersInParallel,
+  computeRiskScore,
+} from "@better-vibe/branch-narrator";
 
-- [ ] `bun run test` - Run test suite
-- [ ] `bun run check` - Run SvelteKit type check
-- [ ] Test `GET/POST /api/users` endpoint
-- [ ] Verify `/dashboard` page renders correctly
+// Collect git changes
+const changeSet = await collectChangeSet({
+  mode: "branch",
+  base: "main",
+  head: "HEAD",
+});
 
-## Risks / Notes
+// Resolve and run profile analyzers
+const profileName = resolveProfileName("auto", changeSet, process.cwd());
+const profile = getProfile(profileName);
+const findings = await runAnalyzersInParallel(profile.analyzers, changeSet);
 
-**Overall Risk:** 🟡 MEDIUM (score: 35/100)
+// Compute risk
+const riskScore = computeRiskScore(findings);
 
-- ⚠️ Major version bump: @sveltejs/kit ^1.0.0 → ^2.0.0
-- ℹ️ New env var: PUBLIC_API_URL
+console.log(`Risk: ${riskScore.level} (${riskScore.score}/100)`);
+console.log(`Findings: ${findings.length}`);
 ```
 
-### JSON Facts
+## Example Output
+
+Sample `facts` output (truncated):
 
 ```json
 {
-  "profile": "sveltekit",
-  "riskScore": {
+  "schemaVersion": "2.1",
+  "git": {
+    "base": "main",
+    "head": "HEAD",
+    "range": "main..HEAD",
+    "mode": "branch"
+  },
+  "profile": {
+    "requested": "auto",
+    "detected": "sveltekit",
+    "confidence": "high"
+  },
+  "stats": {
+    "filesChanged": 12,
+    "insertions": 245,
+    "deletions": 89
+  },
+  "risk": {
     "score": 35,
-    "level": "medium",
-    "evidenceBullets": [
-      "⚠️ Major version bump: @sveltejs/kit ^1.0.0 → ^2.0.0"
+    "level": "moderate",
+    "factors": [
+      { "category": "routes", "weight": 15 },
+      { "category": "dependencies", "weight": 10 },
+      { "category": "config", "weight": 10 }
     ]
   },
   "findings": [
-    {
-      "type": "file-summary",
-      "added": ["src/routes/dashboard/+page.svelte"],
-      "modified": ["package.json"],
-      "deleted": [],
-      "renamed": []
-    },
     {
       "type": "route-change",
-      "routeId": "/dashboard",
-      "file": "src/routes/dashboard/+page.svelte",
+      "findingId": "finding.route-change#a1b2c3d4",
+      "route": "/api/users",
       "change": "added",
-      "routeType": "page"
-    },
-    {
-      "type": "dependency-change",
-      "name": "@sveltejs/kit",
-      "section": "dependencies",
-      "from": "^1.0.0",
-      "to": "^2.0.0",
-      "impact": "major"
+      "methods": ["GET", "POST"],
+      "evidence": [...]
     }
   ]
 }
 ```
 
-## Analyzers
-
-### Route Detector
-
-Detects changes under `src/routes/**`:
-
-- Maps filesystem paths to SvelteKit route IDs
-- Identifies page, layout, endpoint, and error types
-- Extracts HTTP methods from endpoint exports
-- Preserves param notation (`[slug]`, `[[id]]`, `[...rest]`)
-
-### Supabase Migration Detector
-
-Scans `supabase/migrations/*.sql` for:
-
-- **High risk**: `DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `ALTER TYPE`, `DELETE` without `WHERE`
-- **Medium risk**: Migrations without destructive patterns
-- **Low risk**: Only seed/config files changed
-
-### Environment Variable Detector
-
-Extracts env vars from:
+See [`docs/04-types/findings.md`](docs/04-types/findings.md) for the complete
+schema and all finding types.
 
-- `process.env.VAR_NAME`
-- `PUBLIC_*` patterns
-- SvelteKit `$env/static/public` imports
-- SvelteKit `$env/static/private` imports
-
-### Cloudflare Detector
-
-Detects:
-
-- `wrangler.toml` / `wrangler.json` changes
-- GitHub workflow changes mentioning Cloudflare/wrangler
-
-### Vitest Detector
-
-Detects:
-
-- `*.test.ts`, `*.spec.ts` files
-- `tests/` directory changes
-- `vitest.config.*` changes
-
-### Dependency Analyzer
-
-Compares `package.json`:
-
-- Additions, removals, and version bumps
-- Semver impact classification (major/minor/patch)
-- Risk flags for critical package major bumps
-
-## Profiles
-
-### Auto Detection
-
-When `--profile auto` (default), the profile is detected by:
-
-1. **SvelteKit**: Checking for `src/routes` directory or `@sveltejs/kit` in package.json
-2. **React**: Checking for `react`, `react-dom`, and `react-router-dom` in package.json (only when Next.js is not detected)
-3. **Default**: Generic profile for all other projects
-
-### SvelteKit Profile
-
-Runs all analyzers optimized for SvelteKit projects, including:
-- SvelteKit route detection (`src/routes/`)
-- SvelteKit env var patterns (`$env/static/public`, `$env/static/private`)
-
-### React Profile
-
-Runs all analyzers optimized for React projects, including:
-- React Router route detection (JSX `<Route>` components and data routers)
-- Vite env var patterns (`import.meta.env.VITE_*`)
-- React App env var patterns (`process.env.REACT_APP_*`)
-
-**Note**: React Router detection requires `react-router` or `react-router-dom` in package.json.
-
-## Exit Codes
+## Development
 
-| Code | Description |
-|------|-------------|
-| `0` | Success |
-| `1` | Expected failures (not a git repo, invalid refs, etc.) |
-| `2` | Risk score threshold exceeded (when using `risk-report --fail-on-score`) |
+See [`docs/06-development/getting-started.md`](docs/06-development/getting-started.md)
+and [`docs/06-development/testing.md`](docs/06-development/testing.md).
 
-## Development
+Quick commands:
 
 ```bash
-# Install dependencies
 bun install
-
-# Run tests
 bun run test
-
-# Build
 bun run build
-
-# Type check
 bun run typecheck
-
-# Run locally
-bun src/cli.ts pretty -u
-bun src/cli.ts pr-body --base main --head HEAD
-bun src/cli.ts facts -u | jq '.riskScore'
 ```
 
+## Contributing
+
+Contributions are welcome! Please read the development guides before submitting
+a pull request:
+
+- [Getting Started](docs/06-development/getting-started.md) - Setup and workflow
+- [Coding Standards](docs/06-development/coding-standards.md) - Code style and conventions
+- [Testing](docs/06-development/testing.md) - Test requirements
+
+For bug reports and feature requests, please open an issue.
+
 ## Requirements
 
 - Node.js >= 18