# KERNL V2.0 Tool Reference

**Complete reference for all 75 KERNL tools**

**Version:** 5.0.0  
**Last Updated:** January 7, 2026  
**Tools:** 75 across 17 categories

---

## 📖 Table of Contents

1. [Session Management](#session-management) (5 tools)
2. [Project Management](#project-management) (3 tools)
3. [Filesystem Operations](#filesystem-operations) (6 tools)
4. [Intelligence Features](#intelligence-features) (3 tools)
5. [Backlog Management](#backlog-management) (4 tools)
6. [Git Integration](#git-integration) (2 tools)
7. [Research Capabilities](#research-capabilities) (2 tools)
8. [Conversation Export](#conversation-export) (3 tools)
9. [Process Control](#process-control) (7 tools)
10. [Advanced Search](#advanced-search) (4 tools)
11. [System Files](#system-files) (5 tools)
12. [Configuration & Meta](#configuration--meta) (4 tools)
13. [Testing Suite](#testing-suite) (4 tools)
14. [Integration Tools](#integration-tools) (3 tools)
15. [System Control](#system-control) (3 tools)

---

## Session Management

**Revolutionary crash recovery and context preservation**

### `check_resume_needed`

**Purpose:** Detect incomplete work from previous session

**Parameters:**
- `project` (string, required): Project ID to check

**Returns:**
- `needsResume` (boolean): Whether resume is needed
- `resumePrompt` (string): Full context for resuming
- `sessionState` (object): Current session state

**Example:**
```typescript
check_resume_needed({ project: "my-app" })

// Returns:
{
  needsResume: true,
  resumePrompt: "Last session: Refactoring authentication (60% complete)...",
  sessionState: {
    operation: "Refactoring authentication",
    progress: 0.6,
    currentStep: "Implementing JWT validation"
  }
}
```

**Use Cases:**
- Start of EVERY session
- Before beginning new work
- After Claude crashes

---

### `auto_checkpoint`

**Purpose:** Save session progress automatically

**Parameters:**
- `project` (string, required): Project ID
- `operation` (string, required): Current operation
- `progress` (number, required): 0.0-1.0
- `currentStep` (string, optional): Current step
- `decisions` (array, optional): Decisions made
- `nextSteps` (array, optional): Remaining steps
- `activeFiles` (array, optional): Files being edited

**Returns:**
- `success` (boolean): Whether checkpoint saved
- `sessionId` (string): Session identifier
- `recommendation` (string): Timing recommendation

**Example:**
```typescript
auto_checkpoint({
  project: "my-app",
  operation: "Building authentication",
  progress: 0.5,
  currentStep: "Implementing JWT validation",
  decisions: ["Use RS256", "30min expiry"],
  nextSteps: ["Add refresh tokens", "Update tests"],
  activeFiles: ["src/auth/jwt.ts", "src/auth/middleware.ts"]
})

// Call every 5-10 tool calls during active work
```

**Use Cases:**
- Every 5-10 tool calls
- Before risky operations
- At progress milestones (25%, 50%, 75%)

---

### `mark_complete`

**Purpose:** Clear resume state when task complete

**Parameters:**
- `project` (string, required): Project ID
- `summary` (string, required): Completion summary

**Returns:**
- `success` (boolean): Whether cleared
- `message` (string): Confirmation

**Example:**
```typescript
mark_complete({
  project: "my-app",
  summary: "Authentication refactor complete with tests"
})
```

---

### `get_session_state`

**Purpose:** Manually check session state

**Parameters:**
- `project` (string, required): Project ID

**Returns:**
- Current session state or null

---

### `save_session_state`

**Purpose:** Manually save checkpoint

**Parameters:**
- `project` (string, required): Project ID
- `currentTask` (object, required): Task details
- `context` (object, required): Session context

**Returns:**
- Saved session state

---

## Project Management

**Multi-tenant project registry with metadata**

### `pm_register_project`

**Purpose:** Register a new project

**Parameters:**
- `id` (string, required): Project ID (unique)
- `name` (string, required): Project name
- `path` (string, required): Project path
- `config` (object, optional): Project configuration

**Example:**
```typescript
pm_register_project({
  id: "my-app",
  name: "My Application",
  path: "C:/Projects/my-app",
  config: {
    fileScanning: { mode: "auto" },
    git: { enabled: true }
  }
})
```

---

### `pm_list_projects`

**Purpose:** List all registered projects

**Parameters:** None

**Returns:** Array of all projects

---

### `pm_get_project`

**Purpose:** Get specific project details

**Parameters:**
- `project` (string, required): Project ID

**Returns:** Project object with full metadata

---

## Filesystem Operations

**Format-aware file operations with Excel/PDF/Image support**

### `pm_read_file`

**Purpose:** Read file with automatic format detection

**Supported Formats:**
- Text: UTF-8 with line pagination
- Excel: JSON 2D array
- PDF: Text extraction
- Images: Base64 or metadata
- Archives: Contents listing
- Video: Metadata

**Parameters:**
- `project` (string, required): Project ID
- `path` (string, required): File path (relative to project)
- `offset` (number, optional): Line offset (0-based)
- `length` (number, optional): Max lines to read
- `sheet` (string/number, optional): Excel sheet
- `range` (string, optional): Excel range (e.g., "A1:D10")

**Example:**
```typescript
// Read text file
pm_read_file({
  project: "my-app",
  path: "src/main.ts",
  offset: 0,
  length: 100
})

// Read Excel
pm_read_file({
  project: "my-app",
  path: "data.xlsx",
  sheet: "Sheet1",
  range: "A1:D100"
})

// Read image as Base64
pm_read_file({
  project: "my-app",
  path: "logo.png",
  imageMode: "base64"
})
```

---

### `pm_write_file`

**Purpose:** Write file with format handling

**Parameters:**
- `project` (string, required): Project ID
- `path` (string, required): File path
- `content` (string, required): File content
- `mode` (string, optional): "rewrite" or "append" (default: rewrite)

**Example:**
```typescript
// Write text (rewrite)
pm_write_file({
  project: "my-app",
  path: "src/config.ts",
  content: "export const API_URL = '...'",
  mode: "rewrite"
})

// Append to file
pm_write_file({
  project: "my-app",
  path: "logs/app.log",
  content: "New log entry\n",
  mode: "append"
})

// Write Excel (JSON → XLSX)
pm_write_file({
  project: "my-app",
  path: "data.xlsx",
  content: JSON.stringify([["Name", "Age"], ["Alice", 30]]),
  mode: "rewrite"
})
```

---

### `pm_search_files`

**Purpose:** Find files within project

**Parameters:**
- `project` (string, required): Project ID
- `pattern` (string, required): Search pattern (glob)
- `searchType` (string, optional): "files" or "content"

**Example:**
```typescript
// Find TypeScript files
pm_search_files({
  project: "my-app",
  pattern: "*.ts"
})

// Search file contents
pm_search_files({
  project: "my-app",
  pattern: "TODO",
  searchType: "content"
})
```

---

### `pm_batch_read`

**Purpose:** Read multiple files in one operation

**Parameters:**
- `project` (string, required): Project ID
- `paths` (array, required): Array of file paths

**Returns:** Array of file contents with metadata

**Example:**
```typescript
pm_batch_read({
  project: "my-app",
  paths: ["src/main.ts", "src/config.ts", "package.json"]
})
```

---

### `pm_list_files`

**Purpose:** List directory contents

**Parameters:**
- `project` (string, required): Project ID
- `path` (string, optional): Directory path (default: root)
- `recursive` (boolean, optional): Recursive listing

---

### `pm_get_file_info`

**Purpose:** Get file metadata including line counts

**Parameters:**
- `project` (string, required): Project ID
- `path` (string, required): File path

**Returns:**
- Size, dates, permissions
- Line count (for text files)
- Format-specific metadata

**Example:**
```typescript
pm_get_file_info({
  project: "my-app",
  path: "src/main.ts"
})

// Returns:
{
  size: 15000,
  createdAt: "2026-01-01T...",
  modifiedAt: "2026-01-07T...",
  textMetadata: {
    lineCount: 450,
    lastLine: 449,
    appendPosition: 450
  }
}
```

---

## Intelligence Features

**AI-powered semantic search and pattern recognition**

### `search_semantic`

**Purpose:** Find files by meaning using ONNX embeddings

**Parameters:**
- `project` (string, required): Project ID
- `query` (string, required): Natural language query
- `topN` (number, optional): Number of results (default: 10)

**Example:**
```typescript
search_semantic({
  project: "my-app",
  query: "authentication logic",
  topN: 5
})

// Returns:
[
  { path: "src/auth/jwt.ts", score: 0.92 },
  { path: "src/middleware/auth.ts", score: 0.87 },
  { path: "src/routes/login.ts", score: 0.81 }
]
```

---

### `suggest_patterns`

**Purpose:** Get cross-project solution patterns

**Parameters:**
- `currentProblem` (string, required): Problem description
- `limit` (number, optional): Max patterns (default: 5)

**Example:**
```typescript
suggest_patterns({
  currentProblem: "large markdown files slow to query",
  limit: 5
})

// Returns patterns from all projects with confidence scores
```

---

### `pm_index_files`

**Purpose:** Index files for semantic search

**Parameters:**
- `project` (string, required): Project ID
- `reindex` (boolean, optional): Force reindex

---

## Backlog Management

**EPIC tracking and project status monitoring**

### `query_backlog`

**Purpose:** List EPICs with filtering

**Parameters:**
- `project` (string, required): Project ID
- `status` (string, optional): Filter by status
- `priority` (string, optional): Filter by priority
- `limit` (number, optional): Max results

---

### `add_epic`

**Purpose:** Create new EPIC

**Parameters:**
- `project` (string, required): Project ID
- `title` (string, required): EPIC title
- `description` (string, optional): Description
- `priority` (string, optional): P0-P4
- `estimatedHours` (number, optional): Estimate

---

### `complete_epic`

**Purpose:** Mark EPIC as done

**Parameters:**
- `project` (string, required): Project ID
- `epicId` (number, required): EPIC ID
- `actualHours` (number, optional): Actual time

---

### `get_project_status`

**Purpose:** Get project overview

**Parameters:**
- `project` (string, required): Project ID

**Returns:** Total EPICs, status breakdown, time estimates

---

## Git Integration

**Smart commit generation with conventional format**

### `smart_commit`

**Purpose:** Auto-generate commit message

**Parameters:**
- `project` (string, required): Project ID
- `stagedFiles` (array, required): Files to commit
- `context` (string, optional): Additional context

**Example:**
```typescript
smart_commit({
  project: "my-app",
  stagedFiles: ["src/auth/jwt.ts", "src/auth/middleware.ts"],
  context: "Implemented JWT validation with refresh tokens"
})

// Generates:
"feat(auth): implement JWT validation with refresh tokens

- Add JWT validation middleware
- Implement token refresh mechanism
- Add RS256 signing
- Set 30min token expiry"
```

---

### `session_package`

**Purpose:** Package session for commit

**Parameters:**
- `project` (string, required): Project ID

**Returns:** Commit-ready package with message and files

---

## Research Capabilities

**Progressive research with citation tracking**

### `research_progressive`

**Purpose:** Stream research results

**Parameters:**
- `project` (string, required): Project ID
- `query` (string, required): Research query
- `streaming` (boolean, optional): Enable streaming

---

### `search_research`

**Purpose:** Search research history

**Parameters:**
- `project` (string, required): Project ID
- `query` (string, optional): Search query
- `limit` (number, optional): Max results

---

## Conversation Export

**Export Claude.ai conversation history**

### `chrome_export_status`

**Purpose:** Check Chrome readiness for export

**Returns:** Chrome installation and configuration status

---

### `chrome_export_setup`

**Purpose:** Get setup instructions

**Returns:** Step-by-step setup guide

---

### `chrome_export_conversations`

**Purpose:** Export conversations from Claude.ai

**Parameters:**
- `limit` (number, optional): Max conversations
- `outputPath` (string, optional): Output directory

---

## Process Control

**Interactive REPL and process management**

### `sys_start_process`

**Purpose:** Start process with smart detection

**Parameters:**
- `command` (string, required): Command to run
- `timeout_ms` (number, required): Max wait time
- `shell` (string, optional): Shell to use

**Example:**
```typescript
// Start Python REPL
sys_start_process({
  command: "python3 -i",
  timeout_ms: 30000
})

// Start Node REPL
sys_start_process({
  command: "node -i",
  timeout_ms: 30000
})
```

---

### `sys_interact_with_process`

**Purpose:** Send input to running process

**Parameters:**
- `pid` (number, required): Process ID
- `input` (string, required): Input to send
- `timeout_ms` (number, optional): Max wait (default: 8000)
- `wait_for_prompt` (boolean, optional): Auto-wait (default: true)

**Example:**
```typescript
// Load pandas
sys_interact_with_process({
  pid: 1234,
  input: "import pandas as pd"
})

// Read CSV
sys_interact_with_process({
  pid: 1234,
  input: "df = pd.read_csv('data.csv')"
})

// Analyze
sys_interact_with_process({
  pid: 1234,
  input: "print(df.describe())"
})
```

---

### `sys_read_process_output`

**Purpose:** Read process output with pagination

**Parameters:**
- `pid` (number, required): Process ID
- `offset` (number, optional): Line offset
- `length` (number, optional): Max lines
- `timeout_ms` (number, optional): Max wait

---

### `sys_list_sessions`

**Purpose:** List active process sessions

**Returns:** Array of sessions with PIDs and status

---

### `sys_list_processes`

**Purpose:** List system processes

**Returns:** System process list with PIDs

---

### `sys_kill_process`

**Purpose:** Terminate system process by PID

**Parameters:**
- `pid` (number, required): Process ID to kill

---

### `sys_force_terminate`

**Purpose:** Force terminate KERNL session

**Parameters:**
- `pid` (number, required): Session PID

---

## Advanced Search

**Background search with streaming results**

### `sys_start_search`

**Purpose:** Start background search

**Parameters:**
- `path` (string, required): Root path
- `pattern` (string, required): Search pattern
- `searchType` (string, optional): "files" or "content"
- `maxResults` (number, optional): Max results
- `timeout_ms` (number, optional): Search timeout

**Example:**
```typescript
// Search for files
sys_start_search({
  path: "D:/Projects",
  pattern: "*.ts",
  searchType: "files",
  maxResults: 100
})

// Search file contents
sys_start_search({
  path: "D:/Projects",
  pattern: "TODO",
  searchType: "content"
})
```

---

### `sys_get_more_search_results`

**Purpose:** Get search results with pagination

**Parameters:**
- `sessionId` (string, required): Search session ID
- `offset` (number, optional): Result offset
- `length` (number, optional): Max results

---

### `sys_stop_search`

**Purpose:** Stop active search

**Parameters:**
- `sessionId` (string, required): Search session ID

---

### `sys_list_searches`

**Purpose:** List active searches

**Returns:** Array of active search sessions

---

## System Files

**Low-level file system operations**

### `sys_copy_path`

**Purpose:** Copy files or directories

**Parameters:**
- `source` (string, required): Source path
- `dest` (string, required): Destination path
- `recursive` (boolean, optional): Recursive copy

---

### `sys_delete_path`

**Purpose:** Delete files or directories

**Parameters:**
- `path` (string, required): Path to delete
- `recursive` (boolean, optional): Recursive delete

---

### `sys_path_exists`

**Purpose:** Check if path exists

**Parameters:**
- `path` (string, required): Path to check

**Returns:** Boolean existence flag

---

### `sys_move_path`

**Purpose:** Move or rename

**Parameters:**
- `source` (string, required): Source path
- `dest` (string, required): Destination path

---

### `sys_create_directory`

**Purpose:** Create directory

**Parameters:**
- `path` (string, required): Directory path

---

## Configuration & Meta

**System configuration and introspection**

### `sys_get_config`

**Purpose:** Get KERNL configuration

**Returns:** Complete configuration object

**Example:**
```typescript
sys_get_config()

// Returns:
{
  version: "5.0.0",
  database: { path: "...", version: "1.0" },
  features: { crashRecovery: true, ... },
  limits: { maxFileSize: 10485760, ... },
  paths: { dataDir: "..." }
}
```

---

### `sys_set_config_value`

**Purpose:** Update configuration value

**Parameters:**
- `key` (string, required): Dot-notation key
- `value` (any, required): New value

**Example:**
```typescript
sys_set_config_value({
  key: 'features.semanticSearch',
  value: true
})

sys_set_config_value({
  key: 'limits.maxFileSize',
  value: 20971520  // 20MB
})
```

---

### `sys_get_usage_stats`

**Purpose:** Get tool usage analytics

**Returns:**
- Total calls per tool
- Success rates
- Average durations
- Top 10 tools
- Recent activity

---

### `sys_get_tool_info`

**Purpose:** Tool introspection and discovery

**Parameters:**
- `detailed` (boolean, optional): Include full details

**Returns:**
- Total tool count
- Category organization
- Tool descriptions (if detailed)

---

## Testing Suite

**Automated validation and health monitoring**

### `sys_run_tests`

**Purpose:** Run automated test suite

**Parameters:**
- `category` (string, optional): Test category
  - `smoke` - Quick validation (default)
  - `database` - SQLite tests
  - `filesystem` - File operation tests
  - `tools` - Tool handler tests
  - `config` - Configuration tests
  - `integration` - End-to-end tests
  - `all` - Complete suite
- `verbose` (boolean, optional): Detailed output

**Example:**
```typescript
// Quick smoke test
sys_run_tests({ category: 'smoke' })

// Full test suite with details
sys_run_tests({ category: 'all', verbose: true })
```

**Returns:**
- Total tests run
- Pass/fail counts
- Duration (ms)
- Individual results

---

### `sys_validate_tools`

**Purpose:** Validate all tool definitions

**Parameters:**
- `verbose` (boolean, optional): Detailed validation

**Returns:**
- Overall validity
- Error list
- Warning list
- Validation counts

**Example:**
```typescript
sys_validate_tools({ verbose: true })

// Returns:
{
  valid: true,
  totalTools: 75,
  errors: [],
  warnings: [],
  message: "All 75 tools are valid!"
}
```

---

### `sys_check_health`

**Purpose:** System health monitoring

**Parameters:**
- `quick` (boolean, optional): Quick check (skip deep tests)

**Returns:**
- Overall health status
- Individual check results
- Timestamp
- Cache status

**Example:**
```typescript
sys_check_health({ quick: false })

// Returns:
{
  healthy: true,
  checks: {
    database: { status: 'ok', message: 'Database operational (5 projects)' },
    memory: { status: 'ok', message: 'Memory usage: 50MB / 100MB (50%)' },
    tools: { status: 'ok', message: '75 tools registered' },
    process: { status: 'ok', message: 'Process uptime: 3600s' }
  },
  timestamp: '2026-01-07T...'
}
```

---

### `sys_benchmark`

**Purpose:** Performance benchmarking

**Parameters:**
- `operation` (string, optional): Operation to benchmark
  - `all` - All operations (default)
  - `database_write` - SQLite insert
  - `database_read` - SQLite select
  - `file_read` - File read
  - `file_write` - File write
  - `semantic_search` - Search performance
  - `tool_execution` - Handler performance
- `iterations` (number, optional): Iterations per test (default: 100)

**Example:**
```typescript
// Benchmark database writes
sys_benchmark({
  operation: 'database_write',
  iterations: 100
})

// Returns:
{
  totalTests: 1,
  results: [{
    operation: 'database_write',
    iterations: 100,
    avgDuration: 2.5,
    minDuration: 1.8,
    maxDuration: 4.2,
    opsPerSecond: 400
  }]
}
```

---

## Integration Tools

**Documentation generation and export**

### `sys_export_tools`

**Purpose:** Export tool registry to JSON

**Parameters:**
- `format` (string, optional): Export format
  - `full` - Complete definitions (default)
  - `summary` - Names, categories, descriptions
  - `schema` - JSON Schema only
  - `categories` - Grouped by category
- `output` (string, required): Output file path

**Example:**
```typescript
// Full export
sys_export_tools({
  format: 'full',
  output: 'D:/tools.json'
})

// Category-based export
sys_export_tools({
  format: 'categories',
  output: 'D:/tools-by-category.json'
})
```

---

### `sys_generate_docs`

**Purpose:** Auto-generate documentation

**Parameters:**
- `format` (string, optional): Documentation format
  - `markdown` - GitHub Markdown (default)
  - `html` - Standalone HTML
  - `json` - Structured JSON
- `output` (string, required): Output file path
- `includeExamples` (boolean, optional): Include examples (default: true)

**Example:**
```typescript
// Generate markdown docs
sys_generate_docs({
  format: 'markdown',
  output: 'D:/TOOLS.md',
  includeExamples: true
})

// Generate HTML docs
sys_generate_docs({
  format: 'html',
  output: 'D:/tools.html'
})
```

---

### `sys_get_version`

**Purpose:** Get version information

**Parameters:**
- `detailed` (boolean, optional): Include detailed info

**Returns:**
- Version number (5.0.0)
- Codename (V2.0)
- Tool count
- Feature flags (if detailed)
- Phase completion (if detailed)

**Example:**
```typescript
// Basic version
sys_get_version()

// Detailed with features
sys_get_version({ detailed: true })

// Returns:
{
  version: '5.0.0',
  codename: 'V2.0',
  toolCount: 75,
  features: {
    crashRecovery: true,
    semanticSearch: true,
    crossProjectLearning: true,
    systemControl: true,
    desktopCommanderParity: true
  },
  phases: { completed: 7, total: 7, progress: 100 }
}
```

---

## System Control

**Revolutionary desktop control features**

### `sys_edit_block`

**Purpose:** Surgical file editing with find/replace

**Parameters:**
- `file_path` (string, required): File to edit
- `old_string` (string, required): Text to find
- `new_string` (string, required): Replacement text
- `expected_replacements` (number, optional): Expected matches (default: 1)

**Example:**
```typescript
sys_edit_block({
  file_path: "D:/src/config.ts",
  old_string: "const API_URL = 'http://localhost'",
  new_string: "const API_URL = 'https://api.prod.com'",
  expected_replacements: 1
})
```

---

### `sys_write_pdf`

**Purpose:** Create or modify PDF files

**Parameters:**
- `path` (string, required): PDF path
- `content` (string | array, required): Markdown or operations
- `outputPath` (string, optional): Output path (for modifications)

**Example:**
```typescript
// Create PDF from markdown
sys_write_pdf({
  path: "D:/report.pdf",
  content: "# Report\n\nThis is the report content..."
})

// Modify existing PDF
sys_write_pdf({
  path: "D:/existing.pdf",
  outputPath: "D:/modified.pdf",
  content: [
    { type: "delete", pageIndexes: [0, 2] },
    { type: "insert", pageIndex: 1, markdown: "# New Page" }
  ]
})
```

---

### `sys_copy_file_user_to_claude`

**Purpose:** Copy file from user's computer to Claude's computer

**Parameters:**
- `path` (string, required): File path on user's computer

**Returns:** Path in Claude's filesystem

**Example:**
```typescript
// Copy large Excel file for processing
sys_copy_file_user_to_claude({
  path: "D:/user-data/large-dataset.xlsx"
})
// → File now in Claude's /mnt/user-data/uploads/
```

---

## Quick Reference

### Most Used Tools

**Session Management:**
```typescript
check_resume_needed({ project: "my-app" })
auto_checkpoint({ project: "my-app", operation: "...", progress: 0.5 })
mark_complete({ project: "my-app", summary: "..." })
```

**File Operations:**
```typescript
pm_read_file({ project: "my-app", path: "src/main.ts" })
pm_write_file({ project: "my-app", path: "src/config.ts", content: "..." })
pm_batch_read({ project: "my-app", paths: ["a.ts", "b.ts"] })
```

**Search:**
```typescript
search_semantic({ project: "my-app", query: "auth logic", topN: 5 })
sys_start_search({ path: "D:/", pattern: "*.ts", searchType: "files" })
```

**Process Control:**
```typescript
sys_start_process({ command: "python3 -i", timeout_ms: 30000 })
sys_interact_with_process({ pid: 1234, input: "import pandas" })
sys_read_process_output({ pid: 1234 })
```

**Testing & Health:**
```typescript
sys_run_tests({ category: 'smoke' })
sys_check_health({ quick: false })
sys_validate_tools({ verbose: true })
```

**Documentation:**
```typescript
sys_generate_docs({ format: 'markdown', output: 'D:/docs.md' })
sys_export_tools({ format: 'full', output: 'D:/tools.json' })
sys_get_version({ detailed: true })
```

---

## Best Practices

### Session Management
1. **Always** call `check_resume_needed` at start of session
2. **Checkpoint** every 5-10 tool calls during active work
3. **Mark complete** when task finishes
4. Include meaningful `decisions` and `nextSteps` in checkpoints

### File Operations
1. Use **batch operations** for multiple files
2. Use **pagination** (offset/length) for large files
3. Check **file info** first to see line counts
4. Use **semantic search** for discovery

### Process Management
1. Set appropriate **timeouts** (30s for REPLs)
2. Wait for **prompts** in interactive processes
3. Use **pagination** for large outputs
4. Always **terminate** when done

### Testing
1. Run **smoke tests** frequently
2. **Validate tools** after changes
3. **Check health** before major operations
4. **Benchmark** to establish baselines

---

## Troubleshooting

### Common Issues

**Session not resuming:**
- Check if `mark_complete` was called
- Verify database connectivity
- Run `sys_check_health`

**Semantic search not working:**
- Check if files are indexed: `pm_index_status`
- Reindex if needed: `pm_index_files({ reindex: true })`
- Verify ONNX model loaded

**Process not responding:**
- Check if still running: `sys_list_sessions`
- Increase timeout
- Try `sys_force_terminate` if hung

**Performance issues:**
- Run `sys_benchmark` to identify bottleneck
- Check `sys_get_usage_stats` for hot paths
- Run `sys_check_health` for resource issues

---

**KERNL V2.0 Tool Reference**  
**Complete! 75 tools documented**  
**Last updated: January 7, 2026**