From f8f98ffd8010b48d654cab60a51b63a196bd8df1 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Sat, 26 Sep 2026 04:46:59 +0000
Subject: [PATCH 1/7] Rewrite the install docs around three steps: install,
 sign in, add a node

README starts with the three newcomer steps, each linking to one detailed guide.
docs/getting-started now covers installation (every install.sh option, Caddy and
nginx examples, a quick-tunnel trial, what is created on disk), nodes (the Web
command in sudo and no-sudo form, uninstall, logs, readiness codes), self-hosted
executors, operations (parsar, the Core key, backups, upgrades, troubleshooting)
and the application quickstart with OPENAI_BASE_URL and OPENAI_API_KEY.
docs/configuration.md lists the config.json settings and the runtime settings in
Web. HOSTED-SANDBOX-MANAGER.md becomes the operator reference without repeating
the guides.

The Docker-hosted Agents API archive could not carry a complete Runtime release,
so HOSTED-RELEASE.md and its build step are removed; the standalone archive and
container move under docs/maintainers.md. Distributions now carry a fixed list of
docs whose links stay inside the bundle or point at the bundle's commit on GitHub,
and the build fails on a broken link or anchor.
---
 CONTRIBUTING.md                               |  52 +-
 README.md                                     | 167 ++--
 docs/api/web-management.md                    |   2 +-
 docs/configuration.md                         | 388 ++++----
 docs/getting-started/README.md                |  40 +-
 docs/getting-started/install.md               | 857 +++++++-----------
 docs/getting-started/nodes.md                 | 248 +++++
 docs/getting-started/operations.md            | 562 ++++++------
 docs/getting-started/quickstart.md            | 158 ++--
 docs/getting-started/self-hosted.md           | 129 +++
 docs/maintainers.md                           |  77 ++
 scripts/build-agents-api-release.sh           |  37 +-
 scripts/build-core-distribution.sh            |  10 +-
 scripts/core-distribution-manifest.py         | 126 ++-
 scripts/core-distribution-manifest.test.py    |  46 +
 services/agents-api/CONTAINER.md              |   5 +-
 services/agents-api/HOSTED-RELEASE.md         | 188 ----
 services/agents-api/HOSTED-SANDBOX-MANAGER.md | 335 +++----
 services/agents-api/README.md                 |  32 +-
 services/agents-api/RELEASE.md                |  25 +-
 services/agents-api/deploy/codex/README.md    |  12 +-
 .../agents-api/deploy/microsandbox/README.md  |  10 +-
 .../tools/microsandbox-provider/README.md     |   9 +-
 site/index.html                               |  21 +-
 24 files changed, 1819 insertions(+), 1717 deletions(-)
 create mode 100644 docs/getting-started/nodes.md
 create mode 100644 docs/getting-started/self-hosted.md
 create mode 100644 docs/maintainers.md
 delete mode 100644 services/agents-api/HOSTED-RELEASE.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 62e94d8a5..ad5b15fc9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -826,7 +826,8 @@ as a user service, or, run as root, as a root-owned system service for the dedic
 `parsar-node` user it prepares; it performs no SSH installation, Session creation or
 model call.
 
-The [Hosted Sandbox Manager](services/agents-api/HOSTED-SANDBOX-MANAGER.md) is a
+Node management (Web's **Nodes** page; see the
+[operator reference](services/agents-api/HOSTED-SANDBOX-MANAGER.md)) is a
 deployment-level admin surface, separate from Project credentials. The paired
 console's Core key stays on its server. Enrollment credentials authorize
 initial node configuration reads and registration; durable node credentials authorize
@@ -1703,15 +1704,13 @@ packaged operators and public protocol, not private Store provisioning. Preserve
 the database and native history when replacing the API package. This target does
 not publish a release or provide an installer/supervisor.
 
-`AGENTS_API_RELEASE_RUNTIME_IMAGE=sha256:<image ID>` adds an explicitly qualified
-Linux amd64 Runtime to the same release builder. The Docker archive contains that
-immutable image export, the committed seccomp policy and hosted operator guide,
-with hashes in its manifest and checksums. The default Core-only archive remains
-Docker-free. Image selection and packaging do not qualify an arbitrary image or
-prove compatibility between unrelated Core/Runtime versions: accept the exact
-package with a fresh database, extracted binaries, loaded image and real public
-workflow. Keep model/operator credentials external and Provider ownership stable
-across upgrades. This is the same managed Runtime, not user-managed enrollment.
+The archive stays Docker-free. Its former Docker-hosted variant
+(`AGENTS_API_RELEASE_RUNTIME_IMAGE`) is retired and the builder refuses the variable:
+an image ID alone is not the complete Runtime release a Docker deployment needs.
+Docker-hosted deployments use the matched Core distribution below. The archive and
+the standalone container are advanced paths for running Core alone; keep them off the
+newcomer installation path and document them under
+[Maintainers and advanced deployments](docs/maintainers.md).
 
 #### Matched Core and console distribution
 
@@ -1742,8 +1741,21 @@ contract.
 The installer packages Core and the Web console together,
 with independent `--core-only` and `--web-only` modes. `site/` is the public static
 landing, separate from `apps/web`; it must not create an onboarding prerequisite,
-call a model, or claim complete protocol compatibility. Operator installation,
-optional API examples and service diagnostics live in `docs/getting-started/`.
+call a model, or claim complete protocol compatibility. The root README starts with
+the three newcomer steps (install, sign in and issue a key, add a node), each linking
+to `docs/getting-started/`: installation, nodes, self-hosted executors, operations and
+the application developer quickstart. `docs/configuration.md` is the single settings
+reference; building distributions and running Core alone live in `docs/maintainers.md`.
+Use Web's page and action names in docs, and `OPENAI_BASE_URL` and `OPENAI_API_KEY` for
+application examples.
+
+A distribution carries a fixed list of docs (`BUNDLED_DOCS` in
+`scripts/core-distribution-manifest.py`). The build keeps relative links between
+bundled docs, rewrites every other relative link to the same file on GitHub at the
+bundle's commit (`@SOURCE_REVISION@`), and fails on a link or anchor that does not
+resolve; `make check-distribution` runs the same check on the repository's docs. Keep
+the list self-consistent when adding or moving a doc the installer or its output
+refers to.
 
 `make build-core-distribution` builds from clean committed source and reuses the
 existing API, Runtime, SDK, helper and Web builders. Artifacts record source and
@@ -1884,8 +1896,8 @@ recovery path. Node services restart after failures without a start limit, so a
 outlasts a Core outage, and stop restarting when the node program exits 78
 because Core answered 401 to its credential (a removed or retired node).
 The basic API image and binary builds remain independent artifacts.
-The standalone API release and Core distribution both include the Hosted Sandbox
-Manager guide at the relative path used by their packaged README. Include the
+The standalone API release and Core distribution both include the nodes operator
+reference (`HOSTED-SANDBOX-MANAGER.md`) at the relative path used by their packaged README. Include the
 guide in each artifact checksum list so extracted documentation matches its build.
 The node asset includes the sandbox-node binary. The installer's Docker and
 microsandbox selections use Web's Standard size from
@@ -1940,13 +1952,13 @@ dialog, using the deployment's `core_url` (the installation public URL).
 Do not expose routine network wiring or manual runtime setup as the primary flow.
 Generate a one-time command only on user intent, never retry enrollment writes
 automatically, and discard credentials and late responses when the dialog closes
-or the Core connection changes. Web detects successful addition against the node
-IDs present before enrollment; an existing node reconnecting is not a new
-enrollment. Core also reports the command's `enrollment_id` on the node it
-registered (null for nodes enrolled before Core recorded it); Web's exact match on
-it lands with the Web follow-up.
+or the Core connection changes. Core reports the command's `enrollment_id` on the
+node it registered (null for nodes enrolled before Core recorded it), and Web follows
+the added node by an exact match on it; an existing node reconnecting is not a new
+enrollment.
 The command verifies the installer checksum before execution, retains normal TLS
-verification, and passes the enrollment credential only to the installer process.
+verification, and passes the enrollment credential only to the installer process,
+on standard input.
 
 
 The `/core/v1` proxy retains fixed-origin, cross-site, safe-path, redirect and Upgrade
diff --git a/README.md b/README.md
index 3c02f3eb0..361bc131c 100644
--- a/README.md
+++ b/README.md
@@ -4,101 +4,84 @@
 
 **Open-source Agents API infrastructure, with your choice of native harness.**
 
-Run Codex, Claude Code and MiniMax Code behind one execution API. Parsar Core
-owns Sessions, environments, files, credentials and execution history; each
-native harness keeps its own model and tool loop. Core runs independently of the
-Parsar product.
+Run Codex, Claude Code and MiniMax Code behind the OpenAI Agents API, on machines you
+control. Core serves the API and runs each Session in a sandbox; Web is the
+administrator console that issues the keys applications call Core with.
 
-Core and its administrator Web console ship together. Projects own assets; multiple
-API keys in one Project share its assets and execution principal. Projects and API
-keys live in the database. Management credentials cannot call the Agent API. The
-default installation runs Core, Web and PostgreSQL and selects Docker sandboxes,
-with zero execution nodes. Add execution nodes through Web when you are ready. Core creates each required sandbox from the shared Runtime image. Model
-credentials are supplied through the existing write-only API extension.
+## Get started
 
-Hosted deployments select E2B cloud or one provider across their own local/remote
-nodes (Docker or microsandbox). Web's **Nodes** page shows node health, capacity
-and Session placement. Core places new Sessions automatically; existing Sessions
-retain their node across disconnects and resume.
-
-## Start here
-
-1. **Install Core and Web.** Obtain and verify a matching Linux amd64 bundle,
-   then run its installer. For node access, choose a reachable HTTPS address
-   before the first install and configure your DNS/TLS reverse proxy:
+1. **Install Core and Web with one command.** On a Linux amd64 host with Docker,
+   download a release bundle and run its installer. The repository is internal for
+   now, so sign in to GitHub first. Pick `<tag>` from
+   `gh release list --repo MiniMax-AI/parsar-core`:
 
    ```sh
+   gh auth login
+   gh release download <tag> --repo MiniMax-AI/parsar-core --pattern '*-linux-amd64-offline.tar.gz*'
+   sha256sum -c parsar-core-<commit>-linux-amd64-offline.tar.gz.sha256
+   tar -xzf parsar-core-<commit>-linux-amd64-offline.tar.gz
+   cd parsar-core-<commit>-linux-amd64
    ./install.sh --public-url https://core.example
    ```
 
-   This starts Core, Web and PostgreSQL and selects Docker sandboxes at Web's
-   Standard size, with zero execution nodes; `--sandbox` chooses microsandbox, E2B
-   or none instead. The installer never adds this host as a node. Release
-   bundles are tied to a source revision; an older published bundle does not include
-   current management changes. See the [installation guide](docs/getting-started/install.md)
-   for obtaining/building a matching bundle and the host/network prerequisites.
-2. **Sign in to Web.** Open the console address printed by the installer and
-   sign in with the [Core key](docs/getting-started/operations.md#core-key) from
-   `~/.parsar/core/secrets/core.key`. Keep it private. The console connects to Core
-   automatically. Create a Project on the **Projects and keys** page, then
-   issue a key within it for your application. Save the one-time plaintext
-   response privately; Core stores its digest. Rotate by issuing another key in the
-   same Project and revoking the old one.
-3. **Add a node.** Open **Nodes**, select **Add node**, and copy and run the
-   command on a prepared Linux host, this one included. Web shows when the node is
-   online and its provider is ready. All nodes in a deployment use the same
-   provider. Nodes need the HTTPS public URL: a loopback installation keeps its
-   sandbox selection but can't add nodes until `public_url` is set. After
-   `--sandbox none`, **Nodes** first asks for E2B cloud (its account key and a ready
-   template build, with no node installation) or your own machines with
-   Docker/microsandbox and a sandbox size; finish with **Save configuration**.
-
-Installation and node enrollment do not call a model. Once a node is ready,
-run an optional API example with your own model credentials.
-
-- [Configuration reference](docs/configuration.md)
-- [API documentation: public API and Web management](docs/api/README.md)
-- [Make your first API request](docs/getting-started/quickstart.md)
-- [Service health, data and operations](docs/getting-started/operations.md)
-- [Hosted Sandbox Manager](services/agents-api/HOSTED-SANDBOX-MANAGER.md)
-- [Protocol coverage and native differences](contracts/agents-api/README.md)
-- [Add or select a harness](contracts/agents-api/harness-selection.md)
-- [Public landing page source](site/index.html)
-
-### Other installation options
-
-Run these from an extracted distribution. The plain command uses loopback for
-local console/API access. For node enrollment, use the reachable origin described
-above. Flags only seed the installation's `config.json`; later changes go there
-and take effect with `~/.parsar/core/parsar apply`, and `parsar status`, `start`
-and `stop` replace `install.sh --status` and `--stop`.
-`--sandbox` is a one-time choice of the sandbox backend, saved in the database like
-Web's setup; change it later in Web. `--sandbox-provider` and `--provider` are
-retired: the installer no longer adds its own host as a node.
-
-```sh
-./install.sh                    # Core + Web + PostgreSQL, loopback access, Docker sandboxes, zero nodes
-./install.sh --core-only        # Core + PostgreSQL, Docker sandboxes, zero nodes
-./install.sh --sandbox microsandbox --public-url https://core.example
-./install.sh --sandbox e2b --e2b-api-key-file "$HOME/e2b-api-key" \
-  --e2b-template '<template-id>:<build-uuid>' --public-url https://core.example
-./install.sh --sandbox none     # choose the sandbox backend in Web later
-```
-
-Web-only installation connects the console server to an existing Core; see the
-installation guide for its URL and private credential-file options. Installation
-creates no Project or application key, never creates a sample Session and calls no
-model. Configuration files hold deployment settings, not business identities. API
-examples are optional.
-
-The protocol baseline is `openai-python` 3.13.0 and `agents=v1`. Harness selection,
-model execution configuration and our daemon transport are documented differences.
-A passing workflow does not establish complete OpenAI Agents API compatibility.
+   Put your HTTPS reverse proxy in front first, or install without `--public-url` for a
+   local trial and set it later. See the [installation guide](docs/getting-started/install.md).
+2. **Sign in to Web with the Core key**, from `~/.parsar/core/secrets/core.key`. On
+   **System**, set a default model; on **Projects and keys**, create a project and
+   issue a key. See [Sign in to Web](docs/getting-started/install.md#sign-in-to-web).
+3. **Add a node by pasting one command.** On **Nodes**, choose **Add node**, then
+   **Generate command**, and run the command on a Linux host with sudo. See
+   [Nodes](docs/getting-started/nodes.md).
+
+Applications then set `OPENAI_BASE_URL` to `https://core.example/v1` and
+`OPENAI_API_KEY` to the Project API key, and use the official OpenAI SDK; see
+[Call the API](docs/getting-started/quickstart.md).
+
+## What you get
+
+- **One API, several harnesses.** Core implements part of the pinned OpenAI Agents API
+  (`openai-python` 3.13.0, `agents=v1`). Each Session runs a native harness, Codex,
+  Claude Code or MiniMax Code, which keeps its own model and tool loop. Core's additions
+  live only in `x_agents_core`: the harness and the model provider.
+- **Durable execution.** Core owns Agents, Sessions, Turns, Items, environments, files
+  and credentials, in its own PostgreSQL database.
+- **Your sandboxes.** Core-hosted Sessions run in sandboxes on your nodes (Docker or
+  microsandbox microVMs) or on E2B. Applications can also connect their own machines as
+  self-hosted executors.
+- **A console for administrators.** Web signs in with the Core key, issues Project API
+  keys, adds nodes, sets default models and shows metrics and Session history. It
+  never runs Agents on anyone's behalf.
+- **Independent of the Parsar product.** Core needs no product service or database.
+
+A passing workflow does not establish complete OpenAI Agents API compatibility; the
+[protocol coverage](contracts/agents-api/README.md) records what is qualified and the
+native differences.
+
+## Documentation
+
+| Page | Covers |
+| --- | --- |
+| [Install Core and Web](docs/getting-started/install.md) | Prerequisites, download, installer options, HTTPS and the reverse proxy, first sign-in |
+| [Nodes](docs/getting-started/nodes.md) | Adding, removing and troubleshooting nodes |
+| [Self-hosted executors](docs/getting-started/self-hosted.md) | Connecting an application's own machine to a Session |
+| [Operations](docs/getting-started/operations.md) | The `parsar` command, the Core key, backups, upgrades, troubleshooting |
+| [Configuration reference](docs/configuration.md) | Every setting in `config.json` and in Web |
+| [Call the API](docs/getting-started/quickstart.md) | The application developer's quickstart |
+| [API reference](docs/api/README.md) | The `/v1`, `/core/v1` and `/api/v1` namespaces |
+| [Nodes and sandbox backends: operator reference](services/agents-api/HOSTED-SANDBOX-MANAGER.md) | Node protocol, manual registration, placement, maintenance |
+| [Protocol coverage](contracts/agents-api/README.md) and [harness selection](contracts/agents-api/harness-selection.md) | Supported operations and native differences |
+| [Landing page source](site/index.html) | The public site |
+
+### Maintainers and advanced deployments
+
+Building distributions, producing releases and running Core alone, without Web or the
+installer, are described in [Maintainers and advanced deployments](docs/maintainers.md).
+The standalone Core archive and container are not an installation path for new users.
 
 ## Develop and build
 
 The repository includes the API, its independent PostgreSQL migrations, daemon,
-Runtime/provider adapters, clients, Web console and distribution tools. It has no
+Runtime and provider adapters, clients, Web console and distribution tools. It has no
 Parsar product service, product database or business-user dependency.
 
 ```sh
@@ -107,17 +90,17 @@ make build-daemon
 pnpm dev:web
 ```
 
-Use the toolchain pinned in `go.mod`, Node 22 and pnpm 10.30.3. Build output goes
-under `~/.parsar/build/`. For advanced deployment, see the
-[service guide](services/agents-api/README.md),
+Use the toolchain pinned in `go.mod`, Node 22 and pnpm 10.30.3. Build output goes under
+`~/.parsar/build/`. See the [service guide](services/agents-api/README.md),
 [Docker Runtime](services/agents-api/deploy/codex/README.md),
-[microsandbox provider](services/agents-api/deploy/microsandbox/README.md), and
+[microsandbox provider](services/agents-api/deploy/microsandbox/README.md) and
 [Web development guide](docs/web/README.md).
 
-Core-managed and user-managed environments reuse the colocated daemon, native
-harness, tools and workspace. Caller-owned E2B provisioning uses the official SDK; deployment-managed E2B
-uses the configured SandboxProvider. For caller-owned environments, the returned `remote_url` connects our daemon, not `exec-server`.
-See the [Runtime enrollment guide](services/agents-api/README.md#user-managed-runtime-enrollment).
+Core-managed and user-managed environments reuse the colocated daemon, native harness,
+tools and workspace. Caller-owned E2B provisioning uses the official SDK;
+deployment-managed E2B uses the configured sandbox provider. For caller-owned
+environments, the returned `remote_url` connects our daemon, not `exec-server`. See the
+[Runtime enrollment guide](services/agents-api/README.md#user-managed-runtime-enrollment).
 
 Read [CONTRIBUTING.md](CONTRIBUTING.md) before developing. Historical source-copy
 provenance is retained in [provenance/README.md](provenance/README.md). Existing Go
diff --git a/docs/api/web-management.md b/docs/api/web-management.md
index 4a25ee63d..4725fa397 100644
--- a/docs/api/web-management.md
+++ b/docs/api/web-management.md
@@ -70,7 +70,7 @@ it is operational attribution, not per-key billing.
 ## Sandbox administration
 
 The [deployment configuration contract](../../contracts/agents-api/sandbox-deployment.md),
-[Hosted Sandbox Manager reference](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md)
+[nodes and sandbox backends reference](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md)
 and [generated OpenAPI](../../contracts/agents-api/core.openapi.yaml)
 define deployment and node operations:
 
diff --git a/docs/configuration.md b/docs/configuration.md
index da77a98c5..399f33394 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,91 +1,76 @@
-# Configuration
+# Configuration reference
 
-This is the configuration reference for Core, Web, hosted nodes and the execution
-daemon. Installation and operations guides describe workflows and link here for
-parameters. Each setting has one home; reinstalling does not restore defaults.
+Every setting of a Core installation has exactly one home. There are two kinds:
 
-## Ownership and changes
+| Kind | Examples | Home | Change it with | Takes effect |
+| --- | --- | --- | --- | --- |
+| [Process settings](#process-settings-configjson) | Public URL, ports, logging, harnesses, execution concurrency, audit retention, OAuth origins, database pool, Runtime history export | `config.json` in the installation directory (default `~/.parsar/core`) | Edit the file, then run `parsar apply` | `parsar apply` restarts the services that read the changed settings |
+| [Runtime settings](#runtime-settings-web) | Sandbox backend and size, nodes, Projects and keys, default models, executor credentials | Core's PostgreSQL database | Web, or the Core API (`/core/v1`) with the Core key | At once, without a restart |
 
-| Settings | Home | How changes take effect |
-| --- | --- | --- |
-| Core and Web process settings: public URL, ports, logging, execution concurrency, harnesses, audit retention, OAuth origins, database pool, Runtime history | `<installation>/config.json` | Edit the file, then run `<installation>/parsar apply` |
-| Core key | `<installation>/secrets/core.key` | `parsar rotate-core-key` ([rotation](getting-started/operations.md#rotate-the-core-key)) |
-| Credential encryption key and database password | `<installation>/secrets/` | Fixed after installation; `parsar apply` refuses a changed file |
-| Hosted provider, uniform guest resources, immutable Runtime specification, E2B credentials | Core PostgreSQL | Web or deployment API; existing maintenance/generation checks |
-| Node registration and sandbox capacity | Core PostgreSQL | Administrator enrollment and node updates |
-| Node host paths, Docker socket and local network wiring | Node `provider.json` | Edit host-local fields; restart the node |
-| Downloaded deployment specification | `specification` in node `provider.json` | Validated copy only; must match Core's digest |
-| Daemon connection, identity and execution preparation | Hosted bootstrap or self-hosted registration | Generated automatically; reuse identity across restart |
-
-There is no node enable/disable switch. Registration and guarded removal control
-membership. Core execution concurrency limits concurrent execution and directory/file
-work; node capacity limits reserved/running sandboxes. They are independent.
+Web's **System** page shows both: the installation's addresses, the process settings
+read-only with the path of `config.json` and the apply command, the default models,
+and the sandbox configuration. Secrets live in [`secrets/`](#secrets-and-identity),
+one copy each. No setting is stored twice, and no configuration file defines Projects
+or API keys.
 
-## Installation directory
+## Process settings: config.json
 
-The installer creates the installation directory (default `~/.parsar/core`) with
-mode `0700`. Keep every file in it private to the installation user.
-
-| Path | Content |
-| --- | --- |
-| `config.json` | Operator settings; the only file you edit |
-| `parsar` | Management command: `status`, `start`, `stop`, `apply`, `rotate-core-key` |
-| `secrets/` | `core.key`, `credential.key` and `database.password`, one copy each |
-| `state.json` | Installation ID, Compose project, images and the digests of written files; written by tools only |
-| `generated/` | Files derived from `config.json`: `compose.json`, `core.env`, `core-key-digests.json`, `settings.json`, the native unit and `runtime-history.json` when set |
-| `state/e2b/`, `native/`, `node-payload/` | E2B receipts, native Core binaries and the public node payload |
-
-`parsar apply` overwrites `generated/` and records the digests of the files it
-writes. A generated file that matches neither those digests nor what `config.json`
-renders now was edited by hand: `apply` refuses to run until you move the change
-into `config.json` and run `parsar apply --discard-edits`, which keeps the edited
-copy as `generated/<file>.edited-<time>`. A missing generated file is simply
-written again. `parsar status` reports edited files, `config.json` changes that are
-not applied yet and services that run with other inputs than `config.json` renders.
-
-## config.json
-
-The installer writes every setting that applies to the installation's mode, so
-the file shows each value. Installation flags such as `--public-url`,
-`--core-port` and `--web-port` only seed it; `install.sh --config FILE` seeds it
-from a prepared file instead. Afterwards edit it and run:
+The installer writes every setting that applies to the installation's
+[mode](getting-started/install.md#modes), so the file shows each value. Installer flags
+such as `--public-url`, `--core-port` and `--web-port` only seed it. To change a
+setting, edit the file and apply it:
 
 ```sh
-~/.parsar/core/parsar apply --dry-run   # show changed settings, files and restarts
+~/.parsar/core/parsar apply --dry-run   # show the changed settings, files and restarts
 ~/.parsar/core/parsar apply
 ```
 
-`apply` validates the file first and changes nothing when a value is invalid. It
-then writes the generated files and compares them with what actually runs: each
-Compose container carries the digest of its inputs in the `io.parsar.inputs`
-label, and native Core carries it as `PARSAR_INPUTS` in its process environment.
-`apply` recreates or restarts exactly the services whose running inputs differ,
-Core first, then Web; a Web restart ends every Web sign-in session. When no service
-runs (after `parsar stop`), `apply` only writes the files and the installation
-stays stopped; while any service runs, `apply` also starts the ones that are
-stopped. Because the comparison is with what runs, an interrupted `apply`,
-rotation or rollback is finished by the next `apply`. If Core rejects a value at
-startup and every service was running with the previous files, `apply` restores
-those files, converges on them again and prints Core's startup error line;
-otherwise it reports the failure and leaves the next `apply` to finish. `mode` and
-`native_core` are fixed; install into a new directory to change them. `state.json`
-records both at installation and wins: `apply` refuses a `config.json` that differs,
-and `parsar status` reports it.
-
-Changing `public_url` moves everything Core derives from it: the daemon
-WebSocket URL, the self-hosted `remote_url`, the hosted sandbox bootstrap URL and
-node configuration. When nodes, hosted sandboxes or self-hosted executors are bound
-to the current address, `apply` lists them and asks you to type the new URL
-(`--confirm-public-url-change URL` when non-interactive); it also asks when the
-applied value can't be read. Nodes on the old address
-then get no new sandboxes and must be removed and added again. With
-`public_url: null`, Core uses `http://127.0.0.1:<ports.core>` and only local access
-works; set a real HTTPS URL later without reinstalling.
-
-`core.runtime_history.headers` may hold export credentials. They stay in the 0600
-`config.json` and the generated file Core reads, and never appear in `parsar`
-output or in Core's settings snapshot. Model provider settings are not part of
-`config.json`.
+### How parsar apply works
+
+1. It validates `config.json` and changes nothing if a value is invalid. `mode` and
+   `native_core` are fixed after installation; to change them, install into a new
+   directory.
+2. It writes the files Core, Web and Compose read into `generated/`: `compose.json`,
+   `core.env`, `core-key-digests.json`, `settings.json` and, when used,
+   `runtime-history.json` and the native Core unit. Don't edit them. A generated file
+   edited by hand stops `apply` until you move the change into `config.json` and run
+   `parsar apply --discard-edits`, which keeps the edited copy as
+   `generated/<file>.edited-<time>`.
+3. It compares what it wrote with what actually runs. Each container carries a digest
+   of its inputs (the `io.parsar.inputs` label; native Core carries `PARSAR_INPUTS`),
+   and `apply` recreates or restarts exactly the services whose inputs differ: Core
+   first, then Web. The **Restarts** column below says which services a setting
+   affects. Restarting Web signs everyone out of the console.
+4. While any service runs, `apply` also starts the stopped ones. After `parsar stop`,
+   it only writes the files and the installation stays stopped.
+5. If Core refuses a value at startup, `apply` prints Core's startup error. If every
+   service was running with the previous files, it restores them and starts the
+   services again; otherwise it reports the failure, and the next `apply` finishes
+   the work.
+
+`parsar status` reports changes to `config.json` that are not applied yet and
+generated files edited by hand.
+
+### Changing the public URL
+
+`public_url` is the one origin that applications, nodes, sandboxes and self-hosted
+executors use; Core derives the daemon WebSocket URL, the self-hosted `remote_url` and
+each sandbox's connection address from it. With `null`, Core uses
+`http://127.0.0.1:<ports.core>` and only this host can reach it.
+
+You can set or change it at any time with `parsar apply`. When nodes, hosted
+sandboxes or self-hosted executors are bound to the current address, `apply` lists
+them and asks you to type the new URL (`--confirm-public-url-change URL` when not
+interactive). Afterwards, nodes on the old address get no new sandboxes: remove them
+in Web and add them again. Existing sandboxes and executors keep working only while
+the old address still reaches this Core. Update your reverse proxy first.
+
+### Settings
+
+`core.runtime_history.headers` may hold export credentials. They stay in the
+`0600` `config.json` and the generated file Core reads, and never appear in `parsar`
+output or in Core's settings snapshot. Model providers are not process settings; see
+[Default models](#default-models).
 
 <!-- BEGIN config-reference: generated by scripts/config-reference.py from deploy/install/config.schema.json -->
 | Key | Type | Default | Modes | Change | Restarts | Meaning |
@@ -122,147 +107,130 @@ output or in Core's settings snapshot. Model provider settings are not part of
 | `core.runtime_history.sample_interval_seconds` | integer | none | `all`, `core-only` | `parsar apply` | core | Periodic sampling interval in seconds. |
 <!-- END config-reference -->
 
-The schema is `deploy/install/config.schema.json`; the installation keeps a copy
-in `generated/config.schema.json` for editors. Core serves the non-secret settings
-snapshot, with the path of `config.json` and the apply command, at
-`GET /core/v1/installation`.
+The schema is [`deploy/install/config.schema.json`](../deploy/install/config.schema.json);
+each installation keeps a copy in `generated/config.schema.json` for editors. Core
+serves the non-secret settings snapshot, with the path of `config.json` and the apply
+command, at `GET /core/v1/installation`.
+
+## Runtime settings: Web
+
+Runtime settings live in Core's database. Change them in Web; scripts use the same
+Core API with the Core key.
+
+| Setting | Where in Web | Core API | Notes |
+| --- | --- | --- | --- |
+| Sandbox backend: Docker, microsandbox or E2B | **Nodes** (**Sandbox backend** with E2B): the setup wizard, ending with **Save configuration** | `/core/v1/sandbox/deployment` | One backend per deployment. `install.sh --sandbox` saves the first choice. Changing it needs [maintenance](#sandbox-deployment) |
+| Sandbox size and Runtime release | **Nodes**: the setup wizard | `/core/v1/sandbox/deployment` | Every sandbox gets the same size. See [Sandbox deployment](#sandbox-deployment) |
+| E2B API key and template build | **Sandbox backend**: the setup wizard | `/core/v1/sandbox/deployment` | The key is write-only and encrypted |
+| Maintenance | **Nodes**: **Enter maintenance to change provider**, **Resume hosted placement** | `PATCH /core/v1/sandbox/deployment/maintenance` | Pauses new hosted sandboxes while you change the backend |
+| Nodes and their capacity | **Nodes**: **Add node**, **Edit node**, **Remove node** | `/core/v1/sandbox/enrollment-tokens`, `/core/v1/sandbox/nodes` | See [Node capacity](#node-capacity) and the [nodes guide](getting-started/nodes.md) |
+| Projects and API keys | **Projects and keys**: **Create project**, **Issue key**, **Revoke**, **Archive** | `/core/v1/projects` | Keys are shown once; Core stores digests |
+| Default model per harness | **System**: **Default model** | `/core/v1/harnesses/{harness}/model-provider` | See [Default models](#default-models) |
+| Executor credentials of a self-hosted Session | **Session log**, the Session's page: **Executor credentials** | `/core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials` | See [self-hosted executors](getting-started/self-hosted.md) |
+
+Which harnesses are enabled, and the default one, are process settings
+(`core.harnesses`, `core.default_harness`); System shows them read-only. The
+[API index](api/README.md#core-api) lists every Core API route.
+
+### Sandbox deployment
 
-## Core environment for standalone Core
+Exactly one provider serves the deployment: Docker, microsandbox or E2B. The
+deployment specification holds the per-sandbox resources and, for Docker and
+microsandbox, the Runtime release. Web's setup proposes the Standard size from
+[`standard-sizes.json`](../apps/web/src/features/sandbox/standard-sizes.json) and
+derives Small and Large from it; the installer applies the bundle's copy of the same
+file. The database owns the saved values.
 
-Core reads only its environment. The installer generates `generated/core.env`
-from `config.json`; operators who run Core without the installer set these names
-themselves. Compose loads the file with `env_file` and systemd with
-`EnvironmentFile`, so Compose must be **2.26.0 or newer**.
+| Setting | Standard | Meaning |
+| --- | --- | --- |
+| `resources.cpus` | 2 | Whole vCPUs per sandbox, 1 through 255 |
+| `resources.memory_mib` | Docker 2048, microsandbox 4096 | MiB per sandbox, 512 through 1048576 |
+| `resources.root_disk_mib`, `environment_disk_mib` | microsandbox 8192 each | At least 1024 MiB; microsandbox only |
+| `runtime` | The bundle's Runtime release | Source revision, exact image ID and manifest, and Runtime and firmware hashes; never a mutable tag |
+| Idle suspension, snapshot retention | 300 and 86400 seconds | microsandbox only; fixed |
+
+E2B takes no `runtime`, and Web sends no resources for it: Core adopts the CPU and
+memory of the ready template build `template-id:build-uuid`, and supplied values must
+match it. Docker has no separate disk quota.
+
+Changing the provider, the size or the Runtime is a deployment-wide procedure: enter
+maintenance, let or make every hosted sandbox finish and clean up, save the new
+configuration against the current generation, then resume. A successful change
+retires the old nodes and enrollment commands; history stays. Nothing is deleted
+automatically, and existing Sessions never move between providers. See
+[maintenance](../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
+and the [deployment contract](../contracts/agents-api/sandbox-deployment.md).
+
+### Node capacity
+
+Core approves a node's capacity when you generate its Add node command: **Sandboxes
+at once** (`max_active`, default 2) and **Retained sandboxes** (`max_retained`,
+default 8), with `max_retained >= max_active >= 1`. Change them later with
+**Edit node**. Reservations and cleanup that is not confirmed count against capacity;
+lowering a limit stops no running sandbox. Docker never suspends sandboxes, so its
+`max_retained` always equals `max_active`. A node's own files can't change its
+capacity, size or Runtime.
+
+`core.execution_concurrency` is unrelated: it limits concurrent execution work in Core.
+
+### Default models
+
+Each harness has at most one default model provider: `protocol`, HTTPS `base_url`,
+a write-only `api_key` and, for MiniMax Code, `context_window` and
+`max_output_tokens`. It is the same bundle as `x_agents_core.model_provider`. Core
+encrypts it with `secrets/credential.key` and never returns the key.
+
+New Core-hosted (`openai_hosted`) Sessions and Sessions without an environment
+(`none`) use it when neither the request nor the Agent carries a provider; each
+Session freezes the provider it starts with, so a later change affects only new
+Sessions. Self-hosted Sessions never use it. A hosted or self-hosted Session with no
+provider is refused with 400 `model_provider_required`. See
+[model providers](getting-started/quickstart.md#model-providers) and the
+[model execution contract](../contracts/agents-api/model-execution.md#deployment-defaults).
+
+The operator file `AGENTS_API_EXECUTION_OPTIONS_FILE` is retired; see
+[Upgrade notes](getting-started/operations.md#upgrade-notes).
+
+## Secrets and identity
+
+| File | Content | Changed by |
+| --- | --- | --- |
+| `secrets/core.key` | The [Core key](getting-started/operations.md#core-key) | `parsar rotate-core-key` |
+| `secrets/credential.key` | Encryption key for credentials stored in the database: model providers, E2B key, Vault credentials | Nothing. Keep it with the database; `parsar apply` refuses a changed file |
+| `secrets/database.password` | PostgreSQL password | Nothing. PostgreSQL reads it only when the database is created; `parsar apply` refuses a changed file |
+| `state.json` | Installation ID, Compose project, image IDs, source commit and the digests of generated files | The tools only |
+
+A Web-only installation has only `secrets/core.key`, a copy of its Core's key.
+
+## Appendix: Core environment without the installer
+
+Core reads only its environment. The installer renders `generated/core.env` from
+`config.json`; if you run Core yourself (see
+[Maintainers and advanced deployments](maintainers.md)), set these variables. Compose
+loads the file with `env_file` and systemd with `EnvironmentFile`, so Compose must be
+2.26.0 or newer.
 
 | Variable | Set from |
 | --- | --- |
-| `AGENTS_API_PUBLIC_URL` | `public_url`, or Core's loopback origin. The one origin applications, nodes, sandbox guests and self-hosted executors use; Core derives the daemon WebSocket URL, the self-hosted `remote_url`, the hosted bootstrap and the deployment's read-only `core_url` from it. Required with `AGENTS_API_SANDBOX_INSTALLATION_ID` |
+| `AGENTS_API_PUBLIC_URL` | `public_url`, or Core's loopback origin. Core derives the daemon WebSocket URL, the self-hosted `remote_url`, the hosted sandbox address and the deployment's read-only `core_url` from it. Required with `AGENTS_API_SANDBOX_INSTALLATION_ID` |
 | `AGENTS_API_ADDR` | `ports.core` (native Core) or the container port |
 | `AGENTS_API_DATABASE_URL` | The installation's PostgreSQL without a password, plus `core.database_pool` as `pool_*` query parameters |
-| `AGENTS_API_DATABASE_PASSWORD_FILE` | `secrets/database.password`. `AGENTS_API_DATABASE_URL` must then not contain a password; migrations and the maintenance commands read the file too |
-| `AGENTS_API_CREDENTIAL_KEY_FILE` | `secrets/credential.key`; never regenerate it to repair credentials |
-| `AGENTS_API_CORE_KEY_DIGESTS_FILE` | `generated/core-key-digests.json`, the SHA-256 of the [Core key](getting-started/operations.md#core-key) |
+| `AGENTS_API_DATABASE_PASSWORD_FILE` | `secrets/database.password`. The URL must then carry no password; migrations and the maintenance commands read the file too |
+| `AGENTS_API_CREDENTIAL_KEY_FILE` | `secrets/credential.key` |
+| `AGENTS_API_CORE_KEY_DIGESTS_FILE` | `generated/core-key-digests.json`: a JSON array with the SHA-256 of the Core key |
 | `AGENTS_API_SANDBOX_INSTALLATION_ID` | `state.json`; pinned to the database |
 | `AGENTS_API_SETTINGS_FILE` | `generated/settings.json`, the snapshot Core serves at `GET /core/v1/installation`; Core does not act on it |
 | `AGENTS_API_EXECUTION_CONCURRENCY`, `AGENTS_API_ENGINE`, `AGENTS_API_HARNESSES`, `AGENTS_API_WRITE_AUDIT_RETENTION`, `AGENTS_API_OAUTH_TRUSTED_ORIGINS` | The matching `core.*` settings |
 | `AGENTS_API_RUNTIME_HISTORY_FILE` | `generated/runtime-history.json` when `core.runtime_history` is set; see the [history contract](../contracts/agents-api/runtime-history-api.md) |
 | `PARSAR_LOG_LEVEL`, `PARSAR_LOG_FORMAT`, `PARSAR_LOG_ADD_SOURCE` | `log.*`; Web reads the same three |
-| `AGENTS_API_E2B_STATE_DIR`, `AGENTS_API_E2B_PROVIDER_BIN` | Receipt directory and, for native Core, the bundled helper; the E2B account credential and template belong to the database |
-
-`AGENTS_API_DAEMON_WS_URL` is retired in favor of `AGENTS_API_PUBLIC_URL`,
-`AGENTS_API_CONFIG_FILE` with no replacement, and `AGENTS_API_EXECUTION_OPTIONS_FILE`
-in favor of [deployment model providers](#deployment-model-providers); Core fails at
-startup while any of them is set and says what to do. Core reports loaded file
-paths on startup, without environment values or file contents. Internal
-polling/queue controls remain internal. Runtime history retention remains its
-existing fixed policy.
-
-Native installation paths must be canonical absolute paths without control
-characters, quotes, backslashes or wildcard characters. Do not change the
-installation UUID or backend paths as a substitute for provider maintenance. Core
-refuses a missing installation setting when its database already has a claimed
-deployment.
-
-## Deployment model providers
-
-Each harness has at most one deployment default model provider, stored encrypted in
-PostgreSQL and set with the Core key in Web or through
-`PUT /core/v1/harnesses/{harness}/model-provider`. It takes the same complete
-bundle as `x_agents_core.model_provider` (`protocol`, HTTPS `base_url`, write-only
-`api_key` and, for MiniMax Code, `context_window` and `max_output_tokens`). New
-`openai_hosted` and `none` Sessions without a Session or Agent bundle freeze it;
-`self_hosted` Sessions never use it, and a hosted or self-hosted Session with no
-bundle is rejected with 400 `model_provider_required`. Reads never return the key.
-See [model execution](../contracts/agents-api/model-execution.md#deployment-defaults).
-
-## Database-owned deployment
-
-Exactly one provider serves the deployment: Docker, microsandbox or E2B. A new
-installation selects it once with `install.sh --sandbox` (Docker unless chosen
-otherwise, none with `--web-only`); afterwards Web or `/core/v1/sandbox/deployment`
-change it. Core packaging is independent: `--native-core` does not select
-microsandbox or add an execution node.
-
-Setup requests supply `resources` and, for Docker/microsandbox, the matching
-`runtime` release. Core saves them as `specification` with a digest and generation.
-Web's setup and the installer propose the Standard size from Web's
-`apps/web/src/features/sandbox/standard-sizes.json` (bundled as
-`standard-sizes.json`); Web derives Small and Large from it. PostgreSQL owns the
-submitted values.
-See the [deployment contract](../contracts/agents-api/sandbox-deployment.md) for
-request shapes, immutable identities and provider validation.
-
-| Setting | Standard | Meaning |
-| --- | --- | --- |
-| `resources.cpus` | Per provider in `standard-sizes.json` | Integer vCPUs per sandbox, 1 through 255 |
-| `resources.memory_mib` | Per provider in `standard-sizes.json` | MiB per sandbox, 512 through 1048576 |
-| `resources.root_disk_mib`, `environment_disk_mib` | Microsandbox only, in `standard-sizes.json` | At least 1024 MiB; omitted for Docker/E2B |
-| `runtime` | Matching distribution manifest | Source revision, exact image ID/manifest/ref and runtime/firmware hashes; no mutable tags |
-| Idle interval / snapshot retention | `300` / `86400` seconds | Database-owned microsandbox policy; no node-file override |
-
-E2B resources are optional, and Web sends none: Core then adopts the CPU and memory
-of the ready immutable `template-id:build-uuid`. Supplied values must match that
-build. Omit `runtime`. The E2B account key is encrypted and write-only.
-E2B template storage remains native; Docker has no independent hard disk quota.
-A submitted limit must be enforceable by its provider.
-
-Changing provider, Runtime or guest specification uses the existing explicit
-maintenance procedure: stop fresh hosted admission, settle all retained and pending
-resources, then save against the current generation. A failed check changes
-nothing and deletes nothing. Successful replacement retires old nodes and tokens.
-Explicitly resume, then issue enrollment tokens and register nodes for the new
-generation; maintenance blocks enrollment as well as hosted admission. Hosted
-requests need an online eligible node before they can be accepted. Existing Sessions do not
-migrate between providers. See [maintenance](../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance).
-
-## Node configuration and capacity
-
-Use Web's **Add node** command on a Linux host, including the Core host. Core
-approves capacity when issuing its enrollment token: defaults are **2 active** and
-**8 retained** sandboxes. An administrator may update capacity later through the
-node API. `max_retained >= max_active >= 1`; reservations and uncertain cleanup
-also consume capacity. Lowering a limit does not kill existing resources.
-Microsandbox uses both limits. Docker never suspends, so its `max_retained` always
-equals `max_active`; Core replaces any submitted value.
-
-The generated private `provider.json` includes the provider, installation identity,
-Core address (the installation public URL when the node enrolled), generation,
-approved specification copy and one adapter object:
-
-- Docker: explicit Unix `host`, locally imported `image`, `network`, `extra_hosts`
-  and absolute `seccomp_file`, with the existing nested-sandbox security settings.
-  The imported image must match the approved Runtime release.
-- Microsandbox: absolute `helper_path`, `runtime_home`, `runtime_path` and
-  `firmware_path`, host network policy and validated resource/Runtime copies.
-  The runtime home is an existing private backend namespace.
-
-The node has no `max_active`, `max_retained`, idle-policy or maintenance override.
-Editing the downloaded spec does not change Core. The node validates the content
-and file hashes, and Core compares its digest on enrollment and every connection.
-Mismatch rejects work until the approved configuration is restored. Reconnect
-reads current database capacity; it never writes local limits back to Core.
-
-Keep the private identity/state directory and backend storage together. Do not
-copy node identities, replace a backend directory, or delete snapshots to fix a
-connection problem. Reinstall retains local configuration and identity; changes
-in provider, installation, Core address or release are refused. This is not an
-upgrade or cross-provider migration tool. Core records the address each node
-enrolled with. After the installation public URL changes, such a node receives no
-new sandboxes: remove it in Web and add it again with a fresh state directory.
-
-## Daemon and identity
-
-Hosted Runtime initialization supplies the daemon's connection and identity;
-execution preparation supplies the selected harness configuration through its
-adapter. Self-hosted installation registers once, stores its restricted identity
-and reuses it on restart. Administrators do not maintain another daemon config
-file. `environment.json` records identity and ownership; do not hand-edit it into
-an execution configuration source. Retain credentials, native history, private
-receipts and files independently of process configuration.
-
-The old `AGENTS_API_MANAGED_RUNTIMES_FILE`, embedded Core node and local-node Core
-environment overrides are retired and rejected. Installation selects the sandbox
-backend through the same administrator API as Web and never adds a node; every host,
-the Core host included, joins through Web's Add node. `--sandbox` is a one-time
-setup input, never a persisted override. No old file-managed deployment is migrated
-or adopted.
+| `AGENTS_API_E2B_STATE_DIR`, `AGENTS_API_E2B_PROVIDER_BIN` | The E2B receipt directory and, for native Core, the bundled helper. The E2B key and template live in the database |
+
+Core fails at startup, naming the replacement, while a retired variable is set:
+`AGENTS_API_DAEMON_WS_URL` (use `AGENTS_API_PUBLIC_URL`), `AGENTS_API_CONFIG_FILE`
+(no replacement), `AGENTS_API_EXECUTION_OPTIONS_FILE` (use
+[default models](#default-models)) and `AGENTS_API_MANAGED_RUNTIMES_FILE` (the
+sandbox deployment lives in the database). Core logs the file paths it loads, never
+environment values or file contents. Native installation paths must be canonical
+absolute paths without control characters, quotes, backslashes or wildcards. Keep the
+installation ID and the database together; Core refuses a missing installation ID
+when its database already has a deployment.
diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md
index 6f4d5edbd..69463ea6a 100644
--- a/docs/getting-started/README.md
+++ b/docs/getting-started/README.md
@@ -1,25 +1,21 @@
-# Getting started
+# Parsar Core documentation
 
-Parsar Core is self-deployed, open-source Agents API infrastructure. It provides
-an execution API and an optional Web console, with native harnesses behind one
-Runtime contract. The Parsar product is not required.
+Parsar Core is self-hosted, open-source Agents API infrastructure: Core serves the
+OpenAI Agents API and runs native harnesses (Codex, Claude Code and MiniMax Code) in
+sandboxes on your machines. Web is the administrator console; it issues the keys that
+applications call Core with.
 
-- [Install Core and Web](install.md)
-- [Configuration reference](../configuration.md)
-- [Public API and Web management reference](../api/README.md)
-- [Call the API](quickstart.md)
-- [Operate the installation](operations.md)
-- [Protocol coverage and native differences](https://github.com/MiniMax-AI/parsar-core/blob/main/contracts/agents-api/README.md)
+| Page | For | What it covers |
+| --- | --- | --- |
+| [Install Core and Web](install.md) | Administrators | Prerequisites, download, the installer and every option, HTTPS and the reverse proxy, a local trial, first sign-in, what is created on disk |
+| [Nodes](nodes.md) | Administrators | Adding a node with one command, sudo and no-sudo modes, removal, logs and troubleshooting |
+| [Self-hosted executors](self-hosted.md) | Administrators and application owners | Connecting an application's own machine to a `self_hosted` Session, rotating and revoking its credential |
+| [Operations](operations.md) | Administrators | The `parsar` command, the Core key, backups, upgrades and troubleshooting |
+| [Configuration reference](../configuration.md) | Administrators | Every `config.json` setting and every runtime setting in Web |
+| [Call the API](quickstart.md) | Application developers | `OPENAI_BASE_URL` and `OPENAI_API_KEY`, running a Session, model providers and `x_agents_core` |
+| [API reference](../api/README.md) | Developers | The `/v1`, `/core/v1` and `/api/v1` namespaces and their contracts |
 
-Core and Web ship together. The default installation runs Core, Web and PostgreSQL
-and selects Docker sandboxes, with zero execution nodes; `--sandbox microsandbox`,
-`--sandbox e2b` or `--sandbox none` choose otherwise. Add nodes, the Core host
-included, with **Add node** on the Nodes page in Web; nodes need an HTTPS public URL
-such as `--public-url https://core.example`. Core then creates the execution sandbox
-when a Session needs it. Installing the service does not require a model key or run
-a model request.
-
-The Web console is a client of Core. API users work with Agents, Sessions and
-Environments; operators also maintain the host, provider, Runtime images and
-durable storage. Those operational needs extend beyond the hosted OpenAI
-Platform experience, without redefining its public resource semantics.
+Deeper references: [nodes and sandbox backends](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md)
+for operators, [protocol coverage and native differences](../../contracts/agents-api/README.md),
+and [maintainers and advanced deployments](../maintainers.md) for building
+distributions and running Core without the installer.
diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index 9bd0763b1..7b43b86d1 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -1,553 +1,398 @@
 # Install Core and Web
 
-Install one matching Parsar Core distribution. By default it starts PostgreSQL,
-Core and the existing Web console in containers, then selects Docker sandboxes at
-Web's Standard size through the administrator API, with zero execution nodes.
-It does not import Runtime images, mount the Docker socket or host devices into
-Core, or add this host as a node. [`--sandbox`](#installation-choices) selects
-microsandbox, E2B or no backend instead; afterwards, change the provider,
-per-sandbox resources and immutable Runtime through Web or the administrator API.
-No model key, Environment wizard or sample task is required during installation.
-See [Configuration](../configuration.md) for setting ownership, paths, defaults,
-units, change restrictions and restart behavior.
-
-Recommended path: [install](#verify-extract-and-install) →
-[sign in to Web](#sign-in-to-web) →
-[add a node](#add-nodes-after-a-default-installation).
-You can leave the deployment with zero nodes until you need execution.
-
-## Host requirements
-
-The first distribution targets Linux amd64 with Python 3.9+, Docker and Docker
-Compose 2.26.0 or newer. Run the installer as a non-root user who can use Docker.
-The default installation requires neither KVM nor systemd user services.
-Node-host requirements are listed in the
-[add-node steps](#add-nodes-after-a-default-installation).
-
-## Verify, extract and install
-
-Download the matching Linux amd64 archive and its `.sha256` file from
-[GitHub Releases](https://github.com/MiniMax-AI/parsar-core/releases). Use one
-release for the entire installation. If GitHub requires sign-in, use an authenticated
-browser or `gh release download RELEASE --repo MiniMax-AI/parsar-core`.
-Choose the ordinary `.tar.gz` for a zero-node installation, or `-offline.tar.gz`
-when you also need all execution assets locally. A source checkout alone is not
-an installable binary bundle; [build a distribution](#build-a-distribution) for
-unreleased changes.
-
-For the recommended node workflow, choose an HTTPS address that both node hosts
-and their sandbox guests can reach, such as `https://core.example`. Configure
-your DNS/TLS reverse proxy as described in [Expose Core and Web](#expose-core-and-web),
-and pass that address on the first install. The installer does not create DNS
-records or certificates. You can set or change the public URL later in `config.json`
-(see [Change settings](#change-settings-after-installation)). The command below
-selects Docker sandboxes and still installs zero execution nodes.
+One command installs Core, the Web console and PostgreSQL on a Linux host. Web is
+the administrator console: you sign in with the Core key, issue Project API keys and
+add nodes. Applications call Core's API with those keys.
 
-```sh
-sha256sum -c parsar-core-<commit>-linux-amd64.tar.gz.sha256
-mkdir -p "$HOME/.parsar/releases"
-tar -xzf parsar-core-<commit>-linux-amd64.tar.gz -C "$HOME/.parsar/releases"
-cd "$HOME/.parsar/releases/parsar-core-<commit>-linux-amd64"
-./install.sh --public-url https://core.example
-```
+1. [Check the prerequisites](#prerequisites).
+2. [Download a release bundle](#download-a-release).
+3. [Run the installer](#install).
+4. [Put Core and Web behind HTTPS](#https-and-the-reverse-proxy), or
+   [try it locally first](#try-it-locally-with-a-quick-tunnel).
+5. [Sign in to Web and issue a key](#sign-in-to-web).
+6. [Add a node](nodes.md).
 
-The thin bundle contains same-revision Core and Web service images, PostgreSQL,
-native Core binaries, installer bootstraps, documentation and checksums. Node,
-Runtime and microsandbox binaries are separate prebuilt assets. Installing the
-default zero-node deployment downloads none of those execution assets and needs
-no Go, Node, Rust or source checkout.
-
-The manifest identifies every asset by immutable revision, SHA-256 and byte size.
-Adding a node downloads only its selected provider's assets. Runtime images use
-compressed archives; verified local files and already imported images are reused.
-Downloads use private partial files and bounded retries: an interrupted download,
-or a rerun after one, asks the console only for the missing bytes, and a file is used
-only after its size and SHA-256 match the manifest. An optional `-offline.tar.gz` bundle contains the
-same assets locally.
-
-Nodes download these assets only from the console (Web) that generated their
-command, never from a release URL the build recorded, so node hosts need no access
-to GitHub. The installer copies them into the console's node payload from the
-offline bundle, or from the release's `parsar-core-<commit>-linux-amd64-*` assets
-if you download them into the thin bundle's `artifacts/` directory before running
-`install.sh`. A console without them does not offer Add node for that provider.
+These pages describe the current source. Every bundle carries the docs that match it
+under `docs/`; if you install an older bundle, follow those.
 
-## Sign in to Web
+## Prerequisites
 
-Installation creates the private installation directory `~/.parsar/core`, with
-its settings in `config.json`, its secrets in `secrets/` and the `parsar`
-management command, plus a dedicated PostgreSQL volume. Installation creates no
-Project or application API key. Projects and their keys are managed in the database;
-configuration files contain deployment settings only. New installations create one
-management credential, the [Core key](operations.md#core-key). Secret values are
-not printed.
-
-Open the console address printed by the installer (`https://core.example` in
-the example above) and sign in with the Core key from
-`~/.parsar/core/secrets/core.key`. The console has no user accounts or passwords, and
-one role: administrator, with access to every console operation. The paired
-console already connects to Core with the same key on the server side.
-
-Use Web's **Projects and keys** page or the administrator API to create a Project,
-then issue a named API key within it and save the one-time plaintext response
-privately. Core stores only its digest. Multiple keys in a Project
-share its assets and execution principal; writes record the actual key separately.
-Rotate by issuing another key in that Project and revoking the old one. Archiving
-the Project disables all its keys and retains assets for inspection and deletion.
-API callers use their own keys and the public API endpoint. The Core key cannot
-call `/v1`; the console cannot execute or create Agent resources on their behalf.
-See the [management contract](../../contracts/agents-api/admin-api.md).
-
-Hosts registered through the console supply sandbox resources for hosted Sessions;
-self-hosted Sessions use application-managed environments. Neither installation
-nor key creation calls a model. Run examples separately with the issued API key
-and your model provider key, as described in the [API guide](quickstart.md).
-
-Default local ports and private files:
-
-- API: `http://127.0.0.1:8091/v1`
-- Web upstream: `http://127.0.0.1:8080`; use the configured public URL in your browser
-- Settings: `~/.parsar/core/config.json`
-- Core key: `~/.parsar/core/secrets/core.key`
-- Core key digest: `~/.parsar/core/generated/core-key-digests.json`
-
-Use exactly the displayed console address; the production proxy validates its
-configured origin. Sign-in sessions live in the console's memory. They expire after
-12 hours, and you sign in again after a console restart or a Core key rotation.
-Sign-in, status and sign-out use private `/console/auth` routes and do not extend
-the public Agent API. The console rejects every `/v1` and `/api/v1` request,
-including requests carrying an explicit Bearer token; it holds no caller key.
-
-Core loads the Core key digest from `AGENTS_API_CORE_KEY_DIGESTS_FILE`. Only the
-Core service reads the digest file; containers mount it read-only. The bundled Web server reads the
-Core key through `CORE_CONSOLE_CORE_KEY_FILE` to check sign-in and to proxy
-authenticated console operations; it never sends the key to the browser. The
-migration service receives neither. A Web-only connection to an external Core uses
-that Core's key, configured server-side. Installations from earlier releases
-move to this layout with [`install.sh --convert`](#convert-an-earlier-installation).
-Choose English or Chinese through the System language selector.
-
-## Add nodes after a default installation
-
-1. Log in to the bundled Web console and open **Nodes**.
-   The paired installation needs no second key or Core connection setup.
-   The installer already saved the sandbox backend (Docker at the Standard size,
-   unless [`--sandbox`](#installation-choices) chose otherwise), so continue with
-   step 4. Nodes need an HTTPS public URL that other machines and their sandboxes
-   can reach; on a loopback installation, set `public_url` first.
-2. After `--sandbox none`, or when the installer could not save the selection,
-   choose **E2B cloud** or **Own machines**. Own machines use Docker or
-   microsandbox; select their per-sandbox resources and matched immutable Runtime
-   release. E2B uses an account key and an exact ready template build, with no node
-   installation; each sandbox gets the build's CPU and memory, so setup asks for no
-   size. The paired console address is used automatically. If your network requires
-   a different address for nodes and guests, change it under advanced network
-   settings during initial setup. When
-   opening the console on localhost or an HTTP address, setup requires a
-   non-loopback HTTPS address that nodes and sandbox guests can reach.
-3. Select **Save configuration**. It takes effect without restarting Core and remains in
-   PostgreSQL across restarts. The provider, limits and Runtime are one saved
-   specification; node files cannot override it. Later changes require global
-   maintenance and completed cleanup. Microsandbox uses a five-minute idle timeout
-   and one-day snapshot retention.
-4. For own-machine hosting, click **Add node**, copy the command, and run it on the target Linux amd64
-   host with sudo, or as root. It prepares the host itself: the `parsar-node` service user, its `docker`
-   or `kvm` group and a system service. For Docker nodes, the `docker` group makes that user, and so the
-   node, root-equivalent on the host; use hosts dedicated to sandboxes. Hosts without sudo use the no-sudo
-   command as a prepared user instead.
-   It downloads the matched bootstrap and execution assets from your console
-   (never from a release URL), verifies
-   checksums, reads the saved generation and specification without consuming enrollment,
-   verifies the payload matches that Runtime, imports the image only when missing,
-   and writes the matching provider configuration,
-   registers the node and starts its service. The service keeps retrying while Core
-   is unreachable and stops for good once the node is removed. The installer waits for Core to confirm
-   connection and provider readiness. Web refreshes node health
-   automatically. Wait for the node to be online and its provider to be ready;
-   registration alone does not mean it can accept work. A registered retry uses its
-   retained node credential and refuses changed resource or Runtime settings.
-
-The target host needs curl, sha256sum, Python 3.9+ and systemd, plus Docker Engine or
-KVM with microsandbox's native libraries; the command never installs them and names
-what is missing. The no-sudo command also needs a user with lingering and Docker or KVM
-access. See [Register a host](https://github.com/MiniMax-AI/parsar-core/blob/main/services/agents-api/HOSTED-SANDBOX-MANAGER.md#register-a-host)
-for both modes and for removing a node from its host.
-The command checks host access before downloading the Runtime and verifies
-microsandbox's shared libraries after downloading its native programs.
-The console serves only fixed, non-secret distribution files at `/node-install/`;
-private installation configuration is never part of this payload. Retain the
-installed `node-payload/` directory. Manual console deployments enable the same
-flow with `CORE_CONSOLE_NODE_PAYLOAD_DIR` pointing to the matched distribution
-payload. TLS verification stays enabled; deployments using a private certificate
-authority must provision that trust on the target hosts and Runtime image.
-
-See the [Hosted Sandbox Manager guide](https://github.com/MiniMax-AI/parsar-core/blob/main/services/agents-api/HOSTED-SANDBOX-MANAGER.md)
-for host prerequisites and the registration command. The browser does not install
-software on another machine or receive SSH credentials. Adding a remote node does
-not add a Docker socket or KVM permissions to Core. Node installation and Runtime
-storage remain on the selected host.
-
-When a Session needs a sandbox, Core asks the
-enabled Provider to create one from the prepared Runtime image and initializes
-the colocated daemon, native harness and workspace.
-
-Once a node is ready, you can [make an API request](quickstart.md). Hosted Sessions
-take their model from the request, a saved Agent or the deployment default model
-provider that you set per harness in Web (System) with the Core key; node
-installation never needs a model credential. Without any of these, hosted Session
-creation fails with 400 `model_provider_required`.
-
-## Connect a user-managed Runtime
-
-A `self_hosted` Session uses your own execution machine; it does not enroll that
-machine as a shared sandbox node. The application creates the Session through
-`/v1` with its Project API key. The deployment operator then issues a restricted
-credential for the Session's Environment with the Core key, in Web or with a
-script against Core's loopback port:
+**The Core host**
 
-```sh
-umask 077
-curl -fsS -X POST \
-  "http://127.0.0.1:8091/core/v1/projects/$PROJECT_ID/environments/$ENVIRONMENT_ID/executor-credentials" \
-  -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
-  -d "{\"key_id\":\"$(python3 -c 'import uuid; print(uuid.uuid4())')\"}" \
-  -o executor-key.json
-```
+- Linux amd64 with Python 3.9 or newer.
+- Docker Engine with Docker Compose 2.26.0 or newer (`docker compose version`).
+- A non-root user who can run `docker`. The installer refuses root.
+- Free loopback ports 8091 (Core) and 8080 (Web), or [other ports](#ports-and-directory).
+- The GitHub CLI, `gh`, to download the bundle.
 
-The response is the credential; its secret appears only once. If the
-outcome is uncertain, list the credentials and rotate the same `key_id` instead
-of issuing another. The [credential contract](../../contracts/agents-api/environment-executor-credentials.md)
-describes issuance, rotation and revocation. The Core key and the application's
-`$PROJECT_API_KEY` never leave their own machines.
+The Core host needs no KVM and no systemd user services, unless you choose
+[native Core](#native-core).
 
-On the Session's page, Web shows the install command for its Environment. The
-command contains no secret. Run it on the execution machine and paste the
-credential at the hidden prompt:
+**Network, for nodes and remote access**
 
-```sh
-(umask 077; d=$(mktemp -d) || exit; trap 'rm -rf "$d"' EXIT
-curl -fsS --max-time 30 --max-filesize 1048576 'https://core.example/node-install/self-hosted-install.pyz' -o "$d/install.pyz" &&
-printf '%s  %s\n' 'SHA256' "$d/install.pyz" | sha256sum -c --status &&
-python3 "$d/install.pyz" --source-url 'https://core.example' --environment-id 'ENVIRONMENT_UUID' --remote 'wss://core.example/api/v1/agent-daemon/ws')
-```
+- A DNS name for Core and Web, such as `core.example`, with a TLS certificate.
+- A reverse proxy on the Core host that sends three routes to the right service; see
+  [HTTPS and the reverse proxy](#https-and-the-reverse-proxy).
+
+Node hosts and their sandboxes, E2B sandboxes and self-hosted executors all reach
+Core at this HTTPS address. A local trial needs none of this: install without a
+public URL and set it later.
+
+## Download a release
 
-Web fills in the public URL, the installer's SHA-256 (the
-`self-hosted-install.pyz` line of the console's `/node-install/SHA256SUMS`), the
-Environment ID and the unchanged `remote_url` returned by your Session. The prompt
-accepts the compact or pretty-printed credential and never echoes it. For
-automation without a terminal, add
-`--credential-file /absolute/private/executor-key.json` naming an owned mode-0600
-file instead.
-The Linux amd64 host needs Python 3.9+ and Docker access as a non-root user.
-The installer prepares the matched daemon, native harnesses and local workspace
-inside the same isolated Runtime used for hosted execution. No shared node or
-source build is needed. The Session itself must carry its model: create it with
-`x_agents_core.model_provider` or from a saved Agent that has one. Deployment
-default model providers do not apply to self-hosted Sessions, and creation without
-a provider fails with 400 `model_provider_required`. Core delivers the frozen
-provider only over this Environment's executor connection; the executor host keeps
-it in the Runtime's harness home, which tools and public Files cannot read.
-
-The command waits for Core to confirm that this Environment and its restricted
-credential are connected. It distinguishes a running container from a connected
-Environment. Connection failure or timeout exits with diagnostic and retry
-instructions, preserving the same container, credentials and native history.
-Rerun the command after correcting the reported problem; it does not create
-replacement history. A connected Environment does not prove model availability.
-Submit your task through the Session API to test execution.
-Installation state stays under `~/.parsar/self-hosted/ENVIRONMENT_UUID`; retain its
-credentials, volumes and native history. An uncertain launch gives inspection
-instructions instead of creating replacement history. Session deletion does not
-reclaim user-owned Docker resources.
-
-When the credential is revoked or rotated, the Runtime stops retrying: its log
-shows one message naming the fix, and the container stays up without a restart
-loop. Rotate the same credential in Web, rerun the same command and paste the new
-credential. The installer puts it into the same container, which reconnects with
-its workspace and native history. Issuing a new credential instead does not work
-for an Environment that has already connected. To remove the Runtime, stop its
-container.
-
-## Installation choices
+The repository is internal for now, so GitHub asks you to sign in first:
 
 ```sh
-./install.sh --sandbox microsandbox --public-url https://core.example
-./install.sh --sandbox e2b --e2b-api-key-file "$HOME/e2b-api-key" \
-  --e2b-template '<template-id>:<build-uuid>' --public-url https://core.example
-./install.sh --sandbox none
-./install.sh --core-only
-./install.sh --native-core --public-url https://core.example
+gh auth login
 ```
 
-`--sandbox` selects the sandbox backend once the services are healthy, through the
-same administrator API as Web's setup: `docker` (the default), `microsandbox`, `e2b`
-or `none`, the only choice with `--web-only`. Docker and microsandbox get Web's
-Standard size, read from the bundle's copy of
-`apps/web/src/features/sandbox/standard-sizes.json`, and the bundle's Runtime
-release. E2B takes its account key from `--e2b-api-key-file`: the absolute path of a
-regular file, not a symlink, of at most 4 KiB, with no group or other access (for
-example mode 0600). It also takes a ready template build (`--e2b-template
-template-id:build-uuid`); each sandbox gets the build's CPU and memory. E2B needs
-an HTTPS `--public-url` that is not loopback; otherwise the installer refuses it
-before installing anything. A loopback installation keeps a Docker or microsandbox
-selection, but nodes can't serve it: each sandbox calls Core at the public URL, and
-a loopback address reaches only the sandbox itself. Set `public_url` before adding
-nodes.
-
-These flags are one-time install actions, not settings: `config.json` doesn't hold
-them, and PostgreSQL owns the saved selection. Change it later in Web, through
-maintenance. If Core refuses the selection, for example because E2B rejects the key,
-the installer prints Core's message and exits with an error; the services keep
-running, so choose the backend on the Nodes page. A repair run or a conversion
-never selects a backend.
-
-The installer never adds this host as a node: add it like any other host, with
-**Add node** in Web. `--sandbox-provider` and `--provider` are retired and fail.
-`--core-only` installs Core and PostgreSQL without Web.
-
-The provider choice does not select a harness or alter the public `openai_hosted`
-discriminator. Both node providers use the same colocated Runtime. Core has no embedded
-node or file-managed provider selection. Docker access and microsandbox KVM/native
-paths belong to the separate node service; the Core container receives no Docker
-socket or node state mount. Web receives neither provider authority nor node secrets.
-
-Nodes keep configuration and identity under
-`~/.parsar/nodes/<installation-id>/` in the home of the account that runs them
-(`/var/lib/parsar-node` for a node added with sudo). Microsandbox stores its private
-Runtime home under `~/.parsar/m/<installation-hash-prefix>/` in the same home. Preserve these directories and
-backend storage across restarts. A missing identity is a recovery incident, not
-permission to register over existing resources.
-
-`--native-core` selects a native Core user service independently of the sandbox backend;
-PostgreSQL/Web stay in containers. Native Core itself requires no KVM or node
-Runtime files. Without this flag, Core stays in Compose. The standalone node
-service owns provider processes separately from Core.
-Stopping Core does not stop the node or prove its resources have been reclaimed.
-
-See [Configuration](../configuration.md) for the Standard per-sandbox resources,
-administrator-approved node capacity and the five-minute idle suspension policy.
-Change saved resources or Runtime only through the
-[drained deployment procedure](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance).
-Installation defaults are not evidence of model or workload acceptance.
-
-### Separate Web installation
-
-To install only Web on a Linux host, provide the existing Core origin and a
-private file containing that Core's Core key. A loopback Core uses the same host network namespace;
-a remote Core must use HTTPS.
+Pick a release, download its offline bundle and check it:
 
 ```sh
-./install.sh --web-only \
-  --install-dir "$HOME/.parsar/core-console" \
-  --core-url http://127.0.0.1:8091 \
-  --core-key-file "$HOME/.parsar/core/secrets/core.key"
+gh release list --repo MiniMax-AI/parsar-core
+mkdir -p "$HOME/.parsar/releases" && cd "$HOME/.parsar/releases"
+gh release download <tag> --repo MiniMax-AI/parsar-core --pattern '*-linux-amd64-offline.tar.gz*'
+sha256sum -c parsar-core-<commit>-linux-amd64-offline.tar.gz.sha256
+tar -xzf parsar-core-<commit>-linux-amd64-offline.tar.gz
+cd parsar-core-<commit>-linux-amd64
 ```
 
-Web-only mode starts no database or Core, so it selects no sandbox backend (choose
-it on the Core host), and requires no KVM. Its key remains on the server, outside
-the static Web files.
-The input file must be private (0600) and contain a Core key of at least 32 characters.
+`<tag>` is the release tag from the list, and `<commit>` is the source commit in the
+asset names. The installer also checks every file in the bundle against its
+`SHA256SUMS` before it changes anything.
+
+Each release has two bundles:
 
-The Web-only installation copies the key into its own `secrets/core.key`. After a
-[Core key rotation](operations.md#rotate-the-core-key) on the Core host, copy the
-new file there and run that installation's `parsar apply`.
+| Bundle | Contains | Use it for |
+| --- | --- | --- |
+| `parsar-core-<commit>-linux-amd64-offline.tar.gz` | Core, Web and PostgreSQL images, the installers and every node and Runtime file | Any installation. Web serves the node files to your nodes and self-hosted executors |
+| `parsar-core-<commit>-linux-amd64.tar.gz` | The same without the node and Runtime files | E2B-only or Web-only hosts. Web can't add nodes until the files are present |
 
-Use `--install-dir /absolute/path`, `--core-port 8092` and `--web-port 8081` for
-separate installations. Their database volumes, provider identities and Runtime
-state are independent. Native Core connects to PostgreSQL through an automatically
-selected loopback-only port, recorded as `ports.database` in `config.json`.
+To add the node files to the smaller bundle, download the release's other
+`parsar-core-<commit>-linux-amd64-*` assets (not the two bundles) into the extracted
+bundle's `artifacts/` directory, then run `./install.sh`, or rerun it if the
+installation already exists. Nodes download these files only from your Web console,
+never from GitHub, so node hosts need no GitHub access.
 
-## Change settings after installation
+## Install
 
-Flags only seed `config.json` for a new installation. Afterwards, edit
-`~/.parsar/core/config.json` and apply it:
+From the extracted bundle:
 
 ```sh
-~/.parsar/core/parsar apply --dry-run
-~/.parsar/core/parsar apply
+./install.sh --public-url https://core.example
 ```
 
-`parsar` lives in the installation directory and does not need the extracted
-bundle. [Configuration](../configuration.md#configjson) lists every setting, what
-it restarts and how a public URL change affects nodes. `mode` and `native_core` are
-fixed; install into a new directory to change them.
+The installer:
+
+1. checks the host and the bundle, and loads the Core, Web and PostgreSQL images;
+2. creates the installation directory `~/.parsar/core` with the Core key, `config.json`
+   and the `parsar` command ([what it creates](#what-the-installer-creates));
+3. starts PostgreSQL, Core and Web with Docker Compose, on loopback ports only;
+4. selects Docker sandboxes at Web's Standard size (2 CPUs and 2 GiB each). It adds
+   no node; you add nodes in Web.
 
-Rerunning `./install.sh` on an existing installation reads `config.json` and
-rejects every flag except `--install-dir`. Without flags it repairs the
-installation: it reloads missing images, restores a missing `parsar` command,
-applies `config.json` and starts the services. It refuses a bundle from another
-release. `--sandbox` and the E2B flags apply only to a new installation.
+It creates no Project or API key, makes no model request and runs no sample task.
+It ends by printing the console address, the API base URL and the next steps.
 
-## Convert an earlier installation
+Without `--public-url`, the installation serves only this host
+(`http://127.0.0.1:8080` for Web, `http://127.0.0.1:8091/v1` for the API). Set
+`public_url` in `config.json` later and run `parsar apply`; you don't reinstall. Nodes,
+E2B and self-hosted executors need the public URL.
+
+### Installer options
+
+Flags only seed `config.json` for a new installation. Afterwards you change settings in
+`config.json` with [`parsar apply`](../configuration.md#process-settings-configjson),
+and rerunning `install.sh` accepts no flag except `--install-dir`.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--public-url URL` | none: local access only | Public origin of Core and Web behind your reverse proxy, such as `https://core.example`: HTTPS, no path. Plain HTTP only for a loopback host. Seeds `public_url` |
+| `--sandbox docker\|microsandbox\|e2b\|none` | `docker` (`none` with `--web-only`) | [Sandbox backend](#sandbox-backend) to start with. A one-time choice saved in the database; change it later in Web |
+| `--e2b-api-key-file FILE` | | With `--sandbox e2b`: absolute path of a private file (no group or other access, at most 4 KiB) holding the E2B API key |
+| `--e2b-template ID:BUILD` | | With `--sandbox e2b`: the ready template build, `template-id:build-uuid` |
+| `--core-only` | | [Mode](#modes): Core and PostgreSQL, without Web |
+| `--web-only` | | [Mode](#modes): Web only, connected to an existing Core. Needs `--core-url` and `--core-key-file` |
+| `--core-url URL` | | With `--web-only`: origin of the existing Core, HTTPS or loopback HTTP. Seeds `web.core_url` |
+| `--core-key-file FILE` | | With `--web-only`: absolute path of a private file holding that Core's Core key (at least 32 characters) |
+| `--native-core` | off | Run [Core as a systemd user service](#native-core) instead of a container |
+| `--core-port PORT` | `8091` | Loopback port of Core. Seeds `ports.core` |
+| `--web-port PORT` | `8080` | Loopback port of Web. Seeds `ports.web` |
+| `--install-dir DIR` | `~/.parsar/core` | Absolute installation directory. It must be empty or missing |
+| `--config FILE` | | Seed `config.json` from a prepared file instead of the setting flags above (`--public-url`, the mode flags, `--native-core`, ports, `--core-url`) |
+| `--convert`, `--yes` | | [Convert an installation](operations.md#convert-an-earlier-installation) made before `config.json`; `--yes` skips the confirmation |
+
+#### Sandbox backend
+
+A deployment runs its sandboxes on exactly one backend:
+
+| `--sandbox` | Sandboxes run on | You then |
+| --- | --- | --- |
+| `docker` (default) | Docker on your nodes, 2 CPUs and 2 GiB each | [Add nodes](nodes.md) in Web |
+| `microsandbox` | microVMs on your nodes (KVM), 2 CPUs, 4 GiB memory and two 8 GiB disks each | [Add nodes](nodes.md) in Web |
+| `e2b` | E2B's cloud, with the CPU and memory of your template build | Nothing: E2B needs no nodes |
+| `none` | Nothing yet | Choose the backend on the **Nodes** page in Web |
+
+The Standard sizes come from the bundle's copy of Web's
+[`standard-sizes.json`](../../apps/web/src/features/sandbox/standard-sizes.json). The
+installer saves the choice through the same administrator API that Web uses once the
+services are healthy. If Core refuses it, for example because E2B rejects the key,
+the installer prints Core's message and exits with an error; the services keep
+running, and you choose the backend on the Nodes page.
 
-Installations made before `config.json` have `installation.json`, `config/core.env`
-and `admin/`: those of the installers since the Core key was introduced, including
-the release that added `AGENTS_API_PUBLIC_URL`. Plain `./install.sh` refuses them.
-Convert one with this release's bundle:
+E2B also needs an HTTPS public URL that is not loopback, because E2B's sandboxes
+call Core from E2B's cloud. The installer refuses `--sandbox e2b` without one, before
+it installs anything:
 
 ```sh
-./install.sh --convert --install-dir "$HOME/.parsar/core"
+./install.sh --public-url https://core.example --sandbox e2b \
+  --e2b-api-key-file "$HOME/.parsar/e2b-api-key" --e2b-template '<template-id>:<build-uuid>'
 ```
 
-Conversion is also an upgrade to this release, and its database migrations can't
-be undone: back up the database first (the command prints a `pg_dump` example).
-It reads the old files without changing anything; for an installation made before
-the release that added `AGENTS_API_PUBLIC_URL`, it also reads the sandbox
-deployment's `core_url` from the old Core.
-It then shows the resulting settings and asks for confirmation (`--yes` skips the
-prompt). It writes `config.json` and `state.json`, moves the secrets into `secrets/`
-without copying them, removes the old generated files, and starts the new release
-with the same Compose project, database and installation ID.
-
-It stops before changing anything, and lists each reason, when an item can't be
-converted: an edited `compose.json`, an unknown or edited generated value in
-`core.env`, an external database, or an installation public URL that differs from
-the sandbox deployment's Core URL. For that last case, rerun with `--public-url`
-naming one of the two; choosing the installation's URL means the deployment's nodes
-must be removed and added again. An `AGENTS_API_PUBLIC_URL` set by hand in
-`core.env` is the address Core uses, so it becomes `public_url`, and Core's own
-loopback address there means none. When that would move Web's origin away from the
-installation's public URL, conversion stops and `--public-url` names the one to keep. Hand-set settings such as
-`AGENTS_API_EXECUTION_CONCURRENCY`, `PARSAR_LOG_*` or a Runtime history file move
-into `config.json`. `AGENTS_API_EXECUTION_OPTIONS_FILE` is retired by this release
-and not carried over: set [deployment model providers](../configuration.md#deployment-model-providers)
-instead. Its file is left in place and reported, and `model_provider_sessions.py`
-in the bundle counts the Sessions without a model provider of their own before you
-convert. A
-Runtime history file inside the installation is removed once `config.json` holds
-its settings; one elsewhere is reported as a second copy to delete. Unknown
-files in `config/` and `admin/` are reported and left in place, and a public URL
-that differs from Core's canonical form only by letter case is lowercased. Secret
-files that are links or readable by other users stop the conversion before
-anything changes.
-
-If conversion is interrupted, or the new release fails to start afterwards, fix the
-cause and rerun `./install.sh --convert` with the same bundle to finish it;
-`--public-url` may be repeated but not changed. In a split deployment,
-convert the Core host first, then each Web-only host. A Web-only host converted
-first keeps working; after its Core is converted, run its `parsar apply` to record
-which Core it is paired with.
-
-## Expose Core and Web
-
-For nodes added through Web, install with the intended shared HTTPS endpoint:
+Prepare the template build with the [E2B guide](../../services/agents-api/deploy/e2b/README.md).
+To change the backend or the sandbox size later, use the Nodes page in Web; see
+[Nodes](nodes.md#change-the-sandbox-backend-or-size).
+
+#### Modes
+
+| Mode | Runs | Use it for |
+| --- | --- | --- |
+| all (default) | PostgreSQL, Core and Web | Most installations |
+| `--core-only` | PostgreSQL and Core | A Core whose Web runs on another host, or scripts only. Without Web there is no Add node command |
+| `--web-only` | Web | A second host for the console, paired with an existing Core |
+
+A Web-only installation needs the Core's origin and a private copy of its Core key:
 
 ```sh
-./install.sh --public-url https://core.example
+./install.sh --web-only --install-dir "$HOME/.parsar/core-console" \
+  --public-url https://console.example \
+  --core-url https://core.example \
+  --core-key-file "$HOME/core.key"
 ```
 
-The installer also uses this origin for the `wss` connection URL returned by
-self-hosted Sessions, so remote Runtime hosts never receive a Compose-only
-hostname. Configure your TLS reverse proxy with these routes:
+Its `--public-url` is the address browsers use for this console. Copy the key file
+from the Core host's `secrets/core.key` with mode `0600`; the installer keeps its own
+copy. After the Core key is rotated, copy the new key again; see
+[Rotate the Core key](operations.md#rotate-the-core-key). Web-only installs select no
+sandbox backend; do that on the Core host.
+
+The mode and native Core are fixed once installed. To change them, install into a
+new directory.
+
+#### Native Core
+
+`--native-core` runs Core as a systemd user service of the installing user;
+PostgreSQL and Web stay in containers. It needs a running systemd user manager and
+lingering for that user (`sudo loginctl enable-linger <user>`), and the bundle's
+native binaries must load on the host. PostgreSQL then listens on a loopback port
+the installer picks (`ports.database`), and Web uses the host network. Native Core
+needs no KVM and is unrelated to the sandbox backend.
+
+#### Ports and directory
 
-| Path | Destination | Callers |
+Core and Web listen on `127.0.0.1` only; the reverse proxy reaches them there. The
+installer refuses a port that is in use. Several installations can share a host with
+their own `--install-dir` and ports, for example
+`--install-dir "$HOME/.parsar/core-2" --core-port 8092 --web-port 8081`. Each has its
+own database, Core key and nodes.
+
+## HTTPS and the reverse proxy
+
+Core and Web share one public origin. Your reverse proxy terminates TLS and routes by
+path:
+
+| Path | Goes to | Callers |
 | --- | --- | --- |
-| `/v1`, `/v1/*` | Core (loopback 8091) | Applications, with a Project API key |
-| `/api/v1/*` | Core (loopback 8091) | Nodes and Runtime daemons, with their own machine credentials |
-| Everything else, including `/core/v1/*` and `/node-install/*` | Web (loopback 8080) | Browsers and the console |
-
-Web forwards signed-in `/core/v1` requests to Core with the Core key; operator
-scripts call `/core/v1` on Core's loopback port instead of the public entry.
-Preserve Host and support WebSocket upgrades. Web answers 404 on `/v1` and `/api/v1` and never
-forwards them. A proxy that sends those paths to Web breaks application calls,
-node enrollment and every Runtime daemon connection (`/api/v1/agent-daemon/ws`)
-for Docker, microsandbox, self-hosted and E2B sandboxes alike. When upgrading from
-a release whose Web forwarded node and daemon traffic, change this routing as the
-new release goes live; see [Data and upgrades](operations.md#data-and-upgrades).
-Both the node host and its sandbox guests must reach this address. Installation
-does not create DNS records or certificates, nor expose a host port publicly.
-Without this option, the console uses its loopback address for local access. Do not copy a
-localhost download command to a different machine. Running plain `./install.sh`
-is suitable for local console/API inspection; set `public_url` in `config.json`
-and run `parsar apply` before you enroll nodes. `parsar status` prints the routes
-to configure.
-
-The distribution includes the pinned E2B SDK helper, so selecting E2B does not
-require Python or pip installation on the Core host. Its private receipts live in
-`state/e2b` and are mounted only into Core. Preserve them together with the database
-and credential key when backing up or moving this installation. E2B template
-preparation is described in the [E2B guide](../../services/agents-api/deploy/e2b/README.md).
-
-## After installation
-
-Start with an optional [API request](quickstart.md). The read-only example works
-with the default installation. The execution example requires an installation
-with either E2B configured through Web or a connected, ready Docker/microsandbox node.
-Sandbox setup on the **Nodes** page selects one scheme for the whole deployment.
-E2B uses an account API key and a qualified immutable Runtime template; Core provisions
-sandboxes without a node installer. Own machines use the existing node command.
-Provider, per-sandbox resources and Runtime changes all require maintenance and
-completed resource cleanup; see
-[provider switching](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance).
-Session creation supplies the model and
-harness; model credentials come from the request, a saved Agent or the deployment
-default model provider. Core owns sandbox preparation and
-Runtime startup. Configuration is never injected into a public Agent instruction
-or baked into a Runtime image.
-
-[Operations](operations.md) covers health, restarts, data and provider changes.
-A service health check proves neither model availability nor complete protocol
-compatibility.
-
-## Build a distribution
-
-Release builders need the repository's full Linux toolchain and Docker. Build from
-clean, committed source, with the pinned Codex platform package and a matching
-MiniMax companion prepared through the existing Runtime build instructions:
+| `/v1`, `/v1/*` | Core, `127.0.0.1:8091` | Applications, with a Project API key |
+| `/api/v1/*` | Core, `127.0.0.1:8091` | Nodes, sandboxes and self-hosted executors, with their own machine credentials. Uses WebSockets |
+| Everything else | Web, `127.0.0.1:8080` | Browsers: the console, its sign-in, `/core/v1/*` and `/node-install/*` |
+
+The proxy must:
+
+- **Preserve Host.** Web accepts only requests for the host of its public URL.
+- **Pass WebSocket upgrades** on `/api/v1`. Nodes and Runtime daemons hold long-lived
+  WebSocket connections.
+- **Not buffer or time out streams.** `/v1` streams Session events (server-sent events).
+- **Accept large uploads.** Core enforces its own limits; source files may reach
+  512 MiB.
+
+Web answers 404 on `/v1` and `/api/v1` and never forwards them. If those paths reach
+Web, application calls, node enrollment and every sandbox connection fail. Run the
+proxy on the Core host, since Core and Web listen on loopback. `parsar status` prints
+the routes with this installation's ports.
+
+**Caddy** (obtains and renews the certificate itself; passes Host and WebSockets by
+default):
+
+```caddyfile
+core.example {
+	@core path /v1 /v1/* /api/v1/*
+	handle @core {
+		reverse_proxy 127.0.0.1:8091
+	}
+	handle {
+		reverse_proxy 127.0.0.1:8080
+	}
+}
+```
 
-```sh
-export AGENTS_RUNTIME_CODEX_PACKAGE=/absolute/path/to/codex-linux-package
-export MCODE_HARNESS_BUILD_DIR=/absolute/path/to/mcode-harness-artifact
-export CORE_DISTRIBUTION_RELEASE_BASE_URL=https://downloads.example/releases/COMMIT
-make build-core-distribution
+**nginx** (for example `/etc/nginx/conf.d/parsar-core.conf`, inside the `http` block;
+use your certificate paths):
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 80;
+    server_name core.example;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    server_name core.example;
+    ssl_certificate     /etc/letsencrypt/live/core.example/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/core.example/privkey.pem;
+
+    client_max_body_size 0;          # Core enforces its own upload limits
+    proxy_http_version 1.1;
+    proxy_set_header Host $http_host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_buffering off;             # server-sent events on /v1
+    proxy_request_buffering off;
+    proxy_read_timeout 1h;           # long-lived WebSockets and streams
+    proxy_send_timeout 1h;
+
+    location = /v1    { proxy_pass http://127.0.0.1:8091; }
+    location /v1/     { proxy_pass http://127.0.0.1:8091; }
+    location /api/v1/ { proxy_pass http://127.0.0.1:8091; }
+    location /        { proxy_pass http://127.0.0.1:8080; }
+}
 ```
 
-The builder reuses existing Core, Runtime, SDK and Web build scripts. It records
-the commit, immutable image identities, microsandbox binary hashes and the actual
-Runtime OCI manifest digest. Build output lives under `~/.parsar/build/`; it is
-not automatically published to GitHub, an image registry or a website. Qualify the
-exact bundle before distribution. See the [contributor guide](https://github.com/MiniMax-AI/parsar-core/blob/main/CONTRIBUTING.md).
-
-The release base must host the generated flat asset filenames over HTTPS. Use
-`CORE_DISTRIBUTION_OFFLINE=1` to also emit a full offline archive; a build without
-any release URL must select offline mode. Node installers always obtain assets
-from the console, whichever build recorded a release URL. The release workflow prepares pinned
-harness dependencies, builds versioned assets, and uploads an Actions artifact.
-An explicit manual option can create an unpublished draft release. Neither a
-successful build nor a draft makes a private repository anonymously downloadable;
-publish qualified assets through your chosen distribution channel before sharing
-installation instructions with external users.
-
-## Produce and qualify a release
-
-The `core-release` GitHub Actions workflow builds production assets from a full
-committed source SHA. It uses the existing pinned Runtime builders; acceptance
-credentials and private test certificate authorities must never enter its inputs.
-Run the workflow from the repository's Actions page, or use:
+Replace `core.example` and, if you changed them, the ports. To check the routing:
 
 ```sh
-revision=$(git rev-parse HEAD)
-gh workflow run core-release --repo MiniMax-AI/parsar-core --ref main \
-  -f ref="$revision" -f offline=true -f draft_release=true
+curl -s -o /dev/null -w '%{http_code}\n' -H 'OpenAI-Beta: agents=v1' https://core.example/v1/agents
 ```
 
-The workflow uploads the matched files as an Actions artifact and creates a draft
-Release tagged `build-<full SHA>`. The manifest records the same tag in every
-asset URL. Do not mix files across releases or resolve individual components
-through `latest`. The node command comes from its connected Core, which selects
-the matching release automatically.
-
-Download the draft assets using repository access, verify their checksums, and
-qualify a fresh installation plus the node/self-hosted connection paths before
-publishing the draft. A workflow build alone is not live acceptance. Retain the
-exact tested assets when publishing; do not rebuild or replace files under the
-same release identity. Publishing a Release does not change repository visibility.
-
-For an offline installation, extract the matching `-offline.tar.gz` archive and run
-its `install.sh`, which copies the bundled assets into the console's node payload.
-`install.sh` has no `--offline-root` option; only `self-hosted-install.pyz` accepts
-one, for an executor host. Node commands always download from the console that
-generated them, so install from the offline bundle (or place the release assets in
-the bundle) to let the console serve nodes. Download access errors should be fixed at the
-distribution source, without passing repository credentials into Runtime or
-changing its executor authorization.
+`401` means `/v1` reached Core, which asks for a key; `404` means it reached Web.
+
+Install with `--public-url https://core.example`, or, for an existing installation,
+set `public_url` in `~/.parsar/core/config.json` and run `~/.parsar/core/parsar apply`.
+Core derives every address it hands out from this one setting. If you change it while
+nodes, sandboxes or self-hosted executors use the old address, `parsar apply` lists
+them and asks you to confirm; those nodes must then be added again. See
+[Changing the public URL](../configuration.md#changing-the-public-url).
+
+TLS verification stays on everywhere. With a private certificate authority, node
+hosts, executor hosts and the Runtime image must trust it.
+
+## Try it locally with a quick tunnel
+
+For a trial without DNS or certificates, a
+[Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
+gives the installation a temporary public HTTPS address. It forwards to one local
+port, so put a plain-HTTP proxy with the same three routes in front, for example this
+Caddyfile on `127.0.0.1:8443`:
+
+```caddyfile
+http://:8443 {
+	bind 127.0.0.1
+	@core path /v1 /v1/* /api/v1/*
+	handle @core {
+		reverse_proxy 127.0.0.1:8091
+	}
+	handle {
+		reverse_proxy 127.0.0.1:8080
+	}
+}
+```
+
+1. Install, with or without a public URL (`./install.sh`).
+2. Start the local proxy: `caddy run --config Caddyfile`.
+3. Start the tunnel: `cloudflared tunnel --url http://127.0.0.1:8443`. It prints an
+   address such as `https://random-words.trycloudflare.com`.
+4. Set `"public_url": "https://random-words.trycloudflare.com"` in
+   `~/.parsar/core/config.json` and run `~/.parsar/core/parsar apply`.
+5. Open that address and [sign in](#sign-in-to-web).
+
+A quick tunnel is for trials only. Its address changes whenever `cloudflared`
+restarts; nodes and executors bound to the old address must then be added again.
+Its throughput is low, so the first node download of the Runtime (about 500 MB) can
+be slow; see [slow links](nodes.md#rerun-expiry-and-slow-links). Nodes and E2B need a
+reachable HTTPS address, so a loopback-only installation can't have nodes: Web says so
+at Add node.
+
+## Sign in to Web
+
+1. Open the console address the installer printed: your public URL, or
+   `http://127.0.0.1:8080` on the Core host. Use exactly that address; Web refuses
+   other host names. For a loopback installation on a remote machine, forward the port
+   first: `ssh -L 8080:127.0.0.1:8080 <core-host>`.
+2. Sign in with the Core key:
+
+   ```sh
+   cat ~/.parsar/core/secrets/core.key
+   ```
+
+   The Core key is the installation's administrator credential. Keep it private; see
+   [Core key](operations.md#core-key). Web has no user accounts.
+3. **Set a default model.** Open **System**, find **Default model** and choose
+   **Set** for the harness your applications use (Codex unless you changed
+   `core.default_harness`). Enter the model provider's base URL and API key; MiniMax
+   Code also needs the context window and max output tokens. Core encrypts the key and
+   never shows it again. Core-hosted Sessions use this default when the request and the
+   Agent carry no model provider; self-hosted Sessions never do. See
+   [model providers](quickstart.md#model-providers).
+4. **Create a project and issue a key.** Open **Projects and keys**, select
+   **Create project**, then **Issue key** in it. Copy the key: Web shows it once and
+   Core keeps only a digest. Web also shows how to call the API with it.
+5. Give the key and the API base URL to the application developer, who follows the
+   [API quickstart](quickstart.md).
+
+**Overview** shows the same steps as a **Getting started** checklist, including
+[adding a node](nodes.md).
+
+## What the installer creates
+
+The installation directory, `~/.parsar/core` by default, mode `0700`:
+
+| Path | Content |
+| --- | --- |
+| `config.json` | Process settings. The only file you edit; see the [configuration reference](../configuration.md) |
+| `parsar` | The [management command](operations.md#the-parsar-command) |
+| `secrets/core.key` | The Core key |
+| `secrets/credential.key` | Encryption key for credentials stored in the database. Back it up with the database; never replace it |
+| `secrets/database.password` | PostgreSQL password |
+| `state.json` | Installation ID, Compose project name, image IDs and source commit. Written by the tools only |
+| `generated/` | Files derived from `config.json`: `compose.json`, `core.env`, `core-key-digests.json`, `settings.json`, `config.schema.json`, and `runtime-history.json` or the native Core unit when used. `parsar apply` rewrites them; don't edit them |
+| `node-payload/` | The node and self-hosted installers, the manifest and the node files that Web serves at `/node-install/` |
+| `state/e2b/` | Private E2B receipts |
+| `native/` | Core binaries, with `--native-core` only |
+
+Web-only installations have only `secrets/core.key` among the secrets, and no
+`state/e2b/`; Core-only installations have no `node-payload/`.
+
+In Docker, the installer creates a Compose project named `parsar-<10 hex digits>`
+(`project` in `state.json`) with the containers `database`, `migrate` (runs the
+migrations, then exits), `core` and `web`, and the volume `<project>_database` that
+holds all data. Core and Web publish only `127.0.0.1:8091` and `127.0.0.1:8080`. The
+database publishes no port unless Core is native.
+
+The database holds the sandbox backend selection, and later your Projects, keys,
+nodes, default models and all execution history. Apart from Docker's own storage,
+nothing is written outside your home directory: no system service and no file under
+`/etc`. Native Core adds a systemd user unit, enabled from `generated/`.
+
+## Rerun the installer
+
+Rerunning `./install.sh` from the same bundle repairs an installation: it reloads
+missing images, restores a missing `parsar` command, copies node files newly placed in
+`artifacts/`, applies `config.json` and starts the services. It accepts only
+`--install-dir`. It refuses a bundle from another release; see
+[Upgrades](operations.md#upgrade-an-installation).
diff --git a/docs/getting-started/nodes.md b/docs/getting-started/nodes.md
new file mode 100644
index 000000000..023909e1e
--- /dev/null
+++ b/docs/getting-started/nodes.md
@@ -0,0 +1,248 @@
+# Add and manage nodes
+
+A node is a Linux machine that runs sandboxes for Core-hosted Sessions when the
+sandbox backend is Docker or microsandbox. Core places each new Session on a node with
+free capacity; the node creates the sandbox, and the sandbox connects back to Core.
+With E2B you need no nodes. Self-hosted executors, which applications run for their
+own Sessions, are a different thing; see [Self-hosted executors](self-hosted.md).
+
+You add a node by generating a command in Web and pasting it on the host. The
+[operator reference](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md) covers the
+node protocol, manual registration, placement and failure handling.
+
+## Before you add a node
+
+- **Core has an HTTPS public URL** that the host and its sandboxes can reach: each
+  sandbox calls Core at `public_url`. A loopback installation can't have nodes, and
+  Web says so at Add node. See [HTTPS and the reverse proxy](install.md#https-and-the-reverse-proxy).
+- **Web holds the node files.** Install from the offline bundle, or add the release's
+  node files to the smaller bundle; see [Download a release](install.md#download-a-release).
+  Otherwise Add node says that the console has no node files for the provider.
+- **A sandbox backend is chosen.** The installer selects Docker unless you chose
+  otherwise. After `--sandbox none`, the **Nodes** page first asks you to choose
+  **Own machines**, Docker or microsandbox, and a sandbox size, then
+  **Save configuration**. Every node of a deployment uses that provider.
+
+## Add a node
+
+1. In Web, open **Nodes** and select **Add node**.
+2. Set **Sandboxes at once** (default 2) and **Retained sandboxes** (default 8): how
+   many sandboxes Core may run and keep on this node. You can change them later with
+   **Edit node**.
+3. Select **Generate command** and copy the command. It works once, within 10 minutes;
+   Web counts down and offers **Generate new command** when it expires.
+4. Run it on the host. Web follows the node from registered to connected to ready.
+
+The command downloads the node installer from your console, checks its SHA-256, and
+runs it with a one-time enrollment token. The installer downloads the node files from
+the same console and checks each against the release manifest, imports the Runtime
+image, registers the node, starts its service and waits until Core reports the node
+connected and ready. It never installs software, and it stops with a one-line hint
+before changing anything when a prerequisite is missing.
+
+Web's command runs the installer with sudo: it prepares the host itself, creating a
+`parsar-node` service user and a system service. On a host where you have no sudo, the
+dialog's **No sudo on this host?** section gives the same command without sudo; the
+node then runs as a user service of a user that an administrator prepared.
+
+### The command
+
+This is the command Web generates, with this installation's values:
+
+```sh
+ (umask 077; d=$(mktemp -d) || exit; trap 'rm -rf "$d"' EXIT; s=; [ "$(id -u)" -eq 0 ] || s=sudo
+curl -fsS --max-time 30 --max-filesize 1048576 'https://core.example/node-install/node-install.pyz' -o "$d/node-install.pyz" &&
+printf '%s  %s\n' '<installer-sha256>' "$d/node-install.pyz" | sha256sum -c --status &&
+printf '%s\n' '<enrollment-token>' | $s python3 "$d/node-install.pyz" --enrollment-token-stdin --source-url 'https://core.example' --core-url 'https://core.example' --provider 'docker' --installation-id '<installation-id>')
+```
+
+- It downloads the installer into a private temporary directory, checks its SHA-256,
+  and runs it with `sudo`, or directly in a root shell.
+- The token reaches the installer on standard input, so it never appears in a process
+  argument, an environment variable or sudo's log.
+- The leading space keeps the command out of the shell history where `HISTCONTROL`
+  ignores such lines (the Debian and Ubuntu default).
+- If the command is interrupted or the download stalls, run the same command again:
+  the download resumes.
+
+The host needs:
+
+- Linux amd64 with systemd; Python 3.9+, `curl` and `sha256sum`; root or sudo.
+- SELinux not enforcing. Sudo mode refuses an enforcing host; use the no-sudo command
+  with a prepared user there.
+- One Core per host: a host already running a sudo-mode node for another Core is
+  refused.
+- Docker: rootful Docker Engine running, its socket `/var/run/docker.sock` owned by the
+  `docker` group with mode `0660`, enforcing CPU and memory limits (cgroup v2).
+- microsandbox: `/dev/kvm` in the `kvm` group (hardware or nested virtualization), and
+  the libraries microsandbox links (glibc).
+- CPUs and memory for at least one sandbox of the deployment's size, and about 2 GB of
+  disk for the Runtime image.
+- HTTPS access to the console and Core at the public URL; sandboxes reach Core too.
+
+### Without sudo
+
+The no-sudo command is the same without `sudo`:
+
+```sh
+ (umask 077; d=$(mktemp -d) || exit; trap 'rm -rf "$d"' EXIT
+curl -fsS --max-time 30 --max-filesize 1048576 'https://core.example/node-install/node-install.pyz' -o "$d/node-install.pyz" &&
+printf '%s  %s\n' '<installer-sha256>' "$d/node-install.pyz" | sha256sum -c --status &&
+printf '%s\n' '<enrollment-token>' | python3 "$d/node-install.pyz" --enrollment-token-stdin --source-url 'https://core.example' --core-url 'https://core.example' --provider 'docker' --installation-id '<installation-id>')
+```
+
+Run it as the non-root user that will run the node; run by root, it installs the
+sudo-mode service instead. An administrator prepares that user once:
+
+- Docker: `sudo usermod -aG docker <user>`, with Docker enforcing CPU and memory limits.
+  microsandbox: `sudo usermod -aG kvm <user>` for read and write access to `/dev/kvm`.
+- Lingering, after the group change: `sudo loginctl enable-linger <user>`. After a group
+  change, sign in again as that user; if the user's systemd manager was already
+  running, restart it (`sudo systemctl restart user@$(id -u <user>).service`) or reboot.
+- microsandbox only: a home directory of at most 25 bytes, such as `/home/parsar`,
+  because microsandbox's socket paths are short.
+- The host requirements above, except root and the SELinux rule.
+
+Run the command as that user over SSH, or from a root shell with `su - <user>`. The
+node's state then lives in `~/.parsar/nodes/<installation-id>/` of that user. The
+Docker group makes this user root-equivalent on the host too.
+
+## What sudo mode sets up
+
+| Item | Detail |
+| --- | --- |
+| Service user | System user `parsar-node`, home `/var/lib/parsar-node`, no login shell. An existing account with that home and a nologin shell is adopted; any other account named `parsar-node` is refused |
+| Group | The group that owns `/var/run/docker.sock` (Docker) or `/dev/kvm` (microsandbox): `docker` or `kvm`, nothing else |
+| Service | `/etc/systemd/system/parsar-node-<installation-id>.service`, a root-owned system unit with `User=parsar-node`, enabled at boot. It restarts every 5 seconds while Core is unreachable and stops for good once Core no longer accepts the node |
+| Node state | `/var/lib/parsar-node/.parsar/nodes/<installation-id>/`: identity, configuration, node files. microsandbox keeps its images and sandboxes under `/var/lib/parsar-node/.parsar/m/` |
+| Records | `/etc/parsar-node/`: what the installer created or changed, used by reruns and uninstall |
+| Docker | The Runtime image, imported once, and a network `parsar-node-<installation-id>` |
+
+Root only prepares the account, group, unit and network; everything else runs as
+`parsar-node`, in its own session without a terminal. The installer never installs
+Docker, KVM or packages, never starts Docker, never changes device permissions,
+sudoers, firewall or SELinux settings, and never touches other accounts.
+
+**Docker mode is root-equivalent.** Membership in the `docker` group lets
+`parsar-node`, and so anything that controls the node, act as root on the host. This
+is inherent to running sandboxes on Docker and equally true without sudo. Add Docker
+nodes only on hosts dedicated to sandboxes. microsandbox nodes need only the `kvm`
+group.
+
+**One Core per host.** All sudo-mode nodes share the `parsar-node` account, so a host
+serves one Core in sudo mode; a command from a second Core is refused. A host also
+can't run the same installation's node both with and without sudo.
+
+**The token.** It is single-use, expires after 10 minutes and only registers the node.
+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.
+- If the command expires during a slow download, the downloaded files are kept:
+  generate a new command in Web and run it.
+- Downloads resume where they stopped. A download that brings less than 64 KiB in a
+  minute stops, keeping what it has; run the command again.
+- The Docker Runtime image is about 500 MB. On a slow link, load it first: copy the
+  release's `parsar-core-<commit>-linux-amd64-runtime.tar.gz` asset to the host and run
+  `sudo docker load -i` on it. The installer then finds the exact image and skips the
+  download.
+- Interrupting the installer, or closing its terminal, stops it; run the command again
+  to continue.
+
+## Logs
+
+After you run the command, the Add node dialog shows the node's log command:
+
+| Node installed | Command |
+| --- | --- |
+| With sudo, or by root | `sudo journalctl -u parsar-node-<installation-id>.service` |
+| Without sudo, as the node's user | `journalctl --user -u parsar-node-<installation-id>.service` |
+
+The installation ID is in the command (`--installation-id`) and on the **System** page.
+
+## Remove a node
+
+1. In Web, open **Nodes**, select the node and choose **Remove node**. Core refuses
+   while the node still holds sandboxes, snapshots or pending cleanup; let them finish,
+   or [archive their Sessions](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
+   through the Core API. Removal is permanent: the host can come back only as a new node.
+2. Web then shows **Clean up the host** with the uninstall command. Run it on the host:
+
+   ```sh
+    (umask 077; d=$(mktemp -d) || exit; trap 'rm -rf "$d"' EXIT; s=; [ "$(id -u)" -eq 0 ] || s=sudo
+   curl -fsS --max-time 30 --max-filesize 1048576 'https://core.example/node-install/node-install.pyz' -o "$d/node-install.pyz" &&
+   printf '%s  %s\n' '<installer-sha256>' "$d/node-install.pyz" | sha256sum -c --status &&
+   $s python3 "$d/node-install.pyz" --uninstall --installation-id '<installation-id>')
+   ```
+
+   For a node installed without sudo, **Installed without sudo?** gives the same command
+   without `sudo`; run it as that user.
+
+Uninstall first asks Core, at the address the node enrolled with, whether the node was
+removed, and refuses while Core still lists it. If that address no longer responds, for
+example after the public URL changed, **Old Core address gone?** gives the command with
+`--force`, which skips the check; remove the node on the Nodes page first. Uninstall
+stops and removes the service, the node state, the records and the Docker network. It
+deletes the `parsar-node` account only if the installer created it and no node remains;
+an adopted account only loses the groups the installer added.
+
+It never deletes sandboxes, volumes or images. It keeps the Runtime image and prints
+the `docker image rm` command. For microsandbox it keeps the store under
+`/var/lib/parsar-node/.parsar/m/`, prints how to delete it
+(`sudo -u parsar-node rm -rf <store>`), and keeps a created account until the store is
+gone; rerun uninstall afterwards. With `--force`, microVMs may still use the store, so
+check `pgrep -u parsar-node` first. Uninstall can be rerun until it completes.
+
+## Troubleshooting
+
+### Readiness codes
+
+When a node is online but its provider is not ready, **Nodes** shows one of these codes
+(the `diagnostic` field of `GET /core/v1/sandbox/nodes`). A node reports only its first
+failed check, and the next heartbeat, about ten seconds after a fix, clears or replaces
+the code. The node's log has the local error behind the code.
+
+| Code | Cause | Fix |
+| --- | --- | --- |
+| `docker_unavailable` | The Docker socket is unreachable or not accessible, or Docker fails its info or image request | Start Docker and give the node's user access to `/var/run/docker.sock` |
+| `docker_limits_unsupported` | Docker reports no CPU quota or memory limit support | Use a host whose cgroups enforce CPU and memory limits (cgroup v2) |
+| `runtime_image_unavailable` | Docker does not have the pinned Runtime image | Rerun the add command, or load the image from the matching release |
+| `kvm_unavailable` | The node can't open `/dev/kvm` for reading and writing | Enable hardware virtualization and give the node's user KVM access, through the `kvm` group |
+| `microsandbox_artifacts_unavailable` | The Runtime or firmware is missing or fails its SHA-256 check, or the helper is missing | Rerun the add command |
+| `capacity_insufficient` | The host has fewer CPUs or less memory than one sandbox | Use a larger host, or change the sandbox size |
+| `provider_unavailable` | Any other failure, and every failure an older node reports | Read the node's log |
+
+A new group membership applies only to a new process: restart the service with
+`sudo systemctl restart parsar-node-<installation-id>.service`, or
+`systemctl --user restart parsar-node-<installation-id>.service` without sudo. A node
+that is registered but never connects usually can't reach Core at the public URL, or
+its `/api/v1` WebSocket doesn't pass the reverse proxy.
+
+### Installer messages
+
+| Message | Fix |
+| --- | --- |
+| The enrollment command expired or was already used | Generate a new command in Web and run it |
+| Core's public URL changed after this command was generated | Generate a new command in Web and run it |
+| This host's node uses `<address>`, but this command uses `<address>` | The node was added under an older public URL. Remove it in Web, uninstall it, then add it again |
+| Docker Engine is not installed, or Docker is not running | Install Docker Engine, or `sudo systemctl enable --now docker`, then rerun |
+| Docker on this host does not enforce CPU and memory limits | Use cgroup v2, then rerun |
+| KVM is unavailable, or `/dev/kvm` must be group-accessible | Enable virtualization; your distribution's KVM package sets `root:kvm 0660` |
+| This host has N CPUs and M MiB of memory; each sandbox needs … | Use a larger host, or change the sandbox size |
+| SELinux is enforcing on this host | Use the no-sudo command as a prepared user |
+| This host already runs a sudo-mode node for another Core | One host serves one Core in sudo mode. Remove that node and uninstall it first |
+| Ask the host administrator to enable user lingering, or No systemd user manager is running | No-sudo mode: `sudo loginctl enable-linger <user>`, or use sudo |
+| Core still lists this node | Remove it on the Nodes page first |
+
+## Change the sandbox backend or size
+
+Changing Docker, microsandbox or E2B, the sandbox size or the Runtime release applies to
+the whole deployment. On **Nodes**, choose **Enter maintenance to change provider**, which
+pauses new hosted sandboxes; let the existing ones finish, or archive their Sessions
+through the Core API, until nothing is retained; save the new configuration; then choose
+**Resume hosted placement**. A change retires every node: remove and uninstall them, and
+add the hosts again with new commands. See
+[maintenance](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
+for the exact steps and API.
diff --git a/docs/getting-started/operations.md b/docs/getting-started/operations.md
index deba79b67..0e423a70b 100644
--- a/docs/getting-started/operations.md
+++ b/docs/getting-started/operations.md
@@ -1,110 +1,95 @@
-# Operate your Core
+# Operate your installation
 
-The installation operator owns the host, storage and service availability.
-The default installation selects Docker sandboxes and has zero execution nodes.
-After nodes are added in Web, the Core host included, their operators maintain the
-node services, containers or microVMs on those hosts. Service
-health and provider state are separate from a Session's public execution state.
+The installation operator owns the Core host, its storage and its availability. Node
+hosts run their own services; see [Nodes](nodes.md). Settings are described in the
+[configuration reference](../configuration.md).
 
-Use [Configuration](../configuration.md) for the authoritative setting locations,
-defaults and restart behavior. Process settings live in the installation's
-`config.json` and take effect with `parsar apply`; Compose and systemd only
-launch the processes from the files `apply` generates.
+## The parsar command
 
-## Read service health
-
-Each installation has its own `parsar` command; it does not need the bundle:
+Each installation has its own management command in its directory. It needs neither
+the bundle nor root:
 
 ```sh
 ~/.parsar/core/parsar status
-# For a separate installation:
-~/.parsar/core-console/parsar status
 ```
 
-The command reads only this installation's service status and health endpoints.
-It prints service names, running/exit state, the native Core service state when
-applicable, and available Docker health state. It also prints the public URL, API
-base URL, source commit, the reverse-proxy routes to configure, `config.json`
-changes that are not applied yet and generated files edited by hand. A Web-only
-installation also checks that its Core accepts its Core key. It does not print
-Compose configuration, environment variables, credentials or raw application
-logs. It never creates a Session or calls a model.
+| Command | What it does |
+| --- | --- |
+| `parsar status` | Shows each service and its health, Core and Web health, the public URL, API base URL, console address and source commit, the reverse-proxy routes to configure, `config.json` changes not applied yet and generated files edited by hand. A Web-only installation also checks that its Core accepts its Core key. Exits non-zero when a service is unavailable. It never calls a model |
+| `parsar start` | Starts every service with the files last written by `apply`; warns about unapplied changes |
+| `parsar stop` | Stops PostgreSQL, Core and Web. Data, nodes and sandboxes are kept, and running sandbox work may continue |
+| `parsar apply` | Applies `config.json` and restarts what changed; see [how apply works](../configuration.md#how-parsar-apply-works) |
+| `parsar apply --dry-run` | Shows the changed settings, files and restarts, and changes nothing |
+| `parsar apply --discard-edits` | Overwrites generated files edited by hand, keeping each as `generated/<file>.edited-<time>` |
+| `parsar apply --confirm-public-url-change URL` | Confirms a public URL change without a prompt; must equal the new URL |
+| `parsar apply --yes` | Web-only: pairs Web with a different Core without asking |
+| `parsar rotate-core-key [--yes]` | Replaces the Core key; see [Rotate the Core key](#rotate-the-core-key) |
+
+`install.sh --status` and `--stop` are retired; they name the `parsar` command instead.
+For a second installation, use its own command, such as
+`~/.parsar/core-console/parsar status`.
 
-Use these observations for distinct questions:
+## Service health
+
+Use these observations for different questions:
 
 | Observation | What it establishes |
 | --- | --- |
-| PostgreSQL container health | The dedicated database accepts its readiness check |
-| Core `/healthz` | Core process liveness |
-| Authenticated API resource read | Caller authentication and the requested resource operation |
-| Environment connection | Runtime transport observation |
-| Terminal Turn and queried results | The requested task's recorded execution outcome |
-
-Container liveness alone is not a healthy native harness or an available model.
-Use public Session, Turn, Items, Environment and Usage reads for execution. Reuse
-Core's Runtime observations for sandbox details when available; do not infer
-execution truth from Docker or invent a second lifecycle collector. Use Web's
-**Nodes** page for node connection, provider readiness and placement.
+| `parsar status`, PostgreSQL health | The database accepts its readiness check |
+| Core `/healthz` | Core's process is alive |
+| An authenticated API read | The caller's key works for that resource |
+| Environment connection | The Runtime transport is connected |
+| A finished Turn and its results | The task's recorded outcome |
+
+Service health does not prove that a native harness or a model works. Use Session,
+Turn, Items and Usage reads for execution, and Web's **Nodes** page for node connection,
+readiness and placement. For local diagnosis, use the installation's own Compose file:
+
+```sh
+docker compose -f "$HOME/.parsar/core/generated/compose.json" ps --all
+docker compose -f "$HOME/.parsar/core/generated/compose.json" logs --tail 200 core
+```
+
+Native Core logs to its user unit: `journalctl --user -u <project>-core.service`, with
+`project` from `state.json`. Don't paste `docker compose config`, `docker inspect` or
+raw logs into public issue reports.
 
 ## Stop and restart
 
-Settle active work before a planned restart. Then:
+Let active work settle before a planned restart:
 
 ```sh
 ~/.parsar/core/parsar stop
 ~/.parsar/core/parsar start
 ```
 
-This stops the control-plane services and retains the database, Runtime state and
-credentials. Local and remote nodes run their own services; stopping Core does not stop those
-services. The node service uses `KillMode=process`, so a service restart also
-preserves resident microsandbox processes; microVMs and their work may remain running. Docker-owned Runtime
-containers likewise remain Provider resources. The command does not promise to
-stop all compute. Confirm resource cleanup before a full
-shutdown; do not kill Provider processes directly. A Core restart does not promise
-transparent continuation of an interrupted native tool. Query the same
-Session after reconnecting; do not create a replacement Session to replay uncertain
-work. The official SSE stream is live, and recovery uses durable resource queries.
-
-`parsar start` uses the last applied files; it warns about unapplied `config.json`
-changes. The generated Compose file and `core.env` hold no secrets; secrets reach
-the services as read-only file mounts from `secrets/`. Still, do not paste
-`docker compose config`, `docker inspect` or raw logs into public issue reports.
-For local diagnosis, use the exact installation file:
-
-```sh
-docker compose -f "$HOME/.parsar/core/generated/compose.json" ps --all
-```
+Stopping Core stops no node and no sandbox. Node services, their microVMs and Docker
+containers keep running; stopping is not a way to reclaim compute. A Core restart does
+not continue an interrupted native tool call transparently. After reconnecting, query
+the same Session; don't create a new Session to replay uncertain work. Session event
+streams are live only; recover through Session, Turn and Items reads.
 
-Do not edit files under `generated/`; `parsar apply` refuses to overwrite hand
-edits until you move them into `config.json`.
+A Web restart, including one caused by `parsar apply`, signs everyone out of the
+console.
 
 ## Core key
 
-Each installation has one management credential, the Core key. The installer
-generates a 64-character random key in `<install dir>/secrets/core.key` (default
-install dir `~/.parsar/core`). `parsar apply` writes its SHA-256 digest to
-`generated/core-key-digests.json`. Core reads the digest file named by
-`AGENTS_API_CORE_KEY_DIGESTS_FILE`; Web reads the key file named by
-`CORE_CONSOLE_CORE_KEY_FILE`. Both read them only at startup.
-
-A Core key must have at least 32 characters and no whitespace. Web and the
-Web-only installer refuse a shorter key; Core sees only digests, so it cannot
-check the length. Web limits failed sign-ins, but the correct key always signs in.
-
-The Core key:
+Each installation has one administrator credential, the Core key. The installer
+generates a 64-character random key in `<install dir>/secrets/core.key`, by default
+`~/.parsar/core/secrets/core.key`. The Core key:
 
 - signs in to Web. The browser gets an HttpOnly session cookie, never the key;
-- authorizes `/core/v1` management requests sent to Core as
-  `Authorization: Bearer <Core key>`;
-- never authorizes `/v1`. Applications use Project API keys, which in turn cannot
-  call `/core/v1`.
+- authorizes Core API (`/core/v1`) requests sent as `Authorization: Bearer <Core key>`;
+- never authorizes the Agent API (`/v1`). Applications use Project API keys, which in
+  turn can't call `/core/v1`.
+
+Keep it private: `secrets/` is mode `0700` and its files `0600`. Of the services, only
+Web reads `core.key`; Core reads its SHA-256 from `generated/core-key-digests.json`,
+which `parsar apply` derives from the key. Both read them only at startup. A Core key
+has at least 32 characters and no whitespace. Web limits failed sign-ins.
 
-Keep it private. `secrets/` stays mode `0700` and its files `0600`, owned by the
-installation user. Of the services, only Web reads `core.key`; Core reads only the
-digest file. Don't copy the key into scripts, shell history, logs or issue reports.
-Operator scripts run on the Core host, call Core's loopback port and read the key
-from its file. This example keeps the key off the command line:
+Scripts run on the Core host, call Core's loopback port and read the key from its file,
+which keeps it off the command line:
 
 ```sh
 curl -fsS -H @<(printf 'Authorization: Bearer %s\n' "$(cat "$HOME/.parsar/core/secrets/core.key")") \
@@ -117,233 +102,220 @@ curl -fsS -H @<(printf 'Authorization: Bearer %s\n' "$(cat "$HOME/.parsar/core/s
 ~/.parsar/core/parsar rotate-core-key
 ```
 
-The command asks for confirmation (`--yes` skips it), stops Web, writes a new
-64-character key to `secrets/core.key`, regenerates the digest file, restarts Core
-and waits until it is healthy, then starts Web. It checks that Core accepts the
-new key and rejects the old one. The old key stops working at once, and every Web
-sign-in session ends: sign in again with the new key and update your scripts. If
-the command stops early, `secrets/core.key` holds the key to use and `parsar status`
-reports what does not match it; run `parsar apply` to finish the rotation.
-
-A separate Web-only installation keeps its own copy of the key. After rotating,
-copy `secrets/core.key` from the Core host to that installation's
-`secrets/core.key` (mode `0600`) and run its `parsar apply`; its `parsar status`
-reports a key that Core rejects. `rotate-core-key` refuses to run on a Web-only
-installation, because Core owns the key.
-
-### Upgrade an existing installation
-
-Installations made before `config.json` move to the current layout with
-[`install.sh --convert`](install.md#convert-an-earlier-installation). Conversion
-expects the Core key names below. Earlier releases used other names for these
-files and settings; current Core and Web refuse to start while an old setting is
-present, and the error names the replacement. For such an installation, stop the
-services and rename them first:
-
-| Old | New | Where |
-| --- | --- | --- |
-| `admin/sandbox-admin.key` | `admin/core.key` | File; Web bind mount in `compose.json` |
-| `admin/digests.json` | `admin/core-key-digests.json` | File; Core bind mount in `compose.json` |
-| `AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE` | `AGENTS_API_CORE_KEY_DIGESTS_FILE` | `config/core.env`; its value names the renamed file |
-| `CORE_CONSOLE_ADMIN_TOKEN_FILE` | `CORE_CONSOLE_CORE_KEY_FILE` | Web `environment` in `compose.json` |
-| `--admin-token-file` | `--core-key-file` | `install.sh --web-only` flag; the installer rejects the old flag |
-| `AGENTS_API_DAEMON_WS_URL` (a `wss://…/api/v1/agent-daemon/ws` URL) | `AGENTS_API_PUBLIC_URL` (the origin only, such as `https://core.example`) | `config/core.env` |
-| `AGENTS_API_CONFIG_FILE` | None; delete the line | `config/core.env` |
+It asks for confirmation (`--yes` skips it), stops Web, writes a new key to
+`secrets/core.key`, regenerates the digest file, restarts Core and then starts Web. It
+checks that Core accepts the new key and refuses the old one. The old key stops working
+at once and every console session ends: sign in again and update your scripts. If the
+command stops early, `secrets/core.key` holds the key to use; run `parsar apply` to
+finish.
 
-Also remove `CORE_CONSOLE_AUTH_MODE`, `CORE_CONSOLE_STATE_DIR` and
-`CORE_CONSOLE_PASSWORD_FILE` from Web's environment, with their `state/console`
-and `config/console.password` mounts. Web no longer has accounts, passwords or
-Basic authentication, and it refuses to start while those settings are present.
-The old account state is not read; delete it after the upgrade or keep it as a
-backup. Then start the services and sign in with the Core key.
-
-The deployment no longer stores the Core address, and nodes keep the one they
-enrolled with. For an installation made before `AGENTS_API_PUBLIC_URL` existed,
-`install.sh --convert` takes the public URL from the sandbox deployment's
-`core_url` when the installation had none, and stops when the two differ, so
-existing nodes stay bound. Later installations already name the address in
-`config/core.env`, and conversion keeps it. It also moves the database password into
-`secrets/database.password`. For a Core you run without the installer, read
-`GET /core/v1/sandbox/deployment` with the Core key before upgrading and set
-`AGENTS_API_PUBLIC_URL` to its `core_url`; with any other value, every existing
-node counts as bound to another address and must be re-added. Optionally move the
-password out of `AGENTS_API_DATABASE_URL` into the file named by
-`AGENTS_API_DATABASE_PASSWORD_FILE`.
+A separate Web-only installation keeps its own copy of the key. After rotating, copy
+`secrets/core.key` from the Core host into that installation's `secrets/core.key`
+(mode `0600`) and run its `parsar apply`. Its `parsar status` reports a key that Core
+refuses. `rotate-core-key` refuses to run on a Web-only installation.
 
 ## Projects and API keys
 
-Use Web, or the [Core API](../../contracts/agents-api/admin-api.md) under
-`/core/v1/projects` with the Core key, to create a Project and issue its first key
-after installation. No configuration file
-defines Projects or application keys. API-key plaintext is returned once at issuance,
-with only its digest stored in the database.
+Create Projects and issue their keys in Web, on **Projects and keys**, or with the
+[Core API](../../contracts/agents-api/admin-api.md) under `/core/v1/projects`. A key's
+plaintext is shown once; Core stores only its digest. All keys of a Project share its
+assets and execution principal, and each write records the key that made it.
 
-To rotate, issue another key within the same Project, update the application, then
-revoke the old key. Renaming a Project or revoking a key preserves its assets and
-execution principal. Archiving a Project disables all its keys while retaining
-assets and already accepted execution. Administrators may inspect or delete retained
-resources; they cannot execute them using the Core key.
+To rotate an application key, issue another key in the same Project, update the
+application, then **Revoke** the old key. **Archive** disables all of a Project's keys
+and keeps its assets and accepted work. Administrators can inspect and delete retained
+resources but can't execute with the Core key.
 
 ## Data and upgrades
 
-Retain together:
-
-- the dedicated PostgreSQL volume, including Projects, API-key digests, provenance
-  and large objects;
-- the installation directory: `config.json`, `state.json` (installation identity)
-  and `secrets/`, whose `credential.key` must stay with the database and whose
-  `core.key` is the [Core key](#core-key), including on zero-node installations;
-- the database-owned deployment specification;
-- each separately installed node's private configuration and persistent identity
-  directory on its host (`/var/lib/parsar-node/.parsar/nodes/<installation-id>/` for a
-  node added with sudo, `~/.parsar/nodes/<installation-id>/` for one added as a normal
-  user), as described in the
-  [node guide](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#register-a-host);
-- E2B's private `state/e2b` receipts and SDK connection materials when selected;
-- microsandbox's private state/cache/disks/snapshots, or Docker-owned Runtime
-  volumes and histories;
-- the exact distribution and private deployment configuration needed to recover.
-
-Do not replace a missing node identity directory with a fresh registration;
-restore its original saved state alongside the database and provider storage.
-Restarting the same installation preserves the directory.
-
-Never regenerate the encryption key to resolve an error: stored Session/model and
-Vault credentials require it. Never prune Docker volumes or delete native history
-to make a retry pass. Public Session deletion acknowledgement does not prove that
-all physical provider resources have been reclaimed.
-
-The installer supports fresh installation, same-release repair and
-[conversion](install.md#convert-an-earlier-installation) of an installation made
-before `config.json`. It refuses automatic replacement of an installed revision. For a reviewed upgrade,
-back up the coordinated state, retain the previous distribution, settle execution,
-apply the existing Core migration workflow and replace matched service/Runtime
-artifacts while retaining identities and backend paths. Qualify recovery before
-claiming the upgrade complete; there is no downgrade or history migration promise.
-
-Upgrading to a release that serves node connections at `/api/v1/sandbox-node/*`:
-
-1. Core and its nodes must come from the same distribution; the node installer
-   refuses a mismatched release. Nodes from releases that used the removed
-   `/core/v1/sandbox/enroll` and `/core/v1/sandbox/node/*` paths cannot connect to
-   the new Core. For a Docker or microsandbox deployment, drain with the previous
-   release while its nodes are still connected (steps 1–2 below).
-2. When the new Core and Web go live, change the reverse proxy so that `/api/v1/*`,
-   including WebSocket upgrades, goes directly to Core instead of Web (see
-   [Expose Core and Web](install.md#expose-core-and-web)). The new Web returns 404
-   for `/api/v1`. With the old routing, node enrollment fails and so does every
-   Runtime daemon connection (`/api/v1/agent-daemon/ws`), for Docker, microsandbox,
-   self-hosted and E2B sandboxes alike.
-3. Complete steps 3–4 below with the new distribution's Runtime release. On each
-   node host, stop the old node service and move `~/.parsar/nodes/<installation-id>/`
-   aside as a backup before running the new command from Web.
-
-The installer refuses flags on an existing installation; change process settings
-in `config.json` with `parsar apply`. Rerunning it does not resize sandboxes or
-replace the database selection. Use Web
-or the administrator API for the initial selection and all later provider,
-per-sandbox resource or Runtime changes:
-
-1. Read the current deployment generation and enter global maintenance. Existing
-   work, reads and cleanup remain available; fresh hosted admission stops.
-2. Verify both allocation and pending-Environment counts are zero. Stopped
-   compute, retained snapshots and uncertain cleanup still count. Explicitly
-   [archive each retained hosted Session](../../contracts/agents-api/admin-api.md#administrative-session-archive)
-   through the administrator API with the current generation, read until its
-   resource disposition is `released`, then recheck both counts. Archive retains
-   history and persisted Files/Artifacts, discards unpersisted workspace contents
-   and prevents the original Session from resuming. Unknown cleanup still blocks
-   replacement; an active Turn may finalize after its resources are released.
-3. Submit the complete replacement with the current generation and unchanged Core
-   origin. A failed candidate keeps the previous configuration. A successful
-   changed commit retires old nodes and enrollment tokens while retaining history.
-4. Explicitly resume with the returned generation, then enroll matching nodes where
-   needed. Node enrollment requires maintenance to be off; a node-backed deployment
-   admits hosted work only after a ready node has capacity.
-
-See the [deployment contract](../../contracts/agents-api/sandbox-deployment.md) for
-exact requests and errors. After an uncertain response, read the deployment before
-another write. Editing a node file cannot change its generation, Runtime or resource
-profile; a mismatch fails without replacing identity or resources.
-
-Older installations using `AGENTS_API_MANAGED_RUNTIMES_FILE` must retain their
-previous release and backend while settling and draining work. Current Core rejects
-that setting and does not automatically adopt the old database after it is removed.
-Keep the original business data, credential key, Runtime history and private provider
-state. There is no automatic old-database conversion, force reset or resource deletion.
-The supported current path uses a database-managed deployment.
-
-A Web-selected Docker or microsandbox deployment saved before deployment
-specifications existed has an empty specification after migration. Its nodes use
-the removed `/core/v1/sandbox` node paths, so draining it needs a Core that has the
-pre-specification drain mode (pull request #114) but still serves those paths. No such release
-has been published: build a distribution from main commit
-`7b66be236a627246c85658722314285e6b39d9b8`, or any commit that contains #114 but not
-the move to `/api/v1/sandbox-node`. That Core loads the deployment only to drain:
-nodes enrolled under the previous release reconnect with their existing node
-service, and their sandboxes stay reachable for archive and cleanup. Fresh sandbox
-creation, node configuration reads and enrollment are refused. Back up as above,
-replace Core and Web with that build and complete steps 1–2. Only then upgrade to
-this release, change the reverse proxy as described above and use steps 3–4 with
-its Runtime release. The replacement retires the old nodes. Stop each retired node
-service, move its identity directory aside as a backup, and add the host again
-with a new command from Web. Node IDs change; Session history and
-persisted Files/Artifacts remain. E2B deployments from that period are not covered.
+### Back up
+
+Back up these together; a restore needs all of them:
+
+- the PostgreSQL volume `<project>_database`. It holds Projects, key digests, nodes,
+  default models, encrypted credentials and all execution history, including large
+  objects. A logical dump:
+
+  ```sh
+  docker compose -f "$HOME/.parsar/core/generated/compose.json" exec -T database \
+    pg_dump -U agents_api agents_api > parsar-backup.sql
+  ```
+
+- the installation directory: `config.json`, `state.json` (installation ID) and
+  `secrets/`. `credential.key` must stay with the database, or stored credentials can't
+  be decrypted; never regenerate it to get past an error.
+- `state/e2b/`, when E2B is used: receipts Core needs to clean up E2B sandboxes.
+- each node's state directory on its host,
+  `/var/lib/parsar-node/.parsar/nodes/<installation-id>/` (sudo mode) or
+  `~/.parsar/nodes/<installation-id>/` (no sudo), with its provider storage: Docker
+  volumes or microsandbox's store.
+- the bundle you installed from, to repair or recover the same release.
+
+A missing node state directory is a recovery incident: restore it with the database
+and provider storage rather than registering over existing resources. Never prune
+Docker volumes or delete native history to make a retry pass. A deleted Session does
+not prove that all provider resources were reclaimed.
+
+### Upgrade an installation
+
+| Installation | How to upgrade |
+| --- | --- |
+| Made before `config.json` (it has `installation.json`) | [Convert it](#convert-an-earlier-installation) with the new bundle |
+| Made with `config.json`, same release | Rerun `./install.sh` from the same bundle to repair it |
+| Made with `config.json`, other release | Not automated yet: the installer refuses a bundle from another release |
+
+For an upgrade the installer does not automate, back up as above, keep the previous
+bundle, let execution settle, and apply the new release's migrations with its matched
+Core, Web and Runtime, keeping the installation ID and backend paths. Qualify recovery
+before calling the upgrade done; there is no downgrade.
+
+### Convert an earlier installation
+
+Installations made before `config.json` have `installation.json`, `config/core.env` and
+`admin/`: those of every installer since the Core key was introduced. Plain
+`./install.sh` refuses them. Convert one with the new release's bundle:
+
+```sh
+./install.sh --convert --install-dir "$HOME/.parsar/core"
+```
+
+Conversion is also an upgrade to that release, and its database migrations can't be
+undone: back up first (the command prints a `pg_dump` command). It reads the old files
+without changing anything, shows the resulting settings and asks for confirmation
+(`--yes` skips it). It then writes `config.json` and `state.json`, moves the secrets
+into `secrets/` without copying them, removes the old generated files, and starts the
+new release with the same Compose project, database and installation ID. Settings set
+by hand, such as `AGENTS_API_EXECUTION_CONCURRENCY`, `PARSAR_LOG_*` or a Runtime history
+file, move into `config.json`.
+
+It stops before changing anything, listing each reason, when something can't be
+converted: an edited `compose.json`, an unknown or edited generated value in
+`core.env`, an external database, or an installation public URL that differs from the
+sandbox deployment's Core URL. For that last case, rerun with `--public-url` naming one
+of the two; choosing the installation's URL means the deployment's nodes must be added
+again. Unknown files in `config/` and `admin/` are reported and left in place.
+
+If conversion is interrupted, or the new release fails to start, fix the cause and rerun
+`./install.sh --convert` with the same bundle; `--public-url` may be repeated but not
+changed. In a split deployment, convert the Core host first, then each Web-only host,
+and run the Web host's `parsar apply` afterwards.
+
+### Upgrade notes
+
+Current Core and Web refuse to start while a retired setting is present, and the error
+names the replacement:
+
+| Retired | Replacement | Where |
+| --- | --- | --- |
+| `AGENTS_API_EXECUTION_OPTIONS_FILE` | Default models, set per harness in Web (**System**, **Default model**) or with `PUT /core/v1/harnesses/{harness}/model-provider` | `config/core.env`. `--convert` does not carry it over; it leaves the file, which may hold model keys, and reports it. Delete the file once the defaults are set |
+| `AGENTS_API_DAEMON_WS_URL` (a `wss://…/api/v1/agent-daemon/ws` URL) | `AGENTS_API_PUBLIC_URL` (the origin, such as `https://core.example`), or `public_url` in `config.json` | `config/core.env` |
+| `AGENTS_API_CONFIG_FILE` | None; delete the line | `config/core.env` |
+| `AGENTS_API_MANAGED_RUNTIMES_FILE` | The sandbox deployment in the database, set in Web | `config/core.env`; see [older file-managed installations](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#older-file-managed-installations) |
+| `admin/sandbox-admin.key`, `admin/digests.json` | `admin/core.key`, `admin/core-key-digests.json` (conversion then moves them to `secrets/` and `generated/`) | Files and their `compose.json` mounts |
+| `AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE` | `AGENTS_API_CORE_KEY_DIGESTS_FILE` | `config/core.env` |
+| `CORE_CONSOLE_ADMIN_TOKEN_FILE`, `install.sh --admin-token-file` | `CORE_CONSOLE_CORE_KEY_FILE`, `--core-key-file` | Web environment; installer flag |
+| `CORE_CONSOLE_AUTH_MODE`, `CORE_CONSOLE_STATE_DIR`, `CORE_CONSOLE_PASSWORD_FILE` | None: Web has no accounts or passwords; sign in with the Core key | Web environment, with their `state/console` and `config/console.password` mounts |
+| `install.sh --sandbox-provider`, `--provider` | `install.sh --sandbox`; add the Core host as a node with Add node | Installer flags |
+| `install.sh --status`, `--stop` | `parsar status`, `parsar stop` | Installer flags |
+| `PARSAR_NODE_ENROLLMENT_TOKEN` | The token on standard input with `--enrollment-token-stdin`, as Web's Add node command passes it | Node installer |
+
+Rename or remove the old names of an installation made before `config.json` before
+converting it. Hosted and self-hosted Sessions that relied on the retired options file
+have no model provider of their own and can't start new work after the upgrade. Count
+them before converting, from the new bundle:
+
+```sh
+python3 model_provider_sessions.py --install-dir "$HOME/.parsar/core"
+```
+
+Recreate them with `x_agents_core.model_provider` or an Agent that has one saved.
+
+The deployment no longer stores a Core address; nodes keep the one they enrolled with.
+For a Core you run without the installer, read `GET /core/v1/sandbox/deployment` with
+the Core key before upgrading and set `AGENTS_API_PUBLIC_URL` to its `core_url`; with
+any other value, every existing node counts as bound to another address and must be
+added again.
+
+#### Node connections at /api/v1
+
+Core and its nodes must come from the same distribution; the node installer refuses a
+mismatched release. Nodes from releases that used the removed `/core/v1/sandbox/enroll`
+and `/core/v1/sandbox/node/*` paths can't connect to a current Core. For a Docker or
+microsandbox deployment:
+
+1. Drain with the previous release while its nodes are connected: enter maintenance,
+   archive retained hosted Sessions and wait until nothing is retained (the
+   [maintenance procedure](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)).
+2. When the new Core and Web go live, route `/api/v1/*`, including WebSocket upgrades,
+   to Core instead of Web ([HTTPS and the reverse proxy](install.md#https-and-the-reverse-proxy)).
+   Web returns 404 for `/api/v1`; with the old routing, node enrollment and every Runtime
+   connection fail.
+3. Save the new release's Runtime, resume, and add the nodes again. On each node host,
+   stop the old node service and move its state directory aside as a backup first.
+
+A Web-selected Docker or microsandbox deployment saved before deployment specifications
+existed has an empty specification after migration. Draining it needs a Core that has
+the pre-specification drain mode (pull request #114) but still serves the old node
+paths. No such release was published: build a distribution from main commit
+`7b66be236a627246c85658722314285e6b39d9b8`, or any commit that contains #114 but not the
+move to `/api/v1/sandbox-node`. That Core loads the deployment only to drain; fresh
+sandboxes, node configuration reads and enrollment are refused. Back up, replace Core
+and Web with that build, drain as in step 1, then upgrade to the current release and
+continue with steps 2 and 3. Node IDs change; Session history and persisted Files and
+Artifacts remain. E2B deployments from that period are not covered.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `Run as a non-root user on Linux amd64 with Docker access` | Run `install.sh` as a normal user who can run `docker` |
+| `Docker Compose 2.26.0 or newer is required …` | Update the Docker Compose plugin |
+| `Port N is already in use; select another port` | Free the port, or install with `--core-port`/`--web-port` |
+| `Installation directory is not empty …` | Use an empty `--install-dir` |
+| `This installation is configured by …/config.json …` | Flags only seed a new installation: edit `config.json` and run `parsar apply` |
+| `This installation predates config.json …` | [Convert it](#convert-an-earlier-installation) |
+| `This installation runs another release …` | See [Upgrade an installation](#upgrade-an-installation) |
+| `generated/<file> was edited by hand` | Put the change in `config.json`, then `parsar apply --discard-edits` |
+| `config.json has changes that are not applied` | Run `parsar apply` |
+| `Core rejects secrets/core.key …` | Run `parsar apply`, which restarts Core with the key's digest |
+| `config.json not applied: …` | `parsar apply` printed Core's startup error above; fix `config.json` and apply again |
+| Web answers 403 `Forbidden` | Open exactly the console address `parsar status` prints; the reverse proxy must pass the original Host |
+| `/v1` or `/api/v1` answers 404 | Those paths reach Web; route them to Core ([reverse proxy](install.md#https-and-the-reverse-proxy)) |
+| Web shows that Core is unavailable (502) | Core is stopped or failing: `parsar status`, 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 |
+| Add node says nodes need an HTTPS public URL | Set `public_url` and run `parsar apply` |
+| Add node says the console has no node files | Install from the offline bundle, or add the node files and rerun `./install.sh` |
+| A node is not ready | See [node troubleshooting](nodes.md#troubleshooting) |
 
 ## Exposure and network policy
 
-API and console bind to host loopback. With native Core, PostgreSQL publishes an
-installation-specific loopback port; with container Core it has no published port.
-After console login and same-origin checks, the production Web proxy forwards every
-`/core/v1` request to Core with the Core key, which stays on the server; Core
-decides which routes exist. The TLS reverse proxy routes `/v1` (applications) and
-`/api/v1` (node and Runtime daemon connections) directly to Core. Everything else,
-including console pages, authentication and `/core/v1`, goes to Web. Operator
-scripts call `/core/v1` with the Core key on Core's loopback port. Web returns 404 for
-`/v1` and `/api/v1`, whatever credential a request carries, and forwards no node or
-daemon traffic. Machine routes keep their own enrollment and connection credentials.
-`/node-install/` serves only the matched non-secret node payload. Web has no Docker
-or KVM authority.
-It requires [Core key](#core-key) sign-in and rejects untrusted browser origins.
-There is only one Web role, with full console authority; Agent API caller keys
-remain separate. Sessions live in Web's memory, so sign in again after a Web
-restart or Core key rotation.
-
-A Core restart leaves the separately supervised node and resident microVM processes alone. Host reboot, user
-manager termination and loss of a running microVM are not equivalent to that
-restart and are not qualified cold-recovery workflows. Completed idle snapshots retain their existing recovery contract. When native restore
-omits a configured root-disk size, the exact verified full snapshot must prove the
-inherited capacity; CPU, memory and environment-disk limits still need to match.
-A missing or mismatched proof does not authorize resize or replacement.
-
-microsandbox uses an explicit policy: public egress, the Core/DNS host ports needed
-for the colocated Runtime, and denied inbound/private-network access. Private
-model/MCP endpoints require an explicit operator policy change. Native tool network
-policy remains the Session's separate public configuration.
-
-The Docker node uses the existing nested-sandbox Runtime policy. Its service account
-needs access to the selected host Docker daemon; Core has no Docker socket mount.
-Install on a trusted node host and do
-not share its Docker authority with untrusted users. The default installation
-does not mount the Docker socket or host devices into Core, import Runtime images
-or generate managed Provider configuration.
-
-Host virtualization, credentials, tenant isolation, durable state and actual
-execution are release acceptance requirements. Other missing operational screens
-or low-frequency improvements belong in the backlog; they do not turn this batch
-into a Web redesign or a complete protocol-compatibility claim.
+Core and Web listen on host loopback; PostgreSQL has no published port unless Core is
+native. Your TLS reverse proxy routes `/v1` and `/api/v1` to Core and everything else to
+Web. Web signs administrators in with the Core key, checks the origin of every request,
+and forwards signed-in `/core/v1` requests to Core with the Core key, which stays on
+the server. It answers 404 on `/v1` and `/api/v1` whatever credential a request carries,
+serves only the non-secret node payload at `/node-install/`, and has no Docker or KVM
+access. Machine routes keep their own enrollment and connection credentials. Web
+sign-in sessions live in Web's memory and last 12 hours.
+
+microsandbox uses an explicit network policy: public egress, the Core and DNS ports the
+Runtime needs, and no inbound or private-network access. Private model or MCP endpoints
+need an explicit policy change. A Session's own network policy is separate.
+
+The Docker node uses the nested-sandbox Runtime policy. Its service account needs the
+host's Docker daemon, and Core has no Docker socket. Install nodes on trusted hosts and
+don't share their Docker access with untrusted users.
+
+A Core restart leaves node services and resident microVMs running. A host reboot, the
+end of a user manager or the loss of a running microVM is not a Core restart and is not
+a qualified recovery workflow. Idle snapshots keep their recovery contract.
 
 ### API-key write history
 
-Core records committed public resource writes and their key ownership for the
-administrator console. Set `core.write_audit_retention` in `config.json` (Go
-duration, minimum `1h`, default `2160h`) to control non-creation history. Creation ownership
-remains permanently; removing keys or resources does not cascade-delete records.
-Projects and their API keys are database records. Keys within one Project share
-assets and the same execution principal, while provenance identifies the actual
-key that made each write. Existing resources without recorded provenance return
-null. Historical key-kind metadata remains audit evidence, not a configuration
-authentication path. The Core key is separate from Project API keys. See the
-[query contract](../../contracts/agents-api/write-audit.md) for deployment-authenticated
-Project-scoped batch ownership and cursor history endpoints. Administrator mutations
-have a separate [audit log](../../contracts/agents-api/admin-api.md#monitoring-and-audit). These APIs do not log bodies or secrets.
+Core records which key made each public resource write, for the console. Set
+`core.write_audit_retention` in `config.json` (Go duration, at least `1h`, default
+`2160h`) to control how long non-creation history is kept; creation ownership is kept
+for good. Removing keys or resources does not delete these records. See the
+[query contract](../../contracts/agents-api/write-audit.md); administrator mutations
+have a separate [audit log](../../contracts/agents-api/admin-api.md#monitoring-and-audit).
+Neither logs bodies or secrets.
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index f8eb33f7a..29fbceaf4 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -1,67 +1,53 @@
-# Call your Core
+# Call the API
 
-Install Core using the [installation guide](install.md). Your Core API credential
-authenticates the caller to your installation. It is separate from the model
-provider key used by a native harness. Neither key belongs in source control.
+Core serves the OpenAI Agents API. Applications use the official OpenAI SDK with two
+environment variables, which the SDK reads by default:
 
-Use the fixed client baseline:
+| Variable | Value | From |
+| --- | --- | --- |
+| `OPENAI_BASE_URL` | The installation's API base URL: its public URL followed by `/v1`, such as `https://core.example/v1` | The administrator; Web's **System** page shows it as **API base URL** |
+| `OPENAI_API_KEY` | A Project API key | The administrator issues it on **Projects and keys**; see [Sign in to Web](install.md#sign-in-to-web) |
+
+The Project API key authenticates your application to this Core. It is separate from
+the model provider's key that a harness uses, and neither belongs in source control.
+The API base URL reaches Core directly; Web does not serve `/v1`.
+
+## First request
+
+Use the pinned client version:
 
 ```sh
 python3 -m venv .venv
 . .venv/bin/activate
 pip install openai==3.13.0
+export OPENAI_BASE_URL=https://core.example/v1
+export OPENAI_API_KEY=<project API key>
 ```
 
-The deployment administrator first creates a Project and issues a key within it,
-on Web's **Projects and keys** page or with the [Core key](operations.md#core-key)
-as Bearer credential: `POST /core/v1/projects` with `{"name":"Default"}`, then
-`POST /core/v1/projects/{project_id}/keys` with a descriptive `{"name":"..."}`.
-
-Obtain that key through a private channel and set it as `OPENAI_API_KEY` in your
-application's environment. Set `OPENAI_BASE_URL` to the installation's API base
-URL: `api_base_url` in `GET /core/v1/installation`, which is the public URL followed
-by `/v1`, such as `https://core.example/v1`. The official SDK reads both variables.
-The key's plaintext appears only at issuance; Core stores a digest in its database.
-All keys in the Project share assets, permissions and the same execution principal,
-while write provenance records the actual key. Other Projects remain isolated. The
-installer creates neither a Project nor an API key. The API base URL reaches Core
-directly; the console does not proxy `/v1`.
-
 ```python
 from openai import OpenAI
 
-# Reads OPENAI_API_KEY and OPENAI_BASE_URL.
-client = OpenAI(default_headers={"OpenAI-Beta": "agents=v1"})
+client = OpenAI()  # reads OPENAI_BASE_URL and OPENAI_API_KEY
 print(client.beta.agents.list().data)
 ```
 
-Rotate an application key by issuing a replacement in the same Project and revoking
-the old key. Assets and the Project principal remain unchanged. Archiving a Project
-disables every key while preserving assets and already accepted work. The deployment
-administrator credential cannot substitute for an application key on `/v1`.
+This read checks access; it runs no model and creates no sandbox. The same request
+with curl:
 
-This read verifies API access. It does not invoke a model or create an execution
-environment. Installation has no mandatory sample task.
-
-## Run a Session when you are ready
+```sh
+curl "$OPENAI_BASE_URL/agents" -H "Authorization: Bearer $OPENAI_API_KEY" -H "OpenAI-Beta: agents=v1"
+```
 
-This example requires a connected node whose provider is ready. The default
-installation selects Docker sandboxes and has zero execution nodes: sign in to Web
-and [add a node](install.md#add-nodes-after-a-default-installation), the Core host
-included. You do not need to reinstall Core or change installer flags to add nodes
-in Web.
+All keys of a Project share its assets and execution principal; other Projects are
+isolated. When the administrator rotates your key, they issue a new one in the same
+Project and revoke the old one; your assets stay.
 
-Core creates the sandbox through its Provider using the prepared Runtime image,
-then initializes the daemon, native harness and workspace inside it. You do not
-install or start a separate daemon for a Core-managed Session. The public discriminator remains
-`openai_hosted`; in this deployment it means the sandbox managed by Parsar Core.
-The installation's provider can be microsandbox or Docker.
+## Run a Session
 
-If the administrator set a deployment default model provider for the harness (Web,
-System), a hosted Session needs only `agent.model`. Otherwise, or to use your own
-endpoint, pass the provider with the request. For a Codex-compatible Responses
-endpoint, provide your actual model name, endpoint and key through your
-application's private configuration:
+A Core-hosted Session (`openai_hosted`) runs in a sandbox that Core creates: on a node
+with free capacity, or on E2B. Core prepares the daemon, native harness and workspace
+inside it. The installation needs a ready node or an E2B backend; see
+[Nodes](nodes.md).
 
 ```python
 import os
@@ -86,33 +72,57 @@ session = client.beta.agents.sessions.create(
 print(session.id)
 ```
 
-Running this example makes a real model request and may incur provider charges.
-`extra_body` carries existing Core extensions: harness selection and write-only
-model configuration. They are not fields in the official SDK 3.13.0 protocol.
-The service encrypts model configuration with tenant/Session binding and never
-returns the secret through public resource reads. A `self_hosted` Session must
-always carry its own provider this way or through a saved Agent; deployment
-defaults apply to `openai_hosted` and `none`, never to `self_hosted`. Keep the installation's
-credential encryption key and database together across restarts.
-Keep the complete `agent` object together: SDK 3.13.0 replaces an ordinary body
-field with the corresponding `extra_body` field rather than merging nested fields.
+This makes a real model request and may incur charges. If the administrator set a
+default model for the harness, omit `x_agents_core.model_provider`; `agent.model` is
+still required. SDK 3.13.0 replaces an ordinary body field with the matching
+`extra_body` field instead of merging nested fields, so keep the whole `agent` object
+in `extra_body`.
+
+## Core extensions: x_agents_core
 
-The model must support the selected harness's native protocol:
+`/v1` has exactly the official routes. Core's additions are fields inside
+`x_agents_core`, passed through `extra_body`; any other member is rejected with 400.
 
-| Harness selector | Model protocol | Additional input |
+| Field | Where | Meaning |
 | --- | --- | --- |
-| `codex` | `responses` | Exact provider model ID |
-| `claude_sdk` | `anthropic` | Exact provider model ID |
-| `mcode` | `anthropic` | Actual `context_window` and `max_output_tokens` limits |
+| `x_agents_core.harness` | A saved Agent, or the Session's inline `agent` | Which native harness runs the Agent: `codex`, `claude_sdk` or `mcode`. Omitted: the installation's default harness (`core.default_harness`, Codex unless changed) |
+| `x_agents_core.model_provider` | A saved Agent, or Session creation | The model provider bundle: `protocol`, HTTPS `base_url`, write-only `api_key`, and for `mcode` also `context_window` and `max_output_tokens`. Reads return `api_key_configured` instead of the key |
 
-See [harness selection](https://github.com/MiniMax-AI/parsar-core/blob/main/contracts/agents-api/harness-selection.md) and
-[model execution](https://github.com/MiniMax-AI/parsar-core/blob/main/contracts/agents-api/model-execution.md) for the complete
-extension contract. Native capabilities differ; selecting an engine does not make
-an unsupported model or operation work.
+The provider's protocol must match the harness:
 
-## Observe and recover
+| Harness | `protocol` | Also required |
+| --- | --- | --- |
+| `codex` | `responses` | The provider's exact model ID in `agent.model` |
+| `claude_sdk` | `anthropic` | The provider's exact model ID |
+| `mcode` | `anthropic` | `context_window` and `max_output_tokens` |
+
+See [harness selection](../../contracts/agents-api/harness-selection.md) and
+[model execution](../../contracts/agents-api/model-execution.md) for the full contract.
+Selecting a harness doesn't make an unsupported model or operation work.
+
+## Model providers
+
+A Session takes its model provider from the first of these that has one; bundles are
+never merged:
 
-Query execution history from your application:
+1. `x_agents_core.model_provider` in the Session creation request;
+2. the saved Agent's `x_agents_core.model_provider`;
+3. the installation's default model for the harness, set in Web on **System**,
+   **Default model**.
+
+| Environment | Request or saved Agent | Default model | None of them |
+| --- | --- | --- | --- |
+| `openai_hosted` | Used | Used | 400 `model_provider_required` |
+| `self_hosted` | Used | Never | 400 `model_provider_required` |
+| `none` | Rejected with 400 | Used | Allowed: the device's own environment supplies the model |
+
+A Session freezes its provider when it is created; later changes to the Agent or the
+default affect only new Sessions. Core encrypts the key with the Session and never
+returns it. Self-hosted Sessions always bring their own provider, because the default
+holds the operator's key and the executor host belongs to the application; see
+[Self-hosted executors](self-hosted.md).
+
+## Observe and recover
 
 ```python
 current = client.beta.agents.sessions.retrieve(session.id)
@@ -121,12 +131,12 @@ items = client.beta.agents.sessions.items.list(session.id)
 print(current.id, turns.data, items.data)
 ```
 
-Wait for the Turn's terminal result before treating a task as complete. After a
-client disconnect, recover through Session, Turn and Items queries. SSE is a live
-stream, not a historical replay mechanism. Do not automatically submit the same
-work as a new Session when a response is lost.
+Wait for the Turn's final state before treating a task as done. After a disconnect,
+recover through Session, Turn and Items reads: the event stream is live only and does
+not replay history. Don't submit the same work as a new Session when a response is
+lost.
 
-Files, Artifacts, cancellation, credential management and their current limits
-are documented in the [coverage ledger](https://github.com/MiniMax-AI/parsar-core/blob/main/contracts/agents-api/README.md).
-MCP credentials use the separate Vault API; they are not Core caller keys or
-model-provider credentials.
+Files, Artifacts, cancellation and their current limits are in the
+[coverage ledger](../../contracts/agents-api/README.md). MCP credentials use the
+separate Vault API; they are neither Project API keys nor model provider keys. The
+[API index](../api/README.md) lists every route.
diff --git a/docs/getting-started/self-hosted.md b/docs/getting-started/self-hosted.md
new file mode 100644
index 000000000..b5f08c768
--- /dev/null
+++ b/docs/getting-started/self-hosted.md
@@ -0,0 +1,129 @@
+# Self-hosted executors
+
+A `self_hosted` Session runs on a machine the application owns, the executor host,
+instead of a node. The application creates the Session through `/v1`; the
+administrator issues an executor credential for it in Web; one command on the host
+starts a Runtime container that connects to Core. The Runtime is the same one nodes
+use: daemon, native harness and workspace.
+
+An executor credential works for one Session's environment only. It can't call the
+Agent API, the Core API or node enrollment.
+
+## Before you start
+
+- **Core has an HTTPS public URL.** The Session's `remote_url` is
+  `wss://<public host>/api/v1/agent-daemon/ws`, and the installer connects only over
+  `wss://`. Web shows no command until Core has a reachable public URL.
+- **Web holds the Runtime files.** The installer downloads the Runtime launcher and
+  image from your console, as nodes do; install Core from the offline bundle.
+- **The host** runs Linux amd64 with Python 3.9+, `curl` and `sha256sum`, and Docker
+  usable by a non-root user through `/var/run/docker.sock`. It reaches the public URL
+  over HTTPS.
+- **The Session carries its model provider**, in the request or saved on its Agent.
+  Default models never apply to self-hosted Sessions, and creating one without a
+  provider fails with 400 `model_provider_required`.
+
+## Connect a host
+
+1. **The application creates the Session**, with its Project API key and its own model
+   provider:
+
+   ```python
+   import os
+   from openai import OpenAI
+
+   client = OpenAI()  # reads OPENAI_BASE_URL and OPENAI_API_KEY
+   session = client.beta.agents.sessions.create(
+       environment={"type": "self_hosted", "workspace_directory": "/workspace"},
+       extra_body={
+           "agent": {"model": os.environ["MODEL_NAME"], "x_agents_core": {"harness": "codex"}},
+           "x_agents_core": {"model_provider": {
+               "protocol": "responses",
+               "base_url": os.environ["MODEL_BASE_URL"],
+               "api_key": os.environ["MODEL_API_KEY"],
+           }},
+       },
+   )
+   print(session.id, session.environment.id, session.environment.remote_url)
+   ```
+
+2. **In Web**, open **Session log**, then the Session's page. Its
+   **Executor credentials** section shows **Connect a host** with the
+   **Executor install command**. Copy it and run it on the executor host:
+
+   ```sh
+   (umask 077; d=$(mktemp -d) || exit; trap 'rm -rf "$d"' EXIT
+   curl -fsS --max-time 30 --max-filesize 1048576 'https://core.example/node-install/self-hosted-install.pyz' -o "$d/install.pyz" &&
+   printf '%s  %s\n' '<installer-sha256>' "$d/install.pyz" | sha256sum -c --status &&
+   python3 "$d/install.pyz" --source-url 'https://core.example' --environment-id '<environment-id>' --remote 'wss://core.example/api/v1/agent-daemon/ws')
+   ```
+
+   The command contains no secret. It downloads the installer from your console and
+   checks its SHA-256 before running it.
+3. **Issue the credential.** Select **Issue credential**, then **Copy credential**.
+   Web shows it once.
+4. **Paste it at the installer's hidden prompt** and press Enter. The prompt accepts the
+   compact or the pretty-printed credential and never echoes it.
+
+The installer downloads the Runtime from the console and checks it, starts a container
+named `parsar-selfhost-<32 hex digits>`, and waits until Core confirms that the
+Environment is connected. The Session then runs its Turns there. The command is safe
+to rerun; it resumes the same installation.
+
+For automation without a terminal, choose **Download credential file**, make it private
+(`chmod 600`), and add `--credential-file /absolute/path/executor-key.json` to the
+installer line. The path must not go through a symbolic link.
+
+The host keeps its state in `~/.parsar/self-hosted/<environment-id>/`
+(`--install-dir` chooses another absolute directory). Keep it with the container's
+volumes: they hold the credential, workspace and native history. The Runtime's log is
+`docker logs <container>`. A connected Environment proves the connection, not that the
+model works; send the Session a Turn to test execution.
+
+Core delivers the Session's model provider only over this Environment's executor
+connection. The host keeps it in the Runtime's harness home, where the model's tools
+and the Files API can't read it but the host's owner can.
+
+## Rotate or revoke
+
+| Action in Web | Effect |
+| --- | --- |
+| **Rotate** | The credential gets a new secret; the old secret stops working at once. Rotating a revoked credential restores it |
+| **Revoke** | The credential stops working at once |
+
+After either, the Runtime disconnects and stops retrying: its log shows one message
+that names the fix, and the container keeps running without a restart loop. To
+reconnect the host:
+
+1. **Rotate** the same credential in Web and copy the new secret.
+2. Rerun the same install command on the host and paste it.
+
+The installer puts the new credential into the same container, which reconnects with
+its workspace and history. Issuing a *new* credential doesn't reconnect an Environment
+that has already connected: it stays bound to its first credential, and the installer
+says to rotate that one.
+
+To remove the Runtime instead, stop its container:
+`docker --host unix:///var/run/docker.sock stop <container>`. Deleting the Session does
+not remove containers or volumes on the executor host.
+
+## Without Web
+
+Scripts on the Core host can issue credentials with the Core key through Core's
+loopback port. Choose a new UUID for the credential and keep it:
+
+```sh
+umask 077
+key_id=$(python3 -c 'import uuid; print(uuid.uuid4())')
+curl -fsS -X POST \
+  -H @<(printf 'Authorization: Bearer %s\n' "$(cat "$HOME/.parsar/core/secrets/core.key")") \
+  -H 'Content-Type: application/json' -d "{\"key_id\":\"$key_id\"}" \
+  "http://127.0.0.1:8091/core/v1/projects/$PROJECT_ID/environments/$ENVIRONMENT_ID/executor-credentials" \
+  -o executor-key.json
+```
+
+Rotate with `{"key_id":"…","rotate":true}` on the same route; revoke with
+`DELETE …/executor-credentials/<key_id>`. After an uncertain response, list the
+credentials with `GET` before trying again. The
+[credential contract](../../contracts/agents-api/environment-executor-credentials.md)
+has every rule and error.
diff --git a/docs/maintainers.md b/docs/maintainers.md
new file mode 100644
index 000000000..724cd9082
--- /dev/null
+++ b/docs/maintainers.md
@@ -0,0 +1,77 @@
+# Maintainers and advanced deployments
+
+This page is for people who build and publish Parsar Core, or run Core without the
+installer. To install Core and Web, use the [installation guide](getting-started/install.md)
+instead.
+
+## Build a distribution
+
+Release builders need the repository's full Linux toolchain and Docker. Build from
+clean, committed source, with the pinned Codex platform package and a matching MiniMax
+companion prepared through the existing Runtime build instructions:
+
+```sh
+export AGENTS_RUNTIME_CODEX_PACKAGE=/absolute/path/to/codex-linux-package
+export MCODE_HARNESS_BUILD_DIR=/absolute/path/to/mcode-harness-artifact
+export CORE_DISTRIBUTION_RELEASE_BASE_URL=https://downloads.example/releases/COMMIT
+make build-core-distribution
+```
+
+The builder reuses the existing Core, Runtime, SDK and Web build scripts. It records
+the commit, immutable image identities, microsandbox binary hashes and the actual
+Runtime OCI manifest digest. Output goes to `~/.parsar/build/core-distribution/`; it is
+not published anywhere automatically. Qualify the exact bundle before distributing it.
+See the [contributor guide](../CONTRIBUTING.md).
+
+The release base must serve the generated asset file names over HTTPS. Set
+`CORE_DISTRIBUTION_OFFLINE=1` to also produce the offline bundle; a build without a
+release base must select offline mode. Nodes always download their files from the
+console that generated their command, whatever release base the build recorded.
+
+A bundle carries a fixed set of docs (the build lists them). Links between them stay
+relative; every other relative link is rewritten to the same file on GitHub at the
+bundle's commit, and the build fails if a link or anchor does not resolve.
+
+## Produce and qualify a release
+
+The `core-release` GitHub Actions workflow builds production assets from a full
+committed source SHA with the pinned Runtime builders. Acceptance credentials and
+private test certificate authorities must never enter its inputs. Run it from the
+repository's Actions page, or:
+
+```sh
+revision=$(git rev-parse HEAD)
+gh workflow run core-release --repo MiniMax-AI/parsar-core --ref main \
+  -f ref="$revision" -f offline=true -f draft_release=true
+```
+
+The workflow uploads the matched files as an Actions artifact and, with
+`draft_release`, creates a draft Release tagged `build-<full SHA>`. The manifest records
+the same tag in every asset URL. Don't mix files across releases or resolve components
+through `latest`.
+
+Download the draft assets with repository access, verify their checksums, and qualify a
+fresh installation plus the node and self-hosted connection paths before publishing the
+draft. A workflow build alone is not live acceptance. Publish exactly the tested assets;
+never rebuild or replace files under the same release identity. Publishing a Release
+does not change the repository's visibility.
+
+## Run Core without the installer
+
+These paths give you Core alone, without Web, the `parsar` command or `config.json`.
+They are for development, testing and operators who manage Core's process themselves.
+They are not an installation path for new users.
+
+- [Standalone Core archive](../services/agents-api/RELEASE.md)
+  (`make build-agents-api-release`): Core, its migrator and operator commands for your own
+  PostgreSQL.
+- [Standalone container](../services/agents-api/CONTAINER.md)
+  (`make docker-build-agents-api`): the same in a Linux container image.
+- [Service guide](../services/agents-api/README.md): building and running Core from
+  source.
+
+Core reads only its environment; the
+[configuration appendix](configuration.md#appendix-core-environment-without-the-installer)
+lists the variables. The Docker-hosted variant of the standalone archive is retired: it
+could not describe a complete Runtime release by itself. Docker-hosted deployments use
+the Core distribution and its installer, whose manifest carries the complete release.
diff --git a/scripts/build-agents-api-release.sh b/scripts/build-agents-api-release.sh
index abe6e64e4..03e79e00c 100755
--- a/scripts/build-agents-api-release.sh
+++ b/scripts/build-agents-api-release.sh
@@ -19,6 +19,11 @@ for value in sys.argv[2:]:
         sys.exit("Agents API release directories must be absolute and under ~/.parsar")
 PY
 
+if [[ -n "${AGENTS_API_RELEASE_RUNTIME_IMAGE:-}" ]]; then
+  printf 'AGENTS_API_RELEASE_RUNTIME_IMAGE is retired: the Docker-hosted archive could not carry a complete Runtime release. Build the Core distribution (make build-core-distribution) instead\n' >&2
+  exit 1
+fi
+
 require_clean_source() {
   local source_status
   source_status="$(git -C "$repo_root" status --porcelain --untracked-files=all)"
@@ -32,14 +37,6 @@ source_revision="$(git -C "$repo_root" rev-parse HEAD)"
 source_tree="$(git -C "$repo_root" rev-parse "$source_revision^{tree}")"
 source_epoch="$(git -C "$repo_root" show -s --format=%ct "$source_revision")"
 archive_name="agents-api-$source_revision-linux-amd64.tar.gz"
-runtime_image="${AGENTS_API_RELEASE_RUNTIME_IMAGE:-}"
-if [[ -n "$runtime_image" ]]; then
-  if [[ ! "$runtime_image" =~ ^sha256:[0-9a-f]{64}$ ]]; then
-    printf 'Hosted releases require a qualified immutable Runtime image ID (sha256:...)\n' >&2
-    exit 1
-  fi
-  archive_name="agents-api-docker-$source_revision-linux-amd64.tar.gz"
-fi
 
 mkdir -p "$output_dir"
 release_context="$(mktemp -d "$output_dir/.staging.XXXXXX")"
@@ -63,17 +60,16 @@ if [[ "$(git -C "$repo_root" rev-parse HEAD)" != "$source_revision" ]]; then
   exit 1
 fi
 
-python3 - "$release_context" "$source_revision" "$source_tree" "$source_epoch" "$go_version" "$archive_name" "$runtime_image" <<'PY'
+python3 - "$release_context" "$source_revision" "$source_tree" "$source_epoch" "$go_version" "$archive_name" <<'PY'
 import gzip
 import hashlib
 import json
 import pathlib
-import subprocess
 import sys
 import tarfile
 
 root = pathlib.Path(sys.argv[1])
-revision, tree, epoch, go_version, archive_name, runtime_image = sys.argv[2:]
+revision, tree, epoch, go_version, archive_name = sys.argv[2:]
 source, package = root / "source", root / "package"
 binaries = ["agents-api", "agents-api-migrate", "agents-api-device", "agents-api-environment-key", "parsar-sandbox-node"]
 
@@ -101,25 +97,8 @@ manifest = {
     "upstream_protocol": json.loads((source / "contracts/agents-api/upstream.json").read_text(encoding="utf-8")),
     "binaries": {"bin/" + name: {"sha256": sha256(package / "bin" / name)} for name in binaries},
 }
-extra_members = []
-if runtime_image:
-    inspected = json.loads(subprocess.check_output(["docker", "image", "inspect", runtime_image], text=True))[0]
-    if inspected["Id"] != runtime_image or inspected["Os"] != "linux" or inspected["Architecture"] != "amd64":
-        sys.exit("Hosted releases require the selected Linux amd64 Runtime image")
-    (package / "runtime").mkdir()
-    image_path = package / "runtime/image.tar"
-    subprocess.run(["docker", "image", "save", "--output", str(image_path), runtime_image], check=True)
-    (package / "runtime/seccomp.json").write_bytes((source / "services/agents-api/deploy/codex/seccomp.json").read_bytes())
-    guide = (source / "services/agents-api/HOSTED-RELEASE.md").read_text(encoding="utf-8")
-    (package / "HOSTED.md").write_text(guide.replace("@RUNTIME_IMAGE@", runtime_image).replace("@SOURCE_REVISION@", revision), encoding="utf-8")
-    extra_members = ["HOSTED.md", "runtime/image.tar", "runtime/seccomp.json"]
-    manifest["runtime"] = {
-        "image_id": runtime_image,
-        "platform": {"os": inspected["Os"], "architecture": inspected["Architecture"]},
-        "files": {name: {"sha256": sha256(package / name)} for name in extra_members},
-    }
 (package / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
-members = sorted(["bin/" + name for name in binaries] + ["LICENSE", "README.md", "HOSTED-SANDBOX-MANAGER.md", "manifest.json"] + extra_members)
+members = sorted(["bin/" + name for name in binaries] + ["LICENSE", "README.md", "HOSTED-SANDBOX-MANAGER.md", "manifest.json"])
 (package / "SHA256SUMS").write_text("".join(sha256(package / name) + "  " + name + "\n" for name in members), encoding="utf-8")
 members = sorted(members + ["SHA256SUMS"])
 prefix = archive_name.removesuffix(".tar.gz")
diff --git a/scripts/build-core-distribution.sh b/scripts/build-core-distribution.sh
index 4f19d3388..0ca8f8663 100755
--- a/scripts/build-core-distribution.sh
+++ b/scripts/build-core-distribution.sh
@@ -106,14 +106,8 @@ done
 # Web owns the Standard sandbox sizes; the installer's first deployment uses this copy.
 cp apps/web/src/features/sandbox/standard-sizes.json "$bundle/standard-sizes.json"
 python3 scripts/core-distribution-manifest.py bootstraps "$bundle" "$source_epoch"
-mkdir -p "$bundle/docs"
-cp -R docs/getting-started "$bundle/docs/"
-cp docs/configuration.md "$bundle/docs/configuration.md"
-cp README.md "$bundle/"
-mkdir -p "$bundle/services/agents-api"
-cp services/agents-api/HOSTED-SANDBOX-MANAGER.md "$bundle/services/agents-api/"
-mkdir -p "$bundle/contracts/agents-api"
-cp contracts/agents-api/environment-executor-credentials.md "$bundle/contracts/agents-api/"
+# The bundled docs (BUNDLED_DOCS); links that leave them point at this commit on GitHub.
+python3 scripts/core-distribution-manifest.py docs . "$bundle" "$revision"
 mkdir -p "$bundle/runtime"
 cp services/agents-api/deploy/codex/seccomp.json "$bundle/runtime/"
 cp LICENSE "$bundle/"
diff --git a/scripts/core-distribution-manifest.py b/scripts/core-distribution-manifest.py
index 14f147824..e86f4f77d 100644
--- a/scripts/core-distribution-manifest.py
+++ b/scripts/core-distribution-manifest.py
@@ -6,13 +6,14 @@
 import json
 import os
 import pathlib
+import posixpath
 import re
 import shutil
 import subprocess
 import sys
 import tarfile
 import tempfile
-from urllib.parse import urlsplit
+from urllib.parse import unquote, urlsplit
 import zipapp
 
 
@@ -30,6 +31,27 @@
 }
 
 
+# The docs a distribution carries, by repository path. Links between them stay
+# relative; every other relative link points at the same file on GitHub at the
+# bundle's commit, so no bundled link leads outside the bundle.
+BUNDLED_DOCS = (
+    "README.md",
+    "docs/configuration.md",
+    "docs/getting-started/README.md",
+    "docs/getting-started/install.md",
+    "docs/getting-started/nodes.md",
+    "docs/getting-started/operations.md",
+    "docs/getting-started/quickstart.md",
+    "docs/getting-started/self-hosted.md",
+    "services/agents-api/HOSTED-SANDBOX-MANAGER.md",
+    "contracts/agents-api/environment-executor-credentials.md",
+)
+REPOSITORY_URL = "https://github.com/MiniMax-AI/parsar-core"
+MARKDOWN_LINK = re.compile(r"(!?)\[((?:[^\[\]]|\[[^\]]*\])*)\]\(([^)\s]+)((?:\s+\"[^\"]*\")?)\)")
+FENCE = re.compile(r"\s*(```|~~~)")
+HEADING = re.compile(r"(#{1,6})\s+(.*?)\s*#*\s*\Z")
+
+
 def sha256(path):
     digest = hashlib.sha256()
     with pathlib.Path(path).open("rb") as stream:
@@ -308,12 +330,110 @@ def archive(bundle, epoch, variant=""):
     output.with_name(output.name + ".sha256").write_text(sha256(output) + "  " + output.name + "\n")
 
 
+def markdown_lines(text):
+    """(line, inside a code block) for each line of a Markdown document."""
+    fenced = False
+    for line in text.split("\n"):
+        if FENCE.match(line):
+            fenced = not fenced
+            yield line, True
+        else:
+            yield line, fenced
+
+
+def heading_anchors(text):
+    """GitHub's heading anchors: lowercase, punctuation dropped, spaces to hyphens, repeats numbered."""
+    found, counts = set(), {}
+    for line, code in markdown_lines(text):
+        match = None if code else HEADING.match(line)
+        if match:
+            title = re.sub(r"!?\[([^\]]*)\]\([^)]*\)", r"\1", match.group(2)).replace("`", "").replace("*", "")
+            base = re.sub(r"[^\w\- ]", "", re.sub(r"<[^>]+>", "", title).strip().lower()).replace(" ", "-")
+            count = counts.get(base, 0)
+            counts[base] = count + 1
+            found.add(base if count == 0 else f"{base}-{count}")
+    return found
+
+
+def rewrite_links(text, rewrite):
+    """Apply rewrite(image, target) to every Markdown link outside code blocks and code spans."""
+    lines = []
+    for line, code in markdown_lines(text):
+        if not code:
+            parts = re.split(r"(`[^`]*`)", line)
+            line = "".join(part if index % 2 else MARKDOWN_LINK.sub(
+                lambda match: f"{match.group(1)}[{match.group(2)}]({rewrite(bool(match.group(1)), match.group(3))}{match.group(4)})",
+                part) for index, part in enumerate(parts))
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def docs(source, bundle, revision, names=BUNDLED_DOCS):
+    """Copy the bundled docs; a link that leaves them points at this revision on GitHub.
+
+    Every relative link must name an existing file, and an anchor an existing heading,
+    so a broken link fails the build instead of shipping.
+    """
+    source, bundle = pathlib.Path(source), pathlib.Path(bundle)
+    if not re.fullmatch(r"[0-9a-f]{40}", revision):
+        raise ValueError("Bundled docs need the full source commit")
+    bundled = set(names)
+    anchors = {}
+
+    def headings(path):
+        if path not in anchors:
+            anchors[path] = heading_anchors((source / path).read_text(encoding="utf-8"))
+        return anchors[path]
+
+    def versioned(name):
+        def rewrite(image, link):
+            if re.match(r"[A-Za-z][A-Za-z0-9+.-]*:", link):
+                for kind in ("blob", "tree", "raw"):
+                    if link.startswith(f"{REPOSITORY_URL}/{kind}/main/"):
+                        return f"{REPOSITORY_URL}/{kind}/@SOURCE_REVISION@/" + link[len(f"{REPOSITORY_URL}/{kind}/main/"):]
+                return link
+            path, _, anchor = link.partition("#")
+            target = posixpath.normpath(posixpath.join(posixpath.dirname(name), unquote(path))) if path else name
+            if target == ".." or target.startswith("../") or not (source / target).exists():
+                raise ValueError(f"{name}: link to a missing file: {link}")
+            if anchor and target.endswith(".md") and unquote(anchor) not in headings(target):
+                raise ValueError(f"{name}: link to a missing heading: {link}")
+            if target in bundled:
+                return link
+            kind = "raw" if image else "tree" if (source / target).is_dir() else "blob"
+            return f"{REPOSITORY_URL}/{kind}/@SOURCE_REVISION@/{target}" + ("#" + anchor if anchor else "")
+        return rewrite
+
+    for name in names:
+        text = rewrite_links((source / name).read_text(encoding="utf-8"), versioned(name))
+        target = bundle / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text.replace("@SOURCE_REVISION@", revision), encoding="utf-8")
+    check_docs(bundle, names)
+
+
+def check_docs(bundle, names=BUNDLED_DOCS):
+    """Every relative link in the bundled docs resolves inside the bundle."""
+    bundle = pathlib.Path(bundle)
+    for name in names:
+        def check(image, link):
+            if not re.match(r"[A-Za-z][A-Za-z0-9+.-]*:", link):
+                path, _, anchor = link.partition("#")
+                target = posixpath.normpath(posixpath.join(posixpath.dirname(name), unquote(path))) if path else name
+                if target not in names or (anchor and unquote(anchor) not in heading_anchors(
+                        (bundle / target).read_text(encoding="utf-8"))):
+                    raise ValueError(f"Bundled {name} links outside the bundle: {link}")
+            return link
+        rewrite_links((bundle / name).read_text(encoding="utf-8"), check)
+
+
 if __name__ == "__main__":
     commands = {"extract-runtime": extract_runtime, "verify-runtime": verify_runtime, "verify-image": verify_image,
-                "built-image": built_image, "manifest": manifest, "archive": archive, "bootstraps": bootstraps, "release-base": release_base}
+                "built-image": built_image, "manifest": manifest, "archive": archive, "bootstraps": bootstraps,
+                "release-base": release_base, "docs": docs}
     try:
         commands[sys.argv[1]](*sys.argv[2:])
     except (KeyError, TypeError):
-        sys.exit("Usage: core-distribution-manifest.py extract-runtime|verify-runtime|verify-image|built-image|manifest|archive|bootstraps|release-base ARGS...")
+        sys.exit("Usage: core-distribution-manifest.py extract-runtime|verify-runtime|verify-image|built-image|manifest|archive|bootstraps|release-base|docs ARGS...")
     except (OSError, ValueError, subprocess.CalledProcessError) as error:
         sys.exit(str(error))
diff --git a/scripts/core-distribution-manifest.test.py b/scripts/core-distribution-manifest.test.py
index 89fb1fb9c..af41177af 100644
--- a/scripts/core-distribution-manifest.test.py
+++ b/scripts/core-distribution-manifest.test.py
@@ -248,5 +248,51 @@ def test_bootstraps_include_shared_downloader_and_are_reproducible(self):
                 self.assertEqual(contents.read("__main__.py"), (self.bundle / script).read_bytes())
 
 
+class BundledDocsTests(unittest.TestCase):
+    def setUp(self):
+        self.temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temporary.cleanup)
+        self.source = pathlib.Path(self.temporary.name) / "source"
+        self.bundle = pathlib.Path(self.temporary.name) / "bundle"
+        for name, text in {
+            "README.md": "# Title\n\n![Banner](docs/banner.png)\n[Install](docs/install.md#sign-in-to-web), "
+                         "[API](contracts/api.md#routes), [web](docs/web), `[kept](missing.md)`, "
+                         "[main](https://github.com/MiniMax-AI/parsar-core/blob/main/LICENSE)\n"
+                         "```sh\n[not a link](missing.md)\n```\n",
+            "docs/install.md": "# Install\n## Sign in to Web\n[Back](../README.md#title) [Here](#sign-in-to-web)\n",
+            "docs/banner.png": "",
+            "docs/web/README.md": "# Web\n",
+            "contracts/api.md": "# API\n## Routes\n",
+        }.items():
+            (self.source / name).parent.mkdir(parents=True, exist_ok=True)
+            (self.source / name).write_text(text)
+
+    def test_links_leaving_the_bundle_point_at_the_revision(self):
+        distribution.docs(self.source, self.bundle, REVISION, names=("README.md", "docs/install.md"))
+        versioned = "https://github.com/MiniMax-AI/parsar-core/{}/" + REVISION + "/"
+        self.assertEqual((self.bundle / "README.md").read_text(), (
+            "# Title\n\n![Banner](" + versioned.format("raw") + "docs/banner.png)\n"
+            "[Install](docs/install.md#sign-in-to-web), [API](" + versioned.format("blob") + "contracts/api.md#routes), "
+            "[web](" + versioned.format("tree") + "docs/web), `[kept](missing.md)`, "
+            "[main](" + versioned.format("blob") + "LICENSE)\n```sh\n[not a link](missing.md)\n```\n"))
+        self.assertEqual((self.bundle / "docs/install.md").read_text(), (self.source / "docs/install.md").read_text())
+        self.assertFalse((self.bundle / "contracts").exists())
+
+    def test_broken_links_and_anchors_fail_the_build(self):
+        for text in ("[x](missing.md)", "[x](docs/install.md#no-such-heading)", "[x](../outside.md)", "[x](#nowhere)"):
+            (self.source / "README.md").write_text("# Title\n" + text + "\n")
+            with self.assertRaises(ValueError):
+                distribution.docs(self.source, self.bundle, REVISION, names=("README.md", "docs/install.md"))
+
+    def test_repository_docs_are_self_consistent(self):
+        repository = pathlib.Path(__file__).resolve().parent.parent
+        distribution.docs(repository, self.bundle, REVISION)
+        self.assertEqual({str(path.relative_to(self.bundle)) for path in self.bundle.rglob("*.md")},
+                         set(distribution.BUNDLED_DOCS))
+        for name in distribution.BUNDLED_DOCS:
+            self.assertNotIn("@SOURCE_REVISION@", (self.bundle / name).read_text())
+            self.assertNotIn("/blob/main/", (self.bundle / name).read_text())
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/services/agents-api/CONTAINER.md b/services/agents-api/CONTAINER.md
index f57992b3a..cbac5a4a4 100644
--- a/services/agents-api/CONTAINER.md
+++ b/services/agents-api/CONTAINER.md
@@ -1,4 +1,7 @@
-# Standalone container
+# Standalone container (advanced)
+
+This is not the installation path for new users. To install Core with Web, nodes and
+the `parsar` command, use the [installation guide](../../docs/getting-started/install.md).
 
 This image packages the execution API, its embedded migrator and device operator
 command. It needs a dedicated PostgreSQL database/account and an external daemon
diff --git a/services/agents-api/HOSTED-RELEASE.md b/services/agents-api/HOSTED-RELEASE.md
deleted file mode 100644
index 31d0da1c8..000000000
--- a/services/agents-api/HOSTED-RELEASE.md
+++ /dev/null
@@ -1,188 +0,0 @@
-# Docker-hosted Agents API
-
-This package adds a qualified Linux amd64 Runtime image for Core-managed
-Sessions on Docker. A registered Docker sandbox node, not Core, creates one
-colocated Runtime per Session. Each Runtime contains the daemon, stock
-Codex 0.153.4, local tools and workspace. Core, its PostgreSQL database and
-operator secrets stay outside the Runtime. No source checkout, compiler,
-Parsar service, product database, separate executor or manual daemon enrollment
-is needed. Complete the common database, caller identity and private directory
-setup in `README.md` first; do not start Core until the configuration below is ready.
-
-## Load the qualified Runtime
-
-The supported deployment profile was qualified on Docker 29.1.3 with local Linux
-volumes and unprivileged user namespaces. The Docker engine must support volume
-subpath mounts. Other hosts and security policies need their own isolation checks.
-The Provider uses a non-root container, read-only root, dropped capabilities,
-no-new-privileges, private PID namespace and bounded resources. Stock Codex uses
-its inner bubblewrap sandbox with the bundled seccomp policy and container-specific
-`apparmor=unconfined`; host-wide policy must remain unchanged. Docker availability
-alone does not establish that this native sandbox can run safely.
-
-From the extracted package directory, after checking `SHA256SUMS`:
-
-```sh
-export AGENTS_API_PACKAGE="$PWD"
-docker image load --input "$AGENTS_API_PACKAGE/runtime/image.tar"
-docker image inspect @RUNTIME_IMAGE@ --format '{{.Id}} {{.Os}}/{{.Architecture}}'
-```
-
-The result must be `@RUNTIME_IMAGE@ linux/amd64`. The image is selected by this
-immutable ID; no registry pull or mutable tag is required. Package checksums
-establish transferred bytes, not trust in their distributor or safety of another
-image. Keep the package's `runtime/seccomp.json` available to the node service
-(`seccomp_file` in its provider configuration).
-
-## Configure Core
-
-Core no longer uses a Docker socket or a managed Runtime file; it rejects
-`AGENTS_API_MANAGED_RUNTIMES_FILE` at startup. PostgreSQL owns the hosted
-deployment: provider, per-sandbox resources and one immutable Runtime release,
-selected with the Core key through `POST /core/v1/sandbox/deployment` (see the
-[deployment contract](https://github.com/MiniMax-AI/parsar-core/blob/@SOURCE_REVISION@/contracts/agents-api/sandbox-deployment.md)).
-A Docker node registered with `bin/parsar-sandbox-node` owns the host's Docker
-socket and creates the Runtimes; see
-[register a host](HOSTED-SANDBOX-MANAGER.md#register-a-host).
-
-A Docker Runtime release names all six identities of one matched distribution:
-source commit, image ID, OCI manifest digest, microsandbox reference, Runtime and
-firmware hashes. This package records only the image ID, so it cannot supply that
-release by itself. Use the Core distribution and its
-[installer](https://github.com/MiniMax-AI/parsar-core/blob/@SOURCE_REVISION@/docs/getting-started/install.md),
-whose manifest carries the complete release and whose Web console adds Docker
-nodes.
-
-For a manual deployment with a complete release, set these in addition to the
-common configuration, using a stable installation UUID and the HTTPS origin that
-nodes and sandbox guests reach through your TLS proxy:
-
-```sh
-export AGENTS_API_ADDR=0.0.0.0:8091
-export AGENTS_API_SANDBOX_INSTALLATION_ID="<installation UUID>"
-export AGENTS_API_PUBLIC_URL="https://core.example"
-chmod 0600 "$AGENTS_API_CORE_KEY_DIGESTS_FILE"
-"$AGENTS_API_BIN_DIR/agents-api-migrate"
-"$AGENTS_API_BIN_DIR/agents-api"
-```
-
-Set the deployment default model provider with the Core key, for a
-Responses-compatible endpoint reachable from the Runtime (a host loopback address
-is not the container's host):
-
-```sh
-curl -fsS -X PUT http://127.0.0.1:8091/core/v1/harnesses/codex/model-provider \
-  -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
-  -d '{"protocol":"responses","base_url":"https://<model endpoint>/v1","api_key":"<private model credential>"}'
-```
-
-Core encrypts it, never returns the key and freezes it into each new hosted
-Session. Never put model credentials in Agent instructions, image layers or a
-workspace.
-
-Then select `docker`, the per-sandbox resources and the complete Runtime release
-(the deployment's `core_url` comes from `AGENTS_API_PUBLIC_URL`), and register a node on a host where
-this image is loaded. Hosted admission starts when a ready node has capacity.
-
-Use your existing service supervisor for long-running operation. Migrations are
-explicit. One Core execution worker owns each database; replicas do not provide
-execution HA. `GET /healthz` checks liveness, not successful sandbox preparation.
-
-## Execute through the public client
-
-Use the pinned client described in `README.md`, with `OPENAI_BASE_URL` set to
-`http://127.0.0.1:8091/v1` and `OPENAI_API_KEY` read from the private caller key.
-The public model name must match the trusted endpoint's supported model:
-
-```python
-import base64
-from openai import OpenAI
-
-client = OpenAI()
-session = client.beta.agents.sessions.create(
-    agent={"model": "<configured model>"},
-    environment={"type": "openai_hosted"},
-    input="Create /workspace/result.txt containing a short greeting.",
-)
-print(session.id, session.environment.id)
-```
-
-Core provisions the Runtime automatically. Retrieve the Session and list its Turns
-and Items to observe execution; wait for the Turn to complete before a file upload.
-A connected Environment confirms the daemon transport, not native readiness.
-Keep the Session ID for all subsequent operations:
-
-```python
-print(client.beta.agents.sessions.retrieve(session.id))
-print(client.beta.agents.sessions.turns.list(session.id))
-print(client.beta.agents.sessions.items.list(session.id))
-print(client.beta.agents.environments.files.list(session.environment.id, path="/workspace"))
-client.beta.agents.environments.files.create(
-    session.environment.id,
-    type="inline",
-    path="/workspace/input.txt",
-    data=base64.b64encode(b"Read these exact bytes.").decode(),
-)
-with client.beta.agents.sessions.stream(
-    session.id, input="Read /workspace/input.txt with the native shell and quote it."
-) as stream:
-    for event in stream:
-        print(event.type)
-```
-
-Cancellation of an accepted/running Turn uses the same public Session:
-
-```python
-client.beta.agents.sessions.events.create(
-    session.id, events=[{"type": "agent.session.input.cancel"}]
-)
-```
-
-Query until the Turn is terminal; a cancellation request alone is not completion.
-Pre-Turn reservation cancellation remains a recorded gap. Reconnect clients after
-Core restart and recover through Session/Turn/Items; SSE is live and does not replay
-history. Preserve Runtime containers and both owned volumes for native history and
-workspace continuation. Do not turn an uncertain interrupted execution into a new
-request or delete native history to make a retry succeed.
-
-When finished, `client.beta.agents.sessions.delete(session.id)` requests owned
-Runtime cleanup. Core and the original node must remain running until its
-labelled container and volumes are gone. Public deletion acknowledgment
-is not physical cleanup confirmation. Do not use broad Docker pruning.
-
-To change providers, resources or Runtime, follow the
-[maintenance procedure](HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance): enter
-maintenance at the current generation, archive retained hosted Sessions and verify
-cleanup, submit the replacement, then resume. Maintenance blocks new compute
-without deleting retained resources. One deployment runs exactly one provider,
-E2B, Docker or [microsandbox](deploy/microsandbox/README.md), with no mixed configuration,
-engine-to-provider routing or automatic Session migration.
-
-Back up the independent PostgreSQL database
-(including large objects) and retained Runtime state together under an operator
-recovery plan; the archive itself contains no deployment data.
-
-## Acceptance limits
-
-The qualified basic profile covers public creation, native execution, inline and
-source-file copies/listing, cancellation, retained-history restart and owned
-cleanup. Network access defaults to enabled; explicit disabled confines native
-tools while the trusted harness retains model/Core connectivity, and exact-host
-restricted policies are supported. Environment Templates and inline
-initialization are covered within their
-[recorded limits](https://github.com/MiniMax-AI/parsar-core/blob/@SOURCE_REVISION@/contracts/agents-api/environment-templates.md), and Artifacts are captured on
-accepted Docker profiles. Other hostname forms, service-origin hosted MCP and
-complete protocol parity remain open. Files size and
-directory bounds are local implementation limits, not verified upstream limits.
-
-The same Runtime also serves caller-managed `self_hosted` Sessions. The application
-creates the Session with its Project API key, the deployment operator issues the
-Environment's [executor credential](https://github.com/MiniMax-AI/parsar-core/blob/@SOURCE_REVISION@/contracts/agents-api/environment-executor-credentials.md) with
-the Core key, and the executor host runs the daemon with it. That path is
-[qualified](https://github.com/MiniMax-AI/parsar-core/blob/@SOURCE_REVISION@/contracts/agents-api/user-managed-runtime-v1.md) on user-managed Docker and E2B for all
-three harnesses. It accepts only `/workspace` with empty capability directories,
-rejects service-origin HTTP MCP and has no Environment Templates; the application
-owns and cleans up its compute. This package does not install
-Docker/PostgreSQL/TLS/a supervisor, publish an image, migrate product execution or
-add engines. See the
-[versioned coverage ledger](https://github.com/MiniMax-AI/parsar-core/blob/@SOURCE_REVISION@/contracts/agents-api/README.md).
diff --git a/services/agents-api/HOSTED-SANDBOX-MANAGER.md b/services/agents-api/HOSTED-SANDBOX-MANAGER.md
index 1c3901876..ac0781e5a 100644
--- a/services/agents-api/HOSTED-SANDBOX-MANAGER.md
+++ b/services/agents-api/HOSTED-SANDBOX-MANAGER.md
@@ -1,62 +1,51 @@
-# Hosted Sandbox Manager
+# Nodes and sandbox backends: operator reference
 
-One Core execution owner can manage sandbox nodes on its own host and on other
-Linux hosts, or provision cloud sandboxes directly through E2B. A deployment selects
+This reference is for operators who need the details behind Web's **Nodes** page
+(shown as **Sandbox backend** when the deployment uses E2B): the node protocol,
+manual registration, placement, maintenance and failure handling. To add, remove or
+troubleshoot a node, start with the [nodes guide](../../docs/getting-started/nodes.md).
+
+One Core execution owner manages sandbox nodes on its own host and on other Linux
+hosts, or provisions cloud sandboxes directly through E2B. A deployment selects
 exactly one provider: `e2b`, `docker` or `microsandbox`. PostgreSQL owns that
 selection, the per-sandbox resource limits and the immutable Runtime release.
-Docker/microsandbox nodes must match its installation, generation and specification. These nodes
-are distinct from user-managed `self_hosted` Environments, whose provisioning
-remains the user's responsibility.
-
-The Web console's **Nodes** page (shown as **Sandbox backend** when the deployment
-uses E2B) uses the Core key, separate from
-Project API keys. After console sign-in, the console server forwards the page's
-`/core/v1/sandbox` requests, like every other `/core/v1` request, with the Core
-key it reads from its private file. The Core key never reaches the browser. There
-is no second login or manual key form. For manual or Web-only deployments, an
-operator configures the matching private `0600` Core key file server-side through
-`CORE_CONSOLE_CORE_KEY_FILE`; Web refuses to start without it. Core serves the
-deployment and node routes only when `AGENTS_API_SANDBOX_INSTALLATION_ID` is set.
-
-The sandbox page and its setup, enrollment, status and diagnostic controls support
-Chinese and English. Choose a language in System navigation; the preference is
-saved, and otherwise the page follows the browser's first language. Nodes are the
-main view, arranged around Core in a desktop topology with readiness and capacity
-visible immediately. Select a node for allocation records, diagnostics and guarded
-removal; deployment identifiers are available in secondary details. Animated links
-indicate live connections, not measured traffic. Offline links are static, and
-reduced-motion preferences disable decorative animation.
-
-The installer creates the separate key under the private `secrets/` directory,
-including zero-node installs. Core receives its digest; the bundled Web server
-receives the original private key. Neither is included in static assets or the
-node installation payload. Project keys cannot register, edit or remove nodes.
-
-## Start with zero nodes
-
-Default installation starts Core, Web and PostgreSQL without local compute, and
-selects Docker sandboxes at Web's Standard size through the route below;
-`install.sh --sandbox` chooses microsandbox, E2B or none instead. Without a
-selection, setup on the **Nodes** page first asks for **E2B cloud** or **Own machines**. Own
-machines then choose Docker or microsandbox. Supply the per-sandbox resources and
-matched Runtime release as part of initial setup. E2B takes an account API key and
-a qualified immutable Runtime template build (`template-id:build-uuid`) that must be
-ready before the selection can be saved. E2B CPU/memory limits are optional: Web
-sends none, and Core adopts the build's size; supplied limits must match the build.
-The key is write-only, encrypted by Core and never returned to the browser. E2B
-needs no node installation.
-Setup takes no Core address. Nodes and guests use the installation public URL,
-where the reverse proxy sends `/api/v1`, including WebSocket upgrades, directly to
-Core; Web does not forward it. The deployment reports it as read-only `core_url`.
-E2B requires a public URL that is not loopback; a loopback public URL serves only
-local development, because a guest's loopback address cannot reach its Core host.
+Docker and microsandbox nodes must match its installation, generation and
+specification. These nodes are distinct from user-managed `self_hosted` Environments,
+whose provisioning remains the application's responsibility.
+
+The Nodes page uses the Core key, separate from Project API keys. After console
+sign-in, the console server forwards the page's `/core/v1/sandbox` requests, like
+every other `/core/v1` request, with the Core key it reads from its private file; the
+key never reaches the browser. For a Web you run without the installer, configure the
+private `0600` key file through `CORE_CONSOLE_CORE_KEY_FILE`; Web refuses to start
+without it. Core serves the deployment and node routes only when
+`AGENTS_API_SANDBOX_INSTALLATION_ID` is set. Project keys cannot register, edit or
+remove nodes. The node installation payload that Web serves contains no secret.
+
+## Sandbox backend selection
+
+A new installation selects Docker sandboxes at Web's Standard size unless
+`install.sh --sandbox` chose microsandbox, E2B or none. Without a selection, the
+**Nodes** page first asks for **E2B cloud** or **Own machines**; own machines then
+choose Docker or microsandbox, the per-sandbox resources and the matched Runtime
+release. E2B takes an account API key and a qualified immutable Runtime template build
+(`template-id:build-uuid`) that must be ready before the selection can be saved. E2B
+CPU and memory limits are optional: Web sends none, and Core adopts the build's size;
+supplied limits must match the build. The key is write-only, encrypted by Core and
+never returned to the browser. E2B needs no node installation.
+
+Setup takes no Core address. Nodes and guests use the installation public URL, where
+the reverse proxy sends `/api/v1`, including WebSocket upgrades, directly to Core; Web
+does not forward it. The deployment reports it as the read-only `core_url`. E2B
+requires a public URL that is not loopback; a loopback public URL serves only local
+development, because a guest's loopback address cannot reach its Core host.
 
 **Save configuration** validates and initializes the deployment without creating
-compute. A failed candidate leaves the previous selection intact. Refresh after an uncertain response before
-trying again. Selection persists in PostgreSQL and activates without a restart.
-Removing all nodes does not reset it. E2B uses the same daemon, harness and workspace
-Runtime as node-backed hosting. Configuration alone does not prove provider or model
-readiness. To prepare the qualified E2B Runtime build, use
+compute. A failed candidate leaves the previous selection intact. Refresh after an
+uncertain response before trying again. The selection persists in PostgreSQL and
+activates without a restart; removing all nodes does not reset it. E2B uses the same
+daemon, harness and workspace Runtime as node-backed hosting. Configuration alone does
+not prove provider or model readiness. To prepare the qualified E2B Runtime build, use
 [the E2B build guide](deploy/e2b/README.md); it is not a public Environment Template.
 Microsandbox suspends eligible idle Sessions after 300 seconds and retains their
 snapshots for 86400 seconds. Docker and E2B have no memory snapshot policy.
@@ -68,7 +57,7 @@ reclaims it.
 See [what each field means per sandbox provider](../../contracts/agents-api/sandbox-deployment.md#what-each-field-means-per-sandbox-provider)
 for fields that differ between E2B, Docker and microsandbox.
 
-For source/manual deployments using E2B, install the packaged helper and set
+For deployments without the installer that use E2B, install the packaged helper and set
 `AGENTS_API_E2B_PROVIDER_BIN` to its absolute executable path. Set
 `AGENTS_API_E2B_STATE_DIR` to a persistent directory owned by the Core service user,
 mode `0700`. The standard distribution prepares both. Back up this private state
@@ -84,26 +73,22 @@ receipts to bypass this check. A future credential-repair operation must verify
 account/resource ownership before accepting a replacement key; an inaccessible
 sandbox or empty listing from another account is not proof of cleanup.
 
-For own machines, click **Add node**, copy the installation command from the dialog, and run it on
-the target Linux amd64 host. The command uses the installation public URL. Before
-installing, it reads the active specification with its enrollment token; this read
-does not consume the token. The local provider file is an installed copy of the
-server configuration and cannot select a different Runtime or resource profile.
-Closing the dialog discards its one-time command. An expired command requires
-explicit regeneration; failed or uncertain writes are never retried automatically. The installer checks prerequisites, downloads the matched payload,
-checks its hashes, prepares provider configuration and starts the existing node
-program as a service (see [Register a host](#register-a-host)). Web polls readiness
-and capacity while waiting.
-It does not install software through SSH. Registration itself
-does not create a Session, sandbox or model request. Hosted Session admission
-fails until setup is complete and a ready node has capacity. E2B allocates directly without this node requirement.
-
-For manual zero-node deployments, set `AGENTS_API_SANDBOX_INSTALLATION_ID` to a
-stable UUID, configure `AGENTS_API_CORE_KEY_DIGESTS_FILE`, and enable the daemon
-gateway with `AGENTS_API_PUBLIC_URL`. Do not also set
-`AGENTS_API_MANAGED_RUNTIMES_FILE`. Core derives hosted Runtime bootstrap and the
-public daemon WebSocket address from that URL; it never uses request Host or
-forwarded headers. Preserve the installation UUID and database together.
+For own machines, **Add node** generates a one-time command that uses the
+installation public URL. Before installing, the node installer reads the active
+specification with its enrollment token; this read does not consume the token. The
+local provider file is an installed copy of the server configuration and cannot select
+a different Runtime or resource profile. Closing the dialog discards its one-time
+command. An expired command requires explicit regeneration; failed or uncertain writes
+are never retried automatically. Registration itself creates no Session, sandbox or
+model request. Hosted Session admission fails until setup is complete and a ready node
+has capacity. E2B allocates directly without this node requirement.
+
+For deployments without the installer and with zero nodes, set
+`AGENTS_API_SANDBOX_INSTALLATION_ID` to a stable UUID, configure
+`AGENTS_API_CORE_KEY_DIGESTS_FILE`, and enable the daemon gateway with
+`AGENTS_API_PUBLIC_URL`. Core derives the hosted Runtime bootstrap and the public
+daemon WebSocket address from that URL; it never uses the request Host or forwarded
+headers. Preserve the installation UUID and database together.
 
 Use the live sandbox deployment response (`GET /core/v1/sandbox/deployment`) for
 the current selection, including one made after startup.
@@ -151,74 +136,21 @@ The current installation path uses a database-managed deployment.
 
 ## Register a host
 
-The paired console provides a complete installation command. It downloads only
-a matched bootstrap from `/node-install/`, then checksum-verified prebuilt assets
-from the same console's payload, never from a release URL the build recorded. The
-console must hold them: install from the offline bundle, or place the release assets
-in the bundle's `artifacts/` directory first; `/console/config` lists the providers
-whose assets it holds (`node_artifacts`). It reuses verified cache
-entries and exact imported images, then waits for Core to confirm connection and
-provider readiness. The enrollment token
-is transient and never a console/project credential; the command passes it to the
-installer on standard input (`--enrollment-token-stdin`), never in a process argument,
-an environment variable or sudo's log. A download that brings less than 64 KiB in a
-minute stops; the downloaded part is kept, and running a new command resumes it.
-
-The installer chooses how the node runs from the user that runs it:
-
-- **With sudo or as root (the default command).** It prepares the host itself. It
-  creates the system user `parsar-node` (home `/var/lib/parsar-node`) if missing,
-  or adopts an existing one with that home and a nologin shell. It adds the user to
-  the `docker` group (Docker) or the `kvm` group (microsandbox), whichever owns the
-  device; any other device group is refused. The node runs as the root-owned system
-  service `/etc/systemd/system/parsar-node-<installation-id>.service` with
-  `User=parsar-node`, enabled for boot. No lingering or login session is needed;
-  logs are in `sudo journalctl -u parsar-node-<installation-id>.service`. Node state
-  lives in `/var/lib/parsar-node/.parsar/nodes/<installation-id>/`, and what the
-  installer created or changed is recorded in `/etc/parsar-node/`. Files the service
-  user owns are written and deleted only with that user's credentials; root handles
-  the account, the group, the unit and the Docker network. It never installs
-  Docker, KVM or packages, never changes device permissions and refuses
-  SELinux-enforcing hosts; a missing prerequisite stops it with a one-line hint
-  before anything changes. A foreign account named `parsar-node` is refused. Sudo
-  mode serves **one Core per host**: every sudo-mode node shares `parsar-node`, so a
-  node for a second Core is refused. A node for the same installation installed
-  without sudo is found in the invoking user's home or, for Docker, by its network
-  on the same engine; other users' homes are not searched. The steps that run as
-  `parsar-node` start in their own session with no terminal, so nothing they run
-  can reach the administrator's terminal, and their output appears only as plain
-  text. Interrupting the installer or closing its terminal stops those steps as
-  well.
-
-  **Docker mode is root-equivalent.** Membership in the `docker` group lets
-  `parsar-node`, and so anything that controls the node, act as root on that host.
-  This is inherent to running sandboxes on Docker and equally true in the no-sudo
-  mode. Add Docker nodes only on hosts dedicated to running sandboxes. Microsandbox
-  nodes need only the `kvm` group.
-
-  Pass the token on standard input, as the command does. In sudo mode the installer
-  refuses `PARSAR_NODE_ENROLLMENT_TOKEN`, because `sudo VAR=… python3` records the
-  variable in sudo's log. A sudoers policy with `log_input` records standard input
-  as well; the token is single-use and expires after ten minutes.
-- **As a normal user (for hosts without sudo).** The node runs as that user's
-  systemd user service with state under `~/.parsar/nodes/<installation-id>/`. The
-  user needs lingering and Docker or KVM access, which an administrator grants
-  beforehand. The installer finds the user's systemd manager even from `su` or
-  `sudo -iu`, where no login session sets `XDG_RUNTIME_DIR`.
-
-Python 3.9+, curl and sha256sum, and Docker Engine or KVM with microsandbox's
-native libraries must already exist on the target host. Rerunning the same command preserves the
-node's private identity. A registered retry reads configuration with its retained
-node credential and `X-Parsar-Node-ID`; it does not enroll again. Changes to the
-Core origin, installation, generation, specification or release are refused
-without rewriting state. Use a newly generated token if an unconsumed one expires.
-
-For a public paired endpoint, use `install.sh --public-url https://core.example`
-and an operator-managed TLS reverse proxy preserving Host and WebSocket Upgrade.
-The proxy routes `/api/v1` directly to Core; see
-[Expose Core and Web](../../docs/getting-started/install.md#expose-core-and-web).
+Web's **Add node** command is the supported way to register a host; the
+[nodes guide](../../docs/getting-started/nodes.md) describes its sudo and no-sudo
+modes, what they create, uninstalling and troubleshooting. The command downloads only a
+matched bootstrap from `/node-install/`, then checksum-verified prebuilt assets from
+the same console's payload, never from a release URL the build recorded. The console
+must hold them: install from the offline bundle, or place the release assets in the
+bundle's `artifacts/` directory first; `/console/config` lists the providers whose
+assets it holds (`node_artifacts`). The enrollment token is transient and never a
+console or Project credential; the command passes it to the installer on standard
+input (`--enrollment-token-stdin`).
+
 Nodes use only these machine connection routes, authenticated by their own
-credentials; Web does not forward them and no administrator credential applies:
+credentials. Web does not forward them, and no administrator credential applies. The
+reverse proxy routes `/api/v1`, with WebSocket upgrades, directly to Core; see
+[HTTPS and the reverse proxy](../../docs/getting-started/install.md#https-and-the-reverse-proxy).
 
 | Route | Credential |
 | --- | --- |
@@ -237,30 +169,42 @@ a non-secret `enrollment_id`; the node it registers reports the same value in
 A node and its Core must come from the same distribution. Nodes from releases
 that used the removed `/core/v1/sandbox` node paths cannot connect to this Core:
 drain with the previous release, then upgrade and enroll new nodes, as described
-in [Data and upgrades](../../docs/getting-started/operations.md#data-and-upgrades).
-Manual registration remains available for operator-managed payloads:
-
-Build/install `parsar-sandbox-node` from the same Core release. On the host,
-first read `GET /api/v1/sandbox-node/configuration` with the enrollment Bearer
-token. Build the private provider JSON from its `provider`, `installation_id`,
-`core_url` (the installation public URL), `generation` and `specification`, using the existing local backend
-schema for the host's socket, runtime paths and network policy. The Runtime image
-and resource limits must match the server specification. Docker needs access to its local
-Unix socket and pinned image. Microsandbox needs its qualified runtime, helper,
-firmware and KVM. The native Unix socket limit also requires
-`$HOME/.parsar/m/<12-character installation hash>` to fit within 48 encoded bytes.
-The installer rejects a longer path before creating node state; use a service
-account with a shorter persistent home. A node never receives arbitrary host
-paths from the browser.
-
-Node capacity is approved by Core when the administrator creates an enrollment
-token, then retained in PostgreSQL. Registration and node files cannot overwrite
-it. See [Configuration](../../docs/configuration.md#node-configuration-and-capacity)
-for limits, defaults and changes.
-
-On the **Nodes** page, generate a single-use registration token. Save it in
-a `0600` file on the host. The token expires after the duration shown by Core.
-Run the displayed command with real absolute paths, for example:
+in [Upgrade notes](../../docs/getting-started/operations.md#node-connections-at-apiv1).
+Rerunning the same command preserves the node's private identity. A registered retry
+reads configuration with its retained node credential and `X-Parsar-Node-ID`; it does
+not enroll again. Changes to the Core origin, installation, generation, specification
+or release are refused without rewriting state.
+
+### Manual registration
+
+Manual registration remains available for operator-managed payloads. Build or install
+`parsar-sandbox-node` from the same Core release. On the host, first read
+`GET /api/v1/sandbox-node/configuration` with the enrollment Bearer token. Build the
+private provider JSON from its `provider`, `installation_id`, `core_url` (the
+installation public URL), `generation` and `specification`, plus one adapter object
+for the host:
+
+- Docker: an explicit Unix socket `host`, the locally imported `image`, `network`,
+  `extra_hosts` and an absolute `seccomp_file`, with the existing nested-sandbox
+  security settings. The imported image must match the approved Runtime release.
+- Microsandbox: absolute `helper_path`, `runtime_home`, `runtime_path` and
+  `firmware_path`, the host network policy and validated resource and Runtime copies.
+  The runtime home is an existing private backend namespace. The native Unix socket
+  limit requires `$HOME/.parsar/m/<12-character installation hash>` to fit within 48
+  encoded bytes; the installer rejects a longer path before creating node state, so
+  use a service account with a shorter persistent home.
+
+The node file has no `max_active`, `max_retained`, idle-policy or maintenance
+override, and a node never receives arbitrary host paths from the browser. Editing the
+downloaded specification does not change Core: the node validates its content and file
+hashes, and Core compares its digest at enrollment and on every connection. A mismatch
+rejects work until the approved configuration is restored. Node capacity is approved by
+Core when the administrator creates an enrollment token and retained in PostgreSQL;
+registration and node files can't overwrite it. See
+[Node capacity](../../docs/configuration.md#node-capacity).
+
+Save the single-use registration token in a `0600` file on the host; it expires after
+the duration shown by Core. Run, with real absolute paths:
 
 ```sh
 parsar-sandbox-node register \
@@ -284,7 +228,8 @@ directory or onto another host. Core rejects duplicate connections while the
 original connection is opening, live or finishing disconnect cleanup. A half-open
 connection must reach its heartbeat timeout before a reconnect can be admitted;
 the node retries with bounded backoff. These checks do not attest physical host
-identity. The enrollment token is not the node credential.
+identity. The enrollment token is not the node credential. Reconnection reads the
+current capacity from the database; it never writes local limits back to Core.
 
 ## Placement and recovery
 
@@ -321,35 +266,15 @@ unknown operations or cleanup records cannot be removed. Resolve those resources
 through their normal lifecycle and then retry; the API reports the conflict.
 Offline resources remain owned and visible. Explicit removal permanently retires
 the node identity; adding that host again requires a fresh private state directory.
-After removal, clean up the host with the installer's `--uninstall`, using the same
-checked download as the add command:
-
-```sh
- (umask 077; d=$(mktemp -d) || exit; trap 'rm -rf "$d"' EXIT; s=; [ "$(id -u)" -eq 0 ] || s=sudo
-curl -fsS --max-time 30 --max-filesize 1048576 'https://core.example/node-install/node-install.pyz' -o "$d/node-install.pyz" &&
-printf '%s  %s\n' '<node_installer_sha256>' "$d/node-install.pyz" | sha256sum -c --status &&
-$s python3 "$d/node-install.pyz" --uninstall --installation-id '<installation-id>')
-```
-
-For a node installed as a normal user, run it as that user; it does not use sudo
-then. The installer's checksum is `node_installer_sha256` in the console's
-`/console/config`. Uninstall proceeds only when Core answers 401 to the node's
-credential, or with `--force` for a Core that no longer exists. It stops and removes
-the service, the node state and the Docker network. The `parsar-node` account is
-deleted only when the installer created it and no node remains. An adopted account
-and its home directory stay; uninstall removes only the groups the installer added. Uninstall never removes
-sandboxes, volumes or images: it keeps the Runtime image and a microsandbox node's
-store (`/var/lib/parsar-node/.parsar/m/<hash>`, its images and any sandbox state),
-prints how to remove them (`sudo -u parsar-node rm -rf <store>`), and keeps a
-created account until that store is gone.
-With `--force`, microVMs that `KillMode=process` left running may still use the
-store, so check `pgrep -u parsar-node` first. The host can then be added again with
-a new command.
-The node program then exits with status 78 when Core answers 401 to its credential,
-and the installed service does not restart it. Other failures, including an
-unreachable Core or a 403 from a proxy in front of it, restart the service every
-5 seconds without a start limit.
-Ordinary disconnects and host restarts reuse the original identity.
+After removal, clean up the host with the installer's `--uninstall`, which Web shows
+as **Clean up the host**; see [Remove a node](../../docs/getting-started/nodes.md#remove-a-node).
+Uninstall proceeds only when Core answers 401 to the node's credential, or with
+`--force` for a Core address that no longer answers. It never removes sandboxes,
+volumes or images. The node program exits with status 78 when Core answers 401 to its
+credential, and the installed service does not restart it. Other failures, including
+an unreachable Core or a 403 from a proxy in front of it, restart the service every
+5 seconds without a start limit. Ordinary disconnects and host restarts reuse the
+original identity.
 
 Provider, resource-limit and Runtime changes share one deployment-wide procedure:
 
@@ -437,15 +362,8 @@ not, the node list and node detail (`GET /core/v1/sandbox/nodes` and
 field is absent while the provider is ready. An offline node keeps its last
 reported value, so check `online` first.
 
-| Code | Cause detected by the node | Action |
-| --- | --- | --- |
-| `docker_unavailable` | The configured Docker socket is unreachable or not accessible, or the daemon fails its info or image request | Start Docker and give the node service account access to the configured socket |
-| `docker_limits_unsupported` | Docker reports no CPU quota or memory limit support | Use a Docker host whose cgroups enforce CPU quotas and memory limits |
-| `runtime_image_unavailable` | Docker does not have the pinned Runtime image | Rerun the node installer, or import the image from the matched release |
-| `kvm_unavailable` | The node cannot open `/dev/kvm` for reading and writing, or the host is not Linux | Enable hardware virtualization and give the service account KVM access, for example through the `kvm` group |
-| `microsandbox_artifacts_unavailable` | The pinned Runtime or firmware is missing or fails its SHA-256 check, or the helper is missing or not executable | Rerun the node installer from the matched release |
-| `capacity_insufficient` | The host has fewer CPUs or less memory than one sandbox of the deployment specification | Use a larger host, or change the per-sandbox resources through the maintenance procedure |
-| `provider_unavailable` | Any other failure, such as a missing private microsandbox state directory, and every failure reported by an older node | Read the local error in the node's service journal warning and fix that cause |
+The codes, their causes and fixes are listed in the
+[nodes guide](../../docs/getting-started/nodes.md#readiness-codes).
 
 A node reports only its first failed check. Checks run from the provider platform
 (Docker daemon or KVM), through Docker limit support and host capacity, to the
@@ -454,9 +372,10 @@ image, and missing KVM hides missing artifacts or insufficient capacity. After a
 fix, the next heartbeat (about ten seconds) checks again and clears or replaces
 the code. Repaired Runtime artifacts, a pulled image or a started Docker daemon
 recover this way. A new Docker or KVM group membership applies only to a new
-process: restart the node with `systemctl --user restart
-parsar-node-<installation_id>.service`. The service journal's warning includes
-the local error behind the code; that text never leaves the host.
+process: restart the node service (`sudo systemctl restart
+parsar-node-<installation_id>.service` in sudo mode, `systemctl --user restart …`
+without sudo). The service journal's warning includes the local error behind the code;
+that text never leaves the host.
 
 Only the code crosses the node connection. Probe errors can name host paths or
 contain daemon messages; they are not sent to Core, stored or returned. Core stores
diff --git a/services/agents-api/README.md b/services/agents-api/README.md
index b5673669a..64d77602b 100644
--- a/services/agents-api/README.md
+++ b/services/agents-api/README.md
@@ -85,22 +85,13 @@ Linux amd64 archive, with source/protocol identity, checksums, a license and
 [operator instructions](RELEASE.md). Build from a clean Git worktree with Go and
 Python 3.9+; output defaults to `~/.parsar/build/agents-api-release` (or
 `AGENTS_API_RELEASE_DIR`). The extracted API needs no source checkout or compiler.
-For a Docker-hosted package, first qualify an immutable Linux amd64 Runtime built
-with [the existing Runtime builder](deploy/codex/README.md), then run:
-
-```sh
-AGENTS_API_RELEASE_RUNTIME_IMAGE=sha256:<qualified-image-ID> make build-agents-api-release
-```
-
-The resulting `agents-api-docker-<revision>-linux-amd64.tar.gz` also contains the
-Runtime image export, committed seccomp policy and [hosted guide](HOSTED-RELEASE.md).
-The builder records only the selected image ID and file hashes, not the complete
-Runtime release (six distribution identities) that a Docker deployment requires,
-so this package cannot configure hosted execution by itself. For Docker-hosted
-deployments, the Core distribution and its
-[installer](../../docs/getting-started/install.md) replace it: their manifest
-carries the complete release, and Docker nodes are added from Web. The ordinary
-archive remains Docker-free. Database/Docker setup and publication remain separate.
+The archive and the container are advanced paths for running Core alone; see
+[Maintainers and advanced deployments](../../docs/maintainers.md). The Docker-hosted
+archive variant (`AGENTS_API_RELEASE_RUNTIME_IMAGE`) is retired: it recorded only an
+image ID, not the complete Runtime release a Docker deployment requires. Docker-hosted
+deployments use the Core distribution and its
+[installer](../../docs/getting-started/install.md), whose manifest carries the complete
+release; Docker nodes are added from Web.
 
 ## Database ownership
 
@@ -275,7 +266,7 @@ explicit operator configuration. Select the qualified native image using the
 [engine profile guides](../../contracts/agents-api/README.md#public-engine-profiles),
 then follow the [Docker setup](deploy/codex/README.md#standalone-operator-configuration).
 Core-managed hosting supports deployment-selected E2B, Docker or microsandbox;
-see [Hosted Sandbox Manager](HOSTED-SANDBOX-MANAGER.md). For the separate
+see the [nodes and sandbox backends reference](HOSTED-SANDBOX-MANAGER.md). For the separate
 user-managed E2B path, see
 [E2B Runtime packaging](deploy/e2b/README.md).
 Core remains independently deployed with its own database. Public idle and initial
@@ -480,7 +471,7 @@ V1 uses our daemon as the user-side executor. Deploy daemon, selected harness,
 local tools and protected `/workspace` together using the shared Runtime. For this caller-managed path, the user owns local or E2B allocation, renewal
 and destruction; use the official E2B SDK through the
 [E2B guide](deploy/e2b/README.md). Deployment-managed E2B, Docker and microsandbox
-are separate hosted choices in [Hosted Sandbox Manager](HOSTED-SANDBOX-MANAGER.md).
+are separate hosted choices in the [nodes and sandbox backends reference](HOSTED-SANDBOX-MANAGER.md).
 
 Create a Session with `environment={"type":"self_hosted",
 "workspace_directory":"/workspace"}` and empty/default capability directories.
@@ -646,6 +637,7 @@ not changes to the pinned official protocol.
 
 ## Hosted sandbox nodes
 
-The release includes `parsar-sandbox-node` for local and remote hosts. See the
-[Hosted Sandbox Manager guide](HOSTED-SANDBOX-MANAGER.md) for provider selection,
+The release includes `parsar-sandbox-node` for local and remote hosts. Add nodes with
+Web's one-command flow in the [nodes guide](../../docs/getting-started/nodes.md); the
+[operator reference](HOSTED-SANDBOX-MANAGER.md) covers provider selection, manual
 registration, administrator credentials, fixed Session placement and maintenance.
diff --git a/services/agents-api/RELEASE.md b/services/agents-api/RELEASE.md
index 33a55b7df..2ead8dea8 100644
--- a/services/agents-api/RELEASE.md
+++ b/services/agents-api/RELEASE.md
@@ -1,10 +1,12 @@
-# Agents API distribution
+# Standalone Core archive (advanced)
 
-This Linux amd64 package contains the independent API, embedded migrator and two
-operator commands. It needs PostgreSQL. The Docker variant also includes the
-qualified colocated Runtime image, its seccomp policy and `HOSTED.md`; use that
-guide after the common API setup below. The basic archive needs separately
-installed execution software.
+This is not the installation path for new users. To install Core with Web, nodes and
+the `parsar` command, use the
+[Core distribution and its installer](https://github.com/MiniMax-AI/parsar-core/blob/@SOURCE_REVISION@/docs/getting-started/install.md).
+
+This Linux amd64 package contains the independent API, embedded migrator, operator
+commands and `parsar-sandbox-node`. It needs your own PostgreSQL and separately
+installed execution software, and it has no Web console.
 It does not need a source checkout, Go, Node, the Parsar product or its database.
 The [coverage ledger](https://github.com/MiniMax-AI/parsar-core/blob/@SOURCE_REVISION@/contracts/agents-api/README.md)
 describes supported workflows and remaining protocol gaps. Packaging does not
@@ -52,9 +54,7 @@ application key through the [administrator API](../../contracts/agents-api/admin
 Projects and application keys live only in PostgreSQL. Keys in one Project share
 its scope and principal; rotation uses issuance and revocation without a restart.
 
-For the Docker variant, continue in `HOSTED.md` now to configure the Runtime's
-outward connection and provider before starting Core. For the basic archive,
-set the reachable public origin; Core derives the daemon endpoint from it:
+Set the reachable public origin; Core derives the daemon endpoint from it:
 
 ```sh
 export AGENTS_API_PUBLIC_URL=http://127.0.0.1:8091
@@ -164,8 +164,9 @@ profiles, use the [versioned service guide](https://github.com/MiniMax-AI/parsar
 This package does not install PostgreSQL, daemons, harnesses, TLS or a supervisor,
 and it does not switch Parsar's product execution path.
 
-## Hosted sandbox nodes
+## Sandbox nodes
 
 The release includes `parsar-sandbox-node` for local and remote hosts. See the
-[Hosted Sandbox Manager guide](HOSTED-SANDBOX-MANAGER.md) for provider selection,
-registration, administrator credentials, fixed Session placement and maintenance.
+[nodes and sandbox backends reference](HOSTED-SANDBOX-MANAGER.md) for provider
+selection, manual registration, administrator credentials, fixed Session placement
+and maintenance.
diff --git a/services/agents-api/deploy/codex/README.md b/services/agents-api/deploy/codex/README.md
index 15f700b9a..cd0c74f96 100644
--- a/services/agents-api/deploy/codex/README.md
+++ b/services/agents-api/deploy/codex/README.md
@@ -150,12 +150,12 @@ and memory, and the matched immutable Runtime release in PostgreSQL. Docker does
 not accept independent hard root or workspace disk quotas through this contract.
 The saved public Core origin must be reachable from sandbox guests.
 
-Enroll an ordinary sandbox node using the console's one-line command. It fetches
-and validates the deployment configuration, imports the matched Runtime image and
-actively connects to Core. Core can run independently without a Docker socket;
-the node owns its local Docker access. Node files contain the installed selection
-and host-specific paths, never a separate provider or resource choice. A local
-installation opt-in uses this same node workflow.
+Enroll an ordinary sandbox node with Web's one-command [Add node](../../../../docs/getting-started/nodes.md)
+flow. It fetches and validates the deployment configuration, imports the matched
+Runtime image and actively connects to Core. Core can run independently without a
+Docker socket; the node owns its local Docker access. Node files contain the installed
+selection and host-specific paths, never a separate provider or resource choice. The
+Core host joins through the same command as any other host.
 
 Provider, resource and Runtime changes use deployment maintenance, the current
 generation and verified zero retained or pending execution resources. Stopped
diff --git a/services/agents-api/deploy/microsandbox/README.md b/services/agents-api/deploy/microsandbox/README.md
index 3418015e3..bbeb45b40 100644
--- a/services/agents-api/deploy/microsandbox/README.md
+++ b/services/agents-api/deploy/microsandbox/README.md
@@ -3,9 +3,8 @@
 Run the ordinary standalone sandbox node and its microsandbox helper natively on
 Linux amd64 with KVM access. Core owns scheduling and durable recovery over the
 node protocol; it can run independently in a container or on another host.
-PostgreSQL can remain in Docker. The installer’s local microsandbox opt-in still
-runs Core as a native user service, but that packaging choice is not a requirement
-of the provider architecture.
+PostgreSQL can remain in Docker. Core packaging, container or native, is independent
+of the provider.
 
 A hosted Session gets a dedicated microVM with the existing daemon, native harness
 and workspace. Core suspends it only after a completed Turn has remained idle and
@@ -14,8 +13,9 @@ files and configuration. Native harness startup and shutdown retain their existi
 behavior. This profile uses microsandbox v0.7.2; the helper performs one finite
 operation and exits.
 
-Start with the [installation guide](../../../../docs/getting-started/install.md)
-and [Hosted Sandbox Manager](../../HOSTED-SANDBOX-MANAGER.md). The
+Start with the [installation guide](../../../../docs/getting-started/install.md),
+the [nodes guide](../../../../docs/getting-started/nodes.md) and the
+[nodes operator reference](../../HOSTED-SANDBOX-MANAGER.md). The
 [deployment configuration contract](../../../../contracts/agents-api/sandbox-deployment.md)
 defines the saved selection, resources, Runtime identity and node authorization.
 The [provider contract](../../tools/microsandbox-provider/README.md) describes
diff --git a/services/agents-api/tools/microsandbox-provider/README.md b/services/agents-api/tools/microsandbox-provider/README.md
index e4b48761d..9ced99eca 100644
--- a/services/agents-api/tools/microsandbox-provider/README.md
+++ b/services/agents-api/tools/microsandbox-provider/README.md
@@ -17,16 +17,15 @@ are checked. This does not claim a new direct root-capacity measurement on resto
 The ordinary standalone sandbox node runs this helper natively on Linux amd64,
 under a dedicated service user with KVM access. Core owns lifecycle intent through
 the node protocol and can run in a container or on another host. Core's
-container image does not execute this helper; only the node does. The installer's local
-microsandbox opt-in still uses native Core packaging; that is an installation
-choice, not an architectural requirement.
+container image does not execute this helper; only the node does. Core packaging,
+container or native, is independent of the provider.
 
 PostgreSQL owns the provider, per-sandbox resources and immutable Runtime release.
 The node installs that specification and retains its generation and digest; local
 provider files cannot override it. See the
 [deployment contract](../../../../contracts/agents-api/sandbox-deployment.md),
-[installation guide](../../../../docs/getting-started/install.md) and
-[Hosted Sandbox Manager](../../HOSTED-SANDBOX-MANAGER.md). Core no longer accepts a
+[nodes guide](../../../../docs/getting-started/nodes.md) and
+[nodes operator reference](../../HOSTED-SANDBOX-MANAGER.md). Core no longer accepts a
 file-managed startup selection or automatically adopts an older file-managed
 database.
 
diff --git a/site/index.html b/site/index.html
index 87d5ec3b4..d6f7dc9a9 100644
--- a/site/index.html
+++ b/site/index.html
@@ -36,15 +36,12 @@ <h1 id="hero-title">One Core.<br><span>Many agents.</span></h1>
           <div class="stage-label"><span aria-hidden="true">↳</span> Your application. Your endpoint.</div>
           <div class="code-panel">
             <div class="panel-header"><span class="file-label"><span aria-hidden="true">&lt;/&gt;</span> connect.py</span><span class="panel-tag">PYTHON</span></div>
-            <pre aria-label="Python example listing saved agents from your Core"><code><span class="syntax-keyword">import</span> os
-<span class="syntax-keyword">from</span> openai <span class="syntax-keyword">import</span> OpenAI
+            <pre aria-label="Python example listing saved agents from your Core"><code><span class="syntax-keyword">from</span> openai <span class="syntax-keyword">import</span> OpenAI
 
-client = OpenAI(
-    base_url=<span class="syntax-string">"http://localhost:8091/v1"</span>,
-    api_key=os.environ[<span class="syntax-string">"PARSAR_CORE_API_KEY"</span>],
-)
+<span class="syntax-comment"># OPENAI_BASE_URL: your Core's /v1 address</span>
+<span class="syntax-comment"># OPENAI_API_KEY: a project API key from Web</span>
+client = OpenAI()
 
-<span class="syntax-comment"># Use the same client with your Core.</span>
 <span class="syntax-keyword">for</span> agent <span class="syntax-keyword">in</span> client.beta.agents.list():
     <span class="syntax-function">print</span>(agent.id)</code></pre>
             <div class="code-caption"><span>Official Python client</span><span>3.13.0 <span aria-hidden="true">·</span> agents=v1</span></div>
@@ -76,18 +73,18 @@ <h1 id="hero-title">One Core.<br><span>Many agents.</span></h1>
         <div class="install-copy">
           <p class="eyebrow">02 / Get started</p>
           <h2 id="install-title">Install. Sign in.<br> Add a node.</h2>
-          <p>Install Core and Web together. Add execution nodes when you need them.</p>
+          <p>Install Core and Web together with one command. Add nodes when you need them.</p>
           <a class="text-link" href="https://github.com/MiniMax-AI/parsar-core/blob/main/docs/getting-started/install.md">Read the installation guide <span aria-hidden="true">→</span></a>
-          <div class="install-prerequisites"><span class="note-label">BEFORE YOU START</span><p>Use a verified Linux amd64 bundle. Choose an HTTPS address reachable from your nodes and sandboxes, and configure DNS/TLS before the first install.</p><p>Download a matching bundle from <a href="https://github.com/MiniMax-AI/parsar-core/releases">GitHub Releases</a>, signing in if GitHub asks. For unreleased changes, <a href="https://github.com/MiniMax-AI/parsar-core/blob/main/docs/getting-started/install.md#build-a-distribution">build from source</a>.</p></div>
+          <div class="install-prerequisites"><span class="note-label">BEFORE YOU START</span><p>A Linux amd64 host with Docker. For nodes, an HTTPS address behind your reverse proxy; you can add it after installing.</p><p>Download a bundle from <a href="https://github.com/MiniMax-AI/parsar-core/releases">GitHub Releases</a> with <code>gh release download</code>. The repository is internal for now, so run <code>gh auth login</code> first. For unreleased changes, <a href="https://github.com/MiniMax-AI/parsar-core/blob/main/docs/maintainers.md#build-a-distribution">build a distribution</a>.</p></div>
         </div>
         <div class="setup-path">
           <ol class="setup-steps">
             <li class="setup-step"><span class="step-number" aria-hidden="true">01</span><div class="step-content"><div class="step-title"><h3>Install Core + Web</h3><span class="badge">ZERO NODES</span></div><p>Run from your extracted bundle. Core, Web and PostgreSQL start together. No model key required.</p><pre class="install-command"><code>./install.sh \
     --public-url https://core.example</code></pre></div></li>
-            <li class="setup-step"><span class="step-number" aria-hidden="true">02</span><div class="step-content"><h3>Sign in to your console</h3><p>Open the address printed by the installer. Sign in with the Core key in this private file:</p><div class="file-path"><code>~/.parsar/core/secrets/core.key</code></div><p class="step-detail">The paired console is already connected to Core.</p></div></li>
-            <li class="setup-step"><span class="step-number" aria-hidden="true">03</span><div class="step-content"><h3>Bring a node online</h3><p>Open <strong>Nodes</strong>, choose Docker or microsandbox, then <strong>Save configuration</strong>. Select <strong>Add node</strong>, then copy and run the command on a prepared Linux host.</p><div class="provider-options"><span>Docker</span><span>microsandbox</span></div><p class="step-detail">Web shows when the node is online and its provider is ready. All nodes use the same provider.</p></div></li>
+            <li class="setup-step"><span class="step-number" aria-hidden="true">02</span><div class="step-content"><h3>Sign in and issue a key</h3><p>Open the address printed by the installer. Sign in with the Core key in this private file:</p><div class="file-path"><code>~/.parsar/core/secrets/core.key</code></div><p class="step-detail">Set a default model on <strong>System</strong>, then create a project and issue a key on <strong>Projects and keys</strong>.</p></div></li>
+            <li class="setup-step"><span class="step-number" aria-hidden="true">03</span><div class="step-content"><h3>Add a node</h3><p>Open <strong>Nodes</strong>, choose <strong>Add node</strong>, then <strong>Generate command</strong>. Paste the command on a Linux host with sudo; it prepares the host itself.</p><div class="provider-options"><span>Docker</span><span>microsandbox</span></div><p class="step-detail">Web shows when the node is online and ready. All nodes use the same provider.</p></div></li>
           </ol>
-          <p class="setup-footnote">Installation and enrollment do not call a model. <a href="https://github.com/MiniMax-AI/parsar-core/blob/main/docs/getting-started/install.md#installation-choices">Other installation options <span aria-hidden="true">↗</span></a></p>
+          <p class="setup-footnote">Installation and enrollment do not call a model. <a href="https://github.com/MiniMax-AI/parsar-core/blob/main/docs/getting-started/install.md#installer-options">Other installation options <span aria-hidden="true">↗</span></a></p>
         </div>
       </section>
 

From 486587f2937bf41dec073ba476b95341a4e9436c Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Sat, 26 Sep 2026 04:48:01 +0000
Subject: [PATCH 2/7] Say where E2B settings live and what generated/ holds

---
 docs/configuration.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 399f33394..28147657e 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -10,8 +10,8 @@ Every setting of a Core installation has exactly one home. There are two kinds:
 Web's **System** page shows both: the installation's addresses, the process settings
 read-only with the path of `config.json` and the apply command, the default models,
 and the sandbox configuration. Secrets live in [`secrets/`](#secrets-and-identity),
-one copy each. No setting is stored twice, and no configuration file defines Projects
-or API keys.
+one copy each. Each setting is set in one place; the files in `generated/` are only
+derived from `config.json`. No configuration file defines Projects or API keys.
 
 ## Process settings: config.json
 
@@ -121,7 +121,7 @@ Core API with the Core key.
 | --- | --- | --- | --- |
 | Sandbox backend: Docker, microsandbox or E2B | **Nodes** (**Sandbox backend** with E2B): the setup wizard, ending with **Save configuration** | `/core/v1/sandbox/deployment` | One backend per deployment. `install.sh --sandbox` saves the first choice. Changing it needs [maintenance](#sandbox-deployment) |
 | Sandbox size and Runtime release | **Nodes**: the setup wizard | `/core/v1/sandbox/deployment` | Every sandbox gets the same size. See [Sandbox deployment](#sandbox-deployment) |
-| E2B API key and template build | **Sandbox backend**: the setup wizard | `/core/v1/sandbox/deployment` | The key is write-only and encrypted |
+| E2B API key and template build | **Nodes**: the setup wizard's **E2B cloud** (the page is then called **Sandbox backend**) | `/core/v1/sandbox/deployment` | The key is write-only and encrypted |
 | Maintenance | **Nodes**: **Enter maintenance to change provider**, **Resume hosted placement** | `PATCH /core/v1/sandbox/deployment/maintenance` | Pauses new hosted sandboxes while you change the backend |
 | Nodes and their capacity | **Nodes**: **Add node**, **Edit node**, **Remove node** | `/core/v1/sandbox/enrollment-tokens`, `/core/v1/sandbox/nodes` | See [Node capacity](#node-capacity) and the [nodes guide](getting-started/nodes.md) |
 | Projects and API keys | **Projects and keys**: **Create project**, **Issue key**, **Revoke**, **Archive** | `/core/v1/projects` | Keys are shown once; Core stores digests |

From edb7d23b1549c5f5075efc189811cfa289a4ebc3 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Sat, 26 Sep 2026 04:48:52 +0000
Subject: [PATCH 3/7] Tighten the node prerequisites and upgrade notes wording

---
 docs/getting-started/nodes.md      | 2 +-
 docs/getting-started/operations.md | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/getting-started/nodes.md b/docs/getting-started/nodes.md
index 023909e1e..695173c15 100644
--- a/docs/getting-started/nodes.md
+++ b/docs/getting-started/nodes.md
@@ -101,7 +101,7 @@ sudo-mode service instead. An administrator prepares that user once:
   running, restart it (`sudo systemctl restart user@$(id -u <user>).service`) or reboot.
 - microsandbox only: a home directory of at most 25 bytes, such as `/home/parsar`,
   because microsandbox's socket paths are short.
-- The host requirements above, except root and the SELinux rule.
+- The host requirements above, except root, SELinux and one Core per host.
 
 Run the command as that user over SSH, or from a root shell with `su - <user>`. The
 node's state then lives in `~/.parsar/nodes/<installation-id>/` of that user. The
diff --git a/docs/getting-started/operations.md b/docs/getting-started/operations.md
index 0e423a70b..580b4f4e4 100644
--- a/docs/getting-started/operations.md
+++ b/docs/getting-started/operations.md
@@ -202,8 +202,8 @@ and run the Web host's `parsar apply` afterwards.
 
 ### Upgrade notes
 
-Current Core and Web refuse to start while a retired setting is present, and the error
-names the replacement:
+These names are retired. Core and Web refuse to start while a retired setting is
+present, and `install.sh` rejects its retired flags; each error names the replacement:
 
 | Retired | Replacement | Where |
 | --- | --- | --- |
@@ -217,7 +217,7 @@ names the replacement:
 | `CORE_CONSOLE_AUTH_MODE`, `CORE_CONSOLE_STATE_DIR`, `CORE_CONSOLE_PASSWORD_FILE` | None: Web has no accounts or passwords; sign in with the Core key | Web environment, with their `state/console` and `config/console.password` mounts |
 | `install.sh --sandbox-provider`, `--provider` | `install.sh --sandbox`; add the Core host as a node with Add node | Installer flags |
 | `install.sh --status`, `--stop` | `parsar status`, `parsar stop` | Installer flags |
-| `PARSAR_NODE_ENROLLMENT_TOKEN` | The token on standard input with `--enrollment-token-stdin`, as Web's Add node command passes it | Node installer |
+| `PARSAR_NODE_ENROLLMENT_TOKEN` | The token on standard input with `--enrollment-token-stdin`, as Web's Add node command passes it | Node installer environment |
 
 Rename or remove the old names of an installation made before `config.json` before
 converting it. Hosted and self-hosted Sessions that relied on the retired options file

From b2808e8bb933b2793491e3e9816cfc3ca658e8a2 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Sat, 26 Sep 2026 05:09:48 +0000
Subject: [PATCH 4/7] Name the node payload variable for a Web run without the
 installer

---
 docs/configuration.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/configuration.md b/docs/configuration.md
index 28147657e..55ab956c0 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -225,6 +225,12 @@ loads the file with `env_file` and systemd with `EnvironmentFile`, so Compose mu
 | `PARSAR_LOG_LEVEL`, `PARSAR_LOG_FORMAT`, `PARSAR_LOG_ADD_SOURCE` | `log.*`; Web reads the same three |
 | `AGENTS_API_E2B_STATE_DIR`, `AGENTS_API_E2B_PROVIDER_BIN` | The E2B receipt directory and, for native Core, the bundled helper. The E2B key and template live in the database |
 
+A Web you run without the installer reads the variables in
+[Connecting the administrator console to Core](web/core-connection.md#server-configuration-and-login),
+plus `CORE_CONSOLE_NODE_PAYLOAD_DIR`: the absolute path of the matched distribution's
+node payload (the installer's `node-payload/`). Without it, Add node and the
+self-hosted install command are unavailable.
+
 Core fails at startup, naming the replacement, while a retired variable is set:
 `AGENTS_API_DAEMON_WS_URL` (use `AGENTS_API_PUBLIC_URL`), `AGENTS_API_CONFIG_FILE`
 (no replacement), `AGENTS_API_EXECUTION_OPTIONS_FILE` (use

From 9c6fd9915d55e086ca9609c35908b33609213a86 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Sat, 26 Sep 2026 05:40:36 +0000
Subject: [PATCH 5/7] Check bundled doc links whose text is code, and bundle
 the README banner

The link scanner split each line on code spans first, so a link such as
[`config.json`](path) was neither rewritten nor checked, and three dead
relative links shipped. Links are now found on the whole line, skipping only code
spans outside link text. Anchors follow GitHub's rules for closing hashes and
emphasis, fenced blocks close only on a matching fence, and indented code blocks
are skipped. The README banner ships with the bundle so it renders offline.
---
 scripts/core-distribution-manifest.py      | 116 +++++++++++++++++----
 scripts/core-distribution-manifest.test.py |  47 ++++++---
 2 files changed, 131 insertions(+), 32 deletions(-)

diff --git a/scripts/core-distribution-manifest.py b/scripts/core-distribution-manifest.py
index e86f4f77d..9b44c4fc4 100644
--- a/scripts/core-distribution-manifest.py
+++ b/scripts/core-distribution-manifest.py
@@ -46,10 +46,13 @@
     "services/agents-api/HOSTED-SANDBOX-MANAGER.md",
     "contracts/agents-api/environment-executor-credentials.md",
 )
+# Files the bundled docs show, copied as they are, so they work offline.
+BUNDLED_FILES = ("docs/assets/openagentcore-banner.png",)
 REPOSITORY_URL = "https://github.com/MiniMax-AI/parsar-core"
 MARKDOWN_LINK = re.compile(r"(!?)\[((?:[^\[\]]|\[[^\]]*\])*)\]\(([^)\s]+)((?:\s+\"[^\"]*\")?)\)")
-FENCE = re.compile(r"\s*(```|~~~)")
-HEADING = re.compile(r"(#{1,6})\s+(.*?)\s*#*\s*\Z")
+FENCE = re.compile(r" {0,3}(`{3,}|~{3,})")
+HEADING = re.compile(r" {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*\Z")
+LIST_ITEM = re.compile(r" {0,3}(?:[-*+]|\d{1,9}[.)])(?:[ \t]|\Z)")
 
 
 def sha256(path):
@@ -331,14 +334,81 @@ def archive(bundle, epoch, variant=""):
 
 
 def markdown_lines(text):
-    """(line, inside a code block) for each line of a Markdown document."""
-    fenced = False
+    """(line, inside a code block) for each line of a Markdown document.
+
+    Fenced blocks close only with a fence of the same character, at least as long.
+    A line indented by four or more columns after a blank line is an indented code
+    block, except inside a list, where indentation continues the list item.
+    """
+    fence, in_list, previous_blank, previous_code = None, False, True, False
     for line in text.split("\n"):
-        if FENCE.match(line):
-            fenced = not fenced
+        opening = FENCE.match(line)
+        if fence is not None:
+            closes = opening and opening.group(1)[0] == fence[0] and len(opening.group(1)) >= len(fence) \
+                and not line[opening.end():].strip()
+            if closes:
+                fence = None
             yield line, True
+            continue
+        if opening:
+            fence = opening.group(1)
+            yield line, True
+            continue
+        blank = not line.strip()
+        indent = len(line.expandtabs(4)) - len(line.expandtabs(4).lstrip(" "))
+        code = not blank and indent >= 4 and not in_list and (previous_blank or previous_code)
+        if not blank and not code:
+            if LIST_ITEM.match(line):
+                in_list = True
+            elif indent == 0:
+                in_list = False
+        previous_blank, previous_code = blank, code or (previous_code and blank)
+        yield line, code
+
+
+def code_span_end(line, position):
+    """The end of the code span opening at position, or None when its backticks never close."""
+    run = re.match(r"`+", line[position:]).group(0)
+    closing = re.compile(r"(?<!`)" + run + r"(?!`)").search(line, position + len(run))
+    return closing.end() if closing else None
+
+
+def links(line):
+    """The Markdown links of one line, skipping code spans outside link text."""
+    position = 0
+    while position < len(line):
+        if line[position] == "`":
+            end = code_span_end(line, position)
+            position = end if end is not None else position + len(re.match(r"`+", line[position:]).group(0))
+            continue
+        match = MARKDOWN_LINK.match(line, position) if line[position] in "![" else None
+        if match:
+            yield match
+            position = match.end()
         else:
-            yield line, fenced
+            position += 1
+
+
+def heading_text(title):
+    """A heading's rendered text: code spans keep their content; links, tags and emphasis markers go."""
+    rendered, text, position = [], "", 0
+    while position < len(title):
+        end = code_span_end(title, position) if title[position] == "`" else None
+        if end is None:
+            text += title[position]
+            position += 1
+            continue
+        rendered.append(plain(text) + title[position:end].strip("`"))
+        text, position = "", end
+    return "".join(rendered) + plain(text)
+
+
+def plain(text):
+    """Markdown text without link syntax, HTML tags and emphasis markers; intraword underscores stay."""
+    text = re.sub(r"!?\[([^\]]*)\]\([^)]*\)", r"\1", text)
+    text = re.sub(r"<[^>]+>", "", text)
+    text = re.sub(r"(?<![^\W_])_+|_+(?![^\W_])", "", text)
+    return re.sub(r"[*~]", "", text)
 
 
 def heading_anchors(text):
@@ -347,8 +417,7 @@ def heading_anchors(text):
     for line, code in markdown_lines(text):
         match = None if code else HEADING.match(line)
         if match:
-            title = re.sub(r"!?\[([^\]]*)\]\([^)]*\)", r"\1", match.group(2)).replace("`", "").replace("*", "")
-            base = re.sub(r"[^\w\- ]", "", re.sub(r"<[^>]+>", "", title).strip().lower()).replace(" ", "-")
+            base = re.sub(r"[^\w\- ]", "", heading_text(match.group(2) or "").strip().lower()).replace(" ", "-")
             count = counts.get(base, 0)
             counts[base] = count + 1
             found.add(base if count == 0 else f"{base}-{count}")
@@ -360,16 +429,19 @@ def rewrite_links(text, rewrite):
     lines = []
     for line, code in markdown_lines(text):
         if not code:
-            parts = re.split(r"(`[^`]*`)", line)
-            line = "".join(part if index % 2 else MARKDOWN_LINK.sub(
-                lambda match: f"{match.group(1)}[{match.group(2)}]({rewrite(bool(match.group(1)), match.group(3))}{match.group(4)})",
-                part) for index, part in enumerate(parts))
+            pieces, position = [], 0
+            for match in links(line):
+                pieces.append(line[position:match.start()])
+                pieces.append(f"{match.group(1)}[{match.group(2)}]({rewrite(bool(match.group(1)), match.group(3))}{match.group(4)})")
+                position = match.end()
+            line = "".join(pieces) + line[position:]
         lines.append(line)
     return "\n".join(lines)
 
 
-def docs(source, bundle, revision, names=BUNDLED_DOCS):
-    """Copy the bundled docs; a link that leaves them points at this revision on GitHub.
+def docs(source, bundle, revision, names=BUNDLED_DOCS, files=BUNDLED_FILES):
+    """Copy the bundled docs and the files they show; a link that leaves them points at
+    this revision on GitHub.
 
     Every relative link must name an existing file, and an anchor an existing heading,
     so a broken link fails the build instead of shipping.
@@ -377,7 +449,7 @@ def docs(source, bundle, revision, names=BUNDLED_DOCS):
     source, bundle = pathlib.Path(source), pathlib.Path(bundle)
     if not re.fullmatch(r"[0-9a-f]{40}", revision):
         raise ValueError("Bundled docs need the full source commit")
-    bundled = set(names)
+    bundled = set(names) | set(files)
     anchors = {}
 
     def headings(path):
@@ -409,10 +481,13 @@ def rewrite(image, link):
         target = bundle / name
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_text(text.replace("@SOURCE_REVISION@", revision), encoding="utf-8")
-    check_docs(bundle, names)
+    for name in files:
+        (bundle / name).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(source / name, bundle / name)
+    check_docs(bundle, names, files)
 
 
-def check_docs(bundle, names=BUNDLED_DOCS):
+def check_docs(bundle, names=BUNDLED_DOCS, files=BUNDLED_FILES):
     """Every relative link in the bundled docs resolves inside the bundle."""
     bundle = pathlib.Path(bundle)
     for name in names:
@@ -420,8 +495,9 @@ def check(image, link):
             if not re.match(r"[A-Za-z][A-Za-z0-9+.-]*:", link):
                 path, _, anchor = link.partition("#")
                 target = posixpath.normpath(posixpath.join(posixpath.dirname(name), unquote(path))) if path else name
-                if target not in names or (anchor and unquote(anchor) not in heading_anchors(
-                        (bundle / target).read_text(encoding="utf-8"))):
+                if target not in set(names) | set(files) or not (bundle / target).is_file() or (
+                        anchor and target.endswith(".md")
+                        and unquote(anchor) not in heading_anchors((bundle / target).read_text(encoding="utf-8"))):
                     raise ValueError(f"Bundled {name} links outside the bundle: {link}")
             return link
         rewrite_links((bundle / name).read_text(encoding="utf-8"), check)
diff --git a/scripts/core-distribution-manifest.test.py b/scripts/core-distribution-manifest.test.py
index af41177af..619f2e3b0 100644
--- a/scripts/core-distribution-manifest.test.py
+++ b/scripts/core-distribution-manifest.test.py
@@ -249,46 +249,69 @@ def test_bootstraps_include_shared_downloader_and_are_reproducible(self):
 
 
 class BundledDocsTests(unittest.TestCase):
+    NAMES = ("README.md", "docs/install.md")
+
     def setUp(self):
         self.temporary = tempfile.TemporaryDirectory()
         self.addCleanup(self.temporary.cleanup)
         self.source = pathlib.Path(self.temporary.name) / "source"
         self.bundle = pathlib.Path(self.temporary.name) / "bundle"
         for name, text in {
-            "README.md": "# Title\n\n![Banner](docs/banner.png)\n[Install](docs/install.md#sign-in-to-web), "
-                         "[API](contracts/api.md#routes), [web](docs/web), `[kept](missing.md)`, "
+            "README.md": "# Title\n\n![Banner](docs/banner.png) ![Chart](docs/chart.png)\n"
+                         "[Install](docs/install.md#sign-in-to-web), [API](contracts/api.md#routes), [web](docs/web), "
+                         "`[kept](missing.md)`, [`schema.json`](contracts/schema.json), "
                          "[main](https://github.com/MiniMax-AI/parsar-core/blob/main/LICENSE)\n"
-                         "```sh\n[not a link](missing.md)\n```\n",
-            "docs/install.md": "# Install\n## Sign in to Web\n[Back](../README.md#title) [Here](#sign-in-to-web)\n",
-            "docs/banner.png": "",
+                         "```sh\n[not a link](missing.md)\n```\n\n    [indented code](missing.md)\n",
+            "docs/install.md": "# Install\n## Sign in to Web\n## C#\n## _Emphasis_ and snake_case\n"
+                               "[Back](../README.md#title) [Here](#sign-in-to-web) [C](#c) [E](#emphasis-and-snake_case)\n"
+                               "- A list item\n\n    [continued](#install)\n",
+            "docs/banner.png": "png",
+            "docs/chart.png": "png",
             "docs/web/README.md": "# Web\n",
             "contracts/api.md": "# API\n## Routes\n",
+            "contracts/schema.json": "{}",
         }.items():
             (self.source / name).parent.mkdir(parents=True, exist_ok=True)
             (self.source / name).write_text(text)
 
+    def bundle_docs(self):
+        distribution.docs(self.source, self.bundle, REVISION, names=self.NAMES, files=("docs/banner.png",))
+
     def test_links_leaving_the_bundle_point_at_the_revision(self):
-        distribution.docs(self.source, self.bundle, REVISION, names=("README.md", "docs/install.md"))
+        self.bundle_docs()
         versioned = "https://github.com/MiniMax-AI/parsar-core/{}/" + REVISION + "/"
         self.assertEqual((self.bundle / "README.md").read_text(), (
-            "# Title\n\n![Banner](" + versioned.format("raw") + "docs/banner.png)\n"
+            "# Title\n\n![Banner](docs/banner.png) ![Chart](" + versioned.format("raw") + "docs/chart.png)\n"
             "[Install](docs/install.md#sign-in-to-web), [API](" + versioned.format("blob") + "contracts/api.md#routes), "
             "[web](" + versioned.format("tree") + "docs/web), `[kept](missing.md)`, "
-            "[main](" + versioned.format("blob") + "LICENSE)\n```sh\n[not a link](missing.md)\n```\n"))
+            "[`schema.json`](" + versioned.format("blob") + "contracts/schema.json), "
+            "[main](" + versioned.format("blob") + "LICENSE)\n```sh\n[not a link](missing.md)\n```\n\n"
+            "    [indented code](missing.md)\n"))
         self.assertEqual((self.bundle / "docs/install.md").read_text(), (self.source / "docs/install.md").read_text())
+        self.assertEqual((self.bundle / "docs/banner.png").read_text(), "png")
         self.assertFalse((self.bundle / "contracts").exists())
 
     def test_broken_links_and_anchors_fail_the_build(self):
-        for text in ("[x](missing.md)", "[x](docs/install.md#no-such-heading)", "[x](../outside.md)", "[x](#nowhere)"):
-            (self.source / "README.md").write_text("# Title\n" + text + "\n")
-            with self.assertRaises(ValueError):
-                distribution.docs(self.source, self.bundle, REVISION, names=("README.md", "docs/install.md"))
+        for text in ("[x](missing.md)", "[x](docs/install.md#no-such-heading)", "[x](../outside.md)", "[x](#nowhere)",
+                     "[`code text`](missing.md)", "See [`a`](docs/install.md#gone) and more"):
+            with self.subTest(text=text):
+                (self.source / "README.md").write_text("# Title\n" + text + "\n")
+                with self.assertRaises(ValueError):
+                    self.bundle_docs()
+
+    def test_the_bundle_check_reads_code_span_links(self):
+        self.bundle_docs()
+        (self.bundle / "README.md").write_text("# Title\n[`schema.json`](contracts/schema.json)\n")
+        with self.assertRaises(ValueError):
+            distribution.check_docs(self.bundle, self.NAMES, ("docs/banner.png",))
 
     def test_repository_docs_are_self_consistent(self):
         repository = pathlib.Path(__file__).resolve().parent.parent
         distribution.docs(repository, self.bundle, REVISION)
         self.assertEqual({str(path.relative_to(self.bundle)) for path in self.bundle.rglob("*.md")},
                          set(distribution.BUNDLED_DOCS))
+        for name in distribution.BUNDLED_FILES:
+            self.assertTrue((self.bundle / name).is_file())
         for name in distribution.BUNDLED_DOCS:
             self.assertNotIn("@SOURCE_REVISION@", (self.bundle / name).read_text())
             self.assertNotIn("/blob/main/", (self.bundle / name).read_text())

From fe781f4a497143d1ccdc197b44541f8a795a35f7 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Sat, 26 Sep 2026 05:44:22 +0000
Subject: [PATCH 6/7] Fix the install docs from the blind review and the Web UI
 check

- Web-only: --core-url must reach Core's /core/v1 directly (loopback, or a second
  HTTPS name proxying everything to Core); document the split deployment's proxies.
- Conversion: back up with the old top-level compose.json before --yes; rename only
  the pre-Core-key names by hand and leave the rest, and AGENTS_API_PUBLIC_URL, to
  --convert.
- Quickstart: read the key without echo or history, keep it off curl's command line,
  name the none rejection, and ask for the default provider's model ID.
- README: follow the docs inside the downloaded bundle; Overview's checklist.
- Upgrades between config.json releases are not supported yet; /api/v1 routing
  applies to every sandbox kind; rotate-core-key on a stopped installation.
- Nodes: Retained sandboxes is microsandbox only, the early 401 message, the log
  command, user-manager restart without sudo, Web's labels for readiness codes and
  removal, NODE_USER, and a neutral note on changing the backend.
- Self-hosted: Web's labels and dialog, the credential file name, the Docker CLI and
  root refusal, the rerun refusal after an upgrade or address change, archived
  projects.
- Configuration: Startup settings, Rename, what credential.key seals, the executor
  consequence of a public URL change, the full retired list.
- Claude Code is the display name of harness claude_sdk.
---
 README.md                           |   5 ++
 docs/configuration.md               |  44 ++++++-----
 docs/getting-started/install.md     |  69 +++++++++++------
 docs/getting-started/nodes.md       | 116 ++++++++++++++++------------
 docs/getting-started/operations.md  |  62 ++++++++++-----
 docs/getting-started/quickstart.md  |  22 +++---
 docs/getting-started/self-hosted.md |  53 ++++++++-----
 7 files changed, 226 insertions(+), 145 deletions(-)

diff --git a/README.md b/README.md
index 361bc131c..d37779a09 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,8 @@ administrator console that issues the keys applications call Core with.
 
    Put your HTTPS reverse proxy in front first, or install without `--public-url` for a
    local trial and set it later. See the [installation guide](docs/getting-started/install.md).
+   Follow the docs inside the downloaded bundle (`docs/` and `README.md`): they match
+   its installer, while these pages describe the current source.
 2. **Sign in to Web with the Core key**, from `~/.parsar/core/secrets/core.key`. On
    **System**, set a default model; on **Projects and keys**, create a project and
    issue a key. See [Sign in to Web](docs/getting-started/install.md#sign-in-to-web).
@@ -33,6 +35,9 @@ administrator console that issues the keys applications call Core with.
    **Generate command**, and run the command on a Linux host with sudo. See
    [Nodes](docs/getting-started/nodes.md).
 
+Web's **Overview** tracks these steps, and the first Session, in its **Getting started**
+checklist; they can be done in any order.
+
 Applications then set `OPENAI_BASE_URL` to `https://core.example/v1` and
 `OPENAI_API_KEY` to the Project API key, and use the official OpenAI SDK; see
 [Call the API](docs/getting-started/quickstart.md).
diff --git a/docs/configuration.md b/docs/configuration.md
index 55ab956c0..a4418dd32 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -8,8 +8,8 @@ Every setting of a Core installation has exactly one home. There are two kinds:
 | [Runtime settings](#runtime-settings-web) | Sandbox backend and size, nodes, Projects and keys, default models, executor credentials | Core's PostgreSQL database | Web, or the Core API (`/core/v1`) with the Core key | At once, without a restart |
 
 Web's **System** page shows both: the installation's addresses, the process settings
-read-only with the path of `config.json` and the apply command, the default models,
-and the sandbox configuration. Secrets live in [`secrets/`](#secrets-and-identity),
+read-only under **Startup settings** with the path of `config.json` and the apply
+command, the default models, and the sandbox configuration. Secrets live in [`secrets/`](#secrets-and-identity),
 one copy each. Each setting is set in one place; the files in `generated/` are only
 derived from `config.json`. No configuration file defines Projects or API keys.
 
@@ -63,7 +63,9 @@ sandboxes or self-hosted executors are bound to the current address, `apply` lis
 them and asks you to type the new URL (`--confirm-public-url-change URL` when not
 interactive). Afterwards, nodes on the old address get no new sandboxes: remove them
 in Web and add them again. Existing sandboxes and executors keep working only while
-the old address still reaches this Core. Update your reverse proxy first.
+the old address still reaches this Core, and `apply` warns that self-hosted executors
+must restart with the new `remote_url`; their installer refuses to reuse an
+installation made for the old address. Update your reverse proxy first.
 
 ### Settings
 
@@ -119,12 +121,11 @@ Core API with the Core key.
 
 | Setting | Where in Web | Core API | Notes |
 | --- | --- | --- | --- |
-| Sandbox backend: Docker, microsandbox or E2B | **Nodes** (**Sandbox backend** with E2B): the setup wizard, ending with **Save configuration** | `/core/v1/sandbox/deployment` | One backend per deployment. `install.sh --sandbox` saves the first choice. Changing it needs [maintenance](#sandbox-deployment) |
+| Sandbox backend: Docker, microsandbox or E2B | **Nodes** (**Sandbox backend** with E2B): the setup wizard, ending with **Save configuration** | `/core/v1/sandbox/deployment` | One backend per deployment. `install.sh --sandbox` saves the first choice. To change it, see the Nodes page; that flow will change in a coming release |
 | Sandbox size and Runtime release | **Nodes**: the setup wizard | `/core/v1/sandbox/deployment` | Every sandbox gets the same size. See [Sandbox deployment](#sandbox-deployment) |
 | E2B API key and template build | **Nodes**: the setup wizard's **E2B cloud** (the page is then called **Sandbox backend**) | `/core/v1/sandbox/deployment` | The key is write-only and encrypted |
-| Maintenance | **Nodes**: **Enter maintenance to change provider**, **Resume hosted placement** | `PATCH /core/v1/sandbox/deployment/maintenance` | Pauses new hosted sandboxes while you change the backend |
-| Nodes and their capacity | **Nodes**: **Add node**, **Edit node**, **Remove node** | `/core/v1/sandbox/enrollment-tokens`, `/core/v1/sandbox/nodes` | See [Node capacity](#node-capacity) and the [nodes guide](getting-started/nodes.md) |
-| Projects and API keys | **Projects and keys**: **Create project**, **Issue key**, **Revoke**, **Archive** | `/core/v1/projects` | Keys are shown once; Core stores digests |
+| Nodes and their capacity | **Nodes**: **Add node**, **Edit node**, **Remove node** on a node's page (**Remove** in its list row) | `/core/v1/sandbox/enrollment-tokens`, `/core/v1/sandbox/nodes` | See [Node capacity](#node-capacity) and the [nodes guide](getting-started/nodes.md) |
+| Projects and API keys | **Projects and keys**: **Create project**, **Rename**, **Issue key**, **Revoke**, **Archive** | `/core/v1/projects` | Keys are shown once; Core stores digests |
 | Default model per harness | **System**: **Default model** | `/core/v1/harnesses/{harness}/model-provider` | See [Default models](#default-models) |
 | Executor credentials of a self-hosted Session | **Session log**, the Session's page: **Executor credentials** | `/core/v1/projects/{project_id}/environments/{environment_id}/executor-credentials` | See [self-hosted executors](getting-started/self-hosted.md) |
 
@@ -153,22 +154,21 @@ E2B takes no `runtime`, and Web sends no resources for it: Core adopts the CPU a
 memory of the ready template build `template-id:build-uuid`, and supplied values must
 match it. Docker has no separate disk quota.
 
-Changing the provider, the size or the Runtime is a deployment-wide procedure: enter
-maintenance, let or make every hosted sandbox finish and clean up, save the new
-configuration against the current generation, then resume. A successful change
-retires the old nodes and enrollment commands; history stays. Nothing is deleted
-automatically, and existing Sessions never move between providers. See
-[maintenance](../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
+Changing the provider, the size or the Runtime applies to the whole deployment; see the
+**Nodes** page, and note that this flow will change in a coming release. A successful
+change retires the old nodes and enrollment commands; history stays, and existing
+Sessions never move between providers. See the
+[operator reference](../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
 and the [deployment contract](../contracts/agents-api/sandbox-deployment.md).
 
 ### Node capacity
 
 Core approves a node's capacity when you generate its Add node command: **Sandboxes
-at once** (`max_active`, default 2) and **Retained sandboxes** (`max_retained`,
-default 8), with `max_retained >= max_active >= 1`. Change them later with
-**Edit node**. Reservations and cleanup that is not confirmed count against capacity;
-lowering a limit stops no running sandbox. Docker never suspends sandboxes, so its
-`max_retained` always equals `max_active`. A node's own files can't change its
+at once** (`max_active`, default 2) and, for microsandbox only, **Retained sandboxes**
+(`max_retained`, default 8), with `max_retained >= max_active >= 1`. Docker never
+suspends sandboxes, so Web doesn't ask for it and Core keeps `max_retained` equal to
+`max_active`. Change them later with **Edit node**. Reservations and cleanup that is not
+confirmed count against capacity; lowering a limit stops no running sandbox. A node's own files can't change its
 capacity, size or Runtime.
 
 `core.execution_concurrency` is unrelated: it limits concurrent execution work in Core.
@@ -196,7 +196,7 @@ The operator file `AGENTS_API_EXECUTION_OPTIONS_FILE` is retired; see
 | File | Content | Changed by |
 | --- | --- | --- |
 | `secrets/core.key` | The [Core key](getting-started/operations.md#core-key) | `parsar rotate-core-key` |
-| `secrets/credential.key` | Encryption key for credentials stored in the database: model providers, E2B key, Vault credentials | Nothing. Keep it with the database; `parsar apply` refuses a changed file |
+| `secrets/credential.key` | Encryption key for what Core stores sealed in the database: model providers, the E2B key, Vault credentials, Skills, initial files and environment setup | Nothing. Keep it with the database; `parsar apply` refuses a changed file |
 | `secrets/database.password` | PostgreSQL password | Nothing. PostgreSQL reads it only when the database is created; `parsar apply` refuses a changed file |
 | `state.json` | Installation ID, Compose project, image IDs, source commit and the digests of generated files | The tools only |
 
@@ -234,8 +234,10 @@ self-hosted install command are unavailable.
 Core fails at startup, naming the replacement, while a retired variable is set:
 `AGENTS_API_DAEMON_WS_URL` (use `AGENTS_API_PUBLIC_URL`), `AGENTS_API_CONFIG_FILE`
 (no replacement), `AGENTS_API_EXECUTION_OPTIONS_FILE` (use
-[default models](#default-models)) and `AGENTS_API_MANAGED_RUNTIMES_FILE` (the
-sandbox deployment lives in the database). Core logs the file paths it loads, never
+[default models](#default-models)), `AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE` (use
+`AGENTS_API_CORE_KEY_DIGESTS_FILE`), and `AGENTS_API_MANAGED_RUNTIMES_FILE`,
+`AGENTS_API_SANDBOX_NODE_STATE_DIR` and `AGENTS_API_SANDBOX_NODE_CORE_URL` (the
+sandbox deployment lives in the database and nodes enroll separately). Core logs the file paths it loads, never
 environment values or file contents. Native installation paths must be canonical
 absolute paths without control characters, quotes, backslashes or wildcards. Keep the
 installation ID and the database together; Core refuses a missing installation ID
diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index 7b43b86d1..1a5f9071c 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -68,9 +68,9 @@ Each release has two bundles:
 | `parsar-core-<commit>-linux-amd64-offline.tar.gz` | Core, Web and PostgreSQL images, the installers and every node and Runtime file | Any installation. Web serves the node files to your nodes and self-hosted executors |
 | `parsar-core-<commit>-linux-amd64.tar.gz` | The same without the node and Runtime files | E2B-only or Web-only hosts. Web can't add nodes until the files are present |
 
-To add the node files to the smaller bundle, download the release's other
-`parsar-core-<commit>-linux-amd64-*` assets (not the two bundles) into the extracted
-bundle's `artifacts/` directory, then run `./install.sh`, or rerun it if the
+To add the node files to the smaller bundle, create an `artifacts/` directory in the
+extracted bundle, download the release's other `parsar-core-<commit>-linux-amd64-*`
+assets (not the two bundles) into it, then run `./install.sh`, or rerun it if the
 installation already exists. Nodes download these files only from your Web console,
 never from GitHub, so node hosts need no GitHub access.
 
@@ -161,20 +161,37 @@ To change the backend or the sandbox size later, use the Nodes page in Web; see
 | `--core-only` | PostgreSQL and Core | A Core whose Web runs on another host, or scripts only. Without Web there is no Add node command |
 | `--web-only` | Web | A second host for the console, paired with an existing Core |
 
-A Web-only installation needs the Core's origin and a private copy of its Core key:
+A Web-only console forwards every signed-in `/core/v1` request to its Core with the
+Core key, so `--core-url` must reach Core's `/core/v1` directly. The usual reverse proxy
+sends `/core/v1` to Web, so the Core's public URL doesn't work here:
+
+- **Web on the Core host:** use Core's loopback port, `--core-url http://127.0.0.1:8091`.
+- **Web on another host:** give Core a second HTTPS name whose proxy sends every path to
+  Core, such as `https://core-api.example` to `127.0.0.1:8091` on the Core host, and use
+  it as `--core-url`. Anyone who reaches that name still needs the Core key.
+
+A split deployment then looks like this:
+
+| Host | Install | Reverse proxy |
+| --- | --- | --- |
+| Core | `./install.sh --core-only --public-url https://core.example` | `core.example`: `/v1`, `/v1/*` and `/api/v1/*` to Core (there is no Web here). `core-api.example`: every path to Core |
+| Web | See below | `console.example`: every path to Web |
 
 ```sh
 ./install.sh --web-only --install-dir "$HOME/.parsar/core-console" \
   --public-url https://console.example \
-  --core-url https://core.example \
+  --core-url https://core-api.example \
   --core-key-file "$HOME/core.key"
 ```
 
-Its `--public-url` is the address browsers use for this console. Copy the key file
-from the Core host's `secrets/core.key` with mode `0600`; the installer keeps its own
-copy. After the Core key is rotated, copy the new key again; see
-[Rotate the Core key](operations.md#rotate-the-core-key). Web-only installs select no
-sandbox backend; do that on the Core host.
+The Web host's `--public-url` is the address browsers use for this console; nodes also
+download their installer from it. Applications, nodes and sandboxes use the Core
+host's public URL. Copy the key file from the Core host's `secrets/core.key` with mode
+`0600`; the installer keeps its own copy in `secrets/core.key`, so delete
+`$HOME/core.key` afterwards. After the Core key is rotated, copy the new key again; see
+[Rotate the Core key](operations.md#rotate-the-core-key). A Web-only install selects no
+sandbox backend: the Core host's `--sandbox` does, or later the paired console's
+**Nodes** page.
 
 The mode and native Core are fixed once installed. To change them, install into a
 new directory.
@@ -205,7 +222,7 @@ path:
 | --- | --- | --- |
 | `/v1`, `/v1/*` | Core, `127.0.0.1:8091` | Applications, with a Project API key |
 | `/api/v1/*` | Core, `127.0.0.1:8091` | Nodes, sandboxes and self-hosted executors, with their own machine credentials. Uses WebSockets |
-| Everything else | Web, `127.0.0.1:8080` | Browsers: the console, its sign-in, `/core/v1/*` and `/node-install/*` |
+| Everything else | Web, `127.0.0.1:8080` | Browsers: the console, its sign-in and `/core/v1/*`. Node and executor hosts download their installers from `/node-install/*` |
 
 The proxy must:
 
@@ -342,21 +359,27 @@ at Add node.
 
    The Core key is the installation's administrator credential. Keep it private; see
    [Core key](operations.md#core-key). Web has no user accounts.
-3. **Set a default model.** Open **System**, find **Default model** and choose
-   **Set** for the harness your applications use (Codex unless you changed
-   `core.default_harness`). Enter the model provider's base URL and API key; MiniMax
-   Code also needs the context window and max output tokens. Core encrypts the key and
-   never shows it again. Core-hosted Sessions use this default when the request and the
-   Agent carry no model provider; self-hosted Sessions never do. See
+3. **Set a default model.** Open **System** and find **Default model**. On the harness
+   card marked **Default** (Codex unless you changed `core.default_harness`), choose
+   **Set**; once a provider is configured, the button reads **Replace**. Enter the
+   model provider's base URL and API key; MiniMax Code also needs the context window
+   and max output tokens. Core encrypts the key and never shows it again. The default
+   applies to Core-hosted Sessions and Sessions without an environment when the request
+   and the Agent carry no model provider; self-hosted Sessions never use it. See
    [model providers](quickstart.md#model-providers).
-4. **Create a project and issue a key.** Open **Projects and keys**, select
-   **Create project**, then **Issue key** in it. Copy the key: Web shows it once and
-   Core keeps only a digest. Web also shows how to call the API with it.
-5. Give the key and the API base URL to the application developer, who follows the
+4. **Create a project and issue a key.** Open **Projects and keys**, choose
+   **Create project** and give it a **Name**, then **Issue key** in it with a
+   **Key name**. The **Key issued** dialog shows the key once: choose **Copy key**, keep
+   it somewhere safe, then **I've saved this key**. Core keeps only a digest. The
+   dialog's **How to call** card shows the API base URL and sample requests.
+5. Give the application developer the key, the API base URL and the model ID to use
+   with the default model provider (Sessions must name `agent.model`). They follow the
    [API quickstart](quickstart.md).
 
-**Overview** shows the same steps as a **Getting started** checklist, including
-[adding a node](nodes.md).
+**Overview** tracks the setup in a **Getting started** checklist, in any order:
+**Get sandboxes ready** ([add a node](nodes.md)), **Set a default model**,
+**Create a project and issue a key**, and **Run the first Session**. After you hide it,
+**Show Getting started** in the sidebar brings it back.
 
 ## What the installer creates
 
diff --git a/docs/getting-started/nodes.md b/docs/getting-started/nodes.md
index 5f5433efa..3a4089895 100644
--- a/docs/getting-started/nodes.md
+++ b/docs/getting-started/nodes.md
@@ -26,14 +26,17 @@ node protocol, manual registration, placement and failure handling.
 ## Add a node
 
 1. In Web, open **Nodes** and select **Add node**.
-2. Set **Sandboxes at once** (default 2) and **Retained sandboxes** (default 8): how
-   many sandboxes Core may run and keep on this node. You can change them later with
-   **Edit node**.
-3. Select **Generate command** and copy the command. It works once, within 10 minutes;
-   Web counts down and offers **Generate new command** when it expires.
+2. Set **Sandboxes at once** (default 2): how many sandboxes Core may run on this node.
+   With microsandbox, also set **Retained sandboxes** (default 8): how many it may keep,
+   suspended ones included. With Docker, Core keeps retained equal to at once. You can
+   change them later with **Edit node**.
+3. Select **Generate command** and copy the command. It registers one node, once, and
+   only if it runs within 10 minutes; Web counts down and offers
+   **Generate new command** when it expires.
 4. Run it on the host. Web follows the node from registered to connected to ready.
 
-The command downloads the node installer from your console, checks its SHA-256, and
+The command downloads the node installer from the console's public address, checks
+its SHA-256, and
 runs it with a one-time enrollment token. The installer downloads the node files from
 the same console and checks each against the release manifest, imports the Runtime
 image, registers the node, starts its service and waits until Core reports the node
@@ -94,16 +97,19 @@ printf '%s\n' '<enrollment-token>' | python3 "$d/node-install.pyz" --enrollment-
 Run it as the non-root user that will run the node; run by root, it installs the
 sudo-mode service instead. An administrator prepares that user once:
 
-- Docker: `sudo usermod -aG docker <user>`, with Docker enforcing CPU and memory limits.
-  microsandbox: `sudo usermod -aG kvm <user>` for read and write access to `/dev/kvm`.
-- Lingering, after the group change: `sudo loginctl enable-linger <user>`. After a group
-  change, sign in again as that user; if the user's systemd manager was already
-  running, restart it (`sudo systemctl restart user@$(id -u <user>).service`) or reboot.
+- Docker: `sudo usermod -aG docker NODE_USER`, with Docker enforcing CPU and memory
+  limits. microsandbox: `sudo usermod -aG kvm NODE_USER` for read and write access to
+  `/dev/kvm`.
+- Lingering, after the group change: `sudo loginctl enable-linger NODE_USER`. After a
+  group change, sign in again as that user; if the user's systemd manager was already
+  running, restart it (`sudo systemctl restart user@$(id -u NODE_USER).service`) or
+  reboot.
 - microsandbox only: a home directory of at most 25 bytes, such as `/home/parsar`,
   because microsandbox's socket paths are short.
 - The host requirements above, except root, SELinux and one Core per host.
 
-Run the command as that user over SSH, or from a root shell with `su - <user>`. The
+`NODE_USER` stands for that user, as in the dialog's commands. Run the command as that
+user over SSH, or from a root shell with `su - NODE_USER`. The
 node's state then lives in `~/.parsar/nodes/<installation-id>/` of that user. The
 Docker group makes this user root-equivalent on the host too.
 
@@ -118,8 +124,8 @@ Docker group makes this user root-equivalent on the host too.
 | Records | `/etc/parsar-node/`: what the installer created or changed, used by reruns and uninstall |
 | Docker | The Runtime image, imported once, and a network `parsar-node-<installation-id>` |
 
-Root only prepares the account, group, unit and network; everything else runs as
-`parsar-node`, in its own session without a terminal. The installer never installs
+Root only prepares the account, the group and the unit; everything else, the Docker
+network included, runs as `parsar-node`, in its own session without a terminal. The installer never installs
 Docker, KVM or packages, never starts Docker, never changes device permissions,
 sudoers, firewall or SELinux settings, and never touches other accounts.
 
@@ -142,7 +148,11 @@ where `sudo VAR=… python3` would record it in sudo's log. A sudoers policy wit
 
 - 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.
-- If the command expires during a slow download, the downloaded files are kept:
+- 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.
 - Downloads resume where they stopped. A download that brings less than 64 KiB in a
   minute stops, keeping what it has; run the command again.
@@ -155,7 +165,9 @@ where `sudo VAR=… python3` would record it in sudo's log. A sudoers policy wit
 
 ## Logs
 
-After you run the command, the Add node dialog shows the node's log command:
+The installer prints the node's log command (`Logs: …`) when it finishes. The Add node
+dialog shows it too when something needs attention: when the node reports a problem, or
+when it hasn't become connected and ready about a minute after registering.
 
 | Node installed | Command |
 | --- | --- |
@@ -166,7 +178,8 @@ The installation ID is in the command (`--installation-id`) and on the **System*
 
 ## Remove a node
 
-1. In Web, open **Nodes**, select the node and choose **Remove node**. Core refuses
+1. In Web, open **Nodes** and choose **Remove node** on the node's page, or **Remove**
+   in its list row, then **Confirm removal**. Core refuses
    while the node still holds sandboxes, snapshots or pending cleanup; let them finish,
    or [archive their Sessions](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
    through the Core API. Removal is permanent: the host can come back only as a new node.
@@ -183,9 +196,12 @@ The installation ID is in the command (`--installation-id`) and on the **System*
    without `sudo`; run it as that user.
 
 Uninstall first asks Core, at the address the node enrolled with, whether the node was
-removed, and refuses while Core still lists it. If that address no longer responds, for
-example after the public URL changed, **Old Core address gone?** gives the command with
-`--force`, which skips the check; remove the node on the Nodes page first. Uninstall
+removed, and refuses while Core still lists it. When the node enrolled with an address
+other than the current public URL, the dialog also shows **Old Core address gone?**:
+if that address no longer responds, it gives the command with `--force`, which skips
+the check; remove the node on the Nodes page first. Without the dialog, take the
+installer's SHA-256 from the `node-install.pyz` line of
+`https://core.example/node-install/SHA256SUMS`. Uninstall
 stops and removes the service, the node state, the records and the Docker network. It
 deletes the `parsar-node` account only if the installer created it and no node remains;
 an adopted account only loses the groups the installer added.
@@ -201,32 +217,35 @@ check `pgrep -u parsar-node` first. Uninstall can be rerun until it completes.
 
 ### Readiness codes
 
-When a node is online but its provider is not ready, **Nodes** shows one of these codes
-(the `diagnostic` field of `GET /core/v1/sandbox/nodes`). A node reports only its first
-failed check, and the next heartbeat, about ten seconds after a fix, clears or replaces
-the code. The node's log has the local error behind the code.
-
-| Code | Cause | Fix |
-| --- | --- | --- |
-| `docker_unavailable` | The Docker socket is unreachable or not accessible, or Docker fails its info or image request | Start Docker and give the node's user access to `/var/run/docker.sock` |
-| `docker_limits_unsupported` | Docker reports no CPU quota or memory limit support | Use a host whose cgroups enforce CPU and memory limits (cgroup v2) |
-| `runtime_image_unavailable` | Docker does not have the pinned Runtime image | Rerun the add command, or load the image from the matching release |
-| `kvm_unavailable` | The node can't open `/dev/kvm` for reading and writing | Enable hardware virtualization and give the node's user KVM access, through the `kvm` group |
-| `microsandbox_artifacts_unavailable` | The Runtime or firmware is missing or fails its SHA-256 check, or the helper is missing | Rerun the add command |
-| `capacity_insufficient` | The host has fewer CPUs or less memory than one sandbox | Use a larger host, or change the sandbox size |
-| `provider_unavailable` | Any other failure, and every failure an older node reports | Read the node's log |
-
-A new group membership applies only to a new process: restart the service with
-`sudo systemctl restart parsar-node-<installation-id>.service`, or
-`systemctl --user restart parsar-node-<installation-id>.service` without sudo. A node
-that is registered but never connects usually can't reach Core at the public URL, or
-its `/api/v1` WebSocket doesn't pass the reverse proxy.
+When a node is online but its provider is not ready, **Nodes** shows its status as
+**Provider unavailable**, with the reason in a help tip; **Overview** counts it as a
+**Provider issue**. The API reports the reason as a fixed code, the `diagnostic` field
+of `GET /core/v1/sandbox/nodes`. A node reports only its first failed check, and the
+next heartbeat, about ten seconds after a fix, clears or replaces it. The node's log has
+the local error behind the code.
+
+| Code | Web shows | Cause | Fix |
+| --- | --- | --- | --- |
+| `docker_unavailable` | Docker unavailable | The Docker socket is unreachable or not accessible, or Docker fails its info or image request | Start Docker and give the node's user access to `/var/run/docker.sock` |
+| `docker_limits_unsupported` | Docker limits unsupported | Docker reports no CPU quota or memory limit support | Use a host whose cgroups enforce CPU and memory limits (cgroup v2) |
+| `runtime_image_unavailable` | Runtime image missing | Docker does not have the pinned Runtime image | Rerun the add command, or load the image from the matching release |
+| `kvm_unavailable` | KVM unavailable | The node can't open `/dev/kvm` for reading and writing | Enable hardware virtualization and give the node's user KVM access, through the `kvm` group |
+| `microsandbox_artifacts_unavailable` | microsandbox components missing | The Runtime or firmware is missing or fails its SHA-256 check, or the helper is missing | Rerun the add command |
+| `capacity_insufficient` | Host too small | The host has fewer CPUs or less memory than one sandbox | Use a larger host, or change the sandbox size |
+| `provider_unavailable` | Sandbox provider unavailable | Any other failure, and every failure an older node reports | Read the node's log |
+
+A new group membership applies only to a new process. In sudo mode, restart the node
+service: `sudo systemctl restart parsar-node-<installation-id>.service`. Without sudo,
+the user's systemd manager keeps the groups it started with, so restart that manager:
+`sudo systemctl restart user@$(id -u NODE_USER).service`. A node that is registered
+but never connects usually can't reach Core at the public URL, or its `/api/v1`
+WebSocket doesn't pass the reverse proxy.
 
 ### Installer messages
 
 | Message | Fix |
 | --- | --- |
-| The enrollment command expired or was already used | Generate a new command in Web and run it |
+| `Core rejected the node configuration read (HTTP 401)` before anything downloads, or `The enrollment command expired or was already used` | Generate a new command in Web and run it within 10 minutes |
 | Core's public URL changed after this command was generated | Generate a new command in Web and run it |
 | This host's node uses `<address>`, but this command uses `<address>` | The node was added under an older public URL. Remove it in Web, uninstall it, then add it again |
 | Docker Engine is not installed, or Docker is not running | Install Docker Engine, or `sudo systemctl enable --now docker`, then rerun |
@@ -240,11 +259,10 @@ its `/api/v1` WebSocket doesn't pass the reverse proxy.
 
 ## Change the sandbox backend or size
 
-Changing Docker, microsandbox or E2B, the sandbox size or the Runtime release applies to
-the whole deployment. On **Nodes**, choose **Enter maintenance to change provider**, which
-pauses new hosted sandboxes; let the existing ones finish, or archive their Sessions
-through the Core API, until nothing is retained; save the new configuration; then choose
-**Resume hosted placement**. A change retires every node: remove and uninstall them, and
-add the hosts again with new commands. See
-[maintenance](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
-for the exact steps and API.
+To change the sandbox backend, the sandbox size or the Runtime, see the **Nodes** page;
+this flow will change in a coming release. A change applies to the whole deployment
+and retires every node. Retired nodes drop out of the list, so there is nothing to
+remove in Web: on each host, run the [uninstall command](#remove-a-node) (Core no longer
+accepts the node, so it needs no `--force`), then add the host again with a new command.
+The [operator reference](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
+describes today's procedure and API.
diff --git a/docs/getting-started/operations.md b/docs/getting-started/operations.md
index 6d4945847..7adb95f20 100644
--- a/docs/getting-started/operations.md
+++ b/docs/getting-started/operations.md
@@ -102,10 +102,13 @@ curl -fsS -H @<(printf 'Authorization: Bearer %s\n' "$(cat "$HOME/.parsar/core/s
 ~/.parsar/core/parsar rotate-core-key
 ```
 
-It asks for confirmation (`--yes` skips it), stops Web, writes a new key to
-`secrets/core.key`, regenerates the digest file, restarts Core and then starts Web. It
-checks that Core accepts the new key and refuses the old one. The old key stops working
-at once and every console session ends: sign in again and update your scripts. If the
+It refuses while `config.json` has changes that are not applied or a generated file was
+edited by hand: run `parsar apply` first. It asks for confirmation (`--yes` skips it),
+stops Web, writes a new key to `secrets/core.key` and regenerates the digest file. On a
+running installation it then restarts Core, starts Web and checks that Core accepts the
+new key and refuses the old one; a stopped installation only gets the new files and
+uses the new key at the next `parsar start`. The old key stops working as soon as Core
+restarts, and every console session ends: sign in again and update your scripts. If the
 command stops early, `secrets/core.key` holds the key to use; run `parsar apply` to
 finish.
 
@@ -162,12 +165,10 @@ not prove that all provider resources were reclaimed.
 | --- | --- |
 | Made before `config.json` (it has `installation.json`) | [Convert it](#convert-an-earlier-installation) with the new bundle |
 | Made with `config.json`, same release | Rerun `./install.sh` from the same bundle to repair it |
-| Made with `config.json`, other release | Not automated yet: the installer refuses a bundle from another release |
+| Made with `config.json`, other release | Not supported yet. The installer refuses a bundle from another release and says upgrades arrive with `parsar upgrade`, which doesn't exist yet. Keep running the installed release |
 
-For an upgrade the installer does not automate, back up as above, keep the previous
-bundle, let execution settle, and apply the new release's migrations with its matched
-Core, Web and Runtime, keeping the installation ID and backend paths. Qualify recovery
-before calling the upgrade done; there is no downgrade.
+There is no downgrade: database migrations can't be undone, so back up before any
+upgrade or conversion.
 
 ### Convert an earlier installation
 
@@ -180,9 +181,17 @@ Installations made before `config.json` have `installation.json`, `config/core.e
 ```
 
 Conversion is also an upgrade to that release, and its database migrations can't be
-undone: back up first (the command prints a `pg_dump` command). It reads the old files
-without changing anything, shows the resulting settings and asks for confirmation
-(`--yes` skips it). It then writes `config.json` and `state.json`, moves the secrets
+undone. Back up the database first. An installation made before `config.json` keeps its
+Compose file at the top of the installation directory:
+
+```sh
+docker compose -f "$HOME/.parsar/core/compose.json" exec -T database \
+  pg_dump -U agents_api agents_api > parsar-backup.sql
+```
+
+Conversion reads the old files without changing anything, shows the resulting settings
+and the same backup command, and asks for confirmation. `--yes` skips the prompt and
+runs the migrations at once, so use it only after backing up. It then writes `config.json` and `state.json`, moves the secrets
 into `secrets/` without copying them, removes the old generated files, and starts the
 new release with the same Compose project, database and installation ID. Settings set
 by hand, such as `AGENTS_API_EXECUTION_CONCURRENCY`, `PARSAR_LOG_*` or a Runtime history
@@ -220,8 +229,14 @@ replacement:
 | `install.sh --status`, `--stop` | `parsar status`, `parsar stop` | Installer flags |
 | `PARSAR_NODE_ENROLLMENT_TOKEN` | The token on standard input with `--enrollment-token-stdin`, as Web's Add node command passes it | Node installer; it refuses the variable |
 
-Rename or remove the old names of an installation made before `config.json` before
-converting it. Hosted and self-hosted Sessions that relied on the retired options file
+Before converting, rename or remove only the names from before the Core key:
+`admin/sandbox-admin.key`, `admin/digests.json`, `AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE`
+and the retired `CORE_CONSOLE_*` settings. Leave `AGENTS_API_DAEMON_WS_URL`,
+`AGENTS_API_CONFIG_FILE` and `AGENTS_API_EXECUTION_OPTIONS_FILE` to `--convert`, which
+maps or reports them. Don't add `AGENTS_API_PUBLIC_URL` by hand: when it is present,
+conversion takes it as the address Core uses and skips the check against the sandbox
+deployment's Core address that keeps existing nodes bound. Hosted and self-hosted
+Sessions that relied on the retired options file
 have no model provider of their own and can't start new work after the upgrade. Count
 them before converting, from the new bundle:
 
@@ -240,17 +255,21 @@ added again.
 #### Node connections at /api/v1
 
 Core and its nodes must come from the same distribution; the node installer refuses a
-mismatched release. Nodes from releases that used the removed `/core/v1/sandbox/enroll`
-and `/core/v1/sandbox/node/*` paths can't connect to a current Core. For a Docker or
+mismatched release. Current releases serve every machine connection at `/api/v1`, and
+Web returns 404 there. When the new Core and Web go live, route `/api/v1/*`, including
+WebSocket upgrades, to Core instead of Web
+([HTTPS and the reverse proxy](install.md#https-and-the-reverse-proxy)); with the old
+routing, node enrollment and every Runtime connection fail, for Docker, microsandbox,
+E2B and self-hosted executors alike.
+
+Nodes from releases that used the removed `/core/v1/sandbox/enroll` and
+`/core/v1/sandbox/node/*` paths can't connect to a current Core. For a Docker or
 microsandbox deployment:
 
 1. Drain with the previous release while its nodes are connected: enter maintenance,
    archive retained hosted Sessions and wait until nothing is retained (the
    [maintenance procedure](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)).
-2. When the new Core and Web go live, route `/api/v1/*`, including WebSocket upgrades,
-   to Core instead of Web ([HTTPS and the reverse proxy](install.md#https-and-the-reverse-proxy)).
-   Web returns 404 for `/api/v1`; with the old routing, node enrollment and every Runtime
-   connection fail.
+2. Upgrade Core and Web, and change the routing as above.
 3. Save the new release's Runtime, resume, and add the nodes again. On each node host,
    stop the old node service and move its state directory aside as a backup first.
 
@@ -269,7 +288,8 @@ Artifacts remain. E2B deployments from that period are not covered.
 
 | Symptom | Cause and fix |
 | --- | --- |
-| `Run as a non-root user on Linux amd64 with Docker access` | Run `install.sh` as a normal user who can run `docker` |
+| `Run as a non-root user on Linux amd64 with Docker access` | Run `install.sh` as a normal user, on Linux amd64 |
+| `Installation failed; inspect prerequisites and private deployment files` | A prerequisite failed without its own message, most often Docker: check that `docker info` and `docker compose version` work for this user |
 | `Docker Compose 2.26.0 or newer is required …` | Update the Docker Compose plugin |
 | `Port N is already in use; select another port` | Free the port, or install with `--core-port`/`--web-port` |
 | `Installation directory is not empty …` | Use an empty `--install-dir` |
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 29fbceaf4..6e158d5c5 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -21,7 +21,7 @@ python3 -m venv .venv
 . .venv/bin/activate
 pip install openai==3.13.0
 export OPENAI_BASE_URL=https://core.example/v1
-export OPENAI_API_KEY=<project API key>
+read -rs OPENAI_API_KEY && export OPENAI_API_KEY   # paste the Project API key; it isn't echoed
 ```
 
 ```python
@@ -31,11 +31,13 @@ client = OpenAI()  # reads OPENAI_BASE_URL and OPENAI_API_KEY
 print(client.beta.agents.list().data)
 ```
 
-This read checks access; it runs no model and creates no sandbox. The same request
-with curl:
+`read -rs` keeps the key out of your shell history. This read checks access; it runs no
+model and creates no sandbox. The same request with curl, which keeps the key off its
+command line:
 
 ```sh
-curl "$OPENAI_BASE_URL/agents" -H "Authorization: Bearer $OPENAI_API_KEY" -H "OpenAI-Beta: agents=v1"
+curl "$OPENAI_BASE_URL/agents" -H "OpenAI-Beta: agents=v1" \
+  -H @<(printf 'Authorization: Bearer %s\n' "$OPENAI_API_KEY")
 ```
 
 All keys of a Project share its assets and execution principal; other Projects are
@@ -74,7 +76,7 @@ print(session.id)
 
 This makes a real model request and may incur charges. If the administrator set a
 default model for the harness, omit `x_agents_core.model_provider`; `agent.model` is
-still required. SDK 3.13.0 replaces an ordinary body field with the matching
+still required, so ask the administrator which model ID the default provider serves. SDK 3.13.0 replaces an ordinary body field with the matching
 `extra_body` field instead of merging nested fields, so keep the whole `agent` object
 in `extra_body`.
 
@@ -85,16 +87,16 @@ in `extra_body`.
 
 | Field | Where | Meaning |
 | --- | --- | --- |
-| `x_agents_core.harness` | A saved Agent, or the Session's inline `agent` | Which native harness runs the Agent: `codex`, `claude_sdk` or `mcode`. Omitted: the installation's default harness (`core.default_harness`, Codex unless changed) |
+| `x_agents_core.harness` | A saved Agent, or the Session's inline `agent` | Which native harness runs the Agent: `codex` (Codex), `claude_sdk` (Claude Code) or `mcode` (MiniMax Code). Omitted: the installation's default harness (`core.default_harness`, Codex unless changed) |
 | `x_agents_core.model_provider` | A saved Agent, or Session creation | The model provider bundle: `protocol`, HTTPS `base_url`, write-only `api_key`, and for `mcode` also `context_window` and `max_output_tokens`. Reads return `api_key_configured` instead of the key |
 
 The provider's protocol must match the harness:
 
 | Harness | `protocol` | Also required |
 | --- | --- | --- |
-| `codex` | `responses` | The provider's exact model ID in `agent.model` |
-| `claude_sdk` | `anthropic` | The provider's exact model ID |
-| `mcode` | `anthropic` | `context_window` and `max_output_tokens` |
+| Codex (`codex`) | `responses` | The provider's exact model ID in `agent.model` |
+| Claude Code (`claude_sdk`) | `anthropic` | The provider's exact model ID |
+| MiniMax Code (`mcode`) | `anthropic` | `context_window` and `max_output_tokens` |
 
 See [harness selection](../../contracts/agents-api/harness-selection.md) and
 [model execution](../../contracts/agents-api/model-execution.md) for the full contract.
@@ -114,7 +116,7 @@ never merged:
 | --- | --- | --- | --- |
 | `openai_hosted` | Used | Used | 400 `model_provider_required` |
 | `self_hosted` | Used | Never | 400 `model_provider_required` |
-| `none` | Rejected with 400 | Used | Allowed: the device's own environment supplies the model |
+| `none` | Rejected with 400 `unsupported_or_invalid_configuration` | Used | Allowed: the device's own environment supplies the model |
 
 A Session freezes its provider when it is created; later changes to the Agent or the
 default affect only new Sessions. Core encrypts the key with the Session and never
diff --git a/docs/getting-started/self-hosted.md b/docs/getting-started/self-hosted.md
index b5f08c768..d3aeb9e90 100644
--- a/docs/getting-started/self-hosted.md
+++ b/docs/getting-started/self-hosted.md
@@ -14,11 +14,13 @@ Agent API, the Core API or node enrollment.
 - **Core has an HTTPS public URL.** The Session's `remote_url` is
   `wss://<public host>/api/v1/agent-daemon/ws`, and the installer connects only over
   `wss://`. Web shows no command until Core has a reachable public URL.
-- **Web holds the Runtime files.** The installer downloads the Runtime launcher and
-  image from your console, as nodes do; install Core from the offline bundle.
-- **The host** runs Linux amd64 with Python 3.9+, `curl` and `sha256sum`, and Docker
-  usable by a non-root user through `/var/run/docker.sock`. It reaches the public URL
-  over HTTPS.
+- **Web holds the installer and the Runtime files.** The installer downloads the Runtime
+  launcher and image from the console's public address, as nodes do; install Core from
+  the offline bundle. A console without the self-hosted installer shows no
+  **Connect a host** section at all.
+- **The host** runs Linux amd64 with Python 3.9+, `curl`, `sha256sum` and the Docker
+  CLI, with Docker usable through `/var/run/docker.sock` by the non-root user that runs
+  the installer; the installer refuses root. It reaches the public URL over HTTPS.
 - **The Session carries its model provider**, in the request or saved on its Agent.
   Default models never apply to self-hosted Sessions, and creating one without a
   provider fails with 400 `model_provider_required`.
@@ -47,9 +49,9 @@ Agent API, the Core API or node enrollment.
    print(session.id, session.environment.id, session.environment.remote_url)
    ```
 
-2. **In Web**, open **Session log**, then the Session's page. Its
-   **Executor credentials** section shows **Connect a host** with the
-   **Executor install command**. Copy it and run it on the executor host:
+2. **In Web**, open **Session log**, then the Session's page. In its
+   **Executor credentials** section, **Connect a host** shows a command in a
+   **Terminal** block; copy it and run it on the executor host:
 
    ```sh
    (umask 077; d=$(mktemp -d) || exit; trap 'rm -rf "$d"' EXIT
@@ -60,18 +62,23 @@ Agent API, the Core API or node enrollment.
 
    The command contains no secret. It downloads the installer from your console and
    checks its SHA-256 before running it.
-3. **Issue the credential.** Select **Issue credential**, then **Copy credential**.
-   Web shows it once.
+3. **Issue the credential.** Select **Issue credential**. The **Executor credential**
+   dialog shows it once: choose **Copy credential**.
 4. **Paste it at the installer's hidden prompt** and press Enter. The prompt accepts the
-   compact or the pretty-printed credential and never echoes it.
+   compact or the pretty-printed credential and never echoes it. Then choose **Done** in
+   the dialog; after that the credential can't be shown again. Closing the dialog with
+   × keeps the credential on the page until you choose **Done**.
 
 The installer downloads the Runtime from the console and checks it, starts a container
 named `parsar-selfhost-<32 hex digits>`, and waits until Core confirms that the
-Environment is connected. The Session then runs its Turns there. The command is safe
-to rerun; it resumes the same installation.
-
-For automation without a terminal, choose **Download credential file**, make it private
-(`chmod 600`), and add `--credential-file /absolute/path/executor-key.json` to the
+Environment is connected. The Session then runs its Turns there. Rerunning the same
+command resumes the same installation. It refuses, with "This installation belongs to
+another Environment or distribution", once Core runs another release or its public URL
+changed: the host's installation is tied to both.
+
+For automation without a terminal, choose **Download credential file**, which saves
+`executor-credential-<first 8 characters of the environment ID>.json`, make it private
+(`chmod 600`), and add `--credential-file /absolute/path/to/that-file.json` to the
 installer line. The path must not go through a symbolic link.
 
 The host keeps its state in `~/.parsar/self-hosted/<environment-id>/`
@@ -107,19 +114,23 @@ To remove the Runtime instead, stop its container:
 `docker --host unix:///var/run/docker.sock stop <container>`. Deleting the Session does
 not remove containers or volumes on the executor host.
 
+In an archived project, Web shows "This project is archived, so executor credentials
+can't be issued or rotated." Only **Revoke** remains; a host that already holds a
+credential keeps it when you rerun the command.
+
 ## Without Web
 
 Scripts on the Core host can issue credentials with the Core key through Core's
-loopback port. Choose a new UUID for the credential and keep it:
+loopback port (`ports.core` in `config.json`, 8091 by default). Choose a new UUID for
+the credential and keep it:
 
 ```sh
-umask 077
-key_id=$(python3 -c 'import uuid; print(uuid.uuid4())')
-curl -fsS -X POST \
+key_id=$(python3 -c 'import uuid; print(uuid.uuid4())'); echo "credential ID: $key_id"
+(umask 077; curl -fsS -X POST \
   -H @<(printf 'Authorization: Bearer %s\n' "$(cat "$HOME/.parsar/core/secrets/core.key")") \
   -H 'Content-Type: application/json' -d "{\"key_id\":\"$key_id\"}" \
   "http://127.0.0.1:8091/core/v1/projects/$PROJECT_ID/environments/$ENVIRONMENT_ID/executor-credentials" \
-  -o executor-key.json
+  -o executor-key.json)
 ```
 
 Rotate with `{"key_id":"…","rotate":true}` on the same route; revoke with

From 41de66df5722c65409624f6497da6654cc4a2194 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Sat, 26 Sep 2026 06:31:10 +0000
Subject: [PATCH 7/7] Route node files through the Core address in a split
 deployment

Self-hosted executors download their installer from Core's public URL, but Web
serves /node-install/* only for its own name. The split deployment's Core host
now sends /node-install/* to the Web host with Host rewritten, restricts the
core-api name to the Web host, and has Caddy and nginx examples checked against the
console's Host check. The Web host needs the node files when the deployment has
nodes or executors.

Moving a self-hosted executor to a new release or public URL is stated as not
supported yet. The bundle docs build refuses a link that spans lines, since links
are read line by line, and handles an image inside link text. Long lines are
rewrapped, and placeholders use NODE_USER.
---
 README.md                                  |   9 +-
 docs/configuration.md                      |  44 +++----
 docs/getting-started/README.md             |  10 +-
 docs/getting-started/install.md            | 130 ++++++++++++++++++---
 docs/getting-started/nodes.md              |  36 +++---
 docs/getting-started/operations.md         |  16 +--
 docs/getting-started/quickstart.md         |   6 +-
 docs/getting-started/self-hosted.md        |  14 ++-
 docs/maintainers.md                        |   8 +-
 scripts/core-distribution-manifest.py      |  39 +++++--
 scripts/core-distribution-manifest.test.py |   5 +-
 11 files changed, 223 insertions(+), 94 deletions(-)

diff --git a/README.md b/README.md
index d37779a09..7a78ec9b7 100644
--- a/README.md
+++ b/README.md
@@ -24,10 +24,11 @@ administrator console that issues the keys applications call Core with.
    ./install.sh --public-url https://core.example
    ```
 
-   Put your HTTPS reverse proxy in front first, or install without `--public-url` for a
-   local trial and set it later. See the [installation guide](docs/getting-started/install.md).
-   Follow the docs inside the downloaded bundle (`docs/` and `README.md`): they match
-   its installer, while these pages describe the current source.
+   Put your HTTPS reverse proxy in front first, or install without `--public-url` for
+   a local trial and set it later. See the
+   [installation guide](docs/getting-started/install.md). If you're reading this on
+   GitHub, follow the docs inside the downloaded bundle (`README.md` and `docs/`)
+   instead: they match its installer, while GitHub shows the current source.
 2. **Sign in to Web with the Core key**, from `~/.parsar/core/secrets/core.key`. On
    **System**, set a default model; on **Projects and keys**, create a project and
    issue a key. See [Sign in to Web](docs/getting-started/install.md#sign-in-to-web).
diff --git a/docs/configuration.md b/docs/configuration.md
index a4418dd32..376f7e162 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -9,9 +9,10 @@ Every setting of a Core installation has exactly one home. There are two kinds:
 
 Web's **System** page shows both: the installation's addresses, the process settings
 read-only under **Startup settings** with the path of `config.json` and the apply
-command, the default models, and the sandbox configuration. Secrets live in [`secrets/`](#secrets-and-identity),
-one copy each. Each setting is set in one place; the files in `generated/` are only
-derived from `config.json`. No configuration file defines Projects or API keys.
+command, the default models, and the sandbox configuration. Secrets live in
+[`secrets/`](#secrets-and-identity), one copy each. Each setting is set in one place;
+the files in `generated/` are only derived from `config.json`. No configuration file
+defines Projects or API keys.
 
 ## Process settings: config.json
 
@@ -64,8 +65,10 @@ them and asks you to type the new URL (`--confirm-public-url-change URL` when no
 interactive). Afterwards, nodes on the old address get no new sandboxes: remove them
 in Web and add them again. Existing sandboxes and executors keep working only while
 the old address still reaches this Core, and `apply` warns that self-hosted executors
-must restart with the new `remote_url`; their installer refuses to reuse an
-installation made for the old address. Update your reverse proxy first.
+must restart with the new `remote_url`. Their installer refuses to reuse an
+installation made for the old address, and moving an executor isn't supported yet:
+create new self-hosted Sessions and connect their hosts again. Update your reverse
+proxy first.
 
 ### Settings
 
@@ -109,9 +112,10 @@ output or in Core's settings snapshot. Model providers are not process settings;
 | `core.runtime_history.sample_interval_seconds` | integer | none | `all`, `core-only` | `parsar apply` | core | Periodic sampling interval in seconds. |
 <!-- END config-reference -->
 
-The schema is [`deploy/install/config.schema.json`](../deploy/install/config.schema.json);
-each installation keeps a copy in `generated/config.schema.json` for editors. Core
-serves the non-secret settings snapshot, with the path of `config.json` and the apply
+The schema is
+[`deploy/install/config.schema.json`](../deploy/install/config.schema.json); each
+installation keeps a copy in `generated/config.schema.json` for editors. Core serves
+the non-secret settings snapshot, with the path of `config.json` and the apply
 command, at `GET /core/v1/installation`.
 
 ## Runtime settings: Web
@@ -163,13 +167,13 @@ and the [deployment contract](../contracts/agents-api/sandbox-deployment.md).
 
 ### Node capacity
 
-Core approves a node's capacity when you generate its Add node command: **Sandboxes
-at once** (`max_active`, default 2) and, for microsandbox only, **Retained sandboxes**
+Core approves a node's capacity when you generate its Add node command: **Sandboxes at
+once** (`max_active`, default 2) and, for microsandbox only, **Retained sandboxes**
 (`max_retained`, default 8), with `max_retained >= max_active >= 1`. Docker never
 suspends sandboxes, so Web doesn't ask for it and Core keeps `max_retained` equal to
-`max_active`. Change them later with **Edit node**. Reservations and cleanup that is not
-confirmed count against capacity; lowering a limit stops no running sandbox. A node's own files can't change its
-capacity, size or Runtime.
+`max_active`. Change them later with **Edit node**. Reservations and cleanup that is
+not confirmed count against capacity; lowering a limit stops no running sandbox. A
+node's own files can't change its capacity, size or Runtime.
 
 `core.execution_concurrency` is unrelated: it limits concurrent execution work in Core.
 
@@ -232,13 +236,13 @@ node payload (the installer's `node-payload/`). Without it, Add node and the
 self-hosted install command are unavailable.
 
 Core fails at startup, naming the replacement, while a retired variable is set:
-`AGENTS_API_DAEMON_WS_URL` (use `AGENTS_API_PUBLIC_URL`), `AGENTS_API_CONFIG_FILE`
-(no replacement), `AGENTS_API_EXECUTION_OPTIONS_FILE` (use
+`AGENTS_API_DAEMON_WS_URL` (use `AGENTS_API_PUBLIC_URL`), `AGENTS_API_CONFIG_FILE` (no
+replacement), `AGENTS_API_EXECUTION_OPTIONS_FILE` (use
 [default models](#default-models)), `AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE` (use
 `AGENTS_API_CORE_KEY_DIGESTS_FILE`), and `AGENTS_API_MANAGED_RUNTIMES_FILE`,
 `AGENTS_API_SANDBOX_NODE_STATE_DIR` and `AGENTS_API_SANDBOX_NODE_CORE_URL` (the
-sandbox deployment lives in the database and nodes enroll separately). Core logs the file paths it loads, never
-environment values or file contents. Native installation paths must be canonical
-absolute paths without control characters, quotes, backslashes or wildcards. Keep the
-installation ID and the database together; Core refuses a missing installation ID
-when its database already has a deployment.
+sandbox deployment lives in the database and nodes enroll separately). Core logs the
+file paths it loads, never environment values or file contents. Native installation
+paths must be canonical absolute paths without control characters, quotes, backslashes
+or wildcards. Keep the installation ID and the database together; Core refuses a
+missing installation ID when its database already has a deployment.
diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md
index 69463ea6a..244b4259b 100644
--- a/docs/getting-started/README.md
+++ b/docs/getting-started/README.md
@@ -15,7 +15,9 @@ applications call Core with.
 | [Call the API](quickstart.md) | Application developers | `OPENAI_BASE_URL` and `OPENAI_API_KEY`, running a Session, model providers and `x_agents_core` |
 | [API reference](../api/README.md) | Developers | The `/v1`, `/core/v1` and `/api/v1` namespaces and their contracts |
 
-Deeper references: [nodes and sandbox backends](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md)
-for operators, [protocol coverage and native differences](../../contracts/agents-api/README.md),
-and [maintainers and advanced deployments](../maintainers.md) for building
-distributions and running Core without the installer.
+Deeper references: the
+[nodes and sandbox backends](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md)
+reference for operators, the
+[protocol coverage and native differences](../../contracts/agents-api/README.md), and
+[maintainers and advanced deployments](../maintainers.md) for building distributions
+and running Core without the installer.
diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index 1a5f9071c..bb48e6d62 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -22,7 +22,8 @@ under `docs/`; if you install an older bundle, follow those.
 - Linux amd64 with Python 3.9 or newer.
 - Docker Engine with Docker Compose 2.26.0 or newer (`docker compose version`).
 - A non-root user who can run `docker`. The installer refuses root.
-- Free loopback ports 8091 (Core) and 8080 (Web), or [other ports](#ports-and-directory).
+- Free loopback ports 8091 (Core) and 8080 (Web), or
+  [other ports](#ports-and-directory).
 - The GitHub CLI, `gh`, to download the bundle.
 
 The Core host needs no KVM and no systemd user services, unless you choose
@@ -66,7 +67,7 @@ Each release has two bundles:
 | Bundle | Contains | Use it for |
 | --- | --- | --- |
 | `parsar-core-<commit>-linux-amd64-offline.tar.gz` | Core, Web and PostgreSQL images, the installers and every node and Runtime file | Any installation. Web serves the node files to your nodes and self-hosted executors |
-| `parsar-core-<commit>-linux-amd64.tar.gz` | The same without the node and Runtime files | E2B-only or Web-only hosts. Web can't add nodes until the files are present |
+| `parsar-core-<commit>-linux-amd64.tar.gz` | The same without the node and Runtime files | Core-only hosts, and installations that use only E2B. Web can't add nodes or connect self-hosted executors until the files are present |
 
 To add the node files to the smaller bundle, create an `artifacts/` directory in the
 extracted bundle, download the release's other `parsar-core-<commit>-linux-amd64-*`
@@ -149,8 +150,9 @@ it installs anything:
   --e2b-api-key-file "$HOME/.parsar/e2b-api-key" --e2b-template '<template-id>:<build-uuid>'
 ```
 
-Prepare the template build with the [E2B guide](../../services/agents-api/deploy/e2b/README.md).
-To change the backend or the sandbox size later, use the Nodes page in Web; see
+Prepare the template build with the
+[E2B guide](../../services/agents-api/deploy/e2b/README.md). To change the backend or
+the sandbox size later, use the Nodes page in Web; see
 [Nodes](nodes.md#change-the-sandbox-backend-or-size).
 
 #### Modes
@@ -162,20 +164,22 @@ To change the backend or the sandbox size later, use the Nodes page in Web; see
 | `--web-only` | Web | A second host for the console, paired with an existing Core |
 
 A Web-only console forwards every signed-in `/core/v1` request to its Core with the
-Core key, so `--core-url` must reach Core's `/core/v1` directly. The usual reverse proxy
-sends `/core/v1` to Web, so the Core's public URL doesn't work here:
+Core key, so `--core-url` must reach Core's `/core/v1` directly. The default reverse
+proxy sends `/core/v1` to Web, so the Core's public URL doesn't work here:
 
-- **Web on the Core host:** use Core's loopback port, `--core-url http://127.0.0.1:8091`.
+- **Web on the Core host:** use Core's loopback port,
+  `--core-url http://127.0.0.1:8091`.
 - **Web on another host:** give Core a second HTTPS name whose proxy sends every path to
   Core, such as `https://core-api.example` to `127.0.0.1:8091` on the Core host, and use
-  it as `--core-url`. Anyone who reaches that name still needs the Core key.
+  it as `--core-url`. Allow only the Web host's address on that name; anyone else who
+  reaches it still needs the Core key.
 
-A split deployment then looks like this:
+##### Split deployment
 
 | Host | Install | Reverse proxy |
 | --- | --- | --- |
-| Core | `./install.sh --core-only --public-url https://core.example` | `core.example`: `/v1`, `/v1/*` and `/api/v1/*` to Core (there is no Web here). `core-api.example`: every path to Core |
-| Web | See below | `console.example`: every path to Web |
+| Core | `./install.sh --core-only --public-url https://core.example` | `core.example`: `/v1`, `/v1/*` and `/api/v1/*` to Core; `/node-install/*` to the Web host, with Host rewritten to `console.example`; nothing else. `core-api.example`: every path to Core, for the Web host's address only |
+| Web | `./install.sh --web-only …`, below | `console.example`: every path to Web |
 
 ```sh
 ./install.sh --web-only --install-dir "$HOME/.parsar/core-console" \
@@ -184,11 +188,100 @@ A split deployment then looks like this:
   --core-key-file "$HOME/core.key"
 ```
 
-The Web host's `--public-url` is the address browsers use for this console; nodes also
-download their installer from it. Applications, nodes and sandboxes use the Core
-host's public URL. Copy the key file from the Core host's `secrets/core.key` with mode
-`0600`; the installer keeps its own copy in `secrets/core.key`, so delete
-`$HOME/core.key` afterwards. After the Core key is rotated, copy the new key again; see
+Browsers use `console.example`, and nodes download their installer from it.
+Applications, nodes and sandboxes call Core at `core.example`, and self-hosted
+executors download their installer from there too, which is why `core.example` sends
+`/node-install/*` to the Web host. Web serves those files only for its own name, so the
+proxy rewrites Host. The Web host serves every node and executor file, so install it
+from the offline bundle (or add `artifacts/`) when the deployment has nodes or
+self-hosted executors.
+
+Caddy on the Core host, where `203.0.113.10` stands for the Web host's address:
+
+```caddyfile
+core.example {
+	@core path /v1 /v1/* /api/v1/*
+	handle @core {
+		reverse_proxy 127.0.0.1:8091
+	}
+	handle /node-install/* {
+		reverse_proxy https://console.example {
+			header_up Host console.example
+		}
+	}
+	handle {
+		respond 404
+	}
+}
+
+core-api.example {
+	@web remote_ip 203.0.113.10
+	handle @web {
+		reverse_proxy 127.0.0.1:8091
+	}
+	handle {
+		respond 403
+	}
+}
+```
+
+nginx on the Core host, with the `map` from the
+[main example](#https-and-the-reverse-proxy):
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name core.example;
+    ssl_certificate     /etc/letsencrypt/live/core.example/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/core.example/privkey.pem;
+
+    client_max_body_size 0;
+    proxy_http_version 1.1;
+    proxy_set_header Host $http_host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_buffering off;
+    proxy_request_buffering off;
+    proxy_read_timeout 1h;
+    proxy_send_timeout 1h;
+
+    location = /v1    { proxy_pass http://127.0.0.1:8091; }
+    location /v1/     { proxy_pass http://127.0.0.1:8091; }
+    location /api/v1/ { proxy_pass http://127.0.0.1:8091; }
+    location /node-install/ {
+        proxy_pass https://console.example;
+        proxy_set_header Host console.example;   # Web serves node files only for its own name
+        proxy_ssl_server_name on;
+        proxy_ssl_name console.example;
+        proxy_ssl_verify on;
+        proxy_ssl_verify_depth 2;
+        proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
+    }
+    location / { return 404; }
+}
+
+server {
+    listen 443 ssl;
+    server_name core-api.example;
+    ssl_certificate     /etc/letsencrypt/live/core-api.example/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/core-api.example/privkey.pem;
+
+    allow 203.0.113.10;                        # the Web host
+    deny all;
+    client_max_body_size 0;
+    proxy_http_version 1.1;
+    proxy_buffering off;
+    proxy_read_timeout 1h;
+    location / { proxy_pass http://127.0.0.1:8091; }
+}
+```
+
+The Web host's proxy sends every path to Web, for example
+`console.example { reverse_proxy 127.0.0.1:8080 }` in Caddy.
+
+Copy the key file from the Core host's `secrets/core.key` with mode `0600`; the
+installer keeps its own copy in `secrets/core.key`, so delete `$HOME/core.key`
+afterwards. After the Core key is rotated, copy the new key again; see
 [Rotate the Core key](operations.md#rotate-the-core-key). A Web-only install selects no
 sandbox backend: the Core host's `--sandbox` does, or later the paired console's
 **Nodes** page.
@@ -200,7 +293,7 @@ new directory.
 
 `--native-core` runs Core as a systemd user service of the installing user;
 PostgreSQL and Web stay in containers. It needs a running systemd user manager and
-lingering for that user (`sudo loginctl enable-linger <user>`), and the bundle's
+lingering for that user (`sudo loginctl enable-linger "$USER"`), and the bundle's
 native binaries must load on the host. PostgreSQL then listens on a loopback port
 the installer picks (`ports.database`), and Web uses the host network. Native Core
 needs no KVM and is unrelated to the sandbox backend.
@@ -215,7 +308,8 @@ own database, Core key and nodes.
 
 ## HTTPS and the reverse proxy
 
-Core and Web share one public origin. Your reverse proxy terminates TLS and routes by
+By default, Core and Web share one public origin; for Web on its own host, see the
+[split deployment](#split-deployment). Your reverse proxy terminates TLS and routes by
 path:
 
 | Path | Goes to | Callers |
diff --git a/docs/getting-started/nodes.md b/docs/getting-started/nodes.md
index 3a4089895..7ba194645 100644
--- a/docs/getting-started/nodes.md
+++ b/docs/getting-started/nodes.md
@@ -14,14 +14,17 @@ node protocol, manual registration, placement and failure handling.
 
 - **Core has an HTTPS public URL** that the host and its sandboxes can reach: each
   sandbox calls Core at `public_url`. A loopback installation can't have nodes, and
-  Web says so at Add node. See [HTTPS and the reverse proxy](install.md#https-and-the-reverse-proxy).
+  Web says so at Add node. See
+  [HTTPS and the reverse proxy](install.md#https-and-the-reverse-proxy).
 - **Web holds the node files.** Install from the offline bundle, or add the release's
-  node files to the smaller bundle; see [Download a release](install.md#download-a-release).
-  Otherwise Add node says that the console has no node files for the provider.
+  node files to the smaller bundle; see
+  [Download a release](install.md#download-a-release). Otherwise Add node says that
+  the console has no node files for the provider.
 - **A sandbox backend is chosen.** The installer selects Docker unless you chose
   otherwise. After `--sandbox none`, the **Nodes** page first asks you to choose
-  **Own machines**, Docker or microsandbox, and a sandbox size, then
-  **Save configuration**. Every node of a deployment uses that provider.
+  **Own machines**, then microsandbox (preselected as recommended) or Docker, which it
+  asks you to confirm, and a sandbox size, then **Save configuration**. Every node of a
+  deployment uses that provider.
 
 ## Add a node
 
@@ -35,8 +38,7 @@ node protocol, manual registration, placement and failure handling.
    **Generate new command** when it expires.
 4. Run it on the host. Web follows the node from registered to connected to ready.
 
-The command downloads the node installer from the console's public address, checks
-its SHA-256, and
+The command downloads the node installer from your console, checks its SHA-256, and
 runs it with a one-time enrollment token. The installer downloads the node files from
 the same console and checks each against the release manifest, imports the Runtime
 image, registers the node, starts its service and waits until Core reports the node
@@ -125,9 +127,10 @@ Docker group makes this user root-equivalent on the host too.
 | Docker | The Runtime image, imported once, and a network `parsar-node-<installation-id>` |
 
 Root only prepares the account, the group and the unit; everything else, the Docker
-network included, runs as `parsar-node`, in its own session without a terminal. The installer never installs
-Docker, KVM or packages, never starts Docker, never changes device permissions,
-sudoers, firewall or SELinux settings, and never touches other accounts.
+network included, runs as `parsar-node`, in its own session without a terminal. The
+installer never installs Docker, KVM or packages, never starts Docker, never changes
+device permissions, sudoers, firewall or SELinux settings, and never touches other
+accounts.
 
 **Docker mode is root-equivalent.** Membership in the `docker` group lets
 `parsar-node`, and so anything that controls the node, act as root on the host. This
@@ -178,11 +181,12 @@ The installation ID is in the command (`--installation-id`) and on the **System*
 
 ## Remove a node
 
-1. In Web, open **Nodes** and choose **Remove node** on the node's page, or **Remove**
-   in its list row, then **Confirm removal**. Core refuses
-   while the node still holds sandboxes, snapshots or pending cleanup; let them finish,
-   or [archive their Sessions](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
-   through the Core API. Removal is permanent: the host can come back only as a new node.
+1. In Web, open **Nodes** and choose **Remove node** on the node's page, or
+   **Remove** in its list row, then **Confirm removal**. Core refuses while the node
+   still holds sandboxes, snapshots or pending cleanup; let them finish, or
+   [archive their Sessions](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance)
+   through the Core API. Removal is permanent: the host can come back only as a new
+   node.
 2. Web then shows **Clean up the host** with the uninstall command. Run it on the host:
 
    ```sh
@@ -254,7 +258,7 @@ WebSocket doesn't pass the reverse proxy.
 | This host has N CPUs and M MiB of memory; each sandbox needs … | Use a larger host, or change the sandbox size |
 | SELinux is enforcing on this host | Use the no-sudo command as a prepared user |
 | This host already runs a sudo-mode node for another Core | One host serves one Core in sudo mode. Remove that node and uninstall it first |
-| Ask the host administrator to enable user lingering, or No systemd user manager is running | No-sudo mode: `sudo loginctl enable-linger <user>`, or use sudo |
+| Ask the host administrator to enable user lingering, or No systemd user manager is running | No-sudo mode: `sudo loginctl enable-linger NODE_USER`, or use sudo |
 | Core still lists this node | Remove it on the Nodes page first |
 
 ## Change the sandbox backend or size
diff --git a/docs/getting-started/operations.md b/docs/getting-started/operations.md
index 7adb95f20..cf9738a1b 100644
--- a/docs/getting-started/operations.md
+++ b/docs/getting-started/operations.md
@@ -191,11 +191,12 @@ docker compose -f "$HOME/.parsar/core/compose.json" exec -T database \
 
 Conversion reads the old files without changing anything, shows the resulting settings
 and the same backup command, and asks for confirmation. `--yes` skips the prompt and
-runs the migrations at once, so use it only after backing up. It then writes `config.json` and `state.json`, moves the secrets
-into `secrets/` without copying them, removes the old generated files, and starts the
-new release with the same Compose project, database and installation ID. Settings set
-by hand, such as `AGENTS_API_EXECUTION_CONCURRENCY`, `PARSAR_LOG_*` or a Runtime history
-file, move into `config.json`.
+runs the migrations at once, so use it only after backing up. It then writes
+`config.json` and `state.json`, moves the secrets into `secrets/` without copying
+them, removes the old generated files, and starts the new release with the same
+Compose project, database and installation ID. Settings set by hand, such as
+`AGENTS_API_EXECUTION_CONCURRENCY`, `PARSAR_LOG_*` or a Runtime history file, move
+into `config.json`.
 
 It stops before changing anything, listing each reason, when something can't be
 converted: an edited `compose.json`, an unknown or edited generated value in
@@ -338,5 +339,6 @@ Core records which key made each public resource write, for the console. Set
 `2160h`) to control how long non-creation history is kept; creation ownership is kept
 for good. Removing keys or resources does not delete these records. See the
 [query contract](../../contracts/agents-api/write-audit.md); administrator mutations
-have a separate [audit log](../../contracts/agents-api/admin-api.md#monitoring-and-audit).
-Neither logs bodies or secrets.
+have a separate
+[audit log](../../contracts/agents-api/admin-api.md#monitoring-and-audit). Neither
+logs bodies or secrets.
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 6e158d5c5..a907f8787 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -76,9 +76,9 @@ print(session.id)
 
 This makes a real model request and may incur charges. If the administrator set a
 default model for the harness, omit `x_agents_core.model_provider`; `agent.model` is
-still required, so ask the administrator which model ID the default provider serves. SDK 3.13.0 replaces an ordinary body field with the matching
-`extra_body` field instead of merging nested fields, so keep the whole `agent` object
-in `extra_body`.
+still required, so ask the administrator which model ID the default provider serves.
+SDK 3.13.0 replaces an ordinary body field with the matching `extra_body` field
+instead of merging nested fields, so keep the whole `agent` object in `extra_body`.
 
 ## Core extensions: x_agents_core
 
diff --git a/docs/getting-started/self-hosted.md b/docs/getting-started/self-hosted.md
index d3aeb9e90..4e73db89b 100644
--- a/docs/getting-started/self-hosted.md
+++ b/docs/getting-started/self-hosted.md
@@ -14,10 +14,11 @@ Agent API, the Core API or node enrollment.
 - **Core has an HTTPS public URL.** The Session's `remote_url` is
   `wss://<public host>/api/v1/agent-daemon/ws`, and the installer connects only over
   `wss://`. Web shows no command until Core has a reachable public URL.
-- **Web holds the installer and the Runtime files.** The installer downloads the Runtime
-  launcher and image from the console's public address, as nodes do; install Core from
-  the offline bundle. A console without the self-hosted installer shows no
-  **Connect a host** section at all.
+- **Web holds the installer and the Runtime files.** The command downloads the
+  installer, the Runtime launcher and the image from Core's public URL, which the
+  reverse proxy sends to Web (in a [split deployment](install.md#split-deployment), to
+  the Web host); install from the offline bundle. A console without the self-hosted
+  installer shows no **Connect a host** section at all.
 - **The host** runs Linux amd64 with Python 3.9+, `curl`, `sha256sum` and the Docker
   CLI, with Docker usable through `/var/run/docker.sock` by the non-root user that runs
   the installer; the installer refuses root. It reaches the public URL over HTTPS.
@@ -74,7 +75,10 @@ named `parsar-selfhost-<32 hex digits>`, and waits until Core confirms that the
 Environment is connected. The Session then runs its Turns there. Rerunning the same
 command resumes the same installation. It refuses, with "This installation belongs to
 another Environment or distribution", once Core runs another release or its public URL
-changed: the host's installation is tied to both.
+changed: the host's installation is tied to both. Moving an executor to a new release
+or address isn't supported yet. A fresh installation would start a new container
+without the old workspace and native history, so the Session can't continue there:
+stop the old container, create a new self-hosted Session and connect a host for it.
 
 For automation without a terminal, choose **Download credential file**, which saves
 `executor-credential-<first 8 characters of the environment ID>.json`, make it private
diff --git a/docs/maintainers.md b/docs/maintainers.md
index 724cd9082..a3561da69 100644
--- a/docs/maintainers.md
+++ b/docs/maintainers.md
@@ -1,8 +1,8 @@
 # Maintainers and advanced deployments
 
 This page is for people who build and publish Parsar Core, or run Core without the
-installer. To install Core and Web, use the [installation guide](getting-started/install.md)
-instead.
+installer. To install Core and Web, use the
+[installation guide](getting-started/install.md) instead.
 
 ## Build a distribution
 
@@ -63,8 +63,8 @@ They are for development, testing and operators who manage Core's process themse
 They are not an installation path for new users.
 
 - [Standalone Core archive](../services/agents-api/RELEASE.md)
-  (`make build-agents-api-release`): Core, its migrator and operator commands for your own
-  PostgreSQL.
+  (`make build-agents-api-release`): Core, its migrator and operator commands for your
+  own PostgreSQL.
 - [Standalone container](../services/agents-api/CONTAINER.md)
   (`make docker-build-agents-api`): the same in a Linux container image.
 - [Service guide](../services/agents-api/README.md): building and running Core from
diff --git a/scripts/core-distribution-manifest.py b/scripts/core-distribution-manifest.py
index 9b44c4fc4..25fcc8781 100644
--- a/scripts/core-distribution-manifest.py
+++ b/scripts/core-distribution-manifest.py
@@ -424,19 +424,31 @@ def heading_anchors(text):
     return found
 
 
+def rewrite_line(line, rewrite):
+    """Apply rewrite(image, target) to each link of one line, and to an image inside link text."""
+    pieces, position = [], 0
+    for match in links(line):
+        pieces.append(line[position:match.start()])
+        text = rewrite_line(match.group(2), rewrite)
+        pieces.append(f"{match.group(1)}[{text}]({rewrite(bool(match.group(1)), match.group(3))}{match.group(4)})")
+        position = match.end()
+    return "".join(pieces) + line[position:]
+
+
 def rewrite_links(text, rewrite):
     """Apply rewrite(image, target) to every Markdown link outside code blocks and code spans."""
-    lines = []
-    for line, code in markdown_lines(text):
-        if not code:
-            pieces, position = [], 0
-            for match in links(line):
-                pieces.append(line[position:match.start()])
-                pieces.append(f"{match.group(1)}[{match.group(2)}]({rewrite(bool(match.group(1)), match.group(3))}{match.group(4)})")
-                position = match.end()
-            line = "".join(pieces) + line[position:]
-        lines.append(line)
-    return "\n".join(lines)
+    return "\n".join(line if code else rewrite_line(line, rewrite) for line, code in markdown_lines(text))
+
+
+def split_links(text):
+    """Line numbers where a link starts on one line and ends on the next; links are read line by line."""
+    lines, found = list(markdown_lines(text)), []
+    for number, ((first, first_code), (second, second_code)) in enumerate(zip(lines, lines[1:]), 1):
+        if not (first_code or second_code or not second.strip()):
+            joined = first + " " + second.lstrip()
+            if any(match.start() < len(first) < match.end() for match in links(joined)):
+                found.append(number)
+    return found
 
 
 def docs(source, bundle, revision, names=BUNDLED_DOCS, files=BUNDLED_FILES):
@@ -477,7 +489,10 @@ def rewrite(image, link):
         return rewrite
 
     for name in names:
-        text = rewrite_links((source / name).read_text(encoding="utf-8"), versioned(name))
+        original = (source / name).read_text(encoding="utf-8")
+        for number in split_links(original):
+            raise ValueError(f"{name}:{number}: keep each link on one line")
+        text = rewrite_links(original, versioned(name))
         target = bundle / name
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_text(text.replace("@SOURCE_REVISION@", revision), encoding="utf-8")
diff --git a/scripts/core-distribution-manifest.test.py b/scripts/core-distribution-manifest.test.py
index 619f2e3b0..3bb985b1b 100644
--- a/scripts/core-distribution-manifest.test.py
+++ b/scripts/core-distribution-manifest.test.py
@@ -260,6 +260,7 @@ def setUp(self):
             "README.md": "# Title\n\n![Banner](docs/banner.png) ![Chart](docs/chart.png)\n"
                          "[Install](docs/install.md#sign-in-to-web), [API](contracts/api.md#routes), [web](docs/web), "
                          "`[kept](missing.md)`, [`schema.json`](contracts/schema.json), "
+                         "[![Chart](docs/chart.png)](contracts/api.md), "
                          "[main](https://github.com/MiniMax-AI/parsar-core/blob/main/LICENSE)\n"
                          "```sh\n[not a link](missing.md)\n```\n\n    [indented code](missing.md)\n",
             "docs/install.md": "# Install\n## Sign in to Web\n## C#\n## _Emphasis_ and snake_case\n"
@@ -285,6 +286,7 @@ def test_links_leaving_the_bundle_point_at_the_revision(self):
             "[Install](docs/install.md#sign-in-to-web), [API](" + versioned.format("blob") + "contracts/api.md#routes), "
             "[web](" + versioned.format("tree") + "docs/web), `[kept](missing.md)`, "
             "[`schema.json`](" + versioned.format("blob") + "contracts/schema.json), "
+            "[![Chart](" + versioned.format("raw") + "docs/chart.png)](" + versioned.format("blob") + "contracts/api.md), "
             "[main](" + versioned.format("blob") + "LICENSE)\n```sh\n[not a link](missing.md)\n```\n\n"
             "    [indented code](missing.md)\n"))
         self.assertEqual((self.bundle / "docs/install.md").read_text(), (self.source / "docs/install.md").read_text())
@@ -293,7 +295,8 @@ def test_links_leaving_the_bundle_point_at_the_revision(self):
 
     def test_broken_links_and_anchors_fail_the_build(self):
         for text in ("[x](missing.md)", "[x](docs/install.md#no-such-heading)", "[x](../outside.md)", "[x](#nowhere)",
-                     "[`code text`](missing.md)", "See [`a`](docs/install.md#gone) and more"):
+                     "[`code text`](missing.md)", "See [`a`](docs/install.md#gone) and more",
+                     "[![inner](missing.png)](docs/install.md)", "A [link that\nspans lines](docs/install.md)"):
             with self.subTest(text=text):
                 (self.source / "README.md").write_text("# Title\n" + text + "\n")
                 with self.assertRaises(ValueError):