k0ntext 3.0.0 → 3.1.1

package/README.md

@@ -9,6 +9,38 @@
 
 Universal AI context engineering for Claude, GitHub Copilot, Cline, Cursor, Windsurf, Aider, Continue, Antigravity, and Gemini with OpenRouter-powered intelligent analysis.
 
+## 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)
+  - [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 (30 Seconds)
 
 ```bash
@@ -38,7 +70,7 @@ k0ntext index
 # 3. Generate context files
 k0ntext generate
 
-# 4. Start MCP server
+# 4. Start MCP server (auto-configured)
 k0ntext mcp
 ```
 
@@ -73,6 +105,7 @@ K0ntext uses native SQLite extensions for high-performance vector search.
 - 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
 
 ### 🔍 Semantic Search
 - Vector database (sqlite-vec) for intelligent code retrieval
@@ -85,14 +118,61 @@ K0ntext uses native SQLite extensions for high-performance vector search.
 - 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
+
+### 🤖 Git Hooks Automation (v3.1.0)
+- **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
+- Replaces hash-based checks with intelligent understanding
+- Severity-based reporting (high/medium/low)
+- Automatic fix suggestions
+
+### 📋 Fact-Checking (v3.1.0)
+- Validate documentation accuracy against codebase
+- Identify outdated APIs, wrong file paths, missing dependencies
+- Confidence scoring for each claim
+
+### 🗺️ Map-Based Context (v3.1.0)
+- Concise, structured context files
+- Reduce hallucination through precise references
+- Alternative to verbose documentation format
 
 ### 🤖 MCP Server
+- **Auto-Configuration** (v3.1.1) - 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
 - **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 (13 Commands)
+### 🛠️ Complete CLI (18 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
+- **`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)
+- **CLI documentation in all templates** (v3.1.1) - Agent and command templates now include k0ntext CLI usage guidance
 - `init` - Initialize with intelligent analysis
 - `generate` - Generate context files for all tools
 - `mcp` - Start MCP server
@@ -106,10 +186,17 @@ K0ntext uses native SQLite extensions for high-performance vector search.
 - `index` - Index codebase
 - `search` - Search indexed content
 - `stats` - View database statistics
+- **`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
 
 ### 📊 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
 - Persistent database with SHA256 change detection
@@ -159,6 +246,7 @@ 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
 
 #### `k0ntext mcp`
@@ -218,6 +306,7 @@ 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
 
 #### `k0ntext validate`
@@ -362,11 +451,153 @@ k0ntext stats
 k0ntext stats | grep "Context Items"
 ```
 
+### v3.1.0 New Commands
+
+#### `k0ntext drift-detect`
+AI-powered documentation drift detection using semantic analysis.
+
+```bash
+# Detect drift in all context files
+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
+
+#### `k0ntext cross-sync`
+Intelligently synchronize context across all AI tools after drift detection.
+
+```bash
+# Sync all affected files
+k0ntext cross-sync
+
+# Dry run to see what would be synced
+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
+
+#### `k0ntext hooks`
+Manage git hooks for automatic context synchronization.
+
+```bash
+# Install git hooks
+k0ntext hooks install
+
+# Install with force (overwrite existing)
+k0ntext hooks install -f
+
+# Uninstall git hooks
+k0ntext hooks uninstall
+
+# Check hooks status
+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
+
+#### `k0ntext fact-check [files...]`
+Validate documentation accuracy using AI analysis.
+
+```bash
+# Check all documentation files
+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)
+
+### Git Hooks Workflow (v3.1.0)
+
+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
+
+**Skip hooks temporarily:**
+```bash
+K0NTEXT_SKIP_HOOKS=1 git commit -m "message"
+# or
+git commit --no-verify -m "message"
+```
+
 ## 🤖 MCP Server Usage
 
+### Auto-Configuration (v3.1.1)
+
+When you run `k0ntext init`, the MCP server is **automatically configured** in `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "k0ntext": {
+      "command": "npx",
+      "args": ["k0ntext", "mcp"],
+      "env": {
+        "K0NTEXT_PROJECT_ROOT": "${projectFolder}"
+      }
+    }
+  }
+}
+```
+
+**Manual setup is no longer required!** The MCP server works immediately after initialization.
+
 ### Start the Server
 ```bash
-# Start MCP server
+# Start MCP server (auto-configured)
 k0ntext mcp
 ```
 
@@ -467,11 +698,12 @@ Each AI tool has its own configuration file path:
 ```
 k0ntext/
 ├── src/                    # TypeScript source
-│   ├── cli/                # CLI commands (13 commands)
+│   ├── cli/                # CLI commands (18 commands)
+│   ├── config/             # Centralized configuration (v3.1.0)
 │   ├── db/                 # SQLite database client
 │   ├── analyzer/           # Intelligent codebase analysis
 │   ├── embeddings/         # OpenRouter integration
-│   ├── agents/             # Smart agents (Cleanup, Performance)
+│   ├── agents/             # Smart agents (Cleanup, Performance, Drift, FactCheck)
 │   └── mcp.ts              # MCP server implementation
 ├── agents/                 # Agent definitions
 ├── skills/                 # RPI workflow skills

package/dist/agents/drift-agent.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Drift Detection Agent
+ *
+ * Uses AI to detect when documentation drifts from the actual codebase.
+ * This is the core of intelligent drift detection for k0ntext v3.1.0.
+ *
+ * @version 3.1.0
+ */
+import { OpenRouterClient } from '../embeddings/openrouter.js';
+/**
+ * A detected drift issue
+ */
+export interface DriftIssue {
+    /** The file where drift was detected */
+    file: string;
+    /** Severity level */
+    severity: 'low' | 'medium' | 'high';
+    /** What the documentation says */
+    expected: string;
+    /** What the actual codebase has */
+    actual: string;
+    /** Suggested fix (optional) */
+    suggestion?: string;
+    /** Line number where drift occurs (optional) */
+    line?: number;
+}
+/**
+ * Result of drift detection
+ */
+export interface DriftResult {
+    /** All detected drifts */
+    drifts: DriftIssue[];
+    /** Number of drifts automatically fixed */
+    fixed: number;
+    /** Files checked */
+    filesChecked: number;
+    /** Time taken in milliseconds */
+    duration: number;
+}
+/**
+ * Configuration for the drift agent
+ */
+export interface DriftAgentConfig {
+    /** OpenRouter client for AI analysis */
+    openRouter: OpenRouterClient;
+    /** Model override (not recommended) */
+    model?: string;
+    /** Whether to fail on any drift */
+    strict?: boolean;
+    /** Project root directory */
+    projectRoot: string;
+}
+/**
+ * Drift Detection Agent
+ *
+ * Analyzes documentation files and compares them against the actual
+ * codebase to detect discrepancies using AI semantic analysis.
+ */
+export declare class DriftAgent {
+    private openRouter;
+    private model;
+    private strict;
+    private projectRoot;
+    constructor(config: DriftAgentConfig);
+    /**
+     * Detect drift across all context files
+     */
+    detectDrift(options: {
+        paths?: string[];
+        autoFix?: boolean;
+        maxFiles?: number;
+    }): Promise<DriftResult>;
+    /**
+     * Check a single file for drift
+     */
+    private checkFileForDrift;
+    /**
+     * Get the drift detection system prompt
+     */
+    private getDriftDetectionPrompt;
+    /**
+     * Build the drift analysis prompt for a specific file
+     */
+    private buildDriftAnalysisPrompt;
+    /**
+     * Parse the drift detection response
+     */
+    private parseDriftResponse;
+    /**
+     * Get relevant source code samples for comparison
+     */
+    private getRelevantSourceSamples;
+    /**
+     * Discover source files in the project
+     */
+    private discoverSourceFiles;
+    /**
+     * Get all context files to check
+     */
+    private getContextFiles;
+    /**
+     * Attempt to fix drift in a file
+     */
+    private fixDrift;
+    /**
+     * Close the agent and clean up resources
+     */
+    close(): void;
+}
+/**
+ * Create a drift agent
+ */
+export declare function createDriftAgent(config: Omit<DriftAgentConfig, 'projectRoot'>): DriftAgent;
+//# sourceMappingURL=drift-agent.d.ts.map

package/dist/agents/drift-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-agent.d.ts","sourceRoot":"","sources":["../../src/agents/drift-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpC,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AA4CD;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,gBAAgB;IAOpC;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE;QACzB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,WAAW,CAAC;IAuCxB;;OAEG;YACW,iBAAiB;IAsD/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA4B/B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqBhC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;OAEG;YACW,wBAAwB;IAuCtC;;OAEG;YACW,mBAAmB;IA0BjC;;OAEG;YACW,eAAe;IAgB7B;;OAEG;YACW,QAAQ;IAQtB;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,aAAa,CAAC,GAAG,UAAU,CAK1F"}