@triedotdev/mcp 1.0.62 → 1.0.63

package/README.md

@@ -17,7 +17,7 @@ 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.** Skills, on their own, have no unified view. Trie has 26 specialized "scouts" (same as skills, but I call them scouts as they scan and report up), 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.
+**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.
 
@@ -53,20 +53,223 @@ Trie's memory is a tree. The more incidents you report, the smarter the tree get
 - **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.
+- **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
+## What's New (January 2026)
 
-### 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
+### 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 (Phase 1) ✅
+- **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
@@ -92,10 +295,20 @@ $ 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
+### 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.
 
 ---
 
@@ -103,17 +316,18 @@ $ trie bad   # Warning was not helpful
 
 - [Why Trie](#why-trie)
 - [At a Glance](#at-a-glance)
-- [What's New](#whats-new-guardian-architecture-complete)
+- [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 Skill Does](#what-each-skill-does-plain-english)
+- [What Each Scout Does](#what-each-scout-does-plain-english)
 - [MCP Tools](#mcp-tools)
 - [CLI Commands](#cli-commands)
-- [Built-in Skills](#built-in-skills)
+- [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)
@@ -137,11 +351,12 @@ Trie is **truly agentic**—it's not just a collection of linters. Here's what m
 
 | Property | How It Works | Why It's Agentic |
 |----------|--------------|------------------|
-| **Goals** | "Keep the app safe", "Prevent incidents" | Pursues objectives without step-by-step direction |
+| **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** | 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 |
+| **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 |
 
 
 
@@ -184,8 +399,51 @@ Most "agents" are just prompt chains. Trie is different because:
 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.**
+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
 
@@ -195,11 +453,14 @@ 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
+│   │   ├── 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/
 ```
@@ -233,10 +494,23 @@ Trie tracks patterns across ALL your projects. When you fix a SQL injection in P
 |---------|-------------|
 | **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 |
+| **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
 
@@ -252,6 +526,9 @@ Trie tracks patterns across ALL your projects. When you fix a SQL injection in P
 | 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 |
@@ -263,7 +540,7 @@ Trie tracks patterns across ALL your projects. When you fix a SQL injection in P
 | 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 |
+| **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 |
 
 ---
@@ -587,7 +864,30 @@ The built-in skills can optionally use AI for deeper analysis when you have an A
 <details>
 <summary><strong>How do I set up automatic checks on GitHub?</strong></summary>
 
-Add this file to your repo at `.github/workflows/trie.yml`:
+**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
@@ -614,7 +914,7 @@ The guardian reads your project's `.trie/` directory (incidents, patterns, memor
 
 ---
 
-## What Each Skill Does (Plain English)
+## What Each Scout Does (Plain English)
 
 | When You Ask | What It Checks | Why It Matters |
 |--------------|----------------|----------------|
@@ -686,10 +986,11 @@ These tools are available when using Trie via MCP (Cursor, Claude Code, etc.).
 
 | Tool | What It Analyzes |
 |------|------------------|
-| `trie_accessibility` | WCAG 2.1 AA: icon-only buttons, touch targets, heading levels, ARIA validation, 20+ checks |
+| `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` | Visual regression, responsive design, cross-browser issues |
+| `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) |
 | `trie_e2e` | End-to-end test coverage, user flow validation |
 
 ### Operations Skills
@@ -732,6 +1033,11 @@ 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
@@ -766,6 +1072,12 @@ 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
 
@@ -786,22 +1098,22 @@ trie skills add vercel-labs/agent-skills vercel-react-best-practices
 
 ---
 
-## Built-in Skills
+## Built-in Scouts
 
-Trie has ONE guardian agent that decides when to invoke these specialized analyzers (skills).
+Trie has ONE guardian agent that intelligently deploys these 26 autonomous scouts (sophisticated analyzers with domain expertise).
 
-### Security & Compliance (4 skills)
+### Security & Compliance (4 scouts)
 
-| Skill | Description |
+| 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 skills)
+### Code Quality (6 scouts)
 
-| Skill | Description |
+| Scout | Description |
 |-------|-------------|
 | **TypeCheck** | Type errors, missing annotations, null checks |
 | **Bug Finding** | Null safety, edge cases, async issues, race conditions |
@@ -810,9 +1122,9 @@ Trie has ONE guardian agent that decides when to invoke these specialized analyz
 | **Performance** | Memory leaks, inefficient algorithms, bundle size |
 | **Trie Clean** | Clean up AI-generated "vibe code": find common mistakes and quick fixes |
 
-### UI/UX (5 skills)
+### UI/UX (5 scouts)
 
-| Skill | Description |
+| 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 |
@@ -820,9 +1132,9 @@ Trie has ONE guardian agent that decides when to invoke these specialized analyz
 | **Visual QA** | Visual regression, responsive design, cross-browser issues |
 | **E2E** | End-to-end test coverage, user flow validation |
 
-### Operations (6 skills)
+### Operations (6 scouts)
 
-| Skill | Description |
+| Scout | Description |
 |-------|-------------|
 | **DevOps** | Config issues, logging, environment variables, deployment patterns |
 | **Data Flow** | Data flow analysis, state management, API contracts |
@@ -931,15 +1243,76 @@ MODERATE (2 issues)
 ───────────────────
 [A11Y] Line 67: Skipped heading level: h1 to h3
   <h3>Features</h3>
-  Fix: Use h2 after h1
-  WCAG: 2.4.6 Headings and Labels
 
-═══════════════════════════════════════════════════
-SUMMARY: 2 critical, 1 serious, 2 moderate
-Score: 55/100
-═══════════════════════════════════════════════════
+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
+
+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:**
+
+- **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
+
 ### Usage
 
 ```bash
@@ -1232,7 +1605,7 @@ Run trie_super_reviewer on this PR
 
 ### Agent Smith
 
-The ultimate AI code enforcer—43 specialized hunters targeting AI-generated anti-patterns. Runs a swarm of sub-agents to find "vibe-coded" patterns.
+The ultimate AI code enforcer—35+ specialized pattern hunters targeting AI-generated anti-patterns. Runs a swarm of hunters to find "vibe-coded" patterns.
 
 ```
 Run trie_agent_smith on this codebase
@@ -1562,6 +1935,16 @@ trie://team         # Team ownership info
 
 Trie stores all detected incidents for search, pattern discovery, and cross-project learning. Uses BM25 ranking (same algorithm as Elasticsearch) for intelligent search.
 
+### Memory System
+
+**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:
@@ -1825,9 +2208,45 @@ When AI is enabled, you'll see:
 
 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:
+
+```bash
+# Generate full workflow with SARIF + memory caching
+trie ci
+
+# Generate minimal workflow
+trie ci --minimal
+
+# Preview without creating files
+trie ci --dry-run
+```
+
+**What it creates:**
+
+`.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"
+
+**Next steps after running `trie ci`:**
+
+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
+   ```
+
 ### GitHub Actions
 
-Add to `.github/workflows/trie.yml`:
+**Manual setup (alternative):**
+
+Or manually add to `.github/workflows/trie.yml`:
 
 ```yaml
 name: Trie Guardian
@@ -1854,6 +2273,27 @@ jobs:
 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:
@@ -1889,6 +2329,105 @@ jobs:
 | `streaming` | Stream progress updates | `true` |
 | `workers` | Use worker threads | `true` |
 
+### Auto-Escalation Setup
+
+Auto-escalate critical security issues to Slack, email, or webhooks.
+
+**Quick Setup:**
+
+1. Create `.trie/config.json` in your project root
+2. Add escalation configuration:
+
+```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
+  }
+}
+```
+
+**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) |
+
+**Get Slack Webhook URL:**
+
+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
+
+**Multiple Targets:**
+
+```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"]
+      }
+    ]
+  }
+}
+```
+
+**Configuration Options:**
+
+| 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` |
+
+**Test Your Configuration:**
+
+```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
+```
+
+**TUI Configuration:**
+
+Press `c` in watch mode to open Guardian Agent configuration menu (escalation configuration UI coming soon).
+
 ### Example
 
 ```