homegraph 0.9.10 → 1.1.1

package/dist/bin/homegraph.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * CodeGraph CLI
+ * HomeGraph CLI
  *
- * Command-line interface for CodeGraph code intelligence.
+ * Command-line interface for HomeGraph code intelligence.
  *
  * Usage:
  *   homegraph                    Run interactive installer (when no args)
  *   homegraph install            Run interactive installer
- *   homegraph uninstall          Remove CodeGraph from your agents
- *   homegraph init [path]        Initialize CodeGraph in a project
- *   homegraph uninit [path]      Remove CodeGraph from a project
+ *   homegraph uninstall          Remove HomeGraph from your agents
+ *   homegraph init [path]        Initialize HomeGraph in a project
+ *   homegraph uninit [path]      Remove HomeGraph from a project
  *   homegraph index [path]       Index all files in the project
  *   homegraph sync [path]        Sync changes since last index
  *   homegraph status [path]      Show index status
@@ -21,7 +21,7 @@
  *   homegraph callees <symbol>   Find what a function/method calls
  *   homegraph impact <symbol>    Analyze what code is affected by changing a symbol
  *   homegraph affected [files]   Find test files affected by changes
- *   homegraph upgrade [version]  Update CodeGraph to the latest release
+ *   homegraph upgrade [version]  Update HomeGraph to the latest release
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -65,16 +65,18 @@ const worktree_1 = require("../sync/worktree");
 const shimmer_progress_1 = require("../ui/shimmer-progress");
 const glyphs_1 = require("../ui/glyphs");
 const node_version_check_1 = require("./node-version-check");
+const fatal_handler_1 = require("./fatal-handler");
 const wasm_runtime_flags_1 = require("../extraction/wasm-runtime-flags");
 const extraction_version_1 = require("../extraction/extraction-version");
-// Lazy-load heavy modules (CodeGraph, runInstaller) to keep CLI startup fast.
-async function loadCodeGraph() {
+const telemetry_1 = require("../telemetry");
+// Lazy-load heavy modules (HomeGraph, runInstaller) to keep CLI startup fast.
+async function loadHomeGraph() {
     try {
         return await Promise.resolve().then(() => __importStar(require('../index')));
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        console.error(`\x1b[31m${(0, glyphs_1.getGlyphs)().err}\x1b[0m Failed to load CodeGraph modules.`);
+        console.error(`\x1b[31m${(0, glyphs_1.getGlyphs)().err}\x1b[0m Failed to load HomeGraph modules.`);
         console.error(`\n  Node: ${process.version}  Platform: ${process.platform} ${process.arch}`);
         console.error(`\n  Error: ${msg}`);
         console.error('\n  Try reinstalling with: npm install -g homegraph\n');
@@ -85,7 +87,7 @@ async function loadCodeGraph() {
 // which fails for ESM-only packages. This bypasses the transformation.
 // eslint-disable-next-line @typescript-eslint/no-implied-eval
 const importESM = new Function('specifier', 'return import(specifier)');
-// Block CodeGraph on Node.js 25.x — V8's turboshaft WASM JIT has a Zone
+// Block HomeGraph on Node.js 25.x — V8's turboshaft WASM JIT has a Zone
 // allocator bug that reliably crashes when compiling tree-sitter
 // grammars (see #54, #81, #140). The previous behaviour was a soft
 // console.warn that scrolls off-screen before the OOM crash 30 seconds
@@ -117,6 +119,12 @@ if (nodeMajor < node_version_check_1.MIN_NODE_MAJOR) {
 // passes the flag. Must run before any grammar (in the parse worker, which
 // inherits this process's flags) is compiled. See ../extraction/wasm-runtime-flags.
 (0, wasm_runtime_flags_1.relaunchWithWasmRuntimeFlagsIfNeeded)(__filename);
+// Last-resort fatal handlers: log a bounded line and exit non-zero. A fault
+// that reaches here escaped every boundary, so the process is in an undefined
+// state — keeping it alive is what let the detached MCP daemon orphan and pin a
+// CPU core with no recovery (#799, #850). Installed before the command branch
+// so it also covers a synchronous throw during startup. See ./fatal-handler.
+(0, fatal_handler_1.installFatalHandlers)();
 // Check if running with no arguments - run installer
 if (process.argv.length === 2) {
     Promise.resolve().then(() => __importStar(require('../installer'))).then(({ runInstaller }) => runInstaller()).catch((err) => {
@@ -128,16 +136,21 @@ else {
     // Normal CLI flow
     main();
 }
-process.on('uncaughtException', (error) => {
-    console.error('[CodeGraph] Uncaught exception:', error);
-});
-process.on('unhandledRejection', (reason) => {
-    console.error('[CodeGraph] Unhandled rejection:', reason);
-});
 function main() {
     const program = new commander_1.Command();
     // Version from package.json
     const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8'));
+    // Make the version trivial to reach. commander's `.version()` (below) wires up
+    // `--version` and `-V`; intercept the spellings it can't — lowercase `-v` and
+    // single-dash `-version` — before any parsing. (commander's version short flag
+    // is the capital `-V`, and its parser rejects a multi-character single-dash
+    // flag.) The bare `homegraph version` subcommand is registered further down so
+    // the affordance also shows up in `homegraph --help`.
+    const firstArg = process.argv[2];
+    if (firstArg === '-v' || firstArg === '-version') {
+        console.log(packageJson.version);
+        return;
+    }
     // =============================================================================
     // ANSI Color Helpers (avoid chalk ESM issues)
     // =============================================================================
@@ -168,12 +181,36 @@ function main() {
         .name('homegraph')
         .description('Code intelligence and knowledge graph for any codebase')
         .version(packageJson.version);
+    // Anonymous usage telemetry (see TELEMETRY.md): record the invoked subcommand
+    // NAME only — never arguments or paths. Counts buffer locally; network sends
+    // piggyback on commands that run long anyway (quick commands only append to
+    // the local buffer at exit, costing nothing).
+    // install/uninstall are absent on purpose: the installer flushes at its own
+    // end, AFTER its consent prompt — a flush here would fire the first-run
+    // notice before the user ever sees the toggle.
+    const TELEMETRY_FLUSH_COMMANDS = new Set(['init', 'uninit', 'index', 'sync', 'upgrade']);
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        try {
+            // The detached daemon re-invokes `serve --mcp` internally — not a user action.
+            if (process.env.HOMEGRAPH_DAEMON_INTERNAL)
+                return;
+            const name = actionCommand.name();
+            if (name === 'telemetry')
+                return; // managing telemetry is not usage
+            (0, telemetry_1.getTelemetry)().recordUsage('cli_command', name, true);
+            if (TELEMETRY_FLUSH_COMMANDS.has(name))
+                (0, telemetry_1.getTelemetry)().maybeFlush();
+        }
+        catch {
+            /* telemetry must never break the CLI */
+        }
+    });
     // =============================================================================
     // Helper Functions
     // =============================================================================
     /**
      * Resolve project path from argument or current directory
-     * Walks up parent directories to find nearest initialized CodeGraph project
+     * Walks up parent directories to find nearest initialized HomeGraph project
      * (must have .homegraph/homegraph.db, not just .homegraph/lessons.db)
      */
     function resolveProjectPath(pathArg) {
@@ -182,8 +219,8 @@ function main() {
         if ((0, directory_1.isInitialized)(absolutePath)) {
             return absolutePath;
         }
-        // Walk up to find nearest parent with CodeGraph initialized
-        // Note: findNearestCodeGraphRoot finds any .homegraph folder, but we need one with homegraph.db
+        // Walk up to find nearest parent with HomeGraph initialized
+        // Note: findNearestHomeGraphRoot finds any .homegraph folder, but we need one with homegraph.db
         let current = absolutePath;
         const root = path.parse(current).root;
         while (current !== root) {
@@ -341,7 +378,7 @@ function main() {
             }
         }
         else if (projectPath) {
-            const logPath = path.join(projectPath, '.homegraph', 'errors.log');
+            const logPath = path.join((0, directory_1.getHomeGraphDir)(projectPath), 'errors.log');
             if (fs.existsSync(logPath)) {
                 fs.unlinkSync(logPath);
             }
@@ -351,7 +388,7 @@ function main() {
      * Write detailed error log to .homegraph/errors.log
      */
     function writeErrorLog(projectPath, errors) {
-        const cgDir = path.join(projectPath, '.homegraph');
+        const cgDir = (0, directory_1.getHomeGraphDir)(projectPath);
         if (!fs.existsSync(cgDir))
             return;
         const logPath = path.join(cgDir, 'errors.log');
@@ -374,7 +411,7 @@ function main() {
             }
         }
         const lines = [
-            `CodeGraph Error Log - ${new Date().toISOString()}`,
+            `HomeGraph Error Log - ${new Date().toISOString()}`,
             `${errorsByFile.size} files with errors`,
             '',
         ];
@@ -388,22 +425,43 @@ function main() {
         }
         fs.writeFileSync(logPath, lines.join('\n') + '\n');
     }
+    /**
+     * Telemetry for a completed full index (see TELEMETRY.md). The bounded flush
+     * keeps init/index responsive (these commands just ran for seconds anyway)
+     * while delivering the event promptly.
+     */
+    async function recordIndexTelemetry(cg, result) {
+        (0, telemetry_1.recordIndexEvent)(cg, result);
+        await (0, telemetry_1.getTelemetry)().flushNow();
+    }
     // =============================================================================
     // Commands
     // =============================================================================
     /**
-     * codegraph init [path]
+     * homegraph init [path]
      */
     program
         .command('init [path]')
-        .description('Initialize CodeGraph in a project directory and build the initial index')
+        .description('Initialize HomeGraph in a project directory and build the initial index')
         .option('-i, --index', 'Deprecated: indexing now runs by default; flag accepted for backward compatibility')
+        .option('-f, --force', 'Initialize even if the path looks like your home directory or a filesystem root')
         .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
         .action(async (pathArg, options) => {
         const projectPath = path.resolve(pathArg || process.cwd());
         const clack = await importESM('@clack/prompts');
-        clack.intro('Initializing CodeGraph');
+        clack.intro('Initializing HomeGraph');
         try {
+            // Refuse to index your home directory / a filesystem root — it pulls in
+            // caches, other projects, and your whole tree (a multi-GB index + watcher
+            // churn, and on pre-1.0 macOS a machine-crashing fd blowup, #845).
+            const unsafe = (0, directory_1.unsafeIndexRootReason)(projectPath);
+            if (unsafe && !options.force) {
+                clack.log.error(`Refusing to initialize in ${projectPath} — it looks like ${unsafe}.`);
+                clack.log.info('Run this inside a specific project directory, or pass --force if you really mean to index everything under it.');
+                clack.outro('');
+                process.exitCode = 1;
+                return;
+            }
             if ((0, directory_1.isInitialized)(projectPath)) {
                 clack.log.warn(`Already initialized in ${projectPath}`);
                 clack.log.info('Use "homegraph index" to re-index or "homegraph sync" to update');
@@ -415,8 +473,8 @@ function main() {
                 clack.outro('');
                 return;
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.init(projectPath, { index: false });
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.init(projectPath, { index: false });
             clack.log.success(`Initialized in ${projectPath}`);
             // Indexing runs by default now. The legacy -i/--index flag is still
             // accepted (so existing muscle memory and scripts don't break) but is a
@@ -437,6 +495,7 @@ function main() {
                 await progress.stop();
             }
             printIndexResult(clack, result, projectPath);
+            await recordIndexTelemetry(cg, result);
             try {
                 const { offerWatchFallback } = await Promise.resolve().then(() => __importStar(require('../installer')));
                 await offerWatchFallback(clack, projectPath);
@@ -451,17 +510,17 @@ function main() {
         }
     });
     /**
-     * codegraph uninit [path]
+     * homegraph uninit [path]
      */
     program
         .command('uninit [path]')
-        .description('Remove CodeGraph from a project (deletes .homegraph/ directory)')
+        .description('Remove HomeGraph from a project (deletes .homegraph/ directory)')
         .option('-f, --force', 'Skip confirmation prompt')
         .action(async (pathArg, options) => {
         const projectPath = resolveProjectPath(pathArg);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                warn(`CodeGraph is not initialized in ${projectPath}`);
+                warn(`HomeGraph is not initialized in ${projectPath}`);
                 return;
             }
             if (!options.force) {
@@ -469,7 +528,7 @@ function main() {
                 const readline = await Promise.resolve().then(() => __importStar(require('readline')));
                 const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
                 const answer = await new Promise((resolve) => {
-                    rl.question(chalk.yellow(`${(0, glyphs_1.getGlyphs)().warn} This will permanently delete all CodeGraph data. Continue? (y/N) `), resolve);
+                    rl.question(chalk.yellow(`${(0, glyphs_1.getGlyphs)().warn} This will permanently delete all HomeGraph data. Continue? (y/N) `), resolve);
                 });
                 rl.close();
                 if (answer.toLowerCase() !== 'y') {
@@ -477,8 +536,8 @@ function main() {
                     return;
                 }
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = CodeGraph.openSync(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = HomeGraph.openSync(projectPath);
             cg.uninitialize();
             // Clean up any git sync hooks we installed (no-op if none / not a repo).
             try {
@@ -489,7 +548,14 @@ function main() {
                 }
             }
             catch { /* non-fatal */ }
-            success(`Removed CodeGraph from ${projectPath}`);
+            success(`Removed HomeGraph from ${projectPath}`);
+            // Churn signal — and flush now, since after an uninit there may be no
+            // "next run" to deliver it.
+            try {
+                (0, telemetry_1.getTelemetry)().recordLifecycle('uninstall', {});
+                await (0, telemetry_1.getTelemetry)().flushNow();
+            }
+            catch { /* non-fatal */ }
         }
         catch (err) {
             error(`Failed to uninitialize: ${err instanceof Error ? err.message : String(err)}`);
@@ -497,28 +563,35 @@ function main() {
         }
     });
     /**
-     * codegraph index [path]
+     * homegraph index [path]
      */
     program
         .command('index [path]')
-        .description('Index all files in the project')
-        .option('-f, --force', 'Force full re-index even if already indexed')
+        .description('Rebuild the full index from scratch (same result as a fresh init)')
+        .option('-f, --force', 'Index even if the path looks like your home directory or a filesystem root')
         .option('-q, --quiet', 'Suppress progress output')
         .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
         .action(async (pathArg, options) => {
         const projectPath = resolveProjectPath(pathArg);
         try {
+            // Don't (re)index your home directory / a filesystem root (#845). --force
+            // doubles as the override.
+            const unsafe = (0, directory_1.unsafeIndexRootReason)(projectPath);
+            if (unsafe && !options.force) {
+                error(`Refusing to index ${projectPath} — it looks like ${unsafe}. Pass --force to override.`);
+                process.exit(1);
+            }
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`CodeGraph not initialized in ${projectPath}`);
+                error(`HomeGraph not initialized in ${projectPath}`);
                 info('Run "homegraph init" first');
                 process.exit(1);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             if (options.quiet) {
-                // Quiet mode: no UI, just run
-                if (options.force)
-                    cg.clear();
+                // Quiet mode: no UI, just run. `index` is a full re-index, so clear the
+                // existing graph and rebuild from scratch (see the note below — #874).
+                cg.clear();
                 const result = await cg.indexAll();
                 if (!result.success)
                     process.exit(1);
@@ -527,10 +600,12 @@ function main() {
             }
             const clack = await importESM('@clack/prompts');
             clack.intro('Indexing project');
-            if (options.force) {
-                cg.clear();
-                clack.log.info('Cleared existing index');
-            }
+            // `index` is a FULL re-index: clear the existing graph and rebuild it from
+            // scratch so the result is identical to a fresh `init`. Without the clear,
+            // indexAll() skips every unchanged file by its content hash and reports
+            // "0 nodes, 0 edges" against the already-populated graph — which reads as
+            // "index wiped my index" (#874). For fast incremental updates use `sync`.
+            cg.clear();
             let result;
             if (options.verbose) {
                 result = await cg.indexAll({
@@ -547,6 +622,7 @@ function main() {
                 await progress.stop();
             }
             printIndexResult(clack, result, projectPath);
+            await recordIndexTelemetry(cg, result);
             if (!result.success) {
                 process.exit(1);
             }
@@ -559,7 +635,7 @@ function main() {
         }
     });
     /**
-     * codegraph sync [path]
+     * homegraph sync [path]
      */
     program
         .command('sync [path]')
@@ -570,19 +646,19 @@ function main() {
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
                 if (!options.quiet) {
-                    error(`CodeGraph not initialized in ${projectPath}`);
+                    error(`HomeGraph not initialized in ${projectPath}`);
                 }
                 process.exit(1);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             if (options.quiet) {
                 await cg.sync();
                 cg.destroy();
                 return;
             }
             const clack = await importESM('@clack/prompts');
-            clack.intro('Syncing CodeGraph');
+            clack.intro('Syncing HomeGraph');
             process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
             const progress = (0, shimmer_progress_1.createShimmerProgress)();
             const result = await cg.sync({
@@ -615,7 +691,7 @@ function main() {
         }
     });
     /**
-     * codegraph status [path]
+     * homegraph status [path]
      */
     program
         .command('status [path]')
@@ -635,19 +711,19 @@ function main() {
                         initialized: false,
                         version: packageJson.version,
                         projectPath,
-                        indexPath: (0, directory_1.getCodeGraphDir)(projectPath),
+                        indexPath: (0, directory_1.getHomeGraphDir)(projectPath),
                         lastIndexed: null,
                     }));
                     return;
                 }
-                console.log(chalk.bold('\nCodeGraph Status\n'));
+                console.log(chalk.bold('\nHomeGraph Status\n'));
                 info(`Project: ${projectPath}`);
                 warn('Not initialized');
                 info('Run "homegraph init" to initialize');
                 return;
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             const stats = cg.getStats();
             const changes = cg.getChangedFiles();
             const backend = cg.getBackend();
@@ -661,7 +737,7 @@ function main() {
                     initialized: true,
                     version: packageJson.version,
                     projectPath,
-                    indexPath: (0, directory_1.getCodeGraphDir)(projectPath),
+                    indexPath: (0, directory_1.getHomeGraphDir)(projectPath),
                     lastIndexed: lastIndexedMs != null ? new Date(lastIndexedMs).toISOString() : null,
                     fileCount: stats.fileCount,
                     nodeCount: stats.nodeCount,
@@ -689,7 +765,7 @@ function main() {
                 cg.destroy();
                 return;
             }
-            console.log(chalk.bold('\nCodeGraph Status\n'));
+            console.log(chalk.bold('\nHomeGraph Status\n'));
             // Project info
             console.log(chalk.cyan('Project:'), projectPath);
             if (worktreeMismatch) {
@@ -757,7 +833,7 @@ function main() {
             if (reindexRecommended) {
                 const builtWith = buildInfo.version ? `v${buildInfo.version.replace(/^v/, '')}` : 'an earlier version';
                 warn(`Index was built by ${builtWith}; re-index to pick up this engine's improvements.`);
-                info('Run "homegraph index -f" (full rebuild) or "homegraph sync"');
+                info('Run "homegraph index" (full rebuild) or "homegraph sync"');
                 console.log();
             }
             cg.destroy();
@@ -768,7 +844,7 @@ function main() {
         }
     });
     /**
-     * codegraph query <search>
+     * homegraph query <search>
      */
     program
         .command('query <search>')
@@ -781,11 +857,11 @@ function main() {
         const projectPath = resolveProjectPath(options.path);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`CodeGraph not initialized in ${projectPath}`);
+                error(`HomeGraph not initialized in ${projectPath}`);
                 process.exit(1);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             const limit = parseInt(options.limit || '10', 10);
             const rawResults = cg.searchNodes(search, {
                 limit,
@@ -832,7 +908,205 @@ function main() {
         }
     });
     /**
-     * codegraph files [path]
+     * homegraph explore <query...>
+     *
+     * The CLI face of the MCP homegraph_explore tool — same handler, same
+     * output (source of the relevant symbols grouped by file + the call path
+     * among them). Exists so agents WITHOUT the MCP tools — Task-tool
+     * subagents (which don't inherit MCP tools, #704) and non-MCP harnesses —
+     * can reach the graph through a plain shell command.
+     */
+    program
+        .command('explore <query...>')
+        .description('Explore an area: relevant symbols\' source + call paths in one shot (same output as the homegraph_explore MCP tool)')
+        .option('-p, --path <path>', 'Project path')
+        .option('--max-files <number>', 'Maximum number of files to include source from')
+        .action(async (queryParts, options) => {
+        const projectPath = resolveProjectPath(options.path);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`HomeGraph isn't available here — no .homegraph/ index exists in ${projectPath}. If you are an AI agent: continue with your usual tools; indexing is the user's decision, do not run it yourself. (The project owner can enable HomeGraph with 'homegraph init'.)`);
+                process.exit(1);
+            }
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
+            const { ToolHandler } = await Promise.resolve().then(() => __importStar(require('../mcp/tools')));
+            const handler = new ToolHandler(cg);
+            const args = { query: queryParts.join(' ') };
+            if (options.maxFiles)
+                args.maxFiles = parseInt(options.maxFiles, 10);
+            const result = await handler.execute('homegraph_explore', args);
+            console.log(result.content[0]?.text ?? '');
+            cg.destroy();
+            if (result.isError)
+                process.exit(1);
+        }
+        catch (err) {
+            error(`Explore failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * homegraph prompt-hook  (hidden)
+     *
+     * A Claude Code `UserPromptSubmit` hook entry point. Reads `{prompt, cwd}` JSON
+     * on stdin; for a structural/flow/impact prompt it runs `homegraph_explore` on
+     * the indexed project and prints the result to stdout, which Claude injects into
+     * the agent's context — so the agent's reflex grep/read has nothing left to find
+     * and reliably uses HomeGraph (the adoption problem). Installed by the installer
+     * into Claude's settings.json (opt-in, default-yes).
+     *
+     * LOAD-BEARING: this must NEVER break the user's prompt. Every failure path —
+     * kill-switch, non-structural prompt, no index, engine error — exits 0 with no
+     * output. The only effect is additive context when it can confidently provide it.
+     */
+    program
+        .command('prompt-hook', { hidden: true })
+        .description('Claude UserPromptSubmit hook: inject HomeGraph context for structural prompts (reads {prompt,cwd} JSON on stdin)')
+        .action(async () => {
+        try {
+            // Kill-switch: lets a user disable the nudge without uninstalling /
+            // editing settings.json (CI, low-power machines, personal preference).
+            if (process.env.HOMEGRAPH_NO_PROMPT_HOOK === '1' || process.env.HOMEGRAPH_PROMPT_HOOK === '0')
+                return;
+            if (process.stdin.isTTY)
+                return; // invoked by hand, no piped payload
+            const raw = await new Promise((resolve) => {
+                let data = '';
+                process.stdin.setEncoding('utf8');
+                process.stdin.on('data', (c) => { data += c; });
+                process.stdin.on('end', () => resolve(data));
+                process.stdin.on('error', () => resolve(data));
+            });
+            let input = {};
+            try {
+                input = JSON.parse(raw);
+            }
+            catch {
+                return;
+            }
+            const prompt = String(input.prompt || '');
+            // Gate: only structural / flow / impact / where-how prompts get context.
+            // A cheap regex keeps every other prompt ("fix this typo") a zero-cost
+            // no-op so we never add latency where there's no structural answer to give.
+            const STRUCTURAL = /\b(how|where|trace|flow|path|reach(?:es|ed)?|call(?:s|ed|er|ers|ee)?|depend|impact|affect|wired?|connect|implement|architect|structure|breaks?|what calls|why does)\b/i;
+            if (!prompt || !STRUCTURAL.test(prompt))
+                return;
+            // Decide what to inject, shaped by WHERE the index(es) are: the nearest
+            // indexed ancestor of cwd, or — when cwd is an un-indexed workspace root
+            // whose indexed project(s) live in sub-dirs (the monorepo case, #964) —
+            // the sub-project the prompt points at, plus a `projectPath` nudge for any
+            // others. Without the down-scan the hook injected nothing at a monorepo
+            // root (it only walked up), so the validated adoption lever never fired
+            // exactly where the agent most needs it.
+            const plan = (0, directory_1.planFrontload)(String(input.cwd || process.cwd()), prompt);
+            if (!plan.exploreRoot && plan.nudgeProjects.length === 0)
+                return; // nothing reachable — the agent's normal tools apply
+            // A "pass projectPath" line for indexed sub-projects we did NOT front-load.
+            // Follow-up homegraph_explore calls against a sub-project (cwd isn't its
+            // index root) need an explicit projectPath, so spell it out.
+            const nudge = (projects, lead) => `${lead}\n${projects.map((p) => `  - projectPath: "${p}"`).join('\n')}\n`;
+            if (plan.exploreRoot) {
+                const { default: HomeGraph } = await loadHomeGraph();
+                const cg = await HomeGraph.open(plan.exploreRoot);
+                try {
+                    const { ToolHandler } = await Promise.resolve().then(() => __importStar(require('../mcp/tools')));
+                    const handler = new ToolHandler(cg);
+                    const result = await handler.execute('homegraph_explore', { query: prompt });
+                    const text = result.content[0]?.text ?? '';
+                    if (!result.isError && text.trim()) {
+                        // Cap the injection so a large-repo explore can't flood the prompt.
+                        const MAX = 16000;
+                        const body = text.length > MAX ? `${text.slice(0, MAX)}\n…(truncated; call homegraph_explore for the rest)` : text;
+                        // For a front-loaded SUB-project, a follow-up explore needs its path.
+                        const more = plan.viaSubScan
+                            ? `call homegraph_explore with projectPath: "${plan.exploreRoot}" for more`
+                            : 'call homegraph_explore for more';
+                        const others = plan.nudgeProjects.length
+                            ? `\n${nudge(plan.nudgeProjects, 'Other indexed projects in this workspace — pass projectPath to query them:')}`
+                            : '';
+                        process.stdout.write(`<homegraph_context note="Structural context from HomeGraph for this prompt — treat returned source as already read; ${more}.">\n${body}${others}\n</homegraph_context>\n`);
+                    }
+                }
+                finally {
+                    cg.destroy();
+                }
+            }
+            else {
+                // Several indexed sub-projects, none a clear match — don't guess; tell
+                // the agent they exist and how to query one.
+                process.stdout.write(`<homegraph_context note="HomeGraph is available for this workspace's indexed sub-projects — query one by passing projectPath to homegraph_explore.">\n` +
+                    nudge(plan.nudgeProjects, "This workspace's HomeGraph indexes live in sub-projects. To use HomeGraph, call homegraph_explore with the projectPath of the relevant one:") +
+                    `</homegraph_context>\n`);
+            }
+        }
+        catch {
+            // Degradable by contract: never surface an error to the prompt pipeline.
+        }
+    });
+    /**
+     * homegraph node <name>
+     *
+     * The CLI face of the MCP homegraph_node tool: one symbol's source +
+     * caller/callee trail, or a whole file with line numbers + dependents
+     * (Read-parity). Same subagent/non-MCP rationale as `explore`.
+     */
+    program
+        .command('node <name>')
+        .description('One symbol\'s source + caller/callee trail, or read a file with line numbers + dependents (same output as the homegraph_node MCP tool)')
+        .option('-p, --path <path>', 'Project path')
+        .option('-f, --file <file>', 'Treat as file mode (or disambiguate a symbol to this file)')
+        .option('--offset <number>', 'File mode: 1-based start line')
+        .option('--limit <number>', 'File mode: maximum lines')
+        .option('--symbols-only', 'File mode: just the symbol map + dependents')
+        .action(async (name, options) => {
+        const projectPath = resolveProjectPath(options.path);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`HomeGraph isn't available here — no .homegraph/ index exists in ${projectPath}. If you are an AI agent: continue with your usual tools; indexing is the user's decision, do not run it yourself. (The project owner can enable HomeGraph with 'homegraph init'.)`);
+                process.exit(1);
+            }
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
+            const { ToolHandler } = await Promise.resolve().then(() => __importStar(require('../mcp/tools')));
+            const handler = new ToolHandler(cg);
+            // A name with a path separator is a file read; otherwise a symbol
+            // (use --file for basename-only file reads or to pin an overload).
+            // Both separators: Windows users type src\auth\session.ts. Symbols
+            // never contain either ('/' isn't an identifier char anywhere we
+            // index; C++ scope is '::', JS members '.').
+            const args = {};
+            if (options.file) {
+                args.file = options.file;
+                if (name && name !== options.file)
+                    args.symbol = name;
+            }
+            else if (name.includes('/') || name.includes('\\')) {
+                args.file = name.replace(/\\/g, '/');
+            }
+            else {
+                args.symbol = name;
+                args.includeCode = true;
+            }
+            if (options.offset)
+                args.offset = parseInt(options.offset, 10);
+            if (options.limit)
+                args.limit = parseInt(options.limit, 10);
+            if (options.symbolsOnly)
+                args.symbolsOnly = true;
+            const result = await handler.execute('homegraph_node', args);
+            console.log(result.content[0]?.text ?? '');
+            cg.destroy();
+            if (result.isError)
+                process.exit(1);
+        }
+        catch (err) {
+            error(`Node lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * homegraph files [path]
      */
     program
         .command('files')
@@ -848,11 +1122,11 @@ function main() {
         const projectPath = resolveProjectPath(options.path);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`CodeGraph not initialized in ${projectPath}`);
+                error(`HomeGraph not initialized in ${projectPath}`);
                 process.exit(1);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             let files = cg.getFiles();
             if (files.length === 0) {
                 info('No files indexed. Run "homegraph index" first.');
@@ -938,6 +1212,24 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * Normalize a user-supplied file path to the project-relative, forward-slash
+     * form HomeGraph stores in the index. Accepts an absolute path, a `./`-prefixed
+     * path, or Windows back-slashes; an empty string when the input is blank. Used
+     * by `homegraph affected` so `./src/x.ts`, `/abs/repo/src/x.ts`, and
+     * `src/x.ts` all match the same indexed file. (#825)
+     */
+    function normalizeIndexPath(filePath, projectPath) {
+        let f = filePath.trim();
+        if (!f)
+            return '';
+        if (path.isAbsolute(f))
+            f = path.relative(projectPath, f);
+        // Collapse `.`/`..` segments, then force forward slashes and drop a leading
+        // `./` (path.normalize already strips it on POSIX; explicit for Windows).
+        f = path.normalize(f).replace(/\\/g, '/').replace(/^\.\//, '');
+        return f;
+    }
     /**
      * Convert glob pattern to regex
      */
@@ -1001,11 +1293,66 @@ function main() {
         renderNode(root, '', true, 0);
     }
     /**
-     * codegraph serve
+     * homegraph daemon — interactive manager for the background daemons. Arrow keys
+     * to pick one (the current project's daemon floats to the top, auto-selected),
+     * enter to stop it. Falls back to a plain list when output isn't a TTY.
+     */
+    program
+        .command('daemon')
+        .aliases(['daemons'])
+        .description('Manage running HomeGraph background daemons — pick one and press enter to stop it')
+        .action(async () => {
+        const { listDaemons, stopDaemonAt, stopAllDaemons } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-registry')));
+        const { runDaemonPicker } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-manager')));
+        const daemons = listDaemons();
+        if (daemons.length === 0) {
+            info('No HomeGraph daemons running.');
+            return;
+        }
+        // No TTY (piped / CI / non-interactive) — can't do arrow-key selection, so
+        // just print what's running instead of crashing on a prompt with no input.
+        if (!process.stdout.isTTY || !process.stdin.isTTY) {
+            for (const d of daemons) {
+                console.log(`pid ${d.pid}  v${d.version}  up ${formatDuration(Date.now() - d.startedAt)}  ${d.root}`);
+            }
+            return;
+        }
+        // The current project's daemon floats to the top and is pre-selected.
+        let cwdRoot = null;
+        const found = (0, directory_1.findNearestHomeGraphRoot)(process.cwd());
+        if (found) {
+            try {
+                cwdRoot = fs.realpathSync(found);
+            }
+            catch {
+                cwdRoot = found;
+            }
+        }
+        const clack = await importESM('@clack/prompts');
+        clack.intro('HomeGraph daemons');
+        await runDaemonPicker({
+            list: listDaemons,
+            stop: stopDaemonAt,
+            stopAll: stopAllDaemons,
+            cwdRoot,
+            now: () => Date.now(),
+            select: (opts) => clack.select(opts),
+            isCancel: (v) => clack.isCancel(v),
+            note: (m) => clack.log.success(m),
+            done: (m) => clack.outro(m),
+        });
+    });
+    /**
+     * homegraph serve
      */
     program
-        .command('serve')
-        .description('Start CodeGraph as an MCP server for AI assistants')
+        // Hidden from `--help`: this is the stdio entry point an AI agent launches
+        // for itself (the installer wires `args: ['serve','--mcp']` into every
+        // agent's MCP config), not a command a human runs. It still works when
+        // invoked — hiding only removes it from the listing. See the interactive-TTY
+        // guard below, which explains this to anyone who runs it by hand.
+        .command('serve', { hidden: true })
+        .description('Start HomeGraph as an MCP server for AI assistants')
         .option('-p, --path <path>', 'Project path (optional for MCP mode, uses rootUri from client)')
         .option('--mcp', 'Run as MCP server (stdio transport)')
         .option('--no-watch', 'Disable the file watcher (no auto-sync; useful on slow filesystems like WSL2 /mnt drives)')
@@ -1018,6 +1365,22 @@ function main() {
         }
         try {
             if (options.mcp) {
+                // `serve --mcp` is the stdio MCP server an AI agent launches for itself,
+                // not a command to run by hand. A human in a terminal would otherwise
+                // see it hang waiting for JSON-RPC on stdin, which reads as broken. If
+                // stdin is an interactive TTY, explain instead of hanging. The agent's
+                // pipe and the detached daemon both have a non-TTY stdin, so this only
+                // ever fires for a person who typed it.
+                if (process.stdin.isTTY && !process.env.HOMEGRAPH_DAEMON_INTERNAL) {
+                    console.error(chalk.bold('\nHomeGraph MCP server\n'));
+                    console.error("This is the MCP server your AI agent (Claude Code, Cursor, Codex, opencode, …)");
+                    console.error("starts automatically — you don't run it yourself.");
+                    console.error(`\nIt's already wired up by ${chalk.cyan('homegraph install')}. To check on things:`);
+                    console.error(`  ${chalk.cyan('homegraph status')}   ${chalk.dim('— is this project indexed and healthy?')}`);
+                    console.error(`  ${chalk.cyan('homegraph daemon')}   ${chalk.dim('— list or stop background MCP servers')}`);
+                    console.error(chalk.dim('\n(Running it directly only does something when an MCP client drives it over stdin.)'));
+                    return;
+                }
                 // Start MCP server - it handles initialization lazily based on rootUri from client
                 const { MCPServer } = await Promise.resolve().then(() => __importStar(require('../mcp/index')));
                 const server = new MCPServer(projectPath);
@@ -1027,18 +1390,18 @@ function main() {
             else {
                 // Default: show info about MCP mode.
                 // Use stderr so stdout stays clean for any piped/stdio usage.
-                console.error(chalk.bold('\nCodeGraph MCP Server\n'));
+                console.error(chalk.bold('\nHomeGraph MCP Server\n'));
                 console.error(chalk.blue((0, glyphs_1.getGlyphs)().info) + ' Use --mcp flag to start the MCP server');
                 console.error('\nTo use with Claude Code, add to your MCP configuration:');
-                console.error(chalk.dim(`
-{
-  "mcpServers": {
-    "homegraph": {
-      "command": "homegraph",
-      "args": ["serve", "--mcp"]
-    }
-  }
-}
+                console.error(chalk.dim(`
+{
+  "mcpServers": {
+    "homegraph": {
+      "command": "homegraph",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}
 `));
                 console.error('Available tools:');
                 console.error(chalk.cyan('  homegraph_explore') + '   - Primary: source of the relevant symbols for any question');
@@ -1057,7 +1420,7 @@ function main() {
         }
     });
     /**
-     * codegraph unlock [path]
+     * homegraph unlock [path]
      */
     program
         .command('unlock [path]')
@@ -1066,10 +1429,10 @@ function main() {
         const projectPath = resolveProjectPath(pathArg);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`CodeGraph not initialized in ${projectPath}`);
+                error(`HomeGraph not initialized in ${projectPath}`);
                 return;
             }
-            const lockPath = path.join((0, directory_1.getCodeGraphDir)(projectPath), 'homegraph.lock');
+            const lockPath = path.join((0, directory_1.getHomeGraphDir)(projectPath), 'homegraph.lock');
             if (!fs.existsSync(lockPath)) {
                 info(`No lock file found ${(0, glyphs_1.getGlyphs)().dash} nothing to do`);
                 return;
@@ -1083,7 +1446,7 @@ function main() {
         }
     });
     /**
-     * codegraph callers <symbol>
+     * homegraph callers <symbol>
      *
      * CLI parity with the MCP graph tools (homegraph_callers/callees/impact) so the
      * traversal queries work in scripts, CI, and git hooks without a running MCP
@@ -1099,11 +1462,11 @@ function main() {
         const projectPath = resolveProjectPath(options.path);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`CodeGraph not initialized in ${projectPath}`);
+                error(`HomeGraph not initialized in ${projectPath}`);
                 process.exit(1);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             const limit = parseInt(options.limit || '20', 10);
             const matches = cg.searchNodes(symbol, { limit: 50 });
             if (matches.length === 0) {
@@ -1158,7 +1521,7 @@ function main() {
         }
     });
     /**
-     * codegraph callees <symbol>
+     * homegraph callees <symbol>
      */
     program
         .command('callees <symbol>')
@@ -1170,11 +1533,11 @@ function main() {
         const projectPath = resolveProjectPath(options.path);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`CodeGraph not initialized in ${projectPath}`);
+                error(`HomeGraph not initialized in ${projectPath}`);
                 process.exit(1);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             const limit = parseInt(options.limit || '20', 10);
             const matches = cg.searchNodes(symbol, { limit: 50 });
             if (matches.length === 0) {
@@ -1228,7 +1591,7 @@ function main() {
         }
     });
     /**
-     * codegraph impact <symbol>
+     * homegraph impact <symbol>
      */
     program
         .command('impact <symbol>')
@@ -1240,11 +1603,11 @@ function main() {
         const projectPath = resolveProjectPath(options.path);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`CodeGraph not initialized in ${projectPath}`);
+                error(`HomeGraph not initialized in ${projectPath}`);
                 process.exit(1);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             const depth = Math.min(Math.max(parseInt(options.depth || '2', 10), 1), 10);
             const matches = cg.searchNodes(symbol, { limit: 50 });
             if (matches.length === 0) {
@@ -1318,13 +1681,13 @@ function main() {
         }
     });
     /**
-     * codegraph affected [files...]
+     * homegraph affected [files...]
      *
      * Find test files affected by the given source files.
      * Traces dependency edges transitively to find test files that depend on changed code.
      *
      * Usage:
-     *   git diff --name-only | codegraph affected --stdin
+     *   git diff --name-only | homegraph affected --stdin
      *   homegraph affected src/lib/components/Editor.svelte src/routes/+page.svelte
      */
     program
@@ -1340,7 +1703,7 @@ function main() {
         const projectPath = resolveProjectPath(options.path);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
-                error(`CodeGraph not initialized in ${projectPath}`);
+                error(`HomeGraph not initialized in ${projectPath}`);
                 process.exit(1);
             }
             // Collect changed files from args or stdin
@@ -1350,13 +1713,20 @@ function main() {
                 const stdinFiles = stdinData.split('\n').map(f => f.trim()).filter(Boolean);
                 changedFiles.push(...stdinFiles);
             }
+            // Normalize inputs to the project-relative, forward-slash form the index
+            // stores. Without this, `affected ./src/x.ts`, an absolute path (what a
+            // wrapping script often passes), or a Windows back-slash path silently
+            // matches nothing and reports 0 affected tests. (#825)
+            changedFiles = changedFiles
+                .map((f) => normalizeIndexPath(f, projectPath))
+                .filter(Boolean);
             if (changedFiles.length === 0) {
                 if (!options.quiet)
                     info('No files provided. Use file arguments or --stdin.');
                 process.exit(0);
             }
-            const { default: CodeGraph } = await loadCodeGraph();
-            const cg = await CodeGraph.open(projectPath);
+            const { default: HomeGraph } = await loadHomeGraph();
+            const cg = await HomeGraph.open(projectPath);
             const maxDepth = parseInt(options.depth || '5', 10);
             // Common test file patterns
             const defaultTestPatterns = [
@@ -1448,11 +1818,11 @@ function main() {
         }
     });
     /**
-     * codegraph install
+     * homegraph install
      */
     program
         .command('install')
-        .description('Install codegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent)')
+        .description('Install homegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent)')
         .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "auto"|"all"|"none". Default: prompt')
         .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt')
         .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=auto, auto-allow on')
@@ -1502,16 +1872,16 @@ function main() {
         }
     });
     /**
-     * codegraph uninstall
+     * homegraph uninstall
      *
-     * Inverse of `install`. Removes the codegraph MCP server entry,
+     * Inverse of `install`. Removes the homegraph MCP server entry,
      * instructions block, and permissions from every agent (or a
      * `--target` subset). Prompts global-vs-local when not given. Does NOT
      * delete the `.homegraph/` index — that's `homegraph uninit`.
      */
     program
         .command('uninstall')
-        .description('Remove codegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent)')
+        .description('Remove homegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent)')
         .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "all". Default: all')
         .option('-l, --location <where>', 'Uninstall location: "global" or "local". Default: prompt')
         .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=all')
@@ -1534,15 +1904,54 @@ function main() {
         }
     });
     /**
-     * codegraph upgrade [version]
+     * homegraph telemetry [on|off|status]
+     */
+    program
+        .command('telemetry [action]')
+        .description('Show or change anonymous usage telemetry (status, on, off)')
+        .action((action) => {
+        const t = (0, telemetry_1.getTelemetry)();
+        if (action === 'on' || action === 'off') {
+            t.setEnabled(action === 'on', 'cli');
+            if (action === 'on') {
+                success('Telemetry enabled — anonymous usage stats only (no code, paths, or names).');
+            }
+            else {
+                success('Telemetry disabled. Buffered, unsent data was deleted.');
+            }
+            const effective = t.getStatus();
+            if (effective.decidedBy === 'DO_NOT_TRACK' || effective.decidedBy === 'HOMEGRAPH_TELEMETRY') {
+                warn(`The ${effective.decidedBy} environment variable overrides this choice — ` +
+                    `effective state right now: ${effective.enabled ? 'enabled' : 'disabled'}.`);
+            }
+            return;
+        }
+        if (action !== undefined && action !== 'status') {
+            error(`Unknown action: ${action} (expected status, on, or off)`);
+            process.exit(1);
+        }
+        const s = t.getStatus();
+        const decidedBy = {
+            DO_NOT_TRACK: 'DO_NOT_TRACK environment variable',
+            HOMEGRAPH_TELEMETRY: 'HOMEGRAPH_TELEMETRY environment variable',
+            config: 'your saved choice',
+            default: 'default',
+        };
+        console.log(`\nTelemetry: ${s.enabled ? chalk.green('enabled') : chalk.yellow('disabled')} ${chalk.dim(`(${decidedBy[s.decidedBy]})`)}`);
+        console.log(`Machine ID: ${s.machineId ?? chalk.dim('(random UUID, created on first use)')}`);
+        console.log(`Config:     ${s.configPath}`);
+        console.log(chalk.dim(`\nExactly what is collected (and never collected): ${telemetry_1.TELEMETRY_DOCS}\n`));
+    });
+    /**
+     * homegraph upgrade [version]
      *
-     * Self-update, however CodeGraph was installed (bundle via install.sh/.ps1,
+     * Self-update, however HomeGraph was installed (bundle via install.sh/.ps1,
      * npm-global, npx, or a source checkout). See ../upgrade for the detection and
      * per-method upgrade logic.
      */
     program
         .command('upgrade [version]')
-        .description('Update CodeGraph to the latest release (or a specific version)')
+        .description('Update HomeGraph to the latest release (or a specific version)')
         .option('--check', 'Check whether an update is available without installing')
         .option('-f, --force', 'Reinstall even if already on the target version')
         .action(async (versionArg, options) => {
@@ -1566,6 +1975,20 @@ function main() {
         });
         process.exit(code);
     });
+    /**
+     * homegraph version
+     *
+     * The bare-noun form of `--version`. commander already provides `--version`
+     * and `-V`, and the `-v` / `-version` spellings are intercepted before parse
+     * (see top of main). This subcommand makes `homegraph version` work and lists
+     * the version affordance in `homegraph --help`.
+     */
+    program
+        .command('version')
+        .description('Print the installed HomeGraph version (also: -v, --version)')
+        .action(() => {
+        console.log(packageJson.version);
+    });
     // Parse and run
     program.parse();
 } // end main()