repopilot 0.10.0 → 0.12.0

package/README.md

@@ -7,91 +7,82 @@
 [![License](https://img.shields.io/crates/l/repopilot.svg)](LICENSE)
 [![GitHub Stars](https://img.shields.io/github/stars/MykytaStel/repopilot?style=social)](https://github.com/MykytaStel/repopilot)
 
-Audit your repository locally, turn the results into AI-ready remediation context,
-and ship safer changes without sending source code to a hosted scanner.
+**Local-first repository risk checks for safer human and AI-assisted code changes.**
 
-RepoPilot is a local-first CLI for architecture, security, code quality, testing,
-and framework health checks. It gives developers useful terminal reports, CI gates,
-SARIF for GitHub Code Scanning, and Markdown briefs that can be pasted into Claude
-Code, ChatGPT, Cursor, or another coding assistant.
+RepoPilot gives teams a fast safety pass before a pull request, release, or AI
+coding session. It scans a repository locally, explains architecture, security,
+code-quality, testing, and framework risks, then turns findings into AI-ready
+context without uploading your source code to a hosted scanner.
 
-Version `0.10.0` is an adoption and stability release: it focuses on cleaner
-rollout diagnostics, reproducible audit receipts, CI artifacts, and 0.x command
-compatibility while keeping all scans local.
+It is not meant to replace language linters. RepoPilot focuses on repository
+signals that are hard to see from one file at a time: risky files, architecture
+drift, security candidates, testing gaps, review risk, baselines, and remediation
+context for Claude Code, ChatGPT, Cursor, or another coding assistant.
 
-## Why RepoPilot?
+---
 
-Most linters and audit tools stop at the terminal. RepoPilot bridges the gap to your AI assistant:
+## Why RepoPilot?
 
-| | SonarQube / CodeClimate | ESLint / language linters | **RepoPilot** |
-|---|---|---|---|
-| Runs offline | ❌ | ✅ | ✅ |
-| No code upload | ❌ | ✅ | ✅ |
-| Cross-language architecture analysis | ✅ | ❌ | ✅ |
-| LLM-ready output | ❌ | ❌ | ✅ |
-| Fits in a model context window | ❌ | ❌ | ✅ |
-| CI gate on new findings only | ✅ | partial | ✅ |
+Most tools either lint one language or send results into a dashboard. RepoPilot is
+designed for the local development loop:
 
-```bash
-repopilot ai context . | pbcopy   # macOS: paste into your coding assistant
+```text
+scan -> understand risk -> generate AI context -> fix -> review
 ```
 
-## Features
-
-- Repository scanning for projects, folders, and individual files
-- Gitignore-aware walking with built-in ignores for common build, cache, vendor, and native platform directories
-- Architecture findings: oversized files, deep nesting, deep relative imports, risky barrel files, too many modules per directory
-- Coupling analysis: excessive fan-out, high-instability hubs, circular dependencies
-- Code quality findings: cyclomatic complexity density, long functions, TODO/FIXME/HACK markers
-- Security findings: hardcoded secret candidates, committed private keys, committed `.env` files
-- Testing findings: missing test folder, source files without test counterparts
-- Framework findings for JavaScript, React, React Native, Expo, and Django projects
-- React Native architecture profile: project kind, New Architecture, Hermes, Codegen, platform mismatch, and package manager signals
-- Workspace scanning (`--workspace`) for npm, yarn, pnpm, and Cargo workspaces with per-package risk summary — parallel per-package scans
-- Evidence-backed findings with stable rule IDs, severity, file paths, line numbers, and snippets
-- 46 built-in rules with titles, descriptions, recommendations, and docs links
-- `repopilot.toml` configuration generated by `repopilot init`
-- Configuration presets (`--preset strict|balanced|lenient`) for quick threshold tuning
-- Baseline workflow for accepting existing findings in legacy repositories
-- CI-friendly failure thresholds with `--fail-on`
-- Git diff-aware review mode for prioritizing findings introduced by changed lines
-- Doctor adoption guidance for config, baseline, CI gate, report, and receipt readiness
-- Audit receipt JSON from `repopilot scan --receipt` for reproducible scan evidence
-- Console, JSON, Markdown, HTML, and SARIF (2.1.0) scan output — SARIF includes per-result category and workspace package properties
-- First-party GitHub Action wrapper for `scan`, `review`, `compare`, and `ai` workflows, with optional SARIF upload and receipt output for scans
-- Compare mode for diffing two JSON scan reports
-- **`repopilot ai context`** — formats scan output as LLM-ready markdown, paste into Claude Code or ChatGPT to start remediating
-- **`repopilot ai plan`** — turns findings into a prioritized remediation plan
-- **`repopilot ai prompt`** — exports an AI-ready remediation prompt with RepoPilot context
-
-See [docs/rulesets.md](docs/rulesets.md) for the full list of rules and severity levels.
+| Capability | Language linters | Hosted scanners | RepoPilot |
+|---|---:|---:|---:|
+| Runs locally | ✅ | ❌ | ✅ |
+| No source upload required | ✅ | ❌ | ✅ |
+| Cross-language repository view | ❌ | ✅ | ✅ |
+| Architecture and repo risk signals | partial | ✅ | ✅ |
+| AI-ready remediation context | ❌ | ❌ | ✅ |
+| Baseline and PR review workflow | partial | ✅ | ✅ |
+| Default noise reduction / Trust Mode | ❌ | partial | ✅ |
+
+Use RepoPilot when you need to:
+
+- understand the highest-risk files before asking an AI assistant to edit;
+- add a CI gate without blocking on every existing finding;
+- review PR risk from changed lines instead of only whole-repo noise;
+- produce local evidence for releases through Markdown, JSON, SARIF, and receipts.
+
+---
 
 ## Install
 
+With Cargo:
+
 ```bash
 cargo install repopilot
 ```
 
-Install with npm:
+With npm:
 
 ```bash
 npm install -g repopilot
 ```
 
-Install with Homebrew:
+With Homebrew:
 
 ```bash
 brew tap mykytastel/repopilot
 brew install repopilot
 ```
 
-Install with curl (Linux/macOS):
+With curl on Linux/macOS:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/MykytaStel/repopilot/main/install.sh | bash
 ```
 
-The curl installer verifies the GitHub Release SHA256 checksum and aborts if the checksum cannot be downloaded or verified.
+Build from source:
+
+```bash
+git clone https://github.com/MykytaStel/repopilot.git
+cd repopilot
+cargo build --release
+```
 
 Upgrade:
 
@@ -101,381 +92,339 @@ npm update -g repopilot
 brew update && brew upgrade repopilot
 ```
 
-Build from source:
-
-```bash
-git clone https://github.com/MykytaStel/repopilot.git
-cd repopilot
-cargo build --release
-```
+---
 
 ## Quick Start
 
-No config needed. Run this in any repository and see findings immediately:
+Start with a local scan:
 
 ```bash
 repopilot scan .
 ```
 
-Then get an AI-ready brief to paste into Claude Code, Cursor, or ChatGPT:
+Check adoption readiness and create an intentional baseline for existing debt:
 
 ```bash
-repopilot ai context . | pbcopy   # macOS — copies to clipboard
-repopilot ai context .            # print to terminal
+repopilot doctor .
+repopilot baseline create . --output .repopilot/baseline.json
+repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high
 ```
 
-That's the two-minute loop. Scan, read the output, paste the context into your assistant, fix.
+Generate AI-ready context for the highest-risk work:
 
-### Going deeper
+```bash
+repopilot ai context . --budget 4k
+```
 
-Once you want CI integration, baseline tracking, or tighter configuration:
+Copy AI context on macOS:
 
 ```bash
-repopilot init                                              # generate repopilot.toml
-repopilot doctor .                                          # check CI / baseline readiness
-repopilot baseline create .                                 # accept existing findings as known debt
-repopilot review . --base origin/main --fail-on new-high    # CI gate on new findings only
+repopilot ai context . | pbcopy
 ```
 
-Save a shareable report:
+Save a Markdown report:
 
 ```bash
-repopilot scan . --format markdown --output repopilot-report.md --receipt .repopilot/receipt.json
+repopilot scan . --format markdown --output repopilot-report.md
 ```
 
-Reduce scan noise while iterating:
+Run a focused security scan:
 
 ```bash
-repopilot scan . --min-severity high
-repopilot scan . --workspace --min-severity medium
-repopilot scan . --exclude fixtures --max-file-size 1mb --max-files 500
+repopilot scan . --min-severity high --rule security.secret-candidate
 ```
 
-By default, RepoPilot skips low-signal audit paths such as tests, fixtures, examples, generated files, and benchmarks. Use `--include-low-signal` when you want those paths analyzed too.
+Review only changed code against a base branch:
 
-## Local-First AI Workflow
-
-RepoPilot does not call LLM APIs. AI commands scan local files and produce Markdown
-that you decide where to paste.
+```bash
+repopilot review . --base origin/main
+```
 
-`repopilot ai context` scans a project and formats all findings as structured markdown ready to paste into Claude Code, Cursor, ChatGPT, or any LLM assistant. It includes a risk level, tech stack summary, findings grouped by category with evidence snippets and fix recommendations, and a token-count estimate.
+---
 
-```bash
-# Paste into Claude Code or ChatGPT
-repopilot ai context .
+## Trust Mode
 
-# Focus on security only, keep it short
-repopilot ai context . --focus security --budget 2k
+RepoPilot's default scan profile is intentionally quiet.
 
-# Save to file
-repopilot ai context . --output repopilot-context.md
+The default profile focuses on actionable production, security, and runtime risks.
+Strict mode shows the full raw audit output, including maintainability and testing
+suggestions.
 
-# Pipe directly into clipboard (macOS)
-repopilot ai context . --no-header | pbcopy
+```bash
+repopilot scan .                  # default profile
+repopilot scan . --profile strict # full audit output
+repopilot scan . --include-maintainability
 ```
 
-## Example Output
+The visibility engine classifies findings by product intent:
 
+```text
+SecurityRisk | RuntimeRisk | ActionableRisk | Maintainability | TestingGap | Informational
 ```
-$ repopilot ai context .
 
-# RepoPilot Vibe Check — my-app
+Hidden suggestions are summarized by intent, rule, category, and reason, so the
+default report stays quiet without silently losing information.
+
+Read more:
 
-**Risk Level:** 🟠 ELEVATED
-**Tech Stack:** React Native (New Arch), Expo, TypeScript
-**Size:** 94 files · 8,340 LOC · ~42k tokens
-**Health:** 18 findings · 2.2/kloc — 4 high, 9 medium
+- [Trust Mode](docs/trust-mode.md)
+- [Core Visibility Engine](docs/core-visibility-engine.md)
 
-## Security (2 high)
-1. [HIGH] Possible secret detected — `src/config/api.ts:12`
-   ```
-   const API_KEY = "sk_live_…"
-   ```
-   > **Fix:** Move to environment variables or a secrets manager.
+---
 
-## Architecture (2 high)
-1. [HIGH] Circular dependency detected — `src/store/index.ts`
-   > **Fix:** Extract shared types to a separate module to break the cycle.
+## AI Workflow
 
-## Top Recommendations
-1. **Move hardcoded API key** (src/config/api.ts:12) — use process.env or a vault
-2. **Break circular dependency** (src/store/index.ts) — extract shared types
+RepoPilot does not call LLM APIs. It produces local Markdown that you choose where
+to paste.
 
----
-*~3.8k tokens (budget: 4k) · scanned in 312ms — paste into Claude Code, Cursor, or ChatGPT*
+```bash
+repopilot ai context . --focus security
+repopilot ai plan . --focus security
+repopilot ai prompt . --budget 8k
 ```
 
-Paste this into a coding assistant and ask for a focused patch. For larger
-repositories, start with one focus area instead of asking for every finding at
-once.
+Typical loop:
 
-## Recommended Remediation Loop
+```text
+1. Run RepoPilot locally.
+2. Read the risk summary.
+3. Generate focused AI context.
+4. Paste the context into Claude Code, ChatGPT, Cursor, or another assistant.
+5. Apply the patch.
+6. Run RepoPilot review/scan again.
+```
 
-RepoPilot is a local-first safety layer for AI-assisted and vibe-coded changes. Run it after generating or refactoring code to catch newly introduced high-risk findings, workspace hotspots, missing tests, and architecture drift without uploading source code to an external service.
+See [AI workflows](docs/ai-workflows.md).
 
-```bash
-repopilot ai context . --focus security    # get an LLM brief for Claude Code
-repopilot ai plan . --focus security       # get a prioritized hardening plan
-repopilot ai prompt . --budget 8k          # generate a paste-ready remediation prompt
-repopilot review . --base origin/main --baseline .repopilot/baseline.json --fail-on new-high
-repopilot scan . --workspace --min-severity medium --format markdown --output repopilot-report.md
-```
+---
 
-## Commands
+## Core Commands
 
 | Command | Alias | Description |
-|---------|-------|-------------|
-| `repopilot scan <path>` | `s` | Scan a project, folder, or file for findings |
+|---|---:|---|
+| `repopilot scan <path>` | `s` | Scan a project, folder, or file |
+| `repopilot scan <path> --changed` | — | Scan changed files with local cache |
+| `repopilot cache clear [path]` | — | Remove `.repopilot/cache` |
 | `repopilot review [path]` | `r` | Review findings that touch changed Git diff lines |
-| `repopilot ai context <path>` | — | LLM-ready context from a scan |
-| `repopilot ai plan <path>` | — | Prioritized remediation plan |
-| `repopilot ai prompt <path>` | — | AI-ready remediation prompt |
-| `repopilot compare <before> <after>` | `cmp` | Compare two JSON scan reports and show what changed |
-| `repopilot baseline create <path>` | `bl` | Scan a path and store current findings as accepted debt |
+| `repopilot ai context <path>` | — | Generate LLM-ready repository context |
+| `repopilot ai plan <path>` | — | Generate a prioritized remediation plan |
+| `repopilot ai prompt <path>` | — | Generate a paste-ready remediation prompt |
+| `repopilot compare <before> <after>` | `cmp` | Compare two JSON scan reports |
+| `repopilot baseline create <path>` | `bl` | Store current findings as accepted debt |
 | `repopilot doctor [path]` | `d` | Diagnose audit readiness |
-| `repopilot init` | — | Generate a default `repopilot.toml` configuration file |
+| `repopilot init` | — | Generate `repopilot.toml` |
 
-Use `--help` on any command for the full description and examples:
+Get command help:
 
 ```bash
 repopilot --help
 repopilot scan --help
 repopilot review --help
-repopilot baseline create --help
+repopilot ai --help
 ```
 
-## Configuration
-
-RepoPilot automatically reads `repopilot.toml` from the current working directory when running `scan`.
+---
 
-Configuration precedence:
+## Output Formats
 
-```text
-CLI args > repopilot.toml > built-in defaults
+```bash
+repopilot scan . --format console
+repopilot scan . --format json --output report.json
+repopilot scan . --format markdown --output report.md
+repopilot scan . --format html --output report.html
+repopilot scan . --format sarif --output repopilot.sarif
 ```
 
-Generate a default config:
+Use:
+
+- `console` for local development
+- `markdown` for human-readable reports
+- `json` for scripts and integrations
+- `html` for shareable reports
+- `sarif` for GitHub Code Scanning
+
+---
+
+## Configuration
+
+Generate a config file:
 
 ```bash
 repopilot init
-repopilot init --force
-repopilot init --path ./repopilot.toml
 ```
 
-Use an explicit config path:
+Run with an explicit config:
 
 ```bash
 repopilot scan . --config repopilot.toml
 ```
 
-Example `repopilot.toml`:
-
-```toml
-[scan]
-ignore = [
-  ".git",
-  ".github",
-  ".repopilot",
-  "target",
-  "node_modules",
-  "dist",
-  "build",
-  ".next",
-  ".nuxt",
-  ".cache",
-  "coverage",
-  "vendor",
-  "Pods",
-  "DerivedData"
-]
-max_file_bytes = 2097152
-
-[architecture]
-max_file_lines = 300
-huge_file_lines = 1000
-max_directory_modules = 20
-max_directory_depth = 5
-max_function_lines = 50
-max_fan_out = 15
-instability_hub_min_fan_in = 5
-instability_hub_min_instability_pct = 75
-
-[testing]
-detect_missing_tests = true
-
-[security]
-detect_secret_like_names = true
-
-[output]
-default_format = "console"
+Configuration precedence:
+
+```text
+CLI args > repopilot.toml > built-in defaults
 ```
 
-CLI threshold overrides:
+Common scan options:
 
 ```bash
+repopilot scan . --preset strict
+repopilot scan . --preset balanced
+repopilot scan . --preset lenient
 repopilot scan . --max-file-loc 500
-repopilot scan . --max-directory-modules 25
 repopilot scan . --max-directory-depth 6
-repopilot scan . --max-file-size 1mb
-repopilot scan . --max-files 1000
 repopilot scan . --exclude generated
 repopilot scan . --include-low-signal
 ```
 
-`--max-file-size` accepts raw bytes or `kb`, `mb`, and `gb` suffixes. `--exclude` matches an exact path relative to the scan root or a file/directory name; repeat it for multiple paths.
+See [configuration docs](docs/configuration.md).
 
-JSON output includes scan input accounting fields: `files_discovered` for files found after ignore/exclude filters, `files_count` for analyzed text files, `files_skipped_low_signal` for default low-signal skips, and `binary_files_skipped` for unreadable/binary files.
+---
 
-## Baseline Workflow
+## Baseline and Review
 
-Existing repositories often have findings that cannot all be fixed before adopting a new audit tool. A baseline stores accepted existing findings so future scans can distinguish new findings from existing ones.
+Create a baseline for existing findings:
 
 ```bash
-repopilot baseline create .
-repopilot scan . --baseline .repopilot/baseline.json
-repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high
+repopilot baseline create . --output .repopilot/baseline.json
 ```
 
-By default, `baseline create` writes `.repopilot/baseline.json` and creates the `.repopilot/` directory if needed. Use `--output ./baseline.json` for a custom path. Existing baseline files are not overwritten unless you pass `--force`.
-
-Baseline files store accepted existing findings. Future scans can mark findings as `new` or `existing`, which is useful for legacy repositories and CI. Do not refresh a baseline blindly unless the team accepts those findings as technical debt.
-
-## Review Workflow
-
-Use `review` when you want RepoPilot to focus on findings that touch changed Git diff lines.
+Scan against accepted debt:
 
 ```bash
-repopilot review .
-repopilot review . --format json --output review.json
-repopilot review . --baseline .repopilot/baseline.json --fail-on new-high
+repopilot scan . --baseline .repopilot/baseline.json
 ```
 
-By default, `review` compares the working tree against `HEAD`, including staged, unstaged, and untracked files. For branch or CI review, pass a base ref:
+Fail CI only on new high-risk findings:
 
 ```bash
-repopilot review . --base origin/main
-repopilot review . --base origin/main --head HEAD --format markdown
+repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high
 ```
 
-Review mode still scans the repository with the normal rules, but separates findings into in-diff and out-of-diff groups. When import coupling data is available, it also shows blast radius: files that import changed files and may need extra review. When `--fail-on` is used, the CI gate evaluates only in-diff findings.
+Commit `.repopilot/baseline.json` only after reviewing the accepted findings.
+Do not update it just to make CI green; note accepted baseline changes in the PR.
 
-## Output Formats
+Validate or bypass local feedback suppressions:
 
 ```bash
-repopilot scan . --format console
-repopilot scan . --format json --output report.json
-repopilot scan . --format markdown --output report.md
-repopilot scan . --format html --output report.html
-repopilot scan . --format sarif --output repopilot.sarif
+repopilot inspect feedback .
+repopilot scan . --ignore-feedback
 ```
 
-### SARIF output
+Review a pull request or branch diff:
 
 ```bash
-repopilot scan . --format sarif --output repopilot.sarif
+repopilot review . --base origin/main --fail-on-priority p1
 ```
 
-If your installed RepoPilot version does not support `--output`, redirect stdout instead:
+See:
 
-```bash
-repopilot scan . --format sarif > repopilot.sarif
-```
+- [CLI reference](docs/cli.md)
+- [Commands guide](docs/commands.md)
+- [GitHub Code Scanning integration](docs/integrations/github-code-scanning.md)
 
-Use JSON when custom scripts need to parse RepoPilot results. Console, Markdown, and HTML reports include the RepoPilot version, risk summary, top rules, and grouped findings for human review. Use SARIF for CI and code scanning integrations, including GitHub Code Scanning.
-Use `--receipt <path>` with `scan` when CI or release processes need compact evidence of the exact RepoPilot version, git state, scan scope, finding counts, language counts, and health score.
+---
 
-See [docs/integrations/github-code-scanning.md](docs/integrations/github-code-scanning.md) for a copy-paste GitHub Actions workflow, required permissions, and local validation commands.
+## What RepoPilot Checks
+
+RepoPilot includes rules for:
+
+- architecture risk
+- large and complex files
+- deep nesting
+- risky barrel files
+- excessive fan-out and coupling
+- circular dependencies
+- TODO/FIXME/HACK markers
+- long functions
+- hardcoded secret candidates
+- committed private keys
+- committed `.env` files
+- missing test structure
+- source files without test counterparts
+- JavaScript/TypeScript framework signals
+- React and React Native project health
+- Django project health
+- Rust panic/unwrap risk
+- JavaScript runtime exit risk
+
+See the full rule list in [rulesets](docs/rulesets.md).
 
-Compare two JSON reports:
+---
+
+## Example
 
 ```bash
-repopilot scan . --format json --output before.json
-repopilot scan . --format json --output after.json
-repopilot compare before.json after.json
-repopilot compare before.json after.json --format markdown
-repopilot compare before.json after.json --format json --output diff.json
+$ repopilot scan .
+
+RepoPilot Scan
+Version: 0.12.0
+Path: .
+Risk: Elevated
+Health score: 93/100
+Profile: default
+Findings visible: 7
+Hidden suggestions: 657 strict-only suggestions
+
+Top risks:
+	P0 security.secret-candidate src/config/app.ts:12
+	P1 language.rust.panic-risk src/api/routes/search.rs:88
+
+Hidden suggestions breakdown:
+	 379 testing-gap / testing.source-without-test
+	 104 maintainability / code-quality.long-function
+		43 maintainability / architecture.large-file
 ```
 
-## CI Usage
-
-Use `--fail-on new-high` to fail CI only when new high or critical findings are introduced. Supported new-finding thresholds are `new-low`, `new-medium`, `new-high`, and `new-critical`.
-
-When `--fail-on new-*` is used without `--baseline`, RepoPilot treats all current findings as new. For baseline-based adoption, commit an accepted baseline and scan against it in CI.
-
-To upload RepoPilot findings to GitHub Code Scanning, generate SARIF and use `github/codeql-action/upload-sarif`. The workflow must include `security-events: write`.
-The first-party action can also run `command: ai-context`, `command: ai-plan`, or `command: ai-prompt`; those commands emit Markdown and do not produce SARIF. Prefer typed action inputs such as `path`, `config`, `baseline`, `fail-on`, `focus`, `budget`, `output`, and `receipt`; `args` remains available for advanced flags.
-
-```yaml
-name: RepoPilot
-
-on:
-  pull_request:
-
-permissions:
-  contents: read
-  security-events: write
-
-jobs:
-  repopilot:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v5
+Default mode shows what is likely to matter now. Strict mode keeps the full audit:
 
-      - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Install RepoPilot
-        run: cargo install repopilot
+```bash
+repopilot scan . --profile strict
+```
 
-      - name: Run RepoPilot
-        run: repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high --receipt repopilot-receipt.json
+---
 
-      - name: Run RepoPilot (SARIF)
-        run: repopilot scan . --format sarif --output repopilot.sarif
+## Documentation
 
-      - name: Upload to GitHub Code Scanning
-        uses: github/codeql-action/upload-sarif@v4
-        if: always()
-        with:
-          sarif_file: repopilot.sarif
+| Document | Description |
+|---|---|
+| [Install](docs/install.md) | Cargo, npm, Homebrew, curl, and source builds |
+| [AI workflows](docs/ai-workflows.md) | Claude Code, ChatGPT, Cursor, and remediation workflows |
+| [Security](docs/security.md) | Local-first trust model and vulnerability reporting |
+| [Configuration](docs/configuration.md) | `repopilot.toml`, presets, ignore files, and baseline adoption |
+| [Language support](docs/language-support.md) | Supported language/framework tiers and limitations |
+| [Knowledge Engine](docs/knowledge-engine.md) | Rule applicability and local-first learning policy |
+| [Risk Engine](docs/risk-engine.md) | Risk scoring, priorities, and calibration policy |
+| [Local Feedback](docs/local-feedback.md) | Repository-local suppressions and validation |
+| [Trust Mode](docs/trust-mode.md) | Default vs strict visibility and hidden suggestions |
+| [Core Visibility Engine](docs/core-visibility-engine.md) | Finding intent model and visibility decisions |
+| [CLI reference](docs/cli.md) | Commands, flags, and exit codes |
+| [Commands guide](docs/commands.md) | Task-oriented command examples |
+| [Rulesets](docs/rulesets.md) | Implemented rules, categories, and severity levels |
+| [React Native](docs/react-native.md) | React Native and Expo detection |
+| [GitHub Code Scanning](docs/integrations/github-code-scanning.md) | SARIF workflow and CI setup |
+| [Roadmap](docs/roadmap.md) | Pre-1.0 roadmap and v1 gates |
+| [0.12 GTM plan](docs/gtm-0.12.md) | Launch audiences, messaging, and proof points |
+| [Release process](docs/release.md) | Manual release process |
+| [Changelog](CHANGELOG.md) | Version history |
 
-      - name: Upload audit receipt
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: repopilot-receipt
-          path: repopilot-receipt.json
-```
+---
 
 ## Roadmap
 
-These are planned ideas, not current features:
+Planned direction:
 
-- Change Risk Map
-- Better architecture drift detection
-- Optional per-platform npm binary packages for faster installs
+- stronger Trust Mode calibration
+- `repopilot eval` with golden fixtures
+- local feedback validation and report transparency
+- hidden suggestion trend tracking
+- deeper dependency graph and impact analysis
+- AI task packs with context, constraints, and acceptance criteria
 
-## Documentation
+See [roadmap](docs/roadmap.md).
 
-| Document | Description |
-|---|---|
-| [docs/install.md](docs/install.md) | Installation options for Cargo, npm, Homebrew, curl, and source builds |
-| [docs/ai-workflows.md](docs/ai-workflows.md) | Claude Code, ChatGPT, Cursor, and AI remediation workflows |
-| [docs/security.md](docs/security.md) | Local-first trust model, installer security, and vulnerability reporting |
-| [docs/configuration.md](docs/configuration.md) | `repopilot.toml`, presets, ignore files, and baseline adoption |
-| [docs/language-support.md](docs/language-support.md) | Supported language/framework tiers, rule families, and limitations |
-| [docs/cli.md](docs/cli.md) | Complete CLI reference — all commands, flags, and exit codes |
-| [docs/commands.md](docs/commands.md) | Task-oriented command guide and common patterns |
-| [docs/rulesets.md](docs/rulesets.md) | Implemented audit rules, categories, and severity levels |
-| [docs/react-native.md](docs/react-native.md) | React Native and Expo detection, findings, and limitations |
-| [docs/integrations/github-code-scanning.md](docs/integrations/github-code-scanning.md) | GitHub Code Scanning SARIF workflow |
-| [docs/release.md](docs/release.md) | Manual release process |
-| [docs/release-checklist-0.10.md](docs/release-checklist-0.10.md) | 0.10.0 release readiness checklist |
-| [docs/distribution.md](docs/distribution.md) | Distribution channels |
-| [docs/github-ruleset.md](docs/github-ruleset.md) | GitHub branch ruleset configuration |
-| [CHANGELOG.md](CHANGELOG.md) | Version history |
+---
 
 ## License
 
-RepoPilot is licensed under MIT OR Apache-2.0.
+RepoPilot is licensed under **MIT OR Apache-2.0**.