@mrclrchtr/supi-code-intelligence 2.1.0 → 2.2.1

package/src/tool/guidance.ts

@@ -2,6 +2,11 @@
 //
 // Each code_* tool owns its complete promptGuidelines here.
 // Runtime registration data (name, parameters, run) lives in specs.ts.
+//
+// Cross-tool steering is centralized (authored once on its natural-home tool) and
+// some tools have empty promptGuidelines by design: all code_* tools are always
+// active together, so a steering bullet on one tool is always co-visible. See
+// docs/adr/0013-centralized-code-intelligence-prompt-steering-assumes-all-tools-active.md.
 
 import type { CodeIntelligenceToolName } from "../types/index.ts";
 
@@ -19,94 +24,78 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
 export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES: CodeIntelligenceToolPromptSurfaceMap = {
   code_resolve: {
     description:
-      "Resolve human or code references into precise file/range/symbol targets and stable target handles. Use when a symbol, file, or code reference is ambiguous and needs precise resolution. Returns targetId and spanId handles that can be passed to code_graph, code_impact, and code_refactor_plan. Supports anchored (file + line + character), file-only, and query/symbol inputs. Anchored coordinates resolve a real symbol target from provider-backed evidence: an exact identifier coordinate resolves to a named target; a declaration-header coordinate (e.g. an `export` keyword) snaps to the symbol name anchor only when unambiguous. Whitespace/comment/non-symbol coordinates fail honestly and recommend code_inspect. Does not fall back to text search for symbol resolution; ambiguous results return ranked candidates with target IDs for every shown item. Output is truncated to 2000 lines / 50KB.",
+      "Resolve references to evidence-backed code targets and stable targetId/spanId handles for follow-up code_* tools. Accepts query/symbol/file or anchored file+line+character; anchored resolution snaps only to real provider-backed symbols, and whitespace/comment/non-symbol points fail with code_inspect guidance. No text-search fallback; ambiguous results return ranked candidates. Truncates at 2000 lines/50KB.",
     promptSnippet: "code_resolve — resolve references into precise targets and target handles",
     promptGuidelines: [
-      "Use code_resolve when a symbol, file, or code reference is ambiguous and needs precise resolution.",
-      "Prefer code_resolve as the entry point before code_orientation, code_graph, code_impact, or code_refactor_plan — its targetId replaces fragile file/line/character coordinates.",
-      "When code_resolve returns ambiguous results with ranked candidates, pick one and use file + line + character for follow-up resolution.",
+      "Use code_resolve first for ambiguous or symbol-only targets, before graph/impact/refactor/orientation; if resolve returns ranked candidates, narrow with a candidate file + line + character.",
     ],
   },
   code_inspect: {
     description:
-      "Inspect one precise point in a file and return factual syntax, symbol, hover, definition, diagnostics, and code-action information. Use when you need to understand exactly what is at a position without choosing between provider-specific substrate tools. When some providers are unavailable, returns best-effort sections with explicit unavailable notes instead of heuristic guesses. Code action titles are advisory only — there is no tool to execute them yet. Output is truncated to 2000 lines / 50KB.",
+      "Inspect one exact file position for syntax, symbol, hover/definition, nearby diagnostics, and code-action titles. Requires file, line, and character; use for point facts, not broad orientation. Unavailable providers are disclosed; code actions are advisory only. Truncates at 2000 lines/50KB.",
     promptSnippet: "code_inspect — factual point inspection",
-    promptGuidelines: [
-      "Use code_inspect for factual point inspection at one precise file position.",
-      "Provide `file`, `line`, and `character` — code_inspect is intentionally point-based.",
-      "Prefer code_inspect over code_orientation for point-level facts when no symbol target can be resolved.",
-    ],
+    // No guidelines: selection is steered by code_orientation's bullet plus this
+    // self-sufficient description. See ADR 0013 (all code_* tools always active).
+    promptGuidelines: [],
   },
   code_orientation: {
     description:
-      "Primary code-orientation tool for understanding a project, discovered module, directory, file, or symbol before choosing surgical follow-up tools. Use `focus` for a workspace-relative path or discovered module name; omit `focus` for project orientation. Use `focus` + `line` + `character` for symbol orientation, or pass `targetId` from `code_resolve`; `targetId` takes precedence over focus/coordinates and stale target IDs do not fall back. Symbol orientation returns definitions, JSDoc/TSDoc docs, local diagnostics near the target, and Read Next guidance; relation evidence belongs in code_graph, impact evidence in code_impact, and health/status in code_health. Not a point-inspection tool — use code_inspect for exact position facts. `maxResults` caps each rendered list and defaults to 10. Output is truncated to 2000 lines / 50KB.",
+      "Orient around the workspace, module, directory, file, or resolved symbol before surgical work. Omit focus for workspace orientation; use focus for a path/module, or targetId/focus+line+character for symbol orientation. Directory focus may surface local instruction files (CLAUDE.md, AGENTS.md). targetId wins and stale IDs error. Returns landmarks, docs, local diagnostics, and read-next guidance; relations/impact/health belong in code_graph/code_impact/code_health. maxResults caps lists; output is truncated to 2000 lines / 50KB.",
     promptSnippet: "code_orientation — project/module/file/symbol orientation",
     promptGuidelines: [
       "Use `code_orientation({ focus })` for first-pass project/package/directory/file orientation before `bash`/`read`.",
+      "Use directory focus (for example `packages/foo`) to surface local instruction files before package work.",
       "Use code_resolve first for bare symbol names, then pass the resulting targetId to code_orientation.",
       "Use code_graph/code_impact/code_health for relations, impact, or full health instead of asking code_orientation for those sections.",
     ],
   },
   code_graph: {
     description:
-      'Unified relation-graph tool — replaces code_references, code_calls, and code_implementations. Resolves a target once and dispatches to the appropriate analysis service per requested relation. Defaults to ["references"] when `relations` is omitted. Each relation is best-effort: unavailable substrates skip with a note rather than failing the whole call. Each relation annotates its evidence source. The tests relation displays discovery provenance (semantic+conventions or conventions-only) separately from any extracted test labels. `callees` is structural/direct-scope evidence: it reports call expressions by source shape, not symbol identity, and excludes calls inside nested function/method/callback scopes — use `references` on a resolved target for identity-aware incoming callers. Pass `calleeDepth: "deep"` to include callees from nested scopes. `imports` and `exports` use file-level tree-sitter analysis; `tests` discovers companion test files and labels. Targeted graph results include Read Next guidance for source ranges worth inspecting via `read`. `scope` (not `path`) narrows by workspace-relative directory/package. Use code_resolve first to get a targetId, then pass it to code_graph. Output is truncated to 2000 lines / 50KB.',
+      'Analyze relation evidence for a resolved target or coordinates: references, structural callees, imports/exports, implementations, and tests. Defaults to references; relations:["all"] expands all families. Per-relation substrate failures are disclosed. Callees are syntax/direct-scope source-shape calls, not symbol identity; calleeDepth:"deep" includes nested scopes. Scope narrows by workspace path; targetId from code_resolve is preferred. Truncates at 2000 lines/50KB.',
     promptSnippet: "code_graph — semantic and structural relation graph",
-    promptGuidelines: [
-      "Use code_graph to find references, direct structural calls, and implementations for a target.",
-      'Default `relations` is ["references"]; use `relations: ["callees"]` or `["implements"]` for those, or `relations: ["all"]` to expand to every relation family in one call.',
-      "After code_graph, follow up with code_orientation on individual results for type or definition context.",
-      'Pass `calleeDepth: "deep"` to include callees from nested function/method/callback scopes (default `"direct"` excludes them).',
-      'Suggested relations by target kind: For functions/methods: `["references", "callees", "tests"]` — For interfaces/types/classes/enums: `["references", "implements"]` — For files/modules: `["imports", "exports"]` — For tests: `["tests"]`.',
-    ],
+    // No guidelines: selection is steered by this self-sufficient description plus
+    // code_impact's "use code_graph instead of code_impact" bullet. See ADR 0013.
+    promptGuidelines: [],
   },
   code_impact: {
     description:
-      "Estimate blast radius and downstream impact for a target or user-supplied change set before making edits. `changeSetFiles` are explicit workspace-relative files to analyze as in scope for a proposed/current change; they are not inferred from git and carry no line-level diff evidence. Uses semantic evidence for target-based impact and merges semantic references for symbols defined in change-set files when available. Includes Read Next guidance for source ranges worth inspecting via `read` before editing. Does not fall back to heuristic text search. Use a resolved target for precise semantic reference-based impact. Output is truncated to 2000 lines / 50KB.",
+      "Estimate blast radius for a resolved target or user-supplied changeSetFiles before editing. changeSetFiles are explicit files, not inferred from git and no line-level diff; change-only requests report insufficient evidence. Uses semantic references plus deterministic test discovery when available; no heuristic search fallback. Output includes read-next guidance; truncates at 2000 lines/50KB.",
     promptSnippet: "code_impact — blast radius and impact",
     promptGuidelines: [
-      "Use code_impact before edits to estimate blast radius and follow-up checks.",
-      "Use code_graph instead of code_impact when you only need a plain reference list without impact analysis.",
+      "Use code_graph instead of code_impact when you only need a plain reference list.",
     ],
   },
   code_find: {
     description:
-      'Unified ranked code search with strict mode dispatch: default/`mode: "text"` is literal ripgrep, `mode: "regex"` is ripgrep regex, `mode: "semantic"` is LSP workspace-symbol search, and `mode: "ast"` is tree-sitter structured search. `mode: "ast"` requires `kind` and currently supports `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, `enum`, and `test`. `mode: "text"`, `mode: "regex"`, and `mode: "semantic"` do not accept `kind`. `scope` accepts one workspace-relative path or an array of paths; delimiter-separated strings are split only when no exact path exists. `code_find` with `mode: "semantic"` does not silently fall back to text search, and unsupported mode/kind combinations fail. AST `call` mode matches call-site identifiers by name, not by symbol identity; use `code_graph` references for identity-aware callers of a resolved target. Output is truncated to 2000 lines / 50KB.',
+      'Search code with explicit modes: text literal (default), regex, semantic workspace-symbol, or ast structured. mode:"ast" requires `kind` (definition/import/export/call/type/interface/class/method/enum/test); text/regex/semantic reject kind. Semantic mode uses LSP only and does not silently fall back. AST call matches written call-site names, not by symbol identity; use code_graph references on a resolved target for symbol-identity-aware callers. Truncates at 2000 lines/50KB.',
     promptSnippet: "code_find — unified ranked code search",
     promptGuidelines: [
-      "Use code_find as the sole code search tool for literal text, regex, semantic workspace-symbol, or AST structured search.",
-      'code_find with `mode: "ast"` requires `kind` and supports `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, `enum`, and `test`.',
-      'code_find with `mode: "text"`, `mode: "regex"`, or `mode: "semantic"` does not accept `kind`.',
-      'code_find with `mode: "semantic"` does not fall back to text search and fails when semantic capability is unavailable.',
-      'AST `call` mode matches call-site identifiers by name only; use `code_graph` with `relations: ["references"]` on a resolved target for symbol-identity-aware callers.',
+      "Use code_find for explicit text, regex, semantic symbol, or AST search; use code_graph references for symbol-identity callers.",
     ],
   },
   code_refactor_plan: {
     description:
-      'Pure planner: previews a precise semantic refactor plan without mutating files and returns a planId for later use with code_refactor_apply. Supports rename_symbol plus extract_function/extract_variable when the active LSP can return precise edits. Legacy `operation: "rename"` is accepted as a compatibility alias. This tool never mutates files. Output is truncated to 2000 lines / 50KB.',
+      "Preview a semantic refactor plan and return planId; never mutates files. Supports rename_symbol (rename alias) and extract_function/extract_variable when LSP returns precise edits. Requires targetId or anchored file+line+character, plus operation-specific newName/range. Apply separately with code_refactor_apply. Truncates at 2000 lines/50KB.",
     promptSnippet: "code_refactor_plan — preview a precise workflow refactor plan",
     promptGuidelines: [
-      'Use `operation: "rename_symbol"` with code_refactor_plan for symbol renames. Legacy `operation: "rename"` is accepted as a compatibility alias.',
-      'Use `operation: "extract_function"` or `"extract_variable"` with a 1-based `range` and `newName` when the LSP advertises precise extract code actions.',
-      "code_refactor_plan is a pure planner — it returns a planId. Use code_refactor_apply with that planId to execute.",
+      "Use code_refactor_plan to preview rename/extract edits only; mutate later with code_refactor_apply and the returned planId.",
     ],
   },
   code_refactor_apply: {
     description:
-      "Sole mutator in the refactor workflow: applies a previously stored plan by planId. Revalidates the plan and checks file fingerprints, mutating files only when the plan is still fresh. Output is truncated to 2000 lines / 50KB.",
+      "Apply a stored refactor plan by planId. Revalidates plan freshness and file fingerprints before mutating; does not compose new plans. Truncates at 2000 lines/50KB.",
     promptSnippet: "code_refactor_apply — apply a stored refactor plan",
     promptGuidelines: [
-      "Use code_refactor_apply to execute a plan generated by code_refactor_plan.",
-      "Use code_refactor_plan first to obtain a planId, then code_refactor_apply to execute it.",
+      "Use code_refactor_apply only with a planId returned by code_refactor_plan.",
     ],
   },
   code_health: {
     description:
-      "Summarize diagnostics, language server status, dirty workspace signals, coverage, and unused-code findings. Pass refresh: true to recover stale diagnostics before checking. Use scope to narrow to a specific file or package. Use include to request specific sections: diagnostics, servers, dirty, coverage, unused. Defaults to summary level (counts); use level: detailed for per-file listings. Output is truncated to 2000 lines / 50KB.",
+      "Report workspace health: diagnostics, language-server status, dirty files, coverage, and unused code. Use scope/include/level to narrow; refresh:true recovers stale diagnostics. Missing coverage/unused reports are disclosed. Truncates at 2000 lines/50KB.",
     promptSnippet:
       "code_health — diagnostics, server status, coverage, unused-code, and workspace health",
     promptGuidelines: [
-      "Use code_health to check for diagnostics, language server status, dirty workspace state, coverage, or unused-code signals.",
-      "Pass `refresh: true` to code_health to recover stale diagnostics before checking.",
+      "Use code_health for diagnostics/server/dirty/coverage/unused health; pass refresh:true to code_health before relying on stale diagnostics.",
     ],
   },
 };

package/src/tool/orientation/mode.ts

@@ -6,10 +6,17 @@
  * orientation.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import type { ArchitectureModel } from "../../analysis/architecture/model.ts";
+import {
+  findInstructionFilesForDirectory,
+  insertInstructionsNearTop,
+  renderInstructionFiles,
+} from "../../analysis/instruction-files.ts";
 import { normalizePath } from "../../analysis/search/ripgrep.ts";
+import { loadCodeIntelligenceConfig } from "../../config.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import type { OrientationUseCaseResult } from "../../ui/markdown/types.ts";
 import { unavailableContextDetails } from "../infra/error-results.ts";
 import { prepareOrientationDeps } from "./deps.ts";
 import type { CodeOrientationToolParams } from "./execute.ts";
@@ -50,8 +57,52 @@ export async function runOrientationMode(
     },
     { ...deps, cwd: ctx.cwd },
   );
+  const withInstructions = addInstructionFilesForDirectoryFocus(result, focusResolution.path, ctx);
 
-  return { content: result.content, details: { type: "context", data: result.details } };
+  return {
+    content: withInstructions.content,
+    details: { type: "context", data: withInstructions.details },
+  };
+}
+
+function addInstructionFilesForDirectoryFocus(
+  result: OrientationUseCaseResult,
+  focusPath: string | undefined,
+  ctx: CodeIntelToolExecCtx,
+): OrientationUseCaseResult {
+  if (!focusPath || !isDirectory(focusPath)) return result;
+
+  const config = loadCodeIntelligenceConfig(ctx.cwd);
+  const matches = findInstructionFilesForDirectory({
+    directory: focusPath,
+    cwd: ctx.cwd,
+    fileNames: config.instructionFileNames,
+    nativeContextPaths: ctx.session.nativeInstructionPaths,
+    surfacedDirectories: ctx.session.surfacedInstructionDirs,
+  });
+  if (matches.length === 0) return result;
+
+  const rendered = renderInstructionFiles(matches);
+  if (!rendered) return result;
+
+  ctx.session.markInstructionDirsSurfaced(rendered.metadata.files.map((file) => file.directory));
+
+  return {
+    content: insertInstructionsNearTop(result.content, rendered.markdown),
+    details: {
+      ...result.details,
+      renderedSections: ["instructions", ...result.details.renderedSections],
+      instructions: rendered.metadata,
+    },
+  };
+}
+
+function isDirectory(filePath: string): boolean {
+  try {
+    return statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
 }
 
 /**

package/src/tool/result/types.ts

@@ -1,5 +1,6 @@
 import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
 import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { InstructionFilesMetadata } from "../../analysis/instruction-files.ts";
 import type { PrioritySignalsSummary } from "../../analysis/signals/project.ts";
 import type { TestSurfaceDetails } from "../../analysis/tests/test-discovery.ts";
 import type { AnchorKind, TargetStoreEntry } from "../../session/target-store.ts";
@@ -143,6 +144,8 @@ export interface ContextDetails {
   evidenceLists?: EvidenceListMetadata[];
   nextQueries: string[];
   tests?: TestSurfaceDetails;
+  /** Directory-local instruction files surfaced during directory orientation. */
+  instructions?: InstructionFilesMetadata;
   /**
    * Resolved target store entry — populated for both coordinate and targetId
    * precise-target inputs. Absent for orientation/scope-only calls and for

package/src/tool/schemas.ts

@@ -3,27 +3,26 @@ import { type TSchema, Type } from "typebox";
 import type { CodeIntelligenceToolName } from "../types/index.ts";
 
 const ScopeParam = Type.String({
-  description: "Workspace-relative path, package, or directory scope for the workflow query.",
+  description: "Workspace-relative file or directory scope.",
 });
 const FindScopeParam = Type.Union(
   [
     Type.String({
-      description: "Workspace-relative path, package, or directory scope for the search query.",
+      description: "Workspace-relative search scope.",
     }),
     Type.Array(
       Type.String({
-        description: "Workspace-relative path, package, or directory search scope.",
+        description: "Workspace-relative search scope.",
       }),
       {
-        description: "One or more workspace-relative paths, packages, or directories to search.",
+        description: "One or more workspace-relative search scopes.",
         minItems: 1,
         uniqueItems: true,
       },
     ),
   ],
   {
-    description:
-      "Workspace-relative path, package, directory, or array of scopes for the search query.",
+    description: "Workspace-relative search scope or scope list.",
   },
 );
 const FileParam = Type.String({ description: "Target file path." });
@@ -36,13 +35,13 @@ const CharacterParam = Type.Number({
   minimum: 1,
 });
 const MaxResultsParam = Type.Number({
-  description: "Maximum number of ranked results.",
+  description: "Maximum results.",
   minimum: 1,
 });
 const SymbolParam = Type.String({ description: "Symbol name" });
 const TargetIdParam = Type.String({
   description:
-    "Resolved target handle from `code_resolve`. Takes precedence over file/line/character/symbol.",
+    "Resolved target handle from `code_resolve`; takes precedence over other target inputs.",
 });
 const RangeParam = Type.Object(
   {
@@ -114,25 +113,23 @@ export const CodeOrientationParameters = Type.Object(
   {
     focus: Type.Optional(
       Type.String({
-        description:
-          "Workspace-relative path or discovered module name to orient around. Omit for project orientation.",
+        description: "Workspace-relative path or module name; omit for workspace orientation.",
       }),
     ),
     targetId: Type.Optional(
       Type.String({
-        description:
-          "Resolved target handle from `code_resolve`. Takes precedence over `focus`/`line`/`character`. If invalid or stale, the call errors and does not fall back to coordinates.",
+        description: "Resolved target handle; takes precedence, stale IDs error.",
       }),
     ),
     line: Type.Optional(
       Type.Number({
-        description: "1-based line for symbol orientation. Requires `focus` and `character`.",
+        description: "1-based line for symbol orientation with `focus`.",
         minimum: 1,
       }),
     ),
     character: Type.Optional(
       Type.Number({
-        description: "1-based UTF-16 column for symbol orientation. Requires `focus` and `line`.",
+        description: "1-based UTF-16 column for symbol orientation with `focus`.",
         minimum: 1,
       }),
     ),
@@ -153,8 +150,7 @@ export const CodeFindParameters = Type.Object(
     scope: Type.Optional(FindScopeParam),
     mode: Type.Optional(
       StringEnum(["text", "regex", "ast", "semantic"], {
-        description:
-          'Search mode. Omit for literal text search. mode: "ast" requires `kind`; mode: "text", mode: "regex", and mode: "semantic" do not accept `kind`.',
+        description: 'Search mode; omit for literal text. mode:"ast" requires `kind`.',
       }),
     ),
     kind: Type.Optional(
@@ -172,13 +168,12 @@ export const CodeFindParameters = Type.Object(
           "test",
         ],
         {
-          description:
-            'Only valid with `mode: "ast"`. Supported AST kinds: `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, `enum`, `test`. AST `call` matches call-site identifiers by name, not by symbol identity.',
+          description: 'AST kind; only valid with mode:"ast".',
         },
       ),
     ),
     contextLines: Type.Optional(
-      Type.Number({ description: "Context lines to include around matches.", minimum: 0 }),
+      Type.Number({ description: "Context lines around matches.", minimum: 0 }),
     ),
     maxResults: Type.Optional(MaxResultsParam),
   },
@@ -205,11 +200,10 @@ export const CodeGraphParameters = Type.Object(
     relations: Type.Optional(
       Type.Array(
         StringEnum(["all", "references", "callees", "imports", "exports", "implements", "tests"], {
-          description:
-            'Relation families to include in the graph. Use `"all"` to expand to every relation family. `callees` is direct structural outgoing-call evidence: source-shape calls in the enclosing scope, not symbol-identity resolution.',
+          description: "Relation family.",
         }),
         {
-          description: 'Requested relation families. Defaults to ["references"] when omitted.',
+          description: 'Requested relation families; defaults to ["references"].',
           uniqueItems: true,
         },
       ),
@@ -217,8 +211,7 @@ export const CodeGraphParameters = Type.Object(
     maxResults: Type.Optional(MaxResultsParam),
     calleeDepth: Type.Optional(
       StringEnum(["direct", "deep"], {
-        description:
-          'Depth for callee collection. `"direct"` (default): only direct calls from the enclosing scope, excluding nested function/callback scopes. `"deep"`: include all callees within the enclosing scope, including those inside nested scopes.',
+        description: '`"direct"` excludes nested scopes; `"deep"` includes them.',
       }),
     ),
   },
@@ -241,8 +234,7 @@ export const CodeImpactParameters = Type.Object(
     ),
     changeSetFiles: Type.Optional(
       Type.Array(Type.String({ description: "Workspace-relative file in the change set." }), {
-        description:
-          "User-supplied files to analyze as the change set. This is not inferred from git and carries no line-level diff evidence.",
+        description: "Explicit change-set files; not inferred from git and no line-level diff.",
         minItems: 1,
         uniqueItems: true,
       }),
@@ -250,7 +242,7 @@ export const CodeImpactParameters = Type.Object(
     includeTests: Type.Optional(
       Type.Boolean({
         description:
-          "Whether likely tests should be included in the impact set. changeSetFiles analysis uses semantic references when available plus deterministic conventions; target-based analysis may combine semantic references with deterministic conventions.",
+          "Include likely tests using semantic references and deterministic conventions.",
       }),
     ),
     maxResults: Type.Optional(MaxResultsParam),
@@ -272,8 +264,7 @@ export const CodeImpactParameters = Type.Object(
 export const CodeRefactorParameters = Type.Object(
   {
     operation: StringEnum(["rename", "rename_symbol", "extract_function", "extract_variable"], {
-      description:
-        "Precise refactor operation to plan. `rename` is accepted as a compatibility alias for `rename_symbol`.",
+      description: "Refactor operation; `rename` is an alias for `rename_symbol`.",
     }),
     targetId: Type.Optional(
       Type.String({ description: "Resolved target handle from `code_resolve`." }),
@@ -329,13 +320,12 @@ export const CodeHealthParameters = Type.Object(
     ),
     coveragePath: Type.Optional(
       Type.String({
-        description:
-          "Workspace-relative path to a coverage summary JSON file. Defaults to `coverage/coverage-summary.json`.",
+        description: "Coverage summary path; defaults to `coverage/coverage-summary.json`.",
       }),
     ),
     unusedPath: Type.Optional(
       Type.String({
-        description: "Workspace-relative path to a knip JSON report. Defaults to `knip.json`.",
+        description: "Knip report path; defaults to `knip.json`.",
       }),
     ),
   },

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/config/config-settings.ts

@@ -1,207 +0,0 @@
-// Config-aware settings contribution helper for SuPi packages.
-//
-// Registers config-backed settings sections through PI's shared event bus so
-// /supi-settings can collect contributions from all loaded extensions without
-// relying on a shared supi-core module instance.
-
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { SettingItem } from "@earendil-works/pi-tui";
-import {
-  isSettingsContributionCollector,
-  type SettingsScope,
-  type SettingsSection,
-  SUPI_SETTINGS_COLLECT_EVENT,
-} from "../settings/settings-registry.ts";
-import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
-
-// ── Types ──────────────────────────────────────────────────────────────────
-
-/**
- * Supported config value types for declarative persistChange.
- *
- * - `"boolean"`: maps "on" → true, "off" → false
- * - `"number"`: parses integer via Number.parseInt, falls back to unset on invalid
- * - `"stringList"`: splits on comma, trims whitespace, unsets on empty
- */
-export type ConfigSettingType = "boolean" | "number" | "stringList";
-
-/** Extended setting item that can declare its config type for persistence. */
-export interface ConfigSettingItem extends SettingItem {
-  /** Config value type used for auto-generated persistence. */
-  configType?: ConfigSettingType;
-}
-
-/** Helpers provided to persistChange for scoped SuPi config writes. */
-export interface ConfigSettingsHelpers {
-  /** Write a key to the selected scope's config section. */
-  set(key: string, value: unknown): void;
-  /** Remove a key from the selected scope's config section. */
-  unset(key: string): void;
-}
-
-export interface ConfigSettingsPersistedChange {
-  scope: SettingsScope;
-  cwd: string;
-  settingId: string;
-  value: string;
-}
-
-export interface ConfigSettingsOptions<T> {
-  /** Settings contribution identifier — e.g. "lsp", "claude-md". */
-  id: string;
-  /** Human-readable label shown in the UI. */
-  label: string;
-  /** SuPi config section name — e.g. "lsp", "claude-md". */
-  section: string;
-  /** Default config values. */
-  defaults: T;
-  /** Build SettingItem[] from scoped config. */
-  buildItems: (
-    settings: T,
-    scope: SettingsScope,
-    cwd: string,
-    ctx?: ExtensionContext,
-  ) => ConfigSettingItem[];
-  /**
-   * Convert a UI value into scoped SuPi config writes.
-   *
-   * Optional when every item returned by `buildItems` declares `configType`.
-   * Required when any item lacks `configType`.
-   */
-  persistChange?: (
-    scope: SettingsScope,
-    cwd: string,
-    settingId: string,
-    value: string,
-    helpers: ConfigSettingsHelpers,
-  ) => void;
-  /** Optional live runtime sync after successful persistence. */
-  afterPersist?: (change: ConfigSettingsPersistedChange) => void;
-  /** Optional home directory for config resolution (testing). */
-  homeDir?: string;
-}
-
-// ── Auto-generated persistChange ───────────────────────────────────────────
-
-function autoPersistChange(
-  settingId: string,
-  value: string,
-  helpers: ConfigSettingsHelpers,
-  items: ConfigSettingItem[],
-): void {
-  const item = items.find((i) => i.id === settingId);
-  if (!item?.configType) return;
-
-  switch (item.configType) {
-    case "boolean": {
-      helpers.set(settingId, value === "on");
-      break;
-    }
-    case "number": {
-      const num = Number.parseInt(value, 10);
-      if (Number.isFinite(num) && num > 0) {
-        helpers.set(settingId, num);
-      } else {
-        helpers.unset(settingId);
-      }
-      break;
-    }
-    case "stringList": {
-      const names = value
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0);
-      if (names.length > 0) {
-        helpers.set(settingId, names);
-      } else {
-        helpers.unset(settingId);
-      }
-      break;
-    }
-  }
-}
-
-function areAllItemsDeclarative(items: ConfigSettingItem[]): boolean {
-  return items.length > 0 && items.every((i) => i.configType !== undefined);
-}
-
-function createHelpers<T>(options: ConfigSettingsOptions<T>, scope: SettingsScope, cwd: string) {
-  return {
-    set: (key: string, val: unknown) => {
-      writeSupiConfig(
-        { section: options.section, scope, cwd },
-        { [key]: val },
-        { homeDir: options.homeDir },
-      );
-    },
-    unset: (key: string) => {
-      removeSupiConfigKey({ section: options.section, scope, cwd }, key, {
-        homeDir: options.homeDir,
-      });
-    },
-  } satisfies ConfigSettingsHelpers;
-}
-
-function toSettingsSection<T>(options: ConfigSettingsOptions<T>): SettingsSection {
-  let cachedItems: ConfigSettingItem[] | undefined;
-
-  return {
-    id: options.id,
-    label: options.label,
-    loadValues: (scope, cwd, ctx) => {
-      const settings = loadSupiConfigForScope(options.section, cwd, options.defaults, {
-        scope,
-        homeDir: options.homeDir,
-      });
-      const items = options.buildItems(settings, scope, cwd, ctx);
-      cachedItems = items;
-      return items;
-    },
-    persistChange: (scope, cwd, settingId, value) => {
-      const helpers = createHelpers(options, scope, cwd);
-
-      if (options.persistChange) {
-        options.persistChange(scope, cwd, settingId, value, helpers);
-      } else {
-        const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd, undefined);
-        if (!areAllItemsDeclarative(items)) {
-          throw new Error(
-            `Settings contribution "${options.id}" needs persistChange or configType on every item.`,
-          );
-        }
-        autoPersistChange(settingId, value, helpers, items);
-      }
-
-      try {
-        options.afterPersist?.({ scope, cwd, settingId, value });
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Saved setting, but live sync failed: ${message}`, { cause: error });
-      }
-    },
-  };
-}
-
-// ── Registration ───────────────────────────────────────────────────────────
-
-/**
- * Register a config-backed settings contribution for `/supi-settings`.
- *
- * Contributions are collected through PI's process-local event bus. Call this
- * during the extension factory function, not in async session handlers.
- */
-export function registerConfigSettings<T>(
-  pi: ExtensionAPI,
-  options: ConfigSettingsOptions<T>,
-): void {
-  const section = toSettingsSection(options);
-  const dispose = pi.events.on(SUPI_SETTINGS_COLLECT_EVENT, (collector) => {
-    if (isSettingsContributionCollector(collector)) {
-      collector.add(section);
-    }
-  });
-
-  pi.on("session_shutdown", () => {
-    dispose();
-  });
-}