@hanzlaa/rcode 2.1.0 → 2.3.1

package/cli/install.js

@@ -32,18 +32,22 @@
  *   .planning/
  *     council-sessions/        (empty dir, populated on first council run)
  *
- * Zero external dependencies. Pure Node stdlib.
+ * Bundled packages (devDeps, inlined by esbuild in dist/rcode.js):
+ *   picocolors, nanospinner, fast-glob, zod, semver, diff
  *
  * Usage:
  *   node cli/install.js [target-project-dir]
  *   node cli/install.js --help
  *
  * Flags:
- *   --force           overwrite existing files without prompting
- *   --yes             non-interactive, accept defaults
- *   --user <name>     set user_name in config.yaml (default: $USER)
- *   --project <name>  set project_name in config.yaml (default: basename of target)
- *   --language <lang> set communication_language (default: English)
+ *   --force             overwrite existing files without prompting
+ *   --yes               non-interactive, accept defaults
+ *   --user <name>       set user_name in config.yaml (default: $USER)
+ *   --project <name>    set project_name in config.yaml (default: basename of target)
+ *   --language <lang>   set communication_language (default: English)
+ *   --show-diff         print full unified diff for preserved files during update
+ *   --diff-stat         print +N -N summary for preserved files (default on update)
+ *   --accept-all        overwrite all user-modified files with source version
  */
 
 const fs = require('fs');
@@ -51,9 +55,51 @@ const path = require('path');
 const crypto = require('crypto');
 const os = require('os');
 
+// Bundled packages — devDeps inlined by esbuild, loaded from node_modules in dev.
+const pc = require('picocolors');
+const { createSpinner } = require('nanospinner');
+const fg = require('fast-glob');
+const { z } = require('zod');
+const semver = require('semver');
+const { createTwoFilesPatch } = require('diff');
+
+// Output helpers: always respect NO_COLOR / non-TTY (picocolors handles this).
+const ok   = (s) => pc.green('✓') + ' ' + s;
+const fail = (s) => pc.red('✗') + ' ' + s;
+const warn = (s) => pc.yellow('⚠') + ' ' + s;
+const info = (s) => pc.cyan('→') + ' ' + s;
+const dim  = (s) => pc.dim(s);
+const bold = (s) => pc.bold(s);
+
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const SOURCE_ROOT = path.join(PACKAGE_ROOT, 'rihal');
 
+// Zod schema for .rihal/config.yaml validation (#250).
+const ConfigSchema = z.object({
+  user_name: z.string().min(1),
+  project_name: z.string().min(1),
+  communication_language: z.string().default('English'),
+  mode: z.enum(['guided', 'yolo'], {
+    errorMap: () => ({ message: 'expected "guided" or "yolo"' }),
+  }).default('guided'),
+  model_profile: z.string().optional(),
+  commit_planning: z.boolean().optional(),
+  rihal_source_path: z.string().optional(),
+  workflow: z.object({
+    research_by_default: z.boolean().optional(),
+    plan_checker: z.boolean().optional(),
+    post_execute_gates: z.boolean().optional(),
+    ui_safety_gate: z.boolean().optional(),
+    nyquist_validation: z.boolean().optional(),
+  }).optional(),
+  output: z.object({
+    verbose: z.boolean().optional(),
+  }).optional(),
+  git: z.object({
+    branching_strategy: z.string().optional(),
+  }).optional(),
+}).passthrough();
+
 /**
  * Parse command-line args into a normalized options object.
  */
@@ -71,6 +117,19 @@ function parseArgs(argv) {
     ide: 'claude',  // claude, cursor, gemini (copilot = TODO)
     help: false,
     modules: [],  // --module core --module execution or empty = all
+    // #189 — planning commit policy. null = ask interactively (or default true under --yes).
+    // Set true by --commit-planning, false by --no-commit-planning or --ignore-planning.
+    commitPlanning: null,
+    // #232 — non-destructive update. Preserves files the user modified after install.
+    nonDestructive: false,
+    // #232 — force-overwrite always wins.
+    forceOverwrite: false,
+    // #251 — diff display flags
+    showDiff: false,
+    diffStat: false,
+    acceptAll: false,
+    // #252 — skip update-notifier check
+    noUpdateCheck: false,
   };
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
@@ -85,6 +144,14 @@ function parseArgs(argv) {
     else if (arg === '--mode') opts.mode = argv[++i];
     else if (arg === '--ide') opts.ide = argv[++i];
     else if (arg === '--module') opts.modules.push(argv[++i]);
+    else if (arg === '--commit-planning') opts.commitPlanning = true;
+    else if (arg === '--no-commit-planning' || arg === '--ignore-planning') opts.commitPlanning = false;
+    else if (arg === '--non-destructive') opts.nonDestructive = true;
+    else if (arg === '--force-overwrite') opts.forceOverwrite = true;
+    else if (arg === '--show-diff') opts.showDiff = true;       // #251 full unified diff
+    else if (arg === '--diff-stat') opts.diffStat = true;       // #251 +N -N summary (default)
+    else if (arg === '--accept-all') opts.acceptAll = true;     // #251 overwrite all preserved
+    else if (arg === '--no-update-check') opts.noUpdateCheck = true; // #252
     else if (!arg.startsWith('--')) positional.push(arg);
   }
   if (positional[0]) {
@@ -95,6 +162,30 @@ function parseArgs(argv) {
   return opts;
 }
 
+/**
+ * Resolve commit-planning preference — CLI flag wins, then interactive
+ * prompt (when TTY + not --yes), else GSD-style default: true.
+ * #189.
+ */
+async function resolveCommitPlanning(opts) {
+  if (opts.commitPlanning !== null) return opts.commitPlanning;
+  if (opts.yes || !process.stdin.isTTY) return true; // non-interactive default
+
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const prompt = (q) => new Promise(r => rl.question(q, a => r(a)));
+  console.log('');
+  console.log('📋 .planning/ holds PRDs, roadmaps, sprints, SUMMARY files.');
+  console.log('   Commit them to git, or keep them local?');
+  console.log('');
+  console.log('   [Y] Commit — collaborators see the same plans  (default, recommended)');
+  console.log('   [n] Gitignore — planning stays local  (good for sensitive PRDs)');
+  console.log('');
+  const answer = (await prompt('   Commit planning artifacts? [Y/n]: ')).trim().toLowerCase();
+  rl.close();
+  return !(answer === 'n' || answer === 'no');
+}
+
 function printHelp() {
   console.log(`
 Rihal Code installer
@@ -159,17 +250,32 @@ function getPathsForIde(ide, target) {
 }
 
 /**
- * Recursively walk a directory and return absolute file paths.
+ * Walk a directory and return absolute file paths. Uses fast-glob so
+ * symlink cycles are never followed and patterns can be excluded via
+ * .rihalignore files (#249).
  */
-function walkFiles(dir) {
-  const out = [];
-  if (!fs.existsSync(dir)) return out;
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walkFiles(full));
-    else if (entry.isFile()) out.push(full);
-  }
-  return out;
+function walkFiles(dir, extraIgnore = []) {
+  if (!fs.existsSync(dir)) return [];
+  return fg.sync('**/*', {
+    cwd: dir,
+    dot: true,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    ignore: extraIgnore,
+  }).map((rel) => path.join(dir, rel));
+}
+
+/**
+ * Read .rihalignore patterns from a given root directory.
+ * Returns an array of glob-style ignore patterns (same syntax as .gitignore).
+ */
+function readRihalIgnore(root) {
+  const ignoreFile = path.join(root, '.rihalignore');
+  if (!fs.existsSync(ignoreFile)) return [];
+  return fs.readFileSync(ignoreFile, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
 }
 
 function sha256(buffer) {
@@ -284,6 +390,146 @@ function seedStarterPlanning(target, projectName) {
   return true;
 }
 
+/**
+ * Ensure the target project's .gitignore has the rcode-managed block.
+ *
+ * Idempotent via a sentinel comment line. On first install, appends a block
+ * that separates:
+ *   - installed methodology files (ignored; re-install to refresh)
+ *   - user's project config, state, and planning artifacts (committable)
+ *
+ * If the user already has a block (marker present) we leave their customizations
+ * alone. This function is best-effort — never throws. A missing .gitignore
+ * is created. A read/write error is logged and install continues.
+ *
+ * Returns: { action: 'created' | 'appended' | 'already-present' | 'skipped-error' }
+ */
+function ensureRcodeGitignore(target, options = {}) {
+  const commitPlanning = options.commitPlanning !== false; // default true
+  const BEGIN = '# ===== rcode-managed gitignore block (npx @hanzlaa/rcode install) =====';
+  const END   = '# ===== end rcode-managed gitignore block =====';
+
+  const lines = [
+    '',
+    BEGIN,
+    '# Added automatically on first rcode install. Idempotent — safe to re-run.',
+    '# Edit `commit_planning` in .rihal/config.yaml to flip planning-artifact tracking.',
+    '',
+    '# Installed methodology files (regenerate with: npx @hanzlaa/rcode install)',
+    '.claude/',
+    '.rihal/bin/',
+    '.rihal/workflows/',
+    '.rihal/references/',
+    '.rihal/commands/',
+    '.rihal/skills/',
+    '',
+    '# Pulled Rihal brain content (refresh with: rcode brain pull)',
+    '.rihal/brain/rihal-github/',
+    '.rihal/brain/rihal-docs/',
+    '.rihal/brain/best-practices/',
+    '',
+    '# Runtime noise',
+    '.rihal/state.json.lock',
+    '.planning/debug/',
+    '.planning/_backup/',
+  ];
+
+  if (!commitPlanning) {
+    lines.push(
+      '',
+      '# Planning artifacts — kept local (commit_planning: false)',
+      '.planning/'
+    );
+  }
+
+  lines.push(
+    '',
+    '# What you DO commit:',
+    '#   .rihal/config.yaml        - project mode/language/profile/commit_planning',
+    '#   .rihal/state.json         - decisions, roadmap pointer, blockers',
+    '#   .rihal/brain/sources.yaml - brain source manifest',
+    commitPlanning
+      ? '#   .planning/                - PRD, roadmap, sprints, SUMMARY.md files'
+      : '#   (planning artifacts are NOT committed — see commit_planning in config)',
+    END,
+    ''
+  );
+  const BLOCK = lines.join('\n');
+
+  const gitignorePath = path.join(target, '.gitignore');
+  try {
+    if (!fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, BLOCK);
+      return { action: 'created' };
+    }
+    const existing = fs.readFileSync(gitignorePath, 'utf8');
+    // Replace existing rcode block using indexOf (regex escaping on the
+    // sentinel is fiddly — indexOf is deterministic and easier to audit).
+    function spliceBlock(text, newBlock) {
+      const start = text.indexOf(BEGIN);
+      if (start < 0) return null;
+      const endIdx = text.indexOf(END, start);
+      if (endIdx < 0) return null;
+      let sliceStart = start;
+      if (sliceStart > 0 && text[sliceStart - 1] === '\n') sliceStart -= 1;
+      let sliceEnd = endIdx + END.length;
+      if (text[sliceEnd] === '\n') sliceEnd += 1;
+      return text.slice(0, sliceStart) + newBlock + text.slice(sliceEnd);
+    }
+    if (existing.includes(BEGIN)) {
+      const rewritten = spliceBlock(existing, BLOCK);
+      if (rewritten !== null && rewritten !== existing) {
+        fs.writeFileSync(gitignorePath, rewritten);
+        return { action: 'updated' };
+      }
+      return { action: 'already-present' };
+    }
+    fs.writeFileSync(gitignorePath, existing + BLOCK);
+    return { action: 'appended' };
+  } catch (err) {
+    return { action: 'skipped-error', error: err.message };
+  }
+}
+
+/**
+ * Install brain scaffold (sources.yaml + README.md) into .rihal/brain/ on target.
+ * Actual brain content lands after `brain pull` runs.
+ * Closes #188 — previously the package's rihal/brain/sources.yaml was never
+ * copied to the target at all, leaving brain pull permanently broken.
+ */
+function installBrainScaffold(packageRoot, target) {
+  const srcDir = path.join(packageRoot, 'rihal', 'brain');
+  const destDir = path.join(target, '.rihal', 'brain');
+  fs.mkdirSync(destDir, { recursive: true });
+  let copied = 0;
+  for (const name of ['sources.yaml', 'README.md']) {
+    const src = path.join(srcDir, name);
+    const dest = path.join(destDir, name);
+    if (fs.existsSync(src) && !fs.existsSync(dest)) {
+      fs.copyFileSync(src, dest);
+      copied++;
+    }
+  }
+  // Also pre-seed the best-practices subfolder from the package's
+  // rihal/skills/_shared/ so a fresh install has working brain content
+  // immediately, even before brain pull runs against real upstream URLs.
+  const sharedSrc = path.join(packageRoot, 'rihal', 'skills', '_shared');
+  if (fs.existsSync(sharedSrc)) {
+    const bpDest = path.join(destDir, 'best-practices');
+    fs.mkdirSync(bpDest, { recursive: true });
+    for (const entry of fs.readdirSync(sharedSrc, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        const dest = path.join(bpDest, entry.name);
+        if (!fs.existsSync(dest)) {
+          fs.copyFileSync(path.join(sharedSrc, entry.name), dest);
+          copied++;
+        }
+      }
+    }
+  }
+  return copied;
+}
+
 /**
  * Install v1-style skills into the target project.
  *
@@ -575,6 +821,67 @@ function generateFilesManifest(plan, target) {
   return rows.map((r) => r.join(',')).join('\n') + '\n';
 }
 
+/**
+ * Orphan sweep — remove files that were part of a previous install but aren't
+ * in the current plan. Reads `.rihal/_config/files-manifest.csv` from the
+ * previous install and computes the diff against the new plan.
+ *
+ * Closes #196 — without this, upgrading rcode leaves stale skill/command
+ * files around that show up as ghost slash commands in the IDE.
+ *
+ * Deliberately conservative:
+ *   - Only removes files that appeared in the PREVIOUS manifest.
+ *   - Never removes files the user created themselves.
+ *   - Never touches .rihal/config.yaml, .rihal/state.json, or .planning/.
+ *
+ * Returns the number of orphan files removed.
+ */
+function sweepStaleInstalledFiles(target, newPlan) {
+  const manifestPath = path.join(target, '.rihal', '_config', 'files-manifest.csv');
+  if (!fs.existsSync(manifestPath)) return 0;
+
+  let oldRels;
+  try {
+    const rows = fs.readFileSync(manifestPath, 'utf8').split('\n').slice(1).filter(Boolean);
+    oldRels = rows.map(r => r.split(',')[0]).filter(Boolean);
+  } catch {
+    return 0;
+  }
+
+  const newRelsSet = new Set(newPlan.map(e => e.rel.split(path.sep).join('/')));
+  // Safety — never sweep these, even if they somehow landed in the manifest.
+  const neverSweep = /^(\.rihal\/config\.yaml|\.rihal\/state\.json|\.rihal\/state\.json\.lock|\.planning\/|\.rihal\/brain\/sources\.yaml)/;
+
+  let removed = 0;
+  const emptyCandidateDirs = new Set();
+  for (const rel of oldRels) {
+    if (newRelsSet.has(rel)) continue;
+    if (neverSweep.test(rel)) continue;
+    const full = path.join(target, rel);
+    try {
+      if (fs.existsSync(full)) {
+        fs.rmSync(full, { force: true });
+        emptyCandidateDirs.add(path.dirname(full));
+        removed += 1;
+      }
+    } catch {
+      // ignore individual failures — sweep is best-effort
+    }
+  }
+
+  // Remove any now-empty parent dirs (bottom-up, so nested emptiness cascades).
+  const dirsSortedDeep = Array.from(emptyCandidateDirs).sort((a, b) => b.length - a.length);
+  for (const dir of dirsSortedDeep) {
+    try {
+      if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+        fs.rmdirSync(dir);
+      }
+    } catch {}
+  }
+
+  return removed;
+}
+
 function readPackageVersion() {
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
@@ -587,13 +894,18 @@ function readPackageVersion() {
 function generateInstallManifest(opts) {
   const version = readPackageVersion();
   const newModules = opts.modules.length > 0 ? opts.modules : listAvailableModules();
-  // Merge with existing manifest if present
+  // Merge with existing manifest if present; capture previous_version for rollback (#253).
   let existingModules = [];
+  let previousVersion = null;
   const existingPath = path.join(opts.target, '.rihal', '_config', 'manifest.yaml');
   if (fs.existsSync(existingPath)) {
     const text = fs.readFileSync(existingPath, 'utf8');
     let inModules = false;
     for (const line of text.split('\n')) {
+      if (line.startsWith('version:')) {
+        const v = line.replace('version:', '').trim();
+        if (semver.valid(v) && v !== version) previousVersion = v;
+      }
       if (line.startsWith('modules:')) { inModules = true; continue; }
       if (inModules && line.trim().startsWith('-')) { existingModules.push(line.trim().slice(1).trim()); }
       else if (inModules && !line.startsWith(' ')) { inModules = false; }
@@ -601,16 +913,14 @@ function generateInstallManifest(opts) {
   }
   const allModules = [...new Set([...existingModules, ...newModules])];
   const moduleLines = allModules.map((m) => `  - ${m}`).join('\n');
-  return [
+  const lines = [
     '# Rihal v2 install manifest',
     `version: ${version}`,
     `installDate: ${new Date().toISOString()}`,
-    'modules:',
-    moduleLines,
-    'ides:',
-    '  - claude-code',
-    '',
-  ].join('\n');
+  ];
+  if (previousVersion) lines.push(`previous_version: ${previousVersion}`);
+  lines.push('modules:', moduleLines, 'ides:', '  - claude-code', '');
+  return lines.join('\n');
 }
 
 function sanitizeYamlValue(val) {
@@ -626,6 +936,7 @@ function generateConfigYaml(opts) {
     `communication_language: "${sanitizeYamlValue(opts.language)}"`,
     `mode: "${sanitizeYamlValue(opts.mode)}"`,
     `model_profile: "balanced"`,
+    `commit_planning: ${opts.commitPlanning !== false}`,
     `rihal_source_path: "${sanitizeYamlValue(path.dirname(path.dirname(process.argv[1])))}/"`,
     'workflow:',
     '  research_by_default: false',
@@ -638,6 +949,57 @@ function generateConfigYaml(opts) {
   ].join('\n');
 }
 
+/**
+ * Validate a parsed config.yaml object against ConfigSchema (#250).
+ * Returns { valid: true } or { valid: false, errors: string[] }.
+ */
+function validateConfig(data) {
+  const result = ConfigSchema.safeParse(data);
+  if (result.success) return { valid: true };
+  const errors = result.error.issues.map((issue) => {
+    const field = issue.path.join('.');
+    return `  ${field || '(root)'}: ${issue.message}`;
+  });
+  return { valid: false, errors };
+}
+
+/**
+ * Parse a minimal YAML key:value file into a plain object.
+ * Only handles scalar values — sufficient for config.yaml.
+ */
+function parseSimpleYaml(text) {
+  const obj = {};
+  let currentParent = null;
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/#.*$/, '');
+    if (!line.trim()) continue;
+    const indent = line.match(/^(\s*)/)[1].length;
+    if (indent === 0) {
+      const colonAt = line.indexOf(':');
+      if (colonAt === -1) continue;
+      const key = line.slice(0, colonAt).trim();
+      let val = line.slice(colonAt + 1).trim();
+      if (val === '') { currentParent = key; obj[key] = {}; continue; }
+      currentParent = null;
+      if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+      if (val.startsWith("'") && val.endsWith("'")) val = val.slice(1, -1);
+      if (val === 'true') val = true;
+      else if (val === 'false') val = false;
+      obj[key] = val;
+    } else if (currentParent && indent > 0) {
+      const colonAt = line.indexOf(':');
+      if (colonAt === -1) continue;
+      const key = line.slice(0, colonAt).trim();
+      let val = line.slice(colonAt + 1).trim();
+      if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+      if (val === 'true') val = true;
+      else if (val === 'false') val = false;
+      obj[currentParent][key] = val;
+    }
+  }
+  return obj;
+}
+
 /**
  * Convert a markdown command/agent file to Cursor's .mdc format.
  * Wraps the file with Cursor-specific rules frontmatter.
@@ -652,18 +1014,56 @@ function convertToCursorMdc(sourceText) {
 /**
  * Main install routine. Copies files, generates manifests, writes config.
  */
-function install(opts) {
+async function install(opts) {
   if (opts.help) { printHelp(); return 0; }
 
-  console.log(`\n🕌 Rihal Code installer → ${opts.target}`);
+  // Resolve commit-planning preference (interactive prompt or flag) — #189.
+  opts.commitPlanning = await resolveCommitPlanning(opts);
+
+  const pkgVersion = readPackageVersion();
+  console.log(`\n🕌 ${bold('Rihal Code')} ${pc.cyan('v' + pkgVersion)} ${dim('→')} ${opts.target}`);
+
+  // Detect an existing install and surface it (#195).
+  const existingManifestPath = path.join(opts.target, '.rihal', '_config', 'manifest.yaml');
+  if (fs.existsSync(existingManifestPath)) {
+    const m = fs.readFileSync(existingManifestPath, 'utf8').match(/^version:\s*(.+)$/m);
+    const existingVersion = m ? m[1].trim() : 'unknown';
+    const isUpgrade = semver.valid(existingVersion) && semver.valid(pkgVersion)
+      ? semver.lt(existingVersion, pkgVersion)
+      : existingVersion !== pkgVersion;
+    if (isUpgrade) {
+      console.log('  ' + info(`Upgrading ${pc.dim('v' + existingVersion)} → ${pc.green('v' + pkgVersion)} (config + state + .planning preserved)`));
+    } else {
+      console.log('  ' + info(`Refreshing v${existingVersion} (config + state + .planning preserved)`));
+    }
+    if (!opts.force) {
+      console.log(dim('    Pass --force to also sweep orphaned files from the previous version.'));
+    }
+  }
   if (!fs.existsSync(SOURCE_ROOT)) {
     console.error(`✖ Source tree not found at ${SOURCE_ROOT}. Running from wrong dir?`);
     return 1;
   }
 
-  // Validate IDE
+  // Validate IDE — structured error for unsupported editors (#197).
   if (!['claude', 'cursor', 'gemini'].includes(opts.ide)) {
-    console.error(`✖ Unknown IDE: ${opts.ide}. Supported: claude, cursor, gemini`);
+    console.error(`✖ --ide ${opts.ide} is not supported in v${readPackageVersion()}.`);
+    console.error('');
+    console.error('  Currently supported:');
+    console.error('    claude    — Claude Code native (recommended)');
+    console.error('    cursor    — Cursor IDE');
+    console.error('    gemini    — Gemini CLI');
+    console.error('');
+    console.error('  Tracked for v3.0 (see issue #182):');
+    console.error('    vscode    — VS Code native extension');
+    console.error('    jetbrains — IntelliJ / PyCharm');
+    console.error('    zed       — Zed editor');
+    console.error('');
+    if (/^(vscode|vs-code|code)$/i.test(opts.ide)) {
+      console.error('  Workaround: if you use VS Code WITH the Claude Code extension,');
+      console.error('  run `--ide claude` — the extension reads from .claude/ too.');
+      console.error('');
+    }
     return 1;
   }
 
@@ -698,46 +1098,103 @@ function install(opts) {
     console.log(`  Modules: ${opts.modules.join(', ')}`);
   }
 
-  // Copy files
+  // Orphan sweep — remove files from previous install not in the new plan (#196).
+  // Runs on --force only, to preserve user-edited or hand-dropped files on regular installs.
+  let sweptOrphans = 0;
+  if (opts.force) {
+    sweptOrphans = sweepStaleInstalledFiles(opts.target, plan);
+  }
+
+  // Load previous manifest for non-destructive mode (#232).
+  // Map<rel, expectedHashFromPriorInstall> — if a file's current hash matches
+  // its expected-from-prior-install hash, the user hasn't touched it → safe
+  // to overwrite. If hashes differ, user customized it → preserve.
+  const priorManifest = new Map();
+  if (opts.nonDestructive) {
+    const manifestPath = path.join(opts.target, '.rihal', '_config', 'files-manifest.csv');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const lines = fs.readFileSync(manifestPath, 'utf8').split('\n').slice(1).filter(Boolean);
+        for (const line of lines) {
+          const [rel, hash] = line.split(',');
+          if (rel && hash) priorManifest.set(rel, hash);
+        }
+      } catch {
+        // best-effort — if manifest is malformed, fall back to behaving like fresh install
+      }
+    }
+  }
+
+  // Copy files — spinner gives feedback on long installs (#248).
   let copied = 0;
   let skipped = 0;
+  let preserved = 0;
+  const preservedFiles = [];
+  const preservedDiffs = [];  // { rel, insertions, deletions, patch } for #251
+  const spinner = createSpinner(dim(`Installing ${plan.length} files…`), { color: 'cyan' }).start();
+
   for (const entry of plan) {
     const destPath = path.join(opts.target, entry.rel);
+    const relForward = entry.rel.split(path.sep).join('/');
     ensureDir(path.dirname(destPath));
-    if (fs.existsSync(destPath) && !opts.force) {
+
+    // Non-destructive guard (#232): preserve user-modified files.
+    // --accept-all (#251) overrides: treat all files as pristine.
+    if (opts.nonDestructive && !opts.forceOverwrite && !opts.acceptAll && fs.existsSync(destPath)) {
+      const priorHash = priorManifest.get(relForward);
+      if (priorHash) {
+        const installedContent = fs.readFileSync(destPath, 'utf8');
+        const currentHash = sha256(Buffer.from(installedContent));
+        if (currentHash !== priorHash) {
+          // Compute diff stat for display (#251)
+          const srcContent = fs.readFileSync(entry.src, 'utf8');
+          const patch = createTwoFilesPatch(relForward, relForward, installedContent, srcContent, 'installed', 'source');
+          let ins = 0, del = 0;
+          for (const line of patch.split('\n')) {
+            if (line.startsWith('+') && !line.startsWith('+++')) ins++;
+            if (line.startsWith('-') && !line.startsWith('---')) del++;
+          }
+          preserved += 1;
+          preservedFiles.push(relForward);
+          preservedDiffs.push({ rel: relForward, insertions: ins, deletions: del, patch });
+          skipped += 1;
+          continue;
+        }
+        // Hash matches prior install → pristine → safe to overwrite
+      }
+      // No prior hash → new file in this plan → install normally
+    }
+
+    if (fs.existsSync(destPath) && !opts.force && !opts.forceOverwrite) {
       const existingHash = sha256(fs.readFileSync(destPath));
       const sourceHash = sha256(fs.readFileSync(entry.src));
       if (existingHash === sourceHash) { skipped++; continue; }
-      if (!opts.yes) {
-        console.warn(`  ⚠ ${entry.rel} differs from package version — use --force to overwrite`);
+      if (!opts.yes && !opts.nonDestructive) {
+        spinner.stop();
+        console.warn('  ' + warn(`${entry.rel} differs from package version — use --force-overwrite to overwrite`));
+        spinner.start();
         skipped++;
         continue;
       }
     }
 
-    // Warn if overwriting modified file
-    if (fs.existsSync(destPath) && opts.force) {
+    if (fs.existsSync(destPath) && opts.forceOverwrite) {
       const existing = fs.readFileSync(destPath);
       const incoming = fs.readFileSync(entry.src);
       if (!existing.equals(incoming)) {
-        console.log(`  ⚠ Overwriting modified file: ${destPath}`);
+        spinner.update({ text: dim(`overwriting ${entry.rel}`) });
       }
     }
 
-    // Read source file
     let content = fs.readFileSync(entry.src, 'utf8');
-
-    // Convert to Cursor .mdc format if needed
-    if (entry.cursor) {
-      content = convertToCursorMdc(content);
-    }
-
-    // Write to destination
+    if (entry.cursor) content = convertToCursorMdc(content);
     fs.writeFileSync(destPath, content, 'utf8');
     if (entry.executable) fs.chmodSync(destPath, 0o755);
     copied++;
   }
 
+  spinner.success({ text: ok(`${copied} files installed`) });
+
   // Write .rihal/_config/manifest.yaml + agent-manifest.csv + files-manifest.csv
   const configDir = path.join(opts.target, '.rihal', '_config');
   ensureDir(configDir);
@@ -765,6 +1222,18 @@ function install(opts) {
   if (!fs.existsSync(configPath)) {
     fs.writeFileSync(configPath, generateConfigYaml(opts));
   }
+  // Validate config.yaml with zod schema (#250) — warn but never block install.
+  try {
+    const configText = fs.readFileSync(configPath, 'utf8');
+    const configData = parseSimpleYaml(configText);
+    const validation = validateConfig(configData);
+    if (!validation.valid) {
+      console.log('');
+      console.log('  ' + warn('config.yaml has validation errors:'));
+      for (const e of validation.errors) console.log(pc.yellow(e));
+      console.log(dim('  → Edit .rihal/config.yaml to fix, then run /rihal:status'));
+    }
+  } catch { /* best-effort */ }
 
   // Seed .rihal/state.json (skip if already exists — don't overwrite on re-install unless --reset)
   if (!fs.existsSync(stateDest)) {
@@ -801,6 +1270,14 @@ function install(opts) {
   // Seed .planning/ with starter ROADMAP + STATE so workflows work immediately
   const starterSeeded = seedStarterPlanning(opts.target, opts.projectName);
 
+  // Install brain scaffolding at .rihal/brain/ (sources.yaml + README).
+  // Actual brain content lands after first brain pull runs.
+  installBrainScaffold(PACKAGE_ROOT, opts.target);
+
+  // Ensure .gitignore separates installed methodology from committable artifacts.
+  // Reads opts.commitPlanning to decide whether .planning/ is in the ignore block.
+  const gitignoreReport = ensureRcodeGitignore(opts.target, { commitPlanning: opts.commitPlanning });
+
   // Pull Rihal brain content (v2.0 — issue #158).
   // Runs rihal-tools brain pull as a child process. Placeholder URLs
   // are skipped gracefully so this does not fail a fresh install.
@@ -823,53 +1300,185 @@ function install(opts) {
 
   // Summary
   console.log('');
-  console.log(`  Installed: ${copied} file${copied === 1 ? '' : 's'}`);
-  if (skillsInstalled > 0) {
-    console.log(`  Skills:    ${skillsInstalled} phrase-activated (in .claude/skills/)`);
+  if (opts.force && sweptOrphans > 0) console.log('  ' + info(`${sweptOrphans} stale files swept`));
+  if (opts.force && existedBefore) {
+    console.log('  ' + warn('config.yaml and state.json preserved (pass --reset to wipe)'));
   }
   if (brainReport && brainReport.ok) {
     const pulledCount = (brainReport.pulled || []).length;
     const skippedCount = (brainReport.skipped || []).length;
-    console.log(`  Brain:     ${pulledCount} source${pulledCount === 1 ? '' : 's'} pulled` +
-      (skippedCount ? `, ${skippedCount} skipped (placeholder URLs — see issue #162)` : ''));
+    console.log('  ' + ok(`Brain: ${pulledCount} source${pulledCount === 1 ? '' : 's'} pulled` +
+      (skippedCount ? `, ${skippedCount} skipped (placeholder URLs)` : '')));
   } else if (brainReport && brainReport.error) {
-    console.log(`  Brain:     skipped (${brainReport.error})`);
+    console.log('  ' + dim(`Brain: skipped (${brainReport.error})`));
   }
-  if (skipped > 0) console.log(`  Skipped:   ${skipped} (already present, unchanged)`);
-  if (opts.force && existedBefore) {
-    console.log('  ⚠ Preserved: .rihal/config.yaml and .rihal/state.json');
-    console.log('     Pass --reset to wipe and re-init those too.');
+  if (gitignoreReport) {
+    const gitMsg = {
+      'created': '.gitignore created with rcode block',
+      'appended': '.gitignore updated — rcode block appended',
+      'already-present': '.gitignore rcode block already present',
+      'updated': '.gitignore rcode block refreshed',
+      'skipped-error': `.gitignore skipped (${gitignoreReport.error})`,
+    }[gitignoreReport.action] || '.gitignore unchanged';
+    console.log('  ' + dim(gitMsg));
   }
+  if (skipped > 0) console.log('  ' + dim(`${skipped} files skipped (unchanged)`));
+
+  // Diff display for preserved files (#251)
+  if (preserved > 0 && opts.nonDestructive) {
+    console.log('');
+    console.log('  ' + warn(`${preserved} file${preserved === 1 ? '' : 's'} preserved (modified since install):`));
+    for (const d of preservedDiffs.slice(0, 10)) {
+      const stat = pc.green(`+${d.insertions}`) + ' ' + pc.red(`-${d.deletions}`);
+      console.log(`     ${dim(d.rel)}  ${stat}`);
+      if (opts.showDiff && d.patch) {
+        for (const line of d.patch.split('\n').slice(4)) {  // skip file headers
+          if (line.startsWith('+')) process.stdout.write(pc.green(line) + '\n');
+          else if (line.startsWith('-')) process.stdout.write(pc.red(line) + '\n');
+          else if (line.startsWith('@')) process.stdout.write(pc.cyan(line) + '\n');
+          else process.stdout.write(dim(line) + '\n');
+        }
+      }
+    }
+    if (preservedDiffs.length > 10) console.log(dim(`     … and ${preservedDiffs.length - 10} more`));
+    console.log(dim('  To overwrite: re-run with --force-overwrite  |  To see full diffs: --show-diff'));
+    console.log('');
+  }
+
+  // Count installed agents + commands dynamically (#190).
+  const agentsDir = path.join(opts.target, '.claude', 'agents');
+  const commandsDir = path.join(opts.target, '.claude', 'commands', 'rihal');
+  let agentCount = 0, commandCount = 0;
+  try {
+    if (fs.existsSync(agentsDir)) {
+      agentCount = fs.readdirSync(agentsDir).filter(f => f.startsWith('rihal-') && f.endsWith('.md')).length;
+    }
+    if (fs.existsSync(commandsDir)) {
+      commandCount = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md')).length;
+    }
+  } catch {}
+
+  const version = readPackageVersion();
   console.log('');
-  console.log(`  Installed for IDE: ${opts.ide}`);
-  console.log(`  Language: ${opts.language}  (change in .rihal/config.yaml → communication_language)`);
-  console.log(`  Mode: ${opts.mode}  (guided=confirm at gates, yolo=autonomous)`);
-  console.log(`  Model profile: balanced`);
-  console.log('');
-  console.log('  Agents installed (first-class subagents):');
-  console.log('    🧭 rihal-sadiq   — Director of Strategy');
-  console.log('    🏗️  rihal-waleed  — CTO');
-  console.log('    🛡️  rihal-fatima  — QA Lead');
+  console.log(`  ${bold('Version:')}   ${pc.cyan('@hanzlaa/rcode@' + version)}`);
+  console.log(`  ${bold('IDE:')}       ${opts.ide}`);
+  console.log(`  ${bold('Language:')}  ${opts.language}  ${dim('(change in .rihal/config.yaml)')}`);
+  console.log(`  ${bold('Mode:')}      ${opts.mode}  ${dim('(guided=confirm at gates, yolo=autonomous)')}`);
+  console.log(`  ${bold('Planning:')}  ${opts.commitPlanning !== false ? 'committed' : 'gitignored'}  ${dim('(flip: rihal-tools gitignore refresh)')}`);
   console.log('');
-  console.log('  Slash commands installed:');
-  console.log('    /rihal:council  — parallel multi-agent council');
-  console.log('    /rihal:status   — project state dashboard');
-  console.log('    /rihal:insert-phase — insert decimal phase for urgent work');
+  console.log(`  ${bold('Agents:')}    ${pc.green(String(agentCount))} in .claude/agents/`);
+  console.log(`  ${bold('Commands:')}  ${pc.green(String(commandCount))} slash commands in .claude/commands/rihal/`);
+  if (skillsInstalled > 0) console.log(`  ${bold('Skills:')}    ${pc.green(String(skillsInstalled))} phrase-activated in .claude/skills/`);
   console.log('');
   if (starterSeeded) {
-    console.log('  ✓ Starter planning scaffolded in .planning/ (ROADMAP, STATE, PROJECT)');
+    console.log('  ' + ok('Starter planning scaffolded in .planning/ (ROADMAP, STATE, PROJECT)'));
     console.log('');
   }
-  console.log('  Next:');
+  console.log(`  ${bold('Next:')}`);
   console.log(`    cd ${opts.target}`);
-  console.log('    claude  # start Claude Code (or restart if already open)');
-  console.log('    /rihal:sprint-planning      # plan your first sprint');
-  console.log('    /rihal:do                   # interactive command picker');
-  console.log('    /rihal:council <question>   # multi-agent strategic answer');
+  console.log('    claude              # start Claude Code (reload window if already open)');
+  console.log('    /rihal:progress     # where you are, what\'s next');
+  console.log('    /rihal:do           # interactive command picker');
+  console.log('    /rihal:council <q>  # multi-agent strategic answer');
+  console.log('');
+  console.log(dim('  Refresh anytime:'));
+  console.log(dim('    npx @hanzlaa/rcode@latest install   # pull the latest rcode + brain'));
+  console.log(dim(`    /rihal:update v${version}              # pin rcode to a specific version`));
   console.log('');
-  console.log('  ⚠ If Claude Code is already running, start a new session to load commands.');
+  console.log('  ' + warn('If your IDE is already open, reload the window to refresh skills/commands.'));
+  console.log(dim('    Claude Code / VS Code / Cursor:  Cmd+Shift+P → Reload Window'));
   console.log('');
-  return 0;
+
+  // Lightweight update check (#252) — async background, never blocks install.
+  // Suppressed in non-TTY / CI or when --no-update-check is passed.
+  if (!opts.noUpdateCheck && process.stdout.isTTY && !process.env.CI && !process.env.RIHAL_NO_UPDATE_NOTIFIER) {
+    const { execFile } = require('child_process');
+    execFile('npm', ['view', '@hanzlaa/rcode', 'version', '--json'], { timeout: 4000 }, (err, stdout) => {
+      if (err) return;
+      try {
+        const latest = JSON.parse(stdout.trim());
+        if (semver.valid(latest) && semver.gt(latest, version)) {
+          console.log('');
+          console.log('  ╭──────────────────────────────────────────────────────╮');
+          console.log(`  │  ${pc.yellow('Update available:')} ${pc.dim(version)} → ${pc.green(latest)}${' '.repeat(Math.max(0, 20 - version.length - latest.length))}    │`);
+          console.log('  │  Run: npx @hanzlaa/rcode@latest install .            │');
+          console.log('  ╰──────────────────────────────────────────────────────╯');
+          console.log('');
+        }
+      } catch { /* ignore parse errors */ }
+    });
+  }
+
+  // Health check — smoke test that the install actually works (#193).
+  const healthPass = runInstallHealthCheck(opts.target, { agentCount, commandCount, skillsInstalled });
+  return healthPass ? 0 : 1;
+}
+
+/**
+ * Run a 5-point smoke test against the fresh install. Closes #193.
+ * Returns true if all pass, false if any critical check failed.
+ * Prints a clean ✓/✖ line per check.
+ */
+function runInstallHealthCheck(target, counts) {
+  console.log(`  ${bold('Health check:')}`);
+  const { execFileSync } = require('child_process');
+  let fails = 0;
+
+  function check(label, fn) {
+    try {
+      const out = fn();
+      console.log(`    ${ok(label)}${out ? dim(' — ' + out) : ''}`);
+    } catch (err) {
+      fails += 1;
+      console.log(`    ${fail(label)} ${pc.red('—')} ${String(err.message || err).slice(0, 120)}`);
+    }
+  }
+
+  check('rihal-tools.cjs runs', () => {
+    const toolsPath = path.join(target, '.rihal', 'bin', 'rihal-tools.cjs');
+    if (!fs.existsSync(toolsPath)) throw new Error('bin/rihal-tools.cjs not installed');
+    execFileSync('node', ['-c', toolsPath], { stdio: 'pipe' });
+    return 'syntax ok';
+  });
+
+  check('.rihal/config.yaml present', () => {
+    const p = path.join(target, '.rihal', 'config.yaml');
+    if (!fs.existsSync(p)) throw new Error('missing');
+    const text = fs.readFileSync(p, 'utf8');
+    if (!/user_name:|project_name:/.test(text)) throw new Error('config.yaml incomplete');
+    return `${fs.statSync(p).size} bytes`;
+  });
+
+  check('.rihal/state.json parses', () => {
+    const p = path.join(target, '.rihal', 'state.json');
+    if (!fs.existsSync(p)) throw new Error('missing');
+    JSON.parse(fs.readFileSync(p, 'utf8'));
+    return 'valid JSON';
+  });
+
+  check('agents installed', () => {
+    if ((counts.agentCount || 0) < 20) throw new Error(`only ${counts.agentCount} agents (expected ≥ 20)`);
+    return `${counts.agentCount}`;
+  });
+
+  check('skills + commands installed', () => {
+    const issues = [];
+    if ((counts.skillsInstalled || 0) < 20) issues.push(`${counts.skillsInstalled} skills`);
+    if ((counts.commandCount || 0) < 20) issues.push(`${counts.commandCount} commands`);
+    if (issues.length) throw new Error(`low count: ${issues.join(', ')}`);
+    return `${counts.skillsInstalled} skills + ${counts.commandCount} commands`;
+  });
+
+  if (fails > 0) {
+    console.log('');
+    console.log('  ' + fail(`${fails} health check${fails === 1 ? '' : 's'} failed — install may be broken.`));
+    console.log(dim('     Debug: node .rihal/bin/rihal-tools.cjs state read && ls -la .rihal/'));
+    console.log(dim('     Reinstall: npx @hanzlaa/rcode install . --force'));
+    console.log('');
+    return false;
+  }
+  console.log('');
+  return true;
 }
 
 async function main() {
@@ -909,9 +1518,7 @@ async function main() {
     }
   }
 
-  try {
-    process.exit(install(opts));
-  } catch (err) {
+  install(opts).then(code => process.exit(code)).catch(err => {
     if (err.code === 'EACCES' || err.code === 'EPERM') {
       console.error(`✖ Permission denied: ${err.path || err.message}`);
       process.exit(1);
@@ -923,7 +1530,7 @@ async function main() {
     console.error(`✖ Install failed: ${err.message}`);
     if (process.env.DEBUG) console.error(err.stack);
     process.exit(1);
-  }
+  });
 }
 
 if (require.main === module) main();
@@ -933,10 +1540,10 @@ if (require.main === module) main();
  * Converts the index.js-style (args, ctx) signature into a cli/install.js
  * parseArgs-compatible argv and runs install().
  */
-function runFromCli(args /* , ctx */) {
+async function runFromCli(args /* , ctx */) {
   const argv = Array.isArray(args) ? args : [];
   const opts = parseArgs(argv);
-  const code = install(opts);
+  const code = await install(opts);
   if (code !== 0) process.exit(code);
 }