@agentllm/codegraph-arkts 0.7.12 → 0.9.4-arkts.0

package/dist/installer/index.d.ts

@@ -2,7 +2,8 @@
  * CodeGraph Interactive Installer
  *
  * Multi-target: writes MCP server config + instructions for the
- * agents the user picks (Claude Code, Cursor, Codex CLI, opencode).
+ * agents the user picks (Claude Code, Cursor, Codex CLI, opencode,
+ * Hermes Agent).
  * Defaults to the Claude-only behavior for backwards compatibility
  * when no targets are explicitly chosen and nothing else is detected.
  *
@@ -10,7 +11,7 @@
  * is the non-interactive entry point used by the `--target` /
  * `--print-config` CLI flags.
  */
-import type { AgentTarget, Location, WriteResult } from './targets/types';
+import type { AgentTarget, Location, TargetId, WriteResult } from './targets/types';
 export { writeMcpConfig, writePermissions, writeClaudeMd, hasMcpConfig, hasPermissions, hasClaudeMdSection, } from './config-writer';
 export type { InstallLocation } from './config-writer';
 export interface RunInstallerOptions {
@@ -33,6 +34,57 @@ export interface RunInstallerOptions {
  */
 export declare function runInstaller(): Promise<void>;
 export declare function runInstallerWithOptions(opts: RunInstallerOptions): Promise<void>;
+export interface RunUninstallerOptions {
+    /**
+     * Comma-separated target list, or `auto` / `all` / `none`. Defaults
+     * to `all` — uninstall sweeps every known agent and reports which
+     * ones it actually touched, so the user doesn't have to know where
+     * they configured it.
+     */
+    target?: string;
+    /** Skip the location prompt; use this value directly. */
+    location?: Location;
+    /** Non-interactive: location=global, target=all, no prompts. */
+    yes?: boolean;
+}
+export type UninstallStatus = 'removed' | 'not-configured' | 'unsupported';
+/**
+ * Per-target outcome of an uninstall sweep. `removed` means we deleted
+ * at least one thing; `not-configured` means the agent had no codegraph
+ * config at this location (nothing to do); `unsupported` means the
+ * agent has no config concept for this location (e.g. Codex is
+ * global-only, so a `local` uninstall skips it).
+ */
+export interface UninstallReport {
+    id: TargetId;
+    displayName: string;
+    status: UninstallStatus;
+    /** Absolute paths we actually edited/removed (action === 'removed'). */
+    removedPaths: string[];
+    /** Verbatim notes from the target (rare for uninstall). */
+    notes: string[];
+}
+/**
+ * Pure uninstall sweep — no prompts, no I/O beyond the targets' own
+ * file edits. Exposed (and unit-tested) separately from the clack UI in
+ * `runUninstaller` so the aggregation logic can be asserted directly.
+ *
+ * Each target's `uninstall()` is already safe to call when nothing was
+ * installed (it returns `not-found` actions), so this is safe to run
+ * across every target unconditionally.
+ */
+export declare function uninstallTargets(targets: readonly AgentTarget[], location: Location): UninstallReport[];
+/**
+ * Interactive uninstaller — the inverse of `runInstallerWithOptions`.
+ * Asks global-vs-local first (unless `--location`/`--yes` is given),
+ * then sweeps every agent target (or the `--target` subset) and prints
+ * one block per agent so the user sees exactly which providers it hit.
+ *
+ * Removes only what install wrote (MCP server entry, instructions
+ * block, permissions) — never the `.codegraph/` index, which `codegraph
+ * uninit` owns.
+ */
+export declare function runUninstaller(opts: RunUninstallerOptions): Promise<void>;
 /**
  * For every target that has a global config and exposes
  * `wireProjectSurfaces`, write its project-local surfaces (e.g.
@@ -50,4 +102,16 @@ export declare function wireProjectSurfacesForGlobalAgents(): Array<{
     target: AgentTarget;
     file: WriteResult['files'][number];
 }>;
+/**
+ * When the live file watcher will be disabled for this project (e.g. WSL2
+ * /mnt drives, or CODEGRAPH_NO_WATCH), the index would silently go stale.
+ * Explain that, and offer to keep it fresh automatically via git hooks
+ * (commit / pull / checkout) instead of manual `codegraph sync`.
+ *
+ * No-op on environments where the watcher runs normally, so it's safe to
+ * call unconditionally after init.
+ */
+export declare function offerWatchFallback(clack: typeof import('@clack/prompts'), projectPath: string, opts?: {
+    yes?: boolean;
+}): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/installer/index.js

@@ -3,7 +3,8 @@
  * CodeGraph Interactive Installer
  *
  * Multi-target: writes MCP server config + instructions for the
- * agents the user picks (Claude Code, Cursor, Codex CLI, opencode).
+ * agents the user picks (Claude Code, Cursor, Codex CLI, opencode,
+ * Hermes Agent).
  * Defaults to the Claude-only behavior for backwards compatibility
  * when no targets are explicitly chosen and nothing else is detected.
  *
@@ -48,12 +49,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasClaudeMdSection = exports.hasPermissions = exports.hasMcpConfig = exports.writeClaudeMd = exports.writePermissions = exports.writeMcpConfig = void 0;
 exports.runInstaller = runInstaller;
 exports.runInstallerWithOptions = runInstallerWithOptions;
+exports.uninstallTargets = uninstallTargets;
+exports.runUninstaller = runUninstaller;
 exports.wireProjectSurfacesForGlobalAgents = wireProjectSurfacesForGlobalAgents;
+exports.offerWatchFallback = offerWatchFallback;
 const child_process_1 = require("child_process");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const registry_1 = require("./targets/registry");
 const glyphs_1 = require("../ui/glyphs");
+// Import the lightweight submodules directly (not the ../sync barrel, which
+// re-exports FileWatcher and would transitively pull in ../extraction — the
+// installer must stay importable even when native modules can't load).
+const watch_policy_1 = require("../sync/watch-policy");
+const git_hooks_1 = require("../sync/git-hooks");
 // Backwards-compat: keep these named exports — downstream code may
 // import them. The shim in `config-writer.ts` continues to re-export
 // them too.
@@ -119,12 +128,12 @@ async function runInstallerWithOptions(opts) {
             const s = clack.spinner();
             s.start('Installing codegraph CLI...');
             try {
-                (0, child_process_1.execSync)('npm install -g @agentllm/codegraph-arkts', { stdio: 'pipe' });
+                (0, child_process_1.execSync)('npm install -g @colbymchenry/codegraph', { stdio: 'pipe' });
                 s.stop('Installed codegraph CLI on PATH');
             }
             catch {
                 s.stop('Could not install (permission denied)');
-                clack.log.warn('Try: sudo npm install -g @agentllm/codegraph-arkts');
+                clack.log.warn('Try: sudo npm install -g @colbymchenry/codegraph');
             }
         }
         else {
@@ -206,7 +215,7 @@ async function runInstallerWithOptions(opts) {
     }
     // Step 6: for local install, initialize the project.
     if (location === 'local') {
-        await initializeLocalProject(clack);
+        await initializeLocalProject(clack, useDefaults);
     }
     if (location === 'global') {
         clack.note('cd your-project\ncodegraph init -i', 'Quick start');
@@ -216,6 +225,125 @@ async function runInstallerWithOptions(opts) {
         : 'Done!';
     clack.outro(finalNote);
 }
+/**
+ * Pure uninstall sweep — no prompts, no I/O beyond the targets' own
+ * file edits. Exposed (and unit-tested) separately from the clack UI in
+ * `runUninstaller` so the aggregation logic can be asserted directly.
+ *
+ * Each target's `uninstall()` is already safe to call when nothing was
+ * installed (it returns `not-found` actions), so this is safe to run
+ * across every target unconditionally.
+ */
+function uninstallTargets(targets, location) {
+    return targets.map((target) => {
+        if (!target.supportsLocation(location)) {
+            const only = location === 'local' ? 'global' : 'local';
+            return {
+                id: target.id,
+                displayName: target.displayName,
+                status: 'unsupported',
+                removedPaths: [],
+                notes: [`no ${location} config — this agent is ${only}-only`],
+            };
+        }
+        const result = target.uninstall(location);
+        const removedPaths = result.files
+            .filter((f) => f.action === 'removed')
+            .map((f) => f.path);
+        return {
+            id: target.id,
+            displayName: target.displayName,
+            status: removedPaths.length > 0 ? 'removed' : 'not-configured',
+            removedPaths,
+            notes: result.notes ?? [],
+        };
+    });
+}
+/**
+ * Interactive uninstaller — the inverse of `runInstallerWithOptions`.
+ * Asks global-vs-local first (unless `--location`/`--yes` is given),
+ * then sweeps every agent target (or the `--target` subset) and prints
+ * one block per agent so the user sees exactly which providers it hit.
+ *
+ * Removes only what install wrote (MCP server entry, instructions
+ * block, permissions) — never the `.codegraph/` index, which `codegraph
+ * uninit` owns.
+ */
+async function runUninstaller(opts) {
+    const clack = await importESM('@clack/prompts');
+    clack.intro(`CodeGraph v${getVersion()} — uninstall`);
+    const useDefaults = opts.yes === true;
+    // Step 1: which location — asked FIRST, the one decision the user
+    // must make. Global sweeps ~/.claude, ~/.codex, etc.; local sweeps
+    // the configs in this project directory.
+    let location;
+    if (opts.location) {
+        location = opts.location;
+    }
+    else if (useDefaults) {
+        location = 'global';
+    }
+    else {
+        const sel = await clack.select({
+            message: 'Remove CodeGraph from all your projects, or just this one?',
+            options: [
+                { value: 'global', label: 'All projects (global)', hint: '~/.claude, ~/.cursor, ~/.codex, ~/.config/opencode, ~/.hermes' },
+                { value: 'local', label: 'Just this project (local)', hint: './.claude, ./.cursor, ./opencode.jsonc' },
+            ],
+            initialValue: 'global',
+        });
+        if (clack.isCancel(sel)) {
+            clack.cancel('Uninstall cancelled.');
+            process.exit(0);
+        }
+        location = sel;
+    }
+    // Step 2: which agents. Default is every agent, so the user doesn't
+    // have to remember where they installed it — unconfigured agents are
+    // reported as "nothing to remove" and left untouched. An explicit
+    // --target subsets this.
+    let targets;
+    if (opts.target !== undefined) {
+        targets = (0, registry_1.resolveTargetFlag)(opts.target, location);
+    }
+    else {
+        targets = [...registry_1.ALL_TARGETS];
+    }
+    if (targets.length === 0) {
+        clack.outro('No agent targets selected — nothing to do.');
+        return;
+    }
+    // Step 3: sweep + per-agent feedback.
+    const reports = uninstallTargets(targets, location);
+    const removed = reports.filter((r) => r.status === 'removed');
+    for (const r of reports) {
+        if (r.status === 'removed') {
+            for (const p of r.removedPaths) {
+                clack.log.success(`${r.displayName}: removed ${tildify(p)}`);
+            }
+        }
+        else if (r.status === 'not-configured') {
+            clack.log.info(`${r.displayName}: not configured — nothing to remove`);
+        }
+        else {
+            clack.log.info(`${r.displayName}: skipped — ${r.notes[0] ?? 'unsupported location'}`);
+        }
+    }
+    // Step 4: for local uninstall, the index dir is separate — point at
+    // `uninit` so the user knows it's still there (and how to remove it).
+    if (location === 'local' && fs.existsSync(path.join(process.cwd(), '.codegraph'))) {
+        clack.log.info('The .codegraph/ index for this project is still here. Run `codegraph uninit` to delete it.');
+    }
+    // Step 5: summary.
+    if (removed.length > 0) {
+        const names = removed.map((r) => r.displayName).join(', ');
+        clack.outro(`Removed CodeGraph from ${removed.length} agent${removed.length > 1 ? 's' : ''}: ${names}. ` +
+            `Restart ${removed.length > 1 ? 'them' : 'it'} to apply.`);
+    }
+    else {
+        clack.outro(`CodeGraph was not configured in any ${location} agent — nothing to remove.`);
+    }
+}
 /**
  * For every target that has a global config and exposes
  * `wireProjectSurfaces`, write its project-local surfaces (e.g.
@@ -296,10 +424,11 @@ async function resolveTargets(clack, opts, location, useDefaults) {
         .filter((t) => t !== undefined);
 }
 /**
- * Initialize CodeGraph in the current project (for local installs).
- * Unchanged from the pre-refactor version — agent-agnostic by nature.
+ * Initialize CodeGraph in the current project (for local installs), then
+ * offer the watch fallback when the live watcher won't run here (see
+ * offerWatchFallback). Agent-agnostic by nature.
  */
-async function initializeLocalProject(clack) {
+async function initializeLocalProject(clack, useDefaults = false) {
     const projectPath = process.cwd();
     let CodeGraph;
     try {
@@ -314,6 +443,7 @@ async function initializeLocalProject(clack) {
     // Check if already initialized
     if (CodeGraph.isInitialized(projectPath)) {
         clack.log.info('CodeGraph already initialized in this project');
+        await offerWatchFallback(clack, projectPath, { yes: useDefaults });
         return;
     }
     // Initialize
@@ -334,5 +464,65 @@ async function initializeLocalProject(clack) {
         clack.log.success(`Indexed ${formatNumber(result.filesIndexed)} files (${formatNumber(result.nodesCreated)} symbols)`);
     }
     cg.close();
+    await offerWatchFallback(clack, projectPath, { yes: useDefaults });
+}
+/**
+ * When the live file watcher will be disabled for this project (e.g. WSL2
+ * /mnt drives, or CODEGRAPH_NO_WATCH), the index would silently go stale.
+ * Explain that, and offer to keep it fresh automatically via git hooks
+ * (commit / pull / checkout) instead of manual `codegraph sync`.
+ *
+ * No-op on environments where the watcher runs normally, so it's safe to
+ * call unconditionally after init.
+ */
+async function offerWatchFallback(clack, projectPath, opts = {}) {
+    const reason = (0, watch_policy_1.watchDisabledReason)(projectPath);
+    if (!reason)
+        return; // Watcher runs normally — nothing to set up.
+    clack.log.warn(`Live file watching is disabled here — ${reason}.`);
+    clack.log.info('Until you re-sync, the CodeGraph index stays frozen — it will not pick up edits on its own.');
+    // No git repo → the commit-hook path doesn't apply; point at manual sync.
+    if (!(0, git_hooks_1.isGitRepo)(projectPath)) {
+        clack.log.info('Run `codegraph sync` after changing files to refresh the index.');
+        return;
+    }
+    // Already wired up on a previous run — confirm and move on without nagging.
+    if ((0, git_hooks_1.isSyncHookInstalled)(projectPath)) {
+        clack.log.info('Git sync hooks are already installed — the index refreshes after commit / pull / checkout.');
+        return;
+    }
+    let choice;
+    if (opts.yes) {
+        choice = 'hook';
+    }
+    else {
+        const sel = await clack.select({
+            message: 'How should CodeGraph keep its index fresh?',
+            options: [
+                { value: 'hook', label: 'Sync on git commit / pull / checkout', hint: 'installs git hooks (recommended)' },
+                { value: 'manual', label: 'I\'ll run `codegraph sync` myself', hint: 'fully manual' },
+            ],
+            initialValue: 'hook',
+        });
+        if (clack.isCancel(sel)) {
+            clack.log.info('Skipped — run `codegraph sync` after changes to refresh the index.');
+            return;
+        }
+        choice = sel;
+    }
+    if (choice === 'manual') {
+        clack.log.info('Run `codegraph sync` after changing files to refresh the index.');
+        return;
+    }
+    const result = (0, git_hooks_1.installGitSyncHook)(projectPath);
+    if (result.installed.length > 0) {
+        clack.log.success(`Installed git ${result.installed.join(', ')} hook${result.installed.length > 1 ? 's' : ''} — ` +
+            'the index refreshes in the background after each.');
+        clack.log.info('Run `codegraph sync` anytime to refresh immediately.');
+    }
+    else {
+        clack.log.warn(`Could not install git hooks${result.skipped ? ` (${result.skipped})` : ''}. ` +
+            'Run `codegraph sync` after changes instead.');
+    }
 }
 //# sourceMappingURL=index.js.map

package/dist/installer/instructions-template.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Agent-instructions template — the markdown body each agent target
+ * writes into its conventional instructions file (CLAUDE.md /
+ * AGENTS.md / codegraph.mdc / etc.).
+ *
+ * The body content is identical across agents because the codegraph
+ * usage advice is agent-agnostic — only the destination filename and
+ * any optional frontmatter (Cursor `.mdc`) varies per target.
+ *
+ * The legacy `claude-md-template.ts` re-exports these names for
+ * backwards compatibility with downstream importers.
+ */
 /** Markers used by the marker-based section replacement. */
 export declare const CODEGRAPH_SECTION_START = "<!-- CODEGRAPH_START -->";
 export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
@@ -6,11 +18,11 @@ export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
  * instructions file. Includes the start/end markers so the section
  * can be detected and replaced on re-install.
  */
-export declare const INSTRUCTIONS_TEMPLATE = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a SQLite knowledge graph of every symbol, edge, and file in the workspace. Reads are sub-millisecond; the index lags writes by about a second through the file watcher.\n\nPrimary goal: help LLM agents narrow decision space fast. Use it to reduce retrieval noise before editing, not as a second planner.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What is this task / feature / area about?\" | `codegraph_context` |\n| \"Give me a navigation-only slice for this task.\" | `codegraph_repo_map_slice` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Survey an unfamiliar module/topic\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Default LLM-first flow\n\n- Start with `codegraph_context` for the task-level picture.\n- Use `codegraph_repo_map_slice` next when you need a navigation-only slice that narrows the search space without assigning work.\n- Use `codegraph_node`, `codegraph_callers`, `codegraph_callees`, or `codegraph_impact` for focused follow-up on the symbols surfaced above.\n- Use `codegraph_explore` only when the area is genuinely unfamiliar and you need a broader source survey.\n\n### Rules of thumb\n\n- **Trust codegraph results.** Do NOT re-verify them with grep unless you need literal text not carried by the graph.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Use `codegraph_repo_map_slice`** when a coding task needs a noise-reduced navigation slice rather than a full exploration dump. It is navigation-only, not a planner, and should not assign steps.\n- **Use `codegraph_explore`** for broad unfamiliar areas, not narrow lookups.\n- **Trust structured short output first.** `context`, `impact`, and `repo_map_slice` are designed to narrow retrieval space directly for LLM use.\n- **Don't degrade into grep loops.** If codegraph already surfaced relevant symbols/files, continue from those results instead of restarting broad text search.\n- **Don't query immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync.\n\n### ArkTS notes\n\n- ArkTS is first-class in this fork. Treat `.ets` as ArkTS, not as downgraded TypeScript.\n- ArkTS facts come from vendored `ArkAnalyzer`, then flow through shared `search` / `context` / `impact` / `callers` / `callees`.\n- HarmonyOS-aware relations such as `module.json5`, ability/form declarations, lifecycle entry associations, and narrow `Want/IPC` design-time links are query-visible.\n- ArkTS mixed-language bridge paths are valid navigation signals. Use them to move from ArkTS UI code into TS / C++ / Rust bridge layers.\n- `Want/IPC` is structure-only in this fork. It is not a full runtime propagation, full IPC precision graph, or cross-process dataflow graph.\n- Treat ability / form / lifecycle / bridge relations as context-narrowing hints for coding and design work, not as exhaustive runtime truth.\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n<!-- CODEGRAPH_END -->";
+export declare const INSTRUCTIONS_TEMPLATE = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a SQLite knowledge graph of every symbol, edge, and file in the workspace. Reads are sub-millisecond; the index lags writes by about a second through the file watcher.\n\nPrimary goal: help LLM agents narrow decision space fast. Use it to reduce retrieval noise before editing, not as a second planner.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What is this task / feature / area about?\" | `codegraph_context` |\n| \"I need the first hop for a coding task, but do not yet know the right ArkTS entry / bridge / file to inspect.\" | `codegraph_task_map` |\n| \"How does X reach/become Y? / trace the flow from X to Y\" | `codegraph_trace` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Survey an unfamiliar module/topic\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Default LLM-first flow\n\n- Start with `codegraph_task_map` when the task is implementation-oriented and you need a low-noise first hop before choosing which symbols or files to inspect.\n- Start with `codegraph_context` when you need a broader task-level picture and can afford a slightly richer response.\n- Use `codegraph_trace` when the question is specifically about a path from X to Y and the endpoints are already known enough to ask directly.\n- Use `codegraph_node`, `codegraph_callers`, `codegraph_callees`, or `codegraph_impact` for focused follow-up on the symbols surfaced above.\n- Use `codegraph_explore` only when the area is genuinely unfamiliar and you need a broader source survey.\n\n### Tool choice shortcuts\n\n- Use `codegraph_task_map` for coder-style work where the endpoint is not fully known yet and you want likely entry points, bridge hops, convergence points, and a compact confirmed path without a large context dump.\n- Use `codegraph_context` for planner-style or subsystem-orientation work where you want a wider structural picture, not just the first actionable path.\n- Use `codegraph_trace` after `task_map` or `context` has already surfaced plausible endpoints and you now want the explicit path.\n- Use `codegraph_explore` only after the lightweight tools still leave the area ambiguous.\n\n### Rules of thumb\n\n- **Trust codegraph results.** Do NOT re-verify them with grep unless you need literal text not carried by the graph.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Use `codegraph_task_map`** when a coding task needs a noise-reduced navigation slice rather than a full exploration dump. It is a first-hop / trace-launcher aid, not a planner, and should not assign steps.\n- **Use `codegraph_explore`** for broad unfamiliar areas, not narrow lookups.\n- **Trust structured short output first.** `context`, `impact`, and `task_map` are designed to narrow retrieval space directly for LLM use.\n- **Don't degrade into grep loops.** If codegraph already surfaced relevant symbols/files, continue from those results instead of restarting broad text search.\n- **Don't query immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync.\n\n### ArkTS notes\n\n- ArkTS is first-class in this fork. Treat `.ets` as ArkTS, not as downgraded TypeScript.\n- ArkTS facts come from vendored `ArkAnalyzer`, then flow through shared `search` / `context` / `impact` / `callers` / `callees` / `trace`.\n- HarmonyOS-aware relations such as `module.json5`, ability/form declarations, lifecycle entry associations, and narrow `Want/IPC` design-time links are query-visible.\n- ArkTS mixed-language bridge paths are valid navigation signals. Use them to move from ArkTS UI code into TS / C++ / Rust bridge layers.\n- `Want/IPC` is structure-only in this fork. It is not a full runtime propagation, full IPC precision graph, or cross-process dataflow graph.\n- Treat ability / form / lifecycle / bridge relations as context-narrowing hints for coding and design work, not as exhaustive runtime truth.\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n<!-- CODEGRAPH_END -->";
 /**
  * Backwards-compat alias. Existing downstream code may import
  * `CLAUDE_MD_TEMPLATE` from this module via the re-export shim in
  * `claude-md-template.ts`.
  */
-export declare const CLAUDE_MD_TEMPLATE = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a SQLite knowledge graph of every symbol, edge, and file in the workspace. Reads are sub-millisecond; the index lags writes by about a second through the file watcher.\n\nPrimary goal: help LLM agents narrow decision space fast. Use it to reduce retrieval noise before editing, not as a second planner.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What is this task / feature / area about?\" | `codegraph_context` |\n| \"Give me a navigation-only slice for this task.\" | `codegraph_repo_map_slice` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Survey an unfamiliar module/topic\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Default LLM-first flow\n\n- Start with `codegraph_context` for the task-level picture.\n- Use `codegraph_repo_map_slice` next when you need a navigation-only slice that narrows the search space without assigning work.\n- Use `codegraph_node`, `codegraph_callers`, `codegraph_callees`, or `codegraph_impact` for focused follow-up on the symbols surfaced above.\n- Use `codegraph_explore` only when the area is genuinely unfamiliar and you need a broader source survey.\n\n### Rules of thumb\n\n- **Trust codegraph results.** Do NOT re-verify them with grep unless you need literal text not carried by the graph.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Use `codegraph_repo_map_slice`** when a coding task needs a noise-reduced navigation slice rather than a full exploration dump. It is navigation-only, not a planner, and should not assign steps.\n- **Use `codegraph_explore`** for broad unfamiliar areas, not narrow lookups.\n- **Trust structured short output first.** `context`, `impact`, and `repo_map_slice` are designed to narrow retrieval space directly for LLM use.\n- **Don't degrade into grep loops.** If codegraph already surfaced relevant symbols/files, continue from those results instead of restarting broad text search.\n- **Don't query immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync.\n\n### ArkTS notes\n\n- ArkTS is first-class in this fork. Treat `.ets` as ArkTS, not as downgraded TypeScript.\n- ArkTS facts come from vendored `ArkAnalyzer`, then flow through shared `search` / `context` / `impact` / `callers` / `callees`.\n- HarmonyOS-aware relations such as `module.json5`, ability/form declarations, lifecycle entry associations, and narrow `Want/IPC` design-time links are query-visible.\n- ArkTS mixed-language bridge paths are valid navigation signals. Use them to move from ArkTS UI code into TS / C++ / Rust bridge layers.\n- `Want/IPC` is structure-only in this fork. It is not a full runtime propagation, full IPC precision graph, or cross-process dataflow graph.\n- Treat ability / form / lifecycle / bridge relations as context-narrowing hints for coding and design work, not as exhaustive runtime truth.\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n<!-- CODEGRAPH_END -->";
+export declare const CLAUDE_MD_TEMPLATE = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a SQLite knowledge graph of every symbol, edge, and file in the workspace. Reads are sub-millisecond; the index lags writes by about a second through the file watcher.\n\nPrimary goal: help LLM agents narrow decision space fast. Use it to reduce retrieval noise before editing, not as a second planner.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What is this task / feature / area about?\" | `codegraph_context` |\n| \"I need the first hop for a coding task, but do not yet know the right ArkTS entry / bridge / file to inspect.\" | `codegraph_task_map` |\n| \"How does X reach/become Y? / trace the flow from X to Y\" | `codegraph_trace` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Survey an unfamiliar module/topic\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Default LLM-first flow\n\n- Start with `codegraph_task_map` when the task is implementation-oriented and you need a low-noise first hop before choosing which symbols or files to inspect.\n- Start with `codegraph_context` when you need a broader task-level picture and can afford a slightly richer response.\n- Use `codegraph_trace` when the question is specifically about a path from X to Y and the endpoints are already known enough to ask directly.\n- Use `codegraph_node`, `codegraph_callers`, `codegraph_callees`, or `codegraph_impact` for focused follow-up on the symbols surfaced above.\n- Use `codegraph_explore` only when the area is genuinely unfamiliar and you need a broader source survey.\n\n### Tool choice shortcuts\n\n- Use `codegraph_task_map` for coder-style work where the endpoint is not fully known yet and you want likely entry points, bridge hops, convergence points, and a compact confirmed path without a large context dump.\n- Use `codegraph_context` for planner-style or subsystem-orientation work where you want a wider structural picture, not just the first actionable path.\n- Use `codegraph_trace` after `task_map` or `context` has already surfaced plausible endpoints and you now want the explicit path.\n- Use `codegraph_explore` only after the lightweight tools still leave the area ambiguous.\n\n### Rules of thumb\n\n- **Trust codegraph results.** Do NOT re-verify them with grep unless you need literal text not carried by the graph.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Use `codegraph_task_map`** when a coding task needs a noise-reduced navigation slice rather than a full exploration dump. It is a first-hop / trace-launcher aid, not a planner, and should not assign steps.\n- **Use `codegraph_explore`** for broad unfamiliar areas, not narrow lookups.\n- **Trust structured short output first.** `context`, `impact`, and `task_map` are designed to narrow retrieval space directly for LLM use.\n- **Don't degrade into grep loops.** If codegraph already surfaced relevant symbols/files, continue from those results instead of restarting broad text search.\n- **Don't query immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync.\n\n### ArkTS notes\n\n- ArkTS is first-class in this fork. Treat `.ets` as ArkTS, not as downgraded TypeScript.\n- ArkTS facts come from vendored `ArkAnalyzer`, then flow through shared `search` / `context` / `impact` / `callers` / `callees` / `trace`.\n- HarmonyOS-aware relations such as `module.json5`, ability/form declarations, lifecycle entry associations, and narrow `Want/IPC` design-time links are query-visible.\n- ArkTS mixed-language bridge paths are valid navigation signals. Use them to move from ArkTS UI code into TS / C++ / Rust bridge layers.\n- `Want/IPC` is structure-only in this fork. It is not a full runtime propagation, full IPC precision graph, or cross-process dataflow graph.\n- Treat ability / form / lifecycle / bridge relations as context-narrowing hints for coding and design work, not as exhaustive runtime truth.\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n<!-- CODEGRAPH_END -->";
 //# sourceMappingURL=instructions-template.d.ts.map

package/dist/installer/instructions-template.js

@@ -1,6 +1,4 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLAUDE_MD_TEMPLATE = exports.INSTRUCTIONS_TEMPLATE = exports.CODEGRAPH_SECTION_END = exports.CODEGRAPH_SECTION_START = void 0;
 /**
  * Agent-instructions template — the markdown body each agent target
  * writes into its conventional instructions file (CLAUDE.md /
@@ -13,6 +11,8 @@ exports.CLAUDE_MD_TEMPLATE = exports.INSTRUCTIONS_TEMPLATE = exports.CODEGRAPH_S
  * The legacy `claude-md-template.ts` re-exports these names for
  * backwards compatibility with downstream importers.
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_MD_TEMPLATE = exports.INSTRUCTIONS_TEMPLATE = exports.CODEGRAPH_SECTION_END = exports.CODEGRAPH_SECTION_START = void 0;
 const agent_instructions_1 = require("../agent-instructions");
 /** Markers used by the marker-based section replacement. */
 exports.CODEGRAPH_SECTION_START = '<!-- CODEGRAPH_START -->';

package/dist/installer/targets/claude.d.ts

@@ -1,16 +1,20 @@
 /**
- * Claude Code target — the historical default. Writes:
+ * Claude Code target. Writes:
  *
- *   - MCP server entry to `~/.claude.json` (global) or
- *     `./.claude.json` (local).
+ *   - MCP server entry to `~/.claude.json` (global = user scope, loads
+ *     in every project) or `./.mcp.json` (local = project scope, the
+ *     file Claude Code actually reads for a single project). See the
+ *     scope table at https://code.claude.com/docs/en/mcp.
  *   - Permissions to `~/.claude/settings.json` (global) or
  *     `./.claude/settings.json` (local), gated on `autoAllow`.
  *   - Instructions to `~/.claude/CLAUDE.md` (global) or
  *     `./.claude/CLAUDE.md` (local).
  *
- * All paths and shapes ported verbatim from the original
- * `config-writer.ts` so existing Claude Code installs upgrade in
- * place — no migration on disk required.
+ * Earlier versions wrote the local MCP entry to `./.claude.json` — a
+ * file Claude Code never reads — so the server silently never loaded
+ * until the user manually renamed it to `.mcp.json` (issue #207). We
+ * now write `./.mcp.json` and migrate any stale `./.claude.json` entry
+ * out of the way on install and uninstall.
  */
 import { AgentTarget, Location, WriteResult } from './types';
 /**
@@ -21,6 +25,22 @@ import { AgentTarget, Location, WriteResult } from './types';
  * cause side effects callers don't expect.
  */
 export declare function writeMcpEntry(loc: Location): WriteResult['files'][number];
+/**
+ * Remove stale codegraph auto-sync hooks from Claude `settings.json`.
+ *
+ * Surgical at the individual-command level: only entries matching
+ * `isLegacyCodegraphHookCommand` are dropped, so a sibling hook sharing
+ * a matcher group (or the Stop event) with ours survives. We prune a
+ * matcher group only once its `hooks` array is empty, an event only
+ * once it has no groups left, and `hooks` itself only once every event
+ * is gone — and none of that runs unless we actually removed a
+ * codegraph command, so a settings.json with no legacy hooks is left
+ * byte-for-byte untouched and reported `unchanged`.
+ *
+ * Exported so it can be unit-tested directly and reused by both
+ * `install` (an upgrade self-heals) and `uninstall`.
+ */
+export declare function cleanupLegacyHooks(loc: Location): WriteResult['files'][number];
 export declare function writePermissionsEntry(loc: Location): WriteResult['files'][number];
 export declare function writeInstructionsEntry(loc: Location): WriteResult['files'][number];
 export declare const claudeTarget: AgentTarget;