npm run build      # Compiles src/ → dist/ with sourcemaps
npm run typecheck  # Validates types without emitting (tsc --noEmit)
npm run lint       # ESLint static analysis

// index.ts
export function main(context: PluginContext) {
  // 1. Register config schematics (UI toggles)
  context.withConfigSchematics(configSchematics);
  
  // 2. Register prompt preprocessor (Document RAG + ContextGuard)
  context.withPromptPreprocessor(preprocess);
  
  // 3. Register tools provider (all registered categories based on config)
  context.withToolsProvider(toolsProvider);
  
  // 4. Setup cleanup handlers
  process.on('SIGTERM', cleanupBrowserSession);
  process.on('SIGINT', cleanupBrowserSession);
}

toolsProvider() called by LM Studio SDK
    │
    ▼
createToolsProvider(config, stateManager, bgCommandManager)
    │
    ├── StateManager(config) ──────► Load state from disk
    ├── BackgroundCommandManager ──► Initialize process tracker
    └── Declarative Registry Pattern (v1.8.2+):
            │
            ├── TOOL_REGISTRIES array (20 entries, closure-based)
            │   ├── Each entry captures dependencies at definition time
            │   ├── Single for...of loop iterates all entries
            │   └── Config key gating + GOD MODE bypass
            │
            ├── registerFileSystemTools()      ──► 23 tools (enabled by default, incl. pattern_scan)
            ├── registerWebResearchTools()     ──► 3 tools (enabled by default)
            ├── registerGitTools()             ──► 15 tools (disabled by default)
            ├── registerBrowserTools()         ──► 5 tools (disabled by default)
            ├── registerDatabaseTools()        ──► 1 tool (disabled by default)
            ├── registerDocumentTools()        ──► 1 tool (enabled by default)
            ├── registerBackgroundCommandTools() ─► 3 tools (disabled by default)
            ├── registerImageProcessingTools() ─► 4 tools (enabled by default)
            ├── registerHttpClientTools()      ──► 3 tools (disabled by default)
            ├── registerRagTools()             ──► 7 tools (enabled by default: rag_index_files/pdf/docx/xlsx, rag_query_vector, rag_clear_index, rag_web_content — since v1.9.2/v1.9.10)
            ├── registerUiGenerationTools()    ──► 3 tools (disabled by default)
            ├── registerContextManagementTools() ─► 12 tools (enabled by default)
            ├── registerTextProcessingTools()  ──► 4 tools (enabled by default)
            ├── registerRefactorCodeTools()    ──► 2 tools (enabled by default)
            ├── registerExecutionTools()       ──► 5 tools (mixed defaults)
            │
            ▼
        Return Tool[] to SDK ──► **131 unique tools** registered across 24 modules (configurable per user)

Session Activity Occurs
    │
    ▼
auto_summarize_context() called
    │
    ├── Analyze tool usage patterns
    ├── Detect configuration changes
    ├── Identify important decisions
    └── Generate summary
    
    ▼
ContextStorageManager.addEntry(entry)
    │
    ├── Load existing entries from .ai_toolbox_memory.msgpack (Working Dir → Plugin Root fallback)
    ├── Apply default scope: 'global' (v1.9.1+) unless explicitly specified
    ├── Set TTL for session-scoped entries: 24h (v1.9.1+)
    ├── Increment frequency counter on existing entries with matching ID
    ├── Append new entry to beginning of array
    ├── Limit to 1000 entries (prevent unbounded growth)
    └── Save atomically (temp file + rename)

    ▼
Persistent Storage (.ai_toolbox_memory.msgpack)
    │
    ├── get_context_memory(limit, type?) → Retrieve recent entries
    │   ├── Prune expired session entries (TTL check: 24h threshold, v1.9.1+)
    │   ├── Apply heuristic scoring: Recency(70%) + Frequency(30%) sort
    │   └── Return top N scored entries
    │
    ├── search_context(query, maxResults) → Text-based search
    │   ├── Prune expired session entries (v1.9.1+)
    │   ├── Filter by title/content/tags match
    │   ├── Apply heuristic scoring to results
    │   └── Return top N scored matches
    │
    ├── context_summary() → Statistics & counts
    └── delete_context_entry(id) → Remove specific entry

Session Activity Occurs
    │
    ▼
auto_summarize_context() called
    │
    ├── Analyze tool usage patterns
    ├── Detect configuration changes
    ├── Identify important decisions
    └── Generate summary
    
    ▼
ContextStorageManager.addEntry(entry)
    │
    ├── Load existing entries from .ai_toolbox_memory.msgpack → .session_context/.ai_toolbox_memory.msgpack
    ├── Append new entry to beginning of array
    ├── Limit to 1000 entries (prevent unbounded growth)
    └── Save atomically (temp file + rename)
    
    ▼
Persistent Storage (.ai_toolbox_memory.msgpack)
    │
    ├── get_context_memory() → Retrieve recent entries
    ├── search_context(query) → Text-based search
    ├── context_summary() → Statistics & counts
    └── delete_context_entry(id) → Remove specific entry

// Simplified registration pattern (actual implementation uses closure-based registry)
export async function toolsProvider(ctl: ToolsProviderController): Promise<Tool[]> {
  const pluginConfig = ctl.getPluginConfig(configSchematics);
  
  // Construct typed PluginConfig from .get() calls
  const config: PluginConfig = { /* ... */ };

  // Initialize managers (singleton pattern)
  if (!stateManager) stateManager = new StateManager(config);
  if (!backgroundCommandManager) backgroundCommandManager = new BackgroundCommandManager(config);

  const tools: Tool[] = [];

  // --- Declarative Registry Definition (v1.8.2+) ---
  const TOOL_REGISTRIES: ToolRegistryEntry[] = [
    { key: 'fileSystem', register: () => registerFileSystemTools(config, stateManager) },
    { key: 'webSearch', register: () => registerWebResearchTools(config) },
    // ... 18 more entries (20 total)
  ];

  // --- Registry Loop (replaces ~80 lines of if/else blocks) ---
  for (const entry of TOOL_REGISTRIES) {
    if (config[entry.key] || isGodMode) {
      tools.push(...entry.register());
    }
  }

  return tools;
}

class StateManager {
  private state: Map<string, StateEntry>;
  private maxSize: number;
  private persistenceEnabled: boolean;
  private memoryFile!: string; // Resolved at runtime
  
  set(key, value): void         // In-memory + async disk write
  get<T>(key): T | undefined    // In-memory retrieval
  delete(key): boolean          // In-memory + async disk update
  getAllKeys(): Promise<string[]> // Waits for initialization
  clear(): void                 // Resets in-memory state
}

// save_session_summary writes:
await stateManager.set(`${summaryId}_data`, compressed); // Base64-encoded gzip stream < 10k chars
await stateManager.set(`${summaryId}_timestamp`, Date.now());

// get_session_summary reads with backward-compatible fallback:
const keys = await stateManager.getAllKeys(); // Waits for loadFromFile(), returns all keys
const compressedData = stateManager.get(summaryKey);

try {
  const decompressed = zlib.gunzipSync(Buffer.from(compressedData, 'base64')).toString('utf-8');
  sessionSummary = JSON.parse(decompressed); // New format (v1.5.15+)
} catch (parseErr) {
  // Fallback for legacy uncompressed summaries (pre-v1.5.15)
  if (typeof compressedData === 'string' && compressedData.startsWith('{')) {
    try {
      sessionSummary = JSON.parse(compressedData); // Legacy format
    } catch (legacyErr) {
      throw new Error(`Legacy summary parsing failed: ${String(legacyErr)}`);
    }
  } else {
    throw parseErr; // Corrupted or unknown format
  }
}

export type MemoryScope = 'global' | 'project' | 'session';

class ContextStorageManager {
  private storagePath: string; // .ai_toolbox_memory.msgpack
  
  load(): Promise<ContextEntry[]>
  save(entries: ContextEntry[]): Promise<void>
  addEntry(entry: ContextEntry): Promise<void>              // Applies default scope + TTL
  getRecentEntries(limit, type?): Promise<ContextEntry[]>   // Heuristic scoring applied
  searchEntries(query, maxResults): Promise<ContextEntry[]>  // Heuristic scoring applied
  deleteEntry(id): Promise<boolean>
  clearAll(): Promise<void>
  getSummary(): Promise<ContextSummary>
  pruneExpiredSessionEntries(): Promise<number>              // TTL pruning (v1.9.1+)
}

interface ContextEntry {
  id: string;
  timestamp: number;
  date: string;
  type: 'decision' | 'pattern' | 'configuration' | 'file_change' | 'error' | 'summary';
  title: string;
  content: string;
  tags?: string[];
  scope?: MemoryScope;     // NEW (v1.9.1): Context isolation
  frequency?: number;      // NEW (v1.9.1): Access count for scoring
  ttl_ms?: number;         // NEW (v1.9.1): Expiration threshold
}

// Recency Decay: Exponential decay based on age (lambda = 1 day)
const recencyFactor = Math.exp(-ageMs / (24 * 60 * 60 * 1000));

// Frequency Saturation: Prevents infinite bias toward frequently accessed entries
const frequencyFactor = freq / (freq + 5);

// Weighted composite score
return (recencyFactor * 0.7) + (frequencyFactor * 0.3);

Input → Path Validation → Binary Detection → Command Sanitization → SQL Validation
         (validatePath)    (isBinaryFile)     (sanitizeCommand)      (validateSQLQuery)

let currentWorkingDir: string = BASE_DIR;

getWorkingDir(): string
setWorkingDir(newDir: string): boolean
resetWorkingDir(): void
resolvePath(userPath: string): string
getAllowedBases(): string[]

// former src/tools/gatewayTools.ts (REMOVED from codebase 24.08; shown for historical reference)
export async function getGatewayTools(
  provider: ToolsProvider, 
  config: PluginConfig
): Promise<Tool[]> {
  const exploreTools = tool({
    name: 'explore_tools',
    description: 'Discover available tools and their categories...',
    parameters: { category: z.string().optional() },
    implementation: async (params) => {
      await provider.getAvailableTools(); // Ensure registry loaded
      return { success: true, categories: [...] }; // Returns category names only
    }
  });

  const executeGatewayTool = tool({
    name: 'execute_gateway_tool',
    description: 'Executes a specific tool by its name...',
    parameters: { 
      toolName: z.string(),
      arguments: z.record(z.unknown())
    },
    implementation: async (params) => {
      return await provider.executeTool(params.toolName, params.arguments); // Delegates to registry
    }
  });

  return [exploreTools, executeGatewayTool];
}

User Message → AI calls explore_tools(category="fileSystem") 
             → Returns: { success: true, categories: ["read_file", "write_file", ...] }
             → AI decides to use read_file
             → AI calls execute_gateway_tool(toolName="read_file", arguments={file_name: "example.txt"})
             → Gateway delegates to provider.executeTool("read_file", args)
             → Tool executes with full validation, security checks, error handling

User Path Input
    │
    ├── Empty check ────────────────► Reject
    │
    ├── UNC path check (\\\) ──────► Reject
    │
    ├── Relative path?
    │   │
    │   ├── Yes: Resolve against basePath
    │   │         │
    │   │         ├── Within base? ───► Allow
    │   │         └── Outside base? ──► Reject
    │   │
    │   └── No (absolute):
    │         │
    │         ├── In allowed bases? ──► Allow
    │         └── Outside allowed? ───► Reject

Command String
    │
    ▼
Layer 1: Dangerous Pattern Blocking
    │
    ├── Null byte injection ─────────► Reject
    ├── IFS tampering ───────────────► Reject
    ├── Dangerous patterns (rm -rf, sudo, etc.) ─► Reject
    ├── Too many pipes (>2) ─────────► Reject
    ├── Multiple semicolons (>1) ─────► Reject
    ├── Command substitution ($(), ``) ─► Reject
    ├── Environment modification ─────► Reject
    │
    ▼
Layer 2: Tool-Category Enforcement
    │
    ├── classifyCommand() → Set<string>
    │       │
    │       ├── git * / api.github.com → 'gitOperations'
    │       ├── duckduckgo / google / bing → 'webSearch'
    │       ├── puppeteer / playwright / chromium → 'browserAutomation'
    │       ├── sqlite3 / mysql / psql → 'databaseQueries'
    │       ├── curl / wget / http → 'httpClient'
    │       └── nohup / disown / & → 'backgroundCommands'
    │       │
    │       ▼
    │   Check against config toggles
    │       │
    │       ├── Category disabled + !godMode ─► Reject
    │       └── Category enabled or godMode ──► Allow
    │
    ▼
    Allow Execution

JavaScript Code
    │
    ├── require() detection ─────────► Reject
    ├── eval() detection ────────────► Reject
    ├── fs/child_process access ─────► Reject
    ├── Function constructor ────────► Reject
    ├── Dynamic import() ────────────► Reject
    └── __proto__ access ────────────► Reject

// Stops calculating if minimum possible score drops below threshold
function levenshteinSimilarity(a: string, b: string, minScore: number): number | null {
  // Quick rejection for very different lengths
  if (lenDiff / maxLen > (1 - minScore)) return null;
  
  // Two-row optimization (saves memory vs full matrix)
  // Early exit when row minimum exceeds threshold
}

// Concurrency-controlled batch processing
async function findFilesAsync(dirPath, pattern, maxDepth, concurrencyLimit = 4) {
  // Process directories in batches
  for (const batch of batches) {
    await Promise.all(batch.map(dir => searchDir(dir, depth + 1)));
  }
}

regex-mode directory scan:
  phase 1  searchCandidates(ripgrepEngine.ts) — awaited BEFORE scan start (cost outside the 15 s deadline window)
             exit 0 → allow-set of rg-named candidate files (relativized against targetDir; RC-D fix)
             exit 1 → no matches (clean negative; set stays null → full-JS walk runs anyway, byte-for-byte fallback)
             exit 2 / import failure / WASI error → { status:'fallback-required', reason } (e.g. Rust-dialect parse
                      errors: lookarounds/backreferences) → same full-JS fallback, all hang guards intact
  phase 2  existing walkDirectory/processFile pipeline on the candidate set only: per-file stat + size gate FIRST
             (exact-byte skip records), line-cap probe read for non-named files (RC-E fix: byte-identical
             skipped_files contract), then unchanged processWithRegex shaping

User Message
    │
    ▼
promptPreprocessor()
    │
    ├── Check temporalAwareness config
    │   │
    │   └── Enabled?
    │       │
    │       ├── Yes: Get cached datetime (5min TTL)
    │       │         │
    │       │         ├── Format: Standard ([Zeit: ...]) or HEUTE IST Mode
    │       │         │
    │       │         └── Append timestamp to message end
    │       │
    │       └── No: Skip
    │
    ▼
Final Prompt sent to LLM (with timestamp suffix)

User Message Arrives → Step 0: Attachments + Checkpoint Suffix
    │
    ▼
Step 0.5: ContextGuard Token Counting & Auto-Tracker Threshold Check
    │
    ├── Count tokens via History Text Length × 0.25 (+10% buffer)
    ├── autoTracker.checkAndGeneratePrompt() → threshold warning if ≥75% used
    └── Inject checkpointSuffix into all return paths (unified injection)
    │
    ▼
Step 0.6: Auto-Tracker Checkpoint Reply Handling + Message Analysis
    │
    ├── Detect "YES"/"NO" (or German "JA"/"NEIN") reply to pending checkpoint prompt → flush/save memory
    ├── Analyze message for tracking triggers (decisions, completions, errors)
    └── Buffer actions for later flush at next threshold checkpoint
    │
    ▼
Step 0.7: Project Keyword Detection ← NEW (v1.9.8+)
    │
    ├── Read project_registry.json from disk
    ├── Extract candidate words from user message (filter stop-words)
    ├── Match against registered projects with fuzzy normalization (hyphen↔underscore)
    └── If matched → Inject "⚠️ REGISTERED PROJECT DETECTED" confirm-first banner
    │   (Does NOT change CWD this turn; one-shot switch only after an explicit YES/JA reply in a later message)
    │
    ▼
Step 1: Directory Path Detection ← Unchanged
    │
    ├── Detect Windows/Unix/Relative paths in message
    └── If found → Inject "WORKING DIRECTORY DETECTED" confirmation prompt
    │
    ▼
Step 2: Document RAG (if enabled)
            │
            ├── Yes: Load embedding model
            │         │
            │         ├── Process files → chunks
            │         │
            │         ├── Semantic retrieval
            │         │
            │         ├── Filter by affinity threshold
            │         │
            │         └── Inject relevant chunks into prompt
            │
            └── No: Pass through unchanged

browser_open_page(url)
    │
    ▼
BrowserSessionManager.getBrowser()
    │
    ├── Browser exists & connected? ───► Reuse
    │
    └── No: Launch new Puppeteer instance
            │
            ├── Retry with exponential backoff (max 2)
            │
            └── Reset inactivity timer (5 min)
            │
            ▼
        Navigate to URL
            │
            ├── Wait for selector (optional)
            │
            ├── Take screenshot (optional)
            │
            └── Extract text content

Session Activity Detected
    │
    ▼
auto_summarize_context(sessionEvents, configChanges)
    │
    ├── Analyze tool usage patterns (>3 uses = frequent pattern)
    ├── Track configuration changes
    ├── Identify important decisions
    └── Generate session summary
    
    ▼
ContextStorageManager.addEntry(entry)
    │
    ├── Load existing entries from .ai_toolbox_memory.msgpack
    ├── Prepend new entry to array
    ├── Enforce 1000-entry limit
    └── Atomic save (temp file + rename)
    
    ▼
Persistent Storage (.ai_toolbox_memory.msgpack)
    │
    ├── get_context_memory(limit, type?) → Retrieve entries
    ├── search_context(query, maxResults) → Text-based search
    ├── context_summary() → Statistics & counts
    └── delete_context_entry(id) / clearContextMemory(confirm) → Management

User calls get_session_summary() or get_memory()
    │
    ▼
1️⃣ Check Working Directory File:
   {current_working_dir}/.session_context/.ai_toolbox_memory.msgpack
    │
    ├── Found? Decode msgpack → Return ✅ (Local-first hit)
    │
    └── Missing/Empty/Corrupt? Continue...
        │
        ▼
2️⃣ Check Plugin Root File:
   {plugin_root}/.session_context/.ai_toolbox_memory.msgpack
    │
    ├── Found? Decode msgpack → Return ⚠️ (Fallback hit)
    │
    └── Missing/Empty/Corrupt? Continue...
        │
        ▼
3️⃣ Check In-Memory State (RAM):
   stateManager.get('session_summary_latest') or memory_* keys
    │
    ├── Found? Return ⚠️ (Last resort)
    └── Not found? Return ❌ error

User Message Arrives → Step 0.5: ContextGuard Token Counting
    │
    ├── autoTracker.checkAndGeneratePrompt(tokenCount, maxTokens):
    │   ├─ Calculate usagePercentage = (effectiveTokens / maxTokens) * 100
    │   ├─ Compare against threshold (default: 75%)
    │   └─ If >= threshold → Generate warning + FSM: IDLE → THRESHOLD_REACHED
    │
    ▼
Warning injected into user message prompt:
⚠️ SESSION WARNING: You have reached {usage}% of your token limit...

User replies "YES" (German "JA" normalized) → Step 0.6: Checkpoint Reply Detection
    │
    ├── autoTracker.hasPendingWarning()? YES ✓
    ├── replyMatch === 'YES'? YES ✓
    ├── autoTracker.processUserReply('YES') → FSM: THRESHOLD_REACHED → CONFIRMED
    └── autoTracker.checkAndSaveTokenThreshold():
        ├─ flushActionsToMemory() → Save buffered decisions/completions/errors
        └─ autoSaveSessionMemory() → Create checkpoint entry with token stats

User replies "NO" (German "NEIN" normalized) → Step 0.6: Checkpoint Reply Detection
    │
    ├── autoTracker.hasPendingWarning()? YES ✓
    ├── replyMatch === 'NO'? YES ✓
    └── autoTracker.processUserReply('NO') → FSM: THRESHOLD_REACHED → DECLINED → IDLE (reset)

tool result → tokenStatsManager.recordToolResult()
    ├── measures payload size → running mid-loop delta for this turn
    └── logs [AutoTracker] [DELTA] … | chat used ≈ N tok
        where N = turnBaselineTokens (TokenCheck baseline at turn start) + midLoopEstTokens

next preprocess()/threshold evaluation
    └── compares against historyCount + running deltas (FIX #20),
        so 75% / 90% triggers fire inside long multi-tool turns, not only between messages

User Message Arrives
    │
    ▼
promptPreprocessor()
    │
    ├── Check contextGuardEnabled config
    │   │
    │   └── Enabled?
    │       │
    │       ├── Yes: Count tokens in history
    │       │         │
    │       │         ├── Below 90% threshold? ──► Skip compression
    │       │         │
    │       │         └── Above 90% threshold?
    │       │                 │
    │       │                 ▼
    │       │             compressHistory(messages)
    │       │                 │
    │       │                 ├── Identify messages to compress (all except last 10)
    │       │                 ├── Send to summary model
    │       │                 │   └── Use contextGuardSummaryModel or current chat model
    │       │                 │
    │       │                 ├── Generate summary with preserved file paths/names
    │       │                 │
    │       │                 ├── Calculate tokens saved
    │       │                 │
    │       │                 └── Inject visual indicator:
    │       │                         │
    │       │                         ├── 🧠 Emoji header
    │       │                         ├── Messages compressed count
    │       │                         ├── Tokens before → after (e.g., "~85k → ~42k")
    │       │                         ├── Percentage saved (e.g., "Saved ~43,000 tokens (~51%)")
    │       │                         ├── Timestamp
    │       │                         └── Visual separator lines
    │       │
    │       └── No: Skip ContextGuard processing
    │
    ▼
Final Prompt sent to LLM (with or without compression indicator)

🧠 **ContextGuard Compression Active**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Compressed 15 message(s) into summary
• Tokens before: ~85k → after: ~42k
• **Saved ~43,000 tokens (~51%)**
• Timestamp: 19:15:32
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

### CONTEXT SUMMARY (from 15 messages)
[Summary content here...]

User Message Arrives (ContextGuard Enabled)
    │
    ▼
promptPreprocessor() → Native History API Iteration
    │
    ├── history.getLength() — Get message count
    ├── For each message i from 0 to length-1:
    │   ├── msg = history.at(i) — Retrieve message by index
    │   ├── msg.getText() — Extract text content via getter method
    │   ├── msg.getToolCallRequests() — Serialize tool calls if present
    │   └── msg.getToolCallResults() — Serialize tool results if present
    │
    ▼
contextGuard.countTokens(messages, imageCount, modelId, systemPrompt, historyTextLength)
    │
    ├── PRIMARY METHOD: History Text Length × 0.25 ratio (v1.8.8+) — effective ~0.275 with +10% buffer
    │   ├── If historyTextLength provided from native API iteration:
    │   │         │
    │   │         ├── primaryTokenCount = Math.ceil(historyTextLength * 0.25)
    │   │         ├── Add image tokens if applicable (+500 per image)
    │   │         └── Return totalTokens ← ✅ Matches LM Studio sidebar exactly
    │   │
    │   └── Verified at ~130K tokens for 544,578 chars — <0.5% deviation from sidebar
    │
    └── VERIFIED at ~130K tokens for 544,578 chars — <0.3% deviation from sidebar (improved from <0.5%)
    ├── FALLBACK: SDK-native countTokens() × calibration (if history unavailable)
    │   ├── Format messages into prompt string
    │   ├── Call model.countTokens(promptString) via LM Studio SDK
    │   └── Apply TOKEN_SCALING_FACTOR = 65 for overhead compensation ← ⚠️ Legacy fallback
    │
    ▼
Threshold Check: totalTokens >= tokenLimit * 0.9?
    │
    ├── Yes: compressHistory(messages) → Uses History Text Length × 0.24 for compressedPreview too
    └── No: Skip compression

index.ts
├── toolsProvider.ts
│   ├── config.ts
│   ├── stateManager.ts
│   ├── backgroundCommands.ts
│   └── tools/*.ts (15 registered modules)
│       ├── security.ts (shared)
│       ├── workingDir.ts (shared)
│       └── performanceUtils.ts (shared)
├── config.ts
└── promptPreprocessor.ts
    └── config.ts

ConfigSchema (Zod)
├── Tool Gating (13 booleans)
├── Execution Tools (4 booleans)
├── Search Settings (3 fields)
├── Browser Settings (2 fields)
├── Git Settings (2 fields)
├── Document RAG (3 fields)
├── Security Settings (4 fields)
├── State Management (2 fields)
├── i18n (1 field)
├── Notifications (1 field)
├── Temporal Awareness (2 fields: temporalAwareness, dateFormatStyle)
└── ContextGuard (6 fields): v1.4.2
    ├── contextGuardEnabled (boolean) — Master toggle
    ├── contextGuardTokenLimit (number 1K-200K) — Compression threshold
    ├── contextGuardSmartReading (boolean) — Keyword-based file reading
    ├── contextGuardSummaryModel (string) — Dedicated summary model name
    ├── contextGuardTerminalFilterEnabled (boolean) — Terminal output filtering
    └── contextGuardTerminalFilterLength (number 100-20K) — Max terminal chars

src/
├── index.ts                    # Plugin entry point
├── toolsProvider.ts            # Tool registration (conditional config gating)
├── config.ts                   # Zod schema + UI schematics
├── security.ts                 # Path/SQL/command validators
├── stateManager.ts             # Persistent state management
├── workingDir.ts               # Working directory manager
├── performanceUtils.ts         # Caching, async search, Levenshtein
├── promptPreprocessor.ts       # Document RAG + ContextGuard integration
├── backgroundCommands.ts       # Background process manager
├── fuzzySearch.ts              # Fuzzy file search implementation
├── locales/                    # i18n translation files
│   ├── en.ts
│   ├── de.ts
│   ├── zh-CN.ts
│   └── zh-TW.ts
├── tools/                      # Tool category modules (30 source files)
│   ├── fileSystemTools.ts      # File system operations (23 tools — REGISTERED, incl. pattern_scan)
│   ├── patternScan.ts          # pattern_scan search engine (clean-room module, ReDoS-gated; tool registered in fileSystemTools.ts)
│   ├── webResearchTools.ts     # Web research & search (3 tools — REGISTERED; rag_web_content served by vectorRagTools.ts since v1.9.10)
│   ├── browserAutomationTools.ts # Browser automation (5 tools — REGISTERED)
│   ├── gitGithubTools.ts       # Git local ops + GitHub API (15 tools — REGISTERED)
│   ├── databaseTools.ts        # Database queries (1 tool — REGISTERED)
│   ├── documentTools.ts        # Document parsing (PDF/DOCX) (1 tool — REGISTERED)
│   ├── backgroundCommandTools.ts # Background process management (3 tools — REGISTERED)
│   ├── executionTools.ts       # Code execution JS/Python/Terminal (5 tools — REGISTERED)
│   ├── utilityTools.ts         # Utility tools (~25 tools — REGISTERED under 'utility' toggle)
│   ├── imageProcessingTools.ts # Image processing & OCR (4 tools — REGISTERED)
│   ├── httpClientTools.ts      # HTTP client operations (3 tools — REGISTERED)
│   ├── vectorRagTools.ts       # Vector RAG semantic search (7 tools — REGISTERED: rag_index_files, rag_index_pdf, rag_index_docx, rag_index_xlsx, rag_query_vector, rag_clear_index, rag_web_content)
│   ├── textProcessingTools.ts  # Text transformation (4 tools — REGISTERED)
│   ├── uiGenerationTools.ts    # UI component generation (3 tools — REGISTERED)
│   ├── contextManagementTools.ts # Context management & tracking (12 tools — REGISTERED)
│   ├── refactorCodeTools.ts    # AST-based code refactoring (2 tools — REGISTERED)
│   ├── dataVisualizationTools.ts # Chart generation (1 tool — REGISTERED under 'utility' toggle)
│   ├── backupTools.ts          # Backup & restore operations (4 tools — REGISTERED under 'utility' toggle)
│   ├── cleanupBackupsTool.ts   # Cleanup backups utility (1 tool — REGISTERED under 'utility' toggle)
│   ├── lineOperations.ts       # Line-level text operations (1 tool — REGISTERED under 'utility' toggle)
│   ├── taskPlanningTools.ts    # Task planning & execution tracking (3 tools — REGISTERED)
│   ├── markdownPreviewTools.ts # Markdown preview generation (1 tool — REGISTERED under 'utility' toggle)
│   ├── fileModTracker.ts       # File modification tracker (REGISTERED)
│   ├── # networkToolsRegistry.ts — REMOVED 24.08 (was an orphan file with zero imports; deletion was tracked backlog since v1.9.3 and completed in the rag_web_content fix suite)
│   ├── toolPriority.ts         # Cluster-aware tool priority ranking (REGISTERED)
│   ├── # backupUtils.ts / executionRegistry.ts / toolProtocolWarnings.ts / utilityRegistry.ts — REMOVED 01.09.2026 (Tier-1 dead code: zero referencers; see CHANGELOG_v2.md entry ~18:30)
│   └── restoreFromBak.ts       # Backup restoration utility (REGISTERED)
│   ├── attachmentManager.ts    # Attachment handling & management (REGISTERED)
│   ├── browserActions.ts       # Browser action execution & validation (REGISTERED)
│   ├── findLMStudioHome.ts     # LM Studio home directory detection & fallback (REGISTERED)
│   ├── lmStudioApi.ts          # LM Studio REST API integration layer (REGISTERED)
│   └── tokenStatsManager.ts    # Token statistics tracking & management (REGISTERED)
└── types/                      # Type definitions
    ├── dom-augment.d.ts        # DOM type augmentations for browser automation
    ├── node-notifier.d.ts      # Node.js notifier type declarations
    └── types.d.ts              # Core shared type definitions

tests/                          # Jest test suite (25 suites)
├── security.test.ts            # Core security validation tests
├── security.edge-cases.test.ts # Security boundary & edge case testing
├── config.test.ts              # Zod schema + UI schematics validation
├── stateManager.test.ts        # Persistence, path resolution, atomic writes
├── fileSystemTools.test.ts     # File system operation tests (23 tools, incl. pattern_scan)
├── webResearchTools.test.ts    # Multi-engine search & fetch tests
├── browserAutomationTools.test.ts # Puppeteer session management tests
├── gitGithubTools.test.ts      # Git local ops + GitHub API tests
├── databaseTools.test.ts       # SQLite query validation tests
├── executionTools.test.ts      # JS/Python/Terminal sandboxed execution tests
├── utilityTools.test.ts        # Utility tools (backup, chart, line ops) tests
├── backgroundCommands.test.ts  # Background process management tests
├── toolsProvider.test.ts       # Declarative registry pattern integration tests
├── performanceUtils.test.ts    # Caching, async search, Levenshtein tests
├── fuzzySearch.test.ts         # Fuzzy file search similarity scoring tests
├── workingDir.test.ts          # Working directory manager path resolution tests
├── findLMStudioHome.test.ts    # LM Studio home detection & fallback tests
├── i18n.test.ts                # Translation file loading & formatting tests
├── autoTracker.test.ts         # Token threshold checkpointing & session memory tests (v1.6.6+)
├── browserActions.test.ts      # Browser action execution & validation tests
├── fileSearch.test.ts          # Recursive file search with exclusion patterns tests
├── grep_files.test.ts          # Regex/Literal matching, ReDoS protection, performance tests
├── refactorCodeTools.test.ts   # AST-based refactoring & dry-run diff tests (v1.5.30+)
├── hubExclusionClustering.test.ts # Hub-exclusion clustering algorithm verification (83 tests) — NEW v1.9.8
└── projectAutoDetect.test.ts   # Project auto-detection & registration workflow tests — NEW v1.9.8

src/tools/recodeTool/
├── rules/
│   ├── unusedImports.ts              ← Tier 1: Implemented ✅ (extracted from refactorCodeTools.ts) — the only live rule as of 01.09.2026
│   └── # deadCodeDetection / modulePathNormalization / typeInference / asyncModernizer — REMOVED 01.09.2026 (Tier-1 dead code: never wired into any tool operation; see CHANGELOG_v2.md entry ~18:30)
├── recodeEngine.ts           ← AST transformation orchestrator with dry-run diff support (LCS-based)
└── recodeTypes.ts            ← Shared interfaces & schemas (RuleContext, RuleResult, RecodeRule)

export type Confidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';

interface ToolResultMetadata {
  confidence: Confidence;        // EXTRACTED (deterministic), INFERRED (semantic), AMBIGUOUS (uncertain)
  provenance?: string;           // e.g., "file:src/utils.ts L42", "rag_query_vector"
  note?: string;                 // Additional context for confidence assessment
}

// Helper functions
function determineConfidence(operationType, success, fallbackUsed): Confidence;
function createToolResult<T>(data: T, confidence: Confidence, options?): { success: true; data: T & ToolResultMetadata };
function createErrorResult(message: string, provenance?): { success: false; error: string; data: ToolResultMetadata };

Build Dependency Graph → Calculate Degrees → Identify Hubs (80th percentile) → Create Non-Hub Subgraph → Louvain Community Detection → Majority-Vote Hub Reattachment → Cluster Density & Modularity Calculation

function buildDependencyGraph(sourceDirs: string[]): Map<string, Set<string>>;
function addEdge(adjacency, source, target): void;
function calculateDegrees(adjacency): Map<string, number>;
function identifyHubs(degrees, hubThresholdPercentile = 80): Set<string>;
function louvainCommunityDetection(adjacency): Map<string, number>;
function reattachHubsByMajorityVote(hubs, adjacency, nonHubCommunities): Record<string, number>;
function calculateClusterDensity(members, adjacency): number;
function calculateModularity(edges, nodeDegrees, clusterAssignments): number;
function performHubExclusionClustering(adjacency, hubThresholdPercentile = 80): HubExclusionResult;
function analyzeAiToolboxDependencies(): HubExclusionResult;