npm - @praneeth_54/agentdoctor - Versions diffs - 1.1.0 → 1.1.1 - Mend

@praneeth_54/agentdoctor 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -9,8 +9,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Notes
-- Owner-only after this tree is green: `npm publish`, git tag `v1.1.0`, GitHub Release.
-  Do **not** auto-publish from CI agents.
+- Vitest 3 → 4/5 major upgrade remains deferred (dev-only moderate advisory).
+- Do **not** auto-publish from CI agents.
+## [1.1.1] — 2026-09-20
+Patch release: Marketplace Action naming + dependency security pins. npm, git tag,
+GitHub Release, and Action default are aligned on **`1.1.1`**.
+### Changed
+- GitHub Action Marketplace display name is now `AgentDoctor Safety`.
+- npm overrides pin patched transitive versions: `js-yaml@4.3.2`, `fast-uri@3.1.8`,
+  `hono@4.13.8`, `qs@6.16.0`.
+- Fixture `fixtures/multi-agent-project` pins `next@15.5.24` (scan fixture only).
+- Action default `version` input and CI smoke pins use `1.1.1`.
+### Security
+- Clears known high/moderate advisories on transitive lint/MCP stack dependencies
+  without changing the Safety CLI public API.
+- Vitest / `@vitest/mocker` moderate advisory deferred (requires major upgrade).
+### Docs
+- [docs/DEPENDENCY_SECURITY_AUDIT.md](docs/DEPENDENCY_SECURITY_AUDIT.md)
+- [docs/DEPENDABOT_PR_REVIEW.md](docs/DEPENDABOT_PR_REVIEW.md)
+- [docs/release-notes-v1.1.1.md](docs/release-notes-v1.1.1.md)
 ## [1.1.0] — 2026-08-13
@@ -273,7 +298,8 @@ First public beta.
 - Not a complete secret scanner
 - Git “tracked secret” detection deferred
-[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/pranee54/AgentDoctor/releases/tag/v1.1.1
 [1.1.0]: https://github.com/pranee54/AgentDoctor/releases/tag/v1.1.0
 [1.0.0]: https://github.com/pranee54/AgentDoctor/releases/tag/v1.0.0
 [0.3.0-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.3.0-beta

package/README.md CHANGED Viewed

@@ -1,280 +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 track: Safety V1 (`1.0.0`) plus Project Brain MCP for agents (`1.1.0`).
-Scan → Fix → Verify → CI remains the Safety contract. Brain MCP helps agents understand
-what is in a repository, what can be trusted, and why — not a generic coding assistant.
+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:
@@ -285,149 +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. The Action default `version` is `1.0.0`. 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)                     | v1 compatibility promises       |
-| [docs/project-brain.md](docs/project-brain.md)                     | Project Brain understanding     |
-| [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md)                     | Brain → MCP → Agent bridge      |
-| [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
-Issues and pull requests are welcome.
+From [ROADMAP.md](ROADMAP.md):
-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
+| 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          |
-```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
-```
+Non-goals: chatbot / RAG memory, autonomous coding agent, vulnerability-scanner replacement, fabricated ownership.
 ---
-## Project Brain MCP (agent context)
+## Contributing
-Evidence-backed repository understanding for agents (not a search MCP):
+[CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [good first issues](docs/good-first-issues.md)
 ```bash
-agentdoctor brain-mcp --root /absolute/path/to/project
+git clone https://github.com/pranee54/AgentDoctor.git
+cd AgentDoctor
+npm install
+npm run verify
 ```
-Tools: overview, query, explain, trace, claims, evidence, ownership, risk, delta, snapshot.
-Local STDIO only — no API key, no upload. Docs: [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md).
-Examples: [examples/mcp/](examples/mcp/).
 ---
-## Next steps
+## Security
+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).
 ---

package/dist/constants.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-export declare const PACKAGE_VERSION = "1.1.0";
+export declare const PACKAGE_VERSION = "1.1.1";
 export declare const DEFAULT_MAX_FILE_SIZE_BYTES: number;
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export declare const DEFAULT_IGNORE_DIRECTORIES: Set<string>;

package/dist/constants.js CHANGED Viewed

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "1.1.0";
+export const PACKAGE_VERSION = "1.1.1";
 export const DEFAULT_MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024; // 2 MiB
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export const DEFAULT_IGNORE_DIRECTORIES = new Set([

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@praneeth_54/agentdoctor",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Audit AI coding agent configuration in a repository — local, deterministic, no API key.",
   "type": "module",
   "bin": {
@@ -84,12 +84,15 @@
     "@types/node": "^22.19.1",
     "eslint": "^9.39.2",
     "prettier": "^3.7.4",
-    "tsx": "^4.21.0",
+    "tsx": "^4.23.13",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.50.0",
+    "typescript-eslint": "^8.70.0",
     "vitest": "^3.2.4"
   },
   "overrides": {
-    "js-yaml": "4.3.1"
+    "js-yaml": "4.3.2",
+    "fast-uri": "3.1.8",
+    "hono": "4.13.8",
+    "qs": "6.16.0"
   }
 }