mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-15 01:55:13 +02:00

Andrew Altshuler 612741b387

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

Content build-out on top of the Phase 1 topic move. No behavior changes.

Splits (existing content relocated, cross-linked):
- queries/index.md → mutations/index.md (insert/update/delete + the
  inserts-vs-deletes rule) and search/index.md (the multi-modal search
  functions + a hybrid-ranking overview tying nearest/bm25/rrf together).
  queries/index.md now covers 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
  error.rs MergeConflictKind).

New pages (written from the code, user-facing):
- quickstart.md — init → load → query → branch, with verified CLI flags.
- concepts/index.md — what OmniGraph is + the L1/L2 (Lance/OmniGraph) framing.

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

Index wiring: docs/user/index.md and AGENTS.md's topic table link every new
page; also normalized AGENTS.md's docs/user link display text to match the
Phase 1 retargeted paths.

Verified: zero broken .md links; 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 (the
config schema is already coherent in cli/reference.md).

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-14 13:53:46 +03:00

3.2 KiB

Raw Blame History

User Docs

Audience: users, CLI users, HTTP clients, and self-hosting operators

This is the public-facing entry point. These docs describe behavior, commands, configuration, and operational contracts without requiring knowledge of internal recovery mechanics or contributor-only invariants. They are organized by topic — start with install, then follow the section that matches your task.

Start here

Goal	Read
Install OmniGraph	install.md
Run the core loop end to end	quickstart.md
Understand the model	concepts/index.md
Run the CLI	cli/index.md
Look up every CLI flag and config field	cli/reference.md

Schema & queries

Goal	Read
Write schemas (the `.pg` language)	schema/index.md
Read schema-lint diagnostic codes	schema/lint.md
Write queries (the `.gq` language)	queries/index.md
Write data — inserts, updates, deletes	mutations/index.md
Use vector / full-text / hybrid search	search/index.md
Generate embeddings	search/embeddings.md
Build and use indexes	search/indexes.md

Branching & version control

Goal	Read
Work with branches and commits	branching/index.md
Read past versions (time travel)	branching/time-travel.md
Merge branches and resolve conflicts	branching/merge.md
Coordinate multi-query workflows	branching/transactions.md
Read diffs and change feeds	branching/changes.md

Operations

Goal	Read
Deploy the binary or container	deployment.md
Use HTTP endpoints	operations/server.md
Compact, repair, and clean old versions	operations/maintenance.md
Configure Cedar authorization	operations/policy.md
Track actors and audit behavior	operations/audit.md
Interpret errors and output formats	operations/errors.md

Clusters

Goal	Read
Deploy and operate a cluster (how-to)	clusters/index.md
Reference every `cluster.yaml` key and command	clusters/config.md

Concepts & reference

Goal	Read
Understand the model and L1/L2 framing	concepts/index.md
Understand graph layout and URI support	concepts/storage.md
Look up constants and tunables	reference/constants.md

Releases

Release notes live in releases/. Use them for user-visible changes between versions, not for contributor design history.

Boundary

User docs focus on stable behavior. If a paragraph needs to explain internal sidecars, Lance API blockers, or test strategy, it probably belongs in docs/dev/index.md or a developer-area document instead.

3.2 KiB Raw Blame History