docs: update api-guide to match the current API

docs/api-guide.md

@@ -15,6 +15,7 @@ The `WorkerPool` defines the pool of physical "warm" compute capacity. It manage
 | `sandboxClass` | `string` | Optional. The sandbox runtime family for the pool: `gvisor` (default) or `microvm`. Drives the worker pod shape (e.g. KVM device mounts, node placement) and which `SandboxConfig`s are eligible. |
 | `sandboxConfigName` | `string` | Optional. Name of a cluster-scoped [`SandboxConfig`](#3-sandboxconfig-sandbox-binaries) providing the sandbox binaries. If empty, the cluster default `SandboxConfig` for the pool's `sandboxClass` is used. |
 | `template` | `WorkerPoolPodTemplate` | **Optional.** Pod scheduling and resource settings for worker pods. |
+| `terminationGracePeriodSeconds` | `int32` | Optional. Termination grace period for the pool's worker pods, default `300`. On eviction `ateom` forwards `SIGTERM` to the actor so it can save state before the kubelet sends `SIGKILL`. Set it to the longest shutdown your actors need. |
 
 #### `WorkerPoolPodTemplate` (`spec.template`)
 
@@ -98,7 +99,8 @@ The `ActorTemplate` defines the code, environment, and state-management policies
 | `containers` | `[]Container` | **Required.** The workload definition — see [Container Fields](#container-fields) below. Each container may also declare an optional `readyz` HTTP probe — see [Container Readiness Probe](#container-readiness-probe-readyz). |
 | `sandboxClass` | `string` | Optional. The sandbox runtime family this template's actors require: `gvisor` (default) or `microvm`. Only `WorkerPool`s whose `sandboxClass` matches are eligible. |
 | `workerSelector` | `*LabelSelector` | Optional. Gates which `WorkerPool`s actors from this template may use, by matching against each pool's labels. If unset, all pools are eligible (subject to the actor's own `worker_selector`). |
-| `snapshotsConfig` | `SnapshotsConfig` | **Required.** GCS bucket and folder where memory snapshots are stored. |
+| `snapshotsConfig` | `SnapshotsConfig` | **Required.** Where snapshots are stored and what each one contains. See [Snapshots Config](#snapshots-config-snapshotsconfig). |
+| `volumes` | `[]Volume` | Optional. Named volumes containers may mount through `volumeMounts` (max 32). Each entry sets one source: `durableDir` for a directory on rootfs that persists across resumes, or `externalVolumeTemplate` for a per-actor external volume. |
 | `pauseImage` | `string` | **Required.** The image used for the sandbox root (e.g. `gcr.io/gke-release/pause`). |
 | `volumes` | `[]Volume` | Optional. Volumes the containers may mount, each either a `durableDir` or an `externalVolumeTemplate`. Every declared volume must be mounted by at least one container. A `microvm` template may declare several `durableDir` volumes; a `gvisor` template is limited to one, and `externalVolumeTemplate` is `gvisor`-only. |
 
@@ -118,6 +120,19 @@ Substrate bind-mounts a read-only, per-actor identity directory at **`/run/ate`*
 
 Read it fresh rather than caching it at process start. It is delivered as a per-actor bind mount, not an environment variable, precisely so it carries the correct name after a resume from the golden snapshot — an env var (or a file baked into the image) would be frozen at the *golden* actor's name, since it lives in the checkpointed process memory, and would therefore be identical for every actor of the template.
 
+### Snapshots Config (`snapshotsConfig`)
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `location` | `string` | **Required.** Object store URL where snapshots are written, e.g. `gs://my-bucket/snapshots/my-template/`. |
+| `onPause` | `SnapshotScope` | Optional. What a Pause captures (kept on the node). `Full` (default) or `Data`. |
+| `onCommit` | `SnapshotScope` | Optional. What a Suspend captures (uploaded to storage). `Full` (default) or `Data`, and must be a subset of `onPause`. |
+
+`Full` captures process memory, the rootfs delta, and any attached volumes that
+support snapshots. `Data` captures only those volumes, so the actor cold-boots
+from the image on the next resume with its `durableDir` contents restored. See
+the [glossary](glossary.md#snapshots) for the full definitions.
+
 ### Container Fields
 
 Each entry in `containers` describes one process to run in the actor's sandbox.
@@ -262,7 +277,14 @@ The Substrate Control Plane (`ate-api-server`) exposes a gRPC interface for mana
 Registers a new logical actor in the system.
 *   **Request:** `CreateActorRequest`
     *   `actor`: `Actor` — the actor to create. Its `metadata` carries the atespace and name (name must be a DNS-1123 label); `actor_template_namespace` and `actor_template_name` select the `ActorTemplate`.
-*   **Response:** `CreateActorResponse` containing the initialized `Actor` object.
+*   **Response:** the initialized `Actor`.
+
+#### `UpdateActor`
+Changes mutable fields on an existing actor.
+*   **Request:** `UpdateActorRequest`
+    *   `actor`: `ObjectRef` of the actor to update.
+    *   `worker_selector`: replaces the actor's placement constraint. It takes effect on the next `ResumeActor`, not immediately.
+*   **Response:** `UpdateActorResponse` containing the updated `Actor`.
 
 #### `ResumeActor`
 Activates a suspended actor by restoring it onto a physical worker.
@@ -277,22 +299,35 @@ Hibernate a running actor, capturing its current RAM and disk state into a snaps
     *   `actor`: `ObjectRef` of the actor to suspend.
 *   **Response:** `SuspendActorResponse` containing the `Actor` object in `STATUS_SUSPENDED`.
 
+#### `PauseActor`
+Checkpoint a running actor but keep its snapshots on the node VM, so the next resume can be prioritized back onto that node.
+*   **Request:** `PauseActorRequest`
+    *   `actor`: `ObjectRef` of the actor to pause.
+*   **Response:** `PauseActorResponse` containing the updated `Actor`.
+
 #### `DeleteActor`
 Removes an actor from the registry.
 *   **Constraints:** Only actors in `STATUS_SUSPENDED` can be deleted.
 *   **Request:** `DeleteActorRequest`
-*   **Response:** `DeleteActorResponse` (empty).
+*   **Response:** the deleted `Actor` as it was before removal.
 
 #### `GetActor` / `ListActors`
 Query the state of logical actors.
-*   **GetActor:** Retrieves a single actor by ID.
-*   **ListActors:** Lists all actors currently tracked in the database.
+*   **GetActor:** Retrieves a single actor by `ObjectRef`, which carries its atespace and name.
+*   **ListActors:** Lists actors in one atespace, or across all of them when `atespace` is empty. Paginated through `page_size` and `page_token`.
 
 #### `ListWorkers`
 Query the physical resource pool.
-*   **Request:** `ListWorkersRequest`
+*   **Request:** `ListWorkersRequest`, paginated through `page_size` and `page_token`.
 *   **Response:** `ListWorkersResponse` containing a list of `Worker` objects (Pods) and their current assignment status.
 
+#### Atespaces
+An **atespace** is the isolation boundary an actor belongs to. It must exist before any actor can be created in it.
+*   **`CreateAtespace`:** takes the `Atespace` to create, returns the created one. Atespaces are global-scoped, so the name must be unique across the cluster.
+*   **`GetAtespace`:** takes an `ObjectRef`, returns the `Atespace`.
+*   **`ListAtespaces`:** returns `ListAtespacesResponse`, paginated through `page_size` and `page_token`.
+*   **`DeleteAtespace`:** takes an `ObjectRef` and returns the deleted `Atespace`. It rejects with `FailedPrecondition` if any actors remain; there is no cascade delete.
+
 ---
 
 ## 7. Advanced: Actor Identity Credentials