From 3adbc65af2c0ae8028fa3e20048d9015d1fd89a5 Mon Sep 17 00:00:00 2001 From: aaltshuler Date: Thu, 11 Jun 2026 23:37:12 +0300 Subject: [PATCH] docs(cli): config migrate, cluster init, the legacy-file deprecation notice Co-Authored-By: Claude Fable 5 --- docs/dev/rfc-008-deprecate-omnigraph-yaml.md | 6 +++--- docs/user/cli-reference.md | 10 +++++++++- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/dev/rfc-008-deprecate-omnigraph-yaml.md b/docs/dev/rfc-008-deprecate-omnigraph-yaml.md index d496df8..e9c37a9 100644 --- a/docs/dev/rfc-008-deprecate-omnigraph-yaml.md +++ b/docs/dev/rfc-008-deprecate-omnigraph-yaml.md @@ -112,19 +112,19 @@ Two placements worth defending: Per Hyrum's Law (the repo's own deny-list: shipped observable behavior is contract), retirement is staged, loud, and tooled: -1. **Warn.** Loading `omnigraph.yaml` emits a one-line deprecation notice +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.** `omnigraph config migrate` reads an existing +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.** `omnigraph init` stops generating +3. **Stop scaffolding** *(landed)*. `omnigraph init` stops generating `omnigraph.yaml` (it currently scaffolds one into cwd — the source of the test-pollution bug). `omnigraph cluster init` (new, small) scaffolds a minimal `cluster.yaml` instead. diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md index b113ef3..e787ca2 100644 --- a/docs/user/cli-reference.md +++ b/docs/user/cli-reference.md @@ -8,7 +8,7 @@ Top-level command families and subcommands. Graph-targeting commands accept a po | Command | Purpose | |---|---| -| `init` | `--schema ` → initialize a graph (also scaffolds `omnigraph.yaml` if missing) | +| `init` | `--schema ` → initialize a graph (no longer scaffolds `omnigraph.yaml` — RFC-008; use `cluster init` for a config scaffold) | | `load` | bulk load a branch, local or remote (`--mode overwrite\|append\|merge` is **required** — overwrite is destructive, so there is no default). Without `--from` the target branch must exist; `--from ` forks a missing `--branch` from `` first | | `ingest` | deprecated alias of `load --from ` (defaults: `--from main --mode merge`); prints a one-line warning to stderr | | `query` (alias: `read`) | run named read query; source via `--query `, `-e`/`--query-string `, or `--alias ` (exactly one). `read` is the deprecated previous name and prints a one-line warning to stderr | @@ -19,6 +19,8 @@ Top-level command families and subcommands. Graph-targeting commands accept a po | `commit list \| show` | inspect commit graph | | `schema plan \| apply \| show (alias: get)` | migrations | | `lint` (alias: `check`) | offline / graph-backed query validation. Replaces `query lint` / `query check`, which are kept as deprecated argv-level shims that print a one-line warning and rewrite to `omnigraph lint` | +| `cluster init` | scaffold a minimal `cluster.yaml` (`--name`, `--storage`); refuses to overwrite | +| `config migrate` | propose (or `--write`: apply) the RFC-008 split of a legacy `omnigraph.yaml` — team half → ready-to-review `cluster.yaml`, personal half → `~/.omnigraph/config.yaml` (key-level merge, existing entries win), plus dropped-key reasons and manual steps | | `cluster validate \| plan \| apply \| approve \| status \| refresh \| import \| force-unlock` | declarative cluster control plane. `validate` checks a local `cluster.yaml` folder and referenced schema/query/policy files; `plan` diffs it against local JSON state at `__cluster/state.json`, annotates dispositions, and embeds real schema-migration previews; `apply` converges the cluster — stored-query/policy catalog writes (content-addressed under `__cluster/resources/`), graph creates, schema updates (soft drops only; `--as` records the actor), and graph deletes behind a digest-bound approval from `cluster approve --as ` (`apply`/`approve` default the actor from the per-operator `omnigraph.yaml`'s `cli.actor` when `--as` is omitted; nothing else in that file affects cluster commands); what apply converges is what an `omnigraph-server --cluster ` deployment serves on its next restart (omnigraph.yaml deployments are unaffected); `status` reads the state ledger; `refresh`/`import` explicitly update local JSON state from read-only graph observations; `force-unlock ` manually removes a held local state lock by exact id | | `optimize` | non-destructive Lance compaction (skips tables with `Blob` columns or uncovered drift; `--json` reports `skipped`) | | `repair [--confirm] [--force]` | preview or explicitly publish uncovered manifest/head drift. `--confirm` heals verified maintenance drift and exits non-zero if suspicious/unverifiable drift is refused; `--force --confirm` publishes suspicious/unverifiable drift after operator review | @@ -104,6 +106,12 @@ operator server use the legacy chain alone. ## `omnigraph.yaml` schema (legacy combined file) +> **Deprecated (RFC-008).** Loading this file prints a per-key notice +> naming each present key's new home (suppress in CI with +> `OMNIGRAPH_SUPPRESS_YAML_DEPRECATION=1`); `omnigraph config migrate` +> produces the split. The file keeps working through the deprecation +> window. + ```yaml project: { name } graphs: