Polish the Parsar Core landing and onboarding documentation

README.md

@@ -1,18 +1,15 @@
-# OpenAgentCore
-
-![OpenAgentCore: One core. Many agents. Open infrastructure for AI agents.](docs/assets/openagentcore-banner.png)
+# Parsar Core
 
 **Open-source Agents API infrastructure, with your choice of native harness.**
 
-Run Codex, Claude Code and MiniMax Code behind one execution API. OpenAgentCore
+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.
 
 Core and its Web console ship together. The default installation runs Core, Web
-and PostgreSQL with zero execution nodes. A local sandbox provider is optional:
-enable microsandbox or Docker explicitly when installing. With a provider enabled,
-Core creates each required sandbox from the colocated Runtime image. Model
+and PostgreSQL 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.
 
 Hosted deployments use one selected provider across local or remote nodes. The
@@ -22,19 +19,46 @@ existing Sessions retain their node across disconnects and resume.
 
 ## Start here
 
-- [Install Core and Web](docs/getting-started/install.md)
+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:
+
+   ```sh
+   ./install.sh --public-url https://core.example
+   ```
+
+   This starts Core, Web and PostgreSQL with zero execution nodes. Public release
+   bundles are not published yet; see the [installation guide](docs/getting-started/install.md)
+   for building a bundle and the host/network prerequisites.
+2. **Sign in to Web.** Open the console address printed by the installer. Use
+   `admin` and the password in `~/.parsar/core/config/console.password`.
+   The paired console needs no additional API key setup.
+3. **Add a node.** Open **Hosted Sandbox Manager**, choose Docker or microsandbox,
+   and initialize the deployment. The paired console address is used by default;
+   advanced network settings allow a different reachable HTTPS origin. Select
+   **Add node**, then copy and run the command on a prepared Linux host. Web shows when the node is online
+   and its provider is ready. All nodes in a deployment use the same provider.
+
+Installation and node enrollment do not call a model. Once a node is ready,
+run an optional API example with your own model credentials.
+
 - [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)
 
-After verifying and extracting a matching Linux amd64 distribution:
+### 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; the installer does not change an existing installation's public URL.
+Installing a local provider is optional, and is not required for adding nodes in Web.
 
 ```sh
-./install.sh                    # Core + Web + PostgreSQL, no sandbox provider
-./install.sh --core-only        # Core + PostgreSQL, no sandbox provider
+./install.sh                    # Core + Web + PostgreSQL, loopback access, zero nodes
+./install.sh --core-only        # Core + PostgreSQL, zero nodes
 ./install.sh --sandbox-provider true --provider microsandbox
 ./install.sh --sandbox-provider true --provider docker
 ```

docs/getting-started/install.md

@@ -3,45 +3,45 @@
 Install one matching Parsar Core distribution. By default it starts PostgreSQL,
 Core and the existing Web console in containers, with zero execution nodes.
 It does not import Runtime images, mount the Docker socket or host devices into
-Core, or generate a managed Provider configuration. A local sandbox provider is
-an explicit installation option.
+Core, or generate a managed Provider configuration. Add nodes through Web after
+installation. A local sandbox provider is an optional installation choice.
 No model key, Environment wizard or sample task is required during installation.
 
+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 v2. Run the installer as a non-root user who can use Docker.
 The default installation requires neither KVM nor systemd user services.
-Optional microsandbox also requires glibc, a running systemd user manager with
-linger enabled, and user read/write access to `/dev/kvm`. Nested cloud hosts must
-expose hardware virtualization. With this option, Core runs as a native user
-service so restarting it does not terminate the Provider's microVM processes.
-The installer checks these
-prerequisites; it does not grant host permissions or silently fall back to Docker.
-The optional Docker sandbox provider keeps Core in Compose and requires neither
-KVM nor systemd user services.
-
-For optional microsandbox, reserve capacity for the native Runtime: its initial
-profile uses
-4 GiB RAM, 2 CPUs, an 8 GiB root disk and an 8 GiB environment disk per active sandbox, with at most 4 active
-and 16 retained allocations. Limits are operator configuration, not model input.
-Use a trusted, single-operator host and durable local storage. The installer does
-not change host virtualization settings, install Docker, create an OS user or
-expose a remote administration service.
+The optional local provider has additional requirements described under
+[installation choices](#installation-choices). Node-host requirements are listed
+in the [add-node steps](#add-nodes-after-a-default-installation).
 
 ## Verify, extract and install
 
 Obtain the archive and checksum from a trusted distributor. Until a release is
-published, build an archive using [Build a distribution](#build-a-distribution);
+published, obtain a verified bundle from your deployment administrator or build
+an archive using [Build a distribution](#build-a-distribution);
 a source checkout alone is not an installable binary bundle. Do not substitute an
 unpublished download URL.
 
+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. It does not change an existing installation's public URL.
+The command below still installs zero execution nodes.
+
 ```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
+./install.sh --public-url https://core.example
 ```
 
 The bundle contains the same-revision native Core binaries and service image,
@@ -53,12 +53,22 @@ microsandbox payloads are used only when a sandbox provider is enabled.
 The matched `parsar-sandbox-node` executable is included in the native payload
 and Core service image; packaging it does not start or register a node.
 
+## Sign in to Web
+
 Installation creates private configuration under `~/.parsar/core`, a dedicated
 PostgreSQL volume, an API caller key and a credential encryption key. It also
-creates a separate console password and deployment administrator key. Secret values are not printed. On success:
+creates a separate console password and deployment administrator key. Secret values
+are not printed.
+
+Open the console address printed by the installer (`https://core.example` in
+the example above). Sign in as `admin` using the password in
+`~/.parsar/core/config/console.password`. The bundled console is already connected
+to Core; you do not need to paste an API key.
+
+Default local ports and private files:
 
 - API: `http://127.0.0.1:8091/v1`
-- Web console: `http://127.0.0.1:8080`, username `admin`
+- Web upstream: `http://127.0.0.1:8080`; use the configured public URL in your browser
 - Console password file: `~/.parsar/core/config/console.password`
 - API caller key file: `~/.parsar/core/config/caller.key`
 - Sandbox administrator key file: `~/.parsar/core/admin/sandbox-admin.key`
@@ -67,31 +77,6 @@ Use exactly the displayed console address; the production proxy validates its
 configured browser origin. The console password authenticates to the Web server;
 the server holds the independent Core key. Model keys remain API execution input.
 
-## Installation choices
-
-```sh
-./install.sh --sandbox-provider true --provider microsandbox
-./install.sh --sandbox-provider true --provider docker
-./install.sh --core-only
-./install.sh --core-only --sandbox-provider true --provider docker
-```
-
-`--sandbox-provider true` enables a local sandbox provider. If `--provider` is
-omitted, it selects microsandbox. Supplying `--provider` without enabling the
-sandbox provider is an error. `--core-only` installs Core and PostgreSQL without
-Web and has no sandbox provider unless explicitly enabled.
-
-The provider choice does not select a harness or alter the public `openai_hosted`
-discriminator. Both providers reuse one colocated Runtime containing the native
-harnesses. The Docker option grants
-only Core access to the Docker socket; microsandbox uses the native service account's
-KVM access. Web receives neither. An enabled local provider runs through Core's
-embedded node connection and preserves its identity and owner epoch in the private
-`state/sandbox-node` directory. Docker Core mounts only this state directory
-writable in addition to its selected socket; `config` remains read-only.
-Native Core uses the same persistent directory directly. The default zero-node
-installation creates neither this state directory nor its mount.
-
 Every Core installation creates a separate private deployment administrator key at
 `admin/sandbox-admin.key`. Core loads its SHA-256 digest from
 `AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE`. Only the Core container mounts the
@@ -103,7 +88,7 @@ server-side through `CORE_CONSOLE_SANDBOX_ADMIN_TOKEN_FILE`; the Web page does n
 ask the operator to enter another key. Use the same-origin console connection for
 management. Choose English or Chinese through the System language selector.
 
-### Add nodes after a default installation
+## Add nodes after a default installation
 
 1. Log in to the bundled Web console and open **Hosted Sandbox Manager**.
    The paired installation needs no second key or Core connection setup.
@@ -112,15 +97,16 @@ management. Choose English or Chinese through the System language selector.
    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. Save the selection. It takes effect without restarting Core and remains in
+3. Select **Initialize sandbox deployment**. It takes effect without restarting Core and remains in
    PostgreSQL across restarts. All nodes in this deployment use the chosen type;
    this page does not switch providers. Microsandbox uses a five-minute idle
    timeout and one-day snapshot retention.
 4. Click **Add node**, copy the command, and run it as a non-root user on the
    target Linux amd64 host. It downloads the matched files from your console,
    verifies checksums, imports the Runtime image, writes the provider configuration,
    registers the node and starts a systemd user service. Web refreshes node health
-   automatically. A registered but unavailable node cannot accept work.
+   automatically. Wait for the node to be online and its provider to be ready;
+   registration alone does not mean it can accept work.
 
 The target host needs curl, sha256sum, Python 3.9+, a systemd user session with lingering enabled,
 and either Docker socket access or microsandbox's KVM/native-library prerequisites.
@@ -143,6 +129,55 @@ 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). The model
+credentials are supplied with execution requests, not during node installation.
+
+## Installation choices
+
+```sh
+./install.sh --sandbox-provider true --provider microsandbox
+./install.sh --sandbox-provider true --provider docker
+./install.sh --core-only
+./install.sh --core-only --sandbox-provider true --provider docker
+```
+
+`--sandbox-provider true` enables a local sandbox provider. If `--provider` is
+omitted, it selects microsandbox. Supplying `--provider` without enabling the
+sandbox provider is an error. `--core-only` installs Core and PostgreSQL without
+Web and has no sandbox provider unless explicitly enabled.
+
+The provider choice does not select a harness or alter the public `openai_hosted`
+discriminator. Both providers reuse one colocated Runtime containing the native
+harnesses. The Docker option grants
+only Core access to the Docker socket; microsandbox uses the native service account's
+KVM access. Web receives neither. An enabled local provider runs through Core's
+embedded node connection and preserves its identity and owner epoch in the private
+`state/sandbox-node` directory. Docker Core mounts only this state directory
+writable in addition to its selected socket; `config` remains read-only.
+Native Core uses the same persistent directory directly. The default zero-node
+installation creates neither this state directory nor its mount.
+
+### Local provider requirements
+
+Optional microsandbox also requires glibc, a running systemd user manager with
+linger enabled, and user read/write access to `/dev/kvm`. Nested cloud hosts must
+expose hardware virtualization. With this option, Core runs as a native user
+service so restarting it does not terminate the Provider's microVM processes.
+The installer checks these
+prerequisites; it does not grant host permissions or silently fall back to Docker.
+The optional Docker sandbox provider keeps Core in Compose and requires neither
+KVM nor systemd user services.
+
+For optional microsandbox, reserve capacity for the native Runtime: its initial
+profile uses
+4 GiB RAM, 2 CPUs, an 8 GiB root disk and an 8 GiB environment disk per active sandbox, with at most 4 active
+and 16 retained allocations. Limits are operator configuration, not model input.
+Use a trusted, single-operator host and durable local storage. The installer does
+not change host virtualization settings, install Docker, create an OS user or
+expose a remote administration service.
+
+### Separate Web installation
+
 To install only Web on a Linux host, provide the existing Core origin and a
 private caller-key file. A loopback Core uses the same host network namespace;
 a remote Core must use HTTPS.
@@ -167,7 +202,9 @@ revision changes on an existing installation. This includes enabling a sandbox
 provider on an installation originally created without one; rerunning with new
 flags does not migrate it.
 
-For remote nodes, install with the intended shared HTTPS endpoint:
+## Expose Core and Web
+
+For nodes added through Web, install with the intended shared HTTPS endpoint:
 
 ```sh
 ./install.sh --public-url https://core.example
@@ -179,7 +216,9 @@ node and daemon transport routes to Core using their own credentials. 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.
+localhost download command to a different machine. Running plain `./install.sh`
+is suitable for local console/API inspection; prepare the shared endpoint before
+installing a deployment that will enroll nodes.
 
 ## After installation