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

[aaltshuler]

What

Pure structural move of the 23 flat docs/user/*.md files into topic
subdirectories, so the user guide is organized by area instead of a flat
list. Whole files relocated, every cross-doc link recomputed — no prose
rewrites, no content splits (those are Phase 2).

docs/user/
  index.md  install.md  deployment.md
  schema/{index,lint}      queries/index          search/{indexes,embeddings}
  branching/{index,transactions,changes}          cli/{index,reference}
  operations/{server,maintenance,policy,audit,errors}
  clusters/{index,config}  concepts/storage       reference/constants

How

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

Verification

• Zero broken .md links across tracked docs (resolve-every-link sweep).
• scripts/check-agents-md.sh green (every canonical doc linked from an
  index; all index links resolve).
• Touched crates build clean.

Follow-ups (not in this PR)

• Phase 2: split queries/ → mutations + search overview, split
  time-travel out of branching/, add quickstart / concepts / merge / config
  pages, expand the audit stub.
• Website: the public site (omnigraph-web) imports docs/ via a
  flat-only import-docs.mjs; it needs a subdir-aware update before the next
  re-sync. The site stays on its last good sync until then.

🤖 Generated with Claude Code

Greptile Summary

This is a pure structural reorganization of the 23 flat docs/user/*.md files into topic subdirectories (branching/, cli/, clusters/, concepts/, operations/, queries/, reference/, schema/, search/), with all cross-document links recomputed and five stale doc-path references in Rust source updated. No prose content was changed.

• 19 file moves via git mv preserve history; install.md and deployment.md stay top-level; docs/user/index.md is rewritten as a sectioned navigation hub.
• Link sweep covers AGENTS.md (52 pointers updated with old paths as display text and new paths as hrefs), docs/dev/ back-links, and all intra-user-doc relative paths.
• Rust source updated: two user-facing error strings in settings.rs, one --as doc comment in cli.rs, one constant doc comment in query.rs, and one test module comment in ordering.rs.

Confidence Score: 4/5

Safe to merge after fixing the duplicate nav row in docs/user/index.md; all Rust changes are doc-comment strings only and the link sweep is thorough within the repo

The new nav hub has two rows in "Schema & queries" that both resolve to search/indexes.md under different goal descriptions — a copy-paste slip that leaves the index slightly misleading for the first readers of the restructured docs. Everything else looks correct; the CI link check and build passing confirm structural integrity within the repo.

docs/user/index.md — the duplicate "Build and use indexes" / "Use vector / full-text / hybrid search" rows both targeting search/indexes.md should be resolved before merge

Important Files Changed

Filename	Overview
docs/user/index.md	Rewritten as a sectioned nav hub; has a duplicate "Schema & queries" row — both "Use vector/full-text/hybrid search" and "Build and use indexes" link to the same search/indexes.md
AGENTS.md	All 52 href pointers in the topic table updated to new paths; display text intentionally preserves old names as agent-facing backward-compat aliases — CI link check validates hrefs only
crates/omnigraph-server/src/settings.rs	Two user-facing error strings updated from docs/user/server.md to docs/user/operations/server.md; no logic changes
crates/omnigraph-cli/src/cli.rs	Single doc comment path updated from docs/user/policy.md to docs/user/operations/policy.md; no logic changes
crates/omnigraph/src/exec/query.rs	Inline doc comment path updated from docs/user/constants.md to docs/user/reference/constants.md; no logic changes
docs/dev/architecture.md	Two hrefs updated: ../user/storage.md to ../user/concepts/storage.md and ../user/server.md to ../user/operations/server.md
docs/user/branching/transactions.md	Relative links recomputed for new branching/ subdir depth; all six hrefs point to correct sibling/ancestor paths
docs/user/operations/maintenance.md	Five relative links recomputed for new operations/ location; paths correctly use ../ and ../../ prefixes
docs/user/clusters/index.md	Renamed from cluster.md to clusters/index.md; four relative links updated to cross-directory paths; all resolve correctly
docs/dev/invariants.md	Eight hrefs updated to new subdirectory paths; no content changes

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    UI[docs/user/index.md\nnav hub] --> CLI[cli/\nindex - reference]
    UI --> SCH[schema/\nindex - lint]
    UI --> QRY[queries/\nindex]
    UI --> SRC[search/\nindexes - embeddings]
    UI --> BRN[branching/\nindex - transactions - changes]
    UI --> OPS[operations/\nserver - maintenance - policy - audit - errors]
    UI --> CLU[clusters/\nindex - config]
    UI --> CON[concepts/\nstorage]
    UI --> REF[reference/\nconstants]
    UI --> TOP[top-level\ninstall - deployment]
    AGENTS[AGENTS.md] -->|52 hrefs updated| UI
    DEV[docs/dev/**] -->|back-links updated| UI
    RUST[Rust src\nsettings - cli - query - ordering] -->|5 comment paths| UI

Loading

Comments Outside Diff (1)

1. docs/user/index.md, line 1-27 (link)

   Stale path references in related omnigraph-cookbooks repo

   The PR's link sweep covered the omnigraph repo, but two backtick prose references in the companion skills repo still point at the old flat paths. In skills/omnigraph-best-practices/references/cluster.md (lines 130–131), docs/user/cluster.md and docs/user/cluster-config.md should now be docs/user/clusters/index.md and docs/user/clusters/config.md. They are prose strings (not hyperlinks), so they won't fail a link checker, but any agent or developer reading those skills will try to navigate to paths that no longer exist.

   

_{Reviews (1): Last reviewed commit: "docs(user): restructure user docs into t..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[greptile-apps]

Duplicate nav row — both goals resolve to the same file

"Use vector / full-text / hybrid search" (line 25) and "Build and use indexes" (line 27) both link to search/indexes.md. The new hub now has two rows for the same destination under different goal descriptions, which will confuse readers who expect each row to lead somewhere distinct. One row should be removed, or the goals should be differentiated with different target files (e.g., a future search/overview.md once Phase 2 splits the content).

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!