@zokizuan/satori-cli 0.3.1 → 0.4.0

package/README.md

@@ -1,54 +1,63 @@
 # @zokizuan/satori-cli
 
-Shell CLI for Satori installation, skill packaging, and direct tool invocation without a resident MCP client.
+Installer and shell client for Satori MCP. Use this package to configure supported MCP clients, check provider setup, and call Satori tools from a terminal without starting a resident MCP client.
 
-## What It Does
-
-- installs and removes Satori MCP client config for supported clients
-- copies packaged first-party skills:
-  - `satori-search`
-  - `satori-navigation`
-  - `satori-indexing`
-- starts a local stdio session against `@zokizuan/satori-mcp` for direct shell workflows
-
-## Install / Uninstall
+## Quick Start
 
 ```bash
-npx -y @zokizuan/satori-cli@0.3.1 install --client codex
-npx -y @zokizuan/satori-cli@0.3.1 install --client claude
-npx -y @zokizuan/satori-cli@0.3.1 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.3.1 uninstall --client codex
-npx -y @zokizuan/satori-cli@0.3.1 doctor
+npx -y @zokizuan/satori-cli@0.4.0 install --client all
+npx -y @zokizuan/satori-cli@0.4.0 doctor
 ```
 
-Managed install writes MCP config that launches:
+Supported clients are `codex`, `claude`, `opencode`, and `all`.
 
-```toml
-[mcp_servers.satori]
-command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@4.9.1"]
-startup_timeout_ms = 180000
-```
+The installer performs package resolution once, stores the MCP server under `~/.satori/mcp-runtime/`, writes a stable launcher at `~/.satori/bin/satori-mcp.js`, and writes client-specific config that starts the launcher directly with Node. Resident MCP startup should not run `npx` or require a custom long startup timeout.
+
+The installer only manages Satori-owned config and the first-party workflow skill:
+
+- `satori`
 
 ## Commands
 
 ```bash
-satori-cli doctor
+npx -y @zokizuan/satori-cli@0.4.0 install --client codex
+npx -y @zokizuan/satori-cli@0.4.0 install --client claude
+npx -y @zokizuan/satori-cli@0.4.0 install --client opencode
+npx -y @zokizuan/satori-cli@0.4.0 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.4.0 uninstall --client codex
+```
+
+`doctor` checks Node, package visibility, provider env, and Milvus env without starting an MCP client.
+
+## Direct Tool Calls
+
+```bash
 satori-cli tools list
-satori-cli tool call <toolName> --args-json '{"path":"/abs/repo","query":"auth"}'
-satori-cli tool call <toolName> --args-file ./args.json
-satori-cli tool call <toolName> --args-json @-
-satori-cli <toolName> [schema-subset flags]
+satori-cli tool call search_codebase --args-json '{"path":"/abs/repo","query":"auth flow"}'
+satori-cli tool call search_codebase --args-file ./args.json
+satori-cli tool call search_codebase --args-json @-
+satori-cli search_codebase --path /abs/repo --query "auth flow"
 ```
 
-Global flags (`--startup-timeout-ms`, `--call-timeout-ms`, `--format`, `--debug`) must appear before the command token.
+Global flags such as `--startup-timeout-ms`, `--call-timeout-ms`, `--format`, and `--debug` must appear before the command token.
+
+## Runtime Requirements
+
+Indexing and search require an embedding provider plus a Milvus-compatible backend. MCP startup and `tools list` do not require those credentials; provider-backed tool calls return `MISSING_PROVIDER_CONFIG` when setup is incomplete.
 
-`doctor` checks local setup without starting an MCP client: Node version, npm package visibility, provider env, and Milvus env.
+Common local setup:
+
+```bash
+EMBEDDING_PROVIDER=Ollama
+EMBEDDING_MODEL=nomic-embed-text
+OLLAMA_HOST=http://127.0.0.1:11434
+MILVUS_ADDRESS=localhost:19530
+```
 
 ## Development
 
 ```bash
 pnpm --filter @zokizuan/satori-cli build
 pnpm --filter @zokizuan/satori-cli test
-pnpm --filter @zokizuan/satori-cli release:smoke
+pnpm run release:smoke:cli
 ```

package/assets/skills/satori/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: satori
+description: Use when working with Satori MCP for code search, exact navigation, call graph context, bounded reads, indexing, sync, reindex, or stale index recovery.
+---
+
+# Satori
+
+Use this skill when a task needs Satori MCP for code discovery, navigation, or index lifecycle work.
+
+## Tools
+
+Satori exposes exactly six MCP tools:
+
+1. `list_codebases`
+2. `manage_index`
+3. `search_codebase`
+4. `file_outline`
+5. `call_graph`
+6. `read_file`
+
+## Default Workflow
+
+1. Use `manage_index(action="status", path=...)` when index state is unknown.
+2. If the codebase is not indexed, use `manage_index(action="create", path=...)`.
+3. Search the requested path with `search_codebase(path=..., query=..., scope="runtime", resultMode="grouped", groupBy="symbol", rankingMode="auto_changed_first")`.
+4. Use `file_outline(resolveMode="exact", symbolIdExact|symbolLabelExact)` to lock exact symbol spans when identity is available.
+5. If `callGraphHint.supported=true`, call `call_graph(path=..., symbolRef=..., direction="both", depth=1)`.
+6. Use `read_file(path=..., open_symbol=...)` or deterministic line spans for final evidence before editing.
+
+## Search Rules
+
+- Start with natural-language intent, not filenames.
+- Default to `scope="runtime"`.
+- Use operators only when useful: `lang:`, `path:`, `-path:`, `must:`, `exclude:`.
+- Pass the user's requested path; if Satori resolves an indexed parent, follow returned fallback payloads exactly.
+- Treat warnings as usable-but-degraded results, not fatal errors.
+- Use `debug=true` only when ranking or filter explanations are required.
+
+## Navigation Rules
+
+- Treat `navigationFallback` as authoritative. Do not invent spans.
+- `open_symbol` must resolve deterministically. Do not guess on ambiguity.
+- Prefer `read_file(mode="annotated")` when outline metadata helps.
+- Follow continuation hints when plain reads are truncated.
+- Read the relevant implementation and call sites before editing behavior.
+
+## Index Rules
+
+- If any tool returns `requires_reindex`, run `manage_index(action="reindex")`, then retry the original call. Do not substitute `sync`.
+- Use `manage_index(action="sync")` for freshness convergence and ignore-rule updates.
+- Never call `manage_index(action="clear")` unless the user explicitly requests destructive reset.
+- Respect blocked and actively indexing states instead of forcing retries blindly.
+- `MISSING_PROVIDER_CONFIG` is active only when it appears as the tool response `code` or `reason`. If it appears inside search results, it may just be matched code content.
+
+## Status Handling
+
+- `not_indexed`: create the index.
+- `not_ready` with indexing reason: check status and wait for terminal completion.
+- `requires_reindex`: reindex before trusting search or navigation.
+- `unsupported`: fall back to deterministic `read_file` spans when supplied by `navigationFallback`.
+- Noise mitigation hint: update `.satoriignore`, wait debounce, rerun search, and use `manage_index(action="sync")` only for immediate convergence.

package/dist/args.d.ts

@@ -49,7 +49,7 @@ export interface ResolveRawArgsOptions {
     stdin?: NodeJS.ReadStream;
     stdinTimeoutMs: number;
 }
-export type InstallClient = "all" | "claude" | "codex";
+export type InstallClient = "all" | "claude" | "codex" | "opencode";
 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/args.js

@@ -20,7 +20,7 @@ function stripFlagPrefix(token) {
 }
 function parseGlobalOptions(argv) {
     const globals = {
-        startupTimeoutMs: 180000,
+        startupTimeoutMs: 30000,
         callTimeoutMs: 600000,
         format: "json",
         debug: false,
@@ -116,8 +116,8 @@ function parseInstallCommand(kind, args) {
         const token = args[i];
         if (token === "--client") {
             const next = args[i + 1];
-            if (next !== "all" && next !== "claude" && next !== "codex") {
-                throw new CliError("E_USAGE", "--client must be one of: all, claude, codex.", 2);
+            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;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type ManagedRuntimeCommand } from "./install.js";
 import type { DoctorResult } from "./doctor.js";
 interface RunCliOptions {
     writeStdout?: (text: string) => void;
@@ -12,6 +13,7 @@ interface RunCliOptions {
     callTimeoutMs?: number;
     cwd?: string;
     installabilityVerifier?: () => string | Promise<string>;
+    installRuntimeCommand?: ManagedRuntimeCommand;
     doctorRunner?: (options: {
         env: NodeJS.ProcessEnv;
     }) => DoctorResult;

package/dist/index.js

@@ -45,8 +45,8 @@ function buildHelpPayload() {
     return {
         usage: "satori-cli <command>",
         commands: [
-            "install [--client all|codex|claude] [--dry-run]",
-            "uninstall [--client all|codex|claude] [--dry-run]",
+            "install [--client all|codex|claude|opencode] [--dry-run]",
+            "uninstall [--client all|codex|claude|opencode] [--dry-run]",
             "doctor",
             "tools list",
             "tool call <toolName> --args-json '<json>'",
@@ -211,11 +211,14 @@ export async function runCli(argv, options = {}) {
             return result.status === "error" ? 1 : 0;
         }
         if (parsed.command.kind === "install" || parsed.command.kind === "uninstall") {
+            let packageSpecifier;
             if (parsed.command.kind === "install") {
-                await (options.installabilityVerifier || verifyManagedPackageInstallability)();
+                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") {

package/dist/install.d.ts

@@ -1,5 +1,11 @@
+import { execFileSync } from "node:child_process";
 import type { InstallClient } from "./args.js";
+type ExecFileSyncLike = typeof execFileSync;
 type ClientName = Exclude<InstallClient, "all">;
+export interface ManagedRuntimeCommand {
+    command: string;
+    args: string[];
+}
 export interface InstallCommandInput {
     kind: "install" | "uninstall";
     client: InstallClient;
@@ -9,13 +15,17 @@ export interface InstallCommandOptions {
     homeDir?: string;
     packageSpecifier?: string;
     skillAssetRoot?: string;
+    runtimeCommand?: ManagedRuntimeCommand;
+    execFileSyncImpl?: ExecFileSyncLike;
 }
 export interface ClientInstallResult {
     client: ClientName;
     configPath: string;
-    skillsPath: string;
+    skillsPath?: string;
+    instructionsPath?: string;
     configChanged: boolean;
     skillsChanged: boolean;
+    instructionsChanged: boolean;
     status: "updated" | "unchanged";
     dryRun: boolean;
 }

package/dist/install.js

@@ -1,13 +1,36 @@
 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 { applyEdits, modify, parse as parseJsonc } from "jsonc-parser";
 import { CliError } from "./errors.js";
 import { resolveManagedPackageSpecifier } from "./managed-package.js";
 const MANAGED_BLOCK_START = "# >>> satori-cli managed satori start >>>";
 const MANAGED_BLOCK_END = "# <<< satori-cli managed satori end <<<";
-const OWNED_SKILL_DIRS = ["satori-search", "satori-navigation", "satori-indexing"];
-const MANAGED_TIMEOUT_MS = 180000;
+const INSTRUCTIONS_BLOCK_START = "<!-- satori-mcp:start -->";
+const INSTRUCTIONS_BLOCK_END = "<!-- satori-mcp:end -->";
+const OWNED_SKILL_DIRS = ["satori"];
+const MANAGED_RUNTIME_DIR = "mcp-runtime";
+const MANAGED_BIN_DIR = "bin";
+const MANAGED_LAUNCHER_FILE = "satori-mcp.js";
+const OPENCODE_INSTRUCTIONS = `# Satori MCP
+
+This project uses Satori MCP for semantic code search, deterministic navigation, and index lifecycle management.
+
+## Priority Order
+1. \`search_codebase\` - find candidate code by behavior, concept, or symbol
+2. \`file_outline\` - lock exact symbol spans before reading or editing
+3. \`call_graph\` - inspect callers and callees when supported
+4. \`read_file\` - open exact spans or fallback windows
+5. \`manage_index\` - create, sync, reindex, or inspect index status
+
+## Rules
+- Prefer Satori tools before grep/glob for code discovery.
+- If a tool returns \`requires_reindex\`, run \`manage_index(action="reindex")\` and retry the original call.
+- Treat \`navigationFallback\` as authoritative when call graph is unavailable.
+- Read the relevant implementation and call sites before editing behavior.
+`;
 function resolveDefaultSkillAssetRoot() {
     const currentFile = fileURLToPath(import.meta.url);
     return path.resolve(path.dirname(currentFile), "..", "assets", "skills");
@@ -26,12 +49,26 @@ function resolveClientTargets(homeDir) {
         {
             client: "codex",
             configPath: path.join(homeDir, ".codex", "config.toml"),
-            skillsPath: path.join(homeDir, ".codex", "skills"),
+            companion: {
+                kind: "skills",
+                path: path.join(homeDir, ".codex", "skills"),
+            },
         },
         {
             client: "claude",
             configPath: path.join(homeDir, ".claude", "settings.json"),
-            skillsPath: path.join(homeDir, ".claude", "skills"),
+            companion: {
+                kind: "skills",
+                path: path.join(homeDir, ".claude", "skills"),
+            },
+        },
+        {
+            client: "opencode",
+            configPath: path.join(homeDir, ".config", "opencode", "opencode.json"),
+            companion: {
+                kind: "instructions",
+                path: path.join(homeDir, ".config", "opencode", "AGENTS.md"),
+            },
         },
     ];
 }
@@ -60,13 +97,167 @@ function normalizeTrailingNewline(value) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function buildCodexManagedBlock(packageSpecifier) {
+function toTomlString(value) {
+    return JSON.stringify(value);
+}
+function buildTomlArray(values) {
+    return `[${values.map(toTomlString).join(", ")}]`;
+}
+function packageNameFromSpecifier(packageSpecifier) {
+    if (packageSpecifier.startsWith("@")) {
+        const versionMarker = packageSpecifier.indexOf("@", 1);
+        return versionMarker === -1 ? packageSpecifier : packageSpecifier.slice(0, versionMarker);
+    }
+    const versionMarker = packageSpecifier.indexOf("@");
+    return versionMarker === -1 ? packageSpecifier : packageSpecifier.slice(0, versionMarker);
+}
+function safeRuntimeDirName(packageSpecifier) {
+    return packageSpecifier.replace(/[^A-Za-z0-9._@-]+/g, "-");
+}
+function resolveRuntimeRoot(homeDir, packageSpecifier) {
+    return path.join(homeDir, ".satori", MANAGED_RUNTIME_DIR, safeRuntimeDirName(packageSpecifier));
+}
+function resolveRuntimePackageRoot(homeDir, packageSpecifier) {
+    return path.join(resolveRuntimeRoot(homeDir, packageSpecifier), "node_modules", ...packageNameFromSpecifier(packageSpecifier).split("/"));
+}
+function resolveRuntimeEntryPath(packageRoot, packageJson) {
+    const bin = packageJson?.bin;
+    let relativeEntry = "dist/index.js";
+    if (bin && typeof bin === "object" && !Array.isArray(bin) && typeof bin.satori === "string") {
+        relativeEntry = bin.satori;
+    }
+    else if (typeof bin === "string") {
+        relativeEntry = bin;
+    }
+    else if (typeof packageJson?.main === "string") {
+        relativeEntry = packageJson.main;
+    }
+    return path.resolve(packageRoot, relativeEntry);
+}
+function resolveLauncherPath(homeDir) {
+    return path.join(homeDir, ".satori", MANAGED_BIN_DIR, MANAGED_LAUNCHER_FILE);
+}
+function plannedManagedRuntimeCommand(homeDir, packageSpecifier) {
+    return {
+        command: process.execPath,
+        args: [resolveRuntimeEntryPath(resolveRuntimePackageRoot(homeDir, packageSpecifier))],
+    };
+}
+function managedClientCommand(homeDir) {
+    return {
+        command: process.execPath,
+        args: [resolveLauncherPath(homeDir)],
+    };
+}
+function buildLauncherScript(runtimeCommand) {
+    return [
+        "#!/usr/bin/env node",
+        "",
+        "const { spawn } = require(\"node:child_process\");",
+        "",
+        `const command = ${JSON.stringify(runtimeCommand.command)};`,
+        `const baseArgs = ${JSON.stringify(runtimeCommand.args)};`,
+        "const child = spawn(command, [...baseArgs, ...process.argv.slice(2)], {",
+        "  stdio: \"inherit\",",
+        "  env: process.env,",
+        "});",
+        "",
+        "child.on(\"error\", (error) => {",
+        "  console.error(`Failed to start Satori MCP runtime: ${error.message}`);",
+        "  process.exit(1);",
+        "});",
+        "",
+        "child.on(\"exit\", (code, signal) => {",
+        "  if (signal) {",
+        "    console.error(`Satori MCP runtime exited from signal ${signal}`);",
+        "    process.exit(1);",
+        "  }",
+        "  process.exit(code ?? 0);",
+        "});",
+        "",
+    ].join("\n");
+}
+function writeTextFileAtomic(filePath, content, mode) {
+    ensureParentDir(filePath);
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tempPath, content, "utf8");
+    if (mode !== undefined) {
+        fs.chmodSync(tempPath, mode);
+    }
+    fs.renameSync(tempPath, filePath);
+}
+function prepareLauncherInstall(homeDir, runtimeCommand) {
+    const launcherPath = resolveLauncherPath(homeDir);
+    const current = readTextIfExists(launcherPath);
+    const next = buildLauncherScript(runtimeCommand);
+    return {
+        changed: current !== next,
+        apply: () => {
+            if (current === next) {
+                return;
+            }
+            writeTextFileAtomic(launcherPath, next, 0o755);
+        },
+    };
+}
+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 installManagedRuntimeCommand(homeDir, packageSpecifier, execImpl) {
+    const runtimeRoot = resolveRuntimeRoot(homeDir, packageSpecifier);
+    ensureDir(runtimeRoot);
+    try {
+        execImpl("npm", [
+            "install",
+            "--prefix",
+            runtimeRoot,
+            "--omit=dev",
+            "--no-package-lock",
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+            packageSpecifier,
+        ], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        throw new CliError("E_USAGE", `Failed to install Satori MCP runtime package ${packageSpecifier} into ${runtimeRoot}. ${npmOutput(error)}`, 2);
+    }
+    const packageRoot = resolveRuntimePackageRoot(homeDir, packageSpecifier);
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    let packageJson;
+    try {
+        packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch (error) {
+        throw new CliError("E_USAGE", `Installed Satori MCP runtime is missing package metadata at ${packageJsonPath}: ${error.message}`, 2);
+    }
+    const command = {
+        command: process.execPath,
+        args: [resolveRuntimeEntryPath(packageRoot, packageJson)],
+    };
+    if (!fs.existsSync(command.args[0])) {
+        throw new CliError("E_USAGE", `Installed Satori MCP runtime entry does not exist: ${command.args[0]}`, 2);
+    }
+    return command;
+}
+function buildCodexManagedBlock(runtimeCommand) {
     return [
         MANAGED_BLOCK_START,
         "[mcp_servers.satori]",
-        'command = "npx"',
-        `args = ["-y", "${packageSpecifier}"]`,
-        `startup_timeout_ms = ${MANAGED_TIMEOUT_MS}`,
+        `command = ${toTomlString(runtimeCommand.command)}`,
+        `args = ${buildTomlArray(runtimeCommand.args)}`,
         MANAGED_BLOCK_END,
         "",
     ].join("\n");
@@ -77,12 +268,12 @@ function codexHasUnmanagedSatoriSection(content) {
     }
     return !(content.includes(MANAGED_BLOCK_START) && content.includes(MANAGED_BLOCK_END));
 }
-function prepareCodexInstall(filePath, packageSpecifier) {
+function prepareCodexInstall(filePath, runtimeCommand) {
     const current = readTextIfExists(filePath) ?? "";
     if (codexHasUnmanagedSatoriSection(current)) {
         throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove [mcp_servers.satori] manually or convert it to the managed block first.`, 2);
     }
-    const managedBlock = buildCodexManagedBlock(packageSpecifier);
+    const managedBlock = buildCodexManagedBlock(runtimeCommand);
     let next = current;
     if (current.includes(MANAGED_BLOCK_START) && current.includes(MANAGED_BLOCK_END)) {
         next = current.replace(new RegExp(`${escapeRegExp(MANAGED_BLOCK_START)}[\\s\\S]*?${escapeRegExp(MANAGED_BLOCK_END)}\\n?`, "m"), managedBlock);
@@ -146,45 +337,36 @@ function parseJsonObject(filePath) {
     }
     return parsed;
 }
-function buildClaudeServerConfig(packageSpecifier) {
+function buildClaudeServerConfig(runtimeCommand) {
     return {
-        command: "npx",
-        args: ["-y", packageSpecifier],
-        timeout: MANAGED_TIMEOUT_MS,
+        command: runtimeCommand.command,
+        args: runtimeCommand.args,
     };
 }
-function isManagedPackageSpecifier(value) {
-    return typeof value === "string" && /^@zokizuan\/satori-mcp@.+$/.test(value);
+function isManagedLauncherPath(value) {
+    return typeof value === "string" && value.replace(/\\/g, "/").endsWith(`/.satori/${MANAGED_BIN_DIR}/${MANAGED_LAUNCHER_FILE}`);
+}
+function isManagedCommandParts(command, args) {
+    if (!Array.isArray(args)) {
+        return false;
+    }
+    const entryPath = args[0];
+    return typeof command === "string"
+        && command.length > 0
+        && args.length === 1
+        && isManagedLauncherPath(entryPath);
 }
 function isManagedClaudeEntry(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return false;
     }
     const entry = value;
-    if (entry.command !== "npx") {
-        return false;
-    }
-    if (entry.timeout !== MANAGED_TIMEOUT_MS) {
-        return false;
-    }
-    if (!Array.isArray(entry.args)) {
-        return false;
-    }
-    if (entry.args.length === 2) {
-        return entry.args[0] === "-y" && isManagedPackageSpecifier(entry.args[1]);
-    }
-    if (entry.args.length === 4) {
-        return entry.args[0] === "-y"
-            && entry.args[1] === "--package"
-            && isManagedPackageSpecifier(entry.args[2])
-            && entry.args[3] === "satori";
-    }
-    return false;
+    return isManagedCommandParts(entry.command, entry.args);
 }
-function prepareClaudeInstall(filePath, packageSpecifier) {
+function prepareClaudeInstall(filePath, runtimeCommand) {
     const currentObject = parseJsonObject(filePath);
     const currentSerialized = JSON.stringify(currentObject);
-    const desiredServer = buildClaudeServerConfig(packageSpecifier);
+    const desiredServer = buildClaudeServerConfig(runtimeCommand);
     const mcpServersValue = currentObject.mcpServers;
     let mcpServers;
     if (mcpServersValue === undefined) {
@@ -198,12 +380,13 @@ function prepareClaudeInstall(filePath, packageSpecifier) {
     }
     const existingSatori = mcpServers.satori;
     if (existingSatori !== undefined && !isManagedClaudeEntry(existingSatori)) {
-        throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove mcpServers.satori manually or align it to the managed npx form first.`, 2);
+        throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove mcpServers.satori manually or align it to the managed Satori form first.`, 2);
     }
     mcpServers.satori = {
         ...existingSatori,
         ...desiredServer,
     };
+    delete mcpServers.satori.timeout;
     currentObject.mcpServers = mcpServers;
     const next = `${JSON.stringify(currentObject, null, 2)}\n`;
     return {
@@ -245,6 +428,87 @@ function prepareClaudeUninstall(filePath) {
         },
     };
 }
+function parseJsoncObject(filePath, content) {
+    const errors = [];
+    const parsed = parseJsonc(content, errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length > 0) {
+        throw new CliError("E_USAGE", `Failed to parse JSONC config at ${filePath}.`, 2);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("E_USAGE", `Expected top-level JSON object in ${filePath}.`, 2);
+    }
+    return parsed;
+}
+function buildOpenCodeServerConfig(runtimeCommand) {
+    return {
+        enabled: true,
+        type: "local",
+        command: [runtimeCommand.command, ...runtimeCommand.args],
+    };
+}
+function isManagedOpenCodeEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const entry = value;
+    if (Array.isArray(entry.command)) {
+        const [command, ...args] = entry.command;
+        return isManagedCommandParts(command, args);
+    }
+    return isManagedCommandParts(entry.command, entry.args);
+}
+function mutateJsonc(filePath, current, pathSegments, value) {
+    const edits = modify(current, pathSegments, value, {
+        formattingOptions: {
+            insertSpaces: true,
+            tabSize: 2,
+            eol: "\n",
+        },
+    });
+    const next = applyEdits(current, edits);
+    return {
+        changed: next !== current,
+        apply: () => {
+            if (next === current) {
+                return;
+            }
+            ensureParentDir(filePath);
+            fs.writeFileSync(filePath, next.endsWith("\n") ? next : `${next}\n`, "utf8");
+        },
+    };
+}
+function prepareOpenCodeInstall(filePath, runtimeCommand) {
+    const current = readTextIfExists(filePath) ?? "{}\n";
+    const currentObject = parseJsoncObject(filePath, current);
+    const mcpValue = currentObject.mcp;
+    if (mcpValue !== undefined && (!mcpValue || typeof mcpValue !== "object" || Array.isArray(mcpValue))) {
+        throw new CliError("E_USAGE", `Expected mcp to be an object in ${filePath}.`, 2);
+    }
+    const existingSatori = mcpValue?.satori;
+    if (existingSatori !== undefined && !isManagedOpenCodeEntry(existingSatori)) {
+        throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove mcp.satori manually or align it to the managed Satori form first.`, 2);
+    }
+    return mutateJsonc(filePath, current, ["mcp", "satori"], buildOpenCodeServerConfig(runtimeCommand));
+}
+function prepareOpenCodeUninstall(filePath) {
+    const current = readTextIfExists(filePath);
+    if (!current) {
+        return { changed: false, apply: () => { } };
+    }
+    const currentObject = parseJsoncObject(filePath, current);
+    const mcpValue = currentObject.mcp;
+    if (!mcpValue || typeof mcpValue !== "object" || Array.isArray(mcpValue)) {
+        return { changed: false, apply: () => { } };
+    }
+    const existingSatori = mcpValue.satori;
+    if (existingSatori === undefined) {
+        return { changed: false, apply: () => { } };
+    }
+    if (!isManagedOpenCodeEntry(existingSatori)) {
+        throw new CliError("E_USAGE", `Refusing to remove unmanaged Satori config in ${filePath}. Remove mcp.satori manually instead.`, 2);
+    }
+    return mutateJsonc(filePath, current, ["mcp", "satori"], undefined);
+}
 function prepareSkillInstall(skillsPath, skillAssetRoot) {
     const writes = [];
     let changed = false;
@@ -284,24 +548,92 @@ function prepareSkillRemoval(skillsPath) {
         },
     };
 }
-function prepareMutation(target, command, packageSpecifier, skillAssetRoot) {
-    const configMutation = command.kind === "install"
-        ? target.client === "codex"
-            ? prepareCodexInstall(target.configPath, packageSpecifier)
-            : prepareClaudeInstall(target.configPath, packageSpecifier)
-        : target.client === "codex"
-            ? prepareCodexUninstall(target.configPath)
+function buildManagedInstructionsBlock() {
+    return [
+        INSTRUCTIONS_BLOCK_START,
+        OPENCODE_INSTRUCTIONS.trim(),
+        INSTRUCTIONS_BLOCK_END,
+        "",
+    ].join("\n");
+}
+function prepareInstructionsInstall(filePath) {
+    const current = readTextIfExists(filePath) ?? "";
+    const block = buildManagedInstructionsBlock();
+    let next = current;
+    if (current.includes(INSTRUCTIONS_BLOCK_START) && current.includes(INSTRUCTIONS_BLOCK_END)) {
+        next = current.replace(new RegExp(`${escapeRegExp(INSTRUCTIONS_BLOCK_START)}[\\s\\S]*?${escapeRegExp(INSTRUCTIONS_BLOCK_END)}\\n?`, "m"), block);
+    }
+    else if (current.trim().length === 0) {
+        next = block;
+    }
+    else {
+        next = `${normalizeTrailingNewline(current)}\n${block}`;
+    }
+    return {
+        changed: next !== current,
+        apply: () => {
+            if (next === current) {
+                return;
+            }
+            ensureParentDir(filePath);
+            fs.writeFileSync(filePath, next, "utf8");
+        },
+    };
+}
+function prepareInstructionsRemoval(filePath) {
+    const current = readTextIfExists(filePath);
+    if (!current || !current.includes(INSTRUCTIONS_BLOCK_START) || !current.includes(INSTRUCTIONS_BLOCK_END)) {
+        return { changed: false, apply: () => { } };
+    }
+    const next = current
+        .replace(new RegExp(`\\n?${escapeRegExp(INSTRUCTIONS_BLOCK_START)}[\\s\\S]*?${escapeRegExp(INSTRUCTIONS_BLOCK_END)}\\n?`, "m"), "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .replace(/^\n+/, "");
+    return {
+        changed: next !== current,
+        apply: () => {
+            if (next === current) {
+                return;
+            }
+            fs.writeFileSync(filePath, next, "utf8");
+        },
+    };
+}
+function prepareCompanionMutation(companion, command, skillAssetRoot) {
+    if (companion.kind === "skills") {
+        return command.kind === "install"
+            ? prepareSkillInstall(companion.path, skillAssetRoot)
+            : prepareSkillRemoval(companion.path);
+    }
+    return command.kind === "install"
+        ? prepareInstructionsInstall(companion.path)
+        : prepareInstructionsRemoval(companion.path);
+}
+function prepareConfigMutation(target, command, runtimeCommand) {
+    if (target.client === "codex") {
+        return command.kind === "install"
+            ? prepareCodexInstall(target.configPath, runtimeCommand)
+            : prepareCodexUninstall(target.configPath);
+    }
+    if (target.client === "claude") {
+        return command.kind === "install"
+            ? prepareClaudeInstall(target.configPath, runtimeCommand)
             : prepareClaudeUninstall(target.configPath);
-    const skillsMutation = command.kind === "install"
-        ? prepareSkillInstall(target.skillsPath, skillAssetRoot)
-        : prepareSkillRemoval(target.skillsPath);
+    }
+    return command.kind === "install"
+        ? prepareOpenCodeInstall(target.configPath, runtimeCommand)
+        : prepareOpenCodeUninstall(target.configPath);
+}
+function prepareMutation(target, command, runtimeCommand, skillAssetRoot) {
+    const configMutation = prepareConfigMutation(target, command, runtimeCommand);
+    const companionMutation = prepareCompanionMutation(target.companion, command, skillAssetRoot);
     return {
         target,
         configChanged: configMutation.changed,
-        skillsChanged: skillsMutation.changed,
+        companionChanged: companionMutation.changed,
         apply: () => {
             configMutation.apply();
-            skillsMutation.apply();
+            companionMutation.apply();
         },
     };
 }
@@ -309,8 +641,20 @@ export function executeInstallCommand(command, options = {}) {
     const homeDir = options.homeDir ?? os.homedir();
     const packageSpecifier = options.packageSpecifier ?? resolveDefaultPackageSpecifier();
     const skillAssetRoot = options.skillAssetRoot ?? resolveDefaultSkillAssetRoot();
-    const prepared = selectTargets(homeDir, command.client).map((target) => (prepareMutation(target, command, packageSpecifier, skillAssetRoot)));
+    const plannedRuntimeCommand = options.runtimeCommand ?? plannedManagedRuntimeCommand(homeDir, packageSpecifier);
+    const clientCommand = managedClientCommand(homeDir);
+    let launcherMutation = command.kind === "install"
+        ? prepareLauncherInstall(homeDir, plannedRuntimeCommand)
+        : { changed: false, apply: () => { } };
+    const prepared = selectTargets(homeDir, command.client).map((target) => (prepareMutation(target, command, clientCommand, skillAssetRoot)));
     if (!command.dryRun) {
+        if (command.kind === "install" && !options.runtimeCommand) {
+            const installedRuntimeCommand = installManagedRuntimeCommand(homeDir, packageSpecifier, options.execFileSyncImpl ?? execFileSync);
+            launcherMutation = prepareLauncherInstall(homeDir, installedRuntimeCommand);
+        }
+        if (command.kind === "install") {
+            launcherMutation.apply();
+        }
         for (const mutation of prepared) {
             mutation.apply();
         }
@@ -322,10 +666,12 @@ export function executeInstallCommand(command, options = {}) {
         results: prepared.map((mutation) => ({
             client: mutation.target.client,
             configPath: mutation.target.configPath,
-            skillsPath: mutation.target.skillsPath,
+            skillsPath: mutation.target.companion.kind === "skills" ? mutation.target.companion.path : undefined,
+            instructionsPath: mutation.target.companion.kind === "instructions" ? mutation.target.companion.path : undefined,
             configChanged: mutation.configChanged,
-            skillsChanged: mutation.skillsChanged,
-            status: mutation.configChanged || mutation.skillsChanged ? "updated" : "unchanged",
+            skillsChanged: mutation.target.companion.kind === "skills" ? mutation.companionChanged : false,
+            instructionsChanged: mutation.target.companion.kind === "instructions" ? mutation.companionChanged : false,
+            status: mutation.configChanged || mutation.companionChanged || launcherMutation.changed ? "updated" : "unchanged",
             dryRun: command.dryRun,
         })),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Shell CLI for Satori MCP installation and skill-based workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -9,12 +9,13 @@
     "satori-cli": "dist/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "@zokizuan/satori-mcp": "4.9.1"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "jsonc-parser": "^3.3.1",
+    "@zokizuan/satori-mcp": "4.11.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "tsx": "^4.19.4",
+    "tsx": "^4.22.4",
     "typescript": "^5.0.0"
   },
   "files": [

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

@@ -1,38 +0,0 @@
----
-name: satori-indexing
-description: Use when Satori codebases are not indexed, stale, blocked, still indexing, or need lifecycle 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.
-- Use `status` and `list_codebases` freely; provider credentials are only needed for provider-backed lifecycle actions.
-
-## 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.
-- `MISSING_PROVIDER_CONFIG`: run `satori-cli doctor` when available, then set missing provider or Milvus env before retrying create/reindex/sync/search.
-- Ignore-rule noise mitigation: update `.satoriignore`, wait debounce, and run `sync` for immediate convergence.

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

@@ -1,39 +0,0 @@
----
-name: satori-navigation
-description: Use when search has returned candidate code and exact spans, symbol reads, or call relationships are needed.
----
-
-# 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`
-
-For lifecycle remediation (`requires_reindex`, `not_indexed`, indexing waits), switch to `satori-indexing`.
-
-## Workflow
-
-1. Use grouped `search_codebase` results as the starting point.
-2. Use `file_outline(resolveMode="exact", symbolIdExact|symbolLabelExact)` to lock the symbol span when exact identity is available.
-3. If `callGraphHint.supported=true`, call `call_graph(path=..., symbolRef=..., direction="both", depth=1)`.
-4. If `callGraphHint.supported=false`, execute `navigationFallback.readSpan.args` exactly.
-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.
-- Other tools do not run search freshness; remediate stale index state before trusting navigation.
-
-## Remediation
-
-- `requires_reindex`: switch to `satori-indexing` and reindex before retrying navigation.
-- `not_ready` or `not_indexed`: switch to `satori-indexing`; wait or create before retrying navigation.
-- `unsupported`: fall back to deterministic `read_file` spans when supplied by `navigationFallback`.

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

@@ -1,39 +0,0 @@
----
-name: satori-search
-description: Use when finding code by behavior, concept, or symbol before opening files or falling back to 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=...)` when index state is unknown.
-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 the user-requested path 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:`.
-- Pass the user's requested path; if Satori resolves an indexed parent, follow returned `navigationFallback` exactly.
-- 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")`.
-- `not_indexed`: run `manage_index(action="create")` on the repository root or requested indexed root.
-- `MISSING_PROVIDER_CONFIG` is active only when it appears as the tool response `code` or `reason`. If it appears inside `search_codebase` results, it may just be matched code content.
-- Noise mitigation hint: update `.satoriignore`, wait debounce, rerun search, and use `manage_index(action="sync")` only for immediate convergence.