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

Andrew Altshuler d46e50dd6d

docs(user): restructure user docs into topic sections (Phase 1) (#223 )

Move the 23 flat docs/user/*.md files into topic subdirectories so the
user guide is organized by area (schema, queries, search, branching, cli,
operations, clusters, concepts, reference) instead of a flat list. This is
a pure structural move — whole files relocated, every cross-doc link
recomputed, no prose rewrites or content splits (those follow in Phase 2).

- 19 `git mv`s (install.md, deployment.md stay top-level); history preserved
  (renames detected at 92–100% similarity).
- All intra-doc links, AGENTS.md's topic table (52 pointers), and the
  docs/dev + docs/releases back-links recomputed via relpath from each
  file's new location.
- docs/user/index.md rewritten as a sectioned nav hub.
- Fixed 5 doc-path references in Rust (comments + two user-facing server
  settings error strings) to point at the new locations.

Verified: zero broken .md links across tracked docs; check-agents-md.sh
green (with the untracked scratch docs set aside); touched crates build.

Note: the public site (omnigraph-web) imports docs/ via a flat-only script;
its import-docs.mjs needs a subdir-aware update before the next re-sync.

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

2026-06-14 13:52:14 +03:00

2.7 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 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 and mutations (the `.gq` language)	queries/index.md
Use vector / full-text / hybrid search	search/indexes.md
Generate embeddings	search/embeddings.md
Build and use indexes	search/indexes.md

Branching & version control

Goal	Read
Work with branches, commits, and snapshots	branching/index.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 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.

2.7 KiB Raw Blame History