fix(installer): preserve configuration and handle failed installs safely

CONTRIBUTING.md

@@ -2589,17 +2589,23 @@ or filesystem isolation. Automatic installation remains separate.
   Workspace model Provider credentials belong to the Parsar catalog and are sent
   through the write-only Core Session execution extension. Operator defaults remain
   an independent Core deployment option. An unconfigured product can start; Core operations return an explicit unavailable error.
-- Root Compose deploys the product and its database. It mounts
-  `PARSAR_CORE_CONFIG_DIR` read-only for workspace bindings and caller key files.
-  The installer creates an empty binding list without overwriting existing
-  configuration. The product does not start a runtime container.
-- The installer pulls the server image, prepares the data directory for the
-  image's actual UID/GID, verifies writability, then starts the product. Only the
-  preparation container runs as root. It generates stable database/master keys.
-- The installer is a thin Compose wrapper. Its options cover the installation
-  directory, web bind/port, server image and validation. Native runtime history
-  migration and sandbox image options have been removed; no legacy deployment
-  compatibility or data backfill is provided by this cutover.
+- Root Compose deploys the product and database; Core is a separate deployment.
+  Keep operator installation instructions in [README.md#quick-start](README.md#quick-start).
+- The installer remains a standalone Bash 3.2-compatible Compose wrapper. Preserve
+  existing settings and secrets unless explicitly overridden. Stage and validate
+  configuration and pull images before committing files or preparing mounts.
+  Persist generated secrets only after verifying the actual Docker data mounts are
+  empty; inability to inspect data requires recovery of the original secrets.
+  Once mount preparation begins, retain matching configuration on failure; do not
+  attempt automatic database rollback. Serialize installers per canonical home and
+  clean temporary files and locks on normal exits and handled signals.
+- Prepare data mounts for the image's configured UID/GID using root only for the
+  one-off preparation. Initialize missing Core bindings without replacing existing
+  contents; new bindings must be readable by the server and editable by the operator.
+  Persistent containers must not reference temporary Compose overrides. Wait for
+  database health and the server's `/readyz`; never remove unrelated orphan containers.
+- Native runtime history migration and sandbox image options remain outside this
+  product/Core installation path; do not reintroduce legacy deployment backfills.
 - Services exposed through a deployment platform may gain an ingress network,
   but they must remain explicitly attached to the Compose `default` network
   when they depend on internal service DNS names such as `postgres`.

README.md

@@ -32,24 +32,36 @@ keeps its own database for members, business assets, permissions and collaborati
 
 ## Quick Start
 
-Requires Docker with Docker Compose v2.
+Requires Bash, Docker running Linux containers, and Docker Compose v2.15 or newer
+(on Linux, macOS, or WSL2). Start Docker before installing.
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/MiniMax-AI-Dev/parsar/main/install.sh | bash
 ```
 
-Open <http://127.0.0.1:18080> and create the first owner account in the web
-setup flow. The first registered user is the administrator.
-
-The installer writes generated config, secrets, database files, and runtime
-state under `~/.parsar/`.
-
-For local development from a checkout:
-
-```bash
-make docker-build
-./install.sh --image parsar:dev
-```
+Open <http://127.0.0.1:18080> and create the first administrator account.
+Configuration, secrets and data default to `~/.parsar/`. Back up this directory
+before upgrading; keep `.env` with its matching database and encrypted data.
+
+Rerun the installation command to upgrade. Existing settings are preserved;
+explicit options or exported `PARSAR_*` installation settings override them.
+For a custom directory or port, append options with `bash -s -- --home /absolute/path
+--port 19090`. Use `--help` for all options and `--dry-run` to validate without
+saving configuration or starting containers. Advanced settings belong in `.env`.
+Use `--compose-file /absolute/path/docker-compose.yml` to retain a custom Compose
+file; otherwise the installer uses the current checkout's file or downloads it.
+
+The installer prints commands for status, logs and shutdown. Download, configuration
+or image-pull failures leave existing files and services unchanged. Later failures
+retain configuration and data so the same command can be retried after fixing the
+reported error. It does not roll back database migrations or remove unrelated
+containers, volumes or images. Normal exits and handled interruptions remove
+temporary files and the installation lock; after a forced kill or power loss,
+remove `<home>/.install.lock` and `<home>/.install.*` only after confirming no
+installer is running. Never delete `.env` to resolve an installation error.
+
+For a locally built server image, run `make docker-build`, then
+`PARSAR_IMAGE_PULL_POLICY=never ./install.sh --image parsar:dev` from the checkout.
 
 The default Compose stack starts PostgreSQL and the Parsar web control plane.
 Deploy Core separately and configure a distinct Core project credential for each