docs: document global-first layered config, config view, and use

Add a Layered config section to cli-reference.md (precedence chain, OMNIGRAPH_HOME/
CONFIG/XDG resolution, ~/.omnigraph layout, merge semantics) and the config view /
use command rows; note global-first in cli.md; record the layered-config test surface
in testing.md; update the RFC-002 implementation-status banner (V1-remainder landed).

docs/dev/rfc-002-config-cli-architecture.md

@@ -14,9 +14,17 @@ alias proposed below; and `uri:` is honored-but-deprecation-warned (not auto-rew
 `storage.uri`). **Crate-location corrections** (the "Reconciliation"/"Implementation"
 sections below predate V0): the config schema now lives in the extracted `omnigraph-config`
 crate, and `QueryRegistry` was extracted to `omnigraph-queries` (not "kept in
-`omnigraph-server`"). Deferred: layered global-first config + merge/provenance + `config
-view`, the `cli:`→`defaults:` / `server:`→`serve:` renames (V1-remainder), route unification
-+ remote client (V2), and the auth model (V3).
+`omnigraph-server`").
+
+**Implementation status — V1-remainder landed.** Also shipped: the schema reshape
+(`cli:`→`defaults:`, `server:`→`serve:` with a `graphs:` list, removed `project:` and
+top-level `policy:`/`queries:` — legacy spellings honored-but-warned, rejected under
+`version: 1`); and the **global-first layered config** — global `~/.omnigraph/config.yaml`
+merged under the project file with per-field provenance, eager per-layer path resolution,
+`omnigraph config view [--resolved] [--show-origin]`, and `omnigraph use` (active-context
+State layer). The server stays single-layer (deployment manifest). **Divergence:**
+`serve.graphs` ships in its final list shape but rejects >1 entry until route unification.
+Still deferred: route unification + remote client (V2) and the auth model (V3).
 
 ## Summary
 

docs/dev/testing.md

@@ -47,7 +47,14 @@ tests are inline in `omnigraph-config` (`src/lib.rs` test module); the
 `GraphLocator` discriminant +
 graph-identity tests are inline in `omnigraph-cli` (`src/main.rs`) plus
 `tests/cli.rs` / `tests/system_local.rs`; the server embedded-only rejection tests
-are in `omnigraph-server/tests/server.rs` (`multi_graph_startup`).
+are in `omnigraph-server/tests/server.rs` (`multi_graph_startup`). The **global-first
+layered config** (RFC-002 §4) — global-dir precedence, eager per-layer path
+resolution, the merge engine + provenance (`src/merge.rs`), `load_layered_config_in`,
+state-layer precedence, and error/warning layer-attribution — is inline in
+`omnigraph-config`; `config view` / `omnigraph use` end-to-end tests are in
+`omnigraph-cli/tests/cli.rs`. CLI tests pin `OMNIGRAPH_HOME` to an empty temp dir
+(`tests/support/mod.rs`) so spawned binaries never read the developer's real global
+config.
 
 ## Fixtures
 

docs/user/cli-reference.md

@@ -25,6 +25,8 @@ A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` sc
 | `cleanup --keep N --older-than 7d --confirm` | destructive version GC |
 | `embed` | offline JSONL embedding pipeline |
 | `policy validate \| test \| explain` | Cedar tooling. Selects `defaults.graph`, else `serve.graphs`, else top-level `policy.file` |
+| `config view [--resolved] [--show-origin] [--json] [<graph>]` | print the merged config; `--show-origin` labels each field with its source layer; `--resolved <graph>` prints the typed locator (embedded/remote) |
+| `use <graph>` | set the active graph (writes `~/.omnigraph/state/active.yaml`); a bare command then targets it |
 | `version` / `-v` | print `omnigraph 0.3.x` |
 
 ## `omnigraph.yaml` schema
@@ -93,6 +95,33 @@ aliases:
 | `project:` | removed (no consumer) |
 | `uri:` | `storage:` (embedded) / `server:` (remote) |
 
+## Layered config (global-first)
+
+The CLI reads up to three config layers and merges them, so it works from any
+directory with no project file (the `kubectl`/`gh` posture). Precedence, low → high:
+
+**built-in defaults < global < active-context state < project < env vars < CLI flags**
+
+| Layer | Path | Notes |
+|---|---|---|
+| Global | `~/.omnigraph/config.yaml` | the primary, self-sufficient default; secret-free, machine-local |
+| State | `~/.omnigraph/state/active.yaml` | written by `omnigraph use`; sets the active graph |
+| Project | `./omnigraph.yaml` (or `--config`) | optional repo-scoped override + deployment manifest |
+
+**Global dir resolution:** `OMNIGRAPH_CONFIG` (explicit file) > `OMNIGRAPH_HOME` (dir) >
+`$XDG_CONFIG_HOME/omnigraph` (if set) > `~/.omnigraph`. The global file is
+`<dir>/config.yaml`.
+
+**Merge semantics:** settings-objects (`defaults`, `serve`) deep-merge per field; the
+named-resource maps (`servers`, `graphs`, `aliases`) union by key, with a higher
+layer's entry replacing the lower *wholesale*; lists and scalars replace. Relative
+paths (`policy.file`, `queries.<>.file`, `storage`, `query.roots`) resolve against the
+directory of the layer that defined them.
+
+`omnigraph config view --show-origin` prints which layer each value came from;
+`config view --resolved <graph>` prints the final embedded/remote locator. The server
+does **not** layer the global config — it reads only the project/`--config` manifest.
+
 ## Output formats (`query` command, alias: `read`)
 
 - `json` — pretty-printed object with metadata + rows

docs/user/cli.md

@@ -149,6 +149,16 @@ The config file can also define:
 When policy is enabled, `schema apply` is authorized through the
 `schema_apply` action and is typically limited to admins on protected `main`.
 
+### Global-first layering
+
+The CLI merges a user-global `~/.omnigraph/config.yaml` under the project
+`./omnigraph.yaml`, so it works from any directory with no project file. A graph,
+server, or default defined only in the global config is fully usable. Inspect the
+result with `omnigraph config view [--show-origin] [--resolved <graph>]`, and set the
+active default graph with `omnigraph use <graph>`. Precedence, env vars, and merge
+rules are in [cli-reference.md](cli-reference.md#layered-config-global-first). The
+server is unaffected — it reads only its project/`--config` deployment manifest.
+
 ## Deprecated names
 
 The CLI was renamed to align with the HTTP server's canonical endpoint