@nxuss/lemma 1.10.0 → 1.12.0

package/README.md

@@ -1,4 +1,4 @@
-# 🧠 Lemma v1.10.0
+# 🧠 Lemma
 
 [![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)
@@ -8,439 +8,115 @@
 [![Tests](https://img.shields.io/badge/tests-378%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 ```text
-    __                                
+    __
    / /   ___  ____ ___  ____ ___  ____ _
   / /   / _ \/ __ `__ \/ __ `__ \/ __ `/
- / /___/  __/ / / / / / / / / / / /_/ / 
-/_____/\___/_/ /_/ /_/_/ /_/ /_/\__,_/  
+ / /___/  __/ / / / / / / / / / / /_/ /
+/_____/\___/_/ /_/ /_/_/ /_/ /_/\__,_/
 ```
 
 > **The Intelligent local-first AI Gateway — Privacy, Performance, Static Code Intelligence, and Infrastructure Command Center 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**, **22 Infrastructure Management Tools**, and a suite of **95 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
+Lemma sits between your development environment and LLM providers as an MCP server / local proxy.
+It cuts what actually enters the model's context — repeated reads, unfiltered command output, tool
+schemas the project can't use — while keeping every answer verifiable: a cache hit is disclosed as
+a cache hit, a compressed file is never what the user sees, and a savings number always traces back
+to an auditable ledger, never an estimate.
 
-Since v1.7.0 those 95 tools are all registered, but only the ones your project can actually use
-are advertised to the model each turn. The rest stay one `lemma_toolbox` call away. See
-[Tool profiles](#-tool-profiles).
+## 🚀 Quick start
 
----
-
-## 📋 Changelog
-
-### v1.10.0 — Repeated output stops being re-sent, and a stale memory can't hide behind a fresh one *(NEW)*
-
-Two separate problems, same root cause: Lemma was treating an answer as one indivisible blob,
-so any change anywhere forced either "resend everything" or "trust nothing."
-
-| Change | What it does | Why it matters |
-| :--- | :--- | :--- |
-| **Output dedup across the board** | `run_workspace_command`, `search_workspace`, the dependency graph, and `test_oracle` now return `IDENTICAL: ... (call #N)` or a diff instead of the same payload again. | Re-running the same command/search mid-session (common in an edit/verify loop) used to re-send the full output every time. |
-| **`read_workspace_file` in delta mode** | Re-reading a file that changed since the last read now returns `CHANGED: N hunks +a/-b` when the diff is under 50% of the file, instead of the whole file. | The read cache already tracked what was "unchanged"; it had no answer for "changed a little." |
-| **`affected_tests`** *(new tool)* | Given changed files, walks the dependency graph (memoized by file fingerprint) and returns only the tests that could actually be affected. | Replaces full-suite reruns — the single largest context sink in an edit/verify loop — with a scoped list. |
-| **Local prefilter for `search_workspace`** *(opt-in, `LEMMA_LOCAL_PREFILTER=1`)* | Ranks candidate files with a local Ollama model before they're sent, instead of after. Fails open on any error. | Search stays cheap even when it can't distinguish "roughly relevant" from "exactly what was asked" purely by text match. |
-| **Claim-level freshness in The Brain** | `store_memory` accepts `claims: [{text, filePaths?, symbols?}]` — a response with several independent statements can now go stale one claim at a time instead of all-or-nothing. `search_memory` reports which claims are still ✓ fresh and which are ✗ stale. | Symbol-level freshness (v1.8.0) already stopped an unrelated edit in the same file from staling a memory. This is the same idea one level up: an unrelated *claim* in the same memory shouldn't stale the ones still true. |
-
-Both dedup and delta mode share one invariant, unchanged from before: a compressed or
-withheld payload is only ever a stand-in for content the model already received in this
-session. Nothing is ever hidden that wasn't sent first.
-
-**378 tests passing** (up from 333), including coverage for partial claim invalidation and
-that entries written before `claims` existed keep working with no migration step.
-
-### v1.9.0 — The tools stop fighting the agent using them
-
-Lemma's savings only count if the agent actually uses the tools. Five defects were pushing it back
-to its native tools instead — which means the file gets read twice, and Lemma's overhead is charged
-for nothing. Each one below was found by driving the tools as a consumer, not by reading the code.
-
-| Change | What it does | Why it matters |
-| :--- | :--- | :--- |
-| **Real line numbers in `read_workspace_file`** | Every line carries its true line number in the original file, mapped through compression rather than renumbered. Squeezer markers get a blank gutter instead of borrowing a neighbour's number. | A compressed read could not be cited (`file.ts:120`) or edited from, so the agent re-read the file with a native tool — paying for it twice and cancelling the squeeze. |
-| **`offset` / `limit`** | Read a line range of a large file, numbered from the range start. | Whole-file reads were the only option, on files where a 30-line window was the actual need. |
-| **Imports are named, not just counted** | `// [Lemma Squeezer: Squeezed 2 import/dependency lines: fs, path]` | "Squeezed 3 import lines" made *"is this module already imported?"* unanswerable without a full re-read. |
-| **`run_workspace_command` timeout: 15s → 120s, configurable to 600s** | `timeoutMs` parameter. | 15s is below the runtime of a real `npm test` or `tsc --noEmit` — the exact commands the output distiller exists for. The tool always timed out, so it was never used. |
-| **Timed-out commands keep their output** | Partial stdout/stderr is distilled and returned with a truncation notice. | The old path discarded everything on timeout, and the partial output is normally where the failure is. |
-| **Allowlist covers real toolchains** | `python`, `pytest`, `cargo`, `go`, `make`, `rg`, `sed`, `awk`, `docker`, `kubectl`, `gh` and more. Still deny-by-default. | A blocked command is not a command prevented — it is a refused round-trip followed by the same command run through an unrestricted shell, outside Lemma's view. |
-| **The read cache stops withholding unsent content** | The dedup key now includes the view (range, numbering, compact mode), not just the path. | Reading lines 1-50 then 51-100 returned `UNCHANGED` for content that had **never been sent**. This was data loss, not just friction. |
-| **`UNCHANGED` carries a symbol outline** | Instead of a bare hash, the marker lists the file's symbols and their lines. | *"Reuse your existing copy"* assumes the agent still has it — but its context gets compacted as a session grows, and the server has no way to know. |
-| **Free sessions stop paying for tools they can't run** | `resolveToolSurface` takes an entitlement check; Pro-gated tools are no longer advertised without a license. They stay registered and discoverable via `lemma_toolbox`. | A free session advertised the full core surface — read, search, patch, run, AST — and refused 14 of those 20 at call time, charging ~3k tokens per turn for the privilege. |
-| **TURBOMODE prompt: ~1,700 → ~894 tokens** | Rule 3 no longer contradicts rule 0. Rationale written for human readers moved into source comments. | *"NEVER read files blindly, always call get_ast_hologram first"* told the model to spend a round-trip to save a read that was often cheaper than the round-trip. |
-
-**Safety net for the new gutter:** `apply_workspace_patch` strips a line-number prefix from a search
-block, but only when *every* non-empty line carries one. A lone `1| ` inside real content (a markdown
-table) is left alone. Both cases are covered by tests.
-
-Line numbers are exact rather than approximate because of what compression actually does: it only
-*drops* whole lines and normalizes whitespace *within* a line — it never reorders, merges or splits
-them. A line that cannot be located reports no number rather than a wrong one, and does not
-desynchronise the lines after it.
-
-**333 tests passing** (up from 309), including a guard that fails the build if a prompt trim removes
-one of the correctness disclosures. It caught a real regression during this work.
-
-### v1.8.1 — Two correctness fixes: secret scrubbing and patch data loss
-
-An audit of the tools with no test coverage turned up two bugs where the tool looked done but
-silently produced wrong output.
-
-- **`apply_workspace_patch` could corrupt a line.** The exact-match strategy computed
-  `startLine`/`endLine` from a raw substring `indexOf`, but the handler always spliced by whole
-  line. A search block that was a *fragment* of a line (not the entire line) collapsed
-  `startLine === endLine`, and the splice replaced the entire line with just the replacement —
-  discarding everything else on it. Exact matches now splice by character offset;
-  whitespace-normalized/indent-anchored/fuzzy matches (already full-line windows) are unaffected.
-- **The privacy scrubber only recognized 3 generic patterns.** Default patterns covered
-  `API_KEY`/`EMAIL`/`Bearer ...` shapes only — vendor-specific secrets (Stripe, AWS, GitHub,
-  Google, Slack, JWTs, PEM private-key blocks) and custom-named secrets (e.g. a project's own
-  `_SALT` or `_WEBHOOK_SECRET` env var) passed through unmasked. Also, a project's custom
-  `lemma.config.json` patterns silently *replaced* the defaults instead of adding to them, so
-  defining one narrow pattern dropped coverage for everything else. Added vendor-specific
-  patterns plus a generic `ENV_SECRET` catch-all keyed on variable-name conventions, and custom
-  patterns now augment the defaults by default (`replaceDefaults: true` opts into full override).
-
-### v1.8.0 — The Brain learns from project history, not just what it's told *(NEW)*
-
-Every memory in The Brain used to depend on the assistant remembering to call `store_memory`. If
-nobody called it, the Brain knew nothing about work that already happened.
-
-| Change | What it does | Why it matters |
-| :--- | :--- | :--- |
-| **`lemma-brain-ingest`** *(new CLI)* | Feeds The Brain from git commits and `CHANGELOG.md` — no assistant call needed. Incremental via a marker file, safe to wire to `post-commit`. | The Brain stops depending on the model remembering to save anything. |
-| **Checkpoints now feed The Brain** | `saveCheckpoint()` indexes any checkpoint with real content into the same Brain `search_memory` reads. | Decisions and bugs recorded in a checkpoint used to be invisible to search. |
-| **`get_project_history`** *(new tool)* | Merges recent commits, checkpoints, and Brain memories for the current project into one call. | Answers "what have we done here" without three separate lookups. |
-| **Outcome tagging** | `store_memory` accepts `outcome: 'failed'`; search surfaces it as a warning, not a suggestion. | A dead end is now as memorable as a fix. |
-| **Symbol-level freshness** | `store_memory` accepts `symbols: [{filePath, symbolName}]` — freshness is judged by that function's own source, not the whole file. | An unrelated edit elsewhere in the file no longer stales the memory out. |
-
-**PR review memory was silently going nowhere.** `BrainBridge` talked to the proxy's
-`/api/search`/`/api/memory/store`, both backed by ChromaDB + a local Ollama server on `:11434` —
-the exact stack TheBrainV2 replaced in 1.0.0. Whenever Ollama wasn't running (the common case
-now), every call failed inside a `try/catch` and returned empty. It now reads/writes `TheBrainV2`
-directly, so PR review and interactive coding share one memory instead of two disconnected ones.
-
-**Two projects could quietly share — or split — memories.** `deriveProjectId` hashed the
-project path without resolving symlinks; on macOS `process.cwd()` and an `os.tmpdir()`-built path
-can report different strings for the same directory, hashing to two different project scopes. It
-now resolves via `fs.realpathSync` first.
-
-**Spanish text was mangled before it reached the index.** `tokenize()` used `\w` to strip
-punctuation, which doesn't match accented letters — "Cómo" became "mo", "diseño" became "dise",
-and the same word typed without its accent tokenized completely differently. `tokenize()` now
-normalizes diacritics first, and gained an additive English/Spanish stemmer and Spanish stopwords.
-
-**`token_budget` reported a multiplier no ledger backed.** It fetched a proxy route that doesn't
-exist, silently fell back to an uncosted estimate, and reported a bigger number than the
-session's own auditable ledger would support. It now reads the real `SavingsLedger` net position
-(`/api/savings-breakdown`) or says plainly there's nothing to report if the proxy isn't running.
-
-### v1.7.0 — The cost of being connected
-
-Every tool schema Lemma advertises goes into the model's system prompt and is **re-sent on every
-request of the session** — including schemas for tools the project can never use. On this repo that
-was ~13,950 tokens per turn before Lemma saved anything.
-
-| Change | What it does | Why it matters |
-| :--- | :--- | :--- |
-| **Project-scoped tool surface** | Core tools are always advertised; situational groups (infrastructure, review) only when the repo shows evidence they apply. `mcp.toolProfile` accepts `auto`, `core`, or `full`. | ~3,420 tokens of schemas per turn instead of ~11,600. |
-| **`lemma_toolbox`** *(new)* | Lists tools whose schemas were withheld, returns any tool's schema, and invokes it. | A withheld schema is a deferred cost, never a lost capability. |
-| **Leaner TURBOMODE prompt** | ~2,340 → ~1,700 tokens. Instructions for tools the session doesn't advertise are gone; every correctness rule stays, enforced by tests. | The prompt stops paying for advice the model can't act on directly. |
-| **Overhead in `token_budget`** | Reports profile, advertised vs. hidden counts, active groups, and the real schema token cost. | The fixed cost is visible instead of assumed. |
-
-**Total fixed cost per turn on this repo: ~5,120 tokens, down from ~13,950.**
-
-**The Brain reported cache hits that never happened.** Duplicate detection runs an internal search
-before storing a memory, and that search shared the counters behind the reported hit rate — while
-searching with a minimum similarity of 0, so it matched nearly every time. Every store inflated the
-session hit rate and bumped an unrelated entry's hit counter. Internal lookups no longer count.
-**Reported hit rates will be lower after upgrading; the lower number is the correct one.**
-
-**Three features silently did nothing.** `get_telepathic_hints`, `auto_context_bundle`, and
-`test_autofix_interceptor` read prior knowledge from `<project>/.lemma/memory/` — a directory no
-code path writes. They returned empty in every project while the Brain held the answers. All three
-now query the Brain directly.
-
-**Also in this release:**
-
-- **Memories are scoped by project** via a `projectId` derived from the git remote. Entries stored
-  before this release stay visible everywhere rather than disappearing.
-- **Brain entries are ~38% smaller** — `terms` duplicated `Object.keys(termFreq)` and is now
-  rebuilt on load instead of stored. Existing files are read unchanged.
-- **`get_project_onboarding` works without the proxy**, falling back to a locally derived map
-  instead of returning an error on the first call of the session.
-- **`lemma-checkpoint`** *(new CLI)* captures a checkpoint from repository state, so it no longer
-  depends on the assistant remembering to call the tool. See [Session checkpoints](#-session-checkpoints).
-- **Removed the `lemma-autopilot` prompt** — it told the model to call tools unconditionally, the
-  opposite of the net-savings accounting added in v1.6.0. `lemma-turbomode` is the supported prompt.
-
----
-
-### v1.6.0 — The savings ledger can now report a loss
-
-Every release up to this one measured only what Lemma **saved**. That is single-entry bookkeeping:
-a number that can only go up is not evidence of anything, because the ledger had no way to express
-the outcome *"this session cost more than it returned."* Meanwhile Lemma's own overhead — the
-TURBOMODE prompt and 93 tool schemas injected into the model's system prompt, plus every tool
-result that lands in context — was real spend that appeared nowhere.
-
-| Change | What it does | Why it matters |
-| :--- | :--- | :--- |
-| **Cost side of the ledger** | Records `mcpInstructions` (prompt + all tool schemas, charged **once at MCP connect** — ~13,700 tokens on this repo), `toolResult` (charged on **every** call, including ones that also report a saving), and `cacheMiss`. | A session now starts visibly underwater and has to earn its way out, instead of starting at zero and only ever climbing. |
-| **Net position** | `getSnapshot()` returns `net.netTokens`, `net.netCost`, and `net.ratio` (saved ÷ spent). The terminal summary prints **`NET COST`** instead of `NET SAVED` when the ratio drops below 1.0. | The report is falsifiable. If Lemma isn't paying for itself, it says so. |
-| **`POST /api/cost-record`** *(new)* | Counterpart to `/api/savings-record`, so out-of-process callers (MCP server, CLI) can charge the ledger. Unknown sources are rejected with a 400. | Costs incurred outside the proxy were previously unrecordable. |
-| **Versioned ledger file** | `_version: 2`. Savings stay top-level so pre-v2 readers keep working; costs are additive under `_costs`. A v1 ledger loads with zeroed costs rather than failing. | No migration step, no data loss on upgrade. |
-
-**Three ways the old numbers were wrong**, now fixed:
-
-- **Cache hits were credited a hardcoded 2,000 tokens** — every semantic, synthesized, and cloud
-  hit reported the same invented figure regardless of what was actually served. Savings are now
-  measured from the cached payload that replaced the LLM call. The 2,000 placeholder survives only
-  in `stats.json` for dashboard continuity and is explicitly **barred from the ledger**: a guess
-  must not become part of a net-position claim.
-- **`pruneHistoryMessages` counted chars as tokens**, inflating history-prune savings ~4x. It now
-  converts with the same `chars / 4` heuristic used everywhere else.
-- **A cache *miss* is not charged.** The lookup is local, so a miss costs latency, not tokens.
-  Charging it an invented figure would repeat the exact error this release exists to correct.
-
-**Also fixed**: `reportSessionOverhead()` ran *after* `await trySamplingContext()`, which blocks on
-a `sampling/createMessage` round-trip that clients without sampling support never answer — so the
-overhead charge was stalled until the SDK timeout, or dropped entirely. It now runs first.
-
-**TURBOMODE prompt rewritten** at the top: it no longer promises to "multiply your LLM membership
-50x" or tell the model to poll `token_budget` every 5 turns (a scheduled call that produces a
-report instead of work, and costs tokens each time). It now states the real goal — reduce what
-enters context without costing a correct answer — and warns that a tool call which saves less than
-its own round-trip is a net loss.
-
----
-
-### v1.5.0 — Command output stops being the biggest unoptimized token sink
-
-`run_workspace_command` returned raw stdout/stderr in full — a failing `npm test` put thousands of
-lines into context to communicate three broken assertions. Long output is now distilled by
-deterministic per-format parsers (no LLM summarization: a summarizer that invents a test name is
-worse than the dump it replaced).
-
-| Format | What survives distillation |
-| :--- | :--- |
-| jest / vitest | Failing test titles, assertion reason and diff, project-local source location. Code frames and `node_modules` stack frames dropped. |
-| tsc | Grouped by file; a repeated diagnostic printed once with its positions (`TS2322 ×40 … at 1:7, 2:7, …`) instead of forty identical lines. |
-| eslint (stylish) | Grouped by file with a rule-frequency header, capped per file. |
-| anything else | Head, tail, and the error/failure lines from the middle, each with its line number, plus an explicit count of what was withheld. |
-
-Measured on this repo: a 30-failure jest run went from 32,324 → 7,183 chars (78% withheld); a
-65-error `tsc --noEmit` from 5,597 → 527 (91%).
-
-**Lossless, not lossy.** The complete output is written to disk *before* anything is trimmed and
-the reply carries a handle; the footer always states how much was withheld. `output_region` *(new
-tool)* retrieves stored output verbatim — the whole run, one named section (a failing test title or
-file path), or a line range. Small outputs pass through untouched with no handle.
-
-**Also fixed**: stderr was discarded on success. `execSync` leaves stderr attached to the parent
-unless `stdio` is overridden, so a *passing* jest or tsc run — both report on stderr — returned an
-empty "Output:". Switched to `spawnSync`, which also raises the output limit to 20MB.
+```bash
+npm install -g @nxuss/lemma
+lemma init      # auto-configures MCP for your IDE
+lemma start     # gateway + dashboard on http://localhost:8081
+```
 
 ---
 
-### v1.4.0 — Correctness-first patching, search, and memory freshness
+## ✨ What Lemma actually does
 
-An audit of the everyday MCP path — read a file, search the workspace, patch it, remember the
-answer — found the same failure mode repeating: a tool that looked done but silently degraded
-correctness or wasted tokens the moment reality diverged from the happy path. This release fixes
-that path end to end.
+- **Shared Semantic Memory ("The Brain")** — a zero-dependency local index (BM25 + Jaccard, no
+  ChromaDB/Ollama required) that persists solutions, fixes, and decisions across every project and
+  every session, with claim- and symbol-level freshness so a stale answer can't hide behind a fresh one.
+- **Verifiable caching, not marketing numbers** — `state_hash_cache` only hits when the files an
+  answer depends on are byte-identical; `token_receipt` gives a real per-session breakdown of how
+  each answer was produced instead of an invented "% saved."
+- **Privacy Firewall** — API keys, credentials, and PII are scrubbed automatically from every file
+  read and workspace search, before anything leaves your machine.
+- **Zero-token static intelligence** — dependency graphs, entropy/coupling/risk scores, and an AST
+  symbol index, computed locally with the TypeScript Compiler API. No LLM calls, no tokens.
+- **Command output distillation** — a failing `npm test`/`tsc` run is parsed by deterministic
+  per-format rules (jest, tsc, eslint) down to the failures that matter; the full output is never
+  lost, just stored and retrievable on demand.
+- **Surgical, AST-based patching** — `surgical_ast_insert` and `refactor` edit or rename by
+  compiler-verified AST location instead of asking the model to output a full-file rewrite.
+- **Infrastructure Command Center** — 22 free tools for Jenkins, OKD/OpenShift, and Terraform:
+  discover, connect, deploy, diagnose, and detect drift, all via MCP.
+- **Scoped tool surface** — of the 96 registered tools, only the ones your project shows evidence
+  of needing are advertised to the model each turn; the rest stay one `lemma_toolbox` call away.
 
-| Tool | What changed | Why |
-| :--- | :--- | :--- |
-| `apply_workspace_patch` | Cascading match: exact → whitespace-normalized → indent-anchored → fuzzy (similarity-scored, with an anti-tie margin). On total failure, the error now includes a line-diff against the closest candidate block instead of a generic "not found". | A patch built from a `read_workspace_file(compact:true)` view (comments/imports stripped, whitespace collapsed) could never byte-match the file on disk — a guaranteed failure on the most common read→edit flow, forcing an expensive full re-read every time. |
-| `search_workspace` | Respects `.gitignore`, skips binaries and files over 500KB, supports comma-separated multi-extension filters, caps results with `maxResults`, and groups matches by file (capped per file) instead of one repeated-path line per hit. Code files (`.ts/.tsx/.js/.jsx`) get symbol-level grouping — matches inside the same function/class collapse into one entry with its signature and full line list instead of raw duplicate lines. Repeating an identical query while the workspace is unchanged (tracked via a cheap mtime/size fingerprint, no content re-reads) returns the cached result instantly. | A single broad query could read 300+ files (2.6MB+) unfiltered and return 15,000+ tokens of flat, path-repeated text — often more expensive than just reading the files directly. |
-| `read_workspace_file` | Tracks the content hash last sent for each `(file, compact)` pair for the life of the MCP session. Re-reading an unchanged file returns a short `UNCHANGED` marker instead of the full content again; `force:true` bypasses it. | Re-reading the same file to verify an edit — one of the most common steps in a multi-turn coding session — was resending the full file every time, even when nothing had changed since the last read. |
-| `store_memory` / `search_memory` | `store_memory` accepts an optional `filePaths` array and records a sha256 per file. `search_memory` now splits results into **fresh** (safe to reuse) and **stale** (a tracked file changed since it was stored) — a stale hit is never returned as if it were current. | The Brain's semantic match (BM25 + Jaccard) is intentionally fuzzy so differently-phrased questions still hit — but with no invalidation, a fuzzy hit could resurface a stale answer about code that had since changed, with no signal that it was stale. |
-
-**Net effect**: the four tools an agent reaches for by default — read, search, patch, remember —
-now fail closed (a diff instead of a dead-end error) and skip redundant work automatically instead
-of requiring the calling model to remember to check first.
-
-### Files changed
-- `src/utils/PatchMatcher.ts` *(new)* — cascading match strategies + line-diff generator
-- `src/utils/WorkspaceSearch.ts` *(new)* — gitignore-aware, capped, grouped search
-- `src/utils/StructuralSearch.ts` *(new)* — AST-based symbol grouping for code file matches
-- `src/utils/SearchCache.ts` *(new)* — session-scoped, fingerprint-invalidated search cache
-- `src/utils/ReadWorkspaceCache.ts` *(new)* — session-scoped read-dedup
-- `src/subconscious/TheBrainV2.ts` — `fileHashes` on entries, `checkEntryFreshness`, `fresh`/`staleFiles` on search results
-- `src/mcp/tools.ts` — wired all of the above into `apply_workspace_patch`, `search_workspace`, `read_workspace_file`, `store_memory`, `search_memory`
+See [`CHANGELOG.md`](CHANGELOG.md) for the full, per-version history.
 
 ---
 
-### v1.3.0 — Verifiable Caching
-
-Two new tools built around a single rule: don't ask the model to trust a similarity score or a
-savings estimate — give it something it can actually verify.
-
-| Tool | Description |
-| :--- | :--- |
-| `state_hash_cache` | Reasoning cache keyed to the sha256 of the files an answer depends on. A hit only fires when those files are byte-identical to when the answer was cached — changing one line forces a guaranteed MISS, no similarity guessing. |
-| `token_receipt` | Per-session auditable ledger of how each answer was produced (exact cache hit, semantic cache hit, file read, fresh reasoning) — a real breakdown instead of a marketing "% saved" number. |
-
-Also in this release: `smarter_cache`'s match threshold moved from 0.75 → 0.8 to cut down false
-hits, `turbosqueeze` no longer touches code shown to the user (internal context only), and file
-insertions default to symbol-level `surgical_ast_insert` patches instead of full-file rewrites.
-
-### v1.2.0 — Infrastructure Command Center
-
-**22 new tools, all FREE**, for managing Jenkins, OKD/OpenShift, and Terraform deployments:
+## 💎 Free vs Pro
 
-#### 🆓 Infrastructure Tools Added in v1.2.0
+46 of the 96 registered tools work with no license; 49 require Pro. Enforced by one allowlist in
+code (`FREE_TOOLS` in `src/mcp/tools.ts`), not by narrative. A session without a license doesn't
+even advertise the Pro tools — they stay registered and discoverable via `lemma_toolbox`.
 
-| Tool | Category | Description |
+| | Free (46) | Pro (49) |
 | :--- | :--- | :--- |
-| `infra_discover` | Discovery | Auto-detect Jenkins, OKD, and Terraform in the environment |
-| `infra_connect` | Discovery | Connect to an infrastructure provider with credentials |
-| `infra_status` | Monitoring | Consolidated status of all connected providers |
-| `infra_health_check` | Monitoring | Detailed health check with latency and version info |
-| `infra_diagnose` | Troubleshooting | Analyze issues and suggest fixes (caches solutions in TheBrain) |
-| `infra_analyze_monolith` | Migration | Analyze monolith codebase for microservice migration |
-| `infra_suggest_split` | Migration | Suggest microservice split points based on coupling analysis |
-| `jenkins_generate_pipeline` | CI/CD | Generate Jenkinsfile (standard or multibranch) |
-| `jenkins_trigger_build` | CI/CD | Trigger Jenkins build (semi-automated) |
-| `jenkins_build_status` | Monitoring | Get Jenkins build status, duration, and URL |
-| `jenkins_logs` | Troubleshooting | Get last 80 lines of Jenkins build console output |
-| `okd_generate_manifests` | Deploy | Generate OKD manifests (DC, BC, IS, Route, Service) |
-| `okd_apply` | Deploy | Apply OKD manifests (semi-automated with dry-run) |
-| `okd_status` | Monitoring | Compact pod/build/route status summary |
-| `okd_logs` | Troubleshooting | Get pod logs filtered by severity |
-| `okd_events` | Troubleshooting | Recent cluster events for debugging |
-| `okd_describe` | Troubleshooting | Describe any OKD resource |
-| `okd_route_url` | Deploy | Get external URL for an OKD route |
-| `terraform_plan` | IaC | Run terraform plan (returns only changes) |
-| `terraform_apply` | IaC | Run terraform apply (semi-automated) |
-| `terraform_state_list` | Monitoring | List resources in Terraform state |
-| `terraform_drift` | Troubleshooting | Detect configuration drift |
-
-#### CLI Commands
-
-```bash
-lemma infra discover                          # Auto-detect providers
-lemma infra connect <provider>                # Connect with credentials
-lemma infra status                            # Dashboard of all providers
-lemma infra health                            # Detailed health check
-lemma infra deploy jenkins --project <name>   # Deploy via Jenkins
-lemma infra deploy okd --project <ns>         # Deploy via OKD
-lemma infra logs <provider> <target>          # Get logs
-lemma infra diagnose                          # General diagnosis
-lemma infra terraform plan                    # Terraform plan
-lemma infra terraform apply                   # Terraform apply
-lemma infra analyze monolith                  # Analyze monolith for migration
-```
-
-#### Configuration
+| **Caching & memory** | `smarter_cache`, `state_hash_cache`, `token_receipt`, `search_memory`, `store_memory`, `token_budget` | `get_telepathic_hints`, `query_hybrid_consensus`, `semantic_dedup_guard`, `local_semantic_autofix` |
+| **Reading & context** | `read_workspace_file`, `scrub_privacy`, `import_tree_context`, `bulk_file_digest`, `auto_context_bundle`, `git_blame_heat`, `type_coverage_report` | `get_ast_hologram`, `smart_file_slice`, `get_symbol_surgical_context`, `diff_only` |
+| **Writing & workspace** | — | `write_workspace_file`, `apply_workspace_patch`, `multi_file_patch`, `search_workspace`, `run_workspace_command`, `validate_patch_sandbox`, `surgical_ast_insert` |
+| **Static analysis** | — | `entropy_score`, `coupling_radar`, `pattern_fossil`, `precrime_static`, `dead_export_necromancer`, `depgraph`, `refactor`, `ast_flow_visualizer`, `cognitive_map` |
+| **Infrastructure** | All 22: `infra_*`, `jenkins_*`, `okd_*`, `terraform_*` | — |
+| **Automation & PR review** | `conversation_checkpoint`, `test_autofix_interceptor`, `prompt_pattern_cache` | `review_diff`, `review_pr`, `pr_status`, `test_oracle`, `auto_heal`, AutoPilot, Silent Patch Watcher |
 
-Add to `lemma.config.json`:
+Get Pro: `lemma activate <key>` → [lemma.nxus.studio/upgrade](https://lemma.nxus.studio/upgrade)
 
-```json
-{
-  "infra": {
-    "jenkins": {
-      "url": "https://jenkins.example.com",
-      "credentialsId": "github-creds"
-    },
-    "okd": {
-      "server": "https://api.okd.example.com:6443",
-      "project": "my-namespace",
-      "route": { "tls": true, "hostname": "app.example.com" }
-    },
-    "terraform": {
-      "backend": "s3",
-      "bucket": "my-terraform-state",
-      "region": "us-east-1"
-    }
-  }
-}
-```
-
-Or use environment variables: `JENKINS_URL`, `JENKINS_USERNAME`, `JENKINS_API_TOKEN`, `OKD_SERVER`, `OKD_TOKEN`, `OKD_PROJECT`, `TF_BACKEND`, `TF_BUCKET`, `TF_REGION`.
-
-**Optimized for token savings**: Infrastructure tools use TheBrain caching, compressed responses, lazy loading, and semantic dedup to minimize context usage.
-
----
-
-### v1.1.0 — Token Avalanche
-
-**11 new tools, all FREE**, focused on maximizing token savings without requiring Pro:
-
-#### 🆓 Free Tools Added in v1.1.0
-
-| Tool | Token Savings | Description |
-| :--- | :--- | :--- |
-| `file_fingerprint` | -60-70% re-reads | SHA256 hash cache per file. Returns 'unchanged' when hash matches, skipping full re-reads. |
-| `git_blame_heat` | -1000-2000 tok/session | Git blame + risk scoring per line. Identifies hotspots and high-risk authors. Zero LLM cost. |
-| `type_coverage_report` | -1000 tok/review | TypeScript type safety score via AST. Reports typed vs untyped declarations, `any` count, score 0-100. |
-| `import_tree_context` | -3000 tok/exploration | Bidirectional import graph. Shows what imports what, external deps, reverse dependencies. |
-| `read_token_budgeted` | -70-90% file reads | Read file with hard token limit. Returns only most relevant sections via AST-based scoring. |
-| `bulk_file_digest` | -80% round-trips | Read N files in one call, return compressed digest. Saves round-trip overhead. |
-| `auto_context_bundle` | -75% round-trips | One-call context: content + imports + schema types + Brain hints. Replaces 4-5 separate tool calls. |
-| `repeat_guard` | -10-15% output | Jaccard similarity check against recent outputs. Prevents duplicate explanations. |
-| `conversation_checkpoint` | -3000-5000 tok/session | Save/load session state to `.lemma/session/`. Prevents re-explaining context across turns. |
-| `test_autofix_interceptor` | -5000 tok/debugging | Run tests + search Brain for matching fixes. Returns failures with suggested fixes from past sessions. |
-| `prompt_pattern_cache` | -20-30% prompts | Find/store optimized prompt templates. Auto-merges similar patterns. Tracks hit counts. |
-
-**Updated TURBOMODE prompt** with 6 new automatic behaviors (rules 4b-4d, 8-12).
-
-#### Other v1.1.0 Changes
-- 199 tests passing (28 new test files)
-- Zero new npm dependencies
-- All new tools are FREE (no Pro license required)
+Full per-tool listing: `lemma_toolbox { "action": "list" }`.
 
 ---
 
 ## 🎚️ Tool profiles
 
-Every tool schema an MCP server advertises is injected into the model's system prompt and re-sent
-on **every request** of the session. Advertising all 95 tools costs ~11,600 tokens per turn — much
-of it schemas for tools a given project can never use.
-
-Lemma advertises a scoped surface instead. Nothing is removed: every tool stays registered and
-callable, and `lemma_toolbox` reaches the ones whose schemas were withheld.
-
-| Profile | Advertises |
-| :--- | :--- |
-| `auto` *(default)* | Core tools, plus situational groups the repo shows evidence for |
-| `core` | Core tools only |
-| `full` | Everything, as before v1.7.0 |
+Every advertised tool schema is re-sent on **every request** of the session — advertising all 96
+costs ~11,600 tokens/turn. Lemma advertises a scoped surface instead: core tools always, situational
+groups (e.g. infrastructure) only when the repo shows evidence for them. Nothing is removed —
+everything stays registered and reachable via `lemma_toolbox`.
 
 ```jsonc
 // lemma.config.json
-{ "mcp": { "toolProfile": "full" } }   // or set LEMMA_TOOL_PROFILE=full
+{ "mcp": { "toolProfile": "full" } }   // "auto" (default) | "core" | "full"
 ```
 
-**Core** covers workspace reading and navigation, the patch/validate write path, AST context,
-caching (`state_hash_cache`, `smarter_cache`, `search_memory`, `store_memory`), routing advice, and
-the ledger. **Situational groups** are advertised on evidence — the infrastructure group when a
-`Jenkinsfile`, `kustomization.yaml`, `.openshift/`, or a `.tf` file is present, or a provider is
-already connected.
-
-Reaching anything else:
-
 ```jsonc
 lemma_toolbox { "action": "list",   "query": "terraform drift" }   // what exists
 lemma_toolbox { "action": "schema", "tool":  "terraform_drift" }   // its inputs
 lemma_toolbox { "action": "call",   "tool":  "terraform_drift", "args": {} }
 ```
 
-`token_budget` reports the profile in use, advertised vs. hidden counts, and what the advertised
-schemas actually cost this session.
+`token_budget` reports the profile in use and what the advertised schemas actually cost this session.
 
 ---
 
-## 💾 Session checkpoints
-
-`conversation_checkpoint` saves what a session established so the next one doesn't re-derive it —
-but it only runs if the assistant remembers to call it at the end, which is not something to build
-on. `lemma-checkpoint` derives a checkpoint from repository state instead:
+## 🛠️ CLI reference
 
-```bash
-lemma-checkpoint [projectRoot] [--summary "text"]
-```
+| Command | Action |
+| :--- | :--- |
+| `lemma init` | Bootstraps config and auto-configures MCP for OpenCode, Claude Desktop, Cursor, Windsurf, Kiro, VS Code. |
+| `lemma start` | Launches proxy, cache engine, and dashboard at `http://localhost:8081`. |
+| `lemma stop` / `lemma status` / `lemma stats` | Stop, health check, and net token/cost report (reports `NET COST` when a session is underwater). |
+| `lemma mcp` | Starts the stdin/stdout MCP server for IDE integration. |
+| `lemma heal` / `lemma autopilot` / `lemma watch` | Diagnose+repair the last crash / toggle autonomous fix-apply / silent patch-only watcher. |
+| `lemma patches` / `lemma apply <id>` / `lemma discard <id>` | List, apply, or discard a pending Silent Patch Watcher fix. |
+| `lemma activate <key>` | Activate a Pro license. |
+| `lemma-checkpoint [projectRoot]` | Derive a session checkpoint from repo state (branch, changed files, commits) with no assistant call. |
+| `lemma-brain-ingest [projectRoot] [--changelog]` | Feed The Brain from git commits and `CHANGELOG.md`, incrementally. |
 
-It records the branch, changed files, and recent commits to `<project>/.lemma/session/`, exits 0
-even outside a git repository, and is meant to be wired to your host's session-end event:
+Wire the standalone bins into hooks so memory doesn't depend on the assistant remembering to call a tool:
 
 ```jsonc
 // ~/.claude/settings.json
@@ -448,410 +124,39 @@ even outside a git repository, and is meant to be wired to your host's session-e
   "command": "lemma-checkpoint \"${CLAUDE_PROJECT_DIR:-$PWD}\"" }] }] } }
 ```
 
-Decisions made and tasks left pending exist only in the conversation, so an automatic capture
-leaves those fields empty rather than inventing them — a checkpoint saved by the assistant stays
-the richer record when one exists.
-
----
-
-## 🧠 Feeding The Brain from project history
-
-`store_memory` also depends on the assistant remembering to call it. `lemma-brain-ingest` pulls
-memories from sources that already exist and don't need an assistant in the loop:
-
-```bash
-lemma-brain-ingest [projectRoot] [--max N] [--changelog] [--no-commits]
-```
-
-- Every git commit (message + files touched) becomes one Brain entry, so `search_memory` and
-  `get_telepathic_hints` can recall *why* a change happened, not just what the code looks like now.
-- `--changelog` also ingests `CHANGELOG.md` (falls back to `docs/CHANGELOG.md`) — one entry per release, parsed
-  directly, no LLM involved.
-
-A marker file under `<project>/.lemma/session/` tracks the last commit and changelog version
-ingested, so this is safe to run after every commit and safe to run by hand for a one-time
-backfill of existing history — both take the same incremental path and never double-store.
-Wire it to a post-commit hook to keep it current automatically:
-
 ```bash
 echo 'lemma-brain-ingest "$(git rev-parse --show-toplevel)" &' >> .git/hooks/post-commit
 chmod +x .git/hooks/post-commit
 ```
 
----
-
-## 💎 Free vs Pro
-
-Of the 95 registered tools, 46 work with no license and 49 require Pro. This split is enforced by
-one allowlist in code (`FREE_TOOLS` in `src/mcp/tools.ts`), not by narrative — if a tool isn't in
-that list, it's Pro, regardless of what a description elsewhere implies.
-
-Since v1.9.0, a session without a license does not *advertise* the Pro tools either. Sending their
-schemas every turn only to refuse the call charged roughly 3k tokens per turn for capabilities the
-session could not use. They remain registered and discoverable through `lemma_toolbox`, which is
-where you find out a capability exists and what unlocks it.
-
-### 🆓 Free (46 Tools)
-
-These tools work **without a Pro license**. Activate them with just `lemma init`:
-
-| Tool | What It Does |
-| :--- | :--- |
-| `smarter_cache` | Semantic cache lookup before reasoning from scratch |
-| `state_hash_cache` | Reasoning cache keyed to file content hashes — exact invalidation |
-| `token_receipt` | Auditable per-session ledger of how each answer was produced |
-| `search_memory` | Semantic search across The Brain, all projects |
-| `store_memory` | Persist verified solutions/fixes/decisions into The Brain |
-| `get_project_history` | Git log + checkpoints + Brain memories in one call |
-| `token_budget` | Session token/cost dashboard, including Lemma's own overhead |
-| `squeeze_prompt` | Compress code blocks before they enter your own context |
-| `turbosqueeze` | Extreme internal-context compression (never shown to the user) |
-| `read_workspace_file` | Read a file (or a line range) with auto-compression, privacy scrubbing, and real line numbers |
-| `scrub_privacy` | Mask PII, API keys, and secrets from any text block |
-| `summarize_long_text` | Summarize via local Ollama, falls back to truncation |
-| `lemma_toolbox` | List, inspect, and call tools whose schemas were withheld |
-| `file_fingerprint` | File hash cache — avoid re-reads |
-| `git_blame_heat` | Git blame + risk scoring |
-| `type_coverage_report` | TypeScript type safety score |
-| `import_tree_context` | Bidirectional import graph |
-| `read_token_budgeted` | Token-budgeted file reader |
-| `bulk_file_digest` | Multi-file digest in one call |
-| `auto_context_bundle` | Full context bundle per file |
-| `repeat_guard` | Duplicate output detector |
-| `conversation_checkpoint` | Session state save/load |
-| `test_autofix_interceptor` | Test failure → Brain auto-fix |
-| `prompt_pattern_cache` | Reusable prompt templates |
-| `infra_discover` | Auto-detect Jenkins, OKD, Terraform |
-| `infra_connect` | Connect to infrastructure providers |
-| `infra_status` | Consolidated infrastructure status |
-| `infra_health_check` | Detailed provider health check |
-| `infra_diagnose` | Analyze and fix infrastructure issues |
-| `infra_analyze_monolith` | Analyze monolith for microservice migration |
-| `infra_suggest_split` | Suggest microservice split points |
-| `jenkins_generate_pipeline` | Generate Jenkinsfile |
-| `jenkins_trigger_build` | Trigger Jenkins builds |
-| `jenkins_build_status` | Jenkins build status |
-| `jenkins_logs` | Jenkins build logs |
-| `okd_generate_manifests` | Generate OKD manifests |
-| `okd_apply` | Apply OKD manifests |
-| `okd_status` | OKD pod/build/route status |
-| `okd_logs` | OKD pod logs |
-| `okd_events` | OKD cluster events |
-| `okd_describe` | Describe OKD resources |
-| `okd_route_url` | Get OKD route URL |
-| `terraform_plan` | Terraform plan |
-| `terraform_apply` | Terraform apply |
-| `terraform_state_list` | List Terraform state resources |
-| `terraform_drift` | Detect Terraform drift |
-
-### 💎 Pro (49 Tools)
-
-All remaining tools require a Pro license. Activate with `lemma activate <key>` → [Get Pro](https://lemma.nxus.studio/upgrade)
-
-| Category | Tools |
-| :--- | :--- |
-| **AI Proxy** | OpenAI/Anthropic/Gemini proxy, exact-match cache, complexity router |
-| **The Brain (advanced)** | `get_telepathic_hints`, `query_hybrid_consensus`, `semantic_dedup_guard`, `local_semantic_autofix` — basic search/store/smarter_cache are Free |
-| **Zero-Token Static** | `entropy_score`, `coupling_radar`, `pattern_fossil`, `git_heatmap_risk`, `precrime_static`, `dead_export_necromancer` |
-| **Architecture** | `depgraph`, `refactor`, `ast_flow_visualizer`, `imports_skeleton_resolver`, `cognitive_map`, `file_intent_index` |
-| **Code Intelligence** | `get_ast_hologram`, `validate_patch_sandbox`, `surgical_ast_insert`, `get_symbol_surgical_context`, `smart_file_slice`, `diff_only` |
-| **Workspace writes** | `write_workspace_file`, `create_workspace_file`, `apply_workspace_patch`, `multi_file_patch`, `search_workspace`, `list_workspace_dir`, `run_workspace_command`, `output_region` |
-| **Optimization (advanced)** | `wormhole_squeeze`, `compress_context`, `prune_conversation_history` — `turbosqueeze`, `squeeze_prompt`, `token_budget` are Free |
-| **PR Review** | `review_diff`, `review_pr`, `pr_status`, `generate_pr_workflow` |
-| **Session & Automation** | `test_oracle`, `schema_extract`, `changelog_auto`, `env_snapshot`, `migration_tracer`, `spec_to_stub`, `batch_tool_calls`, `get_routing_advice`, `get_project_onboarding`, `auto_heal`, `semantic_grep` |
-| **Automation (background)** | AutoPilot, Auto-Heal, Silent Patch Watcher |
-
-> **The MCP server itself is Pro.** All 49 Pro tools — the advanced Brain layer, PreCrime, AST
-> Hologram, `depgraph`, `refactor`, every workspace-write tool, and every PR review tool — require a
-> Pro license. The 46 Free tools above (including all 22 Infrastructure tools and `read_workspace_file`
-> with its automatic privacy scrubbing) are accessible without activation.
-
----
-
-## ⚡ What's in the Pro MCP
-
-### 🏗️ Infrastructure Command Center *(NEW in v1.2.0)*
-**Lemma is now your single pane of glass for Jenkins, OKD/OpenShift, and Terraform.** All 22 infrastructure tools are FREE and integrate with TheBrain for intelligent caching of deploy patterns and troubleshooting solutions.
-
-- **Jenkins**: Generate Jenkinsfiles, trigger builds, check status, get logs — all via MCP
-- **OKD/OpenShift**: Generate DeploymentConfig, BuildConfig, ImageStream, Route manifests. Apply with dry-run. Monitor pods, builds, events
-- **Terraform**: Plan, apply, list state resources, detect configuration drift
-- **Monolith Analysis**: Analyze your codebase for microservice migration — identifies modules, coupling, and suggests split points
-- **Token-Optimized**: TheBrain caches successful deploys and troubleshooting patterns. Compressed responses. Lazy provider loading
-
-```bash
-# Quick start
-lemma infra connect jenkins -u https://jenkins.example.com
-lemma infra connect okd -u https://api.okd.example.com:6443 -t $OKD_TOKEN
-lemma infra status
-lemma infra deploy okd -n my-app -i my-image:latest
-```
-
-### 🧠 Shared Semantic Memory — The Brain (Zero-Dependency)
-Lemma maintains a persistent semantic cache index (`TheBrainV2`) using Okapi BM25 + Jaccard re-ranking and Bloom Filters that runs entirely on your local machine with NO external ML dependencies (no ChromaDB, no Ollama required). Every solution, bug fix, and architecture decision you work through gets stored and semantically indexed globally across all your projects. Future sessions can retrieve this knowledge in milliseconds (<10ms) — saving you thousands of tokens.
-
-### 🛡️ Privacy Firewall (Semantic Scrubber)
-**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.
-
-### 🔮 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.
-
-### 🧮 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.
-
-### 🗺️ AST Hologram — Zero Tokens
-Scans the workspace and returns a dense JSON index of exported symbols with file paths and line numbers. Lemma now routes this through an internal language adapter layer: TypeScript keeps full compiler-backed behavior, `.NET` uses a native adapter path, and unsupported languages return an explicit fallback index instead of pretending semantic parity.
-
-### 📡 `depgraph` — Real-Time Dependency Graph
-**Architecture-aware blast radius analysis.** Builds a real-time, bidirectional dependency graph for any file in the workspace using the TypeScript Compiler API — zero LLM calls, zero tokens. Shows exactly what a file imports, what imports it (reverse dependencies), and what symbols it exports.
-
-```
-📦 src/services/pantry.ts
-├── importa:
-│   ├── src/lib/utils/ingredient-parser.ts  → parseIngredientString, normalizeUnit
-│   └── src/db/prisma.ts                    → PrismaClient
-├── es importado por:
-│   ├── src/app/actions/generate-recipe.ts
-│   └── src/components/PantryWidget.tsx
-└── exporta:
-    ├── applyRecipeDeductions
-    └── getPantryBalance
-```
-
-Supports `--depth` (1-5), `--format text|mermaid|json`, `--reverse`, `--circular` (cycle detection), and `--external` (include node_modules).
-
-### 🔧 `refactor` — Declarative Codemod Engine
-**Multi-file refactoring with surgical precision.** Rename any symbol across the entire workspace or move files updating all importers — using the TypeScript Compiler API for accurate AST-based reference detection. Zero LLM calls.
-
-**`rename`** — Finds every reference to a symbol (via AST, not text search) and renames it everywhere:
-```bash
-# Preview first
-lemma refactor --operation rename --from "applyRecipeDeductions" --to "deductPantryIngredients" \
-  --file src/services/pantry.ts --dryRun
-
-# Apply with TypeScript verification
-lemma refactor --operation rename --from "applyRecipeDeductions" --to "deductPantryIngredients" \
-  --file src/services/pantry.ts --tscCheck
-```
-
-**`move`** — Moves a file physically and rewires every import path in the workspace:
-```bash
-lemma refactor --operation move \
-  --from src/lib/validation/recipe.schema.ts \
-  --to src/lib/schemas/recipe.ts \
-  --tscCheck
-```
-
-Supports `--dryRun` (unified diff preview), `--tscCheck` (post-refactor type verification), and `--backup` (`.bak` files).
-
-## 🌐 Multi-Language Semantic Runtime
-
-Lemma now separates universal MCP tools from language-specific semantic tooling.
-
-| Capability Tier | Meaning |
-| :--- | :--- |
-| `full` | Native semantic adapter with language-aware guarantees. |
-| `partial` | Some language awareness exists, but not full semantic parity. |
-| `fallback` | Safe read-only or heuristic response. No semantic safety claim. |
-| `unsupported` | Mutation is refused until a real adapter exists. |
-
-### Current semantic support
-
-| Tool | TypeScript / JavaScript | .NET | Python / Go / Java (today) |
-| :--- | :--- | :--- | :--- |
-| `get_ast_hologram` | `full` | `full` | `fallback` |
-| `validate_patch_sandbox` | `full` via `tsc` | `full` via `dotnet build` when CLI is available | `fallback` |
-| `depgraph` | `full` | `full` | `fallback` |
-| `refactor` | `full` | `unsupported` | `unsupported` |
-
-Universal tools such as file reads, workspace search, memory, onboarding, prompt compression, and privacy scrubbing remain language-agnostic. Semantic tools keep the same MCP names, but are now routed through adapter and runtime registries internally.
-
-### 🚦 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.
-
-### ✂️ 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.
-
-### 🛸 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.
-
-### 🩺 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.
-
-### 🕵️ Silent Patch Watcher
-**Magia negra, no invasiva.** Like Autopilot, but **never touches your code**. Lemma watches your project silently, detects TypeScript errors on save, generates fixes, and stores them as patches in `.lemma/patches/`. You review with `lemma patches` and apply with `lemma apply <id>`.
-
-```
-lemma watch              ← starts silently watching src/
-[youse save a file with a bug]
-📬 macOS notification    ← "Lemma: TS2322 in route.ts:42"
-lemma patches            ← shows 1 pending fix
-lemma apply ts2322-...   ← applies the fix
-npm run build            ← ✅ passes
-```
-
-### 🧬 `get_symbol_surgical_context` — Surgical Symbol Context
-**Saves up to 90% input tokens.** Instead of reading complete dependency source files, this tool parses your workspace via TS Compiler AST and extracts ONLY the targeted symbol implementation along with the precise function/class signatures of all its direct workspace imports.
-
-### ⚙️ `surgical_ast_insert` — AST Surgical Code Injector
-**Saves up to 95% output tokens.** Removes the need for the LLM to output massive file diffs or rewrite entire files. The LLM only outputs the exact function snippet, and Lemma compiles it surgically into the class/scope AST at the specified anchor point.
-
-### 🩹 `local_semantic_autofix` — Offline Self-Healing
-**Resolves compilation/runtime crashes in <15ms with 0 tokens.** When your tests or compilers crash, Lemma queries the global error index in `TheBrainV2`. If a matching traceback fix is found in memory (solved in this or any other repo on your machine), it applies the resolution instantly.
-
-### 💰 `generate_executive_roi_report` — Corporate ROI Ledger
-Generates a complete executive Markdown/PDF-ready report of total direct API dollars saved, developer hours reclaimed from caching, security masking events, and scalability financial projections for engineering managers.
-
-### 🌀 `wormhole_squeeze` — Reversible Code Compression
-Compresses your source code using non-colliding mathematical unicode symbols (like `⨃`, `⨂`, `⨁`) and temporary aliases to shrink file sizes by up to 70% while keeping it 100% reversible.
-
-### 📐 `smart_file_slice` — Context Slicing
-Reads only the relevant lines of a file around a keyword or query, avoiding sending the entire file to the LLM. Saves ~85% of input tokens.
-
-### 🧪 `test_oracle` — Smart Test Failure Filter
-Executes unit tests locally and returns ONLY the failing test cases with compressed stack traces, keeping successful test logs out of the prompt. Saves ~90% tokens.
-
-### 📄 `schema_extract` — High-Level Type Extractor
-Extracts TS interfaces, types, Zod schemas, or Prisma schemas via AST, stripping out all execution and implementation code. Saves ~80% tokens.
-
-### 📜 `changelog_auto` — Zero-Token conventional changelogs
-Generates a conventional commit changelog directly from git history logs with 0 LLM queries.
-
-### 🪚 `spec_to_stub` — Spec Mock Stub Creator
-Parses interfaces and types to output a mock stub template object configuration using pure AST.
-
-### 📋 `env_snapshot` — Env Dependency Capture
-Captures node/npm versions, package.json dependencies, and present `.env` keys (hiding private values/credentials) for instant environment onboarding.
-
-### 🧭 `migration_tracer` — Prisma Migration Analyst
-Traces recent schema modifications (creates, alters, drops) from local Prisma migration files without reading the full SQL code.
-
-### 🩹 `multi_file_patch` — Multi-File Search-and-Replace
-Applies search-and-replace patches to multiple files in a single call. Eliminates round-trips for multi-file refactoring.
-
-### 📁 `file_intent_index` — Codebase Categorizer
-Automatically groups workspace files by domain intent (auth, routing, config, schemas) for lightning fast navigation.
-
-### 🧠 `cognitive_map` — Auto-Cognitive Knowledge Graph
-A persistent, auto-updating structural knowledge graph representing codebase domains, patterns, decisions, and known bugs at `~/.lemma-cache/cog_map.json`.
-
-### 🔍 `semantic_grep` — BM25 Concept Search
-Token relevance concept searching across your codebase, allowing natural language queries instead of strict substring matches.
-
-### 📦 `imports_skeleton_resolver` — Import Signature Mapper
-Scans imports inside a file and retrieves exported TypeScript signatures from local dependencies in a unified reference sheet. Saves ~85% reading tokens.
-
-### 🎨 `ast_flow_visualizer` — Flowchart Generator
-Compiles any TS function's control flow statements (loops, ifs, try-catches) into an interactive visual Mermaid diagram rendered directly in markdown.
-
----
-
-## 🚀 Quick Start (Zero Config)
-
-```bash
-# Install globally
-npm install -g @nxuss/lemma
-
-# Initialize (auto-configures local DB and MCP for your IDEs)
-lemma init
-
-# Start the gateway + dashboard
-lemma start
-```
-
----
-
-## 🛠️ CLI Reference
-
-| Command | Action |
-| :--- | :--- |
-| `lemma init` | Bootstraps config and auto-configures MCP for OpenCode, 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` | Health of all modules and active connections. |
-| `lemma stats` | Real-time token and cost metrics — savings, Lemma's own overhead, and the net position between them. Reports `NET COST` when the session is underwater. |
-| `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 autopilot` | Toggle autonomous background watcher mode (auto-applies fixes). |
-| `lemma watch` | Silent background watcher — saves patches without touching code. |
-| `lemma patches` | List available patches (`--all`, `--pending`). |
-| `lemma apply <id>` | Apply a pending fix patch. |
-| `lemma discard <id>` | Discard a pending fix patch. |
-| `lemma activate <key>` | Activate Pro license for full MCP access. |
-| `lemma-checkpoint [projectRoot]` | Standalone bin: derive a session checkpoint from repo state (branch, changed files, recent commits) without an assistant call. See [Session checkpoints](#-session-checkpoints). |
-| `lemma-brain-ingest [projectRoot]` | Standalone bin: feed The Brain from git commits and `CHANGELOG.md`, incrementally. See [Feeding The Brain from project history](#-feeding-the-brain-from-project-history). |
-
-### Customizing via `lemma.config.json`
+Customize via `lemma.config.json`:
 
 ```json
 {
-  "system": {
-    "clipboardWatcher": { "disabled": false }
-  },
-  "mcp": {
-    "allowedCommandPrefixes": ["npm", "git", "tsc", "your-custom-tool"]
-  }
+  "system": { "clipboardWatcher": { "disabled": false } },
+  "mcp": { "allowedCommandPrefixes": ["npm", "git", "tsc", "your-custom-tool"] }
 }
 ```
 
 ---
 
-## 🔌 MCP Integration
-
-Add Lemma to any MCP-compatible IDE in seconds:
+## 🔌 MCP integration
 
-### OpenCode (Terminal AI)
-Just run `lemma init`. Lemma automatically registers its MCP server in your `~/.opencode.json` and injects its autonomous rules so OpenCode works with zero configuration.
-
-### Cursor / Windsurf / Kiro / Antigravity
-1. Go to **Settings → MCP**
-2. Add new server: **Command** = `lemma mcp`
-
-### Claude Desktop
-```json
-{
-  "mcpServers": {
-    "lemma": {
-      "command": "npx",
-      "args": ["-y", "@nxuss/lemma", "mcp"]
-    }
-  }
-}
-```
+| Client | Setup |
+| :--- | :--- |
+| OpenCode | `lemma init` — registers itself in `~/.opencode.json`, zero config. |
+| Cursor / Windsurf / Kiro / Antigravity | Settings → MCP → add server, command `lemma mcp`. |
+| Claude Desktop | Add to `mcpServers`: `{ "lemma": { "command": "npx", "args": ["-y", "@nxuss/lemma", "mcp"] } }` |
 
-Once connected, your IDE gains access to all **95 MCP tools** (46 Free + 49 Pro — see
-[Free vs Pro](#-free-vs-pro) for the full, current split) and Lemma auto-injects the TurboMode
-system prompt on handshake. By default only the tools your project shows evidence of needing are
-*advertised* each turn — see [Tool profiles](#-tool-profiles) — but every tool is registered and
-reachable via `lemma_toolbox` regardless of profile.
-
-### ⚡ TurboMode Auto-Injection
-
-When connected via `lemma mcp`, Lemma auto-injects its system prompt on handshake. The real,
-current prompt (`LEMMA_TURBOMODE_PROMPT` in `src/mcp/prompts.ts`) states the goal — reduce what
-enters context without ever costing a correct answer — and enforces it with rules including:
-
-- A tool call costs tokens too: expect a call to save more than its own round-trip, or skip it.
-- `lemma_toolbox` reaches every tool whose schema was withheld from this session — check it
-  before saying a capability is missing.
-- Compression (`turbosqueeze`, `wormhole_squeeze`, `squeeze_prompt`) is for the model's own
-  context only; the user always gets the real, uncompressed file.
-- `smarter_cache` hits must be disclosed as cached, never presented as freshly reasoned, and
-  re-verified before acting on them.
-- `state_hash_cache` (exact file-hash invalidation) is preferred over `smarter_cache` (semantic
-  similarity) whenever the answer depends on specific files.
-- `store_memory` only after a solution is actually verified — an unverified fix stored here
-  becomes a false cache hit later.
-- `get_routing_advice` before assuming a mechanical task needs the biggest available model.
-- `surgical_ast_insert` by default for adding to an existing file, instead of rewriting it whole.
-- `token_receipt` for "how much did we save," never an invented estimate.
+Once connected, Lemma auto-injects its TurboMode system prompt on handshake — states the goal
+(reduce what enters context without ever costing a correct answer) and enforces it: a tool call
+must save more than its own round-trip, `smarter_cache` hits are disclosed as cached and
+re-verified before being acted on, `store_memory` only fires after a solution is verified, and
+compression is always for the model's own context — the user gets the real file.
 
 ---
 
-## 📡 MCP Resources
+## 📡 MCP resources
 
 | Resource URI | Description |
 | :--- | :--- |
@@ -865,57 +170,25 @@ enters context without ever costing a correct answer — and enforces it with ru
 
 ## 🔒 Security
 
-### Network Binding
-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
-```
-
-### MCP Command Allowlist
-`run_workspace_command` only executes commands from an allowlist. It is deny-by-default, but the
-defaults cover the toolchains a normal repo builds and tests with — JS/TS (`npm`, `npx`, `pnpm`,
-`tsc`, `jest`, `vitest`, `eslint`), Python (`python`, `pytest`, `ruff`), Go, Rust, Ruby, JVM,
-`make`, version control (`git`, `gh`), read-only shell utilities (`ls`, `grep`, `rg`, `sed`, `awk`,
-`find`), and container/infra CLIs (`docker`, `kubectl`, `terraform`).
+**Network binding.** Binds only to `127.0.0.1` by default — not network-accessible unless you set
+`LEMMA_BIND_HOST=0.0.0.0` and enable `AUTH_ENABLED`/`AUTH_REQUIRE_API_KEY`/`AUTH_ALLOWED_ORIGINS`.
 
-A command missing from this list is not a command prevented: the agent gets a refusal, then runs the
-same thing through an unrestricted shell where Lemma can neither distil the output nor account for
-it. The list is scoped to keep that from happening for ordinary development work.
-
-Extend for your project in `lemma.config.json`:
-```json
-{
-  "mcp": {
-    "allowedCommandPrefixes": ["your-tool", "another-cmd"]
-  }
-}
-```
-
-See [`.env.security.example`](.env.security.example) for all security-related environment variables.
+**Command allowlist.** `run_workspace_command` is deny-by-default, with defaults covering normal
+JS/TS, Python, Go, Rust, Ruby, JVM, `make`, git/gh, read-only shell utilities, and container/infra
+CLIs. Extend via `lemma.config.json` → `mcp.allowedCommandPrefixes`. See
+[`.env.security.example`](.env.security.example) for every security-related env var.
 
 ---
 
-## 🦜 SDK Integrations
+## 🦜 SDK integrations & proxy mode
 
-### CrewAI
 ```typescript
 import { LemmaCrewAIProvider } from '@nxuss/lemma/crewai';
-
 const crew = new LemmaCrewAIProvider({ agents: [...] });
 ```
 
----
-
-## 🔄 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`
+Point any OpenAI-compatible tool at `http://localhost:8081/v1` for transparent caching and privacy
+(Cursor: Settings → Models → Override Base URL; VS Code/Continue: `apiBase`).
 
 ---