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-server/tests/stored_queries.rs

@@ -369,6 +369,47 @@ async fn list_queries_is_read_gated_so_a_non_invoker_can_list() {
     );
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn list_queries_surfaces_query_description_and_instruction() {
+    // E2e for the query-level `.gq` surface: `@description`/`@instruction` on
+    // a stored query declaration are carried through to clients via the typed
+    // `QueryCatalogEntry` fields over `GET /queries`. A query without them
+    // omits both fields (serde `skip_serializing_if = "Option::is_none"`).
+    let described = "query described($name: String) \
+        @description(\"Find a person by exact name.\") \
+        @instruction(\"Use for exact lookups; prefer search for fuzzy matches.\") \
+        { match { $p: Person { name: $name } } return { $p.age } }";
+    let (_temp, app) = app_with_stored_queries(
+        &[
+            ("described", described, true),
+            ("bare", "query bare() { match { $p: Person } return { $p.name } }", true),
+        ],
+        &[("act-invoke", "t-invoke")],
+        INVOKE_POLICY_YAML,
+    )
+    .await;
+    let (status, body) = json_response(&app, get_request(&g("/queries"), "t-invoke")).await;
+    assert_eq!(status, StatusCode::OK, "body: {body}");
+    let entries = body["queries"].as_array().unwrap();
+
+    let described = entries.iter().find(|q| q["name"] == "described").unwrap();
+    assert_eq!(
+        described["description"], "Find a person by exact name.",
+        "query @description surfaces over GET /queries: {described}"
+    );
+    assert_eq!(
+        described["instruction"],
+        "Use for exact lookups; prefer search for fuzzy matches.",
+        "query @instruction surfaces over GET /queries: {described}"
+    );
+
+    let bare = entries.iter().find(|q| q["name"] == "bare").unwrap();
+    assert!(
+        bare.get("description").is_none() && bare.get("instruction").is_none(),
+        "a query without the annotations omits both fields: {bare}"
+    );
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn list_queries_is_empty_when_no_registry() {
     let (_temp, app) = app_for_loaded_graph_with_auth("demo-token").await;