diff --git a/docs/user/audit.md b/docs/user/audit.md
index 52cecde..845c2e0 100644
--- a/docs/user/audit.md
+++ b/docs/user/audit.md
@@ -3,5 +3,5 @@
 - `Omnigraph::audit_actor_id: Option<String>` is the actor in effect.
 - `_as` variants of every write API let callers override the actor: `mutate_as`, `load_as`, `branch_merge_as`, `apply_schema_as`, etc.
 - Actor IDs are persisted on `GraphCommit.actor_id` with split storage in `_graph_commit_actors.lance` (the commit graph is split into `_graph_commits.lance` for the linkage and `_graph_commit_actors.lance` for the actor map).
-- HTTP server uses the bearer-token actor automatically; CLI uses the local user / explicit env (no implicit actor).
+- HTTP server uses the bearer-token actor automatically. The CLI resolves one actor chain everywhere: `--as` > legacy `cli.actor` in `omnigraph.yaml` > `operator.actor` in `~/.omnigraph/config.yaml` > none (RFC-007).
 - Pre-v0.4.0 graphs also stored actor IDs on `RunRecord.actor_id` in `_graph_runs.lance` / `_graph_run_actors.lance`. The Run state machine was removed in MR-771; those files are inert post-v0.4.0. The v2→v3 manifest migration sweeps any stale `__run__*` branches on first write-open (MR-770); the inert dataset bytes remain until a `delete_prefix` primitive lands.
diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md
index 74d772f..1dbc1ff 100644
--- a/docs/user/cli-reference.md
+++ b/docs/user/cli-reference.md
@@ -27,7 +27,36 @@ Top-level command families and subcommands. Graph-targeting commands accept eith
 | `policy validate \| test \| explain` | Cedar tooling. Selects `cli.graph`, else `server.graph`, else top-level `policy.file` |
 | `version` / `-v` | print `omnigraph 0.3.x` |
 
-## `omnigraph.yaml` schema
+## Config surfaces
+
+Two config surfaces with single owners (RFC-007/RFC-008), plus a zero-config
+tier:
+
+| Surface | Owner | Location | Declares |
+|---|---|---|---|
+| Cluster config | the team, in a repo | `cluster.yaml` + checkout ([cluster-config.md](cluster-config.md)) | what the system **is**: graphs, schemas, queries, policies, storage |
+| Operator config | one person | `~/.omnigraph/config.yaml` (override dir with `$OMNIGRAPH_HOME`) | who **I** am: identity, ergonomics |
+| Flags / env | per invocation | — | everything, explicitly |
+
+`omnigraph.yaml` (below) is the legacy combined file — fully supported
+today, slated for staged deprecation (RFC-008); its keys' future homes are
+listed there.
+
+### `~/.omnigraph/config.yaml` (operator)
+
+```yaml
+operator:
+  actor: act-andrew     # default identity for every --as cascade:
+                        #   --as > legacy cli.actor > operator.actor > none
+defaults:
+  output: table         # read format default, below --json/--format/alias/legacy
+```
+
+Absent file = empty layer. Unknown keys warn and load (a file written for a
+newer CLI works on an older one). `$OMNIGRAPH_CONFIG=<path>` stands in for
+`--config` (the flag wins) in both the CLI and the server.
+
+## `omnigraph.yaml` schema (legacy combined file)
 
 ```yaml
 project: { name }