contextdigger 2.4.0
AI-powered context governance for codebases. Intelligent sub-area creation, multi-strategy splitting, interactive refusal, and AI-readable context export.
License: MIT
Requires Python: >=3.11
Keywords: claude-code, code-navigation, codebase-exploration, context, discovery, productivity

# ContextDigger ⛏️

> **Dig deep into your codebase. Unearth context. Navigate with precision.**

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-2.3.4-green.svg)](https://github.com/ialameh/contextdigger/releases)

**Created by [Sam Alameh](https://github.com/ialameh)** | More tools at [FlowMason.com](https://www.flowmason.com)

---

## TL;DR - Quick Start

```bash
# One-line install (installs Python package + Claude Code skills)
curl -sSL https://raw.githubusercontent.com/ialameh/contextdigger/main/install.sh | bash

# In your project (using Claude Code)
/init-dig         # One-time setup: Discover your codebase structure
/dig backend-api  # Start digging into a specific area
/dig-dashboard    # View overview and suggestions
```

**Alternative - Manual Installation:**
```bash
# Step 1: Install Python package
pip3 install --user git+https://github.com/ialameh/contextdigger.git

# Step 2: Install Claude Code skills
curl -o - "https://raw.githubusercontent.com/ialameh/contextdigger/main/install-skills.sh" | bash
```

**What you get:**
- ⛏️ **Auto-discovery**: Excavates logical code areas from any codebase
- 🗺️ **Structured Navigation**: History, breadcrumbs, snapshots, bookmarks
- 📊 **Deep Analytics**: Test coverage, hotspots, performance profiling
- 🔍 **Advanced Search**: Query across all areas, notes, and context
- 📈 **Dashboard & Insights**: Real-time health checks and statistics
- 🤝 **Team-Ready**: Share knowledge, track activity, collaborate
- 🚀 **50+ Commands**: Complete toolkit for codebase exploration
- ⚡ **Rich Autocomplete**: Shell completion better than Salesforce CLI!

**NEW: Shell Autocomplete** (Better than sf/sfdx!)
```bash
# One command to install autocomplete
pip install contextdigger
contextdigger completion install

# Reload your shell
source ~/.bashrc   # or ~/.zshrc
```

Features:
- ✅ Auto-installs to your shell config (.bashrc/.zshrc)
- ✅ Command completion with descriptions
- ✅ Dynamic area/bookmark/context completion
- ✅ Context-aware argument suggestions
- ✅ Real-time updates from your `.cdg/` directory

See [AUTOCOMPLETE.md](AUTOCOMPLETE.md) for full details.

---

## What is ContextDigger?

Large codebases are like archaeological sites - layers of code, hidden connections, buried context. **ContextDigger helps you excavate understanding** by:

1. **Auto-discovering** logical areas in your codebase
2. **Maintaining context** as you navigate between areas
3. **Tracking exploration** sessions and bookmarks
4. **Working across** any language or framework

### The Problem

🤯 **Context switching kills productivity**
- Lost 15-20 minutes every time you switch areas
- Forget where important code lives
- Can't remember what you were working on

### The Solution

⛏️ **ContextDigger organizes chaos**
- Auto-discovers code areas (frontend, backend, tests, etc.)
- Lets you `/dig` into specific areas with full context
- Marks important spots so you can `/goto-spot` instantly
- Tracks what you explored and when

---

## Key Features

### ⛏️ Auto-Discovery
Automatically excavates code areas from your project:
- Detects languages (Python, JS/TS, Salesforce, etc.)
- Identifies frameworks (Next.js, Astro, React, etc.)
- Groups related files into logical areas
- Generates smart area names and descriptions

### 🗺️ Context Navigation
Navigate with precision:
- `/dig <area>` - Dig into a specific code area
- `/redig` - Interactive area selector
- `/dig-status` - See where you're currently digging
- `/mark-spot` - Bookmark important code locations
- `/goto-spot` - Jump to marked locations

### 📊 Session Tracking
Never lose your place:
- Tracks files you viewed and modified
- Records exploration sessions
- Maintains history per code area
- Helps teams understand who's working where

### 🚀 Minimal Friction
Designed for flow:
- **Zero approval prompts** - Commands run instantly without interruption
- **One-line installation** - Everything in a single command
- Lightweight `.cdg/` directory in each project
- Fast discovery (1-5 seconds for most projects)
- Works offline once installed

---

## Complete Feature Set

**40+ commands across 9 major feature areas:**

### 🗺️ Navigation & Context
- **Browser-like History** - Back/forward/trail navigation through areas
- **Context Snapshots** - Save/restore/compare complete mental state
- **Precision Bookmarks** - Mark spots, jump instantly with context
- **Pattern-Based Suggestions** - Get recommended areas based on your work

### 👥 Team Collaboration
- **Team Presence** - See who's working where in real-time
- **Knowledge Base** - Notes, documentation, shared insights
- **Activity Tracking** - Team member contributions and focus

### 🔍 Code Intelligence
- **Dependency Analysis** - Import mapping and relationship graphs
- **Impact Analysis** - See what's affected by changes
- **Hot Spots** - Find frequently changed or problematic areas
- **Test Coverage** - Convention-based coverage detection
- **Coverage Gaps** - Identify untested code areas

### ⚡ Performance & Quality
- **Performance Profiling** - Complexity metrics and slow code detection
- **Complexity Analysis** - LOC, imports, file counts
- **Quality Scoring** - Automated code quality assessment

### 🤖 Automation & Search
- **Automation Rules** - Context-aware workflow automation
- **Advanced Search** - Query across all areas, notes, bookmarks
- **Pattern Matching** - Find by regex and patterns
- **Relevance Scoring** - Weighted search results

### 📈 Analytics & Insights (Enhanced in v2.0)
- **Intelligent Insights Engine** - Pattern detection and actionable recommendations
- **Budget Hotspot Detection** - Identify areas that frequently exceed limits
- **Recurring Violation Analysis** - Detect patterns in policy violations
- **Usage Trend Detection** - Find frequently accessed areas
- **Work Analytics** - Time tracking and productivity metrics
- **Productivity Scoring** - Multi-factor performance analysis
- **Time Distribution** - Session-based activity tracking
- **Trend Analysis** - Growth and usage patterns
- **Impact Scoring** - Prioritize insights by severity and confidence

### 💾 Data Management
- **Export System** - JSON, CSV, HTML formats
- **Backup & Restore** - Complete data preservation with safety
- **Health Checks** - Data integrity validation
- **Cleanup Tools** - Remove old unused data

### 📊 Dashboard & Reporting
- **Overview Dashboard** - Real-time metrics, alerts, suggestions
- **Statistics** - Detailed usage analytics with insights
- **Comprehensive Reports** - Full markdown documentation
- **Visual Analytics** - Tag distributions, activity graphs

### 📋 Governance & Provenance (NEW in v1.4.0)
- **File Provenance Tracking** - Know WHY every file was loaded into context
- **Transparent Accountability** - Multi-reason provenance for complete visibility
- **Provenance Completeness** - Track % of files with documented reasons
- **Automatic Tracking** - Provenance captured during dig and export operations
- **Dashboard Integration** - At-a-glance provenance metrics
- **6 Reason Types** - entry_point, dependency, bookmark, history, pattern_match, user_request

### 🔄 Continuation Contracts (NEW in v1.4.0)
- **Eliminate "What was I doing?"** - Never lose context when resuming work
- **Auto-Capture Context** - Automatically save intent, files, notes on area switch
- **One-Command Resume** - `contextdigger continue` to pick up exactly where you left off
- **Work Templates** - Pre-built templates for bug-fix, feature, refactor workflows
- **Progress Tracking** - Track status (investigating → implementing → testing)
- **Smart Suggestions** - Dashboard prompts you to resume paused work
- **Seamless Area Switching** - Auto-pause current work when switching areas

### 🛡️ Budget Governance (NEW in v1.4.0 - Phases 1.3 & 1.4)
- **Budget Alerts** - Automatic warnings at configurable thresholds (50%, 80%, 90%)
- **Health Monitoring** - Real-time budget health (healthy, warning, critical, exceeded)
- **Governance Policies** - Configurable enforcement modes (strict, warning, advisory)
- **Policy Compliance** - Check budget compliance against governance rules
- **Violation Handling** - Automatic actions on budget violations (block, log, notify, suggest)
- **Policy Persistence** - Save and load governance policies from configuration
- **Audit Logging** - Complete audit trail of all budget checks and violations
- **Audit Statistics** - Compliance rates and violation tracking over time
- **Dashboard Integration** - Budget health displayed prominently in dashboard
- **Smart Icons** - Visual indicators for budget status (✅ ⚠️ 🔴 💥)

### 🔮 Trend Analysis & Predictions (NEW in v2.2.0)
- **Historical Pattern Tracking** - Store and analyze patterns over time in .cdg/insights/history/
- **Trend Detection** - Identify improving, degrading, or stable patterns automatically
- **Multi-dimensional Analysis** - Track trends by area, pattern type, and time period
- **Predictive Insights** - Forecast future issues based on historical trends
- **Risk Scoring** - 0.0-1.0 risk assessment for predicted issues with timeframe estimation
- **Automated Remediation** - Smart suggestions with step-by-step guidance and code examples
- **6 Remediation Types** - Split area, reduce scope, refactor code, update patterns, policy adjustment, increase budget
- **AI Enhancement (Optional)** - Local LLM integration via Ollama (Qwen 3B recommended)
- **Fully Local** - AI processing happens on your machine, code never leaves your computer
- **Privacy-Preserving** - Optional AI features disabled by default, works perfectly without LLM

---

## Installation

### ⚡ Quick Install (Recommended)

**One command installs everything:**

```bash
curl -sSL https://raw.githubusercontent.com/ialameh/contextdigger/main/install.sh | bash
```

This automatically:
- ✅ Checks Python 3.11+ requirement
- ✅ Installs Python package from GitHub
- ✅ Installs all 37 Claude Code skills
- ✅ Works for both fresh installs and upgrades

**For interactive area picker (recommended for 20+ areas):**

```bash
pip install 'contextdigger[interactive]'
```

This adds fuzzy search and keyboard navigation for large codebases.

### 🔄 Updating

**Use the same command to upgrade:**

```bash
curl -sSL https://raw.githubusercontent.com/ialameh/contextdigger/main/install.sh | bash
```

The installer detects existing installations and upgrades them automatically.

### 📋 Manual Installation (Alternative)

If you prefer step-by-step:

```bash
# Basic installation
pip3 install --user git+https://github.com/ialameh/contextdigger.git

# Full installation with interactive picker (recommended)
pip3 install --user 'git+https://github.com/ialameh/contextdigger.git#egg=contextdigger[interactive]'

# Install Claude Code skills
curl -o - "https://raw.githubusercontent.com/ialameh/contextdigger/main/install-skills.sh" | bash
```

### ✓ Verify Installation

```bash
# Check Python package
contextdigger --version
cdg --version  # short alias

# Check skills in Claude Code (should show 37 files)
ls ~/.claude/commands/*dig*.md | wc -l
```

---

## Quick Start Guide

### 1. Initialize in Your Project

```bash
cd /path/to/your/project
/init-dig
```

**What happens:**
- Scans your project structure
- Detects languages and frameworks
- Discovers logical code areas
- Creates `.cdg/` directory with area definitions

**Example output:**
```
⛏️  Digging through codebase...
   Found languages: python, typescript
   Discovered 4 code areas

✓ Discovered 4 code areas

1. backend-api
   Name: Backend API
   Type: python
   Files: 23

2. frontend-components
   Name: React Components
   Type: typescript
   Files: 45

...
```

### 2. Dig Into an Area

**Interactive Mode (v1.2.0+)** - Navigate with fuzzy search:

```bash
/dig
```

**What you see:**
```
? Select a code area to dig into (type to filter):
> backend-api (23 files) - REST API endpoint handlers
  frontend-components (45 files) - React UI components
  database-models (15 files) - SQLAlchemy ORM models
  authentication (8 files) - User login and session management
  ...

  [Type to filter | ↑↓ to navigate | Enter to select | Ctrl+C to cancel]
```

Just start typing to filter areas instantly. Perfect for codebases with 20+ areas.

**Direct Mode** - Jump straight to a known area:

```bash
/dig backend-api
```

**Shows:**
- Area information
- Files in this area
- Recent exploration history
- Suggested next steps

**Plain List** - Non-interactive list view:

```bash
/dig --list
```

### 3. Mark Important Spots

```bash
/mark-spot auth-handler
```

**Saves:**
- Current file and line number
- Surrounding context
- Your notes

### 4. Navigate Back

```bash
/goto-spot auth-handler
```

**Jumps to:**
- Exact file and line
- Restores context
- Continues your work

---

## Commands Reference

**50+ commands across 11 feature areas:**

### Discovery & Navigation (6 commands)
| Command | Description |
|---------|-------------|
| `/init-dig` | Initialize ContextDigger, discover code areas |
| `/dig` | Interactive fuzzy picker (v1.2.0+) |
| `/dig <area>` | Dig into a specific code area |
| `/dig --list` | Show plain list of all areas |
| `/redig` | Interactive area selector |
| `/dig-status` | Show current dig status |
| `/mark-spot [name]` | Mark current location as bookmark |
| `/goto-spot <name>` | Jump to marked bookmark |

### History & Breadcrumbs (4 commands)
| Command | Description |
|---------|-------------|
| `/dig-history` | View complete exploration history |
| `/dig-back` | Navigate backward in history |
| `/dig-forward` | Navigate forward in history |
| `/dig-trail` | Show breadcrumb trail of visited areas |

### Context Snapshots (4 commands)
| Command | Description |
|---------|-------------|
| `/dig-snapshot [name]` | Save current context state |
| `/dig-snapshots` | List all saved snapshots |
| `/dig-compare <snapshot>` | Compare current state with snapshot |
| `/dig-restore <snapshot>` | Restore saved context snapshot |

### Pattern-Based Suggestions (2 commands)
| Command | Description |
|---------|-------------|
| `/dig-suggest` | Get pattern-based area suggestions |
| `/dig-suggest-pattern` | Structured area recommendations |

### Team Collaboration (4 commands)
| Command | Description |
|---------|-------------|
| `/dig-team` | View team activity and presence |
| `/dig-note [title]` | Create note in current area |
| `/dig-notes [area]` | View all notes for area |
| `/dig-knowledge [area]` | Browse knowledge base |

### Dependency Analysis (3 commands)
| Command | Description |
|---------|-------------|
| `/dig-deps [area]` | Show area dependencies |
| `/dig-impact <area>` | Analyze change impact |
| `/dig-graph` | Visualize dependency graph |

### Code Intelligence (5 commands)
| Command | Description |
|---------|-------------|
| `/dig-hotspots` | Find frequently changed code |
| `/dig-coverage [area]` | Show test coverage analysis |
| `/dig-gaps` | Find untested code areas |
| `/dig-perf [area]` | Performance profiling data |
| `/dig-slow` | Find slow/complex code |

### Automation & Search (4 commands)
| Command | Description |
|---------|-------------|
| `/dig-auto <rule>` | Create automation rule |
| `/dig-auto-list` | List all automation rules |
| `/dig-search <query>` | Search all context data |
| `/dig-find <pattern>` | Find by pattern matching |

### Analytics & Insights (3 commands) - Enhanced in v2.0
| Command | Description |
|---------|-------------|
| `insights` | Generate intelligent insights from patterns |
| `insights critical` | Show critical insights only |
| `insights warnings` | Show warning-level insights |
| `insights area <name>` | Show insights for specific area |
| `/dig-analytics` | View work analytics and productivity |
| `/dig-report [file]` | Generate comprehensive report |

### Export & Backup (2 commands)
| Command | Description |
|---------|-------------|
| `/dig-export <format>` | Export data (JSON/CSV/HTML) |
| `/dig-backup [action]` | Backup or restore all data |

### Dashboard & Utilities (3 commands)
| Command | Description |
|---------|-------------|
| `/dig-dashboard` | Overview dashboard with alerts |
| `/dig-health` | System health check |
| `/dig-stats` | Detailed statistics |

### Governance & Provenance (1 command) - NEW in v1.4.0
| Command | Description |
|---------|-------------|
| `/dig-provenance [session]` | Show file provenance - why files were loaded |

**File Provenance Tracking** provides complete transparency for context decisions:
- **Why was this file loaded?** Every file has documented reasons
- **Multi-reason support** Files can have multiple justifications (e.g., entry_point + bookmark)
- **6 Reason Types:** entry_point, dependency, bookmark, history, pattern_match, user_request
- **Automatic tracking** Provenance captured during `/dig` and context export
- **Session-scoped** Full audit trail per exploration session
- **Completeness metric** See % of files with provenance

**Example Output:**
```
📋 File Provenance - Session session-001
======================================================================
Total files tracked: 15

Reason Types:
  • pattern_match: 13 files
  • entry_point: 2 files
  • bookmark: 1 files
  • export: 15 files

File Details:
----------------------------------------------------------------------

📄 api/models.py
   Loaded by: dig
   Area: backend-api
   Reasons (3):
     • entry_point: Primary file for Backend API area
     • bookmark: User bookmarked this file in Backend API
       → Source: bookmarks
     • export: Exported as part of backend-api area context
```

**Provenance appears in:**
- AI context exports (`.cdg/context/<area>.txt`)
- Dashboard summary (when session active)
- Dedicated provenance command

### Continuation Contracts (3 commands) - NEW in v1.4.0
| Command | Description |
|---------|-------------|
| `/dig-continue` or `continue` | Resume last work session |
| `/dig-pause` or `pause` | Pause current work and save state |
| `/dig-contracts [limit]` or `contracts [limit]` | List all contracts |

**Continuation Contracts** eliminate "What was I doing?" moments:
- **Auto-created** when you `/dig` into an area
- **Auto-captures** files, bookmarks, notes as context
- **Auto-pauses** when switching to a different area
- **One-command resume** to pick up exactly where you left off
- **Work templates** for bug-fix, feature, refactor workflows
- **Progress tracking** through investigating → implementing → testing

**Example Workflow:**
```
# Start working (contract auto-created)
$ contextdigger dig backend-api
⛏️  Digging into: Backend API
   [Contract created automatically]

# Pause your work
$ contextdigger pause
⏸️  Paused: Working on Backend API
   Contract saved to history

# Days later - resume exactly where you left off
$ contextdigger continue
📋 Resuming active contract: Working on Backend API
   Area: Backend API
   Status: investigating | Progress: 40%

   Notes: Currently exploring Backend API

   Open Files (5):
     • api/auth.py
     • api/models.py
     • api/routes.py
     • ...

⛏️  Digging into backend-api...

# View all your work history
$ contextdigger contracts
📋 Contracts (showing 10 most recent)

## In Progress
🔍 Fix authentication bug
   Area: Backend API
   Status: implementing | Progress: 60%

## Completed
✓ Add user registration
   Area: Backend API
   Completed: 2025-12-22 16:45
```

**Contract Structure:**
- **Intent**: What you're working on
- **Problem**: What you're solving
- **Goal**: What success looks like
- **Status**: investigating, implementing, testing, blocked, completed
- **Progress**: 0-100% completion
- **Context**: Files, bookmarks, notes, next actions

**Templates Available** (in `contextdigger/templates/`):
- `bug-fix.yaml` - Template for fixing bugs
- `feature.yaml` - Template for implementing features
- `refactor.yaml` - Template for code refactoring

**Dashboard Integration:**
Shows active contract and suggests resuming paused work.

### Budget Governance (4 command variants) - NEW in v1.4.0 Phase 1.3
| Command | Description |
|---------|-------------|
| `policy` | Show current budget governance policy |
| `policy check` | Check compliance with budget policy |
| `policy strict` | Enable strict enforcement mode |
| `policy warning` | Enable warning mode (default) |
| `policy advisory` | Enable advisory mode |

**Budget Governance** ensures attention budgets are respected:
- **Budget Alerts** at configurable thresholds (50%, 80%, 90%)
- **Health Monitoring** with 4 levels: healthy, warning, critical, exceeded
- **Governance Policies** with 3 enforcement modes
- **Policy Compliance** checking for budget violations
- **Violation Handling** with configurable actions (block, log, notify, suggest)
- **Dashboard Integration** showing budget health prominently

**Example Workflow:**
```
# View current budget policy
$ contextdigger policy
📋 Current Budget Governance Policy
======================================================================

  Policy: Default Budget Policy
  ID: default
  Status: Enabled
  Enforcement: Warning

  Budget Limits:
    Max Files: 15
    Max Lines: 3,000

  Alert Thresholds:
    50% - INFO
    80% - WARNING
    90% - CRITICAL

  Violation Actions:
    • Log
    • Notify

======================================================================
Current Budget Status
----------------------------------------------------------------------
  Health: ✅ Healthy
  Files: 8/15 (53%)
  Lines: 1,247/3,000 (42%)

  ✅ In compliance with policy

# Check compliance with current area
$ contextdigger policy check
🔍 Policy Compliance Check
======================================================================
  Area: Backend API

  ❌ Policy Violations Detected

  ⚠️  Warning: lines at 80% of budget: 2,400/3,000 lines (80%)

  ⚠️  Operation allowed with warnings

  Actions taken:
    • Log violation: Lines at 80% (threshold: 80%)
    • Notify user of budget violation
```

**Enforcement Modes:**
- **Strict** 🔴 - Operations that violate budget will be BLOCKED
- **Warning** ⚠️  - Operations show warnings but proceed (default)
- **Advisory** ℹ️  - Budget violations show suggestions only

**Budget Health in Dashboard:**
```
## ✅ Budget Health
------------------------------------------------------------
  Status: Healthy
  Files: 8/15 (53%)
  Lines: 1,247/3,000 (42%)
```

**Budget Alerts During Dig:**
When digging into an area, budget alerts appear automatically:
```
$ contextdigger dig large-area

⛏️  Digging into: Large Area

   Budget: 12/15 files, 2,700/3,000 lines.
   🔴 Critical: lines at 90% of budget: 2,700/3,000 lines (90%)
   ⚠️  Warning: Approaching budget limit
```

### Audit Logging (3 command variants) - NEW in v1.4.0 Phase 1.4
| Command | Description |
|---------|-------------|
| `audit` | Show recent audit events |
| `audit violations` | Show recent budget violations |
| `audit stats` | Show audit statistics |

**Audit Logging** provides complete transparency into governance:
- **Event Tracking** - All budget checks and policy compliance logged
- **Violation History** - Complete record of budget violations with details
- **Compliance Statistics** - Track compliance rate over time
- **Automatic Logging** - Events logged during policy check and dig operations
- **Persistent Storage** - Audit log stored in .cdg/audit/audit.jsonl

**Example Workflow:**
```
# View recent audit events
$ contextdigger audit
📋 Audit Log (showing 20 most recent)
======================================================================

✅ 2025-12-23 14:30 - policy_compliance
   Policy: default
   Budget: 8 files, 1,247 lines
   Area: backend-api

❌ 2025-12-23 14:25 - policy_violation
   Policy: default
   Budget: 15 files, 2,800 lines
   Violations:
     • Warning: lines at 90% of budget
   Area: frontend-components

# View only violations
$ contextdigger audit violations
📋 Budget Violations (showing 3 most recent)
======================================================================

❌ 2025-12-23 14:25
   Policy: default
   Budget: 15/15 files, 2,800/3,000 lines
   Violations:
     • Warning: lines at 90% of budget
   Actions:
     • Log violation
     • Notify user of budget violation
   Area: frontend-components

# View compliance statistics
$ contextdigger audit stats
📊 Audit Statistics
======================================================================

  Total Events: 45
  Violations: 8
  Compliance: 37

  Compliance Rate: 82.2%
  Status: ⚠️  Good

----------------------------------------------------------------------
```

**Policy Persistence:**
Policies are automatically saved in `.cdg/policies/` directory:
- Policies stored as JSON files
- Active policy tracked in `.cdg/config.json`
- Load and switch between multiple policies
- Policy inheritance and customization

### Intelligence & Insights (4 command variants) - NEW in v2.0 Phase 2.1
| Command | Description |
|---------|-------------|
| `insights` | Generate intelligent insights from patterns |
| `insights critical` | Show critical insights only |
| `insights warnings` | Show warning-level insights |
| `insights area <name>` | Show insights for specific area |

**Intelligence & Insights Engine** analyzes patterns and provides actionable recommendations:
- **Pattern Detection** - Identifies behavioral patterns in your codebase usage
- **Smart Recommendations** - Context-aware suggestions based on detected patterns
- **Impact Scoring** - Prioritize insights by severity (0.0-1.0 scale)
- **Confidence Scoring** - Reliability of each pattern detection
- **Multiple Detectors** - Hotspots, violations, usage trends

**Pattern Types:**
- **Budget Hotspots** - Areas that frequently exceed budget limits
- **Recurring Violations** - Patterns in policy violations
- **Usage Spikes** - Frequently accessed areas indicating high activity
- **Frequent Changes** - Areas with consistent development activity

**Insight Levels:**
- **Critical** 🔴 - Urgent issues requiring immediate attention
- **Warning** ⚠️ - Important issues to address soon
- **Info** ℹ️ - Informational insights and suggestions

**Example Workflow:**
```
# Generate all insights
$ contextdigger insights
🔍 Insights Generated
======================================================================

Total Insights: 5
  Critical: 1
  Warnings: 2
  Info: 2

Top Insights (by impact):
----------------------------------------------------------------------

🔴 CRITICAL: Budget Hotspot: backend-api
   This area has exceeded budget limits 7 times. Consider optimization.

   Pattern Details:
     Type: budget_hotspot
     Occurrences: 7
     Confidence: 100%
     Avg Overage: 450 lines

   Recommendations:
     • Split the area into smaller, more focused sub-areas
     • Review file selection criteria to reduce scope
     • Increase budget limits if this area requires more context
     • Use bookmarks to focus on specific files instead of entire area

----------------------------------------------------------------------

⚠️  WARNING: Recurring Violations: frontend-components
   'Files exceeded' violations occur frequently in this area (5 times).

   Pattern Details:
     Type: recurring_violation
     Occurrences: 5
     Confidence: 83%

   Recommendations:
     • Address the root cause of 'Files exceeded' violations
     • Adjust governance policy thresholds if violations are expected
     • Refactor area to reduce complexity and size

----------------------------------------------------------------------

ℹ️  INFO: High Activity: database-models
   This area is accessed frequently (8 events), indicating high development activity.

   Pattern Details:
     Type: frequent_changes
     Occurrences: 8
     Confidence: 64%

   Recommendations:
     • Consider creating a continuation contract for ongoing work
     • Document patterns and insights for this active area
     • Ensure adequate test coverage for frequently changed code

# Show only critical issues
$ contextdigger insights critical
🔍 Critical Insights (1)
======================================================================

🔴 Budget Hotspot: backend-api
   This area has exceeded budget limits 7 times. Consider optimization.

   Impact Score: 0.90

# Show insights for specific area
$ contextdigger insights area backend-api
🔍 Insights for Area: backend-api (2 insights)
======================================================================

🔴 CRITICAL: Budget Hotspot: backend-api
   ...

⚠️  WARNING: Recurring Violations: backend-api
   ...
```

**Dashboard Integration:**
The dashboard shows top 3 critical/warning insights automatically:
```
## 🔍 Insights
------------------------------------------------------------
🔴 Budget Hotspot: backend-api (Impact: 0.90)
   Area exceeds budget limits frequently (7 times)

⚠️  Recurring Violations: frontend-components (Impact: 0.62)
   'Files exceeded' violations detected (5 times)

Run 'contextdigger insights' for detailed analysis
```

**How Insights Work:**
1. **Data Collection** - Analyzes audit logs and session history
2. **Pattern Detection** - Runs specialized detectors (hotspots, violations, trends)
3. **Insight Generation** - Converts patterns to actionable insights
4. **Recommendation Engine** - Provides context-aware suggestions
5. **Prioritization** - Scores by impact and confidence

**Storage:**
Insights can be saved to `.cdg/insights.json` for tracking over time and trend analysis.

### Intelligence Expansion (7 commands) - NEW in v2.2.0 Phase 13
| Command | Description |
|---------|-------------|
| `trends` | Analyze historical trends in patterns and usage |
| `trends area <name>` | Show trends for specific area |
| `predictions` | Generate predictive insights based on trends |
| `predictions area <name>` | Show predictions for specific area |
| `remediate` | Get automated remediation suggestions |
| `remediate --enhance` | Use AI for enhanced suggestions (requires Ollama) |
| `llm status` | Show LLM integration status |
| `llm enable` | Enable local LLM integration |
| `llm disable` | Disable LLM integration |

**Intelligence Expansion** builds on the Insights Engine with predictive capabilities:
- **Historical Trend Analysis** - Track patterns over time in `.cdg/insights/history/`
- **Trend Detection** - Automatically identify improving, degrading, or stable patterns
- **Multi-dimensional Analysis** - Analyze trends by area, pattern type, and time period
- **Confidence Scoring** - Data consistency-based reliability assessment
- **Predictive Insights** - Forecast future issues based on historical trends
- **Risk Scoring** - 0.0-1.0 risk assessment with probability calculation
- **Timeframe Estimation** - Predict when issues are likely to occur
- **Automated Remediation** - Template-based fix suggestions with step-by-step guidance
- **6 Remediation Types** - Split area, reduce scope, refactor code, update patterns, policy adjustment, increase budget
- **Optional AI Enhancement** - Local Ollama/Qwen integration for enhanced suggestions
- **Privacy-Preserving** - AI processing happens locally, code never leaves your machine

**Example Workflow:**
```bash
# Analyze trends across all areas
$ contextdigger trends
🔮 Trend Analysis
======================================================================

Total Trends Detected: 3

Trends by Type:
  • budget_hotspot: 2
  • recurring_violation: 1

----------------------------------------------------------------------

📈 DEGRADING: backend-api (budget_hotspot)
   Confidence: 87%
   Change Rate: +15.2% per week

   Pattern History:
     • Week 1: 5 occurrences
     • Week 2: 7 occurrences
     • Week 3: 9 occurrences

   Trend: Worsening over time

----------------------------------------------------------------------

# Get predictive insights
$ contextdigger predictions
🔮 Predictive Insights
======================================================================

Total Predictions: 2

Critical Predictions: 1
Warning Predictions: 1

----------------------------------------------------------------------

🔴 CRITICAL: backend-api likely to exceed budget
   Risk Score: 0.85
   Probability: 85%
   Timeframe: Within 1 week

   Based on Trend:
     Type: budget_hotspot
     Direction: degrading
     Confidence: 87%

   Recommendations:
     • Take action in the next 1 week to prevent issue
     • Review area scope and reduce file count
     • Consider splitting area into smaller sub-areas

----------------------------------------------------------------------

# Get automated remediation suggestions
$ contextdigger remediate
🔧 Remediation Suggestions
======================================================================

Total Suggestions: 3

By Priority:
  • Critical: 1
  • Warning: 2

----------------------------------------------------------------------

🔴 CRITICAL: Split backend-api area
   Type: split_area
   Effort: Medium

   Problem: Area 'backend-api' consistently exceeds budget limits

   Step-by-step Guide:
     1. Identify logical sub-components within backend-api
     2. Create new areas for each sub-component
     3. Move files to appropriate areas
     4. Update area descriptions and patterns

   Code Example:
     contextdigger dig backend-api
     # Identify sub-areas (e.g., 'auth', 'api', 'models')
     # Create new areas with focused patterns

----------------------------------------------------------------------

# Use AI-enhanced suggestions (requires Ollama)
$ contextdigger remediate --enhance
🤖 AI-Enhanced Remediation
======================================================================

Using LLM: qwen3b (via Ollama)

Total Suggestions: 3 (AI-enhanced)

----------------------------------------------------------------------

🔴 CRITICAL: Split backend-api into focused sub-areas
   Type: split_area
   Effort: Medium
   AI Enhanced: ✓

   Problem: Area 'backend-api' consistently exceeds budget limits

   AI Analysis:
     The backend-api area contains multiple concerns including
     authentication, API routes, and data models. Splitting into
     'backend-auth', 'backend-routes', and 'backend-models' would
     create more focused areas that respect budget constraints.

   Specific Recommendations:
     • backend-auth: auth.py, middleware.py, jwt_utils.py
     • backend-routes: routes.py, handlers.py, views.py
     • backend-models: models.py, schemas.py, validators.py

   Implementation Steps:
     1. Create backend-auth area for authentication logic
     2. Create backend-routes area for API endpoints
     3. Create backend-models area for data structures
     4. Update each area's patterns to match file groups
     5. Test that each area loads correctly

----------------------------------------------------------------------

# Check LLM integration status
$ contextdigger llm status
🤖 LLM Integration Status
======================================================================

  Status: Enabled
  Provider: Ollama
  Model: qwen3b
  Endpoint: http://localhost:11434

  ✅ Connection successful

  Model Info:
    • Model: qwen3b
    • Size: 3B parameters
    • Status: Available
```

**Trend Detection Types:**
- **Improving** 📈 - Pattern occurrences decreasing over time
- **Degrading** 📉 - Pattern occurrences increasing over time (potential issues)
- **Stable** ➡️  - Pattern occurrences consistent over time

**Remediation Types:**
1. **split_area** - Split large areas into smaller, focused sub-areas
2. **reduce_scope** - Reduce file patterns to narrow area scope
3. **refactor_code** - Refactor code to reduce complexity
4. **update_patterns** - Update detection patterns for better targeting
5. **policy_adjustment** - Adjust governance policies and thresholds
6. **increase_budget** - Increase budget limits for legitimate cases

**LLM Integration (Optional):**
- Fully local AI processing via Ollama
- Recommended model: Qwen 3B (fast, lightweight, accurate)
- AI enhancement is optional and disabled by default
- Works perfectly without LLM
- Code never leaves your machine

**Data Storage:**
- Trend history: `.cdg/insights/history/`
- Pattern snapshots: `.cdg/insights/history/snapshot_<timestamp>.json`
- Predictions cache: In-memory (not persisted)

### CLI (Alternative)
```bash
contextdigger init           # Initialize discovery
contextdigger dig            # Interactive picker (v1.2.0+)
contextdigger dig <area>     # Dig into specific area
contextdigger dig --list     # Plain list of areas
contextdigger list           # List all areas
contextdigger status         # Show current status
contextdigger provenance     # Show file provenance (v1.4.0+)
contextdigger continue       # Resume last work session (v1.4.0+)
contextdigger pause          # Pause current work (v1.4.0+)
contextdigger policy         # Manage governance policies (v1.4.0+)
contextdigger audit          # View audit logs (v1.4.0+)
contextdigger insights       # Generate intelligent insights (v2.0+)
contextdigger trends         # Analyze historical trends (v2.2.0+)
contextdigger predictions    # Generate predictive insights (v2.2.0+)
contextdigger remediate      # Get remediation suggestions (v2.2.0+)
contextdigger llm            # Manage LLM integration (v2.2.0+)
contextdigger contracts      # List all contracts (v1.4.0+)
cdg --help                   # Short alias
```

---

## Project Structure

After running `/init-dig`:

```
your-project/
└── .cdg/                      # ContextDigger data directory
    ├── config.json            # Project configuration
    ├── .gitignore             # Excludes user-specific data
    ├── areas/                 # Discovered code areas (commit these!)
    │   ├── backend-api.json
    │   ├── frontend-components.json
    │   └── ...
    ├── sessions/              # Exploration history (gitignored)
    │   └── <session-id>.json
    ├── bookmarks/             # Marked locations (gitignored)
    │   └── bookmarks.json
    ├── contracts/             # Continuation contracts (NEW v1.4.0)
    │   ├── active.json        # Current active contract
    │   ├── history/           # Completed/paused contracts
    │   │   └── <contract-id>.json
    │   └── templates/         # Work templates
    │       ├── bug-fix.yaml
    │       ├── feature.yaml
    │       └── refactor.yaml
    ├── provenance/            # File provenance tracking (NEW v1.4.0)
    │   └── session-<id>.json  # Why files were loaded
    ├── insights/              # Intelligence & insights (NEW v2.0+)
    │   ├── insights.json      # Current insights
    │   └── history/           # Trend analysis (NEW v2.2.0)
    │       └── snapshot_<timestamp>.json
    └── context/               # AI-readable context exports
        └── <area>.txt         # Includes provenance section
```

**What to commit:**
- ✅ `.cdg/areas/` - Share discovered areas with team
- ✅ `.cdg/contracts/templates/` - Share work templates with team
- ❌ `.cdg/sessions/` - Personal exploration history
- ❌ `.cdg/bookmarks/` - Personal bookmarks
- ❌ `.cdg/contracts/active.json` - Personal active work
- ❌ `.cdg/contracts/history/` - Personal work history

---

## Supported Languages & Frameworks

**Auto-detected:**
- Python (pytest, unittest)
- JavaScript/TypeScript (Jest, Vitest, Mocha)
- Salesforce (Apex, LWC)
- Next.js, Astro, React
- Markdown, Shell scripts

**Works w