Skip to content

armgit / Ix

Public Imported from GitHub
0

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

feat(context): budget the bundle in tokens, not characters

KageBinary7bc83d2aa3f9
diff --git a/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts b/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts
index 97ab0685..503bac22 100644
--- a/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts
+++ b/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts
@@ -57,7 +57,7 @@ function bundle(opts: {
metadata: { query: "", seedEntities: [], hopsExpanded: 1, asOfRev: 1 },
} as never,
provenance: opts.provenance ?? {},
- budgets: { maxEntities: opts.maxEntities ?? 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: opts.maxEntities ?? 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
isStale: () => false,
});
}
@@ -131,7 +131,7 @@ describe("ix context evidence says where things are", () => {
metadata: { query: "", seedEntities: [], hopsExpanded: 1, asOfRev: 1 },
} as never,
provenance: {},
- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
isStale: () => false,
});
diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.ts
index 7a3f60e4..8fbf9c40 100644
--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts
+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts
@@ -208,7 +208,7 @@ function bundleWith(claims: ScoredClaim[], stale = false) {
provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },
asOfRev: undefined,
depth: undefined,
- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
});
}
@@ -405,7 +405,7 @@ describe("ix context investigation state", () => {
provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },
asOfRev: undefined,
depth: undefined,
- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
});
const diff = diffInvestigations(stored, fresh);
@@ -487,14 +487,14 @@ describe("ix context investigation state", () => {
// fresh bundle in front of it had been built with 50/100/25/12000 -- a
// budget neither side of the comparison had used together.
const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
- saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };
+ saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 };
saveInvestigation("widget-check", saved);
const stored = loadInvestigation("widget-check")!;
const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);
- expect(fresh.budgets).toEqual({ maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 });
+ expect(fresh.budgets).toEqual({ maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 });
const baselineDiff = diffInvestigations(stored, fresh);
- expect(baselineDiff.budgets.saved).toEqual({ maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 });
+ expect(baselineDiff.budgets.saved).toEqual({ maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 });
expect(baselineDiff.budgets.requested).toBeUndefined();
expect(baselineDiff.budgets.effective).toEqual(fresh.budgets);
expect(baselineDiff.budgets.requestedApplied).toBe(false);
@@ -545,7 +545,7 @@ describe("ix context investigation state", () => {
// future refactor flattens renderInvestigationDiff back to "entities/-
// +", the budget block disappears and the silent ignore comes back.
const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
- saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };
+ saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 };
saveInvestigation("widget-check", saved);
const stored = loadInvestigation("widget-check")!;
const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);
@@ -583,9 +583,9 @@ describe("ix context investigation state", () => {
// Records, not the prose block with the colons moved. `scope=requested`
// carries `applied=` so the precedence rule — saved budgets govern
// --diff — is a field an agent can test rather than a sentence to read.
- expect(llm.lines).toContain("budgets scope=saved entities=5 relationships=1 evidence=2 chars=12000");
+ expect(llm.lines).toContain("budgets scope=saved entities=5 relationships=1 evidence=2 tokens=1500 chars=12000");
expect(llm.lines).toContain("budgets scope=requested evidence=25 applied=false");
- expect(llm.lines).toContain("budgets scope=effective entities=50 relationships=100 evidence=25 chars=12000");
+ expect(llm.lines).toContain("budgets scope=effective entities=50 relationships=100 evidence=25 tokens=1500 chars=12000");
// And none of the prose survives into the record stream.
expect(llm.lines.some((l) => l.includes(":") && l.startsWith(" "))).toBe(false);
@@ -686,7 +686,7 @@ describe("ix context investigation state", () => {
provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },
asOfRev: undefined,
depth: undefined,
- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
});
const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "llm"));
diff --git a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts
index 9acfaa71..3b26540d 100644
--- a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts
+++ b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts
@@ -242,7 +242,7 @@ describe("mode-flag coverage does not drift from the command", () => {
*/
const CONTEXT_BUILD_FLAGS = [
"kind", "path", "pick", "depth", "asOfRev",
- "maxEntities", "maxRelationships", "maxEvidence", "maxChars",
+ "maxEntities", "maxRelationships", "maxEvidence", "maxTokens", "maxChars",
];
/** Meaningful to every mode, so in neither group. */
const CONTEXT_UNIVERSAL_FLAGS = ["format"];
diff --git a/ix-cli/src/cli/__tests__/context-pick-validation.test.ts b/ix-cli/src/cli/__tests__/context-pick-validation.test.ts
index 9741e1ec..96ea368f 100644
--- a/ix-cli/src/cli/__tests__/context-pick-validation.test.ts
+++ b/ix-cli/src/cli/__tests__/context-pick-validation.test.ts
@@ -117,7 +117,7 @@ describe("ix context --max-* validation", () => {
["--max-entities", "Maximum entities in the bundle", 50, 1, 500],
["--max-relationships", "Maximum relationships in the bundle", 100, 1, 1000],
["--max-evidence", "Maximum evidence items in the bundle", 25, 1, 200],
- ["--max-chars", "Maximum characters of evidence output", 12000, 1000, 1000000],
+ ["--max-tokens", "Maximum tokens of evidence output", 1500, 500, 200000],
] as const) {
// One assertion per flag, so a failure names which one lost its default
// rather than reporting that some string was missing from a wall of help.
@@ -125,6 +125,13 @@ describe("ix context --max-* validation", () => {
`${flag} <n> ${text} (default: ${fallback}, clamped to ${min}-${max})`,
);
}
+
+ // `--max-chars` is the exception, and says so instead of naming a default
+ // it no longer has: its absence produces whatever --max-tokens works out
+ // to, not 12000.
+ expect(flat, "help for --max-chars").toContain(
+ "--max-chars <n> Maximum characters of evidence output (overrides --max-tokens; clamped to 1000-1000000)",
+ );
});
});
diff --git a/ix-cli/src/cli/__tests__/context-token-budget.test.ts b/ix-cli/src/cli/__tests__/context-token-budget.test.ts
new file mode 100644
index 00000000..651dc1c1
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/context-token-budget.test.ts
@@ -0,0 +1,58 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { Command } from "commander";
+import { describe, expect, it } from "vitest";
+
+import {
+ BUNDLE_CHARS_PER_TOKEN,
+ clampBudgets,
+ detectContextModeConflict,
+ registerContextCommand,
+} from "../commands/context.js";
+
+describe("--max-tokens", () => {
+ it("is what bounds a default bundle, not 12,000 characters", () => {
+ const budgets = clampBudgets({});
+ expect(budgets.maxTokens).toBe(1500);
+ expect(budgets.maxChars).toBe(Math.round(1500 * BUNDLE_CHARS_PER_TOKEN));
+ // The old default was nearly four times this.
+ expect(budgets.maxChars).toBeLessThan(12_000);
+ });
+
+ it("moves the character budget with it", () => {
+ expect(clampBudgets({ maxTokens: 3000 }).maxChars).toBe(Math.round(3000 * BUNDLE_CHARS_PER_TOKEN));
+ expect(clampBudgets({ maxTokens: 500 }).maxChars).toBe(1070);
+ });
+
+ it("is clamped to its range before it is converted", () => {
+ expect(clampBudgets({ maxTokens: 1 }).maxTokens).toBe(500);
+ expect(clampBudgets({ maxTokens: 10_000_000 }).maxTokens).toBe(200_000);
+ // And the derived character budget still lands inside --max-chars' range.
+ expect(clampBudgets({ maxTokens: 10_000_000 }).maxChars).toBeLessThanOrEqual(1_000_000);
+ expect(clampBudgets({ maxTokens: 1 }).maxChars).toBeGreaterThanOrEqual(1000);
+ });
+
+ it("gives way to an explicit --max-chars", () => {
+ const budgets = clampBudgets({ maxChars: 40_000 });
+ expect(budgets.maxChars).toBe(40_000);
+ // The token field still reports what it would have been, so --diff can say
+ // which budget the caller had in force.
+ expect(budgets.maxTokens).toBe(1500);
+ });
+
+ it("is refused alongside --max-chars rather than silently losing to it", () => {
+ const message = detectContextModeConflict({ maxTokens: 2000, maxChars: 40_000 });
+ expect(message).toContain("--max-tokens and --max-chars cannot be combined");
+ expect(detectContextModeConflict({ maxTokens: 2000 })).toBeUndefined();
+ expect(detectContextModeConflict({ maxChars: 40_000 })).toBeUndefined();
+ });
+
+ it("is registered, and refuses a value that is not a positive integer", () => {
+ const program = new Command().name("ix").exitOverride();
+ registerContextCommand(program);
+ const context = program.commands.find((c) => c.name() === "context")!;
+ const option = context.options.find((o) => o.long === "--max-tokens");
+ expect(option).toBeDefined();
+ expect(() => option!.parseArg!("1e3", undefined)).toThrow(/positive integer/);
+ });
+});
diff --git a/ix-cli/src/cli/__tests__/context.test.ts b/ix-cli/src/cli/__tests__/context.test.ts
index e0c02487..442c8be0 100644
--- a/ix-cli/src/cli/__tests__/context.test.ts
+++ b/ix-cli/src/cli/__tests__/context.test.ts
@@ -103,7 +103,7 @@ function input() {
provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },
asOfRev: undefined,
depth: undefined,
- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
};
}
@@ -135,7 +135,7 @@ describe("ix context bundle", () => {
it("enforces budgets and reports explicit truncation", () => {
const bundle = buildBundle({
...input(),
- budgets: { maxEntities: 1, maxRelationships: 0, maxEvidence: 2, maxChars: 12000 },
+ budgets: { maxEntities: 1, maxRelationships: 0, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 },
});
expect(bundle.entities).toHaveLength(1);
@@ -172,7 +172,7 @@ describe("ix context bundle", () => {
...input(),
context: makeContext({ nodes, edges }),
// Room for the target plus a couple of entities, not all four.
- budgets: { maxEntities: 3, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: 3, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
});
const kept = new Set(bundle.entities.map((e) => e.id));
@@ -287,7 +287,7 @@ describe("ix context bundle", () => {
buildBundle({
...input(),
context: makeContext({ nodes }),
- budgets: { maxEntities: 5, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: 5, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
isStale: () => { probes += 1; return false; },
});
@@ -341,7 +341,7 @@ describe("ix context bundle", () => {
it("bounds evidence by the exact serialized representation, not an estimate", () => {
const claims = Array.from({ length: 60 }, (_, i) => makeClaim(`statement number ${i} with some padding text`, 0.5));
- const budgets = { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 500 };
+ const budgets = { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 500 };
const bundle = buildBundle({ ...input(), context: makeContext({ claims }), budgets });
diff --git a/ix-cli/src/cli/__tests__/mcp.test.ts b/ix-cli/src/cli/__tests__/mcp.test.ts
index b611b968..c3b75ceb 100644
--- a/ix-cli/src/cli/__tests__/mcp.test.ts
+++ b/ix-cli/src/cli/__tests__/mcp.test.ts
@@ -56,7 +56,7 @@ function contextBundle() {
provenance: { historyLength: 0, stale: false },
freshness: { stale: false, classification: "current" },
evidence: [],
- budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
truncation: { entitiesTruncated: 0, relationshipsTruncated: 0, evidenceTruncated: 0, charactersTruncated: 0 },
metadata: { rankingRule: "deterministic-tier" },
};
diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.ts
index 979f8726..ef284ee0 100644
--- a/ix-cli/src/cli/commands/context.ts
+++ b/ix-cli/src/cli/commands/context.ts
@@ -26,17 +26,18 @@ import { resolveFileOrReport } from "../resolve.js";
import { createStaleProbe, hasCompletedSourceGraphBaseline } from "../stale.js";
import { renderNote, renderSection, renderWarning, renderWarningErr, reportFailure } from "../ui.js";
-/** The four `--max-*` knobs that bound a bundle. */
+/** The `--max-*` knobs that bound a bundle. */
interface BudgetSnapshot {
maxEntities: number;
maxRelationships: number;
maxEvidence: number;
+ maxTokens: number;
maxChars: number;
}
/**
- * The four budgets, described once: flag key, output label, clamp range, and
- * the default applied when the flag is absent.
+ * The budgets, described once: flag key, output label, clamp range, and the
+ * default applied when the flag is absent.
*
* These four facts used to live in five hand-maintained places -- the option
* registration, the `clampInt` calls, the record fields, the prose formatter
@@ -52,6 +53,7 @@ const BUDGETS = [
{ key: "maxEntities", flag: "--max-entities", label: "entities", help: "Maximum entities in the bundle", min: 1, max: 500, fallback: 50 },
{ key: "maxRelationships", flag: "--max-relationships", label: "relationships", help: "Maximum relationships in the bundle", min: 1, max: 1000, fallback: 100 },
{ key: "maxEvidence", flag: "--max-evidence", label: "evidence", help: "Maximum evidence items in the bundle", min: 1, max: 200, fallback: 25 },
+ { key: "maxTokens", flag: "--max-tokens", label: "tokens", help: "Maximum tokens of evidence output", min: 500, max: 200_000, fallback: 1_500 },
{ key: "maxChars", flag: "--max-chars", label: "chars", help: "Maximum characters of evidence output", min: 1000, max: 1_000_000, fallback: 12_000 },
] as const satisfies ReadonlyArray<{
key: keyof BudgetSnapshot;
@@ -97,13 +99,45 @@ function budgetParser(key: keyof BudgetSnapshot): (value: string) => number {
return (value: string) => parseBudgetOption(value, example);
}
-/** Apply the table's range and default to whatever the caller supplied. */
-function clampBudgets(opts: Partial<BudgetSnapshot>): BudgetSnapshot {
+/**
+ * Characters per token in a real bundle.
+ *
+ * Measured across 41 recorded bundles whose prompts differed only by the
+ * bundle: 2.14, against the ~4 of ordinary English. A bundle is dense
+ * `key=value` and JSON with identifiers in it, and identifiers tokenize badly.
+ *
+ * Conservative on purpose, and it stays conservative as the bundle gets
+ * cleaner: pulling identifier-heavy rows out raises the real ratio, so an
+ * estimate pinned at 2.14 over-counts tokens and the bundle comes in under its
+ * budget rather than over it. Re-measure before lowering it, never raise it to
+ * make a bundle fit.
+ */
+export const BUNDLE_CHARS_PER_TOKEN = 2.14;
+
+/**
+ * Apply the table's range and default to whatever the caller supplied, and
+ * turn the token budget into the character budget that bounds the evidence.
+ *
+ * `--max-tokens` is the budget a caller actually has: the thing being spent is
+ * a context window, and 12,000 characters is a number nobody can convert in
+ * their head into what it costs them. `--max-chars` stays for the caller who
+ * needs exact bytes, and wins outright when passed — the two together are
+ * refused up front rather than silently ranked, because which one lost is not
+ * visible in the output.
+ */
+export function clampBudgets(opts: Partial<BudgetSnapshot>): BudgetSnapshot {
const out = {} as BudgetSnapshot;
for (const b of BUDGETS) {
const raw = opts[b.key];
out[b.key] = raw === undefined ? b.fallback : Math.min(b.max, Math.max(b.min, raw));
}
+ if (opts.maxChars === undefined) {
+ const chars = budgetField("maxChars");
+ out.maxChars = Math.min(
+ chars.max,
+ Math.max(chars.min, Math.round(out.maxTokens * BUNDLE_CHARS_PER_TOKEN)),
+ );
+ }
return out;
}
@@ -264,7 +298,17 @@ export function registerContextCommand(program: Command): void {
.option("--max-entities <n>", budgetHelp("maxEntities"), budgetParser("maxEntities"))
.option("--max-relationships <n>", budgetHelp("maxRelationships"), budgetParser("maxRelationships"))
.option("--max-evidence <n>", budgetHelp("maxEvidence"), budgetParser("maxEvidence"))
- .option("--max-chars <n>", budgetHelp("maxChars"), budgetParser("maxChars"))
+ .option("--max-tokens <n>", budgetHelp("maxTokens"), budgetParser("maxTokens"))
+ // Not `budgetHelp`: there is no independent default to name any more. The
+ // character budget is derived from `--max-tokens` unless this flag is
+ // passed, and printing "(default: 12000)" beside a flag whose absence
+ // produces 3,210 would be the kind of drift the BUDGETS table exists to
+ // stop.
+ .option(
+ "--max-chars <n>",
+ `${budgetField("maxChars").help} (overrides --max-tokens; clamped to ${budgetField("maxChars").min}-${budgetField("maxChars").max})`,
+ budgetParser("maxChars"),
+ )
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.option("--out <path>", "Write the JSON bundle to this file instead of stdout")
.option("--save <id>", "Persist the bundle as a resumable investigation state")
@@ -536,6 +580,13 @@ export function detectContextModeConflict(
return `${ignored.join(", ")} cannot be combined with --${mode}; ${why}, so ${ignored.length > 1 ? "those flags change" : "that flag changes"} nothing. Drop ${ignored.length > 1 ? "them" : "it"}, or run ix context <target> to build a bundle with ${ignored.length > 1 ? "them" : "it"}.`;
}
}
+ if (opts.maxTokens !== undefined && opts.maxChars !== undefined) {
+ // Refused rather than ranked. They bound the same thing — the evidence
+ // block — in two units, and whichever one lost does not appear anywhere in
+ // the output, so a caller who set both would have no way to tell which
+ // budget was applied. Same rule `ix diff` uses for --summary and --limit.
+ return "--max-tokens and --max-chars cannot be combined; both bound the evidence block, in different units. Use --max-tokens for a context-window budget, or --max-chars for exact bytes.";
+ }
if (opts.list && opts.resume) {
return "--list and --resume cannot be combined; --list enumerates saved investigations, --resume renders one. Run --list first, then --resume the id you want.";
}
diff --git a/ix-cli/src/cli/context-bundle-schema.ts b/ix-cli/src/cli/context-bundle-schema.ts
index 6d4ad35d..42394363 100644
--- a/ix-cli/src/cli/context-bundle-schema.ts
+++ b/ix-cli/src/cli/context-bundle-schema.ts
@@ -24,7 +24,7 @@ export const INVESTIGATION_SCHEMA = "ix-investigation/1";
*
* The shapes below mirror the `ContextBundle` and `EvidenceItem` interfaces in
* `commands/context.ts`. Fields the renderers and `--diff` dereference by name
- * — `evidence[].title`, the four `budgets`, the four `truncation` counters and
+ * — `evidence[].title`, the `budgets`, the four `truncation` counters and
* the `metadata` values `--diff` re-sends to the backend — are pinned to their
* real types rather than left as open records: validation that accepts `{}`
* where the code goes on to read `.title` or `.maxEntities` only moves the
@@ -106,6 +106,13 @@ export const contextBundleSchema = z.object({
maxEntities: z.number().int().positive(),
maxRelationships: z.number().int().positive(),
maxEvidence: z.number().int().positive(),
+ // Optional, and only this one. A bundle built before `--max-tokens`
+ // existed carries the other four and nothing else, and zod strips keys it
+ // does not declare — so leaving it out here would not have been "tolerant
+ // of old files", it would have silently dropped the field from every new
+ // one on its way to disk. Required would refuse to load those old files
+ // instead, which is a worse answer than reporting `tokens=not-given`.
+ maxTokens: z.number().int().positive().optional(),
maxChars: z.number().int().positive(),
}),
truncation: z.object({
diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.md
index e712c14f..10c4ffd4 100644
--- a/skills/ix/references/flags.md
+++ b/skills/ix/references/flags.md
@@ -47,6 +47,11 @@ surfaces (#575).
--limit 50` exits with an error rather than a shorter list. `--detailed`
auto-paginates on its own; `--offset` or `--regions` turns that off, and
`--limit` only sets the page size.
+- **`ix context` budgets the evidence block in tokens, not characters.**
+ `--max-tokens` defaults to 1,500 and is converted at 2.14 characters per
+ token, measured across 41 recorded bundles. `--max-chars` is still there for
+ a caller who needs exact bytes and overrides it; passing both is refused
+ rather than silently ranked, because the output does not say which one won.
- **`--pick <n>` is 1-based** everywhere it appears, and is how you resolve an
ambiguous target without re-running with a longer name.
- **`--no-recursive` and `--no-open` negate a default-on behaviour**, so their
@@ -147,7 +152,8 @@ Build a bounded, deterministic context bundle for a symbol, file, or entity (or
| `--max-entities` | `<n>` | — | Maximum entities in the bundle (default: 50, clamped to 1-500) |
| `--max-relationships` | `<n>` | — | Maximum relationships in the bundle (default: 100, clamped to 1-1000) |
| `--max-evidence` | `<n>` | — | Maximum evidence items in the bundle (default: 25, clamped to 1-200) |
-| `--max-chars` | `<n>` | — | Maximum characters of evidence output (default: 12000, clamped to 1000-1000000) |
+| `--max-tokens` | `<n>` | `1500` | Maximum tokens of evidence output (clamped to 500-200000) |
+| `--max-chars` | `<n>` | — | Maximum characters of evidence output; overrides `--max-tokens` (clamped to 1000-1000000) |
| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |
| `--out` | `<path>` | — | Write the JSON bundle to this file instead of stdout |
| `--save` | `<id>` | — | Persist the bundle as a resumable investigation state |