feat(api+cli+docs): unified query response contract for multi-strategy routing

[Copilot]

• Update cli/src/lib/types.ts: add QueryResultItem, QueryResponse, RoutingDecision, GraphResult, GraphEntity, GraphEdge, GraphMeta (with full server-side fields + index signature), EntityPath, EntityDocument types; keep old QueryResult as deprecated
• Update cli/src/lib/api-client.ts: add strategy param to query(), return typed QueryResponse
• Update cli/src/commands/query.ts: add --strategy and --verbose flags with validation (allowed set + "auto" → undefined); strategy-aware output formatting (routing line, filter match, graph documents section); fix scopedResponses to spread out preserving ok
• Update docs/09-api-reference.md: fix request example (no graphExpand+strategy mix); update graph presence condition; expand graph.meta field table (full server-side fields); fix metadata text note to reflect actual behavior
• Update docs/03-cli.md: add --strategy, --verbose, --since, --until, --filterField, --filterCombine to flag table; add strategy-aware output subsection with per-strategy examples
• Update docs/01-architecture.md: extend POST /query bullet; add Query Router sequence diagram; update hybrid sequence diagram
• Update skill/SKILL.md: fix filter examples to use key-value format (remove legacy must array); expand graph meta example with full traversal metadata fields; add strategy to query parameters table; add Query Strategies subsection
• Add 9 tests for strategy-aware CLI output: strategy in/out of request body, "auto" handling, invalid strategy exit, semantic with/without --verbose, metadata routing+filter match, graph routing+documents section, empty graph documents suppression
• All 189 tests pass

Original prompt

---

This section details on the original issue you should resolve

<issue_title>feat(api+cli+docs): Unified query response contract for multi-strategy routing</issue_title>
<issue_description>## Parent

• Parent issue: EPIC(feat): Hybrid Query Router — metadata, graph, and semantic query strategies #109

Summary

Standardize POST /query response shape across all strategy modes, add strategy-aware CLI output, and update all documentation. This is the final integration point that pins the unified contract and ensures all consumers — API clients, CLI, and docs — are aligned.

Dependencies

Issue	Provides
#112 (router)	routing field in response
#113 (graph)	Expanded GraphResult shape
#116 (metadata)	Metadata-only result behavior
#110 (hybrid)	Hybrid result shape
#93 (CLI enhancements)	Coordination for CLI flag additions

Merge Order

This issue merges LAST in the epic. It integrates and pins the canonical shape produced by all prior issues.
Per CC-5 in #109: #113 → #112 → #117 (this issue).

---

Scope

In scope

• Pin canonical TypeScript interfaces for the unified response contract
• CLI: --strategy, --verbose flags (new in this issue)
• CLI: strategy-aware output formatting (routing line, filter match, graph documents)
• Documentation updates: API reference, CLI docs, architecture, skill guidance
• Backward compatibility verification

Out of scope

• Strategy execution internals (done in feat(query): Router and classifier (rules + LLM fallback) #112, feat(query): Graph strategy using current relational graph tables #113, feat(query): Metadata strategy engine for structured and temporal filters #116, feat(query): Hybrid execution and result merge/rerank #110)
• Changes to /query/download-first or /query/fulltext-first
• Database migrations
• Streaming or SSE variants
• --since/--until CLI flags (already implemented in feat(query): Metadata strategy engine for structured and temporal filters #116)

---

Response Contract

Top-Level Envelope

Field	Type	Presence	Description
ok	true	always	Success indicator
results	QueryResultItem[]	always	Ranked result items
graph	GraphResult	when strategy is graph/hybrid	Entity graph data
routing	RoutingDecision	always	How the strategy was selected

Per-Item Result

Field	Type	Description
id	string/number	"baseId:chunkIndex" or arbitrary string
score	number (0–1)	Cosine similarity; 1.0 for metadata-only
source	string?	Source URL or path
text	string?	Chunk text; absent for metadata-only results
payload	object?	Enrichment metadata (unchanged shape)

Routing Decision

Field	Type	Description
strategy	enum	metadata | graph | semantic | hybrid
method	enum	explicit | rule | llm | rule_fallback | default
confidence	0–1	Classification confidence
rule	string?	Matched rule name
durationMs	number	Router wall-clock time (ms)

Graph Result

Field	Type	Description
entities[]	array	With depth, isSeed, description per entity
relationships[]	array	source, target, type edges
paths[]	array	Entity traversal chains
documents[]	array?	Source documents linked to entities
meta	object	entityCount, capped, timedOut, warnings[]

---

CLI Changes

New Flags (owned by this issue)

Flag	Type	Default	Description
--strategy <name>	string	(auto)	Force strategy: semantic, metadata, graph, hybrid
--verbose	boolean	false	Always print routing decision and timing

Existing Flags (owned by #116, verified here)

Flag	Type	Description
--since <date>	string	ISO 8601 lower date bound (temporal filter)
--until <date>	string	ISO 8601 upper date bound (temporal filter)

These flags are already implemented by #116. This issue verifies they work correctly with strategy-aware output but does NOT re-implement them.

Strategy-Aware Output

Routing line (shown when strategy ≠ semantic OR when --verbose):

routing: <strategy>  (<method>, <durationMs>ms)

Output per strategy:

flowchart LR
    S[Strategy] --> SE[semantic]
    S --> ME[metadata]
    S --> GR[graph]
    S --> HY[hybrid]

    SE --> SE_OUT["#N score=X<br/>collection: …<br/>source: …<br/>snippet: …"]
    ME --> ME_OUT["#N score=1.00<br/>routing: metadata …<br/>filter match: field=val …"]
    GR --> GR_OUT["#N score=X<br/>routing: graph …<br/>snippet: …<br/>--- graph documents ---"]
    HY --> HY_OUT["#N score=X<br/>routing: hybrid …<br/>snippet: …<br/>--- graph documents ---"]

Loading

Strategy	Score	Text shown	Extras
semantic	cosine similarity	snippet (280 chars)	routing line only with `-...

• Fixes feat(api+cli+docs): Unified query response contract for multi-strategy routing #117

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1f917d6ea4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Pins a unified POST /query response contract across routing strategies, updates the CLI to accept a user-selected strategy and display strategy-aware output, and aligns documentation to the new routing/graph response model.

Changes:

• Added/updated TypeScript types to represent the canonical query response shape, including routing and graph structures.
• Extended CLI query command with --strategy / --verbose and strategy-aware output formatting (routing line, metadata filter match, graph documents section).
• Updated API reference, CLI docs, architecture docs, and skill docs to describe the multi-strategy router and unified response envelope.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
cli/src/lib/types.ts	Introduces unified response types (QueryResponse, RoutingDecision, GraphResult, etc.).
cli/src/lib/api-client.ts	Extends query() to optionally send strategy and return a typed QueryResponse.
cli/src/commands/query.ts	Adds --strategy / --verbose options and implements strategy-aware output formatting.
docs/09-api-reference.md	Documents strategy, routing, and expanded graph response example and tables.
docs/03-cli.md	Documents new CLI flags and describes per-strategy output behavior.
docs/01-architecture.md	Updates /query architecture description and adds router sequence diagram.
skill/SKILL.md	Updates skill documentation to include strategy, routing, and updated response examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mfittko]

@copilot address all review comments

[mfittko]

Full review complete — approving.

What I verified:

• Unified query response contract types are aligned in CLI (QueryResponse, RoutingDecision, GraphResult, extended GraphMeta).
• CLI strategy behavior is implemented and validated: --strategy validation, auto omission, --verbose routing line behavior, metadata filter-match output, and graph documents section.
• Strategy propagation now covers all query paths, including /query, /query/download-first, and /query/fulltext-first.
• Docs updated consistently across API reference, CLI docs, architecture, and skill guide.
• Build + test evidence:
  • cli: npm test (191 passing) and npm run build passing.
  • api: npm run build passing.
  • api tests are largely green; 3 src/db.test.ts failures are environment-specific (database "raged" does not exist) and unrelated to this PR’s logic.
• All review threads are resolved (0 unresolved).

Given current branch state (including 8fb25b7), this is ready to merge.

[mfittko]

Final AC/DoD evidence summary for #117 (PR #122)

Acceptance Criteria

• All strategy modes return one stable response contract (ok, results, routing, optional graph)
• routing field present in every query response
• Existing clients remain compatible (additive contract; unknown fields tolerated)
• CLI shows routing line for non-semantic strategies, or when --verbose
• CLI shows filter match: for metadata-only results
• CLI shows graph documents section when graph.documents is present
• --strategy sends explicit strategy in request body
• --since / --until continue working with strategy-aware output
• graphExpand: true remains accepted without error
• CLI types aligned with canonical API contract (QueryResponse, RoutingDecision, GraphResult, expanded GraphMeta)
• All four docs updated and cross-consistent (09-api-reference, 03-cli, 01-architecture, skill/SKILL.md)
• TypeScript compilation succeeds for both api/ and cli/
• Tests pass (local + CI)
• Backward compatibility checklist completed in PR discussion/review evidence

Definition of Done

• Acceptance criteria completed with linked code/tests/docs evidence
• Unified contract is consistent across API, CLI types, formatter output, and docs
• --strategy / --verbose behavior covered by CLI tests
• Default CLI behavior preserved unless explicitly strategy-routed
• API and CLI builds pass in CI
• Backward compatibility validated with additive contract behavior
• Sample outputs included in docs for semantic/metadata/graph/hybrid

Final note

The remaining review blocker (strategy propagation to download/fulltext query paths) was fixed in commit 8fb25b7, with regression tests added for both /query/download-first and /query/fulltext-first strategy propagation.