@triedotdev/mcp 1.0.36 → 1.0.38

package/README.md

@@ -2,17 +2,21 @@
 
 **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)
-- Slash-friendly commands: `/trie` and `/trie_<tool>` work the same as `trie`.
-- Command palette: call `trie` with `action` to dispatch (scan, any agent, agent_smith, pr_review, watch, test, fix, explain, list_agents).
-- Clear MCP naming: all tools are discoverable with `trie_*` prefixes while short aliases still work.
-- Agent Smith speedups: single-pass file loading (skips binaries/giants), shared content across hunters, and stable memory hashes for better resurrected-issue tracking.
+
+- **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.
 
 ---
 
@@ -24,11 +28,16 @@ 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)
+- [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)
 - [Custom Agents](#custom-agents)
 - [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)
 - [Configuration](#configuration)
 - [License](#license)
 
@@ -40,7 +49,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 |
@@ -66,15 +75,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
+
+Pick the tool you use:
 
-Settings → MCP Servers → Add:
+<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
 {
@@ -87,54 +112,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>
 
-### Configure Claude Code
+<details>
+<summary><strong>Claude Code (click to expand)</strong></summary>
+
+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
+
+Fix: Add auth middleware before processing payment
+```
 
-## Usage
+### Step 4: Fix Issues
 
-Once configured, ask your AI assistant:
+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:
+---
+
+## Your Ongoing Workflow
 
-- `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`).
+Once set up, here's how to use Trie day-to-day.
 
-### How It Works
+### 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 |
+
+**How it works across tools:**
+
+```
+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 |
 
-Trie generates **actionable reports** with high-confidence issues. It does not auto-fix code. Instead:
+The health score ensures your project's context **travels with you** across every tool.
 
-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
+---
+
+### 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>
 
 ---
 
@@ -168,14 +401,14 @@ Run a specific agent directly:
 | `trie_security` | SQL injection, XSS, hardcoded secrets, auth bypasses, OWASP Top 10 |
 | `trie_privacy` | GDPR/CCPA/PCI-DSS compliance, PII exposure, logging sensitive data |
 | `trie_soc2` | Access control gaps, missing audit logs, encryption issues |
-| `trie_legal` | HIPAA/COPPA compliance, consent patterns, data retention |
+| `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_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 |
 | `trie_devops` | Config issues, logging, environment variables, deployment patterns |
 | `trie_clean` | Clean up AI-generated code: find vibe-coded patterns and quick fixes |
-| `trie_design` | Awwwards-level polish, design systems, motion design |
+| `trie_design` | Design intelligence with AI slop detection, verified token systems, contrast validation |
 | `trie_ux` | Simulate happy path, security tester, confused user, impatient user |
 
 ---
@@ -233,7 +466,7 @@ trie-agent agents
 | **Security** | SQL injection, XSS, hardcoded secrets, auth bypasses, OWASP Top 10 |
 | **Privacy** | GDPR/CCPA/PCI-DSS compliance, PII exposure, data encryption |
 | **SOC 2** | Access control gaps, missing audit logs, encryption, secrets management |
-| **Legal** | HIPAA/COPPA compliance, consent patterns, data retention |
+| **Legal** | Comprehensive app legal: licensing, ToS, accessibility, IP, GDPR/CCPA, e-commerce, COPPA, marketing compliance |
 
 ### Code Quality (6 agents)
 
@@ -251,18 +484,283 @@ trie-agent agents
 | Agent | Description |
 |-------|-------------|
 | **Accessibility** | WCAG 2.1 compliance, keyboard nav, screen readers, color contrast |
-| **Design Engineer** | Awwwards-level polish, design systems, motion design, creative CSS |
+| **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 |
+
+---
+
+## 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
+
+---
+
+## Legal Agent (v2.0)
+
+The Legal Agent has been completely rebuilt to be the most comprehensive legal compliance scanner for app development—covering everything from open source licensing to international data protection.
+
+### What It Covers (21 Categories)
+
+#### License & Open Source
+
+| Issue | Description |
+|-------|-------------|
+| **GPL/Copyleft Detection** | Flags GPL/AGPL code that may require your project to be open-sourced |
+| **AGPL Network Use** | Critical warning for AGPL's SaaS/network copyleft provisions |
+| **License Headers** | Missing SPDX identifiers in source files |
+| **Dependency Audit** | Recommends license-checker tools for third-party packages |
+| **Attribution Requirements** | MIT/BSD/Apache attribution obligations |
+
+#### Terms & Legal Documents
+
+| Issue | Description |
+|-------|-------------|
+| **Missing ToS** | User registration without Terms of Service reference |
+| **Pre-checked Consent** | ToS acceptance boxes that are pre-checked (unenforceable) |
+| **Privacy Policy** | Data collection without privacy policy disclosure |
+| **CalOPPA** | California Online Privacy Protection Act requirements |
+
+#### Third-Party & API Compliance
+
+| Issue | Description |
+|-------|-------------|
+| **API Terms** | Detects OpenAI, Stripe, Meta, Google, Twilio, AWS, YouTube usage |
+| **Font Licensing** | Flags font files that may require commercial licenses |
+| **Stock Assets** | Attribution requirements for Unsplash, Pexels, etc. |
+
+#### Intellectual Property
+
+| Issue | Description |
+|-------|-------------|
+| **Code Attribution** | Stack Overflow code (CC BY-SA), copied code comments |
+| **Trademark Usage** | Apple, Google, Microsoft, Amazon brand guideline compliance |
+
+#### Accessibility (Legal)
+
+| Issue | Description |
+|-------|-------------|
+| **ADA/Section 508** | Images without alt text, keyboard accessibility |
+| **WCAG Violations** | Color-only indicators, missing video captions |
+
+#### Data Protection
+
+| Issue | Description |
+|-------|-------------|
+| **GDPR/CCPA** | Consent management, data portability, right to erasure |
+| **Analytics Consent** | Tracking scripts without cookie consent |
+| **Data Retention** | Missing retention policies and deletion procedures |
+
+#### E-Commerce & Payments
+
+| Issue | Description |
+|-------|-------------|
+| **PCI DSS** | Direct card handling instead of tokenization (Stripe, etc.) |
+| **Price Transparency** | Hidden taxes/fees before checkout |
+| **Subscription Cancellation** | FTC Click-to-Cancel Rule compliance |
+| **Refund Policy** | Missing return/refund policy disclosure |
+
+#### Marketing & Advertising
+
+| Issue | Description |
+|-------|-------------|
+| **CAN-SPAM** | Marketing emails without unsubscribe mechanism |
+| **TCPA** | SMS marketing without express written consent |
+| **FTC Disclosure** | Affiliate links, sponsored content without disclosure |
+| **Fake Reviews** | Synthetic/AI-generated testimonials |
+
+#### Age & Child Safety
+
+| Issue | Description |
+|-------|-------------|
+| **COPPA** | Child-directed content without parental consent |
+| **Age Verification** | Alcohol, gambling, adult content without age gates |
+
+#### Export & International
+
+| Issue | Description |
+|-------|-------------|
+| **Export Controls (EAR)** | Strong encryption with international distribution |
+| **OFAC Sanctions** | Missing sanctions screening for international users |
+| **GDPR (EU)** | EU market without GDPR compliance |
+| **LGPD (Brazil)** | Brazil market without LGPD compliance |
+| **Cross-Border Transfers** | International data transfers without SCCs |
+
+#### User Content & Moderation
+
+| Issue | Description |
+|-------|-------------|
+| **Content Moderation** | User-generated content without moderation system |
+| **DMCA Safe Harbor** | File uploads without takedown procedures |
+
+#### Contracts & Liability
+
+| Issue | Description |
+|-------|-------------|
+| **Clickwrap Enforceability** | Agreement acceptance without scroll/read verification |
+| **Consent Recording** | Terms acceptance without timestamp/version logging |
+| **Warranty Disclaimers** | Missing "AS IS" and limitation of liability |
+| **Security Disclosure** | Missing security.txt or vulnerability disclosure process |
+
+### Severity Levels
+
+| Level | Examples |
+|-------|----------|
+| **Critical** | AGPL in SaaS, PCI violations, TCPA SMS marketing, fake reviews |
+| **Serious** | Missing ToS, no consent management, CAN-SPAM violations, COPPA |
+| **Moderate** | Missing data portability, license attribution, content moderation |
+| **Low** | License headers, security.txt, warranty disclaimers |
+
+---
+
+## Design Engineer (v2.0)
+
+The Design Engineer agent has been rebuilt with a comprehensive 5-layer design intelligence architecture to detect "AI slop" and enforce professional design standards.
+
+### What It Detects
+
+| Issue | Description |
+|-------|-------------|
+| **Surface Hierarchy** | Dark-on-dark surfaces with <8% lightness delta |
+| **Neon Colors** | Oversaturated colors (>80% saturation) that look amateur |
+| **Purple Overuse** | >40% violet/purple palette (common AI tell) |
+| **Accent Rainbow** | Multiple accent hue families (>1) in same view |
+| **Typography Uniformity** | Single font-weight usage lacking hierarchy |
+| **Missing Modern Fonts** | System-only font stacks without Inter/Geist |
+| **Magic Numbers** | Spacing values not on 4px grid |
+| **Low Contrast** | Text failing WCAG AA (4.5:1 ratio) |
+
+### Design Health Score
+
+Each scan produces a **Design Health Score** (0-100) with breakdown:
+- Token adoption %
+- Contrast compliance %
+- Spacing consistency %
+- Typography system %
+- Surface hierarchy %
+
+### Domain-Aware Recommendations
+
+The agent detects your product type and provides tailored guidance:
+
+| Domain | Default Mode | Accent Suggestions | Reference |
+|--------|--------------|-------------------|-----------|
+| **Fitness** | Dark | Orange, Tomato, Amber | Strava, Peloton |
+| **Fintech** | Light | Sky, Teal, Grass | Mercury, Stripe |
+| **Creative Tools** | Dark | Violet, Pink, Sky | Figma, Linear |
+| **E-commerce** | Light | Tomato, Pink, Amber | Shopify, Glossier |
+| **Dashboard** | Light | Blue, Indigo, Cyan | Vercel, Linear |
+
+### Verified Token Sources
+
+Instead of hardcoding colors, the agent references external sources:
+- **Radix Colors** — radix-ui.com/colors (contrast-guaranteed)
+- **Tailwind CSS** — tailwindcss.com/docs (zinc/slate scales)
+- **shadcn/ui** — ui.shadcn.com (production themes)
+
+### Exported Constants
+
+Design tokens are exported for use in other tools:
+
+```typescript
+import {
+  DESIGN_TOKEN_SOURCES,
+  TYPOGRAPHY_TOKENS,
+  SPACING_TOKENS,
+  MOTION_DESIGN_TOKENS,
+  DOMAIN_DESIGN_RULES,
+} from '@triedotdev/mcp/agents/design-engineer';
+```
 
 ---
 
@@ -410,6 +908,89 @@ 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 |
+
+### 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. See [PRODUCTION_SHIPPING.md](./PRODUCTION_SHIPPING.md) for the complete guide.
+
+### Quick Production Check
+
+```bash
+# Full production readiness scan
+trie scan --agents security,privacy,bugs,performance --fail-on serious
+
+# Or via MCP
+trie_scan with agents: ["security", "privacy", "bugs", "performance"]
+```
+
+### What It Covers
+
+| Area | What's Checked |
+|------|----------------|
+| **Security Hardening** | SQL injection, XSS, auth bypass, secrets, dependencies |
+| **Scalability** | Connection pooling, stateless design, N+1 queries |
+| **Architecture** | Circular dependencies, god classes, coupling |
+| **Reliability** | Error handling, health checks, timeouts |
+| **Revenue Protection** | Payment security, data compliance, business logic |
+
+### CI/CD Gate
+
+Add to your workflow:
+
+```yaml
+- uses: triedotdev/trie-action@v1
+  with:
+    agents: security,privacy,bugs,performance,architecture
+    fail-on: serious
+    upload-sarif: true
+```
+
+---
+
 ## Configuration
 
 ### Scan Options