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: add design doc for stabilize and optimize patch
riley0227ebd372fb1718
diff --git a/docs/plans/2026-03-08-stabilize-optimize-design.md b/docs/plans/2026-03-08-stabilize-optimize-design.mdnew file mode 100644index 00000000..90b7b9c1--- /dev/null+++ b/docs/plans/2026-03-08-stabilize-optimize-design.md@@ -0,0 +1,38 @@+# Stabilize and Optimize Existing Ix Workflows — Design++**Goal:** Fix broken high-level commands, make JSON mode fully strict, improve defaults for agent safety.++**Scope:** Backend list endpoint, rank/inventory fixes, JSON audit, safer search defaults, doc updates. Diff optimization and callers fallback changes deferred — both already work.++---++## 1. Fix rank and inventory++**Root cause:** Both commands use `client.search("", { kind })` which matches everything in ArangoDB (CONTAINS with empty string returns true for all values). The backend already has `findNodesByKind()` but no REST route exposes it.++**Backend change:** Add `POST /v1/list` route exposing `findNodesByKind()`. Request: `{ kind: string, limit?: number }`. Response: array of GraphNode. ~30 lines of Scala.++**CLI client:** Add `IxClient.listByKind(kind, opts?)` method calling `POST /v1/list`.++**inventory.ts:** Replace `client.search("")` with `client.listByKind()`. Add client-side path filtering on provenance source_uri.++**rank.ts:** Same replacement. Ranking logic stays the same.++## 2. Strict JSON cleanup++**Already done:** `resolve.ts` routes all diagnostics to stderr (previous patch Task 2).++**Remaining:** Audit all command files for unguarded `console.log` calls that leak to stdout in JSON mode. Fix any found to use `stderr()` or format guards. Remove stray `console.log("CLI depth:")` in api.ts.++## 3. Safer search defaults++Lower default search limit from 20 to 10. Add `unfiltered_search` diagnostic when no `--kind` filter used.++## 4. Doc updates++Update AGENTS.md, CLAUDE.md to reflect working rank/inventory, emphasize `--kind` on search, keep high-level commands as preferred entry points.++## Deferred++- Diff server-side summary optimization — current client-side summary works+- Callers fallback tightening — already bounded (10 matches max)