eslint-plugin-ai-guard 1.3.0 → 1.4.0

package/README.md

@@ -1,457 +1,683 @@
-<p align="center">
-  <img src="./assets/logo.png" alt="AI Guard Logo" width="80" />
-  <h1 align="center">eslint-plugin-ai-guard</h1>
-  <p align="center">
-    <strong>🛡️ GitHub-native guardrails for AI-generated code.</strong>
-  </p>
-  <p align="center">
-    <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><img src="https://img.shields.io/npm/v/eslint-plugin-ai-guard.svg?style=flat-square&color=7c3aed" alt="npm version"></a>
-    <a href="https://github.com/YashJadhav21/eslint-plugin-ai-guard/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YashJadhav21/eslint-plugin-ai-guard/ci.yml?style=flat-square&label=CI&color=10b981" alt="CI"></a>
-    <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><img src="https://img.shields.io/npm/dm/eslint-plugin-ai-guard.svg?style=flat-square&color=3b82f6" alt="downloads"></a>
-    <a href="https://github.com/YashJadhav21/eslint-plugin-ai-guard/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/eslint-plugin-ai-guard.svg?style=flat-square&color=64748b" alt="MIT License"></a>
-    <a href="https://github.com/YashJadhav21/eslint-plugin-ai-guard/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/security-policy-orange?style=flat-square" alt="Security Policy"></a>
-  </p>
-</p>
-
----
-
-## What is ai-guard?
-
-**ai-guard** is an ESLint plugin and GitHub Action that catches reliability and security bugs
-specific to AI-generated code — the patterns Copilot, Claude, Cursor, and Gemini consistently get wrong.
-
-It integrates directly into GitHub pull request workflows: blocking dangerous merges, generating
-SARIF reports for GitHub Code Scanning, and posting inline PR annotations at the exact line where
-the bug lives.
-
-```bash
-# Scan immediately — no config needed
-npx ai-guard run
-
-# PR-aware changed-only scan with GitHub Advanced Security
-npx ai-guard changed --sarif --sarif-output results.sarif
-```
-
-  <img src="./assets/ss8.jpg" alt="GitHub PR Inline Annotations by AI Guard" width="1000" />
-
----
-
-## The Problem
-
-AI coding assistants generate code that **looks correct but isn't.** The patterns they get wrong
-are consistent, predictable, and existing linters don't catch them:
-
-| Pattern | Why AI Gets It Wrong |
-|---------|---------------------|
-| `try {} catch (e) {}` | AI adds catch blocks without handling the error |
-| `array.map(async ...)` | AI generates async callbacks returning `Promise[]`, not values |
-| `fetch(url)` without await | AI forgets to await or handle promise rejection |
-| `const apiKey = 'sk-...'` | AI uses placeholder credentials that get committed |
-| `eval(userInput)` | AI generates dynamic evaluation without security context |
-| `if (true) { ... }` | AI leaves dead scaffolding branches in generated code |
-
-ai-guard is purpose-built to catch what AI tools consistently get wrong — before those bugs reach production.
-
----
-
-## Install
-
-```bash
-npm install --save-dev eslint-plugin-ai-guard
-```
-
-**Requirements:** Node.js ≥ 18 · ESLint ≥ 8
-
----
-
-## Quick Start
-
-```bash
-# Zero-config project scan
-npx ai-guard run
-
-# Security-focused scan
-npx ai-guard run --security
-
-# Strict mode — all 18 rules at error
-npx ai-guard run --strict
-
-# Scan only changed files (PR-aware)
-npx ai-guard changed --pr
-```
-
-**No configuration required.** ai-guard ships with a production-tuned `recommended` preset.
-
----
-
-## GitHub Actions Integration
-
-Drop this into any repository to get PR validation, SARIF-based Code Scanning, and
-GitHub Advanced Security integration in under 5 minutes:
-
-```yaml
-# .github/workflows/ai-guard.yml
-name: AI Guard
-
-on: [pull_request]
-
-permissions:
-  security-events: write
-  contents: read
-
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Required for changed-file detection
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'npm'
-
-      - run: npm ci
-
-      - name: Scan changed files
-        run: |
-          npx ai-guard changed \
-            --pr \
-            --strict \
-            --sarif \
-            --sarif-output ai-guard-results.sarif \
-            --fail-on high
-
-      - name: Upload to GitHub Code Scanning
-        uses: github/codeql-action/upload-sarif@v3
-        if: always()
-        with:
-          sarif_file: ai-guard-results.sarif
-          category: ai-guard
-```
-
-This produces:
-- ✅ Inline PR annotations at the exact line of each finding
-- ✅ GitHub Advanced Security summary ("17 new alerts including 3 high severity")
-- ✅ Persistent alerts in `Security → Code scanning`
-- ✅ PR status check that blocks merges on high-severity findings
-
-### Inline PR Annotations
-<img src="./assets/ss9.jpg" alt="AI Guard PR Inline Annotations" width="1000" />
-
-### GitHub Advanced Security Summary
-<img src="./assets/ss10.jpg" alt="GitHub Advanced Security Summary for AI Guard" width="1000" />
-
-### GitHub Code Scanning Alerts
-<img src="./assets/ss11.jpg" alt="GitHub Code Scanning Alerts List" width="1000" />
-
-See [`docs/github-actions.md`](./docs/github-actions.md) for the complete workflow reference
-including full-scan mode, baseline mode, and SARIF debugging.
-
----
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `ai-guard run` | Scan your project with the recommended preset |
-| `ai-guard run --strict` | All 18 rules at error — for CI enforcement |
-| `ai-guard run --security` | Security rules only |
-| `ai-guard run --sarif` | Output SARIF for GitHub Code Scanning |
-| `ai-guard run --json` | Output results as JSON (CI-friendly) |
-| `ai-guard changed --pr` | Scan only files changed in this PR |
-| `ai-guard changed --staged` | Scan only staged files (pre-commit hook) |
-| `ai-guard init` | Auto-configure ESLint + workflow + agent context |
-| `ai-guard init --yes` | Zero-prompt setup — recommended for CI/scripts |
-| `ai-guard init-context` | Generate AI agent rules (CLAUDE.md, .cursorrules, etc.) |
-| `ai-guard baseline` | Save current issues, track only new ones going forward |
-| `ai-guard report` | Generate a shareable HTML report |
-| `ai-guard doctor` | Diagnose your ESLint and ai-guard setup |
-
-### Fail Strategies
-
-```bash
---fail-on errors   # Fail on any error-level finding (default)
---fail-on high     # Fail only on high-severity findings
---fail-on none     # Never fail — always continue
---max-warnings 0   # Fail on any warning
-```
-
-### Example Output
-
-```
-  AI GUARD
-
-  Files scanned:  142  ·  Issues in:  7 files  ·  Duration:  312ms  ·  Preset:  strict
-
-  ── Summary by Category ──
-
-  🔴  Security            3 errors
-  🟠  Reliability         2 errors
-  🟡  Async Stability     2 warnings
-
-  Total: 5 errors · 2 warnings
-
-  ── By Rule ──
-    • no-hardcoded-secret: 3
-    • no-empty-catch: 2
-    • no-floating-promise: 2
-
-  ── Next Steps ──
-  ℹ  Run ai-guard baseline to save these issues and track only new ones
-  ℹ  Run ai-guard report   to generate a shareable HTML report
-```
-
----
-
-## Rules
-
-### 🔴 Security
-
-| Rule | Recommended | What it catches |
-|------|------------|------------------|
-| [`no-hardcoded-secret`](./docs/rules/no-hardcoded-secret.md) | **error** | API keys, passwords, tokens in source. Autofix: `process.env.*` |
-| [`no-eval-dynamic`](./docs/rules/no-eval-dynamic.md) | **error** | `eval()` / `new Function()` with non-literal args |
-| [`no-sql-string-concat`](./docs/rules/no-sql-string-concat.md) | warn | SQL built by string concatenation — SQL injection risk |
-| [`no-unsafe-deserialize`](./docs/rules/no-unsafe-deserialize.md) | warn | `JSON.parse(req.body)` without validation |
-| [`require-auth-middleware`](./docs/rules/require-auth-middleware.md) | warn | Express/Fastify routes without authentication middleware |
-| [`require-authz-check`](./docs/rules/require-authz-check.md) | warn | Resource access without ownership checks |
-
-### 🟠 Reliability
-
-| Rule | Recommended | What it catches |
-|------|------------|------------------|
-| [`no-empty-catch`](./docs/rules/no-empty-catch.md) | **error** | `catch (e) {}` — errors silently vanish. Autofix: inserts TODO |
-| [`no-broad-exception`](./docs/rules/no-broad-exception.md) | warn | `catch (e: any)` that hides the real error type |
-| [`no-catch-log-rethrow`](./docs/rules/no-catch-log-rethrow.md) | off* | Catch blocks that only `console.log` + rethrow |
-| [`no-catch-without-use`](./docs/rules/no-catch-without-use.md) | off* | Caught error variable never used |
-
-### 🟡 Async Stability
-
-| Rule | Recommended | What it catches |
-|------|------------|------------------|
-| [`no-floating-promise`](./docs/rules/no-floating-promise.md) | **error** | Async calls with no `await`, return, or `.catch()`. Autofix: adds `void` |
-| [`no-async-array-callback`](./docs/rules/no-async-array-callback.md) | warn | `array.map(async ...)` — returns `Promise[]` not values |
-| [`no-await-in-loop`](./docs/rules/no-await-in-loop.md) | warn | Sequential `await` in loops — use `Promise.all` |
-| [`no-async-without-await`](./docs/rules/no-async-without-await.md) | warn | `async` function that never uses `await` |
-| [`no-redundant-await`](./docs/rules/no-redundant-await.md) | off* | `return await` outside try/catch |
-
-### 🔵 AI Patterns
-
-| Rule | Recommended | What it catches |
-|------|------------|------------------|
-| [`no-dead-branch`](./docs/rules/no-dead-branch.md) | warn | `if (true)`, `if (false)`, `x && !x` — scaffolding leftovers |
-| [`no-duplicate-logic-block`](./docs/rules/no-duplicate-logic-block.md) | off* | Consecutive duplicate code blocks |
-| [`no-console-in-handler`](./docs/rules/no-console-in-handler.md) | off* | `console.log` in route handlers — use a logger |
-
-*Enabled at `error` in the `strict` preset.
-
-Full rule documentation: [`docs/rules/`](./docs/rules/)
-
----
-
-## Presets
-
-| Preset | Purpose | Best For |
-|--------|---------|----------|
-| `recommended` | Critical issues at `error`, context-sensitive at `warn` | All projects on day one |
-| `strict` | All 18 rules at `error` | CI enforcement in mature codebases |
-| `security` | Security rules only | Security-focused scanning |
-
-### ESLint Flat Config
-
-```javascript
-// eslint.config.mjs
-import aiGuard from 'eslint-plugin-ai-guard';
-
-export default [
-  {
-    plugins: { 'ai-guard': aiGuard },
-    rules: { ...aiGuard.configs.recommended.rules },
-  },
-];
-```
-
----
-
-## AI Agent Integration
-
-Generate instruction files so **Claude Code, Cursor, and GitHub Copilot** automatically avoid
-the 18 most common AI-generated anti-patterns at generation time:
-
-```bash
-npx ai-guard init-context
-```
-
-This writes:
-- `CLAUDE.md` — loaded automatically by Claude Code
-- `.cursorrules` — loaded automatically by Cursor
-- `.github/copilot-instructions.md` — loaded automatically by GitHub Copilot
-
-Your AI tools will avoid these patterns **before you even run the linter.**
-
-See [`docs/ai-agents.md`](./docs/ai-agents.md) for the complete integration guide.
-
----
-
-## Real-World Example
-
-```typescript
-// ❌ Typical AI-generated code — 4 issues in one function
-async function processUserOrders(userId: string) {
-  const apiKey = 'sk-prod-1234567890abcdef';  // no-hardcoded-secret
-
-  const orders = await db.query(
-    'SELECT * FROM orders WHERE id = ' + userId  // no-sql-string-concat
-  );
-
-  for (const order of orders) {
-    await sendEmail(order.email);  // no-await-in-loop
-  }
-
-  updateAnalytics(userId);  // no-floating-promise
-}
-
-// ✅ After ai-guard fixes
-async function processUserOrders(userId: string) {
-  const apiKey = process.env.API_KEY;
-
-  const orders = await db.query(
-    'SELECT * FROM orders WHERE id = $1', [userId]
-  );
-
-  await Promise.all(orders.map(async (order) => sendEmail(order.email)));
-
-  void updateAnalytics(userId);
-}
-```
-
----
-
-## Autofix Support
-
-```bash
-npx eslint src --fix
-```
-
-| Rule | What Gets Fixed |
-|------|-----------------|
-| `no-hardcoded-secret` | Literal → `process.env.VAR_NAME` |
-| `no-empty-catch` | Inserts `/* TODO: handle error */` |
-| `no-floating-promise` | Marks with `void` |
-| `no-await-in-loop` | Rewrites simple loops to `Promise.all(...)` |
-| `no-async-without-await` | Removes unnecessary `async` keyword |
-
----
-
-## Philosophy
-
-- **Precision over recall** — we'd rather miss a bug than create noise
-- **Low false positives** — a rule that fires on valid code goes to `warn` or gets disabled
-- **Gradual adoption** — `recommended` is safe for day-one; `strict` is opt-in
-- **Self-validating** — ai-guard scans its own source in CI with the strict preset
-- **GitHub-native** — SARIF output, Code Scanning, PR annotations are first-class features
-
----
-
-## Development
-
-```bash
-git clone https://github.com/YashJadhav21/eslint-plugin-ai-guard.git
-cd eslint-plugin-ai-guard
-npm install
-npm run test         # 678 tests across 39 test files
-npm run build        # Build CJS + ESM bundles
-npm run typecheck    # TypeScript strict check
-npm run lint:self    # Scan own source with ai-guard
-npm run lint:full    # Strict scan of src/ + cli/
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.
-
----
-
-## Documentation
-
-| Doc | Purpose |
-|-----|---------|
-| [`docs/github-actions.md`](./docs/github-actions.md) | GitHub Actions workflow reference |
-| [`docs/ai-agents.md`](./docs/ai-agents.md) | AI agent integration guide |
-| [`docs/architecture.md`](./docs/architecture.md) | Architecture and internals |
-| [`docs/benchmarks.md`](./docs/benchmarks.md) | Benchmarks vs ESLint, @typescript-eslint |
-| [`docs/rules/`](./docs/rules/) | Per-rule documentation |
-| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | Contribution guide |
-| [`SECURITY.md`](./SECURITY.md) | Security policy |
-| [`CHANGELOG.md`](./CHANGELOG.md) | Release history |
-| [`ROADMAP.md`](./ROADMAP.md) | Planned features |
-
----
-
-## FAQ
-
-<details>
-<summary><strong>Is ai-guard a replacement for ESLint?</strong></summary>
-
-No. ai-guard runs *on top of* ESLint. It adds 18 rules specifically tuned for AI-generated
-code patterns. Your existing ESLint rules continue to work as normal.
-</details>
-
-<details>
-<summary><strong>Does ai-guard require TypeScript type information?</strong></summary>
-
-No. All rules use AST heuristics, not type analysis. This makes ai-guard faster than
-type-aware linters and zero-config for JavaScript projects. See
-[benchmarks](./docs/benchmarks.md) for performance comparison.
-</details>
-
-<details>
-<summary><strong>Will ai-guard slow down my CI?</strong></summary>
-
-Typically adds 1–2 seconds to a CI run. Changed-only mode (`ai-guard changed --pr`)
-is even faster because it only scans files modified in the PR.
-</details>
-
-<details>
-<summary><strong>How do I reduce false positives?</strong></summary>
-
-Start with `recommended` preset (default). The `strict` preset enables all rules,
-which may be noisy for some codebases. You can also:
-- Use `ai-guard baseline` to ignore pre-existing issues
-- Configure per-rule options (e.g., `allowedLoggers` for `no-console-in-handler`)
-- Use `// eslint-disable-next-line ai-guard/rule-name` for intentional overrides
-</details>
-
-<details>
-<summary><strong>Does ai-guard work with Copilot / Cursor / Claude Code?</strong></summary>
-
-Yes — in two ways:
-1. **Lint after generation**: ai-guard catches issues after AI generates code
-2. **Prevent before generation**: `ai-guard init-context` creates instruction files
-   (CLAUDE.md, .cursorrules) that teach AI agents to avoid these patterns
-</details>
-
----
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---------|-----|
-| `Cannot find module 'eslint-plugin-ai-guard'` | Run `npm install --save-dev eslint-plugin-ai-guard` |
-| Config parse errors after `init` | Run `ai-guard doctor` to diagnose |
-| SARIF upload fails in GitHub Actions | Ensure `permissions: security-events: write` is set |
-| Too many findings in strict mode | Switch to `recommended` preset or use `ai-guard baseline` |
-| Rules not firing on `.ts` files | Install `@typescript-eslint/parser` |
-| `ai-guard init` skips workflow/context | Use `ai-guard init --yes` for zero-prompt setup |
-
----
-
-## License
-
-[MIT](LICENSE) — free forever. No rules behind a paywall.
-
----
-
-<p align="center">
-  Built to make AI-assisted development reliable and trustworthy. ⚡
-</p>
+<p align="center">
+  <a href="https://getaiguard.dev">
+    <img src="./assets/logo/ai-guard-logo.png" alt="AI Guard Logo" width="260" />
+  </a>
+</p>
+
+<h1 align="center">AI Guard</h1>
+
+<p align="center">
+  <strong>Deterministic AST safety layer and CI guardrails for AI-assisted JavaScript and TypeScript code.</strong>
+</p>
+
+<p align="center">
+  <a href="https://getaiguard.dev"><strong>Website</strong></a> &nbsp;•&nbsp;
+  <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><strong>npm Package</strong></a> &nbsp;•&nbsp;
+  <a href="https://github.com/ai-guard-dev/eslint-plugin-ai-guard"><strong>GitHub Repository</strong></a> &nbsp;•&nbsp;
+  <a href="./docs/rules/"><strong>Rules Catalog</strong></a> &nbsp;•&nbsp;
+  <a href="./docs/benchmarks.md"><strong>Benchmarks</strong></a> &nbsp;•&nbsp;
+  <a href="./docs/integrations/claude-code.md"><strong>Claude Code</strong></a> &nbsp;•&nbsp;
+  <a href="./docs/getting-started.md"><strong>Documentation</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><img src="https://img.shields.io/npm/v/eslint-plugin-ai-guard.svg?style=flat-square&color=0284c7" alt="npm version"></a>
+  <a href="https://github.com/ai-guard-dev/eslint-plugin-ai-guard/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ai-guard-dev/eslint-plugin-ai-guard/ci.yml?style=flat-square&label=CI&color=10b981" alt="CI Status"></a>
+  <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><img src="https://img.shields.io/npm/dm/eslint-plugin-ai-guard.svg?style=flat-square&color=3b82f6" alt="npm downloads"></a>
+  <a href="https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-64748b?style=flat-square" alt="MIT License"></a>
+  <a href="https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/security-policy-orange?style=flat-square" alt="Security Policy"></a>
+  <a href="https://getaiguard.dev"><img src="https://img.shields.io/badge/website-getaiguard.dev-0ea5e9?style=flat-square" alt="Website"></a>
+</p>
+
+---
+
+## What is AI Guard?
+
+**AI Guard** (`eslint-plugin-ai-guard`) provides:
+- **ESLint plugin** with 18 deterministic rules and 4 presets (`recommended`, `strict`, `security`, `agent`)
+- **CLI** (`ai-guard`) for terminal, changed-file, and CI scanning
+- **GitHub Action** with native SARIF 2.1.0 output for GitHub Code Scanning
+- **Claude Code integration** with a zero-config PostToolUse hook
+- **MCP server** (`ai-guard-mcp`) for local AI-agent workflows (Claude Code, Claude Desktop, Antigravity)
+
+It is engineered to detect reliability bugs, async hazards, security vulnerabilities, and code-scaffolding defects frequently introduced during AI-assisted development (GitHub Copilot, Cursor, Claude Code, Gemini Code Assist, etc.).
+
+AI Guard analyzes Abstract Syntax Trees (AST) using ESLint's native engine. It runs locally in your editor, in your terminal via the zero-config CLI, and in your CI/CD pipelines via native SARIF 2.1.0 integration with GitHub Code Scanning.
+
+### What AI Guard is NOT
+
+> [!IMPORTANT]
+> - **AI Guard is NOT an AI detector.** It does not attempt to predict whether code was authored by an LLM or a human.
+> - **AI Guard detects dangerous or fragile code patterns** that LLMs repeatedly introduce due to incomplete context, hallucinated patterns, or probabilistic generation.
+> - **AI Guard does NOT replace ESLint.** It extends ESLint with 18 specialized, high-impact rules that core ESLint and standard configurations omit.
+
+---
+
+## Why AI Guard?
+
+AI coding assistants write code at remarkable velocity, but generated code repeatedly suffers from predictable reliability and security anti-patterns that conventional linters miss:
+
+| Pattern | Why AI Assistants Generate It | Real-World Impact |
+| :--- | :--- | :--- |
+| **Floating Promises** | Omits `await`, `return`, or `.catch()` on async calls | Unhandled promise rejections, silent failures in background jobs |
+| **Async Array Iteration** | Passes async callbacks into `array.map()` or `.filter()` | Returns unawaited `Promise[]` instead of resolved values |
+| **Sequential Awaits in Loops** | Loops over items with sequential `await` | Significant latency bottlenecks; blocks event loop execution |
+| **Empty Catch Blocks** | Inserts generic `try { ... } catch (e) {}` blocks | Swallows production exceptions silently without telemetry |
+| **Hardcoded Secrets** | Injects placeholder or real API keys/tokens | Credential leakage in version control and deployment bundles |
+| **Dynamic `eval()`** | Generates dynamic function compilation | Arbitrary code execution and code injection |
+| **Raw SQL Concatenation** | Concatenates query strings with variables | Severe SQL injection vulnerabilities |
+| **Unsafe Deserialization** | Calls `JSON.parse(req.body)` directly without schema checks | Denial of service and unhandled runtime crashes |
+| **Missing Route Auth & Authz** | Emits boilerplate endpoints without auth middleware | Unprotected API endpoints and IDOR privilege escalations |
+| **Dead Branches & Scaffolding** | Leaves `if (true)` or conflicting conditions from prompt iterations | Bloated bundles and dead code paths |
+
+AI Guard provides an instantaneous, deterministic feedback loop that catches these issues before they reach pull requests or production.
+
+---
+
+## Architecture & Workflow
+
+```mermaid
+flowchart TD
+    subgraph Dev["1. Development & Prompt Phase"]
+        A["Developer + AI Coding Assistant\n(Copilot, Cursor, Claude Code)"] --> B["JavaScript / TypeScript Code"]
+    end
+
+    subgraph ShiftLeft["Shift Left — Context Injection"]
+        SL["npx ai-guard init-context"] -.-> CTX["CLAUDE.md\n.cursorrules\ncopilot-instructions.md"]
+        CTX -.-> A
+    end
+
+    subgraph Analysis["2. Deterministic AST Analysis"]
+        B --> C["ESLint Parser\n(espree / @typescript-eslint/parser)"]
+        C --> D["AST Representation"]
+        D --> E["AI Guard Rules Engine\n(18 Deterministic Rules)"]
+    end
+
+    subgraph Tiers["3. Classification & Presets"]
+        E --> F{"Active Preset\n(recommended | strict | security | agent)"}
+        F --> G["Confidence Tiering & AST Filtering"]
+    end
+
+    subgraph Outputs["4. Output & Remediation"]
+        G --> H["Local CLI Scanning\n(ai-guard run / changed)"]
+        G --> I["Autofix Remediation\n(eslint --fix)"]
+        G --> J["HTML Dashboard\n(ai-guard report)"]
+        G --> K["SARIF 2.1.0 Artifact\n(ai-guard --sarif)"]
+    end
+
+    subgraph CI["5. GitHub Pull Request & CI/CD"]
+        K --> L["GitHub Action\nai-guard-dev/eslint-plugin-ai-guard@v1"]
+        L --> M["GitHub Code Scanning Alerts"]
+        L --> N["Inline PR Code Annotations"]
+        L --> O["PR Status Check (Blocks Merge)"]
+    end
+```
+
+---
+
+## Rules Catalog
+
+AI Guard includes **18 deterministic rules** divided into four specialized categories. Every rule is engineered with low false-positive heuristics and validated against real-world production codebases:
+
+### 🔴 Security (6 Rules)
+
+| Rule | Recommended | What It Catches | Fixable? |
+| :--- | :---: | :--- | :---: |
+| [`no-hardcoded-secret`](./docs/rules/no-hardcoded-secret.md) | **`error`** | API keys, bearer tokens, passwords, and private keys committed directly in source code. | **Yes** (`process.env.*`) |
+| [`no-eval-dynamic`](./docs/rules/no-eval-dynamic.md) | **`error`** | `eval()`, `new Function()`, and `setTimeout`/`setInterval` with dynamic/non-literal string expressions. | No |
+| [`no-sql-string-concat`](./docs/rules/no-sql-string-concat.md) | `warn` | SQL queries constructed by string concatenation or raw template literals — SQL injection risks. | No |
+| [`no-unsafe-deserialize`](./docs/rules/no-unsafe-deserialize.md) | `warn` | Unchecked `JSON.parse()` called directly on HTTP request inputs (`req.body`, `req.query`, `req.params`). | No |
+| [`require-auth-middleware`](./docs/rules/require-auth-middleware.md) | `warn` | Express and Fastify route definitions exposed without authentication middleware. | No |
+| [`require-authz-check`](./docs/rules/require-authz-check.md) | `warn` | Endpoints accessing sensitive resources or user IDs without tenant/ownership authorization checks. | No |
+
+### 🟠 Reliability (4 Rules)
+
+| Rule | Recommended | What It Catches | Fixable? |
+| :--- | :---: | :--- | :---: |
+| [`no-empty-catch`](./docs/rules/no-empty-catch.md) | **`error`** | Empty `catch (e) {}` blocks that silently swallow exceptions without logging or rethrowing. | **Yes** (inserts `/* TODO: handle error */`) |
+| [`no-broad-exception`](./docs/rules/no-broad-exception.md) | `warn` | Catching broad exception types like `catch (e: any)` that mask system faults and typing. | No |
+| [`no-catch-log-rethrow`](./docs/rules/no-catch-log-rethrow.md) | `off`* | Catch blocks that only log to `console` and rethrow without adding context or diagnostic info. | No |
+| [`no-catch-without-use`](./docs/rules/no-catch-without-use.md) | `off`* | Caught error variables that are declared in catch parameters but never referenced. | No |
+
+### 🟡 Async Stability (5 Rules)
+
+| Rule | Recommended | What It Catches | Fixable? |
+| :--- | :---: | :--- | :---: |
+| [`no-floating-promise`](./docs/rules/no-floating-promise.md) | **`error`** | Async function invocations without `await`, `.catch()`, or `return` — leading to silent dropped errors. | **Yes** (marks with `void`) |
+| [`no-async-array-callback`](./docs/rules/no-async-array-callback.md) | `warn` | Async callbacks passed to `map()`, `filter()`, `forEach()`, or `reduce()` returning `Promise[]`. | No |
+| [`no-await-in-loop`](./docs/rules/no-await-in-loop.md) | `warn` | Sequential `await` in loops where iterations can be safely executed concurrently with `Promise.all`. | **Yes** (rewrites to `Promise.all`) |
+| [`no-async-without-await`](./docs/rules/no-async-without-await.md) | `warn` | Functions declared `async` that never execute an `await` expression, adding unnecessary Promise overhead. | No |
+| [`no-redundant-await`](./docs/rules/no-redundant-await.md) | `off`* | Redundant `return await` statements outside of `try...catch` blocks. | No |
+
+### 🔵 AI Patterns (3 Rules)
+
+| Rule | Recommended | What It Catches | Fixable? |
+| :--- | :---: | :--- | :---: |
+| [`no-dead-branch`](./docs/rules/no-dead-branch.md) | `warn` | Unreachable or tautological branches (`if (true)`, `if (false)`, `x && !x`) left behind from LLM code synthesis. | No |
+| [`no-duplicate-logic-block`](./docs/rules/no-duplicate-logic-block.md) | `off`* | Consecutive duplicate code blocks or repeated conditional branches duplicated during AI edits. | No |
+| [`no-console-in-handler`](./docs/rules/no-console-in-handler.md) | `off`* | Unstructured `console.log` statements left in HTTP route handlers instead of production loggers. | No |
+
+*\* Enabled at `error` level in the `strict` preset.*
+
+---
+
+## Presets
+
+AI Guard exports four official configurations ready for flat config or legacy setups:
+
+| Preset | Description | Configuration Focus |
+| :--- | :--- | :--- |
+| **`recommended`** | **Default.** Balanced adoption preset. Enables 4 high-confidence critical rules at `error`, 9 context-sensitive rules at `warn`, and disables 5 noisy rules. Zero noise on day one. | Production codebases, new teams |
+| **`strict`** | Enforces **all 18 rules at `error`**. Designed for zero-tolerance CI gates, high-assurance software, and mature teams. | Strict CI/CD quality gates |
+| **`security`** | Focuses exclusively on the **6 security rules** (`no-hardcoded-secret`, `no-eval-dynamic`, `no-sql-string-concat` at `error`; remainder at `warn`). | AppSec auditing & security scans |
+| **`agent`** | **5 high-signal rules at `error`**. Optimized for AI-agent editing workflows where lint feedback runs immediately after each file edit (e.g., PostToolUse hooks). | Claude Code, Cursor, real-time agent loops |
+
+---
+
+## Quick Start & Installation
+
+Install the package as a development dependency using your package manager:
+
+```bash
+# npm
+npm install --save-dev eslint-plugin-ai-guard
+
+# pnpm
+pnpm add -D eslint-plugin-ai-guard
+
+# yarn
+yarn add -D eslint-plugin-ai-guard
+
+# bun
+bun add -d eslint-plugin-ai-guard
+```
+
+### Requirements
+
+- **Node.js:** `>= 20.0.0`
+- **ESLint:** `>= 8.0.0` (Supports both Flat Config and legacy configs)
+- **TypeScript (optional):** `@typescript-eslint/parser >= 6.0.0` for TypeScript AST parsing
+
+---
+
+## ESLint Configuration
+
+### 1. Modern Flat Config (`eslint.config.mjs` / `eslint.config.js`)
+
+AI Guard exports full native support for modern ESLint Flat Config:
+
+```javascript
+// eslint.config.mjs
+import aiGuard from 'eslint-plugin-ai-guard';
+
+export default [
+  {
+    plugins: {
+      'ai-guard': aiGuard,
+    },
+    rules: {
+      ...aiGuard.configs.recommended.rules,
+      // Custom overrides if desired:
+      'ai-guard/no-floating-promise': 'error',
+    },
+  },
+];
+```
+
+To use the `strict` or `security` preset in flat config:
+
+```javascript
+// Strict preset — all 18 rules at error
+rules: {
+  ...aiGuard.configs.strict.rules,
+}
+
+// Security preset — security rules only
+rules: {
+  ...aiGuard.configs.security.rules,
+}
+```
+
+### 2. Legacy Config (`.eslintrc.js` / `.eslintrc.json`)
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  plugins: ['ai-guard'],
+  extends: ['plugin:ai-guard/recommended'],
+};
+```
+
+---
+
+## CLI Reference
+
+AI Guard includes a full-featured CLI binary (`ai-guard`) that runs out of the box with zero ESLint configuration files required:
+
+```bash
+npx ai-guard <command> [options]
+```
+
+### Core Commands
+
+| Command | Purpose | Common Options |
+| :--- | :--- | :--- |
+| `run` | Scan your workspace using AI Guard AST rules | `--path <dir>`, `--strict`, `--security`, `--json`, `--sarif`, `--fail-on <level>`, `--max-warnings <n>` |
+| `changed` | Fast CI scan — only scans modified files in git | `--pr`, `--staged`, `--base <branch>`, `--strict`, `--sarif`, `--sarif-output <file>`, `--fail-on <level>` |
+| `init` | Automatically detect environment & configure ESLint | `--preset <name>`, `--flat`, `--dry-run`, `-y, --yes` |
+| `init-context` | Generate prompt instruction files for AI coding agents | `-a, --all`, `--force`, `--dry-run`, `--rules <categories>` |
+| `doctor` | Diagnose your ESLint, parser, and plugin environment | (No options needed — prints actionable diagnostic report) |
+| `baseline` | Snapshot current issues to track only new regressions | `--save`, `--check`, `--mode <strict\|stable>`, `--preset <name>` |
+| `report` | Generate an interactive standalone HTML audit report | `--path <dir>`, `--preset <name>`, `--output <file>`, `--no-open`, `--json` |
+| `preset` | Interactively select and switch active preset in config | (Interactive prompt with automatic config patch & backup) |
+| `ignore` | Add standard ignore paths (`.next`, `dist`, `build`) to config | (Patches flat config or legacy ignores safely) |
+
+### CLI Usage Examples
+
+```bash
+# 1. Immediate scan of current directory
+npx ai-guard run
+
+# 2. Strict CI scan failing only on high-confidence issues
+npx ai-guard run --strict --fail-on high
+
+# 3. Pull Request scan (diffs against PR target branch)
+npx ai-guard changed --pr --sarif --sarif-output results.sarif
+
+# 4. Generate AI agent guardrails for Cursor, Claude Code, and Copilot
+npx ai-guard init-context --all
+
+# 5. Generate interactive HTML diagnostic report
+npx ai-guard report --output ai-guard-report.html
+
+# 6. Save existing issues as baseline and only fail on new regressions
+npx ai-guard baseline --save
+npx ai-guard baseline --check
+```
+
+---
+
+## AI Agent Integration (`init-context`)
+
+Standard linters only run **after** code has already been written. The `init-context` command shifts your guardrails left by embedding AI Guard's rules directly into the instruction files loaded by your AI coding tools:
+
+```bash
+npx ai-guard init-context --all
+```
+
+This generates three targeted context files:
+1. **`CLAUDE.md`** — Automatically loaded by **Claude Code**
+2. **`.cursorrules`** — Automatically loaded by **Cursor**
+3. **`.github/copilot-instructions.md`** — Automatically loaded by **GitHub Copilot**
+
+### How Shift-Left Works
+
+```
+AI Guard (init-context)
+       ↓
+Generates project guardrail files (CLAUDE.md, .cursorrules, copilot-instructions.md)
+       ↓
+AI coding assistant reads safety rules before generating code
+       ↓
+Model avoids floating promises, empty catches, and hardcoded secrets at prompt time
+       ↓
+AI Guard CLI & GitHub Action deterministically verifies the output in CI
+```
+
+This dual-layer defense minimizes review friction and ensures generated code meets your security standard on the first pass.
+
+---
+
+## Claude Code Integration
+
+AI Guard integrates directly with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as a **PostToolUse validation hook**. Every time Claude Code edits or writes a JS/TS file, AI Guard automatically scans it for common issues.
+
+```bash
+# One-command setup
+npx ai-guard init-claude
+```
+
+This configures a PostToolUse hook in `.claude/settings.json` that runs AI Guard's fast `agent` preset (5 high-confidence rules, ~50-200ms per file) after every file edit. Claude Code reads the diagnostics and can fix issues automatically.
+
+```bash
+# Preview before applying
+npx ai-guard init-claude --dry-run
+
+# Use per-machine settings (gitignored)
+npx ai-guard init-claude --local
+```
+
+**Agent preset rules:** `no-hardcoded-secret`, `no-eval-dynamic`, `no-empty-catch`, `no-sql-string-concat`, `no-floating-promise`
+
+→ [Full documentation](./docs/integrations/claude-code.md)
+
+---
+
+## GitHub Action
+
+The official AI Guard GitHub Action runs on PRs, detects changed files, provides step summaries, outputs SARIF 2.1.0, and posts inline PR annotations directly on GitHub:
+
+```yaml
+# .github/workflows/ai-guard.yml
+name: AI Guard
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main]
+
+jobs:
+  ai-guard-scan:
+    name: AI Guard Code Review
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      security-events: write
+      actions: read
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required for git diff comparison
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Run AI Guard
+        uses: ai-guard-dev/eslint-plugin-ai-guard@v1
+        with:
+          preset: 'recommended'
+          fail-on: 'high'
+          changed-only: 'true'
+          upload-sarif: 'true'
+```
+
+### Action Inputs (`action.yml`)
+
+| Input | Description | Default |
+| :--- | :--- | :---: |
+| `preset` | Rule preset: `recommended` \| `strict` \| `security` | `'recommended'` |
+| `fail-on` | Severity threshold to fail CI: `high` \| `medium` \| `any` \| `none` | `'high'` |
+| `changed-only` | Scan only files changed in this PR / commit | `'true'` |
+| `path` | Target file or directory to scan | `'.'` |
+| `upload-sarif` | Upload results to GitHub Code Scanning | `'true'` |
+| `github-summary` | Write an execution breakdown to the GitHub Actions Job Summary | `'true'` |
+| `working-directory`| Working directory for scanning (ideal for monorepos) | `'.'` |
+| `package-manager` | Package manager: `auto` \| `npm` \| `pnpm` \| `yarn` | `'auto'` |
+| `sarif-output` | Output filepath for generated SARIF report | `'ai-guard-results.sarif'` |
+| `install-deps` | Install project dependencies prior to scanning | `'true'` |
+
+### Action Outputs
+
+| Output | Description |
+| :--- | :--- |
+| `issues-found` | Total number of issues found across scanned files |
+| `high-confidence-count` | Number of high-confidence issues flagged |
+| `medium-confidence-count` | Number of medium-confidence issues flagged |
+| `files-scanned` | Count of files analyzed during the execution |
+| `sarif-file` | Absolute path to the generated SARIF 2.1.0 artifact |
+| `duration-ms` | Total scan execution duration in milliseconds |
+
+---
+
+## SARIF & GitHub Code Scanning
+
+AI Guard natively outputs **SARIF 2.1.0** (`Static Analysis Results Interchange Format`). When uploaded via the GitHub Action or `github/codeql-action/upload-sarif@v3`, findings integrate directly with GitHub Advanced Security:
+
+- **Inline PR Annotations:** Direct comments on the exact source lines where flaws exist.
+- **Security Dashboard:** Persistent alerts under your repository's `Security → Code scanning` tab.
+- **Merge Protection:** Block merges automatically when high-confidence security or async bugs are detected.
+
+### Visual Previews
+
+#### Inline Pull Request Annotations
+<img src="./assets/ss9.jpg" alt="AI Guard PR Inline Annotations" width="1000" />
+
+#### GitHub Advanced Security Summary
+<img src="./assets/ss10.jpg" alt="GitHub Advanced Security Summary for AI Guard" width="1000" />
+
+#### Persistent Code Scanning Dashboard
+<img src="./assets/ss11.jpg" alt="GitHub Code Scanning Alerts List" width="1000" />
+
+---
+
+## Rule Examples (Before & After)
+
+### 1. `no-floating-promise` (Unhandled Promises)
+
+```typescript
+// ❌ BAD: Floating promise. Errors are dropped silently.
+async function syncUserProfile(user: User) {
+  sendTelemetryEvent('user_sync', user.id);
+  database.save(user);
+}
+
+// ✅ GOOD: Awaited, explicitly handled, or marked with void
+async function syncUserProfile(user: User) {
+  await database.save(user);
+  void sendTelemetryEvent('user_sync', user.id); // Explicitly unhandled
+}
+```
+
+### 2. `no-hardcoded-secret` (Committed Credentials)
+
+```typescript
+// ❌ BAD: Secret committed inline
+const client = new PaymentGateway({
+  apiKey: 'sk-prod-983427598273498273948273',
+});
+
+// ✅ GOOD: Read from environment variable (Autofixable!)
+const client = new PaymentGateway({
+  apiKey: process.env.API_KEY,
+});
+```
+
+### 3. `no-await-in-loop` (Sequential Latency Trap)
+
+```typescript
+// ❌ BAD: Consecutive awaits block each iteration sequentially
+async function fetchAllUsers(ids: string[]) {
+  const users = [];
+  for (const id of ids) {
+    users.push(await fetchUser(id));
+  }
+  return users;
+}
+
+// ✅ GOOD: Concurrently fetched with Promise.all (Autofixable!)
+async function fetchAllUsers(ids: string[]) {
+  return await Promise.all(ids.map((id) => fetchUser(id)));
+}
+```
+
+### 4. `no-empty-catch` (Swallowed Errors)
+
+```typescript
+// ❌ BAD: Exception swallowed without trace
+try {
+  parseConfiguration(rawConfig);
+} catch (e) {}
+
+// ✅ GOOD: Logged, rethrown, or documented (Autofixable!)
+try {
+  parseConfiguration(rawConfig);
+} catch (e) {
+  logger.error('Configuration parsing failed', { error: e });
+  throw e;
+}
+```
+
+### 5. `no-sql-string-concat` (SQL Injection)
+
+```typescript
+// ❌ BAD: Dynamic string interpolation in SQL
+const query = `SELECT * FROM users WHERE organization_id = '${orgId}' AND role = '${role}'`;
+await db.query(query);
+
+// ✅ GOOD: Parameterized query binding
+const query = 'SELECT * FROM users WHERE organization_id = $1 AND role = $2';
+await db.query(query, [orgId, role]);
+```
+
+---
+
+## Automatic Remediation (Autofix)
+
+Rules that have deterministic solutions provide automatic autofix handlers. Run ESLint's native `--fix` flag to automatically resolve them:
+
+```bash
+npx eslint . --fix
+```
+
+| Rule | Automatic Fix Behavior |
+| :--- | :--- |
+| `no-hardcoded-secret` | Replaces hardcoded string literal with `process.env.VARIABLE_NAME` |
+| `no-empty-catch` | Inserts `/* TODO: handle error */` comment to prevent silent swallowing |
+| `no-floating-promise` | Prepends `void ` expression to intentionally unawaited calls |
+| `no-await-in-loop` | Rewrites straightforward sequential loops to `await Promise.all(...)` |
+
+---
+
+## Benchmarks & Empirical Evaluation
+
+AI Guard has been empirically evaluated across multiple benchmarks comparing runtime scan performance, coverage gaps vs. standard tooling, and detection accuracy across real-world codebases.
+
+### 1. What AI Guard Catches vs. Conventional Linters
+
+Conventional linters either omit AI-specific hazards entirely or require heavyweight TypeScript type-checking (`parserOptions.project`) that significantly slows down CI:
+
+| Pattern | AI Guard Rule | ESLint Core | `@typescript-eslint` |
+| :--- | :--- | :---: | :--- |
+| **Floating Promises** (unawaited async call) | [`no-floating-promise`](./docs/rules/no-floating-promise.md) | ❌ None | `@typescript-eslint/no-floating-promises` *(requires type info)* |
+| **Async Array Callbacks** (`.map(async ...)`) | [`no-async-array-callback`](./docs/rules/no-async-array-callback.md) | ❌ None | Partial: `no-misused-promises` *(requires type info)* |
+| **Empty Catch Blocks** (swallowed errors) | [`no-empty-catch`](./docs/rules/no-empty-catch.md) | `no-empty` *(weaker)* | ❌ None |
+| **Hardcoded Secrets / API Tokens** | [`no-hardcoded-secret`](./docs/rules/no-hardcoded-secret.md) | ❌ None | ❌ None |
+| **Raw SQL String Concatenation** | [`no-sql-string-concat`](./docs/rules/no-sql-string-concat.md) | ❌ None | ❌ None |
+| **Missing Route Auth Middleware** | [`require-auth-middleware`](./docs/rules/require-auth-middleware.md) | ❌ None | ❌ None |
+| **Missing Route Authorization Checks** | [`require-authz-check`](./docs/rules/require-authz-check.md) | ❌ None | ❌ None |
+| **Dynamic `eval()` / `new Function()`** | [`no-eval-dynamic`](./docs/rules/no-eval-dynamic.md) | `no-eval` *(blanket ban)* | ❌ None |
+| **Unsafe `JSON.parse(req.body)`** | [`no-unsafe-deserialize`](./docs/rules/no-unsafe-deserialize.md) | ❌ None | ❌ None |
+| **Async Without Await** | [`no-async-without-await`](./docs/rules/no-async-without-await.md) | ❌ None | `require-await` |
+| **Sequential Await in Loop** | [`no-await-in-loop`](./docs/rules/no-await-in-loop.md) | `no-await-in-loop` *(no fix)* | ❌ None |
+| **Dead Code Branches (`if (true)`)** | [`no-dead-branch`](./docs/rules/no-dead-branch.md) | ❌ None | ❌ None |
+
+> [!TIP]
+> **Minimal Type-Information Dependency:** 17 of 18 AI Guard rules operate in pure syntax/scope-analysis mode without `projectService` or `tsconfig.json`. The `no-floating-promise` rule optionally uses TypeScript parser services for higher recall on cross-module Promise calls, with syntax/scope-based heuristics as a zero-config fallback.
+
+---
+
+### 2. Runtime Performance
+
+Benchmark: scanning 196 TypeScript / JavaScript files (`algorithm-automata-simulator`, Windows 11, Node.js 20, median of 3 runs):
+
+| Tool / Mode | Scan Time | Configuration Overhead |
+| :--- | :---: | :--- |
+| **`ai-guard run --strict`** | **~1.8s** | **Zero config** (18 AST heuristic rules, no `tsconfig.json` needed) |
+| `eslint .` (recommended) | ~2.5s | Core syntax rules only (misses floating promises & secrets) |
+| `eslint .` (type-aware `@typescript-eslint`) | **~8–12s** | Requires full TS compiler graph binding (**4x–6x slower**) |
+
+AI Guard executes **4x–6x faster** than type-aware linting suites because it leverages deterministic AST heuristics rather than reconstructing the full TypeScript symbol graph.
+
+---
+
+### 3. Empirical Bug Detection & Precision Study
+
+Two comprehensive empirical benchmark evaluations were conducted to measure real-world precision and detection yields:
+
+#### A. Accuracy & False Positive Audit (4 Real-World Repositories, 378 Files)
+
+| Category | Findings | True Positives | False Positive Rate |
+| :--- | :---: | :---: | :---: |
+| **Security** (`no-hardcoded-secret`, `no-eval-dynamic`, etc.) | 15 | 15 | **0%** |
+| **Reliability** (`no-empty-catch`, broad exceptions) | 53 | 53 | **0%** |
+| **Async Stability** (`no-floating-promise`, async callbacks) | 43 | ~40 | **~7%** |
+| **AI Patterns** (duplicate logic, dead branches) | 58 | 43 | **26%** *(reduced in v1.2.8+)* |
+
+#### B. Dual-Mode Detection Study (48 Call Sites & Real Production Target)
+
+Audited across a controlled multi-file test corpus (13 files, 48 call sites) and a real-world Express + MongoDB production application (`Truvita New`):
+
+- **High Precision:** **100% precision** on type-aware exclusive findings (26 of 26 verified True Positives; 0 false alarms on synchronous controls).
+- **Critical Detection:** Detected **1 critical database startup race condition** in production (`server/index.ts connectDB()`) where an unawaited connection call allowed requests to hit the database before initialization.
+- **Single-File Actionability:** **100%** of findings were resolvable locally at the call site (`await`, `.catch()`, or `void`).
+
+For the complete methodology, raw findings, and benchmark harness, see [**`docs/benchmarks.md`**](./docs/benchmarks.md).
+
+---
+
+## Performance & Philosophy
+
+- **Zero LLM Overhead:** AI Guard does not call external APIs, does not incur token costs, and does not add LLM latency. A scan of 100+ files executes in milliseconds.
+- **100% Deterministic:** Every finding is derived strictly from Abstract Syntax Tree analysis. No probabilistic drift, no non-deterministic hallucinated findings.
+- **Low False Positives:** Built with precision-first design. Context-sensitive rules are configured at `warn` or `off` in the recommended preset so developers are never blocked by noise.
+- **Self-Scanning:** AI Guard enforces its own rules on its own codebase in CI using the `strict` preset.
+
+---
+
+## MCP Server (Model Context Protocol)
+
+AI Guard includes a local MCP server that exposes its deterministic analysis engine to MCP-capable AI clients (Claude Code, Claude Desktop, and other MCP-compatible integrations).
+
+```bash
+npx ai-guard-mcp
+```
+
+**Available tools:**
+
+| Tool | Description |
+| :--- | :--- |
+| `ai_guard_scan_file` | Scan a single JS/TS file with structured findings |
+| `ai_guard_scan_diff` | Scan changed files in git diff (including newly created untracked JS/TS files) |
+| `ai_guard_rules` | List available rules and presets |
+
+**Claude Code configuration** (`.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ai-guard": {
+      "command": "npx",
+      "args": ["ai-guard-mcp"]
+    }
+  }
+}
+```
+
+For detailed documentation, tool schemas, and security model, see [**`docs/mcp-server.md`**](./docs/mcp-server.md).
+
+---
+
+## Learn More & Ecosystem
+
+Visit [getaiguard.dev](https://getaiguard.dev) to explore interactive documentation, rule catalogs, benchmarks, and deep-dive engineering articles.
+
+### Official Links
+
+- **Website:** [https://getaiguard.dev](https://getaiguard.dev)
+- **GitHub Organization:** [https://github.com/ai-guard-dev](https://github.com/ai-guard-dev)
+- **Repository:** [https://github.com/ai-guard-dev/eslint-plugin-ai-guard](https://github.com/ai-guard-dev/eslint-plugin-ai-guard)
+- **npm Registry:** [https://www.npmjs.com/package/eslint-plugin-ai-guard](https://www.npmjs.com/package/eslint-plugin-ai-guard)
+- **GitHub Action:** [ai-guard-dev/eslint-plugin-ai-guard@v1](https://github.com/ai-guard-dev/eslint-plugin-ai-guard)
+
+---
+
+## Contributing
+
+We welcome contributions, new rule ideas, bug reports, and false-positive reports!
+
+1. Check out our [Contributing Guide](CONTRIBUTING.md) for local setup and testing standards.
+2. Review our [Security Policy](SECURITY.md) to report vulnerabilities responsibly.
+3. Check open issues or submit new ones on our [Issue Tracker](https://github.com/ai-guard-dev/eslint-plugin-ai-guard/issues).
+
+---
+
+## License
+
+[MIT](LICENSE) © AI Guard Authors. Free and open source forever.