docs: describe runtime and backup contracts

Electron consumes launch paths from its baked stamp, not a fixed
Python-version directory. Backups preserve data and declarations,
not runtime downloads or browser profiles.

State both contracts in the build and migration guides. Keep the
backup exclusions and quick/full distinction aligned across English
and Chinese, with stable comparison anchors.

The bilingual site build, website typecheck, pinned diagram linter
and added-prose checks passed. All six affected routes and new
backup links were checked in rendered output. Unrelated locale-link
warnings remain. No native package acceptance is implied.

apps/desktop/BUILDING.md

@@ -36,9 +36,9 @@ This is broader than the source installer's extra named `all`.
 
 The backend runs from app resources. Launchers execute the store interpreter
 with the source and dependency paths; they do not boot through a relocated
-venv executable. First boot verifies payload facts without changing signed files.
-It can create user-state records and CLI links. Provider calls, model downloads,
-and optional integration setup can still use the network.
+venv executable. Startup can create user-state records and CLI links.
+Provider calls, model downloads, and optional integration setup can still use
+the network.
 
 Git is a platform exception: Windows stages Git for Windows with Bash.
 POSIX targets use system Git. A Mac without Command Line Tools can therefore
@@ -48,15 +48,17 @@ User data remains outside the package. Optional additions use writable PM
 storage and complete Python environment generations, not writes into the app.
 See [Package management](../../website/docs/reference/package-management.md).
 
-## Current Python migration blocker
+## Python runtime contract
 
-The staging pin now selects Python 3.14, but
-`electron/payload-backend.ts` still defaults POSIX dependency discovery to
-`venv/lib/python3.11/site-packages`. No build path supplies its `PYTHON_VER`
-override. This mismatch prevents normal bundled macOS/Linux backend resolution.
-The native resolver must use the payload's actual Python version before a
-3.14 bundle can satisfy startup and update acceptance. A successful staging
-step does not resolve this blocker.
+The PM bundle builder records interpreter and dependency paths in the payload
+manifest. `scripts/write-build-stamp.mjs` copies that runtime contract into the
+desktop stamp. The desktop build embeds the stamp in Electron.
+`electron/payload-backend.ts` reads `runtime.sitePackages` from this stamp.
+It does not select a Python version or search for dependency directories.
+
+Staging does not prove native startup or package replacement. Those checks
+use the [bundled-update acceptance suite](../../tests/install/BUNDLED_UPDATES.md).
+Acceptance requires a native run with the actual signed release artifacts.
 
 ## Complete native build
 

website/docs/getting-started/updating.md

@@ -93,7 +93,7 @@ This suppresses both cached update notices and passive update-check network requ
 
 For an admitted source checkout, `hermes update` runs these phases:
 
-1. **Pre-update snapshot** — a lightweight state snapshot is saved by default (covers pairing data, cron jobs, `config.yaml`, `.env`, `auth.json`, and other state files that get modified at runtime; individual files over 1 GiB are skipped so a large sessions DB never slows the update down). Because the code swap and gateway restarts touch every profile, the same snapshot is taken for **every profile** on the install — each into its own `state-snapshots/` directory — and the post-update cron-jobs safety net checks each profile against its own snapshot. Controlled by `updates.pre_update_backup` (`quick` by default, `full` for a zip of all of `HERMES_HOME`, `off` to disable). Recoverable via the snapshot restore flow described under [Snapshots and rollback](../user-guide/checkpoints-and-rollback.md). Quick snapshots are file-loss recovery, not code-rollback insurance — for a coherent point-in-time rollback use `--backup` (full mode).
+1. **Pre-update snapshot** — Hermes saves selected state files for every profile in that profile's `state-snapshots/` directory. These include pairing data, cron jobs, `config.yaml`, `.env`, and `auth.json`. Automatic quick snapshots skip individual files larger than 1 GiB. `updates.pre_update_backup` selects `quick`, `full`, or `off`. Full archives use the [backup exclusions](/reference/faq#hermes-backup-vs-hermes-profile-export). Recovery uses [Snapshots and rollback](../user-guide/checkpoints-and-rollback.md). Quick snapshots recover state files, not application code.
 2. **Code update** — applies the configured source branch or stable release tag and updates submodules.
 3. **Post-pull syntax validation + auto-rollback** — after the pull, Hermes compiles the nine critical files every `hermes` invocation imports at startup. If any fails to parse (e.g. an orphan merge-conflict marker, an accidentally truncated file), Hermes runs `git reset --hard <pre-pull-sha>` to roll the install back so your shell stays bootable. Re-run `hermes update` once the upstream fix lands.
 4. **Dependency preparation** — PM provisions required tools and prepares a complete Python environment from the new lock, existing extras, and enabled plugin requirements. It validates that environment before publishing its selection.
@@ -203,7 +203,13 @@ updates:
   pre_update_backup: full
 ```
 
-`updates.pre_update_backup` is a single knob with three modes: `quick` (default — the lightweight state snapshot described above), `full` (the quick snapshot plus a complete `HERMES_HOME` zip; can add minutes on large homes), and `off` (no pre-update backup at all — `--no-backup` does the same for a single run). Legacy boolean values still work: `true` means `full`, `false` means `off`.
+`updates.pre_update_backup` has three modes:
+
+- `quick` saves the selected state files described above. This is the default.
+- `full` adds a zip archive with the [backup exclusions](/reference/faq#hermes-backup-vs-hermes-profile-export). Large data directories can take several minutes.
+- `off` disables pre-update backups. `--no-backup` selects this mode for one run.
+
+Legacy boolean values remain supported: `true` means `full`, and `false` means `off`.
 
 :::tip Moving to a new machine instead?
 Update backups protect an in-place update. If you're migrating your whole setup to different hardware, use `hermes backup` + `hermes import` instead — see [Exporting Hermes to another machine](/reference/faq#exporting-hermes-to-another-machine) and [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export).
@@ -336,7 +342,11 @@ same manager that installed them. Their package files are not removed by the
 source uninstaller. Data deletion is separate from package removal.
 
 :::tip Moving to a new machine rather than leaving?
-Take your setup with you before removing anything: `hermes backup` captures the entire `~/.hermes` directory including credentials, while `hermes profile export` packs a single profile with credentials excluded by design (so an export alone is not a full backup). See [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export).
+Run `hermes backup` before you remove the installation. The full archive includes
+credentials but excludes downloaded runtimes, dependency environments, caches,
+and browser profiles. Review its skipped-file report before you delete source data.
+`hermes profile export` packs one profile without credentials.
+See [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export).
 :::
 
 ### Manual Uninstall

website/docs/reference/faq.md

@@ -766,7 +766,9 @@ Skills with very long descriptions are truncated to 40 characters in the Telegra
    ```bash
    hermes backup
    ```
-   This creates a zip of your entire `~/.hermes/` directory — config, API keys, memories, skills, sessions, and profiles — saved to your home directory as `~/hermes-backup-<timestamp>.zip`.
+   This saves a zip archive at `~/hermes-backup-<timestamp>.zip`.
+   The full backup covers configuration, credentials, memories, skills, sessions,
+   and profiles under the Hermes data root. It is not an application or runtime image.
 
 3. Copy the zip to the new machine and import it:
    ```bash
@@ -793,16 +795,32 @@ hermes profile import ./work-backup.tar.gz work
 
 The imported profile will have all config, memories, sessions, and skills from the export. You may need to update paths or re-authenticate with providers if the new machine has a different setup.
 
-### `hermes backup` vs `hermes profile export`
+### `hermes backup` vs `hermes profile export` {#hermes-backup-vs-hermes-profile-export}
 
 | Feature | `hermes backup` | `hermes profile export` |
 | :--- | :--- | :--- |
 | **Use Case** | **Full machine migration** | **Porting/sharing a specific profile** |
-| **Scope** | Global (entire `~/.hermes` directory) | Local (single profile directory) |
+| **Scope** | Hermes data root, with the exclusions listed below | Single profile directory |
 | **Includes** | All profiles, global config, API keys, sessions | Single profile: SOUL.md, memories, sessions, skills |
 | **Credentials** | **Included** (`.env` and `auth.json`) | **Excluded** (stripped for safe sharing) |
 | **Format** | `.zip` | `.tar.gz` |
 
+The full backup excludes:
+
+- The source checkout, dependency environments, and downloaded tools, models, and runtimes.
+- Build caches, checkpoints, previous backups, and quick snapshots.
+- Browser profiles, including copies of real-browser credentials.
+- Bytecode, SQLite sidecars, `gateway.pid`, `cron.pid`, and `.backup.lock`.
+
+`hermes backup --quick` saves selected state files instead of a full archive.
+It is not a replacement for the full backup before a machine migration.
+
+Full backups report files that fail to copy. An archive can therefore exist
+with missing data. Review the skipped-file report before you remove the source installation.
+Restored package declarations let PM download dependencies again. Bytecode and
+SQLite sidecars regenerate locally. The exclusions do not remove `.env` or
+`auth.json` from the full backup.
+
 **Manual fallback (rsync):** If you prefer to copy files directly, exclude the code repo:
 ```bash
 rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/

website/docs/user-guide/desktop.md

@@ -32,13 +32,9 @@ hermes desktop
 
 That uses the selected installation's configuration and data home.
 
-:::warning Current source-branch package limit
-The Python 3.14 migration still needs a POSIX payload-resolver correction:
-Electron currently defaults to a Python 3.11 dependency path. Do not treat
-new macOS/Linux bundles from this branch as accepted until that correction
-and native startup/update checks pass. This does not describe the status of
-an older published package.
-:::
+The bundled app uses the interpreter and dependency paths embedded in its
+build stamp. It does not use a fixed Python-version directory.
+Successful payload staging does not prove native installation, startup, or updates.
 
 ### Package variants and CLI commands
 
@@ -53,8 +49,9 @@ release matrix leg.
   execution aliases expose `hermes`, `hermes-agent`, and `hermes-acp`.
 - **macOS:** copy the app from its DMG into Applications before opening it.
   Bundled startup attempts to link those CLI commands into `~/.local/bin`.
-  Add that directory to your shell's PATH. Existing entries, including stale
-  symlinks, are left untouched; inspect them if the wrong command runs.
+  Add that directory to your shell's PATH. Startup repairs broken links that
+  name the same command in an old bundled payload. It preserves regular files,
+  live links, and links to unrelated commands.
 - **Linux:** source development and AppImage build support exist, but the
   bundled desktop release legs are disabled. Do not assume a published Linux
   package from the local build target alone.

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/updating.md

@@ -24,7 +24,7 @@ hermes update
 
 运行 `hermes update` 时，将依次执行以下步骤：
 
-1. **更新前快照** — 默认保存一份轻量级状态快照（涵盖配对数据、cron 任务、`config.yaml`、`.env`、`auth.json` 及其他运行时修改的状态文件；单个超过 1 GiB 的文件会被跳过，因此大型会话数据库不会拖慢更新）。由 `updates.pre_update_backup` 控制（默认 `quick`，`full` 为整个 `HERMES_HOME` 的 zip 备份，`off` 为禁用）。可通过 [快照与回滚](../user-guide/checkpoints-and-rollback.md) 中描述的快照恢复流程进行恢复。
+1. **更新前快照** — Hermes 在每个 profile 的 `state-snapshots/` 目录中保存指定的状态文件，包括配对数据、cron 任务、`config.yaml`、`.env` 和 `auth.json`。自动快速快照会跳过单个大于 1 GiB 的文件。`updates.pre_update_backup` 可选择 `quick`、`full` 或 `off`。完整归档遵循[备份排除规则](/reference/faq#hermes-backup-vs-hermes-profile-export)。恢复方法见[快照与回滚](../user-guide/checkpoints-and-rollback.md)。快速快照恢复的是状态文件，不是应用程序代码。
 2. **Git pull** — 从 `main` 分支拉取最新代码并更新子模块
 3. **依赖安装** — 运行 `uv pip install -e ".[all]"` 以获取新增或变更的依赖项
 4. **配置迁移** — 检测自当前版本以来新增的配置选项并提示设置
@@ -50,7 +50,13 @@ updates:
   pre_update_backup: full
 ```
 
-`updates.pre_update_backup` 是单一开关，有三种模式：`quick`（默认 — 上述轻量级状态快照）、`full`（快速快照加上完整的 `HERMES_HOME` zip 备份；在大型 home 目录上可能增加数分钟）、`off`（完全不做更新前备份 — `--no-backup` 对单次运行有相同效果）。旧版布尔值仍然有效：`true` 等同于 `full`，`false` 等同于 `off`。
+`updates.pre_update_backup` 有三种模式：
+
+- `quick` 保存上述指定的状态文件。这是默认模式。
+- `full` 另加一份遵循[备份排除规则](/reference/faq#hermes-backup-vs-hermes-profile-export)的 zip 归档。大型数据目录可能需要几分钟。
+- `off` 禁用更新前备份。`--no-backup` 为单次运行选择此模式。
+
+旧版布尔值仍然有效：`true` 等同于 `full`，`false` 等同于 `off`。
 
 ### Windows：另一个 `hermes.exe` 正在运行
 

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md

@@ -739,7 +739,9 @@ skills:
    ```bash
    hermes backup
    ```
-   这会将您整个 `~/.hermes/` 目录（配置、API key、记忆、技能、会话和 profiles）打包为 zip 文件，保存到主目录 `~/hermes-backup-<timestamp>.zip`。
+   归档保存到 `~/hermes-backup-<timestamp>.zip`。
+   完整备份涵盖 Hermes 数据根目录中的配置、凭据、记忆、技能、会话和 profiles。
+   它不是应用程序或运行时的完整镜像。
 
 3. 将 zip 文件复制到新机器并导入：
    ```bash
@@ -766,16 +768,31 @@ hermes profile import ./work-backup.tar.gz work
 
 导入的 profile 将包含导出时的所有配置、记忆、会话和技能。如果新机器的设置不同，您可能需要更新路径或重新向提供商进行身份验证。
 
-### `hermes backup` 与 `hermes profile export` 的对比
+### `hermes backup` 与 `hermes profile export` 的对比 {#hermes-backup-vs-hermes-profile-export}
 
 | 功能 | `hermes backup` | `hermes profile export` |
 | :--- | :--- | :--- |
 | **使用场景** | **整机迁移** | **移植/共享特定 profile** |
-| **范围** | 全局（整个 `~/.hermes` 目录） | 局部（单个 profile 目录） |
+| **范围** | Hermes 数据根目录，下列排除项除外 | 单个 profile 目录 |
 | **包含内容** | 所有 profiles、全局配置、API key、会话 | 单个 profile：SOUL.md、记忆、会话、技能 |
 | **凭据** | **包含**（`.env` 和 `auth.json`） | **排除**（为安全共享而剥离） |
 | **格式** | `.zip` | `.tar.gz` |
 
+完整备份不包含以下内容：
+
+- 源代码仓库、依赖环境，以及下载的工具、模型和运行时。
+- 构建缓存、checkpoints、旧备份和快速快照。
+- 浏览器配置目录，包括真实浏览器凭据的副本。
+- 字节码、SQLite 辅助文件，以及 `gateway.pid`、`cron.pid` 和 `.backup.lock`。
+
+`hermes backup --quick` 只保存指定的状态文件，不生成完整归档。
+迁移机器前，它不能替代完整备份。
+
+完整备份会报告复制失败的文件。因此，即使归档已生成，也可能缺少部分数据。
+删除源安装前，请检查跳过文件的报告。
+还原后的软件包声明可让 PM 再次下载依赖项。字节码和 SQLite 辅助文件在本地重新生成。
+上述排除项不会把 `.env` 和 `auth.json` 排除在完整备份之外。
+
 **手动备选方案（rsync）：** 如果您倾向于直接复制文件，请排除代码仓库：
 ```bash
 rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/