@praneeth_54/agentdoctor 1.1.1 → 2.0.1

package/README.md

@@ -1,644 +1,394 @@
 # AgentDoctor
 
-Evidence-backed Project Brain for AI Coding Agents
+## Engineering assurance for AI coding agents.
 
-![AgentDoctor hero](docs/assets/agentdoctor-hero.svg)
-
-AI coding agents can read files. They still lack reliable **repository-level** understanding — what is in a project, what evidence supports a claim, what is dangerous to change, and what must stay **UNKNOWN**.
-
-AgentDoctor analyzes a repository, builds a structured **Project Brain** (claims, evidence, confidence, ownership, risks, snapshots, deltas), and exposes it to agents through local **STDIO MCP**.
+Understand your codebase, assess the impact of changes, govern engineering knowledge, enforce safety policies, and attach inspectable evidence to AI-driven changes.
 
 [![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor?label=npm)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
 [![CI](https://img.shields.io/github/actions/workflow/status/pranee54/AgentDoctor/ci.yml?branch=main&label=CI)](https://github.com/pranee54/AgentDoctor/actions/workflows/ci.yml)
 [![Node](https://img.shields.io/node/v/@praneeth_54/agentdoctor)](https://nodejs.org)
 [![License](https://img.shields.io/github/license/pranee54/AgentDoctor)](LICENSE)
 
-[Documentation](docs/README.md) · [Project Brain](docs/project-brain.md) · [MCP](docs/mcp/brain-mcp.md) · [GitHub Action](#github-action) · [Demo](docs/demo/brain-mcp-demo.md) · [Security](SECURITY.md) · [Roadmap](ROADMAP.md)
+**In-repo cut:** `2.0.1` (publish pending human authorization). Last published: [`@praneeth_54/agentdoctor@2.0.0`](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
 
-```text
-Repository
-   ↓
-Project Understanding
-   ↓
-Project Brain
-   ↓
-Evidence / Claims / Confidence
-   ↓
-MCP
-   ↓
-AI Coding Agent
-```
-
-Also ships **Safety V1**: Scan → Fix → Verify → Policy → CI for Cursor, Claude Code, and Codex configuration. Brain risk is **change-danger analysis**, not vulnerability scanning.
+[Install](#install) · [Quickstart](#quickstart) · [Change assurance](#change-assurance) · [Documentation](docs/2.0.1/README.md) · [MCP](#mcp) · [GitHub Action](#github-action) · [Architecture](#architecture)
 
 ---
 
-## What is AgentDoctor?
-
-Local developer infrastructure for AI coding agents (`@praneeth_54/agentdoctor`, CLI `agentdoctor`, **1.1.0**, Node.js **20+**).
-
-It:
-
-- analyzes repositories with deterministic discovery passes
-- builds a structured Project Brain
-- represents claims with typed evidence and confidence
-- preserves **UNKNOWN** when evidence is missing
-- persists snapshots and computes deltas
-- exposes Brain capabilities through MCP (`agentdoctor brain-mcp --root <path>`)
+## What AgentDoctor is
 
-It is **not** an autonomous coding agent, chatbot, RAG memory product, AGI claim, or vulnerability scanner. It does not claim universal or perfect repository understanding.
+AgentDoctor sits between developers / AI coding agents and the repository’s engineering reality.
 
----
-
-## Why Project Brain?
-
-Agents edit with fragmented context. Ownership gets invented. Blast radius stays implicit. “Why should I trust that?” rarely has an answer with a snapshot id.
+AI agents can write code quickly. The harder engineering problem is knowing whether a change is **correct, safe, compatible, explainable, and consistent** with the rest of the repository.
 
-Project Brain structures understanding that exists in this codebase:
+AgentDoctor collects repository signals — source structure, graphs, Git history, policies, knowledge, and verification evidence — so humans and agents can reason about changes with fewer unsupported assumptions.
 
-architecture · domains · components · entrypoints · dependencies · relationships · ownership · change-danger risks · claims · evidence · confidence · snapshots · deltas
+It is **not** an autonomous coding agent, chatbot, or IDE interceptor. It does **not** guarantee correctness. It produces **evidence and controls** you can inspect.
 
-Details: [docs/project-brain.md](docs/project-brain.md)
+**Short description:** Engineering assurance for AI coding agents — repository intelligence, change evidence, safety controls, and MCP tools.
 
 ---
 
-## Architecture
+## Why AgentDoctor?
 
-![Architecture](docs/assets/architecture.svg)
+Modern AI coding agents can:
 
-| Layer                     | Location                                                    |
-| ------------------------- | ----------------------------------------------------------- |
-| Understanding / discovery | `src/core/understanding/`                                   |
-| Project Brain             | `src/core/understanding/brain/`                             |
-| MCP bridge                | `src/mcp/brain/`                                            |
-| CLI                       | `src/cli/commands/brain-mcp.ts`                             |
-| Safety (separate path)    | `src/core/{scanner,rules,fix,verify,policy}/`, `action.yml` |
+- read individual files
+- generate and edit code
+- run tests when asked
 
-MCP depends on Brain. Brain does not depend on MCP.
+Repository-level context is usually fragmented across:
 
----
+| Signal             | Typical location               |
+| ------------------ | ------------------------------ |
+| Source structure   | AST / imports / modules        |
+| Dependencies       | manifests / lockfiles          |
+| History            | Git                            |
+| Architecture       | docs / conventions / inference |
+| Tests              | test trees / naming heuristics |
+| Policy             | CI rules / allowlists          |
+| Decisions          | ADRs / RFCs / tribal knowledge |
+| Secrets / exposure | config files / ignore rules    |
 
-## Project Brain
-
-![Provenance](docs/assets/provenance.svg)
-
-### Evidence & provenance
+AgentDoctor brings those signals into one local toolchain around an AI-driven engineering change:
 
 ```text
-Claim
-  ↓
-Evidence
-  ↓
-Snapshot
+Developer / AI Agent
+        │
+        ▼
+   AgentDoctor
+        │
+┌───────────────────────────────┐
+│ Repository Intelligence       │
+│ AST / Graph / Git / Impact    │
+├───────────────────────────────┤
+│ Engineering Knowledge         │
+│ Brain / Decisions / Provenance│
+├───────────────────────────────┤
+│ Safety & Policy               │
+│ Scan / Fix / Enforce / Secrets│
+├───────────────────────────────┤
+│ Verification                  │
+│ Tests / Reports / Evidence    │
+└───────────────────────────────┘
+        │
+        ▼
+Safer, explainable engineering decisions
 ```
 
-Successful MCP tools return a provenance envelope: `result`, `evidenceIds`, `confidence` (`[0,1]`, rule-derived / uncalibrated), `snapshot` (`id` + `contentHash`), and `claimStatus` when applicable.
-
-Claim lifecycle: `ACTIVE` · `INVALIDATED` · `SUPERSEDED` · `CONTRADICTED`
-
-Epistemics on evidence: `observed` | `inferred`. ACTIVE claims must reference evidence. Serialization redacts secret-like values.
+---
 
-### UNKNOWN semantics
+## Capability map
 
-```text
-Ownership evidence unavailable
-        ↓
-     UNKNOWN
-```
+Status labels: **SUPPORTED** · **PARTIAL** · **EXPERIMENTAL** · **NOT YET SUPPORTED**
 
-No invented owners. Contract: `preserve-unknown-never-invent`.
+Details and evidence: [docs/2.0/overview/capabilities.md](docs/2.0/overview/capabilities.md) · [readiness matrix](docs/2.0/overview/readiness-matrix.md)
 
-Local runtime store (not committed product source): `<repo>/.agentdoctor/project-brain/`.
+### Repository intelligence
 
----
+| Capability                                           | Status       |
+| ---------------------------------------------------- | ------------ |
+| TypeScript / JavaScript AST graph (+ regex fallback) | PARTIAL      |
+| Import / inferred call relationships                 | PARTIAL      |
+| Git hotspot / engineering intelligence               | PARTIAL      |
+| Change / test / refactor impact                      | PARTIAL      |
+| C4-style architecture views                          | EXPERIMENTAL |
 
-## MCP
+### Engineering knowledge
 
-![MCP tools](docs/assets/mcp-tools.svg)
+| Capability                                                    | Status    |
+| ------------------------------------------------------------- | --------- |
+| Project Brain store + evidence-backed claims                  | SUPPORTED |
+| Repository Brain init / proposal review (never auto-approved) | PARTIAL   |
+| Governed knowledge + abstention on retrieve                   | PARTIAL   |
+| Provenance envelopes on Brain MCP tools                       | SUPPORTED |
 
-```text
-AI Coding Agent → MCP client → agentdoctor brain-mcp --root <abs> → Project Brain
-```
+### Agent interfaces
 
-STDIO only. No API key. No upload. `--root` is required. Diagnostics on **stderr**; protocol on **stdout**.
+| Capability                                                                        | Status    |
+| --------------------------------------------------------------------------------- | --------- |
+| Brain MCP (`brain_*` tools, STDIO)                                                | SUPPORTED |
+| Combined MCP (Brain + intelligence tools)                                         | PARTIAL   |
+| Agent adapters (Cursor, Claude Code, Codex, Copilot, Windsurf, Gemini CLI, Aider) | SUPPORTED |
+| Local dashboard + `/api/v2/*`                                                     | PARTIAL   |
+| Programmatic API (`scan`, Fix, Brain helpers)                                     | SUPPORTED |
 
-### Tools (from `src/mcp/brain/tools/registry.ts`)
+### Safety & governance
 
-| Tool              | Purpose                                                |
-| ----------------- | ------------------------------------------------------ |
-| `brain_overview`  | Compact summary + confidence envelope                  |
-| `brain_query`     | Typed `BrainQueryEngine` queries                       |
-| `brain_explain`   | Evidence-backed `explainClaim`                         |
-| `brain_trace`     | Capped deterministic `traceBrain`                      |
-| `brain_claims`    | Claim lifecycle (default ACTIVE + CONTRADICTED)        |
-| `brain_evidence`  | Typed redacted evidence                                |
-| `brain_ownership` | Explicit CODEOWNERS / MAINTAINERS / package only       |
-| `brain_risk`      | Change-danger risk (not SAST / CVE)                    |
-| `brain_delta`     | Read-only snapshot comparison                          |
-| `brain_snapshot`  | `current` · `history` · `compare` · `load` · `rebuild` |
+| Capability                                               | Status                |
+| -------------------------------------------------------- | --------------------- |
+| Scan → Safe Fix → Verify                                 | SUPPORTED             |
+| Policy gates (`--min-score`, severity, rule, verify-new) | SUPPORTED             |
+| Evaluate-only policy / controlled enforcement runner     | PARTIAL               |
+| Secret scan (redacted findings) + export redaction       | PARTIAL               |
+| Path-safety for MCP / dashboard                          | PARTIAL               |
+| Local-dev team auth (scrypt)                             | PARTIAL — **not SSO** |
 
-Only controlled write: `brain_snapshot` `rebuild` under `<root>/.agentdoctor/project-brain/`.
+### Verification
 
-Contract: [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md)
+| Capability                                              | Status                     |
+| ------------------------------------------------------- | -------------------------- |
+| Change assurance assessment + evidence bundles          | PARTIAL                    |
+| Evidence hash verify (`verified` = integrity only)      | SUPPORTED                  |
+| Unit / integration / MCP STDIO tests (`npm run verify`) | SUPPORTED                  |
+| Packed CLI clean-install smoke                          | SUPPORTED                  |
+| Reproducible AST perf harness                           | PARTIAL (synthetic sample) |
 
 ---
 
-## Real Cursor Agent Validation
+## How AgentDoctor is different
 
-![Agent validation](docs/assets/agent-validation.svg)
+Most engineering tools optimize one layer: static analysis, search, docs generation, dashboards, security scanners, or AI chat.
+
+AgentDoctor is designed around the **lifecycle of an AI-driven change**:
 
 ```text
-Cursor Agent
-    ↓
-MCP discovery (agentdoctor-brain)
-    ↓
-brain_* tool call
-    ↓
-Project Brain
-    ↓
-Evidence-backed result (+ provenance)
+Repository
+    → Understand
+    → Impact
+    → Knowledge
+    → Policy
+    → Change
+    → Verification
+    → Evidence
 ```
 
-Harness: `validation/mcp-agent` on `fixtures/understanding-dependencies-project`.
+That combination is the product direction. It does not mean every layer is equally mature — see the capability map and limitations.
 
-| Q   | Focus          | Expected tools                                    |
-| --- | -------------- | ------------------------------------------------- |
-| Q1  | Overview       | `brain_overview`                                  |
-| Q2  | Entrypoints    | `brain_query`                                     |
-| Q3  | Change risk    | `brain_risk`                                      |
-| Q4  | Ownership      | `brain_ownership`                                 |
-| Q5  | Impact / trace | `brain_trace`                                     |
-| Q6  | Provenance     | `brain_explain`, `brain_claims`, `brain_evidence` |
-| Q7  | Delta          | `brain_delta`, `brain_snapshot`                   |
+---
 
-Documented harness results ([validation/mcp-agent/README.md](validation/mcp-agent/README.md), 2026-08-13, AgentDoctor 1.1.0):
+## Architecture
 
-- Deterministic Brain tool exercise: **10/10** succeeded (actual tool calls, not prose inference)
-- Cursor MCP tools discovered: **PASS** (all 10 listed)
-- Security checks: **10/10**
-- Provenance (tool-level): **PASS**
-- Authenticated LLM Q1–Q7 grading: **BLOCKED** without agent login — kept separate from MCP contract PASS
+```text
+AgentDoctor
+│
+├── Repository Intelligence
+│   ├── AST (TS/JS)
+│   ├── Graph
+│   ├── Git
+│   └── Impact
+│
+├── Engineering Knowledge
+│   ├── Brain
+│   ├── Governance
+│   └── Provenance
+│
+├── Safety
+│   ├── Scanner
+│   ├── Safe Fix
+│   ├── Secrets
+│   └── Policies
+│
+├── Agent Interface
+│   ├── MCP (brain-mcp / mcp)
+│   ├── CLI
+│   ├── API / dashboard
+│   └── Adapters
+│
+└── Verification
+    ├── Tests
+    ├── Reports
+    └── Release validation
+```
 
-Checks include grounding, UNKNOWN ownership guard, risk semantics, provenance, snapshot/delta semantics — not “zero hallucinations.”
+Code layout: `src/{intelligence,knowledge,core,mcp,platform,enforcement,cli}/`
 
-Demo: [docs/demo/brain-mcp-demo.md](docs/demo/brain-mcp-demo.md)
+Canonical docs: [docs/2.0/overview/architecture.md](docs/2.0/overview/architecture.md)
 
 ---
 
-## Built Through Real Validation
-
-1.1.0 was hardened under real MCP, CI, and Windows pressure — not README theater.
+## Engineering principles
 
-| Problem                      | What we learned                                                                                                                                                                                                              |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| MCP cold start               | Session loads latest snapshot or, by default, **compiles on first connect** (`buildIfMissing`). Large roots make host MCP timeouts more likely — prefer an existing snapshot / explicit `rebuild` before attaching an agent. |
-| Large Brain init             | First compile writes under `.agentdoctor/project-brain/`; local Brain state ≠ committed source.                                                                                                                              |
-| STDIO discipline             | Protocol on stdout only; logs on stderr (`src/mcp/brain/server.ts`, `tests/unit/mcp/`).                                                                                                                                      |
-| Cross-process MCP tests      | Unit STDIO client + protocol tests matter more than assuming tool use from answer quality.                                                                                                                                   |
-| Windows CLI                  | `.cmd` / POSIX shim pitfalls → invoke via `node` + `npm-cli.js`; native `cmd` quoting.                                                                                                                                       |
-| Argument escaping            | CodeQL-driven hardening of Windows command argument escaping in test helpers.                                                                                                                                                |
-| CI matrix                    | Ubuntu + Windows quality job; Project Brain laboratory requires `npm run build` before spawn (`f3cd550`).                                                                                                                    |
-| Snapshots                    | Atomic writes, checksum fail-closed, refuse divergent overwrite of the same snapshot id.                                                                                                                                     |
-| Terminal / injection surface | Findings must not become escape channels; Security policy calls out terminal escape injection.                                                                                                                               |
-| UNKNOWN                      | Inventing ownership is a product failure mode.                                                                                                                                                                               |
+1. Evidence over assumptions
+2. Explicit limitations over inflated claims
+3. Safety before automation
+4. Repository context over isolated files
+5. Human approval for governed decisions
+6. Backwards compatibility where documented
+7. Reproducible verification
+8. Explainable agent actions
+9. Least privilege
+10. Secure defaults
 
 ---
 
-## Repository Structure
+## Install
 
-![Repository layout](docs/assets/repository-architecture.svg)
+Requires **Node.js 20+**.
 
-```text
-src/
-├── core/
-│   └── understanding/          # discovery + Project Brain
-├── mcp/
-│   └── brain/                  # STDIO MCP bridge
-└── cli/
-    └── commands/
-        └── brain-mcp.ts
-
-tests/
-└── unit/
-    ├── understanding/
-    └── mcp/
-
-validation/
-├── project-brain/
-├── software-understanding/
-├── real-world/
-└── mcp-agent/
-
-docs/
-├── assets/                     # README diagrams (this landing page)
-├── mcp/
-├── demo/
-└── project-brain.md
-
-examples/mcp/                   # Cursor / Claude Code / Codex config samples
+```bash
+# Local/RC version is 2.0.1; npm registry may still show 2.0.0 until published.
+npm install -g @praneeth_54/agentdoctor@2.0.1   # after publish
+# or from a packed tarball / this repo:
+# npm install /path/to/praneeth_54-agentdoctor-2.0.1.tgz
+npx @praneeth_54/agentdoctor@2.0.1 --help       # after publish
 ```
 
-Do not treat `.agentdoctor/` or project-local agent config dirs as committed AgentDoctor source.
-
----
-
-## Validation
-
-![Validation pipeline](docs/assets/validation-pipeline.svg)
+From source:
 
 ```bash
-npm run verify                 # typecheck · lint · format · unit · build
-npm run verify:understanding
-npm run verify:mcp
-npm run verify:project-brain   # understanding + validate:project-brain + benchmark
-npm run validate:mcp-agent
+git clone https://github.com/pranee54/AgentDoctor.git
+cd AgentDoctor
+npm install
+npm run verify
 ```
 
-| Layer            | How verified                                            | Current note                                                                      |
-| ---------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| Core / Safety    | `npm run verify` + CI quality (Ubuntu/Windows)          | Live [CI badge](https://github.com/pranee54/AgentDoctor/actions/workflows/ci.yml) |
-| Understanding    | `npm run verify:understanding`                          | Unit surface under `tests/unit/understanding/`                                    |
-| Project Brain    | `npm run verify:project-brain` + CI `project-brain` job | Requires built CLI                                                                |
-| MCP              | `npm run verify:mcp`                                    | Protocol + STDIO client tests                                                     |
-| Agent validation | `npm run validate:mcp-agent`                            | MCP discovery **PASS**; LLM Q1–Q7 **BLOCKED** (see report)                        |
-| Benchmark        | `benchmark:project-brain`                               | Part of `verify:project-brain`                                                    |
-| Package          | npm `@praneeth_54/agentdoctor`                          | Published **1.1.0**                                                               |
-| Security         | mcp-agent security suite + [SECURITY.md](SECURITY.md)   | Tool-level **10/10** in report                                                    |
-
-Re-run the commands above for live status; do not treat this table as a substitute for CI.
-
 ---
 
-## Installation
-
-```bash
-npx @praneeth_54/agentdoctor@1.1.1
-# or
-npm install -g @praneeth_54/agentdoctor
-agentdoctor --help
-```
+## Quickstart
 
 ```bash
-agentdoctor brain-mcp --root /ABSOLUTE/PATH/TO/YOUR/PROJECT
-
-agentdoctor .
+agentdoctor --version          # 2.0.1
+agentdoctor scan .
 agentdoctor scan . --json
-agentdoctor fix . --dry-run
-agentdoctor verify . --baseline agentdoctor-report.json
-agentdoctor explain security/env-file-exposure
-agentdoctor doctor
+agentdoctor fix --dry-run
+agentdoctor verify --baseline agentdoctor-report.json
+
+# Repository Brain proposals (not auto-approved)
+agentdoctor init --name "My App" --domain "payments"
+agentdoctor brain proposals
+
+# Intelligence
+agentdoctor graph --mode auto --json
+agentdoctor impact --json
+agentdoctor c4 --json
+
+# Change assurance
+agentdoctor change analyze
+agentdoctor change verify
+agentdoctor change explain|diff|status
+agentdoctor evidence inspect <id>
+agentdoctor evidence verify <id>
+agentdoctor proof build|inspect|verify|export <id>
+
+# Architecture / policy / controlled run
+agentdoctor architecture init|check|explain
+agentdoctor policy check|explain --command "npm test"
+agentdoctor run explain --command "npm test"
+agentdoctor workspace create|add|list|status|remove
+
+# MCP (absolute --root required)
+agentdoctor brain-mcp --root /ABS/PATH/TO/REPO
+agentdoctor mcp --root /ABS/PATH/TO/REPO
 ```
 
----
+CLI reference: [docs/2.0/guides/cli.md](docs/2.0/guides/cli.md) · Change assurance: [docs/2.0.1/change-assurance.md](docs/2.0.1/change-assurance.md)
 
-## GitHub Action
-
-AgentDoctor can run repository-level AI coding-agent configuration audits inside GitHub Actions and enforce CI policy gates.
+---
 
-This Action is the **Safety / CI** surface (`action.yml`): Scan → policy gates → JSON report. It does **not** expose Project Brain or MCP. For Brain/MCP, use the CLI and [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md).
+## Change assurance
 
-Recommended pin:
+Structured assessment, evidence bundles, and Change Proof **integrity** (not engineering correctness). Optional `--coverage` for coverage-backed / hybrid test impact. See [docs/2.0.1/FINAL_COMPLETION_AUDIT.md](docs/2.0.1/FINAL_COMPLETION_AUDIT.md).
 
-```yaml
-uses: pranee54/AgentDoctor@v1.1.0
+```bash
+agentdoctor change analyze              # ChangeAssessment (verificationStatus: not-run)
+agentdoctor change verify               # write .agentdoctor/evidence/<id>/ (evidence-produced)
+agentdoctor change explain|diff|status
+agentdoctor evidence inspect <id>       # list artifacts + manifest
+agentdoctor evidence verify <id>        # SHA-256 check; verified only if all hashes match
+agentdoctor proof inspect|verify <id>   # integrity; correctnessStatus always NOT_CLAIMED
 ```
 
-For maximum supply-chain pinning, pin a full commit SHA of this repository. Do not use `@main`.
+`verified` means artifact integrity against the manifest — not that the change is correct or safe. Details: [docs/2.0.1/change-assurance.md](docs/2.0.1/change-assurance.md) · [docs/2.0.1/evidence.md](docs/2.0.1/evidence.md)
 
-### CLI version default (intentional)
-
-| Surface                            | Value                                        |
-| ---------------------------------- | -------------------------------------------- |
-| Action release tag                 | `v1.1.0` (this repository’s Action metadata) |
-| Action input `version` **default** | **`1.0.0`**                                  |
-
-The `v1.1.0` Action release still defaults to the published AgentDoctor **CLI `1.0.0`** for compatibility. That is intentional.
-
-- Omit `version` (or set `version: "1.0.0"`) → install `@praneeth_54/agentdoctor@1.0.0`
-- Set `version: "1.1.1"` explicitly when you want the newer CLI in CI
-- `version: workspace` runs this repo’s built `dist/cli/index.js` (maintainers / local CI after `npm run build`)
-- `latest` / `beta` dist-tags are also accepted
-
-Project Brain and MCP are **not** started by this Action even when `version: "1.1.1"`. The Action still runs Safety scan/verify only.
-
-The Action is report-only until you set a policy input (`minimum-score`, `fail-on-severity`, `fail-on-rule`, or `fail-on-new` with `verify-baseline`).
+---
 
-### Examples
+## MCP
 
-**1. Basic scan** (report-only; default CLI `1.0.0`):
+AgentDoctor exposes local **STDIO** MCP servers (no API key).
 
-```yaml
-permissions:
-  contents: read
+| Server       | Command                              | Tools                                                                                                                                                               |
+| ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Brain MCP    | `agentdoctor brain-mcp --root <abs>` | `brain_overview`, `brain_query`, `brain_explain`, `brain_trace`, `brain_claims`, `brain_evidence`, `brain_ownership`, `brain_risk`, `brain_delta`, `brain_snapshot` |
+| Combined MCP | `agentdoctor mcp --root <abs>`       | All `brain_*` tools **plus** intelligence tools below                                                                                                               |
 
-steps:
-  - uses: actions/checkout@v4
+Intelligence tools (combined MCP):
+`repo_overview`, `codebase_search`, `symbol_lookup`, `dependency_lookup`, `call_graph_lookup`, `test_impact`, `refactor_impact`, `code_health`, `architecture_info`, `architecture_check`, `knowledge_retrieve`, `policy_evaluate`, `change_analyze`, `proof_inspect`, `evidence_inspect`, `graph_query`
 
-  - name: Audit coding-agent configuration
-    id: agentdoctor
-    uses: pranee54/AgentDoctor@v1.1.0
-    with:
-      path: .
-```
+Guide: [docs/2.0/guides/mcp.md](docs/2.0/guides/mcp.md) · Deep Brain MCP: [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md)
 
-**2. Minimum readiness score:**
+---
 
-```yaml
-- uses: pranee54/AgentDoctor@v1.1.0
-  with:
-    path: .
-    minimum-score: "70"
-```
+## GitHub Action
 
-**3. Severity gate:**
+Use AgentDoctor Safety in CI for scan / verify gates. Default npm version input is **`2.0.1`**.
 
 ```yaml
-- uses: pranee54/AgentDoctor@v1.1.0
+- uses: pranee54/AgentDoctor@v2.0.1
   with:
     path: .
+    version: "2.0.1"
     fail-on-severity: critical
 ```
 
-**4. Rule gate:**
+For repository CI against the checked-out build: `version: workspace` (requires `dist/` from `npm run build`).
 
-```yaml
-- uses: pranee54/AgentDoctor@v1.1.0
-  with:
-    path: .
-    fail-on-rule: security/env-file-exposure
-```
-
-**5. Baseline verification:**
-
-```yaml
-- uses: pranee54/AgentDoctor@v1.1.0
-  with:
-    path: .
-    verify-baseline: agentdoctor-report.json
-    fail-on-new: "true"
-```
-
-**6. JSON report** (default `json-output: "true"`; customize path):
-
-```yaml
-- uses: pranee54/AgentDoctor@v1.1.0
-  id: agentdoctor
-  with:
-    path: .
-    json-output: "true"
-    output-file: agentdoctor-report.json
-
-- uses: actions/upload-artifact@v4
-  with:
-    name: agentdoctor-report
-    path: ${{ steps.agentdoctor.outputs.report-path }}
-```
-
-**7. GitHub summary:**
-
-```yaml
-- uses: pranee54/AgentDoctor@v1.1.0
-  with:
-    path: .
-    summary: "true"
-```
-
-**8. GitHub annotations:**
-
-```yaml
-- uses: pranee54/AgentDoctor@v1.1.0
-  with:
-    path: .
-    annotations: "true"
-```
-
-**Combined policy example** (explicit newer CLI):
-
-```yaml
-permissions:
-  contents: read
-
-steps:
-  - uses: actions/checkout@v4
-
-  - name: Audit coding-agent configuration
-    id: agentdoctor
-    uses: pranee54/AgentDoctor@v1.1.0
-    with:
-      path: .
-      version: "1.1.1"
-      output-file: agentdoctor-report.json
-      json-output: "true"
-      minimum-score: "70"
-      fail-on-severity: critical
-      summary: "true"
-      annotations: "true"
-
-  - name: Upload AgentDoctor report
-    if: always()
-    uses: actions/upload-artifact@v4
-    with:
-      name: agentdoctor-report
-      path: ${{ steps.agentdoctor.outputs.report-path }}
-```
-
-### Inputs
-
-From [`action.yml`](action.yml):
-
-| Input              | Required | Default                   | Description                                                                                                                                              |
-| ------------------ | -------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path`             | no       | `.`                       | Repository-relative directory to scan.                                                                                                                   |
-| `version`          | no       | `1.0.0`                   | Published AgentDoctor npm version or dist-tag (`latest` \| `beta`), or `workspace` to run the checked-out repository’s built CLI at `dist/cli/index.js`. |
-| `output-file`      | no       | `agentdoctor-report.json` | Repository-relative path for the JSON report.                                                                                                            |
-| `minimum-score`    | no       | _(empty)_                 | Fail when overall readiness score is below this integer (0–100). Empty skips the gate.                                                                   |
-| `fail-on-severity` | no       | _(empty)_                 | Fail when any finding has this severity or higher (`critical` \| `warning` \| `info`). Empty skips the gate.                                             |
-| `fail-on-rule`     | no       | _(empty)_                 | Comma-separated rule IDs that fail CI when present (e.g. `security/env-file-exposure`).                                                                  |
-| `fail-on-new`      | no       | _(empty)_                 | When `verify-baseline` is set, fail on new findings vs the baseline. Defaults to true whenever `verify-baseline` is non-empty unless set to `false`.     |
-| `verify-baseline`  | no       | _(empty)_                 | Repository-relative path to a prior scan JSON baseline. When set, runs `agentdoctor verify` instead of scan.                                             |
-| `json-output`      | no       | `true`                    | Write a JSON report to `output-file` (`true`/`false`).                                                                                                   |
-| `summary`          | no       | `false`                   | Write a GitHub Actions job step summary (requires CLI with `--summary` support).                                                                         |
-| `annotations`      | no       | `false`                   | Emit GitHub Actions annotations for findings (requires CLI with `--annotations` support).                                                                |
-
-### Outputs
-
-| Output          | Description                                                                     |
-| --------------- | ------------------------------------------------------------------------------- |
-| `report-path`   | Absolute path to the generated JSON report (empty when `json-output` is false). |
-| `outcome`       | `success` \| `policy-failure` \| `configuration-error` \| `internal-failure`    |
-| `overall-score` | Overall readiness score from the scan/verify result when available.             |
+Guide: [docs/2.0/guides/github-action.md](docs/2.0/guides/github-action.md) · Action metadata: [`action.yml`](action.yml)
 
-| `outcome` value       | Meaning                                               |
-| --------------------- | ----------------------------------------------------- |
-| `success`             | Scan/verify completed without a failing policy gate.  |
-| `policy-failure`      | A configured policy gate failed (exit `1`).           |
-| `configuration-error` | Invalid Action/CLI configuration or usage (exit `2`). |
-| `internal-failure`    | Unexpected failure during execution.                  |
-
-Exit-code details: [docs/exit-codes.md](docs/exit-codes.md). Scoring: [docs/scoring.md](docs/scoring.md).
-
-### Action security notes
-
-Controls implemented in `action.yml`:
-
-- Paths must stay inside `GITHUB_WORKSPACE` (`realpath` + containment checks)
-- Traversal and parent-escape attempts are rejected
-- Symlink escapes for `output-file` parents / final file and for `verify-baseline` are rejected
-- Newlines in Action path inputs are rejected
-- `output-file` must resolve to a regular file path inside the workspace (not a directory or symlink)
-- `verify-baseline` must exist, realpath back into the workspace, and remain a file
-- `version` must match an exact npm semver, `latest`/`beta`, or `workspace`
-- No Action-level credential inputs
-
-Boundary (honest): the Action executes AgentDoctor against repository contents (treated as untrusted) and, except for `version: workspace`, may invoke `npm exec` against the public npm registry. This is not a claim of universal security.
-
-Related: [SECURITY.md](SECURITY.md)
-
-### Action versioning
-
-| Recommendation | Value                               |
-| -------------- | ----------------------------------- |
-| Preferred tag  | `uses: pranee54/AgentDoctor@v1.1.0` |
-| Stronger pin   | Full commit SHA of this repository  |
-| Avoid          | `@main`                             |
-
-The existing `v1.1.0` product tag is the Action metadata consumers should pin today. Changing the Action’s default CLI `version` input is a separate, explicit decision and is **not** done in this documentation update.
+Marketplace listing: confirm in the GitHub UI if you need Marketplace discovery beyond the Action in this repository.
 
 ---
 
-## Try it yourself
+## Security model
 
-1. **Install:** `npx @praneeth_54/agentdoctor@1.1.1 --help`
-2. **Run Brain MCP:** `agentdoctor brain-mcp --root /ABSOLUTE/PATH/TO/YOUR/PROJECT`
-3. **Connect MCP:** copy [examples/mcp/cursor.mcp.json](examples/mcp/cursor.mcp.json) (or Claude / Codex siblings) with absolute paths
-4. **First query:** call `brain_overview`
-5. **Demo:** [docs/demo/first-5-minutes.md](docs/demo/first-5-minutes.md)
+| Control     | Behavior                                                                   |
+| ----------- | -------------------------------------------------------------------------- |
+| Path safety | MCP / dashboard reject traversal, encoded escapes, hostile URLs            |
+| Safe Fix    | Preflight targets; refuse symlink write-through / non-allowlisted paths    |
+| Secrets     | Opt-in scan; findings and exports redact sensitive patterns                |
+| Policy      | Evaluate-only by default (`executionResult: "not-executed"`)               |
+| Enforcement | Controlled runner blocks; does **not** claim IDE interception              |
+| Dashboard   | Loopback by default; non-loopback requires explicit opt-in                 |
+| Team auth   | Local-dev scrypt + optional OIDC JWT validation — **not** full browser SSO |
 
-### Built for developers who care about repository understanding
-
-| Link                                                                           | Purpose                        |
-| ------------------------------------------------------------------------------ | ------------------------------ |
-| [docs/quickstart.md](docs/quickstart.md)                                       | 5-minute path to MCP           |
-| [docs/demo/first-5-minutes.md](docs/demo/first-5-minutes.md)                   | Practical walkthrough          |
-| [docs/demo/architecture-walkthrough.md](docs/demo/architecture-walkthrough.md) | Architecture for evaluators    |
-| [docs/why-agentdoctor.md](docs/why-agentdoctor.md)                             | Why this exists                |
-| [docs/engineering-lessons.md](docs/engineering-lessons.md)                     | Real 1.1.0 engineering lessons |
-| [CONTRIBUTING.md](CONTRIBUTING.md)                                             | Dev setup + gates              |
-| [docs/community/good-first-issues.md](docs/community/good-first-issues.md)     | Starter contributions          |
-| [ROADMAP.md](ROADMAP.md)                                                       | Shipped vs planned             |
-| [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md)                                 | MCP contract                   |
-
-Primary ask: run AgentDoctor on a repository you know well. If the Brain is wrong or incomplete, [file a Brain-quality issue](.github/ISSUE_TEMPLATE/brain-quality.md).
+Threat model: [docs/2.0/overview/security-threat-model.md](docs/2.0/overview/security-threat-model.md) · Trust boundaries: [docs/2.0/overview/trust-boundaries.md](docs/2.0/overview/trust-boundaries.md)
 
 ---
 
-## MCP Quick Start
-
-Configs: [examples/mcp/](examples/mcp/). Use placeholders — never commit machine paths.
-
-**Cursor** ([examples/mcp/cursor.mcp.json](examples/mcp/cursor.mcp.json)):
-
-```json
-{
-  "mcpServers": {
-    "agentdoctor-brain": {
-      "command": "node",
-      "args": [
-        "/ABSOLUTE/PATH/TO/AgentDoctor/dist/cli/index.js",
-        "brain-mcp",
-        "--root",
-        "/ABSOLUTE/PATH/TO/YOUR/PROJECT"
-      ]
-    }
-  }
-}
-```
+## What AgentDoctor does not do
 
-Also: [examples/mcp/claude-code.mcp.json](examples/mcp/claude-code.mcp.json), [examples/mcp/codex.config.toml](examples/mcp/codex.config.toml).
+- Full browser OAuth / production IdP login UX (JWT validation library path exists; redirect flow is experimental)
+- Complete multi-language AST (Java / Kotlin / Rust / Dart / Go extractors external or unsupported)
+- Coverage as universal ground truth without a coverage file / test map
+- IDE / agent process interception (external host APIs)
+- Production multi-tenant cloud / managed hosting in this package
+- Guaranteed autonomous command execution of “allowed” policies
+- Treating inferred C4 / heuristic impact as approved architecture truth
+- Shipping full `docs/2.0.1/` inside the npm tarball (Option B: README + GitHub docs)
 
-Tip: rebuild or ensure a snapshot exists before attaching an agent if the repository is large.
+Full list: [docs/2.0.1/limitations.md](docs/2.0.1/limitations.md) · [docs/2.0/overview/known-limitations.md](docs/2.0/overview/known-limitations.md)
 
 ---
 
-## Design Boundaries
-
-| AgentDoctor IS           | AgentDoctor IS NOT                 |
-| ------------------------ | ---------------------------------- |
-| Repository understanding | Chatbot                            |
-| Structured Project Brain | Generic RAG / AI memory            |
-| Evidence-backed claims   | Autonomous coding agent            |
-| MCP interface            | Vulnerability scanner              |
-| Change-danger analysis   | “Understands every repo perfectly” |
-| Snapshots / deltas       | Zero-hallucination guarantee       |
-
----
-
-## Release 1.1.0
-
-Version verified in `package.json` / `PACKAGE_VERSION`: **1.1.0** (also on npm).
-
-Shipped: Project Brain packaging, `brain-mcp`, ten provenance tools, snapshots/delta, agent validation harness + docs. Safety V1 unchanged.
+## Roadmap note: Change Proof
 
-[docs/release-notes-v1.1.0.md](docs/release-notes-v1.1.0.md) · [CHANGELOG.md](CHANGELOG.md)
+Change assessment, evidence, and proof **integrity** shipped in 2.0.1. `correctnessStatus` is always `ENGINEERING_CORRECTNESS_NOT_CLAIMED`. Broader compliance / team-scale proof UX remains planned.
 
-GitHub Action usage and the intentional CLI `version` default (`1.0.0`): [GitHub Action](#github-action).
+See [ROADMAP.md](ROADMAP.md) · [docs/2.0.1/limitations.md](docs/2.0.1/limitations.md) · [docs/2.0.1/FINAL_COMPLETION_AUDIT.md](docs/2.0.1/FINAL_COMPLETION_AUDIT.md).
 
 ---
 
-## Documentation
-
-| Doc                                                          | Contents                  |
-| ------------------------------------------------------------ | ------------------------- |
-| [docs/quickstart.md](docs/quickstart.md)                     | Developer quickstart      |
-| [docs/project-brain.md](docs/project-brain.md)               | Project Brain model       |
-| [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md)               | MCP contract              |
-| [docs/demo/brain-mcp-demo.md](docs/demo/brain-mcp-demo.md)   | Fixture-backed MCP demo   |
-| [docs/demo/first-5-minutes.md](docs/demo/first-5-minutes.md) | 5-minute walkthrough      |
-| [docs/why-agentdoctor.md](docs/why-agentdoctor.md)           | Product rationale         |
-| [docs/engineering-lessons.md](docs/engineering-lessons.md)   | 1.1.0 engineering lessons |
-| [docs/release-notes-v1.1.0.md](docs/release-notes-v1.1.0.md) | 1.1.0 notes               |
-| [SECURITY.md](SECURITY.md)                                   | Vulnerability reporting   |
-| [ROADMAP.md](ROADMAP.md)                                     | Shipped vs planned        |
-| [docs/README.md](docs/README.md)                             | Full index                |
+## Documentation map
 
----
-
-## Roadmap
-
-From [ROADMAP.md](ROADMAP.md):
-
-| Status         | Focus                                                                             |
-| -------------- | --------------------------------------------------------------------------------- |
-| 🟢 Shipped     | Safety `1.0.x`; Project Brain → MCP → Agent (`1.1.0`)                             |
-| 🟡 Next        | Developer adoption: feedback, Brain quality, docs/ecosystem (not a new Brain API) |
-| 🟡 Planned     | Agent Context layer; change-aware / reliable agent context; Brain Delta workflows |
-| 🔵 Exploratory | CI/PR Brain analysis; team-scale intelligence; additional MCP transports          |
-
-Non-goals: chatbot / RAG memory, autonomous coding agent, vulnerability-scanner replacement, fabricated ownership.
+| Audience                               | Start here                                                                                                                |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Product / 2.0.1                        | [docs/2.0.1/README.md](docs/2.0.1/README.md)                                                                              |
+| Product / 2.0                          | [docs/2.0/README.md](docs/2.0/README.md)                                                                                  |
+| Capabilities / readiness               | [capabilities](docs/2.0/overview/capabilities.md) · [readiness](docs/2.0/overview/readiness-matrix.md)                    |
+| Guides                                 | [docs/2.0/guides/](docs/2.0/guides/)                                                                                      |
+| Reference (rules, scoring, exit codes) | [docs/reference/](docs/reference/)                                                                                        |
+| Contributing                           | [CONTRIBUTING.md](CONTRIBUTING.md) · [docs/development/development.md](docs/development/development.md)                   |
+| Changelog                              | [CHANGELOG.md](CHANGELOG.md)                                                                                              |
+| Release evidence                       | [FINAL_RELEASE_AUDIT](docs/2.0.1/FINAL_RELEASE_AUDIT.md) · [FINAL_COMPLETION_AUDIT](docs/2.0.1/FINAL_COMPLETION_AUDIT.md) |
 
 ---
 
 ## Contributing
 
-[CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [good first issues](docs/good-first-issues.md)
-
-```bash
-git clone https://github.com/pranee54/AgentDoctor.git
-cd AgentDoctor
-npm install
-npm run verify
-```
-
----
-
-## Security
-
-Local analysis. No API key for core Brain/Safety. No default upload. Redacted Brain serialization.
-
-Report privately via [SECURITY.md](SECURITY.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md). Prefer evidence-backed PRs, honest status labels, and no inflated capability claims.
 
 ---
 
 ## License
 
-[MIT](LICENSE) © AgentDoctor Contributors
+MIT — see [LICENSE](LICENSE).