@nxuss/lemma 0.8.1 → 0.9.0

package/README.md

@@ -1,11 +1,10 @@
-# 🧠 Lemma v0.8.1
+# 🧠 Lemma v0.9.0
 
 [![npm version](https://img.shields.io/npm/v/@nxuss/lemma.svg?color=orange&style=flat-square)](https://www.npmjs.com/package/@nxuss/lemma)
 [![License](https://img.shields.io/npm/l/@nxuss/lemma.svg?color=blue&style=flat-square)](https://github.com/Nxusbets/lemma/blob/main/LICENSE)
-[![Build Status](https://img.shields.io/badge/tests-139%20passed-brightgreen.svg?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-32-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
 [![Security](https://img.shields.io/badge/privacy-firewall%20active-blueviolet?style=flat-square)](https://github.com/Nxusbets/lemma)
 [![Caching](https://img.shields.io/badge/semantic%20memory-enabled-success?style=flat-square)](https://github.com/Nxusbets/lemma)
-[![MCP Tools](https://img.shields.io/badge/MCP%20tools-25-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 ```text
     __                                
@@ -13,321 +12,217 @@
   / /   / _ \/ __ `__ \/ __ `__ \/ __ `/
  / /___/  __/ / / / / / / / / / / /_/ / 
 /_____/\___/_/ /_/ /_/_/ /_/ /_/\__,_/  
-                                        
 ```
-> **The Intelligent local-first AI Gateway — Privacy, Performance, and Precision for the Agentic Era.**
 
-Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, and **Privacy Guardrails**.
+> **The Intelligent local-first AI Gateway — Privacy, Performance, and Static Code Intelligence for the Agentic Era.**
+
+Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, **Privacy Guardrails**, and a suite of **32 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
 
 ---
 
 ## ⚡ Killer Features
 
-### 🖥️ Real-Time Telemetry & Time-Travel Dashboard
-**Full Observability & Interactive Debugging.** Spin up a gorgeous React-based dashboard at `http://localhost:8081/dashboard/` to monitor your entire AI workflow. View real-time charts of cost savings, token compactions, and cache hits. Walk through complex multi-agent conversations step-by-step using a time-travel slider, select and inspect active agent states, and export detailed telemetry audits instantly.
-
-### 🛸 Kiro/Cursor Composer Bypass (Pro Option) 💎
-**Autonomous Multi-File Editing For Free.** Exposes `write_workspace_file`, smart `apply_workspace_patch` (smart search-and-replace patching), and sandbox terminal tool `run_workspace_command` (compile/lint check) to Cursor's standard chat or Claude Desktop via MCP. Any standard free chat instantly acts as a fully-featured, unlimited autonomous multi-file Composer without needing a premium Kiro/Cursor Pro subscription.
-
-### 🌌 AST Time-Travel Telemetry: El Multiverso de Código (Pro Option) 💎
-**Regressive Error Debugging & Time-Travel.** Spawns a background recursive file watcher that debounces filesystem edits and calculates incremental AST diffs on every save. Merges active compiler crash logs to package a chronologically ordered time-traveling timeline resource (`lemma://multiverse/timeline`) so your LLM agents can inspect past codebase states and regressions instantly when you say "It broke".
-
-### 🗺️ Zero-Shot Project Onboarding (Pro Option) 💎
-**One-Shot Architecture Map.** Exposes a dynamic onboard resource (`lemma://project/onboarding`) that scans package files, folders, and key directory markers to compile a beautiful, structured markdown guide of your codebase's stack, directory layouts, and design principles so the LLM gets fully onboarded in a single shot.
-
-### 🧠 Cross-Project Bug Telepathy (Pro Option) 💎
-**Global Developer Hive Mind.** Lemma dynamically scans and queries vector memory indexes of all other local projects on your computer. If you solved a compiler issue or technical blocker in a different workspace last week, Lemma will telepathically inject that high-confidence solution to the current project's chat without you typing a single word.
-
-### ✂️ Codebase Context Squeezer & Log Collapsing
-**Massive Speedups & Zero Token Waste.** Get instant model responses and make your context windows go up to 10x further. Lemma dynamically squeezes outgoing codebase payloads, strips comments/whitespaces, and collapses repetitive console logs or redundant compiler stack traces, saving up to 95% on token consumption automatically.
-
-### 🛸 Local Cache-Augmented Response Synthesis (CARS)
-**Zero-Cost Answer Synthesis.** Experience instantaneous responses for questions similar to what you've asked before—without hitting the cloud or spending a single penny on API tokens. Lemma automatically refines past knowledge to answer your current questions in under a second, keeping your work completely private and free of charge.
-
-### 📋 Clipboard Telepathic Watcher (Universal Squeezer)
-**Universal Token Optimization Anywhere.** Enjoy Lemma's massive token-saving compression even in locked enterprise IDEs, web browsers, or closed developer chats. It works silently in the background, making sure that any code you paste into any chat is already fully optimized and compressed. You get ultra-compact, high-speed prompts everywhere instantly.
+### 🧠 Shared Semantic Memory — The Brain
+Lemma maintains a persistent vector database (ChromaDB) that accumulates knowledge across all your projects. Every solution, bug fix, and architecture decision you work through gets stored and semantically indexed. Future sessions can retrieve this knowledge in milliseconds — no cloud, no tokens, no re-explaining.
 
 ### 🛡️ Privacy Firewall (Semantic Scrubber)
-**Enterprise-Grade Privacy.** Code with absolute peace of mind. Lemma prevents your sensitive secrets, API keys, credentials, and personally identifiable information (PII) from ever escaping your machine or reaching cloud providers, while ensuring your development flows are completely uninterrupted.
-
-### 🚦 Complexity Router (Cost-Optimizer)
-**Smart Budget Management.** Slash your AI bills by up to 90% without sacrificing quality. Lemma intelligently evaluates your tasks, automatically using the most cost-effective resources for simple queries while reserving premium models for complex reasoning problems, ensuring optimal efficiency.
-
-### 🧠 Telepathic Context Injector & Real-Time MCP Sync
-**Live App Consciousness.** Say goodbye to manual debugging and copy-pasting runtime errors. Your AI assistant stays perfectly synchronized with your application's active state, automatically alerting you to errors and bugs the instant they happen so you can fix them immediately.
-
-### ⚡ Zero-Cost Local Streaming Fallback
-**Uninterrupted Offline Coding.** Never get blocked by cloud outages, network drops, or missing API keys. Lemma provides a seamless fallback that keeps your AI chat streaming instantly and completely for free, even when you're fully offline.
+**Enterprise-Grade Privacy.** Prevents API keys, credentials, and PII from ever leaving your machine. Applied automatically to every file read and workspace search via MCP.
 
-### 💾 Shared Semantic Cache
-**Sub-Millisecond Response Speeds.** Eliminate redundant costs and wait times. Lemma is smart enough to deliver instant responses to recurring or conceptually similar ideas, cutting your total API expenditure by 40-70% and saving you hours of waiting.
+### 🔮 PreCrime Static Analyzer — Zero Tokens
+**Minority Report for your code.** Combines cyclomatic complexity, git churn history, and module coupling into a composite risk score per file. Predicts which files are most likely to produce a bug before you touch them — using only the TypeScript Compiler API and git log. No LLM. No Ollama. No tokens.
 
----
+### 🕸️ Coupling Radar — Zero Tokens
+Builds a full import/export dependency graph of your codebase using the TypeScript Compiler. Detects circular dependencies, god modules (imported by everything), dead islands (no importers), and fan-in/fan-out per module. Essential before any large refactor.
 
-## 🔌 Native SDKs: LangChain & CrewAI Integration
+### 🧮 Entropy Score — Zero Tokens
+Mathematical chaos score (0-100) per file using the TS Compiler API. Measures cyclomatic complexity, nesting depth, `any` ratio, and average function size. Tells you exactly where refactor debt is accumulating.
 
-Lemma isn't just for IDE chats. Bring enterprise privacy and cost-savings to your codebases and agentic frameworks.
+### 🗺️ AST Hologram — Zero Tokens
+Scans the entire workspace and returns a dense JSON index of all exported symbols (classes, functions, interfaces, types, consts) with file paths and line numbers. Use this instead of reading individual files — saves up to 90% tokens when navigating large codebases.
 
-### 🦜 LangChain Integration
-Run secure, ultra-efficient chains with a single line of code. Lemma integrates natively as a first-class provider in LangChain, tree-shaking outgoing tool calls and caching complex semantic queries.
-```typescript
-import { LemmaLangChainProvider } from '@nxuss/lemma/langchain';
+### 🚦 Complexity Router
+Intelligently evaluates each prompt and routes it to the most cost-effective model. Reserves premium models for complex reasoning, uses smaller models for simple tasks. Slashes your AI bill without sacrificing quality.
 
-const model = new LemmaLangChainProvider({
-  apiKey: process.env.OPENAI_API_KEY,
-});
-```
+### ✂️ Context Squeezer & TurboMode
+Dynamically squeezes outgoing code payloads, strips comments, collapses whitespace, and compacts JSON. Saves up to 90% on token consumption. Automatically injected via the `lemma-turbomode` system prompt on MCP handshake.
 
-### 👥 CrewAI Integration
-Coordinate heavy multi-agent swarms without breaking your bank. Lemma automatically handles agent-to-agent communication compression, prevents token bloat, and provides high-speed consensus caching.
-```typescript
-import { LemmaCrewAIProvider } from '@nxuss/lemma/crewai';
+### 🛸 Autonomous Workspace Control
+Exposes `write_workspace_file`, smart `apply_workspace_patch` (collision-safe search-and-replace), and `run_workspace_command` (with allowlist security) to any IDE via MCP. Any standard chat instantly becomes a fully-featured autonomous multi-file editor.
 
-const crew = new LemmaCrewAIProvider({
-  agents: [...],
-});
-```
+### 🩺 AutoPilot & Auto-Heal
+Lemma's background file watcher detects TypeScript compilation errors on every save, parses the error, and calls the auto-heal agent to apply a fix — automatically. When Autopilot succeeds, the fix is stored in The Brain for future sessions.
 
 ---
 
-## 🚀 Smart CLI (Zero-Config)
-
-Lemma introduces a powerful, unified command-line tool. Get started, monitor, and manage your local AI gateway effortlessly:
+## 🚀 Quick Start (Zero Config)
 
 ```bash
-# 1. Install globally
+# Install globally
 npm install -g @nxuss/lemma
 
-# 2. Initialize (Auto-configures local database and environment)
+# Initialize (auto-configures local DB and MCP for your IDEs)
 lemma init
 
-# 3. Spin up the gateway and launch the gorgeous dashboard
+# Start the gateway + dashboard
 lemma start
 ```
 
-### 🛠️ CLI Reference
+---
+
+## 🛠️ CLI Reference
 
 | Command | Action |
 | :--- | :--- |
-| `lemma init` | Bootstraps configuration files and auto-discovers project stack. |
-| `lemma start` | Launches the proxy, cache engine, and dashboard. |
+| `lemma init` | Bootstraps config and auto-configures MCP for Claude Desktop, Cursor, Windsurf, Kiro, VS Code. |
+| `lemma start` | Launches proxy, cache engine, and dashboard at `http://localhost:8081`. |
 | `lemma stop` | Gracefully shuts down the background proxy. |
-| `lemma status` | Displays health of all optimization modules and active connections. |
-| `lemma stats` | High-density metrics showing real-time token and cost savings. |
-| `lemma mcp` | Starts stdin/stdout MCP server for IDE integration (Cursor, Claude, VS Code, etc.). |
+| `lemma status` | Health of all modules and active connections. |
+| `lemma stats` | Real-time token and cost savings metrics. |
+| `lemma mcp` | Starts the stdin/stdout MCP server for IDE integration. |
 | `lemma heal` | Auto-diagnose and repair the latest server crash from live context logs. |
-| `lemma upgrade` | See Pro features and get a license key. |
-| `lemma activate <key>` | Activate a Pro license key. |
-| `lemma autopilot` | Toggle autonomous mode for unattended cost optimization. |
-| `lemma clipboard` | Toggle the Clipboard Telepathic Watcher daemon. |
+| `lemma autopilot` | Toggle autonomous background watcher mode. |
 
-### ⚙️ Customization & System Options
+### Customizing via `lemma.config.json`
 
-By default, Lemma works seamlessly with zero configuration. However, if you are running in a sensitive enterprise environment or want absolute control over filesystem modifications, you can customize Lemma's behavior.
+```json
+{
+  "system": {
+    "clipboardWatcher": { "disabled": false }
+  },
+  "mcp": {
+    "allowedCommandPrefixes": ["npm", "git", "tsc", "your-custom-tool"]
+  }
+}
+```
 
-#### CLI Command Options
+---
 
-* **`lemma init`**: Initializes project, auto-discovers stack, and prompts before editing IDE configs.
-* **`lemma init --no-configure`**: Initialize without MCP server configuration for any IDE.
-* **`lemma init --yes`**: Skip all prompts and accept defaults (auto-configures all IDEs).
-* **`lemma start --no-clipboard`**: Start the proxy without spawning the background Clipboard watcher daemon.
+## 🔌 MCP Integration
 
-#### Customizing via `lemma.config.json`
+Add Lemma to any MCP-compatible IDE in seconds:
 
-Create or edit `lemma.config.json` in your project root to disable or fine-tune specific background daemons:
+### Cursor / Windsurf / Kiro / Antigravity
+1. Go to **Settings → MCP**
+2. Add new server: **Command** = `lemma mcp`
 
+### Claude Desktop
 ```json
 {
-  "system": {
-    "autoConfigure": {
-      "disabled": false,
-      "editor": true,
-      "shell": true,
-      "claude": true
-    },
-    "clipboardWatcher": {
-      "disabled": false
+  "mcpServers": {
+    "lemma": {
+      "command": "npx",
+      "args": ["-y", "@nxuss/lemma", "mcp"]
     }
   }
 }
 ```
 
----
+Once connected, your IDE gains access to all **32 MCP tools** and Lemma auto-injects the TurboMode system prompt on handshake.
 
-## 🛠️ MCP Tools Reference (v0.8.0 — 25 Tools)
+---
 
-When connected via `lemma mcp`, your Chat IDE gains access to **25 native tools** covering workspace navigation, code safety, semantic memory, AI cost optimization, autonomous project context injection, and TurboMode optimization.
+## 🛠️ MCP Tools Reference (v0.9.0 — 32 Tools)
 
 ### 🗂️ Workspace Tools
 
 | Tool | Description |
 | :--- | :--- |
-| `read_workspace_file` | Read a file with automatic token compression (up to 80% savings) and privacy scrubbing. |
-| `write_workspace_file` | Write content to a file, creating directories as needed. |
-| `apply_workspace_patch` | Smart search-and-replace patch — safe against duplicate matches. |
+| `read_workspace_file` | Read a file with automatic token compression and privacy scrubbing. |
+| `write_workspace_file` | Write content to a file, creating parent directories as needed. |
+| `apply_workspace_patch` | Smart search-and-replace patch — safe against duplicate matches. Returns clear errors if search block is ambiguous. |
 | `list_workspace_dir` | Recursively list the project structure up to a configurable depth. |
-| `search_workspace` | Fast text search (grep) across all project files with optional extension filter. |
-| `run_workspace_command` | Execute bash commands (tests, linters, git) in the workspace root. Returns stdout/stderr. |
+| `search_workspace` | Fast text search (grep) across all project files with optional extension filter. Results are privacy-scrubbed. |
+| `run_workspace_command` | Execute bash commands in the workspace root. Secured by an allowlist. 15s timeout. |
 
-### 🔬 Code Intelligence Tools ✨ NEW in v0.7.0
+### 🔬 Code Intelligence Tools
 
 | Tool | Description |
 | :--- | :--- |
-| `get_ast_hologram` | **Holographic AST Map.** Scans the workspace and returns a dense JSON index of all exported symbols (classes, functions, interfaces, types, consts) with their file paths and line numbers. Use this **instead of reading individual files** — saves up to 90% tokens when navigating large codebases. |
-| `validate_patch_sandbox` | **AST Multiverse Auto-Debugger.** Validates a proposed patch in an isolated sandbox (`/tmp`) **before** applying it to the workspace. Runs `tsc --noEmit` and bracket-balance checks. Returns a clear `✅ SAFE TO APPLY` or `❌ DO NOT APPLY` verdict with full diagnostics. |
+| `get_ast_hologram` | **Holographic AST Map.** Scans the workspace via TS Compiler API and returns a dense JSON index of all exported symbols with file paths and line numbers. Use instead of reading individual files — 90% token savings. Zero LLM calls. |
+| `validate_patch_sandbox` | **Pre-flight Validator.** Validates a proposed patch in an isolated sandbox before applying it. Runs `tsc --noEmit` and bracket-balance checks. Returns `SAFE TO APPLY` or `DO NOT APPLY` verdict. |
+| `diff_only` | Compute a compact line-by-line diff between the last known state of a file and its current content. Session-scoped state tracking. |
 
 ### 🧠 Brain & Memory Tools
 
 | Tool | Description |
 | :--- | :--- |
-| `search_memory` | Semantic search across The Brain — retrieves past solutions and context from all your projects. |
-| `store_memory` | Explicitly save a key technical decision, code snippet, or architecture note into The Brain for future sessions. |
-| `query_hybrid_consensus` | **Hybrid Consensus Engine.** Checks The Brain for a cached answer at a configurable similarity threshold (default 80%). Brain **HIT** → instant response, zero cloud tokens spent. Brain **MISS** → instructs the IDE to proceed with cloud and auto-stores the result afterward. |
-| `get_telepathic_hints` | **Proactive Telepathy.** Given the path of the file being edited, automatically surfaces the top N most relevant memories and past solutions from The Brain — no explicit query needed. Front-loads context before you write a single line. |
+| `search_memory` | Semantic search across The Brain — retrieves past solutions and context from all your projects globally. |
+| `store_memory` | Persist a technical solution, bug fix, or architecture decision into The Brain for future sessions. |
+| `query_hybrid_consensus` | **Hybrid Consensus Engine.** Checks The Brain at configurable threshold (default 80%). HIT → instant answer, zero cloud tokens. MISS → proceed with cloud and cache afterward. |
+| `get_telepathic_hints` | **Proactive Telepathy.** Given the active file path, surfaces the top N most relevant past solutions from The Brain — no query needed. |
 
 ### ⚙️ Optimization & Privacy Tools
 
 | Tool | Description |
 | :--- | :--- |
 | `scrub_privacy` | Mask PII, API keys, and secrets from any text block using the Privacy Firewall. |
-| `squeeze_prompt` | Compress code blocks and boilerplate in any prompt — up to 80% token reduction. |
-| `summarize_long_text` | Automatically summarize lengthy content to stay within context window limits. |
-| `prune_conversation_history` | Intelligently trim conversation history while preserving critical context. |
-| `diff_only` | Extract only the changed lines between two code blocks — minimal token diff. |
-| `batch_tool_calls` | Execute multiple tool calls in parallel for high-throughput operations. |
-| `get_routing_advice` | Analyze a prompt and get the optimal model recommendation from the Complexity Router. |
-| `auto_heal` | Diagnose and auto-heal the latest local server crash from Lemma's live context logs. |
-| `get_project_onboarding` | Download a one-shot architectural mental model of the current project codebase. |
-| `turbosqueeze` | Extreme prompt compression — strips comments, imports, whitespace, compacts JSON. |
-| `compress_context` | Summarize old conversation turns via Ollama (fallback: truncation). |
-| `smarter_cache` | Predictive cache — queries The Brain at 75% threshold before reasoning. |
-| `token_budget` | Optimization dashboard with multiplier, savings, and recommendations. |
-
-### 🚀 TurboMode Tools (NEW in v0.8.0)
+| `squeeze_prompt` | Compress code blocks and boilerplate in any prompt. Up to 80% token reduction. |
+| `turbosqueeze` | **Extreme compression.** Strips comments, imports, whitespace, and compacts JSON. Returns reduction stats. |
+| `compress_context` | Summarizes old conversation turns, keeps last N turns intact. Falls back to truncation if no Ollama. |
+| `prune_conversation_history` | Intelligently decimate conversation history while preserving critical recent context. |
+| `summarize_long_text` | Summarize lengthy content via Ollama to save context window space. Falls back gracefully. |
+| `smarter_cache` | **Predictive cache.** Queries The Brain at 75% threshold before any reasoning. Auto-suggests `store_memory` on MISS. |
+| `token_budget` | Optimization dashboard: multiplier, total tokens saved, active strategies, and recommendations. |
+| `get_routing_advice` | Analyze a prompt and get optimal model recommendation from the Complexity Router. |
+| `get_project_onboarding` | Download a one-shot architectural mental model of the current codebase. |
+| `auto_heal` | Diagnose and auto-heal the latest crash from Lemma's live context logs. |
+| `batch_tool_calls` | Execute multiple tool calls in parallel via `Promise.all`. High-throughput operations in a single MCP round-trip. |
+
+### 🔮 Zero-Token Static Intelligence Tools (NEW in v0.9.0)
+
+> All tools in this section use **zero LLM tokens, zero Ollama, zero cloud**. Pure local computation via TypeScript Compiler API, git, and math.
 
 | Tool | Description |
 | :--- | :--- |
-| `turbosqueeze` | **Extreme prompt compression.** Strips comments, imports, whitespace, and compacts JSON. Returns reduction stats and reports savings to proxy ledger. |
-| `compress_context` | **Conversation summarization.** Summarizes old turns via Ollama (falls back to truncation), keeps last N turns intact, reports token savings. |
-| `smarter_cache` | **Predictive cache.** Queries The Brain at 75% threshold before any reasoning, auto-suggests `store_memory` on MISS. |
-| `token_budget` | **Optimization dashboard.** Displays current multiplier, tokens saved, tool calls, and optimization recommendations. |
+| `entropy_score` | **Mathematical chaos score** (0-100) per file. Measures cyclomatic complexity, max nesting depth, `any` type ratio, and average function size. Identifies which files need refactoring before you touch them. |
+| `coupling_radar` | **Dependency graph analysis.** Detects circular imports, god modules (high fan-in), dead islands (no importers), and fan-in/fan-out per module. Essential before large refactors. |
+| `pattern_fossil` | **Zombie code detector.** Finds patterns that were replaced in most of the codebase but survive in old files: `var` vs `const/let`, callbacks vs `async/await`, `require()` vs `import`, `: any` vs generics. Reports adoption percentage. |
+| `git_heatmap_risk` | **Git churn analysis.** Calculates change frequency per file and co-edit pairs (files that always change together = hidden coupling). Returns a risk score for each file based on historical git behavior. |
+| `precrime_static` | **Minority Report predictor.** Combines `entropy_score` (40%) + `git_heatmap_risk` (40%) + `coupling_radar` (20%) into a composite PreCrime Score per file. Ranks files by bug probability with per-factor breakdown and names the riskiest functions. |
+| `semantic_dedup_guard` | **Brain dedup firewall.** Before calling `store_memory`, pass content through here. If similarity ≥ 92% → rejects as duplicate. If 75–91% → warns and shows the similar entry. Keeps The Brain lean and dense. |
+| `dead_export_necromancer` | **Dead code auditor.** Maps every `export` in the workspace against every `import`. Symbols exported but never imported anywhere = zombie code inflating your context. Reports dead exports by file with estimated token waste. |
 
 ### ⚡ TurboMode Auto-Injection
-When connected via `lemma mcp`, Lemma automatically injects 7 TurboMode rules into the agent's system prompt during handshake — no manual prompt loading required:
-1. `turbosqueeze` before writing code
+
+When connected via `lemma mcp`, Lemma auto-injects 7 rules into the agent's system prompt on handshake:
+
+1. `turbosqueeze` before writing large code blocks
 2. `smarter_cache` before any reasoning
-3. `compress_context` every turn
-4. `store_memory` after every solution
-5. `get_ast_hologram` before reading files
-6. `batch_tool_calls` for parallel operations
-7. No fluff or chit-chat
+3. `store_memory` after every resolved solution
+4. `get_ast_hologram` before reading files
+5. `batch_tool_calls` for parallel operations
+6. `semantic_dedup_guard` before every `store_memory`
+7. No fluff, no chit-chat — maximum density
 
-### 📡 Dashboard MCP Toggle
-The Dashboard Header now shows a **clickable MCP status badge** — click to enable/disable MCP integration instantly. The badge cycles through `active` (cyan), `idle` (gray), and `offline` (red) states.
+---
 
-### 📡 MCP Resources
+## 📡 MCP Resources
 
 | Resource URI | Description |
 | :--- | :--- |
-| `lemma://runtime/context` | Live application errors, stack traces, and runtime state. Subscribable — your IDE gets notified the instant a crash happens. |
+| `lemma://runtime/context` | Live application errors, stack traces, and runtime state. Subscribable — IDE notified instantly on crash. |
 | `lemma://stats/usage` | Current token savings, cost report, and cache hit metrics in JSON. |
-| `lemma://project/context` | Active project metadata, tech stack, memory count, and token savings — used for automatic context injection on cache misses. |
+| `lemma://project/context` | Active project metadata, tech stack, memory count, and token savings. |
 | `lemma://project/onboarding` | Dynamic project architecture guide compiled on demand. |
-| `lemma://multiverse/timeline` | Chronological AST diff timeline of the last 10 code micro-snapshots. |
+| `lemma://multiverse/timeline` | Chronological AST diff timeline of recent code snapshots. |
 
 ---
 
-## 💎 Tier Comparison
-
-| Feature | 🆓 Free (Standard) | 💎 Pro ($12/mo) |
-| :--- | :--- | :--- |
-| **Privacy Firewall** | ✅ Included | ✅ Advanced Masking |
-| **Complexity Router** | ✅ Included | ✅ Custom Routing Policies |
-| **Caching** | Exact Match | **Semantic Memory** |
-| **Hive Mind** | Local Only | **Cloud Sync (Team Memory) + Cross-Project Telepathy 💎** |
-| **AST Time-Travel Telemetry** | ❌ None | **Codebase Multiverse (Cap 10 AST Snapshots) 💎** |
-| **Kiro/Cursor Composer Bypass** | ❌ None | **Smart Patches & Sandbox Terminal MCP 💎** |
-| **Zero-Shot Onboarding Guide** | ❌ None | **Codebase Architecture Map MCP 💎** |
-| **AST Hologram** | ❌ None | **Symbol Map — 90% token savings 💎** |
-| **Sandbox Patch Validator** | ❌ None | **Pre-flight code safety checks 💎** |
-| **Hybrid Consensus Engine** | ❌ None | **Brain-first query routing 💎** |
-| **Proactive Telepathy** | ❌ None | **Auto-surfaced context hints 💎** |
-| **Telemetry Dashboard** | Basic Stats | **Time-Travel Debugger & 60fps Graph** |
-| **Limits** | 300 requests/mo | **Unlimited Agentic Power** |
-
----
-
-## 🛠️ Integration: Power Up Your Favorite Tools
-
-Lemma is compatible with **any** tool that allows you to configure a custom OpenAI Base URL. This means you can add Lemma's intelligence to your existing workflow in seconds.
-
-### 💬 Use it with AI Chats & IDEs
-You don't need to change your habits. Just point your tool's "Base URL" to Lemma:
-*   **Cursor:** Go to `Settings > Models > OpenAI API > Override Base URL` and set it to `http://localhost:8081/v1`.
-*   **VS Code (Continue):** Update your `config.json` to use `http://localhost:8081/v1` as the `apiBase`.
-*   **AutoGPT / BabyAGI:** Set the `OPENAI_API_BASE` environment variable.
-*   **Custom Apps:** Replace `https://api.openai.com/v1` with `http://localhost:8081/v1` in your SDK initialization.
-
-### 💎 Pro Integration (Model Context Protocol - MCP)
-For **Lemma Pro** users, expose Lemma's entire intelligence layer — Privacy Firewall, Semantic Brain, AST Hologram, Sandbox Validator, Hybrid Consensus, and Proactive Telepathy — directly as native tools using the **Model Context Protocol (MCP)**. This lets the LLM read, search, write, patch, validate, and compile files autonomously.
-
-#### 🟢 Cursor / Antigravity / Windsurf:
-1. Go to **Settings > Features > MCP**.
-2. Click **+ Add New MCP Server**.
-3. Configure the server:
-   * **Name**: `Lemma`
-   * **Type**: `command`
-   * **Command**: `lemma mcp`
-4. Click **Save**. A green **"Connected"** dot will appear, confirming that the IDE has loaded all 25 of Lemma's tools.
-
-#### 🟢 Claude Desktop:
-Add the following to your `claude_desktop_config.json` configuration file:
-```json
-{
-  "mcpServers": {
-    "lemma": {
-      "command": "npx",
-      "args": ["-y", "@nxuss/lemma", "mcp"]
-    }
-  }
-}
-```
-
-### ⚡ Why use Lemma for Chat?
-1.  **Privacy:** Your IDE won't leak your secrets to the cloud.
-2.  **Context:** Lemma syncs your runtime crashes directly to your chat window.
-3.  **Speed:** Instant responses for similar questions via Semantic Cache.
-4.  **Intelligence:** AST Hologram + Hybrid Consensus = dramatically fewer tokens spent per session.
-5.  **Observability:** Gorgeous dashboard showing you exactly how much cash and tokens you are saving.
-
----
-
-## 🔒 Security & Privacy
+## 🔒 Security
 
 ### Network Binding
-By default, Lemma binds only to `127.0.0.1` (localhost). It is **not accessible from the network** unless you explicitly set:
+By default, Lemma binds only to `127.0.0.1` (localhost). Not network-accessible unless explicitly configured:
 ```env
 LEMMA_BIND_HOST=0.0.0.0
+AUTH_ENABLED=true
+AUTH_REQUIRE_API_KEY=true
+AUTH_ALLOWED_ORIGINS=https://yourdomain.com
 ```
-> ⚠️ If you do expose Lemma to the network, always enable authentication first:
-> ```env
-> AUTH_ENABLED=true
-> AUTH_REQUIRE_API_KEY=true
-> AUTH_ALLOWED_ORIGINS=https://yourdomain.com
-> ```
-
-### 📋 Clipboard Watcher Disclosure
-The **Clipboard Telepathic Watcher** polls your system clipboard every 1 second to automatically compress code you copy. This is disclosed in the startup banner. To disable it:
-```env
-# In your .env
-LEMMA_DISABLE_CLIPBOARD=true
-```
-Or via CLI flag: `lemma start --no-clipboard`
 
 ### MCP Command Allowlist
-The `run_workspace_command` MCP tool only executes commands from an allowlist. Default safe prefixes include `npm`, `npx`, `git`, `tsc`, `node`, `jest`, `eslint`, `ls`, `grep`, and more.
+`run_workspace_command` only executes commands from an allowlist. Default safe prefixes: `npm`, `npx`, `git`, `tsc`, `node`, `jest`, `eslint`, `ls`, `grep`, and more.
 
-To extend the allowlist for your project, add to `lemma.config.json`:
+Extend for your project in `lemma.config.json`:
 ```json
 {
   "mcp": {
@@ -336,24 +231,37 @@ To extend the allowlist for your project, add to `lemma.config.json`:
 }
 ```
 
-### License Security (Cloud Server)
-When running the cloud server in production, set a private license salt:
-```env
-# Generate with: openssl rand -hex 32
-LEMMA_LICENSE_SALT=your-random-64-char-hex-string
+See [`.env.security.example`](.env.security.example) for all security-related environment variables.
+
+---
+
+## 🦜 SDK Integrations
+
+### LangChain
+```typescript
+import { LemmaLangChainProvider } from '@nxuss/lemma/langchain';
+
+const model = new LemmaLangChainProvider({
+  apiKey: process.env.OPENAI_API_KEY,
+});
 ```
 
-### Stripe Webhooks (Cloud Server)
-The Stripe webhook endpoint requires a webhook signing secret in production:
-```env
-STRIPE_WEBHOOK_SECRET=whsec_...
+### CrewAI
+```typescript
+import { LemmaCrewAIProvider } from '@nxuss/lemma/crewai';
+
+const crew = new LemmaCrewAIProvider({ agents: [...] });
 ```
-Get this from **Stripe Dashboard → Developers → Webhooks → Signing Secret**. Without it, the endpoint is disabled in `NODE_ENV=production`.
 
-For local testing: `STRIPE_SKIP_SIGNATURE_VERIFY=true`
+---
 
-### Full Security Template
-See [`.env.security.example`](.env.security.example) for all security-related environment variables.
+## 🔄 Using as a Proxy
+
+Point any OpenAI-compatible tool to Lemma's local proxy for transparent caching and privacy:
+
+- **Cursor:** `Settings > Models > OpenAI API > Override Base URL` → `http://localhost:8081/v1`
+- **VS Code (Continue):** Set `apiBase` to `http://localhost:8081/v1`
+- **Custom apps:** Replace `https://api.openai.com/v1` with `http://localhost:8081/v1`
 
 ---
 

package/dist/cjs/cli/lemma-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA0bA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AA2jED,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6KhL"}
+{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AAsbA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AAmgED,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6KhL"}