Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
docs(skill): steer the skill to ranges, and stop shipping install notes in it (#684)
Ian Hockc39f1bdc8192
diff --git a/docs/README.md b/docs/README.mdindex 438cb3c4..b19d9631 100644--- a/docs/README.md+++ b/docs/README.md@@ -5,4 +5,5 @@- [`ix mcp`](mcp.md) — serving the graph tools over MCP, and registering AI clients- [Consolidating the per-host plugins onto `ix mcp`](mcp-plugin-consolidation.md)- [System prerequisites](prerequisites.md) — what the installer checks for and installs+- [Installing the skill into a harness](skill-harnesses.md) — where `install-skill.sh` writes, and how it decides a harness is present- [Parse-pool teardown](parse-pool-teardown.md) — why nothing calls `terminate()`, and what was measureddiff --git a/docs/skill-harnesses.md b/docs/skill-harnesses.mdnew file mode 100644index 00000000..6eee8fb4--- /dev/null+++ b/docs/skill-harnesses.md@@ -0,0 +1,38 @@+# Installing the skill into a harness++Where `scripts/install-skill.sh` puts `skills/ix`, how it decides a harness is+present, and the two environment seams its probe battery reads.++This lived in `skills/ix/SKILL.md` until it was moved here. It is contributor+documentation: an agent that loads the skill to answer a question about a+codebase pays for every byte of it and can act on none of it.++The skill installer (`scripts/install-skill.sh`) reads an explicit, small harness table from `ix-cli/scripts/skill-harnesses.mjs` — claude, agents, codex and cursor only. Each entry's skills directory is verified against what that harness actually reads (Cursor uses `~/.cursor/skills-cursor`, not `~/.cursor/skills`); gemini, opencode, openclaw and vscode have no skills convention, so they are deliberately not install targets. Adding a harness is a one-line edit in that table, after checking where the harness really looks. `ix mcp install` uses the separate MCP host registry (`ix-cli/src/mcp/hosts.ts`) — a different table answering a different question.++When `TOOLSCAN_PATH` is set, both surfaces consult its discovery output so a harness CLI installed outside `PATH` can still be found — and `ix mcp install` executes the absolute path toolscan reports, so the off-PATH harness is inspected and registered through the binary toolscan found. Toolscan is optional and additive: if it is unset or fails, the embedded `PATH` and config-directory probes remain authoritative. `TOOLSCAN_PATH` is opt-in: neither surface ever looks `toolscan` up on `PATH` (the CLI executes whatever `TOOLSCAN_PATH` names, so only set it to a binary you trust).++The probe battery has two environment seams:++| Seam | Used by | Default |+|---|---|---|+| `TOOLSCAN_PATH` | `skill-harnesses.mjs --probe`, `ix mcp install` | Unset — no toolscan, embedded probes decide |+| `HARNESS_HOME` | `skill-harnesses.mjs --probe` | `os.homedir()`; `install-skill.sh` uses the shell's `$HOME` |++For a hermetic probe with no real user configuration:++```bash+HARNESS_HOME="$(mktemp -d)" \+ node ix-cli/scripts/skill-harnesses.mjs --probe+```++To drive the same probe with a local or npm-installed toolscan bundle:++```bash+TOOLSCAN_PATH=/path/to/toolscan/dist/toolscan.mjs \+ HARNESS_HOME="$(mktemp -d)" \+ node ix-cli/scripts/skill-harnesses.mjs --probe+```++`--probe` emits `id|label|bin|config-dir|skill-dir|present|detectedVia`, where `present` is `1` or `0` and `detectedVia` names the probe that decided (`toolscan` | `path` | `config-dir` | `none`). `scripts/install-skill.sh --dry-run --json` emits the same per-harness view as machine-readable JSON: one object per host with `action` (`would-install` | `would-refuse` | `installed` | `refused` | `skip`), `dest`, and `detectedVia` — so CI can assert *how* a harness was found, not just that it was. A `would-refuse` in the preview exits 1, matching the real run's conflict exit, so scripts can rely on the two agreeing.++The install report's `--format json|llm` output carries `detectedVia` per host (`toolscan` | `path` | `config-dir` | `none`), so a consumer can see which probe decided presence — a host toolscan found reads `toolscan` even when its CLI also happens to be on PATH, and a host found by the PATH probe reads `path` rather than being misattributed to its config directory.diff --git a/skills/ix/SKILL.md b/skills/ix/SKILL.mdindex 35a0a363..21112044 100644--- a/skills/ix/SKILL.md+++ b/skills/ix/SKILL.md@@ -1,6 +1,6 @@---name: ix-description: "This skill should be used when answering structural questions about a codebase: understanding what a symbol is, tracing flows, measuring change impact, finding callers/callees/imports, or detecting code smells. It drives the Ix CLI (ix map/explain/trace/impact/search/rank/smells) against a persistent code graph stored in a local backend, instead of grepping or guessing. Run scripts/bootstrap.sh once to install the CLI and start the backend, then ix map on the repo root."+description: "Answer structural questions about a codebase — what a symbol is, what calls it, what a change breaks, where the hotspots are — from a persistent code graph via the ix CLI, instead of grepping."license: Apache-2.0metadata:version: 1.0.0@@ -9,108 +9,70 @@ metadata:# Ix — Persistent Codebase Map-## Overview+Ix parses a repository with tree-sitter (26 languages) into a graph of symbols,+calls and imports, kept in a local backend (ArangoDB via Docker) and persisted+between sessions. Query it for structural answers — what a symbol is, what calls+it, how a flow moves, what a change breaks, which files carry the most weight,+where the smells are — instead of reading files to find out. It does not answer+prose or history questions.-Ix parses a repository with tree-sitter (26 languages), builds a graph of its symbols, calls, and imports, and stores it in a local backend (ArangoDB via Docker). Query that graph with `ix` commands to answer bounded, structural questions instead of reading files blindly. The graph persists between sessions.--Use this skill whenever the question is about structure, relationships, or impact: what a symbol is, what calls it, what it calls, how data flows, what breaks if a change lands, which files are most depended-on, or where the smells are.--## When to Use--- Answering "what is this / what does it touch" questions about a symbol, class, or module.-- Tracing how a flow moves through the system.-- Estimating blast radius before a change.-- Finding callers, callees, imports, and dependents.-- Detecting smells, ranking hotspots, and scoring subsystems.-- Onboarding to an unfamiliar codebase.--Do not use this skill for prose-style or history questions — use it for structural, graph-backed answers.--## Quick Start (first run)--Map the target repo with the bootstrap script:+## First run```bash-bash scripts/bootstrap.sh [repo-root] [--no-map] # Bash / Git Bash / macOS / Linux-powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 [repo-root] [-NoMap] # Windows PowerShell+bash scripts/bootstrap.sh [repo-root] [--no-map] # macOS / Linux / Git Bash+powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 [repo-root] [-NoMap] # Windows```-The bootstrap checks Node >= 22, git, Docker, and ripgrep; installs the `ix` CLI if missing; starts the local Docker backend; and maps the repo by default. Re-run `scripts/bootstrap.sh` on each new repo to register and map it.--Refresh the graph after code changes:+Checks Node >= 22, git, Docker and ripgrep, installs the CLI if missing, starts+the backend, and maps the repo. Re-run it per repo.-```bash-ix map --silent-```--## Core Workflow--Map → Explain → Trace → Impact+## Core workflow| Step | Command | Example ||---|---|---|-| Build/refresh the graph | `ix map` | `ix map .` |+| Bounded context to start from | `ix context` | `ix context IngestionService` || Understand a component | `ix explain` | `ix explain IngestionService` |-| Bounded deterministic context | `ix context` | `ix context IngestionService --max-entities 20` || Trace a flow | `ix trace` | `ix trace user_login_flow` |-| Analyze impact | `ix impact` | `ix impact verify_token --format llm` |--## Using the Skill--1. Start with high-level commands for one-shot answers: `ix overview`, `ix impact`, `ix rank`.-2. Drill down with primitives — `ix search`, `ix callers`, `ix callees`, `ix contains`, `ix imports`, `ix imported-by`, `ix depends` — reusing exact entity IDs from prior JSON output.-3. Prefer `--format llm` when reading output yourself (token-minimal); use `--format json` when chaining commands or extracting a field. See references/output-formats.md.-4. For the full command surface, decomposition recipes, and best practices, load references/commands.md; for a command's complete flag list, load references/flags.md.-5. If the backend is unreachable or a command fails, load references/troubleshooting.md.+| Blast radius of a change | `ix impact` | `ix impact verify_token` |+| Build / refresh the graph | `ix map` | `ix map .` |++## How to spend calls++1. **Start with `ix context <file-or-symbol>`** — one bounded call that names the+ files and symbols that matter, with line ranges.+2. **Read the ranges, not the files.** `ix read <symbol>`, or `path:120-180`, is+ one to three thousand tokens; the file around it is commonly thirty to sixty+ thousand — and every one of those is re-sent on every later step of the turn.+3. Drill down with primitives, reusing the exact entity IDs from earlier output:+ `ix search`, `ix callers`, `ix callees`, `ix contains`, `ix imports`,+ `ix imported-by`, `ix depends`.+4. **Do not poll `ix status`.** A command that needs the backend says so itself,+ with a hint; a health check in front of every call is a wasted round trip.+5. Format: `llm` is the one to read, and `IX_FORMAT=llm` (or+ `ix config set format llm`) makes it the default so it need not be typed per+ call; `json` is for chaining or extracting a field. On `ix context` the same+ answer runs about 7.6 : 0.8 : 1 for json : llm : text.## Rules-1. Before answering codebase questions, run targeted `ix` commands. Do not answer from training data alone.-2. After noticing contradictory information, run `ix conflicts` and present the results.-3. Never guess codebase facts — if Ix has structured data, use it.-4. Immediately after modifying code, run `ix map --silent` to re-ingest.-5. When Ix reports low confidence, mention the uncertainty to the user, suggest re-running `ix map`, and never present low-confidence data as established fact.--## Harness install seam--The skill installer (`scripts/install-skill.sh`) reads an explicit, small harness table from `ix-cli/scripts/skill-harnesses.mjs` — claude, agents, codex and cursor only. Each entry's skills directory is verified against what that harness actually reads (Cursor uses `~/.cursor/skills-cursor`, not `~/.cursor/skills`); gemini, opencode, openclaw and vscode have no skills convention, so they are deliberately not install targets. Adding a harness is a one-line edit in that table, after checking where the harness really looks. `ix mcp install` uses the separate MCP host registry (`ix-cli/src/mcp/hosts.ts`) — a different table answering a different question.--When `TOOLSCAN_PATH` is set, both surfaces consult its discovery output so a harness CLI installed outside `PATH` can still be found — and `ix mcp install` executes the absolute path toolscan reports, so the off-PATH harness is inspected and registered through the binary toolscan found. Toolscan is optional and additive: if it is unset or fails, the embedded `PATH` and config-directory probes remain authoritative. `TOOLSCAN_PATH` is opt-in: neither surface ever looks `toolscan` up on `PATH` (the CLI executes whatever `TOOLSCAN_PATH` names, so only set it to a binary you trust).--The probe battery has two environment seams:--| Seam | Used by | Default |-|---|---|---|-| `TOOLSCAN_PATH` | `skill-harnesses.mjs --probe`, `ix mcp install` | Unset — no toolscan, embedded probes decide |-| `HARNESS_HOME` | `skill-harnesses.mjs --probe` | `os.homedir()`; `install-skill.sh` uses the shell's `$HOME` |--For a hermetic probe with no real user configuration:--```bash-HARNESS_HOME="$(mktemp -d)" \- node ix-cli/scripts/skill-harnesses.mjs --probe-```--To drive the same probe with a local or npm-installed toolscan bundle:--```bash-TOOLSCAN_PATH=/path/to/toolscan/dist/toolscan.mjs \- HARNESS_HOME="$(mktemp -d)" \- node ix-cli/scripts/skill-harnesses.mjs --probe-```--`--probe` emits `id|label|bin|config-dir|skill-dir|present|detectedVia`, where `present` is `1` or `0` and `detectedVia` names the probe that decided (`toolscan` | `path` | `config-dir` | `none`). `scripts/install-skill.sh --dry-run --json` emits the same per-harness view as machine-readable JSON: one object per host with `action` (`would-install` | `would-refuse` | `installed` | `refused` | `skip`), `dest`, and `detectedVia` — so CI can assert *how* a harness was found, not just that it was. A `would-refuse` in the preview exits 1, matching the real run's conflict exit, so scripts can rely on the two agreeing.--The install report's `--format json|llm` output carries `detectedVia` per host (`toolscan` | `path` | `config-dir` | `none`), so a consumer can see which probe decided presence — a host toolscan found reads `toolscan` even when its CLI also happens to be on PATH, and a host found by the PATH probe reads `path` rather than being misattributed to its config directory.--## References--- **references/commands.md** — full command routing tables, decomposition recipes, best practices, and the do-not-use list. Load before running any command beyond the core four above.-- **references/flags.md** — every flag the CLI registers, per command, with values and defaults. Load when a command needs shaping beyond the examples in commands.md, or to check whether a flag exists before guessing.-- **references/output-formats.md** — `--format llm|json|text` rules, commands that do not implement `llm`, and Pro-gated commands. Load when formatting output or when a "requires Ix Pro" error appears.-- **references/troubleshooting.md** — prerequisites, backend health checks, `ix doctor`, and environment flags. Load when a command fails or the backend is unreachable.--## Scripts--- **scripts/bootstrap.sh** — cross-platform first-run setup (bash; works on macOS, Linux, and Windows under Git Bash / MSYS2 / WSL).-- **scripts/bootstrap.ps1** — native Windows PowerShell first-run setup.+1. Answer codebase questions from targeted `ix` commands, not from training data.+2. Never guess a codebase fact that Ix holds.+3. On contradictory information, run `ix conflicts` and present the results.+4. Refresh with `ix map --silent` when the graph has gone stale — after a branch+ switch, a pull, or a batch of edits. Editor plugins re-ingest edited files on+ a debounce; this is not a per-edit step.+5. When Ix reports low confidence, say so, suggest re-running `ix map`, and never+ present it as established fact.++## References — load on demand++- **references/commands.md** — command routing tables, decomposition recipes,+ best practices, the do-not-use list. Before any command beyond the table above.+- **references/flags.md** — every flag the CLI registers, per command, with+ values and defaults. Before guessing whether a flag exists.+- **references/output-formats.md** — the `llm|json|text` rules, what does not+ implement `llm`, and which commands are Pro-gated.+- **references/troubleshooting.md** — prerequisites, `ix doctor`, backend health,+ environment flags. When a command fails.+- **scripts/bootstrap.sh** / **scripts/bootstrap.ps1** — first-run setup (bash;+ and native PowerShell for Windows).diff --git a/skills/ix/references/commands.md b/skills/ix/references/commands.mdindex 418e67f6..90e0596e 100644--- a/skills/ix/references/commands.md+++ b/skills/ix/references/commands.md@@ -7,17 +7,23 @@ This file routes a goal to a command. For the complete flag surface of anycommand — every option, its accepted values and its default — see[flags.md](flags.md).+The examples carry no `--format`. Set it once instead of per call: `IX_FORMAT=llm`+in the environment, or `ix config set format llm`. `llm` is the format to read —+records, one per line, and on `ix context` roughly a ninth of the bytes of the+same answer in `json`. Reach for `--format json` on the one call whose output you+are going to parse. See [output-formats.md](output-formats.md).+## High-Level Workflow Commands (prefer first)These aggregate multiple graph operations into single bounded responses.| Goal | Command | Example ||---|---|---|-| Blast radius / impact | `ix impact` | `ix impact UserService --format llm` |-| Hotspot discovery | `ix rank` | `ix rank --by dependents --kind class --top 10 --format llm` |-| One-shot summary | `ix overview` | `ix overview IngestionService --format llm` |-| Deterministic context bundle | `ix context` | `ix context IngestionService --format llm` |-| Scoped entity listing | `ix inventory` | `ix inventory --kind function --path auth.py --format llm` |+| Blast radius / impact | `ix impact` | `ix impact UserService` |+| Hotspot discovery | `ix rank` | `ix rank --by dependents --kind class --top 10` |+| One-shot summary | `ix overview` | `ix overview IngestionService` |+| Deterministic context bundle | `ix context` | `ix context IngestionService` |+| Scoped entity listing | `ix inventory` | `ix inventory --kind function --path auth.py` |## Finding & Understanding Code@@ -26,7 +32,7 @@ These aggregate multiple graph operations into single bounded responses.| Find entity by name | `ix search` | `ix search IngestionService --kind class --limit 10` || Understand a symbol | `ix explain` | `ix explain IngestionService` || Read source code | `ix read` | `ix read src/auth.py:10-50` or `ix read verify_token` |-| Full entity details | `ix entity` | `ix entity <id> --format json` |+| Full entity details | `ix entity` | `ix entity <id>` || Fast text search | `ix text` | `ix text "verify_token" --language python --limit 20` || Find symbol (graph+text) | `ix locate` | `ix locate AuthProvider --kind class` |@@ -34,7 +40,7 @@ These aggregate multiple graph operations into single bounded responses.| Goal | Command | Example ||---|---|---|-| What calls a function | `ix callers` | `ix callers verify_token --format json` |+| What calls a function | `ix callers` | `ix callers verify_token` || What a function calls | `ix callees` | `ix callees processPayment` || Members of a class | `ix contains` | `ix contains IngestionService` || What an entity imports | `ix imports` | `ix imports auth_provider.py` |@@ -45,18 +51,18 @@ These aggregate multiple graph operations into single bounded responses.| Goal | Command | Example ||---|---|---|-| Entity history | `ix history` | `ix history <entityId> --format llm` |-| Changes between revisions | `ix diff` | `ix diff 1 5 --summary --format llm` |-| Detect contradictions | `ix conflicts` | `ix conflicts --format llm` |+| Entity history | `ix history` | `ix history <entityId>` |+| Changes between revisions | `ix diff` | `ix diff 1 5 --summary` |+| Detect contradictions | `ix conflicts` | `ix conflicts` |## Architecture Analysis| Goal | Command | Example ||---|---|---|-| Detect code smells | `ix smells` | `ix smells --format json` |-| Score subsystems | `ix subsystems` | `ix subsystems --level 2 --format json` |-| List smell claims | `ix smells --list` | `ix smells --list --format json` |-| List subsystem scores | `ix subsystems --list` | `ix subsystems --list --format json` |+| Detect code smells | `ix smells` | `ix smells` |+| Score subsystems | `ix subsystems` | `ix subsystems --level 2` |+| List smell claims | `ix smells --list` | `ix smells --list` |+| List subsystem scores | `ix subsystems --list` | `ix subsystems --list` |## Ingestion & Health@@ -67,14 +73,14 @@ These aggregate multiple graph operations into single bounded responses.| Backend health | `ix status` | `ix status` || System doctor | `ix doctor` | `ix doctor` || Start backend | `ix docker start` | `ix docker start` |-| Graph statistics | `ix stats` | `ix stats --format json` |+| Graph statistics | `ix stats` | `ix stats` |## Session Metrics| Goal | Command | Example ||---|---|---|-| Token savings so far | `ix savings` | `ix savings --format llm` |-| Per-command breakdown | `ix savings --detail` | `ix savings --detail --format llm` |+| Token savings so far | `ix savings` | `ix savings` |+| Per-command breakdown | `ix savings --detail` | `ix savings --detail` || Clear lifetime totals | `ix savings reset` | `ix savings reset` |`ix savings` reports how many tokens the graph saved against a naive@@ -92,7 +98,7 @@ estimates.|---|---|---|---|| `--detail` | — | off | Add one record per command type, within each scope || `--model <model>` | `opus\|sonnet\|haiku\|gpt-4o` | `opus` | Pricing table for `money_saved` only — token and water figures do not change |-| `--format <fmt>` | `text\|json\|llm` | `text` | See output-formats.md |+| `--format <fmt>` | `text\|json\|llm` | `IX_FORMAT`, else `format` in config, else `text` | See output-formats.md |`ix savings reset` clears **both** scopes (`DELETE /v1/savings`, which runs`session.set(empty) *> store.resetSavings`). It takes no flags, does not prompt,@@ -122,26 +128,26 @@ Reading a graph command's savings needs the backend up: the numbers come from**"How does ingestion work?"**```bash-ix overview IngestionService --format json # start here-ix contains IngestionService --format json # more detail if needed-ix callees parseFile --format json+ix overview IngestionService # start here+ix contains IngestionService # more detail if needed+ix callees parseFile```**"What depends on verify_token?"**```bash-ix impact verify_token --format json # one-shot answer-ix callers verify_token --format json # or manually-ix imported-by verify_token --format json+ix impact verify_token # one-shot answer+ix callers verify_token # or manually+ix imported-by verify_token```**"What are the most important classes?"**```bash-ix rank --by dependents --kind class --top 10 --format json+ix rank --by dependents --kind class --top 10```**"List all functions in a file"**```bash-ix inventory --kind function --path auth.py --format llm+ix inventory --kind function --path auth.py```## Best Practicesdiff --git a/skills/ix/references/output-formats.md b/skills/ix/references/output-formats.mdindex 22e958c9..4aa0bd29 100644--- a/skills/ix/references/output-formats.md+++ b/skills/ix/references/output-formats.md@@ -5,17 +5,31 @@Query commands accept `--format text|json|llm`:- **`--format llm`** — use when reading the result yourself. Token-minimal,- newline-delimited (`key=value`, one record per line). Smallest output.+ newline-delimited (`key=value`, one record per line). Smallest output; on+ `ix context` it is roughly a ninth of the same answer in `json`.- **`--format json`** — use when chaining results between commands or pulling aspecific field out of a response.- **`--format text`** — human-oriented tables and trees.+### Setting it once++Resolution is: the flag, then `IX_FORMAT`, then `format` in `~/.ix/config.yaml`+(`ix config set format llm`), then `text`. Set the env var or the config key and+stop passing the flag; an explicit `--format` still wins on the call that needs+something else. `ix config show` reports when `IX_FORMAT` is overriding the+stored value.++A command that does not implement the configured format keeps its own default+rather than being handed one it cannot render — `query` renders `text` and+`json` only, so `IX_FORMAT=llm` leaves it on `text`.+### Commands that accept `--format` but route `llm` to `text`-`explain`, `read`, `status`, and the deprecated `query` do not implement `llm`-and fall back to human-oriented text without an error. Use `--format json` on-those if the output needs to be parsed. Everywhere else, `llm` behaves as-documented.+The deprecated `query` takes `text|json` only. `diff --content` (verbatim hunks)+and `ingest` fall back to text without an error. `explain`, `read`, `status`,+`doctor` and `savings` **do** implement `llm` — that was the last prose+fallback, and `explain`'s records are about 55% smaller than the `json` people+used as a workaround.### Commands with no `--format` at all