k0ntext 3.7.0 → 3.8.1

package/README.md

@@ -1,4 +1,8 @@
-# K0ntext
+<div align="center">
+
+![K0ntext Banner](./assets/banner.png)
+
+**Universal AI context engineering for Claude, GitHub Copilot, Cline, Cursor, Windsurf, Aider, Continue, Antigravity, and Gemini with OpenRouter-powered intelligent analysis.**
 
 [![npm version](https://img.shields.io/npm/v/k0ntext.svg)](https://www.npmjs.com/package/k0ntext)
 [![npm downloads](https://img.shields.io/npm/dt/k0ntext.svg)](https://www.npmjs.com/package/k0ntext)
@@ -7,43 +11,31 @@
 [![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 [![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io)
 
-Universal AI context engineering for Claude, GitHub Copilot, Cline, Cursor, Windsurf, Aider, Continue, Antigravity, and Gemini with OpenRouter-powered intelligent analysis.
+</div>
+
+---
 
 ## Table of Contents
 
-- [Quick Start](#-quick-start-30-seconds)
-- [Zero-to-Hero Workflow](#-zero-to-hero-workflow)
-- [Windows Support](#-windows-support)
-- [Features Overview](#-features-overview)
-  - [Interactive REPL Shell](#-interactive-repl-shell-v330)
-  - [Enhanced TUI Panels](#-enhanced-tui-panels-v331)
-  - [Intelligent Analysis](#-intelligent-analysis)
-  - [Semantic Search](#-semantic-search)
-  - [Cross-Tool Sync](#-cross-tool-sync)
-  - [Git Hooks Automation](#-git-hooks-automation-v310)
-  - [Drift Detection](#-drift-detection-v310)
-  - [Fact-Checking](#-fact-checking-v310)
-  - [Map-Based Context](#-map-based-context-v310)
-  - [MCP Server](#-mcp-server)
-  - [Complete CLI](#-complete-cli-18-commands)
-  - [Smart Agents](#-smart-agents)
-  - [SQLite Storage](#-sqlite-storage)
-- [Complete CLI Reference](#-complete-cli-reference)
-  - [Core Commands](#core-commands)
-  - [v3.1.0 New Commands](#v310-new-commands)
-  - [Git Hooks Workflow](#-git-hooks-workflow-v310)
-- [MCP Server Usage](#-mcp-server-usage)
-- [Supported AI Tools](#-supported-ai-tools)
-- [Configuration](#-configuration)
-- [Architecture](#-architecture)
-- [Development](#-development)
-- [Performance Monitoring](#-performance-monitoring)
-- [Troubleshooting](#-troubleshooting)
-- [Community](#-community)
+- [Quick Start](#quick-start)
+- [Zero-to-Hero Workflow](#zero-to-hero-workflow)
+- [Windows Support](#windows-support)
+- [Features Overview](#features-overview)
+- [Latest Release](#latest-release-v380)
+- [v3.8.0 Release](#latest-release-v380) - Context System, Snapshots, & Bug Fixes
+- [Complete CLI Reference](#complete-cli-reference)
+- [MCP Server Usage](#mcp-server-usage)
+- [Supported AI Tools](#supported-ai-tools)
+- [Configuration](#configuration)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Performance Monitoring](#performance-monitoring)
+- [Troubleshooting](#troubleshooting)
+- [Community](#community)
 
 ---
 
-## 🚀 Quick Start (30 Seconds)
+## Quick Start
 
 ```bash
 # Install globally
@@ -59,7 +51,7 @@ k0ntext generate
 k0ntext mcp
 ```
 
-## 🎯 Zero-to-Hero Workflow
+## Zero-to-Hero Workflow
 
 ### New Project Setup
 ```bash
@@ -91,7 +83,7 @@ k0ntext generate --force
 k0ntext validate --strict
 ```
 
-## 🖥️ Windows Support
+## Windows Support
 
 K0ntext uses native SQLite extensions for high-performance vector search.
 
@@ -100,224 +92,153 @@ K0ntext uses native SQLite extensions for high-performance vector search.
 - **Instant install:** These versions install without extra tools
 - **Non-LTS versions (v23/v24):** May require [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) to compile the database driver
 
-## ✨ Features Overview
+## Features Overview
 
-### 🖥️ Interactive REPL Shell (v3.3.0)
+### Interactive REPL Shell
 - **Auto-start**: Running `k0ntext` with no arguments launches the interactive shell
 - **Session persistence**: Command history and statistics saved across sessions
 - **Built-in commands**: help, stats, index, search, config, drift, init, update, exit
 - **Orange gradient theme** with Unicode/ASCII fallback and terminal capability detection
 - **Update checker** with automatic version notifications on startup
 
-### 🎨 Enhanced TUI Panels (v3.3.1)
-- **Advanced Search Panel** - Filtered, sortable search with `--type`, `--sort`, `--limit` flags and content previews
-- **Configuration UI** - Interactive editor with 4 categories (Project, AI Tools, Features, Display)
-- **Indexing Progress** - Real-time multi-stage progress visualization with ora spinner
-- **Drift Detection** - Three-axis analysis (file dates, structure, git diff) with severity-coded reporting
+### Enhanced TUI Panels
+- **Advanced Search Panel** -- Filtered, sortable search with `--type`, `--sort`, `--limit` flags and content previews
+- **Configuration UI** -- Interactive editor with 4 categories (Project, AI Tools, Features, Display)
+- **Indexing Progress** -- Real-time multi-stage progress visualization with ora spinner
+- **Drift Detection** -- Three-axis analysis (file dates, structure, git diff) with severity-coded reporting
 
-### 🧠 Intelligent Analysis
+### Intelligent Analysis
 - OpenRouter-powered codebase analysis with embeddings
 - Tech stack detection and documentation
 - Workflow discovery and categorization
 - Automatic context generation
-- **Centralized model configuration** (v3.1.0) - Single source of truth for all AI operations
+- Centralized model configuration -- single source of truth for all AI operations
 
-### 🔍 Semantic Search
+### Semantic Search
 - Vector database (sqlite-vec) for intelligent code retrieval
 - Hybrid search (text + semantic)
 - Content type filtering (workflow, agent, command, code, doc, etc.)
 - Real-time indexing with watch mode
 
-### 🔄 Cross-Tool Sync
+### Cross-Tool Sync
 - **9 AI Tools Supported:** Claude, Copilot, Cline, Antigravity, Windsurf, Aider, Continue, Cursor, Gemini
 - Automatic synchronization between tool configurations
 - Change detection with SHA256 hashing
 - Sync status monitoring
-- **Intelligent cross-sync** (v3.1.0) - AI-powered propagation of changes across tools
+- Intelligent cross-sync -- AI-powered propagation of changes across tools
 
-### 🤖 Git Hooks Automation (v3.1.0)
-- **Pre-commit workflow** - Automatic context maintenance
+### Git Hooks Automation
+- **Pre-commit workflow** -- Automatic context maintenance
 - Drift detection on every commit
 - Automatic cross-sync when drift detected
 - Updated context files auto-added to commits
 
-### 🎯 Drift Detection (v3.1.0)
-- **AI-powered semantic analysis** - Detect when documentation diverges from code
+### Drift Detection
+- **AI-powered semantic analysis** -- Detect when documentation diverges from code
 - Replaces hash-based checks with intelligent understanding
 - Severity-based reporting (high/medium/low)
 - Automatic fix suggestions
 
-### 📋 Fact-Checking (v3.1.0)
+### Fact-Checking
 - Validate documentation accuracy against codebase
 - Identify outdated APIs, wrong file paths, missing dependencies
 - Confidence scoring for each claim
 
-### 🗺️ Map-Based Context (v3.1.0)
+### Map-Based Context
 - Concise, structured context files
 - Reduce hallucination through precise references
 - Alternative to verbose documentation format
 
-### 🔢 Version Detection (v3.4.0)
-- **Automatic version checking** - Detects outdated context files
-- **Semantic version parsing** - Supports 5 version marker formats
-- **Update type indicators** - Major/minor/patch with emoji (🚨/✨/🔧)
-- **Database tracking** - Stores version history and check timestamps
-- **Integrated into init** - `k0ntext check` command and `--no-version-check` option
-
-### 📝 User Modification Handling (v3.4.0)
-- **SHA-256 hash detection** - Detects when users edit generated files
-- **Automatic backup creation** - Creates backups before overwriting modified files
-- **Dual backup strategy** - File-copy with git-stash fallback
-- **Interactive prompts** - Asks user before overwriting custom changes
-- **Restore system** - `k0ntext restore` command for backup recovery
-
-### 🎨 Template Engine Enhancement (v3.4.0)
-- **Handlebars integration** - Rich template-based content generation
-- **15 custom helpers** - join, first, truncate, slugify, formatDate, eq, ne, and, or, defaults, json, keys, values, length
-- **Rich project data** - Generated files include actual project metadata
-- **Graceful fallback** - Inline functions when templates unavailable
-
-### 🔄 Template Sync System (v3.5.0)
-- **Automatic `.claude/` sync** - Syncs commands/, agents/, schemas/, standards/, tools/, automation/ from package
-- **Hash-based change detection** - SHA-256 (16 char) for consistency with DatabaseClient
-- **File state classification** - identical, safe-update, conflict, new, deleted, user-only
-- **Auto-merge strategies** - Safe updates automatically applied, conflicts prompt user
-- **Interactive conflict resolution** - Show diff, keep-local, overwrite, or skip options
-- **Batch resolution** - Keep-all, overwrite-all, or individual for multiple conflicts
-- **Backup before overwrite** - Automatic backups to `.k0ntext/backups/`
-- **Archive removed files** - Moved to `.k0ntext/archive/` with timestamp
-- **Dual manifest tracking** - Database + file (`.claude/.k0ntext-manifest.json`)
-- **Init integration** - Runs automatically during `k0ntext init` (skip with `--no-template-sync`)
-
-### 🤖 MCP Server
-- **Auto-Configuration** (v3.1.1) - MCP server automatically configured in `.claude/settings.json` on init
+### Version Detection
+- **Automatic version checking** -- Detects outdated context files
+- **Semantic version parsing** -- Supports 5 version marker formats
+- **Update type indicators** -- Major/minor/patch with emoji
+- **Database tracking** -- Stores version history and check timestamps
+
+### User Modification Handling
+- **SHA-256 hash detection** -- Detects when users edit generated files
+- **Automatic backup creation** -- Creates backups before overwriting modified files
+- **Dual backup strategy** -- File-copy with git-stash fallback
+- **Interactive prompts** -- Asks user before overwriting custom changes
+
+### Template Engine
+- **Handlebars integration** -- Rich template-based content generation
+- **15 custom helpers** -- join, first, truncate, slugify, formatDate, eq, ne, and, or, defaults, json, keys, values, length
+- **Rich project data** -- Generated files include actual project metadata
+
+### Template Sync System
+- **Automatic `.claude/` sync** -- Syncs commands/, agents/, schemas/, standards/, tools/, automation/ from package
+- **Hash-based change detection** -- SHA-256 for consistency with DatabaseClient
+- **File state classification** -- identical, safe-update, conflict, new, deleted, user-only
+- **Interactive conflict resolution** -- Show diff, keep-local, overwrite, or skip options
+- **Backup before overwrite** -- Automatic backups to `.k0ntext/backups/`
+
+### Database Snapshots
+- **Create/restore/diff snapshots** -- Full database save/restore with gzip compression
+- **Snapshot comparison** -- Diff two snapshots to see what changed
+- **Persistent todo lists** -- Survive context compactions via markdown files
+
+### MCP Server
+- **Auto-Configuration** -- MCP server automatically configured in `.claude/settings.json` on init
 - **10 Tools:** search_context, get_item, add_knowledge, analyze, get_tool_configs, query_graph, get_stats
 - **6 Prompts:** context-engineer, core-architect, api-developer, database-ops, integration-hub, deployment-ops
 - Real-time context access for AI assistants
 - Knowledge graph traversal
 
-### 🛠️ Complete CLI (22 Commands)
-- `init` - Initialize with intelligent analysis **(auto-configures MCP in v3.1.1)**
-- `generate` - Generate context files for all tools
-- `mcp` - Start MCP server
-- `sync` - Sync across AI tools
-- `cleanup` - Clean up conflicting tool folders
-- `validate` - Validate context files
-- `export` - Export database
-- `import` - Import from exports
-- `performance` - Show performance metrics
-- `watch` - Auto-index file changes
-- `index` - Index codebase
-- `search` - Search indexed content
-- `stats` - View database statistics
-- **`check`** - Check if context files are outdated (v3.4.0)
-- **`restore`** - Restore AI tool config files from backups (v3.4.0)
-- **`sync-templates`** - Sync `.claude/` templates from package (v3.5.0)
-- **`template-status`** - Show template sync status (v3.5.0)
-- **`drift-detect`** - AI-powered documentation drift detection (v3.1.0)
-- **`cross-sync`** - Intelligent sync across all AI tools (v3.1.0)
-- **`hooks`** - Git hooks management (install/uninstall/status) (v3.1.0)
-- **`fact-check`** - Validate documentation accuracy (v3.1.0)
-- `generate --map` - Generate concise map-based context files (v3.1.0)
-
-### 📊 Smart Agents
-- **CleanupAgent** - Remove conflicting AI tool folders (.cursor, .windsurf, .cline, etc.)
-- **PerformanceMonitorAgent** - Track database performance and suggest optimizations
-- **DriftAgent** (v3.1.0) - AI-powered documentation drift detection
-- **FactCheckAgent** (v3.1.0) - Validate documentation accuracy against codebase
-
-### 🗃️ SQLite Storage
+### Complete CLI
+- `init` -- Initialize with intelligent analysis (auto-configures MCP)
+- `generate` -- Generate context files for all tools
+- `mcp` -- Start MCP server
+- `sync` -- Sync across AI tools
+- `cleanup` -- Clean up conflicting tool folders
+- `validate` -- Validate context files
+- `export` -- Export database
+- `import` -- Import from exports
+- `performance` -- Show performance metrics
+- `watch` -- Auto-index file changes
+- `index` -- Index codebase
+- `search` -- Search indexed content
+- `stats` -- View database statistics
+- `check` -- Check if context files are outdated
+- `restore` -- Restore AI tool config files from backups
+- `sync-templates` -- Sync `.claude/` templates from package
+- `template-status` -- Show template sync status
+- `drift-detect` -- AI-powered documentation drift detection
+- `cross-sync` -- Intelligent sync across all AI tools
+- `hooks` -- Git hooks management (install/uninstall/status)
+- `fact-check` -- Validate documentation accuracy
+- `generate --map` -- Generate concise map-based context files
+- `snapshot` -- Create/restore/list/diff/delete database snapshots
+- `migrate` -- Manage database migrations
+- `shell` -- Launch interactive REPL shell
+
+### Smart Agents
+- **CleanupAgent** -- Remove conflicting AI tool folders (.cursor, .windsurf, .cline, etc.)
+- **PerformanceMonitorAgent** -- Track database performance and suggest optimizations
+- **DriftAgent** -- AI-powered documentation drift detection
+- **FactCheckAgent** -- Validate documentation accuracy against codebase
+
+### SQLite Storage
 - Persistent database with SHA256 change detection
 - Embeddings support for semantic search
 - Knowledge graph relationships
 - Automatic schema migrations
 
-## 🆕 v3.5.0 - Template Sync System
-
-### Smart Template Management
-
-K0ntext v3.5.0 introduces a comprehensive template sync system that automatically keeps your `.claude/` directory up-to-date with the latest package templates while preserving your customizations.
-
-**Key Features:**
-- ✅ **Automatic sync on init** - Templates are synced during `k0ntext init`
-- ✅ **User modification detection** - Detects files you've customized
-- ✅ **Interactive conflict resolution** - Choose to keep your changes or use templates
-- ✅ **Hash-based comparison** - Efficient SHA-256 change detection
-- ✅ **Backup before overwrites** - Automatic backups to `.k0ntext/backups/`
-- ✅ **Dry-run mode** - Preview changes before applying them
-- ✅ **Selective sync** - Sync specific directories (commands, agents, etc.)
-
-### How It Works
-
-1. **First init** - Creates all 55 template files (agents, commands, schemas, standards, tools)
-2. **You modify files** - Your customizations are tracked
-3. **Re-run init** - Detects your modifications and prompts for resolution
-4. **Force sync** - Use `--force` to auto-overwrite with templates
-
-### User Modification Detection
-
-The system intelligently detects when you've modified template files:
-
-```bash
-# You customize a file
-echo "# My custom notes" >> .claude/commands/analytics.md
-
-# Re-run init - detects modification
-k0ntext init
-
-# Output:
-# ⚠ 1 conflict(s) detected:
-#   ⚠ commands/analytics.md [modified]
-#
-# File: commands/analytics.md
-# State: Modified in both template and locally
-#   ⚠ You have modified this file
-#  Template hash: 375ec9c90c168811
-#  Local hash: ee727b7a1a20a0c2
-# ? How would you like to resolve this?
-#   Show diff
-# ❯ Keep local version
-#   Overwrite with template
-#   Skip for now
-```
-
-### New Commands
-
-```bash
-# Sync templates and handle conflicts
-k0ntext sync-templates              # Interactive mode
-k0ntext sync-templates --dry-run     # Preview changes
-k0ntext sync-templates --force        # Auto-overwrite conflicts
-k0ntext sync-templates --verbose      # Show detailed diffs
-
-# Check sync status
-k0ntext template-status              # Quick status check
-k0ntext template-status --verbose    # Detailed file listings
-
-# Skip template sync during init
-k0ntext init --no-template-sync
-```
+---
 
-### Bug Fixes in v3.5.0
+## Latest Release (v3.8.0)
 
-- ✅ **Fixed user modification detection** - Now detects changes made after initial sync
-- ✅ **Fixed force sync** - `--force` now actually overwrites conflict files
-- ✅ **Fixed path resolution** - Templates are correctly found from compiled JavaScript
-- ✅ **Fixed conflict tracking** - Resolved conflicts are properly excluded from counts
+- **Database Snapshots** -- Create, restore, diff, and delete database snapshots with gzip compression
+- **Persistent Todo Lists** -- TodoListManager service with markdown files that survive context compactions
+- **AI-Powered Cleanup** -- CleanupAgent with OpenRouter-powered analysis for intelligent folder cleanup
+- **Timestamp Tracking** -- TimestampTracker service for precise sync tracking
+- **Database Schema v1.6.0** -- New tables for todo sessions, tasks, file timestamps, and generated files
 
-### Template Files Synced
+See [CHANGELOG.md](CHANGELOG.md) for full release history.
 
-| Directory | Files | Description |
-|-----------|-------|-------------|
-| `commands/` | 12 | Slash command definitions |
-| `agents/` | 6 | AI agent configurations |
-| `schemas/` | 14 | JSON schemas for validation |
-| `standards/` | 4 | Coding standards |
-| `tools/` | 3 | Tool-specific configurations |
-| `automation/` | 1 | Automation settings |
-| **Total** | **40** | **Excluded:** `context/`, `indexes/` (user-specific) |
+---
 
-## 📖 Complete CLI Reference
+## Complete CLI Reference
 
 ### Core Commands
 
@@ -336,10 +257,10 @@ k0ntext init --no-intelligent
 ```
 
 **Options:**
-- `--no-intelligent` - Skip OpenRouter-powered analysis
-- `--no-version-check` - Skip version checking for outdated context files (v3.4.0)
-- `--no-template-sync` - Skip template synchronization (v3.5.0)
-- `-v, --verbose` - Show detailed output
+- `--no-intelligent` -- Skip OpenRouter-powered analysis
+- `--no-version-check` -- Skip version checking for outdated context files
+- `--no-template-sync` -- Skip template synchronization
+- `-v, --verbose` -- Show detailed output
 
 #### `k0ntext generate`
 Generate context files for all AI tools.
@@ -359,10 +280,10 @@ k0ntext generate -v
 ```
 
 **Options:**
-- `-ai, --ai <tools>` - Specific tools (comma-separated)
-- `--force` - Force regenerate all files
-- `--map` - Use concise map-based format (new in v3.1.0)
-- `-v, --verbose` - Show detailed output
+- `-ai, --ai <tools>` -- Specific tools (comma-separated)
+- `--force` -- Force regenerate all files
+- `--map` -- Use concise map-based format
+- `-v, --verbose` -- Show detailed output
 
 #### `k0ntext mcp`
 Start the Model Context Protocol server.
@@ -376,7 +297,7 @@ k0ntext mcp --db .my-context.db
 ```
 
 **Options:**
-- `--db <path>` - Database file path
+- `--db <path>` -- Database file path
 
 #### `k0ntext sync`
 Synchronize context across AI tools.
@@ -399,10 +320,10 @@ k0ntext sync --force
 ```
 
 **Options:**
-- `--check` - Only check synchronization status
-- `--from <tool>` - Sync from specific tool
-- `--to <tool>` - Sync to specific tool
-- `--force` - Force sync even if up-to-date
+- `--check` -- Only check synchronization status
+- `--from <tool>` -- Sync from specific tool
+- `--to <tool>` -- Sync to specific tool
+- `--force` -- Force sync even if up-to-date
 
 #### `k0ntext cleanup`
 Clean up context folders from other AI tools.
@@ -419,10 +340,10 @@ k0ntext cleanup -v
 ```
 
 **Options:**
-- `--dry-run` - Show what would be removed
-- `--keep <folders>` - Folders to keep (comma-separated)
-- `--ai` - Use AI to intelligently analyze which folders can be safely removed (new in v3.1.0)
-- `-v, --verbose` - Show detailed output
+- `--dry-run` -- Show what would be removed
+- `--keep <folders>` -- Folders to keep (comma-separated)
+- `--ai` -- Use AI to intelligently analyze which folders can be safely removed
+- `-v, --verbose` -- Show detailed output
 
 #### `k0ntext validate`
 Validate context files and AI tool configurations.
@@ -439,8 +360,8 @@ k0ntext validate --strict
 ```
 
 **Options:**
-- `--fix` - Automatically fix validation errors
-- `--strict` - Treat warnings as errors
+- `--fix` -- Automatically fix validation errors
+- `--strict` -- Treat warnings as errors
 
 #### `k0ntext export <output>`
 Export context database to file.
@@ -457,8 +378,8 @@ k0ntext export workflows.json --type workflow
 ```
 
 **Options:**
-- `--format <format>` - Export format (json, markdown)
-- `--type <type>` - Filter by context type
+- `--format <format>` -- Export format (json, markdown)
+- `--type <type>` -- Filter by context type
 
 #### `k0ntext import <input>`
 Import context data from exported files.
@@ -472,8 +393,8 @@ k0ntext import context.json --merge
 ```
 
 **Options:**
-- `--format <format>` - Import format (json, markdown)
-- `--merge` - Merge with existing data (default: replace)
+- `--format <format>` -- Import format (json, markdown)
+- `--merge` -- Merge with existing data (default: replace)
 
 #### `k0ntext performance`
 Show performance metrics and optimization suggestions.
@@ -487,7 +408,7 @@ k0ntext performance --json
 ```
 
 **Options:**
-- `--json` - Output as JSON
+- `--json` -- Output as JSON
 
 #### `k0ntext watch`
 Watch for file changes and auto-update index.
@@ -501,7 +422,7 @@ k0ntext watch -d 2000
 ```
 
 **Options:**
-- `-d, --delay <ms>` - Debounce delay in milliseconds
+- `-d, --delay <ms>` -- Debounce delay in milliseconds
 
 #### `k0ntext index`
 Index codebase content into the database.
@@ -524,11 +445,11 @@ k0ntext index -v
 ```
 
 **Options:**
-- `--docs` - Index documentation files only
-- `--code` - Index source code only
-- `--tools` - Index AI tool configurations only
-- `--all` - Index everything (default)
-- `-v, --verbose` - Show detailed output
+- `--docs` -- Index documentation files only
+- `--code` -- Index source code only
+- `--tools` -- Index AI tool configurations only
+- `--all` -- Index everything (default)
+- `-v, --verbose` -- Show detailed output
 
 #### `k0ntext search <query>`
 Search across indexed content.
@@ -551,9 +472,9 @@ k0ntext search "database" -l 5
 ```
 
 **Options:**
-- `-t, --type <type>` - Filter by type
-- `-l, --limit <n>` - Maximum results (default: 10)
-- `-m, --mode <mode>` - Search mode: text, semantic, hybrid
+- `-t, --type <type>` -- Filter by type
+- `-l, --limit <n>` -- Maximum results (default: 10)
+- `-m, --mode <mode>` -- Search mode: text, semantic, hybrid
 
 #### `k0ntext stats`
 Show database and indexing statistics.
@@ -561,14 +482,11 @@ Show database and indexing statistics.
 ```bash
 # View all statistics
 k0ntext stats
-
-# Show specific stats (filtered by index)
-k0ntext stats | grep "Context Items"
 ```
 
-### v3.1.0 New Commands
+### Context Management Commands
 
-#### `k0ntext check` (v3.4.0)
+#### `k0ntext check`
 Check if context files are outdated.
 
 ```bash
@@ -586,11 +504,11 @@ k0ntext check --update --force
 ```
 
 **Options:**
-- `--update` - Prompt to update outdated files
-- `--force` - Update without prompting
-- `-v, --verbose` - Show detailed output
+- `--update` -- Prompt to update outdated files
+- `--force` -- Update without prompting
+- `-v, --verbose` -- Show detailed output
 
-#### `k0ntext restore` (v3.4.0)
+#### `k0ntext restore`
 Restore AI tool config files from backups.
 
 ```bash
@@ -605,18 +523,15 @@ k0ntext restore --backup "AI_CONTEXT.md.2026-02-09T14.30.45.123Z.bak"
 
 # Restore for specific tool
 k0ntext restore --tool claude --list
-
-# Force restore without confirmation
-k0ntext restore --backup <path> --force
 ```
 
 **Options:**
-- `--list` - List available backups
-- `--backup <path>` - Restore from specific backup path
-- `--tool <name>` - Filter by tool name
-- `--force` - Restore without confirmation
+- `--list` -- List available backups
+- `--backup <path>` -- Restore from specific backup path
+- `--tool <name>` -- Filter by tool name
+- `--force` -- Restore without confirmation
 
-#### `k0ntext sync-templates` (v3.5.0)
+#### `k0ntext sync-templates`
 Sync `.claude/` templates from package `templates/base/`.
 
 ```bash
@@ -631,22 +546,16 @@ k0ntext sync-templates --subdirs commands,agents
 
 # Force overwrite all conflicts
 k0ntext sync-templates --force
-
-# Verbose output with diffs
-k0ntext sync-templates --verbose
-
-# Skip archiving removed files
-k0ntext sync-templates --no-archive
 ```
 
 **Options:**
-- `--dry-run` - Show changes without applying
-- `--force` - Auto-overwrite conflicts without prompting
-- `--subdirs <dirs>` - Comma-separated subdirectories to sync (commands,agents,schemas,standards,tools,automation)
-- `-v, --verbose` - Show detailed output including diffs
-- `--no-archive` - Skip archiving removed files
+- `--dry-run` -- Show changes without applying
+- `--force` -- Auto-overwrite conflicts without prompting
+- `--subdirs <dirs>` -- Comma-separated subdirectories to sync
+- `-v, --verbose` -- Show detailed output including diffs
+- `--no-archive` -- Skip archiving removed files
 
-#### `k0ntext template-status` (v3.5.0)
+#### `k0ntext template-status`
 Show template sync status.
 
 ```bash
@@ -657,10 +566,24 @@ k0ntext template-status
 k0ntext template-status --verbose
 ```
 
-**Options:**
-- `-v, --verbose` - Show detailed status with file listings
+#### `k0ntext snapshot`
+Manage database snapshots.
+
+```bash
+# Create a snapshot
+k0ntext snapshot
+
+# Restore from snapshot
+k0ntext snapshot restore
+
+# List all snapshots
+k0ntext snapshots
 
-### v3.1.0 New Commands (Legacy)
+# Diff two snapshots
+k0ntext snap-diff
+```
+
+### AI Analysis Commands
 
 #### `k0ntext drift-detect`
 AI-powered documentation drift detection using semantic analysis.
@@ -672,23 +595,16 @@ k0ntext drift-detect
 # Detect drift in specific paths
 k0ntext drift-detect -p CLAUDE.md,.cursorrules
 
-# Check up to 20 files
-k0ntext drift-detect --max-files 20
-
 # Strict mode (fails on any drift)
 k0ntext drift-detect --strict
-
-# Verbose output
-k0ntext drift-detect -v
 ```
 
 **Options:**
-- `--fix` - Automatically fix detected drift (experimental)
-- `--strict` - Fail on any drift detected
-- `-p, --paths <paths>` - Comma-separated paths to check
-- `--max-files <number>` - Maximum files to check (default: 50)
-- `--model <model>` - Override model (not recommended)
-- `-v, --verbose` - Show detailed output
+- `--fix` -- Automatically fix detected drift (experimental)
+- `--strict` -- Fail on any drift detected
+- `-p, --paths <paths>` -- Comma-separated paths to check
+- `--max-files <number>` -- Maximum files to check (default: 50)
+- `-v, --verbose` -- Show detailed output
 
 #### `k0ntext cross-sync`
 Intelligently synchronize context across all AI tools after drift detection.
@@ -702,20 +618,14 @@ k0ntext cross-sync --dry-run
 
 # Sync to specific tools only
 k0ntext cross-sync --to claude,cursor
-
-# Sync from specific files
-k0ntext cross-sync --affected CLAUDE.md,.cursorrules
-
-# Verbose output with details
-k0ntext cross-sync -v
 ```
 
 **Options:**
-- `--dry-run` - Show what would be synced without making changes
-- `--from <tool>` - Sync only from specific tool
-- `--to <tools>` - Sync only to specific tools (comma-separated)
-- `--affected <files>` - Comma-separated list of affected files
-- `-v, --verbose` - Show detailed sync output
+- `--dry-run` -- Show what would be synced without making changes
+- `--from <tool>` -- Sync only from specific tool
+- `--to <tools>` -- Sync only to specific tools (comma-separated)
+- `--affected <files>` -- Comma-separated list of affected files
+- `-v, --verbose` -- Show detailed sync output
 
 #### `k0ntext hooks`
 Manage git hooks for automatic context synchronization.
@@ -724,9 +634,6 @@ Manage git hooks for automatic context synchronization.
 # Install git hooks
 k0ntext hooks install
 
-# Install with force (overwrite existing)
-k0ntext hooks install -f
-
 # Uninstall git hooks
 k0ntext hooks uninstall
 
@@ -735,13 +642,9 @@ k0ntext hooks status
 ```
 
 **Subcommands:**
-- `install` - Install pre-commit hook for automatic workflow
-- `uninstall` - Remove installed hooks
-- `status` - Show hook installation status
-
-**Install Options:**
-- `-f, --force` - Overwrite existing hooks
-- `--skip-backup` - Skip backing up existing hooks
+- `install` -- Install pre-commit hook for automatic workflow
+- `uninstall` -- Remove installed hooks
+- `status` -- Show hook installation status
 
 #### `k0ntext fact-check [files...]`
 Validate documentation accuracy using AI analysis.
@@ -752,28 +655,22 @@ k0ntext fact-check
 
 # Check specific files
 k0ntext fact-check CLAUDE.md .cursorrules
-
-# Set minimum confidence threshold
-k0ntext fact-check --min-confidence 0.7
-
-# Verbose output
-k0ntext fact-check -v
 ```
 
 **Options:**
-- `--fix` - Automatically fix detected issues (experimental)
-- `-v, --verbose` - Show detailed output
-- `--min-confidence <number>` - Minimum confidence to report (0-1, default: 0.5)
+- `--fix` -- Automatically fix detected issues (experimental)
+- `-v, --verbose` -- Show detailed output
+- `--min-confidence <number>` -- Minimum confidence to report (0-1, default: 0.5)
 
-### Git Hooks Workflow (v3.1.0)
+### Git Hooks Workflow
 
 When you install hooks with `k0ntext hooks install`, the pre-commit hook automatically:
 
-1. **Autosync** - Sync context from source of truth
-2. **Validate** - Check for context errors
-3. **Drift Detect** - AI-powered drift detection
-4. **Cross-Sync** - Update all AI tool contexts if drift found
-5. **Auto-Add** - Include updated context files in commit
+1. **Autosync** -- Sync context from source of truth
+2. **Validate** -- Check for context errors
+3. **Drift Detect** -- AI-powered drift detection
+4. **Cross-Sync** -- Update all AI tool contexts if drift found
+5. **Auto-Add** -- Include updated context files in commit
 
 **Skip hooks temporarily:**
 ```bash
@@ -782,9 +679,9 @@ K0NTEXT_SKIP_HOOKS=1 git commit -m "message"
 git commit --no-verify -m "message"
 ```
 
-## 🤖 MCP Server Usage
+## MCP Server Usage
 
-### Auto-Configuration (v3.1.1)
+### Auto-Configuration
 
 When you run `k0ntext init`, the MCP server is **automatically configured** in `.claude/settings.json`:
 
@@ -812,22 +709,22 @@ k0ntext mcp
 
 ### Available MCP Tools
 
-1. **search_context** - Semantic search across all indexed content
-2. **get_item** - Get a specific context item by ID or path
-3. **add_knowledge** - Store new insights or facts
-4. **analyze** - Run intelligent analysis on codebase
-5. **get_tool_configs** - Get AI tool configurations
-6. **query_graph** - Traverse knowledge graph
-7. **get_stats** - Get database statistics
+1. **search_context** -- Semantic search across all indexed content
+2. **get_item** -- Get a specific context item by ID or path
+3. **add_knowledge** -- Store new insights or facts
+4. **analyze** -- Run intelligent analysis on codebase
+5. **get_tool_configs** -- Get AI tool configurations
+6. **query_graph** -- Traverse knowledge graph
+7. **get_stats** -- Get database statistics
 
 ### Available Prompts
 
-1. **context-engineer** - Initialize and configure AI context system
-2. **core-architect** - Design system architecture
-3. **api-developer** - Develop API endpoints
-4. **database-ops** - Database operations
-5. **integration-hub** - External integrations
-6. **deployment-ops** - CI/CD and deployment
+1. **context-engineer** -- Initialize and configure AI context system
+2. **core-architect** -- Design system architecture
+3. **api-developer** -- Develop API endpoints
+4. **database-ops** -- Database operations
+5. **integration-hub** -- External integrations
+6. **deployment-ops** -- CI/CD and deployment
 
 ### Example MCP Tool Usage
 
@@ -852,28 +749,28 @@ await add_knowledge({
 });
 ```
 
-## 🎨 Supported AI Tools
+## Supported AI Tools
 
 ### Fully Supported
-- **Claude** - AI_CONTEXT.md
-- **GitHub Copilot** - .github/copilot-instructions.md
-- **Cursor** - .cursorrules
-- **Windsurf** - .windsurf/rules.md
-- **Cline** - .clinerules
-- **Aider** - .aider.conf.yml
-- **Continue** - .continue/config.json
-- **Antigravity** - .agent/README.md
-- **Gemini** - .gemini/config.md
+- **Claude** -- AI_CONTEXT.md
+- **GitHub Copilot** -- .github/copilot-instructions.md
+- **Cursor** -- .cursorrules
+- **Windsurf** -- .windsurf/rules.md
+- **Cline** -- .clinerules
+- **Aider** -- .aider.conf.yml
+- **Continue** -- .continue/config.json
+- **Antigravity** -- .agent/README.md
+- **Gemini** -- .gemini/config.md
 
 ### RPI Workflow Skills
-- **@context-engineer** - Setup and configuration
-- **@core-architect** - System design
-- **@api-developer** - API development
-- **@database-ops** - Database operations
-- **@integration-hub** - External integrations
-- **@deployment-ops** - CI/CD and deployment
+- **@context-engineer** -- Setup and configuration
+- **@core-architect** -- System design
+- **@api-developer** -- API development
+- **@database-ops** -- Database operations
+- **@integration-hub** -- External integrations
+- **@deployment-ops** -- CI/CD and deployment
 
-## 🔧 Configuration
+## Configuration
 
 ### Environment Variables
 
@@ -900,49 +797,58 @@ Each AI tool has its own configuration file path:
 - Antigravity: `.agent/README.md`
 - Gemini: `.gemini/config.md`
 
-## 🏗️ Architecture
+## Architecture
 
 ### System Components
 
 ```
 k0ntext/
 ├── src/                    # TypeScript source
-│   ├── cli/                # CLI commands (20 commands)
-│   │   ├── version/        # Version detection system (v3.4.0)
-│   │   ├── commands/       # Command implementations
-│   │   └── utils/          # File detector, backup manager (v3.4.0)
-│   ├── config/             # Centralized configuration (v3.1.0)
-│   ├── db/                 # SQLite database client
+│   ├── agent-system/       # TodoListManager, TimestampTracker
+│   ├── agents/             # Smart agents (Cleanup, Performance, Drift, FactCheck)
 │   ├── analyzer/           # Intelligent codebase analysis
+│   ├── cli/                # CLI commands, REPL shell, utilities
+│   │   ├── version/        # Version detection system
+│   │   ├── commands/       # Command implementations
+│   │   └── utils/          # File detector, backup manager
+│   ├── config/             # Centralized model configuration
+│   ├── db/                 # SQLite database client + migrations
 │   ├── embeddings/         # OpenRouter integration
-│   ├── agents/             # Smart agents (Cleanup, Performance, Drift, FactCheck)
-│   ├── template-engine/    # Handlebars template system (v3.4.0)
+│   ├── services/           # SnapshotManager and services
+│   ├── template-engine/    # Handlebars template system
+│   ├── template-sync/      # Template synchronization
+│   ├── utils/              # Utilities (chunking, encoding)
 │   └── mcp.ts              # MCP server implementation
 ├── agents/                 # Agent definitions
 ├── skills/                 # RPI workflow skills
 ├── templates/              # Output templates
+│   ├── base/               # Templates synced to user .claude/ directories
+│   └── map/                # Map-based context templates
 └── .k0ntext.db             # SQLite database (auto-created)
 ```
 
 ### Data Flow
 
-1. **Initialization** - `k0ntext init` discovers and analyzes codebase
-2. **Indexing** - `k0ntext index` stores content in SQLite with embeddings
-3. **Generation** - `k0ntext generate` creates tool-specific context files
-4. **Sync** - `k0ntext sync` keeps all AI tools synchronized
-5. **MCP Server** - `k0ntext mcp` provides real-time context to AI assistants
+1. **Initialization** -- `k0ntext init` discovers and analyzes codebase
+2. **Indexing** -- `k0ntext index` stores content in SQLite with embeddings
+3. **Generation** -- `k0ntext generate` creates tool-specific context files
+4. **Sync** -- `k0ntext sync` keeps all AI tools synchronized
+5. **MCP Server** -- `k0ntext mcp` provides real-time context to AI assistants
 
 ### Database Schema
 
 The SQLite database contains:
-- **Context Items** - Workflows, agents, commands, code, docs
-- **Embeddings** - Vector embeddings for semantic search
-- **Relations** - Knowledge graph connections
-- **Sync State** - Change tracking for synchronization (with version tracking in v3.4.0)
-- **Tool Configs** - AI tool configurations
-- **Generated Files** - File tracking with hashes and backups (v3.4.0)
-
-## 🚀 Development
+- **Context Items** -- Workflows, agents, commands, code, docs
+- **Embeddings** -- Vector embeddings for semantic search
+- **Relations** -- Knowledge graph connections
+- **Sync State** -- Change tracking for synchronization (with version tracking)
+- **Tool Configs** -- AI tool configurations
+- **Generated Files** -- File tracking with hashes and backups
+- **Todo Sessions/Tasks** -- Persistent task management
+- **File Timestamps** -- Sync tracking timestamps
+- **Snapshots** -- Database snapshot metadata
+
+## Development
 
 ### Build and Test
 
@@ -981,16 +887,18 @@ npm run publish:public
 4. Run tests and linting
 5. Submit a pull request
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
 ### Project Structure
 
-- `src/cli/` - Command implementations
-- `src/db/` - Database operations
-- `src/analyzer/` - Code analysis logic
-- `src/agents/` - Smart agents
-- `templates/` - Context templates
-- `.claude/` - Claude Code development context
+- `src/cli/` -- Command implementations
+- `src/db/` -- Database operations
+- `src/analyzer/` -- Code analysis logic
+- `src/agents/` -- Smart agents
+- `templates/` -- Context templates
+- `.claude/` -- Claude Code development context
 
-## 📊 Performance Monitoring
+## Performance Monitoring
 
 The PerformanceMonitorAgent provides insights into:
 - Query execution times
@@ -1006,13 +914,7 @@ k0ntext performance
 k0ntext performance --json
 ```
 
-Common optimization suggestions:
-- Add indexes for frequently queried columns
-- Run VACUUM for large databases
-- Review and optimize slow queries
-- Monitor cache hit rates
-
-## 🔍 Troubleshooting
+## Troubleshooting
 
 ### Common Issues
 
@@ -1049,13 +951,15 @@ k0ntext index -v
 k0ntext generate -v
 ```
 
-## 🤝 Community
+See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for the full troubleshooting guide.
+
+## Community
 
 - **GitHub Issues:** [Report bugs and request features](https://github.com/SireJeff/k0ntext/issues)
 - **Discussions:** [Join community discussions](https://github.com/SireJeff/k0ntext/discussions)
-- **Documentation:** [Full API documentation](./docs/)
+- **Documentation:** [Full docs](./docs/)
 
-## 📄 License
+## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
@@ -1066,4 +970,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 **Issues:** https://github.com/SireJeff/k0ntext/issues
 **MCP Protocol:** https://modelcontextprotocol.io
 
-Made with ❤️ by [SireJeff](https://github.com/SireJeff)
+Made with care by [SireJeff](https://github.com/SireJeff)