@triedotdev/mcp 1.0.50 → 1.0.52

package/README.md

@@ -1,96 +1,269 @@
 # Trie
 
-**A central registry for agents and skills that follow you from Cursor to CI/CD and everything in between.**
-
-Download the Trie workspace: https://www.trie.dev
+**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.**
 
+Download the Trie workspace: https://www.trie.dev  
 Follow me on X: https://x.com/louiskishfy
 
-## Why Trie
+## 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.
 
-Trie is purpose-built for the last mile of shipping AI-generated code.
+So I built Trie with a few principles:
 
-The last mile of shipping is where things break—not because your code doesn't work, but because the context you captured while building doesn't travel with you. Trie fixes that. One registry and triager runs identically in Cursor, Claude Code, the CLI, and GitHub Actions—master files that every surface can see, not scattered configs you forget to sync. Ingest your compliance docs, style guides, or internal policies (PDF/TXT/MD/RTF) and Trie compresses them into enforceable agents saved to `.trie/agents/`. Version them in TypeScript, test them locally, deploy them to CI with identical behavior. Triager logs show exactly which agents fired and why—no black-box routing. Built for people who need signal that their AI-generated code is reliable and right for the context they've captured, while they're still building.
+**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*.
 
-## What's New (latest updates)
+**One guardian, not a committee.** Skills, on their own, have no unified view. Trie has 26 specialized skills, but they all feed into one guardian agent that knows the full picture. One brain that watches, learns, and warns. You can also add skills from any repo you find online.
 
-- **Comprehensive Skills Library**: 150+ skills across 12 categories now auto-suggested based on your stack. Run `trie init` to see personalized suggestions, or browse with `trie skills list <category>`. Categories include: marketing (23), development (25), security (10), design (9), documents (5), productivity (17), and more.
+**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.
 
-- **Bootstrap System**: Run `trie init` to auto-detect your stack (framework, language, database). Optionally customize `.trie/RULES.md` for coding standards. Works out of the box - no config required.
+**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."
 
-- **Issue Memory & Cross-Project Learning**: Issues are now stored in `.trie/memory/` with BM25 search (same algorithm as Elasticsearch). Intelligent compaction summarizes old issues instead of deleting them, tracking trends and recurring patterns over time.
+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.
 
-- **Extended Skill Gating**: Skills can now declare requirements for npm dependencies, environment variables, binaries in PATH, and config files. Only skills whose requirements match your project environment are loaded.
+### Key Capabilities
 
-- **External Skills**: Install reusable capabilities from Vercel, Anthropic, Expo, Stripe, Supabase, Trail of Bits, or any GitHub repository. Skills are applied by the skill-review agent during scans and tracked in your project context.
+**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.
 
-- **Project Info Registry**: Store important project context in `.trie/PROJECT.md` that travels with you across Claude Code, Cursor, GitHub Actions, and CLI. Define your project description, tech stack, conventions, architecture, and custom AI instructions—all in one place.
+**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
 
-- **Accessibility Agent (v2.0)**: Comprehensive WCAG 2.1 AA compliance. Detects icon-only buttons, touch targets, skipped headings, positive tabIndex, ARIA validation, color-only indicators, and 20+ more checks with WCAG criterion references.
+**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
 
-- **Memory-Influenced Triaging**: The triager now uses issue memory to boost agent priority. Agents that found issues before, have recurring patterns, or have cross-project patterns get boosted confidence. If your codebase trend is "declining", all agents get a slight boost.
+Trie's memory is a tree. The more incidents you report, the smarter the tree gets. Hot paths = risky areas.
 
-- **Moneybags Agent**: Estimates dollar cost of bugs using IBM/NIST research. Costs scale with your user count—use `--users 10000` to match your scale (default: 250 users).
+## 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 skills**: 26 specialized analyzers (security, privacy, SOC2, accessibility, etc.) that the guardian uses when appropriate.
+- **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).
 
-- **Production Ready Agent**: Production gate that checks for health endpoints, graceful shutdown, connection pooling, security headers, rate limiting, and monitoring. Get a ship/no-ship verdict before every deploy.
+## What's New
+
+### Guardian Agent
+- **Autonomous observation**: Git hooks (pre-commit, pre-push), file watchers, proactive nudging
+- **Memory tree**: Trie data structure for O(m) file lookups + SQLite for detailed incident history
+- **Learning loop**: Bayesian confidence updates, automatic pattern discovery (3+ incidents), co-occurrence detection
+- **Plain English warnings**: Comprehensive glossary (690 lines, 200+ terms), context-aware explanations
+- **Fast hooks**: `trie check` completes in < 500ms (no LLM calls in git hooks)
+- **Feedback system**: `trie ok`/`trie bad` for thumbs up/down, adjusts confidence in real-time
+
+### 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 Skills (Terminology Update)
+- Built-in analyzers now live in `src/skills/built-in/` and extend `BaseSkill`
+- The guardian agent (singular) decides when to invoke skills based on risk and context
+- Skills provide specialized analysis; the agent provides autonomous behavior
 
 ---
 
 ## Table of Contents
 
+- [Why Trie](#why-trie)
+- [At a Glance](#at-a-glance)
+- [What's New](#whats-new-guardian-architecture-complete)
+- [The Guardian Architecture](#the-guardian-architecture)
 - [Features](#features)
 - [Quick Start](#quick-start)
-- [Usage](#usage)
+- [The Guardian Workflow](#the-guardian-workflow)
+- [Common Questions](#common-questions)
+- [What Each Skill Does](#what-each-skill-does-plain-english)
 - [MCP Tools](#mcp-tools)
-- [CLI](#cli)
-- [Built-in Agents](#built-in-agents)
-- [Accessibility Agent (v2.0)](#accessibility-agent-v20)
-- [Moneybags Agent (v1.1)](#moneybags-agent-v11)
-- [Legal Agent (v2.0)](#legal-agent-v20)
-- [Design Engineer (v2.0)](#design-engineer-v20)
-- [Special Agents](#special-agents)
+- [CLI Commands](#cli-commands)
+- [Built-in Skills](#built-in-skills)
+  - [Accessibility Skill (v2.0)](#accessibility-skill-v20)
+  - [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)
-- [CI/CD Integration](#cicd-integration)
 - [VS Code Extension](#vs-code-extension)
-- [Agent Context System](#agent-context-system)
-- [Production Shipping](#production-shipping)
+- [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** | "Keep the app safe", "Prevent incidents" | Pursues objectives without step-by-step direction |
+| **Observation** | Git hooks, file watchers, CI events | Acts proactively, not just when asked |
+| **Reasoning** | Queries context graph for history/patterns, calculates risk | Uses memory to understand situations |
+| **Action** | Warns, explains, suggests, blocks, escalates | Takes action autonomously in plain English |
+| **Learning** | Tracks outcomes, adjusts confidence, discovers patterns | Improves from experience |
+
+
+
+### 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)
+
+**Trie's job is to be your guardian angel—watching over your shoulder, warning you about danger, and getting smarter every time something goes wrong.**
+
+### 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)
+│   │   └── 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 |
 |---------|-------------|
-| **22 Built-in Agents** | Security, Privacy, SOC 2, Legal, Architecture, Performance, E2E, Visual QA, Data Flow, Moneybags, Production Ready, and more |
+| **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 Built-in Skills** | 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 |
+
+### 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 agents based on code context, issue history, and memory patterns |
-| **Streaming Progress** | Real-time progress updates as agents complete |
+| **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 |
 |---------|-------------|
-| **Watch Mode** | Automatically scan files as you code |
+| **Plain English** | 690-line glossary translates jargon. Non-technical founders understand every warning. |
+| **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, or any GitHub repo |
-| **Works Everywhere** | Auto-detects Cursor, Claude Code, OpenCode, VS Code—adapts output automatically |
+| **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 |
 |---------|-------------|
-| **CI/CD Integration** | GitHub Actions, pre-commit hooks, SARIF output |
+| **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 |
 | **VS Code Extension** | Inline diagnostics, quick-fix code actions, scan on save |
 
 ---
@@ -226,164 +399,189 @@ Explain the checkout.ts security issue
 
 ---
 
-## Your Ongoing Workflow
-
-Once set up, here's how to use Trie day-to-day.
+## The Guardian Workflow
 
-### How Trie Remembers Your Project
+Trie is ONE agent with autonomous behavior. Here's how it works day-to-day.
 
-**You don't have to remember anything.** Trie automatically tracks:
+### Teaching the Guardian
 
-| What Trie Remembers | Why It Matters |
-|---------------------|----------------|
-| Last scan results | AI knows what issues exist without re-scanning |
-| Health score (0-100) | Controls what agents run (see below) |
-| Which files have issues | AI focuses on problem areas first |
-| What type of code you have | Runs the right checks (payments, auth, etc.) automatically |
-| Scan history | See if issues are getting better or worse |
+When something breaks, tell Trie:
 
-**How context sharing works:**
-
-Think of `trie scan` and `trie checkpoint` as saving your game. Context is captured when you run them:
+```bash
+$ trie tell "users can't log in after my last push"
 
-```
-trie scan (full analysis) or trie checkpoint (quick save)
-    ↓
-Saves to .trie/AGENTS.md, .trie/memory/
-    ↓
-Open same project in Claude Code
-    ↓
-Claude Code reads trie://context → sees your history
+📝 Got it. I'll remember that changes to auth/ caused this.
+   Next time you change those files, I'll warn you.
 ```
 
-| Command | What It Does |
-|---------|--------------|
-| `trie scan` | Full analysis - runs agents, finds issues, updates health score |
-| `trie checkpoint "message"` | Quick save - saves your current context without running agents |
+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
 
-- Context persists in `.trie/` files in your project directory
-- Any MCP client (Cursor, Claude Code) can read `trie://context`
-- CLI and GitHub Actions read the same `.trie/` files
+### Before You Push
 
-**Where it's stored:** `.trie/AGENTS.md` contains your health score and checkpoints. `.trie/memory/` contains searchable issue logs.
-
-### Health Score: The Priority System
-
-Your **health score** isn't just a number—it actively controls how Trie works across all your tools:
-
-| Health Score | What Happens |
-|--------------|--------------|
-| **80-100** | Normal mode: Trie runs targeted checks based on your code |
-| **50-79** | Cautious mode: Agents that found issues before run again automatically |
-| **Below 50** | Full scan mode: ALL agents run regardless of context |
+```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
 
-**How it works across tools:**
+```bash
+# Warning was helpful
+$ trie ok
 
+# Warning was not helpful (false positive)
+$ trie bad
 ```
-Cursor: Run trie scan → finds 14 issues → Health drops to 56%
-                    ↓
-        Saved to .trie/AGENTS.md
-                    ↓
-Claude Code: Open same project → read trie://context → sees 56% health
-                    ↓
-        Run trie scan → more thorough checks (low health = all agents)
-                    ↓
-GitHub Actions: Reads .trie/ → same health score → stricter CI gates
-```
-
-**Why this matters:**
 
-| Scenario | Without Trie | With Trie |
-|----------|--------------|-----------|
-| Quick fix in Cursor | No history | Run `trie scan` → knows security found issues → runs it |
-| Switch to Claude Code | Starts fresh | Reads `.trie/` → picks up your 56% health |
-| Push to GitHub | Generic checks | Reads `.trie/` → focused on known problem areas |
+This updates pattern confidence immediately. The agent gets smarter.
 
-The `.trie/` directory ensures your project's context **travels with you** across every tool. Just run `trie scan` to capture it.
+### Checking Health
 
----
+```bash
+$ trie status
 
-### Before Pushing Code
+🌳 Your codebase memory tree:
 
-Ask Trie:
-```
-Scan my changes before I push
-```
+Hot zones (3+ incidents):
+  🔥 auth/ (3 incidents across 2 files)
+     ├─ login.ts (2 incidents)
+     └─ session.ts (1 incident)
 
-### Before Launching to Users
+Files that break together:
+  🔗 auth/login.ts ↔ auth/session.ts (67% co-occurrence)
 
-```
-Run a full Trie scan - I'm about to launch
+Safest areas (0 incidents):
+  ✅ components/
+  ✅ utils/
+  ✅ api/
 ```
 
-This runs security, privacy, performance, and architecture checks.
+### The Memory Tree
 
-### When Something Breaks
+Trie's memory is a **prefix tree** of your codebase's failure patterns:
 
 ```
-Trie, check this file for bugs: src/api/orders.ts
+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]
 ```
 
-### Weekly Maintenance
-
-```
-Give me a Trie health report
-```
-
-This reads from `.trie/AGENTS.md` which tracks your project state over time.
-
----
-
-## What Each Check Does (Plain English)
-
-| When You Ask | What It Checks | Why It Matters |
-|--------------|----------------|----------------|
-| "Run security scan" | Login/password handling, data exposure, hack vulnerabilities | Prevents your app from being hacked |
-| "Run privacy scan" | User data handling, GDPR/CCPA compliance | Avoids fines up to $10,000+ per violation |
-| "Run bugs scan" | Logic errors, edge cases, crash points | Prevents app crashes for users |
-| "Run performance scan" | Slow queries, memory leaks, scaling issues | App stays fast with 1000+ users |
-| "Run legal scan" | Terms of service, license compliance, regulations | Avoids lawsuits |
-| "Run design scan" | UI patterns, accessibility, UX issues | Better user experience |
+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>Do I need to pay for an API key?</strong></summary>
-
-No. Trie works without any API keys using pattern matching.
+<summary><strong>How does the learning work?</strong></summary>
 
-For deeper AI analysis, you can optionally add an Anthropic API key:
-1. Get a key from [console.anthropic.com](https://console.anthropic.com)
-2. Add to your environment: `export ANTHROPIC_API_KEY=your-key-here`
+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
 
-This enables AI-enhanced scanning with better accuracy.
+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 only scans and reports. It never modifies code without you asking. When you want fixes:
-- Ask your AI assistant to apply specific fixes
-- Or run `trie_fix` which only applies high-confidence, safe fixes
+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 an issue?</strong></summary>
+<summary><strong>What if I don't understand a warning?</strong></summary>
 
 Ask for an explanation:
 ```
-Explain the issue Trie found in checkout.ts in simple terms
-```
+$ trie explain
 
-Or ask what could go wrong:
-```
-What's the worst case if I don't fix this security issue?
+🛡️ 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>
@@ -392,162 +590,218 @@ What's the worst case if I don't fix this security issue?
 Add this file to your repo at `.github/workflows/trie.yml`:
 
 ```yaml
-name: Trie Check
+name: Trie Guardian
 on: [push, pull_request]
 
 jobs:
-  scan:
+  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:
-          agents: security,privacy,bugs
+          # Fast check on every push
+          command: check
           fail-on: critical
 ```
 
-Now every push is automatically checked.
+The guardian reads your project's `.trie/` directory (incidents, patterns, memory) and uses that context in CI.
 
 </details>
 
 ---
 
+## What Each Skill 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 Tools
 
 These tools are available when using Trie via MCP (Cursor, Claude Code, etc.).
 
-### Core Tools
+### Scanning & Analysis
 
 | Tool | Description |
 |------|-------------|
-| `trie_scan` | Scan code with intelligent agent selection |
-| `trie_watch` | Watch mode—automatically scan files as you code |
+| `trie_scan` | Full scan with intelligent skill selection |
+| `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 |
-| `trie_project` | View and manage project info (.trie/PROJECT.md) |
-| `trie_init` | Initialize bootstrap files, detect stack, suggest skills |
+
+### Memory & Learning
+
+| Tool | Description |
+|------|-------------|
+| `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 |
+| `trie_context` | Read full context (memory + patterns + history) |
 | `trie_checkpoint` | Quick save context without running a full scan |
 
-### Custom Skill Tools
+### Project & Configuration
 
 | 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 skills (external and custom) |
-
-### Individual Agent Tools
+| `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 |
 
-Run a specific agent directly:
+### Security & Compliance Skills
 
-| Tool | What It Catches |
-|------|-----------------|
+| 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 |
-| `trie_accessibility` | WCAG 2.1 AA: icon-only buttons, touch targets, heading levels, ARIA validation, focus management, 20+ checks |
-| `trie_architecture` | Code organization, SOLID principles, N+1 queries, scalability |
-| `trie_bugs` | Null safety, edge cases, async issues, common bugs |
+
+### 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 |
+|------|------------------|
+| `trie_accessibility` | WCAG 2.1 AA: icon-only buttons, touch targets, heading levels, ARIA validation, 20+ checks |
+| `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` | Visual regression, responsive design, cross-browser issues |
+| `trie_e2e` | End-to-end test coverage, user flow validation |
+
+### Operations Skills
+
+| Tool | What It Analyzes |
+|------|------------------|
 | `trie_devops` | Config issues, logging, environment variables, deployment patterns |
-| `trie_clean` | Clean up AI-generated code: find vibe-coded patterns and quick fixes |
-| `trie_design` | Design intelligence with AI slop detection, verified token systems, contrast validation |
-| `trie_ux` | Simulate happy path, security tester, confused user, impatient user |
+| `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)
 
-## CLI
+| 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 |
 
-Trie includes a CLI for terminal-based scanning and CI/CD integration.
+### Custom & External Skills
 
-> **Note:** The CLI is separate from MCP tools. Use MCP tools (`trie_scan`, `trie_watch`) when working inside Cursor/Claude Code. Use the CLI for terminal/CI usage.
+| 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 |
 
-### Commands
+---
+
+## CLI Commands
 
 ```bash
-# List available commands
-trie-agent help
+# Bootstrap (installs git hooks, detects stack, suggests skills)
+trie init
 
-# Basic scan (generates report and exits)
-trie-agent scan
+# Report an incident (builds memory)
+trie tell "users can't log in after my push"
 
-# Watch for changes (continuously scans and reports)
-trie-agent watch
+# Quick check before pushing (< 500ms, no LLM)
+trie check
 
-# Scan specific directory
-trie-agent scan --dir ./src
+# Give feedback on last warning
+trie ok      # Helpful - increases confidence
+trie bad     # Not helpful - decreases confidence
 
-# Scan specific files
-trie-agent scan --files "src/api.ts,src/auth.ts"
+# Pause warnings for 1 hour
+trie quiet
 
-# Run specific agents
-trie-agent scan --agents security,privacy,bugs
+# View memory tree, patterns, and health
+trie status
 
-# Output JSON report
-trie-agent scan --format json --output report.json
-
-# List all available agents
-trie-agent agents
+# Full scan with intelligent skill selection
+trie scan
 
-# Install an external skill
-trie-agent skills add vercel-labs/agent-skills vercel-react-best-practices
+# Scan specific directory
+trie scan --dir ./src
 
-# List installed skills
-trie-agent skills list
+# Scan with specific skills
+trie scan --skills security,privacy,bugs
 
-# Browse skill categories (150+ skills across 12 categories)
-trie-agent skills list categories
+# Watch mode (proactive nudging while you code)
+trie watch
 
-# View skills in a category
-trie-agent skills list marketing      # 23 skills
-trie-agent skills list development    # 25 skills
-trie-agent skills list security       # 10 skills
+# Output JSON report
+trie scan --format json --output report.json
 
-# Initialize bootstrap files
-trie-agent init
+# Quick save (checkpoint without full scan)
+trie checkpoint "finished auth flow"
 
 # Search issue memory
-trie-agent memory search "SQL injection"
+trie memory search "SQL injection"
 
 # View cross-project patterns
-trie-agent memory global patterns
+trie memory global patterns
 
-# Quick save (checkpoint without full scan)
-trie-agent checkpoint "finished auth flow"
+# List available skills
+trie skills list
 
-# List checkpoints
-trie-agent checkpoint list
+# Browse skill categories (150+ skills across 12 categories)
+trie skills list categories
 
-# View skills
-trie-agent skills list
+# 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_watch`) | Working inside Cursor/Claude Code |
-| **Terminal/CI** | CLI (`trie-agent scan`, `trie-agent watch`) | Running from terminal, CI pipelines, scripts |
+| **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 Agents
+## Built-in Skills
 
-### Security & Compliance (4 agents)
+Trie has ONE guardian agent that decides when to invoke these specialized analyzers (skills).
 
-| Agent | Description |
+### Security & Compliance (4 skills)
+
+| Skill | 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 agents)
+### Code Quality (6 skills)
 
-| Agent | Description |
+| Skill | Description |
 |-------|-------------|
 | **TypeCheck** | Type errors, missing annotations, null checks |
 | **Bug Finding** | Null safety, edge cases, async issues, race conditions |
@@ -556,9 +810,9 @@ trie-agent skills list
 | **Performance** | Memory leaks, inefficient algorithms, bundle size |
 | **Trie Clean** | Clean up AI-generated "vibe code": find common mistakes and quick fixes |
 
-### UI/UX (5 agents)
+### UI/UX (5 skills)
 
-| Agent | Description |
+| Skill | 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 |
@@ -566,21 +820,22 @@ trie-agent skills list
 | **Visual QA** | Visual regression, responsive design, cross-browser issues |
 | **E2E** | End-to-end test coverage, user flow validation |
 
-### Operations (5 agents)
+### Operations (6 skills)
 
-| Agent | Description |
+| Skill | 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 Agent (v2.0)
+## Accessibility Skill (v2.0)
 
-The Accessibility Agent has been completely rebuilt to provide comprehensive WCAG 2.1 AA compliance checking—matching and exceeding tools like rams.ai, axe-core, and Lighthouse.
+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
 
@@ -700,9 +955,9 @@ trie_accessibility
 
 ---
 
-## Moneybags Agent
+## Moneybags Skill
 
-The Moneybags agent answers the question every CFO asks: **"How much will this bug cost us?"**
+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.**
 
@@ -785,9 +1040,9 @@ trie scan -u 1000000        # Enterprise
 
 ---
 
-## Legal Agent (v2.0)
+## Legal Skill (v2.0)
 
-The Legal Agent has been completely rebuilt to be the most comprehensive legal compliance scanner for app development—covering everything from open source licensing to international data protection.
+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)
 
@@ -902,9 +1157,9 @@ The Legal Agent has been completely rebuilt to be the most comprehensive legal c
 
 ---
 
-## Design Engineer (v2.0)
+## Design Engineer Skill (v2.0)
 
-The Design Engineer agent has been rebuilt with a comprehensive 5-layer design intelligence architecture to detect "AI slop" and enforce professional design standards.
+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
 
@@ -963,9 +1218,9 @@ import {
 
 ---
 
-## Special Agents
+## Special Skills
 
-These agents are **manually invoked**—they don't run during `trie_scan`.
+These skills are **manually invoked**—they don't run during regular guardian checks.
 
 ### Super Reviewer
 
@@ -1149,7 +1404,7 @@ Skills can come from any GitHub repository with a SKILL.md file:
 
 | Source | Examples |
 |--------|----------|
-| [Vercel](https://github.com/vercel-labs/agent-skills) | vercel-react-best-practices, web-design-guidelines |
+| [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 |
@@ -1164,8 +1419,6 @@ Skills can come from any GitHub repository with a SKILL.md file:
 | [Marketing](https://github.com/coreyhaines31/marketingskills) | seo-audit, copywriting, pricing-strategy (23 skills) |
 | Your org | Internal standards, style guides, compliance docs |
 
-Browse all available skills at [skills.sh](https://skills.sh)
-
 ### Auto-Suggested Skills
 
 When you run `trie init`, Trie automatically detects your dependencies and suggests relevant skills:
@@ -1307,30 +1560,27 @@ trie://team         # Team ownership info
 
 ## Issue Memory
 
-Trie stores all detected issues for search and cross-project learning. Uses BM25 ranking (same algorithm as Elasticsearch) for intelligent search.
+Trie stores all detected incidents for search, pattern discovery, and cross-project learning. Uses BM25 ranking (same algorithm as Elasticsearch) for intelligent search.
 
 ### Local Memory (`.trie/memory/`)
 
-Issues from each scan are stored locally:
-- `issues.json` - Searchable issue index with BM25 ranking
-- `YYYY-MM-DD.md` - Daily issue logs
-- `compacted-summaries.json` - Historical summaries (auto-generated)
+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 Issues
+### Search Incidents
 
 **CLI:**
 ```bash
 # Search by keyword
 trie memory search "SQL injection"
 
-# View recent issues
+# View recent incidents
 trie memory recent
 
 # Show statistics
 trie memory stats
-
-# Mark issue resolved
-trie memory resolve <issue-id>
 ```
 
 **MCP:**
@@ -1355,39 +1605,26 @@ trie memory global projects
 trie memory global search "authentication"
 ```
 
-### MCP Resources
-
-```
-trie://memory         # Local issue stats and recent issues
-trie://memory/global  # Cross-project patterns and stats
-```
-
 ### How It Works
 
 1. **BM25 Search**: Uses term frequency, inverse document frequency, and document length normalization for ranking
-2. **Pattern Detection**: Issues are normalized and hashed to detect patterns
-3. **Cross-Project Tracking**: Same pattern in multiple projects is tracked
-4. **Fix Propagation**: When you fix a pattern, it's recorded for other projects
-5. **Smart Suggestions**: Global patterns inform local scans
-
-### Intelligent Compaction
+2. **Pattern Detection**: After 3+ incidents in same area, pattern is automatically created with confidence score
+3. **Cross-Project Tracking**: Same pattern in multiple projects is tracked globally
+4. **Confidence Updates**: `trie ok` / `trie bad` feedback adjusts pattern confidence immediately
+5. **Trie-Powered Discovery**: Hot path detection via tree traversal completes in < 10ms
 
-Instead of deleting old issues, Trie summarizes them:
+### Memory Structure
 
-- **Automatic**: When issues exceed 500, old ones (>30 days) are compacted
-- **Summaries**: Top patterns, hot files, severity breakdown preserved
-- **Trends**: Tracks if codebase is improving, stable, or declining
-- **Recurring Patterns**: Identifies issues that keep appearing across periods
-- **12 Month History**: Keeps up to 12 compacted summaries
-
-```bash
-# View stats including historical data
-trie memory stats
+```
+.trie/memory/
+├── issues.json           # All incidents with metadata
+├── patterns.json         # Discovered patterns
+├── 2024-01-15.md         # Daily log
+└── 2024-01-16.md
 
-# Output includes:
-#   Total Issues: 150
-#   Historical: 1,200 (from compacted summaries)
-#   Trend: improving
+~/.trie/memory/
+├── global-patterns.json  # Cross-project patterns
+└── projects.json         # Tracked project list
 ```
 
 ---
@@ -1582,153 +1819,55 @@ When AI is enabled, you'll see:
 
 ## CI/CD Integration
 
-### GitHub Actions
+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.
 
-Copy the workflow files to your repo:
-
-```bash
-mkdir -p .github/workflows
-cp node_modules/@triedotdev/mcp/.github/workflows/trie-*.yml .github/workflows/
-```
-
-### Available Workflows
-
-**Full Security Scan** (`trie-security-scan.yml`)
-- Runs on push to `main`/`develop`, PRs, and daily schedule
-- Runs security agents: `security`, `privacy`, `soc2`, `legal`
-- Uploads SARIF to GitHub Security tab
-- Comments on PRs with summary
-- Fails build on critical issues
-
-**Pre-commit Checks** (`trie-pre-commit.yml`)
-- Runs on every PR—fast, incremental scanning
-
----
-
-## VS Code Extension
-
-Native VS Code extension with inline diagnostics and quick fixes.
-
-### Features
-- Inline diagnostics from Trie scans
-- Quick-fix code actions
-- Scan on save
-- Status bar integration
-
----
-
-## Agent Context System
-
-> **Simple version:** Trie remembers your project state automatically. See [How Trie Remembers Your Project](#how-trie-remembers-your-project) for the plain-English explanation.
-
-### What Gets Saved
-
-Every time you scan, Trie updates a file in your project (`.trie/AGENTS.md`) with:
-
-| Tracked | Example |
-|---------|---------|
-| Health score | "Your project is at 85/100" |
-| Critical issues | "2 security issues need fixing" |
-| Hot files | "checkout.ts has 3 issues" |
-| Priorities | "Fix payment auth before launching" |
-| Last scan | "Scanned yesterday, 47 files checked" |
-
-### What This Means For You
-
-| Scenario | What Happens |
-|----------|--------------|
-| Open Cursor tomorrow | AI already knows your project state |
-| Switch to Claude Code | Same context, no re-scanning needed |
-| Push to GitHub | CI/CD knows what to focus on |
-| Ask Trie "what should I fix?" | Gives prioritized answer based on your history |
-
-### File Size Management
-
-The context system uses automatic limits to prevent unbounded growth:
-
-| Limit | Value | What Happens |
-|-------|-------|--------------|
-| Max tracked issues | 500 | Oldest issues pruned when exceeded |
-| Locations per issue | 5 | Only most recent locations kept |
-| Scan history | 20 scans | Older scan records removed |
-| Hot files | 10 files | Only top 10 shown |
-| Issue age | 30 days | Stale resolved issues pruned |
-
-You don't need to manage this - Trie automatically prunes old data on each scan.
-
-### Multiple Projects
-
-Each project has its own isolated context:
-
-| Scenario | How It Works |
-|----------|--------------|
-| Switch between projects | Each project has its own `.trie/` folder |
-| Clone on new machine | Context restored from committed `.trie/` files |
-| Monorepo with workspaces | Each workspace can have its own `.trie/` |
-| Team collaboration | Same context when pulling changes |
-
-Trie auto-detects your project root by looking for `package.json`, `.git`, `Cargo.toml`, `go.mod`, or similar project indicators.
-
-### For Developers: Technical Details
-
-<details>
-<summary>MCP Resources (click to expand)</summary>
-
-```
-trie://context        # Combined context (PROJECT.md + scan results)
-trie://project        # User-defined project info (PROJECT.md)
-trie://context/state  # Detailed JSON state
-trie://agents         # Available agents
-trie://config         # Current configuration
-```
-
-Files stored:
-- `.trie/PROJECT.md` - User-defined project context (description, stack, conventions, AI instructions)
-- `.trie/AGENTS.md` - Auto-generated scan context
-- `.trie/state.json` - Machine-readable state for programmatic access
-
-</details>
-
----
-
-## Production Shipping
-
-Trie solves the "last mile" of shipping to production with the **Production Ready** agent.
+### GitHub Actions
 
-### Quick Production Check
+Add to `.github/workflows/trie.yml`:
 
-```bash
-# Run production readiness scan
-trie scan --agents production-ready
+```yaml
+name: Trie Guardian
+on: [push, pull_request]
 
-# Full production scan with cost analysis
-trie scan --agents production-ready,moneybags,security --users 10000
+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
 ```
 
-### What Production Ready Checks
+### What Happens in CI
 
-| Area | What's Checked |
-|------|----------------|
-| **Health Endpoints** | `/health`, `/ready`, `/live` endpoints for orchestrators |
-| **Graceful Shutdown** | SIGTERM handling, connection draining |
-| **Connection Pooling** | Database pool configuration |
-| **Security Headers** | CSP, HSTS, X-Frame-Options, etc. |
-| **Rate Limiting** | API rate limiting configuration |
-| **Monitoring** | Error tracking, APM integration |
-| **Session Storage** | External session store (not in-memory) |
-| **Error Handling** | Global error handlers, no empty catch blocks |
-| **Anti-patterns** | console.log, localhost URLs, TODO comments |
+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)
 
-### CI/CD Gate
+### Full Skill Scan
 
-Add to your workflow:
+For deeper analysis (security, privacy, etc.), add a weekly/nightly job:
 
 ```yaml
-- uses: triedotdev/trie-action@v1
-  with:
-    agents: production-ready,security,privacy,moneybags
-    fail-on: serious
-    upload-sarif: true
+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
 ```
 
 ---