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
feat(skill): ship the ix agent skill and the HTTP API reference (#368)
Alot1z2157158446a7
diff --git a/.gitignore b/.gitignoreindex 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/*.classdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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 Systemdiff --git a/README.md b/README.mdindex 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+```+## RequirementsThe 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.mdnew file mode 100644index 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.yamlnew file mode 100644index 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.shnew file mode 100644index 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\""+fidiff --git a/skills/ix/SKILL.md b/skills/ix/SKILL.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.ps1new file mode 100644index 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.shnew file mode 100644index 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"