k0ntext 3.0.0

package/docs/CLEANUP.md

@@ -0,0 +1,76 @@
+# Context Cleanup
+
+The context cleanup feature helps you remove leftover context folders from various AI tools that may be cluttering your project directory.
+
+## Usage
+
+```bash
+k0ntext cleanup [options]
+```
+
+## Options
+
+- `--dry-run` - Show what would be removed without actually deleting anything
+- `--keep <folders>` - Folders to keep (comma-separated list)
+- `--verbose` - Show detailed output during cleanup
+
+## Examples
+
+### Basic cleanup (dry run)
+```bash
+k0ntext cleanup --dry-run
+```
+
+### Clean up with specific folders to keep
+```bash
+k0ntext cleanup --keep .vscode,.github
+```
+
+### Full cleanup with verbose output
+```bash
+k0ntext cleanup --verbose
+```
+
+## Folders Cleaned
+
+The cleanup agent removes the following tool-specific folders:
+
+- `.cursor` - Cursor AI tool
+- `.windsurf` - Windsurf AI tool
+- `.cline` - Cline AI tool
+- `.aider` - Aider AI tool
+- `.continue` - Continue AI tool
+- `.copilot` - GitHub Copilot
+- `.cursorrules` - Cursor rules
+- `.ai-context` - Legacy AI context folders
+- `.github` - GitHub configuration
+- `.vscode` - VSCode settings
+- `.idea` - IntelliJ IDEA settings
+- `.devcontainer` - Dev container configuration
+
+## Safety Features
+
+- **Dry Run Mode**: Always run with `--dry-run` first to see what will be removed
+- **Keep Option**: Specify folders to preserve using the `--keep` flag
+- **Verbose Output**: See detailed information about what's being processed
+- **Error Handling**: Errors during removal are caught and reported without stopping the process
+
+## Best Practices
+
+1. Always run with `--dry-run` first to review what will be removed
+2. Use the `--keep` option to preserve important configuration folders
+3. Backup your project before running a full cleanup
+4. Run cleanup periodically to maintain a clean project structure
+
+## Troubleshooting
+
+If you encounter permission errors:
+- Ensure you have proper file system permissions
+- Try running with elevated privileges if needed
+- Check if folders are in use by running processes
+
+## Related Commands
+
+- `k0ntext init` - Initialize AI context for a project
+- `k0ntext index` - Index codebase content into the database
+- `k0ntext sync` - Sync across AI tools

package/docs/MCP_QUICKSTART.md

@@ -0,0 +1,219 @@
+# K0ntext - MCP Server Quick Start
+
+Connect the K0ntext MCP server to Claude Desktop (or other MCP-compatible AI assistants) to give your AI intelligent access to your codebase.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is a standard for AI assistants to access external tools and data. With K0ntext's MCP server, your AI can:
+
+- Search your codebase semantically
+- Retrieve specific files and context
+- Query the knowledge graph
+- Run intelligent analysis
+- Check documentation drift
+
+## Prerequisites
+
+1. **K0ntext installed:**
+   ```bash
+   npm install -g k0ntext
+   ```
+
+2. **Claude Desktop** (or another MCP-compatible client)
+
+3. **A project initialized with K0ntext:**
+   ```bash
+   cd your-project
+   k0ntext init
+   ```
+
+## Setup with Claude Desktop
+
+### Step 1: Find Your Claude Config
+
+The config location depends on your OS:
+
+| Platform | Config Path |
+|----------|-------------|
+| macOS    | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows  | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux    | `~/.config/Claude/claude_desktop_config.json` |
+
+### Step 2: Add K0ntext MCP Server
+
+Edit your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "k0ntext": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "k0ntext",
+        "mcp"
+      ],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+**Important:** Replace `/path/to/your/project` with your actual project path.
+
+#### Multiple Projects
+
+For multiple projects, use different server names:
+
+```json
+{
+  "mcpServers": {
+    "k0ntext-project-a": {
+      "command": "npx",
+      "args": ["-y", "k0ntext", "mcp"],
+      "cwd": "/path/to/project-a"
+    },
+    "k0ntext-project-b": {
+      "command": "npx",
+      "args": ["-y", "k0ntext", "mcp"],
+      "cwd": "/path/to/project-b"
+    }
+  }
+}
+```
+
+### Step 3: Restart Claude Desktop
+
+Completely quit and restart Claude Desktop.
+
+### Step 4: Verify Connection
+
+In a new Claude conversation, you should see **k0ntext** listed in the available MCP tools.
+
+## Available MCP Tools
+
+The K0ntext MCP server provides these tools:
+
+| Tool | Description |
+|------|-------------|
+| `search_context` | Semantic search across indexed content |
+| `get_item` | Retrieve specific context items by ID |
+| `add_knowledge` | Store insights and facts |
+| `analyze` | Run intelligent codebase analysis |
+| `get_tool_configs` | View AI tool configurations |
+| `query_graph` | Traverse knowledge graph |
+| `get_stats` | Database statistics |
+| `add_relation` | Add relationships between items |
+| `find_path` | Find paths between items |
+| `run_drift_check` | Check documentation sync |
+
+## Usage Examples
+
+### Semantic Search
+
+Ask Claude:
+> "Search my codebase for how authentication is implemented"
+
+Claude will use `search_context` to find relevant code.
+
+### Get Specific Item
+
+Ask Claude:
+> "Get the item with ID abc123"
+
+### Add Knowledge
+
+Ask Claude:
+> "Add to my knowledge base: The authentication system uses JWT tokens with a 1-hour expiration"
+
+### Run Analysis
+
+Ask Claude:
+> "Run an intelligent analysis of my codebase"
+
+## Troubleshooting
+
+### MCP Server Not Appearing
+
+1. **Check config path:** Ensure you're editing the correct config file
+2. **Restart Claude:** Completely quit and restart Claude Desktop
+3. **Check project path:** Verify `cwd` points to a valid project with `.k0ntext.db`
+4. **Check logs:** Look for MCP errors in Claude's developer console
+
+### Database Not Found
+
+```
+Error: Database file not found: .k0ntext.db
+```
+
+**Solution:** Run `k0ntext init` in your project directory first.
+
+### OpenRouter API Key Missing
+
+If using intelligent analysis:
+
+```
+Error: OPENROUTER_API_KEY not set
+```
+
+**Solution:** Set your API key:
+```bash
+export OPENROUTER_API_KEY="your-key-here"
+```
+
+Or add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).
+
+### Port Already in Use
+
+```
+Error: Port 3000 already in use
+```
+
+**Solution:** The MCP server uses stdio (not HTTP), so this shouldn't occur. If it does, ensure no other MCP servers are configured with the same name.
+
+## Advanced Configuration
+
+### Custom Server Port (Future)
+
+The current MCP server uses stdio transport. HTTP/SSE transport may be added in the future.
+
+### Environment Variables
+
+Available environment variables for the MCP server:
+
+```bash
+# Database location
+export K0NTEXT_DB_PATH="/custom/path/.k0ntext.db"
+
+# OpenRouter API key (for intelligent analysis)
+export OPENROUTER_API_KEY="your-key-here"
+
+# Log level
+export K0NTEXT_LOG_LEVEL="debug"  # debug, info, warn, error
+```
+
+## MCP Prompts
+
+K0ntext also provides **6 prompts** for Claude:
+
+| Prompt | Description |
+|--------|-------------|
+| `analyze-codebase` | Analyze the entire codebase |
+| `find-similar-code` | Find code similar to a pattern |
+| `explain-architecture` | Explain system architecture |
+| `review-changes` | Review recent code changes |
+| `suggest-improvements` | Suggest code improvements |
+| `check-drift` | Check documentation drift |
+
+These prompts can be invoked directly from Claude Desktop.
+
+## Next Steps
+
+- **Full Documentation:** https://github.com/SireJeff/k0ntext
+- **Troubleshooting:** [Troubleshooting Guide](TROUBLESHOOTING.md)
+- **MCP Specification:** https://modelcontextprotocol.io
+
+## Support
+
+- **Issues:** https://github.com/SireJeff/k0ntext/issues
+- **Discussions:** https://github.com/SireJeff/k0ntext/discussions

package/docs/QUICKSTART.md

@@ -0,0 +1,119 @@
+# K0ntext - Quick Start Guide
+
+Get up and running with K0ntext in 5 minutes.
+
+## Installation
+
+```bash
+npm install -g k0ntext
+```
+
+**Requirements:** Node.js 18 or higher
+
+## Initialize Your Project
+
+Navigate to your project directory and run:
+
+```bash
+cd your-project
+k0ntext init
+```
+
+This will:
+1. Analyze your codebase (intelligent analysis powered by OpenRouter)
+2. Create a SQLite database at `.k0ntext.db`
+3. Index your source code with semantic embeddings
+4. Generate optimized context files for your AI tools
+
+### Skip Intelligent Analysis (Optional)
+
+If you want to skip the OpenRouter-powered intelligent analysis:
+
+```bash
+k0ntext init --no-intelligent
+```
+
+This will use a faster static analysis instead.
+
+## Generate Context Files
+
+To regenerate context files for all AI tools:
+
+```bash
+k0ntext generate
+```
+
+## Start MCP Server
+
+The MCP (Model Context Protocol) server provides AI assistants with tools to query your codebase:
+
+```bash
+k0ntext mcp
+```
+
+See [MCP Quick Start](MCP_QUICKSTART.md) for setup instructions.
+
+## Other Commands
+
+```bash
+k0ntext index          # Index codebase into database
+k0ntext search <query> # Semantic search across code
+k0ntext sync           # Sync context across AI tools
+k0ntext stats          # Database statistics
+```
+
+## What Gets Created
+
+After initialization, you'll find:
+
+```
+your-project/
+├── .k0ntext.db          # SQLite database (embeddings + metadata)
+├── .k0ntext/            # Generated contexts
+│   ├── AI_CONTEXT.md       # For Claude/Cursor/etc
+│   └── sync-state.json     # Cross-tool sync state
+├── .github/copilot-instructions.md  # For GitHub Copilot
+├── .clinerules             # For Cline
+├── .cursorrules            # For Cursor
+└── ...more tool configs
+```
+
+## Next Steps
+
+1. **Configure Claude Desktop with MCP** → [MCP Quick Start](MCP_QUICKSTART.md)
+2. **Learn about cross-tool sync** → [Migration Guide](MIGRATE_TO_UNIFIED.md)
+3. **Troubleshoot issues** → [Troubleshooting](TROUBLESHOOTING.md)
+
+## How It Works
+
+K0ntext uses a three-phase process:
+
+1. **Analysis Phase** (optional):
+   - OpenRouter API analyzes your entire codebase
+   - Identifies patterns, tech stack, and architecture
+   - Provides AI-powered insights for better context
+
+2. **Indexing Phase**:
+   - Files are scanned and change-detected (SHA256)
+   - Content is embedded with OpenRouter embeddings
+   - Stored in SQLite with sqlite-vec for vector search
+
+3. **Generation Phase**:
+   - Context files are generated for 9+ AI tools
+   - Cross-tool sync state is tracked
+   - Optimized prompts are created for each tool
+
+## Environment Variables
+
+```bash
+# Optional: For intelligent analysis
+export OPENROUTER_API_KEY="your-key-here"
+
+# Optional: Specify which AI tools to generate for
+export AI_CONTEXT_TOOLS="claude,copilot,cline"
+```
+
+## Support
+
+- **Issues:** https://github.com/SireJeff/k0ntext/issues
+- **Docs:** https://github.com/SireJeff/k0ntext