@nxuss/lemma 1.21.0 → 1.22.1

package/.agents/skills/lemma/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lemma
-description: Lemma — cache semántico, firewall de privacidad y memoria cross-sesión para Muse. Usa `lemma call <tool>` vía bash para acceder a 70+ tools sin MCP nativo.
+description: Lemma — cache semántico, firewall de privacidad y memoria cross-sesión para Muse. Usa `lemma call <tool>` vía bash para acceder a 70+ tools sin MCP nativo. Cárgala al iniciar cada sesión: search_memory antes de razonar, store_memory al verificar una solución.
 user-invocable: true
 allowed-tools: bash
 ---
@@ -33,19 +33,20 @@ Si Lemma no encaja, usa tu tool nativo. No fuerces Lemma donde no aporta.
 
 ## Cómo llamar a Lemma desde Muse (preferido)
 
-Usa el wrapper `lemma call` — evita craft de JSON-RPC manual y escapa args por ti. Está disponible como `node ./lemma-proxy.cjs call` o `node ./bin/lemma-call.js` o `npx @nxuss/lemma call` si instalaste global.
+Usa el wrapper `lemma call` — evita craft de JSON-RPC manual y escapa args por ti. Está disponible como `lemma call` (instalación global por npm), `npx @nxuss/lemma call`, o local `node ./lemma-proxy.cjs call` / `node ./bin/lemma-call.js`.
 
 ```bash
 # 1. Lookup en memoria antes de razonar (preferido — wrapper)
-node ./lemma-proxy.cjs call search_memory --query "tu pregunta"
+lemma call search_memory --query "tu pregunta"
 # o JSON explícito:
-node ./lemma-proxy.cjs call search_memory '{"query":"tu pregunta"}'
+lemma call search_memory '{"query":"tu pregunta"}'
+# (en este repo también vale: node ./lemma-proxy.cjs call search_memory --query "tu pregunta")
 
 # 2. Busca en workspace (con scrubbing)
-node ./lemma-proxy.cjs call search_workspace --query "texto" --maxResults 10
+lemma call search_workspace --query "texto" --maxResults 10
 
 # 3. Guarda solución verificada
-node ./lemma-proxy.cjs call store_memory '{"content":"solución verificada","tags":["bugfix"]}'
+lemma call store_memory '{"content":"solución verificada","tags":["bugfix"]}'
 
 # 4. Lista tools disponibles
 node ./lemma-proxy.cjs call --list
@@ -122,3 +123,4 @@ npm i -D @nxuss/lemma && npx lemma init
 ```
 
 > Generado por `lemma init` — @nxuss/lemma para Muse.
+<!-- managed by lemma init (@nxuss/lemma): re-run lemma init after upgrading to refresh -->

package/README.md

@@ -27,11 +27,13 @@ to an auditable ledger, never an estimate.
 
 ```bash
 npm install -g @nxuss/lemma
-lemma init      # auto-configures MCP for your IDE (Claude Code, Cursor, Codex, Windsurf, Kiro, OpenCode)
+lemma init      # auto-configures MCP for your IDE (Muse, Claude Code, Cursor, Codex, Windsurf, Kiro, OpenCode)
 lemma start     # gateway + dashboard on http://localhost:8081
 ```
 
 > **Muse** — no setup needed. This repo is already Muse-compatible zero-config: clone and open with `muse` — the skill at `.agents/skills/lemma/SKILL.md` auto-loads and `lemma call` works via `bash`. See [MCP integration](#-mcp-integration).
+>
+> **🆕 v1.22.0 — Lemma auto-activates in every LLM client.** `npm i -g @nxuss/lemma` registers the skill in your **user** catalog (auto-loads in every `muse` session, any project) and `lemma init` wires each project for Muse, Claude Code, Cursor, Codex, Windsurf, Kiro and OpenCode. Health check: `lemma doctor`.
 
 ---
 
@@ -156,7 +158,7 @@ Customize via `lemma.config.json`:
 
 | Client | Setup |
 | :--- | :--- |
-| **Muse** (`muse` CLI · Muse Spark) | **Zero-config** — clone this repo and open with `muse`; skill at `.agents/skills/lemma/SKILL.md` auto-loads, `lemma call` wrapper via `bash` (no MCP native needed). No `lemma init` required. |
+| **Muse** (`muse` CLI · Muse Spark) | `lemma init` installs the skill into your **user** catalog (`muse skills install --scope user`, auto-loads in every session) + project skill; `npm i -g @nxuss/lemma` also registers it via postinstall. `lemma call` wrapper via `bash` (no MCP native needed). Health check: `lemma doctor`. |
 | 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"] } }` |

package/bin/doctor.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Lemma doctor — verifies the Lemma wiring on this machine / project:
+ * wrapper, project skill, user skill (muse), and AGENTS.md block.
+ *
+ * Usage: `lemma doctor` (exit 0 = usable, exit 1 = wrapper broken).
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CYAN = '\x1b[36m', GREEN = '\x1b[32m', YELLOW = '\x1b[33m', DIM = '\x1b[2m', RESET = '\x1b[0m', BOLD = '\x1b[1m';
+
+function ok(msg) { process.stdout.write(`  ${GREEN}✓${RESET} ${msg}\n`); }
+function warn(msg) { process.stdout.write(`  ${YELLOW}!${RESET} ${msg}\n`); }
+function fail(msg) { process.stdout.write(`  ${YELLOW}✗${RESET} ${msg}\n`); }
+
+function shortErr(e) {
+  try {
+    const raw = (e && (e.stderr || e.stdout || e.message)) || '';
+    const line = raw.toString().split('\n').map((s) => s.trim()).filter(Boolean)[0] || '';
+    return line.slice(0, 160);
+  } catch {
+    return '';
+  }
+}
+
+function museOnPath() {
+  try {
+    if (process.platform === 'win32') return true;
+    require('child_process').execSync('command -v muse', { stdio: 'ignore', timeout: 10000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveMcpServer(pkgRoot) {
+  const candidates = [
+    path.join(pkgRoot, 'dist', 'cjs', 'mcp', 'index.js'),
+    path.join(pkgRoot, 'mcp-server.js'),
+  ];
+  return candidates.find((p) => fs.existsSync(p)) || null;
+}
+
+async function main() {
+  const pkgRoot = path.join(__dirname, '..');
+  const cwd = process.cwd();
+  let broken = false;
+  process.stdout.write(`\n  ${BOLD}${CYAN}Lemma Doctor${RESET}\n\n`);
+
+  // 1. Wrapper + tool catalog (the core: everything else is advice).
+  const server = resolveMcpServer(pkgRoot);
+  if (!server) {
+    fail('no MCP server found (dist/cjs/mcp/index.js nor mcp-server.js) — run npm run build');
+    broken = true;
+  } else {
+    try {
+      const out = execFileSync(process.execPath,
+        [path.join(pkgRoot, 'bin', 'lemma-call.js'), '--list'],
+        { encoding: 'utf8', timeout: 60000, stdio: ['ignore', 'pipe', 'ignore'] });
+      const tools = JSON.parse(out);
+      ok(`wrapper works via ${path.relative(pkgRoot, server)} — ${tools.length} tools`);
+    } catch {
+      fail('wrapper failed: `lemma call --list` did not return a tool catalog');
+      broken = true;
+    }
+  }
+
+  // 2. Project skill (this repo / project).
+  const projSkill = path.join(cwd, '.agents', 'skills', 'lemma', 'SKILL.md');
+  if (fs.existsSync(projSkill)) {
+    const body = fs.readFileSync(projSkill, 'utf8');
+    if (body.includes('Cárgala al iniciar')) ok('project skill current (.agents/skills/lemma/SKILL.md)');
+    else warn('project skill is stale (pre auto-load trigger) — re-run `lemma init`');
+  } else {
+    warn('no project skill — run `lemma init` in this project');
+  }
+
+  // 3. User skill (every `muse` session, any project).
+  // Note: inside a project that defines its own `lemma` skill, the CLI shadows
+  // the user skill (project wins — by design) and `inspect --source user` then
+  // reports "not found". Fall back to the on-disk check before crying missing.
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  const userSkillFile = path.join(configHome, 'muse', 'skills', 'lemma', 'SKILL.md');
+  const projSkillHere = fs.existsSync(projSkill);
+  if (!museOnPath()) {
+    warn('muse CLI not on PATH — user skill not applicable here');
+  } else {
+    try {
+      execFileSync('muse', ['skills', 'inspect', 'lemma', '--source', 'user'],
+        { stdio: 'pipe', timeout: 30000 });
+      ok('user skill installed (auto-loads in every muse session)');
+    } catch (e) {
+      const detail = shortErr(e);
+      if (fs.existsSync(userSkillFile) && projSkillHere) {
+        ok('user skill installed (shadowed by this project\u2019s skill here — project wins, as designed)');
+      } else if (fs.existsSync(userSkillFile)) {
+        warn('user skill files exist but the CLI does not see them' + (detail ? ` (${detail})` : ''));
+      } else {
+        warn('user skill missing' + (detail ? ` (${detail})` : '') + ' — run `lemma init` or `muse skills install <pkg>/.agents/skills/lemma --scope user --force`');
+      }
+    }
+  }
+
+  // 4. AGENTS.md block (session-start nudge for AGENTS.md-aware agents).
+  const agentsPath = path.join(cwd, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath) || !fs.readFileSync(agentsPath, 'utf8').includes('@nxuss/lemma')) {
+    warn('no Lemma block in ./AGENTS.md — run `lemma init`');
+  } else if (fs.readFileSync(agentsPath, 'utf8').includes('At session')) {
+    ok('AGENTS.md block current (session-start guard)');
+  } else {
+    warn('AGENTS.md block is stale (pre Muse guard) — re-run `lemma init`');
+  }
+
+  process.stdout.write(`\n  ${DIM}Brain: ~/.lemma-cache/lemma_brain.json · proxy: lemma-proxy.cjs status${RESET}\n\n`);
+  return broken ? 1 : 0;
+}
+
+if (require.main === module) {
+  main().then((code) => process.exit(code)).catch((e) => {
+    console.error('doctor failed:', e.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { main };

package/bin/init.js

@@ -4,7 +4,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync, spawn } = require('child_process');
+const { execSync, execFileSync, spawn } = require('child_process');
 
 const LEMMA_CACHE = path.join(os.homedir(), '.lemma-cache');
 const BRAIN_FILE = path.join(LEMMA_CACHE, 'lemma_brain.json');
@@ -399,7 +399,7 @@ function configureClaudeCode() {
 // license tier (semantic cache vs. exact-match cache), which has nothing to do with
 // gateway credentials. The proxy (lemma-proxy.ts) never validates whatever token the
 // client sends anyway: it always signs upstream requests with its OWN server-side
-// ANTHROPIC_API_KEY (see installProxyDaemon). So ANTHROPIC_AUTH_TOKEN here is just a
+// ANTHROPIC_API_KEY (loaded from ~/.lemma-cache/env). So ANTHROPIC_AUTH_TOKEN here is just a
 // fixed local placeholder to satisfy Claude Code's "a token is present" check.
 function configureClaudeCodeGateway(anthropicApiKey) {
   if (!anthropicApiKey) {
@@ -436,10 +436,13 @@ The MCP server \`lemma\` is connected. For clients with native MCP support
 (Claude Code, Cursor, Codex, Windsurf, Kiro, OpenCode), NEVER use native tools
 when a Lemma equivalent exists.
 
-> **Muse Code:** you DO NOT have native \`mcp__lemma__*\` tools. For you,
-> \`AGENTS.md\` is advisory. Follow \`.agents/skills/lemma/SKILL.md\` instead —
-> it has priority and uses \`lemma call\` via bash. Do not enforce the table
-> below as a hard block; use it only when \`lemma call\` actually helps.
+> **Muse Code:** you DO NOT have native \`mcp__lemma__*\` tools. At session
+> start, load the \`lemma\` skill (user scope if present, else
+> \`.agents/skills/lemma/SKILL.md\`) and follow it instead of this file — it
+> has priority and uses \`lemma call\` via bash. Then call \`search_memory\`
+> with the task topic before reasoning. Do not enforce the table below as a
+> hard block; use \`lemma call\` when it actually helps. If no \`lemma\` skill
+> is installed, tell the user to run \`npx @nxuss/lemma init\`.
 
 ## Mandatory Substitutions (MCP-native clients only)
 
@@ -464,7 +467,7 @@ when a Lemma equivalent exists.
 2. Call \`search_memory\` with the task topic — recall past solutions
 3. When done: call \`store_memory\` with the solution
 
-> Muse: use \`node ./lemma-proxy.cjs call <tool>\` (see \`.agents/skills/lemma/SKILL.md\`).
+> Muse: use \`lemma call <tool>\` (or \`node ./lemma-proxy.cjs call <tool>\` in this repo — see \`.agents/skills/lemma/SKILL.md\`).
 
 ## Bug Reporting
 
@@ -574,7 +577,7 @@ function configureKiro() {
 // OpenCode: register MCP server in opencode.json + Muse skill
 const MUSE_SKILL_CONTENT = `---
 name: lemma
-description: Lemma — cache semántico, firewall de privacidad y memoria cross-sesión para Muse. Usa lemma call <tool> vía bash para acceder a 70+ tools sin MCP nativo.
+description: Lemma — cache semántico, firewall de privacidad y memoria cross-sesión para Muse. Usa \`lemma call <tool>\` vía bash para acceder a 70+ tools sin MCP nativo. Cárgala al iniciar cada sesión: search_memory antes de razonar, store_memory al verificar una solución.
 user-invocable: true
 allowed-tools: bash
 ---
@@ -607,19 +610,20 @@ Si Lemma no encaja, usa tu tool nativo. No fuerces Lemma donde no aporta.
 
 ## Cómo llamar a Lemma desde Muse (preferido)
 
-Usa el wrapper \`lemma call\` — evita craft de JSON-RPC manual y escapa args por ti. Está disponible como \`node ./lemma-proxy.cjs call\` o \`node ./bin/lemma-call.js\` o \`npx @nxuss/lemma call\` si instalaste global.
+Usa el wrapper \`lemma call\` — evita craft de JSON-RPC manual y escapa args por ti. Está disponible como \`lemma call\` (instalación global por npm), \`npx @nxuss/lemma call\`, o local \`node ./lemma-proxy.cjs call\` / \`node ./bin/lemma-call.js\`.
 
 \`\`\`bash
 # 1. Lookup en memoria antes de razonar (preferido — wrapper)
-node ./lemma-proxy.cjs call search_memory --query "tu pregunta"
+lemma call search_memory --query "tu pregunta"
 # o JSON explícito:
-node ./lemma-proxy.cjs call search_memory '{"query":"tu pregunta"}'
+lemma call search_memory '{"query":"tu pregunta"}'
+# (en este repo también vale: node ./lemma-proxy.cjs call search_memory --query "tu pregunta")
 
 # 2. Busca en workspace (con scrubbing)
-node ./lemma-proxy.cjs call search_workspace --query "texto" --maxResults 10
+lemma call search_workspace --query "texto" --maxResults 10
 
 # 3. Guarda solución verificada
-node ./lemma-proxy.cjs call store_memory '{"content":"solución verificada","tags":["bugfix"]}'
+lemma call store_memory '{"content":"solución verificada","tags":["bugfix"]}'
 
 # 4. Lista tools disponibles
 node ./lemma-proxy.cjs call --list
@@ -696,17 +700,51 @@ npm i -D @nxuss/lemma && npx lemma init
 \`\`\`
 
 > Generado por \`lemma init\` — @nxuss/lemma para Muse.
+<!-- managed by lemma init (@nxuss/lemma): re-run lemma init after upgrading to refresh -->
 `;
 
+// Installs the Lemma skill into the user's GLOBAL muse skill catalog so it
+// auto-loads in every `muse` session — not just in projects where `lemma init`
+// was run. Best-effort: never fails `lemma init` — but LOUD about the reason,
+// so a missing user skill is diagnosable instead of silent.
+function shortErr(e) {
+  try {
+    const raw = (e && (e.stderr || e.stdout || e.message)) || '';
+    const line = raw.toString().split('\n').map((s) => s.trim()).filter(Boolean)[0] || '';
+    return line.slice(0, 160);
+  } catch {
+    return '';
+  }
+}
+
+function configureMuseUserSkill(skillDir) {
+  try {
+    execSync('command -v muse', { stdio: 'ignore' });
+  } catch {
+    return { ok: false, reason: 'muse CLI not found on PATH' };
+  }
+  try {
+    execFileSync('muse', ['skills', 'install', skillDir, '--scope', 'user', '--force'],
+      { stdio: 'pipe', timeout: 30000 });
+    return { ok: true, reason: '' };
+  } catch (e) {
+    const detail = shortErr(e);
+    return { ok: false, reason: 'muse skills install failed' + (detail ? `: ${detail}` : '') };
+  }
+}
+
 function configureMuse() {
   const cwd = process.cwd();
   const skillDir = path.join(cwd, '.agents', 'skills', 'lemma');
+  let project = false;
   try {
     ensureDir(skillDir);
     const skillPath = path.join(skillDir, 'SKILL.md');
     fs.writeFileSync(skillPath, MUSE_SKILL_CONTENT, 'utf8');
-    return true;
-  } catch { return false; }
+    project = true;
+  } catch { project = false; }
+  const userRes = project ? configureMuseUserSkill(skillDir) : { ok: false, reason: 'project skill write failed' };
+  return { project, user: userRes.ok, userReason: userRes.reason };
 }
 
 function ensureKiroMigratesAgentsMd() {
@@ -757,20 +795,19 @@ function configureOpenCode() {
   return true;
 }
 
-function installProxyDaemon() {
+// Installs the cache-proxy daemon as a user-level launchd/systemd unit.
+// OPT-IN ONLY: `lemma init` never calls this without an explicit --daemon flag.
+// Secrets are never baked into the unit file: the daemon loads ~/.lemma-cache/env
+// at startup (see lemma-proxy.cjs loadEnvFile), where `lemma init` persists keys
+// with mode 0600 instead.
+function installProxyDaemon(homeDir = os.homedir()) {
   const isMac = process.platform === 'darwin';
   const isLinux = process.platform === 'linux';
 
-  // The full proxy server (lemma-proxy.ts) needs its own server-side credentials to sign
-  // upstream requests — it never trusts whatever token the calling client sends. A launchd/
-  // systemd service does not inherit the shell's exported env, so these must be baked into
-  // the unit definition at install time or the daemon silently falls back to local Ollama.
-  const anthropicApiKey = process.env.ANTHROPIC_API_KEY || '';
-  const openaiApiKey = process.env.OPENAI_API_KEY || '';
   const proxyArgs = ['start', '--port', PORT, '--no-configure', '--no-clipboard'];
 
   if (isMac) {
-    const plistDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const plistDir = path.join(homeDir, 'Library', 'LaunchAgents');
     ensureDir(plistDir);
     const plistPath = path.join(plistDir, 'com.lemma.cache-proxy.plist');
     const argEntries = proxyArgs.map((a) => `    <string>${a}</string>`).join('\n');
@@ -778,9 +815,7 @@ function installProxyDaemon() {
       `    <key>LEMMA_PROXY_PORT</key><string>${PORT}</string>`,
       `    <key>LEMMA_CACHE_DIR</key><string>${LEMMA_CACHE}</string>`,
       `    <key>LEMMA_DISABLE_CLIPBOARD</key><string>true</string>`,
-      anthropicApiKey ? `    <key>ANTHROPIC_API_KEY</key><string>${anthropicApiKey}</string>` : '',
-      openaiApiKey ? `    <key>OPENAI_API_KEY</key><string>${openaiApiKey}</string>` : '',
-    ].filter(Boolean).join('\n');
+    ].join('\n');
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -810,15 +845,13 @@ ${envEntries}
   }
 
   if (isLinux) {
-    const svcDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    const svcDir = path.join(homeDir, '.config', 'systemd', 'user');
     ensureDir(svcDir);
     const envLines = [
       `Environment=LEMMA_PROXY_PORT=${PORT}`,
       `Environment=LEMMA_CACHE_DIR=${LEMMA_CACHE}`,
       `Environment=LEMMA_DISABLE_CLIPBOARD=true`,
-      anthropicApiKey ? `Environment=ANTHROPIC_API_KEY=${anthropicApiKey}` : '',
-      openaiApiKey ? `Environment=OPENAI_API_KEY=${openaiApiKey}` : '',
-    ].filter(Boolean).join('\n');
+    ].join('\n');
     const svc = `[Unit]
 Description=Lemma Cache Proxy
 After=network.target
@@ -841,6 +874,39 @@ WantedBy=default.target
   return false;
 }
 
+// Best-effort removal of a previously installed daemon unit. Plain `lemma init`
+// (no --daemon) calls this so a silent or legacy install can never linger behind:
+// the daemon only exists while the user explicitly asked for it.
+function removeProxyDaemon(homeDir = os.homedir()) {
+  if (process.platform === 'darwin') {
+    const plistPath = path.join(homeDir, 'Library', 'LaunchAgents', 'com.lemma.cache-proxy.plist');
+    if (!fs.existsSync(plistPath)) return false;
+    try { execSync('launchctl unload ' + plistPath, { stdio: 'ignore' }); } catch {}
+    try { fs.unlinkSync(plistPath); } catch {}
+    return !fs.existsSync(plistPath);
+  }
+  if (process.platform === 'linux') {
+    const svcPath = path.join(homeDir, '.config', 'systemd', 'user', 'lemma-cache-proxy.service');
+    if (!fs.existsSync(svcPath)) return false;
+    try { execSync('systemctl --user disable lemma-cache-proxy --now', { stdio: 'ignore' }); } catch {}
+    try { fs.unlinkSync(svcPath); } catch {}
+    return !fs.existsSync(svcPath);
+  }
+  return false;
+}
+
+// Global side effects stay opt-in: a plain `lemma init` only writes project-local
+// files + MCP registrations. --daemon installs the background proxy daemon,
+// --gateway reroutes the user's Claude Code model traffic through that proxy.
+function parseInitArgs(argv = process.argv) {
+  const args = argv.slice(2);
+  return {
+    showHelp: args.includes('--help') || args.includes('-h'),
+    wantDaemon: args.includes('--daemon'),
+    wantGateway: args.includes('--gateway'),
+  };
+}
+
 function applyEnvToCurrentProcess() {
   const proxyUrl = `http://localhost:${PORT}`;
   process.env.LEMMA_PROXY_PORT = PORT;
@@ -851,21 +917,29 @@ function applyEnvToCurrentProcess() {
   process.env.LITELLM_PROXY_BASE_URL = proxyUrl;
 }
 
-function createEnvFile() {
+// 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) {
   const proxyUrl = `http://localhost:${PORT}`;
+  const keyLines = [
+    process.env.ANTHROPIC_API_KEY ? `export ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}` : '',
+    process.env.OPENAI_API_KEY ? `export OPENAI_API_KEY=${process.env.OPENAI_API_KEY}` : '',
+  ].filter(Boolean).join('\n');
   const envContent = `# Lemma Cache Proxy — Auto-generated by \`lemma init\`
 # Source this file in your shell to route LLM traffic through the cache:
-#   source ${ENV_FILE}
+#   source ${envFile}
 export LEMMA_PROXY_PORT=${PORT}
 export LEMMA_CACHE_DIR=${LEMMA_CACHE}
 export OPENAI_BASE_URL=${proxyUrl}
 export OPENAI_API_BASE=${proxyUrl}
 export CODEX_BASE_URL=${proxyUrl}
 export LITELLM_PROXY_BASE_URL=${proxyUrl}
-`;
-  fs.writeFileSync(ENV_FILE, envContent, 'utf8');
+${keyLines ? keyLines + '\n' : ''}`;
+  fs.writeFileSync(envFile, envContent, 'utf8');
+  try { fs.chmodSync(envFile, 0o600); } catch {}
   applyEnvToCurrentProcess();
-  return ENV_FILE;
+  return envFile;
 }
 
 function setupShellIntegration() {
@@ -904,7 +978,26 @@ function setupShellIntegration() {
   return configured;
 }
 
-async function main() {
+async function main(argv = process.argv) {
+  const opts = parseInitArgs(argv);
+  if (opts.showHelp) {
+    process.stderr.write(`
+  Lemma Init — project setup (project-local files + MCP registrations only)
+
+  Usage: lemma init [--daemon] [--gateway]
+
+    --daemon    Install + start the background cache-proxy daemon
+                (launchd KeepAlive on macOS, systemd user unit on Linux).
+                Without it, no daemon is installed — and a previously installed
+                one is removed.
+    --gateway   Reroute this user's Claude Code model traffic through the proxy
+                (~/.claude/settings.json). Requires ANTHROPIC_API_KEY in env.
+                Without it, Claude Code keeps its own auth untouched.
+
+`);
+    return;
+  }
+
   process.stderr.write(`\n  ${BOLD}${CYAN}Lemma Init — Magic Setup${RESET}\n\n`);
 
   ensureDir(LEMMA_CACHE);
@@ -923,17 +1016,23 @@ async function main() {
   configureClaudeCode();
   ok('Claude Code / CLI configured (CLAUDE.md + .claude/settings.local.json)');
 
-  const anthropicApiKey = process.env.ANTHROPIC_API_KEY || '';
-  const gatewayResult = configureClaudeCodeGateway(anthropicApiKey);
-  if (gatewayResult.activated) {
-    ok(`Claude Code gateway activated (~/.claude/settings.json → ANTHROPIC_BASE_URL=http://localhost:${PORT})`);
+  // --gateway is opt-in: flipping the user's global Claude Code auth without being
+  // asked is exactly how Pro subscribers end up billed as API usage.
+  if (!opts.wantGateway) {
+    skip('Claude Code gateway not requested — model traffic + auth untouched (MCP tools only). Re-run with --gateway to route it via the proxy.');
   } else {
-    warn('Claude Code gateway NOT activated — no ANTHROPIC_API_KEY in this environment.');
-    warn(`  Model traffic keeps going directly to Anthropic (subscription/OAuth or your own key, unchanged).`);
-    warn(`  Only Lemma's MCP tools are active for Claude Code — no cache savings on the model traffic itself.`);
-    warn(`  To enable it: export ANTHROPIC_API_KEY=sk-ant-... and re-run \`lemma init\`.`);
-    warn(`  This SWITCHES Claude Code off your subscription/OAuth session for LLM calls — they'll be`);
-    warn(`  signed by the proxy's own ANTHROPIC_API_KEY instead, and billed/rate-limited as API usage.`);
+    const anthropicApiKey = process.env.ANTHROPIC_API_KEY || '';
+    const gatewayResult = configureClaudeCodeGateway(anthropicApiKey);
+    if (gatewayResult.activated) {
+      ok(`Claude Code gateway activated (~/.claude/settings.json → ANTHROPIC_BASE_URL=http://localhost:${PORT})`);
+    } else {
+      warn('Claude Code gateway NOT activated — no ANTHROPIC_API_KEY in this environment.');
+      warn(`  Model traffic keeps going directly to Anthropic (subscription/OAuth or your own key, unchanged).`);
+      warn(`  Only Lemma's MCP tools are active for Claude Code — no cache savings on the model traffic itself.`);
+      warn(`  To enable it: export ANTHROPIC_API_KEY=sk-ant-... and re-run \`lemma init --gateway\`.`);
+      warn(`  This SWITCHES Claude Code off your subscription/OAuth session for LLM calls — they'll be`);
+      warn(`  signed by the proxy's own ANTHROPIC_API_KEY instead, and billed/rate-limited as API usage.`);
+    }
   }
 
   updateAgentsMd();
@@ -951,9 +1050,11 @@ async function main() {
   configureOpenCode();
   ok('OpenCode configured (opencode.json MCP + instructions)');
 
-  const museOk = configureMuse();
-  if (museOk) ok('Muse configured (.agents/skills/lemma/SKILL.md)');
-  else warn('Muse skill could not be configured');
+  const museResult = configureMuse();
+  if (museResult.project) {
+    ok('Muse configured (.agents/skills/lemma/SKILL.md)' + (museResult.user ? ' + user skill (auto-load in every muse session)' : ''));
+    if (!museResult.user) warn(`Muse user skill NOT installed — ${museResult.userReason || 'unknown reason'}`);
+  } else warn('Muse skill could not be configured');
 
   const hasContinue = detectTool('Continue.dev', () => configureContinueDotDev());
   if (hasContinue) ok('Continue.dev configured');
@@ -984,9 +1085,15 @@ async function main() {
   if (hasWindsurf) ok('Windsurf detected — env auto-configured');
   else skip('Windsurf not detected');
 
-  const daemonOk = installProxyDaemon();
-  if (daemonOk) ok('Cache proxy daemon installed & started (OpenAI + Anthropic /v1/messages, streaming)');
-  else warn('Could not install daemon — run `lemma proxy start` manually');
+  if (opts.wantDaemon) {
+    const daemonOk = installProxyDaemon();
+    if (daemonOk) ok('Cache proxy daemon installed & started (OpenAI + Anthropic /v1/messages, streaming)');
+    else warn('Could not install daemon — run `lemma proxy start` manually');
+  } else if (removeProxyDaemon()) {
+    ok('Removed previously installed proxy daemon (re-run with --daemon to restore it)');
+  } else {
+    skip('Proxy daemon not installed (opt-in via `lemma init --daemon`)');
+  }
 
   const envFile = createEnvFile();
   ok(`Env file created: ${envFile}`);
@@ -997,10 +1104,15 @@ async function main() {
 
   process.stderr.write(`\n  ${BOLD}${GREEN}✓ Lemma init complete${RESET}\n`);
   process.stderr.write(`  ${DIM}──────────────────────────────────────${RESET}\n`);
-  process.stderr.write(`  ${GREEN}●${RESET} Cache proxy running on http://localhost:${PORT}\n`);
+  if (opts.wantDaemon) {
+    process.stderr.write(`  ${GREEN}●${RESET} Cache proxy running on http://localhost:${PORT}\n`);
+  } else {
+    process.stderr.write(`  ${DIM}○ Cache proxy daemon not installed (opt-in: \`lemma init --daemon\`)${RESET}\n`);
+  }
   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`);
+  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`);
   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`);
@@ -1009,7 +1121,11 @@ async function main() {
   process.stderr.write(`  ${DIM}Logs: ${LEMMA_CACHE}/proxy-daemon.log${RESET}\n\n`);
 }
 
-main().catch(e => {
-  console.error('init failed:', e.message);
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch(e => {
+    console.error('init failed:', e.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { main, configureMuse, configureMuseUserSkill, updateAgentsMd, MUSE_SKILL_CONTENT, LEMMA_RULES_CONTENT, installProxyDaemon, removeProxyDaemon, parseInitArgs, createEnvFile };

package/bin/postinstall.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Lemma postinstall — registers the Lemma skill in the user's GLOBAL muse
+ * 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.
+ */
+
+const { execSync, execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function museOnPath() {
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('where', ['muse'], { stdio: 'ignore', timeout: 10000 });
+    } else {
+      execSync('command -v muse', { stdio: 'ignore', timeout: 10000 });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function main() {
+  try {
+    const skillDir = path.join(__dirname, '..', '.agents', 'skills', 'lemma');
+    if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) return;
+    if (!museOnPath()) return;
+    execFileSync('muse', ['skills', 'install', skillDir, '--scope', 'user', '--force'],
+      { stdio: 'ignore', timeout: 25000 });
+  } catch {
+    // Best-effort by contract: npm install must never fail because of this.
+  }
+}
+
+main();

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

@@ -2,6 +2,8 @@
 export declare function startBackgroundClipboardWatcher(cliOpts?: {
     clipboard?: boolean;
 }): void;
+export declare const MAX_WORKSPACE_WATCHERS = 512;
+export declare function isUnsafeWatchRoot(dir: string): boolean;
 export declare function performAutoHeal(apply: boolean): Promise<{
     success: boolean;
     message: string;

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

@@ -1 +1 @@
-{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA0cA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AA4nED,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA8KhL"}
+{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA0cA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AAqfD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGtD;AAyqDD,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA8KhL"}