Skip to content

armgit / Ix

Public Imported from GitHub
0

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

docs(claude): mark Pro-only commands and steer agents to --format llm (#342)

KageBinarycff1288d1c3c
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 RULES
1. 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.ts
new file mode 100644
index 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.ts
index 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.`);