@zokizuan/satori-mcp 4.11.8 → 4.11.16

package/README.md

@@ -4,11 +4,11 @@ Read-only MCP server for Satori. It gives coding agents six deterministic tools
 
 ## Install
 
-Use the CLI installer for normal setup:
+Installer ownership is **`@zokizuan/satori-cli` only** (this package serves MCP tools; it does not install client configs). Use the CLI installer for normal setup:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.6 install --client all
-npx -y @zokizuan/satori-cli@0.4.6 doctor
+npx -y @zokizuan/satori-cli@latest install --client all
+npx -y @zokizuan/satori-cli@latest doctor
 ```
 
 The CLI installer supports `codex`, `claude`, `opencode`, and `all`. It creates the runtime cache, writes the stable launcher, and writes client config for you. Avoid using `npx` as the resident MCP server command; first-run package resolution can exceed normal MCP startup timeouts.
@@ -16,7 +16,7 @@ The CLI installer supports `codex`, `claude`, `opencode`, and `all`. It creates
 Use `--profile default|minimal|all-text` to write repo-local `satori.toml` during install:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.6 install --client all --profile minimal
+npx -y @zokizuan/satori-cli@latest install --client all --profile minimal
 ```
 
 Profiles control indexing breadth, not search scope. `default` is safe-broad, `minimal` indexes source plus docs/text, and `all-text` indexes additional UTF-8 text files under the size limit. `search_codebase` still defaults to `scope=runtime`.
@@ -45,7 +45,7 @@ For Codex, add `--install-guidance-hook` only when you want an installer-managed
 Advanced direct execution is available through the package bin:
 
 ```bash
-npx -y @zokizuan/satori-mcp@4.11.8 --help
+npx -y @zokizuan/satori-mcp@4.11.16 --help
 ```
 
 Use direct package execution for inspection, smoke tests, or unsupported harnesses. For supported clients, prefer `satori-cli install` so startup does not depend on package-manager resolution.
@@ -63,16 +63,21 @@ read_file path="/absolute/path/to/repo/src/auth.ts" start_line=1 end_line=160
 
 Important defaults:
 
-- `search_codebase` starts with runtime code, grouped by symbol.
-- `search_codebase` runs freshness checks before returning results.
+- Public paths for tools are **absolute filesystem paths**. Relative paths are rejected (not CWD-resolved).
+- `search_codebase` starts with `scope=runtime`, `resultMode=grouped`, `groupBy=symbol`, `rankingMode=auto_changed_first`.
+- `search_codebase` is the sync-on-read freshness tool; other tools may gate compatibility but do not replace it.
 - Grouped search is symbol-owned: chunks are supporting evidence for an owner symbol, not the final navigation unit.
 - Exact symbol navigation uses `symbolInstanceId`. `symbolKey` is stable-ish candidate lookup only, not exact identity.
+- Ready/`indexed` means searchable-readable, not automatically symbol-rich. Check `manage_index status` `symbolQuality` or Ready-line `symbolQuality=…` before treating outline/graph as rich navigation evidence (`symbol_rich` \| `mixed` \| `symbol_sparse` \| `search_only` \| `unknown` — observed registry evidence, not a parser diagnosis).
 - Index profiles still honor `.satoriignore`, `.gitignore`, `satori.toml`, and the hard denylist for secrets, lockfiles, generated output, dependencies, binaries, bundles, logs, and database dumps.
-- `read_file` is bounded and can return continuation hints.
-- `requires_reindex` means reindex first, then retry the original call.
-- `manage_index action="clear"` is destructive and should be explicit.
-- After changing `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, embedding dimension, `HYBRID_MODE`, vector backend settings, or the Satori runtime version, restart all Satori MCP clients before running `manage_index create`, `reindex`, `sync`, or `clear`.
-- Satori records live runtime owners in `~/.satori/runtime/owners.json` and blocks those index mutations with `status="blocked"` / `reason="runtime_owner_conflict"` if another live Satori MCP runtime has a different fingerprint, package version, or config identity. MCP tools do not kill processes or ask interactive cleanup questions.
+- `read_file` only reads under tracked searchable roots (`indexed` / `sync_completed`); it is not a general host filesystem reader. Relative paths and root escapes are denied.
+- Prefer `recommendedNextAction` when present; if `callGraphHint.supported=false`, follow `navigationFallback` args rather than inventing spans.
+- `requires_reindex` means reindex first, then retry the original call (do not substitute `sync`).
+- `manage_index action="clear"` is destructive and should be explicit. `repair` only rebuilds local readiness when vector payload and trusted fingerprint proof match; otherwise use create/reindex.
+- After changing `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, embedding dimension, `HYBRID_MODE`, vector backend settings, or the Satori runtime version, restart **all** Satori MCP clients before running `manage_index create`, `reindex`, `sync`, `clear`, or `repair`.
+- Satori records live runtime owners in `~/.satori/runtime/owners.json` and blocks those index mutations with `status="blocked"` / `reason="runtime_owner_conflict"` if another live Satori MCP runtime has a different fingerprint, package version, or config identity.
+- On `runtime_owner_conflict`, the manage envelope lists conflicting **pids**, **versions**, and conflict reasons, plus a concrete `hints.nextStep`. MCP tools never kill other processes. Stop the listed host clients (or only orphaned Satori MCP node PIDs), leave a single package version/config running, then retry. `manage_index status` and `list_codebases` also show a compact **Runtime owners** line (live pids/versions); multi-version means mutations may block. `satori-cli doctor` reports multi-version live owners.
+- Grouped `search_codebase` results with supported call graph attach **`inboundRecovery`**: a ready-to-run `must:` search to verify callers before blast-radius edits (`call_graph` inbound stays advisory/low).
 
 ## Navigation Sidecars
 
@@ -81,7 +86,7 @@ Completed full indexes write a derived symbol registry and relationship sidecar.
 - The symbol registry stores candidate owner keys, exact symbol instances, file-owner fallback symbols, and outline records used by grouped search, `file_outline`, and exact reads.
 - The relationship sidecar stores conservative `CALLS v0` edges plus TypeScript/JavaScript `IMPORTS`/`EXPORTS v0` edges with manifest compatibility gates.
 - Runtime navigation still serves canonical JSON sidecars by default. When the default shared runtime store is created at process startup, `SATORI_NAVIGATION_BACKEND=sqlite` can opt that shared store into SQLite-backed reads only after SQLite proves parity with the canonical JSON symbol registry and relationship sidecars. If canonical JSON is missing or incompatible, SQLite is not served as truth; if SQLite is missing, stale, incompatible, or parity-mismatched while JSON is compatible, runtime falls back to JSON with a warning. When the default shared runtime store is created with `SATORI_NAVIGATION_DUAL_READ=1`, JSON remains the serving backend and the runtime emits once-per-root parity mismatch warnings without changing the served result.
-- `CALLS v0` is heuristic/name-based. Same-file unique targets can be high confidence, cross-file name-only targets start low confidence, and ambiguous same-name targets are skipped.
+- `CALLS v0` is heuristic/name-based. Same-file unique targets can be high confidence; cross-file name-only targets start low and are upgraded when IMPORTS/EXPORTS evidence supports them, or when the imported file has a unique same-name target (class methods without top-level EXPORTS). Generic names like `push`/`get` stay suppressed without EXPORTS. Ambiguous same-name targets are skipped.
 - `IMPORTS`/`EXPORTS v0` records only resolvable relative module edges and unambiguous local export declarations. Package imports, unresolved paths, ambiguous exports, and multiline module syntax are skipped.
 - `call_graph` uses compatible relationship sidecars as the canonical source for symbol-owned traversal.
 - Successful incremental sync reuses changed-file symbol output, preserves unchanged registry state, and recomputes relationships against the merged registry without re-splitting unchanged files. If changed-file indexing stops early, navigation state is cleared instead of publishing a mixed generation.
@@ -103,7 +108,7 @@ Users who want literal values in a client config can replace the generated pass-
 ```toml
 [mcp_servers.satori.env]
 EMBEDDING_PROVIDER = "VoyageAI"
-EMBEDDING_MODEL = "voyage-4-large"
+EMBEDDING_MODEL = "voyage-code-3"
 EMBEDDING_OUTPUT_DIMENSION = "1024"
 VOYAGEAI_API_KEY = "pa-..."
 VOYAGEAI_RERANKER_MODEL = "rerank-2.5"
@@ -115,7 +120,7 @@ Cloud-quality setup:
 
 ```bash
 EMBEDDING_PROVIDER=VoyageAI
-EMBEDDING_MODEL=voyage-4-large
+EMBEDDING_MODEL=voyage-code-3
 EMBEDDING_OUTPUT_DIMENSION=1024
 VOYAGEAI_API_KEY=your-api-key
 VOYAGEAI_RERANKER_MODEL=rerank-2.5
@@ -131,12 +136,12 @@ The full generated tool reference below is kept in the npm README for MCP client
 
 ### `manage_index`
 
-Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action="status" to observe progress.
+Manage index lifecycle operations (create/reindex/sync/status/clear/repair) for a codebase path. repair rebuilds local readiness only when existing vector payload and trusted runtime fingerprint proof match; otherwise it refuses and asks for create/reindex. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action="status" to observe progress.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `action` | enum("create", "reindex", "sync", "status", "clear") | yes |  | Required operation to run. |
-| `path` | string | yes |  | ABSOLUTE path to the target codebase. |
+| `action` | enum("create", "reindex", "sync", "status", "clear", "repair") | yes |  | Required operation to run. |
+| `path` | string | yes |  | ABSOLUTE filesystem path to the target codebase (relative paths are rejected). |
 | `force` | boolean | no |  | Only for action='create'. Force rebuild from scratch. |
 | `allowUnnecessaryReindex` | boolean | no |  | Only for action='reindex'. Override preflight block when reindex is detected as unnecessary ignore-only churn. |
 | `customExtensions` | array<string> | no |  | Only for action='create'. Additional file extensions to include. |
@@ -149,9 +154,9 @@ Unified semantic search with runtime-first defaults (start with scope="runtime")
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `path` | string | yes |  | ABSOLUTE path to an indexed codebase or subdirectory. |
+| `path` | string | yes |  | ABSOLUTE filesystem path to an indexed codebase or subdirectory (relative paths are rejected). |
 | `query` | string | yes |  | Natural-language query. |
-| `scope` | enum("runtime", "mixed", "docs") | no | `"runtime"` | Search scope policy. runtime includes source/runtime code and tests while excluding docs/generated/artifacts/landing/fixtures; docs returns docs/tests only; mixed includes all. Docs scope skips reranker by policy in the current tool surface. |
+| `scope` | enum("runtime", "mixed", "docs") | no | `"runtime"` | Search scope policy. runtime includes source/runtime code and tests while excluding docs/generated/artifacts/landing/fixtures; docs returns documentation paths only (not tests); mixed includes all. Docs scope skips reranker by policy in the current tool surface. |
 | `resultMode` | enum("grouped", "raw") | no | `"grouped"` | Output mode. grouped returns merged search groups, raw returns chunk hits. |
 | `groupBy` | enum("symbol", "file") | no | `"symbol"` | Grouping strategy in grouped mode. |
 | `rankingMode` | enum("default", "auto_changed_first") | no | `"auto_changed_first"` | Ranking policy. auto_changed_first boosts files changed in the current git working tree when available. |
@@ -160,11 +165,11 @@ Unified semantic search with runtime-first defaults (start with scope="runtime")
 
 ### `call_graph`
 
-Traverse registry-resolved caller/callee relationships for indexed TS/JS/Python code. On symbol-owned indexes, call_graph uses compatible relationship sidecars for conservative CALLS v0 traversal and upgrades low-confidence cross-file calls only when current IMPORTS/EXPORTS evidence deterministically supports the target symbol. In successful traversal responses, sidecar.nodeCount and sidecar.edgeCount report the counts returned in that response, not whole-sidecar totals for the indexed codebase.
+Traverse registry-resolved caller/callee relationships for indexed TS/JS/Python code. Relationship-backed CALLS v0 is heuristic and name-based (not a compiler-grade call graph): unique same-file name matches are high confidence; cross-file edges stay low unless IMPORTS/EXPORTS evidence upgrades them, or an imported module has a unique same-name target (e.g. class methods without a top-level EXPORTS record; generic names like push/get stay suppressed). Traversal is bounded (depth/limit) and incomplete by design—empty or short edge lists are not proof of “no callers.” Output is advisory navigation context, not authoritative blast-radius proof; confirm impact with search_codebase, read_file, tests, and references before editing. In successful traversal responses, sidecar.nodeCount and sidecar.edgeCount report counts returned in that response, not whole-sidecar totals.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `path` | string | yes |  | ABSOLUTE path to the indexed codebase root (or subdirectory). |
+| `path` | string | yes |  | ABSOLUTE filesystem path to the indexed codebase root or subdirectory (relative paths are rejected). |
 | `symbolRef` | object | yes |  | Symbol reference from a grouped search result callGraphHint. |
 | `direction` | enum("callers", "callees", "both") | no | `"both"` | Traversal direction from the starting symbol. |
 | `depth` | integer | no | `1` | Traversal depth (max 3). |
@@ -176,8 +181,8 @@ Return a sidecar-backed symbol outline for one file, including call_graph jump h
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `path` | string | yes |  | ABSOLUTE path to the indexed codebase root. |
-| `file` | string | yes |  | Relative file path inside the codebase root. |
+| `path` | string | yes |  | ABSOLUTE filesystem path to the indexed codebase root (relative paths are rejected). |
+| `file` | string | yes |  | Repo-relative file path inside the codebase root (not absolute; resolved only against that root). |
 | `start_line` | integer | no |  | Optional start line filter (1-based, inclusive). |
 | `end_line` | integer | no |  | Optional end line filter (1-based, inclusive). |
 | `limitSymbols` | integer | no | `500` | Maximum number of returned symbols after line filtering. |
@@ -187,11 +192,11 @@ Return a sidecar-backed symbol outline for one file, including call_graph jump h
 
 ### `read_file`
 
-Read file content from the local filesystem, with optional 1-based inclusive line ranges and safe truncation.
+Read file content under an indexed/searchable Satori codebase root only (not a general host filesystem reader). Requires an absolute path whose canonical real path is inside a tracked root with status indexed or sync_completed. Supports optional 1-based inclusive line ranges and safe truncation.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `path` | string | yes |  | ABSOLUTE path to the file. |
+| `path` | string | yes |  | ABSOLUTE path to the file under an indexed/searchable codebase root (relative paths are rejected). |
 | `start_line` | integer | no |  | Optional start line (1-based, inclusive). |
 | `end_line` | integer | no |  | Optional end line (1-based, inclusive). |
 | `mode` | enum("plain", "annotated") | no | `"plain"` | Output mode. plain returns text only; annotated returns content plus sidecar-backed outline metadata. |

package/dist/cli/args.d.ts

@@ -19,16 +19,6 @@ export type ParsedCommand = {
     kind: "help";
 } | {
     kind: "version";
-} | {
-    kind: "install";
-    client: InstallClient;
-    dryRun: boolean;
-    installGuidanceHook: boolean;
-    profile?: InstallProfile;
-} | {
-    kind: "uninstall";
-    client: InstallClient;
-    dryRun: boolean;
 } | {
     kind: "tools-list";
 } | {
@@ -49,8 +39,9 @@ export interface ResolveRawArgsOptions {
     stdin?: NodeJS.ReadStream;
     stdinTimeoutMs: number;
 }
-export type InstallClient = "all" | "claude" | "codex" | "opencode";
-export type InstallProfile = "default" | "minimal" | "all-text";
+/** Hard-deprecation messages only — no installer work, no config writes. */
+export declare const MCP_INSTALL_USE_SATORI_CLI_MESSAGE = "Install is owned by @zokizuan/satori-cli. Use: npx -y @zokizuan/satori-cli@latest install --client <client>";
+export declare const MCP_UNINSTALL_USE_SATORI_CLI_MESSAGE = "Uninstall is owned by @zokizuan/satori-cli. Use: npx -y @zokizuan/satori-cli@latest uninstall --client <client>";
 export declare function parseCliArgs(argv: string[]): ParsedCliInput;
 export declare function resolveRawArguments(rawArgsMode: RawArgsMode, options: ResolveRawArgsOptions): Promise<Record<string, unknown>>;
 export declare function parseWrapperArgumentsFromSchema(toolName: string, inputSchema: unknown, wrapperArgs: string[]): Record<string, unknown>;

package/dist/cli/args.js

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import { CliError } from "./errors.js";
+/** Installer SSOT is packages/cli (satori-cli). MCP CLI keeps these reserved so they never become tool wrappers. */
 const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version", "install", "uninstall"]);
+/** Hard-deprecation messages only — no installer work, no config writes. */
+export const MCP_INSTALL_USE_SATORI_CLI_MESSAGE = "Install is owned by @zokizuan/satori-cli. Use: npx -y @zokizuan/satori-cli@latest install --client <client>";
+export const MCP_UNINSTALL_USE_SATORI_CLI_MESSAGE = "Uninstall is owned by @zokizuan/satori-cli. Use: npx -y @zokizuan/satori-cli@latest uninstall --client <client>";
 const PRIMITIVE_TYPES = new Set(["string", "number", "integer", "boolean"]);
 function isWrapperJsonSchema(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -112,45 +116,6 @@ function parseRawArgsMode(args) {
     }
     return { rawArgsMode, remaining };
 }
-function parseInstallCommand(kind, args) {
-    let client = "all";
-    let dryRun = false;
-    let installGuidanceHook = false;
-    let profile;
-    for (let i = 0; i < args.length; i += 1) {
-        const token = args[i];
-        if (token === "--client") {
-            const next = args[i + 1];
-            if (next !== "all" && next !== "claude" && next !== "codex" && next !== "opencode") {
-                throw new CliError("E_USAGE", "--client must be one of: all, claude, codex, opencode.", 2);
-            }
-            client = next;
-            i += 1;
-            continue;
-        }
-        if (token === "--dry-run") {
-            dryRun = true;
-            continue;
-        }
-        if (kind === "install" && token === "--install-guidance-hook") {
-            installGuidanceHook = true;
-            continue;
-        }
-        if (kind === "install" && token === "--profile") {
-            const next = args[i + 1];
-            if (next !== "default" && next !== "minimal" && next !== "all-text") {
-                throw new CliError("E_USAGE", "--profile must be one of: default, minimal, all-text.", 2);
-            }
-            profile = next;
-            i += 1;
-            continue;
-        }
-        throw new CliError("E_USAGE", `Unknown arguments for ${kind}: ${args.slice(i).join(" ")}`, 2);
-    }
-    return kind === "install"
-        ? { kind, client, dryRun, installGuidanceHook, profile }
-        : { kind, client, dryRun };
-}
 export function parseCliArgs(argv) {
     const { globals, rest } = parseGlobalOptions(argv);
     if (rest.length === 0 || rest[0] === "help" || rest.includes("--help") || rest.includes("-h")) {
@@ -166,16 +131,10 @@ export function parseCliArgs(argv) {
         };
     }
     if (rest[0] === "install") {
-        return {
-            globals,
-            command: parseInstallCommand("install", rest.slice(1))
-        };
+        throw new CliError("E_USAGE", MCP_INSTALL_USE_SATORI_CLI_MESSAGE, 2);
     }
     if (rest[0] === "uninstall") {
-        return {
-            globals,
-            command: parseInstallCommand("uninstall", rest.slice(1))
-        };
+        throw new CliError("E_USAGE", MCP_UNINSTALL_USE_SATORI_CLI_MESSAGE, 2);
     }
     if (rest[0] === "tools") {
         if (rest.length === 2 && rest[1] === "list") {

package/dist/cli/index.d.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import { type CallToolResult, type ListToolsResult } from "./client.js";
-import { type ManagedRuntimeCommand } from "./install.js";
 interface RunCliOptions {
     writeStdout?: (text: string) => void;
     writeStderr?: (text: string) => void;
@@ -12,8 +11,6 @@ interface RunCliOptions {
     startupTimeoutMs?: number;
     callTimeoutMs?: number;
     cwd?: string;
-    installabilityVerifier?: () => string | Promise<string>;
-    installRuntimeCommand?: ManagedRuntimeCommand;
     connectSession?: (options: {
         command: string;
         args: string[];

package/dist/cli/index.js

@@ -6,8 +6,6 @@ import { parseCliArgs, parseWrapperArgumentsFromSchema, resolveRawArguments } fr
 import { connectCliMcpSession } from "./client.js";
 import { asCliError, CliError } from "./errors.js";
 import { emitError, emitJson, parseStructuredEnvelope } from "./format.js";
-import { executeInstallCommand } from "./install.js";
-import { verifyManagedPackageInstallability } from "./package-installability.js";
 import { resolveServerEntryPath } from "./resolve-server-entry.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null;
@@ -44,15 +42,14 @@ function resolveDefaultServerArgs() {
 }
 function buildHelpPayload() {
     return {
-        usage: "satori-cli <command>",
+        usage: "satori <command> (tool shell; install via satori-cli)",
         commands: [
-            "install [--client all|codex|claude|opencode] [--profile default|minimal|all-text] [--dry-run] [--install-guidance-hook]",
-            "uninstall [--client all|codex|claude|opencode] [--dry-run]",
             "tools list",
             "tool call <toolName> --args-json '<json>'",
             "tool call <toolName> --args-file <path>",
             "<toolName> [schema-driven flags]"
         ],
+        install: "npx -y @zokizuan/satori-cli@latest install --client all",
         globalFlags: [
             "--startup-timeout-ms <n>",
             "--call-timeout-ms <n>",
@@ -155,22 +152,6 @@ export async function runCli(argv, options = {}) {
             }
             return 0;
         }
-        if (parsed.command.kind === "install" || parsed.command.kind === "uninstall") {
-            let packageSpecifier;
-            if (parsed.command.kind === "install") {
-                packageSpecifier = await (options.installabilityVerifier || verifyManagedPackageInstallability)();
-            }
-            const result = executeInstallCommand(parsed.command, {
-                homeDir: effectiveEnv.HOME,
-                packageSpecifier,
-                runtimeCommand: options.installRuntimeCommand,
-            });
-            emitJson(writers, result);
-            if (parsed.globals.format === "text") {
-                writers.writeStderr(`satori-cli ${parsed.command.kind} completed for ${parsed.command.client}.\n`);
-            }
-            return 0;
-        }
         const session = await (options.connectSession || connectCliMcpSession)({
             command: options.serverCommand || process.execPath,
             args: options.serverArgs || resolveDefaultServerArgs(),

package/dist/config.d.ts

@@ -3,6 +3,8 @@ export type VectorStoreProvider = 'Milvus';
 export type FingerprintSource = 'verified' | 'assumed_v2';
 export declare const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 export declare const DEFAULT_MANAGE_RETRY_AFTER_MS = 2000;
+/** Package version from packages/mcp/package.json (not the stale historical default 1.0.0). */
+export declare function resolveMcpPackageVersion(): string;
 export interface IndexFingerprint {
     embeddingProvider: EmbeddingProvider;
     embeddingModel: string;
@@ -54,6 +56,7 @@ export interface CodebaseSnapshotV1 {
 }
 interface CodebaseInfoBase {
     lastUpdated: string;
+    collectionName?: string;
     indexFingerprint?: IndexFingerprint;
     fingerprintSource?: FingerprintSource;
     reindexReason?: 'legacy_unverified_fingerprint' | 'fingerprint_mismatch' | 'missing_fingerprint' | 'navigation_recovery_failed';

package/dist/config.js

@@ -1,13 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { envManager } from "@zokizuan/satori-core";
 export const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 export const DEFAULT_MANAGE_RETRY_AFTER_MS = 2000;
+/** Package version from packages/mcp/package.json (not the stale historical default 1.0.0). */
+export function resolveMcpPackageVersion() {
+    try {
+        const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const raw = fs.readFileSync(packageJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+            return parsed.version.trim();
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0";
+}
 // Helper function to get default model for each provider
 export function getDefaultModelForProvider(provider) {
     switch (provider) {
         case 'OpenAI':
             return 'text-embedding-3-small';
         case 'VoyageAI':
-            return 'voyage-4-large';
+            return 'voyage-code-3';
         case 'Gemini':
             return 'gemini-embedding-001';
         case 'Ollama':
@@ -106,7 +124,7 @@ export function createMcpConfig() {
     }
     const config = {
         name: envManager.get('MCP_SERVER_NAME') || "Satori MCP Server",
-        version: envManager.get('MCP_SERVER_VERSION') || "1.0.0",
+        version: envManager.get('MCP_SERVER_VERSION') || resolveMcpPackageVersion(),
         // Embedding provider configuration
         encoderProvider: defaultProvider,
         encoderModel: getEmbeddingModelForProvider(defaultProvider),
@@ -209,13 +227,13 @@ Environment Variables:
 
 Examples:
   # Install resident MCP config without package-manager startup on every client launch
-  npx -y @zokizuan/satori-cli@0.4.6 install --client all
+  npx -y @zokizuan/satori-cli@latest install --client all
 
   # Start MCP server with OpenAI and explicit Milvus address
   OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 satori
 
   # Start MCP server with VoyageAI and specific model
-  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token satori
+  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-code-3 MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token satori
 
   # Start MCP server with Gemini and specific model
   EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token satori

package/dist/core/backend-diagnostics.js

@@ -36,7 +36,7 @@ function createVectorBackendDiagnostic(code) {
         case "ZILLIZ_CLUSTER_STOPPED":
             return {
                 code,
-                message: "Vector backend is unavailable because the Zilliz Cloud cluster is stopped.",
+                message: "Zilliz Cloud cluster is stopped. Resume it in Zilliz Cloud, then retry the tool call.",
                 hints: {
                     backend: {
                         code,
@@ -101,13 +101,16 @@ function createVectorBackendDiagnostic(code) {
         case "VECTOR_BACKEND_CONNECTION_CLOSED":
             return {
                 code,
-                message: "Vector backend connection closed before the tool call completed.",
+                message: "Vector backend connection closed before the tool call completed. Check backend health, provider environment, network connectivity, or an MCP process restart in the previous log lines.",
                 hints: {
                     backend: {
                         code,
                         provider: "unknown",
                         retryable: true,
                         nextSteps: [
+                            "If the previous response mentions ZILLIZ_CLUSTER_STOPPED, resume the Zilliz cluster at https://cloud.zilliz.com.",
+                            "If the previous response mentions MISSING_PROVIDER_CONFIG, set the missing env values in the MCP client environment and restart the client.",
+                            "For non-Zilliz Milvus-compatible backends, confirm the service is running and reachable at MILVUS_ADDRESS.",
                             "Retry the MCP tool call after confirming the backend is healthy.",
                             "Restart the MCP client/session if the MCP process exited after the transport failure.",
                         ],

package/dist/core/call-graph.d.ts

@@ -84,6 +84,8 @@ export interface CallGraphResponseSupported {
         nodeCount: number;
         edgeCount: number;
     };
+    /** Executable recovery steps when graph evidence is incomplete (e.g. notes-only inbound). */
+    hints?: Record<string, unknown>;
 }
 export type CallGraphQueryResponse = CallGraphResponseSupported | CallGraphResponseUnsupported;
 export interface CallGraphDeltaPolicy {

package/dist/core/handlers.d.ts

@@ -7,7 +7,7 @@ import { FileOutlineInput } from "./search-types.js";
 import { CallGraphSidecarManager } from "./call-graph.js";
 import { type ReindexPreflightResult } from "./working-tree-state.js";
 import { type SearchDiagnostics } from "./search-execution.js";
-import type { RuntimeOwnerMutationGate } from "./runtime-owner.js";
+import { type RuntimeOwnerMutationGate } from "./runtime-owner.js";
 type IndexCodebaseArgs = {
     path: string;
     force?: boolean;
@@ -58,6 +58,8 @@ export declare class ToolHandlers {
     private buildReindexInstruction;
     private buildReindexHint;
     private buildCreateHint;
+    private buildSyncHint;
+    private buildRepairHint;
     private buildManageIndexRecommendedAction;
     private buildStatusHint;
     private buildManageRequiresReindexHints;
@@ -83,9 +85,9 @@ export declare class ToolHandlers {
     private getContextActiveIgnorePatterns;
     private getContextIndexedExtensions;
     private getContextTrackedRelativePaths;
-    private writeIndexCompletionMarker;
     private clearIndexCompletionMarker;
     private pruneIndexedCollectionFamily;
+    private pruneUnprovenStagedCollectionFamily;
     private markCodebaseCleared;
     private stringifyToolJson;
     private buildRuntimeOwnerConflictResponseIfBlocked;
@@ -96,11 +98,14 @@ export declare class ToolHandlers {
     private buildManageActionBlockedMessage;
     private getManageRetryAfterMs;
     private buildStaleLocalHint;
+    private getSnapshotCollectionName;
+    private canSyncStaleLocal;
     private buildStaleLocalMessage;
     private withProofDebugHint;
     private validateCompletionProof;
     private extractIndexedRecoveryFromCompletionProof;
     private recoverIndexedSnapshotFromCompletionProof;
+    private getActiveIndexedCollectionNameForSnapshotRecovery;
     private refreshSnapshotStateFromDisk;
     private isPathWithinCodebase;
     private getTrackedRootEntryForPath;
@@ -181,6 +186,13 @@ export declare class ToolHandlers {
         }>;
         isError?: boolean;
     }>;
+    handleRepairIndex(args: ToolArgs): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
     handleSearchCode(args: ToolArgs): Promise<{
         content: {
             type: string;