@zokizuan/satori-cli 0.3.0 → 0.3.2

package/README.md

@@ -1,54 +1,49 @@
 # @zokizuan/satori-cli
 
-Shell CLI for Satori installation, skill packaging, and direct tool invocation without a resident MCP client.
+Shell CLI for installing Satori MCP config, copying first-party skills, checking setup, and calling Satori tools without 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
+## Install Satori for a Client
 
 ```bash
-npx -y @zokizuan/satori-cli@0.3.0 install --client codex
-npx -y @zokizuan/satori-cli@0.3.0 install --client claude
-npx -y @zokizuan/satori-cli@0.3.0 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.3.0 uninstall --client codex
-npx -y @zokizuan/satori-cli@0.3.0 doctor
+npx -y @zokizuan/satori-cli@0.3.2 install --client codex
+npx -y @zokizuan/satori-cli@0.3.2 install --client claude
+npx -y @zokizuan/satori-cli@0.3.2 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.3.2 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.3.2 doctor
 ```
 
-Managed install writes MCP config that launches:
+Managed installs write config that launches:
 
 ```toml
 [mcp_servers.satori]
 command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@4.9.0"]
+args = ["-y", "@zokizuan/satori-mcp@4.10.1"]
 startup_timeout_ms = 180000
 ```
 
-## Commands
+The installer only manages Satori-owned config and skills:
+
+- `satori-search`
+- `satori-navigation`
+- `satori-indexing`
+
+## Direct Tool Calls
 
 ```bash
-satori-cli doctor
 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.
 
-`doctor` checks local setup without starting an MCP client: Node version, npm package visibility, provider env, and Milvus env.
+`doctor` checks Node, package visibility, provider env, and Milvus env without starting an MCP client.
 
 ## Development
 
 ```bash
 pnpm --filter @zokizuan/satori-cli build
 pnpm --filter @zokizuan/satori-cli test
-pnpm --filter @zokizuan/satori-cli release:smoke
 ```

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

@@ -1,6 +1,6 @@
 ---
 name: satori-indexing
-description: Index lifecycle and remediation for Satori. Use when codebases are not indexed, stale, blocked, or need freshness recovery.
+description: Use when Satori codebases are not indexed, stale, blocked, still indexing, or need lifecycle recovery.
 ---
 
 # Satori Indexing
@@ -27,10 +27,12 @@ Use only:
 - 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,6 +1,6 @@
 ---
 name: satori-navigation
-description: Deterministic symbol navigation with Satori. Use after search results are found to lock exact spans and inspect call relationships.
+description: Use when search has returned candidate code and exact spans, symbol reads, or call relationships are needed.
 ---
 
 # Satori Navigation
@@ -14,12 +14,14 @@ Use only:
 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. 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.
+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
@@ -28,9 +30,10 @@ Use only:
 - `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`: reindex before retrying navigation.
-- `not_ready`: wait for indexing to finish.
+- `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,6 +1,6 @@
 ---
 name: satori-search
-description: Semantic-first code search with Satori. Use for intent-based code discovery before file reads or grep.
+description: Use when finding code by behavior, concept, or symbol before opening files or falling back to grep.
 ---
 
 # Satori Search
@@ -16,16 +16,17 @@ Use only:
 
 ## Workflow
 
-1. Check readiness with `manage_index(action="status", path=...)`.
+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 with `search_codebase(path=..., query=..., scope="runtime", resultMode="grouped", groupBy="symbol", rankingMode="auto_changed_first")`.
+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.
 
@@ -33,4 +34,6 @@ Use only:
 
 - `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Shell CLI for Satori MCP installation and skill-based workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@zokizuan/satori-mcp": "4.9.0"
+    "@zokizuan/satori-mcp": "4.10.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",