Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

feat(skill): ship the ix agent skill and the HTTP API reference (#368)

Alot1z2157158446a7
diff --git a/.gitignore b/.gitignore
index 33cf633a..07bdbfa1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,13 @@
target/
+# Skill distribution artifact (skills/ix packaged zip).
+# Anchored: a bare `dist/` matches at any depth, which would also swallow
+# ix-cli/dist and core-ingestion/dist — already ignored explicitly below, and
+# better kept that way so the intent of each is visible.
+/dist/
+
+# Session/tooling artifacts (Freebuff preview state, generated knowledge graphs)
+.freebuff/
+.understand-anything/
.bsp/
.idea/
*.class
diff --git a/CLAUDE.md b/CLAUDE.md
index 56051842..3878dd61 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,3 +1,78 @@
+# Project: Ix (this repo)
+
+This checkout is **Ix itself** plus the **`ix` agent skill** that wraps it. The
+backend is NOT in this repo — it is the released Docker image running at
+`http://localhost:8090`; the Compass visualizer serves the SPA + API proxy on
+`http://localhost:8080`. Requires Node ≥ 22, git, Docker, ripgrep.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `ix-cli/` | The `@ix/cli` TypeScript package — command routing (`src/cli/`), registration hub (`src/cli/register/oss.ts`), HTTP client (`src/client/api.ts`), response types (`src/client/types.ts`) |
+| `core-ingestion/` | Tree-sitter parser/classifier (26 languages) |
+| `skills/ix/` | The agent skill this project ships: `SKILL.md`, `references/` (commands, output-formats, troubleshooting), `scripts/` (bootstrap.sh/ps1) |
+| `docs/` | `api/` (HTTP API reference + OpenAPI spec), `llm-format.md`, `prerequisites.md` |
+| `scripts/` | `bootstrap.sh` (first-run), `install-skill.sh` (deploy skill to `~/.claude/skills` + `~/.agents/skills`) |
+
+## Commands
+
+```bash
+# CLI dev (from ix-cli/)
+npm run build # build-core-ingestion + tsc
+npm run typecheck # tsc --noEmit
+npm test # build + vitest + parser smoke
+npm run dev # tsx src/cli/main.ts
+
+# Skill + tooling (from repo root)
+bash scripts/bootstrap.sh [repo-root] # install CLI, start backend, map repo
+bash scripts/install-skill.sh # deploy skills/ix to ~/.claude + ~/.agents
+# Repackage the skill zip into ./dist (gitignored). Needs the skill-creator
+# skill installed; on Windows set PYTHONIOENCODING=utf-8 or its emoji print crashes.
+python "$HOME/.agents/skills/skill-creator/scripts/package_skill.py" skills/ix ./dist
+
+# Visualizer / preview
+ix view start --all --no-open --port 8080 # combined multi-workspace view
+ix map --silent # refresh the graph after code changes
+```
+
+## Boundaries & Gotchas (all verified this session — write these down, they cost hours)
+
+- **`ix reset` is GLOBAL.** `ix reset` / `ix reset --code` take no workspace_id
+ and wipe **every** workspace's graph in the shared backend (Ix + packwise +
+ any other). The only scoped variant is `/v1/reset/workspace`, which the CLI
+ does not expose. After a reset, re-map each workspace.
+- **The OSS↔Pro command boundary is derived at runtime, not declared.**
+ `main.ts` snapshots `ossCmdNames` right after `registerOssCommands()`; the
+ Pro probe diffs against it. Adding a command to `oss.ts` silently makes it
+ OSS; removing one makes Pro own it. `registerProCommands` is async and MUST
+ be awaited.
+- **`registerPatchesCommand` is defined but never registered** in `oss.ts` —
+ `ix patches` is an "unknown command" today.
+- **`ix upgrade` wipes `~/.ix/cli/compass`.** The Compass assets ship only via
+ `ix upgrade`, and re-running the installer re-extracts over them, so a
+ re-install can leave `ix view` with no UI. `bootstrap.sh` re-runs `ix upgrade`
+ when it finds the directory missing; skip that with `IX_SKIP_COMPASS=1`.
+- **Windows path trap:** Git Bash `/tmp` ≠ Windows `C:\tmp` — node/python
+ cannot read files Git Bash wrote to `/tmp`. Use project-relative paths.
+
+## Patterns
+
+- **Skill edit workflow:** edit `skills/ix/` → `bash scripts/install-skill.sh`
+ to deploy to `~/.claude/skills/ix` and `~/.agents/skills/ix` → start a new
+ agent session so the skill is re-read.
+- **After modifying code:** run `ix map --silent` to re-ingest.
+
+## Typecheck & Test Discipline
+
+Run `npm run typecheck` (from `ix-cli/`) after non-trivial CLI edits and
+`node --check` on any edited standalone script before deploying.
+
+---
+
+The section below is the auto-generated Ix CLI command reference (regenerated by
+the Ix Memory system — do not hand-edit between the markers):
+
<!-- IX-MEMORY START -->
# Ix Memory System
diff --git a/README.md b/README.md
index 2ec60735..6e343545 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,46 @@ Windows (PowerShell):
irm https://raw.githubusercontent.com/ix-infrastructure/ix-cursor-plugin/main/install.ps1 | iex
```
+## Claude Code / Freebuff Skill
+
+[`skills/ix/`](skills/ix/SKILL.md) is a self-contained **Claude Code skill** (also
+loaded natively by Freebuff / Codebuff) that teaches any LLM agent to drive the
+`ix` CLI: build the graph, explain symbols, trace flows, analyze impact, and
+detect smells — instead of grepping and guessing.
+
+**Install it** (deploys to `~/.claude/skills/ix` and `~/.agents/skills/ix` so it
+works in every project):
+
+```bash
+bash scripts/install-skill.sh
+```
+
+Then start a new session and ask your agent to set it up:
+
+> Set up Ix and map this repo
+
+The skill's bootstrap script does the rest — installs the `ix` CLI if missing,
+starts the local Docker backend, and maps the current repo:
+
+```bash
+# Bash / Git Bash / macOS / Linux
+bash skills/ix/scripts/bootstrap.sh .
+
+# Windows PowerShell
+powershell -ExecutionPolicy Bypass -File skills/ix/scripts/bootstrap.ps1 .
+```
+
+The skill follows the progressive-disclosure layout — a lean `SKILL.md` with the
+full command reference, output-format rules, and troubleshooting split into
+`references/`, plus `scripts/` for first-run setup — so it is portable to Claude
+Code, Freebuff, and any other skill-compatible agent. Edit `skills/ix/` and
+re-run `scripts/install-skill.sh` to update your installed copy. To produce a
+distributable zip:
+
+```bash
+python "$HOME/.agents/skills/skill-creator/scripts/package_skill.py" skills/ix dist
+```
+
## Requirements
The install script sets up everything for you on macOS and Linux. It checks for and installs anything that is missing:
diff --git a/docs/api/README.md b/docs/api/README.md
new file mode 100644
index 00000000..d1fc53ae
--- /dev/null
+++ b/docs/api/README.md
@@ -0,0 +1,619 @@
+# Ix HTTP API Reference
+
+The Ix backend exposes a JSON-over-HTTP API on **`http://localhost:8090`** (the
+local Docker memory-layer). The `ix` CLI and the Compass visualizer are its two
+primary clients. This reference is generated from the client source
+(`ix-cli/src/client/api.ts`), the visualizer server template
+(`ix-cli/src/cli/commands/view.js`), and the shared client types
+(`ix-cli/src/client/types.ts`).
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Quick Start](#quick-start)
+3. [Authentication & Scoping](#authentication--scoping)
+4. [Base Endpoints](#base-endpoints)
+5. [Endpoints by Area](#endpoints-by-area)
+ - [Health & Capabilities](#health--capabilities)
+ - [Context & Question Answering](#context--question-answering)
+ - [Ingestion & Mapping](#ingestion--mapping)
+ - [Search & Discovery](#search--discovery)
+ - [Entities & Traversal](#entities--traversal)
+ - [Planning Artifacts](#planning-artifacts)
+ - [Patches & Provenance](#patches--provenance)
+ - [Analysis (Diff, Conflicts, Smells, Subsystems)](#analysis)
+ - [Stats & Savings](#stats--savings)
+ - [Reset](#reset)
+6. [Visualizer Proxy Surface](#visualizer-proxy-surface)
+7. [Data Models](#data-models)
+8. [Error Reference](#error-reference)
+9. [Timeouts & Deadlines](#timeouts--deadlines)
+10. [Versioning](#versioning)
+
+## Overview
+
+All endpoints are under `/v1` and speak JSON. Requests use `Content-Type:
+application/json`; responses are JSON objects. There is no version prefix other
+than `/v1`; schema compatibility is signaled by `schema_version` in
+`/v1/health`.
+
+The API has two logical surfaces:
+
+- **Backend API (direct, port 8090)** — used by the CLI.
+- **Visualizer proxy (port 8080)** — Compass serves the SPA and proxies every
+ `/v1/*` request to the backend, stamping workspace/system scoping headers.
+
+## Quick Start
+
+```bash
+# Liveness + graph schema version
+curl -s http://localhost:8090/v1/health
+
+# Ingest a repository
+curl -s -X POST http://localhost:8090/v1/ingest \
+ -H "Content-Type: application/json" \
+ -d '{"path": "/absolute/path/to/repo", "recursive": true}'
+
+# Search for a symbol
+curl -s -X POST http://localhost:8090/v1/search \
+ -H "Content-Type: application/json" \
+ -d '{"term": "IngestionService", "limit": 10, "kind": "class"}'
+
+# Get structured context for a question
+curl -s -X POST http://localhost:8090/v1/context \
+ -H "Content-Type: application/json" \
+ -d '{"query": "how does ingestion flow end to end?"}'
+```
+
+## Authentication & Scoping
+
+- **Local backend**: no authentication. The endpoint is bound to localhost.
+- **Scoping headers**: the visualizer proxy stamps `x-ix-workspace` (and
+ `x-ix-system` when the launch directory is part of a stitched multi-repo
+ system) on every proxied `/v1` request. The backend reads these as a
+ fallback when no explicit `workspace_id` / `system_id` is on the request.
+- **Query/body scoping**: most read endpoints accept optional `workspace_id`
+ and `system_id` parameters to bound the result set server-side.
+- **Pro features**: `GET /v1/capabilities` reports whether Pro features are
+ enabled. Treat an absent field as *unknown*, not *false* (older backends).
+
+## Base Endpoints
+
+| Method | Path | Client | Purpose |
+|---|---|---|---|
+| GET | `/v1/health` | `health()` | Liveness, status, `schema_version` |
+| GET | `/v1/capabilities` | `capabilities()` | Pro feature flags |
+| POST | `/v1/context` | `query()` | Structured-context QA |
+
+## Endpoints by Area
+
+### Health & Capabilities
+
+#### GET `/v1/health`
+
+Liveness probe. Returns `{"status": "ok", "schema_version": 3}`. A client whose
+expected schema version differs forces a clean re-ingest (e.g. after the
+absolute→relative `source_uri` migration).
+
+**Response**
+
+```json
+{ "status": "ok", "schema_version": 3 }
+```
+
+#### GET `/v1/capabilities`
+
+Feature-detection probe. Returns an object whose presence/absence drives
+client behavior.
+
+**Response**
+
+```json
+{ "proFeaturesEnabled": true }
+```
+
+### Context & Question Answering
+
+#### POST `/v1/context`
+
+Ask a bounded structural question; the backend returns claims, conflicts,
+decisions, intents, and the supporting subgraph.
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `query` | string | required — the question |
+| `asOfRev` | number | optional — read the graph as of this revision |
+| `depth` | string | optional — traversal depth hint |
+
+**Response** — `StructuredContext` (see [Data Models](#data-models)).
+
+### Ingestion & Mapping
+
+#### POST `/v1/ingest`
+
+Ingest a path into the graph. Long-running: the client allows **30 minutes**.
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `path` | string | required — absolute path to ingest |
+| `recursive` | boolean | optional |
+| `force` | boolean | optional — re-ingest unchanged files |
+
+**Response** — `IngestResult`:
+
+```json
+{
+ "filesProcessed": 128,
+ "patchesApplied": 142,
+ "filesSkipped": 3,
+ "entitiesCreated": 640,
+ "latestRev": 217,
+ "skipReasons": { "unchanged": 1, "emptyFile": 1, "parseError": 1, "tooLarge": 0 }
+}
+```
+
+#### POST `/v1/map`
+
+Return the full code map (systems → subsystems → members). The visualizer and
+`ix map` consume this. Reads **snake_case** keys off the raw body.
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `full` | boolean | default `false` |
+| `workspace_id` | string | optional — scope to a workspace |
+| `system_id` | string | optional — scope to a stitched system |
+
+**Response**
+
+```json
+{
+ "file_count": 409,
+ "region_count": 44,
+ "levels": 3,
+ "map_rev": 217,
+ "outcome": "ok",
+ "regions": [],
+ "edges": [],
+ "hierarchy": []
+}
+```
+
+#### POST `/v1/source-hashes`
+
+Workspace-scoped baseline lookup. Returns one row per `(workspace_id, uri)` so
+each file matches against its **own** workspace's hash (avoids collisions when
+workspaces share relative paths).
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `uris` | string[] | required — workspace-relative paths |
+| `workspaceIds` | string[] | optional — bounds the query server-side |
+
+**Response** — array of `{ workspaceId: string | null, uri: string, hash: string }`.
+
+#### GET `/v1/source-hashes/exists`
+
+Returns `{ "exists": boolean }` — whether an ingest baseline exists for the
+scoped workspace.
+
+#### POST `/v1/stitch`
+
+Cross-repo stitching (Ix#225 Path 2). Registers this workspace's published
+packages (`provides`) and production-dep external imports (`consumes`); the
+backend joins them bidirectionally against other workspaces and writes
+cross-repo `IMPORTS` edges.
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `workspaceId` | string | required |
+| `provides` | array | `{ name, entryNodeId, entryUri? }` |
+| `consumes` | array | `{ name, consumerNodeId }` |
+| `exports` | array | optional — `{ name, nodeId }` |
+| `symbolConsumes` | array | optional — `{ symbol, callerNodeId, pkg? }` |
+
+**Response** — `{ stitched: number, systemId: string | null, edges: [{ src, dst, name }] }`.
+
+#### GET `/v1/stitch/system/{workspaceId}`
+
+Return the `system_id` a workspace currently belongs to (null for a singleton).
+Older backends 404 — clients fall back to `{ systemId: null }`.
+
+### Search & Discovery
+
+#### POST `/v1/search`
+
+Search nodes by name/term.
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `term` | string | required |
+| `limit` | number | optional |
+| `kind` | string | optional — filter by entity kind |
+| `language` | string | optional |
+| `asOfRev` | number | optional |
+| `nameOnly` | boolean | optional |
+| `workspaceId` / `systemId` | string | optional — scope |
+
+**Response** — array of `GraphNode`.
+
+#### POST `/v1/search/semantic`
+
+Vector-similarity search. The backend embeds the term and returns nodes already
+ordered by similarity — **do not re-rank client-side**. The request field is
+`term` (not `query`); no `language` filter. Requires the extraction service
+(cloud); returns **503** when not configured.
+
+**Response** — array of `GraphNode`.
+
+#### POST `/v1/list`
+
+List entities by kind.
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `kind` | string | required |
+| `limit` | number | optional |
+| `scope` | string | optional |
+| `workspaceId` / `systemId` | string | optional |
+
+**Response** — array of `GraphNode`.
+
+### Entities & Traversal
+
+#### GET `/v1/entity/{id}`
+
+Fetch a node with its claims and edges.
+
+**Response** — `{ node: GraphNode, claims: unknown[], edges: unknown[] }`.
+
+#### GET `/v1/resolve-prefix/{prefix}`
+
+Resolve a shortened entity id prefix. Full UUIDs pass through untouched.
+
+**Response**
+
+```json
+{ "id": "900031a5-..." }
+```
+
+or, on ambiguity, `{ "error": "ambiguous", "matches": ["…"] }`; the client
+throws `Ambiguous prefix …` in that case.
+
+#### POST `/v1/expand`
+
+Expand a node's neighborhood.
+
+**Request body**
+
+| Field | Type | Default |
+|---|---|---|
+| `nodeId` | string | required |
+| `direction` | string | `"both"` |
+| `predicates` | string[] | — |
+| `hops` | number | `1` |
+
+**Response** — `{ nodes: GraphNode[], edges: GraphEdge[] }`.
+
+#### POST `/v1/expand-by-name`
+
+Same as expand, but by entity name.
+
+### Planning Artifacts
+
+Planning artifacts (goals, truth statements, decisions, bugs, tasks) persist
+across code-graph resets.
+
+#### GET `/v1/truth`
+
+List planning artifacts. **Response** — array of `GraphNode`.
+
+#### POST `/v1/truth`
+
+Create a goal/truth statement.
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `statement` | string | required |
+| `parentIntent` | string | optional |
+
+**Response** — `{ status: string, nodeId: string, rev: number }`.
+
+#### POST `/v1/decide`
+
+Record a decision.
+
+**Request body** — `{ title, rationale, intentId? }`.
+
+**Response** — `{ status, nodeId, rev }`.
+
+#### GET `/v1/decisions`
+
+List decisions. **Query**: `limit`, `topic`. **Response** — array of `GraphNode`.
+
+### Patches & Provenance
+
+#### GET `/v1/patches`
+
+List patches. **Query**: `limit`. **Response** — array of `PatchSummary`:
+
+```json
+[{ "patch_id": "…", "rev": 217, "intent": "…", "source_uri": "…", "timestamp": "…" }]
+```
+
+#### GET `/v1/patches/{id}`
+
+Fetch a single patch.
+
+#### POST `/v1/patch`
+
+Commit one patch. Client timeout **5 minutes**.
+
+**Request body** — `GraphPatchPayload` (see [Data Models](#data-models)).
+
+**Response** — `PatchCommitResult`: `{ status, rev }`.
+
+#### POST `/v1/patches/batch`
+
+Commit an array of patches directly as the body (not wrapped).
+
+#### POST `/v1/patches/bulk`
+
+Commit patches wrapped as `{ "patches": [...] }`. Client timeout **5 minutes**
+(prevents hangs when a k8s ingress closes idle connections).
+
+#### POST `/v1/provenance/{entityId}`
+
+Provenance for an entity.
+
+### Analysis
+
+#### POST `/v1/diff`
+
+Diff between graph revisions.
+
+**Request body**
+
+| Field | Type | Notes |
+|---|---|---|
+| `fromRev` | number | required |
+| `toRev` | number | required |
+| `entityId` | string | optional |
+| `summary` | boolean | optional |
+| `limit` | number | optional |
+
+#### GET `/v1/conflicts`
+
+List detected conflicts. **Response** — array of `ConflictReport`.
+
+#### POST `/v1/smells`
+
+Run smell analysis. **Query params**: `orphan-max-connections`, `god-module-chunks`,
+`god-module-fan`, `weak-max-neighbors`, `workspace_id`, `system_id`.
+
+#### GET `/v1/smells`
+
+List computed smells. **Query**: `workspace_id`, `system_id`.
+
+#### POST `/v1/subsystems/score`
+
+Score subsystems. **Query**: `workspace_id`, `system_id`.
+
+#### GET `/v1/subsystems`
+
+List subsystems. **Query**: `detailed`, `limit`, `offset`, `regions`,
+`edge_cap`, `member_file_cap`, `workspace_id`, `system_id`.
+
+#### GET `/v1/subsystems/map`
+
+Subsystem map for the visualizer. **Query**: `target` (entity id), `pick`
+(1-based candidate for ambiguous targets), `workspace_id`, `system_id`.
+
+### Stats & Savings
+
+#### GET `/v1/stats`
+
+Graph statistics. **Query**: `workspace_id`, `system_id`.
+
+**Response** — node/edge totals by kind:
+
+```json
+{
+ "nodes": { "total": 10144, "byKind": [ { "kind": "function", "count": 1883 } ] },
+ "edges": { "total": 26084, "byKind": [ … ] }
+}
+```
+
+#### GET `/v1/savings`
+
+Token-savings metrics. **Query**: `detail=true` for detail.
+
+#### DELETE `/v1/savings`
+
+Reset savings metrics.
+
+### Reset
+
+> ⚠️ **`ix reset` is GLOBAL.** The reset endpoints below take **no
+> workspace_id** and wipe every workspace's graph in the shared backend. The
+> only scoped variant is `/v1/reset/workspace`, which the CLI does not expose.
+
+| Method | Path | Behavior |
+|---|---|---|
+| POST | `/v1/reset` | Wipe **all** nodes and edges (sync; local endpoints) |
+| POST | `/v1/reset/async` | Begin an async wipe (remote endpoints) |
+| POST | `/v1/reset/code` | Wipe only the code graph, preserving planning artifacts |
+| POST | `/v1/reset/code/async` | Async variant of the code wipe |
+| GET | `/v1/reset/status/{opId}` | Poll async op — `{ state: "done" \| "failed", error? }` |
+| POST | `/v1/reset/workspace` | **Scoped** wipe — `{ workspaceId }`; other workspaces untouched |
+
+**Async reset flow (client-side):** local endpoints use the sync path; remote
+endpoints begin via `/async`, then poll `/v1/reset/status/{opId}` every 2s up
+to 15 minutes. A 404 on `begin` falls back to the sync path (old backend); a
+404 on `status` means the op was lost to a server restart — reset is idempotent,
+so re-run to confirm.
+
+## Visualizer Proxy Surface
+
+Compass (`ix view`, default port **8080**) adds three behaviors on top of the
+backend:
+
+1. **`/v1/*` proxy** — every backend request is proxied to `localhost:8090`
+ with `x-ix-workspace` and `x-ix-system` headers baked in at launch, so the
+ browser app never knows about workspaces. `--all` opts out of scoping.
+2. **SPA fallback** — any other path serves `index.html`. There is no
+ `/__ix/remap` endpoint: a `POST` to it falls through to this handler and
+ returns the SPA HTML with a `200`, so a caller cannot tell it did nothing.
+ Re-map from the CLI with `ix map .` instead.
+
+## Data Models
+
+### GraphNode
+
+```ts
+interface GraphNode {
+ id: string;
+ kind: string; // function | class | file | module | region | …
+ name: string;
+ attrs: Record<string, unknown>;
+ provenance: {
+ sourceUri: string; // workspace-relative path (POSIX separators)
+ sourceHash?: string;
+ extractor: string;
+ sourceType: string;
+ observedAt: string;
+ };
+ createdRev: number;
+ deletedRev?: number;
+ createdAt: string;
+ updatedAt: string;
+}
+```
+
+### GraphEdge
+
+```ts
+interface GraphEdge {
+ id: string;
+ src: string;
+ dst: string;
+ predicate: string; // calls | imports | contains | …
+ attrs: Record<string, unknown>;
+ createdRev: number;
+ deletedRev?: number;
+}
+```
+
+### StructuredContext
+
+```ts
+interface StructuredContext {
+ claims: ScoredClaim[];
+ compactClaims?: CompactScoredClaim[];
+ conflicts: ConflictReport[];
+ decisions: DecisionReport[];
+ intents: IntentReport[];
+ nodes: GraphNode[];
+ edges: GraphEdge[];
+ metadata: { query: string; seedEntities: string[]; hopsExpanded: number; asOfRev: number; depth?: string };
+}
+```
+
+### IngestResult
+
+```ts
+interface IngestResult {
+ filesProcessed: number;
+ patchesApplied: number;
+ filesSkipped?: number;
+ entitiesCreated: number;
+ latestRev: number;
+ skipReasons?: { unchanged: number; emptyFile: number; parseError: number; tooLarge: number; minifiedLikely?: number };
+}
+```
+
+### GraphPatchPayload
+
+```ts
+interface GraphPatchPayload {
+ patchId: string;
+ actor: string;
+ timestamp: string;
+ source: {
+ uri: string; // workspace-relative, opaque key for joins/tombstones
+ sourceHash?: string;
+ extractor: string;
+ sourceType: string;
+ workspaceId?: string; // SHA-256 of the workspace root path
+ };
+ baseRev: number;
+ ops: Array<{ type: string; [k: string]: unknown }>;
+ replaces: string[];
+ intent?: string;
+}
+```
+
+### PatchCommitResult
+
+```ts
+interface PatchCommitResult { status: string; rev: number; }
+```
+
+### HealthResponse
+
+```ts
+interface HealthResponse { status: string; schema_version?: number; }
+```
+
+### CapabilitiesResponse
+
+```ts
+interface CapabilitiesResponse { proFeaturesEnabled?: boolean; }
+```
+
+## Error Reference
+
+| Code | Meaning |
+|---|---|
+| `4xx` | Client error — body is plain text (not JSON), surfaced as `"<status>: <text>"` |
+| `404` | Unknown endpoint / entity / lost async op / old backend without async endpoints |
+| `502` | Cloud proxy timeout on long sync ops — use the async variants |
+| `503` | `/v1/search/semantic` without the extraction service configured |
+
+Client error convention: `IxClient` throws `Error("<status>: <text>")` on any
+non-`ok` response, so CLI errors carry both the HTTP status and the raw body.
+
+## Timeouts & Deadlines
+
+| Operation | Per-request timeout |
+|---|---|
+| General `get` / `post` | 2 minutes |
+| `POST /v1/patch`, `/v1/patches/bulk` | 5 minutes |
+| `POST /v1/ingest`, `/v1/map` | 30 minutes |
+| Async reset begin / status poll | 30 seconds each |
+| Sync reset (local) | 10 minutes |
+| Shared deadline (`ix map`) | hard wall-clock budget; aborts all in-flight requests via `AbortSignal.any` |
+
+## Versioning
+
+- The graph has a schema version (`/v1/health.schema_version`, currently `v3`);
+ a mismatch forces a clean re-ingest.
+- Endpoints are additive under `/v1`; the `capabilities` probe is the
+ recommended way to feature-detect rather than hard-code against versions.
+- Older backends may 404 new endpoints (`/v1/stitch/system/*`, async reset) —
+ clients implement fallbacks, and so should any new client code.
diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
new file mode 100644
index 00000000..a9a3ca38
--- /dev/null
+++ b/docs/api/openapi.yaml
@@ -0,0 +1,1101 @@
+openapi: 3.0.0
+info:
+ title: Ix Backend API
+ description: |
+ JSON-over-HTTP API for the Ix persistent codebase graph. Served by the
+ local backend at http://localhost:8090 (Docker memory-layer). The `ix` CLI
+ and Compass visualizer are the primary clients. Local deployments have no
+ authentication; remote deployments may gate Pro features (see
+ /v1/capabilities). Scoping is via `workspace_id` / `system_id` query/body
+ params, or the `x-ix-workspace` / `x-ix-system` headers stamped by the
+ visualizer proxy.
+ version: "1.0.0"
+ contact:
+ name: Ix
+ url: https://github.com/ix-infrastructure/Ix
+servers:
+ - url: http://localhost:8090
+ description: Local backend (Docker memory-layer)
+ - url: http://localhost:8080
+ description: Compass visualizer (proxies /v1 to the backend)
+tags:
+ - name: health
+ - name: context
+ - name: ingestion
+ - name: search
+ - name: entities
+ - name: planning
+ - name: patches
+ - name: analysis
+ - name: stats
+ - name: reset
+
+paths:
+ /v1/health:
+ get:
+ tags: [health]
+ summary: Liveness probe and graph schema version
+ operationId: getHealth
+ responses:
+ "200":
+ description: Healthy
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/HealthResponse"
+
+ /v1/capabilities:
+ get:
+ tags: [health]
+ summary: Feature detection (Pro flags)
+ operationId: getCapabilities
+ responses:
+ "200":
+ description: Capability flags
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/CapabilitiesResponse"
+
+ /v1/context:
+ post:
+ tags: [context]
+ summary: Structured-context question answering
+ operationId: queryContext
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [query]
+ properties:
+ query: { type: string }
+ asOfRev: { type: integer, description: Read the graph as of this revision }
+ depth: { type: string, description: Traversal depth hint }
+ responses:
+ "200":
+ description: Structured context
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/StructuredContext"
+
+ /v1/ingest:
+ post:
+ tags: [ingestion]
+ summary: Ingest a path into the graph (long-running, up to 30 min)
+ operationId: ingest
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [path]
+ properties:
+ path: { type: string, description: Absolute path to ingest }
+ recursive: { type: boolean }
+ force: { type: boolean, description: Re-ingest unchanged files }
+ responses:
+ "200":
+ description: Ingestion result
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/IngestResult"
+
+ /v1/map:
+ post:
+ tags: [ingestion]
+ summary: Full code map (systems → subsystems → members)
+ operationId: getMap
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ full: { type: boolean, default: false }
+ workspace_id: { type: string }
+ system_id: { type: string }
+ responses:
+ "200":
+ description: Code map
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ file_count: { type: integer }
+ region_count: { type: integer }
+ levels: { type: integer }
+ map_rev: { type: integer }
+ outcome: { type: string }
+ regions: { type: array, items: { type: object } }
+ edges: { type: array, items: { type: object } }
+ hierarchy: { type: array, items: { type: object } }
+
+ /v1/source-hashes:
+ post:
+ tags: [ingestion]
+ summary: Workspace-scoped source-hash baseline lookup
+ operationId: getSourceHashes
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [uris]
+ properties:
+ uris: { type: array, items: { type: string }, description: Workspace-relative paths }
+ workspaceIds: { type: array, items: { type: string } }
+ responses:
+ "200":
+ description: One row per (workspace_id, uri)
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+ properties:
+ workspaceId:
+ type: string
+ nullable: true
+ uri: { type: string }
+ hash: { type: string }
+
+ /v1/source-hashes/exists:
+ get:
+ tags: [ingestion]
+ summary: Whether an ingest baseline exists
+ operationId: hasIngestBaseline
+ responses:
+ "200":
+ description: Baseline existence
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ exists: { type: boolean }
+
+ /v1/stitch:
+ post:
+ tags: [ingestion]
+ summary: Cross-repo stitching (register provides/consumes, join edges)
+ operationId: stitch
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [workspaceId, provides, consumes]
+ properties:
+ workspaceId: { type: string }
+ provides:
+ type: array
+ items:
+ type: object
+ required: [name, entryNodeId]
+ properties:
+ name: { type: string }
+ entryNodeId: { type: string }
+ entryUri: { type: string }
+ consumes:
+ type: array
+ items:
+ type: object
+ required: [name, consumerNodeId]
+ properties:
+ name: { type: string }
+ consumerNodeId: { type: string }
+ exports:
+ type: array
+ items:
+ type: object
+ properties:
+ name: { type: string }
+ nodeId: { type: string }
+ symbolConsumes:
+ type: array
+ items:
+ type: object
+ properties:
+ symbol: { type: string }
+ callerNodeId: { type: string }
+ pkg: { type: string }
+ responses:
+ "200":
+ description: Stitch result
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ stitched: { type: integer }
+ systemId:
+ type: string
+ nullable: true
+ edges:
+ type: array
+ items:
+ type: object
+ properties:
+ src: { type: string }
+ dst: { type: string }
+ name: { type: string }
+
+ /v1/stitch/system/{workspaceId}:
+ get:
+ tags: [ingestion]
+ summary: System id a workspace belongs to (null for singleton)
+ operationId: workspaceSystem
+ parameters:
+ - name: workspaceId
+ in: path
+ required: true
+ schema: { type: string }
+ responses:
+ "200":
+ description: System membership
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ systemId:
+ type: string
+ nullable: true
+
+ /v1/search:
+ post:
+ tags: [search]
+ summary: Search nodes by term
+ operationId: search
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [term]
+ properties:
+ term: { type: string }
+ limit: { type: integer }
+ kind: { type: string }
+ language: { type: string }
+ asOfRev: { type: integer }
+ nameOnly: { type: boolean }
+ workspaceId: { type: string }
+ systemId: { type: string }
+ responses:
+ "200":
+ description: Matching nodes
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/GraphNode"
+
+ /v1/search/semantic:
+ post:
+ tags: [search]
+ summary: Vector-similarity search (ordered by similarity; do not re-rank)
+ operationId: semanticSearch
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [term]
+ properties:
+ term: { type: string }
+ limit: { type: integer }
+ kind: { type: string }
+ workspaceId: { type: string }
+ systemId: { type: string }
+ responses:
+ "200":
+ description: Nodes ordered by similarity
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/GraphNode"
+ "503":
+ description: Extraction service not configured
+
+ /v1/list:
+ post:
+ tags: [search]
+ summary: List entities by kind
+ operationId: listByKind
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [kind]
+ properties:
+ kind: { type: string }
+ limit: { type: integer }
+ scope: { type: string }
+ workspaceId: { type: string }
+ systemId: { type: string }
+ responses:
+ "200":
+ description: Entities
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/GraphNode"
+
+ /v1/entity/{id}:
+ get:
+ tags: [entities]
+ summary: Fetch a node with claims and edges
+ operationId: getEntity
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema: { type: string }
+ responses:
+ "200":
+ description: Node bundle
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ node: { $ref: "#/components/schemas/GraphNode" }
+ claims: { type: array, items: { type: object } }
+ edges: { type: array, items: { $ref: "#/components/schemas/GraphEdge" } }
+
+ /v1/resolve-prefix/{prefix}:
+ get:
+ tags: [entities]
+ summary: Resolve a shortened id prefix
+ operationId: resolvePrefix
+ parameters:
+ - name: prefix
+ in: path
+ required: true
+ schema: { type: string }
+ responses:
+ "200":
+ description: Resolved id or ambiguity error
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ id: { type: string }
+ error: { type: string, enum: [ambiguous] }
+ matches: { type: array, items: { type: string } }
+
+ /v1/expand:
+ post:
+ tags: [entities]
+ summary: Expand a node's neighborhood
+ operationId: expand
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [nodeId]
+ properties:
+ nodeId: { type: string }
+ direction: { type: string, default: both }
+ predicates: { type: array, items: { type: string } }
+ hops: { type: integer, default: 1 }
+ responses:
+ "200":
+ description: Neighborhood
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ nodes: { type: array, items: { $ref: "#/components/schemas/GraphNode" } }
+ edges: { type: array, items: { $ref: "#/components/schemas/GraphEdge" } }
+
+ /v1/expand-by-name:
+ post:
+ tags: [entities]
+ summary: Expand by entity name
+ operationId: expandByName
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [name]
+ properties:
+ name: { type: string }
+ direction: { type: string, default: both }
+ predicates: { type: array, items: { type: string } }
+ kinds: { type: array, items: { type: string } }
+ responses:
+ "200":
+ description: Neighborhood
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ nodes: { type: array, items: { $ref: "#/components/schemas/GraphNode" } }
+ edges: { type: array, items: { $ref: "#/components/schemas/GraphEdge" } }
+
+ /v1/truth:
+ get:
+ tags: [planning]
+ summary: List planning artifacts (goals, truth statements)
+ operationId: listTruth
+ responses:
+ "200":
+ description: Artifacts
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/GraphNode"
+ post:
+ tags: [planning]
+ summary: Create a goal/truth statement
+ operationId: createTruth
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [statement]
+ properties:
+ statement: { type: string }
+ parentIntent: { type: string }
+ responses:
+ "200":
+ description: Created artifact
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/NodeCreationResult"
+
+ /v1/decide:
+ post:
+ tags: [planning]
+ summary: Record a decision
+ operationId: decide
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [title, rationale]
+ properties:
+ title: { type: string }
+ rationale: { type: string }
+ intentId: { type: string }
+ responses:
+ "200":
+ description: Created decision
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/NodeCreationResult"
+
+ /v1/decisions:
+ get:
+ tags: [planning]
+ summary: List decisions
+ operationId: listDecisions
+ parameters:
+ - name: limit
+ in: query
+ schema: { type: integer }
+ - name: topic
+ in: query
+ schema: { type: string }
+ responses:
+ "200":
+ description: Decisions
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/GraphNode"
+
+ /v1/patches:
+ get:
+ tags: [patches]
+ summary: List patches
+ operationId: listPatches
+ parameters:
+ - name: limit
+ in: query
+ schema: { type: integer }
+ responses:
+ "200":
+ description: Patch summaries
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/PatchSummary"
+
+ /v1/patches/{id}:
+ get:
+ tags: [patches]
+ summary: Fetch a single patch
+ operationId: getPatch
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema: { type: string }
+ responses:
+ "200":
+ description: Patch
+
+ /v1/patch:
+ post:
+ tags: [patches]
+ summary: Commit a single patch (5 min client timeout)
+ operationId: commitPatch
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/GraphPatchPayload"
+ responses:
+ "200":
+ description: Commit result
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/PatchCommitResult"
+
+ /v1/patches/batch:
+ post:
+ tags: [patches]
+ summary: Commit an array of patches (unwrapped body)
+ operationId: commitPatchBatch
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/GraphPatchPayload"
+ responses:
+ "200":
+ description: Commit results
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/PatchCommitResult"
+
+ /v1/patches/bulk:
+ post:
+ tags: [patches]
+ summary: "Commit patches wrapped as { patches: [...] } (5 min client timeout)"
+ operationId: commitPatchBulk
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [patches]
+ properties:
+ patches:
+ type: array
+ items:
+ $ref: "#/components/schemas/GraphPatchPayload"
+ responses:
+ "200":
+ description: Commit results
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/PatchCommitResult"
+
+ /v1/provenance/{entityId}:
+ post:
+ tags: [patches]
+ summary: Provenance for an entity
+ operationId: provenance
+ parameters:
+ - name: entityId
+ in: path
+ required: true
+ schema: { type: string }
+ responses:
+ "200":
+ description: Provenance
+
+ /v1/diff:
+ post:
+ tags: [analysis]
+ summary: Diff between graph revisions
+ operationId: diff
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [fromRev, toRev]
+ properties:
+ fromRev: { type: integer }
+ toRev: { type: integer }
+ entityId: { type: string }
+ summary: { type: boolean }
+ limit: { type: integer }
+ responses:
+ "200":
+ description: Diff
+
+ /v1/conflicts:
+ get:
+ tags: [analysis]
+ summary: List detected conflicts
+ operationId: conflicts
+ responses:
+ "200":
+ description: Conflicts
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+
+ /v1/smells:
+ get:
+ tags: [analysis]
+ summary: List computed smells
+ operationId: listSmells
+ parameters:
+ - name: workspace_id
+ in: query
+ schema: { type: string }
+ - name: system_id
+ in: query
+ schema: { type: string }
+ responses:
+ "200":
+ description: Smells
+ post:
+ tags: [analysis]
+ summary: Run smell analysis
+ operationId: runSmells
+ parameters:
+ - name: orphan-max-connections
+ in: query
+ schema: { type: integer }
+ - name: god-module-chunks
+ in: query
+ schema: { type: integer }
+ - name: god-module-fan
+ in: query
+ schema: { type: integer }
+ - name: weak-max-neighbors
+ in: query
+ schema: { type: integer }
+ - name: workspace_id
+ in: query
+ schema: { type: string }
+ - name: system_id
+ in: query
+ schema: { type: string }
+ responses:
+ "200":
+ description: Smell analysis result
+
+ /v1/subsystems:
+ get:
+ tags: [analysis]
+ summary: List subsystems
+ operationId: listSubsystems
+ parameters:
+ - name: detailed
+ in: query
+ schema: { type: boolean }
+ - name: limit
+ in: query
+ schema: { type: integer }
+ - name: offset
+ in: query
+ schema: { type: integer }
+ - name: regions
+ in: query
+ schema: { type: string }
+ - name: edge_cap
+ in: query
+ schema: { type: integer }
+ - name: member_file_cap
+ in: query
+ schema: { type: integer }
+ - name: workspace_id
+ in: query
+ schema: { type: string }
+ - name: system_id
+ in: query
+ schema: { type: string }
+ responses:
+ "200":
+ description: Subsystems
+
+ /v1/subsystems/score:
+ post:
+ tags: [analysis]
+ summary: Score subsystems
+ operationId: scoreSubsystems
+ parameters:
+ - name: workspace_id
+ in: query
+ schema: { type: string }
+ - name: system_id
+ in: query
+ schema: { type: string }
+ responses:
+ "200":
+ description: Scores
+
+ /v1/subsystems/map:
+ get:
+ tags: [analysis]
+ summary: Subsystem map for the visualizer
+ operationId: getSubsystemMap
+ parameters:
+ - name: target
+ in: query
+ schema: { type: string }
+ - name: pick
+ in: query
+ schema: { type: integer, description: 1-based candidate for ambiguous targets }
+ - name: workspace_id
+ in: query
+ schema: { type: string }
+ - name: system_id
+ in: query
+ schema: { type: string }
+ responses:
+ "200":
+ description: Subsystem map
+
+ /v1/stats:
+ get:
+ tags: [stats]
+ summary: Graph statistics
+ operationId: stats
+ parameters:
+ - name: workspace_id
+ in: query
+ schema: { type: string }
+ - name: system_id
+ in: query
+ schema: { type: string }
+ responses:
+ "200":
+ description: Node/edge totals by kind
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ nodes:
+ type: object
+ properties:
+ total: { type: integer }
+ byKind:
+ type: array
+ items:
+ type: object
+ properties:
+ kind: { type: string }
+ count: { type: integer }
+ edges:
+ type: object
+ properties:
+ total: { type: integer }
+ byKind:
+ type: array
+ items:
+ type: object
+ properties:
+ kind: { type: string }
+ count: { type: integer }
+
+ /v1/savings:
+ get:
+ tags: [stats]
+ summary: Token-savings metrics
+ operationId: savings
+ parameters:
+ - name: detail
+ in: query
+ schema: { type: boolean }
+ responses:
+ "200":
+ description: Savings metrics
+ delete:
+ tags: [stats]
+ summary: Reset savings metrics
+ operationId: savingsReset
+ responses:
+ "200":
+ description: Reset confirmation
+
+ /v1/reset:
+ post:
+ tags: [reset]
+ summary: Wipe ALL nodes and edges (global — no workspace scoping)
+ operationId: reset
+ responses:
+ "200":
+ description: Reset confirmation
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ResetResult"
+
+ /v1/reset/async:
+ post:
+ tags: [reset]
+ summary: Begin an async wipe (remote deployments)
+ operationId: resetAsync
+ responses:
+ "200":
+ description: Operation handle
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ opId: { type: string }
+
+ /v1/reset/status/{opId}:
+ get:
+ tags: [reset]
+ summary: Poll an async reset operation
+ operationId: resetStatus
+ parameters:
+ - name: opId
+ in: path
+ required: true
+ schema: { type: string }
+ responses:
+ "200":
+ description: Operation state
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ state: { type: string, enum: [done, failed, running] }
+ error:
+ type: string
+ nullable: true
+
+ /v1/reset/code:
+ post:
+ tags: [reset]
+ summary: Wipe only the code graph (preserves planning artifacts)
+ operationId: resetCode
+ responses:
+ "200":
+ description: Reset confirmation
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ResetResult"
+
+ /v1/reset/code/async:
+ post:
+ tags: [reset]
+ summary: Begin an async code-graph wipe
+ operationId: resetCodeAsync
+ responses:
+ "200":
+ description: Operation handle
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ opId: { type: string }
+
+ /v1/reset/workspace:
+ post:
+ tags: [reset]
+ summary: Wipe exactly one workspace (other workspaces untouched)
+ operationId: deleteWorkspace
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [workspaceId]
+ properties:
+ workspaceId: { type: string }
+ responses:
+ "200":
+ description: Workspace wiped
+
+components:
+ schemas:
+ HealthResponse:
+ type: object
+ properties:
+ status: { type: string }
+ schema_version: { type: integer, description: On-disk graph format version }
+ CapabilitiesResponse:
+ type: object
+ properties:
+ proFeaturesEnabled:
+ type: boolean
+ description: Absent = unknown (older backends), not false
+ GraphNode:
+ type: object
+ required: [id, kind, name, attrs, provenance, createdRev, createdAt, updatedAt]
+ properties:
+ id: { type: string }
+ kind: { type: string }
+ name: { type: string }
+ attrs: { type: object, additionalProperties: true }
+ provenance:
+ type: object
+ properties:
+ sourceUri: { type: string, description: Workspace-relative path }
+ sourceHash: { type: string }
+ extractor: { type: string }
+ sourceType: { type: string }
+ observedAt: { type: string, format: date-time }
+ createdRev: { type: integer }
+ deletedRev: { type: integer }
+ createdAt: { type: string, format: date-time }
+ updatedAt: { type: string, format: date-time }
+ GraphEdge:
+ type: object
+ required: [id, src, dst, predicate, attrs, createdRev]
+ properties:
+ id: { type: string }
+ src: { type: string }
+ dst: { type: string }
+ predicate: { type: string, description: calls | imports | contains | … }
+ attrs: { type: object, additionalProperties: true }
+ createdRev: { type: integer }
+ deletedRev: { type: integer }
+ StructuredContext:
+ type: object
+ properties:
+ claims: { type: array, items: { type: object } }
+ compactClaims: { type: array, items: { type: object } }
+ conflicts: { type: array, items: { type: object } }
+ decisions: { type: array, items: { type: object } }
+ intents: { type: array, items: { type: object } }
+ nodes: { type: array, items: { $ref: "#/components/schemas/GraphNode" } }
+ edges: { type: array, items: { $ref: "#/components/schemas/GraphEdge" } }
+ metadata:
+ type: object
+ properties:
+ query: { type: string }
+ seedEntities: { type: array, items: { type: string } }
+ hopsExpanded: { type: integer }
+ asOfRev: { type: integer }
+ depth: { type: string }
+ IngestResult:
+ type: object
+ properties:
+ filesProcessed: { type: integer }
+ patchesApplied: { type: integer }
+ filesSkipped: { type: integer }
+ entitiesCreated: { type: integer }
+ latestRev: { type: integer }
+ skipReasons:
+ type: object
+ properties:
+ unchanged: { type: integer }
+ emptyFile: { type: integer }
+ parseError: { type: integer }
+ tooLarge: { type: integer }
+ minifiedLikely: { type: integer }
+ NodeCreationResult:
+ type: object
+ properties:
+ status: { type: string }
+ nodeId: { type: string }
+ rev: { type: integer }
+ PatchSummary:
+ type: object
+ properties:
+ patch_id: { type: string }
+ rev: { type: integer }
+ intent: { type: string }
+ source_uri: { type: string }
+ timestamp: { type: string }
+ PatchSource:
+ type: object
+ required: [uri, extractor, sourceType]
+ properties:
+ uri: { type: string, description: Workspace-relative path; opaque join key }
+ sourceHash: { type: string }
+ extractor: { type: string }
+ sourceType: { type: string }
+ workspaceId: { type: string, description: SHA-256 of the workspace root path }
+ PatchOp:
+ type: object
+ required: [type]
+ properties:
+ type: { type: string }
+ additionalProperties: true
+ GraphPatchPayload:
+ type: object
+ required: [patchId, actor, timestamp, source, baseRev, ops, replaces]
+ properties:
+ patchId: { type: string }
+ actor: { type: string }
+ timestamp: { type: string, format: date-time }
+ source: { $ref: "#/components/schemas/PatchSource" }
+ baseRev: { type: integer }
+ ops: { type: array, items: { $ref: "#/components/schemas/PatchOp" } }
+ replaces: { type: array, items: { type: string } }
+ intent: { type: string }
+ PatchCommitResult:
+ type: object
+ properties:
+ status: { type: string }
+ rev: { type: integer }
+ ResetResult:
+ type: object
+ properties:
+ ok: { type: boolean }
+ message: { type: string }
diff --git a/scripts/install-skill.sh b/scripts/install-skill.sh
new file mode 100644
index 00000000..86243543
--- /dev/null
+++ b/scripts/install-skill.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+#
+# Install the Ix skill so Claude Code and Freebuff can use it.
+#
+# Deploys skills/ix to:
+# ~/.claude/skills/ix — Claude Code (global)
+# ~/.agents/skills/ix — Freebuff / Codebuff (global)
+#
+# Freebuff's skill loader searches ~/.claude/skills, ~/.agents/skills, and the
+# project's .claude/skills and .agents/skills, so a global install makes the
+# skill available in every project. Re-run after editing skills/ix.
+#
+# Usage: bash scripts/install-skill.sh
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SRC="$ROOT/skills/ix"
+[ -f "$SRC/SKILL.md" ] || { echo "error: $SRC/SKILL.md not found" >&2; exit 1; }
+
+FORCE=0
+[ "${1:-}" = "--force" ] && FORCE=1
+
+installed=0
+for dest in "$HOME/.claude/skills/ix" "$HOME/.agents/skills/ix"; do
+ mkdir -p "$(dirname "$dest")"
+ if [ -e "$dest" ]; then
+ # Refuse to delete something that is not a previous install of this skill.
+ # `ix` is a short name, and the unconditional `rm -rf` this replaces would
+ # silently destroy a hand-written skill that happened to share it — with no
+ # prompt, no backup, and nothing in the output to say it had happened.
+ if [ "$FORCE" != "1" ] && ! grep -qs '^name: ix$' "$dest/SKILL.md"; then
+ echo "error: $dest exists and is not an Ix skill install." >&2
+ echo " Move it aside, or re-run with --force to overwrite it." >&2
+ exit 1
+ fi
+ rm -rf "$dest"
+ fi
+ cp -R "$SRC" "$dest"
+ echo "Installed: $dest"
+ installed=1
+done
+
+if [ "$installed" = "1" ]; then
+ echo
+ echo "Ix skill installed for Claude Code and Freebuff."
+ echo "Start a new session so the agent picks it up, then ask it to use Ix:"
+ echo " \"Set up Ix and map this repo\""
+fi
diff --git a/skills/ix/SKILL.md b/skills/ix/SKILL.md
new file mode 100644
index 00000000..f74e7783
--- /dev/null
+++ b/skills/ix/SKILL.md
@@ -0,0 +1,82 @@
+---
+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."
+license: Apache-2.0
+metadata:
+ version: 1.0.0
+ source: https://github.com/ix-infrastructure/Ix
+---
+
+# Ix — Persistent Codebase Map
+
+## Overview
+
+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:
+
+```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
+```
+
+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:
+
+```bash
+ix map --silent
+```
+
+## Core Workflow
+
+Map → Explain → Trace → Impact
+
+| Step | Command | Example |
+|---|---|---|
+| Build/refresh the graph | `ix map` | `ix map .` |
+| Understand a component | `ix explain` | `ix explain IngestionService` |
+| 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.
+5. If the backend is unreachable or a command fails, load references/troubleshooting.md.
+
+## 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.
+
+## 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/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.
diff --git a/skills/ix/references/commands.md b/skills/ix/references/commands.md
new file mode 100644
index 00000000..0db632b8
--- /dev/null
+++ b/skills/ix/references/commands.md
@@ -0,0 +1,135 @@
+# Ix Command Reference
+
+Use bounded, composable CLI commands — never broad queries. Run every command
+with the `ix` prefix from the repo root of the mapped workspace.
+
+## 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` |
+| Scoped entity listing | `ix inventory` | `ix inventory --kind function --path auth.py --format llm` |
+
+## Finding & Understanding Code
+
+| Goal | Command | Example |
+|---|---|---|
+| 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` |
+| Fast text search | `ix text` | `ix text "verify_token" --language python --limit 20` |
+| Find symbol (graph+text) | `ix locate` | `ix locate AuthProvider --kind class` |
+
+## Navigating Relationships
+
+| Goal | Command | Example |
+|---|---|---|
+| What calls a function | `ix callers` | `ix callers verify_token --format json` |
+| 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` |
+| What imports an entity | `ix imported-by` | `ix imported-by AuthProvider` |
+| Dependency impact | `ix depends` | `ix depends verify_token --depth 2` |
+
+## History, Diffs & Contradictions
+
+| 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` |
+
+## 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` |
+
+## Ingestion & Health
+
+| Goal | Command | Example |
+|---|---|---|
+| Update graph + map | `ix map --silent` | `ix map --silent` |
+| Ingest GitHub data | `ix ingest` | `ix ingest --github owner/repo --limit 50` |
+| 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` |
+
+## Decomposition Recipes
+
+**"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
+```
+
+**"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
+```
+
+**"What are the most important classes?"**
+```bash
+ix rank --by dependents --kind class --top 10 --format json
+```
+
+**"List all functions in a file"**
+```bash
+ix inventory --kind function --path auth.py --format llm
+```
+
+## Best Practices
+
+- Always use `--kind` with `ix search` to get bounded results.
+- Use `ix inventory` instead of `ix search ""` for listing entities by kind.
+- Use `ix diff --summary` for broad revision comparisons; `--full` only when
+ every individual change is needed.
+- Always use `--limit` to cap result sets.
+- Use `--path` or `--language` to restrict text searches.
+- Reuse exact entity IDs from previous JSON results when chaining commands.
+- Decompose large questions into multiple targeted calls.
+
+## Gotchas (surprises that already bit us)
+
+- **`ix reset` is GLOBAL, not workspace-scoped.** `ix reset` → `POST
+ /v1/reset`, and `ix reset --code` → `POST /v1/reset/code`; neither sends a
+ workspace_id, so both wipe EVERY workspace's graph in the shared backend —
+ the cwd only decides which mtime cache gets cleared. Running
+ `ix reset -y --code` in one repo also destroys the graphs of every other
+ mapped workspace (e.g. packwise) and empties the `--all` combined view;
+ re-run `ix map` per workspace to rebuild. A workspace-scoped endpoint
+ (`/v1/reset/workspace`, via `deleteWorkspace`) exists server-side, but the
+ CLI does not expose it.
+
+- **The OSS↔Pro command boundary is derived at runtime, not declared.**
+ `main.ts` snapshots `ossCmdNames` immediately after `registerOssCommands()`;
+ the Pro probe (`tryLoadProCommands`) then diffs whatever commands exist
+ against that set to decide which count as "Pro". Consequences:
+ - Adding a `register*Command` call in `oss.ts` silently reclassifies that
+ command as OSS — it vanishes from the Pro help diff.
+ - Removing one from `oss.ts` makes Pro own it, or — without the license — a
+ Pro stub replaces it (stubs skip any name already registered, so an OSS
+ command left in place blocks its stub).
+ - `registerProCommands` is async (each Pro command is dynamically imported)
+ and MUST be awaited; skipping the await makes every `ix <pro-cmd>` fail
+ with "unknown command".
+ - Real example: `registerPatchesCommand` is defined but never called in
+ `oss.ts`, so `ix patches` errors as an unknown command today; wiring it in
+ would flip it to OSS.
+
+## Do NOT Use
+
+- `ix query` — deprecated, produces oversized low-signal responses.
+- NLP-style free-text QA in a single command — decompose into targeted calls.
diff --git a/skills/ix/references/output-formats.md b/skills/ix/references/output-formats.md
new file mode 100644
index 00000000..bfacbc4a
--- /dev/null
+++ b/skills/ix/references/output-formats.md
@@ -0,0 +1,50 @@
+# Output Formats & Pro Features
+
+## Output formats
+
+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.
+- **`--format json`** — use when chaining results between commands or pulling a
+ specific field out of a response.
+- **`--format text`** — human-oriented tables and trees.
+
+### 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.
+
+### Commands with no `--format` at all
+
+`config`, `init`, `reset`, `upgrade`, `view`, `watch`. (`ingest` does accept
+`--format`, despite being an action command.)
+
+## Pro features
+
+Commands marked **[Pro]** require Ix Pro (server-side). The **Planning** and
+**Workflows** sections of the CLI are entirely Pro-only — including `plan`,
+`plans`, `task`, `tasks`, and `workflow`.
+
+If any Pro command prints `The '<name>' command requires Ix Pro.`, this install
+does not have them — skip that step, do not retry it, and do not mention it
+again for the rest of the session. Nothing outside those marks is Pro-gated.
+
+Pro-only surface: `plan`, `plans`, `task`, `tasks`, `workflow`, `decide`,
+`decisions`, `goal`, `truth`, `bug`, `bugs`, `briefing`, `patches`.
+
+### Semantic boundaries (Pro record types)
+
+- **decision** — a choice between alternatives, with rationale. Use `ix decide`.
+- **bug** — something broken, missing, or incorrect. Use `ix bug create`.
+- **task/plan** — intended work and sequencing. Use `ix plan` / `ix plan task`.
+
+## Confidence scores
+
+Ix returns confidence scores with results. When data has low confidence:
+
+- Mention the uncertainty to the user.
+- Suggest re-running `ix map` to refresh the graph.
+- Never present low-confidence data as established fact.
diff --git a/skills/ix/references/troubleshooting.md b/skills/ix/references/troubleshooting.md
new file mode 100644
index 00000000..fc06dbff
--- /dev/null
+++ b/skills/ix/references/troubleshooting.md
@@ -0,0 +1,53 @@
+# Troubleshooting & Prerequisites
+
+## Prerequisites
+
+- **Node.js >= 22** — required by the `ix` CLI.
+- **git** — used for workspace detection.
+- **Docker + Docker Compose** — runs the local backend (ArangoDB on
+ 127.0.0.1:8529 and the Ix Memory Layer on 127.0.0.1:8090). Docker Desktop
+ must be running on macOS/Windows.
+- **ripgrep** — powers `ix text`; optional but recommended (non-fatal if
+ missing).
+
+The bootstrap script (`scripts/bootstrap.sh` / `bootstrap.ps1`) checks and
+installs these, then installs the `ix` CLI if missing.
+
+## Backend not reachable
+
+Most first-run problems are the backend not being up yet. Diagnose in order:
+
+```bash
+ix status # is the backend reachable?
+ix docker start # start the backend (ArangoDB + memory layer)
+ix doctor # check system health — server, database, graph integrity
+```
+
+If a command reports `Ix backend not reachable`, run `ix docker start` and try
+again.
+
+## Common failure modes
+
+| Symptom | Fix |
+|---|---|
+| `Ix backend not reachable` | `ix docker start`, wait, then `ix doctor` |
+| Docker daemon not running | Start Docker Desktop / the Docker service, then re-run bootstrap |
+| `ix: command not found` | Re-run bootstrap (installs the CLI), or restart the shell so PATH picks up the wrapper |
+| `The '<name>' command requires Ix Pro.` | Not installed — skip the step, do not retry or mention it again this session |
+| `ix text` errors | Install ripgrep (brew/apt/dnf/choco) |
+| `Compass UI not found` on `ix view` | Run `ix upgrade` to fetch Compass. Re-running the installer wipes the Compass assets, so bootstrap auto-restores them with `ix upgrade`; skip with `IX_SKIP_COMPASS=1` |
+| Compass shows "Compass not connected to a codebase" | The scoped workspace has no graph — run `ix map .` from the repo root, then reload the tab |
+| Slow or stale results | Re-run `ix map --silent` to refresh the graph |
+
+## Environment flags
+
+- `IX_DEBUG=1` — full stack traces on any error.
+- `IX_SKIP_INSTALL=1` — skip the CLI install step in bootstrap.
+- `IX_SKIP_BACKEND=1` — skip starting/waiting for the backend in bootstrap.
+- `IX_SKIP_MAP=1` — skip `ix map` in bootstrap.
+
+## Re-mapping
+
+The graph persists between sessions but goes stale as code changes. Re-run
+`ix map --silent` from the repo root after every meaningful code change so
+answers stay current.
diff --git a/skills/ix/scripts/bootstrap.ps1 b/skills/ix/scripts/bootstrap.ps1
new file mode 100644
index 00000000..dc97a02f
--- /dev/null
+++ b/skills/ix/scripts/bootstrap.ps1
@@ -0,0 +1,114 @@
+# Ix skill bootstrap (Windows PowerShell) - install the ix CLI, start the local
+# backend, and map a repo.
+#
+# Usage:
+# powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 [repo-root] [-NoMap] [-NoBackend]
+#
+# Requires: Node.js >= 22, git, Docker Desktop (running), ripgrep (for `ix text`, optional).
+#
+# NOTE: keep this file pure ASCII. Windows PowerShell 5.1 reads .ps1 files
+# without a BOM as ANSI, so non-ASCII bytes (e.g. an em dash) get misparsed as
+# smart quotes and break the script.
+
+param(
+ [string]$Repo = "",
+ [switch]$NoMap,
+ [switch]$NoBackend
+)
+
+$ErrorActionPreference = "Stop"
+function Info { Write-Host "[ix-skill] $args" -ForegroundColor Cyan }
+function Warn { Write-Host "[ix-skill] $args" -ForegroundColor Yellow }
+function Fail { Write-Host "[ix-skill] $args" -ForegroundColor Red; exit 1 }
+
+if (-not $Repo) { $Repo = (Get-Location).Path }
+Info "Ix skill bootstrap - repo: $Repo"
+
+# --- Prerequisites ------------------------------------------------------------
+$nodeVer = ""
+try { $nodeVer = (node --version).TrimStart("v") } catch {}
+if ($nodeVer) {
+ if ([version]$nodeVer -ge [version]"22.0.0") { Info "Node $nodeVer OK." }
+ else { Warn "Node $nodeVer detected; Ix requires Node >= 22 (https://nodejs.org)." }
+} else {
+ Warn "Node.js not found; Ix requires Node >= 22 (https://nodejs.org)."
+}
+
+try { git --version | Out-Null; Info "git OK." } catch { Warn "git not found; Ix uses it for workspace detection." }
+try { rg --version | Out-Null; Info "ripgrep OK (powers 'ix text')." } catch { Warn "ripgrep not found - 'ix text' will not work. Install: choco install ripgrep" }
+
+$dockerUp = $false
+try {
+ docker info *> $null
+ if ($LASTEXITCODE -eq 0) { $dockerUp = $true; Info "Docker daemon is running." }
+} catch {}
+if (-not $dockerUp) {
+ Warn "Docker daemon is NOT running. Start Docker Desktop first, then re-run this script."
+ $NoBackend = $true
+}
+
+# --- Resolve the ix CLI ---------------------------------------------------------
+# The installer registers ~/.ix\bin in the user PATH, but long-lived shells and
+# agents spawned before the install may not see it. Resolve it before deciding
+# whether to install.
+$ixBin = Join-Path $env:USERPROFILE ".ix\bin"
+if (-not (Get-Command ix -ErrorAction SilentlyContinue)) {
+ if (Test-Path (Join-Path $ixBin "ix.cmd")) { $env:Path = "$ixBin;$env:Path"; Info "Found ix at ~/.ix\bin - added to PATH for this session." }
+}
+
+# --- Install the ix CLI (only if still missing) ---------------------------------
+if (Get-Command ix -ErrorAction SilentlyContinue) {
+ Info "ix CLI already installed."
+} elseif ($env:IX_SKIP_INSTALL -eq "1") {
+ Warn "IX_SKIP_INSTALL=1 - skipping ix CLI install. 'ix' is not on PATH."
+} else {
+ Info "Installing the ix CLI (official installer)..."
+ Invoke-RestMethod https://ix-infra.com/install.ps1 | Invoke-Expression
+ if (-not (Get-Command ix -ErrorAction SilentlyContinue)) {
+ $ixBin2 = Join-Path $env:USERPROFILE ".ix\bin"
+ if (Test-Path (Join-Path $ixBin2 "ix.cmd")) { $env:Path = "$ixBin2;$env:Path" }
+ }
+ if (-not (Get-Command ix -ErrorAction SilentlyContinue)) {
+ Fail "ix CLI install finished but 'ix' is still not on PATH. Restart your shell, then re-run this script."
+ }
+ Info "ix CLI installed."
+}
+if (-not (Get-Command ix -ErrorAction SilentlyContinue)) {
+ Fail "The ix CLI is not on PATH. Run the official installer, restart your shell, then re-run this bootstrap."
+}
+
+# --- Compass (visualizer UI) ----------------------------------------------------
+# The installer re-extracts the CLI tarball over the ix home and wipes the
+# Compass assets, which ship only via `ix upgrade`. Ensure they exist so
+# `ix view` never silently breaks after an installer re-run.
+if ($env:IX_SKIP_COMPASS -ne "1") {
+ $ixHome = Join-Path $env:USERPROFILE ".ix"
+ if ($env:IX_HOME) { $ixHome = $env:IX_HOME }
+ $compassIndex = Join-Path $ixHome "cli\compass\index.html"
+ if (Test-Path $compassIndex) {
+ Info "Compass UI present."
+ } else {
+ Warn "Compass UI missing at $ixHome\cli\compass (a re-install likely wiped it) - running 'ix upgrade' to restore it."
+ try { ix upgrade } catch { Warn "'ix upgrade' failed - 'ix view' will be unavailable until it is re-run." }
+ }
+}
+
+# --- Backend -------------------------------------------------------------------
+if (-not $NoBackend) {
+ Info "Starting the Ix backend (ArangoDB + memory layer)..."
+ try { ix docker start } catch { Warn "`ix docker start` reported a problem - run `ix doctor` and `ix status`." }
+ for ($i = 0; $i -lt 15; $i++) {
+ if (ix status *> $null) { break }
+ Start-Sleep -Seconds 2
+ }
+ try { ix status } catch { Warn "Backend still not reachable. Run: ix docker start; ix doctor" }
+}
+
+# --- Map the repo ---------------------------------------------------------------
+if (-not $NoMap) {
+ Info "Mapping $Repo - this builds the persistent graph (can take a while on large repos)..."
+ Push-Location $Repo
+ try { ix map . } finally { Pop-Location }
+}
+
+Info "Done. Try: ix explain <symbol>, ix trace <flow>, ix impact <symbol> --format llm"
diff --git a/skills/ix/scripts/bootstrap.sh b/skills/ix/scripts/bootstrap.sh
new file mode 100644
index 00000000..c853daa7
--- /dev/null
+++ b/skills/ix/scripts/bootstrap.sh
@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+#
+# Ix skill bootstrap — install the ix CLI, start the local backend, and map a repo.
+#
+# Usage:
+# bash scripts/bootstrap.sh [repo-root] [--no-map]
+#
+# Flags:
+# --no-map setup only (CLI + backend); do not run `ix map`
+# --no-backend do not start/wait for the Docker backend (CLI install only)
+#
+# Env overrides:
+# IX_SKIP_INSTALL=1 skip the ix CLI install step
+# IX_SKIP_BACKEND=1 same as --no-backend
+# IX_SKIP_MAP=1 same as --no-map
+#
+# Requires: Node.js >= 22, git, Docker (backend), ripgrep (for `ix text`, optional).
+# Works on macOS, Linux, and Windows under Git Bash / MSYS2 / WSL.
+
+set -euo pipefail
+
+REPO="${1:-$PWD}"
+if [ "${REPO}" = "--no-map" ] || [ "${REPO}" = "--no-backend" ]; then
+ REPO="$PWD"
+fi
+DO_MAP=1
+DO_BACKEND=1
+for arg in "$@"; do
+ case "$arg" in
+ --no-map) DO_MAP=0 ;;
+ --no-backend) DO_BACKEND=0 ;;
+ --*) ;;
+ esac
+done
+[ "${IX_SKIP_MAP:-0}" = "1" ] && DO_MAP=0
+[ "${IX_SKIP_BACKEND:-0}" = "1" ] && DO_BACKEND=0
+
+info() { printf '\033[1;36m[ix-skill]\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m[ix-skill]\033[0m %s\n' "$*"; }
+fail() { printf '\033[1;31m[ix-skill]\033[0m %s\n' "$*" >&2; exit 1; }
+
+# Detect Windows (Git Bash / MSYS2 / Cygwin).
+is_windows() { [ -n "${MSYSTEM:-}" ] || [ -n "${WSL_DISTRO_NAME:-}" ] || case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) return 0 ;; *) return 1 ;; esac; }
+
+version_ge() { # version_ge <got> <want>
+ # `sort -C` succeeds when its input is already in order, so feeding it
+ # want-then-got asks "is want <= got" — which is the question. The `-r` this
+ # used to carry asked the reverse and inverted the whole check: Node 22.22.2
+ # against a floor of 22 warned, and Node 18 passed silently.
+ printf '%s\n%s\n' "$2" "$1" | sort -V -C 2>/dev/null
+}
+
+command_exists() { command -v "$1" >/dev/null 2>&1; }
+
+info "Ix skill bootstrap — repo: $REPO"
+
+# --- Prerequisites -----------------------------------------------------------
+node_ok=0
+if command_exists node; then
+ node_ver="$(node --version | tr -d 'v')"
+ if version_ge "$node_ver" "22"; then node_ok=1; else warn "Node $node_ver detected; Ix requires Node >= 22."; fi
+else
+ warn "Node.js not found; Ix requires Node >= 22 (https://nodejs.org)."
+fi
+
+command_exists git || warn "git not found; Ix uses it for workspace detection."
+
+if command_exists rg; then
+ info "ripgrep found (powers 'ix text')."
+else
+ warn "ripgrep not found — 'ix text' will not work. Install it (macOS: brew install ripgrep; Linux: apt/dnf install ripgrep; Windows: choco install ripgrep)."
+fi
+
+if command_exists docker; then
+ if docker info >/dev/null 2>&1; then
+ info "Docker daemon is running."
+ else
+ warn "Docker is installed but the daemon is NOT running. Start Docker Desktop / the Docker service first, then re-run this script."
+ [ "$DO_BACKEND" = "1" ] && DO_BACKEND=0 && warn "Skipping backend start for now (daemon not up)."
+ fi
+else
+ warn "Docker not found — the Ix backend needs Docker. Install Docker Desktop / Docker Engine, then re-run this script."
+ DO_BACKEND=0
+fi
+
+# --- Resolve the ix CLI -------------------------------------------------------
+# The Windows installer ships ix.cmd and registers ~/.ix/bin in the user PATH,
+# but long-lived shells and agents spawned before the install may not see it.
+# Resolve the standard install location before deciding whether to install.
+if ! command_exists ix && [ -x "$HOME/.ix/bin/ix" ]; then
+ export PATH="$HOME/.ix/bin:$PATH"
+ info "Found ix at $HOME/.ix/bin — added to PATH for this session."
+fi
+
+# --- Install the ix CLI (only if still missing) --------------------------------
+if command_exists ix; then
+ info "ix CLI already installed: $(ix --version 2>/dev/null || echo present)."
+elif [ "${IX_SKIP_INSTALL:-0}" = "1" ]; then
+ warn "IX_SKIP_INSTALL=1 — skipping ix CLI install. 'ix' is not on PATH."
+else
+ info "Installing the ix CLI (official installer)…"
+ if is_windows; then
+ if command_exists powershell; then
+ powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://ix-infra.com/install.ps1 | iex"
+ else
+ fail "Windows detected but powershell not found. Run in PowerShell: irm https://ix-infra.com/install.ps1 | iex"
+ fi
+ else
+ curl -fsSL https://ix-infra.com/install.sh | sh
+ fi
+ # A fresh install only updates the user PATH, which new processes pick up but
+ # the current shell does not. Resolve the standard location explicitly.
+ if ! command_exists ix && [ -x "$HOME/.ix/bin/ix" ]; then
+ export PATH="$HOME/.ix/bin:$PATH"
+ fi
+ command_exists ix || fail "ix CLI install finished but 'ix' is still not on PATH. Restart your shell, or check ~/.ix/cli and PATH, then re-run this script."
+ info "ix CLI installed."
+fi
+command_exists ix || fail "The ix CLI is not on PATH. Run the official installer, restart your shell, then re-run this bootstrap."
+
+# --- Compass (visualizer UI) --------------------------------------------------
+# The official installer re-extracts the CLI tarball over the ix home and wipes
+# the Compass assets, which ship only via `ix upgrade`. Ensure they exist so
+# `ix view` never silently breaks after an installer re-run.
+ensure_compass() {
+ local ix_home="${IX_HOME:-$HOME/.ix}"
+ if [ -f "$ix_home/cli/compass/index.html" ]; then
+ info "Compass UI present."
+ return 0
+ fi
+ warn "Compass UI missing at $ix_home/cli/compass (a re-install likely wiped it) — running 'ix upgrade' to restore it."
+ ix upgrade || warn "'ix upgrade' failed — 'ix view' will be unavailable until it is re-run."
+}
+if [ "${IX_SKIP_COMPASS:-0}" != "1" ]; then
+ ensure_compass
+fi
+
+# --- Backend ------------------------------------------------------------------
+if [ "$DO_BACKEND" = "1" ]; then
+ info "Starting the Ix backend (ArangoDB + memory layer)…"
+ ix docker start || warn "`ix docker start` reported a problem — run `ix doctor` and `ix status` for details."
+ for _ in $(seq 1 15); do
+ if ix status >/dev/null 2>&1; then break; fi
+ sleep 2
+ done
+ ix status || warn "Backend still not reachable. Run: ix docker start && ix doctor"
+fi
+
+# --- Map the repo -------------------------------------------------------------
+if [ "$DO_MAP" = "1" ]; then
+ info "Mapping $REPO — this builds the persistent graph (can take a while on large repos)…"
+ ( cd "$REPO" && ix map . )
+fi
+
+info "Done. Try: ix explain <symbol>, ix trace <flow>, ix impact <symbol> --format llm"