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: one slug for an unresolved target, and document the status booleans (#538)
KageBinary07bf4a7252a8
diff --git a/docs/llm-format.md b/docs/llm-format.mdindex 00c3fd75..68ed1501 100644--- a/docs/llm-format.md+++ b/docs/llm-format.md@@ -25,7 +25,11 @@ so consumers can pass the flag unconditionally without a per-command lookup.backslash-escaped and newline / carriage-return / tab are encoded as `\n` /`\r` / `\t`, so a record never spans more than one line.- **Errors:** a uniform `error code=<slug> message="..."` line in the same- format as data lines; the process still exits non-zero.+ format as data lines; the process still exits non-zero. A target that does+ not exist is always `unresolved_target`, whichever command was asked —+ `context`, `explain`, `read`, `locate`, `subsystems`, `trace`. (The backend+ spells the same condition `unknown_target` in its own JSON bodies; that is a+ wire detail and is translated on the way out, so a consumer never sees both.)## Hierarchies@@ -170,7 +174,7 @@ when that was.Error line:```-error code=unknown_target message="No entity named 'IngestionService' found" suggestions=Ingestion,Service+error code=unresolved_target message="No entity named 'IngestionService' found" suggestions=Ingestion,Service```## Status@@ -197,9 +201,21 @@ Two deliberate exceptions remain:one-record-per-line invariant is relaxed, and the count is what lets aconsumer relax it safely.- **`status` is not smaller** — it is within a byte or two of `json`, because- the payload is a handful of scalars either way. It is in Tier 5 for the- explicit `stale=true|false` field, which is the question the command gets- called to answer and which `text` only implied through a warning line.+ the payload is a handful of scalars either way. It is in Tier 5 for its+ explicit boolean fields, which are the questions the command gets called to+ answer and which `text` only implied through warning lines:++ ```+ status backend=ok endpoint=http://localhost:8090 graph_complete=true map_complete=false rev=2467 last_ingest_at=2026-08-29T01:38:43.341Z stale_files=0 stale=false+ ```++ `graph_complete` and `map_complete` are two different questions and a+ workspace can sit at `true`/`false`. The source graph is ingested and current+ — search, `read`, `context` and `explain` all answer from it — while no+ architecture hierarchy has been recorded for that revision, so `map`,+ `subsystems` and region-scoped views may be empty or stale. `stale` follows+ `graph_complete`, not `map_complete`: it is a claim about files having+ changed, and a missing hierarchy does not make a file out of date.Still routing to `text`: `diff --content` (verbatim hunks) and `ingest`, ahidden implementation-detail command whose output is a completion summary.diff --git a/ix-cli/src/cli/__tests__/llm-renderers.test.ts b/ix-cli/src/cli/__tests__/llm-renderers.test.tsindex 46a4d957..01cd6968 100644--- a/ix-cli/src/cli/__tests__/llm-renderers.test.ts+++ b/ix-cli/src/cli/__tests__/llm-renderers.test.ts@@ -114,9 +114,9 @@ describe("renderSubsystemErrorLlm", () => {const line = renderSubsystemErrorLlm({ error: "ambiguous_target", target_query: "Auth", candidates: [{ pick: 1, label: "Auth", level: 2, label_kind: "subsystem", file_count: 4 }, { pick: 2, label: "AuthZ", level: 2, label_kind: "subsystem", file_count: 2 }] });expect(line).toBe('error code=ambiguous_target message="Multiple regions matched \\"Auth\\"." candidates=1:Auth,2:AuthZ');});- it("renders unknown_target with suggestions", () => {+ it("renders the backend's unknown_target body as an unresolved_target record", () => {const line = renderSubsystemErrorLlm({ error: "unknown_target", target_query: "Foo", message: "No region named Foo.", suggestions: ["Bar", "Baz"] });- expect(line).toBe('error code=unknown_target message="No region named Foo." suggestions=Bar,Baz');+ expect(line).toBe('error code=unresolved_target message="No region named Foo." suggestions=Bar,Baz');});});diff --git a/ix-cli/src/cli/__tests__/llm-tier4.test.ts b/ix-cli/src/cli/__tests__/llm-tier4.test.tsindex 0fc9c9e8..5a70ffdb 100644--- a/ix-cli/src/cli/__tests__/llm-tier4.test.ts+++ b/ix-cli/src/cli/__tests__/llm-tier4.test.ts@@ -56,6 +56,6 @@ describe("renderLocateLlm", () => {it("emits a structured error when nothing resolves", () => {const lines = renderLocateLlm({ resolvedTarget: null, resolutionMode: "none", systemPath: null, diagnostics: ["No graph entity found."] } as any, "foo");- expect(lines).toEqual(['error code=unknown_target message="No graph entity found for \\"foo\\"."']);+ expect(lines).toEqual(['error code=unresolved_target message="No graph entity found for \\"foo\\"."']);});});diff --git a/ix-cli/src/cli/__tests__/llm.test.ts b/ix-cli/src/cli/__tests__/llm.test.tsindex 24e6e5f7..213ebced 100644--- a/ix-cli/src/cli/__tests__/llm.test.ts+++ b/ix-cli/src/cli/__tests__/llm.test.ts@@ -78,11 +78,11 @@ describe("llmLine", () => {describe("llmError", () => {it("renders a uniform error record", () => {- const line = llmError("unknown_target", "No entity named 'Foo' found", [+ const line = llmError("unresolved_target", "No entity named 'Foo' found", [["suggestions", "Bar,Baz"],]);expect(line).toBe(- 'error code=unknown_target message="No entity named \'Foo\' found" suggestions=Bar,Baz'+ 'error code=unresolved_target message="No entity named \'Foo\' found" suggestions=Bar,Baz');});});diff --git a/ix-cli/src/cli/__tests__/mcp.test.ts b/ix-cli/src/cli/__tests__/mcp.test.tsindex 49bd0e79..daf853c2 100644--- a/ix-cli/src/cli/__tests__/mcp.test.ts+++ b/ix-cli/src/cli/__tests__/mcp.test.ts@@ -113,7 +113,7 @@ describe("ix mcp", () => {});it("marks a structured LLM error as an MCP error when the CLI exits successfully", async () => {- const error = 'error code=unknown_target message="No graph entity found for \\"Missing\\"."';+ const error = 'error code=unresolved_target message="No graph entity found for \\"Missing\\"."';const client = await connect(async () => ({ok: true,stdout: error,diff --git a/ix-cli/src/cli/commands/locate.ts b/ix-cli/src/cli/commands/locate.tsindex ac22163b..a4975e28 100644--- a/ix-cli/src/cli/commands/locate.ts+++ b/ix-cli/src/cli/commands/locate.ts@@ -219,7 +219,7 @@ function humanizeBreadcrumb(nodes: Array<{ name: string; kind: string }>): strinexport function renderLocateLlm(output: LocateOutput, symbol: string): string[] {const t = output.resolvedTarget;if (!t) {- return [llmError("unknown_target", `No graph entity found for "${symbol}".`)];+ return [llmError("unresolved_target", `No graph entity found for "${symbol}".`)];}const lines = [llmLine("locate", [["target", t.name],diff --git a/ix-cli/src/cli/commands/subsystems.ts b/ix-cli/src/cli/commands/subsystems.tsindex fa79ac75..d8d2eb7b 100644--- a/ix-cli/src/cli/commands/subsystems.ts+++ b/ix-cli/src/cli/commands/subsystems.ts@@ -30,6 +30,14 @@ interface AmbiguousSubsystemResult {}>;}+/**+ * The backend's own error body for a region name it could not resolve — see+ * `SubsystemRoutes.scala`. `unknown_target` is its spelling and stays as it is+ * here: this type and the guard below describe a wire response, not anything+ * this CLI chose. What we emit for it is `unresolved_target`, the one slug+ * every command uses for "that target does not exist", so an agent routing on+ * the code has one branch rather than two.+ */interface UnknownSubsystemTargetResult {error: "unknown_target";target_query: string;@@ -361,7 +369,7 @@ export function renderSubsystemErrorLlm(body: unknown): string {]);}if (isUnknownSubsystemTargetResult(body)) {- return llmError("unknown_target", body.message, [+ return llmError("unresolved_target", body.message, [["suggestions", (body.suggestions ?? []).join(",") || undefined],]);}