Refresh skills and operator guides for 0.13

changelog.d/current-agent-guides.changed.md

@@ -0,0 +1 @@
+- Agent skills and deployment guides now describe the current 0.13 workflows, exact receipts and live configuration updates. Obsolete commands, historical workarounds and duplicated migration instructions have been removed.

docs/user/deployment.md

@@ -31,94 +31,56 @@ OMNIGRAPH_SERVER_BEARER_TOKENS_JSON='{"act-service":"secret"}' \
     --bind 0.0.0.0:8080
 ```
 
-Use `GET /healthz` for process health and `GET /readyz` for readiness:
-`/readyz` reports `loading` (startup is still pending), `serving`,
-`degraded` (some graphs unavailable), `blocked` (none ready), or `draining`.
-It includes the applied `config_digest` it booted from
-(`booted_serving_digest`), the ledger revision, and `served_graph_count`,
-`ready_graph_count`, `loading_graph_count` and `blocked_graph_count`.
-`served_graph_count` counts the whole registry. Graphs closed for a transition also
-contribute to `blocked_graph_count`. Readiness stays 503 while any graph is
-loading. Once startup finishes, it returns 200 when at least one graph is ready
-or the applied inventory is empty, and 503 when all graphs are unavailable or
-shutdown has begun. The listener opens after configuration and
-authorization validation, before graphs open. Healthy graphs become available
-as they finish loading, while readiness holds aggregate traffic until loading
-finishes. A nonempty cluster with no healthy graph exits with a
-startup error after its opening attempts finish. With `--require-all-graphs`,
-all graphs remain unavailable until every graph opens successfully; any failure
-stops the server. Wait for readiness before sending data requests: the printed
-listening address and `/healthz` confirm only that the listener is live.
-
-Readiness is unauthenticated and names no graph. Authorized `GET /graphs`
-returns one `graphs` list, including blocked entries, with each graph's `state`
-(`loading`, `ready`, `blocked`, `transitioning` or `stopping`), `read_available`, `write_available` and
-`action`. Availability describes the runtime, not the caller's permissions.
-Blocked entries include a sanitized `failure`: `invalid_configuration`,
-`invalid_policy`, `invalid_external_blob_policy`, `open_failed` or
-`invalid_stored_queries`. Details remain in server logs.
-`apply_correction_or_restart` means fix a query, policy or provider configuration
-through deployment, or restore damaged graph storage from a verified backup and
-restart. It does not authorize adopting a different graph identity.
-`wait_for_restart` describes shutdown.
-`wait_for_startup` means the graph's one startup attempt has not completed
-admission. It promises no retry time and does not trigger another open.
-`wait_for_transition` means that graph's admissions are closed while its owner
-finishes a transition. Wait for that owner, or restart if the transition was
-abandoned or expired; there is no promised retry time. Other ready graphs can
-continue serving and transitioning. Server-owned deployments activate schema and
-stored-query changes through this transition; a proved pre-effect refusal restores
-the unchanged views. See [live deployment](clusters/index.md#deploy-without-restarting).
-Ready entries use `none`. There is no separate `quarantined` list or automatic startup retry.
-
-`GET /cluster/deployments/{id}` separates the durable achieved result from its
-current `active` status. Active means this process has installed that exact
-deployment and all its graph bindings are ready. Loading, blocked graphs,
-partial convergence and shutdown keep it false. A normal restart verifies its
-own bindings before reporting the retained current deployment active; successful
-apply alone is not activation. Activation does not rewrite the durable receipt.
-
-Known loading, blocked or transitioning graphs return 503 (`graph_unavailable`) to callers authorized to
-read `main` or list the management inventory; other callers cannot use this response to discover
-them. Unknown graphs return 404. A 503 does not authorize replaying a write.
-Add `--require-all-graphs` when any blocked graph should fail startup.
-`omnigraph graphs list --server <name|url>` displays graph ID, state and URI;
-`--json` preserves the full inventory fields. Minimal discovery remains IDs/names only.
-
-An admitted write continues if its client disconnects. The server keeps its
-capacity reserved through the whole operation, including optional source deletion
-after a merge. A lost response can still leave the caller unsure whether the
-write committed; follow the [failure outcome](operations/troubleshooting.md#failed-data-write-commands)
-before submitting it again.
-
-Once its complete request body is accepted, a read also keeps its capacity
-reserved until execution finishes, even if the caller disconnects. MCP
-cancellation and its 30-second response deadline stop waiting for the result;
-an admitted read continues and retains its tool slot until execution finishes.
-
-Shutdown is bounded: at SIGTERM the server closes operation admission and stops
-accepting connections. It waits for entered graph opens, admitted writes, executing reads, read bodies
-and server stream producers for at most `--shutdown-grace-seconds` (else
-`OMNIGRAPH_SHUTDOWN_GRACE_SECONDS`, else 25), then exits 2 with the unfinished
-work logged. The deadline is kept by a thread, so a stalled request or a
-blocked runtime cannot extend it. Signal handling begins after configuration
-loading, before graph opening, and covers serving startup. Disconnected callers
-do not remove their executing work from this wait. A graph finishing startup
-after shutdown begins cannot become available. A panic or uncertain
-completion in startup or an admitted write closes admission
-for every graph in that process and starts the same shutdown path without renewing
-an existing deadline. After HTTP connections and the other known logical owners
-finish, the process exits 2 immediately; the watchdog remains the upper bound.
-Unresolved reservations stay charged until exit. This is process containment,
-not proof that native storage I/O settled or that the engine can be reused.
-A proven pre-effect failure, such as a failed initial schema read or a native-tag
-retirement refusal, releases its reservation and keeps admission open. Error
-status or a transient storage category alone does not establish that proof.
-A clean drain exits 0. Set the orchestrator's own
-termination grace longer than this value; a cutoff is crash-equivalent for the
-work it interrupts, and the next open recovers it as after any crash.
-For a v2 cluster, even a clean exit retains its cluster lock. Follow the
-[ownership-transfer procedure](#writer-topology) before starting the next owner.
+Use `GET /healthz` for process liveness and `GET /readyz` for readiness.
+The listener can accept health checks while graphs are still loading.
+
+| Readiness state | HTTP | Meaning |
+|---|---|---|
+| `loading` | 503 | At least one graph is still opening. |
+| `serving` | 200 | All graphs are ready, or the applied inventory is empty. |
+| `degraded` | 200 | Startup finished; some graphs are unavailable but others can serve. |
+| `blocked` | 503 | No graph is ready. A nonempty cluster whose startup opens all fail exits. |
+| `draining` | 503 | Shutdown has begun. |
+
+Readiness includes the booted configuration digest, ledger revision and
+ready/loading/blocked graph counts. It is unauthenticated and names no graphs.
+`--require-all-graphs` holds every graph unavailable until all open successfully
+and makes any opening failure fatal. There are no automatic startup retries.
+
+Authorized `GET /graphs` and `omnigraph graphs list --server URL --json` expose
+each graph's state, read/write availability, suggested action and sanitized
+failure category. Availability is independent of the caller's permissions.
+Loading or transitioning entries tell callers to wait for their existing owner;
+blocked entries require configuration correction or storage recovery. Details
+are in server logs. Minimal identity discovery returns IDs and names only.
+
+Known unavailable graphs return `503 graph_unavailable` only to callers allowed
+to discover their availability; unknown graphs return 404. Neither response
+authorizes replaying a write. Use exact deployment status to observe
+[activation](clusters/index.md#deploy-without-restarting): durable completion
+alone does not establish that the affected bindings are serving.
+
+An admitted write continues after client disconnect, including optional source
+removal after a merge. Executing reads also retain their capacity until execution
+finishes. A lost write response can leave the outcome unknown; follow
+[failure outcomes](operations/troubleshooting.md#failed-data-write-commands)
+before submitting again.
+
+On SIGTERM the server closes admission and drains entered graph opens, admitted
+operations and response producers. `--shutdown-grace-seconds` overrides
+`OMNIGRAPH_SHUTDOWN_GRACE_SECONDS`; the default is 25 seconds. A clean drain exits
+0. Unfinished work at the deadline is logged and the process exits 2. Set the
+orchestrator's termination grace longer than the server's.
+
+A panic or uncertain completion in startup or an admitted write closes admission
+for **every graph in that process**. Once the other known operations finish, the
+process exits 2; the grace deadline is the upper bound. A proven pre-effect
+refusal keeps admission open. The error's HTTP status or storage category alone
+does not prove whether effects started.
+
+Drain does not prove native storage I/O has settled. Even a clean exit retains
+the cluster lock. Follow [ownership transfer](#writer-topology) before starting
+the next owner.
 
 ## Admission limits
 
@@ -140,52 +102,32 @@ refuses the corresponding admission lane.
 | `OMNIGRAPH_READ_INGRESS_BYTES_MAX` | 67108864 (64 MiB) | Reserved/retained read/MCP body bytes |
 | `OMNIGRAPH_BODY_TIMEOUT_SECONDS` | 30 | Time allowed to collect one complete request body |
 
-The default ingress allowances total 320 MiB across the independent lanes;
-configure both byte limits when setting an instance's input budget.
-Body timeouts above 86400 seconds also warn and use the 30-second default.
-Ingress reserves the route's maximum before reading, then reduces the reservation
-to the actual body size. Body collection limits remain 1 MiB for ordinary JSON
-requests, 32 MiB for bulk load and 64 KiB for MCP. Cluster deployment POSTs
-allow 16 MiB plus 1 KiB for the request envelope; the captured bundle itself is
-limited to 16 MiB. MCP uses the read-body
-lane after authentication. Registered bulk routes alone
-receive the larger limit; a stored query named `load` or `ingest` keeps the
-ordinary JSON limit. Stored-query admission uses the registry's typed read/write
-kind. Disconnect does not release input or
-operation capacity already transferred to executing work. The body timeout ends
-at complete collection; it does not cancel admitted execution. These input limits
-do not bound total process RSS or all memory and I/O used by the engine. Size an
-instance for the graph, workload
-and configured concurrency as well as request bytes.
-
-The server allows 128 read-response observers and, independently, 64 write-response
-observers. Executing reads, pending results, bodies, yielded bytes and their server
-producers retain the slot until their final owner releases it. Bodyless reads
-consume only a read observer; slow
-reads cannot exhaust write-body or write-response capacity. Status routes bypass
-ordinary admission so they remain callable during saturation.
-
-Export and change-baseline responses reserve 256 KiB each from a fixed 2 MiB
-process allowance, permitting eight simultaneous reservations. Each response
-allows three outstanding 64 KiB chunks plus one pending producer chunk; at most
-two chunks wait in its queue. Yielded chunks, including retained clones and
-slices, keep their reservation until released. A new response waits at most
-250 ms for process capacity before HTTP 413. Once admitted, a producer waits
-for chunk capacity or disconnect without a per-chunk deadline; ordinary queue
-backpressure has no additional deadline. An interrupted baseline supplies no
-usable terminal cursor. Consumers must release each received server buffer to
-continue; an in-process consumer retaining every buffer can exhaust its lane.
-An HTTP client may still collect its received response: those client buffers are
-separate from the server's transport buffers. These limits cover transport
-payload buffers, not engine row/Arrow encoding, native work or total process RSS.
-
-The engine separately limits retained keyed batches, keyed parse estimates
-and removed-ID collections across each operation's tables; see
-[mutation limits](mutations/index.md#limits-and-conflicts). These fixed limits
-return HTTP 413 with structured `resource_limit` details before the operation's
-data fragments or publication, and leave the server available for smaller work.
-They do not undo an implicitly created load branch or earlier command effects,
-and do not establish a process memory ceiling or automatic retry safety.
+The independent write/read ingress allowances total 320 MiB by default.
+Collection reserves the route maximum, then reduces it to the actual body size.
+Body limits are 1 MiB for ordinary JSON, 32 MiB for registered bulk-load routes,
+64 KiB for MCP, and 16 MiB plus 1 KiB envelope for deployment submission.
+A stored query named `load` still uses the ordinary JSON limit. Body timeouts
+above 86400 seconds use the 30-second default.
+
+The collection deadline ends when the body is complete; it does not cancel
+execution. Disconnects do not release capacity held by executing work.
+Read/MCP bodies have a separate lane from writes. Independently, 128 read-response
+observers and 64 write-response observers retain capacity through execution and
+response delivery. Status routes remain available during saturation.
+
+Export and change-baseline responses share a fixed 2 MiB transport allowance:
+eight 256 KiB reservations, each holding at most three outstanding 64 KiB chunks
+and one pending producer chunk. New responses wait at most 250 ms for capacity
+before HTTP 413. Admitted streams use backpressure without a per-chunk deadline,
+so slow clients do not lose data merely by pausing. Interrupted baselines have
+no usable terminal cursor. In-process consumers must release yielded buffers
+to let producers continue.
+
+These are input and transport bounds, **not a total process memory ceiling**.
+Size instances for graph execution, native I/O and concurrency too. The engine's
+separate [mutation limits](mutations/index.md#limits-and-conflicts) return
+structured HTTP 413 refusals before data publication; they do not undo earlier
+commands or an implicitly created load branch, and do not establish retry safety.
 
 ## Container
 
@@ -229,7 +171,7 @@ Set `AWS_ALLOW_HTTP=true` only for a trusted local development endpoint. Do not
 put credentials in `cluster.yaml` or graph URIs.
 
 The same storage root must be visible to servers and out-of-band cluster or
-maintenance jobs. Submit schema/query changes and graph additions to the running
+maintenance jobs. Submit configuration changes to the running
 server with `cluster apply --server`; the root's applied revision remains the
 deployment artifact. Direct apply requires ownership transfer before serving.
 

docs/user/operations/policy.md

@@ -2,8 +2,9 @@
 
 OmniGraph uses Cedar policy bundles to authorize graph, server, and cluster
 configuration actions.
-Policies are declared in `cluster.yaml` and installed during cluster bootstrap
-or graph creation. Servers load them at startup or when activating a new graph.
+Declare policies in `cluster.yaml`. Apply them at bootstrap or update them on
+running graphs with `cluster apply --server URL --config DIR`. The server
+activates the new permissions after affected requests drain.
 
 ## Actions
 
@@ -14,7 +15,7 @@ Graph-scoped actions:
 | `read` | Queries, snapshots, branches, and commits |
 | `export` | Snapshot export |
 | `change` | Mutations and loads |
-| `schema_apply` | Schema changes |
+| `schema_apply` | Schema changes and graph deletion (also requires `read`) |
 | `branch_create` | Branch creation |
 | `branch_delete` | Branch deletion |
 | `branch_merge` | Branch merge |

docs/user/operations/server.md

@@ -207,6 +207,7 @@ keep their existing routes and do not expose MCP.
 | `GET /openapi.json` | Runtime copy of the OpenAPI document |
 | `GET /graphs` | Graph metadata catalog; requires `graph_list` policy |
 | `GET /graphs/discovery` | Graph IDs and display names only; requires an identity credential |
+| `POST /cluster/plan` | Preview configuration changes and schema migrations without applying them |
 | `POST /cluster/deployments` | Submit an exact-ID deployment: graph creation/deletion or schema, query, policy, provider and Blob-binding changes |
 | `GET /cluster/deployments`, `GET /cluster/deployments/{id}` | Authorized deployment status and current-process activation observation |
 | `GET /.well-known/oauth-protected-resource` | Public OIDC resource metadata; only when OIDC trust is configured |