feat(cli): surface stored-query @description/@instruction in queries list

[aaltshuler]

What

omnigraph queries list now surfaces a stored query's @description and @instruction — its catalog metadata (what the query does and how to invoke it) — in both human and --json output.

Previously the CLI dropped both fields even though they were available on the registry entry, while the HTTP GET /queries catalog already carried them. This closes that asymmetry.

Behavior (the agreed shape)

• Query with @description → prints the description: line and the JSON description field.
• Query with @instruction → prints the instruction: line and the JSON instruction field.
• Query with neither → no extra lines; JSON omits both fields entirely (skip_serializing_if = "Option::is_none").

This matches the HTTP catalog shape documented in docs/user/operations/server.md ({ name, tool_name, description, instruction, mutation, params }).

Example human output:

read      described($name: String) [mcp: described]
    description: Find a person by exact name.
    instruction: Use for exact lookups; prefer search for fuzzy matches.
read      bare()

Commits

1. test: e2e coverage documenting the two annotation surfaces as they exist today — schema-level @description/@instruction persisting into _schema.ir.json (engine lifecycle.rs) and query-level annotations surfacing over GET /queries (server stored_queries.rs). No behavior change.
2. feat(cli): the queries list change + CLI tests for both halves of the contract (present → shown, absent → omitted).

Scope note

Only the query-catalog surface changed. Schema-type-level @description/@instruction (on nodes/edges/props) still have no dedicated CLI surface beyond raw schema show source — that's a separate use case (schema documentation, not invocation guidance) and was intentionally left out.

Tests

All green (full files):

• omnigraph-engine lifecycle: 14 passed
• omnigraph-server stored_queries: 14 passed
• omnigraph-cli cli_queries: 12 passed

🤖 Generated with Claude Code

Greptile Summary

This PR surfaces stored-query @description and @instruction annotations in omnigraph queries list, closing the asymmetry between the CLI catalog and the HTTP GET /queries endpoint that already carried both fields. The change is purely additive — new optional fields in QueriesListItem with skip_serializing_if, a small formatting helper for multiline values in human output, and a documentation row in the CLI reference.

• helpers.rs / output.rs: wires q.decl.description and q.decl.instruction into the QueriesListItem DTO and prints them as indented annotation lines in human mode; --json output omits both fields when absent, matching the QueryCatalogEntry shape already in omnigraph-api-types.
• Tests: three new CLI integration tests cover present-in-both-modes, multiline continuation indentation, and clean omission; server and engine e2e tests validate the full annotation round-trip from .gq source through GET /queries.
• Docs: new queries list | validate row in docs/user/cli/reference.md documents the human and --json output shapes, including when optional fields appear.

Confidence Score: 5/5

Safe to merge — purely additive output change with no modifications to storage, server logic, or existing behavior.

The change reads two already-populated fields from an existing struct, adds them to a display DTO with skip_serializing_if, and prints them conditionally. No data path, mutation path, or auth path is touched. Tests cover both the presence and absence contract in human and JSON modes.

No files require special attention.

Important Files Changed

Filename	Overview
crates/omnigraph-cli/src/helpers.rs	Adds print_query_annotation helper and wires description/instruction into human-readable queries list output; one unreachable None arm (dead code, no bug).
crates/omnigraph-cli/src/output.rs	Adds optional description and instruction fields to QueriesListItem with skip_serializing_if — correctly mirrors QueryCatalogEntry from omnigraph-api-types.
crates/omnigraph-cli/tests/cli_queries.rs	Three new tests covering: annotations present in human and JSON output, multiline continuation indentation, and clean omission when absent.
crates/omnigraph-server/tests/stored_queries.rs	New e2e test validates @description/@Instruction round-trip through GET /queries for both annotated and bare queries.
crates/omnigraph/tests/lifecycle.rs	Two schema-level tests: annotations persist verbatim into _schema.ir.json on init, and @Instruction on a property correctly aborts init.
docs/user/cli/reference.md	Adds a queries list

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[".gq source file\n@description / @instruction"] -->|parsed by compiler| B["QueryDecl\n(decl.description, decl.instruction)"]
    B -->|stored in registry| C["Cluster snapshot\n(queries registry)"]
    C -->|HTTP GET /queries| D["QueryCatalogEntry\n{name, tool_name, description?, instruction?, mutation, params}"]
    C -->|CLI: queries list| E["QueriesListItem\n{name, mcp_expose, tool_name, mutation, description?, instruction?, params}"]
    E -->|human output| F["kind  name(params)\n    description: …\n    instruction: …"]
    E -->|--json output| G["JSON: fields omitted\nwhen None"]
    D -->|omnigraph-ts SDK| H["TypeScript QueryCatalogEntry\n{description?, instruction?, …}"]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[".gq source file\n@description / @instruction"] -->|parsed by compiler| B["QueryDecl\n(decl.description, decl.instruction)"]
    B -->|stored in registry| C["Cluster snapshot\n(queries registry)"]
    C -->|HTTP GET /queries| D["QueryCatalogEntry\n{name, tool_name, description?, instruction?, mutation, params}"]
    C -->|CLI: queries list| E["QueriesListItem\n{name, mcp_expose, tool_name, mutation, description?, instruction?, params}"]
    E -->|human output| F["kind  name(params)\n    description: …\n    instruction: …"]
    E -->|--json output| G["JSON: fields omitted\nwhen None"]
    D -->|omnigraph-ts SDK| H["TypeScript QueryCatalogEntry\n{description?, instruction?, …}"]

Loading

_{Reviews (5): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}