mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-12 01:45:14 +02:00

aaltshuler 97eb65e921 docs(cluster): operator how-to guide for deploying and managing clusters

New docs/user/cluster.md — the practical companion to cluster-config.md's
reference: zero-to-served walkthrough (validate/import/plan/apply, derived
roots, data loading, --cluster serving), the day-2 edit->plan->apply->restart
loop with a per-change-kind table, drift observation and convergence, the
approval gate for destructive changes, crash/lock/lost-ledger recovery, the
boot-refusal table with remedies, deployment patterns (replicas, backup
unit, CI gating), and the explicit not-yet list (hot reload, S3-hosted
cluster dirs, per-query exposure, pipelines). Linked from the user index,
the agent guide's topic map, and cross-linked from the reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-06-10 22:10:19 +03:00

2.1 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 should describe behavior, commands, configuration, and operational contracts without requiring knowledge of MRs, internal recovery mechanics, or contributor-only invariants.

Start Here

Goal	Read
Install OmniGraph	install.md
Run the CLI locally	cli.md
Look up every CLI flag and config field	cli-reference.md
Deploy and operate a cluster (how-to guide)	cluster.md
Validate and plan cluster config	cluster-config.md
Write schemas	schema-language.md
Read schema-lint diagnostic codes	schema-lint.md
Write queries and mutations	query-language.md
Use embeddings	embeddings.md

Operate A Graph

Goal	Read
Understand graph layout and URI support	storage.md
Work with branches, commits, and snapshots	branches-commits.md
Coordinate multi-query workflows	transactions.md
Read diffs and change feeds	changes.md
Build and use indexes	indexes.md
Compact and clean old versions	maintenance.md
Interpret errors and output formats	errors.md

Run The Server

Goal	Read
Deploy the binary or container	deployment.md
Use HTTP endpoints	server.md
Configure Cedar authorization	policy.md
Track actors and audit behavior	audit.md

Releases

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

Boundary

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

2.1 KiB Raw Blame History