@hanzlaa/rcode 3.4.20 → 3.4.22

package/cli/generate-command-skills.cjs

@@ -149,7 +149,7 @@ Identical to \`/rihal-${cmdName}\`. See the workflow file for the canonical outp
 `;
 }
 
-function main(packageRoot, targetSkillsDir, version) {
+function main(packageRoot, targetSkillsDir, version, options = {}) {
   if (!fs.existsSync(targetSkillsDir)) {
     fs.mkdirSync(targetSkillsDir, { recursive: true });
   }
@@ -158,11 +158,20 @@ function main(packageRoot, targetSkillsDir, version) {
   const commandsDir = path.join(packageRoot, 'rihal', 'commands');
   if (!fs.existsSync(commandsDir)) {
     console.warn(`[generate-command-skills] commands dir not found: ${commandsDir}`);
-    return { generated: 0, skipped: 0 };
+    return { generated: 0, skipped: 0, skippedGlobal: 0 };
   }
 
+  // Issue #679: skip stubs whose name already exists in ~/.claude/skills/.
+  // Otherwise the slash picker shows the same /rihal-* twice.
+  const os = require('os');
+  const globalSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+  const globalSkills = (options.skipGlobalDuplicates && fs.existsSync(globalSkillsDir))
+    ? new Set(fs.readdirSync(globalSkillsDir).filter(n => n.startsWith('rihal-')))
+    : new Set();
+
   let generated = 0;
   let skipped = 0;
+  let skippedGlobal = 0;
 
   for (const file of fs.readdirSync(commandsDir)) {
     if (!file.endsWith('.md')) continue;
@@ -177,6 +186,28 @@ function main(packageRoot, targetSkillsDir, version) {
       continue;
     }
 
+    if (globalSkills.has(skillName)) {
+      // Global skill of same name exists — installing a sidebar stub here would
+      // duplicate the entry in Claude Code's slash picker. Also clean up any
+      // previously-generated stub with the same name.
+      const existingStub = path.join(targetSkillsDir, skillName);
+      if (fs.existsSync(existingStub)) {
+        try {
+          const existingFile = path.join(existingStub, 'SKILL.md');
+          if (fs.existsSync(existingFile)) {
+            const text = fs.readFileSync(existingFile, 'utf8');
+            // Only delete previously-generated stubs (marker present) — never
+            // user customizations.
+            if (/^generated:\s*true/m.test(text)) {
+              fs.rmSync(existingStub, { recursive: true, force: true });
+            }
+          }
+        } catch { /* non-fatal */ }
+      }
+      skippedGlobal++;
+      continue;
+    }
+
     const cmdPath = path.join(commandsDir, file);
     const cmdText = fs.readFileSync(cmdPath, 'utf8');
     const cmdFm = parseFrontmatter(cmdText);

package/cli/index.js

@@ -3,14 +3,14 @@
  * Rihal Code CLI
  *
  * Usage:
- *   npx @hanzlahabib/rihal-code init          → scaffold .rihal/ in current project
- *   npx @hanzlahabib/rihal-code dashboard     → start the Diwan view-only dashboard
- *   npx @hanzlahabib/rihal-code serve         → alias for dashboard
- *   npx @hanzlahabib/rihal-code digest        → print compact agent digests
- *   npx @hanzlahabib/rihal-code team          → list the team roster
- *   npx @hanzlahabib/rihal-code doctor        → compliance check
- *   npx @hanzlahabib/rihal-code version       → print version
- *   npx @hanzlahabib/rihal-code help          → this message
+ *   npx @hanzlaa/rcode init          → scaffold .rihal/ in current project
+ *   npx @hanzlaa/rcode dashboard     → start the Diwan view-only dashboard
+ *   npx @hanzlaa/rcode serve         → alias for dashboard
+ *   npx @hanzlaa/rcode digest        → print compact agent digests
+ *   npx @hanzlaa/rcode team          → list the team roster
+ *   npx @hanzlaa/rcode doctor        → compliance check
+ *   npx @hanzlaa/rcode version       → print version
+ *   npx @hanzlaa/rcode help          → this message
  */
 
 const path = require('path');

package/cli/install.js

@@ -275,7 +275,7 @@ function printInstallHeader(targetVersion) {
     pc.cyan('│') + '   ' + dim('A persistent context-brain for your editor') + '             ' + pc.cyan('│'),
     pc.cyan('│') + '                                                           ' + pc.cyan('│'),
     pc.cyan('│') + '   ' + dim('version  ') + pc.green('v' + v) + '                                          ' + pc.cyan('│'),
-    pc.cyan('│') + '   ' + dim('docs     ') + 'github.com/hanzla-habib/rihal-code              ' + pc.cyan('│'),
+    pc.cyan('│') + '   ' + dim('docs     ') + 'github.com/hanzlahabib/rihal-code               ' + pc.cyan('│'),
     pc.cyan('│') + '                                                           ' + pc.cyan('│'),
     pc.cyan('╰───────────────────────────────────────────────────────────╯'),
     '',
@@ -370,11 +370,32 @@ async function resolveIde(opts) {
 async function resolveCommitPlanning(opts) {
   if (opts.commitPlanning !== null) return opts.commitPlanning;
   if (opts.noPrompt || opts.global) return false; // global install: no planning artifacts
-  if (opts.yes || !process.stdin.isTTY) return true; // non-interactive default
 
+  // Issue #685: on re-install, read the existing .rihal/config.yaml and use
+  // its commit_planning value as the default. Otherwise the new prompt
+  // answer overwrites .gitignore but NOT config.yaml, leaving two sources of
+  // truth that silently diverge. Users on re-install almost always want to
+  // KEEP their existing setting unless they explicitly pass --commit-planning.
+  let existingValue = null;
+  try {
+    const cfgPath = path.join(opts.target, '.rihal', 'config.yaml');
+    if (fs.existsSync(cfgPath)) {
+      const cfg = fs.readFileSync(cfgPath, 'utf8');
+      const m = cfg.match(/^commit_planning:\s*(true|false)\s*$/m);
+      if (m) existingValue = m[1] === 'true';
+    }
+  } catch { /* fall through to prompt */ }
+
+  if (opts.yes || !process.stdin.isTTY) {
+    return existingValue !== null ? existingValue : true; // honor existing on re-install
+  }
+
+  const initialValue = existingValue === false ? 'gitignore' : 'commit';
   const choice = await clack.select({
-    message: '📋 .planning/ holds PRDs, roadmaps, sprints, SUMMARY files. How should they be tracked?',
-    initialValue: 'commit',
+    message: existingValue !== null
+      ? '📋 .planning/ tracking — current setting preserved unless you change it.'
+      : '📋 .planning/ holds PRDs, roadmaps, sprints, SUMMARY files. How should they be tracked?',
+    initialValue,
     options: [
       { value: 'commit',    label: 'Commit',    hint: 'collaborators see the same plans (recommended)' },
       { value: 'gitignore', label: 'Gitignore', hint: 'planning stays local (good for sensitive PRDs)' },
@@ -548,7 +569,15 @@ function seedStarterPlanning(target, projectName) {
   const today = new Date().toISOString().slice(0, 10);
   const name = projectName || path.basename(target);
 
+  // Stub planning files: clearly marked as install templates so users (and
+  // /rihal-new-project Step 0.5 detection) can tell them apart from real
+  // planning artifacts. See issues #670 #671 #676.
+  const STUB_BANNER =
+    `<!-- INSTALL STUB — overwritten by /rihal-new-project. Delete this file or run\n` +
+    `     /rihal-new-project before committing. See https://github.com/hanzlahabib/rihal-code/issues/670 -->\n\n`;
+
   fs.writeFileSync(projectPath,
+    STUB_BANNER +
     `# ${name}\n\n` +
     `**One-line:** Describe what this project is in one sentence.\n\n` +
     `## Vision\n\n` +
@@ -558,6 +587,7 @@ function seedStarterPlanning(target, projectName) {
   );
 
   fs.writeFileSync(roadmapPath,
+    STUB_BANNER +
     `# ${name} — Roadmap\n\n` +
     `**Milestone: M1 — Initial Delivery** (v1.0)\n` +
     `Started: ${today} · Current\n\n` +
@@ -572,6 +602,7 @@ function seedStarterPlanning(target, projectName) {
   );
 
   fs.writeFileSync(statePath,
+    STUB_BANNER +
     `# ${name} — State\n\n` +
     `**Last updated:** ${today}\n` +
     `**Milestone:** M1 — Initial Delivery\n` +
@@ -580,27 +611,33 @@ function seedStarterPlanning(target, projectName) {
     `---\n\n` +
     `## Decisions\n\n_None yet._\n\n` +
     `## Blockers\n\n_None._\n\n` +
-    `## Next Action\n\nSay "plan a sprint" or run \`/rihal-sprint-planning\` to break Phase 01 into stories.\n`
+    `## Next Action\n\nRun \`/rihal-new-project <description>\` to bootstrap, or \`/rihal-sprint-planning\` once a real phase exists.\n`
   );
 
-  // Also pre-seed .rihal/state.json with Phase 01 so sprint tools work
-  // immediately (otherwise auto-init in rihal-tools.cjs creates state with
-  // empty phases[], requiring manual set-phase before sprint add).
+  // Issue #670: do NOT pre-seed .rihal/state.json with a fake project +
+  // "Setup & Scaffolding" phase. That made every fresh install look like a
+  // real initialized project and broke /rihal-new-project Step 0.5 detection.
+  //
+  // Write a minimal shell with _seeded_stub:true so:
+  //   - rihal-tools doesn't have to re-init on first call (avoids race)
+  //   - /rihal-new-project Step 0.5 (issue #671) can detect "stub" reliably
+  //   - sprint tools that previously relied on phase 01 will surface a clear
+  //     "no phases yet — run /rihal-new-project first" error instead of
+  //     silently operating on a fake phase
   const rihalStateJson = path.join(target, '.rihal', 'state.json');
   if (!fs.existsSync(rihalStateJson)) {
     const now = new Date().toISOString();
     const state = {
       version: '1',
-      project: name,
+      project: null,
+      _seeded_stub: true,
       created: now,
       updated: now,
-      current_phase: '01',
+      current_phase: null,
       current_plan: 0,
       current_sprint: null,
-      milestone: 'M1 — Initial Delivery',
-      phases: [
-        { id: '01', name: 'Setup & Scaffolding', status: 'planned' }
-      ],
+      milestone: null,
+      phases: [],
       executions: [],
       decisions: [],
       blockers: [],
@@ -857,16 +894,26 @@ function installBrainScaffold(packageRoot, target) {
  *
  * A skill is marked internal by adding `internal: true` to its SKILL.md frontmatter.
  */
-function installSkills(packageRoot, target) {
+function installSkills(packageRoot, target, options = {}) {
   const skillsSource = path.join(packageRoot, 'rihal/skills');
   const skillsDest = path.join(target, '.claude/skills');
   const internalDest = path.join(target, '.rihal/skills');
 
-  if (!fs.existsSync(skillsSource)) return 0;
+  if (!fs.existsSync(skillsSource)) return { count: 0, skippedGlobal: 0 };
   fs.mkdirSync(skillsDest, { recursive: true });
   fs.mkdirSync(internalDest, { recursive: true });
 
+  // Issue #679: when ~/.claude/skills/<name>/ already exists with the rihal-
+  // prefix, Claude Code reads from BOTH global and project, showing every
+  // /rihal-* twice in the slash picker. Skip the project copy for any rihal-*
+  // skill that already lives in the global skills dir.
+  const globalSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+  const globalRihalSkills = (options.skipGlobalDuplicates && fs.existsSync(globalSkillsDir))
+    ? new Set(fs.readdirSync(globalSkillsDir).filter(n => n.startsWith('rihal-')))
+    : new Set();
+
   let count = 0;
+  let skippedGlobal = 0;
 
   function isInternalSkill(skillDir) {
     const skillMd = path.join(skillDir, 'SKILL.md');
@@ -875,6 +922,13 @@ function installSkills(packageRoot, target) {
     return /^internal:\s*true\s*$/m.test(text);
   }
 
+  function hasLocalOverride(destDir) {
+    if (!fs.existsSync(destDir)) return false;
+    try {
+      return fs.readdirSync(destDir).some(f => f.endsWith('.local.md'));
+    } catch { return false; }
+  }
+
   function walkForSkills(dir) {
     if (!fs.existsSync(dir)) return;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -885,9 +939,23 @@ function installSkills(packageRoot, target) {
         const destName = entry.name.startsWith('rihal-')
           ? entry.name
           : `rihal-${entry.name}`;
-        const dest = isInternalSkill(src)
+        const internal = isInternalSkill(src);
+        const dest = internal
           ? path.join(internalDest, destName)   // internal → .rihal/skills/
           : path.join(skillsDest, destName);     // user-facing → .claude/skills/
+
+        // Skip user-facing (non-internal) rihal-* skills when the same name
+        // exists globally — UNLESS the user has a *.local.md override on the
+        // project copy, in which case we always preserve their customization.
+        if (!internal && globalRihalSkills.has(destName) && !hasLocalOverride(dest)) {
+          // Also remove the existing project copy (left over from previous
+          // installs that didn't dedup) so it stops showing in the picker.
+          if (fs.existsSync(dest)) {
+            try { fs.rmSync(dest, { recursive: true, force: true }); } catch { /* non-fatal */ }
+          }
+          skippedGlobal++;
+          continue;
+        }
         copyDirRecursive(src, dest);
         count++;
       } else {
@@ -900,7 +968,7 @@ function installSkills(packageRoot, target) {
     walkForSkills(path.join(skillsSource, bucket));
   }
 
-  return count;
+  return { count, skippedGlobal };
 }
 
 /**
@@ -1409,6 +1477,18 @@ function convertToCursorMdc(sourceText) {
 async function install(opts) {
   if (opts.help) { printHelp(); return 0; }
 
+  // Issue #680: --reset alone is a footgun — silently does nothing. Fail
+  // fast with a clear message before any work happens.
+  if (opts.reset && !opts.force) {
+    console.log('');
+    console.log('  ' + warn('--reset has no effect without --force.'));
+    console.log('  ' + dim('  --reset wipes config.yaml and state.json. To prevent accidental data loss,'));
+    console.log('  ' + dim('  it must be paired with --force. Re-run as:'));
+    console.log('  ' + dim('    rcode install --reset --force'));
+    console.log('');
+    return 2;
+  }
+
   const pkgVersion = readPackageVersion();
 
   // Header banner — only shown for interactive runs to keep CI/non-TTY logs terse.
@@ -1738,8 +1818,10 @@ async function install(opts) {
     const configDir = path.join(opts.target, '.rihal', '_config');
     ensureDir(configDir);
     fs.writeFileSync(path.join(configDir, 'manifest.yaml'), generateInstallManifest(opts));
-    // Install skills + sidebar stubs globally
-    let skillsInstalled = installSkills(PACKAGE_ROOT, opts.target);
+    // Install skills + sidebar stubs globally — never dedup against globals,
+    // because in --global mode the target IS the global dir.
+    const skillsResult = installSkills(PACKAGE_ROOT, opts.target);
+    let skillsInstalled = skillsResult.count;
     try {
       const { main: generateCommandSkills } = require(path.join(PACKAGE_ROOT, 'cli', 'generate-command-skills.cjs'));
       const stubsDir = path.join(opts.target, '.claude', 'skills');
@@ -1815,6 +1897,7 @@ async function install(opts) {
         plan.length = 0;
         filtered.forEach(e => plan.push(e));
       }
+
     } catch { /* non-fatal — skip detection on permission errors */ }
   }
 
@@ -1839,11 +1922,34 @@ async function install(opts) {
   } else if (opts.force && (fs.existsSync(configPath) || fs.existsSync(stateDest))) {
     existedBefore = true;
   }
+  // Note: --reset without --force is rejected at the top of install() (#680).
 
   // Write .rihal/config.yaml (user_name, project_name, language, mode)
   // Note: config.yaml is user data and should NOT be overwritten on --force (unless --reset)
   if (!fs.existsSync(configPath)) {
     fs.writeFileSync(configPath, generateConfigYaml(opts));
+  } else {
+    // Issue #685: re-install path. config.yaml is preserved BUT if the user
+    // just changed commit_planning via the prompt/flag, .gitignore will be
+    // rewritten with the new value while config.yaml keeps the old one,
+    // creating a silent drift. Update only commit_planning in-place
+    // (preserve everything else the user may have customized).
+    try {
+      const before = fs.readFileSync(configPath, 'utf8');
+      const desired = opts.commitPlanning !== false;
+      const re = /^commit_planning:\s*(true|false)\s*$/m;
+      const match = before.match(re);
+      const currentInFile = match ? match[1] === 'true' : null;
+      if (match && currentInFile !== desired) {
+        const updated = before.replace(re, `commit_planning: ${desired}`);
+        fs.writeFileSync(configPath, updated);
+        console.log('  ' + dim(`Updated commit_planning in config.yaml (${currentInFile} → ${desired}) — closes #685.`));
+      } else if (!match) {
+        // Older config without the key — append it so the next read finds it.
+        const appended = before.replace(/\n*$/, '') + `\ncommit_planning: ${desired}\n`;
+        fs.writeFileSync(configPath, appended);
+      }
+    } catch { /* best-effort — never fail install on this */ }
   }
   // Validate config.yaml with zod schema (#250) — warn but never block install.
   try {
@@ -1901,7 +2007,16 @@ async function install(opts) {
 
   // Install v1-style phrase-activated skills (scaffold-project, create-prd,
   // retrospective, etc.) into .claude/skills/ alongside the v2 agents/commands.
-  let skillsInstalled = installSkills(PACKAGE_ROOT, opts.target);
+  // Issue #679: skip rihal-* skills that already exist in ~/.claude/skills/
+  // (global precedence) so the slash picker doesn't show every command twice.
+  // Reuse the isProjectInstall flag declared earlier in this scope.
+  const skillsResult = installSkills(PACKAGE_ROOT, opts.target, {
+    skipGlobalDuplicates: isProjectInstall,
+  });
+  let skillsInstalled = skillsResult.count;
+  if (skillsResult.skippedGlobal > 0) {
+    console.log('  ' + dim(`Skipped ${skillsResult.skippedGlobal} project-level rihal skills (global ones in ~/.claude/skills/ take precedence) — closes #679.`));
+  }
 
   // Generate install-time skill stubs that mirror sidebar-worthy slash commands.
   // Source codebase stays clean — these stubs only exist at the install
@@ -1910,11 +2025,16 @@ async function install(opts) {
   try {
     const { main: generateCommandSkills } = require(path.join(PACKAGE_ROOT, 'cli', 'generate-command-skills.cjs'));
     const stubsDir = path.join(opts.target, '.claude', 'skills');
-    const result = generateCommandSkills(PACKAGE_ROOT, stubsDir, readPackageVersion());
+    const result = generateCommandSkills(PACKAGE_ROOT, stubsDir, readPackageVersion(), {
+      skipGlobalDuplicates: isProjectInstall,
+    });
     if (result.generated > 0) {
       console.log('  ' + dim(`${result.generated} sidebar skill stub${result.generated === 1 ? '' : 's'} generated for command discoverability`));
       skillsInstalled += result.generated;
     }
+    if (result.skippedGlobal > 0) {
+      console.log('  ' + dim(`Skipped ${result.skippedGlobal} sidebar stub${result.skippedGlobal === 1 ? '' : 's'} that duplicate global ~/.claude/skills/ — closes #679.`));
+    }
   } catch (err) {
     // Non-fatal: install succeeds without sidebar stubs
     console.log('  ' + dim(`(sidebar stub generation skipped: ${err.message})`));
@@ -2023,6 +2143,7 @@ async function install(opts) {
   const agentsDir = idePaths.agentsDir;
   const commandsDir = idePaths.commandsDir;
   let agentCount = 0, commandCount = 0;
+  let agentsFromGlobal = false, commandsFromGlobal = false;
   try {
     if (fs.existsSync(agentsDir)) {
       agentCount = fs.readdirSync(agentsDir).filter(f => (f.startsWith('rihal-') || f.startsWith('rcode-')) && (f.endsWith('.md') || f.endsWith('.mdc'))).length;
@@ -2034,6 +2155,22 @@ async function install(opts) {
         : f => f.endsWith('.md') || f.endsWith('.mdc');
       commandCount = fs.readdirSync(commandsDir).filter(commandFilter).length;
     }
+    // Issue #669 — when global precedence applied (project copies were
+    // intentionally removed), count from ~/.claude/ instead so the summary
+    // doesn't lie about the install state.
+    if (agentCount === 0 || commandCount === 0) {
+      const os = require('os');
+      const homeAgents = path.join(os.homedir(), '.claude/agents');
+      const homeCommands = path.join(os.homedir(), '.claude/commands');
+      if (agentCount === 0 && fs.existsSync(homeAgents)) {
+        const n = fs.readdirSync(homeAgents).filter(f => f.startsWith('rihal-') && f.endsWith('.md')).length;
+        if (n > 0) { agentCount = n; agentsFromGlobal = true; }
+      }
+      if (commandCount === 0 && fs.existsSync(homeCommands)) {
+        const n = fs.readdirSync(homeCommands).filter(f => f.startsWith('rihal-') && f.endsWith('.md')).length;
+        if (n > 0) { commandCount = n; commandsFromGlobal = true; }
+      }
+    }
   } catch {}
 
   const version = readPackageVersion();
@@ -2047,8 +2184,8 @@ async function install(opts) {
   // Show the actual install paths so cursor/gemini/antigravity output is accurate
   const relAgents = path.relative(opts.target, idePaths.agentsDir) || idePaths.agentsDir;
   const relCommands = path.relative(opts.target, idePaths.commandsDir) || idePaths.commandsDir;
-  console.log(`  ${bold('Agents:')}    ${pc.green(String(agentCount))} in ${relAgents}/`);
-  console.log(`  ${bold('Commands:')}  ${pc.green(String(commandCount))} slash commands in ${relCommands}/`);
+  console.log(`  ${bold('Agents:')}    ${pc.green(String(agentCount))} in ${agentsFromGlobal ? '~/.claude/agents/ (global)' : relAgents + '/'}`);
+  console.log(`  ${bold('Commands:')}  ${pc.green(String(commandCount))} slash commands in ${commandsFromGlobal ? '~/.claude/commands/ (global)' : relCommands + '/'}`);
   if (skillsInstalled > 0) console.log(`  ${bold('Skills:')}    ${pc.green(String(skillsInstalled))} phrase-activated`);
   console.log('');
   if (starterSeeded) {

package/cli/lib/manifest.cjs

@@ -124,6 +124,25 @@ function verifyClaudeInstall(cwd, packageRoot) {
     }
   }
 
+  // Issue #664 — global precedence fallback.
+  // The installer (cli/install.js ~line 1773) intentionally removes project-
+  // level .claude/agents/rihal-*.md when the user's ~/.claude/ already has
+  // them, to avoid duplicate commands. Without this fallback the verifier
+  // reports 0 agents on every successful install in that scenario.
+  if (installedAgents.size === 0) {
+    try {
+      const os = require('os');
+      const globalAgentsDir = path.join(os.homedir(), '.claude/agents');
+      if (fs.existsSync(globalAgentsDir)) {
+        for (const f of fs.readdirSync(globalAgentsDir)) {
+          if (f.startsWith('rihal-') && f.endsWith('.md')) {
+            installedAgents.add(f.replace(/^rihal-/, '').replace(/\.md$/, ''));
+          }
+        }
+      }
+    } catch { /* non-fatal — permission errors etc. */ }
+  }
+
   // Actions: .claude/skills/<bare-name>/ — exclude rihal-* dirs (those are
   // either agent stubs or command stubs, never action skills).
   const allInstalled = readInstalledDirs(skillsDir);

package/cli/set-profile.js

@@ -2,11 +2,11 @@
  * rihal-code set-profile — change the model profile for the current project
  *
  * Usage:
- *   npx @hanzlahabib/rihal-code set-profile balanced
- *   npx @hanzlahabib/rihal-code set-profile quality
- *   npx @hanzlahabib/rihal-code set-profile budget
- *   npx @hanzlahabib/rihal-code set-profile inherit
- *   npx @hanzlahabib/rihal-code set-profile                  # show current
+ *   npx @hanzlaa/rcode set-profile balanced
+ *   npx @hanzlaa/rcode set-profile quality
+ *   npx @hanzlaa/rcode set-profile budget
+ *   npx @hanzlaa/rcode set-profile inherit
+ *   npx @hanzlaa/rcode set-profile                  # show current
  *
  * This is a thin wrapper over `rihal-code config model_profile <name>`.
  * All config read/write goes through cli/lib/config.cjs, which handles

package/cli/show-model.js

@@ -2,9 +2,9 @@
  * rihal-code show-model — print the resolved model for an agent (or all agents)
  *
  * Usage:
- *   npx @hanzlahabib/rihal-code show-model              # all agents in current profile
- *   npx @hanzlahabib/rihal-code show-model waleed       # single agent
- *   npx @hanzlahabib/rihal-code show-model --profile=quality   # different profile
+ *   npx @hanzlaa/rcode show-model              # all agents in current profile
+ *   npx @hanzlaa/rcode show-model waleed       # single agent
+ *   npx @hanzlaa/rcode show-model --profile=quality   # different profile
  */
 
 const {

package/cli/uninstall.js

@@ -250,8 +250,15 @@ function isKnownSkillName(name) {
 /**
  * Build the list of files/dirs (relative to cwd) that the uninstall plan
  * will delete or mutate. Used to feed `tar --files-from=-`.
+ *
+ * @param {object} plan — uninstall plan
+ * @param {string} cwd — project root
+ * @param {object} [options]
+ * @param {boolean} [options.purge=false] — when true, also include .rihal/
+ *   and .planning/ in the backup so --purge users can recover state.json,
+ *   decisions, and planning artifacts. Issue #683.
  */
-function planToPathList(plan, cwd) {
+function planToPathList(plan, cwd, options = {}) {
   const paths = [];
 
   for (const name of plan.claude.skills) {
@@ -278,6 +285,26 @@ function planToPathList(plan, cwd) {
     paths.push('AGENTS.md');
   }
 
+  // Issue #683: --purge wipes .rihal/ AND .planning/ but the backup never
+  // included them. User loses state.json, decisions, planning artifacts with
+  // no recovery. Add them when purging — but EXCLUDE .rihal/backups/ itself
+  // (we'd be writing into the dir we're tar-ing).
+  if (options.purge) {
+    const rihalDir = path.join(cwd, '.rihal');
+    if (fs.existsSync(rihalDir)) {
+      // Walk one level deep and add everything except backups/
+      try {
+        for (const entry of fs.readdirSync(rihalDir)) {
+          if (entry === 'backups') continue;
+          paths.push(path.join('.rihal', entry));
+        }
+      } catch { /* fall through; ok=false from tar will warn */ }
+    }
+    if (fs.existsSync(path.join(cwd, '.planning'))) {
+      paths.push('.planning');
+    }
+  }
+
   return paths;
 }
 
@@ -288,8 +315,8 @@ function planToPathList(plan, cwd) {
  * (tar missing, no paths, etc.); the caller should warn the user but may
  * still proceed since the user already confirmed the destructive action.
  */
-function createBackup(cwd, plan) {
-  const paths = planToPathList(plan, cwd);
+function createBackup(cwd, plan, options = {}) {
+  const paths = planToPathList(plan, cwd, { purge: options.purge === true });
   if (paths.length === 0) {
     return { ok: false, warning: 'nothing to back up' };
   }
@@ -301,11 +328,17 @@ function createBackup(cwd, plan) {
     return { ok: false, warning: 'tar not available on this system' };
   }
 
-  const backupsDir = path.join(cwd, '.rihal/backups');
+  // Issue #683: when --purge wipes .rihal/, a backup written into
+  // .rihal/backups/ would be deleted moments later. Write to a sibling
+  // .rihal-backups/ at the project root instead so the backup survives.
+  // For non-purge runs, keep the historical .rihal/backups/ location.
+  const backupsDir = options.purge
+    ? path.join(cwd, '.rihal-backups')
+    : path.join(cwd, '.rihal/backups');
   try {
     fs.mkdirSync(backupsDir, { recursive: true });
   } catch (err) {
-    return { ok: false, warning: `could not create .rihal/backups/: ${err.message}` };
+    return { ok: false, warning: `could not create ${path.relative(cwd, backupsDir)}/: ${err.message}` };
   }
 
   const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
@@ -489,10 +522,15 @@ async function runUninstall(args) {
 
   // Create a timestamped backup before doing anything destructive.
   // Non-fatal on failure — the user already confirmed, we just warn.
+  // Issue #683: --purge backs up .rihal/ and .planning/ too so users can
+  // recover state.json, decisions log, and planning artifacts.
   console.log();
-  const backup = createBackup(cwd, plan);
+  const backup = createBackup(cwd, plan, { purge: opts.purge === true });
   if (backup.ok) {
     console.log(`   💾 backup created: ${backup.path}`);
+    if (opts.purge) {
+      console.log('      includes .rihal/ and .planning/ (state, decisions, planning artifacts)');
+    }
   } else {
     console.log(`   ⚠ no backup created (${backup.warning}) — continuing anyway`);
   }
@@ -649,15 +687,29 @@ async function runUninstall(args) {
 
     // Strip the rcode-managed block from .gitignore. The installer writes
     // a fenced block; we remove it cleanly without touching user lines.
+    //
+    // Issue #684: previous regex `/\n?# rcode[\s\S]*?(?=\n\n|\n$|$)/g` was a
+    // footgun — it matched ANY user line starting with "# rcode" (e.g.
+    // "# rcode notes", "# rcode is great") and greedily consumed everything
+    // up to the next blank line, silently nuking user content.
+    //
+    // Three shapes have ever shipped:
+    //   1. Current (install.js:653-654): "# ===== rcode-managed gitignore block ... =====" ... "# ===== end rcode-managed gitignore block ====="
+    //   2. Old fenced markers: "# >>> rihal-code >>>" ... "# <<< rihal-code <<<"
+    //   3. Hypothetical legacy single-line "# rcode" — never actually
+    //      committed by any installer version we can find. Removed.
+    //
+    // Both kept patterns require BOTH sentinel markers to be present —
+    // user content with "# rcode" prefix is now safe.
     const gitignorePath = path.join(cwd, '.gitignore');
     if (fs.existsSync(gitignorePath)) {
       try {
         const before = fs.readFileSync(gitignorePath, 'utf8');
-        // Match either fenced markers or the legacy "# rcode" header through to
-        // the next blank line — both shapes the installer has used historically.
         const stripped = before
+          // Current shape (install.js BEGIN/END markers — exact match).
+          .replace(/\n?# ===== rcode-managed gitignore block[\s\S]*?# ===== end rcode-managed gitignore block =====\n?/g, '\n')
+          // Legacy >>> / <<< fenced shape.
           .replace(/\n?# >>> rihal-code >>>[\s\S]*?# <<< rihal-code <<<\n?/g, '\n')
-          .replace(/\n?# rcode[\s\S]*?(?=\n\n|\n$|$)/g, '\n')
           .replace(/\n{3,}/g, '\n\n');
         if (stripped !== before) {
           fs.writeFileSync(gitignorePath, stripped);

package/dist/rcode.js

@@ -15129,7 +15129,7 @@ var require_install = __commonJS({
         pc.cyan("\u2502") + "   " + dim("A persistent context-brain for your editor") + "             " + pc.cyan("\u2502"),
         pc.cyan("\u2502") + "                                                           " + pc.cyan("\u2502"),
         pc.cyan("\u2502") + "   " + dim("version  ") + pc.green("v" + v) + "                                          " + pc.cyan("\u2502"),
-        pc.cyan("\u2502") + "   " + dim("docs     ") + "github.com/hanzla-habib/rihal-code              " + pc.cyan("\u2502"),
+        pc.cyan("\u2502") + "   " + dim("docs     ") + "github.com/hanzlahabib/rihal-code               " + pc.cyan("\u2502"),
         pc.cyan("\u2502") + "                                                           " + pc.cyan("\u2502"),
         pc.cyan("\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"),
         ""
@@ -16485,6 +16485,7 @@ ${BLOCK}`);
       const agentsDir = idePaths.agentsDir;
       const commandsDir = idePaths.commandsDir;
       let agentCount = 0, commandCount = 0;
+      let agentsFromGlobal = false, commandsFromGlobal = false;
       try {
         if (fs2.existsSync(agentsDir)) {
           agentCount = fs2.readdirSync(agentsDir).filter((f) => (f.startsWith("rihal-") || f.startsWith("rcode-")) && (f.endsWith(".md") || f.endsWith(".mdc"))).length;
@@ -16493,6 +16494,25 @@ ${BLOCK}`);
           const commandFilter = primaryIde === "claude" ? (f) => f.startsWith("rihal-") && (f.endsWith(".md") || f.endsWith(".mdc")) : (f) => f.endsWith(".md") || f.endsWith(".mdc");
           commandCount = fs2.readdirSync(commandsDir).filter(commandFilter).length;
         }
+        if (agentCount === 0 || commandCount === 0) {
+          const os2 = require("os");
+          const homeAgents = path2.join(os2.homedir(), ".claude/agents");
+          const homeCommands = path2.join(os2.homedir(), ".claude/commands");
+          if (agentCount === 0 && fs2.existsSync(homeAgents)) {
+            const n = fs2.readdirSync(homeAgents).filter((f) => f.startsWith("rihal-") && f.endsWith(".md")).length;
+            if (n > 0) {
+              agentCount = n;
+              agentsFromGlobal = true;
+            }
+          }
+          if (commandCount === 0 && fs2.existsSync(homeCommands)) {
+            const n = fs2.readdirSync(homeCommands).filter((f) => f.startsWith("rihal-") && f.endsWith(".md")).length;
+            if (n > 0) {
+              commandCount = n;
+              commandsFromGlobal = true;
+            }
+          }
+        }
       } catch {
       }
       const version = readPackageVersion();
@@ -16505,8 +16525,8 @@ ${BLOCK}`);
       console.log("");
       const relAgents = path2.relative(opts.target, idePaths.agentsDir) || idePaths.agentsDir;
       const relCommands = path2.relative(opts.target, idePaths.commandsDir) || idePaths.commandsDir;
-      console.log(`  ${bold("Agents:")}    ${pc.green(String(agentCount))} in ${relAgents}/`);
-      console.log(`  ${bold("Commands:")}  ${pc.green(String(commandCount))} slash commands in ${relCommands}/`);
+      console.log(`  ${bold("Agents:")}    ${pc.green(String(agentCount))} in ${agentsFromGlobal ? "~/.claude/agents/ (global)" : relAgents + "/"}`);
+      console.log(`  ${bold("Commands:")}  ${pc.green(String(commandCount))} slash commands in ${commandsFromGlobal ? "~/.claude/commands/ (global)" : relCommands + "/"}`);
       if (skillsInstalled > 0) console.log(`  ${bold("Skills:")}    ${pc.green(String(skillsInstalled))} phrase-activated`);
       console.log("");
       if (starterSeeded) {
@@ -17070,6 +17090,20 @@ var require_manifest = __commonJS({
           }
         }
       }
+      if (installedAgents.size === 0) {
+        try {
+          const os = require("os");
+          const globalAgentsDir = path2.join(os.homedir(), ".claude/agents");
+          if (fs2.existsSync(globalAgentsDir)) {
+            for (const f of fs2.readdirSync(globalAgentsDir)) {
+              if (f.startsWith("rihal-") && f.endsWith(".md")) {
+                installedAgents.add(f.replace(/^rihal-/, "").replace(/\.md$/, ""));
+              }
+            }
+          }
+        } catch {
+        }
+      }
       const allInstalled = readInstalledDirs(skillsDir);
       const actionsInstalled = new Set(
         [...allInstalled].filter((n) => !n.startsWith("rihal-"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.4.20",
+  "version": "3.4.22",
   "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

@@ -985,6 +985,26 @@ function cmdState(subArgs) {
       try { process.kill(pid, 0); return true; } catch { return false; }
     }
 
+    // Issue #681: auto-clear the install-time _seeded_stub marker once the
+    // state has graduated to a real project (project field set + at least one
+    // real phase OR REQUIREMENTS.md present). project-status (#675) reads
+    // _seeded_stub; if no writer ever clears it, every project stays "stub"
+    // forever and downstream workflows misroute.
+    if (state._seeded_stub === true) {
+      const phases = Array.isArray(state.phases) ? state.phases : [];
+      const firstPhaseName = phases[0]?.name || '';
+      const hasRealPhase = phases.length > 1 ||
+        (firstPhaseName && firstPhaseName !== 'Setup & Scaffolding');
+      const hasRequirements = (() => {
+        try {
+          return fs.existsSync(path.join(PROJECT_ROOT, '.planning', 'REQUIREMENTS.md'));
+        } catch { return false; }
+      })();
+      if ((state.project && hasRealPhase) || hasRequirements) {
+        delete state._seeded_stub;
+      }
+    }
+
     state.updated = new Date().toISOString();
     fs.mkdirSync(RIHAL_DIR, { recursive: true });
     const lockPath = statePath + '.lock';
@@ -1069,6 +1089,23 @@ function cmdState(subArgs) {
     return state;
   }
 
+  // --- clear-stub --- (issue #681)
+  // Explicit way to flip _seeded_stub off. Useful for /rihal-new-project once
+  // PROJECT.md / REQUIREMENTS.md / ROADMAP.md are committed. The auto-clear in
+  // writeState() also handles this, but having an explicit subcommand lets
+  // workflows be self-documenting and idempotent.
+  if (sub === 'clear-stub') {
+    if (!fs.existsSync(statePath)) {
+      return { ok: false, error: 'No state.json — nothing to clear.' };
+    }
+    const state = readState();
+    if (!state) return { ok: false, error: 'state.json unreadable' };
+    const wasStub = state._seeded_stub === true;
+    if (wasStub) delete state._seeded_stub;
+    writeState(state);
+    return { ok: true, was_stub: wasStub, project: state.project || null };
+  }
+
   // --- init ---
   if (sub === 'init') {
     let existing;
@@ -5278,6 +5315,62 @@ function cmdSummaryExtract(args) {
  * Hides internal machinery (lock metadata, full history) from callers
  * that only need a render-ready summary.
  */
+/**
+ * cmdProjectStatus — classify project lifecycle state into one of:
+ *   uninstalled    — no .rihal/config.yaml
+ *   uninitialized  — config present, no state.json
+ *   stub           — install-seeded scaffolding only (issue #670)
+ *   real           — /rihal-new-project has run
+ *
+ * Real-project signals (any → real):
+ *   - .planning/REQUIREMENTS.md exists
+ *   - .planning/research/ directory exists
+ *   - state.phases.length > 1
+ *   - first phase name ≠ "Setup & Scaffolding"
+ *
+ * Closes #675 — single source of truth for "is this project initialized."
+ */
+function cmdProjectStatus() {
+  const configPath = path.join(RIHAL_DIR, 'config.yaml');
+  const statePath = path.join(RIHAL_DIR, 'state.json');
+  const planningDir = path.join(PROJECT_ROOT, '.planning');
+
+  if (!fs.existsSync(configPath)) return { ok: true, status: 'uninstalled' };
+  if (!fs.existsSync(statePath)) return { ok: true, status: 'uninitialized' };
+
+  let state;
+  try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); }
+  catch (e) { return { ok: false, error: `invalid state.json: ${e.message}` }; }
+
+  const hasRequirements = fs.existsSync(path.join(planningDir, 'REQUIREMENTS.md'));
+  const hasResearch = fs.existsSync(path.join(planningDir, 'research'));
+  const phases = state.phases || [];
+  const phaseCountReal = phases.length > 1;
+  const firstPhaseName = phases[0]?.name || '';
+  const phaseNameReal = firstPhaseName && firstPhaseName !== 'Setup & Scaffolding';
+
+  const isReal = hasRequirements || hasResearch || phaseCountReal || phaseNameReal;
+  const isStub = state._seeded_stub === true || !state.project || !isReal;
+
+  let status;
+  if (isReal) status = 'real';
+  else if (isStub) status = 'stub';
+  else status = 'uninitialized';
+
+  return {
+    ok: true,
+    status,
+    signals: {
+      project: state.project || null,
+      seeded_stub: state._seeded_stub === true,
+      has_requirements: hasRequirements,
+      has_research: hasResearch,
+      phase_count: phases.length,
+      first_phase_name: firstPhaseName || null,
+    },
+  };
+}
+
 function cmdStateSnapshot() {
   const statePath = path.join(RIHAL_DIR, 'state.json');
   if (!fs.existsSync(statePath)) return { ok: true, state: null };
@@ -5652,6 +5745,9 @@ async function main() {
       case 'agent-skills':
         result = cmdAgentInfo(args[0]);
         break;
+      case 'project-status':
+        result = cmdProjectStatus();
+        break;
       case 'version':
         console.log(readPackageVersion());
         return;

package/rihal/state.json

@@ -1,15 +1,14 @@
 {
   "version": "1",
-  "project": "__PROJECT_NAME__",
+  "project": null,
+  "_seeded_stub": true,
   "created": "__INSTALL_DATE__",
   "updated": "__INSTALL_DATE__",
-  "current_phase": "01",
+  "current_phase": null,
   "current_plan": 0,
   "current_sprint": null,
-  "milestone": "M1 — Initial Delivery",
-  "phases": [
-    { "id": "01", "name": "Setup & Scaffolding", "status": "planned" }
-  ],
+  "milestone": null,
+  "phases": [],
   "executions": [],
   "decisions": [],
   "blockers": [],

package/rihal/workflows/new-project.md

@@ -88,25 +88,67 @@ Valid Rihal subagent types (use exact names — do not fall back to 'general-pur
 - rihal-roadmapper — Creates phased execution roadmaps
 </available_agent_types>
 
-## Step 0.5 — Detect existing project (redirect)
+## Step 0.5 — Detect existing project (stub-aware redirect)
 
-Before any processing, check if a project already exists in this directory:
+Before any processing, classify the project state into one of:
+
+- **none** — no `.rihal/state.json`, no `.planning/` → proceed
+- **stub** — install-seeded scaffolding only (issue #670) → proceed (overwrite stub)
+- **real** — a previous `/rihal-new-project` ran here → guard, unless `--force`
 
 ```bash
-EXISTING=$(node .rihal/bin/rihal-tools.cjs state read 2>/dev/null | grep '"project"' | head -1)
+# --force / --reinit bypasses the guard entirely (issue #672).
+# --auto implies --force on stub state (issue #674).
+FORCE=false
+case " $ARGUMENTS " in
+  *" --force "*|*" --reinit "*) FORCE=true ;;
+esac
+
+# Single source of truth: rihal-tools project-status returns one of
+#   uninstalled | uninitialized | stub | real
+# (see issue #675 for the contract). Falls back to `none` when
+# rihal-tools is unavailable so the workflow still proceeds.
+PROJECT_STATE=$(node .rihal/bin/rihal-tools.cjs project-status 2>/dev/null \
+  | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).status||'none')}catch{console.log('none')}})" \
+  || echo "none")
+[ "$PROJECT_STATE" = "uninstalled" ] || [ "$PROJECT_STATE" = "uninitialized" ] && PROJECT_STATE="none"
 ```
 
-If `$EXISTING` is non-empty (project already initialized):
+**If `PROJECT_STATE=real` and `FORCE=false`:** show the guard:
 
 ```
 ⚠ A rihal project already exists here.
 
-To check current state: /rihal-status
-To find next action: /rihal-next
-To start a fresh phase instead: /rihal-add-phase
+Quick actions:
+  /rihal-status            check current state
+  /rihal-next              find next action
+  /rihal-add-phase         add a phase to the current milestone
+
+To start over (overwrites .planning/* and .rihal/state.json):
+  /rihal-new-project --force <description>
+  rcode install --reset                        nuclear option — wipes config + state
+```
+
+STOP — do not proceed.
+
+**If `PROJECT_STATE=stub` (issue #670 install scaffolding):** print a one-liner and proceed:
+
+```
+ℹ Install stub detected — overwriting with real project setup.
+```
+
+**If `PROJECT_STATE=none`:** proceed silently.
+
+**If `PROJECT_STATE=real` and `FORCE=true`:** create a rollback tag, then proceed:
+
+```bash
+if git rev-parse --git-dir >/dev/null 2>&1; then
+  TAG="pre-rihal-rewrite-$(date +%Y%m%d-%H%M%S)"
+  git tag "$TAG" 2>/dev/null && echo "ℹ Rollback tag created: $TAG"
+fi
 ```
 
-Only proceed past this step if no project exists (`$EXISTING` is empty).
+In interactive mode (not `--auto`), confirm via AskUserQuestion before overwriting. In `--auto` or YOLO mode, proceed without confirmation.
 
 <auto_mode>