@triedotdev/mcp 1.0.37 → 1.0.38

package/README.md

@@ -2,16 +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)
-- **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.
+- **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 +28,7 @@ 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)
@@ -30,6 +36,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)
 - [Configuration](#configuration)
 - [License](#license)
 
@@ -41,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 |
@@ -67,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
 
-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 +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>
+
+<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
 
-## Usage
+📍 src/api/checkout.ts:47
 
-Once configured, ask your AI assistant:
+Fix: Add auth middleware before processing payment
+```
 
+### 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 |
 
-Trie generates **actionable reports** with high-confidence issues. It does not auto-fix code. Instead:
+**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
 
-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
+**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 |
+
+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>
 
 ---
 
@@ -257,13 +489,100 @@ trie-agent agents
 | **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
 
 ---
 
@@ -589,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