omnigraph/docs/dev/rfc-008-deprecate-omnigraph-yaml.md

# RFC: Deprecate `omnigraph.yaml` — One Concern per Config Surface

**Status:** Proposed
**Date:** 2026-06-11
**Builds on:** [rfc-007-operator-config.md](rfc-007-operator-config.md) (the
operator layer that absorbs the identity/credential keys),
[rfc-005-server-cluster-boot.md](rfc-005-server-cluster-boot.md) (Landed —
cluster-booted serving), RFC-006 storage roots (landed: #186/#190/#194).
**Supersedes in part:** RFC-007's "project layer" framing (§Relationship
below) and [rfc-002-config-cli-architecture.md](rfc-002-config-cli-architecture.md)'s
assumption that `omnigraph.yaml` remains the project manifest.
**Target release:** staged; final removal at the next major (see Sequencing).

## Summary

Retire `omnigraph.yaml`. It is three unrelated concerns wearing one
filename — server deployment config, project/CLI conveniences, and operator
identity — and the mixture is not a cosmetic wart but the root cause of a
recurring class of problems: operators keeping personal copies of "project"
files, repo checkouts able to carry credential-adjacent keys (the #139
security findings), `omnigraph init` scaffolding config into unrelated
directories, and every config discussion needing a paragraph to establish
which of the three files is meant.

The end state is **two config surfaces with single owners**:

| Surface | Owner | Declares |
|---|---|---|
| **Cluster config** (`cluster.yaml` + catalog) | the team, in a repo | what the system *is*: graphs, schemas, queries, policies, storage |
| **Operator config** (`~/.omnigraph/`) | one person, in `$HOME` | who *I* am: identity, credentials, known servers, ergonomics |

plus **flags/env** for the zero-config tier (one graph, one server, no
control plane) — which already works today with no file at all.

`omnigraph.yaml` has no role left once every key has a better home. This
RFC gives each key that home, and stages the retirement so that no working
setup breaks without a loud warning, a migration command, and a full
deprecation cycle first.

## Motivation

- **It breaks the ownership logic.** A config file must have one owner. A
  file that carries `graphs:` (team-owned, reviewable) next to `cli.actor`
  (one person's identity) and `auth.env_file` (credential loading) can be
  neither safely committed nor sensibly personal. Every real deployment
  this cycle tripped on it: per-operator copies in `~/exp/intel`,
  graph-scoped alias URIs that only make sense per-person, the #139
  findings where a checkout-supplied file could redirect tokens.
- **The cluster made it redundant.** Since RFC-005/006, a cluster
  deployment serves from the applied catalog — `--cluster` mode does not
  read `omnigraph.yaml` *at all*. Stored queries, policies, bindings, and
  graph addressing all have authoritative homes. What remains in
  `omnigraph.yaml` for cluster users is dead weight that can silently
  disagree with what is actually serving.
- **Two declarative dialects is one too many.** `cluster.yaml` and
  `omnigraph.yaml` both declare graphs/queries/policies with different
  schemas, different validation strictness, and different lifecycle
  guarantees. Maintaining, documenting, and testing both — and explaining
  when each applies — is a permanent tax (the "programming integrated over
  time" lens says: this forks on every config-surface change).

## Non-Goals

- **Breaking anyone now.** Every `omnigraph.yaml` that works today keeps
  working through the entire deprecation window, with warnings.
- **Retiring the zero-config tier.** `omnigraph-server s3://bucket/g.omni
  --bind …` plus env vars stays first-class forever — that tier needs *no*
  file, which is the point.
- **Forcing the control plane on single-graph users.** The migration target
  for a multi-graph yaml deployment is a *minimal* cluster (file-rooted,
  no bucket required, `cluster.yaml` barely longer than the `graphs:` map
  it replaces) — but a single graph never needs even that.
- **Touching `cluster.yaml`** — its schema and strictness are unchanged.

## Where every key goes (the complete migration map)

The full `OmnigraphConfig` surface (verified against
`crates/omnigraph-server/src/config.rs:182-207`):

| `omnigraph.yaml` key | Concern | New home |
|---|---|---|
| `graphs.<name>.uri` | what exists / where | `cluster.yaml` `graphs:` (storage-root-derived) — or a flag/env for the zero-config tier |
| `graphs.<name>.queries`, top-level `queries:` | what exists | cluster catalog (`.gq` discovery, RFC-004/#183) |
| `graphs.<name>.policy.file`, top-level `policy.file`, `server.policy.file` | what's enforced | `cluster.yaml` `policies:` + `applies_to` bindings |
| `server.bind` | deployment runtime | `--bind` / env (already authoritative; the key is a default) |
| `server.graph` | deployment runtime | `--target`-style flag / env in the zero-config tier; meaningless under cluster boot |
| `graphs.<name>.bearer_token_env`, `auth.env_file` | credentials | operator credentials chain (RFC-007 §D4) |
| `cli.actor` | identity | `operator.actor` (RFC-007 §D3) |
| `cli.output_format`, `cli.table_*` | personal ergonomics | `defaults:` in operator config (RFC-007 §D2) |
| `cli.graph`, `cli.branch` | personal targeting | operator config: named servers + a per-operator default target (RFC-007 PR 3) |
| `aliases.<name>` | a personal name conflated with a content pointer | **splits in two** (RFC-007 §D2 "bindings, not content"): the referenced `.gq` file's *content* becomes a catalog stored query (team-reviewed); the *binding* becomes an operator alias referencing that name. `config migrate` proposes both halves but cannot publish catalog content itself — that is a `cluster apply` |
| `query.roots` | discovery convenience | obsolete — cluster query discovery (#183) replaced it |
| `project.name` | label | dropped (the cluster's `metadata.name` is the deployment label) |

Two placements worth defending:

- **Aliases are operator config, not cluster config.** The stored query is
  the shared contract (catalog-owned, digest-pinned); an alias is one
  person's shorthand with their favorite default params and target. Putting
  aliases in the cluster would force team review on personal ergonomics;
  leaving them per-directory recreates today's problem. Per-operator,
  keyed by server/graph name, is the AWS-profile shape.
- **Multi-graph serving without a control plane migrates to a minimal
  cluster, not to a new file.** The honest cost: `cluster import` + `apply`
  once, on a `file://` root next to the graphs. The honest benefit: one
  declarative dialect, one validation path, one serving source — and the
  upgrade path to buckets/approvals is a one-line `storage:` change instead
  of a re-platform.

## Deprecation mechanics

Per Hyrum's Law (the repo's own deny-list: shipped observable behavior is
contract), retirement is staged, loud, and tooled:

1. **Warn** *(landed)*. Loading `omnigraph.yaml` emits a one-line deprecation notice
   naming the replacement for each key actually present in the file (not a
   generic banner — the migration map above, applied to *your* file).
   Suppressible per-process (`OMNIGRAPH_SUPPRESS_YAML_DEPRECATION=1`) for
   CI logs during the window.
2. **Migrate** *(landed)*. `omnigraph config migrate` reads an existing
   `omnigraph.yaml` and writes the split: the team half as a ready-to-review
   `cluster.yaml` (+ moves query/policy files into the checkout layout),
   the personal half merged into `~/.omnigraph/config.yaml` — printing a
   diff-style summary and touching nothing without `--write`. The command
   is the test of the migration map's completeness: any key it cannot
   place is a bug in this RFC.
3. **Stop scaffolding** *(landed)*. `omnigraph init` stops generating
   `omnigraph.yaml` (it scaffolded one into cwd — the source of the
   test-pollution bug). **No replacement scaffold**: a minimal
   `cluster.yaml` is five lines; a generator would be a second copy of the
   schema to keep in sync, producing a file that is unusable until
   hand-edited anyway (Terraform has no config scaffolder either). New
   users copy from the cluster quick-start; migrants get a ready-to-review
   `cluster.yaml` from `config migrate`.
4. **Opt-in strict** *(landed — the release gap to stages 1–3 collapsed: no version boundary was crossed between them, so all four ship in the same release)*. `OMNIGRAPH_NO_LEGACY_CONFIG=1` turns the warning into
   an error — for teams that finished migrating and want regressions caught.
5. **Remove at the next major** *(eased by [rfc-009-unify-access-paths.md](rfc-009-unify-access-paths.md) Phases 4–5: declared plane capabilities and route alignment shrink the yaml-boot removal diff)*. Loading the file becomes an error pointing
   at `config migrate`. The `OmnigraphConfig` code path, the dual
   query-registry loaders, and the yaml-mode server boot source are deleted
   — the payoff that makes the whole exercise worth it.

Stages 1–3 can land in one release once RFC-007 PRs 1–2 exist (the operator
layer must exist before anything can migrate *to* it). Stage 4 the release
after. Stage 5 at the major, with the removal listed in release notes from
stage 1 onward.

## What this deletes, eventually

- The `OmnigraphConfig` struct and its 12-key surface, the
  `load_config`/`load_cli_config` pair and its env-side-effect, the
  scaffolder, and the legacy resolution paths (`resolve_cli_graph`'s dual
  modes — finding #11's root cause).
- The yaml-mode multi-graph server boot (`ServerConfigMode::Multi` keeps
  existing — cluster boot constructs it — but its `omnigraph.yaml` source
  goes).
- An entire class of documentation ("which file does X go in?") and the
  #139 security surface (a checkout cannot hijack what no longer loads).

## Relationship to RFC-007 and RFC-002

RFC-007 ships the operator layer this RFC migrates *to*; its "project
layer" language should be read as transitional — after this RFC, the
project layer **is** the cluster checkout, and RFC-007's PR 3 (project
`server:` references) applies to `cluster.yaml`-adjacent operator targeting
rather than to `omnigraph.yaml`. RFC-002's locator/state-layer work, if
resumed, targets the two-surface world directly. RFC-002's file-naming
decisions (`~/.omnigraph/` as the one dir) are unaffected.

## Open questions

- **Window length**: one minor release between warn (stage 1) and strict
  (stage 4), or two? Cookbooks, skills, and the deployment docs all need
  the same pass; the migration command makes a short window defensible.
- **`omnigraph login` vs `config migrate` ordering** — both write
  `~/.omnigraph/`; whichever lands first establishes the file-locking and
  atomic-write helpers the other reuses.
- **Does the MCP server config** (RFC-003) reference `omnigraph.yaml`
  anywhere that needs the same treatment? To be audited in stage 1.