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

[aaltshuler]

Stacked on #223 (base = docs/topic-restructure). Review/merge #223 first;
this PR's diff is Phase 2 only.

What

Content build-out on top of the Phase 1 topic move — no behavior changes,
docs only.

Splits (existing content relocated + cross-linked)

• queries/index.md → mutations/index.md (insert/update/delete + the
  inserts-vs-deletes-in-one-query rule) and search/index.md (the
  multi-modal search functions + a hybrid-ranking overview tying
  nearest/bm25/rrf together). queries/index.md keeps the read shape and
  points at both.
• branching/index.md → branching/time-travel.md (snapshots / time
  travel) and 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, with verified CLI flags
  (--mode required on load, positional URI for local graphs, etc.).
• concepts/index.md — what OmniGraph is + the L1/L2 (Lance / OmniGraph)
  framing.

Expanded

• operations/audit.md — from a 7-line struct dump to a real actor-tracking
  page (server token-resolved vs CLI --as chain; reading the trail; the
  omnigraph:recovery reserved actor).

Wiring

docs/user/index.md and AGENTS.md's topic table link every new page; AGENTS.md's
docs/user link display text normalized to match the Phase 1 retargeted 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 (config schema is already
coherent in cli/reference.md, so not split now).

🤖 Generated with Claude Code

Greptile Summary

This is a docs-only build-out (Phase 2) that splits the existing query-language and branching pages into focused sub-pages, adds front-door pages (quickstart.md, concepts/index.md), expands audit.md from a struct dump into a real actor-tracking guide, and wires everything into docs/user/index.md and AGENTS.md. No code changes are included.

• New pages — mutations/index.md, search/index.md, branching/merge.md, branching/time-travel.md, quickstart.md, concepts/index.md — all split accurately from existing content; the 7 MergeConflictKind variants in merge.md match error.rs.
• AGENTS.md wiring — display-text normalization and new topic-table rows are correct; all target paths resolve.
• audit.md expansion — greatly improved, but the documented CLI actor-resolution chain drops the still-active legacy cli.actor (omnigraph.yaml) step that sits between --as and operator.actor in the implementation.

Confidence Score: 4/5

Docs-only change with no code modifications; safe to merge with the audit chain omission noted.

The new pages are accurate and the AGENTS.md wiring is clean. The one substantive issue is that audit.md's expanded CLI actor chain omits the legacy cli.actor (omnigraph.yaml) step that is still active in the implementation and sits between --as and operator.actor — users debugging actor provenance with a legacy config would find the docs misleading. Two additional minor style/accuracy issues round out the findings.

docs/user/operations/audit.md — the actor resolution chain should include the deprecated-but-active legacy step.

Important Files Changed

Filename	Overview
AGENTS.md	Link display-text normalization and addition of Phase 2 topic rows — all target paths verified correct against the Phase 1 restructure.
docs/user/operations/audit.md	Expanded from struct-dump to prose; the CLI actor resolution chain silently drops the legacy cli.actor (omnigraph.yaml) step that is still active in code.
docs/user/mutations/index.md	New page split from queries/index.md; D₂ error message quote is truncated compared to what the runtime actually emits.
docs/user/concepts/index.md	New concepts page with L1/L2 table; minor inconsistency in HTTP server link text using a file path rather than a human-readable label.
docs/user/quickstart.md	New quickstart page; CLI flags, --mode requirement, and positional URI usage all match code and AGENTS.md quick-reference flows.
docs/user/branching/merge.md	New merge page; all 7 MergeConflictKind variants are correctly enumerated and described.
docs/user/branching/time-travel.md	New time-travel page split from branching/index.md; accurately describes snapshot-isolated reads and the CLI --snapshot flag.
docs/user/search/index.md	New search page with function table and hybrid-ranking rrf example; all functions match the original queries/index.md table.
docs/user/branching/index.md	L2 snapshot section replaced with cross-links to new time-travel.md and merge.md pages; content is accurately redirected.
docs/user/queries/index.md	Search and mutation sections extracted to dedicated pages; this page correctly retains the read shape, RETURN, ORDER/LIMIT, and IR sections.
docs/user/index.md	Front-door nav updated with quickstart, concepts, mutations, search, and branching sub-pages; all links verified against existing files.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    IDX[docs/user/index.md\nfront door] --> QS[quickstart.md\nnew]
    IDX --> CON[concepts/index.md\nnew]
    IDX --> QRY[queries/index.md\nread shape only]
    IDX --> MUT[mutations/index.md\nnew split]
    IDX --> SRC[search/index.md\nnew split]
    IDX --> BR[branching/index.md\nbranches + commits]
    IDX --> TT[branching/time-travel.md\nnew split]
    IDX --> MRG[branching/merge.md\nnew split]
    IDX --> AUD[operations/audit.md\nexpanded]

    QRY -- mutations --> MUT
    QRY -- search funcs --> SRC
    BR -- snapshots --> TT
    BR -- merge --> MRG
    SRC --> EMB[search/embeddings.md]
    SRC --> IXS[search/indexes.md]
    CON --> BR
    CON --> TT
    CON --> MRG
    CON --> SRC
    CON --> QRY

Loading

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

Greptile also left 3 inline comments on this PR.

[greptile-apps]

Legacy cli.actor step missing from resolution chain

The code in crates/omnigraph-cli/src/helpers.rs (line 173) documents and implements the full chain as --as > legacy cli.actor in omnigraph.yaml (RFC-008 window) > operator.actor > none, and the corresponding tests in cli_cluster.rs (line 730, 783) explicitly assert that a legacy cli.actor outranks operator.actor during the deprecation window. The expanded docs here show only two steps (--as → operator.actor), silently dropping the middle entry. A user with cli.actor set in omnigraph.yaml will see that actor appear in their audit trail with no documentation explaining where it came from.

[greptile-apps]

D₂ error message quote is truncated vs. runtime

The original queries/index.md quoted the full error: "…split into separate mutations: (1) inserts and updates, then (2) deletes. This restriction lifts when Lance exposes a two-phase delete API (tracked: MR-793 / Lance-upstream)." The runtime still emits this longer form. A user who encounters the actual error and searches the docs will find a shorter quote that doesn't match, making the docs harder to correlate with live output. This appears to be the "de-dev polish" deferred to Phase 3, but worth noting so the Phase 3 pass either updates the quoted text to match code or updates the code to emit the shorter form.

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 HTTP server link uses the file path as its visible label, which is inconsistent with the CLI entry directly above it (which uses the command name `omnigraph`). Rendered output will show operations/server.md as a clickable string, which reads awkwardly and gives no hint that it leads to the HTTP server reference.

Suggested change

	- The **CLI** ([`omnigraph`](../cli/index.md)) and the
	**HTTP server** ([`operations/server.md`](../operations/server.md)) are two front
	ends over the same engine, so embedded and remote behavior match.
	- The **CLI** ([`omnigraph`](../cli/index.md)) and the
	**HTTP server** ([server reference](../operations/server.md)) are two front
	ends over the same engine, so embedded and remote behavior match.

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!