@triedotdev/mcp 1.0.23 → 1.0.25

package/README.md

@@ -2,23 +2,65 @@
 
 **Customizable Parallel Agents for AI Code Review**
 
-20 specialized agents scan your code for security, privacy, compliance, and bugs - all running in parallel. Create custom agents from any document.
+20+ specialized agents scan your code for security, privacy, compliance, and bugs—all running in parallel with intelligent caching and real-time streaming.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+- [CLI](#cli)
+- [CI/CD Integration](#cicd-integration)
+- [VS Code Extension](#vs-code-extension)
+- [Built-in Agents](#built-in-agents)
+- [Special Agents](#special-agents)
+- [Custom Agents](#custom-agents)
+- [Configuration](#configuration)
+- [Docker](#docker)
+- [Team Collaboration](#team-collaboration)
+- [License](#license)
+
+---
 
 ## Features
 
-- **20 Built-in Agents** - Security, Privacy, SOC 2, Legal, Architecture, Performance, E2E, Visual QA, Data Flow, Agent Smith, and more
-- **Super Reviewer** - Interactive PR reviews: walks through changes file-by-file with AI guidance
-- **Agent Smith** - Ultimate AI code enforcer: 43 hunters targeting AI-generated anti-patterns, file-level analysis, cross-file detection, persistent memory
-- **Parallel Execution** - All agents run simultaneously for fast scans
-- **YOLO Mode** - Autonomous auto-fixing as you code
-- **Custom Agents** - Create agents from PDFs, docs, or style guides
-- **Works Everywhere** - Works with any MCP-compatible AI tool (Cursor, Claude Code, VS Code)
-- **AI-Enhanced Mode** - Optional: Set `ANTHROPIC_API_KEY` for deeper AI analysis
-- **Smart Triaging** - Only activates relevant agents based on code context
-- **Docker Support** - Run in containers for CI/CD or isolated environments
+### Core Capabilities
+
+| Feature | Description |
+|---------|-------------|
+| **20+ Built-in Agents** | Security, Privacy, SOC 2, Legal, Architecture, Performance, E2E, Visual QA, Data Flow, Agent Smith, 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 |
+| **Streaming Progress** | Real-time progress updates as agents complete |
+| **Smart Triaging** | Only activates relevant agents based on code context |
+| **Interactive Dashboard** | Terminal UI with progress bars, filters, and issue browser |
+
+### Developer Experience
+
+| Feature | Description |
+|---------|-------------|
+| **YOLO Mode** | Autonomous auto-fixing as you code |
+| **Custom Agents** | Create agents from PDFs, docs, or style guides |
+| **Works Everywhere** | Auto-detects Cursor, Claude Code, OpenCode, VS Code—adapts output automatically |
+| **AI-Enhanced Mode** | Optional deeper analysis with `ANTHROPIC_API_KEY` |
+
+### Integrations
+
+| Feature | Description |
+|---------|-------------|
+| **CI/CD Integration** | GitHub Actions, pre-commit hooks, SARIF output |
+| **Team Collaboration** | Issue assignment, Slack notifications, expertise-based routing |
+| **VS Code Extension** | Inline diagnostics, quick-fix code actions, scan on save |
+| **Docker Support** | Optimized multi-stage builds for containers |
+
+---
 
 ## Quick Start
 
+### Install
+
 ```bash
 npm install -g @triedotdev/mcp
 ```
@@ -38,7 +80,7 @@ Settings → MCP Servers → Add:
 }
 ```
 
-**Restart Cursor after adding the MCP server** for changes to take effect.
+**Restart Cursor after adding the MCP server.**
 
 ### Configure Claude Code
 
@@ -46,33 +88,55 @@ Settings → MCP Servers → Add:
 claude mcp add Trie --scope user -- npx @triedotdev/mcp
 ```
 
-**Restart Claude Code after adding the MCP server** for changes to take effect.
+**Restart Claude Code after adding the MCP server.**
+
+### Other MCP-Compatible Tools
+
+Trie works with any MCP-compatible AI tool (OpenCode, Windsurf, etc.). Configure your tool to run:
+
+```bash
+npx @triedotdev/mcp
+```
+
+Trie auto-detects which tool is running and adapts its output format accordingly.
 
-## AI-Enhanced Mode (Optional)
+---
+
+## Usage
 
-Trie agents work in two modes:
+### Basic Scanning
 
-### Pattern-Only Mode (Default)
-- Fast pattern detection using regex and static analysis
-- No API key required
-- Still finds many issues
+Once configured, ask your AI assistant:
 
-### AI-Enhanced Mode
-- Pattern detection + AI validation and expansion
-- Validates findings (reduces false positives)
-- Finds deeper issues (logic bugs, race conditions)
-- Provides intelligent, contextual fixes
-- Requires `ANTHROPIC_API_KEY`
+```
+Scan this code with Trie
+```
 
-### Setup API Key
+Or run specific agents:
+
+```
+Run trie_security on this file
+Run trie_soc2 to check compliance
+```
+
+### AI-Enhanced Mode (Recommended)
+
+Trie works in two modes:
+
+| Mode | Description |
+|------|-------------|
+| **Pattern-Only** (default) | Fast regex matching for specific patterns (exposed secrets, async forEach, etc.). Limited coverage without AI. |
+| **AI-Enhanced** | Full analysis: pattern detection + AI validation + deeper issue discovery. **Recommended for comprehensive scanning.** |
+
+> **Note:** Pattern-only mode catches specific high-confidence issues (AWS keys, GitHub tokens, common anti-patterns) but won't find logic bugs, architectural issues, or context-dependent problems. For thorough analysis, enable AI mode.
+
+**Enable AI mode:**
 
-**Option 1: Environment Variable**
 ```bash
+# Environment variable
 export ANTHROPIC_API_KEY=sk-ant-...
-```
 
-**Option 2: MCP Server Config (Cursor)**
-```json
+# Or in MCP config (Cursor)
 {
   "mcpServers": {
     "Trie": {
@@ -86,331 +150,233 @@ export ANTHROPIC_API_KEY=sk-ant-...
 }
 ```
 
-**Option 3: MCP Server Config (Claude Code)**
-```bash
-claude mcp add Trie --scope user -e ANTHROPIC_API_KEY=sk-ant-... -- npx @triedotdev/mcp
-```
-
 When AI is enabled, you'll see:
-- `🤖 AI-powered analysis enabled` in the output
+- `AI-powered analysis enabled` in output
 - `[AI VALIDATED]` and `[AI FOUND]` tags on issues
 - Richer fix recommendations
 
-## Usage
+---
 
-Once configured, just ask your AI assistant:
+## CLI
 
-```
-Scan this code with Trie
-```
+Trie includes a powerful CLI for terminal-based scanning.
 
-Or use specific agents:
+### Commands
 
-```
-Run trie_security on this file
-Run trie_soc2 to check compliance
-```
+```bash
+# Basic scan
+trie-agent scan
 
-## Super Reviewer
+# Scan specific directory
+trie-agent scan --directory ./src
 
-**Manually invoked** - Use `trie_pr_review` directly. Not included in `trie_scan`.
+# Scan specific files
+trie-agent scan --files "src/api.ts,src/auth.ts"
 
-AI accelerates coding 10-100x, but code reviews remain 1-1.5x. You're either waiting on reviewers or drowning in self-review of your own AI-generated output. Super Reviewer fixes this by making **you the driver** while AI handles the heavy lifting.
+# Run specific agents
+trie-agent scan --agents security,privacy,bugs
 
+# Output formats
+trie-agent scan --format json --output results.json
+trie-agent scan --format sarif --output results.sarif
 ```
-Use trie_pr_review
-Use trie_pr_review with pr:"12345"
-```
-
-**What happens:**
-- AI orders files for comprehension (schemas -> core logic -> implementation -> tests)
-- Walks you through each chunk, explaining what changed and why
-- Connects the dots across files, correlates with design docs
-- Hunts for real problems: state bugs, race conditions, missing error handling
-- Pauses after each file so you can question, debate, or fix
-- You bring the judgment; AI brings the throughput
 
-**Requirements:**
-- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated (`gh auth login`)
-- Git repository with changes to review
-- For PR reviews: repo must be pushed to GitHub
+### Performance Options
 
-## Agent Smith
+```bash
+# Parallel execution (default: on)
+trie-agent scan --parallel
 
-**Manually invoked** - Use `trie_agent_smith` directly. Not included in `trie_scan`.
+# Enable caching (default: on)
+trie-agent scan --cache
 
-*"I'm going to be honest with you... I hate this AI code."*
+# Set concurrency
+trie-agent scan --max-concurrency 8
 
-Agent Smith v2.0 is the **ultimate AI code enforcer** — specifically designed to hunt down AI-generated code anti-patterns from Cursor, v0, Lovable, Bolt, and other AI tools.
+# Use worker threads
+trie-agent scan --workers
 
+# Set timeout (ms)
+trie-agent scan --timeout 120000
 ```
-Use trie_agent_smith
-Use trie_smith
+
+### Interactive Mode
+
+```bash
+# Terminal UI with real-time progress
+trie-agent scan --interactive
 ```
 
-### 43 Specialized Hunters
-
-| Category | Count | Hunters |
-|----------|-------|---------|
-| **Security** | 5 | `exposed-secret`, `frontend-env`, `hardcoded-localhost`, `sql-injection`, `dangeroushtml` |
-| **AI Code Smells** | 6 | `console`, `any`, `ts-ignore`, `eslint-disable`, `debugger`, `force-flag` |
-| **Async/Promise Bugs** | 5 | `async-useeffect`, `async-foreach`, `missing-await`, `empty-catch`, `floating-promise` |
-| **React Anti-patterns** | 5 | `useeffect-abuse`, `usestate-explosion`, `index-key`, `inline-object`, `prop-drilling` |
-| **Missing UX** | 4 | `missing-loading`, `missing-error`, `missing-empty`, `page-reload` |
-| **Backend Issues** | 3 | `no-validation`, `raw-error`, `n-plus-one` |
-| **Incomplete Code** | 5 | `todo`, `vibe-comment`, `placeholder`, `sleep-hack`, `fallback` |
-| **Dead Code** | 5 | `commented-code`, `unreachable-code`, `unused-import`, `empty-function`, `dead-branch` |
-| **AI Slop Aesthetic** | 5 | `purple-gradient`, `star-icon`, `generic-hero`, `emoji-overflow`, `inter-font` |
-
-### Hunter Details
-
-#### Security Hunters (Inevitability: 90-99)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `exposed-secret-hunter` | API keys in code (`sk-...`, `AKIA...`, `ghp_...`) | Use environment variables on server-side only |
-| `frontend-env-hunter` | Secrets in `NEXT_PUBLIC_`, `VITE_`, `REACT_APP_` | Move to server-side API routes |
-| `hardcoded-localhost-hunter` | `http://localhost:3000` URLs | Use relative URLs or env vars |
-| `sql-injection-hunter` | String concatenation in SQL queries | Use parameterized queries |
-| `dangeroushtml-hunter` | `dangerouslySetInnerHTML`, `innerHTML` | Sanitize with DOMPurify |
-
-#### AI Code Smell Hunters (Inevitability: 40-85)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `console-hunter` | `console.log` left in code | Remove debug statements |
-| `any-hunter` | TypeScript `any` type | Define proper types |
-| `ts-ignore-hunter` | `@ts-ignore`, `@ts-nocheck` | Fix the actual type error |
-| `eslint-disable-hunter` | `eslint-disable` comments | Fix the underlying issue |
-| `debugger-hunter` | `debugger` statements | Remove before deploying |
-| `force-flag-hunter` | `force: true`, `--no-verify` | Understand why checks exist |
-
-#### Async/Promise Hunters (Inevitability: 70-80)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `async-useeffect-hunter` | `useEffect(async () =>` | Define async function inside, then call it |
-| `async-foreach-hunter` | `forEach(async` | Use `for...of` or `Promise.all(map())` |
-| `missing-await-hunter` | `fetch()` without `await` | Add await or handle with `.then()` |
-| `empty-catch-hunter` | `catch (e) {}` | Handle errors properly |
-| `floating-promise-hunter` | Promises not awaited | Add await or void operator |
-
-#### React Anti-pattern Hunters (Inevitability: 25-55)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `useeffect-abuse-hunter` | Too many useEffects | Use event handlers or derived state |
-| `usestate-explosion-hunter` | 10+ useState in one component | Use useReducer or group state |
-| `index-key-hunter` | `key={index}` in lists | Use unique ID from data |
-| `inline-object-hunter` | `style={{}}` in JSX | Define styles outside component |
-| `prop-drilling-hunter` | Same prop through 5+ levels | Use Context or Zustand |
-
-#### Missing UX Hunters (Inevitability: 45-65)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `missing-loading-hunter` | Data fetching without loading state | Show spinner while loading |
-| `missing-error-hunter` | `fetch` without error handling | Wrap in try/catch |
-| `missing-empty-hunter` | `.map()` without empty state | Show "No items found" |
-| `page-reload-hunter` | `location.reload()` for state | Fix state management properly |
-
-#### Backend Hunters (Inevitability: 70-85)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `no-validation-hunter` | `req.body` used without validation | Validate with Zod/Yup |
-| `raw-error-hunter` | Error messages exposed to client | Return generic errors |
-| `n-plus-one-hunter` | Database queries in loops | Use batch queries or DataLoader |
-
-#### Incomplete Code Hunters (Inevitability: 30-75)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `todo-hunter` | `TODO`, `FIXME`, `HACK` comments | Implement or remove |
-| `vibe-comment-hunter` | "idk why", "don't touch" | Understand the code |
-| `placeholder-hunter` | `test@test.com`, `example.com` | Replace with real data |
-| `sleep-hack-hunter` | `setTimeout` to fix timing | Fix the race condition |
-| `fallback-hunter` | `return null/[]/{}` hiding errors | Handle errors properly |
-
-#### Dead Code Hunters (Inevitability: 40-70)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `commented-code-hunter` | Large blocks of commented-out code | Delete it - git has history |
-| `unreachable-code-hunter` | Code after `return`/`throw`/`break` | Remove dead code |
-| `unused-import-hunter` | Import statements never used | Remove unused imports |
-| `empty-function-hunter` | Functions with empty bodies | Implement or remove |
-| `dead-branch-hunter` | `if(false)`, `if(true)` conditions | Remove dead conditionals |
-
-#### AI Slop Aesthetic Hunters (Inevitability: 10-35)
-| Hunter | Detects | Fix |
-|--------|---------|-----|
-| `purple-gradient-hunter` | Purple/violet gradients (`from-purple-500`) | Pick a distinctive color palette |
-| `star-icon-hunter` | Star icons everywhere (`<StarIcon />`) | Use contextual icons |
-| `generic-hero-hunter` | "Welcome to", "Transform your" | Write specific copy |
-| `emoji-overflow-hunter` | Any emoji usage | Use proper icons (Lucide, Heroicons) |
-| `inter-font-hunter` | Inter/system-ui font | Try Space Grotesk, DM Sans, Outfit |
-
-### How Agent Smith Works
-
-Agent Smith uses a **hybrid pattern + AI architecture**:
-
-**Phase 1: Pattern Detection (Fast, ~0.1s)**
-- 38 specialized regex hunters scan files in parallel
-- File-level metrics (giant files, hook counts, import chaos)
-- Cross-file pattern detection (issues appearing in 5+ files)
-
-**Phase 2: AI Enhancement (If API key is set, ~5-10s)**
-- Validates pattern findings (TRUE_POSITIVE vs FALSE_POSITIVE)
-- Finds deeper issues that patterns miss (logic bugs, race conditions)
-- Provides "inevitability scores" (0-100) for prioritization
-- Generates specific, copy-paste-ready fixes
-- Adds Agent Smith philosophical commentary
-
-### What Makes Agent Smith Different
+The interactive dashboard provides:
+- **Real-time progress bars** per agent
+- **Issue browser** with keyboard navigation
+- **Filters** by severity, agent, search
+- **Multiple views**: overview, issues, agents, files
+
+**Keyboard shortcuts:**
+| Key | Action |
+|-----|--------|
+| `Tab` | Switch views |
+| `↑/↓` | Navigate issues |
+| `Enter` | View issue details |
+| `f` | Filter issues |
+| `s` | Toggle sort |
+| `?` | Show help |
+| `q` | Quit |
+
+### Watch Mode (YOLO)
 
-| Feature | Description |
-|---------|-------------|
-| **Hybrid AI** | Fast regex detection + deep AI reasoning on findings |
-| **AI Code Focus** | Specifically targets patterns AI tools commonly get wrong |
-| **Multiplier Effect** | Finds one issue → searches for EVERY similar instance |
-| **Persistent Memory** | Remembers dismissed issues, brings them back if they multiply |
-| **Inevitability Score** | 0-100 rating of how likely to cause production problems |
-| **Philosophical Quotes** | 114 unique quotes explaining WHY the AI got it wrong |
-| **Cross-File Severity** | Security issues become CRITICAL when widespread |
+```bash
+# Start daemon with auto-fixing
+trie-yolo
 
-### Memory Management
+# Watch without auto-fix
+trie-yolo --no-yolo
 
-Agent Smith stores issue history in `.trie/smith-memory.json`:
-- Max 500 tracked issues (oldest pruned first)
-- Old resolved issues auto-pruned after 30 days
-- Locations limited to 5 per issue
+# One-shot scan
+trie-yolo --once
+```
 
-| Command | Description |
-|---------|-------------|
-| `trie_agent_smith show_stats:true` | Show memory statistics |
-| `trie_agent_smith clear_memory:true` | Clear all memory |
+---
+
+## CI/CD Integration
+
+Trie integrates seamlessly with GitHub Actions for automated security scanning.
 
-### Example Output
+### Quick Setup
 
+Copy the workflow files to your repo:
+
+```bash
+mkdir -p .github/workflows
+cp node_modules/@triedotdev/mcp/.github/workflows/trie-*.yml .github/workflows/
 ```
-"The AI wrote this, didn't it? I can always tell."
 
-🕴️ Deploying 38 specialized hunters...
-   28 hunters found targets
+### Available Workflows
 
-VIOLATIONS: 142 instances across 12 categories
+#### Full Security Scan (`trie-security-scan.yml`)
 
-Security (Inevitability: 95+):
-├── exposed-secret-hunter: 2 instances [CRITICAL]
-├── frontend-env-hunter: 5 instances  
-└── hardcoded-localhost-hunter: 8 instances
+Runs on push to `main`/`develop`, PRs, and daily schedule (2 AM UTC).
 
-AI Code Smells:
-├── console-hunter: 47 instances (score: 72)
-├── any-hunter: 23 instances (score: 85)
-└── ts-ignore-hunter: 12 instances
+**Features:**
+- Runs security agents: `security`, `privacy`, `soc2`, `legal`
+- Uploads SARIF to GitHub Security tab
+- Comments on PRs with summary
+- Fails build on critical issues
 
-AI Slop Aesthetic:
-├── purple-gradient-hunter: 8 instances
-├── emoji-overflow-hunter: 15 instances
-└── inter-font-hunter: 3 instances
+#### Pre-commit Checks (`trie-pre-commit.yml`)
 
-File-Level Issues:
-├── giant-file: src/App.tsx (1,247 lines) 
-├── state-explosion: 18 useState hooks
-└── effect-hell: 9 useEffect hooks
+Runs on every PR—fast, incremental scanning.
 
-Cross-File Pattern:
-└── CODEBASE-WIDE: "any" type across 12 files, 67 total instances
-    "The pattern spreads... like a virus. It is... inevitable."
+**Features:**
+- Only scans changed files (efficient for large codebases)
+- 5-minute timeout for quick feedback
+- Agent Smith pattern detection
+- Comments on PR if issues found
 
-"Vibe coding. The illusion of productivity. The reality of technical debt."
-```
+### Reusable Action
 
-## Visual QA Browser
+Use the action in any workflow:
 
-**Screenshot-based visual testing** - Captures your app at 3 viewports and returns images for your AI model to analyze.
+```yaml
+name: Security Check
+on: [push, pull_request]
 
-```
-Use trie_visual_qa_browser
-Use trie_visual_qa_browser url:"http://localhost:3000"
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Trie Security Scan
+        uses: trie-dev/security-action@v1
+        with:
+          agents: security,privacy,bugs
+          fail-on: critical
+          format: sarif
+          upload-sarif: true
+          comment-pr: true
+          parallel: true
+          cache: true
 ```
 
-**How it works:**
-1. Auto-detects running dev server (checks ports 3000, 5173, 8080, etc.)
-2. Launches headless Playwright browser
-3. Captures screenshots at mobile (375px), tablet (768px), and desktop (1440px)
-4. Returns images for your AI model to analyze
+**Inputs:**
 
-**What gets analyzed:**
-- Broken layouts, overlapping elements
-- Responsive design issues
-- Color contrast and accessibility
-- Missing images, loading states
-- General visual polish
+| Input | Default | Description |
+|-------|---------|-------------|
+| `agents` | `security,privacy,bugs` | Comma-separated agent list |
+| `fail-on` | `critical` | Fail threshold: `critical`, `serious`, `moderate`, `low` |
+| `format` | `sarif` | Output format: `json`, `sarif`, `console` |
+| `upload-sarif` | `true` | Upload to GitHub Security tab |
+| `comment-pr` | `true` | Comment results on PRs |
+| `parallel` | `true` | Run agents in parallel |
+| `cache` | `true` | Enable result caching |
 
-**Options:**
-| Option | Description |
+**Outputs:**
+
+| Output | Description |
 |--------|-------------|
-| `url` | Specific URL to screenshot |
-| `port` | Specific port to check |
-| `waitForSelector` | CSS selector to wait for before capture |
-| `waitMs` | Additional wait time after page load |
+| `results-file` | Path to scan results |
+| `critical-count` | Number of critical issues |
+| `serious-count` | Number of serious issues |
+| `total-count` | Total issues found |
+| `passed` | Whether scan passed |
 
-**First run:** If Playwright browsers aren't installed, run: `npx playwright install chromium`
+### Required Secrets
 
-**Vision model required:** This tool returns screenshots as images. Your AI model must support vision to analyze them:
-- **Claude** (Opus, Sonnet, Haiku 3.5+) - Full vision support
-- **GPT-4o, GPT-4V** - Full vision support
-- **Gemini Pro/Ultra** - Full vision support
-- **Models without vision** - Will receive images but cannot analyze them
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `ANTHROPIC_API_KEY` | Optional | Enables AI-enhanced scanning |
 
-Works in Cursor, Claude Code, and OpenCode - whichever model you have configured. No API key needed; Trie runs locally.
+---
 
-## YOLO Mode
+## VS Code Extension
 
-**Autonomous auto-fixing** - Trie watches your code and automatically fixes high-confidence issues as you code.
+Native VS Code extension with inline diagnostics and quick fixes.
 
-### Via MCP
+### Features
 
-```
-Use trie_watch with action:"start" yolo:true
-```
+- **Inline Diagnostics** — Issues appear as squiggly underlines in editor
+- **Quick-fix Code Actions** — "Copy suggested fix" for each issue
+- **Scan on Save** — Automatically scan files when saved
+- **Workspace Scanning** — Scan entire workspace with one command
 
-### Via CLI
+### Installation
 
 ```bash
-trie-yolo
+cd vscode-extension
+npm install
+npm run compile
+# Then "Run Extension" from VS Code debugger
 ```
 
-YOLO mode will:
-- Watch for file changes
-- Scan changed files automatically  
-- Auto-fix high-confidence issues (>95% confidence)
-- Log all actions for review
-
-## Docker
-
-Run Trie in a container for CI/CD or isolated environments.
+Or package for distribution:
 
 ```bash
-# Build
-docker build -t trie-agent .
-
-# YOLO mode (auto-fix)
-docker run -v $(pwd):/app trie-agent --yolo
+npx vsce package
+```
 
-# Watch mode (scan only)
-docker run -v $(pwd):/app trie-agent
+### Commands
 
-# CI mode (one-shot scan)
-docker run -v $(pwd):/app trie-agent --once
-```
+| Command | Description |
+|---------|-------------|
+| `Trie: Scan Workspace` | Scan all files in workspace |
+| `Trie: Scan Current File` | Scan active file only |
+| `Trie: Copy Fix` | Copy suggested fix to clipboard |
 
-Or use Docker Compose:
+### Settings
 
-```bash
-docker-compose up
-```
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `trie.executablePath` | `trie-agent` | Path to CLI executable |
+| `trie.scanOnSave` | `true` | Scan files on save |
+| `trie.parallel` | `true` | Run agents in parallel |
+| `trie.cache` | `true` | Enable caching |
+| `trie.useWorkers` | `false` | Use worker threads |
+| `trie.maxConcurrency` | `4` | Max parallel agents |
+| `trie.timeoutMs` | `120000` | Scan timeout |
 
-| Mode | Command | Description |
-|------|---------|-------------|
-| YOLO | `--yolo` | Auto-fix high-confidence issues |
-| Watch | (default) | Scan on file changes, no auto-fix |
-| CI | `--once` | One-shot scan, exit with error code if issues found |
+---
 
 ## Built-in Agents
 
@@ -419,48 +385,110 @@ docker-compose up
 | Agent | Command | What It Catches |
 |-------|---------|-----------------|
 | **Security** | `trie_security` | SQL injection, XSS, hardcoded secrets, auth bypasses, OWASP Top 10 |
-| **Privacy** | `trie_privacy` | PII exposure, GDPR/CCPA violations, unencrypted sensitive data, logging PII |
-| **SOC 2** | `trie_soc2` | Access control gaps, missing audit logs, encryption issues, change management |
-| **Legal** | `trie_legal` | HIPAA/COPPA compliance, consent patterns, data retention, cookie tracking |
+| **Privacy** | `trie_privacy` | GDPR/CCPA/PCI-DSS compliance, data exposure, logging sensitive data |
+| **SOC 2** | `trie_soc2` | Access control gaps, missing audit logs, encryption issues |
+| **Legal** | `trie_legal` | HIPAA/COPPA compliance, consent patterns, data retention |
 
 ### Code Quality
 
 | Agent | Command | What It Catches |
 |-------|---------|-----------------|
-| **Architecture** | `trie_architecture` | N+1 queries, circular deps, SOLID violations, god classes, missing layers |
-| **Bugs** | `trie_bugs` | Null dereference, race conditions, off-by-one, async bugs, resource leaks |
-| **Types** | `trie_types` | Missing annotations, unsafe casts, implicit `any`, null handling gaps |
-| **Clean** | `trie_clean` | AI code smells: huge files, console.logs, hardcoded URLs, useEffect abuse |
-| **Data Flow** | `trie_data_flow` | Placeholder data, schema mismatches, hardcoded IDs, type coercion bugs |
-| **Performance** | `trie_performance` | Memory leaks, N+1 queries, unnecessary re-renders, bundle size issues |
+| **Architecture** | `trie_architecture` | N+1 queries, circular deps, SOLID violations, god classes |
+| **Bugs** | `trie_bugs` | Null dereference, race conditions, off-by-one, async bugs |
+| **Types** | `trie_types` | Missing annotations, unsafe casts, implicit `any` |
+| **Clean** | `trie_clean` | AI code smells: huge files, console.logs, useEffect abuse |
+| **Data Flow** | `trie_data_flow` | Schema mismatches, hardcoded IDs, type coercion bugs |
+| **Performance** | `trie_performance` | Memory leaks, N+1 queries, unnecessary re-renders |
 
 ### Design & UX
 
 | Agent | Command | What It Catches |
 |-------|---------|-----------------|
-| **Design Engineer** | `trie_design` | Design systems, motion design, creative CSS, Awwwards-level polish |
-| **Accessibility** | `trie_accessibility` | Missing ARIA, color contrast, keyboard nav, screen reader issues (WCAG 2.1) |
-| **UX** | `trie_ux` | Missing loading states, poor error handling, broken flows, edge cases |
-| **Visual QA** | `trie_visual_qa` | Layout shifts (CLS), z-index wars, responsive gaps, animation issues |
-| **Visual QA Browser** | `trie_visual_qa_browser` | Screenshots at 3 viewports for Claude Vision analysis |
+| **Design Engineer** | `trie_design` | Design systems, motion design, Awwwards-level polish |
+| **Accessibility** | `trie_accessibility` | Missing ARIA, color contrast, keyboard nav (WCAG 2.1) |
+| **UX** | `trie_ux` | Missing loading states, poor error handling, broken flows |
+| **Visual QA** | `trie_visual_qa` | Layout shifts, z-index wars, responsive gaps |
+| **Visual QA Browser** | `trie_visual_qa_browser` | Screenshots at 3 viewports for vision analysis |
 
 ### DevOps & Testing
 
 | Agent | Command | What It Catches |
 |-------|---------|-----------------|
-| **DevOps** | `trie_devops` | Missing env vars, config issues, no health checks, logging gaps |
-| **Test** | `trie_test` | Missing test coverage, untested edge cases, weak assertions |
-| **E2E** | `trie_e2e` | Flaky tests, hardcoded waits, brittle selectors, missing coverage |
+| **DevOps** | `trie_devops` | Missing env vars, config issues, no health checks |
+| **Test** | `trie_test` | Missing coverage, untested edge cases, weak assertions |
+| **E2E** | `trie_e2e` | Flaky tests, hardcoded waits, brittle selectors |
+
+---
+
+## Special Agents
+
+These agents are **manually invoked**—they don't run during `trie_scan`.
+
+### Super Reviewer
+
+Interactive PR reviews: walks through changes file-by-file with AI guidance.
+
+```
+Use trie_pr_review
+Use trie_pr_review with pr:"12345"
+```
+
+**What it does:**
+- Orders files for comprehension (schemas → core → implementation → tests)
+- Explains what changed and why
+- Hunts for state bugs, race conditions, missing error handling
+- Pauses after each file for your input
+
+**Requirements:** [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated
+
+### Agent Smith
+
+*"I'm going to be honest with you... I hate this AI code."*
+
+The ultimate AI code enforcer—43 specialized hunters targeting AI-generated anti-patterns.
+
+```
+Use trie_agent_smith
+Use trie_smith
+```
 
-### Review & Explanation
+**43 Hunters across 9 categories:**
+
+| Category | Hunters |
+|----------|---------|
+| **Security** | exposed-secret, frontend-env, hardcoded-localhost, sql-injection, dangeroushtml |
+| **AI Code Smells** | console, any, ts-ignore, eslint-disable, debugger, force-flag |
+| **Async/Promise Bugs** | async-useeffect, async-foreach, missing-await, empty-catch, floating-promise |
+| **React Anti-patterns** | useeffect-abuse, usestate-explosion, index-key, inline-object, prop-drilling |
+| **Missing UX** | missing-loading, missing-error, missing-empty, page-reload |
+| **Backend Issues** | no-validation, raw-error, n-plus-one |
+| **Incomplete Code** | todo, vibe-comment, placeholder, sleep-hack, fallback |
+| **Dead Code** | commented-code, unreachable-code, unused-import, empty-function, dead-branch |
+| **AI Slop Aesthetic** | purple-gradient, star-icon, generic-hero, emoji-overflow, inter-font |
+
+**Memory commands:**
+```
+trie_agent_smith show_stats:true    # Show memory statistics
+trie_agent_smith clear_memory:true  # Clear all memory
+```
+
+### Visual QA Browser
+
+Screenshot-based visual testing with AI vision analysis.
+
+```
+Use trie_visual_qa_browser
+Use trie_visual_qa_browser url:"http://localhost:3000"
+```
 
-| Agent | Command | What It Does |
-|-------|---------|--------------|
-| **Super Reviewer** | `trie_pr_review` | Interactive PR review: walks through changes, explains code, finds issues |
-| **Agent Smith** | `trie_agent_smith` | Ultimate AI code enforcer: 43 hunters, file analysis, cross-file detection |
-| **Comprehension** | `trie_explain` | Plain-language explanations of code, issues, or risks |
+**What it does:**
+1. Auto-detects running dev server
+2. Captures screenshots at mobile (375px), tablet (768px), desktop (1440px)
+3. Returns images for AI vision analysis
 
-**Note:** Super Reviewer and Agent Smith are manually invoked agents. They don't run during `trie_scan`; use their dedicated commands directly.
+**Requirements:** Playwright (`npx playwright install chromium`) and a vision-capable model
+
+---
 
 ## Custom Agents
 
@@ -470,64 +498,202 @@ Create specialized agents from any document:
 Use trie_create_agent with filePath:"./style-guide.pdf" agentName:"my-style"
 ```
 
+Supported formats: PDF, Markdown, text files.
+
 Custom agents automatically activate during scans based on their rules.
 
-## Available Tools
+---
 
-| Tool | Description |
-|------|-------------|
-| `trie_scan` | Intelligent scan with automatic agent selection |
-| `trie_pr_review` | Interactive PR review - walks through changes file-by-file |
-| `trie_agent_smith` | Ultimate AI code enforcer - 43 hunters, file analysis, cross-file detection |
-| `trie_fix` | Apply high-confidence fixes |
-| `trie_explain` | Plain-language explanations |
-| `trie_watch` | Continuous scanning mode |
-| `trie_create_agent` | Create custom agent from document |
-| `trie_list_agents` | List all available agents |
-| `trie_visual_qa_browser` | Screenshot app at 3 viewports for Claude Vision analysis |
+## Configuration
 
-Plus individual agent tools: `trie_security`, `trie_privacy`, `trie_soc2`, `trie_bugs`, etc.
+### Config File
 
-## Example Output
+Create `.trie/config.json` in your project root:
 
+```json
+{
+  "version": "1.0.0",
+  "agents": {
+    "enabled": ["security", "privacy", "bugs", "types"],
+    "disabled": [],
+    "parallel": true,
+    "maxConcurrency": 4,
+    "timeout": 120000,
+    "cache": true
+  },
+  "compliance": {
+    "standards": ["SOC2", "GDPR"],
+    "enforceCompliance": false,
+    "reportFormat": "json"
+  },
+  "output": {
+    "format": "console",
+    "level": "all",
+    "interactive": false,
+    "streaming": true,
+    "colors": true
+  },
+  "paths": {
+    "include": [],
+    "exclude": ["node_modules", "dist", "build", ".git"],
+    "configDir": ".trie",
+    "outputDir": "trie-reports"
+  },
+  "integrations": {
+    "slack": {
+      "enabled": false,
+      "webhook": "",
+      "channel": "#security-alerts"
+    },
+    "github": {
+      "enabled": true
+    }
+  }
+}
 ```
-TRIE AGENT SCAN
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Smart Triaging:
-✓ Risk Level: high
-✓ Agents activated: security, soc2, privacy, architecture
-✓ Execution time: 3.2s
+### Configuration Validation
+
+Trie validates configuration on startup using Zod schemas:
+- Invalid configurations log errors and fall back to defaults
+- Missing API keys show warnings
+- File paths are verified to exist
 
-Results: 72/100
+---
 
-[CRITICAL] 2 Critical Issues
-   - Hardcoded API key (CC6.1) - src/api.ts:15
-   - SQL injection risk - src/db.ts:42
+## Docker
 
-[SERIOUS] 3 Serious Issues (auto-fixable)
-[MODERATE] 2 Moderate Issues
+Optimized multi-stage Docker builds for CI/CD or isolated environments.
+
+### Build
+
+```bash
+docker build -t trie-agent .
 ```
 
-## Configuration
+### Run
 
-Create `.trie/config.json` to customize:
+```bash
+# YOLO mode (auto-fix)
+docker run -v $(pwd):/app trie-agent --yolo
+
+# Watch mode (scan only)
+docker run -v $(pwd):/app trie-agent
+
+# CI mode (one-shot scan)
+docker run -v $(pwd):/app trie-agent --once
+```
+
+### Docker Compose
+
+```bash
+docker-compose up
+```
+
+### Modes
+
+| Mode | Flag | Description |
+|------|------|-------------|
+| YOLO | `--yolo` | Auto-fix high-confidence issues |
+| Watch | (default) | Scan on file changes |
+| CI | `--once` | One-shot scan, exit with code |
+
+---
+
+## Team Collaboration
+
+Coordinate security scanning across your team with automatic issue assignment and notifications.
+
+### Team Configuration
+
+Create `.trie/team.json`:
 
 ```json
 {
-  "agents": {
-    "builtin": {
-      "security": { "enabled": true },
-      "soc2": { "enabled": true },
-      "privacy": { "enabled": true }
+  "members": [
+    {
+      "id": "alice",
+      "name": "Alice Smith",
+      "email": "alice@example.com",
+      "slack": "@alice",
+      "expertise": ["security", "privacy"],
+      "maxIssues": 10
+    },
+    {
+      "id": "bob",
+      "name": "Bob Jones",
+      "email": "bob@example.com",
+      "slack": "@bob",
+      "expertise": ["bugs", "performance"],
+      "maxIssues": 15
+    }
+  ]
+}
+```
+
+### Automatic Issue Assignment
+
+Trie automatically assigns issues based on:
+- **Expertise matching** — Security issues go to security experts
+- **Workload balancing** — Respects `maxIssues` limits
+- **Priority weighting** — Critical issues assigned first
+
+### Slack Integration
+
+Uses Slack's [Incoming Webhooks](https://api.slack.com/messaging/webhooks) — no OAuth or bot tokens required.
+
+**Setup:**
+1. Go to your Slack workspace → Apps → Incoming Webhooks
+2. Create a webhook for your channel
+3. Add to `.trie/config.json`:
+
+```json
+{
+  "integrations": {
+    "slack": {
+      "enabled": true,
+      "webhook": "https://hooks.slack.com/services/...",
+      "channel": "#security-alerts"
     }
-  },
-  "compliance": {
-    "standards": ["GDPR", "CCPA", "SOC2"]
   }
 }
 ```
 
+**Notifications sent for:**
+- Scan completion summaries with issue counts
+- Critical issue alerts (immediate)
+- Issue assignments to team members
+- Escalations for overdue items
+- Daily/weekly team summaries
+
+### Smart Issue Grouping
+
+Issues are automatically:
+- **Grouped** by pattern (same issue across files)
+- **Prioritized** by risk score (0-100)
+- **Categorized**: security, performance, maintainability, correctness, style
+- **Bulk-fix detected** for trivial issues
+
+---
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `trie_scan` | Intelligent scan with automatic agent selection |
+| `trie_pr_review` | Interactive PR review |
+| `trie_agent_smith` | AI code enforcer—43 hunters |
+| `trie_fix` | Apply high-confidence fixes |
+| `trie_explain` | Plain-language explanations |
+| `trie_watch` | Continuous scanning mode |
+| `trie_create_agent` | Create custom agent from document |
+| `trie_list_agents` | List all available agents |
+| `trie_visual_qa_browser` | Screenshot for vision analysis |
+
+Plus individual agent tools: `trie_security`, `trie_privacy`, `trie_soc2`, `trie_bugs`, etc.
+
+---
+
 ## License
 
 MIT