docs(user): split language/branching pages + front-door pages (Phase 2)

[aaltshuler]

Phase 2 of the docs restructure (Phase 1 = #223, merged). Content build-out —
docs only, no behavior changes.

Splits (existing content relocated + cross-linked)

• queries/index.md → mutations/index.md + search/index.md (with a
  hybrid-ranking overview tying nearest/bm25/rrf).
• branching/index.md → branching/time-travel.md + branching/merge.md
  (three-way merge + the 7 conflict kinds, verified against
  MergeConflictKind in error.rs).

New pages (written from the code)

• quickstart.md — init → load → query → branch, verified CLI flags.
• concepts/index.md — what OmniGraph is + L1/L2 (Lance / OmniGraph) framing.

Expanded

• operations/audit.md — 7-line stub → real actor-tracking page.

Wiring

docs/user/index.md + AGENTS.md topic table link every new page; AGENTS.md
docs/user link display text normalized to the Phase 1 paths.

Verification

• Zero broken .md links across docs.
• scripts/check-agents-md.sh green (57 links, 54 docs).

Deferred to Phase 3

De-dev polish (grammar paths / IR internals still in queries/branching),
guides/, and a possible reference/config.md split.

🤖 Generated with Claude Code

Greptile Summary

Phase 2 docs restructure: splits the old queries/index.md into separate mutations, search, and query pages; splits branching/index.md into time-travel and merge sub-pages; and adds three new front-door pages (quickstart, concepts/index, expanded audit). AGENTS.md's topic table is updated to use canonical Phase-1 paths throughout.

• New pages — quickstart.md, concepts/index.md, mutations/index.md, search/index.md, branching/time-travel.md, branching/merge.md are written from source and cross-linked from both docs/user/index.md and AGENTS.md.
• CLI accuracy issues — quickstart.md and time-travel.md use the omnigraph read alias, which emits a runtime deprecation warning; the canonical command is omnigraph query. Additionally, the branch create and branch merge examples in quickstart.md and merge.md pass the graph URI as a trailing positional argument, but those subcommands declare uri as a --uri flag — clap will reject the commands as written.
• Minor content gaps — mutations/index.md drops the "temporary until Lance two-phase delete lands" framing for the D₂ restriction, and audit.md's actor-chain omits the still-active legacy cli.actor step.

Confidence Score: 3/5

The docs are correct and well-linked overall, but two CLI examples in the new quickstart will fail at runtime and one will always print a deprecation warning — problems a user would hit on their very first interaction.

The quickstart is the first thing new users run. Two of its branch commands pass the graph URI as a trailing positional, which clap rejects outright — users get an error before completing step 5. The same broken form appears in merge.md. The read-query examples in quickstart.md and time-travel.md use omnigraph read, which emits a stderr deprecation warning on every invocation. These are verified against the actual CLI source.

docs/user/quickstart.md and docs/user/branching/merge.md need the branch-command URI fixes; docs/user/branching/time-travel.md needs the omnigraph query rename.

Important Files Changed

Filename	Overview
docs/user/quickstart.md	New quickstart page; two issues: uses deprecated omnigraph read alias (prints a warning) and passes graph URI as positional to branch create/branch merge (clap will reject it).
docs/user/branching/merge.md	New merge reference page; conflict-kinds table is accurate against MergeConflictKind in engine. CLI example passes the graph URI as a trailing positional, which BranchCommand::Merge rejects (--uri flag required).
docs/user/branching/time-travel.md	New time-travel page; --snapshot flag verified against cli.rs. Uses deprecated omnigraph read alias instead of canonical omnigraph query.
docs/user/mutations/index.md	New mutations page split from queries/index.md; content is accurate but the D₂ temporary-restriction note (pending Lance two-phase delete) is dropped.
docs/user/operations/audit.md	Expanded from stub to full page; the legacy cli.actor in omnigraph.yaml step is silently omitted from the actor-resolution chain (still active for legacy-config users).
AGENTS.md	Link display-text normalized from legacy path aliases to canonical paths; capability matrix Cedar-policy link fixed; no content changes.
docs/user/concepts/index.md	New concepts overview page; L1/L2 table and cross-links are accurate.
docs/user/search/index.md	New search page; function table and rrf hybrid example are accurate.
docs/user/queries/index.md	Mutations and search sections removed and replaced with cross-links to new pages; remaining read-query content is intact.
docs/user/index.md	Routing table updated to add quickstart, concepts, mutations, time-travel, and merge entries; all links verified against new pages.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    IDX[docs/user/index.md] --> QS[quickstart.md NEW]
    IDX --> CON[concepts/index.md NEW]
    IDX --> Q[queries/index.md TRIMMED]
    IDX --> MUT[mutations/index.md NEW]
    IDX --> SRCH[search/index.md NEW]
    IDX --> BR[branching/index.md TRIMMED]
    IDX --> TT[branching/time-travel.md NEW]
    IDX --> MRG[branching/merge.md NEW]
    IDX --> AUD[operations/audit.md EXPANDED]

    Q -- "pointers to" --> MUT
    Q -- "pointers to" --> SRCH
    BR -- "pointers to" --> TT
    BR -- "pointers to" --> MRG

    AGENTS[AGENTS.md] -- "topic table updated" --> IDX

Loading

_{Reviews (1): Last reviewed commit: "docs(user): split language/branching pag..." | Re-trigger Greptile}

Greptile also left 6 inline comments on this PR.

[greptile-apps]

omnigraph read is a deprecated alias that prints a warning

helpers.rs contains "read" => eprintln!("warning: \omnigraph read` is deprecated; use `omnigraph query` instead"), so every invocation emits this warning to stderr. A quickstart is the first thing users run; directing them to a deprecated form creates an immediate bad impression. Replace both omnigraph readcalls on lines 38 and 47 withomnigraph query`.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

omnigraph read prints warning: \omnigraph read` is deprecated; use `omnigraph query` instead(seecrates/omnigraph-cli/src/helpers.rs`). This time-travel page is new and should use the canonical command from the start.

Suggested change

	omnigraph read --query ./q.gq --name find --snapshot <snapshot-id> s3://bucket/graph.omni
	omnigraph query --query ./q.gq --name find --snapshot <snapshot-id> s3://bucket/graph.omni

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Graph URI must be --uri for branch subcommands, not a trailing positional

BranchCommand::Create declares uri as #[arg(long)] (a --uri flag) with only name: String as the positional argument. Passing graph.omni as a second positional causes clap to error with "unexpected argument 'graph.omni' found". The same applies to branch merge on line 53. The correct forms are omnigraph branch create review/new-hires --uri graph.omni and omnigraph branch merge review/new-hires --into main --uri graph.omni. Note: AGENTS.md's Quick-reference flows section has the same pattern for branch merge (pre-existing) — that may need a companion fix.

[greptile-apps]

Same URI-placement issue as in quickstart.md: BranchCommand::Merge uses uri as a --uri long flag, not a positional. Passing the S3 path as a trailing positional will be rejected by clap.

Suggested change

	omnigraph branch merge review/2026-04-25 --into main s3://bucket/graph.omni
	omnigraph branch merge review/2026-04-25 --into main --uri s3://bucket/graph.omni

[greptile-apps]

The original queries/index.md framed the D₂ restriction as temporary: "This restriction lifts when Lance exposes a two-phase delete API (tracked: MR-793)." Dropping that context makes the limitation look permanent and may cause users to design around it unnecessarily rather than treating it as a known, tracked constraint.

Suggested change

	The restriction exists because inserts/updates and deletes commit through
	different paths today, and mixing them in one query creates ordering hazards
	(e.g. a same-row insert-then-delete, or a cascading delete of a just-inserted
	edge). Keeping the two kinds in separate queries keeps each one atomic and
	correct.
	The restriction exists because inserts/updates and deletes commit through
	different paths today, and mixing them in one query creates ordering hazards
	(e.g. a same-row insert-then-delete, or a cascading delete of a just-inserted
	edge). Keeping the two kinds in separate queries keeps each one atomic and
	correct. This restriction is tracked for removal once Lance exposes a two-phase
	delete API (MR-793).

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

The old stub included a legacy step in the CLI actor chain: legacy \cli.actor` in `omnigraph.yaml`. AGENTS.md notes that omnigraph.yaml` "still loads with per-key deprecation warnings," so this step is still live. Omitting it means operators using the legacy config won't see why their actor is being applied.

Suggested change

	1. `--as <actor>` on the command,
	2. then `operator.actor` in `~/.omnigraph/config.yaml` (see the
	[CLI reference](../cli/reference.md)),
	3. otherwise none.
	1. `--as <actor>` on the command,
	2. then `cli.actor` in the legacy `omnigraph.yaml` (if present; deprecated per RFC-008),
	3. then `operator.actor` in `~/.omnigraph/config.yaml` (see the
	[CLI reference](../cli/reference.md)),
	4. otherwise none.