@kishlay42/moth-ai 1.0.1

package/dist/ui/components/FlameLogo.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+// Palette mapping: Character -> { color: Hex, symbol: Char }
+const PALETTE = {
+    // Deep Blue / Background blend
+    '1': { color: '#0f20a2', char: '░' },
+    // Outer Blue
+    '2': { color: '#0020ef', char: '▒' },
+    // Mid Blue
+    '3': { color: '#002dff', char: '▓' },
+    // Bright Blue
+    '4': { color: '#0088af', char: '█' },
+    // Cyan
+    '5': { color: '#00c7f7', char: '█' },
+    // Light Cyan
+    '6': { color: '#00ffff', char: '█' },
+    // White Core
+    '7': { color: '#ffffff', char: '█' },
+};
+const HD_FLAME_ART = [
+    "             333             ",
+    "           2333332           ",
+    "          233444332          ",
+    "        2334555554332        ",
+    "       234556666655432       ",
+    "      34567777777776543      ",
+    "     2456777777777776542     ",
+    "    235677766666667776532    ",
+    "    345677655555556776543    ",
+    "   23456765444444456765432   ",
+    "   23455654333333345655432   ",
+    "   12344543222222234544321   ",
+    "   11233432111111123433211   "
+];
+export const FlameLogo = () => {
+    return (_jsx(Box, { flexDirection: "column", marginRight: 2, children: HD_FLAME_ART.map((row, rowIndex) => (_jsx(Box, { children: row.split('').map((char, colIndex) => {
+                const pixel = PALETTE[char];
+                return (_jsx(Text, { color: pixel?.color || undefined, children: pixel ? pixel.char : ' ' }, `${rowIndex}-${colIndex}`));
+            }) }, rowIndex))) }));
+};

package/dist/ui/components/WordFlame.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text } from 'ink';
+import BigText from 'ink-big-text';
+export const WordFlame = ({ text, big = false }) => {
+    if (big) {
+        return (_jsx(Text, { color: "#3EA0C3", children: _jsx(BigText, { text: text, font: "block", colors: ['#0192e5', '#0192e5'] }) }) // BigText needs specific handling or Text wrapper
+        );
+    }
+    return (_jsx(Text, { color: "#0192e5", children: text }));
+};

package/dist/ui/components/WordMoth.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text } from 'ink';
+import BigText from 'ink-big-text';
+export const WordMoth = ({ text, big = false }) => {
+    if (big) {
+        return (_jsx(Text, { color: "#3EA0C3", children: _jsx(BigText, { text: text, font: "block", colors: ['#0192e5', '#0192e5'] }) }) // BigText needs specific handling or Text wrapper
+        );
+    }
+    return (_jsx(Text, { color: "#0192e5", children: text }));
+};

package/dist/ui/wizards/LLMRemover.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text, useInput, Newline, useApp } from 'ink';
+import { removeProfile, saveConfig } from '../../config/configManager.js';
+import { deleteApiKey } from '../../config/keychain.js';
+export const LLMRemover = ({ config: initialConfig, onExit }) => {
+    const { exit } = useApp();
+    const [localConfig, setLocalConfig] = useState(initialConfig);
+    const [selectionIndex, setSelectionIndex] = useState(0);
+    const [message, setMessage] = useState('');
+    const [confirming, setConfirming] = useState(null);
+    useInput(async (input, key) => {
+        // Escape or Ctrl+C/X to exit
+        if (key.escape || (key.ctrl && (input === 'c' || input === 'x'))) {
+            onExit();
+            return;
+        }
+        if (localConfig.profiles.length === 0) {
+            return;
+        }
+        // Navigation
+        if (key.upArrow) {
+            setSelectionIndex(prev => (prev - 1 + localConfig.profiles.length) % localConfig.profiles.length);
+            return;
+        }
+        if (key.downArrow) {
+            setSelectionIndex(prev => (prev + 1) % localConfig.profiles.length);
+            return;
+        }
+        const selectedProfile = localConfig.profiles[selectionIndex];
+        // Confirmation Mode
+        if (confirming) {
+            if (key.return || input.toLowerCase() === 'y') {
+                // Do the delete
+                const nameToRemove = selectedProfile.name;
+                let newConfig = removeProfile(localConfig, nameToRemove);
+                await deleteApiKey(nameToRemove); // Helper needs to be imported or mocked if not in configManager? It's in keychain.ts actually. 
+                // Wait, removeProfile in configManager does cleaner logic but key deletion is separate usually? 
+                // Checking imports... "deleteApiKey" is in keychain.ts.
+                // I need to import it.
+                saveConfig(newConfig);
+                setLocalConfig(newConfig);
+                setConfirming(null);
+                setMessage(`Profile '${nameToRemove}' removed.`);
+                setSelectionIndex(0);
+                setTimeout(() => setMessage(''), 3000);
+            }
+            else if (input.toLowerCase() === 'n' || key.escape) {
+                setConfirming(null);
+            }
+            return;
+        }
+        // Trigger Delete
+        if (key.return || key.delete || key.backspace) {
+            setConfirming(selectedProfile.name);
+        }
+    });
+    // Need to fix imports for deleteApiKey which is in keychain, not configManager. 
+    // I will assume I can import it from '../../config/keychain.js'.
+    if (localConfig.profiles.length === 0) {
+        return (_jsxs(Box, { flexDirection: "column", padding: 1, borderStyle: "round", borderColor: "red", children: [_jsx(Text, { color: "red", children: "No profiles found." }), _jsx(Text, { children: "Use \"moth llm add\" to create one." })] }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, borderStyle: "round", borderColor: "red", children: [_jsx(Text, { bold: true, color: "red", children: "MOTH LLM REMOVER" }), _jsx(Text, { color: "yellow", children: "Hint: Select profile and press Enter to delete." }), _jsx(Newline, {}), confirming ? (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "red", padding: 1, children: [_jsx(Text, { bold: true, color: "white", backgroundColor: "red", children: " WARNING " }), _jsx(Text, { children: "Are you sure you want to permanently delete profile:" }), _jsxs(Text, { bold: true, children: ["'", confirming, "'?"] }), _jsx(Newline, {}), _jsx(Text, { bold: true, children: "[Y] Yes, Delete   [N] No, Cancel" })] })) : (localConfig.profiles.map((p, i) => {
+                const isSelected = i === selectionIndex;
+                const isActive = p.name === localConfig.activeProfile;
+                return (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: isSelected ? "red" : undefined, bold: isSelected, children: isSelected ? "❯ " : "  " }), _jsx(Text, { bold: isActive, color: isActive ? "green" : (isSelected ? "red" : undefined), children: p.name }), _jsxs(Text, { children: [" (", p.provider, " / ", p.model, ")"] }), isActive && _jsx(Text, { color: "green", dimColor: true, children: " (active)" })] }, i));
+            })), message && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "red", children: message }) }))] }));
+};

package/dist/ui/wizards/LLMWizard.js

@@ -0,0 +1,149 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { Box, Text, useInput } from 'ink';
+import SelectInput from 'ink-select-input';
+import TextInput from 'ink-text-input';
+// 1. Model Families
+const FAMILIES = [
+    { label: 'GPT (OpenAI)', value: 'gpt' },
+    { label: 'Claude (Anthropic)', value: 'claude' },
+    { label: 'Gemini (Google)', value: 'gemini' },
+    { label: 'LLaMA (Meta)', value: 'llama' },
+    { label: 'Mistral', value: 'mistral' },
+    { label: 'Qwen', value: 'qwen' },
+    { label: 'Phi', value: 'phi' },
+    { label: 'DeepSeek', value: 'deepseek' },
+    { label: 'Other / Custom', value: 'custom' },
+];
+// 2. Deployment Types
+const DEPLOYMENTS = [
+    { label: 'Local (On my machine)', value: 'local' },
+    { label: 'Cloud (Hosted API)', value: 'cloud' },
+];
+// Suggested models per family
+const FAMILY_MODELS = {
+    'gpt': ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'gpt-3.5-turbo'],
+    'claude': ['claude-3-5-sonnet-20240620', 'claude-3-opus-20240229', 'claude-3-haiku-20240307'],
+    'gemini': ['gemini-1.5-pro', 'gemini-1.5-flash', 'gemini-1.0-pro'],
+    'llama': ['llama3.1', 'llama3', 'llama2'],
+    'mistral': ['mistral', 'mixtral', 'codestral'],
+    'qwen': ['qwen2.5', 'qwen2'],
+    'phi': ['phi3.5', 'phi3'],
+    'deepseek': ['deepseek-coder-v2', 'deepseek-chat'],
+};
+export const LLMWizard = ({ onComplete, onCancel }) => {
+    const [step, setStep] = useState(1);
+    const [family, setFamily] = useState('');
+    const [deployment, setDeployment] = useState('');
+    const [model, setModel] = useState('');
+    const [isCustomModel, setIsCustomModel] = useState(false);
+    const [apiKey, setApiKey] = useState('');
+    const [baseUrl, setBaseUrl] = useState('');
+    // Resolution State
+    const [resolvedRuntime, setResolvedRuntime] = useState({ provider: 'openai-compatible', requiresKey: true, requiresUrl: false });
+    // --- STEP 1: FAMILY ---
+    const handleFamilySelect = (item) => {
+        setFamily(item.value);
+        setStep(2);
+    };
+    // --- STEP 2: DEPLOYMENT ---
+    const handleDeploymentSelect = (item) => {
+        const deployType = item.value;
+        setDeployment(deployType);
+        resolveRuntime(family, deployType);
+    };
+    const resolveRuntime = (fam, deploy) => {
+        // LOGIC RESOLUTION
+        if (deploy === 'local') {
+            setResolvedRuntime({
+                provider: 'ollama',
+                defaultBaseUrl: 'http://localhost:11434/v1',
+                requiresKey: false,
+                requiresUrl: false // Implicitly handles URL usually, or we can confirm it
+            });
+        }
+        else {
+            // CLOUD
+            if (fam === 'gemini') {
+                setResolvedRuntime({ provider: 'gemini-native', requiresKey: true, requiresUrl: false });
+            }
+            else if (fam === 'claude') {
+                setResolvedRuntime({ provider: 'claude-native', requiresKey: true, requiresUrl: false });
+            }
+            else if (fam === 'gpt') {
+                // OpenAI standard
+                setResolvedRuntime({ provider: 'openai-compatible', requiresKey: true, requiresUrl: false });
+            }
+            else {
+                // LLaMA, Mistral, etc on Cloud -> Generic OpenAI Compatible (Groq, etc)
+                setResolvedRuntime({ provider: 'openai-compatible', requiresKey: true, requiresUrl: true });
+            }
+        }
+        setStep(3);
+    };
+    // --- STEP 3: MODEL VARIANT ---
+    const handleModelSelect = (item) => {
+        if (item.value === 'custom') {
+            setIsCustomModel(true);
+            setModel('');
+        }
+        else {
+            setModel(item.value);
+            setStep(4);
+        }
+    };
+    const handleCustomModelSubmit = (val) => {
+        setModel(val);
+        setStep(4);
+    };
+    // --- STEP 4: AUTH / CREDENTIALS ---
+    // This step might be split if we need both Key and URL.
+    // Let's do Key first, then URL if needed.
+    const [subStep, setSubStep] = useState('key');
+    useEffect(() => {
+        if (step === 4) {
+            if (resolvedRuntime.requiresKey) {
+                setSubStep('key');
+            }
+            else if (resolvedRuntime.requiresUrl) {
+                setSubStep('url');
+            }
+            else {
+                // Nothing needed
+                setStep(5);
+            }
+        }
+    }, [step, resolvedRuntime]);
+    const handleKeySubmit = (val) => {
+        setApiKey(val);
+        if (resolvedRuntime.requiresUrl) {
+            setSubStep('url');
+        }
+        else {
+            setStep(5);
+        }
+    };
+    const handleUrlSubmit = (val) => {
+        setBaseUrl(val);
+        setStep(5);
+    };
+    // --- STEP 5: CONFIRM ---
+    useInput((input, key) => {
+        if (step === 5 && key.return) {
+            onComplete({
+                name: `${family}-${model}`.replace(/[^a-zA-Z0-9-_]/g, '-').toLowerCase(),
+                provider: resolvedRuntime.provider,
+                model: model,
+                apiKey: apiKey || undefined,
+                baseUrl: baseUrl || resolvedRuntime.defaultBaseUrl || undefined
+            });
+        }
+        if (input === 'c' && key.ctrl) {
+            onCancel();
+        }
+    });
+    // RENDER HELPERS
+    const modelItems = (FAMILY_MODELS[family] || []).map(m => ({ label: m, value: m }));
+    modelItems.push({ label: 'Type Custom Model Name...', value: 'custom' });
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, borderStyle: "round", borderColor: "magenta", width: 65, children: [_jsx(Text, { bold: true, color: "magenta", children: "\uD83D\uDD25 MOTH MODEL WIZARD" }), _jsx(Text, { color: "gray", children: "--------------------------------------------------" }), step === 1 && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "cyan", children: "STEP 1: SELECT MODEL FAMILY" }), _jsx(Box, { marginTop: 1, children: _jsx(SelectInput, { items: FAMILIES, onSelect: handleFamilySelect }) })] })), step === 2 && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "cyan", children: "STEP 2: SELECT DEPLOYMENT" }), _jsxs(Text, { color: "gray", children: ["Where will ", family, " run?"] }), _jsx(Box, { marginTop: 1, children: _jsx(SelectInput, { items: DEPLOYMENTS, onSelect: handleDeploymentSelect }) })] })), step === 3 && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "cyan", children: "STEP 3: SELECT MODEL VARIANT" }), _jsxs(Text, { color: "gray", children: ["Runtime: ", resolvedRuntime.provider, " (", deployment, ")"] }), isCustomModel ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { children: "Enter specific model name:" }), _jsx(TextInput, { value: model, onChange: setModel, onSubmit: handleCustomModelSubmit })] })) : (_jsx(Box, { marginTop: 1, children: _jsx(SelectInput, { items: modelItems, onSelect: handleModelSelect }) }))] })), step === 4 && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "cyan", children: "STEP 4: CREDENTIALS" }), subStep === 'key' && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { children: ["Enter API Key for ", family, " (", deployment, "):"] }), _jsx(TextInput, { value: apiKey, onChange: setApiKey, onSubmit: handleKeySubmit, mask: "*" })] })), subStep === 'url' && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { children: "Enter Base URL endpoint:" }), _jsx(TextInput, { value: baseUrl, onChange: setBaseUrl, onSubmit: handleUrlSubmit, placeholder: "https://api.groq.com/openai/v1" })] }))] })), step === 5 && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "green", children: "STEP 5: CONFIRM RESOLUTION" }), _jsxs(Box, { marginTop: 1, flexDirection: "column", borderStyle: "single", padding: 1, borderColor: "white", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Family:" }), "     ", family] }), _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Deployment:" }), " ", deployment] }), _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Runtime:" }), "    ", resolvedRuntime.provider] }), _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Model:" }), "      ", model] }), _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Auth:" }), "       ", apiKey ? '(Provided)' : '(None)'] }), _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Endpoint:" }), "   ", baseUrl || resolvedRuntime.defaultBaseUrl || '(Default)'] })] }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "green", bold: true, children: "Press [ENTER] to save configuration." }), _jsx(Text, { color: "red", children: "Press [Ctrl+C] to cancel." })] })] }))] }));
+};

package/dist/utils/paths.js

@@ -0,0 +1,22 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+export const CONFIG_DIR = path.join(os.homedir(), '.moth');
+export function ensureConfigDir() {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+export function findProjectRoot(cwd = process.cwd()) {
+    let currentDir = cwd;
+    while (true) {
+        if (fs.existsSync(path.join(currentDir, 'package.json')) || fs.existsSync(path.join(currentDir, '.git'))) {
+            return currentDir;
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}

package/dist/utils/text.js

@@ -0,0 +1,49 @@
+export function levenshtein(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    // increment along the first column of each row
+    let i;
+    for (i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    // increment each column in the first row
+    let j;
+    for (j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    // Fill in the rest of the matrix
+    for (i = 1; i <= b.length; i++) {
+        for (j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) == a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                Math.min(matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j] + 1 // deletion
+                ));
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+export function findClosestCommand(input, commands) {
+    let closest = null;
+    let minDistance = Infinity;
+    for (const cmd of commands) {
+        const distance = levenshtein(input, cmd);
+        if (distance < minDistance) {
+            minDistance = distance;
+            closest = cmd;
+        }
+    }
+    // Threshold: allow max distance of 2 for words len > 3, else 1
+    const threshold = input.length > 3 ? 2 : 1;
+    if (minDistance <= threshold) {
+        return closest;
+    }
+    return null;
+}

package/docs/architecture.md

@@ -0,0 +1,63 @@
+# System Architecture
+
+## Overview
+Moth is a local, LLM-agnostic code intelligence CLI. It acts as an orchestrator between the user, the filesystem, and various LLM providers.
+
+## High-Level Architecture
+
+```mermaid
+graph TD
+    User[User] -->|Commands/Prompts| CLI[CLI Entry Point (index.ts)]
+    CLI --> UI[UI Layer (Ink)]
+    CLI --> Config[Config Manager]
+    UI --> App[App Component]
+    App --> Orch[Agent Orchestrator]
+    Orch --> Tools[Tool Registry]
+    Orch --> LLM[LLM Client]
+    
+    subgraph Core Logic
+    Orch
+    Tools
+    end
+    
+    subgraph Infrastructure
+    Config
+    LLM
+    FS[File System]
+    end
+    
+    Tools --> FS
+    LLM -->|API Calls| Cloud[Cloud Providers (OpenAI/Gemini/Claude)]
+    LLM -->|Local| Local[Ollama/LocalHost]
+```
+
+## Component Interaction
+
+### Chat Session Flow
+1.  **Initialization**: `startChatSession()` in `index.ts` loads configuration and mounts the `App` component.
+2.  **Input**: User types a prompt.
+3.  **App State**: `App.tsx` captures the input and appends it to the `messages` history.
+4.  **Orchestration**: `App.tsx` calls `orchestrator.run(prompt, history)`.
+5.  **Agent Loop**:
+    *   **System Prompt**: Constructed with available tools.
+    *   **LLM Call**: History + System Prompt + User Prompt sent to LLM.
+    *   **Reasoning**: LLM returns a JSON `AgentStep` (Thought + ToolCall/FinalAnswer).
+    *   **Execution**: If ToolCall, `ToolRegistry` executes the tool (e.g., `write_to_file`).
+    *   **Recursion**: Output is fed back to LLM until `finalAnswer` is reached.
+6.  **Render**: `App.tsx` updates the UI with the stream or final result.
+
+### LLM Provider Resolution
+The system uses a **Model-First** pattern to resolve providers:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Wizard
+    participant Config
+    
+    User->>Wizard: Select Family (e.g. LLaMA)
+    User->>Wizard: Select Deployment (Local)
+    Wizard->>Config: Resolve to 'ollama' provider
+    Wizard->>Config: Set URL to 'http://127.0.0.1:11434'
+    Wizard->>User: Confirm "Runtime: Ollama"
+```

package/docs/core_logic.md

@@ -0,0 +1,53 @@
+# Core Logic Modules
+
+## Agent Orchestrator (`src/agent/orchestrator.ts`)
+
+The `AgentOrchestrator` is the brain of Moth. It implements a ReAct-style loop to solve user tasks.
+
+### Key Responsibilities
+-   **Conversation History**: It maintains `messages` state (User/Assistant), providing short-term memory.
+-   **Tool Execution**: It parses LLM responses and executes tools via `ToolRegistry`.
+-   **Loop Management**: It manages the `maxSteps` loop to prevent infinite recursion.
+
+### Code Snippet: Memory Injection
+```typescript
+// src/agent/orchestrator.ts
+async *run(prompt: string, history: LLMMessage[] = []): AsyncGenerator<AgentStep, string, unknown> {
+    // ...
+    const messages: LLMMessage[] = [
+        { role: 'user', content: systemPrompt },
+        ...history, // <--- Injection of past context
+        { role: 'user', content: currentPrompt }
+    ];
+    // ...
+}
+```
+
+## Context Management (`src/context`)
+
+Moth uses a proactive context system to understand the user's project.
+
+### Project Scanner (`src/context/scanner.ts`)
+-   **Function**: Scans the current directory to identify project types (Node.js, Python, C++, etc.).
+-   **Heuristics**: Checks for marker files (`package.json`, `requirements.txt`, `CMakeLists.txt`).
+
+## Configuration Manager (`src/config/configManager.ts`)
+
+The config manager handles persistent state, including LLM profiles.
+
+### Data Structure
+```typescript
+interface ActiveConfig {
+    activeProfile: string;
+    profiles: Record<string, LLMProfile>;
+}
+
+interface LLMProfile {
+    name: string;
+    provider: 'ollama' | 'openai-compatible' | 'gemini-native' | ...;
+    model: string;
+    apiBase?: string;
+    apiKeyLoc?: string; // Pointer to keychain, not the key itself
+}
+```
+-   **Security**: API keys are NEVER stored in `config.json`. They are managed via the system keychain (or mock implementation).

package/docs/index.md

@@ -0,0 +1,30 @@
+# Moth Documentation 📜
+
+Welcome to the comprehensive documentation for Moth, the Model-First Code Intelligence CLI.
+
+## Table of Contents
+
+### 1. [System Architecture](./architecture.md)
+*   High-Level Overview
+*   Mermaid Diagrams (System & Workflows)
+*   Interaction Flows
+
+### 2. [Core Logic](./core_logic.md)
+*   **Orchestrator**: The ReAct Agent Brain.
+*   **Context**: How Moth analyzes your project.
+*   **Config**: State management and security.
+
+### 3. [UI Components](./ui_components.md)
+*   **Ink Architecture**: React-based TUI.
+*   **Wizards**: Interactive setup flows.
+*   **Components**: Reusable UI elements.
+
+### 4. [LLM Integration](./llm_integration.md)
+*   **Factory Pattern**: Dynamic client creation.
+*   **Adapters**: OpenAI, Gemini, Claude, Ollama.
+*   **Model-First Design**: Resolution logic.
+
+## Quick Links
+
+*   [Implementation Plan](../.gemini/antigravity/brain/0989b9c8-1bda-4a68-b9de-08e5d9c71f0f/implementation_plan.md) (Internal Planning)
+*   [Walkthrough](../.gemini/antigravity/brain/0989b9c8-1bda-4a68-b9de-08e5d9c71f0f/walkthrough.md) (User Guide)

package/docs/llm_integration.md

@@ -0,0 +1,49 @@
+# LLM Integration (`src/llm`)
+
+Moth routes all model interactions through a unified adapter layer.
+
+## Factory Pattern (`src/llm/factory.ts`)
+
+The `createLLMClient` function instantiates the correct adapter based on the configuration.
+
+```typescript
+export const createLLMClient = (config: ActiveConfig): LLMClient => {
+    switch (config.provider) {
+        case 'ollama':
+        case 'openai-compatible':
+            return new OpenAIAdapter(...);
+        case 'gemini-native':
+            return new GeminiAdapter(...);
+        case 'claude-native':
+            return new ClaudeAdapter(...);
+        // ...
+    }
+}
+```
+
+## Adapter Interface (`src/llm/types.ts`)
+
+All adapters must implement the `LLMClient` interface.
+
+```typescript
+export interface LLMClient {
+    chat(messages: LLMMessage[]): Promise<string>;
+    chatStream(messages: LLMMessage[]): AsyncGenerator<string, void, unknown>;
+}
+```
+
+## Supported Providers
+
+### OpenAI Compatible (`src/llm/openAIAdapter.ts`)
+-   **Usage**: Used for OpenAI, Ollama, vLLM, DeepSeek, generic endpoints.
+-   **Configuration**: Requires `apiBase` (URL) and optionally `apiKey`.
+-   **Ollama Special Case**: Uses `http://127.0.0.1:11434/v1` as default base.
+
+### Gemini Native (`src/llm/geminiAdapter.ts`)
+-   **Usage**: Google Gemini API.
+-   **Library**: Uses `@google/generative-ai` SDK.
+-   **Safety**: Configures safety settings to BLOCK_NONE for coding tasks.
+
+### Claude Native (`src/llm/claudeAdapter.ts`)
+-   **Usage**: Anthropic Claude API.
+-   **Library**: Uses `@anthropic-ai/sdk`.

package/docs/ui_components.md

@@ -0,0 +1,44 @@
+# UI Components (`src/ui`)
+
+Moth uses [React Ink](https://github.com/vadimdemedes/ink) to render a Terminal User Interface (TUI).
+
+## Main Application (`src/ui/App.tsx`)
+
+The `App` component acts as the main view controller.
+
+### Features
+-   **Chat Interface**: Renders a scrollable list of messages using `flexDirection="column"`.
+-   **Input Handling**: Captures user keystrokes for chat and control signals (Pause/Resume).
+-   **Permission Queue**: Intercepts tool execution requests and displays a "Permission Required" overlay.
+
+```tsx
+// Structure of the App component
+<Box flexDirection="column">
+    <Header />
+    <MessageList messages={messages} />
+    {pendingPermission && <PermissionOverlay request={pendingPermission} />}
+    <InputArea isProcessing={isProcessing} />
+</Box>
+```
+
+## Wizards
+
+Wizards are self-contained interactive components used for configuration.
+
+### LLM Add Wizard (`src/ui/wizards/LLMWizard.tsx`)
+Implements the **Model-First** setup flow.
+1.  **Family Selection**: Selects model family (LLaMA, GPT, etc.).
+2.  **Deployment Selection**: Local vs Cloud.
+3.  **Credential Entry**: Conditional rendering of input fields.
+4.  **Confirmation**: Final summary view.
+
+### LLM Remove Wizard (`src/ui/wizards/LLMRemover.tsx`)
+-   Displays a list of profiles.
+-   Uses styled selection (Green for active, Red for deletion target).
+-   Requires explicit 'y' confirmation to prevent accidents.
+
+## Utilities
+
+### WordMoth (`src/ui/components/WordMoth.tsx`)
+-   Renders the "MOTH" ascii art header.
+-   Supports gradient coloring (Blue/Cyan theme).