@eventmodelers/cli 0.0.1 → 0.0.2

package/README.md

@@ -41,6 +41,16 @@ your-project/
 
 The four backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc. `modeling-kit` only installs skills + the agent loop, with no backend opinion.
 
+### Installing skills globally
+
+By default, skills are copied into the project's own `.claude/skills/`. Pass `--global` to `init` or `init-modeling` to install them into `~/.claude/skills/` instead — available in every project without re-running the installer each time:
+
+```bash
+npx @eventmodelers/cli init-modeling --global
+```
+
+Everything else (the kit dir, project scaffold, credentials, MCP registration) still targets the current directory as usual — `--global` only changes where skills land.
+
 ## Claude execution & config resolution
 
 During install you can optionally point the agent at a local LLM server (vLLM, Ollama) instead of the default Claude Code endpoint, and/or pin a specific model:
@@ -144,19 +154,41 @@ Which skills install depends on the chosen stack — see `stacks/<name>/template
 ## Commands
 
 ```bash
-npx @eventmodelers/cli init --stack <name>   # scaffold a stack + install + configure (alias: install)
-npx @eventmodelers/cli init-modeling         # skills + agent loop only, no backend scaffold (alias: modeling)
-npx @eventmodelers/cli run                   # start the agent loop (ralph-claude.js) from the installed kit dir
-npx @eventmodelers/cli run --ollama          # same, via local Ollama (ralph-ollama.js)
-npx @eventmodelers/cli run --bash            # bash-only loop, no realtime (ralph.sh)
-npx @eventmodelers/cli stacks                # list available stacks
-npx @eventmodelers/cli status                # check what's installed
-npx @eventmodelers/cli config                # print the fully resolved config (file + env), token masked
-npx @eventmodelers/cli uninstall             # remove the installed kit dir
+npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install + configure (alias: install)
+npx @eventmodelers/cli init --stack <name> --global # same, but skills go to ~/.claude/skills/ (every project)
+npx @eventmodelers/cli init-modeling                # skills + agent loop only, no backend scaffold (alias: modeling)
+npx @eventmodelers/cli init-modeling --global       # same, but skills go to ~/.claude/skills/ (every project)
+npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
+npx @eventmodelers/cli run --ollama                 # same, via local Ollama (ralph-ollama.js)
+npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
+npx @eventmodelers/cli stacks                       # list available stacks
+npx @eventmodelers/cli status                       # check what's installed
+npx @eventmodelers/cli config                       # print the fully resolved config (file + env), token masked
+npx @eventmodelers/cli uninstall                    # remove everything init/init-modeling installed
 ```
 
 `run` is a thin dispatcher — it just finds the installed kit dir (whatever it's named for the stack) and execs the runner file already sitting in it. The agent loop's actual logic stays in the scaffolded `<kit-dir>/`, not in this package, since you (and the agent itself, via `AGENT.md`) may customize those files per project.
 
+### Uninstall
+
+Every `init`/`init-modeling` run writes an install manifest into `<kit-dir>/.eventmodelers/install-manifest.json` recording exactly what it put down. `uninstall` reads that manifest back and removes only:
+
+- the kit dir (`.build-kit/` or `.agent-modeling-kit/`)
+- the skills it copied — from `.claude/skills/` normally, or `~/.claude/skills/` if it was installed with `--global`
+- the `eventmodelers` entry it added to `.claude/settings.json`'s `mcpServers` (the rest of that file, and the file itself, is left in place)
+
+It deliberately **never** touches the root project scaffold (`package.json`, `src/`, `server.ts`, migrations, `docker-compose.yml`, etc.) — that's your actual application code, not tooling, so `uninstall` won't delete it even though `init` wrote it.
+
+If a kit dir predates this tracking (no manifest present), `uninstall` falls back to only removing the kit dir itself and tells you so — any skills or MCP registration from that older install need to be cleaned up by hand.
+
+Registering the MCP server with another harness (`claude mcp add`, `code --add-mcp`, or the manual Cursor/Windsurf steps) happens outside this project's files, so `uninstall` doesn't attempt to undo it — remove it yourself in that harness if you connected one.
+
+```bash
+npx @eventmodelers/cli uninstall                    # remove the one installed kit dir (errors if more than one is present)
+npx @eventmodelers/cli uninstall --build-kit         # remove .build-kit/ specifically
+npx @eventmodelers/cli uninstall --modeling-kit      # remove .agent-modeling-kit/ specifically
+```
+
 `--config <path>` and `--print` are global flags accepted by every command. `--print` skips the "connect MCP globally?" prompt during install and just prints the `claude mcp add` command instead of running it — combined with the env vars above, `--print` makes `init` fully non-interactive:
 
 ```bash

package/cli.js

@@ -15,6 +15,7 @@ import {
 } from 'fs';
 import { execSync } from 'child_process';
 import { createInterface, emitKeypressEvents, moveCursor, clearScreenDown } from 'readline';
+import { homedir } from 'os';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -285,10 +286,26 @@ async function installStack(stackKey, stackCfg, options = {}) {
       process.exit(1);
     }
 
-    // --- 1. Install skills and Claude settings into project root ---
-    console.log('📦 Installing Claude skills...');
-    console.log('   Copies skills and settings into .claude/ so Claude Code picks them up automatically.\n');
-    copyDirContents(join(templatesSource, '.claude'), join(targetDir, '.claude'));
+    // --- 1. Install skills (project-local by default, or ~/.claude/skills/ with --global) ---
+    // Recorded into the install manifest (step 8) so `uninstall` can remove exactly
+    // these files later and nothing the user added independently.
+    const claudeSkillsSrc = join(templatesSource, '.claude', 'skills');
+    const installedSkills = existsSync(claudeSkillsSrc) ? readdirSync(claudeSkillsSrc) : [];
+    let claudeExtras = [];
+
+    if (options.global) {
+      const globalSkillsDir = join(homedir(), '.claude', 'skills');
+      console.log('📦 Installing Claude skills globally...');
+      console.log(`   Copies skills into ${globalSkillsDir} so they're available in every project, not just this one.\n`);
+      copyDirContents(claudeSkillsSrc, globalSkillsDir);
+    } else {
+      console.log('📦 Installing Claude skills...');
+      console.log('   Copies skills and settings into .claude/ so Claude Code picks them up automatically.\n');
+      copyDirContents(join(templatesSource, '.claude'), join(targetDir, '.claude'));
+      claudeExtras = existsSync(join(templatesSource, '.claude'))
+        ? readdirSync(join(templatesSource, '.claude')).filter((f) => f !== 'skills')
+        : [];
+    }
 
     // --- 2. Spread stack scaffold files into the project root ---
     const rootSrc = join(templatesSource, 'root');
@@ -493,6 +510,17 @@ async function installStack(stackKey, stackCfg, options = {}) {
       }
     }
 
+    // --- 8. Install manifest (drives precise `uninstall` later) ---
+    // Only the footprint listed here is ever removed by `uninstall` — the root
+    // scaffold (step 2) is real project source the user builds on, so it's
+    // deliberately left out and never touched by uninstall.
+    const manifestDir = join(kitDir, '.eventmodelers');
+    mkdirSync(manifestDir, { recursive: true });
+    writeFileSync(
+      join(manifestDir, 'install-manifest.json'),
+      JSON.stringify({ stack: stackKey, global: !!options.global, skills: installedSkills, claudeExtras, mcpRegistered: true }, null, 2),
+    );
+
     console.log('\n✅ Done!\n');
     console.log('Start the agent (realtime + task loop in one process):');
     console.log('       npx @eventmodelers/cli run\n');
@@ -500,7 +528,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     console.log('       npx @eventmodelers/cli run --ollama\n');
     console.log('Or using the bash loop only (no realtime):');
     console.log('       npx @eventmodelers/cli run --bash\n');
-    console.log(`Skills are ready in .claude/skills/ — use /connect to set a board ID.\n`);
+    console.log(`Skills are ready in ${options.global ? join(homedir(), '.claude', 'skills') : '.claude/skills/'} — use /connect to set a board ID.\n`);
     console.log('💡 Recommended: add Chrome DevTools MCP for browser inspection:');
     console.log('       claude mcp add chrome-devtools --scope user -- npx chrome-devtools-mcp@latest\n');
 }
@@ -519,19 +547,21 @@ program
   .alias('install')
   .description('Scaffold a stack + install the agent modeling kit into the current directory')
   .option('--stack <name>', `Stack to install (${Object.keys(STACKS).join(', ')})`)
+  .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
   .action(async (opts, command) => {
     const stackKey = await resolveStack(opts.stack);
     const globalOpts = command.optsWithGlobals();
-    await installStack(stackKey, STACKS[stackKey], { configPath: globalOpts.config, print: globalOpts.print });
+    await installStack(stackKey, STACKS[stackKey], { configPath: globalOpts.config, print: globalOpts.print, global: opts.global });
   });
 
 program
   .command('init-modeling')
   .alias('modeling')
   .description('Install skills + the agent loop only — no backend scaffold')
+  .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
-    await installStack(MODELING_KIT.key, MODELING_KIT, { configPath: globalOpts.config, print: globalOpts.print });
+    await installStack(MODELING_KIT.key, MODELING_KIT, { configPath: globalOpts.config, print: globalOpts.print, global: opts.global });
   });
 
 program
@@ -579,9 +609,60 @@ program
     console.log(`\nNot a stack — skills + agent loop only, no backend: npx @eventmodelers/cli init-modeling`);
   });
 
+// Removes exactly what a given `init`/`init-modeling` run put down — read back from
+// the install manifest written at the end of installStack() — and nothing else: not
+// unrelated skills the user added by hand, not the root project scaffold.
+function uninstallKitDir(kitDir, cwd) {
+  const manifestPath = join(kitDir, '.eventmodelers', 'install-manifest.json');
+  const manifest = readJsonSafe(manifestPath);
+
+  if (manifest.skills?.length) {
+    const skillsDir = manifest.global ? join(homedir(), '.claude', 'skills') : join(cwd, '.claude', 'skills');
+    for (const name of manifest.skills) {
+      const p = join(skillsDir, name);
+      if (existsSync(p)) {
+        rmSync(p, { recursive: true, force: true });
+        console.log(`  ✓ Removed ${relative(cwd, p) || p}`);
+      }
+    }
+  }
+
+  if (manifest.claudeExtras?.length && !manifest.global) {
+    for (const name of manifest.claudeExtras) {
+      const p = join(cwd, '.claude', name);
+      if (existsSync(p)) {
+        rmSync(p, { recursive: true, force: true });
+        console.log(`  ✓ Removed ${relative(cwd, p)}`);
+      }
+    }
+  }
+
+  if (manifest.mcpRegistered) {
+    const settingsPath = join(cwd, '.claude', 'settings.json');
+    if (existsSync(settingsPath)) {
+      try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        if (settings.mcpServers?.[MCP_SERVER_NAME]) {
+          delete settings.mcpServers[MCP_SERVER_NAME];
+          if (Object.keys(settings.mcpServers).length === 0) delete settings.mcpServers;
+          writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+          console.log(`  ✓ Removed ${MCP_SERVER_NAME} MCP entry from ${relative(cwd, settingsPath)}`);
+        }
+      } catch {}
+    }
+  }
+
+  if (!existsSync(manifestPath)) {
+    console.log(`  ℹ️  ${relative(cwd, kitDir)} predates install tracking — only the kit dir itself was removed; any installed skills or MCP registration must be cleaned up by hand.`);
+  }
+
+  rmSync(kitDir, { recursive: true, force: true });
+  console.log(`  ✓ Removed ${relative(cwd, kitDir) || kitDir}`);
+}
+
 program
   .command('uninstall')
-  .description('Remove the installed kit dir from the current directory')
+  .description('Remove everything init/init-modeling installed: the kit dir, the skills it copied (project-local or ~/.claude/skills with --global), and its MCP entry in .claude/settings.json. Leaves the root project scaffold untouched.')
   .option('--build-kit', `Remove ${STACKS.node.kitDirName}/ (the backend-stack kit dir)`)
   .option('--modeling-kit', `Remove ${MODELING_KIT.kitDirName}/ (the modeling-only kit dir)`)
   .action((opts) => {
@@ -611,8 +692,7 @@ program
     }
 
     for (const t of targets) {
-      rmSync(t, { recursive: true, force: true });
-      console.log(`  ✓ Removed ${t}`);
+      uninstallKitDir(t, cwd);
     }
     console.log('✅ Uninstalled');
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, or modeling-only)",
   "type": "module",
   "bin": {