diff --git a/AGENTS.md b/AGENTS.md
index f9023c9d1..57626aa7c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -58,7 +58,7 @@ The categories are [process settings](docs/configuration.md#process-settings), [
 
 ### Pre-release: no compatibility layers
 
-OpenAgentCore is pre-release. Replace superseded interfaces, execution paths and files outright. Keep no version fallback, compatibility shim or migration for superseded behavior unless an explicit upgrade contract requires it. Keep the pinned official public protocol, valid data and still-used, verified infrastructure. Do not rewrite working infrastructure only to rename it.
+OpenAgentCore is pre-release. Replace superseded interfaces, execution paths and files outright. Keep no version fallback, compatibility shim or migration for superseded behavior unless an explicit upgrade contract requires it. The [in-place upgrade](docs/getting-started/operations.md#upgrade) from v0.0.10 or later is that contract: persisted changes ship as forward migrations (goose for PostgreSQL, `oac init` for the data volume), and a landed migration is never edited. Protocols may change; the release notes list each change with the operator actions it requires. Keep the pinned official public protocol, valid data and still-used, verified infrastructure. Do not rewrite working infrastructure only to rename it.
 
 ## Documentation
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7973a5e9d..8e373e8d5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -37,7 +37,7 @@ This guide owns how to work in the repository: documentation ownership, the repo
 | Installer lifecycle, locking, generated state, managed HTTPS and downloads | [Deployment](deploy/README.md) and [Node installer](deploy/node/README.md) |
 | Operator installation and alternatives | [Installation](docs/getting-started/install.md), [installation options](docs/getting-started/install-options.md) |
 | Settings, defaults, files and installation layout | [Configuration](docs/configuration.md) |
-| Operator commands, keys, backup and version policy | [Operations](docs/getting-started/operations.md) |
+| Operator commands, keys, backup and upgrades | [Operations](docs/getting-started/operations.md) |
 | Web console request boundary and sign-in | [Console server](docs/web/console-server.md) |
 | Web page behavior and visual rules | [Web product](apps/web/PRODUCT.md), [Web design](apps/web/DESIGN.md) |
 | Application example behavior and local operation | [Application example](example/parsar/README.md) |
@@ -145,7 +145,7 @@ Native adapter changes require their build/check targets and live provider accep
 
 Provider bootstrap, Runtime images and Harness adapters must agree on these names.
 
-The [installation version policy](docs/getting-started/operations.md#installation-version-policy) owns release changes and preservation of installed data and resources.
+[Upgrade](docs/getting-started/operations.md#upgrade) owns release changes and preservation of installed data and resources.
 
 ## Branding
 
diff --git a/apps/web/src/features/sandbox/NodeRolloutStatus.tsx b/apps/web/src/features/sandbox/NodeRolloutStatus.tsx
index 8a12cf4a6..4e41978a8 100644
--- a/apps/web/src/features/sandbox/NodeRolloutStatus.tsx
+++ b/apps/web/src/features/sandbox/NodeRolloutStatus.tsx
@@ -14,6 +14,6 @@ export function NodeRolloutStatus({ node, stale = false }: { node: SandboxNode;
   return <span className="status-with-help">
     <StatusDot tone={tones[state]} label={t(labels[state])} />
     {state === "failed" && node.rollout.diagnostic ? <DiagnosticTip code={node.rollout.diagnostic} /> : null}
-    {state === "update_required" ? <HelpTip>{t("In-place upgrades from older project versions are not supported. Reinstall using the current version. Existing data is not removed automatically.")}</HelpTip> : null}
+    {state === "update_required" ? <HelpTip>{t("This node can't prepare new sandbox configurations and keeps serving the one it registered with. To move it to the current configuration, choose Remove node, then add the host again with Add node.")}</HelpTip> : null}
   </span>;
 }
diff --git a/apps/web/src/i18n/locales/zh-CN/sandbox.ts b/apps/web/src/i18n/locales/zh-CN/sandbox.ts
index a6c368a89..836699d15 100644
--- a/apps/web/src/i18n/locales/zh-CN/sandbox.ts
+++ b/apps/web/src/i18n/locales/zh-CN/sandbox.ts
@@ -59,7 +59,7 @@ export const sandbox = {
   "Review affected nodes for preparation errors, incompatible node software or an unconfirmed connection. Qualified earlier generations may still serve work.": "请检查相关节点的准备错误、不兼容的节点程序或尚未确认的连接。符合条件的旧代次仍可提供服务。",
   "Existing sandboxes keep their configuration generation. Saving does not move them or prove the target is ready.": "现有沙箱保留所属配置代次。保存不会迁移沙箱，也不代表目标配置已就绪。",
   "Changes keep this backend and existing Sessions and nodes. Core prepares the new target for future work; placement may continue on qualified earlier generations.": "修改会保留当前沙箱提供商、现有 Session 和节点。Core 为后续任务准备新目标配置，期间仍可能将任务分配到符合条件的旧代次。",
-  "In-place upgrades from older project versions are not supported. Reinstall using the current version. Existing data is not removed automatically.": "不支持旧项目版本原地升级，请使用当前版本重新安装。现有数据不会自动删除。",
+  "This node can't prepare new sandbox configurations and keeps serving the one it registered with. To move it to the current configuration, choose Remove node, then add the host again with Add node.": "该节点无法准备新的沙箱配置，会继续服务注册时的配置。要让它使用当前配置，请选择“移除节点”，再通过“添加节点”重新添加该主机。",
   "The saved serving generation is not proof that this node is online, ready or has free capacity.": "已保存的服务代次不代表节点当前在线、已就绪或有空闲容量。",
   "Node observations are from an earlier configuration generation. Refreshing does not change their owned sandboxes.": "节点观测来自较早的配置代次。刷新不会改变节点所属的沙箱。",
   "Leave blank to keep the saved key. Any key you enter is verified as a replacement, even if unchanged.": "留空可保留已保存的密钥。填写的密钥都会作为替换密钥进行验证，即使内容未变。",
diff --git a/contracts/agents-api/node-generation-protocol.md b/contracts/agents-api/node-generation-protocol.md
index 3b19e7fe6..4e37d8407 100644
--- a/contracts/agents-api/node-generation-protocol.md
+++ b/contracts/agents-api/node-generation-protocol.md
@@ -123,4 +123,4 @@ The readiness classes, one exported error and one code each, are authored in `se
 
 Preparation diagnostics keep fixed typed causes. Only artifact transfer, checksum or release-provenance failures report `runtime_download_failed`; the private preparer signals that class through its exit category, without Core or the node parsing stderr. Provider, ownership, cancellation and unclassified failures keep their typed code or `provider_unavailable`. No raw provider text crosses the protocol.
 
-The current wire version is 5. Create bootstrap and Resume requests may carry an optional workspace filesystem binding. The node validates its tenant and Environment against the allocation reference, its immutable ObjectID, and its attachment configuration ID against the supplied configuration before forwarding it. The filesystem resolver validates adapter-native ownership. A missing binding selects owned storage; a present binding cannot fall back. Error responses may retain a Resume target only when its nonempty native ID, name, generation and snapshot provenance match the requested target; this is cleanup evidence, never successful restore.
+Create bootstrap and Resume requests may carry an optional workspace filesystem binding. The node validates its tenant and Environment against the allocation reference, its immutable ObjectID, and its attachment configuration ID against the supplied configuration before forwarding it. The filesystem resolver validates adapter-native ownership. A missing binding selects owned storage; a present binding cannot fall back. Error responses may retain a Resume target only when its nonempty native ID, name, generation and snapshot provenance match the requested target; this is cleanup evidence, never successful restore.
diff --git a/contracts/agents-api/zh/node-generation-protocol.md b/contracts/agents-api/zh/node-generation-protocol.md
index 0b4e9c6bf..d60bc1d1d 100644
--- a/contracts/agents-api/zh/node-generation-protocol.md
+++ b/contracts/agents-api/zh/node-generation-protocol.md
@@ -1,7 +1,7 @@
 ---
 title: "沙箱节点协议"
 source: contracts/agents-api/node-generation-protocol.md
-source_hash: fb446e91c3df3c9e397e5e9abb794245b0ae11d81176879207718680e8ab4173
+source_hash: 06982830caebaaaa95b37a78c73710555a332a4a182aeab6d73836a964805443
 ---
 
 沙箱节点在其主机上运行 Docker 或 microsandbox 提供商，并通过一个 WebSocket 与 Core 相连。Core 通过该连接发送提供商操作；节点针对本地提供商执行这些操作，并报告就绪状态、主机测量值及其持有的部署代次。Core 始终是唯一的生命周期所有者：节点绝不重试变更操作或调度工作。帧和校验器位于 [`services/core/internal/sandbox/node`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/sandbox/node)（`wire.go`、`generation_wire.go`）；节点用于注册和读取配置的 HTTP 路由位于[机器连接 API](machine-api.md#node-routes)。
@@ -125,4 +125,4 @@ Runtime 字节缺失时，绝不将固定的放置实例迁移到当前 Runtime
 
 准备诊断使用固定的类型化原因。只有制品传输、校验和或版本来源验证失败才会报告 `runtime_download_failed`；私有准备器通过退出类别指示这一类失败，Core 和节点都不解析 stderr。提供商故障、所有权故障、取消和未分类故障保留其类型化代码，或使用 `provider_unavailable`。协议中不会传输任何提供商原始文本。
 
-当前线协议版本为 5。Create 引导和 Resume 请求可携带可选的工作区文件系统绑定。节点在转发前校验其租户及 Environment 与分配引用一致、ObjectID 不可变且有效，以及挂载配置 ID 与所传配置一致。文件系统解析器负责适配器原生所有权校验。未提供绑定时选择自有存储；已提供绑定时不得回退。错误响应仅可保留原生 ID 非空且名称、代次、快照来源均匹配请求的 Resume 目标；这仅为清理证据，不代表恢复成功。
+Create 引导和 Resume 请求可携带可选的工作区文件系统绑定。节点在转发前校验其租户及 Environment 与分配引用一致、ObjectID 不可变且有效，以及挂载配置 ID 与所传配置一致。文件系统解析器负责适配器原生所有权校验。未提供绑定时选择自有存储；已提供绑定时不得回退。错误响应仅可保留原生 ID 非空且名称、代次、快照来源均匹配请求的 Resume 目标；这仅为清理证据，不代表恢复成功。
diff --git a/docs/configuration.md b/docs/configuration.md
index 4cc8ef6b8..d4846c559 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -245,7 +245,8 @@ The installer creates `~/.oac/core` by default (`$HOME/.oac/core` on Windows). I
 | Path | Content | Changed by |
 | --- | --- | --- |
 | `.env` | Process settings and the stable Compose project name | You, then `oac apply` |
-| `compose.yaml`, `compose-sha256sums.txt` | Verified release service definition | The release |
+| `compose.yaml` | Verified release service definition | The installer, when it installs or [upgrades](./getting-started/operations.md#upgrade) |
+| `compose.override.yaml` | Optional local Compose entries. For a source bundle it is JSON and also holds the four service images and Web's `/node-payload` bind | You. `install.py` replaces only its own entries and requires JSON |
 | `oac` (`oac.exe` on Windows) | Native management command | The installer |
 
 The sibling `<install-dir>.lock` directory remains for synchronization; `<install-dir>.staging` holds unpublished installation files. Neither contains service data. On Unix the installer creates private directories with mode `0700` and configuration files with mode `0600`.
diff --git a/docs/development.md b/docs/development.md
index e8f000747..d9896a1bb 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -86,7 +86,7 @@ docker compose up -d --wait --pull never
 ./oac core-key --show
 ```
 
-`install.py` requires an empty installation directory. Configuration preparation failures before `compose.yaml`, `.env` and `oac` exist require removing that incomplete directory and retrying. After those files exist, use Compose to retry. Use the [operator commands](./getting-started/operations.md) for configuration, keys and stopping services. A different source commit is a fresh installation, not an in-place upgrade: delete managed resources and uninstall nodes first, then remove the old Compose containers and data volume with `docker compose down --volumes`, and remove its installation directory. This permanently deletes that test installation's data. Alternatively choose another installation directory and Web port.
+Rerunning the same bundle's `install.py` on its installation directory resumes the installation with the saved settings; `--public-url` is required only for a new directory. A bundle from another commit refuses an existing installation unless you pass `--upgrade`, which [upgrades it in place](./getting-started/operations.md#upgrade). If preparation fails before `compose.yaml` and `.env` exist, remove that incomplete directory and retry. Use the [operator commands](./getting-started/operations.md) for configuration, keys and stopping services.
 
 ## Build and run components
 
diff --git a/docs/getting-started/install-options.md b/docs/getting-started/install-options.md
index 251f0b0fe..5d8b411d7 100644
--- a/docs/getting-started/install-options.md
+++ b/docs/getting-started/install-options.md
@@ -41,7 +41,7 @@ On either platform, open its server terminal and run `docker compose ls` to find
 
 After signing in, choose the sandbox backend and add nodes using [Nodes](./nodes.md). The Compose stack deploys the control plane; execution machines remain separate.
 
-Stop with `docker compose stop` using the same files and environment. Back up the data volume and configuration together while the services are stopped. Follow the [installation version policy](./operations.md#installation-version-policy): a different release needs a new Compose project and a fresh data volume.
+Stop with `docker compose stop` using the same files and environment. Back up the data volume and configuration together while the services are stopped. To upgrade, back up first, then deploy the new release's `compose.yaml` with the same project, environment and data volume: initialization upgrades the volume and Core migrates the database. [Upgrade](./operations.md#upgrade) describes what is kept and why an older release is refused.
 
 ## Process settings
 
@@ -56,11 +56,12 @@ These flags are written to `.env` once. After installation, edit that file and r
 
 ## Installation actions
 
-`--install-dir` chooses where the installation is created. It is not a process setting.
+`--install-dir` chooses where the installation is created. Neither option is a process setting.
 
 | Option | Purpose |
 | --- | --- |
-| `--install-dir DIR` | Absolute installation directory; defaults to `~/.oac/core`. Use an empty or missing directory for a new installation, or an existing installation directory to [retry](./install.md#install) |
+| `--install-dir DIR` | Absolute installation directory; defaults to `~/.oac/core`. Use an empty or missing directory for a new installation, or an existing installation directory to [retry](./install.md#install) or upgrade |
+| `--upgrade` | Upgrade the existing installation in `--install-dir` to the installer's release; see [Upgrade](./operations.md#upgrade) |
 
 Several installations can share a machine when they use distinct installation directories and ports. Use distinct IP addresses or a shared reverse proxy for more. Each installation has its own database, Core key and nodes.
 
diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index f7771bb40..7db2e74e5 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -58,7 +58,7 @@ Downloads and configuration checks happen before the installation directory is p
 curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.sh | bash -s -- --install-dir "$HOME/.oac/core"
 ```
 
-Use your chosen directory if it differs. A rerun uses the saved Compose file and settings; installation flags only apply to new directories. Existing images and containers are reused; missing images are downloaded. To change settings, edit `.env` and run `oac apply`. A new release needs a new directory; see [version policy](./operations.md#installation-version-policy).
+Use your chosen directory if it differs. A rerun uses the saved Compose file and settings; installation flags only apply to new directories. Existing images and containers are reused; missing images are downloaded. To change settings, edit `.env` and run `oac apply`. To move to a newer release, follow [Upgrade](./operations.md#upgrade).
 
 For insufficient space or quota, free space on the filesystem named by the error. Image-loading failures can also require space in Docker's storage, which may be on a different filesystem.
 
diff --git a/docs/getting-started/nodes.md b/docs/getting-started/nodes.md
index 179f3d3f9..de618397c 100644
--- a/docs/getting-started/nodes.md
+++ b/docs/getting-started/nodes.md
@@ -78,13 +78,13 @@ Root only prepares the account, the group and the unit; everything else, the Doc
 
 **One Core per host.** Nodes share the `oac-node` account, so a host serves one Core; a command from a second Core is refused.
 
-**One release.** A node runs the program of the console that added it and is never upgraded in place; see the [installation version policy](./operations.md#installation-version-policy).
+**Node software.** A node keeps the host program of the console that added it; an upgrade of Core doesn't replace it. A release that changes the node protocol lists the actions it requires; see [protocol changes](./operations.md#protocol-changes).
 
 **The token.** It is single-use, expires after 10 minutes and only registers the node. The installer takes it only on standard input and refuses it in the environment, where `sudo VAR=… python3` would record it in sudo's log. A sudoers policy with `log_input` records standard input, and so the token.
 
 ## Rerun, expiry and slow links
 
-- Rerunning the same command is safe. Once the node is registered, a rerun uses the node's own credential, changes nothing that already matches and needs no token. It refuses, without changing anything, when the node's retained identity belongs to another Core address or installation.
+- Rerunning the same command is safe. Once the node is registered, a rerun uses the node's own credential, changes nothing that already matches and needs no token. It refuses, without changing anything, when the node's retained identity belongs to another Core address or installation, and with `Retained node specification differs from Core` once the sandbox configuration has changed since the node registered. A node added with this command prepares new configurations itself; see [Change the sandbox configuration](#change-the-sandbox-configuration).
 - A command that already expired, or was used on another host, fails at once with `Core rejected the node configuration read (HTTP 401)`: generate a new command and run it within 10 minutes.
 - If the command expires during a slow download, registration fails with `The enrollment command expired or was already used`. The downloaded files are kept: generate a new command in Web and run it.
 - Failed or interrupted downloads discard their temporary files. A rerun downloads missing files from the beginning and reuses verified complete files. A transfer that brings less than 64 KiB in a minute stops; check the network and retry.
diff --git a/docs/getting-started/operations.md b/docs/getting-started/operations.md
index 205fbbcf3..57b16b06c 100644
--- a/docs/getting-started/operations.md
+++ b/docs/getting-started/operations.md
@@ -17,7 +17,7 @@ docker compose -f ~/.oac/core/compose.yaml ps
 | `docker compose ps` | Shows the services. Run it in the installation directory |
 | `docker compose start` | Starts the services |
 | `docker compose stop` | Stops the services. Data, nodes and sandboxes are kept |
-| `oac apply` | Runs `oac-core check-config`, then `docker compose up -d --wait`. A failed check changes no service |
+| `oac apply` | Checks the data volume and `.env`, then starts the services and recreates those whose configuration changed; see [how oac apply works](../configuration.md#how-oac-apply-works). A failed check changes no service |
 | `oac core-key [--show]` | Identifies the key location in the data volume, or prints the key with `--show` |
 | `oac rotate-core-key` | Replaces the Core key and restarts Core and Web |
 | `docker compose down` | Removes the containers. Data is kept; to delete it, [uninstall](#uninstall) |
@@ -125,7 +125,7 @@ Core records which key made each public resource write; the retention of that hi
 
 ## Back up
 
-A recoverable backup contains one consistent, stopped-write set. A database dump or Core volume export alone does not include independent workspace storage or node compute state. Use the same release when restoring; see [installation version policy](#installation-version-policy).
+A recoverable backup contains one consistent, stopped-write set. A database dump or Core volume export alone does not include independent workspace storage or node compute state. Restore the data volume together with the installation directory from the same backup, which holds the release that wrote it; a newer release can [upgrade](#upgrade) the restored installation afterward.
 
 ### Backup contents
 
@@ -166,6 +166,52 @@ The cold released baseline resumes only qualified native history after new compu
 
 Start the database, Core and node services only after their restored dependencies are complete; keep ingress restricted while checking them. In an isolated rehearsal, verify a retained Session's files and native continuation on fresh compute where qualified, confirm that deleted objects cannot be reopened, and check that no old writer can access the restored namespace. Record the results before relying on the backup for recovery.
 
+## Upgrade {#upgrade}
+
+An installation of v0.0.10 or later upgrades in place to a newer release. It keeps its database, data volume, `.env`, secrets, Core key, installation ID and the entries you added to `compose.override.yaml`. An older installation can't upgrade: install the new release into a new directory. Downgrades are refused.
+
+1. Read the target release's notes for [protocol changes](#protocol-changes) and the actions they require.
+2. [Back up](#back-up) the installation. The upgrade takes no backup, and after it the backup is the only way back to the previous release.
+3. Run the target release's installer with `--upgrade` and the installation directory:
+
+   ```sh
+   curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.sh | bash -s -- --upgrade --install-dir "$HOME/.oac/core"
+   ```
+
+   `--version TAG` selects a release other than the latest. On Windows, pass the same flags to the downloaded `install.ps1`. For an installation from a [source bundle](../development.md#install-a-checkout-without-publishing-a-release), run the new bundle's installer: `python3 <bundle>/install.py --install-dir <dir> --upgrade`.
+4. When you are ready, [apply the release's Runtime](#runtime-after-an-upgrade).
+
+Without `--upgrade`, another release's installer changes nothing and stops with `This installation runs release <old>; this installer is <new>. Back up the installation (Upgrade in the operations guide), then rerun with --upgrade.` (`install.py` says `this bundle is`). The installed release's installer resumes the installation, with or without the flag. Installation and mutating `oac` commands share the [installation lock](../configuration.md#installation-directory); if another command is running, wait for it to finish before retrying.
+
+### What the upgrade does
+
+The installer downloads the release's `compose.yaml` and pulls missing images. Before it replaces any file, it runs the new release's configuration check and initialization with the installation's `.env` and Compose overrides. Initialization upgrades the data volume, or refuses a downgrade. The installer then puts the new `compose.yaml` and `oac` in place and starts the services, recreating those that changed; Core migrates the database as it starts. [Deployment](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/README.md#installation) describes each step. The restart interrupts work as any [Core restart](#stop-and-restart) does; nodes and sandboxes keep running and reconnect.
+
+On success the installer prints the Core key and the line `Upgraded from <old> to <new>. Settings → Sandbox and scheduling offers this release's Runtime; sandboxes keep their current Runtime until you apply it.`
+
+If a check fails, the installer prints `Upgrade stopped; the running services are unchanged` with Docker's output, and the previous release keeps serving. Fix the cause and rerun the command. Once initialization has upgraded the data volume, the previous release can no longer start on it: if a later step fails, for example with `startup failed; data retained, rerun the installer`, rerun the same command, which repeats every step safely, or [roll back](#roll-back).
+
+### Runtime after an upgrade
+
+The upgrade leaves the sandbox configuration unchanged: nodes keep serving the saved Runtime, and new Sessions use it. To move to the release's Runtime, open **Settings** → **Sandbox and scheduling**, choose **Use this installation's Runtime** in the **Runtime** row, review the change and choose **Save configuration**. Nodes then prepare the new generation, and existing sandboxes keep theirs until they are released; see [Change the sandbox configuration](./nodes.md#change-the-sandbox-configuration). An E2B deployment has no **Runtime** row; its template keeps working unless the release changes the Core–Runtime protocol.
+
+### Protocol changes
+
+Three connections require the same protocol version on both sides: Core and its nodes, a node and its microsandbox helper, and Core and the Runtime. The upgrade changes no node host and no running sandbox. A release that changes one of these protocols says so in its release notes and names which of these actions it requires:
+
+- reinstall each node: [remove it](./nodes.md#remove-a-node), clean up the host, then add the host again with **Add node**;
+- apply the release's Runtime right after the upgrade; sandboxes on earlier generations stop working;
+- [build a new E2B template](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/deploy/e2b/README.md#build-a-template) and select it in [the sandbox configuration](./nodes.md#change-the-sandbox-configuration);
+- reinstall [self-hosted machines](./self-hosted.md#connect-a-machine).
+
+### Downgrades
+
+Initialization refuses a release that is not newer than the installed one, with `This installation runs release <installed> (<date>); this release, <own> (<date>), is not newer. Downgrades are not supported: run that release or a newer one, or restore the backup taken before the upgrade.` The installer reports it as a stopped upgrade, and the installation keeps running. Core refuses a database that a newer release migrated, with `Agents API database schema version N is newer than this Core supports (M). Downgrades are not supported: run the release that upgraded this database or a newer one, or restore the backup taken before the upgrade.` To return to an earlier release, [roll back](#roll-back).
+
+### Roll back
+
+A rollback restores the backup taken before the upgrade: stop the services, [restore](#restore-and-rehearse) the data volume and the installation directory, then start them. Restore before you apply the release's Runtime if you can: once nodes have prepared it, the restored database doesn't know their new generation, so also [remove every node](./nodes.md#remove-a-node) and add it again. Sessions and data created after the backup are lost.
+
 ## Uninstall
 
 ```sh
@@ -182,25 +228,17 @@ Uninstall stops no sandbox: node sandboxes keep running on their nodes, and E2B
 
 Nodes on other hosts keep running. To uninstall them the usual way, remove them in Web first, as in [Remove a node](./nodes.md#remove-a-node). After the installation directory is gone, their Core is gone: on each node host, run the node uninstall command with `--force`, using `node-install.pyz` from the release that installed them. The installation ID is `secrets/core/installation.id` in the data volume.
 
-## Installation version policy
-
-An installation runs one release for its whole life. In-place version upgrades and downgrades are not supported. Nothing migrates data between releases.
-
-To move to a new release, install it into a new, empty directory, with its own database, Core key and nodes, and add nodes from its Web. Keep the old installation, its data and its nodes until their work is finished. Nodes run the program of the console that added them and are never upgraded in place; Core accepts only nodes that speak its own node protocol.
-
-An interrupted installation can [resume with its saved configuration](./install.md#install). An unrelated nonempty directory is refused.
-
-Installation and mutating `oac` commands share the [installation lock](../configuration.md#installation-directory). If another command is running, wait for it to finish before retrying.
-
 ## Troubleshooting
 
 | Symptom | Cause and fix |
 | --- | --- |
-| `Port N is already in use.` | Another program holds that port. Stop it, or choose another `--web-port`. The installer does not move to a different port |
-| `Directory is not a complete Core installation` | Preserve the directory and choose another `--install-dir` |
+| `Web port unavailable; choose --web-port` | Another program holds that port. Stop it, or choose another `--web-port`. The installer does not move to a different port |
+| `incomplete installation: preserve … and choose another directory` | Preserve the directory and choose another `--install-dir` |
 | `configuration check failed; no service was changed` | `.env` has a value Core rejects. The message names the variable and not the value. Fix `.env` and run `oac apply` again |
+| `data volume check failed; no service was changed` | Initialization refused the data volume; the message names the cause, such as a volume a newer release upgraded. See [downgrades](#downgrades) |
+| `This installation runs release …` | The installer or initialization belongs to another release. To move to a newer one, follow [Upgrade](#upgrade); downgrades are refused |
 | `Docker Compose 2.26 or newer is required` | Update the Docker Compose plugin |
-| `Installation and data retained at …` | Read the service logs above it, fix the cause, then [resume installation](./install.md#install); keep the data |
+| `startup failed; data retained, rerun the installer` | Read the service logs above it, fix the cause, then [resume installation](./install.md#install); keep the data |
 | Web answers 403 `Forbidden` | The browser host is not `OAC_PUBLIC_URL`. Open that origin; a reverse proxy must pass the original Host |
 | Web shows that Core is unavailable (502) | Core is stopped or failing: `docker compose ps`, then Core's log |
 | Session creation returns 400 `model_provider_required` | No model provider: set a [default model](../configuration.md#default-models) for the Harness, or pass one; self-hosted Sessions always pass their own |
diff --git a/docs/maintainers.md b/docs/maintainers.md
index 8e787804f..ff7766d54 100644
--- a/docs/maintainers.md
+++ b/docs/maintainers.md
@@ -132,7 +132,7 @@ git push origin v1.2.3
 
 Tags use `vMAJOR.MINOR.PATCH`, optionally with a prerelease suffix such as `-rc.1` and build metadata such as `+build.1`. A prerelease suffix creates a GitHub prerelease. Pushing the tag is the release decision. Automated checks establish build and test results, not real-model qualification: assess live execution evidence before you push the tag. Model credentials and private certificate authorities never enter CI or release inputs, including acceptance images that contain them.
 
-The release notes list every protocol version change (the node wire protocol, the microsandbox helper or the Core–Runtime protocol) with the actions it requires of operators. After the Release is published, set `deploy/compose/smoke-pins.json` to its tag and the SHA-256 of its `compose.yaml`, so the Compose smoke upgrades from the latest published release.
+The release notes list every protocol version change (the node wire protocol, the microsandbox helper or the Core–Runtime protocol) with the actions it requires of operators. Core must never require a secret or file that only a newer initialization creates: an upgrade runs the new Core's `check-config` before the new `init`. After the Release is published, set `deploy/compose/smoke-pins.json` to its tag and the SHA-256 of its `compose.yaml`, so the Compose smoke upgrades from the latest published release.
 
 The workflow runs `check` on the tagged commit, including the full local gate, official-client and image acceptance, and the native matrix with its packaging artifacts enabled. After checks succeed, one `build` job on `blacksmith-4vcpu-ubuntu-2204` prepares the pinned Runtime inputs, reuses the native installers, builds the distribution and publishes directly from its local files. This combined job has `contents: write` and `packages: write`; checkout does not persist credentials. It retains the assets as an uncompressed Actions artifact only when publication fails, for recovery, or when a manual build does not publish.
 
diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md
index bad35339b..9966f6a97 100644
--- a/docs/zh/configuration.md
+++ b/docs/zh/configuration.md
@@ -1,7 +1,7 @@
 ---
 title: "配置参考"
 source: docs/configuration.md
-source_hash: da6efd48db2be8e2b7afafceeb825be946d25faf606e1ed8b749f036fa3ed793
+source_hash: d8e517c85fbc4da3e6cc8906d49c8ac9d92c7b571edf964916d4c2d7efbc5c6d
 ---
 
 Core 安装的每项设置都恰好只有一个归属位置，分属以下三类：
@@ -249,7 +249,8 @@ Session 创建可以在异步工作区准入之前成功。容量耗尽时，Cor
 | 路径 | 内容 | 修改者 |
 | --- | --- | --- |
 | `.env` | 进程设置和固定的 Compose 项目名 | 用户修改后运行 `oac apply` |
-| `compose.yaml`、`compose-sha256sums.txt` | 已校验的发行版服务定义 | 发行流程 |
+| `compose.yaml` | 已校验的发行版服务定义 | 安装程序，在安装或[升级](getting-started/operations.md#upgrade)时 |
+| `compose.override.yaml` | 可选的本地 Compose 条目。源码包安装中它是 JSON，还保存四个服务镜像和 Web 的 `/node-payload` 绑定 | 用户。`install.py` 只替换自己的条目，并要求 JSON 格式 |
 | `oac`（Windows 为 `oac.exe`） | 原生管理命令 | 安装程序 |
 
 同级 `<install-dir>.lock` 目录用于同步操作并一直保留；`<install-dir>.staging` 保存尚未就位的安装文件。两者都不保存服务数据。Unix 上安装程序以 `0700` 创建私有目录，以 `0600` 创建配置文件。
diff --git a/docs/zh/development.md b/docs/zh/development.md
index 5ae8dfb49..be6120276 100644
--- a/docs/zh/development.md
+++ b/docs/zh/development.md
@@ -1,7 +1,7 @@
 ---
 title: "开发 OpenAgentCore"
 source: docs/development.md
-source_hash: cf241a574a30389dc38d0fdaa87fe5d82714beed489e39e42bd6710478f3a3eb
+source_hash: b4d3c7f1700ac0d60038069a7cc62a5e8231e32cc8e33513814da841d260d112
 ---
 
 准备工作副本，构建组件并验证修改。如需使用已安装的实例，从[入门指南](getting-started/index.md)开始。修改代码前阅读[贡献者规则](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md)。
@@ -88,7 +88,7 @@ docker compose up -d --wait --pull never
 ./oac core-key --show
 ```
 
-`install.py` 要求安装目录为空。若配置准备在 `compose.yaml`、`.env` 和 `oac` 三者齐备之前失败，删除该未完成目录后重试；这些文件齐备后使用 Compose 重试。配置、密钥和停止服务参见[运维命令](getting-started/operations.md)。不同源码提交需要全新安装，不支持原地升级：先删除受管资源并卸载节点，再执行 `docker compose down --volumes` 删除旧 Compose 容器和数据卷，最后删除安装目录。这会永久删除该测试安装的数据。也可以选择另一安装目录和 Web 端口。
+对安装目录重新运行同一源码包的 `install.py`，会以已保存的设置继续该安装；只有新目录才需要 `--public-url`。其他提交的源码包会拒绝已有安装，除非传入 `--upgrade`，此时会[原地升级](getting-started/operations.md#upgrade)该安装。若在 `compose.yaml` 和 `.env` 齐备之前准备失败，删除该未完成目录后重试。配置、密钥和停止服务参见[运维命令](getting-started/operations.md)。
 
 ## 构建与运行组件 {#build-and-run-components}
 
diff --git a/docs/zh/getting-started/install-options.md b/docs/zh/getting-started/install-options.md
index 5604fa82b..b83046487 100644
--- a/docs/zh/getting-started/install-options.md
+++ b/docs/zh/getting-started/install-options.md
@@ -1,7 +1,7 @@
 ---
 title: "安装选项"
 source: docs/getting-started/install-options.md
-source_hash: 2fa7ecf80a4f78813dee915b9f327137b286bda61c706022c29512ba9e282e62
+source_hash: b1392b29ace751cdd42738a1aeb1e29068ceb83bf74ee940604b432e59785ad9
 ---
 
 [默认安装](install.md)无需任何选项。本页介绍安装选项、Compose 部署和反向代理配置。
@@ -43,7 +43,7 @@ docker compose exec web oac-web core-key
 
 登录后，使用 [Nodes](nodes.md)选择沙箱提供商并添加节点。Compose 堆栈部署控制平面；执行机器仍需单独部署。
 
-使用相同的文件和环境运行 `docker compose stop` 以停止服务。停止服务后，备份数据卷。请遵循[安装版本策略](operations.md#installation-version-policy)：使用不同发布版本时，需要创建新的 Compose 项目并使用全新的数据卷。
+使用相同的文件和环境运行 `docker compose stop` 以停止服务。停止服务后，一并备份数据卷和配置。升级时先备份，再使用相同的项目、环境和数据卷部署新版本的 `compose.yaml`：初始化会升级数据卷，Core 会迁移数据库。[升级](operations.md#upgrade)说明会保留哪些内容，以及为何拒绝较旧的版本。
 
 ## 进程设置 {#process-settings}
 
@@ -58,11 +58,12 @@ docker compose exec web oac-web core-key
 
 ## 安装操作 {#installation-actions}
 
-`--install-dir` 选择安装目录。它不是进程设置。
+`--install-dir` 选择安装目录。这两个选项都不是进程设置。
 
 | 选项 | 用途 |
 | --- | --- |
-| `--install-dir DIR` | 绝对安装目录；默认为 `~/.oac/core`。新安装使用空目录或不存在的目录；[重试](install.md#install)使用已有安装目录 |
+| `--install-dir DIR` | 绝对安装目录；默认为 `~/.oac/core`。新安装使用空目录或不存在的目录；[重试](install.md#install)或升级时使用已有安装目录 |
+| `--upgrade` | 将 `--install-dir` 中的已有安装升级到安装程序所属的版本；参见[升级](operations.md#upgrade) |
 
 只要使用不同的安装目录和端口，多个安装就可以共用一台机器。需要更多安装时，请使用不同的 IP 地址或共享反向代理。每个安装都有自己的数据库、Core 密钥和节点。
 
diff --git a/docs/zh/getting-started/install.md b/docs/zh/getting-started/install.md
index b33035352..a717e11d0 100644
--- a/docs/zh/getting-started/install.md
+++ b/docs/zh/getting-started/install.md
@@ -1,7 +1,7 @@
 ---
 title: "安装 Core 和 Web"
 source: docs/getting-started/install.md
-source_hash: 9b8c548e48923c2ee6e51deaebb85422db2b568f36a6718af6b44ff13099ff2a
+source_hash: 8afdf9e68232572599bf432b0d98b08e456b26c6c51280b3bd7139c4ef2db8ea
 ---
 
 一条命令即可在 Linux、macOS 或 Windows 上安装 Core、Web 控制台和 PostgreSQL。用 Core 密钥登录 Web，设置默认模型并签发项目 API 密钥。应用使用这些密钥调用 Core。Session 在你添加的节点上的沙箱中运行，也可以在 E2B 上运行。
@@ -60,7 +60,7 @@ curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/
 curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.sh | bash -s -- --install-dir "$HOME/.oac/core"
 ```
 
-如果使用了其他目录，请替换路径。重新执行时沿用已保存的 Compose 文件和设置；安装参数只对新目录生效。已有镜像和容器直接复用，缺失镜像会重新下载。修改设置请编辑 `.env` 并运行 `oac apply`。新发布版使用新目录；见[版本策略](operations.md#installation-version-policy)。
+如果使用了其他目录，请替换路径。重新执行时沿用已保存的 Compose 文件和设置；安装参数只对新目录生效。已有镜像和容器直接复用，缺失镜像会重新下载。修改设置请编辑 `.env` 并运行 `oac apply`。要换到更新的发布版本，请按[升级](operations.md#upgrade)操作。
 
 空间或配额不足时，请释放错误信息所指文件系统的空间。加载镜像失败还可能需要释放 Docker 存储空间，该存储可能位于另一个文件系统。
 
diff --git a/docs/zh/getting-started/nodes.md b/docs/zh/getting-started/nodes.md
index 768c9947b..860f424ad 100644
--- a/docs/zh/getting-started/nodes.md
+++ b/docs/zh/getting-started/nodes.md
@@ -1,7 +1,7 @@
 ---
 title: "添加和管理节点"
 source: docs/getting-started/nodes.md
-source_hash: 1a87d17a7d38d808c8d60c616b439bfb4d50c549412e2366dc8c4d7cc01c28d5
+source_hash: 58450f2e430e5c8d7758835990b9726421f5fe361c6dd22441ae9c9be887e387
 ---
 
 节点是一台 Linux 主机，在沙箱提供商为 microsandbox（推荐）或 Docker 时，为 Core 托管 Session 运行沙箱。Core 将新 Session 分配给有空余容量的节点；节点创建沙箱，沙箱回连 Core。E2B 不需要节点。应用为自己的 Session 连接的机器是[自托管执行器](self-hosted.md)，而不是节点。
@@ -80,13 +80,13 @@ root 只准备账号、组和服务单元；其他操作（包括 Docker 网络
 
 **每台主机只服务一个 Core。** 节点共享 `oac-node` 账号，因此主机只服务一个 Core；第二个 Core 的命令会被拒绝。
 
-**一个发行版本。** 节点运行添加它的控制台所提供的程序，不进行原地升级；参阅[安装版本策略](operations.md#installation-version-policy)。
+**节点程序。** 节点保留添加它的控制台所提供的主机程序；升级 Core 不会替换它。更改节点协议的版本会列出所需操作；参阅[协议变更](operations.md#protocol-changes)。
 
 **令牌。** 令牌仅用于注册节点，一次性使用，10 分钟后过期。安装程序只从标准输入接收它，拒绝环境变量中的令牌，因为 `sudo VAR=… python3` 会在 sudo 日志中记录它。启用了 `log_input` 的 sudoers 策略会记录标准输入，从而记录令牌。
 
 ## 重新运行、过期与慢速网络 {#rerun-expiry-and-slow-links}
 
-- 重新执行同一命令是安全的。节点注册后，重新运行使用节点自身凭据，不改变已匹配的内容，也无需令牌。保留的节点身份属于其他 Core 地址或安装时，程序拒绝且不修改任何内容。
+- 重新执行同一命令是安全的。节点注册后，重新运行使用节点自身凭据，不改变已匹配的内容，也无需令牌。保留的节点身份属于其他 Core 地址或安装时，程序拒绝且不修改任何内容；节点注册后沙箱配置发生变化时，程序同样不做修改，并以 `Retained node specification differs from Core` 拒绝。通过此命令添加的节点会自行准备新配置；参阅[修改沙箱配置](#change-the-sandbox-configuration)。
 - 已过期或已在其他主机使用的命令立即失败，显示 `Core rejected the node configuration read (HTTP 401)`：生成新命令并在 10 分钟内执行。
 - 慢速下载期间命令过期时，注册失败并显示 `The enrollment command expired or was already used`。下载文件保留：在 Web 生成新命令后执行。
 - 失败或中断时删除下载残片；重新执行时从头下载缺失文件，复用已校验的完整文件。每分钟下载不足 64 KiB 时会停止，请检查网络后重试。
diff --git a/docs/zh/getting-started/operations.md b/docs/zh/getting-started/operations.md
index c40e3dc2a..198ff2773 100644
--- a/docs/zh/getting-started/operations.md
+++ b/docs/zh/getting-started/operations.md
@@ -1,7 +1,7 @@
 ---
 title: "运维"
 source: docs/getting-started/operations.md
-source_hash: dbbd6d6729435146779a1fcf0d262ca4b9d4f45859b80f5804c945ef68e4f07c
+source_hash: 36a0202a83bc194598d64750a876f51ca3461ea9c615c6e1afad4caa78c4ad30
 ---
 
 安装运维人员负责 Core 主机、存储和可用性。节点主机运行各自的服务；参阅[节点](nodes.md)。设置见[配置参考](../configuration.md)。
@@ -19,7 +19,7 @@ docker compose -f ~/.oac/core/compose.yaml ps
 | `docker compose ps` | 在安装目录中展示服务 |
 | `docker compose start` | 启动服务 |
 | `docker compose stop` | 停止服务。保留数据、节点和沙箱 |
-| `oac apply` | 先运行 `oac-core check-config`，再执行 `docker compose up -d --wait`。校验失败时不改动任何服务 |
+| `oac apply` | 检查数据卷和 `.env`，然后启动服务，并重新创建配置有变化的服务；参见 [oac apply 的工作方式](../configuration.md#how-oac-apply-works)。校验失败时不改动任何服务 |
 | `oac core-key [--show]` | 指出 Core 密钥在数据卷中的位置；加上 `--show` 时打印密钥本身 |
 | `oac rotate-core-key` | 替换 Core 密钥并重启 Core 和 Web |
 | `docker compose down` | 移除容器。数据保留；要删除数据，请[卸载](#uninstall) |
@@ -127,7 +127,7 @@ Core 记录每次公开资源写入所使用的密钥；历史保留策略为 [`
 
 ## 备份 {#back-up}
 
-可恢复的备份必须是一组在停止写入期间取得的一致数据。仅数据库转储或 Core 卷导出不包含独立工作区存储及节点计算状态。恢复时使用相同版本；参见[安装版本策略](#installation-version-policy)。
+可恢复的备份必须是一组在停止写入期间取得的一致数据。仅数据库转储或 Core 卷导出不包含独立工作区存储及节点计算状态。恢复数据卷时，同时恢复同一份备份中的安装目录，其中保存着写入该数据的版本；之后可以用更新的版本[升级](#upgrade)恢复后的安装。
 
 ### 备份内容 {#backup-contents}
 
@@ -168,6 +168,52 @@ docker compose -f "$HOME/.oac/core/compose.yaml" exec -T database \
 
 恢复依赖全部完整后才启动 database、Core 和节点服务；检查期间保持入口受限。在隔离演练中，验证保留 Session 的文件和具备资格时在新计算资源上的原生续接，确认已删除对象无法重新打开，并检查旧写入方均无法访问恢复后的命名空间。在依赖备份进行恢复前记录结果。
 
+## 升级 {#upgrade}
+
+v0.0.10 及更高版本的安装可以原地升级到更新的发布版本，并保留数据库、数据卷、`.env`、密钥、Core 密钥、安装 ID 以及你在 `compose.override.yaml` 中添加的条目。更早的安装无法升级：请将新版本安装到新目录。降级会被拒绝。
+
+1. 阅读目标版本的发布说明，了解[协议变更](#protocol-changes)及其要求的操作。
+2. [备份](#back-up)安装。升级不会备份；升级之后，备份是回到先前版本的唯一途径。
+3. 使用目标版本的安装程序，带上 `--upgrade` 和安装目录运行：
+
+   ```sh
+   curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.sh | bash -s -- --upgrade --install-dir "$HOME/.oac/core"
+   ```
+
+   `--version TAG` 选择最新版本以外的发布版本。Windows 上，将相同参数传给下载的 `install.ps1`。对于从[源码包](../development.md#install-a-checkout-without-publishing-a-release)安装的实例，运行新源码包的安装程序：`python3 <bundle>/install.py --install-dir <dir> --upgrade`。
+4. 准备好后，[应用该版本的 Runtime](#runtime-after-an-upgrade)。
+
+不带 `--upgrade` 时，其他版本的安装程序不做任何更改，并以 `This installation runs release <old>; this installer is <new>. Back up the installation (Upgrade in the operations guide), then rerun with --upgrade.` 停止（`install.py` 的提示为 `this bundle is`）。无论是否带该参数，已安装版本的安装程序都会继续该安装。安装程序和修改状态的 `oac` 命令共用[安装锁](../configuration.md#installation-directory)；其他命令正在运行时，等待其结束后重试。
+
+### 升级会做什么 {#what-the-upgrade-does}
+
+安装程序下载该版本的 `compose.yaml` 并拉取缺失的镜像。替换任何文件之前，它使用安装的 `.env` 和 Compose 覆盖文件运行新版本的配置检查和初始化。初始化会升级数据卷，或拒绝降级。随后安装程序将新的 `compose.yaml` 和 `oac` 放到位并启动服务，重新创建有变化的服务；Core 启动时迁移数据库。[部署](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/README.md#installation)说明了每个步骤。这次重启对工作的影响与任何一次 [Core 重启](#stop-and-restart)相同；节点和沙箱继续运行并重新连接。
+
+成功时，安装程序打印 Core 密钥以及一行 `Upgraded from <old> to <new>. Settings → Sandbox and scheduling offers this release's Runtime; sandboxes keep their current Runtime until you apply it.`
+
+如果某项检查失败，安装程序会打印 `Upgrade stopped; the running services are unchanged` 及 Docker 的输出，先前版本继续提供服务。修复原因后重新运行命令。初始化升级数据卷后，先前版本便无法再在该数据卷上启动：如果后续步骤失败（例如出现 `startup failed; data retained, rerun the installer`），重新运行同一命令，它会安全地重复每个步骤；也可以[回滚](#roll-back)。
+
+### 升级后的 Runtime {#runtime-after-an-upgrade}
+
+升级不会改变沙箱配置：节点继续服务已保存的 Runtime，新 Session 也使用它。要切换到该版本的 Runtime，打开 **设置** → **沙箱与调度**，在 **Runtime** 行选择 **使用本安装的 Runtime**，确认更改后选择 **保存配置**。节点随后准备新代次，现有沙箱保留原代次，直到被释放；参阅[修改沙箱配置](nodes.md#change-the-sandbox-configuration)。E2B 部署没有 **Runtime** 行；除非该版本更改了 Core–Runtime 协议，其模板继续可用。
+
+### 协议变更 {#protocol-changes}
+
+以下三种连接要求两端的协议版本相同：Core 与节点、节点与 microsandbox 辅助程序、Core 与 Runtime。升级不会改动任何节点主机或正在运行的沙箱。更改其中某个协议的版本会在发布说明中注明，并指出需要以下哪些操作：
+
+- 重新安装每个节点：[移除节点](nodes.md#remove-a-node)，清理主机，再通过 **添加节点** 重新添加该主机；
+- 升级后立即应用该版本的 Runtime；仍在较早代次上的沙箱将停止工作；
+- [构建新的 E2B 模板](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/deploy/e2b/README.md#build-a-template)，并在[沙箱配置](nodes.md#change-the-sandbox-configuration)中选择它；
+- 重新安装[自托管机器](self-hosted.md#connect-a-machine)。
+
+### 降级 {#downgrades}
+
+初始化会拒绝不比已安装版本更新的版本，并提示 `This installation runs release <installed> (<date>); this release, <own> (<date>), is not newer. Downgrades are not supported: run that release or a newer one, or restore the backup taken before the upgrade.` 安装程序将其报告为已停止的升级，安装继续运行。Core 会拒绝由更新版本迁移过的数据库，并提示 `Agents API database schema version N is newer than this Core supports (M). Downgrades are not supported: run the release that upgraded this database or a newer one, or restore the backup taken before the upgrade.` 要回到较早的版本，请[回滚](#roll-back)。
+
+### 回滚 {#roll-back}
+
+回滚即恢复升级前的备份：停止服务，[恢复](#restore-and-rehearse)数据卷和安装目录，然后启动服务。尽量在应用该版本的 Runtime 之前恢复：节点准备好它之后，恢复的数据库并不知道节点的新代次，因此还需[移除每个节点](nodes.md#remove-a-node)并重新添加。备份之后创建的 Session 和数据会丢失。
+
 ## 卸载 {#uninstall}
 
 ```sh
@@ -184,25 +230,17 @@ cd && rm -rf ~/.oac/core
 
 其他主机上的节点继续运行。按常规方式卸载时，先在 Web 移除，见[移除节点](nodes.md#remove-a-node)。安装目录删除后，它们的 Core 已不存在：在各节点主机使用当时发布版的 `node-install.pyz`，执行带 `--force` 的节点卸载命令。安装 ID 在数据卷的 `secrets/core/installation.id` 中。
 
-## 安装版本策略 {#installation-version-policy}
-
-安装在整个生命周期使用同一发行版本。不支持原地升级或降级，也不在版本间迁移数据。
-
-迁移到新版本时，安装到全新的空目录，使用独立数据库、Core 密钥和节点，并从新 Web 添加节点。保留旧安装、数据和节点，直到工作完成。节点运行添加它的控制台所提供的程序，不原地升级；Core 仅接受使用自身节点协议的节点。
-
-中断的安装可以[沿用已保存配置继续](install.md#install)。与本安装无关的非空目录会被拒绝。
-
-安装程序和修改状态的 `oac` 命令共用[安装锁](../configuration.md#installation-directory)。其他命令正在运行时，等待其结束后重试。
-
 ## 问题排查 {#troubleshooting}
 
 | 症状 | 原因与解决方法 |
 | --- | --- |
-| `Port N is already in use.` | 其他程序占用该端口。停止它，或另选 `--web-port`。安装程序不会改用其他端口 |
-| `Directory is not a complete Core installation` | 保留目录内容，选择另一个 `--install-dir` |
+| `Web port unavailable; choose --web-port` | 其他程序占用该端口。停止它，或另选 `--web-port`。安装程序不会改用其他端口 |
+| `incomplete installation: preserve … and choose another directory` | 保留目录内容，选择另一个 `--install-dir` |
 | `configuration check failed; no service was changed` | `.env` 中有 Core 拒绝的值。消息只包含变量名。修正 `.env` 后再次运行 `oac apply` |
+| `data volume check failed; no service was changed` | 初始化拒绝了数据卷；消息会说明原因，例如数据卷已被更新的版本升级。参见[降级](#downgrades) |
+| `This installation runs release …` | 安装程序或初始化属于另一个版本。要换到更新的版本，请按[升级](#upgrade)操作；降级会被拒绝 |
 | `Docker Compose 2.26 or newer is required` | 更新 Docker Compose 插件 |
-| `Installation and data retained at …` | 查看上方服务日志，修复原因，再[继续安装](install.md#install)；不要删除数据 |
+| `startup failed; data retained, rerun the installer` | 查看上方服务日志，修复原因，再[继续安装](install.md#install)；不要删除数据 |
 | Web 返回 403 `Forbidden` | 浏览器主机名不是 `OAC_PUBLIC_URL`。打开该源地址；反向代理必须传递原始 Host |
 | Web 显示 Core 不可用（502） | Core 停止或失败：先 `docker compose ps`，再查看 Core 日志 |
 | 创建 Session 返回 400 `model_provider_required` | 缺少模型提供商：为 Harness 设置[默认模型](../configuration.md#default-models)，或显式提供；自托管 Session 始终自带提供商 |
diff --git a/docs/zh/maintainers.md b/docs/zh/maintainers.md
index 44f90e4c7..44343b008 100644
--- a/docs/zh/maintainers.md
+++ b/docs/zh/maintainers.md
@@ -1,7 +1,7 @@
 ---
 title: "构建并发布 OpenAgentCore"
 source: docs/maintainers.md
-source_hash: ae368641567f256f0579182f65cc565e5c6d10161bdb35e6b473306b03167b53
+source_hash: 06be9f5ebff84ac8d7ec419e965345d0ac7d0064f8c79f35c4c025f73b9b82dd
 ---
 
 本指南面向负责构建和发布 OpenAgentCore 的维护者。要安装 Core 和 Web，请使用 [安装指南](getting-started/install.md)。安装器代码遵循的规则见 [部署](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/README.md) 和 [节点安装器](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/node/README.md)；必需检查见 [CONTRIBUTING](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md#required-checks)。
@@ -134,7 +134,7 @@ git push origin v1.2.3
 
 标签使用 `vMAJOR.MINOR.PATCH` 格式，可选用 `-rc.1` 等预发布后缀以及 `+build.1` 等构建元数据。预发布后缀会创建 GitHub 预发布版。推送标签即表示发布决定。自动检查用于确定构建和测试结果，而不是真实模型资格：推送标签前应评估实际执行证据。模型凭据和私有证书颁发机构绝不能进入 CI 或发布输入，包含它们的验收镜像也不例外。
 
-发布说明会列出每一项协议版本变更（节点线协议、microsandbox 辅助程序或 Core–Runtime 协议），以及它要求运维人员执行的操作。Release 发布后，将 `deploy/compose/smoke-pins.json` 设为它的标签及其 `compose.yaml` 的 SHA-256，使 Compose 冒烟测试从最新的已发布版本升级。
+发布说明会列出每一项协议版本变更（节点线协议、microsandbox 辅助程序或 Core–Runtime 协议），以及它要求运维人员执行的操作。Core 绝不能依赖只有更新版本的初始化才会创建的密钥或文件：升级会先运行新 Core 的 `check-config`，再运行新的 `init`。Release 发布后，将 `deploy/compose/smoke-pins.json` 设为它的标签及其 `compose.yaml` 的 SHA-256，使 Compose 冒烟测试从最新的已发布版本升级。
 
 工作流会在带标签的提交上运行 `check`，包括完整的本地门禁、官方客户端和镜像验收，以及启用打包构件的原生平台矩阵。检查成功后，`blacksmith-4vcpu-ubuntu-2204` 上的一个 `build` 作业会准备固定的 Runtime 输入、复用原生安装器、构建分发包，并直接从本地文件发布。此合并作业具有 `contents: write` 和 `packages: write` 权限；检出过程不会保留凭据。只有发布失败或手动构建不发布时，才会把这些文件保留为未压缩的 Actions 构建产物，供恢复使用。
 
diff --git a/services/core/README.md b/services/core/README.md
index d8b3d8623..0a29c26cc 100644
--- a/services/core/README.md
+++ b/services/core/README.md
@@ -16,7 +16,7 @@
 
 ## Database
 
-Core uses its own PostgreSQL database and account and shares no tables with an application. Its migrations are embedded goose migrations in [`migrations/`](migrations), tracked in `agents_api_schema_version`; a migration is never edited after it lands. Queries live in `internal/db/queries` and generate typed code with sqlc: run `make sqlc-generate` after changing a query and commit the generated files, which `make check-sqlc` compares.
+Core uses its own PostgreSQL database and account and shares no tables with an application. Its migrations are embedded goose migrations in [`migrations/`](migrations), tracked in `agents_api_schema_version`; a migration is never edited after it lands. Core applies pending migrations when it starts and refuses a database whose schema version is newer than its own, which a [downgrade](../../docs/getting-started/operations.md#downgrades) would produce. Queries live in `internal/db/queries` and generate typed code with sqlc: run `make sqlc-generate` after changing a query and commit the generated files, which `make check-sqlc` compares.
 
 ## Run from source