@hanzlaa/rcode 3.4.16 → 3.4.18

package/cli/doctor.js

@@ -259,6 +259,77 @@ function runCompliance(packageRoot) {
   return failing;
 }
 
+// ---------- Duplicate-installation check ----------
+
+/**
+ * Detect rcode/rihal-code installations across all known package managers.
+ * Multiple installs cause duplicate slash commands in Claude Code (#637-#644).
+ * Returns { count, installs[], warnings[] }.
+ */
+function checkDuplicateInstalls() {
+  const os = require('os');
+  const home = os.homedir();
+  const installs = [];
+
+  // Resolve every global node_modules dir we know about.
+  const dirs = [];
+  for (const cmd of [['npm', ['root', '-g']], ['pnpm', ['root', '-g']]]) {
+    try {
+      const r = spawnSync(cmd[0], cmd[1], { encoding: 'utf8' });
+      if (r.status === 0 && r.stdout.trim()) dirs.push({ manager: cmd[0], dir: r.stdout.trim() });
+    } catch { /* not installed */ }
+  }
+  // Also scan all nvm node versions — npm root -g only covers the active one.
+  const nvmRoot = path.join(home, '.nvm', 'versions', 'node');
+  if (fs.existsSync(nvmRoot)) {
+    for (const v of fs.readdirSync(nvmRoot)) {
+      const dir = path.join(nvmRoot, v, 'lib', 'node_modules');
+      if (fs.existsSync(dir) && !dirs.some(d => d.dir === dir)) {
+        dirs.push({ manager: `nvm/${v}`, dir });
+      }
+    }
+  }
+
+  for (const { manager, dir } of dirs) {
+    for (const scope of ['@hanzlaa', '@hanzlahabib']) {
+      const scopeDir = path.join(dir, scope);
+      if (!fs.existsSync(scopeDir)) continue;
+      for (const pkg of fs.readdirSync(scopeDir)) {
+        if (pkg === 'rcode' || pkg === 'rihal-code' || pkg.startsWith('rihal')) {
+          let version = 'unknown';
+          try {
+            const pkgJson = JSON.parse(fs.readFileSync(path.join(scopeDir, pkg, 'package.json'), 'utf8'));
+            version = pkgJson.version;
+          } catch {}
+          installs.push({ manager, scope, pkg, version, dir: path.join(scopeDir, pkg) });
+        }
+      }
+    }
+  }
+
+  return { count: installs.length, installs };
+}
+
+function printDuplicateChecks(result) {
+  if (result.count === 0) {
+    console.log(`   ✓ No global rcode installs found`);
+    return 0;
+  }
+  if (result.count === 1) {
+    const i = result.installs[0];
+    console.log(`   ✓ Single global install: [${i.manager}] ${i.scope}/${i.pkg}@${i.version}`);
+    return 0;
+  }
+  // Multiple installs — DUPLICATE — this causes the duplicate-commands bug.
+  console.log(`   ✗ ${result.count} global installs detected — this causes duplicate slash commands!`);
+  for (const i of result.installs) {
+    console.log(`     [${i.manager}] ${i.scope}/${i.pkg}@${i.version}`);
+    console.log(`       ${i.dir}`);
+  }
+  console.log(`\n     Fix: rcode nuke --yes && npm install -g @hanzlaa/rcode`);
+  return 1;
+}
+
 // ---------- Entrypoint ----------
 
 module.exports = function doctor(args, { packageRoot }) {
@@ -270,10 +341,14 @@ module.exports = function doctor(args, { packageRoot }) {
   const checks = runPreflight(cwd, packageRoot);
   const preflightFailures = printChecks(checks);
 
+  console.log(`\nDuplicate installations:`);
+  const dupResult = checkDuplicateInstalls();
+  const duplicateFailures = printDuplicateChecks(dupResult);
+
   console.log(`\nPackage compliance:`);
   const complianceFailures = runCompliance(packageRoot);
 
-  const totalFailures = preflightFailures + complianceFailures;
+  const totalFailures = preflightFailures + complianceFailures + duplicateFailures;
   console.log();
   if (totalFailures === 0) {
     console.log(`✅ All checks passed.`);

package/cli/index.js

@@ -25,6 +25,7 @@ const COMMANDS = {
   update: require('./update'),
   uninstall: require('./uninstall'),
   remove: require('./uninstall'),  // alias
+  nuke: require('./nuke'),         // full cleanup across all package managers + global state
   dashboard: require('./dashboard'),
   serve: require('./dashboard'),
   digest: require('./digest'),
@@ -57,6 +58,10 @@ Usage:
   update         Refresh skill files (backs up .rihal/ state first)
   uninstall      Remove Rihal Code from the current project
   remove         Alias for uninstall
+  nuke           Wipe ALL rihal/rcode installs everywhere (global packages,
+                 binaries, ~/.claude/* rihal artifacts, ~/.rihal/, project artifacts)
+                 Default = dry-run. Pass --yes to remove. Pass --include-planning
+                 to also remove .planning/ in CWD.
   config         Get/set project configuration (project_name, user_name, etc.)
   context        Memory bank freshness (--check | --refresh | --install-hook)
   github-sync    Sync .rihal/ phases/epics/stories to GitHub (dry-run default)
@@ -86,9 +91,56 @@ Documentation: https://github.com/hanzlahabib/rihal-code
   `.trim());
 }
 
+/**
+ * npm 10+ suppresses postinstall script output during global installs, so users
+ * who run `npm install -g @hanzlaa/rcode` see only "added 1 package" with no
+ * confirmation that 100+ commands and skills were installed. We detect a fresh
+ * install on the first `rcode <anything>` invocation by checking for a marker
+ * file under ~/.rihal/, print a one-time welcome banner, then drop the marker.
+ */
+function maybeShowFirstRunBanner() {
+  const os = require('os');
+  const home = os.homedir();
+  const markerDir = path.join(home, '.rihal');
+  const marker = path.join(markerDir, '.welcome-shown');
+  if (fs.existsSync(marker)) return;
+
+  // Only show banner if global install actually ran — i.e. ~/.claude/commands/
+  // has rihal-*.md files. Otherwise this is a developer running from source.
+  const globalCommands = path.join(home, '.claude', 'commands');
+  let hasGlobalRihal = false;
+  try {
+    hasGlobalRihal = fs.existsSync(globalCommands) &&
+      fs.readdirSync(globalCommands).some(f => f.startsWith('rihal-') && f.endsWith('.md'));
+  } catch { /* unreadable */ }
+  if (!hasGlobalRihal) return;
+
+  console.log(`\n🕌 Rihal Code v${PACKAGE_JSON.version} — first run detected.\n`);
+  console.log(`   ✓ ${countGlobalRihal(globalCommands)} slash commands installed → ~/.claude/commands/`);
+  console.log(`   ✓ All /rihal-* commands available in every Claude Code project.`);
+  console.log(`\n   To set up a project:  cd my-project && rcode install`);
+  console.log(`   Show all commands:    rcode help`);
+  console.log(`   Diagnose issues:      rcode doctor\n`);
+
+  try {
+    fs.mkdirSync(markerDir, { recursive: true });
+    fs.writeFileSync(marker, `installed ${PACKAGE_JSON.version} at ${new Date().toISOString()}\n`);
+  } catch { /* if we can't write the marker, banner shows again next time — annoying but not broken */ }
+}
+
+function countGlobalRihal(dir) {
+  try {
+    return fs.readdirSync(dir).filter(f => f.startsWith('rihal-') && f.endsWith('.md')).length;
+  } catch { return 0; }
+}
+
 async function main() {
   const [, , command = 'help', ...args] = process.argv;
 
+  // Show first-run banner before dispatching — npm hides postinstall output,
+  // so this is the user's first visible confirmation that the install worked.
+  maybeShowFirstRunBanner();
+
   const handler = COMMANDS[command];
   if (!handler) {
     console.error(`Unknown command: ${command}`);

package/cli/install.js

@@ -177,6 +177,13 @@ function parseArgs(argv) {
     opts.target = path.resolve(positional[0]);
     opts.targetProvided = true;
   }
+  // --global without an explicit target means "install to ~/.claude/" — i.e.
+  // home dir. Without this, running `rcode install --global` from inside a
+  // project directory wrote rihal artifacts to that project, not to the user's
+  // home where Claude Code reads global commands from.
+  if (opts.global && !opts.targetProvided) {
+    opts.target = os.homedir();
+  }
   if (!opts.projectName) opts.projectName = path.basename(opts.target);
   return opts;
 }

package/cli/nuke.js

@@ -0,0 +1,404 @@
+/**
+ * rcode nuke — one-shot full cleanup
+ *
+ * Removes EVERY trace of rihal/rcode from the system:
+ *   - Global npm/pnpm/yarn/bun installs (both @hanzlaa/rcode and legacy @hanzlahabib/rihal-code)
+ *   - Global binaries (rcode, rihal, rihal-code) in all known PATH dirs
+ *   - Global Claude Code artifacts (~/.claude/commands/rihal*, ~/.claude/agents/rihal-*, ~/.claude/skills/rihal-*)
+ *   - Global state (~/.rihal/)
+ *   - Project-level artifacts in CWD (.claude/commands/rihal*, .claude/agents/rihal-*, .rihal/, .planning/ optional)
+ *
+ * Default mode: dry-run — prints what *would* be removed.
+ * Pass --yes to actually remove. Pass --include-planning to also remove .planning/ in CWD.
+ *
+ * Why this exists: gaps #1-#4 in the duplicate-commands incident (May 2026).
+ * - Multiple package managers can hold separate copies invisibly to each other.
+ * - rcode uninstall only cleans the project, not global package installs.
+ * - Users had no single command to fully reset.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function exists(p) {
+  try { fs.accessSync(p); return true; } catch { return false; }
+}
+
+function readDirSafe(p) {
+  try { return fs.readdirSync(p); } catch { return []; }
+}
+
+/**
+ * Resolve where each package manager keeps its global node_modules.
+ * Returns a list of { manager, dir } — dir may not exist.
+ */
+function getGlobalNodeModulesDirs() {
+  const home = os.homedir();
+  const candidates = [];
+
+  // npm — npm root -g resolves to the active node version's lib/node_modules.
+  try {
+    const r = spawnSync('npm', ['root', '-g'], { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) candidates.push({ manager: 'npm', dir: r.stdout.trim() });
+  } catch { /* npm not installed */ }
+
+  // pnpm — `pnpm root -g`
+  try {
+    const r = spawnSync('pnpm', ['root', '-g'], { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) candidates.push({ manager: 'pnpm', dir: r.stdout.trim() });
+  } catch { /* pnpm not installed */ }
+
+  // yarn classic — `yarn global dir` returns the parent; node_modules is inside.
+  try {
+    const r = spawnSync('yarn', ['global', 'dir'], { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) {
+      candidates.push({ manager: 'yarn', dir: path.join(r.stdout.trim(), 'node_modules') });
+    }
+  } catch { /* yarn not installed */ }
+
+  // bun — `bun pm bin -g` returns the bin dir; sibling install/global has node_modules.
+  try {
+    const r = spawnSync('bun', ['pm', 'bin', '-g'], { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) {
+      // bun layout: ~/.bun/install/global/node_modules + ~/.bun/bin
+      candidates.push({ manager: 'bun', dir: path.join(home, '.bun', 'install', 'global', 'node_modules') });
+    }
+  } catch { /* bun not installed */ }
+
+  // Hardcoded fallbacks for stale/dead version managers (nvm versions that npm root doesn't know about).
+  const nvmRoot = path.join(home, '.nvm', 'versions', 'node');
+  if (exists(nvmRoot)) {
+    for (const v of readDirSafe(nvmRoot)) {
+      const dir = path.join(nvmRoot, v, 'lib', 'node_modules');
+      if (exists(dir) && !candidates.some(c => c.dir === dir)) {
+        candidates.push({ manager: `nvm/${v}`, dir });
+      }
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * For a given global node_modules dir, return a list of rihal/rcode package paths.
+ * Looks for both @hanzlaa/rcode (current) and @hanzlahabib/rihal-code (legacy).
+ */
+function findRihalPackages(globalNodeModules) {
+  const found = [];
+  for (const scope of ['@hanzlaa', '@hanzlahabib']) {
+    const scopeDir = path.join(globalNodeModules, scope);
+    if (!exists(scopeDir)) continue;
+    for (const pkg of readDirSafe(scopeDir)) {
+      // Match rcode, rihal-code, or anything starting with rihal
+      if (pkg === 'rcode' || pkg === 'rihal-code' || pkg.startsWith('rihal')) {
+        found.push({ scope, pkg, dir: path.join(scopeDir, pkg) });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Resolve global bin directories where rcode/rihal/rihal-code may live.
+ */
+function getGlobalBinDirs() {
+  const home = os.homedir();
+  const dirs = new Set();
+
+  // npm prefix bin
+  try {
+    const r = spawnSync('npm', ['prefix', '-g'], { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) dirs.add(path.join(r.stdout.trim(), 'bin'));
+  } catch {}
+
+  // pnpm bin
+  try {
+    const r = spawnSync('pnpm', ['bin', '-g'], { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) dirs.add(r.stdout.trim());
+  } catch {}
+
+  // yarn bin
+  try {
+    const r = spawnSync('yarn', ['global', 'bin'], { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) dirs.add(r.stdout.trim());
+  } catch {}
+
+  // bun
+  try {
+    const r = spawnSync('bun', ['pm', 'bin', '-g'], { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) dirs.add(r.stdout.trim());
+  } catch {}
+
+  // Hardcoded fallbacks
+  dirs.add(path.join(home, '.local', 'share', 'pnpm'));
+  dirs.add(path.join(home, '.local', 'bin'));
+  dirs.add(path.join(home, '.bun', 'bin'));
+
+  // nvm bins
+  const nvmRoot = path.join(home, '.nvm', 'versions', 'node');
+  if (exists(nvmRoot)) {
+    for (const v of readDirSafe(nvmRoot)) {
+      dirs.add(path.join(nvmRoot, v, 'bin'));
+    }
+  }
+
+  return [...dirs].filter(exists);
+}
+
+const RCODE_BINS = ['rcode', 'rihal', 'rihal-code'];
+
+function findRihalBins(binDir) {
+  const found = [];
+  for (const name of RCODE_BINS) {
+    const p = path.join(binDir, name);
+    if (exists(p)) {
+      let target = null;
+      try { target = fs.readlinkSync(p); } catch {}
+      // Only flag if it's clearly ours (target points at rcode/rihal-code package).
+      // If it's not a symlink, include it anyway — bare scripts in pnpm bin etc.
+      if (!target || /rcode|rihal-code|@hanzlaa|@hanzlahabib/.test(target)) {
+        found.push({ name, path: p, target });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Find rihal-related artifacts in a Claude Code config dir (~/.claude or .claude in CWD).
+ */
+function findClaudeArtifacts(claudeDir) {
+  const found = [];
+  if (!exists(claudeDir)) return found;
+
+  // .claude/commands/rihal-*.md (claude-style root)
+  const cmdRoot = path.join(claudeDir, 'commands');
+  if (exists(cmdRoot)) {
+    for (const f of readDirSafe(cmdRoot)) {
+      if (f.startsWith('rihal-') && (f.endsWith('.md') || f.endsWith('.mdc'))) {
+        found.push({ kind: 'command', path: path.join(cmdRoot, f) });
+      }
+    }
+    // .claude/commands/rihal/ (vscode-style subdir)
+    const rihalSubdir = path.join(cmdRoot, 'rihal');
+    if (exists(rihalSubdir)) {
+      found.push({ kind: 'commands-dir', path: rihalSubdir });
+    }
+  }
+
+  // .claude/agents/rihal-*.md
+  const agentsDir = path.join(claudeDir, 'agents');
+  if (exists(agentsDir)) {
+    for (const f of readDirSafe(agentsDir)) {
+      if (f.startsWith('rihal-') && (f.endsWith('.md') || f.endsWith('.mdc'))) {
+        found.push({ kind: 'agent', path: path.join(agentsDir, f) });
+      }
+    }
+  }
+
+  // .claude/skills/rihal-*
+  const skillsDir = path.join(claudeDir, 'skills');
+  if (exists(skillsDir)) {
+    for (const d of readDirSafe(skillsDir)) {
+      if (d.startsWith('rihal-')) {
+        found.push({ kind: 'skill-dir', path: path.join(skillsDir, d) });
+      }
+    }
+  }
+
+  return found;
+}
+
+function buildPlan({ includePlanning }) {
+  const home = os.homedir();
+  const cwd = process.cwd();
+  const plan = {
+    packages: [],
+    bins: [],
+    globalClaude: [],
+    globalRihal: null,
+    projectClaude: [],
+    projectRihal: null,
+    projectPlanning: null,
+  };
+
+  // Global node_modules packages
+  for (const { manager, dir } of getGlobalNodeModulesDirs()) {
+    for (const pkg of findRihalPackages(dir)) {
+      plan.packages.push({ manager, ...pkg });
+    }
+  }
+
+  // Global binaries
+  for (const binDir of getGlobalBinDirs()) {
+    for (const bin of findRihalBins(binDir)) {
+      plan.bins.push({ binDir, ...bin });
+    }
+  }
+
+  // Global Claude artifacts (~/.claude/)
+  plan.globalClaude = findClaudeArtifacts(path.join(home, '.claude'));
+
+  // Global state (~/.rihal/)
+  const globalRihal = path.join(home, '.rihal');
+  if (exists(globalRihal)) plan.globalRihal = globalRihal;
+
+  // Project-level (CWD only — never recurse, user may have many projects)
+  plan.projectClaude = findClaudeArtifacts(path.join(cwd, '.claude'));
+  const projectRihal = path.join(cwd, '.rihal');
+  if (exists(projectRihal) && cwd !== home) plan.projectRihal = projectRihal;
+
+  if (includePlanning) {
+    const projectPlanning = path.join(cwd, '.planning');
+    if (exists(projectPlanning) && cwd !== home) plan.projectPlanning = projectPlanning;
+  }
+
+  return plan;
+}
+
+function printPlan(plan, { dryRun }) {
+  const banner = dryRun ? '[DRY RUN — pass --yes to remove]' : '[REMOVING]';
+  console.log(`\n🔥 rcode nuke ${banner}\n`);
+
+  let total = 0;
+  const section = (title, items) => {
+    if (!items || (Array.isArray(items) && items.length === 0)) return;
+    console.log(`${title}`);
+    if (Array.isArray(items)) {
+      for (const item of items) {
+        console.log(`  • ${item.description || item.path || item.dir || JSON.stringify(item)}`);
+        total++;
+      }
+    } else {
+      console.log(`  • ${items}`);
+      total++;
+    }
+    console.log('');
+  };
+
+  section('📦 Global packages (node_modules):', plan.packages.map(p => ({
+    description: `[${p.manager}] ${p.scope}/${p.pkg}  →  ${p.dir}`,
+  })));
+
+  section('🔗 Global binaries:', plan.bins.map(b => ({
+    description: `${b.path}${b.target ? `  →  ${b.target}` : ''}`,
+  })));
+
+  section('🤖 ~/.claude/ artifacts:', plan.globalClaude.map(a => ({
+    description: `[${a.kind}] ${a.path}`,
+  })));
+
+  if (plan.globalRihal) section('🗂️  ~/.rihal/ (global state):', plan.globalRihal);
+
+  section('🤖 ./.claude/ artifacts (current project):', plan.projectClaude.map(a => ({
+    description: `[${a.kind}] ${a.path}`,
+  })));
+
+  if (plan.projectRihal) section('🗂️  ./.rihal/ (project state):', plan.projectRihal);
+  if (plan.projectPlanning) section('📋 ./.planning/ (your work — only with --include-planning):', plan.projectPlanning);
+
+  if (total === 0) {
+    console.log('  ✓ nothing to remove — system is clean.\n');
+  } else {
+    console.log(`  Total: ${total} item(s).\n`);
+  }
+  return total;
+}
+
+function rmrf(p) {
+  try { fs.rmSync(p, { recursive: true, force: true }); return true; }
+  catch (err) { console.warn(`  ⚠ failed to remove ${p}: ${err.message}`); return false; }
+}
+
+function uninstallPackage(manager, scope, pkg) {
+  const fullName = `${scope}/${pkg}`;
+  const cmd = manager === 'pnpm' ? ['pnpm', ['remove', '-g', fullName]]
+    : manager === 'yarn' ? ['yarn', ['global', 'remove', fullName]]
+    : manager === 'bun' ? ['bun', ['remove', '-g', fullName]]
+    : ['npm', ['uninstall', '-g', fullName]];
+  try {
+    const r = spawnSync(cmd[0], cmd[1], { stdio: 'pipe', encoding: 'utf8' });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+function executePlan(plan) {
+  let removed = 0;
+
+  // Try clean uninstall via package manager first (cleans bins automatically)
+  for (const p of plan.packages) {
+    const manager = p.manager.startsWith('nvm/') ? 'npm' : p.manager;
+    process.stdout.write(`  ${manager} uninstall ${p.scope}/${p.pkg} ... `);
+    const ok = uninstallPackage(manager, p.scope, p.pkg);
+    console.log(ok ? '✓' : '⚠ failed via PM, falling back to rm');
+    if (!ok) rmrf(p.dir);
+    removed++;
+  }
+
+  // Force-remove any leftover bins (broken symlinks etc.)
+  for (const b of plan.bins) {
+    if (exists(b.path)) {
+      if (rmrf(b.path)) { console.log(`  ✓ removed bin ${b.path}`); removed++; }
+    }
+  }
+
+  // Claude artifacts (global)
+  for (const a of plan.globalClaude) {
+    if (rmrf(a.path)) { console.log(`  ✓ removed ${a.path}`); removed++; }
+  }
+  if (plan.globalRihal && rmrf(plan.globalRihal)) {
+    console.log(`  ✓ removed ${plan.globalRihal}`); removed++;
+  }
+
+  // Claude artifacts (project)
+  for (const a of plan.projectClaude) {
+    if (rmrf(a.path)) { console.log(`  ✓ removed ${a.path}`); removed++; }
+  }
+  if (plan.projectRihal && rmrf(plan.projectRihal)) {
+    console.log(`  ✓ removed ${plan.projectRihal}`); removed++;
+  }
+  if (plan.projectPlanning && rmrf(plan.projectPlanning)) {
+    console.log(`  ✓ removed ${plan.projectPlanning}`); removed++;
+  }
+
+  return removed;
+}
+
+module.exports = function nuke(args = []) {
+  const dryRun = !args.includes('--yes') && !args.includes('-y');
+  const includePlanning = args.includes('--include-planning');
+
+  // Safety: detect if CWD is the rcode source repo itself.
+  const cwdPkgJson = path.join(process.cwd(), 'package.json');
+  if (exists(cwdPkgJson)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(cwdPkgJson, 'utf8'));
+      if (pkg.name === '@hanzlaa/rcode' || pkg.name === '@hanzlahabib/rihal-code') {
+        console.log('\n⚠  You are inside the rcode source repo.');
+        console.log('   Nuke would remove this repo\'s .claude/, .rihal/, and possibly .planning/.');
+        console.log('   That is your source code — almost certainly not what you want.');
+        console.log('   Run nuke from a different directory, or pass --i-know-what-im-doing to override.\n');
+        if (!args.includes('--i-know-what-im-doing')) return;
+      }
+    } catch { /* package.json unreadable, ignore */ }
+  }
+
+  const plan = buildPlan({ includePlanning });
+  const total = printPlan(plan, { dryRun });
+
+  if (total === 0 || dryRun) {
+    if (dryRun && total > 0) {
+      console.log('To actually remove these, re-run with:  rcode nuke --yes');
+      console.log('To also remove .planning/ (your work):  rcode nuke --yes --include-planning\n');
+    }
+    return;
+  }
+
+  console.log('Executing...\n');
+  const removed = executePlan(plan);
+  console.log(`\n✅ Done. Removed ${removed} item(s). Reinstall:  npm install -g @hanzlaa/rcode\n`);
+};

package/dist/rcode.js

@@ -15063,6 +15063,9 @@ var require_install = __commonJS({
         opts.target = path2.resolve(positional[0]);
         opts.targetProvided = true;
       }
+      if (opts.global && !opts.targetProvided) {
+        opts.target = os.homedir();
+      }
       if (!opts.projectName) opts.projectName = path2.basename(opts.target);
       return opts;
     }
@@ -17976,6 +17979,340 @@ To reinstall later:`);
   }
 });
 
+// cli/nuke.js
+var require_nuke = __commonJS({
+  "cli/nuke.js"(exports2, module2) {
+    "use strict";
+    var fs2 = require("fs");
+    var os = require("os");
+    var path2 = require("path");
+    var { spawnSync } = require("child_process");
+    function exists(p) {
+      try {
+        fs2.accessSync(p);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    function readDirSafe(p) {
+      try {
+        return fs2.readdirSync(p);
+      } catch {
+        return [];
+      }
+    }
+    function getGlobalNodeModulesDirs() {
+      const home = os.homedir();
+      const candidates = [];
+      try {
+        const r = spawnSync("npm", ["root", "-g"], { encoding: "utf8" });
+        if (r.status === 0 && r.stdout.trim()) candidates.push({ manager: "npm", dir: r.stdout.trim() });
+      } catch {
+      }
+      try {
+        const r = spawnSync("pnpm", ["root", "-g"], { encoding: "utf8" });
+        if (r.status === 0 && r.stdout.trim()) candidates.push({ manager: "pnpm", dir: r.stdout.trim() });
+      } catch {
+      }
+      try {
+        const r = spawnSync("yarn", ["global", "dir"], { encoding: "utf8" });
+        if (r.status === 0 && r.stdout.trim()) {
+          candidates.push({ manager: "yarn", dir: path2.join(r.stdout.trim(), "node_modules") });
+        }
+      } catch {
+      }
+      try {
+        const r = spawnSync("bun", ["pm", "bin", "-g"], { encoding: "utf8" });
+        if (r.status === 0 && r.stdout.trim()) {
+          candidates.push({ manager: "bun", dir: path2.join(home, ".bun", "install", "global", "node_modules") });
+        }
+      } catch {
+      }
+      const nvmRoot = path2.join(home, ".nvm", "versions", "node");
+      if (exists(nvmRoot)) {
+        for (const v of readDirSafe(nvmRoot)) {
+          const dir = path2.join(nvmRoot, v, "lib", "node_modules");
+          if (exists(dir) && !candidates.some((c) => c.dir === dir)) {
+            candidates.push({ manager: `nvm/${v}`, dir });
+          }
+        }
+      }
+      return candidates;
+    }
+    function findRihalPackages(globalNodeModules) {
+      const found = [];
+      for (const scope of ["@hanzlaa", "@hanzlahabib"]) {
+        const scopeDir = path2.join(globalNodeModules, scope);
+        if (!exists(scopeDir)) continue;
+        for (const pkg of readDirSafe(scopeDir)) {
+          if (pkg === "rcode" || pkg === "rihal-code" || pkg.startsWith("rihal")) {
+            found.push({ scope, pkg, dir: path2.join(scopeDir, pkg) });
+          }
+        }
+      }
+      return found;
+    }
+    function getGlobalBinDirs() {
+      const home = os.homedir();
+      const dirs = /* @__PURE__ */ new Set();
+      try {
+        const r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8" });
+        if (r.status === 0 && r.stdout.trim()) dirs.add(path2.join(r.stdout.trim(), "bin"));
+      } catch {
+      }
+      try {
+        const r = spawnSync("pnpm", ["bin", "-g"], { encoding: "utf8" });
+        if (r.status === 0 && r.stdout.trim()) dirs.add(r.stdout.trim());
+      } catch {
+      }
+      try {
+        const r = spawnSync("yarn", ["global", "bin"], { encoding: "utf8" });
+        if (r.status === 0 && r.stdout.trim()) dirs.add(r.stdout.trim());
+      } catch {
+      }
+      try {
+        const r = spawnSync("bun", ["pm", "bin", "-g"], { encoding: "utf8" });
+        if (r.status === 0 && r.stdout.trim()) dirs.add(r.stdout.trim());
+      } catch {
+      }
+      dirs.add(path2.join(home, ".local", "share", "pnpm"));
+      dirs.add(path2.join(home, ".local", "bin"));
+      dirs.add(path2.join(home, ".bun", "bin"));
+      const nvmRoot = path2.join(home, ".nvm", "versions", "node");
+      if (exists(nvmRoot)) {
+        for (const v of readDirSafe(nvmRoot)) {
+          dirs.add(path2.join(nvmRoot, v, "bin"));
+        }
+      }
+      return [...dirs].filter(exists);
+    }
+    var RCODE_BINS = ["rcode", "rihal", "rihal-code"];
+    function findRihalBins(binDir) {
+      const found = [];
+      for (const name of RCODE_BINS) {
+        const p = path2.join(binDir, name);
+        if (exists(p)) {
+          let target = null;
+          try {
+            target = fs2.readlinkSync(p);
+          } catch {
+          }
+          if (!target || /rcode|rihal-code|@hanzlaa|@hanzlahabib/.test(target)) {
+            found.push({ name, path: p, target });
+          }
+        }
+      }
+      return found;
+    }
+    function findClaudeArtifacts(claudeDir) {
+      const found = [];
+      if (!exists(claudeDir)) return found;
+      const cmdRoot = path2.join(claudeDir, "commands");
+      if (exists(cmdRoot)) {
+        for (const f of readDirSafe(cmdRoot)) {
+          if (f.startsWith("rihal-") && (f.endsWith(".md") || f.endsWith(".mdc"))) {
+            found.push({ kind: "command", path: path2.join(cmdRoot, f) });
+          }
+        }
+        const rihalSubdir = path2.join(cmdRoot, "rihal");
+        if (exists(rihalSubdir)) {
+          found.push({ kind: "commands-dir", path: rihalSubdir });
+        }
+      }
+      const agentsDir = path2.join(claudeDir, "agents");
+      if (exists(agentsDir)) {
+        for (const f of readDirSafe(agentsDir)) {
+          if (f.startsWith("rihal-") && (f.endsWith(".md") || f.endsWith(".mdc"))) {
+            found.push({ kind: "agent", path: path2.join(agentsDir, f) });
+          }
+        }
+      }
+      const skillsDir = path2.join(claudeDir, "skills");
+      if (exists(skillsDir)) {
+        for (const d of readDirSafe(skillsDir)) {
+          if (d.startsWith("rihal-")) {
+            found.push({ kind: "skill-dir", path: path2.join(skillsDir, d) });
+          }
+        }
+      }
+      return found;
+    }
+    function buildPlan({ includePlanning }) {
+      const home = os.homedir();
+      const cwd = process.cwd();
+      const plan = {
+        packages: [],
+        bins: [],
+        globalClaude: [],
+        globalRihal: null,
+        projectClaude: [],
+        projectRihal: null,
+        projectPlanning: null
+      };
+      for (const { manager, dir } of getGlobalNodeModulesDirs()) {
+        for (const pkg of findRihalPackages(dir)) {
+          plan.packages.push({ manager, ...pkg });
+        }
+      }
+      for (const binDir of getGlobalBinDirs()) {
+        for (const bin of findRihalBins(binDir)) {
+          plan.bins.push({ binDir, ...bin });
+        }
+      }
+      plan.globalClaude = findClaudeArtifacts(path2.join(home, ".claude"));
+      const globalRihal = path2.join(home, ".rihal");
+      if (exists(globalRihal)) plan.globalRihal = globalRihal;
+      plan.projectClaude = findClaudeArtifacts(path2.join(cwd, ".claude"));
+      const projectRihal = path2.join(cwd, ".rihal");
+      if (exists(projectRihal) && cwd !== home) plan.projectRihal = projectRihal;
+      if (includePlanning) {
+        const projectPlanning = path2.join(cwd, ".planning");
+        if (exists(projectPlanning) && cwd !== home) plan.projectPlanning = projectPlanning;
+      }
+      return plan;
+    }
+    function printPlan(plan, { dryRun }) {
+      const banner = dryRun ? "[DRY RUN \u2014 pass --yes to remove]" : "[REMOVING]";
+      console.log(`
+\u{1F525} rcode nuke ${banner}
+`);
+      let total = 0;
+      const section = (title, items) => {
+        if (!items || Array.isArray(items) && items.length === 0) return;
+        console.log(`${title}`);
+        if (Array.isArray(items)) {
+          for (const item of items) {
+            console.log(`  \u2022 ${item.description || item.path || item.dir || JSON.stringify(item)}`);
+            total++;
+          }
+        } else {
+          console.log(`  \u2022 ${items}`);
+          total++;
+        }
+        console.log("");
+      };
+      section("\u{1F4E6} Global packages (node_modules):", plan.packages.map((p) => ({
+        description: `[${p.manager}] ${p.scope}/${p.pkg}  \u2192  ${p.dir}`
+      })));
+      section("\u{1F517} Global binaries:", plan.bins.map((b) => ({
+        description: `${b.path}${b.target ? `  \u2192  ${b.target}` : ""}`
+      })));
+      section("\u{1F916} ~/.claude/ artifacts:", plan.globalClaude.map((a) => ({
+        description: `[${a.kind}] ${a.path}`
+      })));
+      if (plan.globalRihal) section("\u{1F5C2}\uFE0F  ~/.rihal/ (global state):", plan.globalRihal);
+      section("\u{1F916} ./.claude/ artifacts (current project):", plan.projectClaude.map((a) => ({
+        description: `[${a.kind}] ${a.path}`
+      })));
+      if (plan.projectRihal) section("\u{1F5C2}\uFE0F  ./.rihal/ (project state):", plan.projectRihal);
+      if (plan.projectPlanning) section("\u{1F4CB} ./.planning/ (your work \u2014 only with --include-planning):", plan.projectPlanning);
+      if (total === 0) {
+        console.log("  \u2713 nothing to remove \u2014 system is clean.\n");
+      } else {
+        console.log(`  Total: ${total} item(s).
+`);
+      }
+      return total;
+    }
+    function rmrf(p) {
+      try {
+        fs2.rmSync(p, { recursive: true, force: true });
+        return true;
+      } catch (err) {
+        console.warn(`  \u26A0 failed to remove ${p}: ${err.message}`);
+        return false;
+      }
+    }
+    function uninstallPackage(manager, scope, pkg) {
+      const fullName = `${scope}/${pkg}`;
+      const cmd = manager === "pnpm" ? ["pnpm", ["remove", "-g", fullName]] : manager === "yarn" ? ["yarn", ["global", "remove", fullName]] : manager === "bun" ? ["bun", ["remove", "-g", fullName]] : ["npm", ["uninstall", "-g", fullName]];
+      try {
+        const r = spawnSync(cmd[0], cmd[1], { stdio: "pipe", encoding: "utf8" });
+        return r.status === 0;
+      } catch {
+        return false;
+      }
+    }
+    function executePlan(plan) {
+      let removed = 0;
+      for (const p of plan.packages) {
+        const manager = p.manager.startsWith("nvm/") ? "npm" : p.manager;
+        process.stdout.write(`  ${manager} uninstall ${p.scope}/${p.pkg} ... `);
+        const ok = uninstallPackage(manager, p.scope, p.pkg);
+        console.log(ok ? "\u2713" : "\u26A0 failed via PM, falling back to rm");
+        if (!ok) rmrf(p.dir);
+        removed++;
+      }
+      for (const b of plan.bins) {
+        if (exists(b.path)) {
+          if (rmrf(b.path)) {
+            console.log(`  \u2713 removed bin ${b.path}`);
+            removed++;
+          }
+        }
+      }
+      for (const a of plan.globalClaude) {
+        if (rmrf(a.path)) {
+          console.log(`  \u2713 removed ${a.path}`);
+          removed++;
+        }
+      }
+      if (plan.globalRihal && rmrf(plan.globalRihal)) {
+        console.log(`  \u2713 removed ${plan.globalRihal}`);
+        removed++;
+      }
+      for (const a of plan.projectClaude) {
+        if (rmrf(a.path)) {
+          console.log(`  \u2713 removed ${a.path}`);
+          removed++;
+        }
+      }
+      if (plan.projectRihal && rmrf(plan.projectRihal)) {
+        console.log(`  \u2713 removed ${plan.projectRihal}`);
+        removed++;
+      }
+      if (plan.projectPlanning && rmrf(plan.projectPlanning)) {
+        console.log(`  \u2713 removed ${plan.projectPlanning}`);
+        removed++;
+      }
+      return removed;
+    }
+    module2.exports = function nuke(args = []) {
+      const dryRun = !args.includes("--yes") && !args.includes("-y");
+      const includePlanning = args.includes("--include-planning");
+      const cwdPkgJson = path2.join(process.cwd(), "package.json");
+      if (exists(cwdPkgJson)) {
+        try {
+          const pkg = JSON.parse(fs2.readFileSync(cwdPkgJson, "utf8"));
+          if (pkg.name === "@hanzlaa/rcode" || pkg.name === "@hanzlahabib/rihal-code") {
+            console.log("\n\u26A0  You are inside the rcode source repo.");
+            console.log("   Nuke would remove this repo's .claude/, .rihal/, and possibly .planning/.");
+            console.log("   That is your source code \u2014 almost certainly not what you want.");
+            console.log("   Run nuke from a different directory, or pass --i-know-what-im-doing to override.\n");
+            if (!args.includes("--i-know-what-im-doing")) return;
+          }
+        } catch {
+        }
+      }
+      const plan = buildPlan({ includePlanning });
+      const total = printPlan(plan, { dryRun });
+      if (total === 0 || dryRun) {
+        if (dryRun && total > 0) {
+          console.log("To actually remove these, re-run with:  rcode nuke --yes");
+          console.log("To also remove .planning/ (your work):  rcode nuke --yes --include-planning\n");
+        }
+        return;
+      }
+      console.log("Executing...\n");
+      const removed = executePlan(plan);
+      console.log(`
+\u2705 Done. Removed ${removed} item(s). Reinstall:  npm install -g @hanzlaa/rcode
+`);
+    };
+  }
+});
+
 // cli/dashboard.js
 var require_dashboard = __commonJS({
   "cli/dashboard.js"(exports2, module2) {
@@ -18530,6 +18867,65 @@ var require_doctor = __commonJS({
       }
       return failing;
     }
+    function checkDuplicateInstalls() {
+      const os = require("os");
+      const home = os.homedir();
+      const installs = [];
+      const dirs = [];
+      for (const cmd of [["npm", ["root", "-g"]], ["pnpm", ["root", "-g"]]]) {
+        try {
+          const r = spawnSync(cmd[0], cmd[1], { encoding: "utf8" });
+          if (r.status === 0 && r.stdout.trim()) dirs.push({ manager: cmd[0], dir: r.stdout.trim() });
+        } catch {
+        }
+      }
+      const nvmRoot = path2.join(home, ".nvm", "versions", "node");
+      if (fs2.existsSync(nvmRoot)) {
+        for (const v of fs2.readdirSync(nvmRoot)) {
+          const dir = path2.join(nvmRoot, v, "lib", "node_modules");
+          if (fs2.existsSync(dir) && !dirs.some((d) => d.dir === dir)) {
+            dirs.push({ manager: `nvm/${v}`, dir });
+          }
+        }
+      }
+      for (const { manager, dir } of dirs) {
+        for (const scope of ["@hanzlaa", "@hanzlahabib"]) {
+          const scopeDir = path2.join(dir, scope);
+          if (!fs2.existsSync(scopeDir)) continue;
+          for (const pkg of fs2.readdirSync(scopeDir)) {
+            if (pkg === "rcode" || pkg === "rihal-code" || pkg.startsWith("rihal")) {
+              let version = "unknown";
+              try {
+                const pkgJson = JSON.parse(fs2.readFileSync(path2.join(scopeDir, pkg, "package.json"), "utf8"));
+                version = pkgJson.version;
+              } catch {
+              }
+              installs.push({ manager, scope, pkg, version, dir: path2.join(scopeDir, pkg) });
+            }
+          }
+        }
+      }
+      return { count: installs.length, installs };
+    }
+    function printDuplicateChecks(result) {
+      if (result.count === 0) {
+        console.log(`   \u2713 No global rcode installs found`);
+        return 0;
+      }
+      if (result.count === 1) {
+        const i = result.installs[0];
+        console.log(`   \u2713 Single global install: [${i.manager}] ${i.scope}/${i.pkg}@${i.version}`);
+        return 0;
+      }
+      console.log(`   \u2717 ${result.count} global installs detected \u2014 this causes duplicate slash commands!`);
+      for (const i of result.installs) {
+        console.log(`     [${i.manager}] ${i.scope}/${i.pkg}@${i.version}`);
+        console.log(`       ${i.dir}`);
+      }
+      console.log(`
+     Fix: rcode nuke --yes && npm install -g @hanzlaa/rcode`);
+      return 1;
+    }
     module2.exports = function doctor(args, { packageRoot }) {
       const cwd = process.cwd();
       console.log(`
@@ -18539,9 +18935,13 @@ var require_doctor = __commonJS({
       const checks = runPreflight(cwd, packageRoot);
       const preflightFailures = printChecks(checks);
       console.log(`
+Duplicate installations:`);
+      const dupResult = checkDuplicateInstalls();
+      const duplicateFailures = printDuplicateChecks(dupResult);
+      console.log(`
 Package compliance:`);
       const complianceFailures = runCompliance(packageRoot);
-      const totalFailures = preflightFailures + complianceFailures;
+      const totalFailures = preflightFailures + complianceFailures + duplicateFailures;
       console.log();
       if (totalFailures === 0) {
         console.log(`\u2705 All checks passed.`);
@@ -20483,6 +20883,8 @@ var COMMANDS = {
   uninstall: require_uninstall(),
   remove: require_uninstall(),
   // alias
+  nuke: require_nuke(),
+  // full cleanup across all package managers + global state
   dashboard: require_dashboard(),
   serve: require_dashboard(),
   digest: require_digest(),
@@ -20514,6 +20916,10 @@ Usage:
   update         Refresh skill files (backs up .rihal/ state first)
   uninstall      Remove Rihal Code from the current project
   remove         Alias for uninstall
+  nuke           Wipe ALL rihal/rcode installs everywhere (global packages,
+                 binaries, ~/.claude/* rihal artifacts, ~/.rihal/, project artifacts)
+                 Default = dry-run. Pass --yes to remove. Pass --include-planning
+                 to also remove .planning/ in CWD.
   config         Get/set project configuration (project_name, user_name, etc.)
   context        Memory bank freshness (--check | --refresh | --install-hook)
   github-sync    Sync .rihal/ phases/epics/stories to GitHub (dry-run default)
@@ -20542,8 +20948,46 @@ Getting started:
 Documentation: https://github.com/hanzlahabib/rihal-code
   `.trim());
 }
+function maybeShowFirstRunBanner() {
+  const os = require("os");
+  const home = os.homedir();
+  const markerDir = path.join(home, ".rihal");
+  const marker = path.join(markerDir, ".welcome-shown");
+  if (fs.existsSync(marker)) return;
+  const globalCommands = path.join(home, ".claude", "commands");
+  let hasGlobalRihal = false;
+  try {
+    hasGlobalRihal = fs.existsSync(globalCommands) && fs.readdirSync(globalCommands).some((f) => f.startsWith("rihal-") && f.endsWith(".md"));
+  } catch {
+  }
+  if (!hasGlobalRihal) return;
+  console.log(`
+\u{1F54C} Rihal Code v${PACKAGE_JSON.version} \u2014 first run detected.
+`);
+  console.log(`   \u2713 ${countGlobalRihal(globalCommands)} slash commands installed \u2192 ~/.claude/commands/`);
+  console.log(`   \u2713 All /rihal-* commands available in every Claude Code project.`);
+  console.log(`
+   To set up a project:  cd my-project && rcode install`);
+  console.log(`   Show all commands:    rcode help`);
+  console.log(`   Diagnose issues:      rcode doctor
+`);
+  try {
+    fs.mkdirSync(markerDir, { recursive: true });
+    fs.writeFileSync(marker, `installed ${PACKAGE_JSON.version} at ${(/* @__PURE__ */ new Date()).toISOString()}
+`);
+  } catch {
+  }
+}
+function countGlobalRihal(dir) {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.startsWith("rihal-") && f.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}
 async function main() {
   const [, , command = "help", ...args] = process.argv;
+  maybeShowFirstRunBanner();
   const handler = COMMANDS[command];
   if (!handler) {
     console.error(`Unknown command: ${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.4.16",
+  "version": "3.4.18",
   "description": "rcode — the memory bank for AI-driven SaaS teams. Persistent project context, distinctive engineering personas, and phase-based workflows. Built by Rihal. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rihal/bin/rihal-tools.cjs

@@ -2390,6 +2390,11 @@ function cmdState(subArgs) {
     //   Format B — heading style:   ## Phase 01 — Name  /  ### Phase 01: Name
     // Milestone heading is also matched in any of: "## Milestone M1", "## Milestone v1.0 — Name",
     // "**Milestone: v1.0 — Name**".
+
+    // Issue #651 — must be declared in outer scope. The prune step at end of
+    // sync references seenNums even when roadmap_exists is false (no-op prune
+    // path), causing 'seenNums is not defined' crash.
+    const seenNums = new Set();
     if (parsed.roadmap_exists) {
       const roadmap = fs.readFileSync(roadmapPath, 'utf8');
       const milestoneMatches = [
@@ -2425,8 +2430,6 @@ function cmdState(subArgs) {
       parsed.phases_normalized = beforeClean - cleaned.length;
       state.phases = cleaned;
 
-      const seenNums = new Set();
-
       const upsertPhase = (phaseNum, phaseName, phaseGoal) => {
         if (!/^\d/.test(phaseNum)) return;
         if (phaseName.toLowerCase() === 'phase') return;

package/rihal/workflows/execute.md

@@ -573,7 +573,8 @@ If `CODE_REVIEW_ENABLED` is `"false"`: display "Code review skipped (workflow.co
 REVIEWER_MODEL=$(node ".rihal/bin/rihal-tools.cjs" resolve-model code-reviewer 2>/dev/null | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{console.log(JSON.parse(d).model)}catch{console.log('')}})" || echo "sonnet")
 REVIEWER_MODEL=${REVIEWER_MODEL:-sonnet}
 REVIEWER_SKILLS=$(node ".rihal/bin/rihal-tools.cjs" agent-skills rihal-code-reviewer 2>/dev/null || echo "")
-PADDED=$(printf "%02d" "${PHASE_NUMBER}")
+# Issue #652 — no leading zeros. Variable name kept for backward compat in this workflow.
+PADDED="${PHASE_NUMBER}"
 REVIEW_FILE="${PHASE_DIR}/${PADDED}-REVIEW.md"
 ```
 

package/rihal/workflows/plan.md

@@ -209,8 +209,9 @@ Exit workflow.
 
 ```bash
 EXISTING_PLAN_COUNT=$(ls "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null | wc -l | tr -d ' ')
-NEXT_PLAN_NUMBER=$(printf "%02d" $((EXISTING_PLAN_COUNT + 1)))
-PADDED_PHASE=$(printf "%02d" "${PHASE}")
+# Issue #652 — no leading zeros in planning artifacts. Phase 8 not 08, plan 2 not 02.
+NEXT_PLAN_NUMBER=$((EXISTING_PLAN_COUNT + 1))
+PADDED_PHASE="${PHASE}"
 GAP_PLAN_FILENAME="${PADDED_PHASE}-${NEXT_PLAN_NUMBER}-SPRINT.md"
 GAP_PLAN_PATH="${PHASE_DIR}/${GAP_PLAN_FILENAME}"
 ```