@triedotdev/mcp 1.0.74 → 1.0.76

package/README.md

@@ -1,2519 +1,424 @@
-# Trie
+# Trie - Your Code Guardian
 
-**A guardian agent that follows you from Cursor to CI/CD and everything in between. Trie watches your codebases, remembers what broke before, and warns you before you ship something risky.**
+**An AI-powered code assistant that watches your codebase, learns from your mistakes, and prevents bugs before they ship.**
 
-Download the Trie workspace: https://www.trie.dev  
-Follow me on X: https://x.com/louiskishfy
+[![Download Workspace](https://img.shields.io/badge/Download-Trie%20Workspace-blue)](https://www.trie.dev) [![Follow on X](https://img.shields.io/badge/Follow-@louiskishfy-1DA1F2?logo=x)](https://x.com/louiskishfy)
 
-## More Info
+## What Trie Does
 
-Long article I wrote here about this emerging space in AI tooling, this project, and the problems I'm working on solving: https://www.linkedin.com/pulse/your-new-ai-tool-probably-prompt-pack-lou-kishfy-gxjac/?trackingId=Dcuh2kGsRaigIt06UTUw5Q%3D%3D
+Trie is like having an experienced developer watching over your code 24/7. It:
 
-## Why Trie Exists
-
-I shipped consumer apps that gained traction quickly with Cursor and Claude Code—real users, paying customers. AI-generated code helped me move fast, but it became a nightmare to maintain as one person. I'd fix something and forget why. The same bugs came back. My codebase grew faster than my memory of it. I burned through tokens like no tomorrow.
-
-I realized I needed something to watch over my projects so I could maintain them alone. A guardian that remembers what broke, warns me before I ship something risky, and doesn't require me to re-explain context every time I switch tools.
-
-I use Cursor, CLI, GitHub Actions—sometimes all in the same hour. It seemed ridiculous that my context couldn't follow me. Every tool had its own silo. I'd teach one thing to my IDE and lose it when I pushed to CI.
-
-So I built Trie with a few principles:
-
-**Memory that travels with git.** The `.trie/` directory commits to your repo. Same incident history, same patterns, same risk scores—whether you're in Cursor, VS Code, CLI, or CI/CD. No external service. No re-explaining. Your context is *yours*.
-
-**One guardian, not a committee.** Trie has 26 autonomous **scouts** (built-in analyzers) that intelligently scan and report findings up to one guardian agent that knows the full picture. Unlike simple skills, scouts are sophisticated analyzers with their own logic, severity scoring, and domain expertise. You can also add external skills from any repo you find online.
-
-**Fast enough for git hooks.** I chose a trie data structure because I needed O(m) lookups that don't slow down my workflow. File paths as tree branches. Hot zones light up where problems cluster. Under 10ms for pattern matching, under 500ms for pre-push checks.
-
-**Plain English.** When I'm tired at 2am and a user reports a bug, I don't want to parse cryptic linter output. Trie speaks like a teammate: "This file broke twice last month. The auth changes look risky. Maybe add a test before pushing."
-
-Trie is the guardian I wished I had when my apps took off and I was alone trying to keep them running in the middle of the night. I hope this helps you! @ me on X for feedback and requests.
-
-### Key Capabilities
-
-**Memory that travels:**
-- `.trie/` directory committed to git = your project's incident history, patterns, and risk scores
-- Same context in Cursor, Claude Code, VS Code, CLI, and GitHub Actions
-- Cross-project learning: patterns discovered across all your projects inform each new one
-- No re-explaining. Trie knows what broke before, everywhere you work.
-
-**Autonomous guardian:**
-- **Watches**: Git hooks, file watchers, proactive nudging—acts without being asked
-- **Remembers**: `trie tell "users can't log in"` builds a searchable memory tree
-- **Learns**: After 3+ incidents, discovers patterns automatically. Confidence adjusts with feedback.
-- **Warns**: `trie check` runs < 500ms before push, no LLM calls in hooks
-- **Speaks plain English**: Non-technical founders understand every warning
-
-**Technical foundation:**
-- Trie data structure for O(m) lookups, prefix search, hot zone detection—all under 10ms
-- SQLite for detailed incident history and relationships
-- BM25 search for intelligent memory queries
-- Bayesian confidence updates for continuous improvement
-
-Trie's memory is a tree. The more incidents you report, the smarter the tree gets. Hot paths = risky areas.
-
-## At a Glance
-- **Context that travels**: `.trie/` directory = single source of truth. Cursor → CLI → CI/CD → back to Cursor. Same memory everywhere.
-- **Cross-project learning**: Patterns discovered across all your projects. Fix a SQL injection in Project A, Trie warns about similar patterns in Project B.
-- **Core commands**: `trie init` (bootstrap + hooks), `trie check` (risk review before push), `trie tell "<incident>"` (build memory), `trie ok`/`trie bad` (feedback), `trie status` (health score).
-- **Guardian agent**: ONE agent that watches, learns, and warns. It has goals, observes changes, reasons about risk, and nudges you in plain English.
-- **Built-in scouts**: 26 autonomous analyzers (security, privacy, SOC2, accessibility, etc.) with sophisticated logic that intelligently report to the guardian agent.
-- **MCP integration**: `trie_scan`, `trie_check`, `trie_tell`, `trie_fix`, `trie_explain`, `trie_memory`, `trie_context`—all return plain English.
-- **Memory structure**: Prefix tree (trie) for O(m) file lookups + SQLite for detailed history. Fast enough for git hooks (< 500ms).
-- **Learning loop**: Confidence updates, pattern discovery, co-occurrence detection—all powered by trie traversal (< 10ms).
-
-## What's New (January 2026)
-
-### Hypothesis & Goals Improvements (Latest)
-
-**Bug Fixes**
-- **Goal progress calculation**: Reduction goals now display correctly. Previously "Reduce from 20 → 10, currently at 15" showed 150% instead of 50%. Fixed with proper reduction formula.
-- **Hypothesis status transitions**: Auto-generated hypotheses now properly transition from `proposed` → `testing` when first evidence is gathered.
-
-**Enhancements**
-- **Path-aware goal tracking**: Goals like "Improve code quality in the auth module" now correctly filter issues by directory path. Matches patterns like "in the auth module", "in src/", "in components folder".
-- **Progress bar clamping**: Progress bars now clamp to 0-100% to prevent display overflow for edge cases.
-
-### Guardian Agency
-
-**Persistent Memory**
-- Zero data loss after restarts—insights, cooldowns, and dismissals survive
-- Goals and hypotheses persist across sessions
-- State loads in <100ms
-
-**Goals (Auto + Manual)**
-- Auto-generates goals from incident patterns (e.g., "Reduce auth/ incidents by 50%")
-- Add your own goals via CLI or TUI
-- Adaptive scan frequency based on risk level (1-10 minutes)
-- Goal tracking with achievement celebrations
-
-```bash
-# CLI: Add manual goals
-trie goal add "Reduce auth issues by 50%"
-trie goal add "Eliminate all critical security issues"
-trie goal list
-trie goal complete <id>
-
-# TUI: Press o in watch mode
-# [a] add  [Enter] complete  [d] delete  [b] back
-```
-
-**Hypotheses (Auto + Manual)**
-- Auto-generates hypotheses from patterns
-- Add your own hypotheses via CLI or TUI
-- Guardian collects evidence and updates confidence over time
-
-```bash
-# CLI: Add manual hypotheses
-trie hypothesis add "Mondays have more bugs than Fridays"
-trie hypothesis add "Code reviews reduce bug rate"
-trie hypothesis list
-trie hypothesis validate <id>
-
-# TUI: Press y in watch mode
-# [a] add  [v] validate  [x] invalidate  [d] delete
-```
-
-**Watch Mode TUI Panels**
-
-| Key | Panel | Description |
-|-----|-------|-------------|
-| `o` | Goals | View, add, complete, delete goals |
-| `y` | Hypotheses | View, add, validate/invalidate hypotheses |
-| `g` | Guardian | Alert history and insights |
-| `i` | Toolkit | Scouts (autonomous) + Skills (installable) |
-| `h` | Help | Full keyboard shortcuts |
-
-**Predictive Intelligence**
-- Multi-factor risk scoring: incident count, recency, severity, complexity, churn
-- Trend prediction (increasing/stable/decreasing)
-- Self-improving hypotheses that validate over time
-- Example: "Friday deployments cause 2.3x more issues" → validated with 89% confidence
-
-**Autonomous Actions**
-- Auto-escalates critical security issues to Slack/email/webhook
-- Respects quiet hours (9pm-8am) with bypass for critical issues
-- Meta-learning adjusts insight weights based on your feedback
-- Effectiveness tracking with recommendations
-
-### Autonomy System
-
-**Push Blocking with Bypass**
-- Pre-push hook blocks on critical issues
-- Bypass with `TRIE_BYPASS=1 git push` or `git push --no-verify`
-- All bypasses logged for audit trail
-
-**Git Hooks - How They Work**
-
-Hooks are installed when you run `trie init`:
-- Written to `.git/hooks/` (local to your repo, not pushed to GitHub)
-- Works with terminal, GitHub Desktop, and any git client
-- Persists until you remove them
-
-| Hook | When it runs | What it does |
-|------|--------------|--------------|
-| `pre-commit` | Before each commit | Quick scan of staged files |
-| `post-commit` | After each commit | Updates context graph |
-| `pre-push` | Before push | Blocks on critical issues |
-
-**Bypassing hooks:**
-```bash
-# Skip all hooks for this push
-git push --no-verify
-
-# Skip Trie blocking but still log the bypass
-TRIE_BYPASS=1 git push
-
-# Skip all hooks for this commit
-git commit --no-verify -m "message"
-```
-
-**Removing hooks:**
-```bash
-rm .git/hooks/pre-push
-rm .git/hooks/pre-commit
-rm .git/hooks/post-commit
-```
-
-**Reinstalling hooks:**
-```bash
-trie init
-```
-
-> **Note:** Hooks are per-repo and local. Teammates need to run `trie init` after cloning to get hooks (git doesn't transfer hooks for security reasons).
-
-**Auto-Check in Watch Mode**
-- When critical issues detected, auto-runs full check
-- Configurable threshold and cooldown
-- No more "Run pre-push check" suggestions—it just runs
-
-**Auto-Fix with Human-in-the-Loop**
-- Detects trivial fixes (console.log, debugger, etc.)
-- Always asks before applying: `Fix 12 issues? (y)es / (r)eview / (n)o`
-- Review mode shows each fix before applying
-
-**Progressive Escalation**
-| Occurrence | Action |
-|------------|--------|
-| 1st | Suggest fix |
-| 3rd | Auto-run full check |
-| 5th | Escalate to Slack/email |
-| 10th | Block operations until fixed |
-
-**Configuration**
-```json
-// .trie/config.json
-{
-  "autonomy": {
-    "level": "proactive",
-    "autoCheck": { "enabled": true, "onCritical": true },
-    "autoFix": { "enabled": true, "askFirst": true },
-    "pushBlocking": { "enabled": true, "allowBypass": true }
-  },
-  "escalation": {
-    "enabled": true,
-    "targets": [
-      {
-        "type": "slack",
-        "enabled": true,
-        "config": {
-          "webhookUrl": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
-          "channel": "#security-alerts",
-          "username": "Trie Guardian"
-        },
-        "forSeverities": ["critical"],
-        "forCategories": ["security", "all"]
-      }
-    ],
-    "cooldownMinutes": 15,
-    "maxEscalationsPerHour": 5,
-    "respectQuietHours": true,
-    "criticalBypassQuietHours": true
-  }
-}
-```
-
-**Escalation Targets:**
-- `slack` - Send to Slack via webhook
-- `email` - Send via email (requires SMTP configuration)
-- `webhook` - POST to custom webhook endpoint
-
-Configure multiple targets for redundancy. Set up in `.trie/config.json` or via TUI (press `c` → `5` in watch mode).
-
-**What this means:**
-```
-Traditional tools: "Found 15 issues" (same every time)
-
-Trie Guardian: "auth/login.ts has 5 past incidents (5x above average).
-               Test coverage dropped from 85% → 72%.
-               Recommendation: Request extra review before merge.
-               
-               🎯 Goal progress: auth/ incidents 15 → 7 (53% reduction!)
-               🔮 Hypothesis validated: Friday deploys cause issues"
-```
-
-### Memory System Hardening
-- **Atomic writes**: Temp file + rename pattern prevents data corruption on crash/interrupt
-- **SHA256 hashing**: Cryptographic deduplication (replaced collision-prone bit-shift hash)
-- **Backup rotation**: Automated 5-backup rotation with recovery commands
-- **Zod validation**: Schema validation for all memory data structures
-- **Why Phase 1 only**: JSON performs well at Trie's scale (1K-10K issues). SQLite, embeddings, and session management add complexity without proportional value for a security scanning CLI tool.
-
-### Guardian + Visual QA Integration
-- **Automatic suggestions**: Guardian detects 2+ critical/serious accessibility issues and suggests visual QA
-- **Browser screenshots**: `trie_visual_qa_browser` captures mobile/tablet/desktop screenshots
-- **AI vision analysis**: AI analyzes screenshots to validate real-world accessibility impact
-- **Smart cooldowns**: 5-minute cooldown prevents duplicate suggestions
-- **Complete workflow**: Code analysis → Guardian insight → Screenshot capture → Vision analysis
-
-### CI/CD Command
-- **New command**: `trie ci` generates GitHub Actions workflow with memory caching
-- **Cross-run learning**: Cache `.trie/memory` for pattern recognition across CI runs
-- **SARIF output**: Results appear in GitHub Security tab
-- **Memory benefits**: "This issue was introduced 3 PRs ago", "Similar issue fixed in PR #42"
-- **Minimal mode**: `trie ci --minimal` for simpler workflow
-
-### Guardian Agent Enhancements
-- **Proactive insights**: Synthesizes patterns across multiple skills (security, accessibility, etc.)
-- **Verbose details**: Issue breakdowns, affected files, examples, trends in expanded view
-- **Conversational UX**: Speaks like a helpful colleague, not a system
-- **Priority scoring**: 1-10 priority levels with intelligent cooldowns
-- **Celebration mode**: Recognizes improvements and fixed issues
-- **Autonomous goal generation**: Creates goals from patterns, tracks progress, celebrates achievements
-- **Predictive risk scoring**: Multi-factor analysis identifies risky files before they break
-- **Hypothesis validation**: Generates and validates hypotheses about your codebase patterns
-- **Auto-escalation**: Critical security issues automatically sent to Slack/email during work hours
-- **Meta-learning**: Adjusts behavior based on your feedback (which insights you find helpful)
-
-### Core Workflow
-```bash
-# Report an incident
-$ trie tell "users can't log in after my push"
-📝 Got it. Linked to auth/login.ts. Next time you change this file, I'll warn you.
-
-# Before pushing
-$ git push
-🛡️ Trie: Hold on...
-   
-   You're changing auth/login.ts
-   This file has broken 2 times before.
-   
-   Last time (Jan 15): 3 users couldn't log in for 2 hours
-   
-   My suggestion: Test the login flow before pushing.
-   
-   Risk: HIGH
-
-# Give feedback
-$ trie ok    # Warning was helpful
-$ trie bad   # Warning was not helpful
-```
-
-### Built-in Scouts vs External Skills
-
-**Scout Architecture (Built-in Analyzers):**
-- **26 autonomous scouts** live in `src/skills/built-in/` and extend `BaseSkill`
-- Each scout has **sophisticated logic**: severity scoring, domain expertise, contextual analysis
-- **Intelligent reporting**: Scouts analyze and synthesize findings before reporting to the Guardian
-- **Examples**: Security Scout detects injection patterns, Privacy Scout analyzes GDPR compliance
-
-**External Skills (Simple Rules):**
-- **Installable knowledge**: Downloaded from GitHub repos as static rules/patterns
-- **No autonomous logic**: Just detection patterns that Skills Review agent applies
-- **Examples**: React best practices, style guides, compliance docs
-
-**The Guardian decides** when to deploy scouts based on risk, context, and patterns. Scouts provide autonomous intelligence; external skills provide knowledge to apply.
-
----
-
-## Table of Contents
-
-- [Why Trie](#why-trie)
-- [At a Glance](#at-a-glance)
-- [What's New](#whats-new-january-2026)
-- [The Guardian Architecture](#the-guardian-architecture)
-- [Features](#features)
-- [Quick Start](#quick-start)
-- [The Guardian Workflow](#the-guardian-workflow)
-- [Common Questions](#common-questions)
-- [What Each Scout Does](#what-each-scout-does-plain-english)
-- [MCP Tools](#mcp-tools)
-- [CLI Commands](#cli-commands)
-- [Built-in Scouts](#built-in-scouts)
-  - [Accessibility Skill (v2.0)](#accessibility-skill-v20)
-  - [Guardian + Visual QA Integration](#guardian--visual-qa-integration)
-  - [Moneybags Skill](#moneybags-skill)
-  - [Legal Skill (v2.0)](#legal-skill-v20)
-  - [Design Engineer Skill (v2.0)](#design-engineer-skill-v20)
-- [Special Skills](#special-skills)
-- [Custom Skills](#custom-skills)
-- [External Skills](#external-skills)
-- [Bootstrap System](#bootstrap-system)
-- [Issue Memory](#issue-memory)
-- [Project Info Registry](#project-info-registry)
-- [AI-Enhanced Mode](#ai-enhanced-mode)
-- [VS Code Extension](#vs-code-extension)
-- [CI/CD Integration](#cicd-integration)
-- [Configuration](#configuration)
-- [License](#license)
-
----
-
-## The Guardian Architecture
-
-Trie is **truly agentic**—it's not just a collection of linters. Here's what makes it an agent:
-
-| Property | How It Works | Why It's Agentic |
-|----------|--------------|------------------|
-| **Goals** | Auto-generates goals from patterns (e.g., "Reduce auth/ incidents by 50%") | Pursues objectives without step-by-step direction |
-| **Observation** | Git hooks, file watchers, CI events | Acts proactively, not just when asked |
-| **Reasoning** | Multi-factor risk prediction, hypothesis validation, trend analysis | Uses memory to understand situations |
-| **Action** | Warns, explains, suggests, blocks, auto-escalates critical issues | Takes action autonomously in plain English |
-| **Learning** | Meta-learning from feedback, hypothesis validation, confidence updates | Improves from experience |
-| **Prediction** | Risk scoring predicts which files are likely to break | Anticipates problems before they occur |
-
-
-
-### The Memory Tree
-
-
-```
-src/
-  auth/
-    login.ts → [3 incidents, confidence: 85%, last: Jan 15]
-    session.ts → [1 incident, confidence: 45%, last: Dec 20]
-  payment/
-    checkout.ts → [5 incidents, confidence: 92%, last: Jan 10]
-    stripe.ts → [2 incidents, confidence: 60%, last: Jan 8]
-```
-
-This enables:
-- **O(m) lookups**: Check if `auth/login.ts` is risky in < 1ms
-- **Prefix matching**: Find all incidents in `auth/*` in < 5ms
-- **Hot zone detection**: Identify risky directories in < 10ms
-- **Pattern discovery**: Walk the tree, find patterns naturally in < 10ms
-- **Auto-complete**: `trie tell "auth"` → suggests files instantly
-
-### Performance
-
-| Operation | Target | Why It Matters |
-|-----------|--------|----------------|
-| `trie check` (pre-push hook) | < 500ms | Developers won't bypass slow hooks |
-| File risk lookup | < 1ms | Real-time feedback while coding |
-| Directory incident count | < 5ms | Instant hot zone detection |
-| Pattern discovery | < 10ms | Continuous learning without blocking |
-
-### What Makes This Different
-
-Most "agents" are just prompt chains. Trie is different because:
-
-1. **Autonomous behavior**: Watches your changes continuously via hooks, not just when asked
-2. **Persistent memory that travels**: `.trie/` directory follows your code. Same context in Cursor, CLI, CI/CD, VS Code—no re-explaining
-3. **Cross-project learning**: Fix a pattern in one project, Trie warns about it in all future projects
-4. **Proactive guidance**: Warns before you push, nudges during editing, explains in plain English
-5. **Continuous learning**: Gets noticeably better after 10 incidents. Confidence adjusts with every `trie ok`/`trie bad`
-6. **Instant lookups**: Trie data structure + SQLite = O(m) file lookups (< 1ms), pattern discovery (< 10ms)
-7. **Predictive intelligence**: Multi-factor risk scoring predicts which files will break before they do
-8. **Self-improving hypotheses**: Generates hypotheses about your codebase patterns and validates them over time
-9. **Autonomous escalation**: Auto-escalates critical security issues to Slack/email (respects quiet hours)
-10. **Meta-learning**: Adjusts insight weights based on which warnings you find helpful vs. dismiss
-
-**Trie's job is to be your guardian angel—watching over your shoulder, warning you about danger, predicting problems before they happen, and getting smarter every time something goes wrong.**
-
-### Guardian Agency Architecture
-
-The Guardian is a **95% agentic system**—everything except direct code modification (which is intentional):
-
-```
-┌─────────────────────────────────────────────────────┐
-│                  Guardian Agent                      │
-│            (Observes, Learns, Predicts)              │
-└─────────────────────────────────────────────────────┘
-                        │
-        ┌───────────────┼───────────────┐
-        ▼               ▼               ▼
-   ┌─────────┐    ┌──────────┐    ┌──────────┐
-   │ Memory  │    │ Pattern  │    │  Meta-   │
-   │ System  │    │ Engine   │    │ Learning │
-   │         │    │          │    │          │
-   │ • BM25  │    │ • Trends │    │ • Track  │
-   │ • Store │    │ • Hypo's │    │ outcomes │
-   │ • Graph │    │ • Risk   │    │ • Adjust │
-   └─────────┘    └──────────┘    └──────────┘
-        │               │               │
-        └───────────────┼───────────────┘
-                        ▼
-              ┌──────────────────┐
-              │   Skill Engine   │
-              │ (Scans codebase) │
-              └──────────────────┘
-```
-
-| Capability | Status |
-|------------|--------|
-| Memory & Persistence | ✅ Insights, goals, hypotheses survive restarts |
-| Pattern Recognition | ✅ BM25 + trend analysis |
-| Goal Setting | ✅ Auto-generates from patterns |
-| Prediction | ✅ Multi-factor risk scoring |
-| Learning | ✅ Meta-learning from feedback |
-| Autonomous Action | ✅ Auto-escalation to Slack/email |
-| Context Awareness | ✅ Quiet hours, crunch mode |
-
-### Context That Travels
-
-The `.trie/` directory is your project's memory:
-
-```
-your-project/
-├── .trie/
-│   ├── memory/
-│   │   ├── issues.json              # All incidents with BM25 search
-│   │   ├── patterns.json            # Discovered patterns (3+ incidents)
-│   │   ├── guardian-insights.json   # Persistent insights, cooldowns, dismissals
-│   │   ├── guardian-state.json      # Goals, hypotheses, metrics, timing
-│   │   ├── compacted-summaries.json # Historical summaries
-│   │   └── 2024-01-15.md            # Daily logs
-│   ├── context.db                   # SQLite graph (files, changes, incidents)
-│   └── config.json                  # Guardian configuration
-├── .git/
-└── src/
-```
-
-**This directory is committed to git**, which means:
-
-| Scenario | What Happens |
-|----------|--------------|
-| **Work in Cursor** | Report incident with `trie tell`, memory updates |
-| **Switch to CLI** | Run `trie check` → same memory, same patterns |
-| **Push to GitHub** | CI reads `.trie/` → focused checks on known problem areas |
-| **Teammate pulls** | Gets your incident history, patterns, risk scores |
-| **Clone on laptop** | Full context restored from `.trie/` directory |
-| **Open in VS Code** | Same guardian, same warnings, same memory |
-
-**Cross-project learning:**
-
-```
-~/.trie/memory/global-patterns.json
-```
-
-Trie tracks patterns across ALL your projects. When you fix a SQL injection in Project A, Trie remembers. When you start Project B, it warns about similar patterns immediately—even if Project B has never seen that specific issue.
-
----
-
-## Features
-
-### Core Capabilities
-
-| Feature | Description |
-|---------|-------------|
-| **Context That Travels** | `.trie/` directory committed to git = same memory in Cursor, CLI, CI/CD, VS Code. No re-explaining. |
-| **Cross-Project Learning** | Global pattern tracking. Fix SQL injection in Project A → Trie warns in Project B. |
-| **26 Autonomous Scouts** | Security, Privacy, SOC 2, Legal, Architecture, Performance, E2E, Visual QA, Data Flow, Moneybags, Production Ready, and more |
-| **Autonomous Observation** | Git hooks, file watchers, proactive nudging—acts without being asked |
-| **Learning Loop** | Bayesian confidence updates, automatic pattern discovery (3+ incidents), `trie ok`/`trie bad` feedback |
-| **Instant Performance** | Trie data structure: < 1ms file lookups, < 10ms pattern discovery, < 500ms git hooks |
-| **Memory Hardening** | Atomic writes, SHA256 hashing, backup rotation, Zod validation—data corruption prevented |
-
-### Guardian Agency (95% Agentic)
-
-| Feature | Description |
-|---------|-------------|
-| **Autonomous Goals** | Auto-generates goals from patterns (e.g., "Reduce auth/ incidents by 50%"), tracks progress, celebrates achievements |
-| **Predictive Risk Scoring** | Multi-factor analysis (incidents, recency, severity, complexity, churn) identifies risky files before they break |
-| **Self-Improving Hypotheses** | Generates hypotheses about your codebase (e.g., "Friday deploys cause issues"), validates with evidence over time |
-| **Auto-Escalation** | Critical security issues automatically sent to Slack/email/webhook—respects quiet hours (9pm-8am) |
-| **Meta-Learning** | Adjusts insight weights based on your feedback—learns which warnings you find helpful |
-| **Adaptive Scanning** | Scan frequency adjusts to risk level (1-10 minutes)—scans more often when issues are critical |
-| **Contextual Timing** | Respects quiet hours, work days, and crunch mode—defers low-priority items when you're busy |
-
-### Performance & Execution
-
-| Feature | Description |
-|---------|-------------|
-| **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** | Activates skills based on code context, issue history, and memory patterns |
-| **Streaming Progress** | Real-time progress updates as skills complete |
-
-### Developer Experience
-
-| Feature | Description |
-|---------|-------------|
-| **Plain English** | 690-line glossary translates jargon. Non-technical founders understand every warning. |
-| **Guardian Insights** | Proactive, conversational feedback with priority scoring and cooldowns |
-| **Visual QA Integration** | Guardian auto-suggests browser screenshots when accessibility issues found |
-| **CI/CD Command** | `trie ci` generates GitHub Actions workflow with memory caching |
-| **Watch Mode** | Proactive nudging while you code (optional) |
-| **Custom Skills** | Create skills from PDFs, docs, or style guides |
-| **External Skills** | Install capabilities from Vercel, Anthropic, Expo, Stripe, 150+ skills across 12 categories |
-| **Works Everywhere** | Cursor, Claude Code, OpenCode, VS Code, CLI, CI/CD—adapts output automatically |
-| **AI-Enhanced Mode** | Optional deeper analysis with `ANTHROPIC_API_KEY` |
-
-### Integrations
-
-| Feature | Description |
-|---------|-------------|
-| **MCP Protocol** | Native integration with Cursor, Claude Code, and all MCP-compatible tools |
-| **CI/CD Integration** | GitHub Actions, pre-commit hooks, SARIF output for GitHub Security tab, memory caching |
-| **VS Code Extension** | Inline diagnostics, quick-fix code actions, scan on save |
-
----
-
-## Quick Start
-
-### 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
-node --version
-```
-
-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:
-
-<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
-{
-  "mcpServers": {
-    "Trie": {
-      "command": "npx",
-      "args": ["@triedotdev/mcp"]
-    }
-  }
-}
-```
-
-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>
-
-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
-```
-
-4. **Restart Claude Code**
-
-**That's it!** Trie is now connected.
-
-</details>
-
-<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
-```
-
-### Step 4: Fix Issues
-
-For each issue, you can:
-
-**Option A: Ask your AI to fix it**
-```
-Fix the authentication issue in checkout.ts that Trie found
-```
-
-**Option B: Use Trie's auto-fix** (for high-confidence fixes)
-```
-Run trie_fix to apply safe fixes
-```
-
-**Option C: Get more details first**
-```
-Explain the checkout.ts security issue
-```
-
----
-
-## The Guardian Workflow
-
-Trie is ONE agent with autonomous behavior. Here's how it works day-to-day.
-
-### Teaching the Guardian
-
-When something breaks, tell Trie:
-
-```bash
-$ trie tell "users can't log in after my last push"
-
-📝 Got it. I'll remember that changes to auth/ caused this.
-   Next time you change those files, I'll warn you.
-```
-
-The guardian:
-1. Links the incident to recent changes (git history)
-2. Adds the incident to its memory tree (trie data structure)
-3. Updates file risk scores
-4. Discovers patterns after 3+ similar incidents
-
-### Before You Push
-
-```bash
-$ git push
-
-🛡️ Trie: Hold on...
-
-   You're changing auth/login.ts
-   📊 This file has broken 2 times before.
-   
-   Last time (Jan 15): 3 users couldn't log in for 2 hours
-   
-   🌳 Pattern: auth/ is becoming a hot zone
-   
-   My suggestion: Test login AND session behavior
-   (These files often break together)
-   
-   Risk: HIGH
-   
-   [Continue] [Cancel]
-```
-
-The check runs in < 500ms:
-1. **Trie lookup** (< 1ms): Finds file incident history
-2. **Prefix search** (< 1ms): Checks directory-level patterns
-3. **Hot zone detection** (< 5ms): Identifies risky areas
-4. **Co-occurrence check** (< 10ms): Files that break together
-5. **Generate warning** (< 50ms): Plain English explanation
-
-### Giving Feedback
-
-```bash
-# Warning was helpful
-$ trie ok
-
-# Warning was not helpful (false positive)
-$ trie bad
-```
-
-This updates pattern confidence immediately. The agent gets smarter.
-
-### Checking Health
-
-```bash
-$ trie status
-
-🌳 Your codebase memory tree:
-
-Hot zones (3+ incidents):
-  🔥 auth/ (3 incidents across 2 files)
-     ├─ login.ts (2 incidents)
-     └─ session.ts (1 incident)
-
-Files that break together:
-  🔗 auth/login.ts ↔ auth/session.ts (67% co-occurrence)
-
-Safest areas (0 incidents):
-  ✅ components/
-  ✅ utils/
-  ✅ api/
-```
-
-### The Memory Tree
-
-Trie's memory is a **prefix tree** of your codebase's failure patterns:
-
-```
-src/
-  auth/
-    login.ts → [3 incidents, confidence: 85%, last: Jan 15]
-    session.ts → [1 incident, confidence: 45%, last: Dec 20]
-  payment/
-    checkout.ts → [5 incidents, confidence: 92%, last: Jan 10]
-```
-
-This makes lookups instant (O(m) where m = path length) and enables:
-- Prefix matching: "Find all incidents in `auth/*`" → < 1ms
-- Hot zone detection: "Which directories have 3+ incidents?" → < 10ms
-- Auto-complete: `trie tell "auth"` → suggests `auth/login.ts`, `auth/session.ts`
-- Pattern discovery: Walk the tree, find hot paths naturally → < 10ms
-
----
-
-## Common Questions
-
-<details>
-<summary><strong>How does the learning work?</strong></summary>
-
-Trie uses Bayesian confidence updates. When you report an incident (`trie tell`), it:
-1. Links the incident to recent changes (git history)
-2. Adds it to the memory tree (trie data structure)
-3. Updates file risk scores
-4. After 3+ similar incidents, discovers patterns automatically
-
-When you give feedback (`trie ok` / `trie bad`), confidence adjusts immediately. False positives decrease a pattern's confidence; true positives increase it.
-
-</details>
-
-<details>
-<summary><strong>Will Trie change my code automatically?</strong></summary>
-
-No. Trie scans and suggests—it never edits code on its own. You stay in control.
-
-**What Trie does:**
-- Warn about risky changes
-- Explain past incidents
-- Suggest what to test
-- Flag security issues
-
-**What about `trie_fix`?**
-
-`trie_fix` generates fix prompts that guide your AI assistant (Claude, Cursor) to apply changes. The AI does the editing, not Trie. You review and approve every change through your normal workflow.
-
-**What Trie doesn't do:**
-- Edit files directly
-- Create pull requests automatically
-- Run arbitrary commands
-- Make changes without your review
-
-</details>
-
-<details>
-<summary><strong>What if I don't understand a warning?</strong></summary>
-
-Ask for an explanation:
-```
-$ trie explain
-
-🛡️ Detailed Explanation
-
-You changed: auth/login.ts
-
-History:
-• Jan 15, 2024: 3 users couldn't log in for 2 hours
-  - You changed session timeout logic
-  - Users got logged out unexpectedly  
-  - Had to roll back
-
-• Dec 20, 2023: Login button stopped working
-  - Missing null check on user object
-  - 5 users affected
-
-Pattern: auth/ directory has 3 total incidents
-Files that break together: login.ts ↔ session.ts (67% of the time)
-
-My suggestion: Test both login AND session behavior together
-```
-
-Everything is in plain English. No jargon.
-
-</details>
-
-<details>
-<summary><strong>Does it work offline?</strong></summary>
-
-Yes. The core guardian works entirely offline:
-- `trie check` in git hooks (< 500ms, no network)
-- Pattern matching and risk scoring (local database)
-- Memory queries (trie + SQLite, all local)
-
-The built-in skills can optionally use AI for deeper analysis when you have an API key, but it's not required.
-
-</details>
-
-<details>
-<summary><strong>How do I set up automatic checks on GitHub?</strong></summary>
-
-**Quick setup (recommended):**
-
-Run `trie ci` to generate a GitHub Actions workflow with memory caching:
-
-```bash
-# Generate full workflow with SARIF output
-trie ci
-
-# Generate minimal workflow
-trie ci --minimal
-
-# Preview without creating files
-trie ci --dry-run
-```
-
-This creates `.github/workflows/trie-scan.yml` that:
-- ✅ Caches Trie memory across runs for cross-run learning
-- ✅ Enables insights like "This issue was introduced 3 PRs ago"
-- ✅ Tracks trends: improving, stable, or declining
-- ✅ Uploads SARIF results to GitHub Security tab
-
-**Manual setup:**
-
-Or add this file to your repo at `.github/workflows/trie.yml`:
-
-```yaml
-name: Trie Guardian
-on: [push, pull_request]
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Need history for incident context
-      
-      - uses: triedotdev/trie-action@v1
-        with:
-          # Fast check on every push
-          command: check
-          fail-on: critical
-```
-
-The guardian reads your project's `.trie/` directory (incidents, patterns, memory) and uses that context in CI.
-
-</details>
-
----
-
-## What Each Scout 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 |
-| "Run accessibility scan" | WCAG 2.1 AA compliance, screen reader support | Makes your app usable by everyone |
-| "Run production-ready scan" | Health endpoints, graceful shutdown, security headers | Confirms you're ready to ship |
-| "Run moneybags scan" | Dollar cost of bugs at your user scale | Shows ROI of fixing issues now vs later |
-
----
-
-## MCP Apps - Interactive UIs
-
-**New:** Trie now supports **MCP Apps**—interactive UI components that render directly in Claude, ChatGPT, VS Code, and other MCP clients.
-
-Instead of text-only output, Trie tools return rich, interactive interfaces:
-
-| Tool | UI App | What You Get |
-|------|--------|--------------|
-| `trie_scan` | **Scan Dashboard** | Filter by severity/agent, expand issues, one-click fix actions, export JSON |
-| `trie_memory` | **Memory Tree** | Hierarchical view with bar charts, cross-project patterns, collapsible sections |
-| `trie_pr_review` | **PR Review** | File tree, side-by-side diffs, inline comments, approve/request changes |
-| `trie_visual_qa_browser` | **Visual QA** | Screenshot gallery, viewport comparison, issue annotations |
-
-### Memory Tree Visualization
-
-When you use `trie_memory`, you get an interactive tree view:
-
-```
-MEMORY TREE [1000 issues]
-├──────────────────────────────────────┤
-  ▼ By Severity
-    │ critical (5)  █░░░░░░░░░░░░░░░
-    │ high (10)     █░░░░░░░░░░░░░░░
-    │ medium (75)   ███████████░░░░░
-    └ low (110)     ████████████████
-  ▼ By File (Hot Spots)
-    ├─ styles.css (57)          ████████████████
-    ├─ stack-detector.ts (23)   ██████░░░░░░░░░░
-    └─ attack-surface.ts (10)   ███░░░░░░░░░░░░░
-  ▼ Cross-Project Patterns (88 recurring)
-    ├─ "Loose equality check..." - seen in 2 projects
-    ├─ "Missing license header..." - seen in 2 projects
-    └─ "Potential N+1 query..." - seen in 2 projects
-```
-
-**Key features:**
-- Collapsible sections (severity, files, agents, patterns)
-- Visual bar charts showing issue distribution
-- **Cross-project patterns** - highlights recurring issues across your codebases
-- Click any category to drill down into specific issues
-- Resolve/unresolve actions inline
-
-### Client Support
-
-MCP Apps work in:
-- **Claude Desktop** ✅
-- **Claude Web** ✅
-- **ChatGPT** ✅
-- **VS Code Insiders** ✅
-- **Goose** ✅
-
-### How It Works
-
-1. You call a Trie tool like `trie_scan` or `trie_memory`
-2. Your AI client detects the UI resource and fetches it
-3. An interactive dashboard renders in your chat
-4. You can filter, expand, click actions—all within the conversation
-5. The model sees your interactions and responds accordingly
-
-No configuration needed—the UIs work automatically when you use Trie via MCP.
-
----
-
-## MCP Tools
-
-These tools are available when using Trie via MCP (Cursor, Claude Code, etc.).
-
-### Scanning & Analysis
-
-| Tool | Description | UI App |
-|------|-------------|--------|
-| `trie_scan` | Full scan with intelligent skill selection | ✅ Interactive dashboard |
-| `trie_watch` | Watch mode—proactive nudging as you code | — |
-| `trie_check` | Quick risk check before push (< 500ms, no LLM) | — |
-| `trie_fix` | Generate fix recommendations for detected issues | — |
-| `trie_explain` | Explain code, issues, or changes in plain language | — |
-
-### Memory & Learning
-
-| Tool | Description | UI App |
-|------|-------------|--------|
-| `trie_tell` | Report an incident to build the agent's memory | — |
-| `trie_feedback` | Give thumbs up/down on warnings (updates confidence) | — |
-| `trie_memory` | Search and manage issue memory across projects | ✅ Interactive tree |
-| `trie_context` | Read full context (memory + patterns + history) | — |
-| `trie_checkpoint` | Quick save context without running a full scan | — |
-
-### Project & Configuration
-
-| Tool | Description |
-|------|-------------|
-| `trie_init` | Initialize bootstrap files, detect stack, suggest skills |
-| `trie_project` | View and manage project info (.trie/PROJECT.md) |
-| `trie_reconcile` | Sync from context.json after rebases or multi-device edits |
-
-### Security & Compliance Skills
-
-| Tool | What It Analyzes |
-|------|------------------|
-| `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` | Licensing, ToS, accessibility, IP, GDPR/CCPA, e-commerce, marketing, COPPA |
-
-### Code Quality Skills
-
-| Tool | What It Analyzes |
-|------|------------------|
-| `trie_bugs` | Null safety, edge cases, async issues, race conditions |
-| `trie_types` | Type errors, missing annotations, null checks |
-| `trie_architecture` | Code organization, SOLID principles, N+1 queries, scalability |
-| `trie_performance` | Memory leaks, inefficient algorithms, bundle size |
-| `trie_test` | Missing test coverage, test quality, edge case coverage |
-| `trie_clean` | Clean up AI-generated "vibe code": find common mistakes and quick fixes |
-
-### UI/UX Skills
-
-| Tool | What It Analyzes | UI App |
-|------|------------------|--------|
-| `trie_accessibility` | WCAG 2.1 AA: icon-only buttons, touch targets, heading levels, ARIA validation, 20+ checks. **Guardian auto-suggests visual QA when critical a11y issues found.** | — |
-| `trie_design` | AI slop detection, verified token systems, contrast validation, design health scoring | — |
-| `trie_ux` | User testing simulations: happy path, security tester, confused user, impatient user | — |
-| `trie_visual_qa` | Static CSS/layout analysis: CLS risks, responsive patterns, overflow issues | — |
-| `trie_visual_qa_browser` | **Browser screenshots** at mobile/tablet/desktop for Guardian visual analysis (requires dev server) | ✅ Screenshot gallery |
-| `trie_e2e` | End-to-end test coverage, user flow validation | — |
-| `trie_pr_review` | **PR reviews**: File-by-file diff viewer with inline actions | ✅ Interactive diff viewer |
-
-### Operations Skills
-
-| Tool | What It Analyzes |
-|------|------------------|
-| `trie_devops` | Config issues, logging, environment variables, deployment patterns |
-| `trie_data_flow` | Data flow analysis, state management, API contracts |
-| `trie_production_ready` | Production gate: health endpoints, graceful shutdown, security headers, rate limiting |
-| `trie_moneybags` | 💰 Estimates dollar cost of bugs scaled to your user count |
-| `trie_comprehension` | Plain language explanations for non-technical stakeholders |
-
-### Special Skills (Manually Invoked)
-
-| Tool | Description |
-|------|-------------|
-| `trie_super_reviewer` | Interactive PR reviews: walks through changes file-by-file with AI guidance |
-| `trie_agent_smith` | Ultimate AI code enforcer—43 specialized hunters targeting AI-generated anti-patterns |
-
-### Custom & External Skills
-
-| Tool | Description |
-|------|-------------|
-| `trie_create_skill` | Create a custom skill from a PDF, TXT, or MD document |
-| `trie_save_skill` | Save a custom skill configuration |
-| `trie_list_skills` | List all installed skills (external and custom) |
-| `trie_skill_review` | Apply installed external/custom skills to code review |
-
----
-
-## CLI Commands
-
-```bash
-# Bootstrap (installs git hooks, detects stack, suggests skills)
-trie init
-
-# Report an incident (builds memory)
-trie tell "users can't log in after my push"
-
-# Quick check before pushing (< 500ms, no LLM)
-trie check
-
-# Generate CI/CD workflow (NEW!)
-trie ci                    # Full workflow with SARIF + memory caching
-trie ci --minimal          # Minimal workflow
-trie ci --dry-run          # Preview without creating files
-
-# Give feedback on last warning
-trie ok      # Helpful - increases confidence
-trie bad     # Not helpful - decreases confidence
-
-# Pause warnings for 1 hour
-trie quiet
-
-# View memory tree, patterns, and health
-trie status
-
-# Full scan with intelligent skill selection
-trie scan
-
-# Scan specific directory
-trie scan --dir ./src
-
-# Scan with specific skills
-trie scan --skills security,privacy,bugs
-
-# Watch mode (proactive nudging while you code)
-trie watch
-
-# Output JSON report
-trie scan --format json --output report.json
-
-# Quick save (checkpoint without full scan)
-trie checkpoint "finished auth flow"
-
-# Search issue memory
-trie memory search "SQL injection"
-
-# View cross-project patterns
-trie memory global patterns
-
-# Guardian Agency commands
-trie guardian goals           # View active goals and progress
-trie guardian hypotheses      # View hypotheses and their confidence
-trie guardian metrics         # View agent effectiveness metrics
-trie guardian risk src/auth   # Get risk prediction for a file/directory
-
-# List available skills
-trie skills list
-
-# Browse skill categories (150+ skills across 12 categories)
-trie skills list categories
-
-# Install an external skill
-trie skills add vercel-labs/agent-skills vercel-react-best-practices
-```
-
-### CLI vs MCP Tools
-
-| Use Case | Tool | When to Use |
-|----------|------|-------------|
-| **Interactive coding** | MCP tools (`trie_scan`, `trie_check`, `trie_tell`) | Working inside Cursor/Claude Code |
-| **Terminal/CI** | CLI (`trie scan`, `trie check`, `trie tell`) | Running from terminal, CI pipelines, scripts |
-| **VS Code** | VS Code extension | Using VS Code (not Cursor/Claude Code) |
-
----
-
-## Built-in Scouts
-
-Trie has ONE guardian agent that intelligently deploys these 26 autonomous scouts (sophisticated analyzers with domain expertise).
-
-### Security & Compliance (4 scouts)
-
-| Scout | Description |
-|-------|-------------|
-| **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** | Comprehensive app legal: licensing, ToS, accessibility, IP, GDPR/CCPA, e-commerce, COPPA, marketing compliance |
-
-### Code Quality (6 scouts)
-
-| Scout | Description |
-|-------|-------------|
-| **TypeCheck** | Type errors, missing annotations, null checks |
-| **Bug Finding** | Null safety, edge cases, async issues, race conditions |
-| **Software Architect** | Code organization, SOLID principles, N+1 queries, scalability |
-| **Test** | Missing test coverage, test quality, edge case coverage |
-| **Performance** | Memory leaks, inefficient algorithms, bundle size |
-| **Trie Clean** | Clean up AI-generated "vibe code": find common mistakes and quick fixes |
-
-### UI/UX (5 scouts)
-
-| Scout | Description |
-|-------|-------------|
-| **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 (6 scouts)
-
-| Scout | 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 |
-| **Skill Review** | Applies external and custom skills to code review |
-
----
-
-## Accessibility Skill (v2.0)
-
-The Accessibility Skill 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>
-
-Accessibility Score: 65/100
-ℹ️ Consider running 'trie_visual_qa_browser' to capture screenshots for Guardian visual analysis of these accessibility issues.
-```
-
-### Guardian + Visual QA Integration
-
-When the accessibility skill finds **critical or multiple serious issues**, the **Guardian agent automatically suggests** running browser-based visual QA:
-
-```bash
-# Guardian detects accessibility issues during scan
-$ trie scan src/components/
-
-🛡️ Guardian Insight
-Priority: 7 | Category: quality
+- **Learns from your mistakes** - Remember when you broke authentication last month? Trie does too.
+- **Prevents repeat bugs** - Warns you before you make the same mistake twice
+- **Works everywhere** - Same intelligence whether you're coding, committing, or deploying
+- **Speaks plain English** - No cryptic error codes at 2 AM
 
-Found 5 accessibility issues that could block users. 
-Screenshots would help validate real impact.
-
-Suggested Action: Capture screenshots for visual analysis
-Command: trie_visual_qa_browser url:"http://localhost:3000"
-
-Affected Files:
-• Button.tsx
-• Modal.tsx
-• Form.tsx
-
-Issue Breakdown:
-• critical: 2
-• serious: 3
-```
-
-**How it works:**
-
-1. **Accessibility skill** runs static analysis on UI code (JSX, TSX, Vue, etc.)
-2. Finds critical/serious WCAG violations (missing alt text, no focus indicators, etc.)
-3. **Guardian** sees pattern: accessibility issues that need visual validation
-4. **Guardian suggests** running `trie_visual_qa_browser` to capture screenshots
-5. Run the command (requires your dev server running)
-6. **Guardian analyzes screenshots** with AI vision to verify real-world impact
-7. Get actionable feedback on actual rendering issues
-
-**Example workflow:**
-
-```bash
-# 1. Start your dev server
-$ npm run dev
-# Dev server running on http://localhost:3000
-
-# 2. Scan finds accessibility issues
-$ trie scan src/components/
-# Guardian: "Screenshots would help validate real impact"
-
-# 3. Capture screenshots at multiple viewports
-$ trie_visual_qa_browser url:"http://localhost:3000"
-# 📸 Capturing: mobile (375x812), tablet (768x1024), desktop (1440x900)
-
-# 4. Guardian analyzes with vision AI
-# Returns: "Focus indicators invisible on mobile, icon button 
-# has no visible label, heading hierarchy broken causing 
-# screen reader confusion"
-```
-
-**Why this matters:**
+## Quick Start
 
-- **Static analysis** finds code patterns but can't see the rendered page
-- **Browser screenshots** show what users actually experience
-- **AI vision** validates whether issues truly impact accessibility
-- **Guardian synthesizes** both code analysis + visual evidence for better insights
+### 1. Install Trie
 
-### Usage
+Make sure you have Node.js installed, then:
 
 ```bash
-# Run accessibility scan
-trie scan --agents accessibility
+# Install Trie globally
+npm install -g trie
 
-# Full UI scan (accessibility + design)
-trie scan --agents accessibility,design-engineer
-
-# MCP usage
-trie_accessibility
+# Set up in your project
+cd your-project
+trie init
 ```
 
----
-
-## Moneybags Skill
-
-The Moneybags skill 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:
+### 2. Run Your First Scan
 
 ```bash
-# Default (250 users - early stage app)
+# Scan your entire codebase
 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 Skill (v2.0)
-
-The Legal Skill 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 Skill (v2.0)
-
-The Design Engineer skill 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';
+# Quick health check
+trie status
 ```
 
----
+### 3. Start Teaching Trie
 
-## Special Skills
+When bugs happen, tell Trie about them:
 
-These skills are **manually invoked**—they don't run during regular guardian checks.
-
-### Super Reviewer
+```bash
+# Report an incident
+trie tell "Users can't log in after the password reset"
 
-Interactive PR reviews: walks through changes file-by-file with AI guidance.
+# Before pushing code
+trie check
 
-```
-Run trie_super_reviewer on this PR
+# Give feedback on warnings
+trie ok    # This warning was helpful
+trie bad   # This was a false alarm
 ```
 
-### Agent Smith
+## Why Trie Exists
 
-The ultimate AI code enforcer—35+ specialized pattern hunters targeting AI-generated anti-patterns. Runs a swarm of hunters to find "vibe-coded" patterns.
+Building apps with AI tools like Cursor and Claude is incredibly fast - but maintaining them alone is a nightmare. You fix a bug and forget why it happened. The same issues keep coming back. Your codebase grows faster than your memory of it.
 
-```
-Run trie_agent_smith on this codebase
-```
+Trie solves this by being your **persistent memory**. It remembers what broke before, learns patterns across your projects, and warns you before you ship risky code.
 
----
+## Key Features
 
-## Custom Skills
+### Smart Memory
+- **Git-based storage** - Your project's memory travels with your code in `.trie/` folder
+- **Cross-project learning** - Patterns discovered in one project help prevent bugs in others
+- **Incident tracking** - Build a searchable history of what went wrong and why
 
-Create your own skills from PDFs, style guides, or documentation. Custom skills are portable review rules that travel with your project—they work in Cursor, Claude Code, CI/CD, and everywhere in between.
+### Intelligent Analysis
+- **26 built-in scouts** - Automated analyzers for security, performance, accessibility, and more
+- **Custom skills** - Add external analyzers from the community
+- **Risk scoring** - Intelligent priority ranking based on your actual incident history
 
-### Create a Custom Skill
+### Development Integration
+- **Git hooks** - Automatic checks before commits and pushes
+- **Watch mode** - Real-time monitoring while you code
+- **Fast performance** - Sub-500ms checks, won't slow down your workflow
 
-```
-Create a custom skill from my-style-guide.pdf called "brand_guidelines"
-```
+### Developer Experience
+- **Plain English warnings** - "This auth change broke twice before" instead of cryptic codes
+- **Multiple interfaces** - CLI, MCP tools for Claude/Cursor, visual dashboards
+- **Flexible workflow** - Works with any editor, any git workflow, any deployment setup
 
-Or use the MCP tool directly:
+## How It Works
 
-```
-trie_create_skill with filePath: "./docs/style-guide.pdf", skillName: "brand_guidelines"
-```
+### The Guardian System
 
-### How It Works
+Trie uses a "Guardian Agent" architecture:
 
-1. **Parse** — Trie extracts text from your document (PDF, TXT, MD)
-2. **Compress** — AI distills the document into actionable rules
-3. **Register** — The skill is saved to `.trie/skills/custom/` and runs automatically during scans
+1. **Scouts** continuously analyze your code for potential issues
+2. **Guardian** receives scout reports and decides what matters based on your history
+3. **Memory Tree** stores incident patterns using a trie data structure for fast lookups
+4. **Learning Loop** improves predictions based on your feedback
 
-### List Custom Skills
+### Memory That Travels
 
 ```
-trie_list_skills
+your-project/
+├── .trie/
+│   ├── memory/          # Incident history
+│   ├── patterns/        # Learned patterns
+│   ├── context.json     # Project knowledge graph
+│   └── config.json      # Settings
+├── src/
+└── .git/
 ```
 
-Custom skills are stored in `.trie/skills/custom/` in your project directory.
-
----
-
-## External Skills
-
-Install reusable capabilities from Vercel, Anthropic, Expo, Stripe, Supabase, or any GitHub repository. Skills are knowledge/instructions that agents apply during code review.
-
-### Key Concept: Agents vs Skills
-
-| | Agent (Brain) | Skill (Knowledge) |
-|---|---------------|-------------------|
-| **Decides when to run** | Yes | No - invoked by agent |
-| **Has its own logic** | Yes | No - detection patterns |
-| **Makes decisions** | Yes | No - follows rules |
-| **Examples** | SecurityAgent, TriagerAgent | react-best-practices, brand_guidelines |
+The `.trie/` folder commits with your code, so your project's intelligence is preserved and shared across:
+- Local development
+- CI/CD pipelines
+- Team members
+- Different machines
 
-**Two types of skills:**
-- **External Skills** — Installed from GitHub repos (e.g., `vercel-labs/agent-skills`)
-- **Custom Skills** — Created from your documents (PDFs, style guides, books)
+## Core Workflow
 
-Both skill types are applied by the **skill-review agent** during scans and travel with your project.
-
-### Install a Skill
-
-**CLI:**
+### 1. Teaching Phase
 ```bash
-# From Vercel's skills repository
-trie-agent skills add vercel-labs/agent-skills vercel-react-best-practices
-
-# From Anthropic's skills
-trie-agent skills add anthropics/skills frontend-design
-
-# From any GitHub repo with a SKILL.md
-trie-agent skills add myorg/internal-standards code-style
-```
-
-**Using MCP (Cursor/Claude Code):**
-```
-Install the vercel-react-best-practices skill from vercel-labs/agent-skills
-```
+# Something breaks in production
+trie tell "Payment processing failed for EU customers"
 
-### Browse Available Skills
-
-Trie includes 150+ skills organized into 12 categories:
-
-```bash
-# List all categories
-trie-agent skills list categories
-
-# Browse skills by category
-trie-agent skills list marketing      # 23 skills (SEO, copywriting, CRO, etc.)
-trie-agent skills list development    # 25 skills (TDD, debugging, code review, etc.)
-trie-agent skills list security       # 10 skills (semgrep, codeql, Trail of Bits, etc.)
-trie-agent skills list design         # 9 skills (canvas, brand, UI/UX, etc.)
-trie-agent skills list documents      # 5 skills (pdf, xlsx, pptx, docx, etc.)
-trie-agent skills list productivity   # 17 skills (meetings, diagrams, READMEs, etc.)
+# Trie learns: "payments/" + "EU" + "failed" = high risk pattern
 ```
 
-### List Installed Skills
-
+### 2. Prevention Phase
 ```bash
-trie-agent skills list
-```
+# Later, you modify payment code
+git add src/payments/eu-handler.js
+git commit -m "Update EU payment logic"
 
-Output:
+# Trie warns: "This area broke 2 weeks ago with EU payments. Consider extra testing."
 ```
-Installed Skills (2):
-
-  vercel-react-best-practices (applied 12x)
-    React and Next.js performance optimization
-    Source: vercel-labs/agent-skills
 
-  web-design-guidelines (applied 8x)
-    Modern web design patterns and accessibility
-    Source: vercel-labs/agent-skills
+### 3. Feedback Loop
+```bash
+# Warning was helpful
+trie ok
 
-These skills are applied by the skill-review agent during scans.
+# Warning was wrong
+trie bad
 
-Explore more: trie skills list categories
+# Trie adjusts confidence for similar future warnings
 ```
 
-### How It Works
+## Advanced Features
 
-1. **Install** - Skills are cloned from GitHub to `.trie/skills/`
-2. **Load** - The skill-review agent loads installed skills on startup
-3. **Apply** - During scans, the agent applies skill knowledge to code review
-4. **Track** - Usage is recorded in your project context
-
-### Remove a Skill
+### Goals & Hypotheses
+Set improvement goals and test theories:
 
 ```bash
-trie-agent skills remove react-best-practices
-```
-
-### Skill Format
+# Set a goal
+trie goal add "Reduce authentication bugs by 50%"
 
-Skills follow the [Agent Skills specification](https://agentskills.io/specification):
+# Add a hypothesis
+trie hypothesis add "Code reviews reduce bug rate"
 
-```
-skill-name/
-  SKILL.md          # Required: YAML frontmatter + instructions
-  scripts/          # Optional: executable code
-  references/       # Optional: additional docs
-  assets/           # Optional: templates, data
+# Trie tracks progress and validates hypotheses over time
 ```
 
-Example SKILL.md:
-```yaml
----
-name: react-best-practices
-description: React and Next.js performance optimization
----
+### Watch Mode
+Real-time monitoring with visual dashboard:
 
-# React Best Practices
-
-## Guidelines
-1. Avoid creating components inside render
-2. Use React.memo for expensive components
-3. Prefer useCallback for event handlers
-...
+```bash
+trie watch
 ```
 
-### MCP Resource
+Interactive panels for goals, memory, scout activity, and more.
 
-Access installed skills via MCP:
-```
-Read trie://skills
-```
+### Integration with AI Coding Tools
 
-### Skill Sources
-
-Skills can come from any GitHub repository with a SKILL.md file:
-
-| Source | Examples |
-|--------|----------|
-| [Vercel](https://skills.sh) | vercel-react-best-practices, web-design-guidelines |
-| [Anthropic](https://github.com/anthropics/skills) | frontend-design, webapp-testing, mcp-builder, pdf, xlsx, docx |
-| [Expo](https://github.com/expo/skills) | building-native-ui, upgrading-expo, expo-deployment (9 skills) |
-| [Stripe](https://github.com/stripe/ai) | stripe-best-practices |
-| [Better Auth](https://github.com/better-auth/skills) | better-auth-best-practices, create-auth-skill |
-| [Remotion](https://github.com/remotion-dev/skills) | remotion-best-practices |
-| [Callstack](https://github.com/callstackincubator/agent-skills) | react-native-best-practices |
-| [Supabase](https://github.com/supabase/agent-skills) | supabase-postgres-best-practices |
-| [Trail of Bits](https://github.com/trailofbits/skills) | semgrep, codeql, secure-workflow-guide (10 skills) |
-| [Vue/Nuxt](https://github.com/hyf0/vue-skills) | vue-best-practices, pinia-best-practices |
-| [Three.js](https://github.com/cloudai-x/threejs-skills) | threejs-fundamentals, threejs-animation (10 skills) |
-| [obra/superpowers](https://github.com/obra/superpowers) | test-driven-development, systematic-debugging (14 skills) |
-| [Marketing](https://github.com/coreyhaines31/marketingskills) | seo-audit, copywriting, pricing-strategy (23 skills) |
-| Your org | Internal standards, style guides, compliance docs |
-
-### Auto-Suggested Skills
-
-When you run `trie init`, Trie automatically detects your dependencies and suggests relevant skills:
-
-| Dependency | Skills Suggested |
-|------------|------------------|
-| `next`, `react` | vercel-react-best-practices, web-design-guidelines, frontend-design |
-| `vue`, `nuxt` | vue-best-practices, pinia-best-practices, nuxt skills |
-| `expo` | 9 Expo skills (building-native-ui, upgrading-expo, etc.) |
-| `three` | 10 Three.js skills (fundamentals, animation, shaders, etc.) |
-| `@supabase/supabase-js` | supabase-postgres-best-practices |
-| `stripe` | stripe-best-practices |
-| `better-auth` | better-auth-best-practices |
-| `playwright` | webapp-testing, e2e-testing-patterns |
-| `tailwindcss` | tailwind-design-system, responsive-design |
-| `typescript` | typescript-advanced-types |
-| And 20+ more... | Run `trie init` to see suggestions for your stack |
-
-### Skill Gating
-
-Skills can declare requirements in their frontmatter. Only skills whose requirements are met are loaded.
-
-**Simple (backwards compatible):**
-
-```yaml
----
-name: react-best-practices
-description: React and Next.js optimization
-requires: [react, next]
----
-```
+Trie provides MCP (Model Context Protocol) tools for seamless integration with Claude, Cursor, and other AI assistants:
 
-**Extended requirements:**
-
-```yaml
----
-name: docker-deploy-skill
-description: Docker deployment best practices
-requirements:
-  deps: [docker-compose]          # npm deps (all required)
-  anyDeps: [react, vue, svelte]   # At least one required
-  env: [DOCKER_HOST, CI]          # Environment variables
-  bins: [docker, kubectl]         # Binaries in PATH
-  configFiles: [Dockerfile]       # Files that must exist
----
-```
+- `trie_scan` - Analyze code with AI-friendly output
+- `trie_check` - Quick risk assessment
+- `trie_tell` - Report incidents
+- `trie_memory` - Search incident history
+- `trie_fix` - Apply suggested fixes
 
-| Check | What It Does |
-|-------|--------------|
-| `deps` | All listed npm packages must be in package.json |
-| `anyDeps` | At least one must be present (OR condition) |
-| `env` | Environment variables must be set |
-| `bins` | Binaries must be available in PATH |
-| `configFiles` | Files must exist in project root |
+## Built-in Scouts
 
-When you install skills, they're automatically filtered based on your project:
-- A React skill with `requires: [react]` only loads in React projects
-- A Docker skill with `requirements.bins: [docker]` only loads when Docker is installed
-- Skills without requirements always load
+Trie includes 26 specialized analyzers:
 
-This prevents irrelevant skills from cluttering your scans.
+### Security & Compliance
+- **Security Scout** - Vulnerabilities, injection risks, secrets
+- **Privacy Scout** - PII handling, GDPR/HIPAA compliance
+- **Legal Scout** - Regulatory compliance patterns
+- **SOC2 Scout** - Access controls, audit trails
 
----
+### Code Quality
+- **Bug Scout** - Common bugs, edge cases, null safety
+- **Architecture Scout** - SOLID principles, scalability issues
+- **Types Scout** - Type errors, missing annotations
+- **Clean Scout** - AI-generated code cleanup
 
-## Bootstrap System
+### User Experience
+- **Accessibility Scout** - WCAG compliance, screen readers
+- **UX Scout** - User journey analysis, usability issues
+- **Design Scout** - Visual consistency, design systems
 
-Trie works out of the box - no setup required. Run `trie init` to optionally create context files for customization.
+### Operations
+- **DevOps Scout** - Configuration issues, deployment patterns
+- **Performance Scout** - Speed bottlenecks, optimization opportunities
 
-### Files (all optional)
+[View all scouts →](#built-in-scouts)
 
-| File | Purpose |
-|------|---------|
-| `.trie/RULES.md` | Your coding standards (edit to customize) |
-| `.trie/TEAM.md` | Team ownership and escalation paths |
-| `.trie/PROJECT.md` | Project overview and conventions |
-| `.trie/BOOTSTRAP.md` | First-run checklist (auto-deleted when complete) |
+## Installation & Setup
 
-### Initialize
+### Requirements
+- Node.js 16 or higher
+- Git repository
 
-**CLI:**
+### Installation
 ```bash
-trie init
-```
+# Install globally
+npm install -g trie
 
-**MCP:**
+# Or use npx for one-time runs
+npx trie scan
 ```
-trie_init
-```
-
-This auto-detects your stack and suggests relevant skills:
-
-```
-Detected Stack:
-  Framework: Next.js 14.0.0
-  Language: TypeScript
-  Database: Supabase
-  Auth: Better Auth
-
-Suggested Skills (based on your stack):
-  trie skills add vercel-labs/agent-skills vercel-react-best-practices
-  trie skills add vercel-labs/agent-skills web-design-guidelines
-  trie skills add supabase/agent-skills supabase-postgres-best-practices
-  trie skills add better-auth/skills better-auth-best-practices
-  trie skills add wshobson/agents typescript-advanced-types
-
-Explore skill categories:
-  trie skills list documents        # 5 skills
-  trie skills list marketing        # 23 skills
-  trie skills list development      # 25 skills
-  trie skills list security         # 10 skills
-  trie skills list productivity     # 17 skills
-  trie skills list categories       # see all 12 categories
-
-Browse all skills: https://skills.sh
-```
-
-### Commands
 
+### Project Setup
 ```bash
-# Initialize bootstrap files
+# Initialize in your project
+cd your-project
 trie init
 
-# Check bootstrap status
-trie init status
-
-# Mark bootstrap complete (deletes BOOTSTRAP.md)
-trie init complete
+# This creates:
+# - .trie/ directory with initial config
+# - Git hooks for automatic checking
+# - Bootstrap files (optional)
 ```
 
-### MCP Resources
+### AI Tool Integration
 
+**For Claude (MCP)**:
+Add to your MCP settings:
+```json
+{
+  "mcpServers": {
+    "trie": {
+      "command": "trie",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
-trie://bootstrap    # Bootstrap status
-trie://rules        # User-defined coding standards
-trie://team         # Team ownership info
-```
-
----
-
-## Issue Memory
 
-Trie stores all detected incidents for search, pattern discovery, and cross-project learning. Uses BM25 ranking (same algorithm as Elasticsearch) for intelligent search.
+**For Cursor/VS Code**:
+Install the Trie extension from your editor's marketplace.
 
-### Memory System
+## CLI Reference
 
-**Data Integrity Improvements:**
-- **Atomic writes**: Temp file + rename pattern prevents corruption on crash/interrupt
-- **SHA256 hashing**: Cryptographic deduplication (no collision risk)
-- **Backup rotation**: 5 automated backups with recovery commands
-- **Zod validation**: Schema validation catches malformed data early
-
-JSON files perform well at Trie's scale (1,000-10,000 issues). SQLite, vector embeddings, and session management add complexity without proportional value for a security scanning CLI tool.
-
-### Local Memory (`.trie/memory/`)
-
-Incidents from each `trie tell` command are stored locally:
-- `issues.json` - Searchable incident index with BM25 ranking
-- `patterns.json` - Discovered patterns (3+ incidents with confidence scores)
-- `YYYY-MM-DD.md` - Daily incident logs (human-readable)
-
-### Search Incidents
-
-**CLI:**
+### Basic Commands
 ```bash
-# Search by keyword
-trie memory search "SQL injection"
-
-# View recent incidents
-trie memory recent
-
-# Show statistics
-trie memory stats
+trie init          # Set up Trie in your project
+trie scan          # Analyze codebase with intelligent skill selection
+trie status        # View project health and memory stats
+trie check         # Quick risk check before pushing (< 500ms)
+trie tell "<msg>"  # Report an incident to build memory
 ```
 
-**MCP:**
-```
-trie_memory action="search" query="SQL injection"
-trie_memory action="stats"
-trie_memory action="recent" limit=10
-```
-
-### Cross-Project Memory (`~/.trie/memory/`)
-
-Patterns are tracked across all your projects. After each `trie scan` or `trie tell`, patterns are automatically recorded to your home directory (`~/.trie/memory/`) for cross-project learning—no manual sync needed.
-
+### Memory Management
 ```bash
-# View patterns across projects
-trie memory global patterns
-
-# List tracked projects
-trie memory global projects
-
-# Search global patterns
-trie memory global search "authentication"
-```
-
-### How It Works
-
-1. **Automatic Sync**: Every `trie scan` and `trie tell` writes to both local (`.trie/memory/`) and global (`~/.trie/memory/`) memory automatically
-2. **BM25 Search**: Uses term frequency, inverse document frequency, and document length normalization for ranking
-3. **Pattern Detection**: After 3+ incidents in same area, pattern is automatically created with confidence score
-4. **Cross-Project Tracking**: Same pattern in multiple projects increments occurrence count and tracks which projects have it
-5. **Confidence Updates**: `trie ok` / `trie bad` feedback adjusts pattern confidence immediately
-6. **Trie-Powered Discovery**: Hot path detection via tree traversal completes in < 10ms
-
-### Memory Structure
-
+trie memory search "auth"     # Search incident history
+trie memory stats             # View memory statistics
+trie memory purge smart       # Clean up old/resolved issues
 ```
-.trie/memory/                      # Local (per-project, committed to git)
-├── issues.json                    # All incidents with metadata
-├── compacted-summaries.json       # Historical summaries (auto-compacted)
-├── 2024-01-15.md                  # Daily log
-└── 2024-01-16.md
-
-~/.trie/memory/                    # Global (home directory, cross-project)
-├── global-patterns.json           # Patterns seen across projects
-├── GLOBAL_MEMORY.md               # Auto-generated summary
-└── projects/                      # Per-project summaries
-    ├── my-app.json
-    └── another-project.json
-```
-
----
-
-## Project Info Registry
-
-Store important project-specific information in `.trie/PROJECT.md` that's automatically available to all AI tools.
 
-### Why Project Info?
-
-When you work across multiple tools (Cursor, Claude Code, GitHub Actions, CLI), context gets lost. The Project Info Registry solves this by providing a single source of truth for:
-
-- Project description and purpose
-- Technology stack and frameworks
-- Architecture decisions and patterns
-- Coding conventions and style guidelines
-- Environment info (URLs, API endpoints)
-- Team ownership and contacts
-- Compliance requirements
-- Custom instructions for AI assistants
-
-### Create PROJECT.md
-
-**Using CLI:**
+### Goals & Learning
 ```bash
-trie-agent project init
+trie goal add "<goal>"           # Set improvement goal
+trie hypothesis add "<theory>"   # Test a hypothesis
+trie goal list                   # View progress
 ```
 
-**Using MCP (Cursor/Claude Code):**
-```
-trie_project action="init"
-```
-
-This creates a template at `.trie/PROJECT.md` with sections ready to fill in.
-
-### View Project Info
-
-**CLI:**
+### Feedback & Training
 ```bash
-trie-agent project
-```
-
-**MCP:**
-```
-trie_project action="view"
-```
-
-**MCP Resource:**
-```
-Read trie://project
-```
-
-### Update Sections
-
-**MCP:**
-```
-trie_project action="update" section="Technology Stack" content="- **Language:** TypeScript\n- **Framework:** Next.js 14\n- **Database:** PostgreSQL"
-```
-
-### How It Works
-
-```
-your-project/
-├── .trie/
-│   └── PROJECT.md    ← Your project context
-├── src/
-└── package.json
-```
-
-The PROJECT.md file is:
-- **Committed to git** — context travels with your code
-- **Available via `trie://project`** — AI tools can read it directly
-- **Integrated into `trie://context`** — included in overall project context
-- **Per-project** — each project has its own file
-
-### Template Sections
-
-| Section | What to Include |
-|---------|-----------------|
-| **Project Overview** | What does this project do? Who is it for? |
-| **Technology Stack** | Languages, frameworks, databases, cloud services |
-| **Architecture** | Key patterns, system design, important decisions |
-| **Coding Conventions** | Style rules, naming conventions, patterns to follow |
-| **Environment** | Dev/staging/prod URLs, API endpoints |
-| **Team** | Who owns what, contact info |
-| **Compliance** | GDPR, SOC2, HIPAA requirements |
-| **AI Instructions** | Special instructions for AI assistants |
-
-### Example PROJECT.md
-
-```markdown
-## Project Overview
-
-E-commerce platform for sustainable products. 
-Focus on fast checkout and mobile-first UX.
-
-## Technology Stack
-
-- **Language:** TypeScript
-- **Framework:** Next.js 14 (App Router)
-- **Database:** PostgreSQL with Prisma ORM
-- **Hosting:** Vercel + Supabase
-
-## Architecture
-
-- Server Components by default, Client Components only when needed
-- tRPC for type-safe API calls
-- Zustand for client state
-
-## Coding Conventions
-
-- Use `pnpm` for package management
-- Prefer named exports over default exports
-- Use Tailwind CSS, no inline styles
-- Tests required for payment-related code
-
-## AI Instructions
-
-When working on this project:
-1. Always use Server Components unless client interactivity is needed
-2. Check for accessibility issues (we target WCAG AA)
-3. Payment code must be reviewed by security agent before commit
+trie ok          # Last warning was helpful
+trie bad         # Last warning was wrong
+trie pause       # Disable warnings for 1 hour
 ```
 
-### Multi-Project Support
-
-Each project has its own `.trie/PROJECT.md`:
-
-```
-~/projects/
-├── project-a/.trie/PROJECT.md  ← Project A's context
-├── project-b/.trie/PROJECT.md  ← Project B's context  
-└── project-c/.trie/PROJECT.md  ← Project C's context
+### Watch Mode
+```bash
+trie watch       # Start interactive monitoring dashboard
 ```
 
-When you open Project A in Cursor, it reads Project A's context. Switch to Project B, and it reads Project B's context. No configuration needed.
-
----
-
-## AI-Enhanced Mode
-
-Trie works in two modes:
-
-| Mode | Description |
-|------|-------------|
-| **Pattern-Only** (default) | Fast regex matching for specific patterns (exposed secrets, async forEach, etc.). Limited coverage. |
-| **AI-Enhanced** | Full analysis: pattern detection + AI validation + deeper issue discovery. **Recommended.** |
-
-### Enable AI Mode
-
-**For MCP usage (Cursor/Claude Code):**
-
-Add the API key to your MCP configuration:
+## Configuration
 
+### Scan Behavior
+Create `.trie/config.json`:
 ```json
 {
-  "mcpServers": {
-    "Trie": {
-      "command": "npx",
-      "args": ["@triedotdev/mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "sk-ant-..."
-      }
-    }
+  "scanOptions": {
+    "maxConcurrency": 4,
+    "timeoutMs": 30000,
+    "includeNodeModules": false
+  },
+  "autoEscalation": {
+    "enabled": true,
+    "webhookUrl": "https://hooks.slack.com/...",
+    "quietHours": { "start": "21:00", "end": "08:00" }
   }
 }
 ```
 
-**For CLI usage (terminal/CI):**
-
-Add the API key to your project's `.env.local` file:
-
-```bash
-echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env.local
-```
+### Git Hooks
+Installed automatically with `trie init`:
 
-Then load it before running CLI commands:
+- **pre-commit** - Quick scan of staged files
+- **post-commit** - Update context graph
+- **pre-push** - Block critical issues (can be bypassed)
 
+To bypass:
 ```bash
-set -a; source .env.local; set +a
-trie-agent scan
+git push --no-verify              # Skip all hooks
+TRIE_BYPASS=1 git push           # Skip Trie but log bypass
 ```
 
-> **Important:** MCP config only applies to the MCP server. CLI commands need the key in your shell environment.
-
-When AI is enabled, you'll see:
-- `AI-powered analysis enabled` in output
-- `[AI VALIDATED]` and `[AI FOUND]` tags on issues
-- Richer fix recommendations
-
----
-
 ## CI/CD Integration
 
-The guardian agent works in CI/CD by reading your project's `.trie/` directory—the same memory, patterns, and incident history you've built locally.
-
-### Quick Setup (Recommended)
-
-Use the `trie ci` command to generate a GitHub Actions workflow:
-
+### GitHub Actions
 ```bash
-# Generate full workflow with SARIF + memory caching
-trie ci
+# Generate workflow file
+trie ci github
 
-# Generate minimal workflow
-trie ci --minimal
+# Creates .github/workflows/trie.yml with:
+# - Full codebase scan
+# - Memory caching for speed
+# - SARIF upload for GitHub Security tab
+```
 
-# Preview without creating files
-trie ci --dry-run
+### Custom CI
+```bash
+# In your CI pipeline
+npm install -g trie
+trie scan --output=sarif > trie-results.sarif
 ```
 
-**What it creates:**
+## Memory System
 
-`.github/workflows/trie-scan.yml` with:
-- ✅ Memory caching across runs (enables cross-run learning)
-- ✅ SARIF output for GitHub Security tab
-- ✅ Pattern recognition: "This issue was introduced 3 PRs ago"
-- ✅ Trend tracking: improving, stable, or declining
-- ✅ Historical context: "Similar issue fixed in PR #42"
+### Local Memory
+Each project stores its own memory in `.trie/memory/`:
+- Incident reports and patterns
+- Risk scores and confidence levels
+- Performance over time
 
-**Next steps after running `trie ci`:**
+### Cross-Project Memory
+Global patterns stored in `~/.trie/memory/`:
+- Patterns that apply across projects
+- Skill effectiveness data
+- Your personal coding patterns
 
-1. Add `ANTHROPIC_API_KEY` to GitHub Secrets (Settings → Secrets → Actions)
-2. Commit and push:
-   ```bash
-   git add .github/workflows/trie-scan.yml
-   git commit -m "Add Trie security scan with memory"
-   git push
-   ```
+### Memory Management
+```bash
+# View capacity (default: 10,000 issues)
+trie memory stats
 
-### GitHub Actions
+# Smart cleanup (removes resolved + old low-priority)
+trie memory purge smart
 
-**Manual setup (alternative):**
-
-Or manually add to `.github/workflows/trie.yml`:
-
-```yaml
-name: Trie Guardian
-on: [push, pull_request]
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Need git history for incident context
-      
-      - name: Guardian Check
-        run: |
-          npx @triedotdev/mcp check --fail-on=critical
-```
+# Remove all resolved issues
+trie memory purge resolved
 
-### What Happens in CI
-
-1. **Reads memory**: Loads `.trie/memory/` (incidents, patterns)
-2. **Checks changes**: Analyzes files in current commit
-3. **Risk assessment**: Uses incident history + patterns for scoring
-4. **Plain English**: Reports warnings just like locally
-5. **Fails build**: If critical issues detected (configurable)
-
-### Memory Caching Benefits
-
-When you use `trie ci` to generate workflows, memory is cached across runs:
-
-- **Pattern recognition**: "This issue was introduced 3 PRs ago"
-- **Historical context**: "Similar issue was fixed in PR #42"
-- **Trend tracking**: Improving, stable, or declining
-- **Resolution tracking**: Knows when issues get fixed
-- **Cross-PR learning**: Patterns from one PR inform future PRs
-
-### Advanced Examples
-
-See `.github/workflows/examples.md` for comprehensive workflow examples:
-- Multi-environment scanning (dev/staging/prod)
-- Scheduled security audits
-- Custom output processing
-- Integration with existing tools (ESLint, Snyk, etc.)
-- Memory persistence strategies
-- Organization-wide memory sharing
-- Compliance reporting (SOC2, etc.)
-
-### Full Skill Scan
-
-For deeper analysis (security, privacy, etc.), add a weekly/nightly job:
-
-```yaml
-name: Weekly Guardian Scan
-on:
-  schedule:
-    - cron: '0 2 * * 1'  # Monday 2am
-
-jobs:
-  full-scan:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Run full scan
-        run: |
-          npx @triedotdev/mcp scan --skills security,privacy,soc2
+# Remove issues older than 90 days
+trie memory purge old --days=90
 ```
 
----
-
-## Configuration
-
-### Scan Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `parallel` | Run agents in parallel | `true` |
-| `cache` | Enable result caching | `true` |
-| `maxConcurrency` | Max parallel agents | `4` |
-| `timeoutMs` | Agent timeout in milliseconds | `120000` |
-| `streaming` | Stream progress updates | `true` |
-| `workers` | Use worker threads | `true` |
-
-### Auto-Escalation Setup
+## Custom Skills
 
-Auto-escalate critical security issues to Slack, email, or webhooks.
+### Adding External Skills
+```bash
+# From skill repositories
+trie skill install vercel/ai-best-practices
+trie skill install anthropic/typescript-patterns
 
-**Quick Setup:**
+# From any GitHub repo
+trie skill install username/repo-name
+```
 
-1. Create `.trie/config.json` in your project root
-2. Add escalation configuration:
+### Creating Your Own Skills
+```bash
+# Create from documentation
+trie skill create my-skill --doc=./coding-standards.md
 
-```json
-{
-  "escalation": {
-    "enabled": true,
-    "targets": [
-      {
-        "type": "slack",
-        "enabled": true,
-        "config": {
-          "webhookUrl": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
-          "channel": "#security-alerts",
-          "username": "Trie Guardian"
-        },
-        "forSeverities": ["critical"],
-        "forCategories": ["security", "all"]
-      }
-    ],
-    "cooldownMinutes": 15,
-    "maxEscalationsPerHour": 5,
-    "respectQuietHours": true,
-    "criticalBypassQuietHours": true
-  }
-}
+# This creates a custom analyzer based on your documentation
 ```
 
-**Target Types:**
-
-| Type | Description | Required Config |
-|------|-------------|-----------------|
-| `slack` | Slack webhook | `webhookUrl`, optional `channel`, `username` |
-| `webhook` | Custom POST endpoint | `webhookUrl` |
-| `email` | Email notification | `email` (SMTP config in env) |
+### Skill Format
+Skills are simple markdown files with detection rules:
 
-**Get Slack Webhook URL:**
+```markdown
+# My Custom Skill
 
-1. Go to https://api.slack.com/apps
-2. Create new app or select existing
-3. Enable "Incoming Webhooks"
-4. Add webhook to workspace
-5. Copy webhook URL
+## Detection Rules
+- File patterns: `*.js`, `*.ts`
+- Code patterns: `console.log`, `debugger`
 
-**Multiple Targets:**
+## Analysis
+Look for debugging statements left in production code.
 
-```json
-{
-  "escalation": {
-    "targets": [
-      {
-        "type": "slack",
-        "enabled": true,
-        "config": { "webhookUrl": "..." },
-        "forSeverities": ["critical"],
-        "forCategories": ["security"]
-      },
-      {
-        "type": "webhook",
-        "enabled": true,
-        "config": { "webhookUrl": "https://your-api.com/alerts" },
-        "forSeverities": ["critical", "serious"],
-        "forCategories": ["all"]
-      }
-    ]
-  }
-}
+## Fix Suggestions
+Remove or replace with proper logging.
 ```
 
-**Configuration Options:**
+## Troubleshooting
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `enabled` | Enable auto-escalation | `true` |
-| `cooldownMinutes` | Minutes between escalations of same file | `15` |
-| `maxEscalationsPerHour` | Max escalations per hour | `5` |
-| `respectQuietHours` | Respect quiet hours (9pm-8am) | `true` |
-| `criticalBypassQuietHours` | Critical issues bypass quiet hours | `true` |
+### Common Issues
 
-**Test Your Configuration:**
+**Trie not finding issues**: Your codebase might be very clean, or you haven't taught Trie about your specific patterns yet. Try `trie tell` to report some known issues.
 
-```bash
-# Watch mode will show escalation status
-trie watch
-
-# Check Guardian insights panel (press 'g')
-# You'll see "Auto-escalation: enabled (1 target)" if configured correctly
-```
+**Scans are slow**: Reduce concurrency with `--max-concurrency=2` or exclude large directories in config.
 
-**TUI Configuration:**
+**Too many false positives**: Use `trie bad` to train Trie, and consider adjusting scout sensitivity in config.
 
-Press `c` in watch mode to open Guardian Agent configuration menu (escalation configuration UI coming soon).
-
-### Example
-
-```
-trie_scan with parallel: true, cache: true, maxConcurrency: 8
-```
+**Hooks not working**: Reinstall with `trie init`. Make sure you have write permissions to `.git/hooks/`.
 
----
+### Getting Help
+- GitHub Issues: [Report bugs and request features](https://x.com/louiskishfy)
+- Twitter: [@louiskishfy](https://x.com/louiskishfy) for quick questions
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details.