@nxuss/lemma 1.40.0 → 1.41.0

package/README.md

@@ -1,9 +1,9 @@
 # 🧠 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)
-[![MCP](https://img.shields.io/badge/MCP-91%20tools-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
-[![Local-first](https://img.shields.io/badge/local--first-no%20cloud%20required-success?style=flat-square)](https://github.com/Nxusbets/lemma)
+![License](https://img.shields.io/npm/l/@nxuss/lemma.svg?color=blue&style=flat-square)
+![MCP](https://img.shields.io/badge/MCP-91%20tools-ff69b4?style=flat-square)
+![Local-first](https://img.shields.io/badge/local--first-no%20cloud%20required-success?style=flat-square)
 
 **A memory your AI agent can verify, and a context window that only holds what matters.**
 
@@ -19,6 +19,12 @@ lemma init      # wires Claude Code, Cursor, Codex, Windsurf, Kiro, OpenCode, Mu
 
 That's it: your agent now has Lemma's tools. The dashboard opens at `http://localhost:8081/dashboard/`.
 
+> **Run `lemma init` in every project, and again after each upgrade.** `npm install -g` updates Lemma's
+> code, but part of what Lemma does lives in files `init` writes into *your project*: the rules your agent
+> reads (`CLAUDE.md` / `AGENTS.md`), the pre-approved tool permissions, and the hooks for the other clients.
+> Without it you keep the old rules and keep seeing permission prompts. Then reconnect the MCP server
+> (`/mcp` in Claude Code) so the running session loads the new build. [What an upgrade does on its own](#after-an-upgrade).
+
 ---
 
 ## Why Lemma
@@ -28,6 +34,15 @@ in a local index (BM25, no embeddings service, no cloud). Every memory is tied t
 symbols it's about, so when the code changes it comes back **stale** instead of confidently
 wrong — and a memory with no evidence is labelled as such, never sold as a verified answer.
 
+**↪ Work that survives the session (Pro).** A session that edited code leaves a hand-off built from the
+transcript and git, with no model tokens: the task exactly as it was given, the files changed, the last test
+run. The next session's briefing points at it, so "continue where we left off" has something to continue from.
+An agent's own note tends to keep function names and drop their parameter lists; the hand-off keeps the plan
+verbatim. In our benchmark (a plan said only in the first session, graded by hidden tests) agents with Lemma
+finished it in 3 of 3 runs, Claude Code's built-in memory in 1 of 3 and another agent-memory tool in 0 of 3 (3-run
+cells, one model, our own benchmark: a lead, not a proof). It costs more per task, not less, because the agent
+does the work the others skip.
+
 **✍️ It fills itself.** A test, build or lint command that goes red → green is saved as
 `fix: <the error>` with the diff that fixed it. Commits become memories. Next time the same
 error shows up, the agent is pointed at the fix — through hooks in Claude Code, Codex, Cursor
@@ -60,14 +75,15 @@ pretending (`capability_matrix`).
 
 ## Free vs Pro
 
-41 of the 91 tools are free, including all memory, upkeep and export tools. Pro adds writing and patching,
-`search_workspace`, `run_workspace_command`, static analysis, PR review and auto-heal.
+Free covers what your agent can already do natively (reading, searching, running commands, patching) plus the
+memory you write and read yourself, upkeep and export. Pro is what keeps memories true over time and carries work
+across sessions: `verify_memory`, `refresh_memory`, `brain_team`, and the automatic end-of-session capture and hand-off.
 
 | | Free | Pro |
 | :--- | :--- | :--- |
-| Memory | `search_memory`, `store_memory`, `get_memory`, `update_memory`, `verify_memory`, `brain_team`, `brain_upkeep`, `brain_export`… | `get_telepathic_hints`, `semantic_dedup_guard`, `local_semantic_autofix` |
-| Context | `read_workspace_file`, `scrub_privacy`, `token_budget`, `token_receipt`, `auto_context_bundle` | `get_ast_hologram`, `smart_file_slice`, `get_symbol_surgical_context` |
-| Workspace | — | `apply_workspace_patch`, `write_workspace_file`, `run_workspace_command`, `validate_patch_sandbox`, `surgical_ast_insert` |
+| Memory | `search_memory`, `store_memory`, `get_memory`, `update_memory`, `forget_memory`, `brain_upkeep`, `brain_export`… | `verify_memory`, `refresh_memory`, `brain_team`, automatic session capture and hand-off, `get_telepathic_hints`, `semantic_dedup_guard`, `local_semantic_autofix` |
+| Context | `read_workspace_file`, `get_ast_hologram`, `output_region`, `scrub_privacy`, `token_budget`, `token_receipt`, `auto_context_bundle` | `smart_file_slice`, `get_symbol_surgical_context` |
+| Workspace | `search_workspace`, `run_workspace_command`, `apply_workspace_patch` | `write_workspace_file`, `validate_patch_sandbox`, `surgical_ast_insert` |
 | Analysis & review | `type_coverage_report`, `git_blame_heat` | `depgraph`, `entropy_score`, `refactor`, `review_diff`, `review_pr`, `test_oracle` |
 | Monolith analysis | `infra_analyze_monolith`, `infra_suggest_split` (not advertised; via `lemma_toolbox`) | — |
 
@@ -89,9 +105,25 @@ Without a license, Pro tools aren't advertised to the model at all. Full list:
 `post-checkout`, and post-tool hooks for Claude Code, Codex, Cursor and OpenCode). In Claude Code
 it adds a `SessionStart` briefing and a prompt-time recall too, and pre-approves the read and
 memory tools so using them never costs a permission prompt. Existing hooks are kept; `--no-hooks`
-skips them. An install from an older version gets the missing Claude Code hooks the next time the
-MCP server starts; re-run `lemma init` after upgrading to refresh the agent rules. Health check:
-`lemma doctor`.
+skips them. Health check: `lemma doctor`.
+
+### After an upgrade
+
+After `npm install -g @nxuss/lemma` and reconnecting the MCP server, a project that already ran
+`lemma init` gets some things by itself and needs `lemma init` again for the rest:
+
+| | Comes with the upgrade | Needs `lemma init` again |
+| :--- | :---: | :---: |
+| New and fixed tool behaviour (freshness checks, the diff shown on a STALE memory, the hand-off logic) | ✅ | |
+| Missing Claude Code hooks (`SessionStart`, prompt recall, the note before an edit, `SessionEnd`), added at the next MCP start | ✅ | |
+| Agent rules in `CLAUDE.md` / `AGENTS.md` (when to search, store and leave a hand-off) | | ✅ |
+| Pre-approved read and memory tool permissions (otherwise the agent is asked each time) | | ✅ |
+| Hooks and config for Codex, Cursor, OpenCode, Windsurf and Kiro | | ✅ |
+| A project that never ran `lemma init` | | ✅ |
+
+The startup repair adds hooks but never changes what your agent may do without asking, which is why
+permissions and rules wait for `lemma init`. It keeps what you wrote in those files and only replaces
+Lemma's own block.
 
 ### CLI
 
@@ -119,8 +151,7 @@ MCP server starts; re-run `lemma init` after upgrading to refresh the agent rule
 }
 ```
 
-`LEMMA_BRAIN_ENCRYPT=1` stores the Brain AES-256-GCM encrypted at rest. Security-related
-environment variables are documented in [`.env.security.example`](.env.security.example).
+`LEMMA_BRAIN_ENCRYPT=1` stores the Brain AES-256-GCM encrypted at rest.
 
 ### Proxy mode (optional)
 
@@ -130,4 +161,4 @@ project, never served across projects.
 
 ---
 
-Changelog: [`CHANGELOG.md`](CHANGELOG.md) · MIT © Nxus Studio · [Lemma Pro](https://lemma.nxus.studio/upgrade)
+MIT © Nxus Studio · [lemma.nxus.studio](https://lemma.nxus.studio) · [Lemma Pro](https://lemma.nxus.studio/upgrade)

package/bin/brain-ingest.js

@@ -16,6 +16,8 @@
  * Usage: lemma-brain-ingest [projectRoot] [--commits [--max N]] [--changelog] [--team-pull]
  *        lemma-brain-ingest --hook-result [--host=claude|codex|cursor|opencode] < payload.json
  *        lemma-brain-ingest --prompt-submit < payload.json
+ *        lemma-brain-ingest --pre-tool < payload.json
+ *        lemma-brain-ingest --session-end < payload.json
  *
  * --team-pull   Import the repo's shared memories from .lemma-brain/ (post-merge/post-checkout).
  * --hook-result Read a host PostToolUse hook payload on stdin (Claude Code shape) and:
@@ -123,6 +125,29 @@ async function promptSubmit() {
   await reportOffered(dist, payload && payload.cwd, [recall]);
 }
 
+// PreToolUse hook (Claude Code), edits only: the memories about the file, before it is written.
+// Prints context and nothing else — never a permission decision, so it cannot stop or prompt a tool.
+async function preTool() {
+  const dist = path.join(__dirname, '..', 'dist', 'cjs');
+  let preEditRecall, formatHostOutput;
+  try {
+    ({ preEditRecall } = require(path.join(dist, 'subconscious', 'HostRecall.js')));
+    ({ formatHostOutput } = require(path.join(dist, 'subconscious', 'HostAdapters.js')));
+  } catch {
+    return; // no build — a hook must stay silent and harmless
+  }
+  let payload;
+  try {
+    payload = JSON.parse(readStdin());
+  } catch {
+    return;
+  }
+  const recall = preEditRecall(payload, payload && payload.cwd);
+  const out = formatHostOutput('claude', recall ? recall.text : '', 'PreToolUse');
+  if (out) process.stdout.write(out);
+  await reportOffered(dist, payload && payload.cwd, [recall]);
+}
+
 // SessionStart hook (Claude Code): the Brain's briefing and the Lemma playbook, in context
 // before the first prompt — no tool call for the agent to remember or skip.
 async function sessionStart() {
@@ -155,10 +180,26 @@ async function sessionStart() {
   await reportOffered(dist, payload.cwd, [recall]);
 }
 
+// SessionEnd hook (Claude Code): a session that did real work and stored nothing leaves its closing
+// answer in the Brain (see SessionCapture). Silent: the host shows nothing at session end.
+async function sessionEnd() {
+  const dist = path.join(__dirname, '..', 'dist', 'cjs');
+  let payload = {};
+  try {
+    payload = JSON.parse(readStdin()) || {};
+  } catch {
+    return;
+  }
+  const { captureSession } = require(path.join(dist, 'utils', 'SessionCapture.js'));
+  captureSession(payload, payload.cwd);
+}
+
 async function main() {
   const args = process.argv.slice(2);
+  if (args.includes('--session-end')) return sessionEnd();
   if (args.includes('--session-start')) return sessionStart();
   if (args.includes('--prompt-submit')) return promptSubmit();
+  if (args.includes('--pre-tool')) return preTool();
   if (args.includes('--hook-result')) return hookResult(args);
   const maxIndex = args.indexOf('--max');
   const maxCommits = maxIndex >= 0 ? parseInt(args[maxIndex + 1], 10) : undefined;

package/bin/init.js

@@ -261,94 +261,39 @@ function loadLemmaToolNames() {
 
 const LEMMA_TOOL_NAMES = loadLemmaToolNames();
 // Pre-approved in Claude Code: reading, searching and the Brain's lifecycle — local, and nothing
-// a native Read/Grep couldn't already do. Tools that write code (apply_workspace_patch,
-// surgical_ast_insert), run commands (run_workspace_command), delete (forget_memory) or
-// dispatch arbitrary tools (lemma_toolbox) still ask.
+// a native Read/Grep couldn't already do — plus run_workspace_command. Tools that write code
+// (apply_workspace_patch, surgical_ast_insert), delete (forget_memory) or dispatch arbitrary tools
+// (lemma_toolbox) still ask.
+//
+// run_workspace_command is pre-approved on purpose, and it is a real trade-off: a tool that asks on
+// every call is one agents stop using, and it is the one that turns a 70k-character test run into
+// its failures (measured). What it lets through without a prompt is whatever Lemma's own allowlist
+// permits (npm, git, node, python, make, docker… — deny-by-default, no redirection or substitution),
+// which is more than a native Bash rule like `Bash(npx jest *)` would. To tighten it: set
+// mcp.confirmActions or mcp.sandbox (docker) in lemma.config.json, or remove the entry from
+// permissions.allow.
 const LEMMA_PREAPPROVED_TOOLS = [
   'search_memory', 'get_memory', 'verify_memory', 'store_memory', 'update_memory', 'refresh_memory',
   'downvote_memory', 'read_workspace_file', 'list_workspace_dir', 'search_workspace', 'smart_file_slice',
   'get_ast_hologram', 'get_symbol_surgical_context', 'output_region', 'get_project_onboarding',
-  'state_hash_cache', 'smarter_cache', 'token_receipt', 'get_routing_advice',
+  'state_hash_cache', 'smarter_cache', 'token_receipt', 'get_routing_advice', 'run_workspace_command',
 ].map((name) => `mcp__lemma__${name}`);
 
 const CLAUDE_MD_CONTENT = `# Lemma MCP — Cómo usar las herramientas de este proyecto
 
-Tienes conectado el servidor MCP \`lemma\`. Lo que hace que las herramientas nativas no pueden
-es **recordar entre sesiones**: el Brain guarda fixes y decisiones verificadas, y avisa cuando el
-código del que dependen cambió. Ese valor solo existe si se consulta y se alimenta, así que estos
-momentos no son opcionales:
-
-## Disparadores — haz esto siempre
-
-| Cuando… | Llama | Por qué no basta lo nativo |
-|---|---|---|
-| Vas a investigar un bug, un error o un "¿por qué X?" | \`mcp__lemma__search_memory\` con el texto del error o la pregunta | Puede que ya esté resuelto; \`grep\` no encuentra lo que se aprendió en otra sesión |
-| Un aviso 🧠 de Lemma nombra memorias | \`mcp__lemma__get_memory\` de la primera | El aviso trae solo el titular; el cuerpo tiene los archivos y el porqué |
-| Un fix quedó verificado (tests pasan, build ok, el usuario confirmó) | \`mcp__lemma__store_memory\` con \`filePaths\`: la causa raíz, la trampa o lo que no funcionó — no un resumen de qué cambió | Si no se guarda, la próxima sesión lo vuelve a investigar desde cero; un resumen de cambios ya está en git log y nadie lo vuelve a buscar |
-| Una memoria resultó desactualizada o incorrecta | \`mcp__lemma__update_memory\` / \`forget_memory\` | Guardar otra al lado deja dos versiones y la búsqueda mezcla ambas |
-| Vas a leer código que aún no ubicaste, o que puede tener secretos | \`mcp__lemma__search_workspace\` / \`read_workspace_file\` | Enmascaran API keys antes de que entren a tu contexto |
-
-Si las tools de Lemma te llegan diferidas (solo el nombre), cárgalas en **una sola** llamada a
-ToolSearch: \`select:mcp__lemma__search_memory,mcp__lemma__get_memory,mcp__lemma__verify_memory,mcp__lemma__store_memory,mcp__lemma__update_memory,mcp__lemma__read_workspace_file,mcp__lemma__search_workspace\`.
-
-Fuera de esos momentos usa tu criterio: para un archivo chico que ya ubicaste, \`Read\` nativo
-cuesta menos que el ida y vuelta, y para procesos, puertos o git Lemma no tiene nada que aportar.
-
-## Referencia: qué tool para qué
-
-| Tarea | Tool de Lemma | Por qué |
-|---|---|---|
-| Leer/listar/buscar en el workspace | \`mcp__lemma__read_workspace_file\`, \`list_workspace_dir\`, \`search_workspace\` | Auto-scrubbing de secretos y compresión de contexto sin perder el archivo real |
-| Pregunta puntual, de una sola sesión, atada a archivos concretos | \`mcp__lemma__state_hash_cache\` (action="lookup" antes de razonar, "store" después) | Hit solo si el hash exacto de esos archivos no cambió — invalidación exacta, no una adivinanza por similitud. Match de texto exacto en la query: no sirve para "¿algo así ya se resolvió?", solo para "esta misma pregunta, ¿estos archivos siguen igual?" |
-| Conocimiento que debe sobrevivir sesiones, con seguimiento por símbolo (no todo el archivo) | \`mcp__lemma__search_memory\` / \`store_memory\` | Motor con más garantías: invalida por símbolo específico (no por archivo completo), distingue cambio de código real vs. cambio de branch, y sigue cadenas de memorias derivadas — no solo "sin dependencia de archivos", también rastrea archivos con más precisión que state_hash_cache |
-| Pregunta general, sin dependencia de archivos ni necesidad de sobrevivir sesiones | \`mcp__lemma__smarter_cache\` | Cache semántico difuso; si hay hit, dilo explícitamente ("esto viene de una respuesta cacheada") en vez de presentarlo como recién razonado |
-| Tarea mecánica/trivial y quieres saber si conviene un modelo más barato | \`mcp__lemma__get_routing_advice\` | Evita gastar presupuesto de modelo grande en algo mecánico |
-| Agregar un método/función a un archivo existente | \`mcp__lemma__surgical_ast_insert\` | Patch quirúrgico en vez de reescribir el archivo completo |
-| Antes de aplicar un patch generado | \`mcp__lemma__validate_patch_sandbox\` | Valídalo antes de escribirlo, no después |
-| "¿Cuánto ahorramos de verdad?" | \`mcp__lemma__token_receipt\` | Bitácora auditable real, no una cifra inventada |
-| Leer una memoria por su id (antes de editarla, o para un id que traes de otra sesión) | \`mcp__lemma__get_memory\` | Lectura determinista: \`search_memory\` es un ranking y puede no devolver la entrada que buscas. Editar un documento vivo sin leerlo antes es editarlo a ciegas |
-| Corregir o extender una memoria que ya existe | \`mcp__lemma__update_memory\` | Reescribe en su sitio conservando id, hits y las aristas \`derivedFrom\`. \`store_memory\` siempre crea un id nuevo: re-guardar una versión corregida deja las dos y la búsqueda devuelve una mezcla arbitraria de ambas |
-| Guardar una solución para el futuro | \`mcp__lemma__store_memory\` | Solo después de verificarla (tests pasaron, el usuario confirmó) — una solución mala guardada se vuelve un cache hit falso más adelante |
-| Una memoria salió STALE pero la verificaste y sigue siendo correcta | \`mcp__lemma__refresh_memory\` | Re-ancla la evidencia conservando id, hits y las aristas \`derivedFrom\`; guardar un casi-duplicado pierde las tres (y el dedup suele rechazarlo) |
-| Una memoria está simplemente mal, no solo mal encajada | \`mcp__lemma__forget_memory\` | Borrado real. Para "no era lo que buscaba en esta consulta" usa \`downvote_memory\`: esa memoria puede ser la correcta para otra pregunta |
-
-El ciclo de vida completo (\`search\` → \`get\` → \`update\`/\`refresh\`/\`forget\`) está anunciado:
-ante una memoria desactualizada, corrígela; no guardes otra al lado.
-
-## No todas las tools de Lemma están en tu lista
-
-Cada schema que Lemma anuncia se re-envía en **cada** request de la sesión, así que solo se
-anuncian las que este proyecto puede usar de verdad. El resto sigue registrado y disponible:
-
-- \`mcp__lemma__lemma_toolbox\` con \`action="list"\` (y un \`query\`) para ver qué existe.
-- \`action="schema"\` para leer los inputs de una tool antes de llamarla.
-- \`action="call"\` para ejecutarla.
-
-Antes de decirle al usuario que Lemma no puede hacer algo, revisa el toolbox. Si el proyecto
-necesita todas las tools anunciadas de forma permanente, pon \`mcp.toolProfile: "full"\` en
-\`lemma.config.json\`.
-
-## Antes de pedirle código al usuario
-
-No le pidas que pegue archivos, logs o documentación que puedes obtener tú: agota primero
-\`search_workspace\`, \`get_ast_hologram\` (estructura: da nombres y líneas, no firmas) y
-\`read_workspace_file\`. Cada ida y vuelta con el usuario cuesta más que la lectura.
-
-## Al iniciar en este proyecto
-
-El hook \`SessionStart\` de Lemma ya te dio un resumen del Brain al arrancar (si no lo ves,
-\`lemma doctor\` dice qué falta). Para más contexto: \`mcp__lemma__get_project_onboarding\`.
-Lo que venga del Brain no es un hecho hasta verificarlo contra el estado actual del código.
-
-## Al investigar un bug, además
+El servidor MCP \`lemma\` recuerda entre sesiones y avisa cuando el código del que depende una memoria cambió. Úsalo en estos momentos:
 
-\`lemma_toolbox\` → \`get_telepathic_hints\` con el archivo relevante para contexto de runtime.
+## Disparadores
 
-## Una sola regla dura
+- Vas a investigar un bug, un error o un "¿por qué X?" → \`mcp__lemma__search_memory\` con el error o la pregunta.
+- Un aviso 🧠 nombra memorias → \`mcp__lemma__get_memory\` de la primera.
+- Un fix quedó verificado (tests pasan) → \`mcp__lemma__store_memory\` con \`filePaths\`: la causa raíz o la trampa, no un resumen del cambio.
+- Terminas una sesión con trabajo a medias o por partes → \`store_memory\` (o \`update_memory\` si ya hay una) con lo HECHO, lo PENDIENTE y los nombres/firmas exactos de lo especificado; no resumas la especificación.
+- Una memoria quedó desactualizada → \`update_memory\` (o \`forget_memory\`); no guardes otra al lado.
+- Tests, build o lint con salida larga → \`mcp__lemma__run_workspace_command\`: devuelve los fallos y el resumen; el resto se abre con \`output_region\`.
+- Código que aún no ubicaste o que puede tener secretos → \`search_workspace\` / \`read_workspace_file\`.
 
-Cualquier respuesta que dependa de un cache hit, un fix auto-sugerido, o un archivo comprimido
-para tu propio contexto debe entregarse con la información real y sin ocultar que vino de ahí.
-Ahorrar tokens nunca debe costar que el usuario reciba algo incorrecto sin saberlo.
+Si las tools de Lemma llegan diferidas (solo el nombre), cárgalas en una sola llamada a ToolSearch. Las demás están en \`mcp__lemma__lemma_toolbox\` (\`list\`, \`schema\`, \`call\`). No le pidas al usuario código que puedas leer tú. Si una respuesta viene de cache o de un archivo comprimido, dilo.
 
 ---
 *Auto-generado por \`lemma init\` — @nxuss/lemma*
@@ -488,6 +433,7 @@ OpenCode).
 | Investigating a bug, an error, or a "why does X" | \`search_memory\` with the error text or question | grep can't find what was learned in another session |
 | A 🧠 Lemma note names memories | \`get_memory\` on the top one | The note carries the headline; the body has the files and the reason |
 | A fix is verified (tests pass, build ok, user confirmed) | \`store_memory\` with \`filePaths\`: the root cause, the trap or what didn't work — not a summary of what changed | Unsaved, the next session investigates it from scratch; a change summary is already in git log and nobody searches for it |
+| You end a session with work half done or split in parts | \`store_memory\` (or \`update_memory\` if one exists): what is DONE, what is PENDING, and the exact names/signatures that were specified — don't summarise the spec | The next session starts with no memory of the plan; a vague note loses the details |
 | A memory turned out outdated or wrong | \`update_memory\` / \`forget_memory\` | A near-duplicate leaves two versions and search mixes them |
 | Reading code you haven't located yet, or that may hold secrets | \`search_workspace\` / \`read_workspace_file\` | They mask API keys before they reach your context |
 | Applying a generated patch | \`validate_patch_sandbox\` first | Validate before writing, not after |
@@ -990,7 +936,7 @@ function applyEnvToCurrentProcess() {
 // Upstream API keys live here (mode 0600) instead of inside the launchd/systemd
 // unit: the proxy daemon loads this file at startup (lemma-proxy.cjs loadEnvFile),
 // so a background service gets credentials without baking secrets into a unit file.
-function createEnvFile(envFile = ENV_FILE) {
+function createEnvFile(envFile = ENV_FILE, { routing = true } = {}) {
   const proxyUrl = `http://localhost:${PORT}`;
   const keyLines = [
     process.env.ANTHROPIC_API_KEY ? `export ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}` : '',
@@ -1001,14 +947,14 @@ function createEnvFile(envFile = ENV_FILE) {
 #   source ${envFile}
 export LEMMA_PROXY_PORT=${PORT}
 export LEMMA_CACHE_DIR=${LEMMA_CACHE}
-export OPENAI_BASE_URL=${proxyUrl}
+${routing ? `export OPENAI_BASE_URL=${proxyUrl}
 export OPENAI_API_BASE=${proxyUrl}
 export CODEX_BASE_URL=${proxyUrl}
 export LITELLM_PROXY_BASE_URL=${proxyUrl}
-${keyLines ? keyLines + '\n' : ''}`;
+` : ''}${keyLines ? keyLines + '\n' : ''}`;
   fs.writeFileSync(envFile, envContent, 'utf8');
   try { fs.chmodSync(envFile, 0o600); } catch {}
-  applyEnvToCurrentProcess();
+  if (routing) applyEnvToCurrentProcess();
   return envFile;
 }
 
@@ -1048,6 +994,44 @@ function setupShellIntegration() {
   return configured;
 }
 
+/**
+ * Undo what an earlier `lemma init` appended to the shell: the two lines that source the env file
+ * (only that exact block — anything the user wrote, or commented out, is left alone) and the
+ * launchctl variables, only when they still hold the value we set.
+ *
+ * Routing OPENAI_BASE_URL & co. through localhost:8081 is only safe while the proxy is guaranteed
+ * to be up, which is what --daemon installs. Without it, the first time the proxy was not running
+ * every OpenAI-compatible tool in every new terminal (and GUI apps, via launchctl) failed with
+ * 'connection refused'.
+ */
+function removeShellIntegration(home = os.homedir()) {
+  const block = /\n?# Lemma Cache Proxy — auto-configured by `lemma init`\n\[ -f "[^"\n]*lemma-cache\/env" \] && \. "[^"\n]*lemma-cache\/env"\n?/g;
+  let removed = false;
+  for (const file of [path.join(home, '.zshrc'), path.join(home, '.bashrc'), path.join(home, '.config', 'fish', 'config.fish')]) {
+    try {
+      if (!fs.existsSync(file)) continue;
+      const content = fs.readFileSync(file, 'utf8');
+      const next = content.replace(block, '\n');
+      if (next !== content) {
+        fs.writeFileSync(file, next, 'utf8');
+        removed = true;
+      }
+    } catch {}
+  }
+  if (process.platform === 'darwin') {
+    for (const name of ['OPENAI_BASE_URL', 'CODEX_BASE_URL']) {
+      try {
+        const current = String(execSync(`launchctl getenv ${name}`, { stdio: ['ignore', 'pipe', 'ignore'] }) || '').trim();
+        if (current === `http://localhost:${PORT}`) {
+          execSync(`launchctl unsetenv ${name}`, { stdio: 'ignore' });
+          removed = true;
+        }
+      } catch {}
+    }
+  }
+  return removed;
+}
+
 async function main(argv = process.argv) {
   const opts = parseInitArgs(argv);
   if (opts.showHelp) {
@@ -1150,7 +1134,7 @@ async function main(argv = process.argv) {
   });
   if (hasCodex) {
     const codexConfigured = configureCodexCliMcp();
-    if (codexConfigured) ok('Codex CLI configured (MCP + OPENAI_BASE_URL env)');
+    if (codexConfigured) ok('Codex CLI configured (MCP)');
     else warn('Codex CLI detected but MCP config could not be auto-updated');
   } else skip('Codex CLI not detected');
 
@@ -1176,12 +1160,20 @@ async function main(argv = process.argv) {
     skip('Brain hooks not installed (--no-hooks)');
   }
 
-  const envFile = createEnvFile();
+  // Routing model traffic through the local proxy is tied to the daemon: only then is the proxy
+  // guaranteed to be listening. Without it nothing in the user's shell or GUI apps is pointed at it.
+  const envFile = createEnvFile(ENV_FILE, { routing: opts.wantDaemon });
   ok(`Env file created: ${envFile}`);
 
-  const shellOk = setupShellIntegration();
-  if (shellOk) ok('Shell rc files updated (source ~/.lemma-cache/env)');
-  else warn('Could not update shell rc — source manually: source ~/.lemma-cache/env');
+  if (opts.wantDaemon) {
+    const shellOk = setupShellIntegration();
+    if (shellOk) ok('Shell rc files updated (source ~/.lemma-cache/env)');
+    else warn('Could not update shell rc — source manually: source ~/.lemma-cache/env');
+  } else if (removeShellIntegration()) {
+    ok('Removed the proxy routing an earlier init added to your shell (OPENAI_BASE_URL & co. pointed at a proxy that is not installed)');
+  } else {
+    skip('Shell and app environment untouched — no model traffic is routed (opt-in via `lemma init --daemon`)');
+  }
 
   process.stderr.write(`\n  ${BOLD}${GREEN}✓ Lemma init complete${RESET}\n`);
   process.stderr.write(`  ${DIM}──────────────────────────────────────${RESET}\n`);
@@ -1192,14 +1184,22 @@ async function main(argv = process.argv) {
   }
   process.stderr.write(`  ${GREEN}●${RESET} MCP server ready  ${DIM}(lemma mcp)${RESET}\n`);
   process.stderr.write(`  ${GREEN}●${RESET} Dashboard active  ${DIM}(lemma stats)${RESET}\n`);
-  process.stderr.write(`  ${GREEN}●${RESET} New terminals: env vars auto-loaded\n`);
+  if (opts.wantDaemon) {
+    process.stderr.write(`  ${GREEN}●${RESET} New terminals: env vars auto-loaded\n`);
+  }
   process.stderr.write(`  ${DIM}Upkeep: re-run 'lemma init' after upgrading @nxuss/lemma (refreshes skills + rules)${RESET}\n`);
-  process.stderr.write(`  ${GREEN}●${RESET} Todos los IDE/CLI nuevos ya apuntan al proxy\n`);
+  if (opts.wantDaemon) {
+    process.stderr.write(`  ${GREEN}●${RESET} Todos los IDE/CLI nuevos ya apuntan al proxy\n`);
+  }
   process.stderr.write(`  ${gatewayResult.activated ? GREEN + '●' : YELLOW + '○'}${RESET} Claude Code gateway: ${gatewayResult.activated ? 'ACTIVE (model traffic cached)' : 'inactive (MCP tools only)'}\n`);
   process.stderr.write(`  ${DIM}──────────────────────────────────────${RESET}\n`);
-  process.stderr.write(`  ${YELLOW}Para activar en ESTA terminal:${RESET}\n`);
-  process.stderr.write(`  ${BOLD}source ${ENV_FILE}${RESET}\n`);
-  process.stderr.write(`  ${DIM}Logs: ${LEMMA_CACHE}/proxy-daemon.log${RESET}\n\n`);
+  if (opts.wantDaemon) {
+    process.stderr.write(`  ${YELLOW}Para activar en ESTA terminal:${RESET}\n`);
+    process.stderr.write(`  ${BOLD}source ${ENV_FILE}${RESET}\n`);
+    process.stderr.write(`  ${DIM}Logs: ${LEMMA_CACHE}/proxy-daemon.log${RESET}\n\n`);
+  } else {
+    process.stderr.write(`  ${DIM}Open your agent (Claude Code, Cursor, Codex…) in this project and the MCP tools are there.${RESET}\n\n`);
+  }
 }
 
 if (require.main === module) {
@@ -1209,4 +1209,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { main, configureMuse, configureMuseUserSkill, updateAgentsMd, configureClaudeCode, MUSE_SKILL_CONTENT, LEMMA_RULES_CONTENT, CLAUDE_MD_CONTENT, installProxyDaemon, removeProxyDaemon, parseInitArgs, createEnvFile, installBrainFeeds };
+module.exports = { removeShellIntegration, setupShellIntegration, main, configureMuse, configureMuseUserSkill, updateAgentsMd, configureClaudeCode, MUSE_SKILL_CONTENT, LEMMA_RULES_CONTENT, CLAUDE_MD_CONTENT, installProxyDaemon, removeProxyDaemon, parseInitArgs, createEnvFile, installBrainFeeds };

package/bin/postinstall.js

@@ -6,9 +6,10 @@
  * catalog so it auto-loads in every `muse` session, with zero extra steps
  * after `npm i [-g] @nxuss/lemma`.
  *
- * Total function: never fails the install, never prints on success, finishes
- * in well under a second when there is nothing to do. No build output needed —
- * skill install only registers a markdown file, it never invokes any tool.
+ * It also tells the person to run `lemma init` in their projects, once, on a GLOBAL install
+ * to a terminal (see notify). Total function: never fails the install, finishes in well under a
+ * second when there is nothing to do. No build output needed — skill install only registers a
+ * markdown file, it never invokes any tool.
  */
 
 const { execSync, execFileSync } = require('child_process');
@@ -28,7 +29,58 @@ function museOnPath() {
   }
 }
 
+const NOTICE = [
+  '',
+  '  Lemma is installed. One more step, in each project you want it in:',
+  '',
+  '      lemma init',
+  '',
+  '  Run it again after every upgrade: it updates the agent rules and the pre-approved',
+  '  permissions, which the package alone cannot change. Then reconnect the MCP server',
+  '  (/mcp in Claude Code). What an upgrade does by itself: README, "After an upgrade".',
+  '',
+].join('\n');
+
+/**
+ * Only a global install is the moment someone is setting Lemma up. `npx -y @nxuss/lemma mcp`
+ * (how some clients launch the server) and installs as a dependency run this script too, and
+ * a message written to the terminal there would land on top of the client's own screen.
+ */
+function shouldNotify(env) {
+  if (env.npm_config_global !== 'true') return false;
+  if (env.CI || env.LEMMA_QUIET) return false;
+  if (/^(silent|error)$/.test(env.npm_config_loglevel || '')) return false;
+  return true;
+}
+
+/**
+ * npm 7+ hides a postinstall script's output on a normal install, so printing to stdout would
+ * reach nobody. The controlling terminal is written directly instead; with no terminal (a pipe,
+ * a container) that fails quietly and the notice goes to stderr, which `--foreground-scripts` shows.
+ */
+function notify() {
+  try {
+    const fd = fs.openSync(process.platform === 'win32' ? '\\\\.\\CON' : '/dev/tty', 'w');
+    try {
+      fs.writeSync(fd, `${NOTICE}\n`);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    try {
+      process.stderr.write(`${NOTICE}\n`);
+    } catch {
+      // a notice is never worth failing an install
+    }
+  }
+}
+
 function main() {
+  try {
+    if (shouldNotify(process.env)) notify();
+  } catch {
+    // best-effort, same contract as below
+  }
   try {
     const skillDir = path.join(__dirname, '..', '.agents', 'skills', 'lemma');
     if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) return;
@@ -40,4 +92,6 @@ function main() {
   }
 }
 
-main();
+if (require.main === module) main();
+
+module.exports = { shouldNotify, NOTICE };