@praneeth_54/agentdoctor 1.0.0 → 1.1.1

package/README.md

@@ -1,278 +1,418 @@
 # AgentDoctor
 
+Evidence-backed Project Brain 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**.
+
 [![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor?label=npm)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
-[![npm downloads](https://img.shields.io/npm/dm/@praneeth_54/agentdoctor)](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)
+[![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)
 
-**Lighthouse for AI coding agents.**
+[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)
 
-Audit coding-agent configuration before it becomes a repository problem.
+```text
+Repository
+   ↓
+Project Understanding
+   ↓
+Project Brain
+   ↓
+Evidence / Claims / Confidence
+   ↓
+MCP
+   ↓
+AI Coding Agent
+```
 
-AgentDoctor is a local CLI that inspects project-level AI coding agent setup — Cursor, Claude Code, and Codex — for security, instructions, context, and MCP configuration. Deterministic static analysis. No API key. No code upload by default.
+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.
 
-```bash
-npx @praneeth_54/agentdoctor
-```
+---
+
+## What is AgentDoctor?
+
+Local developer infrastructure for AI coding agents (`@praneeth_54/agentdoctor`, CLI `agentdoctor`, **1.1.0**, Node.js **20+**).
 
-Public release (`1.0.0`). Scan → Fix → Verify → CI. Deterministic scores in the terminal and JSON.
+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>`)
+
+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.
 
 ---
 
-## What you get
+## Why Project Brain?
 
-![AgentDoctor scanning a repository and reporting coding-agent security findings](docs/images/cli-scan.png)
+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.
 
-_Real scan of the included `insecure-agent-project` fixture using AgentDoctor v1.0.0._
+Project Brain structures understanding that exists in this codebase:
 
-```text
-$ npx @praneeth_54/agentdoctor
+architecture · domains · components · entrypoints · dependencies · relationships · ownership · change-danger risks · claims · evidence · confidence · snapshots · deltas
 
-🩺 AgentDoctor v1.0.0
+Details: [docs/project-brain.md](docs/project-brain.md)
 
-Scanning repository...
+---
 
-Repository
-  Framework: Node.js
-  Language: JavaScript
-  Package manager: npm
-  Files scanned: 7
+## Architecture
+
+![Architecture](docs/assets/architecture.svg)
+
+| 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` |
 
-AI Coding Agents
+MCP depends on Brain. Brain does not depend on MCP.
 
-✓ Cursor       configured
-✓ Claude Code  configured
-✓ Codex        configured
+---
 
-Findings
+## Project Brain
 
-CRITICAL
+![Provenance](docs/assets/provenance.svg)
 
-  ✗ Sensitive environment file may enter agent context
-    .env
-    Affected: Claude Code, Codex
-    Fix: Add an agent-specific exclusion (for example .cursorignore or a
-         Claude Code Read deny rule), keep the file out of version control,
-         and rotate any credentials that may have been exposed.
+### Evidence & provenance
 
-  ✗ Private key or credential file present in repository
-    test-private-key.pem
-    Affected: Claude Code, Codex, Cursor
+```text
+Claim
+  ↓
+Evidence
+  ↓
+Snapshot
+```
 
-WARNING
+Successful MCP tools return a provenance envelope: `result`, `evidenceIds`, `confidence` (`[0,1]`, rule-derived / uncalibrated), `snapshot` (`id` + `contentHash`), and `claimStatus` when applicable.
 
-  ! Claude Code bypassPermissions mode enabled
-    .claude/settings.json
+Claim lifecycle: `ACTIVE` · `INVALIDATED` · `SUPERSEDED` · `CONTRADICTED`
 
-Summary
+Epistemics on evidence: `observed` | `inferred`. ACTIVE claims must reference evidence. Serialization redacts secret-like values.
 
-  3 critical
-  1 warning
-  0 info
+### UNKNOWN semantics
 
-  Readiness: 13/100
-  Category and agent scores: agentdoctor scan --json
+```text
+Ownership evidence unavailable
+        ↓
+     UNKNOWN
 ```
 
-Abbreviated text example from the same fixture for accessibility and search. Secret values are never printed. Re-run the scan if counts change.
+No invented owners. Contract: `preserve-unknown-never-invent`.
+
+Local runtime store (not committed product source): `<repo>/.agentdoctor/project-brain/`.
 
 ---
 
-## Why AgentDoctor?
+## MCP
 
-Repositories accumulate agent configuration quickly:
+![MCP tools](docs/assets/mcp-tools.svg)
 
-- Multiple instruction formats (`.cursor/rules`, `CLAUDE.md`, `AGENTS.md`)
-- Stale path references in always-on instructions
-- Ignore differences between `.gitignore`, `.cursorignore`, and agent defaults
-- MCP filesystem scopes that are broader than intended
-- Generated directories and large logs that waste context
-- Credential-like files that may be readable by agents
-- Conflicting assumptions about what each agent can see
+```text
+AI Coding Agent → MCP client → agentdoctor brain-mcp --root <abs> → Project Brain
+```
 
-Manually reviewing all of that across Cursor, Claude Code, and Codex is slow and inconsistent. AgentDoctor provides one deterministic local audit with stable rule IDs, evidence paths, and affected-agent information.
+STDIO only. No API key. No upload. `--root` is required. Diagnostics on **stderr**; protocol on **stdout**.
 
-| Analogy         | Domain                           |
-| --------------- | -------------------------------- |
-| Lighthouse      | Web pages                        |
-| `npm audit`     | Dependencies                     |
-| ESLint          | Source code                      |
-| **AgentDoctor** | **AI coding agent environments** |
+### Tools (from `src/mcp/brain/tools/registry.ts`)
 
-AgentDoctor analyzes configuration. It does not run agents or call an LLM. `agentdoctor fix` may append safe context exclusions (Cursor `.cursorignore`, Claude Code Read deny rules, and Codex filesystem deny keys); it does not rewrite secrets, credentials, or security modes such as `bypassPermissions`.
+| 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` |
 
----
+Only controlled write: `brain_snapshot` `rebuild` under `<root>/.agentdoctor/project-brain/`.
 
-## Before / after
+Contract: [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md)
 
-**Before**
+---
+
+## Real Cursor Agent Validation
 
-A repository may contain:
+![Agent validation](docs/assets/agent-validation.svg)
 
 ```text
-.cursor/rules/
-AGENTS.md
-CLAUDE.md
-.claude/settings.json
-.mcp.json
-.env
+Cursor Agent
+    ↓
+MCP discovery (agentdoctor-brain)
+    ↓
+brain_* tool call
+    ↓
+Project Brain
+    ↓
+Evidence-backed result (+ provenance)
 ```
 
-Potential problems stay invisible until something leaks into model context, CI, or a teammate’s agent session:
+Harness: `validation/mcp-agent` on `fixtures/understanding-dependencies-project`.
 
-- environment or credential-like files reachable by agents
-- stale instruction path references
-- broad MCP filesystem access
-- oversized always-on context
+| 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`                   |
 
-**Run**
+Documented harness results ([validation/mcp-agent/README.md](validation/mcp-agent/README.md), 2026-08-13, AgentDoctor 1.1.0):
 
-```bash
-npx @praneeth_54/agentdoctor
-```
+- 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
+
+Checks include grounding, UNKNOWN ownership guard, risk semantics, provenance, snapshot/delta semantics — not “zero hallucinations.”
 
-**After**
+Demo: [docs/demo/brain-mcp-demo.md](docs/demo/brain-mcp-demo.md)
+
+---
 
-You get deterministic findings with:
+## Built Through Real Validation
 
-- stable rule IDs (for example `security/env-file-exposure`)
-- evidence paths
-- affected agents when exposure claims are supported
-- conservative recommendations
-- readiness score (`scores.overall` in JSON; overall line in the terminal)
+1.1.0 was hardened under real MCP, CI, and Windows pressure — not README theater.
 
-Safe context exclusions (Cursor / Claude Code / Codex) can be applied with `agentdoctor fix`. Security and review findings stay manual — Fix explains why and does not invent unsafe edits.
+| 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.                                                                                                                                                                               |
 
 ---
 
-## Quick start
+## Repository Structure
 
-### One-shot (recommended)
+![Repository layout](docs/assets/repository-architecture.svg)
 
-```bash
-npx @praneeth_54/agentdoctor
+```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
 ```
 
-Pin a version when you need a fixed install:
+Do not treat `.agentdoctor/` or project-local agent config dirs as committed AgentDoctor source.
 
-```bash
-npx @praneeth_54/agentdoctor@1.0.0
-```
+---
+
+## Validation
 
-### Global (optional)
+![Validation pipeline](docs/assets/validation-pipeline.svg)
 
 ```bash
-npm install -g @praneeth_54/agentdoctor
-agentdoctor
+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
 ```
 
-### Scan → Fix → Verify
-
-```bash
-# 1. Scan (save a baseline for Verify)
-npx @praneeth_54/agentdoctor scan . --json > agentdoctor-report.json
+| 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                                                    |
 
-# 2. Fix safe context exclusions (preview first with --dry-run)
-npx @praneeth_54/agentdoctor fix . --dry-run
-npx @praneeth_54/agentdoctor fix . -y
+Re-run the commands above for live status; do not treat this table as a substitute for CI.
 
-# 3. Verify against the baseline
-npx @praneeth_54/agentdoctor verify . --baseline agentdoctor-report.json
-```
+---
 
-`fix` writes safe context exclusions for Cursor (`.cursorignore`), Claude Code
-(`permissions.deny` Read rules in `.claude/settings.json`), and Codex (filesystem `deny`
-keys under a permissions profile in `.codex/config.toml`) for findings such as unignored
-`build/` or large logs. Review/manual security findings are listed as skipped — address those
-yourself, then re-run `verify`.
+## Installation
 
-### Common commands
+```bash
+npx @praneeth_54/agentdoctor@1.1.1
+# or
+npm install -g @praneeth_54/agentdoctor
+agentdoctor --help
+```
 
 ```bash
+agentdoctor brain-mcp --root /ABSOLUTE/PATH/TO/YOUR/PROJECT
+
 agentdoctor .
 agentdoctor scan . --json
 agentdoctor fix . --dry-run
-agentdoctor verify . --ci --baseline agentdoctor-report.json
+agentdoctor verify . --baseline agentdoctor-report.json
 agentdoctor explain security/env-file-exposure
 agentdoctor doctor
 ```
 
-Package name: `@praneeth_54/agentdoctor` (npm blocks the unscoped name). CLI binary: `agentdoctor`. Requires **Node.js 20+**.
+---
+
+## GitHub Action
 
-### Programmatic API
+AgentDoctor can run repository-level AI coding-agent configuration audits inside GitHub Actions and enforce CI policy gates.
 
-```bash
-npm install @praneeth_54/agentdoctor
-```
+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).
 
-```ts
-import { scan, verify, buildFixPlan, applyFixPlan } from "@praneeth_54/agentdoctor";
+Recommended pin:
 
-const result = await scan({ cwd: process.cwd() });
-console.log(result.summary);
-console.log(result.scores?.overall);
-console.log(result.agentSecurityAnalysis); // "full" | "limited"
+```yaml
+uses: pranee54/AgentDoctor@v1.1.0
 ```
 
----
+For maximum supply-chain pinning, pin a full commit SHA of this repository. Do not use `@main`.
 
-## Supported agents
+### CLI version default (intentional)
 
-Project-level configuration only (repository files). Global user settings are not scanned.
+| Surface                            | Value                                        |
+| ---------------------------------- | -------------------------------------------- |
+| Action release tag                 | `v1.1.0` (this repository’s Action metadata) |
+| Action input `version` **default** | **`1.0.0`**                                  |
 
-| Agent           | What AgentDoctor inspects                                              |
-| --------------- | ---------------------------------------------------------------------- |
-| **Cursor**      | `.cursor/rules/*.mdc`, `.cursorignore`, Cursor MCP config, `AGENTS.md` |
-| **Claude Code** | `CLAUDE.md`, `.claude/settings*.json`, `.claude/rules`, MCP config     |
-| **Codex**       | `AGENTS.md` / overrides, project `.codex/` configuration               |
+The `v1.1.0` Action release still defaults to the published AgentDoctor **CLI `1.0.0`** for compatibility. That is intentional.
 
-Additional adapters are planned — see [ROADMAP.md](ROADMAP.md).
+- 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.
 
-## Finding categories
+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`).
 
-| Category         | Examples                                                              |
-| ---------------- | --------------------------------------------------------------------- |
-| **Security**     | Env-file exposure, private-key filenames, broad MCP filesystem scopes |
-| **Context**      | Large instruction files, large logs, unignored generated directories  |
-| **Instructions** | Empty instructions, duplicate content, missing path references        |
-| **MCP**          | Malformed MCP config, high-risk filesystem path arguments             |
+### Examples
 
-Full catalog with severities and fixability: [docs/rules.md](docs/rules.md).
+**1. Basic scan** (report-only; default CLI `1.0.0`):
 
-Explain any rule:
+```yaml
+permissions:
+  contents: read
 
-```bash
-npx @praneeth_54/agentdoctor explain security/env-file-exposure
+steps:
+  - uses: actions/checkout@v4
+
+  - name: Audit coding-agent configuration
+    id: agentdoctor
+    uses: pranee54/AgentDoctor@v1.1.0
+    with:
+      path: .
 ```
 
----
+**2. Minimum readiness score:**
 
-## Privacy and trust
+```yaml
+- uses: pranee54/AgentDoctor@v1.1.0
+  with:
+    path: .
+    minimum-score: "70"
+```
 
-**Scans run locally on your machine.**
+**3. Severity gate:**
 
-AgentDoctor:
+```yaml
+- uses: pranee54/AgentDoctor@v1.1.0
+  with:
+    path: .
+    fail-on-severity: critical
+```
 
-- does not require an API key
-- does not upload repository contents by default
-- does not call an LLM for core scanning
-- does not execute MCP servers
-- does not execute project code
-- never prints secret values from files it flags by name
-- enforces repository boundary checks for path references and symlink escape
+**4. Rule gate:**
 
-This is still software that reads untrusted repository trees. Treat findings as guidance, not a security certification. AgentDoctor is **not** a complete secret-content scanner.
+```yaml
+- uses: pranee54/AgentDoctor@v1.1.0
+  with:
+    path: .
+    fail-on-rule: security/env-file-exposure
+```
 
----
+**5. Baseline verification:**
 
-## CI usage
+```yaml
+- uses: pranee54/AgentDoctor@v1.1.0
+  with:
+    path: .
+    verify-baseline: agentdoctor-report.json
+    fail-on-new: "true"
+```
 
-### GitHub Action
+**6. JSON report** (default `json-output: "true"`; customize path):
 
-Run AgentDoctor directly in a workflow:
+```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:
@@ -283,148 +423,219 @@ steps:
 
   - name: Audit coding-agent configuration
     id: agentdoctor
-    uses: pranee54/AgentDoctor@v1.0.0
+    uses: pranee54/AgentDoctor@v1.1.0
     with:
       path: .
-      version: "1.0.0"
+      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 }}
 ```
 
-Policy inputs: `minimum-score`, `fail-on-severity`, `fail-on-rule`, `fail-on-new`,
-`verify-baseline`, `summary`, `annotations`. The Action stays report-only until you set a
-policy input. Explicitly set `version: "1.0.0"` after npm publish (the Action default remains
-`0.3.0-beta` until that post-publish bump). For local CI against this repo, use
-`version: workspace` after `npm run build`. The action installs `@praneeth_54/agentdoctor`,
-runs scan (or `verify` when `verify-baseline` is set) with `--json`, and writes the report
-inside the workspace.
+### Inputs
 
-### CLI
+From [`action.yml`](action.yml):
 
-Use JSON directly in other CI systems:
+| 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).                                                                |
 
-```bash
-# Report-only (exit 0 even when findings exist; scores still in JSON)
-npx @praneeth_54/agentdoctor --json
+### Outputs
 
-# Fail when any critical finding exists
-npx @praneeth_54/agentdoctor --ci --json
+| 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.             |
 
-# Fail when overall readiness is below 70 (with --ci also fails on criticals)
-npx @praneeth_54/agentdoctor --ci --json --min-score 70
+| `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.                  |
 
-# Fail on warning-or-higher (overrides the default critical gate from --ci)
-npx @praneeth_54/agentdoctor --ci --json --fail-on-severity warning
-```
+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`:
 
-`--ci` fails when any **critical** finding exists. Override the severity floor with
-`--fail-on-severity`, and use `--min-score` / `--fail-on-rule` for additional gates.
-Omit `--ci` for report-only JSON (exit `0` even when findings exist).
+- 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
 
-Exit codes: [docs/exit-codes.md](docs/exit-codes.md). Compatibility promises: [docs/compatibility.md](docs/compatibility.md).
+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.
 
-### Readiness scoring
+Related: [SECURITY.md](SECURITY.md)
 
-Scans populate `scoringAvailable: true` and a deterministic `scores` object
-(overall, categories, agents). The terminal prints overall readiness; category and agent
-scores are in JSON (`--json`).
+### Action versioning
 
-`--min-score N` is enforced by the CLI. Details (weights, security caps, threshold rules,
-and deferred v2 items): [docs/scoring.md](docs/scoring.md).
+| 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.
 
 ---
 
-## Known limitations
+## Try it yourself
 
-Honest limits of v1:
+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)
 
-| Limitation                  | Status                                                                          |
-| --------------------------- | ------------------------------------------------------------------------------- |
-| Automatic fixes             | Safe Cursor / Claude Code / Codex context exclusions only                       |
-| Security findings           | Review/manual — Fix does not rewrite secrets or security modes                  |
-| Secret-content scanning     | Filename / config heuristics only                                               |
-| Detection style             | Intentionally conservative; false security findings are avoided                 |
-| Agent coverage              | Cursor, Claude Code, Codex project configs                                      |
-| Missing-path residual noise | Broad path-lattice expansion deferred; instruction-directory resolution shipped |
+### Built for developers who care about repository understanding
 
-See [CHANGELOG.md](CHANGELOG.md) and [docs/compatibility.md](docs/compatibility.md).
+| 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).
 
-## Architecture
+---
 
-```text
-Discovery → Project detect → Agent adapters → Rule engine → Findings → Scores → Terminal / JSON
+## 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"
+      ]
+    }
+  }
+}
 ```
 
-Details: [docs/architecture.md](docs/architecture.md)
+Also: [examples/mcp/claude-code.mcp.json](examples/mcp/claude-code.mcp.json), [examples/mcp/codex.config.toml](examples/mcp/codex.config.toml).
+
+Tip: rebuild or ensure a snapshot exists before attaching an agent if the repository is large.
+
+---
+
+## 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.
+
+[docs/release-notes-v1.1.0.md](docs/release-notes-v1.1.0.md) · [CHANGELOG.md](CHANGELOG.md)
+
+GitHub Action usage and the intentional CLI `version` default (`1.0.0`): [GitHub Action](#github-action).
 
 ---
 
 ## Documentation
 
-| Doc                                                                | Contents                        |
-| ------------------------------------------------------------------ | ------------------------------- |
-| [docs/README.md](docs/README.md)                                   | Documentation index             |
-| [docs/architecture.md](docs/architecture.md)                       | Scan pipeline                   |
-| [docs/rules.md](docs/rules.md)                                     | Stable rule IDs                 |
-| [docs/exit-codes.md](docs/exit-codes.md)                           | Process exit codes              |
-| [docs/scoring.md](docs/scoring.md)                                 | Readiness scoring specification |
-| [docs/compatibility.md](docs/compatibility.md)                     | Beta compatibility promises     |
-| [docs/development.md](docs/development.md)                         | Local development               |
-| [docs/github-launch-checklist.md](docs/github-launch-checklist.md) | GitHub About / topics / launch  |
-| [ROADMAP.md](ROADMAP.md)                                           | Near- and medium-term plans     |
-| [CHANGELOG.md](CHANGELOG.md)                                       | Release history                 |
+| 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                |
 
 ---
 
-## Contributing
+## Roadmap
+
+From [ROADMAP.md](ROADMAP.md):
 
-Issues and pull requests are welcome.
+| 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          |
 
-1. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md)
-2. Prefer [good first issues](docs/good-first-issues.md) ideas
-3. Report security issues via [SECURITY.md](SECURITY.md) — never paste real secrets into issues
+Non-goals: chatbot / RAG memory, autonomous coding agent, vulnerability-scanner replacement, fabricated ownership.
+
+---
+
+## 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
-node dist/cli/index.js ./fixtures/clean-configured-project
 ```
 
 ---
 
-## Project Brain (separate laboratory capability)
-
-AgentDoctor V1 ships the **safety** product: Scan → Fix → Verify → Policy → CI.
-
-A parallel **Project Brain** engineering layer lives under `src/core/understanding/` (durable local claims, evidence, snapshots, query/trace/delta). It is:
-
-- **not** part of the published npm package (`tsconfig.build` excludes it)
-- **not** wired into the public CLI
-- documented in [docs/project-brain.md](docs/project-brain.md)
-
-See [PROJECT_AUDIT.txt](PROJECT_AUDIT.txt) and [RELEASE_CHECKLIST.txt](RELEASE_CHECKLIST.txt).
-
----
+## Security
 
-## Next steps
+Local analysis. No API key for core Brain/Safety. No default upload. Redacted Brain serialization.
 
-- **Try it:** `npx @praneeth_54/agentdoctor`
-- **Report a false positive / false negative:** use the issue templates (include version, rule ID, anonymized evidence — no secrets)
-- **Propose a rule or adapter:** [feature request](.github/ISSUE_TEMPLATE/feature_request.md) / [rule proposal](.github/ISSUE_TEMPLATE/rule_proposal.md)
-- **Contribute:** [CONTRIBUTING.md](CONTRIBUTING.md)
-- **Useful?** Star or watch the repository so you see updates
+Report privately via [SECURITY.md](SECURITY.md).
 
 ---