@nxuss/lemma 1.21.0 → 1.22.0

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');
@@ -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() {
@@ -951,9 +989,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');
@@ -1001,6 +1041,7 @@ async function main() {
   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 +1050,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 };

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/lemma-proxy.cjs

@@ -35,7 +35,14 @@ const cmd = process.argv[2];
 
 if (cmd === 'init') {
   const initPath = path.join(__dirname, 'bin', 'init.js');
-  if (fs.existsSync(initPath)) require(initPath);
+  if (fs.existsSync(initPath)) {
+    const initMod = require(initPath);
+    // bin/init.js self-runs only when executed directly; via this `lemma`
+    // binary path it is required, so invoke its exported main().
+    if (initMod && typeof initMod.main === 'function') {
+      initMod.main().catch(e => { console.error('init failed:', e.message); process.exit(1); });
+    }
+  }
   else { console.error('init not found. Run npm run build first.'); process.exit(1); }
 } else if (cmd === 'stats') {
   const cliPath = path.join(__dirname, 'bin', 'cli.js');
@@ -67,6 +74,17 @@ if (cmd === 'init') {
     console.error('lemma-call not found. Run npm run build first.');
     process.exit(1);
   }
+} else if (cmd === 'doctor') {
+  const doctorPath = path.join(__dirname, 'bin', 'doctor.js');
+  if (fs.existsSync(doctorPath)) {
+    const doctorMod = require(doctorPath);
+    if (doctorMod && typeof doctorMod.main === 'function') {
+      doctorMod.main().then((code) => process.exit(code)).catch((e) => {
+        console.error('doctor failed:', e.message);
+        process.exit(1);
+      });
+    }
+  } else { console.error('doctor not found.'); process.exit(1); }
 } else if (cmd === 'proxy') {
   const proxyPath = path.join(__dirname, 'cache-proxy.js');
   if (fs.existsSync(proxyPath)) require(proxyPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxuss/lemma",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Intelligent AI Gateway for IDEs & Agents — Semantic cache, Privacy Firewall, Infrastructure Command Center, and Autonomous Cost-Optimization.",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -87,6 +87,8 @@
     "bin/init.js",
     "bin/cli.js",
     "bin/lemma-call.js",
+    "bin/postinstall.js",
+    "bin/doctor.js",
     "bin/checkpoint.js",
     "bin/brain-ingest.js",
     ".agents/skills/lemma/SKILL.md",
@@ -108,6 +110,7 @@
     "build:sdks": "npm run sdk:build",
     "postbuild": "node scripts/post-build.js && node scripts/fix-esm-extensions.js",
     "prepare": "npm run build:cjs 2>&1 | tail -n 5 || true",
+    "postinstall": "node bin/postinstall.js || true",
     "dev": "npx tsx start-dev.ts",
     "start": "node dist/cjs/index.js",
     "test": "jest",