Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
docs(claude): mark Pro-only commands and steer agents to --format llm (#342)
KageBinarycff1288d1c3c
diff --git a/CLAUDE.md b/CLAUDE.mdindex 45a32156..56051842 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -5,17 +5,39 @@ This project uses Ix Memory — persistent, time-aware context for LLM assistant## Interface-Use the `ix` CLI exclusively. All commands support `--format json` for machine-readable output.+Use the `ix` CLI exclusively.-Use JSON when chaining command results.+**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.++**Four commands advertise `llm` in their help but do not implement it**, and fall+back to human-oriented text without an error: `explain`, `read`, `status`, and the+deprecated `query`. Use `--format json` on those if you need to parse the result.+Everywhere else in the routing tables, `llm` behaves as described.++These commands take no `--format` at all: `config`, `init`, `reset`, `upgrade`,+`view`, `watch`. (`ingest` does accept it, 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 RULES1. BEFORE answering codebase questions → use targeted `ix` CLI commands (see routing below). Do NOT answer from training data alone.-2. AFTER every design or architecture decision → run `ix decide <title> --rationale <text>`.+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. When the user states a goal → run `ix truth add "<statement>"`.+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@@ -27,15 +49,15 @@ Start here. These aggregate multiple graph operations into single bounded respon| Goal | Command | Example ||---|---|---|-| Blast radius / impact | `ix impact` | `ix impact UserService --format json` |-| Hotspot discovery | `ix rank` | `ix rank --by dependents --kind class --top 10` |-| One-shot summary | `ix overview` | `ix overview IngestionService --format json` |-| Scoped entity listing | `ix inventory` | `ix inventory --kind function --path auth.py` |-| Plan work | `ix plan` | `ix plan task "title" --plan <id> --resolves <bugId> --workflow-staged '{"discover":["cmd"]}' --format json` |-| Track decisions | `ix decide` | `ix decide "Use X" --rationale "..." --affects Entity --responds-to <bugId>` |-| Create goals | `ix goal` | `ix goal create "Support GitHub" --format json` |-| Session resume | `ix briefing` | `ix briefing --format json` |-| Track bugs | `ix bug` | `ix bug create "title" --affects Entity` |+| 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@@ -62,20 +84,23 @@ Underlying structural commands — useful for debugging or fine-grained inspecti| Dependency impact | `ix depends` | `ix depends verify_token --depth 2` |### History & Decisions++Only the first three work without Pro.+| Goal | Command | Example ||---|---|---|-| Design decisions | `ix decisions` | `ix decisions --topic ingestion --limit 10` |-| Entity history | `ix history` | `ix history <entityId>` |-| Changes between revisions | `ix diff` | `ix diff 1 5 --summary --format json` |-| Detect contradictions | `ix conflicts` | `ix conflicts --format json` |-| Record a decision | `ix decide` | `ix decide "Use CONTAINS" --rationale "Normalize edges" --responds-to <bugId>` |-| Record a goal | `ix truth add` | `ix truth add "Support 100k file repos"` |-| List goals | `ix truth list` | `ix truth list --format json` |-| Bug tracking | `ix bug create` | `ix bug create "title" --severity high --affects Entity` |-| Update bug status | `ix bug update` | `ix bug update <id> --status resolved` |-| Bug listing | `ix bugs` | `ix bugs --status open --format json` |-| Bug details | `ix bug show` | `ix bug show <id> --format json` |-| List recent patches | `ix patches` | `ix patches --limit 20 --format json` |+| 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` |+| **[Pro]** List recent patches | `ix patches` | `ix patches --limit 20 --format json` |+| **[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 |@@ -162,14 +187,14 @@ ix inventory --kind function --format json- 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 json` when chaining results between commands+- 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+## Semantic Boundaries **[Pro]**-Use the right entity type for the right purpose:+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`.diff --git a/ix-cli/src/cli/__tests__/pro-stub-message.test.ts b/ix-cli/src/cli/__tests__/pro-stub-message.test.tsnew file mode 100644index 00000000..4b57dd74--- /dev/null+++ b/ix-cli/src/cli/__tests__/pro-stub-message.test.ts@@ -0,0 +1,78 @@+import { describe, expect, it } from "vitest";+import { Command } from "commander";++import { registerProStubs } from "../register/oss.js";++/**+ * CLAUDE.md tells agents to detect a Pro-gated install by the exact string+ * `The '<name>' command requires Ix Pro.` and then stop retrying. That contract+ * is only worth documenting if the message actually reaches the user for the+ * invocations people really type — which are never the bare command.+ */+function runStub(argv: string[]): { out: string; err: string; exitCode: number | string | undefined } {+ const program = new Command();+ program.name("ix").exitOverride();+ registerProStubs(program);++ const out: string[] = [];+ const err: string[] = [];+ const origLog = console.log;+ const origErr = console.error;+ const origExit = process.exitCode;+ console.log = (...a: unknown[]) => void out.push(a.join(" "));+ console.error = (...a: unknown[]) => void err.push(a.join(" "));+ process.exitCode = undefined;++ let code: number | string | undefined;+ try {+ program.parse(["node", "ix", ...argv]);+ // commander's error path (exitOverride) throws, so the message lands in the+ // catch below rather than here.+ } catch (e) {+ err.push(String((e as Error).message));+ } finally {+ code = process.exitCode;+ console.log = origLog;+ console.error = origErr;+ process.exitCode = origExit;+ }+ return { out: out.join("\n"), err: err.join("\n"), exitCode: code };+}++describe("Pro stubs", () => {+ it("reports Pro for the bare command", () => {+ const { err, exitCode } = runStub(["bug"]);+ expect(err).toContain("The 'bug' command requires Ix Pro.");+ expect(exitCode).toBe(1);+ });++ // The regression: commander rejects excess operands before the action runs,+ // so every documented Pro example used to die with "too many arguments"+ // instead of the sentinel the docs tell agents to look for.+ it.each([+ ["bug", ["bug", "create", "a title", "--affects", "Entity"]],+ ["bug", ["bug", "update", "abc123", "--status", "resolved"]],+ ["bug", ["bug", "show", "abc123", "--format", "json"]],+ ["bugs", ["bugs", "--status", "open", "--format", "json"]],+ ["truth", ["truth", "add", "Support 100k file repos"]],+ ["truth", ["truth", "list", "--format", "json"]],+ ["goal", ["goal", "create", "Support GitHub", "--format", "json"]],+ ["decide", ["decide", "Use X", "--rationale", "because", "--affects", "Entity"]],+ ["briefing", ["briefing", "--format", "json"]],+ ["decisions", ["decisions", "--topic", "ingestion", "--limit", "10"]],+ ["patches", ["patches", "--limit", "20", "--format", "json"]],+ ["plan", ["plan", "task", "title", "--plan", "p1", "--resolves", "b1"]],+ ["task", ["task", "show", "t1"]],+ ["workflow", ["workflow", "attach", "w1"]],+ ])("reports Pro for %s with arguments", (name, argv) => {+ const { err, exitCode } = runStub(argv);+ expect(err).toContain(`The '${name}' command requires Ix Pro.`);+ expect(err).not.toContain("too many arguments");+ expect(exitCode).toBe(1);+ });++ it("emits the message verbatim as CLAUDE.md quotes it", () => {+ // Single quotes around the name, trailing period. Agents match on this.+ expect(runStub(["decide", "Use X"]).err).toContain("The 'decide' command requires Ix Pro.");+ });+});diff --git a/ix-cli/src/cli/register/oss.ts b/ix-cli/src/cli/register/oss.tsindex 65f510da..70b767e0 100644--- a/ix-cli/src/cli/register/oss.ts+++ b/ix-cli/src/cli/register/oss.ts@@ -112,7 +112,17 @@ export function registerProStubs(program: Command): void {const stub = program.command(name).description(desc)+ // Swallow whatever the caller passed. `allowUnknownOption` alone only+ // covers flags; commander still rejects excess *operands*, and it does so+ // before the action runs. So `ix bug` reached this message but+ // `ix bug create "title" --affects Entity` — the form the docs and every+ // agent actually use — died with "too many arguments for 'bug'" and never+ // said anything about Pro. The subcommand and its arguments are+ // deliberately ignored: the only thing worth saying here is that the+ // whole command needs Pro.+ .argument("[args...]").allowUnknownOption(true)+ .allowExcessArguments(true).action(() => {console.error(`The '${name}' command requires Ix Pro.`);console.error(`Install @ix/pro to enable premium features.`);