@triedotdev/mcp 1.0.166 → 1.0.167

package/README.md

@@ -1,642 +1,431 @@
-# Trie: A trainable AI agent with a cryptographic governance ledger and portable context
+# Trie: Governance ledger for agent-human teams
 
-
-**The ledger that keeps agents and humans aligned when shipping together.**
+**Decision memory that travels from Cursor → CLI → CI/CD, keeping agents and humans aligned.**
 
 [![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)
 
-## What Trie Does
-
-Trie is governance for teams where agents and humans ship together. Every decision, direction change, and tradeoff gets recorded in a governance ledger that every contributor—human or agent—reads from and writes to, across every tool in the stack.
-
-- **Autonomous Operation**: Run `trie watch` and the agent monitors your codebase 24/7
-- **Intelligent Extraction**: Automatically extracts decisions, facts, blockers from every change
-- **Governance ledger**: Tamper-evident chain with digital signatures—the shared memory that travels from Cursor/Claude Code → CLI → CI/CD
-- **Predictive Intelligence**: `trie gotcha` queries the ledger to predict problems before they happen
-- **Continuous Learning**: Feed it incidents with `trie tell`, teach it patterns with your history
-
-The work stays coherent not because someone held it together, but because the ledger did. When any contributor flags a direction change, the ledger surfaces the relevant history instantly. When an agent acts, it does so with full context of what was decided before and why.
-
-### The Agent Coordination Problem
-
-**The problem**: When agents and humans ship code together across Cursor, Claude Code, VS Code, and CI/CD, who's accountable for what? An agent makes a decision in one tool; a human modifies it in another; a second agent undoes both. Without a shared record, coordination becomes chaos.
+## The Problem
 
-**The solution**: Trie's governance ledger provides a shared source of truth that both agents and humans can trust. Every decision, every incident, every fix gets recorded with cryptographic signatures proving who (or what) made each change. When an agent queries the ledger, it gets the full context. When you review changes, you see the reasoning. When something breaks, the ledger shows you exactly what led there.
+When agents and humans ship code together across Cursor, Claude Code, VS Code, and CI/CD, context fragments. An agent makes a decision in one tool, a human forgets it in another, and nothing prevents repeating the same mistake.
 
-Think of it as **double-entry bookkeeping for code decisions**—not blockchain-level immutability, but tamper-evident accountability that works with Git and your existing workflow.
-
-## Why It Matters for Agent Collaboration
-
-When agents can ship production changes, you need governance that works for both humans and AI:
-
-**Traditional tools fall short:**
+**Traditional tools don't solve this:**
 - Linear tracks tasks, not decisions or reasoning
 - GitHub shows changes, not why they were made
 - Slack/Discord: context vanishes in chat history
-- No tool tells you if an agent's change conflicts with yesterday's decision
-
-**Trie's ledger provides:**
-- **Tamper-evident history**: Ed25519 signatures detect if entries are modified
-- **Automatic recording**: Agents and humans write to the same ledger
-- **Cross-tool context**: Works in Cursor, CLI, CI/CD, MCP servers
-- **Accountability**: See who (human or agent) made each decision and when
-- **Pattern learning**: Every incident makes the system smarter
+- No tool tells you if today's change conflicts with yesterday's decision
 
-The ledger ensures nothing is lost. When an agent queries it, answers come with full provenance. When you review changes, you see the reasoning trail. When something breaks, the audit trail is already there.
+## The Solution
 
-### How the Agent Works
+Trie keeps a **governance ledger**—a tamper-evident record of decisions, incidents, and fixes that travels with your code. Every tool reads from the same ledger, so decisions persist and everyone stays aligned.
 
-1. **`trie watch`** - Start the agent, it monitors your codebase autonomously
-2. **Agent Extracts** - Every file change → extract decisions, facts, blockers
-3. **Agent Stores** - Builds decision ledger with signatures and metadata
-4. **`trie gotcha`** - Agent queries ledger to predict problems in your current changes
-5. **`trie tell`** - Feed agent incidents to improve its predictions
-6. **Agent Learns** - Gets better at predicting what matters in YOUR codebase
+- **`trie watch`** - Monitors your codebase 24/7, learns patterns autonomously
+- **`trie gotcha`** - Predicts problems before you ship based on past incidents
+- **Governance ledger** - Decision memory with Git-backed audit trail and digital signatures
+- **Cross-tool context** - Same ledger in Cursor, CLI, CI/CD—no coordination needed
 
-Your decisions persist across tools. Your edge cases don't get forgotten. The ledger keeps agents and humans aligned—so you ship the right thing every time.
+Think of it as **double-entry bookkeeping for code decisions**—not blockchain-level immutability, but tamper-evident accountability that works with Git and your existing workflow.
 
 ## Quick Start
 
-### 1. Install Trie
-
-Make sure you have Node.js installed, then:
+### Install
 
 ```bash
-# Install Trie globally
 npm install -g trie
-
-# Set up in your project
 cd your-project
 trie init
-
-# Configure integrations
-trie setup                    # Show setup guide
-trie setup slack <webhook>    # Set up Slack notifications
 ```
 
-### 2. Start Teaching Trie
-
-When bugs happen, tell Trie about them:
+### Basic Workflow
 
 ```bash
-# Report a specific incident (extracts structured signals)
+# 1. Report incidents as they happen
 trie tell "Users can't log in after password reset"
 
-# Train Trie from your history (reverts/bugfixes)
+# 2. Start autonomous monitoring
+trie watch
+
+# 3. Before pushing, check for risks
+trie gotcha
+
+# 4. Learn from your git history
 trie learn
 
-# Give feedback on predictions
+# 5. Give feedback
 trie ok    # Prediction was helpful
 trie bad   # Prediction was wrong
 ```
 
-## Why Trie Exists
-
-The real challenge isn't generating code—it's governance. When some of your teammates are agents and you're working with multiple humans, context fragments. An agent makes a decision in Cursor, a human forgets it in Claude Code, another agent ships something that breaks what you fixed last week. You're not just maintaining a codebase—you're coordinating a mixed team where work happens across tools, models, and people.
-
-The ledger is the answer. Trie keeps a tamper-evident record of decisions, incidents, and tradeoffs so everyone—human and agent—stays compliant with what you've already learned. Ship the right thing every time. That's the competitive advantage. Software margins are compressing; pure application software is becoming a fundamentally different, worse category. The teams that can coordinate agents and humans, that can scale contributors without losing coherence, will win.
+## Core Features
 
-Cursor is building toward self-driving codebases—agents that merge PRs, manage rollouts, and monitor production. We're moving from a world where developers use agents to create diffs to one where agents ship tested features end-to-end. The closer we march toward self-driving systems and AGI, the more important governance becomes. That shift requires tooling that coordinates work across many agents and models that learn from past runs. Trie is optimized for coordination and collaboration with both humans and agents. It keeps your work compliant, scales your contributors (human and AI), and turns your decision history into durable institutional knowledge.
+### 1. Autonomous Monitoring (`trie watch`)
 
-Tools like Cursor Bugbot flag issues—but flagging doesn't help you avoid similar patterns in the future. Trie remembers what broke, learns across projects, and warns before you ship risky code. You end up architecting better and prompting better because the ledger enforces coherence.
+Real-time agent that monitors your codebase and enforces custom rules:
 
-## Key Features
-
-### Built for Agent + Human Collaboration
-
-- **Shared governance ledger** - Single source of truth that agents and humans both read from and write to
-- **Digital signatures** - Ed25519 signatures prove who (human or agent) created each entry (`trie keys generate`)
-- **Accountability trail** - See exactly what decisions agents made and when, verify authenticity
-- **Cross-tool context** - Works in Cursor, Claude Code, CLI, CI/CD—same ledger everywhere
-- **Tamper detection** - Signatures and Git history make modifications visible
-- **No coordination needed** - Agents and humans write concurrently; Git handles conflicts
-
-### Governance That Scales
-
-- **Tamper-evident ledger** - Append-only chain with cryptographic signatures (not blockchain, think double-entry bookkeeping)
-- **Correction pattern** - Entries never deleted, only marked as corrected with full audit trail
-- **Decision memory** - Captures architectural choices, tradeoffs, and context across all tools
-- **Judgment artifacts** - Not just what shipped, but why, what was considered, and who (or what) decided
-- **Git integration** - Auto-commits ledger changes; distributed backup via Git history
-
-### Intelligence That Compounds
-
-- **Predictive analysis** - `trie gotcha` queries the ledger to predict problems before they happen
-- **Pattern recognition** - Identifies recurring issues and edge cases from your actual incident history
-- **Cross-project learning** - Patterns discovered in one project help prevent bugs in others
-- **System coherence** - Tracks relationships between files, changes, incidents, fixes, and decisions
-- **Continuous learning** - Gets better at predicting what matters in YOUR codebase over time
-
-### Integration Built for Speed
-
-- **Multiple interfaces** - CLI, MCP tools for Claude/Cursor, visual dashboards
-- **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
-- **Flexible workflow** - Works with any editor, any git workflow, any deployment setup
-
-## How It Works
-
-### Memory Architecture
-
-Trie maintains two complementary memory systems that work together to provide both fast queries and tamper-evident governance:
-
-**1. Governance Ledger** (`.trie/memory/ledger.json`)
-- **Purpose**: Cryptographic chain of what was detected and when
-- **Properties**: Append-only, tamper-evident, never deleted
-- **Used for**: Audit trail, compliance, historical analysis, gotcha predictions
-- **Immutability**: Entries are marked as corrected, not deleted (see [Ledger Corrections](./docs/LEDGER_CORRECTIONS.md))
-
-**2. Issue Memory** (`.trie/memory/issues/`)
-- **Purpose**: Fast searchable cache of detected issues
-- **Properties**: Queryable, can be compacted and purged
-- **Used for**: `trie memory search`, pattern recognition, recent issue queries
-- **Lifecycle**: Subject to capacity limits; cleaned up via `trie memory purge` strategies
-
-Both systems sync across your team and travel with your codebase. The `.trie/` folder commits with your code, so your project's intelligence is preserved and shared across:
-
-Local development  
-CI/CD pipelines  
-Team members  
-Cursor/Claude/VS Code  
-Git hooks
-
-### File Structure
+```bash
+# Set any quality rule you want enforced
+trie goal add "No console.log statements in production"
+trie goal add "All API endpoints must have rate limiting"
+trie goal add "We never truncate text in UI components"
 
+# Start watching
+trie watch
 ```
-your-project/
-├── .trie/
-│   ├── hot/             # In-memory current session
-│   ├── warm/            # Queryable governance DB
-│   │   └── decisions.db # SQLite database
-│   ├── cold/            # Archived history
-│   ├── memory/          # Issue cache + ledger.json (cryptographic ledger)
-│   ├── patterns/        # Learned patterns
-│   ├── context.json     # Project knowledge graph
-│   └── config.json      # Settings
-├── .trie-shared/        # Shared ledger for team sync (optional)
-│   ├── active/          # Recent blocks
-│   ├── archived/        # Compressed old blocks
-│   └── ledger-manifest.json
-├── src/
-└── .git/
-```  
-
-### Decision Memory Across Tools
-
-Trie solves the context-across-tools problem with a **cryptographic governance ledger**: an append-only, tamper-evident chain of blocks that stores decisions, incidents, fixes, and tradeoffs. Every tool—Cursor, Claude, VS Code, CLI, CI/CD—reads from the same ledger in `.trie/`, so there is no context fragmentation.
-
-- **Decision nodes** store why you made certain choices and what tradeoffs were considered
-- **Cross-tool access** - Cursor, Claude, VS Code, CLI, and CI/CD all read from the same `.trie/` folder
-- **Context trail** - Knows which environment ran which analysis and when
-- **Relationship tracking** - Files ↔ Changes ↔ Incidents ↔ Fixes ↔ Decisions
-
-When you switch from Cursor to Claude Code to terminal—or when different agents and humans work in parallel—Trie remembers. Every tool shares the same ledger, so governance stays consistent.
-
-### Signal Extraction: Context Without Pollution
-
-The Problem: Agents drown in raw data. Dumping 10,000 lines of logs, 500 Slack messages, and 200 commits into context is expensive and ineffective.
 
-**Trie's Solution**: Extract signal, not noise.
-
-#### Three-Tier Storage
-
-| Tier | What's Stored | Purpose |
-|------|---------------|---------|
-| **HOT** (In-Memory) | Current session data, active decisions | Instant access during work |
-| **WARM** (SQLite DB) | Recent decisions, facts, blockers | Query what you need: *"payment decisions in last 30 days"* |
-| **COLD** (Archived) | Full history, indexed but dormant | Auto-archives after 90 days of low access |
-
-#### How Extraction Works
-
-1. **Raw Input** → You report an incident or commit code
-2. **Extraction** → Cheap model (Haiku) pulls out structured signals:
-   - **Decisions**: "Chose bcrypt over sha256 for password hashing"
-   - **Facts**: "Stripe requires TLS 1.2+ for EU transactions"  
-   - **Blockers**: "Missing VAT validation blocks EU checkout"
-   - **Questions**: "Should we cache session tokens?"
-
-3. **Storage** → Structured data goes to WARM storage with embeddings
-4. **Query** → Agents ask: `trie_get_decisions(relatedTo: "payments")`
-5. **Targeted Context** → Agent gets 5 relevant decisions, not 5,000 raw logs
-
-#### MCP Query Tools
-
-Agents don't get dumps—they query for what they need:
-
-```typescript
-// Agent queries decision ledger
-trie_get_decisions({
-  relatedTo: "checkout/validator.ts",
-  since: "30d",
-  limit: 5
-})
+**Features:**
+- Interactive dashboard with goals, memory, and analysis activity
+- AI-powered goal checking using semantic understanding (not just keywords)
+- Token-aware to manage AI costs
+- Smart caching to avoid duplicate scans
+- Real-time nudges when violations are detected
 
-// Returns targeted context:
-// 1. "Always validate email before Stripe checkout" (3 weeks ago)
-// 2. "EU customers need VAT validation" (2 months ago)
+Run in background with screen or tmux:
+```bash
+screen -S trie-watch
+trie watch
+# Detach: Ctrl+A then D
+# Reattach: screen -r trie-watch
 ```
 
-Why this matters: context management IS the product. Agents get the right information at the right moment, not everything dumped at once.
-
-## Core Workflow
-
-### 0. Planning Phase
+### 2. Predictive Analysis (`trie gotcha`)
 
-**Start every complex task by checking Trie first.** Just like starting in plan mode helps Claude 1-shot implementation, checking Trie before coding helps you avoid known pitfalls:
+Predicts problems before you ship based on your actual incident history:
 
 ```bash
-# Before starting work on a feature, check what broke before
-trie gotcha                    # Predict risks for current changes
-trie memory search "payments"      # See past incidents in this area
-trie status                   # Check overall project health
+# Check current changes for risks
+trie gotcha
 
-# Review past decisions and tradeoffs
-# Trie's Context Graph remembers why you made choices and what happened
+# Connect to Linear for JIT defect prediction
+trie linear auth <your-api-key>
+trie linear sync
 ```
 
-Pro tip: The moment something goes sideways, check Trie again. Don't keep pushing—re-plan with historical context. Trie shows you what broke before, what decisions were made, and what edge cases caused issues. Use that knowledge to inform your plan, then let your AI tools implement it.
+Trie warns you if your current changes correlate with:
+- Historical regressions in the same files
+- High-risk patterns from past incidents
+- Active tickets that might conflict
 
-### 1. Teaching Phase
+### 3. Governance Ledger
 
-```bash
-# Something breaks in production
-trie tell "Payment processing failed for EU customers"
+Tamper-evident record of all decisions, incidents, and fixes:
 
-# Trie learns: "payments/" + "EU" + "failed" = high risk pattern
-# Also records: decision context, affected files, tradeoffs made
-```
+**Architecture:**
+- **Governance ledger** (`.trie/memory/ledger.json`) - Append-only chain with Ed25519 signatures
+- **Issue memory** (`.trie/memory/issues.json`) - Fast searchable cache
 
-### 2. Prevention Phase
+**Key properties:**
+- Never deleted, only corrected (full audit trail)
+- Digital signatures prove who (human or agent) created each entry
+- Auto-commits to Git for distributed backup
+- Works across Cursor, CLI, CI/CD—same ledger everywhere
 
+**Setup signing:**
 ```bash
-# Later, you modify payment code
-git add src/payments/eu-handler.js
-git commit -m "Update EU payment logic"
-
-# Trie warns: "This area broke 2 weeks ago with EU payments. Consider extra testing."
-# Context: Remembers the decision you made last time, the edge case that caused the issue
+trie keys generate    # Generate Ed25519 signing key
+trie keys status      # Check if signing is configured
 ```
 
-### 3. Feedback Loop
-
+**Ledger commands:**
 ```bash
-# Warning was helpful
-trie ok
-
-# Warning was wrong
-trie bad
-
-# Trie adjusts confidence for similar future warnings
-# Also updates: decision patterns, edge case recognition, tradeoff understanding
+trie ledger verify    # Validate chain integrity
+trie ledger history   # Show blocks with author attribution
+trie ledger stats     # Block counts, entries, severity breakdown
 ```
 
-### 4. Governance Phase
-
-This is where Trie shines. As your team grows—more humans, more agents, more tools:
-
+**Corrections (not deletions):**
 ```bash
-# Working in Cursor, an agent makes a decision about error handling
-# Trie records it in the ledger
+# Mark false positive
+trie ledger correct <entry-id> -r "Expected behavior" -t false-positive
 
-# A teammate switches to Claude Code later
-# Same ledger, same decisions, same compliance
-
-# Push from terminal
-# Git hooks check against your full history of decisions and incidents
+# Mark as fixed
+trie ledger correct <entry-id> -r "Fixed in commit abc123"
 
-# CI/CD runs
-# Same checks, same memory, same coherence
+# View correction stats
+trie ledger corrections
 ```
 
-Edge cases, tradeoffs, and system coherence—Trie handles governance by remembering what was decided, why it was decided, and what happened as a result. When agents and humans ship together, the ledger keeps everyone compliant.
-
-## Advanced Features
+## Integrations
 
-### Goals & Hypotheses
+| Integration | Setup | Purpose |
+|-------------|-------|---------|
+| **Linear** | `trie linear auth <key>` | JIT defect prediction from active tickets |
+| **GitHub** | Set `GITHUB_TOKEN` env var | Sync PRs and issues into context graph |
+| **Slack** | `trie setup slack <webhook>` | Team notifications for critical issues |
+| **Cursor Cloud** | Set `CURSOR_API_KEY` | Verified automated fixes via cloud agent |
 
-Set improvement goals and test theories. **Goals are actively enforced in real-time** as you code:
+### Linear Integration
 
 ```bash
-# Set a goal - any custom rule you want enforced
-trie goal add "No console.log statements in production"
-trie goal add "All API endpoints must have rate limiting"
-trie goal add "We never truncate text in UI components"
-
-# Add a hypothesis
-trie hypothesis add "Code reviews reduce bug rate"
-
-# View progress
-trie goal list
+trie linear auth <your-api-key>
+trie linear sync
 ```
 
-**How Goal Checking Works:**
-
-When you run `trie watch`, the system actively monitors your code for goal violations using AI-powered analysis:
-
-1. **Custom & Flexible** - Goals can be any quality rule you define (no emojis, no TODOs, security patterns, UI standards, etc.)
-2. **RAG-Based** - Uses semantic understanding, not just keyword matching
-3. **Real-Time** - Checks every file change against ALL active goals
-4. **Smart Caching** - Avoids re-scanning unchanged files
-5. **Cost-Aware** - Token budgets and cooldowns prevent runaway AI costs
-6. **High Confidence** - Only reports violations with strong confidence scores
-
-**Example Goal Violations Detected:**
-- "No emojis in code" → Finds any Unicode emoji anywhere in files
-- "All functions must have JSDoc" → Checks for missing documentation
-- "No inline styles in React" → Detects style attributes in JSX
-- "Every TODO must have a ticket reference" → Validates TODO format
-
-Goals are tracked over time with metrics (violations caught, fixed, progress percentage).
+Or via MCP: `trie_linear_sync` — syncs tickets into the context graph for gotcha predictions.
 
-### Watch Mode
+### GitHub Integration
 
-Real-time monitoring with **proactive goal violation detection**:
+Sync open PRs and issues into the context graph:
 
 ```bash
-trie watch
+# Via MCP (Cursor/Claude)
+trie_github_sync
+trie_github_branches  # See which branch has latest updates
 ```
 
-**Features:**
-- **Interactive dashboard** with goals, memory, analysis activity panels
-- **AI-powered goal checking** - automatically detects violations of your custom rules
-- **Token-aware** - manages AI costs with budgets and cooldowns
-- **Smart prioritization** - focuses on high-risk files first
-- **Caching** - avoids duplicate scans of unchanged files
-- **Real-time nudges** - immediate feedback when violations are detected
+Requires `GITHUB_TOKEN` (repo scope for private repos, public_repo for public).
 
-Running in Background: To keep trie watch running in the background, use screen or tmux:
+### Slack Integration
 
 ```bash
-# Using screen
-screen -S trie-watch
-trie watch
-# Press Ctrl+A then D to detach
-# Reattach with: screen -r trie-watch
+# Show setup guide
+trie setup slack
 
-# Using tmux
-tmux new -s trie-watch
-trie watch
-# Press Ctrl+B then D to detach
-# Reattach with: tmux attach -t trie-watch
+# Configure webhook
+trie setup slack <webhook-url> [#channel]
+
+# Test connection
+trie setup test-slack
 ```
 
-This allows you to keep the agent running while using other terminals. The interactive dashboard will be available when you reattach.
+Or manually add to `.trie/config.json`:
+```json
+{
+  "integrations": {
+    "slack": {
+      "enabled": true,
+      "webhook": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
+      "channel": "#security"
+    }
+  }
+}
+```
 
-### JIT Defect Prediction ("Gotchas")
+### Cursor Cloud Agent
 
-Trie connects to your issue tracker and project history to predict problems while you work:
+Dispatch high-risk issues to Cursor's cloud for verified, test-passing fixes:
 
 ```bash
-# 1. Connect Linear
-trie linear auth <your-api-key>
-trie linear sync
+# Via MCP
+trie_cloud_fix action:configure apiKey:"key-..."
+trie_cloud_fix action:dispatch issueIds:["issue-1"]
 
-# 2. Learn from history automatically
-trie learn
+# Force cloud dispatch (bypass triage)
+trie_cloud_fix action:dispatch forceCloud:true
 
-# 3. Predict for current changes
-trie gotcha
+# Ad-hoc dispatch
+trie_cloud_fix action:dispatch file:"src/auth.ts" issue:"SQL injection" fix:"Use parameterized queries"
 ```
 
-Trie will warn you if your current task correlates with historical regressions or high-risk signatures.
+The cloud agent runs in an isolated VM, applies the fix, runs tests, captures screenshots, and opens a PR.
 
-### Integrations: Linear, GitHub & Cursor Cloud Agent
+### Pipeline View
 
-**Linear** — Sync active tickets for JIT defect prediction:
+See work across Linear, GitHub, and Trie in one place:
 
 ```bash
-trie linear auth <your-api-key>
-trie linear sync
+# Via MCP
+trie_pipeline                    # Full status: tickets, PRs, issues
+trie_pipeline action:coverage    # Only Trie issues with no ticket/PR
+trie_pipeline action:create_tickets issueIds:["id1","id2"]  # Open tickets
 ```
 
-Or via MCP: `trie_linear_sync` — syncs tickets into the context graph for gotcha predictions.
+## AI Tool Integration (MCP)
 
-**GitHub** — Sync open PRs and issues into the context graph:
+Trie provides Model Context Protocol tools for Claude, Cursor, and AI assistants.
 
-```bash
-# Via MCP (Cursor/Claude)
-trie_github_sync
-```
+### Setup for Cursor/Claude
 
-Links PRs to changed files and to Linear tickets mentioned in PR descriptions. Requires `GITHUB_TOKEN` (repo scope for private repos, public_repo for public).
+Add to your MCP settings:
 
-**Cursor Cloud Agent** — Dispatch high-risk issues to Cursor's cloud for verified, test-passing fixes:
+```json
+{
+  "mcpServers": {
+    "trie": {
+      "command": "trie",
+      "args": ["mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "your-api-key",
+        "LINEAR_API_KEY": "your-key",
+        "GITHUB_TOKEN": "your-token",
+        "CURSOR_API_KEY": "your-cursor-key"
+      }
+    }
+  }
+}
+```
 
-```bash
-# Via MCP
-trie_cloud_fix action:configure apiKey:"key-..."
-trie_cloud_fix action:dispatch issueIds:["issue-1", "issue-2"]
+### Available Tools
 
-# Force cloud dispatch (bypass triage when user explicitly wants cloud)
-trie_cloud_fix action:dispatch forceCloud:true
+**Core:**
+- `trie_tell` - Report incidents and extract structured signals
+- `trie_check` - Quick risk assessment
+- `trie_watch` - Start/stop autonomous monitoring
+- `trie_memory` - Search incident history
+- `trie_fix` - Apply fixes (use `action:route` to see triage plan)
+- `trie_cloud_fix` - Dispatch to Cursor cloud agent
 
-# Ad-hoc dispatch (no scan issues — e.g. from trie_propose_fix)
-trie_cloud_fix action:dispatch file:"src/storage/tiered-storage.ts" issue:"Concurrent file writes corrupt ledger" fix:"Add file locking and atomic writes"
-```
+**Integrations:**
+- `trie_linear_sync` - Sync active Linear tickets
+- `trie_github_sync` - Sync open PRs and issues
+- `trie_github_branches` - Fetch branches with latest commits
+- `trie_pipeline` - Consolidated view of tickets, PRs, issues
 
-The cloud agent runs in an isolated VM, applies the fix, runs tests, captures screenshots, and opens a PR. Requires `CURSOR_API_KEY`. Use `trie_fix action:route` first to see which issues qualify. Add `forceCloud:true` to bypass triage when you explicitly want cloud.
+**Query Tools (Targeted Context):**
+- `trie_get_governance` - Query decisions with filters
+- `trie_get_blockers` - Get active blockers only
+- `trie_get_nudges` - Get unresolved goal violations
+- `trie_get_related_governance` - Find related context
+- `trie_query_context` - Natural language queries across all signals
 
-### Fix Triage System
+**Why query tools matter**: Instead of dumping everything into context, agents ask for exactly what they need. This prevents context pollution and keeps agents focused.
 
-Trie routes each issue to one of three fix strategies based on a scoring system:
+## Advanced Features
 
-| Strategy | When | Action |
-|----------|------|--------|
-| **inline-auto** | Trivial, auto-fixable (score < 0) | Apply fix automatically |
-| **local-ai** | Moderate risk (score 0–3) | `trie_fix` — local AI applies fix |
-| **cloud-agent** | High risk (score ≥ 4) | `trie_cloud_fix` — Cursor cloud agent |
+<details>
+<summary><b>Goals & Custom Rules</b></summary>
 
-Scoring signals: Issue shape (effort, severity, CWE, OWASP), code context (tests, auth/crypto/payments), occurrence history (how often seen), pipeline context (linked PR/ticket), and user config.
+Set improvement goals that are actively enforced in real-time:
 
 ```bash
-# See routing plan before applying
-trie_fix action:route
-```
-
-### Pipeline View
+# Add goals
+trie goal add "No hardcoded API keys"
+trie goal add "All async functions must handle errors"
+trie goal add "Every TODO must have a ticket reference"
 
-Get a consolidated view of your work across Linear, GitHub, and Trie:
+# View progress
+trie goal list
 
-```bash
-# Via MCP
-trie_pipeline                    # Full status: tickets, PRs, issues, coverage gaps
-trie_pipeline action:coverage    # Only Trie issues with no ticket/PR
-trie_pipeline action:create_tickets issueIds:["id1","id2"]  # Open Linear tickets for uncovered issues
+# Get unresolved violations
+trie_get_nudges  # Via MCP
 ```
 
-### Cryptographic Governance Ledger
+Goals use AI-powered semantic understanding to catch violations, not just keyword matching.
 
-Trie uses a **chain-of-blocks ledger** for tamper-evident incident history and team sync. The ledger transforms from isolated per-developer chains into a collaborative, distributed cryptographic ledger that scales to teams while maintaining integrity.
+</details>
 
-**Architecture:**
-- **Chained blocks** — Each block links to the previous via hash; genesis block starts the chain
-- **Merkle roots** — Block contents hashed for integrity verification
-- **Author attribution** — Each block records who added it; git commit correlation for developer attribution
-- **Version 2 format** — Syncable blocks with backwards compatibility for v1 ledgers
+<details>
+<summary><b>Fix Triage System</b></summary>
 
-**Shared storage** (`.trie-shared/`):
+Trie routes each issue to one of three fix strategies:
 
-```
-.trie-shared/
-├── ledger-manifest.json    # Global chain metadata + index
-├── active/                 # Hot storage (recent blocks)
-│   ├── 2024-01-20.json
-│   └── 2024-01-21.json
-└── archived/               # Cold storage (compressed)
-    ├── 2024-01.tar.gz      # Monthly archives
-    └── 2023-12.tar.gz
-```
+| Strategy | When | Action |
+|----------|------|--------|
+| **inline-auto** | Trivial fixes (score < 0) | Apply automatically |
+| **local-ai** | Moderate risk (score 0–3) | `trie_fix` — local AI applies fix |
+| **cloud-agent** | High risk (score ≥ 4) | `trie_cloud_fix` — Cursor cloud agent |
 
-**Compression & scalability:**
-- Automatic archiving after 30 days
-- gzip compression with configurable levels (90%+ space savings)
-- Hot/cold storage tiers; lazy loading of archived content
+See routing plan before applying:
+```bash
+trie_fix action:route
+```
 
-**Conflict resolution:** Divergent chains merge with timestamp or longest-chain strategy; entry deduplication across developer chains.
+</details>
 
-**Git integration:** Auto-sync via `trie sync hooks --install` — pre-push and post-merge hooks keep local and shared ledgers in sync. Commit correlation and developer attribution from git history.
+<details>
+<summary><b>Team Sync (Shared Ledger)</b></summary>
 
-**Backwards compatibility:** Automatic migration of v1 ledgers; legacy detection and zero-data-loss upgrade.
+Sync ledger blocks across your team:
 
 ```bash
-# Sync commands
 trie sync init              # Initialize shared storage
-trie sync pull              # Pull shared updates (auto-migrates legacy)
+trie sync pull              # Pull shared updates
 trie sync push              # Push local changes
-trie sync status            # Show sync state, conflicts
-trie sync migrate           # Manually migrate legacy v1 ledger
-trie sync hooks --install   # Install pre-push/post-merge auto-sync hooks
-
-# Ledger commands
-trie ledger verify          # Validate chain integrity
-trie ledger history         # Show chain with author attribution
-trie ledger stats           # Block counts, entries, severity breakdown
-trie ledger diff            # Compare local vs shared
-trie ledger compress        # Manually archive old blocks
-trie ledger storage         # Detailed storage usage stats
+trie sync status            # Show sync state
+trie sync hooks --install   # Install auto-sync git hooks
 ```
 
-### Integration with AI Coding Tools
-
-Trie provides MCP (Model Context Protocol) tools for seamless integration with Claude, Cursor, and other AI assistants:
+The shared ledger lives in `.trie-shared/` with hot/cold storage tiers and automatic compression.
 
-**Core Tools:**  
-trie_tell - Report incidents and extract structured signals  
-trie_check - Quick risk assessment  
-trie_memory - Search incident history  
-trie_fix - Apply suggested fixes (use action:route to see triage plan)  
-trie_cloud_fix - Dispatch to Cursor cloud agent for verified fixes
+</details>
 
-**Integration Tools:**  
-trie_linear_sync - Sync active Linear tickets  
-trie_github_sync - Sync open PRs and issues from GitHub  
-trie_github_branches - Fetch branches with latest commit info (which branch has latest updates)  
-trie_pipeline - Consolidated view of tickets, PRs, issues, coverage gaps
+<details>
+<summary><b>Memory Management</b></summary>
 
-**Query Tools (Signal Extraction):**  
-trie_get_decisions - Query decisions with filters (tags, time, file)  
-trie_get_blockers - Get active blockers only  
-trie_get_related_decisions - Find related context  
-trie_query_context - Natural language queries across all signal types
+```bash
+# Search incident history
+trie memory search "authentication"
+trie memory stats
+trie memory recent
 
-**Why query tools matter**: Instead of dumping everything into context, agents ask for exactly what they need. This prevents context pollution and keeps agents focused on relevant signal.
+# Clean up old issues (doesn't affect immutable ledger)
+trie memory purge smart      # Remove resolved & old low-priority
+trie memory purge resolved   # All resolved issues
+trie memory purge old        # Older than 90 days
+```
 
-## Installation & Setup
+</details>
 
-### Requirements
+<details>
+<summary><b>Git Hooks</b></summary>
 
-Node.js 16 or higher  
-Git repository
+Installed automatically with `trie init`:
 
-### Installation
+- **pre-commit** - Scan staged files, block on critical issues
+- **post-commit** - Update context graph
+- **pre-push** - Block push on critical issues
 
+**Bypass methods:**
 ```bash
-# Install globally
-npm install -g trie
-
-# Or use npx for one-time runs
-npx trie watch
+git push --no-verify         # Skip all hooks
+TRIE_BYPASS=1 git push      # Skip Trie but log bypass
 ```
 
-### Project Setup
-
-```bash
-# Initialize in your project
-cd your-project
-trie init
-
-# This creates:
-# - .trie/ directory with initial config
-# - Git hooks for automatic checking
-# - Bootstrap files (optional)
-```
+</details>
 
-### API Key Configuration
+## How It Works
 
-Trie works best with these keys:
+### Memory Architecture
 
-ANTHROPIC_API_KEY: Enables AI-powered analysis and explanations.  
-LINEAR_API_KEY: Enables JIT defect prediction by syncing your active tickets.
+Trie maintains two complementary memory systems:
 
-#### 1. Set via Environment (Recommended for MCP)
+**1. Governance Ledger** (`.trie/memory/ledger.json`)
+- Append-only chain with Ed25519 signatures
+- Tamper-evident, never deleted (only corrected)
+- Used for: audit trail, compliance, gotcha predictions
+- Auto-commits to Git for distributed backup
 
-Add these to your .env file or shell config:
+**2. Issue Memory** (`.trie/memory/issues.json`)
+- Fast searchable cache of detected issues
+- Can be compacted and purged
+- Used for: pattern recognition, quick queries
+- Links back to ledger via `ledgerBlockHash`
 
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-export LINEAR_API_KEY=lin_api_...
-```
+Both systems sync across your team and travel with your codebase via Git.
 
-#### 2. Set via CLI (Persistent per project)
+### File Structure
 
-```bash
-trie linear auth <your-key>
 ```
-
-#### 3. Set in MCP Config (Cursor/Claude Code)
-
-Add to your MCP server configuration:
-
-```json
-{
-  "mcpServers": {
-    "trie": {
-      "command": "npx",
-      "args": ["-y", "@triedotdev/mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "your-key",
-        "LINEAR_API_KEY": "your-key"
-      }
-    }
-  }
-}
+your-project/
+├── .trie/
+│   ├── memory/
+│   │   ├── ledger.json     # Governance ledger (cryptographic chain)
+│   │   └── issues.json     # Issue cache
+│   ├── warm/
+│   │   └── decisions.db    # SQLite database for structured queries
+│   ├── context.json        # Project knowledge graph
+│   ├── config.json         # Settings
+│   └── keys/               # Ed25519 signing keys (never committed)
+├── .trie-shared/           # Shared ledger for team sync (optional)
+│   ├── active/
+│   ├── archived/
+│   └── ledger-manifest.json
+└── .git/
 ```
 
-### AI Tool Integration
+### Signal Extraction
 
-For Claude (MCP): Add to your MCP settings:
+Instead of dumping raw logs into context, Trie extracts structured signals:
 
-```json
-{
-  "mcpServers": {
-    "trie": {
-      "command": "trie",
-      "args": ["mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "your-api-key-here",
-        "LINEAR_API_KEY": "your-key",
-        "GITHUB_TOKEN": "your-github-token",
-        "CURSOR_API_KEY": "your-cursor-key"
-      }
-    }
-  }
-}
-```
+**Input:** Incident report, commit, conversation  
+**Extraction:** AI pulls out structured data:
+- **Decisions**: "Chose bcrypt over sha256 for password hashing"
+- **Facts**: "Stripe requires TLS 1.2+ for EU transactions"
+- **Blockers**: "Missing VAT validation blocks EU checkout"
+- **Questions**: "Should we cache session tokens?"
 
-For Cursor: Cursor has built-in MCP support. Add the above configuration to your Cursor MCP settings.
+**Storage:** Goes to queryable database with embeddings  
+**Query:** Agents ask for targeted context, not everything at once
 
-Note: VS Code extension is coming soon.
+This prevents context pollution and keeps agents focused on relevant signals.
 
 ## CLI Reference
 
@@ -644,386 +433,133 @@ Note: VS Code extension is coming soon.
 
 ```bash
 trie init          # Set up Trie in your project
-trie setup         # Show setup guide with integration status
-trie tell          # Report incidents (extracts decisions, facts, blockers)
 trie status        # View project health and memory stats
-trie learn         # Train Trie from history or feedback
+trie tell          # Report incidents (extracts decisions, facts, blockers)
 trie gotcha        # Predict problems with current changes
+trie learn         # Train from git history or feedback
+trie watch         # Start interactive monitoring dashboard
 ```
 
-### Setup & Configuration
+### Goals
 
 ```bash
-trie setup                               # Show setup guide with status
-trie setup slack                         # Show Slack setup guide
-trie setup slack <webhook-url> [channel] # Configure Slack integration
-trie setup test-slack                    # Test Slack connection
+trie goal add "<goal>"     # Set improvement goal
+trie goal list             # View progress
 ```
 
-### Memory Management
+### Memory
 
 ```bash
-trie memory search "database"     # Search incident history
-trie memory stats             # View memory statistics
-trie memory purge smart       # Clean up old/resolved issues
-trie learn                    # Extract patterns from reverts/fixes
+trie memory search "query"  # Search incident history
+trie memory stats           # View statistics
+trie memory recent          # Recent issues
+trie memory purge smart     # Clean up old/resolved
 ```
 
-### Goals & Learning
+### Ledger
 
 ```bash
-trie goal add "<goal>"           # Set improvement goal
-trie hypothesis add "<theory>"   # Test a hypothesis
-trie goal list                   # View progress
-trie linear sync                 # Sync Linear tickets for intent context
+trie ledger verify          # Validate chain integrity
+trie ledger history         # Show blocks with authors
+trie ledger stats           # Block counts, entries, severity
+trie ledger correct <id>    # Mark entry as corrected
+trie ledger corrections     # View correction stats
 ```
 
-### Ledger & Sync
+### Sync
 
 ```bash
-trie ledger verify               # Verify chain integrity
-trie ledger history              # Show blocks with author attribution
-trie ledger stats                # Block counts, entries, severity
-trie ledger diff                # Compare local vs shared ledger
-trie ledger compress             # Archive old blocks
-trie ledger storage              # Storage usage stats
-trie sync init                   # Initialize shared ledger
-trie sync pull                   # Pull from shared storage
-trie sync push                   # Push local blocks to shared
-trie sync status                 # Show sync state and conflicts
-trie sync migrate                # Migrate legacy v1 ledger
-trie sync hooks --install        # Install auto-sync git hooks
+trie sync init              # Initialize shared ledger
+trie sync pull              # Pull from shared storage
+trie sync push              # Push to shared storage
+trie sync status            # Show sync state
+trie sync hooks --install   # Install auto-sync git hooks
 ```
 
-### Feedback & Training
+### Keys
 
 ```bash
-trie ok          # Pattern is good (alias: learn ok)
-trie bad         # Pattern is bad (alias: learn bad)
-trie learn       # Learn from your git history
-trie pause       # Disable warnings for 1 hour
+trie keys generate          # Generate Ed25519 signing key
+trie keys status            # Check if signing is configured
+trie keys public            # Get your public key
 ```
 
-### Watch Mode
+### Feedback
 
 ```bash
-trie watch       # Start interactive monitoring dashboard
-
-# Run in background with screen/tmux:
-screen -S trie-watch && trie watch    # Detach: Ctrl+A, D
-tmux new -s trie-watch && trie watch  # Detach: Ctrl+B, D
+trie ok          # Pattern is good
+trie bad         # Pattern is bad
+trie pause       # Disable warnings for 1 hour
 ```
 
-## Configuration
+### Setup
 
-### Scan Behavior
+```bash
+trie setup                     # Show setup guide
+trie setup slack <webhook>     # Configure Slack
+trie setup test-slack          # Test Slack connection
+trie linear auth <key>         # Configure Linear
+trie linear sync               # Sync Linear tickets
+```
 
-> **Note**: Trie no longer uses traditional "scans". Instead, it extracts structured signals from incidents, commits, and conversations. Configuration below is for legacy compatibility.
+## Configuration
 
-Create .trie/config.json:
+Create `.trie/config.json`:
 
 ```json
 {
   "scanOptions": {
     "maxConcurrency": 4,
-    "timeoutMs": 30000,
-    "includeNodeModules": false
+    "timeoutMs": 30000
   },
-  "autoEscalation": {
-    "enabled": true,
-    "webhookUrl": "https://hooks.slack.com/...",
-    "quietHours": { "start": "21:00", "end": "08:00" }
-  }
-}
-```
-
-### Git Hooks
-
-Installed automatically with trie init:
-
-- **pre-commit** - Quick scan of staged files
-- **post-commit** - Update context graph
-- **pre-push** - Block critical issues (can be bypassed)
-
-**Hook Commands** (called automatically by Git):
-```bash
-trie pre-commit     # Scan staged files, block on critical issues
-trie post-commit    # Update context graph after commit
-trie pre-push       # Block push on critical issues
-```
-
-**Bypass Methods:**
-```bash
-git push --no-verify              # Skip all hooks
-TRIE_BYPASS=1 git push           # Skip Trie but log bypass
-```
-
-### Slack Integration
-
-Trie sends notifications to Slack for team collaboration:
-
-**Quick Setup:**
-```bash
-# Show setup guide
-trie setup slack
-
-# Configure webhook
-trie setup slack <webhook-url> [#channel]
-
-# Test integration
-trie setup test-slack
-```
-
-**Manual Setup:**
-1. Create a Slack webhook: https://api.slack.com/apps
-2. Run: `trie setup slack <webhook-url> [#channel]`
-
-Or manually add to `.trie/config.json`:
-
-```json
-{
   "integrations": {
     "slack": {
       "enabled": true,
-      "webhook": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
-      "channel": "#security"  // Optional: default channel
+      "webhook": "https://hooks.slack.com/...",
+      "channel": "#security"
     }
   },
   "autoEscalation": {
     "enabled": true,
-    "webhookUrl": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
     "quietHours": { "start": "21:00", "end": "08:00" }
   }
 }
 ```
 
-**What Trie sends to Slack:**
-- Decision extractions from incidents
-- Active blockers
-- Risk predictions from gotcha
-- Daily/weekly team summaries
-- Critical decision changes
-- Auto-escalation notifications
-
-### Ledger Corrections (Immutable Audit Trail)
-
-The ledger is **append-only** - entries are never deleted. When mistakes happen, use corrections instead:
-
-**Mark entries as corrected:**
-```bash
-# Correct a false positive
-trie ledger correct <entry-id> -r "Expected behavior, not a bug" -t false-positive
-
-# Mark as fixed
-trie ledger correct <entry-id> -r "Fixed in commit abc123"
-
-# Batch corrections
-trie ledger correct entry1 entry2 entry3 -r "Duplicate detections"
-```
-
-**View correction stats:**
-```bash
-# Show correction statistics
-trie ledger corrections
-
-# View history for specific entries
-trie ledger corrections --entries <entry-id1> <entry-id2>
-```
-
-**What happens:**
-- Original entry preserved for audit trail
-- Entry marked with status (`corrected` or `false-positive`)
-- Correction metadata added (timestamp, reason, who)
-- New correction entry appended to ledger
-- Queries automatically filter out corrected entries
-
-**Why immutability matters:**
-- Full audit trail for compliance and trust
-- Tamper-evidence through cryptographic chain
-- Learn from false positives to improve detection
-- Track correction rates over time
-
-## CI/CD Integration
-
-### GitHub Actions
-
-```bash
-# Generate workflow file
-trie ci github
-
-# Creates .github/workflows/trie.yml with:
-# - Decision ledger queries
-# - Memory caching for speed
-# - Risk prediction on PRs
-```
-
-### Custom CI
-
-```bash
-# In your CI pipeline
-npm install -g trie
-# Query decision ledger for risks
-
-## Memory Architecture
-
-Trie maintains two complementary memory systems that work together:
-
-### 1. Governance Ledger (Primary Product)
-
-**Location:** `.trie/memory/ledger.json`  
-**Purpose:** Tamper-evident record of decisions, incidents, and fixes  
-**Architecture:** Append-only chain of blocks with Ed25519 signatures
-
-This is the **core governance layer** that:
-- Powers `trie gotcha` predictions
-- Provides accountability for agent and human decisions
-- Uses digital signatures to detect tampering
-- Never deleted, only corrected (see [Ledger Corrections](./docs/LEDGER_CORRECTIONS.md))
-- Auto-commits to Git for distributed backup
-
-**How it works:**
-- **Daily blocks** - One block per calendar day; all issues detected that day go into the same block
-- Every entry gets signed with Ed25519 (automatic once key exists)
-- Signatures prove who created each entry and detect modifications
-- Git integration provides distributed backup and history
-- Think: **double-entry bookkeeping**, not blockchain
-
-**Setting up Ed25519 signing:**
-```bash
-# Option 1: Automatic (trie init generates a key)
-trie init
-
-# Option 2: Manual
-trie keys generate    # Generate Ed25519 signing key
-trie keys status      # Check if signing is configured
-trie keys public      # Get your public key for verification
-```
-
-Once a key exists, all new ledger entries are signed automatically. Keys are stored in `.trie/keys/` (never committed to git). Each team member generates their own key.
-
-**Security model:**
-- ✅ **Tamper-evident**: Signatures detect if entries are modified
-- ✅ **Accountability**: See who (human or agent) made each decision
-- ✅ **Git backup**: Distributed history via automatic commits
-- ✅ **Verification**: `trie ledger verify` checks integrity
-- ⚠️ **Not encrypted**: Ledger is plaintext (can add encryption if needed)
-- ⚠️ **Not access-controlled**: Standard file permissions apply
-- ⚠️ **Not deletion-proof**: Can still `rm .trie/` (but Git history remains)
-
-**Real protection comes from:** Git history + Team workflow + PR reviews
-
-Perfect for agent collaboration because:
-- Agents can trust ledger contents (signatures verify authenticity)
-- Humans can audit agent decisions (full provenance trail)
-- Cross-tool context works (same ledger in Cursor, CLI, CI/CD)
-- Conflicts are visible (Git shows competing changes)
-
-Learn more: [Signatures & Git Integration](./docs/SIGNATURES_AND_GIT.md)
-
-### 2. Issue Memory (Query Cache)
-
-**Location:** `.trie/memory/issues.json`  
-**Purpose:** Fast searchable cache for pattern queries  
-**Complementary to:** The ledger
-
-Issue memory caches:
-- **Goal violations** caught by watch mode
-- **Learning extractions** from `trie learn` (git history analysis)
-- **Manual reports** via `trie tell` or chat
-- **Working state** - tracks resolved/open/fixed status
-- **Cross-project patterns** in `~/.trie/memory/`
-
-**Each issue links back to the ledger** via `ledgerBlockHash` for full audit trail.
-
-**Why both systems?**
-- **Ledger** = immutable historical record (what was detected, when)
-- **Issue memory** = mutable working state (resolved, open, metrics)
-
-The ledger ensures nothing is lost. Issue memory tracks current state and makes queries fast.
-
-### Query Issue Memory
-
-```bash
-# Search for patterns
-trie memory search "authentication"
+## Why Trie Exists
 
-# View statistics
-trie memory stats
+When agents and humans ship code together, coordination becomes the bottleneck. Context fragments across tools, decisions get forgotten, and nothing prevents repeating the same mistakes.
 
-# See recent detections
-trie memory recent
-```
+Trie solves this with a governance ledger—a tamper-evident record that travels with your code. Every tool reads from the same ledger, so agents and humans stay aligned. Teams that can coordinate contributors (human and AI) without losing coherence will ship faster and more reliably.
 
-**Note:** Issue memory can be cleaned up (`trie memory purge smart`) without affecting the immutable ledger. The ledger remains the source of truth.
+As codebases move toward agent autonomy—agents that merge PRs, manage rollouts, and monitor production—governance becomes critical. Trie keeps your work compliant, scales your contributors, and turns your decision history into durable institutional knowledge.
 
 ## Troubleshooting
 
-### Common Issues
-
-**Trie not finding issues**: You haven't taught Trie about your specific patterns yet. Use `trie tell` to report incidents and build your decision ledger.
-
-**Memory queries returning empty**: The warm storage is empty. Report some incidents with `trie tell` or run `trie learn` to extract from git history.
+**Trie not finding issues**: You haven't taught Trie about your patterns yet. Use `trie tell` to report incidents.
 
-**Query tools not working**: Make sure you've initialized Trie with `trie init` and have ANTHROPIC_API_KEY set for signal extraction.
+**Memory queries returning empty**: Report incidents with `trie tell` or run `trie learn` to extract from git history.
 
-**Hooks not working**: Reinstall with `trie init`. Make sure you have write permissions to .git/hooks/.
+**Query tools not working**: Make sure you've initialized with `trie init` and have `ANTHROPIC_API_KEY` set.
 
-**Goals showing but not detecting violations**: This happens when goals appear in the UI but aren't active in project state. The Goals view will show a yellow warning box. To fix:
-```bash
-# Quick fix - activate a specific goal
-node fix-goals.js "NO EMOJIS"
+**Hooks not working**: Reinstall with `trie init`. Check write permissions to `.git/hooks/`.
 
-# Or use the proper CLI (recommended)
-trie goal add "NO EMOJIS"
-trie goal list
-```
-### Getting Help
-- Issues: [Report bugs and request features](https://x.com/louiskishfy)
+**Goals showing but not detecting violations**: Goals may not be active in project state. Run `trie goal add "<goal>"` to activate.
 
-## Contributing
+**Quick start:**
+1. Fork and clone the repository
+2. `npm install`
+3. Copy `.env.example` to `.env.local` and add API keys
+4. `npm run build`
+5. `npm test`
 
-We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing feedback, your contributions help make Trie better for everyone.
-
-### Quick Start for Contributors
-
-1. **Fork and clone** the repository
-2. **Install dependencies**: `npm install`
-3. **Set up environment**: Copy `.env.example` to `.env.local` and add your API keys
-4. **Build the project**: `npm run build`
-5. **Run tests**: `npm test`
-
-### Before Submitting
-
-- Ensure all tests pass (`npm test`)
-- Run type checking (`npm run typecheck`)
-- Follow our code style (`npm run lint`)
-- Update documentation for new features
+**Before submitting:**
+- All tests pass (`npm test`)
+- Type checking passes (`npm run typecheck`)
+- Follow code style (`npm run lint`)
+- Update docs for new features
 - Never commit secrets or API keys
 
-**Read our full [Contributing Guide](CONTRIBUTING.md) for detailed guidelines.**
-
-### Ways to Contribute
-
-- 🐛 **Report bugs** - Open an issue with reproduction steps
-- 💡 **Suggest features** - Share ideas for improvements
-- 📝 **Improve docs** - Fix typos, add examples, clarify instructions
-- 🔧 **Submit PRs** - Fix bugs or implement features
-- 🧪 **Add tests** - Improve test coverage
-- 🔐 **Security** - Report vulnerabilities privately (see [SECURITY.md](SECURITY.md))
-
-### Code of Conduct
-
-Be respectful, inclusive, and professional. We're building this together.
-
-## Security
-
-Please report security vulnerabilities privately. See [SECURITY.md](SECURITY.md) for details.
-
-**Never commit:**
-- API keys or secrets
-- `.env.local` or `.env` files
-- Private signing keys (`.trie/keys/`)
-- Personal configuration
 
 ## License