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>

docs/user/schema/index.md

@@ -0,0 +1,88 @@
+# Schema Language (`.pg`)
+
+Pest grammar at `crates/omnigraph-compiler/src/schema/schema.pest`. AST at `schema/ast.rs`. Catalog at `catalog/mod.rs`.
+
+## Top-level declarations
+
+- `interface <Name> { property* }` — reusable property contracts.
+- `node <Name> [implements <Iface>, ...] { property* | constraint* }`
+- `edge <Name>: <FromType> -> <ToType> [@card(min..max)] { property* | constraint* }`
+- Comments: line `//` and block `/* … */`.
+
+## Property declarations
+
+`<ident>: <TypeRef> [annotation*]`
+
+## Built-in scalar types
+
+| Scalar | Arrow type |
+|---|---|
+| `String` | Utf8 |
+| `Blob` | LargeBinary |
+| `Bool` | Boolean |
+| `I32` / `I64` | Int32 / Int64 |
+| `U32` / `U64` | UInt32 / UInt64 |
+| `F32` / `F64` | Float32 / Float64 |
+| `Date` | Date32 |
+| `DateTime` | Date64 |
+| `Vector(<dim>)` | FixedSizeList(Float32, dim), `1 ≤ dim ≤ i32::MAX` |
+| `[<scalar>]` | List(scalar) |
+| `enum(v1, v2, …)` | Utf8 with sorted/dedup'd set of allowed string values |
+| `<scalar>?` | Same as scalar but `nullable: true` |
+
+## Constraints (body level)
+
+| Constraint | On | Effect |
+|---|---|---|
+| `@key(p, …)` | node | Primary key; implies index on key columns; `key_property()` returns the first key |
+| `@unique(p, …)` | node, edge | Uniqueness across listed columns |
+| `@index(p, …)` | node, edge | Build a scalar (BTREE) index on the columns |
+| `@range(p, min..max)` | node | Numeric range validation (open ranges allowed) |
+| `@check(p, "regex")` | node | Regex pattern validation |
+| `@card(min..max?)` | edge | Edge multiplicity — default `0..*`; `0..1`, `1..1`, `1..*`, etc. |
+
+Edge bodies only allow `@unique` and `@index`.
+
+## Annotations
+
+- `@<ident>` or `@<ident>(<literal>)` on any declaration or property.
+- Known annotations:
+  - `@embed` on a Vector property — names the *source* property whose text gets embedded into this vector at ingest (`embed_sources` map in NodeType).
+  - `@description("…")`, `@instruction("…")` on query declarations (carried through to clients).
+- Custom annotations are accepted by the parser and surfaced in catalog metadata; unrecognized annotations don't fail compilation.
+
+## Catalog construction
+
+- Pass 0: collect interfaces.
+- Pass 1: collect nodes, expand `implements`, build constraint and `@embed` mappings, build the Arrow schema for each node table (`id: Utf8` plus all properties; blob columns get `LargeBinary`).
+- Pass 2: collect edges, validate that `from_type` / `to_type` exist, normalize edge names case-insensitively for lookup, validate constraints for edges. Edge Arrow schema: `id: Utf8, src: Utf8, dst: Utf8` plus edge properties.
+
+## Schema IR & stable type IDs
+
+- `SCHEMA_IR_VERSION = 1` (`catalog/schema_ir.rs`).
+- Each interface/node/edge currently gets a `stable_type_id` from a kind+name hash.
+- Rename-preserving accepted IDs are an architectural invariant, but the current hash-on-name implementation is a known gap until migration carries IDs across `@rename_from`.
+- Serialized as JSON for diff/migration plans.
+
+## Schema migration planning
+
+`plan_schema_migration(accepted, desired) -> SchemaMigrationPlan { supported, steps[] }` with step types:
+
+- `AddType { type_kind, name }`
+- `RenameType { type_kind, from, to }`
+- `AddProperty { type_kind, type_name, property_name, property_type }`
+- `RenameProperty { type_kind, type_name, from, to }`
+- `AddConstraint { type_kind, type_name, constraint }`
+- `UpdateTypeMetadata { … annotations }`
+- `UpdatePropertyMetadata { … annotations }`
+- `UnsupportedChange { entity, reason }` (forces `supported=false`)
+
+`apply_schema()` returns `SchemaApplyResult { supported, applied, manifest_version, steps }` and is gated by an internal `__schema_apply_lock__` system branch so concurrent schema applies serialize.
+
+## Destructive drops — `--allow-data-loss`
+
+`DropProperty` and `DropType` steps default to `Soft` mode: the catalog tombstones the entry but the prior column / dataset remains time-travel-reachable via `snapshot_at_version(prev)` until `omnigraph cleanup` runs. Soft drops are reversible.
+
+Pass `--allow-data-loss` (CLI) or `allow_data_loss: true` (HTTP `POST /schema/apply` body, SDK `SchemaApplyOptions`) to promote every drop in the plan to `Hard` mode. Hard drops run `cleanup_old_versions` on the affected dataset immediately after the manifest publish, making the prior column / dataset unreachable. **Irreversible.**
+
+The flag is honored uniformly across transports — `omnigraph schema apply --allow-data-loss`, `POST /schema/apply { schema_source, allow_data_loss: true }`, and `apply_schema_with_options(.., SchemaApplyOptions { allow_data_loss: true })` produce identical plans and identical effects.

docs/user/schema/lint.md

@@ -0,0 +1,61 @@
+# Schema lint
+
+The migration planner emits **code-tagged diagnostics** for every schema change it rejects. Codes have the form `OG-XXX-NNN` and identify the rule (not the message); operators reference them in suppression directives, severity overrides, and CI reports.
+
+This page is the catalog of codes shipped today. The chassis behind it is tracked in [MR-694](https://linear.app/modernrelay/issue/MR-694).
+
+## What's shipped in v0
+
+- Stable code attached to every rejection the planner emits (today: 5 of 17 paths — the rest carry `code: None` and are tagged as future work).
+- Code appears in the user-visible error message: `[OG-DS-104] removing property 'Person.age' is not supported …`.
+- CLI `omnigraph schema plan` shows the code on `unsupported change …` lines.
+- Tests in `tests/schema_apply.rs` assert on codes, not on free-text prose.
+
+## What's not shipped yet
+
+- Severity configuration in `omnigraph.yaml` (planned: `lint: { OG-DS-103: error }`).
+- `@allow(OG-XXX-NNN, "rationale")` suppression directives.
+- Pre-migration checks (the `migration_check { … }` block — MR-941).
+- The CD / VE / LK / NM families (MR-942..945).
+- CI integration (MR-946).
+- Cost-class annotations (MR-944).
+
+See the parent chassis issue (MR-694) for the design and the per-family sub-issues for what's planned.
+
+## Code catalog (v0)
+
+The chassis defines ten families. Today only DS and MF have emitted codes. The remaining families are reserved for future PRs.
+
+| Code | Family | Tier | Default severity | Meaning |
+|---|---|---|---|---|
+| `OG-DS-101` | Destructive | destructive | error | drop graph type with rows (reserved; not yet emitted) |
+| `OG-DS-102` | Destructive | destructive | error | drop node type with rows |
+| `OG-DS-103` | Destructive | destructive | error | drop edge type with rows |
+| `OG-DS-104` | Destructive | destructive | error | drop property with rows |
+| `OG-DS-105` | Destructive | destructive | error | drop populated vector column (reserved) |
+| `OG-MF-103` | Maybe-fail | validated | error | add required property without `@default` to populated type |
+| `OG-MF-104` | Maybe-fail | validated | error | tighten nullable to non-nullable (reserved) |
+| `OG-MF-106` | Maybe-fail | destructive | error | narrowing scalar type |
+
+The full code catalog source of truth lives in `crates/omnigraph-compiler/src/lint/codes.rs`. CI-level invariants (uniqueness, format, family coverage) are unit-tested in the same module.
+
+## Families
+
+The ten chassis families:
+
+| Prefix | Family | Status |
+|---|---|---|
+| **DS** | Destructive (data-loss) | shipped, v0 |
+| **MF** | Maybe-fail / data-dependent | shipped, v0 |
+| **CD** | Constraint deletion (relaxation warning) | tracked in MR-942 |
+| **BC** | Backward-incompatible (rename) | implicit in `@rename_from`; codify later |
+| **NM** | Naming conventions | tracked in MR-945 |
+| **OW** | Ownership (per-resource Cedar) | tracked in MR-722 |
+| **NL** | Non-linear (branch-merge divergence) | stubbed in MR-947 |
+| **VE** | Vector / embedding | tracked in MR-943 |
+| **ED** | Edge / graph topology | tracked in MR-701, MR-943 |
+| **LK** | Lock duration / cost | tracked in MR-944 |
+
+## Prior art
+
+The chassis is modeled on [Atlas's `sqlcheck` analyzers](https://atlasgo.io/lint/analyzers) (DS / MF / CD / BC / NM families). Atlas was the direct inspiration for stable codes, per-rule severity, suppression directives with rationale, and pre-migration checks. omnigraph adapts the chassis to a typed-IR substrate (no SQL injection vector, no per-engine locking, native vector / edge / embedding types Atlas doesn't have).