omnigraph/docs/dev/docs-issues.md

User Docs Coherence Ledger

Last review: 2026-06-20 (against 0.7.1) Status: all open findings resolved — living ledger for future audits.

This page tracks stale or incoherent user-doc claims found during broad docs reviews. Findings are validated against current code/behavior, not just cross-doc consistency. Record new findings as they surface; mark them resolved (with the fixing commit) once the public pages are corrected.

Resolved — 2026-06-20 docs/user coherence sweep

Every finding from the 2026-06-20 review was validated (all reproduced) and fixed. Branch docs/user-coherence-0-7-1.

Pri	Finding	Resolution
P1	cluster apply documented as catalog-only / "Stage 3A" with graph+schema deferred — in both cli/reference.md and the shipped CLI help (cli.rs)	Rewrote both to describe the real converge behavior (creates graphs, applies schema with soft drops, writes catalog, executes approved deletes in one ordered run); deferred now means the genuinely-unsupported case (standalone schema delete).
P1	Stored-query exposure had two contracts: server.md documented a per-query mcp:{expose:false} knob; cluster docs said all queries are listed	Confirmed in code: cluster registry has no expose field (QueryConfig), boot bridge hardcodes expose: true (omnigraph-server settings), no GQ-level annotation. Removed the knob from server.md; documented "every applied query is listed; per-query exposure may become a Cedar-policy decision later".
P1	The same stale "mcp.expose == true subset" contract lived in the OpenAPI surface: utoipa annotations (handlers.rs:1029,1037, omnigraph-api-types/src/lib.rs:404) drove openapi.json (Greptile catch on #293)	Updated the three Rust doc-comment/annotation strings to "every stored query" and regenerated openapi.json (OMNIGRAPH_UPDATE_OPENAPI=1); drift test green. Same-change per AGENTS.md rule 4.
P2	schema/index.md claimed allow_data_loss honored "uniformly across transports" incl. HTTP POST /schema/apply	Scoped to the direct/embedded path; added that cluster-managed graphs evolve via cluster apply (soft drops only) and the HTTP route is 409-disabled for cluster serving.
P2	/load missing from admission / body-limit / rate-limit / manifest-conflict prose (named /ingest only); constants called it "Ingest body limit"	Documented /load as canonical everywhere with /ingest as the deprecated alias; renamed the constant to "Load (bulk-write) body limit".
P2	CLI "Bearer token resolution" section listed removed omnigraph.yaml keys (graphs.<name>.bearer_token_env, auth.env_file)	Replaced with a pointer to the keyed-credential model (OMNIGRAPH_TOKEN_<NAME> → ~/.omnigraph/credentials → OMNIGRAPH_BEARER_TOKEN); no plaintext-in-config path.
P2	Flat route names in a cluster-only server (POST /query, POST /mutate, GET /queries, POST /queries/{name})	Added a one-line note that the per-graph subsections use shorthand under /graphs/{id}/…; the endpoint table is already fully qualified.
—	version printed omnigraph 0.3.x	→ 0.7.x.
—	search/indexes.md used deprecated ingest --mode merge	→ load --mode merge.
—	config.md deferred disposition described as "graph/schema change, later phase"	→ "an unsupported change (e.g. standalone schema delete)".
—	Stale stage labels (Stage 3A, Stage 2C, Stage 1) in active reference docs	Removed / reworded to plain language; release notes keep history.

Open — surfaced 2026-06-20, not yet fixed

• Stale "config-only apply" / "Stage 3A" comments in omnigraph-cluster source (internal rustdoc, not user docs — out of scope for the docs sweep above): src/types.rs:147 ("Applied changes execute (config-only query/policy catalog writes)"), src/types.rs:265 ("Output of config-only cluster apply"), src/diff.rs:256, and src/tests.rs:1129 ("config-only apply (Stage 3A)"). Apply now also runs graph creates, schema applies, and approved deletes (diff.rs:411 GraphCreate / SchemaApply; the Stage-4 create/schema/delete executors + tests apply_creates_graph_and_unblocks_dependents, apply_schema_update_and_dependent_query_in_one_run, apply_blocks_graph_delete_without_approval). Update these comments in a cluster-crate change.
• Cross-repo drift from this sweep (separate repos):
  • omnigraph-ts SDK — its generated spec/openapi.json + packages/sdk/src/generated/types.gen.ts still describe the GET /queries catalog as the mcp.expose subset. No hand-fix: the SDK's scripts/sync-spec.ts pulls openapi.json from a tagged omnigraph release (/omnigraph/v{version}/openapi.json), and the catalog fix landed on main after the v0.7.1 tag — so it is in no tag yet and a hand-edit would be overwritten on the next sync. It flows in automatically when the SDK bumps to a tag containing the fix (v0.7.2+). Tracked, not actioned.
  • omnigraph-cookbooks/docs/best-practices.md bearer_token_env chain — RESOLVED by omnigraph-cookbooks PR #26 (2026-06-21), which deleted docs/best-practices.md as part of the 0.7 restructure; the stale chain survives nowhere on main.

Verification checklist (re-run on the next docs audit)

rg -n "Stage [0-9]|graph/schema changes are deferred|reserved for later stages" docs/user crates/omnigraph-cli/src/cli.rs
rg -n "POST /query|POST /mutate|GET /queries|POST /queries/\{name\}|POST /schema/apply" docs/user
rg -n "ingest --mode|Ingest body limit|/ingest" docs/user
rg -n "0\.3\.x|bearer_token_env|auth\.env_file" docs/user
rg -n "expose: false|mcp\.expose" docs/user

Expected: active user docs have no matches for stale phrases, or the remaining matches are explicitly marked as deprecated aliases, "no longer exist" notes, or route shorthand disclaimed relative to /graphs/{id}. Release notes are allowed to preserve historical behavior.