@zokizuan/satori-mcp 4.4.0 → 4.4.1

package/README.md

@@ -17,7 +17,7 @@ MCP server for Satori — agent-safe semantic code search and indexing.
 - Zod-first tool schemas converted to MCP JSON Schema for `ListTools`
 - Auto-generated tool docs from live tool schemas
 - `read_file` line-range retrieval with default large-file truncation guard and optional `mode="annotated"` metadata envelope
-- Optional proactive sync watcher mode (debounced filesystem events)
+- Optional proactive sync watcher mode (debounced filesystem events for explicitly touched roots in the current session)
 - Index-time AST scope breadcrumbs (TS/JS/Python) rendered in search output as `🧬 Scope`
 - Fingerprint schema `dense_v3`/`hybrid_v3` with hard gate for all pre-v3 indexes
 
@@ -46,6 +46,7 @@ Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposi
 
 - Enabled by default. Set `MCP_ENABLE_WATCHER=false` to disable
 - Debounce window via `MCP_WATCH_DEBOUNCE_MS` (default `5000`)
+- Watchers are session-scoped: startup does not watch every indexed codebase, only roots touched by successful index/search/navigation/read flows in the current session
 - Watch events reuse the same incremental sync pipeline (`reindexByChange`)
 - Ignore control files (`.satoriignore`, root `.gitignore`) trigger no-reindex reconciliation:
   - delete indexed paths now ignored by active rules
@@ -156,7 +157,7 @@ No parameters.
   "mcpServers": {
     "satori": {
       "command": "npx",
-      "args": ["-y", "@zokizuan/satori-mcp@latest"],
+      "args": ["-y", "@zokizuan/satori-mcp@4.4.1"],
       "timeout": 180000,
       "env": {
         "EMBEDDING_PROVIDER": "VoyageAI",
@@ -177,7 +178,7 @@ No parameters.
 ```toml
 [mcp_servers.satori]
 command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@latest"]
+args = ["-y", "@zokizuan/satori-mcp@4.4.1"]
 startup_timeout_ms = 180000
 env = { EMBEDDING_PROVIDER = "VoyageAI", EMBEDDING_MODEL = "voyage-4-large", EMBEDDING_OUTPUT_DIMENSION = "1024", VOYAGEAI_API_KEY = "your-api-key", VOYAGEAI_RERANKER_MODEL = "rerank-2.5", MILVUS_ADDRESS = "your-milvus-endpoint", MILVUS_TOKEN = "your-milvus-token" }
 ```
@@ -213,9 +214,30 @@ Never commit real API keys/tokens into repo config files.
 pnpm --filter @zokizuan/satori-mcp start
 ```
 
-## Shell CLI (`satori-cli`)
+## Shell CLI (`@zokizuan/satori-cli`)
 
-`@zokizuan/satori-mcp` also ships a shell-first client binary that works without an MCP adapter.
+The shell-first installer/client now lives in a separate package: `@zokizuan/satori-cli`.
+
+### Install / Uninstall
+
+Supported installer targets in Phase 1:
+- `codex`
+- `claude`
+- `all`
+
+Examples:
+
+```bash
+npx -y @zokizuan/satori-cli@0.1.1 install --client codex
+npx -y @zokizuan/satori-cli@0.1.1 install --client claude
+npx -y @zokizuan/satori-cli@0.1.1 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.1.1 uninstall --client codex
+```
+
+Install and uninstall run before MCP session startup, only touch Satori-managed config, and copy/remove these packaged skills:
+- `satori-search`
+- `satori-navigation`
+- `satori-indexing`
 
 ### Commands
 
@@ -271,6 +293,8 @@ pnpm --filter @zokizuan/satori-mcp build
 pnpm --filter @zokizuan/satori-mcp typecheck
 pnpm --filter @zokizuan/satori-mcp test
 pnpm --filter @zokizuan/satori-mcp docs:check
+pnpm --filter @zokizuan/satori-cli build
+pnpm --filter @zokizuan/satori-cli test
 ```
 
 `build` automatically runs docs generation from tool schemas.

package/dist/cli/client.js

@@ -39,6 +39,7 @@ export class CliMcpSession {
         return createTimeout(this.client.callTool({ name, arguments: args }), this.callTimeoutMs, "E_CALL_TIMEOUT", `Timed out after ${this.callTimeoutMs}ms while calling tools/call for '${name}'.`);
     }
     async close() {
+        const stderr = this.transport.stderr;
         try {
             await this.client.close();
         }
@@ -51,6 +52,7 @@ export class CliMcpSession {
         catch {
             // Best-effort close.
         }
+        stderr?.removeAllListeners("data");
     }
     logProtocolFailure(error) {
         if (error instanceof CliError) {
@@ -79,7 +81,7 @@ export async function connectCliMcpSession(options) {
     });
     const client = new Client({
         name: "satori-cli",
-        version: "1.1.0",
+        version: "1.1.1",
     });
     const session = new CliMcpSession(client, transport, options.callTimeoutMs, options.writeStderr);
     session.wireStderr();

package/dist/cli/index.d.ts

@@ -10,6 +10,21 @@ interface RunCliOptions {
     startupTimeoutMs?: number;
     callTimeoutMs?: number;
     cwd?: string;
+    installabilityVerifier?: () => string | Promise<string>;
+    connectSession?: (options: {
+        command: string;
+        args: string[];
+        env: Record<string, string | undefined>;
+        cwd?: string;
+        startupTimeoutMs: number;
+        callTimeoutMs: number;
+        writeStderr: (text: string) => void;
+    }) => Promise<CliSession>;
+}
+interface CliSession {
+    listTools(): Promise<any>;
+    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    close(): Promise<void>;
 }
 export declare function runCli(argv: string[], options?: RunCliOptions): Promise<number>;
 export declare function isExecutedDirectlyForPaths(moduleUrl: string, entryPath: string | undefined): boolean;

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import { connectCliMcpSession } from "./client.js";
 import { asCliError, CliError } from "./errors.js";
 import { emitError, emitJson, inferManageStatusState, parseStructuredEnvelope } from "./format.js";
 import { executeInstallCommand } from "./install.js";
+import { verifyManagedPackageInstallability } from "./package-installability.js";
 import { resolveServerEntryPath } from "./resolve-server-entry.js";
 const MANAGE_INDEX_MIN_POLL_TIMEOUT_MS = 10 * 60 * 1000;
 function firstText(result) {
@@ -195,6 +196,9 @@ export async function runCli(argv, options = {}) {
             return 0;
         }
         if (parsed.command.kind === "install" || parsed.command.kind === "uninstall") {
+            if (parsed.command.kind === "install") {
+                await (options.installabilityVerifier || verifyManagedPackageInstallability)();
+            }
             const result = executeInstallCommand(parsed.command, {
                 homeDir: effectiveEnv.HOME,
             });
@@ -204,7 +208,7 @@ export async function runCli(argv, options = {}) {
             }
             return 0;
         }
-        const session = await connectCliMcpSession({
+        const session = await (options.connectSession || connectCliMcpSession)({
             command: options.serverCommand || process.execPath,
             args: options.serverArgs || resolveDefaultServerArgs(),
             env: {

package/dist/cli/install.js

@@ -69,7 +69,7 @@ function buildCodexManagedBlock(packageSpecifier) {
         MANAGED_BLOCK_START,
         "[mcp_servers.satori]",
         'command = "npx"',
-        `args = ["-y", "${packageSpecifier}"]`,
+        `args = ["-y", "--package", "${packageSpecifier}", "satori"]`,
         `startup_timeout_ms = ${MANAGED_TIMEOUT_MS}`,
         MANAGED_BLOCK_END,
         "",
@@ -153,7 +153,7 @@ function parseJsonObject(filePath) {
 function buildClaudeServerConfig(packageSpecifier) {
     return {
         command: "npx",
-        args: ["-y", packageSpecifier],
+        args: ["-y", "--package", packageSpecifier, "satori"],
         timeout: MANAGED_TIMEOUT_MS,
     };
 }
@@ -168,12 +168,14 @@ function isManagedClaudeEntry(value) {
     if (entry.timeout !== MANAGED_TIMEOUT_MS) {
         return false;
     }
-    if (!Array.isArray(entry.args) || entry.args.length !== 2) {
+    if (!Array.isArray(entry.args) || entry.args.length !== 4) {
         return false;
     }
     return entry.args[0] === "-y"
-        && typeof entry.args[1] === "string"
-        && /^@zokizuan\/satori-mcp@.+$/.test(entry.args[1]);
+        && entry.args[1] === "--package"
+        && typeof entry.args[2] === "string"
+        && /^@zokizuan\/satori-mcp@.+$/.test(entry.args[2])
+        && entry.args[3] === "satori";
 }
 function prepareClaudeInstall(filePath, packageSpecifier) {
     const currentObject = parseJsonObject(filePath);

package/dist/cli/package-installability.d.ts

@@ -0,0 +1,14 @@
+import { execFileSync } from "node:child_process";
+type ExecFileSyncLike = typeof execFileSync;
+export interface PackageInstallabilityOptions {
+    packageJsonPath?: string;
+    execFileSyncImpl?: ExecFileSyncLike;
+}
+export interface ReleaseSmokeOptions extends PackageInstallabilityOptions {
+    packageRoot?: string;
+    tempDir?: string;
+}
+export declare function verifyManagedPackageInstallability(options?: PackageInstallabilityOptions): string;
+export declare function runPublishedPackageReleaseSmoke(options?: ReleaseSmokeOptions): void;
+export {};
+//# sourceMappingURL=package-installability.d.ts.map

package/dist/cli/package-installability.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./errors.js";
+function resolveDefaultPackageJsonPath() {
+    const currentFile = fileURLToPath(import.meta.url);
+    return path.resolve(path.dirname(currentFile), "..", "..", "package.json");
+}
+function readPackageJson(packageJsonPath) {
+    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+}
+function looksLikeExactVersion(value) {
+    return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value);
+}
+function npmOutput(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const stdout = "stdout" in error && typeof error.stdout === "string"
+        ? error.stdout
+        : "";
+    const stderr = "stderr" in error && typeof error.stderr === "string"
+        ? error.stderr
+        : "";
+    return `${stdout}\n${stderr}\n${error.message}`.trim();
+}
+function resolveWorkspaceDependencyVersion(packageJsonPath, dependencyName) {
+    const packageRoot = path.dirname(packageJsonPath);
+    const repoRoot = path.resolve(packageRoot, "..", "..");
+    const packagesRoot = path.join(repoRoot, "packages");
+    if (!fs.existsSync(packagesRoot)) {
+        return null;
+    }
+    for (const entry of fs.readdirSync(packagesRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const candidatePath = path.join(packagesRoot, entry.name, "package.json");
+        if (!fs.existsSync(candidatePath)) {
+            continue;
+        }
+        const candidate = readPackageJson(candidatePath);
+        if (candidate.name === dependencyName && looksLikeExactVersion(candidate.version)) {
+            return candidate.version;
+        }
+    }
+    return null;
+}
+function assertPublishedVersion(packageName, version, ownerPackageName, ownerPackageVersion, execImpl, relation) {
+    try {
+        execImpl("npm", ["view", `${packageName}@${version}`, "version", "--json"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        if (relation === "self") {
+            throw new CliError("E_USAGE", `Cannot install ${ownerPackageName}@${ownerPackageVersion} because that package version is not published on npm. Publish ${ownerPackageName}@${ownerPackageVersion} first or use a local dev server config instead.`, 2);
+        }
+        throw new CliError("E_USAGE", `Cannot install ${ownerPackageName}@${ownerPackageVersion} because required dependency ${packageName}@${version} is not published on npm. Publish ${packageName}@${version} first, then rerun satori-cli install.`, 2);
+    }
+}
+export function verifyManagedPackageInstallability(options = {}) {
+    const packageJsonPath = options.packageJsonPath ?? resolveDefaultPackageJsonPath();
+    const execImpl = options.execFileSyncImpl ?? execFileSync;
+    const pkg = readPackageJson(packageJsonPath);
+    const packageSpecifier = `${pkg.name}@${pkg.version}`;
+    assertPublishedVersion(pkg.name, pkg.version, pkg.name, pkg.version, execImpl, "self");
+    for (const [dependencyName, rawDependencyVersion] of Object.entries(pkg.dependencies ?? {})) {
+        const dependencyVersion = looksLikeExactVersion(rawDependencyVersion)
+            ? rawDependencyVersion
+            : rawDependencyVersion.startsWith("workspace:")
+                ? resolveWorkspaceDependencyVersion(packageJsonPath, dependencyName)
+                : null;
+        if (!dependencyVersion) {
+            continue;
+        }
+        assertPublishedVersion(dependencyName, dependencyVersion, pkg.name, pkg.version, execImpl, "dependency");
+    }
+    return packageSpecifier;
+}
+export function runPublishedPackageReleaseSmoke(options = {}) {
+    const packageJsonPath = options.packageJsonPath ?? resolveDefaultPackageJsonPath();
+    const packageRoot = options.packageRoot ?? path.dirname(packageJsonPath);
+    const tempDir = options.tempDir ?? os.tmpdir();
+    const execImpl = options.execFileSyncImpl ?? execFileSync;
+    verifyManagedPackageInstallability({ packageJsonPath, execFileSyncImpl: execImpl });
+    const smokePackDir = fs.mkdtempSync(path.join(tempDir, "satori-release-smoke-"));
+    const smokeExecDir = fs.mkdtempSync(path.join(tempDir, "satori-release-exec-"));
+    const beforeFiles = new Set(fs.readdirSync(smokePackDir));
+    execImpl("pnpm", ["pack", "--pack-destination", smokePackDir], {
+        cwd: packageRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const tarballName = fs.readdirSync(smokePackDir).find((entry) => entry.endsWith(".tgz") && !beforeFiles.has(entry));
+    if (!tarballName) {
+        throw new CliError("E_USAGE", "Release smoke failed: pnpm pack did not produce a tarball.", 2);
+    }
+    const tarballPath = path.join(smokePackDir, tarballName);
+    try {
+        execImpl("npm", ["exec", "--yes", "--package", tarballPath, "--", "satori", "--help"], {
+            cwd: smokeExecDir,
+            encoding: "utf8",
+            env: {
+                ...process.env,
+                npm_config_package_lock: "false",
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        const output = npmOutput(error);
+        const pkg = readPackageJson(packageJsonPath);
+        throw new CliError("E_USAGE", `Release smoke failed for ${pkg.name}@${pkg.version}. The packed tarball did not start via 'npm exec --yes --package <tarball> -- satori --help'. ${output}`, 2);
+    }
+    finally {
+        fs.rmSync(smokePackDir, { recursive: true, force: true });
+        fs.rmSync(smokeExecDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=package-installability.js.map

package/dist/config.js

@@ -169,7 +169,7 @@ export function showHelpMessage() {
     console.log(`
 Satori MCP Server
 
-Usage: npx @zokizuan/satori-mcp@latest [options]
+Usage: npx -y @zokizuan/satori-mcp@4.4.1 [options]
 
 Options:
   --help, -h                          Show this help message
@@ -206,16 +206,16 @@ Environment Variables:
 
 Examples:
   # Start MCP server with OpenAI and explicit Milvus address
-  OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx @zokizuan/satori-mcp@latest
+  OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.4.1
 
   # Start MCP server with VoyageAI and specific model
-  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_TOKEN=your-token npx @zokizuan/satori-mcp@latest
+  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
 
   # Start MCP server with Gemini and specific model
-  EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_TOKEN=your-token npx @zokizuan/satori-mcp@latest
+  EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
 
   # Start MCP server with Ollama and specific model
-  EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_TOKEN=your-token npx @zokizuan/satori-mcp@latest
+  EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
         `);
 }
 //# sourceMappingURL=config.js.map

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@zokizuan/satori-mcp",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "description": "MCP server for Satori with agent-safe semantic search and indexing",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "satori": "dist/index.js",
-    "satori-cli": "dist/cli/index.js"
+    "satori": "dist/index.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
@@ -15,7 +14,7 @@
     "ignore": "^7.0.5",
     "zod": "^3.25.55",
     "zod-to-json-schema": "^3.25.1",
-    "@zokizuan/satori-core": "1.1.0"
+    "@zokizuan/satori-core": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -25,7 +24,6 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "assets/skills/**/*.md",
     "README.md"
   ],
   "repository": {
@@ -44,6 +42,7 @@
   },
   "scripts": {
     "build": "pnpm clean && tsc --build --force && pnpm fix:bin-perms && pnpm docs:generate && pnpm manifest:generate",
+    "build:runtime": "pnpm clean && tsc --build --force && pnpm fix:bin-perms",
     "dev": "tsx --watch src/index.ts",
     "clean": "rimraf dist",
     "lint": "eslint src --ext .ts",
@@ -55,7 +54,8 @@
     "docs:check": "tsx scripts/generate-docs.ts --check",
     "manifest:generate": "tsx scripts/generate-server-manifest.ts",
     "manifest:check": "tsx scripts/generate-server-manifest.ts --check",
-    "fix:bin-perms": "node -e \"const fs=require('fs');try{fs.chmodSync('dist/index.js',0o755);fs.chmodSync('dist/cli/index.js',0o755);}catch(e){console.error(e);process.exit(1);}\"",
-    "test": "pnpm --filter @zokizuan/satori-core build && tsx --test --test-concurrency=1 src/**/*.test.ts"
+    "release:smoke": "tsx scripts/release-smoke.ts",
+    "fix:bin-perms": "node -e \"const fs=require('fs');try{fs.chmodSync('dist/index.js',0o755);}catch(e){console.error(e);process.exit(1);}\"",
+    "test": "pnpm --filter @zokizuan/satori-core build && node --import tsx --test --test-concurrency=1 src/core/**/*.test.ts src/server/**/*.test.ts src/tools/**/*.test.ts src/cli/**/*.test.ts"
   }
 }

package/assets/skills/satori-indexing/SKILL.md

@@ -1,36 +0,0 @@
----
-name: satori-indexing
-description: Index lifecycle and remediation for Satori. Use when codebases are not indexed, stale, blocked, or need freshness recovery.
----
-
-# Satori Indexing
-
-Use this skill when the task is to create, reindex, sync, inspect readiness, or recover from stale index state.
-
-## Tools
-
-Use only:
-1. `list_codebases`
-2. `manage_index`
-
-## Workflow
-
-1. Use `list_codebases` for a global view of tracked roots.
-2. Use `manage_index(action="status", path=...)` for the specific codebase.
-3. Use `manage_index(action="create", path=...)` when the codebase is not indexed.
-4. Use `manage_index(action="reindex", path=...)` only for compatibility gates or explicit rebuilds.
-5. Use `manage_index(action="sync", path=...)` for freshness convergence and ignore-rule updates.
-
-## Rules
-
-- If any tool returns `requires_reindex`, stop and reindex. Do not substitute `sync`.
-- Never call `manage_index(action="clear")` unless the user explicitly requests destructive reset.
-- Treat ignore-only churn as a `sync` problem first.
-- Respect blocked and indexing states instead of forcing retries blindly.
-
-## Status Handling
-
-- `requires_reindex`: run `manage_index(action="reindex")`.
-- `not_ready` with indexing reason: check status and wait for terminal completion.
-- `not_indexed`: create the index.
-- Ignore-rule noise mitigation: update `.satoriignore`, wait debounce, and run `sync` for immediate convergence.

package/assets/skills/satori-navigation/SKILL.md

@@ -1,36 +0,0 @@
----
-name: satori-navigation
-description: Deterministic symbol navigation with Satori. Use after search results are found to lock exact spans and inspect call relationships.
----
-
-# Satori Navigation
-
-Use this skill after `search_codebase` has returned candidate results and you need exact symbol/file navigation.
-
-## Tools
-
-Use only:
-1. `file_outline`
-2. `call_graph`
-3. `read_file`
-
-## Workflow
-
-1. Use grouped `search_codebase` results as the starting point.
-2. If `callGraphHint.supported=true`, call `call_graph(path=..., symbolRef=..., direction="both", depth=1)`.
-3. If `callGraphHint.supported=false`, execute `navigationFallback.readSpan.args` exactly.
-4. Use `file_outline(resolveMode="exact", symbolIdExact|symbolLabelExact)` to lock the symbol span.
-5. Use `read_file(path=..., open_symbol=...)` or deterministic line spans for the final read.
-
-## Rules
-
-- Treat `navigationFallback` as authoritative. Do not invent spans.
-- `open_symbol` must resolve deterministically. Do not guess on ambiguity.
-- `read_file(mode="annotated")` is preferred when outline metadata is useful.
-- Follow continuation hints when plain reads are truncated.
-
-## Remediation
-
-- `requires_reindex`: reindex before retrying navigation.
-- `not_ready`: wait for indexing to finish.
-- `unsupported`: fall back to deterministic `read_file` spans when supplied by `navigationFallback`.

package/assets/skills/satori-search/SKILL.md

@@ -1,36 +0,0 @@
----
-name: satori-search
-description: Semantic-first code search with Satori. Use for intent-based code discovery before file reads or grep.
----
-
-# Satori Search
-
-Use this skill when the task is to find where behavior lives, identify candidate symbols, or narrow the search space before deeper navigation.
-
-## Tools
-
-Use only:
-1. `list_codebases`
-2. `manage_index`
-3. `search_codebase`
-
-## Workflow
-
-1. Check readiness with `manage_index(action="status", path=...)`.
-2. If not indexed, use `manage_index(action="create", path=...)`.
-3. If `requires_reindex` appears, stop and use `manage_index(action="reindex", path=...)`, then retry.
-4. Search with `search_codebase(path=..., query=..., scope="runtime", resultMode="grouped", groupBy="symbol", rankingMode="auto_changed_first")`.
-
-## Search Rules
-
-- Start with natural-language intent, not filenames.
-- Default to `scope="runtime"`.
-- Use operators only when needed: `lang:`, `path:`, `-path:`, `must:`, `exclude:`.
-- Treat warnings as usable-but-degraded results, not fatal errors.
-- Use `debug=true` only when ranking or filter explanations are required.
-
-## Remediation
-
-- `requires_reindex`: run `manage_index(action="reindex")`, not `sync`.
-- `not_ready` with indexing reason: wait or check `manage_index(action="status")`.
-- Noise mitigation hint: update `.satoriignore`, wait debounce, rerun search, and use `manage_index(action="sync")` only for immediate convergence.