homegraph 1.5.8 → 1.6.0

package/dist/mcp/server-instructions.d.ts

@@ -1,7 +1,3 @@
-/**
- * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
- * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
- */
-export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 optional structural evidence for this repo\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism \u2192 `homegraph_explore`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.\n\nA project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\nNo index \u2192 use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.\n";
-export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 optional per-project evidence\n\nPass `projectPath` to an already indexed folder with `.homegraph/`. No index \u2192 use ordinary tools; indexing is managed by the host.\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism \u2192 `homegraph_explore`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.\n\nA project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\n";
+export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 optional structural evidence for this repo\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Engineering overview / which module owns a feature / where `route_map.json` or resource dirs live \u2192 `homegraph_project` (module map + Harmony skeleton pointers + Module roster with local `file:` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism or route registration edges \u2192 `homegraph_explore` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for `element/string.json` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n- Harmony `element/string.json` key/value lookup is searchable via explore/search (Resource hits may include bound `.ets` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.\n- Harmony `form_config.json` / `shortcuts_config.json` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project \u2014 do not treat SDK Form `.d.ts` as project wiring when the negative note says no in-repo form.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with `HomeGraph project root: `\u2026`` \u2014 that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched `projectPath` is ignored (results stay on the bound root) with a short English notice \u2014 do not treat that as a hard error.\n\nA project map (`homegraph_project`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n## Index status\n\nTool replies may start with `HomeGraph project root: \u2026` (absolute join base for relative paths) and end with `HomeGraph status=\u2026`. status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\nNo index \u2192 use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.\n";
+export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 optional per-project evidence\n\nPass `projectPath` to an already indexed folder with `.homegraph/`. No index \u2192 use ordinary tools; indexing is managed by the host.\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Engineering overview / which module owns a feature / where `route_map.json` or resource dirs live \u2192 `homegraph_project` (module map + Harmony skeleton pointers + Module roster with local `file:` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.\n- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism or route registration edges \u2192 `homegraph_explore` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for `element/string.json` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n- Harmony `element/string.json` key/value lookup is searchable via explore/search (Resource hits may include bound `.ets` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.\n- Harmony `form_config.json` / `shortcuts_config.json` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project \u2014 do not treat SDK Form `.d.ts` as project wiring when the negative note says no in-repo form.\n\nDo not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with `HomeGraph project root: `\u2026`` \u2014 that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched `projectPath` is ignored (results stay on the bound root) with a short English notice \u2014 do not treat that as a hard error.\n\nA project map (`homegraph_project`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project, \u22641 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n## Index status\n\nTool replies may start with `HomeGraph project root: \u2026` (absolute join base for relative paths) and end with `HomeGraph status=\u2026`. status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry.\n\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\n";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/server-instructions.js

@@ -1,10 +1,11 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
+const index_availability_1 = require("./index-availability");
 /**
  * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
  * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
 const SOURCE_AND_VALIDATION = `
 - ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.
 - ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.
@@ -19,24 +20,32 @@ Use ordinary bash/search/read tools first for repository paths, symbols, literal
 HomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.
 
 Choose the smallest available tool for that gap:
+- Engineering overview / which module owns a feature / where \`route_map.json\` or resource dirs live → \`homegraph_project\` (module map + Harmony skeleton pointers + Module roster with local \`file:\` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.
 - Exact usage/reference locations → \`homegraph_usages\`; callers/callees → the corresponding tool.
 - Named module dependencies/cycles → \`homegraph_modules\`; native exports/registration → \`homegraph_native\`.
 - One missing symbol body → \`homegraph_node\`; prefer direct read if its path is already known.
-- An unresolved cross-symbol mechanism → \`homegraph_explore\`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.
+- An unresolved cross-symbol mechanism or route registration edges → \`homegraph_explore\` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for \`element/string.json\` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.
 - ArkUI migration analysis → \`homegraph_arkui_migrate\` when that analysis is needed; SDK contracts → project declarations or SDK documentation.
+- Harmony \`element/string.json\` key/value lookup is searchable via explore/search (Resource hits may include bound \`.ets\` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.
+- Harmony \`form_config.json\` / \`shortcuts_config.json\` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project — do not treat SDK Form \`.d.ts\` as project wiring when the negative note says no in-repo form.
 
 Do not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.
 `;
 const QUERY = `## Query and recovery
 
-Write one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as \`taskContext\` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.
+Write one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as \`taskContext\` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with \`HomeGraph project root: \`…\`\` — that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as \`<root>/<relative>\` (use \`/\`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched \`projectPath\` is ignored (results stay on the bound root) with a short English notice — do not treat that as a hard error.
+
+A project map (\`homegraph_project\`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: ≤2 \`homegraph_explore\` attempts per project, ≤1 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.
+`;
+const INDEX_STATUS = `## Index status
 
-A project map is navigation, not proof of a located feature. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: ≤2 \`homegraph_explore\` attempts per project, ≤1 focused depth recovery; existing runtime budgets may be tighter. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.
+Tool replies may start with \`HomeGraph project root: …\` (absolute join base for relative paths) and end with \`HomeGraph status=…\`. ${index_availability_1.PRODUCT_STATUS_GLOSSARY}.
 `;
 exports.SERVER_INSTRUCTIONS = `# HomeGraph — optional structural evidence for this repo
 
 ${ON_DEMAND}
 ${QUERY}
+${INDEX_STATUS}
 ${SOURCE_AND_VALIDATION}
 No index → use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.
 `;
@@ -46,6 +55,7 @@ Pass \`projectPath\` to an already indexed folder with \`.homegraph/\`. No index
 
 ${ON_DEMAND}
 ${QUERY}
+${INDEX_STATUS}
 ${SOURCE_AND_VALIDATION}
 `;
 //# sourceMappingURL=server-instructions.js.map

package/dist/mcp/session.js

@@ -54,6 +54,7 @@ const tools_1 = require("./tools");
 const server_instructions_1 = require("./server-instructions");
 const version_1 = require("./version");
 const directory_1 = require("../directory");
+const runtime_log_1 = require("../runtime-log");
 const update_check_1 = require("../upgrade/update-check");
 const explore_session_state_1 = require("./explore-session-state");
 /**
@@ -249,6 +250,10 @@ class MCPSession {
             serverInfo: exports.SERVER_INFO,
             instructions: initializeInstructions(indexed ? server_instructions_1.SERVER_INSTRUCTIONS : server_instructions_1.SERVER_INSTRUCTIONS_NO_ROOT_INDEX),
         });
+        (0, runtime_log_1.logLifecycle)('mcp.initialize', {
+            projectRoot: explicitPath ?? undefined,
+            indexed,
+        });
         if (explicitPath) {
             // Kick off engine init in the background. If another session in the
             // same daemon already opened the project, `ensureInitialized` is a
@@ -317,6 +322,16 @@ class MCPSession {
         }
         if (this.engine.hasDefaultHomeGraph())
             return;
+        // Spec 0049: empty-root defer — re-probe and start auto-init as soon as
+        // sources appear (do not wait for the next timer tick).
+        if (this.engine.isAutoInitDeferred()) {
+            try {
+                await this.engine.kickDeferredAutoInit();
+            }
+            catch { /* fall through */ }
+            if (this.engine.hasDefaultHomeGraph())
+                return;
+        }
         const hint = this.explicitProjectPath ?? this.engine.getProjectPath();
         if (!hint && !this.rootsAttempted) {
             this.rootsAttempted = true;

package/dist/mcp/tools.d.ts

@@ -119,6 +119,32 @@ export declare function tightenExploreBudgetForQuery(budget: ExploreOutputBudget
  * Set `HOMEGRAPH_EXPLORE_FULL_SOURCE=1` to restore the previous fatter Source.
  */
 export declare function exploreLocatorDigestEnabled(): boolean;
+/**
+ * Spec 0039 — short Registration sources table from indexed Harmony profile routes.
+ * Returns null when nothing to show.
+ */
+export declare function formatHarmonyRegistrationSources(cg: Pick<HomeGraph, 'getNodesByKind'>, maxRows?: number): string | null;
+/**
+ * Spec 0041 / 0048 §3 — short Resource hits table for element/string.json constants.
+ * Spec 0048: append up to 2 in-repo `.ets` binding anchors when signature/docstring
+ * mention `app.string.<key>`.
+ */
+export declare function formatHarmonyResourceHits(cg: Pick<HomeGraph, 'getNodesByKind' | 'getProjectRoot' | 'getFiles'>, query: string, maxRows?: number): string | null;
+/**
+ * Spec 0048 §1–2 — Capability profiles table, or form negative evidence.
+ */
+export declare function formatHarmonyCapabilityProfiles(cg: Pick<HomeGraph, 'getNodesByKind'>, query: string, maxRows?: number): string | null;
+/** Spec 0048 §5 — detect empty / log-only method bodies. */
+export declare function isHarmonyStubBody(source: string): boolean;
+/**
+ * Spec 0048 §5 — seam notes for located explore anchors.
+ */
+export declare function formatHarmonySeamNotes(cg: Pick<HomeGraph, 'getNodesByKind' | 'getNode'>, projectRoot: string, located: Array<{
+    id?: string;
+    name: string;
+    filePath: string;
+    startLine: number;
+}>, maxAnchors?: number): string | null;
 /**
  * Per-file staleness banner emitted at the top of a tool response when the
  * file watcher has pending events for files referenced by the response.
@@ -256,6 +282,7 @@ export declare class ToolHandler {
     private cg;
     private projectCache;
     private defaultProjectHint;
+    private boundProjectPathPinNotice;
     private worktreeMismatchCache;
     private catchUpGate;
     private queryPool;
@@ -342,6 +369,11 @@ export declare class ToolHandler {
      *
      * Walks up parent directories to find the nearest .homegraph/ folder,
      * similar to how git finds .git/ directories.
+     *
+     * Spec 0043: when a default project is already bound, a `projectPath` whose
+     * resolved index root differs from that bound root is soft-pinned back to
+     * the default (no DB switch) and a success-shaped English notice is stashed
+     * for the reply preamble.
      */
     private getHomeGraph;
     /**
@@ -418,6 +450,12 @@ export declare class ToolHandler {
      */
     private isFileStaleOnDisk;
     private withStalenessNotice;
+    /**
+     * Decorate successful tool text (Spec 0035 status footer + Spec 0038 project-root hint
+     * + Spec 0043 bound projectPath pin notice).
+     * Prepends absolute project root + join guidance when known; appends status when missing.
+     */
+    private withProductStatusFooter;
     /**
      * Execute a tool by name.
      *
@@ -425,6 +463,9 @@ export declare class ToolHandler {
      * it (the CLI does) and explore behaves exactly as before, untracked.
      */
     execute(toolName: string, args: Record<string, unknown>, sessionState?: ExploreSessionState): Promise<ToolResult>;
+    /** Spec 0046: HOMEGRAPH_DEBUG tool summary → stderr + daemon.log. */
+    private traceToolCall;
+    private executeCore;
     /**
      * Attach the caller's session view to an explore call's args (CG-17), on a
      * COPY so the caller's object is never mutated. Nothing else sees it: a
@@ -774,6 +815,17 @@ export declare class ToolHandler {
     private handleExplore;
     /** Render literal witnesses before graph-heavy sections, including unindexed UI. */
     private renderLiteralSource;
+    /**
+     * Spec 0039: when the query names Harmony route profiles, lead with a short
+     * Registration sources table so agents see JSON was indexed (avoid re-Read).
+     */
+    private prependHarmonyRegistrationSources;
+    /** Spec 0041: lead with Resource hits when string.json is named or matched. */
+    private prependHarmonyResourceHits;
+    /** Spec 0048 §1–2: Capability profiles or form negative evidence. */
+    private prependHarmonyCapabilityProfiles;
+    /** Spec 0048 §5: seam notes for located anchors. */
+    private prependHarmonySeamNotes;
     /**
      * An explore response plus the record of what it emitted (CG-17). The record
      * rides the result only as far as {@link execute}, which files it into the