# 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.
- **`ix patches` is OSS, not Pro** (#371). It is implemented here and registered
  in `oss.ts`. `@ix/pro` also registers a `patches`; commander throws on the
  duplicate and Pro's `tryRegister` swallows the throw, so the OSS one — which
  registers first — wins on a Kartr install too. Do not re-add it to
  `PRO_COMMANDS`: a stub for a command that exists in OSS shadows the real
  implementation, and the failure is silent rather than a crash.
- **`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

This project uses Ix Memory — persistent, time-aware context for LLM assistants.

## Interface

Use the `ix` CLI exclusively.

**Output format.** Query commands accept `--format text|json|llm`:

- **`--format llm` — prefer this when you are reading the result yourself.** It is
  token-minimal and newline-delimited, and noticeably smaller than `json` on tree-
  and table-shaped output.
- `--format json` — use when chaining results between commands, or when you need
  to pull a specific field out of the response.

Every command that accepts `--format` implements `llm`, with two exceptions that
fall back to text without an error: `diff --content` (verbatim hunks) and
`ingest`. The deprecated `query` accepts only `text|json` — passing `--format
llm` to it silently renders text.

`--format llm` is **not** accepted at all by `config`, `init`, `reset`,
`upgrade`, `view`, `watch` and `docker`, which take no `--format`; passing it is
an `unknown option` error, not a fallback. Do not pass it blind. (`ingest` does
accept `--format`, despite being an action command.)

**Pro features.** Some commands below are marked **[Pro]**, as are the whole
**Planning** and **Workflows** sections — every command in those two tables is
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 and those two sections is
Pro-gated.

## MANDATORY RULES
1. BEFORE answering codebase questions → use targeted `ix` CLI commands (see routing below). Do NOT answer from training data alone.
2. **[Pro]** AFTER every design or architecture decision → run `ix decide <title> --rationale <text>`. Skip permanently if it reports it requires Ix Pro.
3. When you notice contradictory information → run `ix conflicts` and present results to the user.
4. NEVER guess about codebase facts — if Ix has structured data, use it.
5. IMMEDIATELY after modifying code → run `ix map --silent` to re-ingest and update the graph.
6. **[Pro]** When the user states a goal → run `ix truth add "<statement>"`. Skip permanently if it reports it requires Ix Pro.

## Ix CLI Command Routing

Use bounded, composable CLI commands — never broad queries.

### High-Level Workflow Commands (Preferred)

Start here. 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` |
| **[Pro]** Plan work | `ix plan` | `ix plan task "title" --plan <id> --resolves <bugId> --workflow-staged '{"discover":["cmd"]}' --format json` |
| **[Pro]** Track decisions | `ix decide` | `ix decide "Use X" --rationale "..." --affects Entity --responds-to <bugId>` |
| **[Pro]** Create goals | `ix goal` | `ix goal create "Support GitHub" --format json` |
| **[Pro]** Session resume | `ix briefing` | `ix briefing --format json` |
| **[Pro]** Track bugs | `ix bug` | `ix bug create "title" --affects Entity` |

### Low-Level Primitives

Underlying structural commands — useful for debugging or fine-grained inspection.

#### 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 & Decisions

Only the first four work without Pro.

| 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` |
| List recent patches | `ix patches` | `ix patches --limit 20 --format llm` |
| **[Pro]** Design decisions | `ix decisions` | `ix decisions --topic ingestion --limit 10` |
| **[Pro]** Record a decision | `ix decide` | `ix decide "Use CONTAINS" --rationale "Normalize edges" --responds-to <bugId>` |
| **[Pro]** Record a goal | `ix truth add` | `ix truth add "Support 100k file repos"` |
| **[Pro]** List goals | `ix truth list` | `ix truth list --format json` |
| **[Pro]** Bug tracking | `ix bug create` | `ix bug create "title" --severity high --affects Entity` |
| **[Pro]** Update bug status | `ix bug update` | `ix bug update <id> --status resolved` |
| **[Pro]** Bug listing | `ix bugs` | `ix bugs --status open --format json` |
| **[Pro]** Bug details | `ix bug show` | `ix bug show <id> --format json` |

### Planning (Pro)
| Goal | Command | Example |
|---|---|---|
| Create a goal | `ix goal create` | `ix goal create "Support GitHub" --format json` |
| List goals | `ix goal list` | `ix goal list --status active --format json` |
| Create a plan | `ix plan create` | `ix plan create "Fix auth" --goal <id> --responds-to <bugId> --format json` |
| Add a task | `ix plan task` | `ix plan task "Step 1" --plan <id> --depends-on <taskId> --resolves <bugId> --workflow-staged '{"discover":["ix overview X"],"implement":["ix map"],"validate":["ix smells"]}' --format json` |
| Plan status | `ix plan status` | `ix plan status <id> --format json` |
| Next actionable task | `ix plan next` | `ix plan next <id> --with-workflow --format json` |
| Run next task workflow | `ix plan next` | `ix plan next <id> --run-workflow --stage discover --format json` |
| List all plans | `ix plans` | `ix plans --format json` |
| List tasks | `ix tasks` | `ix tasks --status pending --plan <id> --format json` |
| Task details | `ix task show` | `ix task show <id> --with-workflow --format json` |
| Update task | `ix task update` | `ix task update <id> --status done --format json` |
| Run task workflow stage | `ix task update` | `ix task update <id> --run-workflow discover --format json` |

### Workflows (Pro)
Workflows are staged command sequences (discover → implement → validate) attached to tasks, plans, or decisions. All commands must start with `ix ` — no shell operators.

| Goal | Command | Example |
|---|---|---|
| Attach workflow | `ix workflow attach` | `ix workflow attach task <id> --file workflow.json` |
| Show workflow | `ix workflow show` | `ix workflow show task <id> --format json` |
| Validate workflow | `ix workflow validate` | `ix workflow validate task <id>` |
| Run workflow | `ix workflow run` | `ix workflow run task <id> --stage implement --format json` |

**Workflow JSON format:**
```json
{
  "discover":   ["ix overview AuthService", "ix impact AuthService"],
  "implement":  ["ix map --silent"],
  "validate":   ["ix smells --format json", "ix subsystems --format json"]
}
```

### 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` |
| Graph statistics | `ix stats` | `ix stats --format json` |

### Decomposition Examples

**"How does ingestion work?"**
```bash
ix overview IngestionService --format json    # start here
# If you need more detail:
ix contains IngestionService --format json
ix callees parseFile --format json
```

**"What depends on verify_token?"**
```bash
ix impact verify_token --format json          # one-shot answer
# or manually:
ix callers verify_token --format json
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"**
```bash
ix inventory --kind function --format json
```

### 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 (server-side, fast)
- Use `--full` only when you need every individual change
- Always use `--limit` to cap result sets
- Use `--format llm` when you are reading the output; `--format json` only when chaining results between commands or extracting a specific field
- Use `--path` or `--language` to restrict text searches
- Use exact entity IDs from previous JSON results
- Decompose large questions into multiple targeted calls

## Semantic Boundaries **[Pro]**

These record types are Pro-only. Use the right one for the purpose:

- **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`.

## Do NOT Use
- `ix query` — deprecated, produces oversized low-signal responses
- NLP-style QA in a single command

## 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
<!-- IX-MEMORY END -->