docs: add comprehensive architecture, gpu scaling, integration, skeptic, and replay guides

Author: anujsingh-cse

docs/architecture.md

@@ -0,0 +1,63 @@
+# 🏗️ Architecture Guide
+
+GhostCoder operates as a decentralized, event-driven assistant running entirely locally. It bridges the gap between your workspace (IDE/Editor), your terminal (Shell), and local Large Language Models (via Ollama) without requiring any cloud APIs or external telemetry.
+
+```mermaid
+graph TD
+    subgraph Client / Environment
+        Shell[Shell Hooks: Bash/Zsh]
+        Editor[Editor Plugins: Neovim/VSCode]
+    end
+
+    subgraph GhostCoder Daemon
+        IPC[IPC Server: Unix Socket / TCP]
+        Observer[Workspace Watcher: Watchdog]
+        Session[Session Tracker: JSON DB]
+        Brain[Ghost Brain Router]
+        Skeptic[Ghost Skeptic Validator]
+        ModelMgr[Model Manager]
+    end
+
+    subgraph Local LLM Provider
+        Ollama[Ollama API]
+    end
+
+    Shell -->|Command Pre/Post Events| IPC
+    Editor -->|Cursor/Editor Changes| IPC
+    Observer -->|File Write Events| Session
+    IPC -->|Trigger Action| Brain
+    Brain -->|Route to Specialist Agent| ModelMgr
+    ModelMgr -->|classification/generation| Ollama
+    ModelMgr -->|adversarial check| Skeptic
+    Skeptic -->|JSON challenge| Ollama
+    Brain -->|Return approved hint/fix| IPC
+    IPC -->|Push Inline Hint| Editor
+```
+
+---
+
+## 📡 The Daemon & IPC Protocol
+The background daemon (`ghostcoder start`) starts an asynchronous server. By default, it attempts to bind to a Unix Domain Socket at `~/.ghostcoder/ghostcoder.sock`. If running on an unsupported platform or environment, it falls back to a local loopback TCP port (`48673`).
+
+### Core IPC Message Schema
+Clients (IDE plugins, shell wrappers) exchange JSON payloads terminated by newlines (`\n`):
+
+*   **`editor_change`**: Sent by the IDE on cursor movement or document modification. Contains file paths, active lines, and raw buffer contents.
+*   **`command_pre` / `command_post`**: Sent by shell hook scripts when a terminal command is run and when it finishes (capturing status codes and stderr output).
+*   **`status_request`**: Queried by the CLI to retrieve active VRAM consumption, GPU tier metrics, loaded models, and stack definitions.
+*   **`reload_config`**: Used by the CLI client to notify a running daemon of configuration changes, triggering hot-swapping of models.
+
+---
+
+## 🧠 Ghost Brain Routing
+When an event (like a command failure or code edit matching a structural vulnerability) is sent to the daemon, the **Ghost Brain Router** resolves the context:
+
+1.  **Tech Stack Detection**: It inspects file extensions and manifests to identify project technologies (e.g., Node.js, Python, Rust).
+2.  **Specialist Agent Selection**: The classification model routes the situation to the most relevant engineering specialist (e.g., `agency-application-security-engineer`, `agency-devops-automator`, or `agency-senior-developer`).
+3.  **Prompt Assembly**: The system prompt is dynamically assembled from the selected agent's instructions.
+4.  **Generation & Skeptic Validation**: The suggestion is produced by the Coder model and validated by the Ghost Skeptic before being returned to the IDE.
+
+---
+
+## 💾 Session Tracker & Replay DB
+All events, raw error messages, model prompts, and user interactions (apply, dismiss) are logged to a local JSON database at `~/.ghostcoder/sessions/`. This transaction log serves as the single source of truth for replay automation and explanation commands.

docs/gpu_scaling.md

@@ -0,0 +1,55 @@
+# ⚡ GPU Scaling & Model Presets Guide
+
+GhostCoder features a dynamic **GPU Auto-Scaling engine** that auto-detects your local GPU hardware VRAM capacity and automatically loads the largest compatible models.
+
+---
+
+## 📟 GPU Tier System
+When the daemon initializes, it parses `nvidia-smi` (or platform equivalents) to estimate VRAM availability and assigns a hardware profile:
+
+| Profile Tier | VRAM Capacity | Max Model Size | Classifier Model | Coder Model | Reasoner Model | Skeptic Model |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **`entry`** | < 6 GB | 3B params | `qwen2.5:0.5b` | `qwen2.5-coder:1.5b` | `qwen2.5-coder:1.5b` | `qwen2.5:0.5b` |
+| **`mid`** | 6 - 12 GB | 7B params | `qwen2.5:0.5b` | `qwen2.5-coder:7b` | `qwen2.5-coder:7b` | `qwen2.5:0.5b` |
+| **`high`** | 12 - 20 GB | 14B params | `qwen2.5:0.5b` | `qwen2.5-coder:14b` | `deepseek-coder:6.7b` | `qwen2.5:3b` |
+| **`workstation`** | 20 - 48 GB | 32B params | `qwen2.5:3b` | `qwen2.5-coder:32b` | `deepseek-coder:33b` | `qwen2.5:7b` |
+| **`datacenter`** | >= 48 GB | 72B param+ | `qwen2.5:7b` | `qwen2.5-coder:72b` | `deepseek-coder:33b` | `qwen2.5:14b` |
+
+---
+
+## 💾 Memory Allocations & Keep-Alive Lifecycle
+To operate seamlessly alongside other user processes, GhostCoder implements strict VRAM management:
+
+1.  **VRAM Limit**: The maximum memory allowed for models is calculated as `min(Total_VRAM * 85%, Total_VRAM - Headroom)`. The default safety headroom is `500 MB`.
+2.  **Continuous Classifier**: The fast classifier model is loaded permanently with `keep_alive = -1`.
+3.  **On-Demand Coder**: The heavier Coder model is loaded only when generating a suggestion.
+4.  **Auto-Unload Guard**: When loading the Coder model would violate the VRAM budget limit, GhostCoder automatically triggers an eviction command to unload any other active models from Ollama memory (`keep_alive = 0`). Once idle for `30 seconds`, the Coder model is automatically unloaded to free VRAM.
+
+---
+
+## ⚙️ Hardware Overrides & Hot-Swapping
+
+### Project and Global Configuration File
+You can override hardware-detected defaults using global or local YAML configurations:
+- **Global**: `~/.ghostcoder/config.yaml`
+- **Per-Project**: `.ghostcoder/config.yml` in your project root.
+
+```yaml
+# Override config.yaml example
+gpu_tier: workstation
+model_coder: deepseek-coder:33b
+vram_headroom_mb: 1000
+```
+
+### CLI Overrides
+Configure settings directly from the terminal. If the background daemon is running, it will be notified and hot-swap its models immediately:
+```bash
+# Force a mid-range GPU tier profile
+ghostcoder config --gpu-tier mid
+
+# Customize the code generation model
+ghostcoder config --model-coder deepseek-coder:6.7b
+
+# View active GPU metrics and configuration
+ghostcoder status
+```

docs/integrations.md

@@ -0,0 +1,70 @@
+# 🔌 Shell & Editor Integrations
+
+GhostCoder hooks directly into your shell session and your editor via an asynchronous IPC broker, providing zero-latency assistance as you work.
+
+---
+
+## 🐚 Shell Hook Setup
+
+During initialization (`ghostcoder init`), shell scripts are configured to hook into your prompt lifecycle.
+
+### How it works
+The scripts define command hook wrappers (`preexec` and `precmd` equivalents):
+- **`command_pre`**: Triggered before a command starts execution. It alerts the daemon to temporarily pause editor file watches or prepare context.
+- **`command_post`**: Triggered immediately after a command finishes. It captures:
+  - Command exit status code.
+  - Errors from `stderr`.
+  - Directory stack info.
+
+If a command fails (exit code > 0), the wrapper sends a payload to the daemon over TCP/Unix sockets.
+
+---
+
+## 💤 Neovim Integration
+
+The Neovim plugin hooks into editor events using autocmd rules.
+
+### Installation
+Add the following template to your Neovim configurations (`init.lua` or your plugin manager directory):
+
+```lua
+-- lazy.nvim Example
+{
+  "anujsingh-cse/GhostCoder",
+  event = { "BufReadPost", "BufNewFile" },
+  config = function()
+    local gc = require("ghostcoder")
+    gc.setup({
+      socket_path = "~/.ghostcoder/ghostcoder.sock",
+      enable_inline_virtual_text = true,
+      highlight_groups = {
+        suggestion = "Comment",
+        warning = "DiagnosticWarn"
+      }
+    })
+  end
+}
+```
+
+### Event Listeners
+- **CursorHold / CursorMoved**: Periodically reports active file path and cursor line position to the daemon.
+- **TextChanged / TextChangedI**: Notifies the daemon of buffer changes, updating hashes used for dynamic context matching.
+
+---
+
+## 💻 VS Code Extension
+
+The VS Code extension exposes inline recommendations utilizing standard `vscode.languages` diagnostics and inline decoration APIs.
+
+### Setup
+Ensure the Extension configuration specifies the correct fallback port or IPC domain path:
+
+```json
+{
+  "ghostcoder.socketPath": "~/.ghostcoder/ghostcoder.sock",
+  "ghostcoder.fallbackPort": 48673,
+  "ghostcoder.showHintsInline": true
+}
+```
+
+The extension automatically creates a socket channel client to connect with the local daemon on startup, parsing any returned JSON messages to inject annotations directly.

docs/replay_and_audit.md

@@ -0,0 +1,67 @@
+# 🔁 Replay & Audit Trail Guide
+
+Every event, routing decision, code evaluation, and model response in GhostCoder is tracked in a transparent audit ledger. This allows you to inspect, review, and reproduce any changes.
+
+---
+
+## 💾 The Ledger System
+
+Logs are saved as discrete session transactions in your local folder:
+`~/.ghostcoder/sessions/`
+
+Each session file contains sequential events:
+
+```json
+{
+  "session_id": "20260716-112000",
+  "git_branch": "main",
+  "project_path": "/users/developer/ghostcoder",
+  "events": [
+    {
+      "timestamp": 1784175600.123,
+      "event_type": "command_failed",
+      "command": "npm run test",
+      "exit_code": 1,
+      "stderr": "TypeError: Cannot read properties of undefined (reading 'config')"
+    },
+    {
+      "timestamp": 1784175601.456,
+      "event_type": "agent_suggestion_generated",
+      "agent": "agency-senior-developer",
+      "prompt_hash": "a8e9f2d...",
+      "suggestion": "Initialize the config object before parsing...",
+      "skeptic_challenges": []
+    }
+  ]
+}
+```
+
+---
+
+## 🔍 CLI Audit Commands
+
+Use these CLI utilities to audit and replay past actions.
+
+### 1. Explain Decisions
+To query the AI logic behind a specific suggestion:
+```bash
+ghostcoder explain --session <session_id> --event <event_index>
+```
+*Outputs: The original code, the exact agent instructions, the stderr traceback, and the reasoning path chosen by the models.*
+
+### 2. Activity Reporting
+Generate a summary report of issues encountered, agent routing statistics, and fix success rates:
+```bash
+# Get a summary of the current week
+ghostcoder report --period week
+
+# Get a summary of the current month
+ghostcoder report --period month
+```
+
+### 3. Session Replay
+If you reset your workspace or branch and want to re-apply all code modifications proposed during a session:
+```bash
+ghostcoder replay --session <session_id>
+```
+*This parses the transaction log and safely applies all accepted code edits to matching lines in the workspace.*

docs/skeptic_and_safety.md

@@ -0,0 +1,57 @@
+# 🛡️ Ghost Skeptic & Safety Guardrails Guide
+
+GhostCoder implements dual-layer safety validation to prevent incorrect code insertion and protect developers from executing destructive operations.
+
+---
+
+## 🔁 Ghost Skeptic: Adversarial Self-Validation
+
+Every time an engineering specialist agent generates a fix or code block, it is intercepted and evaluated by a separate **Ghost Skeptic** workflow.
+
+```
+[Brain Specialist Agent] ──> Proposes Suggested Fix
+                                    │
+                                    ▼
+[Ghost Skeptic Agent]   ──> Evaluates Suggestion against original code and context
+                                    │
+                  ┌─────────────────┴─────────────────┐
+                  ▼                                   ▼
+          [No Flaws Found]                     [Flaws Detected]
+                  │                                   │
+                  ▼                                   ▼
+        Approve suggestion for User            Attempt Auto-Correction
+                                               (Max 3 iterations)
+                                                      │
+                                                      ▼
+                                            Inject Warning or Block
+```
+
+### Skeptic Evaluation Prompts
+The Skeptic runs with a temperature of `0.1` and uses a structured schema to enforce logical consistency:
+
+```json
+{
+  "challenges": [
+    {
+      "flaw": "Removes a variable validation check, introducing a Potential NoneType dereference.",
+      "severity": "critical",
+      "scenario": "When lookup returns null and caller accesses profile properties",
+      "fix": "Reintroduce if user is not None check before dereference.",
+      "confidence": 0.98
+    }
+  ],
+  "improved_fix": "A corrected code block incorporating the re-added check."
+}
+```
+
+---
+
+## 🧱 Static Command Guardrails
+
+GhostCoder intercepts and screens terminal commands and proposed code changes against a blocklist of high-risk operational patterns.
+
+### Enforced Rules
+
+1.  **Destructive Operations**: Prohibits any command or patch containing unchecked database drop statements (`DROP DATABASE`, `DROP TABLE` without confirmation).
+2.  **Unbounded Deletions**: Flags or blocks recursive file system removal statements containing wildcards or targeting system paths (e.g., `rm -rf /`, `rm -rf *` inside critical workspace directories).
+3.  **Command Execution Blocks**: If an inline suggestion contains commands, they are shown in red to the user in the IDE and require manual copy-paste confirmation to execute (they are never run silently).