# KERNL V2.0 - Desktop Commander Absorption

## 📊 EXECUTIVE SUMMARY

**Mission**: Transform KERNL from persistence layer → complete authoritative agency platform

**Impact**:
- 🎯 **Single MCP server** (eliminate Desktop Commander)
- 🚀 **75 total tools** (44 + 31)
- 💪 **Complete agency**: Persistence + Intelligence + System Control
- 🏆 **Cognitive monopoly**: No competitor has this combination

---

## 🎯 CURRENT STATE → TARGET STATE

```
CURRENT (Incomplete V2.0 Vision)
┌─────────────────────────────────┐
│ KERNL (44 tools)                │
│ ✅ Persistence                  │
│ ✅ Intelligence                 │
│ ❌ System Control               │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│ Desktop Commander (31 tools)    │
│ ✅ System Control               │
│ ❌ Persistence                  │
│ ❌ Intelligence                 │
└─────────────────────────────────┘

TARGET (Complete V2.0 Vision)
┌─────────────────────────────────┐
│ KERNL V2.0 (75 tools)           │
│ ✅ Persistence                  │
│ ✅ Intelligence                 │
│ ✅ System Control               │
│                                  │
│ = AUTHORITATIVE AGENCY          │
└─────────────────────────────────┘

Desktop Commander → DEPRECATED
```

---

## 📋 TOOL BREAKDOWN

### Tools to Add (31 from Desktop Commander)

**Revolutionary (Phase 2 - Highest Priority)**
- ⭐ `edit_block` - Surgical file editing (game-changer!)
- ⭐ `write_pdf` - PDF creation/modification
- ⭐ `start_process` - Terminal with smart detection
- ⭐ `interact_with_process` - REPL control
- ⭐ `read_process_output` - Process output with pagination
- ⭐ `copy_file_user_to_claude` - Cross-filesystem bridge

**Enhanced File Ops (Phase 3 - Merge)**
- 📁 Enhance `pm_read_file` with offset/length/Excel/PDF
- 📁 Enhance `pm_write_file` with chunking/Excel
- 📁 Enhance `pm_list_files` with recursive depth
- 📁 Enhance `pm_get_file_info` with line counts
- 📁 Merge `pm_batch_read` + `read_multiple_files`

**Search (Phase 4)**
- 🔍 `start_search` - Streaming search
- 🔍 `get_more_search_results` - Pagination
- 🔍 `stop_search` - Cancel
- 🔍 `list_searches` - Active searches

**Process Suite (Phase 5)**
- ⚙️ `force_terminate` - Kill process
- ⚙️ `list_sessions` - Active sessions
- ⚙️ `list_processes` - System processes
- ⚙️ `kill_process` - Terminate by PID

**Configuration (Phase 6)**
- ⚙️ `get_config` - Server configuration
- ⚙️ `set_config_value` - Update config
- ⚙️ `get_usage_stats` - Analytics
- ⚙️ `get_recent_tool_calls` - Tool history

**Other**
- 📦 `list_allowed_directories` - Show paths
- 📦 `create_directory` - Make directories
- 📦 `move_file` - Move/rename
- 📦 `get_prompts` - Onboarding prompts

---

## 🏗️ IMPLEMENTATION PLAN

### Phase 1: Foundation & Planning ✅ IN PROGRESS
**Duration**: 2 days  
**Status**: Blueprint complete, awaiting approval

**Deliverables**:
- ✅ Absorption blueprint created
- ⏳ Tool specification document
- ⏳ Naming convention decision
- ⏳ Dependency analysis
- ⏳ Merge strategy design

### Phase 2: Revolutionary Tools
**Duration**: 3 days  
**Tools**: 6 most valuable DC capabilities

**Impact**: Immediately unlocks game-changing features
- Surgical editing (edit_block)
- PDF manipulation
- REPL integration
- Cross-filesystem operations

### Phase 3: Enhanced File Operations
**Duration**: 2 days  
**Tools**: 5 enhanced file operations

**Impact**: Unified file operations with best of both worlds

### Phase 4: Search Capabilities
**Duration**: 2 days  
**Tools**: 4 streaming search tools

**Impact**: Advanced search with project awareness

### Phase 5: Process Management
**Duration**: 2 days  
**Tools**: 5 process control tools

**Impact**: Complete process lifecycle management

### Phase 6: Configuration & Meta
**Duration**: 1 day  
**Tools**: 4 configuration tools

**Impact**: Unified configuration and analytics

### Phase 7: Integration & Testing
**Duration**: 2 days  
**Focus**: Final testing and deployment

**Impact**: Production-ready V2.0

**Total**: ~2 weeks

---

## 🎨 NAMING STRATEGY

**Decision**: Hybrid approach for clarity

| Type | Prefix | Example | When to Use |
|------|--------|---------|-------------|
| Project-Aware | `pm_*` | `pm_read_file` | Needs project context + KERNL DB |
| System Control | `sys_*` | `sys_start_process` | Pure system ops, no project context |
| Enhanced | `pm_*` | `pm_read_file` (enhanced) | Merged KERNL + DC functionality |

**Rationale**:
- Clear separation between project-aware and system-level
- Backward compatible with existing pm_* tools
- Easy to search/filter tools
- Future-proof for additional system tools

---

## ⚠️ CRITICAL OVERLAPS TO RESOLVE

| KERNL Tool | DC Tool | Resolution |
|------------|---------|-----------|
| `pm_read_file` | `read_file` | **Merge**: Enhance with offset/length/Excel/PDF |
| `pm_write_file` | `write_file` | **Merge**: Add chunking + Excel support |
| `pm_batch_read` | `read_multiple_files` | **Merge**: Combine implementations |
| `pm_list_files` | `list_directory` | **Merge**: Add recursive depth |
| `pm_get_file_info` | `get_file_info` | **Merge**: Add line counts |
| `pm_search_files` | `start_search` | **Keep Both**: Different use cases |

**Strategy**: Enhance KERNL tools with DC features, maintain project-awareness

---

## 📦 DEPENDENCIES

**Good News**: Most dependencies already in KERNL! ✅

**Already Present**:
- `pdf-lib` ✅
- `pdf-parse` ✅
- `exceljs` ✅
- `chokidar` ✅
- `sharp` ✅

**Possibly Needed** (To verify):
- Terminal emulation: Node.js built-in or `node-pty`
- Process monitoring: Node.js built-in APIs

**Action**: Minimal dependency additions required

---

## 📊 SUCCESS CRITERIA

### Must Have
- ✅ 75 total tools registered and working
- ✅ 0 new TypeScript errors
- ✅ All existing tests passing
- ✅ Desktop Commander removable from config
- ✅ Complete documentation

### Nice to Have
- ✅ Performance within targets (<100ms file ops)
- ✅ >90% test coverage
- ✅ Migration guide for users
- ✅ Backward compatibility maintained

---

## 🎯 THE V2.0 PROMISE

> **"KERNL V2.0 eliminates the 8-minute death, the bootstrap tax, AND provides full desktop control. One MCP server. Complete agency. Zero friction."**

**What Users Get**:
1. ❌ Remove Desktop Commander MCP
2. ✅ Single unified intelligence layer
3. ✅ Persistent context + system control
4. ✅ Crash recovery for everything
5. ✅ Cross-project learning + file operations
6. ✅ True authoritative agency

---

## 🚦 NEXT ACTIONS

### Immediate (Now)
1. **Review blueprint** - Get user approval on:
   - Naming strategy (pm_* vs sys_*)
   - Overlap resolution approach
   - 7-phase plan (2 weeks)

2. **Create tool specs** - Document all 31 DC tools in detail

3. **Begin Phase 2** - Start with `edit_block` (highest value)

### This Week
- Implement 6 revolutionary tools
- Merge 5 file operation tools
- Begin search capabilities

### Next Week
- Complete process management
- Add configuration tools
- Integration testing
- Production deployment

---

## 📚 REFERENCE

**Full Blueprint**: `D:/Project Mind/kernl-mcp/docs/v2-absorption/DESKTOP_COMMANDER_ABSORPTION_BLUEPRINT.md`

**Key Files**:
- `src/server/mcp-server.ts` - Tool registration
- `src/tools/` - All tool implementations
- `docs/TOOL_REFERENCE.md` - Complete tool docs

**Current Stats**:
- Version: 4.4.0
- Tools: 44 (target: 75)
- Branch: `feature/v2-absorb-desktop-commander`

---

*Quick Reference: V2.0 Desktop Commander Absorption*  
*Status: Phase 1 Complete, Awaiting Approval*  
*Created: January 7, 2026*