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

* test: e2e coverage for @description/@instruction surfaces

Add end-to-end tests pinning the two annotation surfaces as they exist
today, at their real boundaries:

- engine (lifecycle.rs): schema-level @description (node/edge/property)
  and @instruction (node/edge) persist verbatim into the on-disk
  _schema.ir.json through Omnigraph::init; property-level @instruction
  aborts init and writes no schema IR.
- server (stored_queries.rs): query-level @description/@instruction on a
  stored query surface as typed QueryCatalogEntry fields over
  GET /queries, and a query declaring neither omits both fields.

No behavior change — these document the current contract.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

A stored query's @description/@instruction are its catalog metadata —
what it does and how to invoke it. The HTTP GET /queries catalog already
carries them, but `omnigraph queries list` dropped both fields in human
and --json output even though they were available on the registry entry.

Carry description/instruction on QueriesListItem (Option, skipped when
None) and copy them from the query decl. Human output prints an indented
`description:` / `instruction:` line per query when present; --json
includes the fields when present and omits them otherwise — matching the
HTTP catalog shape documented in docs/user/operations/server.md.

Tests (cli_queries.rs): a query with both annotations surfaces them in
human + --json; a query with neither prints no annotation lines and omits
both JSON fields.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(cli): document `queries list` output incl. description/instruction

Per AGENTS.md maintenance Rule 1, document the user-visible `queries list`
output alongside the field addition. The `queries` command family had no
row in the CLI reference top-level table; add one covering `list` (human
+ --json shapes, with description/instruction shown only when declared,
matching the HTTP GET /queries catalog) and `validate`.

Addresses the Greptile P2 review finding on PR #280.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(cli): indent multiline stored-query annotations in `queries list`

A `@description`/`@instruction` value can be multiline (GQ string literals
admit newlines), which made the human `queries list` output break back to
the left margin on continuation lines. Indent continuation lines to align
under the first via a `print_query_annotation` helper. Addresses review
feedback from @martin-g on PR #280.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Ragnor Comerford <ragnor.comerford@gmail.com>

crates/omnigraph-cli/src/helpers.rs

@@ -875,6 +875,25 @@ pub(crate) async fn execute_queries_validate(
     Ok(())
 }
 
+/// Print a stored-query annotation under its `queries list` entry. A
+/// `@description`/`@instruction` value may be multiline (GQ string literals
+/// admit newlines); continuation lines are indented to align under the first
+/// so the catalog stays readable instead of breaking the left margin.
+fn print_query_annotation(label: &str, value: &str) {
+    let prefix = format!("    {label}: ");
+    let continuation = " ".repeat(prefix.len());
+    let mut lines = value.split('\n');
+    match lines.next() {
+        Some(first) => {
+            println!("{prefix}{first}");
+            for line in lines {
+                println!("{continuation}{line}");
+            }
+        }
+        None => println!("{prefix}"),
+    }
+}
+
 /// `queries list --cluster <dir>` (RFC-011): list the catalog's stored queries.
 /// With `--graph`, scope to one graph.
 pub(crate) async fn execute_queries_list(
@@ -893,6 +912,8 @@ pub(crate) async fn execute_queries_list(
                 mcp_expose: q.expose,
                 tool_name: q.tool_name.clone(),
                 mutation: q.is_mutation(),
+                description: q.decl.description.clone(),
+                instruction: q.decl.instruction.clone(),
                 params: q
                     .decl
                     .params
@@ -933,6 +954,12 @@ pub(crate) async fn execute_queries_list(
                 String::new()
             };
             println!("{kind}  {}({params}){mcp}", q.name);
+            if let Some(description) = &q.description {
+                print_query_annotation("description", description);
+            }
+            if let Some(instruction) = &q.instruction {
+                print_query_annotation("instruction", instruction);
+            }
         }
     }
     Ok(())

crates/omnigraph-cli/src/output.rs

@@ -849,6 +849,13 @@ pub(crate) struct QueriesListItem {
     pub(crate) mcp_expose: bool,
     pub(crate) tool_name: Option<String>,
     pub(crate) mutation: bool,
+    /// `@description` from the query declaration — what the query is for.
+    /// Carried so the CLI catalog matches the HTTP `GET /queries` surface.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) description: Option<String>,
+    /// `@instruction` from the query declaration — how/when to invoke it.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(crate) instruction: Option<String>,
     pub(crate) params: Vec<QueriesParam>,
 }