docs(user): coherence cleanup aligned with 0.7.1

[aaltshuler]

Summary

Fixes stale/contradictory claims in docs/user/ (and one shipped CLI help
string) surfaced by a static review and recorded in the new tracked ledger
docs/dev/docs-issues.md. Every finding was validated against current
code/behavior, not just cross-doc consistency — all 6 priority findings + 4
smaller crumbs reproduced. Docs-only except one user-facing CLI help-text fix.

Commits are split P1 first, then P2 + crumbs, then the ledger:

Commit	Fix
cluster apply semantics (P1)	Both cli/reference.md and the CLI help (cli.rs) called apply a "Stage 3A" config-only (query/policy) subset that defers graph/schema "to a later stage". Apply actually creates graphs, applies schema (soft drops), writes catalog, and executes approved deletes in one ordered run (verified: diff.rs GraphCreate/SchemaApply, Stage-4 executors + tests). Rewrote both; deferred now = the genuinely-unsupported case (standalone schema delete).
stored-query exposure (P1)	server.md documented a per-query mcp:{expose:false} knob that doesn't exist in cluster-only serving (registry has no expose field; boot bridge hardcodes expose:true; no GQ annotation). Now documents "every applied query is listed".
schema apply paths (P2)	schema/index.md claimed allow_data_loss honored "uniformly across transports" incl. HTTP. Scoped to direct/embedded; noted cluster apply = soft drops only and the HTTP route is 409-disabled for cluster serving.
/load canonical (P2)	Added /load to admission/body-limit/rate-limit/manifest-conflict prose (named /ingest only); renamed the "Ingest body limit" constant.
bearer-token + version (P2)	Removed stale omnigraph.yaml keys (graphs.<name>.bearer_token_env, auth.env_file) → pointer to the keyed-credential model; version 0.3.x → 0.7.x.
route shorthand + crumbs (P2)	One-line note that per-graph subsections use /graphs/{id}/… shorthand; deferred disposition wording; dropped Stage 2C/Stage 1 labels; ingest --mode merge → load --mode merge.
ledger (dev)	Track docs/dev/docs-issues.md as a living coherence ledger, linked from the dev index; mark the sweep resolved; record one open follow-up (stale "config-only apply" rustdoc comments in omnigraph-cluster/src — internal, separate change).

0.7.1 alignment

No user doc warns against camelCase field names (would be stale post-#283); no
residual 0.3.x/0.6.x strings; queries list @description/@instruction
(#280) already documented.

Verification

• The ledger's own grep checklist comes back clean (only deprecated-alias /
  "no longer exist" / disclaimed-shorthand matches remain).
• scripts/check-agents-md.sh → OK (61 links, 58 docs).
• cargo test -p omnigraph-cli green (no test asserted the old help string);
  CLI builds and cluster apply --help shows the corrected text.

Out of scope: the user's unrelated loader/mod.rs WIP (left untouched), and the
internal cluster-crate comment cleanup (tracked in the ledger).

🤖 Generated with Claude Code

Greptile Summary

This PR fixes stale and contradictory claims across docs/user/ (and one shipped CLI help string) validated against 0.7.1 code behavior, then tracks all findings in a new docs/dev/docs-issues.md coherence ledger. The most impactful corrections are the cluster apply semantics rewrite (from "catalog-only / Stage 3A" to the real converge run) and the removal of the nonexistent mcp:{expose:false} per-query knob.

• cluster apply help text and reference docs rewritten to reflect the actual ordered run: graph creates → schema soft-drops → catalog writes → approved deletes, with deferred now meaning the genuinely-unsupported case (standalone schema delete).
• mcp.expose contract removed from server.md, handlers.rs, lib.rs, and openapi.json; the QueriesCatalogOutput description and the 200-response description are updated — however the OpenAPI summary field (derived from handlers.rs:1035's first doc-comment line) still reads "exposed stored queries" and needs a one-word fix.
• Cross-repo drift (omnigraph-ts stale spec, omnigraph-cookbooks bearer_token_env reference) is acknowledged in the ledger as tracked open items.

Confidence Score: 4/5

Mostly safe docs-only cleanup; one residual inconsistency in the OpenAPI surface needs a one-line fix before the contract is fully coherent.

The PR's central goal is eliminating the stale mcp.expose contract from the OpenAPI surface. It updated the description, response description, and component description — but left the first doc-comment line on server_list_queries unchanged ("List the graph's exposed stored queries"), which utoipa uses as the OpenAPI summary field. That summary appears verbatim in openapi.json line 1008 and will be the first thing any SDK generator or API browser displays. The rest of the doc changes are accurate and well-verified.

crates/omnigraph-server/src/handlers.rs line 1035 and the corresponding openapi.json line 1008 — the OpenAPI summary still says "exposed stored queries."

Important Files Changed

Filename	Overview
crates/omnigraph-server/src/handlers.rs	Description body updated correctly to "every stored query," but the first doc-comment line (OpenAPI summary) still reads "exposed stored queries" — a stale fragment that will re-appear in any downstream OpenAPI regeneration.
openapi.json	Description and response-description fields updated; summary field at line 1008 retains "exposed stored queries" because it is generated from the unchanged first doc-comment line in handlers.rs.
crates/omnigraph-api-types/src/lib.rs	Doc comment on QueriesCatalogOutput updated from "the mcp.expose subset" to "every stored query" — consistent with the rest of the PR.
crates/omnigraph-cli/src/cli.rs	CLI help text for cluster apply rewritten to accurately describe the full converge run (graph creates, schema soft-drops, catalog writes, approved deletes).
docs/dev/docs-issues.md	New living-ledger file tracking resolved findings and open cross-repo drift items; well-structured with a re-runnable verification checklist.
docs/user/cli/reference.md	Rewrote cluster apply prose from "catalog-only / Stage 3A" to the correct converge semantics; removed stale stage labels and deprecated bearer-token keys.
docs/user/operations/server.md	Removed the per-query mcp:{expose:false} knob; added the /load alias and route-shorthand note; all endpoint table entries updated.
docs/user/schema/index.md	Scoped allow_data_loss to the direct/embedded path; added a clear callout that cluster-managed graphs use soft-drops only and HTTP POST /schema/apply is 409-disabled.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["GET /graphs/{id}/queries"] --> B["authorize_request\n(bearer + read on main)"]
    B -->|authorized| C["registry.iter()\n.filter(q.expose)\n.map(query_catalog_entry)"]
    B -->|denied| D["401 / 403"]
    C --> E{"registry present?"}
    E -->|yes| F["QueriesCatalogOutput\n(every query — expose hardcoded true\nin cluster boot bridge)"]
    E -->|no| G["QueriesCatalogOutput\n(empty vec)"]
    F --> H["200 JSON response"]
    G --> H

    style F fill:#d4edda
    style D fill:#f8d7da

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["GET /graphs/{id}/queries"] --> B["authorize_request\n(bearer + read on main)"]
    B -->|authorized| C["registry.iter()\n.filter(q.expose)\n.map(query_catalog_entry)"]
    B -->|denied| D["401 / 403"]
    C --> E{"registry present?"}
    E -->|yes| F["QueriesCatalogOutput\n(every query — expose hardcoded true\nin cluster boot bridge)"]
    E -->|no| G["QueriesCatalogOutput\n(empty vec)"]
    F --> H["200 JSON response"]
    G --> H

    style F fill:#d4edda
    style D fill:#f8d7da

Loading

_{Reviews (2): Last reviewed commit: "docs(api): align GET /queries OpenAPI co..." | Re-trigger Greptile}

[greptile-apps]

omnigraph-cookbooks best-practices still references removed bearer_token_env chain

omnigraph-cookbooks/docs/best-practices.md:372 describes client-side auth as "token resolves via OMNIGRAPH_TOKEN_<NAME> → the credentials file → the legacy bearer_token_env chain." The bearer_token_env key is one of the removed omnigraph.yaml keys documented as "no longer exist" in this very PR. If the ledger's purpose is to be a living coherence checklist, the cookbook drift is worth tracking here (or opening a follow-up in the cookbooks repo) so the removal of that chain is fully reflected across the docs ecosystem.