@triedotdev/mcp 1.0.37 → 1.0.39

package/README.md

@@ -2,16 +2,23 @@
 
 **Customizable Parallel Agents for AI Code Review**
 
-20 specialized agents scan your code for security, privacy, compliance, and bugs—all running in parallel with intelligent caching and real-time streaming.
+Specialized agents scan your code for security, privacy, compliance, and bugs—all running in parallel with intelligent caching and real-time streaming.
 
 ## Why Trie
 
-I like Claude Code Skills, but I found myself wanting more control. Trie keeps one code-first harness (registry + triager) across MCP, CLI, and CI, so the same agents and policies run everywhere—no shuffling separate .md skills per tool. It can turn my docs (PDF/TXT/MD/RTF) into agents (ingests, compresses, builds prompts, saves to `.trie/agents/`), lets me version and test them in TypeScript/JSON with identical behavior locally and in CI, and triager logs show which agents ran and why—no implicit routing. Trie is for people who want to build and govern their own agents with source-controlled prompts and transparent routing.
+Trie is purpose-built for the last mile of shipping AI-generated code.
+
+The last mile of shipping is where things break—not because your code doesn't work, but because the context you captured while building doesn't travel with you. Trie fixes that. One registry and triager runs identically in Cursor, Claude Code, the CLI, and GitHub Actions—master files that every surface can see, not scattered configs you forget to sync. Ingest your compliance docs, style guides, or internal policies (PDF/TXT/MD/RTF) and Trie compresses them into enforceable agents saved to `.trie/agents/`. Version them in TypeScript, test them locally, deploy them to CI with identical behavior. Triager logs show exactly which agents fired and why—no black-box routing. Built for people who need signal that their AI-generated code is reliable and right for the context they've captured, while they're still building.
 
 ## What's New (latest updates)
-- **Legal Agent v2.0**: Complete rewrite, now the most comprehensive legal compliance agent for app development. Covers 21 categories: open source licensing (GPL/AGPL/MIT), Terms of Service, API terms compliance, intellectual property, ADA/WCAG accessibility, GDPR/CCPA data protection, e-commerce/PCI, CAN-SPAM/TCPA marketing, COPPA child safety, export controls, DMCA, and more.
 
-- **Design Engineer v2.0**: Complete rewrite with 5-layer design intelligence architecture, AI slop detection (surface hierarchy, neon colors, purple overuse), verified token systems from Radix/Tailwind, WCAG contrast validation and domain-specific recommendations for fitness, fintech, ecommerce, and more.
+- **Accessibility Agent (v2.0)**: Comprehensive WCAG 2.1 AA compliance. Detects icon-only buttons, touch targets, skipped headings, positive tabIndex, ARIA validation, color-only indicators, and 20+ more checks with WCAG criterion references.
+
+- **Health Score Triaging**: Your health score (0-100) now actively controls what agents run. Below 50%? All agents run automatically. Agents that found issues before get boosted priority in future scans.
+
+- **Moneybags Agent**: Estimates dollar cost of bugs using IBM/NIST research. Costs scale with your user count—use `--users 10000` to match your scale (default: 250 users).
+
+- **Production Ready Agent**: Production gate that checks for health endpoints, graceful shutdown, connection pooling, security headers, rate limiting, and monitoring. Get a ship/no-ship verdict before every deploy.
 
 ---
 
@@ -23,6 +30,8 @@ I like Claude Code Skills, but I found myself wanting more control. Trie keeps o
 - [MCP Tools](#mcp-tools)
 - [CLI](#cli)
 - [Built-in Agents](#built-in-agents)
+- [Accessibility Agent (v2.0)](#accessibility-agent-v20)
+- [Moneybags Agent (v1.1)](#moneybags-agent-v11)
 - [Legal Agent (v2.0)](#legal-agent-v20)
 - [Design Engineer (v2.0)](#design-engineer-v20)
 - [Special Agents](#special-agents)
@@ -30,6 +39,8 @@ I like Claude Code Skills, but I found myself wanting more control. Trie keeps o
 - [AI-Enhanced Mode](#ai-enhanced-mode)
 - [CI/CD Integration](#cicd-integration)
 - [VS Code Extension](#vs-code-extension)
+- [Agent Context System](#agent-context-system)
+- [Production Shipping](#production-shipping) (Production Ready Agent)
 - [Configuration](#configuration)
 - [License](#license)
 
@@ -41,7 +52,7 @@ I like Claude Code Skills, but I found myself wanting more control. Trie keeps o
 
 | Feature | Description |
 |---------|-------------|
-| **20 Built-in Agents** | Security, Privacy, SOC 2, Legal, Architecture, Performance, E2E, Visual QA, Data Flow, and more |
+| **22 Built-in Agents** | Security, Privacy, SOC 2, Legal, Architecture, Performance, E2E, Visual QA, Data Flow, Moneybags, Production Ready, and more |
 | **Parallel Execution** | True parallel execution with worker threads—3-5x faster scans |
 | **Result Caching** | File-based caching with SHA256 hashing—70% faster repeated scans |
 | **Smart Triaging** | Only activates relevant agents based on code context |
@@ -67,15 +78,31 @@ I like Claude Code Skills, but I found myself wanting more control. Trie keeps o
 
 ## Quick Start
 
-### Install
+### Step 1: Install Node.js (if you don't have it)
+
+Trie requires Node.js. Check if you have it by opening Terminal (Mac) or Command Prompt (Windows):
 
 ```bash
-npm install -g @triedotdev/mcp
+node --version
 ```
 
-### Configure Cursor
+If you see a version number (like `v18.0.0`), skip to Step 2. If not:
+- **Mac**: Download from [nodejs.org](https://nodejs.org) or run `brew install node`
+- **Windows**: Download from [nodejs.org](https://nodejs.org)
+
+### Step 2: Set Up Trie in Your AI Coding Tool
 
-Settings → MCP Servers → Add:
+Pick the tool you use:
+
+<details>
+<summary><strong>Cursor (click to expand)</strong></summary>
+
+1. Open Cursor
+2. Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows)
+3. Type "settings" and select **Cursor Settings**
+4. Click **MCP** in the left sidebar
+5. Click **Add MCP Server**
+6. Paste this configuration:
 
 ```json
 {
@@ -88,54 +115,262 @@ Settings → MCP Servers → Add:
 }
 ```
 
-**Restart Cursor after adding the MCP server.**
+7. **Restart Cursor** (Cmd+Q and reopen, or Ctrl+Q on Windows)
+
+**That's it!** Trie is now connected.
+
+</details>
+
+<details>
+<summary><strong>Claude Code (click to expand)</strong></summary>
 
-### Configure Claude Code
+1. Open Claude Code
+2. Open the terminal inside Claude Code
+3. Run this command:
 
 ```bash
 claude mcp add Trie --scope user -- npx @triedotdev/mcp
 ```
 
-**Restart Claude Code after adding the MCP server.**
+4. **Restart Claude Code**
 
-### Other MCP-Compatible Tools
+**That's it!** Trie is now connected.
 
-Trie works with any MCP-compatible AI tool (OpenCode, Windsurf, etc.). Configure your tool to run:
+</details>
 
-```bash
-npx @triedotdev/mcp
+<details>
+<summary><strong>Other AI Tools (Windsurf, OpenCode, etc.)</strong></summary>
+
+Most MCP-compatible tools have a settings page for MCP servers. Add:
+
+- **Command**: `npx`
+- **Arguments**: `@triedotdev/mcp`
+
+Or in JSON format:
+```json
+{
+  "command": "npx",
+  "args": ["@triedotdev/mcp"]
+}
+```
+
+</details>
+
+### Step 3: Run Your First Scan
+
+Open your project in Cursor or Claude Code and type in the chat:
+
+```
+Scan my code with Trie
+```
+
+Trie will:
+1. Analyze your entire codebase
+2. Pick the right checks based on what your code does (payments, auth, user data, etc.)
+3. Show you a prioritized list of issues
+
+**Example output:**
 ```
+🔺 Trie Agent Scan Complete
+
+Scanned: 5 agents | Time: 12.3s | Risk: MEDIUM
 
+🎯 3 Issues Found
+
+🔴 Critical (1)
 ---
+Missing authentication on payment endpoint
+
+📍 src/api/checkout.ts:47
 
-## Usage
+Fix: Add auth middleware before processing payment
+```
 
-Once configured, ask your AI assistant:
+### Step 4: Fix Issues
 
+For each issue, you can:
+
+**Option A: Ask your AI to fix it**
 ```
-Scan this code with Trie
+Fix the authentication issue in checkout.ts that Trie found
 ```
 
-Or run specific agents:
+**Option B: Use Trie's auto-fix** (for high-confidence fixes)
+```
+Run trie_fix to apply safe fixes
+```
 
+**Option C: Get more details first**
 ```
-Run trie_security on this file
-Run trie_soc2 to check compliance
+Explain the checkout.ts security issue
 ```
 
-Slash-friendly command palette:
+---
 
-- `trie` or `/trie` shows the quick menu.
-- `trie` / `/trie` with `{ action: "scan", files?: [], directory?: "" }` runs a full triaged scan.
-- `trie` / `/trie` with `{ action: "<agent>", files?: [] }` runs one agent (e.g., `security`, `ux`, `soc2`, `agent_smith`).
+## Your Ongoing Workflow
 
-### How It Works
+Once set up, here's how to use Trie day-to-day.
+
+### How Trie Remembers Your Project
+
+**You don't have to remember anything.** Trie automatically tracks:
+
+| What Trie Remembers | Why It Matters |
+|---------------------|----------------|
+| Last scan results | AI knows what issues exist without re-scanning |
+| **Health score (0-100)** | Controls what agents run (see below) |
+| Which files have issues | AI focuses on problem areas first |
+| What type of code you have | Runs the right checks (payments, auth, etc.) automatically |
+| Scan history | See if issues are getting better or worse |
+
+**This works everywhere automatically:**
+- ✅ Cursor remembers between sessions
+- ✅ Claude Code picks up where you left off
+- ✅ CLI shows the same status
+- ✅ GitHub Actions uses the same context
+
+**Where it's stored:** A file called `.trie/AGENTS.md` in your project. You can look at it anytime to see your project's health status.
+
+### Health Score: The Priority System
+
+Your **health score** isn't just a number—it actively controls how Trie works across all your tools:
+
+| Health Score | What Happens |
+|--------------|--------------|
+| **80-100** | Normal mode: Trie runs targeted checks based on your code |
+| **50-79** | Cautious mode: Agents that found issues before run again automatically |
+| **Below 50** | Full scan mode: ALL agents run regardless of context |
 
-Trie generates **actionable reports** with high-confidence issues. It does not auto-fix code. Instead:
+**How it works across tools:**
 
-1. **Trie scans** your code and generates a report with prioritized issues
-2. **You review** the issues in the report
-3. **You (or Cursor/Claude Code)** apply fixes based on Trie's recommendations
+```
+Cursor: Scan finds 14 issues → Health drops to 56%
+                    ↓
+Claude Code: Opens same project → Sees 56% health
+                    ↓
+Trie automatically runs more thorough checks
+                    ↓
+GitHub Actions: Same health score → Stricter CI gates
+```
+
+**Why this matters:**
+
+| Scenario | Without Health Score | With Health Score |
+|----------|---------------------|-------------------|
+| Quick fix in Cursor | Might skip security check | Knows security found issues → runs it |
+| Switch to Claude Code | Starts fresh, no context | Picks up your 56% health, stays vigilant |
+| Push to GitHub | Generic checks | Focused on your known problem areas |
+
+The health score ensures your project's context **travels with you** across every tool.
+
+---
+
+### Before Pushing Code
+
+Ask Trie:
+```
+Scan my changes before I push
+```
+
+### Before Launching to Users
+
+```
+Run a full Trie scan - I'm about to launch
+```
+
+This runs security, privacy, performance, and architecture checks.
+
+### When Something Breaks
+
+```
+Trie, check this file for bugs: src/api/orders.ts
+```
+
+### Weekly Maintenance
+
+```
+Give me a Trie health report
+```
+
+This reads from `.trie/AGENTS.md` which tracks your project state over time.
+
+---
+
+## What Each Check Does (Plain English)
+
+| When You Ask | What It Checks | Why It Matters |
+|--------------|----------------|----------------|
+| "Run security scan" | Login/password handling, data exposure, hack vulnerabilities | Prevents your app from being hacked |
+| "Run privacy scan" | User data handling, GDPR/CCPA compliance | Avoids fines up to $10,000+ per violation |
+| "Run bugs scan" | Logic errors, edge cases, crash points | Prevents app crashes for users |
+| "Run performance scan" | Slow queries, memory leaks, scaling issues | App stays fast with 1000+ users |
+| "Run legal scan" | Terms of service, license compliance, regulations | Avoids lawsuits |
+| "Run design scan" | UI patterns, accessibility, UX issues | Better user experience |
+
+---
+
+## Common Questions
+
+<details>
+<summary><strong>Do I need to pay for an API key?</strong></summary>
+
+No. Trie works without any API keys using pattern matching.
+
+For deeper AI analysis, you can optionally add an Anthropic API key:
+1. Get a key from [console.anthropic.com](https://console.anthropic.com)
+2. Add to your environment: `export ANTHROPIC_API_KEY=your-key-here`
+
+This enables AI-enhanced scanning with better accuracy.
+
+</details>
+
+<details>
+<summary><strong>Will Trie change my code automatically?</strong></summary>
+
+No. Trie only scans and reports. It never modifies code without you asking. When you want fixes:
+- Ask your AI assistant to apply specific fixes
+- Or run `trie_fix` which only applies high-confidence, safe fixes
+
+</details>
+
+<details>
+<summary><strong>What if I don't understand an issue?</strong></summary>
+
+Ask for an explanation:
+```
+Explain the issue Trie found in checkout.ts in simple terms
+```
+
+Or ask what could go wrong:
+```
+What's the worst case if I don't fix this security issue?
+```
+
+</details>
+
+<details>
+<summary><strong>How do I set up automatic checks on GitHub?</strong></summary>
+
+Add this file to your repo at `.github/workflows/trie.yml`:
+
+```yaml
+name: Trie Check
+on: [push, pull_request]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: triedotdev/trie-action@v1
+        with:
+          agents: security,privacy,bugs
+          fail-on: critical
+```
+
+Now every push is automatically checked.
+
+</details>
 
 ---
 
@@ -170,7 +405,7 @@ Run a specific agent directly:
 | `trie_privacy` | GDPR/CCPA/PCI-DSS compliance, PII exposure, logging sensitive data |
 | `trie_soc2` | Access control gaps, missing audit logs, encryption issues |
 | `trie_legal` | Licensing, ToS, accessibility, IP, GDPR/CCPA, e-commerce, marketing, COPPA |
-| `trie_accessibility` | WCAG 2.1 compliance, keyboard nav, screen readers, color contrast |
+| `trie_accessibility` | WCAG 2.1 AA: icon-only buttons, touch targets, heading levels, ARIA validation, focus management, 20+ checks |
 | `trie_architecture` | Code organization, SOLID principles, N+1 queries, scalability |
 | `trie_bugs` | Null safety, edge cases, async issues, common bugs |
 | `trie_types` | Type errors, missing annotations, null checks |
@@ -251,19 +486,228 @@ trie-agent agents
 
 | Agent | Description |
 |-------|-------------|
-| **Accessibility** | WCAG 2.1 compliance, keyboard nav, screen readers, color contrast |
+| **Accessibility** | WCAG 2.1 AA compliance: icon-only buttons, touch targets, heading levels, ARIA validation, color-only indicators, keyboard nav, focus management, 20+ checks |
 | **Design Engineer** | AI slop detection, verified token systems, contrast validation, design health scoring, domain-aware recommendations |
 | **User Testing** | Simulate happy path, security tester, confused user, impatient user |
 | **Visual QA** | Visual regression, responsive design, cross-browser issues |
 | **E2E** | End-to-end test coverage, user flow validation |
 
-### Operations (3 agents)
+### Operations (5 agents)
 
 | Agent | Description |
 |-------|-------------|
 | **DevOps** | Config issues, logging, environment variables, deployment patterns |
 | **Data Flow** | Data flow analysis, state management, API contracts |
 | **Comprehension** | Plain language explanations for non-technical stakeholders |
+| **Moneybags** | 💰 Estimates dollar cost of bugs scaled to your user count (default: 250). Use `--users` to configure |
+| **Production Ready** | 🚀 Production gate: health endpoints, graceful shutdown, connection pooling, security headers, rate limiting, monitoring |
+
+---
+
+## Accessibility Agent (v2.0)
+
+The Accessibility Agent has been completely rebuilt to provide comprehensive WCAG 2.1 AA compliance checking—matching and exceeding tools like rams.ai, axe-core, and Lighthouse.
+
+### Severity Levels
+
+| Level | Description | Examples |
+|-------|-------------|----------|
+| **Critical** | Blocks access entirely | Images without alt, icon-only buttons without labels, empty links |
+| **Serious** | Significantly impairs access | Focus outline removed, positive tabIndex, missing ARIA attributes |
+| **Moderate** | Creates barriers | Skipped headings, color-only indicators, small touch targets |
+| **Low** | Best practices | Missing semantic elements, external link warnings |
+
+### What It Detects
+
+#### Critical Issues
+
+| Issue | WCAG | Description |
+|-------|------|-------------|
+| Images without alt text | 1.1.1 | Screen readers cannot describe the image |
+| Icon-only buttons missing aria-label | 4.1.2 | Screen readers announce "button" with no purpose |
+| Non-semantic click handlers | 2.1.1 | `div onClick` without keyboard support blocks keyboard users |
+| Empty links | 2.4.4 | Links with no text content are unusable |
+| Links without href | 2.4.4 | Anchor elements must have destinations |
+
+#### Serious Issues
+
+| Issue | WCAG | Description |
+|-------|------|-------------|
+| Focus outline removed | 2.4.7 | `outline: none` without replacement hides keyboard focus |
+| Positive tabIndex values | 2.4.3 | `tabIndex={5}` disrupts natural tab order |
+| Role without required ARIA | 4.1.2 | `role="slider"` needs `aria-valuenow`, `aria-valuemin`, `aria-valuemax` |
+| Form inputs without labels | 1.3.1 | Inputs must have associated labels or aria-label |
+| Color-only status indicators | 1.4.1 | Red/green for error/success excludes colorblind users |
+| Placeholder as only label | 3.3.2 | Placeholder disappears when user types |
+| Modal without Escape key | 2.1.2 | Keyboard users may be trapped in modal |
+
+#### Moderate Issues
+
+| Issue | WCAG | Description |
+|-------|------|-------------|
+| Skipped heading levels | 2.4.6 | h1 → h3 confuses screen reader navigation |
+| First heading not h1 | 2.4.6 | Pages should start with h1 |
+| Touch targets under 24px | 2.5.8 | Minimum 24×24px for WCAG AA |
+| Missing autocomplete | 1.3.5 | Helps users fill forms faster |
+| Generic link text | 2.4.4 | "Click here" is meaningless out of context |
+| Missing prefers-reduced-motion | 2.3.3 | Animations can trigger vestibular disorders |
+| Status messages without aria-live | 4.1.3 | Toasts/alerts not announced to screen readers |
+
+#### Low Issues
+
+| Issue | WCAG | Description |
+|-------|------|-------------|
+| Touch targets under 44px | 2.5.5 | Recommended 44×44px for AAA |
+| Missing semantic elements | 1.3.1 | `<div class="nav">` should be `<nav>` |
+| External links without warning | 3.2.5 | `target="_blank"` should indicate new window |
+| Disabled elements without explanation | — | Users need to know why action is unavailable |
+
+### ARIA Validation
+
+The agent validates that ARIA roles have their required attributes:
+
+| Role | Required Attributes |
+|------|---------------------|
+| `checkbox` | `aria-checked` |
+| `slider` | `aria-valuenow`, `aria-valuemin`, `aria-valuemax` |
+| `combobox` | `aria-expanded`, `aria-controls` |
+| `progressbar` | `aria-valuenow`, `aria-valuemin`, `aria-valuemax` |
+| `tab` | `aria-selected` |
+| `switch` | `aria-checked` |
+
+### Accessibility Score
+
+Each scan produces an **Accessibility Score** (0-100) based on issue severity:
+
+```
+═══════════════════════════════════════════════════
+ACCESSIBILITY REVIEW: src/components/
+═══════════════════════════════════════════════════
+
+CRITICAL (2 issues)
+───────────────────
+[A11Y] Line 24: Icon-only button missing accessible name
+  <button><CloseIcon /></button>
+  Fix: Add aria-label="Close"
+  WCAG: 4.1.2 Name, Role, Value
+
+SERIOUS (1 issue)
+─────────────────
+[A11Y] Line 48: Focus outline removed without replacement
+  className="outline-none"
+  Fix: Add focus-visible:ring-2 focus-visible:ring-offset-2
+  WCAG: 2.4.7 Focus Visible
+
+MODERATE (2 issues)
+───────────────────
+[A11Y] Line 67: Skipped heading level: h1 to h3
+  <h3>Features</h3>
+  Fix: Use h2 after h1
+  WCAG: 2.4.6 Headings and Labels
+
+═══════════════════════════════════════════════════
+SUMMARY: 2 critical, 1 serious, 2 moderate
+Score: 55/100
+═══════════════════════════════════════════════════
+```
+
+### Usage
+
+```bash
+# Run accessibility scan
+trie scan --agents accessibility
+
+# Full UI scan (accessibility + design)
+trie scan --agents accessibility,design-engineer
+
+# MCP usage
+trie_accessibility
+```
+
+---
+
+## Moneybags Agent
+
+The Moneybags agent answers the question every CFO asks: **"How much will this bug cost us?"**
+
+Built on industry research from IBM, NIST, Ponemon Institute, and Gartner, it calculates the actual dollar cost of each issue—both the cost to fix now and the cost if it reaches production. **Costs scale based on your user count.**
+
+### User Count Scaling
+
+Costs are scaled based on your app's user count (default: 250 users). Use the `--users` flag to match your scale:
+
+```bash
+# Default (250 users - early stage app)
+trie scan
+
+# Scale for your app size
+trie scan --users 1000      # Growing app
+trie scan --users 10000     # Traction
+trie scan --users 100000    # Growth stage
+trie scan -u 1000000        # Enterprise
+```
+
+| User Count | Multiplier | Stage |
+|------------|------------|-------|
+| 50 | 0.3x | MVP |
+| **250** | **1x** | **Early stage (default)** |
+| 1,000 | 2x | Growing |
+| 5,000 | 4x | Traction |
+| 25,000 | 8x | Scale-up |
+| 100,000 | 15x | Growth |
+| 1,000,000+ | 40x | Enterprise |
+
+### Cost Model
+
+| Severity | Fix Now | If Production | Multiplier |
+|----------|---------|---------------|------------|
+| **Critical** | $5,000 | $150,000+ | 30x |
+| **Serious** | $2,000 | $40,000+ | 20x |
+| **Moderate** | $500 | $5,000+ | 10x |
+| **Low** | $100 | $500+ | 5x |
+
+### Category Multipliers
+
+| Category | Multiplier | Why |
+|----------|------------|-----|
+| **Payment Bugs** | 25x | Direct financial loss, fraud exposure |
+| **Data Loss** | 20x | Irrecoverable, legally actionable |
+| **Secrets Exposed** | 15x | Immediate rotation + audit required |
+| **SQL Injection** | 12x | Full system compromise possible |
+| **Privacy Violations** | 10x | GDPR fines up to 4% of revenue |
+| **Auth Bypass** | 10x | Complete security failure |
+| **Crashes** | 8x | $5,600/minute average downtime |
+
+### What It Detects
+
+- Floating-point arithmetic for money (use integer cents!)
+- Rounding errors in financial calculations
+- Dangerous DELETE/TRUNCATE statements
+- Empty catch blocks swallowing errors
+- Assignment in conditions (= instead of ===)
+
+### Example Output
+
+```
+💰 COST ANALYSIS REPORT
+═══════════════════════════════════════
+👥 User Scale: 250 users (Early stage)
+   └─ Costs scaled 1x from 250 baseline
+
+💵 COST IMPACT
+   ├─ Fix now: $3.2k
+   ├─ If production: $28k
+   └─ Savings by fixing now: $24.8k ⚡
+
+💡 Default: 250 users. Scale with: trie scan --users 10000
+```
+
+### Research Sources
+
+- **IBM Systems Sciences Institute**: Production bugs cost 30x more to fix
+- **NIST**: $15k average production bug fix vs $500 in development
+- **Ponemon Institute 2023**: $4.45M average data breach cost
+- **Gartner**: $5,600/minute average downtime cost
 
 ---
 
@@ -589,6 +1033,120 @@ Native VS Code extension with inline diagnostics and quick fixes.
 
 ---
 
+## Agent Context System
+
+> **Simple version:** Trie remembers your project state automatically. See [How Trie Remembers Your Project](#how-trie-remembers-your-project) for the plain-English explanation.
+
+### What Gets Saved
+
+Every time you scan, Trie updates a file in your project (`.trie/AGENTS.md`) with:
+
+| Tracked | Example |
+|---------|---------|
+| Health score | "Your project is at 85/100" |
+| Critical issues | "2 security issues need fixing" |
+| Hot files | "checkout.ts has 3 issues" |
+| Priorities | "Fix payment auth before launching" |
+| Last scan | "Scanned yesterday, 47 files checked" |
+
+### What This Means For You
+
+| Scenario | What Happens |
+|----------|--------------|
+| Open Cursor tomorrow | AI already knows your project state |
+| Switch to Claude Code | Same context, no re-scanning needed |
+| Push to GitHub | CI/CD knows what to focus on |
+| Ask Trie "what should I fix?" | Gives prioritized answer based on your history |
+
+### File Size Management
+
+The context system uses automatic limits to prevent unbounded growth:
+
+| Limit | Value | What Happens |
+|-------|-------|--------------|
+| Max tracked issues | 500 | Oldest issues pruned when exceeded |
+| Locations per issue | 5 | Only most recent locations kept |
+| Scan history | 20 scans | Older scan records removed |
+| Hot files | 10 files | Only top 10 shown |
+| Issue age | 30 days | Stale resolved issues pruned |
+
+You don't need to manage this - Trie automatically prunes old data on each scan.
+
+### Multiple Projects
+
+Each project has its own isolated context:
+
+| Scenario | How It Works |
+|----------|--------------|
+| Switch between projects | Each project has its own `.trie/` folder |
+| Clone on new machine | Context restored from committed `.trie/` files |
+| Monorepo with workspaces | Each workspace can have its own `.trie/` |
+| Team collaboration | Same context when pulling changes |
+
+Trie auto-detects your project root by looking for `package.json`, `.git`, `Cargo.toml`, `go.mod`, or similar project indicators.
+
+### For Developers: Technical Details
+
+<details>
+<summary>MCP Resources (click to expand)</summary>
+
+```
+trie://context        # AGENTS.md content (read this first)
+trie://context/state  # Detailed JSON state
+trie://agents         # Available agents
+trie://config         # Current configuration
+```
+
+Files stored:
+- `.trie/AGENTS.md` - Human-readable context
+- `.trie/state.json` - Machine-readable state for programmatic access
+
+</details>
+
+---
+
+## Production Shipping
+
+Trie solves the "last mile" of shipping to production with the **Production Ready** agent.
+
+### Quick Production Check
+
+```bash
+# Run production readiness scan
+trie scan --agents production-ready
+
+# Full production scan with cost analysis
+trie scan --agents production-ready,moneybags,security --users 10000
+```
+
+### What Production Ready Checks
+
+| Area | What's Checked |
+|------|----------------|
+| **Health Endpoints** | `/health`, `/ready`, `/live` endpoints for orchestrators |
+| **Graceful Shutdown** | SIGTERM handling, connection draining |
+| **Connection Pooling** | Database pool configuration |
+| **Security Headers** | CSP, HSTS, X-Frame-Options, etc. |
+| **Rate Limiting** | API rate limiting configuration |
+| **Monitoring** | Error tracking, APM integration |
+| **Session Storage** | External session store (not in-memory) |
+| **Error Handling** | Global error handlers, no empty catch blocks |
+| **Anti-patterns** | console.log, localhost URLs, TODO comments |
+
+### CI/CD Gate
+
+Add to your workflow:
+
+```yaml
+- uses: triedotdev/trie-action@v1
+  with:
+    agents: production-ready,security,privacy,moneybags
+    fail-on: serious
+    upload-sarif: true
+```
+
+---
+
 ## Configuration
 
 ### Scan Options