fix: close validated init and multi-graph gaps

docs/user/cli.md

@@ -46,12 +46,15 @@ and configure the matching `bearer_token_env` in `omnigraph.yaml`.
 
 ## Multi-graph servers (v0.6.0+)
 
-Against a multi-graph server (started with `--config omnigraph.yaml` referencing a non-empty `graphs:` map), use `omnigraph graphs list` to enumerate the registered graphs:
+Against a multi-graph server (started with `--config omnigraph.yaml` referencing a non-empty `graphs:` map), use `omnigraph graphs list` to enumerate the registered graphs. The server must configure bearer tokens and `server.policy.file` with a rule that allows `graph_list`; `/graphs` is closed by default even when the server runs with `--unauthenticated`.
 
 ```bash
-omnigraph graphs list --uri http://server.example.com --json
+OMNIGRAPH_BEARER_TOKEN=admin-token \
+  omnigraph graphs list --uri http://server.example.com --json
 ```
 
+For config-driven clients, set the remote graph's `bearer_token_env` to an environment variable containing a token whose actor is authorized by `server.policy.file`.
+
 `list` rejects local URI targets — it's for remote multi-graph servers only.
 
 Runtime add/remove is **not** in v0.6.0. To add a graph, stop the server, add a `graphs.<id>` entry to `omnigraph.yaml`, then restart. To remove, stop the server, delete the entry, restart.

docs/user/deployment.md

@@ -109,7 +109,8 @@ docker run --rm -p 8080:8080 \
 
 ## Auth
 
-The server can run unauthenticated for local development, but any shared or
+The server can run unauthenticated for local development only when explicitly
+started with `--unauthenticated` or `OMNIGRAPH_UNAUTHENTICATED=1`. Any shared or
 internet-facing deployment should set a bearer token source.
 
 ### Token sources

docs/user/policy.md

@@ -46,7 +46,12 @@ graphs:
     # no per-graph policy → no engine-layer Cedar enforcement on beta
 ```
 
-Each graph's HTTP request flows through its own per-graph policy. The management endpoint (`GET /graphs`) flows through the server-level policy. When `server.policy.file` is unset and bearer tokens are configured, `GET /graphs` falls through to MR-723 default-deny (only `read`-equivalent actions allowed for authenticated actors — and `graph_list` is not `read`) → 403. So the operator must explicitly authorize via `server-policy.yaml` to expose `/graphs`.
+Top-level `policy.file` is single-graph / CLI-local policy only. Multi-graph
+server startup rejects it because applying one graph policy to every configured
+graph is ambiguous. Move per-graph rules to `graphs.<graph_id>.policy.file` and
+move `graph_list` rules to `server.policy.file`.
+
+Each graph's HTTP request flows through its own per-graph policy. The management endpoint (`GET /graphs`) flows through the server-level policy. When `server.policy.file` is unset, `GET /graphs` is denied in every runtime state, including `--unauthenticated`; with bearer tokens configured, it returns 403 after admission control because `graph_list` is not a `read`-equivalent action. The operator must explicitly authorize via `server-policy.yaml` to expose `/graphs`.
 
 Example server-level policy:
 
@@ -116,12 +121,13 @@ reaches `authorize_request()` without a matching policy permit.
 |---|---|---|---|
 | **Open** | no | no | Every request is permitted. Refuses to start unless `--unauthenticated` or `OMNIGRAPH_UNAUTHENTICATED=1` is set — the operator must explicitly opt in. |
 | **DefaultDeny** | yes | no | Every authenticated request for an action other than `read` is rejected with HTTP 403. Closes the "tokens but forgot the policy file" trap — an operator who sets up auth and forgot to point at a policy file used to ship the illusion of protection. |
-| **PolicyEnabled** | any | yes | Every request is evaluated by Cedar against the configured policy. |
+| **PolicyEnabled** | yes | yes | Every request is evaluated by Cedar against the configured policy. |
 
 The classifier is `classify_server_runtime_state` in
 `crates/omnigraph-server/src/lib.rs`; it returns `Err` for the "no
-tokens, no policy, no flag" cell so the server refuses to start instead
-of silently shipping an open instance. Tests pin every cell of the
+tokens, no policy, no flag" cell and for "policy file, no tokens" so the
+server refuses to start instead of silently shipping an open instance or
+a policy-protected server that can only 401. Tests pin every cell of the
 matrix and the State-2 deny path.
 
 Server-side, `authorize_request()` still runs at the HTTP boundary —

docs/user/server.md

@@ -117,7 +117,9 @@ endpoints (`/snapshot`, `/read`, `/export`, `/branches` GET, `/commits`,
   1. `OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET` — AWS Secrets Manager (build with `--features aws`)
   2. `OMNIGRAPH_SERVER_BEARER_TOKENS_FILE` or `OMNIGRAPH_SERVER_BEARER_TOKENS_JSON` — JSON `{actor_id: token, …}`
   3. `OMNIGRAPH_SERVER_BEARER_TOKEN` — single legacy token, actor `default`
-- If no tokens configured, server runs unauthenticated (local dev) and `/openapi.json` strips the security scheme.
+- If no tokens and no policy are configured, startup refuses unless
+  `--unauthenticated` or `OMNIGRAPH_UNAUTHENTICATED=1` explicitly opts into
+  open local-dev mode. In that mode `/openapi.json` strips the security scheme.
 
 See [deployment.md](deployment.md) for token-source operational details.
 
@@ -136,4 +138,4 @@ See [deployment.md](deployment.md) for token-source operational details.
   admission control" above). No global rate limiter is configured;
   add `tower_http::limit` if a graph-wide cap is needed.
 - Pagination — none (commits/branches return everything; export streams).
-- Multi-tenant routing — one graph per process.
+- Runtime graph add/remove — edit `omnigraph.yaml` and restart.