From 1a6371d015dae1f99beac4be5a3cda1c3e170306 Mon Sep 17 00:00:00 2001 From: Ragnor Comerford Date: Fri, 5 Jun 2026 11:54:23 +0200 Subject: [PATCH] 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 +++++++--- docs/dev/testing.md | 9 ++++++- docs/user/cli-reference.md | 29 +++++++++++++++++++++ docs/user/cli.md | 10 +++++++ 4 files changed, 58 insertions(+), 4 deletions(-) diff --git a/docs/dev/rfc-002-config-cli-architecture.md b/docs/dev/rfc-002-config-cli-architecture.md index 115b42f..9ba1bbe 100644 --- a/docs/dev/rfc-002-config-cli-architecture.md +++ b/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 diff --git a/docs/dev/testing.md b/docs/dev/testing.md index 200f384..febc455 100644 --- a/docs/dev/testing.md +++ b/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 diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md index d6eee90..05655ea 100644 --- a/docs/user/cli-reference.md +++ b/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] []` | print the merged config; `--show-origin` labels each field with its source layer; `--resolved ` prints the typed locator (embedded/remote) | +| `use ` | 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 +`/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 ` 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 diff --git a/docs/user/cli.md b/docs/user/cli.md index 7cc894d..ba6c9b8 100644 --- a/docs/user/cli.md +++ b/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 ]`, and set the +active default graph with `omnigraph use `. 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