caffeinated-whale-cli 3.3.0__tar.gz → 3.5.0__tar.gz

{caffeinated_whale_cli-3.3.0 → caffeinated_whale_cli-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 3.3.0
+Version: 3.5.0
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -26,6 +26,7 @@ Requires-Dist: questionary>=2.1.0
 Requires-Dist: toml>=0.10.2
 Requires-Dist: peewee>=3.17.0
 Requires-Dist: packaging>=24.0
+Requires-Dist: cryptography>=42
 Provides-Extra: dev
 Requires-Dist: black>=25.1.0; extra == "dev"
 Requires-Dist: ruff>=0.8.0; extra == "dev"
@@ -41,8 +42,6 @@ Dynamic: license-file
 # Caffeinated Whale CLI
 
 A command-line interface (CLI) for managing Frappe/ERPNext Docker instances during local development.
-The repository also contains the Phase 1 Tauri desktop shell, which runs the existing Console GUI over the same Python core.
-See [`desktop/README.md`](./desktop/README.md) for its current source-build status, supported platforms, and build instructions.
 
 ## Features
 
@@ -53,20 +52,20 @@ See [`desktop/README.md`](./desktop/README.md) for its current source-build stat
 - **Container Lifecycle** - Start, stop, and restart projects with ease
 - **Scale Beyond Six Benches** - Widen an instance's published port range on demand with `cwcli scale` so more than six benches are reachable from the host - database-safe (only the frappe service is recreated)
 - **Development Tools** - VS Code integration, log viewing, and command execution
+- **Web UI** - A local browser dashboard over every instance, bench, site and app with `cwcli ui`: live health, logs, the `doctor` health check in Settings, and the everyday lifecycle actions
 - **Cache System** - Fast project inspection with SQLite-based caching and configuration storage
 - **Multi-Bench Support** - Address individual benches in a multi-bench instance by numeric index or a durable label with `--bench`
 - **Default Site Support** - Optional `--site` flag when default site is configured
-- **Backup & Restore** - Interactive site restoration with automatic file archive detection and P2P transfer support
+- **Backup & Restore** - Interactive site restoration with automatic file archive detection and P2P transfer support, plus a verified backup store outside the instances with `cwcli backups` (retention, clone and move, off-site S3 copies)
 - **App Management** - List, install, uninstall, and update Frappe apps per bench and per site with `cwcli apps` (multi-site by default, `--json`, honest exit codes)
 - **Private App Repos** - `apps install`/`apps update` authenticate private GitHub/GitLab app fetches through your host's already-signed-in `gh`/`glab`, with no token ever entering the container
 - **Update Management** - App updates with automatic migrations and lock cleanup
 - **Self-Update** - Upgrade cwcli itself to the latest release with `cwcli self-update` (install-method aware)
-- **Environment Preflight** - Read-only checks for Docker, disk space, and tool dependencies with `cwcli doctor` (chainable exit code, `cwcli axi doctor` for agents; the shared cache layer may idempotently initialize cwcli's private cache directory while building the command tree)
+- **Environment Preflight** - Read-only checks for Docker, disk space, and tool dependencies with `cwcli doctor` (chainable exit code, `cwcli axi doctor` for agents)
 - **Update Notices** - A passive, once/day "a newer cwcli is available" hint on stderr, shown only to a human at a TTY
 - **Auto-Inspection** - Background process to keep project cache fresh automatically
 - **System Integration** - Auto-start on system boot with platform-specific configurations
 - **Contextual Tips** - Helpful tips displayed during long-running operations to help you discover features
-- **Desktop Console** - A source-build Tauri 2 shell for the existing Console GUI on Linux and Windows; installer bundles are deferred to a later phase
 
 ## Installation
 
@@ -234,7 +233,7 @@ A cluster containing an unknown short option is rejected as a whole.
 
 Creates a complete Frappe development environment in a single step. Downloads compose files, starts containers, initializes bench, creates a site, and starts the bench's dev services.
 
-Blocks for roughly 10-20 minutes (image pulls, bench init, site creation). Running several `cwcli init` invocations in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance (`cwcli init existing-project --bench another-bench`) never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout.
+Blocks for roughly 10-20 minutes (image pulls, bench init, site creation). Running several `cwcli init` invocations in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance (`cwcli init existing-project --bench another-bench`) never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout. Re-running init against a stopped instance starts its existing containers as they are, without pulling images or recreating them, so its benches keep their Python environments. If the re-run would change that instance's compose settings, such as a different `--port` on an instance still on the default port range (8000-8005), init refuses with exit 1 (`instance.settings_changed`), leaves the compose file unchanged, and names each change; remove the instance with `cwcli rm` (which backs it up) and run init again, or rerun init without the changed options. For an instance created on another `--port` or widened by `cwcli scale`, init does not compare `--port`. An instance whose frappe container has never started, such as one left by a first init that failed at `docker compose up`, has no bench to protect, so init neither refuses nor uses `--no-recreate` there: it pulls images and recreates the containers with the new options.
 
 ```bash
 cwcli init [OPTIONS] [PROJECT_NAME]
@@ -258,7 +257,7 @@ cwcli init [OPTIONS] [PROJECT_NAME]
 | `--frappe-branch TEXT` | Frappe branch or tag for bench init, e.g. `version-16` or `v16.26.3` (default: version-16). Mutually exclusive with `--version` |
 | `--version TEXT` | Frappe version for bench init, resolved by shape: a bare major (`16` → `version-16` branch) or a full semantic version (`16.26.3` → `v16.26.3` tag). Malformed values are rejected with a non-zero exit. Mutually exclusive with `--frappe-branch` |
 | `--frappe-url TEXT` | Custom Frappe repository URL to build from (a fork), passed to `bench init --frappe-path`. Omit to use the default `frappe/frappe` repo. Pair with `--frappe-branch` to check out the fork's branch. A private fork authenticates through the same credential bridge as `apps install`/`apps update` (host `gh`/`glab`, no token in the container); sign in on the host first |
-| `--db-root-password TEXT` | MariaDB root password (default: 123) |
+| `--db-root-password TEXT` | MariaDB root password. On a new instance MariaDB is created with it (handed over as a compose secret, never written into `docker-compose.yml`) and cwcli remembers it in `~/.cwcli/projects/{project_name}/conf/db-root-password` for later `rm-site`, `rm-bench`, `restore`, and re-run `init` commands. Omitted, the instance's remembered password is used, else the default `123`. An instance whose MariaDB already exists keeps the password it was created with |
 | `--admin-password TEXT` | Administrator password for the site, used verbatim. If omitted, a strong password is generated and printed once (interactive runs only); a non-interactive run must supply this flag |
 | `--install-erpnext` | Install ERPNext application after initialization |
 | `--erpnext-branch TEXT` | ERPNext branch to use (default: version-16) |
@@ -438,6 +437,78 @@ Without a reuse flag, a non-interactive session (non-TTY) where the bench alread
 
 ---
 
+### `new-bench` - Add a Bench to an Instance
+
+Adds a bench to an existing instance with the same provisioning `init` gives bench 0: `bench init` for the chosen version or fork, the bench configs, a first site, and optionally ERPNext.
+It then starts the bench's processes and fetches and installs any extra apps on the first site.
+The other benches in the instance keep running.
+
+```bash
+cwcli new-bench [OPTIONS] PROJECT_NAME BENCH_NAME
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--site TEXT` | The first site's name (default: `<BENCH_NAME>.localhost`) |
+| `--version TEXT` | Frappe version: a major (`16`, the default) or a tag (`16.3.0`) |
+| `--frappe-branch TEXT` | A raw Frappe git ref instead of `--version` |
+| `--frappe-url TEXT` | A Frappe fork to build from (private forks use the credential bridge) |
+| `--erpnext` | Install ERPNext on the first site |
+| `-a`, `--app TEXT` | An extra app (git URL or name) to fetch and install on the first site (repeatable) |
+| `--admin-password TEXT` | Administrator password for the first site |
+| `--db-root-password TEXT` | MariaDB root password (default: the one remembered at init; env `CWCLI_DB_ROOT_PASSWORD`) |
+| `-y`, `--yes` | Auto-start a stopped instance without prompting |
+| `-v`, `--verbose` | Stream bench's output |
+
+The Administrator password comes from `--admin-password`, else the `CWCLI_ADMIN_PASSWORD` environment variable, else a hidden prompt.
+A non-interactive session with neither refuses with exit 2.
+A bench name that already exists is refused, never reused.
+The command exits 1 when an extra app fails to install or the bench's processes did not start, even though the bench was created.
+
+```bash
+CWCLI_ADMIN_PASSWORD=... cwcli new-bench my-project bench-v15 --version 15 --erpnext
+cwcli new-bench my-project hrms-bench --app https://github.com/frappe/hrms
+```
+
+**Agent surface:** `cwcli axi new-bench` is the TOON spelling.
+
+---
+
+### `new-site` - Add a Site to a Bench
+
+Creates a site on an existing bench: `bench new-site`, then `install-app` for each `--app`, `bench use` with `--default`, and developer mode with `--dev-mode`.
+
+```bash
+cwcli new-site [OPTIONS] PROJECT_NAME SITE
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--bench TEXT` | Which bench: its numeric index or label |
+| `-a`, `--app TEXT` | An app already on the bench to install on the site (repeatable) |
+| `--default` | Make it the bench's default site |
+| `--dev-mode` | Turn developer mode on for the new site |
+| `--admin-password TEXT` | Administrator password |
+| `--db-root-password TEXT` | MariaDB root password (default: the one remembered at init; env `CWCLI_DB_ROOT_PASSWORD`) |
+| `-y`, `--yes` | Auto-start a stopped instance without prompting |
+| `-v`, `--verbose` | Stream bench's output |
+
+The Administrator password is resolved the same way as for `new-bench`: the flag, then `CWCLI_ADMIN_PASSWORD`, then a hidden prompt, and a non-interactive session with neither refuses with exit 2.
+A site name that already exists on the bench is refused, and every `--app` must already be in the bench's `apps/` folder (fetch one first with `cwcli apps install <project> <app> --fetch-only`).
+
+```bash
+CWCLI_ADMIN_PASSWORD=... cwcli new-site my-project shop.localhost --app erpnext --default
+cwcli new-site my-project shop.localhost --bench 1 --dev-mode
+```
+
+**Agent surface:** `cwcli axi new-site` is the TOON spelling.
+
+---
+
 ### `ls` - List Projects
 
 Scans Docker for Frappe/ERPNext projects and displays their status and ports.
@@ -568,6 +639,7 @@ cwcli start [OPTIONS] [PROJECT_NAME]...
 - **Per-process supervision:** each Procfile process runs under supervisord, so one can be restarted or auto-healed without disturbing the others
 - **Waits for the web server:** on a genuine launch, `start` blocks until the bench's **own** web port actually answers before reporting the bench as running, so a scripted `cwcli start && cwcli status` never catches a transient `degraded`. The port is read from that bench's `sites/common_site_config.json`, never assumed - waiting on a hardcoded `:8000` meant `--bench 1` watched bench 0's port and then warned that a healthy bench had not started. If the port cannot be read, the wait is **skipped** (`web_ready` stays unset) rather than spent on a guess. A timeout (60s) does not fail the start (the stack IS launched) - it prints a warning naming the real port and telling you to check `cwcli status` / `cwcli logs`
 - **Host port verification:** on both a genuine launch and an idempotent no-op, `start` warns when the bench's web server has no live host port binding. The warning names the container port and advises recreating the instance with `cwcli init`
+- **Recovers a missing compose network:** when a Docker or WSL crash has removed the instance's own network (`<project>_default`), `start` recreates it, reconnects the stopped containers with their service aliases, and prints a warning, so the instance starts without manual repair. No container is recreated. A missing network the project does not own, or a recreate that fails, stops the start with the exact `docker network` command to run
 - **Port Conflict Detection:** Automatically checks if required ports are available
 - **Interactive Resolution:** Offers to stop conflicting Frappe projects (use `--yes` to auto-confirm)
 - **Process Identification:** Shows which processes are using ports (cross-platform)
@@ -626,6 +698,11 @@ supervisor rather than stopping any container. Sibling benches keep serving, the
 containers stay up, and `cwcli start --bench` brings it back. Stopping a bench
 that is already stopped is a success, not an error.
 
+A whole-instance stop takes the database down last and gives it up to 60 seconds
+to finish its shutdown. If the database exits non-zero (137 means it was killed
+before it finished shutting down), `stop` says so and exits non-zero instead of
+reporting a clean stop.
+
 **Example:**
 
 ```bash
@@ -767,7 +844,8 @@ Removes a Frappe project: its containers, named Docker volumes, own Docker Compo
 **WARNING:** This action is destructive and cannot be undone.
 Before deleting anything, the command re-caches the project, backs up the databases and files for all sites across every bench (a live `bench backup --with-files`, run once per bench on a multi-bench project), and archives the `docker-compose.yml`, `site_config.json`, and the project's `conf/` directory into a timestamped folder under `~/.cwcli/archive/` (or `$CWCLI_HOME/archive/` when the `CWCLI_HOME` override is set).
 The backup and the config archive are written first, and the named volumes and project directory are only deleted once both have succeeded.
-When volumes are being deleted (the default `--volumes`), a backup that cannot be fully created and verified blocks removal: each backup artifact is copied out of the container to the host archive and the database dump must be present and non-empty.
+Each site's verified backup is then moved into the [backup store](#backups---the-backup-store) as a `before-removal` set, which outlives the instance.
+When volumes are being deleted (the default `--volumes`), a backup that cannot be fully created and verified blocks removal: each backup artifact is copied out of the container to the host archive, and the database dump must be present and non-empty.
 If verification fails, the command aborts before any container is removed and exits non-zero, so data is never destroyed without a confirmed backup.
 Aborting before removal keeps the whole project intact (containers, volumes, network, directory, and cache), so a retry can still take a live backup from the running container.
 Under `--no-volumes` no volume data is destroyed, so a failed backup does not block the container, network, directory, and cache cleanup.
@@ -842,12 +920,21 @@ Permanently drops ONE site from a running bench, leaving the instance and every
 This is deliberately a separate, noun-scoped command rather than a `--site` flag on `cwcli rm`: `cwcli rm` destroys the whole instance (containers, volumes, the project directory), while `rm-site` only ever touches the one named site, so forgetting a flag can never turn a single-site cleanup into an instance-wide deletion.
 
 **WARNING:** This action is destructive and cannot be undone.
-`cwcli rm-site` runs `bench drop-site --force`, which drops the site's database and deletes its files.
+`cwcli rm-site` backs the site up first, then runs `bench drop-site --no-backup`, which drops the site's database and deletes its files.
+
+The backup is the same verified gate `cwcli rm` uses, taken by cwcli itself before anything is dropped: `bench --site <site> backup --with-files`, then this run's database dump and file archives are copied out to `~/.cwcli/archive/{project}_dropped_sites/{site}_{timestamp}/backups/` (or `$CWCLI_HOME/archive/...` when that override is set) and the dump is checked non-empty there.
+If the backup fails or cannot be verified, nothing is dropped, and the command exits non-zero with bench's own error.
+cwcli never relies on `bench drop-site`'s own backup, because with `--force` bench ignores a failed backup and drops the database anyway.
+To drop a site whose backup cannot be taken, run `cwcli run <project> --path <bench> -i drop-site <site> --no-backup` yourself; the error names that command.
 
-`bench drop-site` archives the dropped site's full directory - including `site_config.json` (its database credentials and, if set, its encryption key) - inside the container's own `archived/sites/` folder before this command ever sees it.
+`bench drop-site` then archives the dropped site's full directory - including `site_config.json` (its database credentials and, if set, its encryption key) - inside the container's own `archived/sites/` folder.
 Left there it would grow, unpruned, forever, for the rest of the bench's life.
-So `cwcli rm-site` immediately copies that one archive out to `~/.cwcli/archive/{project}_dropped_sites/` (or `$CWCLI_HOME/archive/...` when that override is set) - the same managed archive location `cwcli rm` already uses - and, only once that copy is verified non-empty on disk, deletes the in-container copy.
-If the copy cannot be verified, the in-container archive is left in place rather than deleted unbacked, and the command exits non-zero so the leftover credentials are never silently missed.
+So `cwcli rm-site` copies that one archive out beside the backup (as `{site}.tar` in the same directory) and, only once that copy is verified non-empty on disk, deletes the in-container copy.
+If anything cannot be verified, the in-container archive is left in place rather than deleted unbacked, and the command exits non-zero so the leftover credentials are never silently missed.
+
+Once the drop has finished, the verified backup files are moved into the [backup store](#backups---the-backup-store) as a `before-removal` set (the `{site}.tar` stays in the archive directory).
+To restore the dropped site, run `cwcli backups restore <project>/<site>/<id> <project> --site <site>`; `cwcli backups list <project>` shows the set's key.
+If the move into the store fails, the files stay in the archive's `backups/` directory and nothing is lost.
 
 ```bash
 cwcli rm-site [OPTIONS] PROJECT_NAME SITE
@@ -866,7 +953,7 @@ cwcli rm-site [OPTIONS] PROJECT_NAME SITE
 |--------|-------------|
 | `--bench TEXT` | Which bench to target: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
 | `-p`, `--path TEXT` | Explicit bench directory inside the container (lower-level alternative to `--bench`; cannot be combined with it) |
-| `--db-root-password TEXT` | MariaDB root password used by `bench drop-site` (default: `123`, matching the compose file's own default) |
+| `--db-root-password TEXT` | MariaDB root password used by `bench drop-site` (default: the password remembered for the instance at `init`, else `123`) |
 | `-y`, `--yes` | Skip the destructive confirmation and auto-start containers |
 | `-v`, `--verbose` | Enable verbose output |
 
@@ -883,7 +970,7 @@ cwcli rm-site my-project task-42.localhost --yes
 cwcli rm-site my-project task-42.localhost --bench 1 --yes
 ```
 
-**Agent surface:** `cwcli axi rm-site <project> <site> --yes` emits the outcome as TOON, including `archived_host_path` and `archive_pruned_in_container`.
+**Agent surface:** `cwcli axi rm-site <project> <site> --yes` emits the outcome as TOON, including `archived_host_path` (the directory holding the verified backup and the site archive) and `archive_pruned_in_container`.
 `--yes` is required (never a prompt) and grants ONLY consent to drop the site - it never auto-starts a stopped project, exactly like every other bench-scoped `axi` verb.
 See [For agents: the `cwcli axi` surface](#for-agents-the-cwcli-axi-surface).
 
@@ -898,8 +985,10 @@ A bench is a directory on the instance's shared workspace bind mount, and its si
 So `cwcli rm-bench` backs up and drops every site on the target bench (deleting each site's database and files), then deletes the bench directory.
 
 **WARNING:** This action is destructive and cannot be undone.
-Each site is dropped through the same verified copy-out that `cwcli rm-site` uses: `bench drop-site` backs the site up, and cwcli copies that archive out to `~/.cwcli/archive/{project}_dropped_sites/` (or `$CWCLI_HOME/archive/...` when that override is set) and verifies it on disk before the bench directory is deleted.
-If any site's backup cannot be copied out, the bench directory is kept (so the trapped backup is never destroyed) and the command exits non-zero.
+Every site is backed up BEFORE any site is dropped, with the same verified gate `cwcli rm-site` and `cwcli rm` use: each site's database dump and file archives are copied out to `~/.cwcli/archive/{project}_dropped_sites/{site}_{timestamp}/backups/` (or `$CWCLI_HOME/archive/...` when that override is set) and the dump is checked non-empty there.
+If any site's backup fails, nothing is dropped and nothing is deleted, and the command exits non-zero with bench's own error.
+Each site is then dropped with `bench drop-site --no-backup` and its archived site directory copied out beside its backup.
+If any site's archive cannot be copied out, the bench directory is kept (so the trapped archive is never destroyed) and the command exits non-zero.
 
 A bench that is still running is refused: stop it first with `cwcli stop <project> --bench <selector>`.
 `cwcli rm-bench` never deletes a bench out from under its own running code.
@@ -920,7 +1009,7 @@ cwcli rm-bench [OPTIONS] PROJECT_NAME
 |--------|-------------|
 | `--bench TEXT` | Which bench to remove: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
 | `-p`, `--path TEXT` | Explicit bench directory inside the container (lower-level alternative to `--bench`; cannot be combined with it) |
-| `--db-root-password TEXT` | MariaDB root password used by `bench drop-site` (default: `123`, matching the compose file's own default) |
+| `--db-root-password TEXT` | MariaDB root password used by `bench drop-site` (default: the password remembered for the instance at `init`, else `123`) |
 | `-y`, `--yes` | Skip the destructive confirmation and auto-start the container |
 | `-v`, `--verbose` | Enable verbose output |
 
@@ -1259,23 +1348,51 @@ A bench that was not running is left alone.
 
 **`apps uninstall`** - removes each app from the target site(s) (`bench --site <site> uninstall-app`). This destroys site data, so it is gated by `-y`/`--yes` or an interactive confirmation (a non-TTY without `--yes` refuses). It uses the same resynchronise-and-verify step as install, so no supervised process - web, scheduler, or worker - can keep running against the code and tables of an app that is gone.
 
-**`apps update`** - the canonical app-update path (what the deprecated `cwcli update` now delegates to). Updating the `frappe` framework app runs `bench update --reset`; other apps use the normal git-pull + migrate flow. After the migrations finish and maintenance mode is lifted, it runs the same **resynchronise** step as `apps install`, so a `git pull` cannot leave the bench's web, scheduler, and workers on the code that was there before it; every migrated site must answer Frappe before the run reports success. `--site` narrows which affected sites are migrated; if none of the named site(s) actually have the app installed, the command refuses and exits non-zero rather than silently migrating nothing (a genuine typo/mismatch guard - a bench with no affected sites at all still exits zero). It accepts the same migration flags as the [deprecated `update` command](#update---update-apps-and-migrate) (`--clear-cache`, `--clear-website-cache`, `--build`, `--skip-maintenance`, `--no-recache`). When updating the `frappe` framework app the flow runs the bench-wide `bench update --reset`, so `--site` and those per-app migration flags do not apply and are reported as ignored.
-`--force` is an opt-in, **destructive** recovery for a conflicting update: if an app's `git pull` hits a **conflict** (local changes that would be overwritten, or a conflicted merge), it hard-resets that app to its remote tracking branch (`git fetch` then `git reset --hard @{u}`), discarding the local changes, so the update completes instead of failing. It fires **only on a conflict** - a clean update is untouched, and a pull that failed for another reason (network, auth) is left as the failure it is rather than having work discarded. Without `--force`, a conflict fails safely and discards nothing. Every force-reset app is reported (`force_reset_apps`) and a warning is printed at the reset. `--force` does not delete untracked files (it never runs `git clean`), matching `apps checkout --reset`. `--force` also clears a git **"dubious ownership"** refusal before pulling: when an app's repository is owned by a different user than the container runs as - common on a shared-mode or migrated instance whose app sources are owned by a pre-migration uid - it re-owns the repository to the container user so the pull proceeds, rather than surfacing a raw git ownership error. A `cwcli start`/`cwcli restart` self-heals the same ownership so a plain `apps update` works too; `--force` fixes it inline without a restart.
+**`apps update`** - the canonical app-update path (what the deprecated `cwcli update` now delegates to). Updating the `frappe` framework app (or `erpnext`) is a **core update**: only the core app you name is reset to its remote branch (`apps update <p> frappe` never touches erpnext) (`git fetch <remote> <branch>` then `git reset --hard <remote>/<branch>`, for the app's own remote and checked-out branch, never bench's bench-wide `bench update --reset`, which hard-reset every app on the bench), every site's stale `locks` folder is cleared first and listed (a site whose migrate lock is held by a running migrate refuses the update before anything runs, with or without the preflight), the bench's requirements are reinstalled, then every affected site migrates under the same per-site maintenance lifecycle as any other app; other apps use the normal git-pull + migrate flow. After the migrations finish and maintenance mode is lifted, it runs the same **resynchronise** step as `apps install`, so a `git pull` cannot leave the bench's web, scheduler, and workers on the code that was there before it; every migrated site must answer Frappe before the run reports success. `--site` narrows which affected sites are migrated; if none of the named site(s) actually have the app installed, the command refuses and exits non-zero rather than silently migrating nothing (a genuine typo/mismatch guard - a bench with no affected sites at all still exits zero). It accepts the same migration flags as the [deprecated `update` command](#update---update-apps-and-migrate) (`--clear-cache`, `--clear-website-cache`, `--build`, `--skip-maintenance`, `--no-recache`). A core update honours `--site` and those flags like any other app, and always rebuilds assets.
+Because the core update never runs bench's own bench-wide update, nothing is set in `sites/common_site_config.json`: a site that fails to migrate is named as such (`failed_migrations`), its maintenance mode is cleared by cwcli's `finally`, and the summary states the bench state - which sites migrated, which did not and why, and whether any site is still in maintenance.
+`--force` is an opt-in, **destructive** recovery for a conflicting update (updating `frappe` gives it a different meaning, described under [the data-loss guard](#apps---manage-frappe-apps) below): if an app's `git pull` hits a **conflict** (local changes that would be overwritten, or a conflicted merge), it hard-resets that app to its remote tracking branch (`git fetch` then `git reset --hard @{u}`), discarding the local changes, so the update completes instead of failing. It fires **only on a conflict** - a clean update is untouched, and a pull that failed for another reason (network, auth) is left as the failure it is rather than having work discarded. Without `--force`, a conflict fails safely and discards nothing. Every force-reset app is reported (`force_reset_apps`) and a warning is printed at the reset. `--force` does not delete untracked files (it never runs `git clean`), matching `apps checkout --reset`. `--force` also clears a git **"dubious ownership"** refusal before pulling: when an app's repository is owned by a different user than the container runs as - common on a shared-mode or migrated instance whose app sources are owned by a pre-migration uid - it re-owns the repository to the container user so the pull proceeds, rather than surfacing a raw git ownership error. A `cwcli start`/`cwcli restart` self-heals the same ownership so a plain `apps update` works too; `--force` fixes it inline without a restart.
+**The `frappe` preflight.** A core update resets the core app's git checkout and reinstalls the bench's requirements before any site migrates, so a git problem (a branch the remote lacks, an unreachable remote, a detached HEAD) or a code requirement the bench cannot meet would otherwise surface mid-run.
+Updating `frappe` therefore runs a preflight first that predicts those failures in seconds, by evaluating bench's own rules against the same state bench reads.
+It reports everything it finds at once, grouped as blockers, data loss, could-not-verify and notices, each with the cwcli command that fixes it.
+Any blocker refuses the update with nothing changed and exits 1.
+Blockers are: an app on a branch its remote does not have, or one its remote's fetch refspec does not cover (a single-branch clone after `cwcli apps checkout` of another branch), an unreachable remote (bench contacts every remote unless `shallow_clone` is set), a detached HEAD, `frappe`/`erpnext` on `master` or not a git checkout, `frappe` without an `upstream` remote, a remote bench would pick by mistake, a repository git refuses for dubious ownership, a path the container user cannot write, a missing `mariadb-dump`/`gzip`/`yarn`/`node`, an unreachable database or `redis_cache`, a site that cannot be opened, a held migrate lock, a nearly full disk, an unreadable `common_site_config.json`, and `release_bench`.
+The preflight also reads the code the reset would install, from the same `git fetch` of each app's branch that bench runs, which moves only the remote-tracking branch and never the checked-out code.
+It blocks when that code needs a newer Python than the bench's environment (`requires-python`) or a newer Node than the container's (`engines.node`), since bench would fail reinstalling it after every backup and every reset, and when it is a frappe major-version upgrade, which bench stops to confirm and cwcli's run cannot answer.
+A `[tool.bench.frappe-dependencies]` the bench cannot satisfy - an app on `develop` declaring `frappe >=17` on a frappe 16 bench, or one app requiring another app's older line - is a blocker, because bench only warns and the site migrate then fails: the finding names the switch (`cwcli apps checkout <project> <app> version-N`), and `--fix-branches` has cwcli perform it before the update (a dirty tree still refuses).
+A checked-out branch the remote's fetch refspec does not cover (a narrow clone switched by hand) is widened in place - `git remote set-branches --add <remote> <branch>` plus a fetch - and logged, since the reset needs `<remote>/<branch>` to exist; `cwcli apps checkout` tracks a branch the same way.
+Uncommitted changes and unpushed commits that the reset would discard are reported as data loss, and refuse the update through the data-loss guard below.
+Any other check that cannot run or times out is reported as unverified and never blocks.
+No preflight can predict a failing patch, schema sync or asset build in the new code; those still surface only in the real run.
+`--no-preflight` skips the checks, for a false positive such as a remote that only a proxy-configured fetch can reach; bench then fails wherever it fails.
+It does not skip the data-loss guard below.
+The findings ride the report as `preflight` (each with a stable `code`, `severity`, `app`/`site`, `message` and `remedy`) plus `preflight_blocked`, on `--json` and `cwcli axi apps update` alike.
+
+**The data-loss guard.** The core reset hard-resets the named core apps (`frappe`, `erpnext`) to their remote branch, so it silently discards their uncommitted changes to tracked files and commits that exist on no remote, branch or tag; other apps are not touched, so their local work is not at risk.
+Untracked files survive, because `git reset --hard` leaves them in place.
+Updating `frappe` therefore refuses, with nothing run, while a core app being reset holds such work, and exits 1 naming each app.
+An app whose local work cannot be checked refuses the same way, rather than being assumed clean.
+`--force` accepts the loss: the reset runs and discards that work.
+On this path `--force` also re-owns an app repository git refuses for dubious ownership before the checks run, and it never gets past a blocker.
+The guard is a safety check, not a prediction, so `--no-preflight` does not skip it; under `--no-preflight` it runs alone, with no remote or service probe.
+A terminal gets the same refusal as a script: there is no prompt, and `--force` is the only way through.
+With `shallow_clone` set in the bench config, bench also expires the reflog and prunes after each reset, so the discarded work cannot be recovered afterwards.
+The report carries `data_loss_refused` (the guard refused) and `data_loss_apps`: the apps holding the work, or after `--force`, the apps whose work bench was allowed to discard.
+
 When `apps/<app>` is a symlink, the update writes through it and the run names the real directory it operated on.
 After the pull, update verifies that the copy the bench actually imports is the copy it just updated; when they differ it does **not** report plain success - it warns, names both paths, and exits non-zero so a script notices the site is still running the other copy.
 
 **`apps checkout`** - fetches and checks out an arbitrary branch, tag, or commit (`REF`) into an app that is **already present** in the bench (`apps/<app>`), so a specific feature branch can be put under test in the instance the app lives in.
 Unlike `apps install` (bench acquisition when needed, then site installation) and `apps update` (the tracked upstream on every app), this targets one existing checkout: it runs `git fetch <remote> <ref>` then `git checkout -B <ref> FETCH_HEAD` in the app directory (the remote is auto-detected - `upstream` for a bench-installed app, `origin` for a hand-cloned one).
 A **dirty working tree is refused** before anything is fetched, so uncommitted work in the in-instance checkout is never carried across a branch switch.
-Once the checkout step moves the tree, the command runs the same **resynchronise** step `apps install` uses, even if a later `--reset` step fails.
+Once a step moves the tree (the `--reset` hard reset or the checkout), the command runs the same **resynchronise** step `apps install` uses, even if the checkout then fails.
 Swapping the code under a running bench and leaving it serving the branch you just moved off is the quietest form of that defect, because nothing errors at all.
 The sites proved are the ones with that app installed, so the command exits non-zero rather than reporting a checkout that left the app unable to serve.
 If one site's installed-app list cannot be read, the command warns that the site was not checked and excludes it from the proof set.
 If the bench's site list itself cannot be read, the resynchronisation fails.
 Dirty means precisely **anything `git status --porcelain` reports: staged changes, unstaged modifications to tracked files, and untracked files**.
 Files matched by `.gitignore` are not reported by git and so never count, which is why ordinary build residue (`__pycache__`, `node_modules`, `*.egg-info`) does not block a checkout.
-`--reset` is the explicit opt-in through that refusal: it hard-resets the working tree to the fetched ref, discarding tracked local edits, which guarantees the clean tree a subsequent `build`/`migrate` needs.
-Note one honest limit: `--reset` does **not** delete untracked files, because cwcli never runs `git clean` - it lets the checkout proceed and leaves them where they are.
+`--reset` is the explicit opt-in through that refusal: it hard-resets the working tree before switching, discarding tracked local edits, so the checkout lands the clean tree a subsequent `build`/`migrate` needs on the fetched ref.
+Note one honest limit: `--reset` does **not** delete untracked files, because cwcli never runs `git clean` - it lets the checkout proceed and leaves them where they are, and an untracked file the target ref would overwrite still makes the checkout fail.
 Like `apps update`, checkout names the real directory when `apps/<app>` is a symlink, and after moving the tree it verifies the bench imports the copy it just changed; if the bench imports a different copy it warns, names both paths, and exits non-zero rather than reporting a checkout the site will not actually run.
 
 **Private repos:** `apps install`/`apps update`/`apps checkout` (and the deprecated `update`), plus any bench subcommand run through [`cwcli run`](#run---execute-bench-commands) (`cwcli run <project> get-app <private-url>`, `cwcli run <project> update --pull`), transparently authenticate git fetches against private GitHub/GitLab app repos through your host's already-signed-in `gh`/`glab` - nothing to configure, no token ever stored in the container, and public repos are unaffected. Sign in on the host first (`gh auth login` / `glab auth login`). This credential bridge only serves operations run **through cwcli**; a raw `git` you run yourself inside the container (in a `docker exec` shell, or `cwcli open`) is not bridged and will prompt or fail auth. Run the fetch through `cwcli run <project> <bench-args>` instead, or - to bridge **interactive** git inside `cwcli open` or a `docker exec` shell (not just cwcli's own operations) - opt into the persistent [`config cred-bridge`](#config-cred-bridge---persistent-credential-bridge).
@@ -1318,7 +1435,7 @@ cwcli apps uninstall frappe-one --app payments --yes
 
 # Update an app (or the framework) - multi-bench aware
 cwcli apps update frappe-one erpnext
-cwcli apps update frappe-one frappe        # runs 'bench update --reset'
+cwcli apps update frappe-one frappe        # core update: frappe only, locks cleared, requirements, migrate
 
 # Check a feature branch out into an already-installed app (private repo authed via the bridge)
 cwcli apps checkout frappe-one erpnext feature/new-report
@@ -1332,7 +1449,7 @@ cwcli apps checkout frappe-one erpnext feature/new-report --reset   # force a cl
 > **Deprecated:** use [`cwcli apps update`](#apps---manage-frappe-apps) instead. `cwcli update` keeps working as an alias (and now prints a deprecation notice), so existing scripts are unaffected.
 
 Updates specified Frappe apps and migrates all sites where they are installed.
-Updating the `frappe` framework app runs `bench update --reset`.
+Updating the `frappe` framework app is the core update described under [`apps update`](#apps---manage-frappe-apps).
 
 ```bash
 cwcli update [OPTIONS] PROJECT_NAME
@@ -1357,6 +1474,9 @@ cwcli update [OPTIONS] PROJECT_NAME
 | `-w`, `--clear-website-cache` | Clear website cache for all affected sites after migration |
 | `-b`, `--build` | Build assets after updating apps |
 | `--skip-maintenance` | Skip enabling maintenance mode for affected sites during update |
+| `--force` | Destructive. Updating `frappe`: run the core reset even though it discards uncommitted or unpushed work in that app (see [the data-loss guard](#apps---manage-frappe-apps)). Other apps: hard-reset an app whose `git pull` hits a conflict instead of failing. Either way, re-own app repositories git refuses for dubious ownership |
+| `--fix-branches` | Updating `frappe`: switch an app whose declared frappe-dependencies do not fit this bench to the matching `version-N` branch first, instead of refusing |
+| `--no-preflight` | Updating `frappe` only: skip the checks that run before the core reset (see [the `frappe` preflight](#apps---manage-frappe-apps)); the data-loss guard still runs |
 | `-y`, `--yes` | Auto-start stopped containers without prompting |
 
 **What It Does:**
@@ -1490,6 +1610,75 @@ Removed locks folder: /workspace/frappe-bench/sites/development.localhost/locks
 
 ---
 
+### `dev-mode` - Developer Mode for a Site
+
+Shows, turns on, or turns off Frappe's developer mode for one site.
+Frappe reads `developer_mode` from `common_site_config.json` (bench-wide), and a site's `site_config.json` overrides it, so the read names where the value you see comes from.
+
+```bash
+cwcli dev-mode [OPTIONS] PROJECT_NAME SITE [on|off]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--bench TEXT` | Which bench: its numeric index or label |
+| `--common` | Set it bench-wide in `common_site_config.json` instead of the site's `site_config.json` |
+| `-y`, `--yes` | Skip the confirmation (and auto-start a stopped instance) |
+
+Without `on` or `off` the command only reads the state.
+A change asks for confirmation, runs `bench set-config developer_mode 1|0` for the site (or with `-g` for `--common`), and then clears the site's cache.
+The command exits 1 if the cache could not be cleared.
+
+```bash
+cwcli dev-mode my-project example.localhost
+cwcli dev-mode my-project example.localhost on
+cwcli dev-mode my-project example.localhost off --common
+```
+
+---
+
+### `db-access` - Check and Repair Site Database Users
+
+Frappe grants each site's database user on the address the frappe container had when the site was created (`'<user>'@'172.21.0.5'`).
+When a restart gives the container a new address, every site answers HTTP 500 with `OperationalError 1045 (Access denied)` while nothing in the site itself changed.
+cwcli closes this three ways: every site it creates or restores gets its user widened to `'<user>'@'%'` right away, `start`/`restart` and the core update check the sites afterwards and report "database login refused for site X" instead of a bare 500, and `db-access` is the read and the one repair.
+
+```bash
+cwcli db-access check PROJECT_NAME [--bench SELECTOR] [--json]
+cwcli db-access repair PROJECT_NAME [--bench SELECTOR] [--site NAME]... --yes [--json]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--bench`, `-b` | Bench selector (index or label) on a multi-bench instance |
+| `--site`, `-s` | `repair` only: limit the repair to these sites (default: every refused site) |
+| `--mariadb-root-password` | MariaDB root password (default: the one stored for the instance; env `CWCLI_DB_ROOT_PASSWORD`) |
+| `--yes`, `-y` | `repair` only: rename the users without asking |
+| `--json` | Machine-readable output |
+
+**Examples:**
+
+```bash
+# Which sites would be refused from the container's current address? (exit 1 if any)
+cwcli db-access check staging16
+
+# Rename each refused site's user to '%' so any container address may connect
+cwcli db-access repair staging16 --yes
+```
+
+**Output:**
+
+```
+tmpcore.localhost  _a72993d7fe8f325a@{172.99.0.9}  container 172.21.0.5  REFUSED
+```
+
+The repair is a `RENAME USER` of the host part only: the user name, password and grants are untouched, and a user already on `'%'` is left alone.
+The web UI shows the same finding on the restart or update job with a "Repair database access" button, and `cwcli axi db-access check` is the agent read.
+
+---
+
 ### `backup` - Back Up a Site
 
 Runs `bench backup` for a site inside the project's frappe container, optionally including public and private files.
@@ -1533,6 +1722,77 @@ cwcli backup my-project --bench staging --with-files
 
 ---
 
+### `backups` - The Backup Store
+
+`cwcli backup` leaves its files inside the bench.
+`cwcli backups` keeps backup sets outside every instance, under `~/.cwcli/backups/<project>/<site>/<id>/`, so they survive `cwcli rm`.
+A set is identified by its key, `project/site/id`.
+Taking a set copies the bench backup out to the host and checks every part: the database dump must be complete, the file archives must list, and the site config must parse.
+Only a fully verified set has its copies inside the bench removed, and a set that fails a check is kept and marked unverified.
+
+```bash
+cwcli backups list [PROJECT] [--site NAME] [--json]
+cwcli backups capture PROJECT [--site NAME] [--bench SEL] [--no-files] [--reason REASON] [--note TEXT] [--json]
+cwcli backups verify KEY [--json]
+cwcli backups delete KEY [--yes]
+cwcli backups restore KEY PROJECT --site NAME [--bench SEL] [--admin-password PW] [--keep-config] [--no-migrate] [--yes] [--json]
+cwcli backups transfer PROJECT --site SOURCE[:TARGET]... [--mode clone|move] [--to-project NAME] [--to-bench SEL] [--no-files] [--keep-config] [--yes] [--json]
+cwcli backups send KEY...
+cwcli backups receive TICKET [--project NAME --site NAME] [--json]
+cwcli backups download KEY [--to DIR]
+cwcli backups upload TAR [--project NAME --site NAME] [--json]
+cwcli backups drill PROJECT --site NAME [--bench SEL] [--set KEY] [--json]
+cwcli backups prune PROJECT [--dry-run] [--yes] [--json]
+cwcli backups settings PROJECT [--daily N] [--weekly N] [--monthly N] [--safety-days N] [--safety-max N] [--min-free-gb N] [--stale-after-days N] [--schedule on|off] [--daily-at HH:MM] [--copy-on-backup/--no-copy-on-backup] [--json]
+cwcli backups s3 configure [--endpoint URL] [--bucket NAME] [--access-key KEY] [--prefix P] [--region R] [--enable/--disable]
+cwcli backups s3 list|copy|fetch|prune ...
+cwcli backups key export --to FILE | import --from FILE [--replace]
+```
+
+| Subcommand | What it does |
+|------------|--------------|
+| `list` | Lists the sets, newest first, with each set's verdict and the store's disk use |
+| `capture` | Takes a verified set of one site into the store (the site defaults like `cwcli backup`); exits 1 if the set did not verify |
+| `verify` | Runs every check on a stored set again |
+| `delete` | Deletes a set; a site's last verified set is never deleted |
+| `restore` | Restores a set into a site: the same site, a new one, another bench, or another instance. It replaces all of the target site's data, so it asks first; a non-interactive session needs `--yes`. By default the set's app settings are carried over and the target's `db_*` keys are kept |
+| `transfer` | Clones (default) or moves one or more sites to another name, bench, or instance, one site at a time |
+| `send` / `receive` | Sends sets to another machine as a sendme ticket, and files a received ticket into this machine's store |
+| `download` / `upload` | Writes one set as a plain (unencrypted) tar, and files such a tar into a store |
+| `drill` | Restores the site's latest verified set into a throwaway site, checks that it answers, drops it, and records the result |
+| `prune` | Applies the instance's retention policy; `--dry-run` lists what would be removed, and removing needs `--yes` |
+| `settings` | Shows or changes the instance's retention, safety, disk floor, daily schedule, and whether new backups are copied off-site |
+| `s3` | Encrypted off-site copies in an S3 bucket (AWS, MinIO, ...): `configure`, `list`, `copy`, `fetch`, `prune`. `list`, `copy`, `fetch` and `prune` work with whichever backup target integration is on, the S3 bucket or a community one. `configure` sets up the machine's S3 backup target integration, one bucket for every instance (the web UI's Settings > Integrations); it reads the secret key from `CWCLI_S3_SECRET_KEY`, tests the bucket, and turns the target on only when the bucket answers, exiting 1 otherwise. When another integration is the backup target it refuses unless `--switch`, which turns that one off once the bucket answers. `--disable` turns it off and keeps its settings |
+| `key` | Exports or imports the key that encrypts off-site copies; restoring an off-site copy on another machine needs it |
+
+**Safety rules:**
+
+- A clone or move onto a target site that already exists asks for confirmation (the web UI asks you to type the site name), and a non-interactive session needs `--yes`. Before the target is replaced, cwcli takes a verified `before-overwrite` set of it into the store; if that set does not verify, the target is left alone.
+- A move needs `--yes`, and drops each source only after its copy answered its checks, through the same backup gate `cwcli rm-site` uses.
+- Retention keeps a site's newest verified set always, keeps safety sets (`before-*` reasons) for 14 days with at most 5 per site, and keeps the newest set of each of the last 7 days and 4 weeks (S3: 7 days, 4 weeks, 12 months). Change these with `cwcli backups settings`.
+- `prune`, the scheduled prune, and the S3 prune never delete an unverified set. An unverified set takes no retention slot and stays until you delete it with `cwcli backups delete`.
+- Apart from the daily backup you can switch on with `cwcli backups settings --schedule on`, cwcli takes an automatic backup in one case only: a core (frappe or erpnext) update started from the web UI or a schedule first takes a verified `before-core-update` set of every site on the bench, and stops before changing anything if one does not verify. `cwcli rm`, `rm-site`, and `rm-bench` also move their removal backups into the store as `before-removal` sets.
+
+```bash
+# Take a verified set of the default site, then list the store
+cwcli backups capture my-project
+cwcli backups list my-project
+
+# Restore a set into a new site on bench 1
+cwcli backups restore my-project/example.localhost/20261027_020000-b0 my-project --site copy.localhost --bench 1
+
+# Clone a site to another instance under a new name
+cwcli backups transfer my-project --site example.localhost:staging.localhost --to-project other-project
+
+# See what the retention policy would remove, then remove it
+cwcli backups prune my-project --dry-run
+cwcli backups prune my-project --yes
+```
+
+**Agent surface:** `cwcli axi backups list|capture|verify|prune|settings` is the TOON spelling.
+
+---
+
 ### `restore` - Restore Site from Backup
 
 Interactively restore a site from a backup with automatic detection of file archives and encryption keys. Supports both local restoration and peer-to-peer backup transfers via sendme.
@@ -1557,7 +1817,7 @@ cwcli restore [OPTIONS] PROJECT_NAME
 | `--bench TEXT` | Which bench to target: its numeric index or label (see [Working with Multiple Benches](#working-with-multiple-benches)) |
 | `-p`, `--path TEXT` | Explicit bench directory inside the container (lower-level alternative to `--bench`; cannot be combined with it) |
 | `--mariadb-root-username TEXT` | MariaDB root username (defaults to `root`; prompted interactively when omitted) |
-| `--mariadb-root-password TEXT` | MariaDB root password. Prompted interactively when omitted; a non-TTY without this flag refuses rather than proceeding with an empty password |
+| `--mariadb-root-password TEXT` | MariaDB root password. When omitted, the password remembered for the instance at `init` is used for the `root` user; with none remembered it is prompted interactively, and a non-TTY without this flag refuses rather than proceeding with an empty password |
 | `--admin-password TEXT` | Set administrator password after restore |
 | `--send` | **P2P Mode:** Share backup with another machine via peer-to-peer transfer |
 | `--receive` | **P2P Mode:** Receive backup from another machine via peer-to-peer transfer |
@@ -1915,15 +2175,13 @@ hint to run `cwcli start` to bring it under cwcli's supervisor. In this mode the
 per-process supervisord `state` is unavailable (there is no supervisord to ask);
 `up` comes straight from `ps`. `status` only reads - it never launches supervisord.
 
-**Maintenance mode is called out plainly.** A site stuck in maintenance mode answers
-HTTP 503 to every user with no other signal - the state a `migrate` / `apps update`
-killed mid-run (a closed terminal, a `kill`, a service stop) leaves behind. When a
-bench's site is in maintenance mode, `status` prints `MAINTENANCE MODE ON` for that
-site (even without `-v`, since it is a fault, not detail) and names the way out
-(`cwcli run <project> --site <site> set-maintenance-mode off`); `cwcli axi status`
-carries it as `maintenance_mode` plus a `status.maintenance_mode` warning. It is read
-live from the site's `site_config.json`, not inferred from the 503, and is skipped in
-the `--watch` loop (which makes no web probe).
+**Maintenance mode is called out plainly.**
+A site stuck in maintenance mode answers HTTP 503 to every user with no other signal - the state a `migrate` / `apps update` killed mid-run (a closed terminal, a `kill`, a service stop) leaves behind.
+When a bench's site is in maintenance mode, `status` prints `MAINTENANCE MODE ON` for that site (even without `-v`, since it is a fault, not detail) and names the way out (`cwcli run <project> --site <site> set-maintenance-mode off`); `cwcli axi status` carries it as `maintenance_mode` plus a `status.maintenance_mode` warning.
+It is read live the way Frappe reads it, not inferred from the 503: the bench's `sites/common_site_config.json` first, with the site's own `site_config.json` overriding it.
+A failed `bench update` (the `cwcli apps update <project> frappe` path) leaves `maintenance_mode` and `pause_scheduler` set in that bench-wide file, which holds down every site on the bench that does not override them.
+`status` reports each one it finds there (`status.maintenance_mode` and `status.scheduler_paused`) with the bench-wide way out, `cwcli run <project> set-config --global --parse maintenance_mode 0` (and the same for `pause_scheduler`); `set-maintenance-mode off` would bring back only the one site.
+These reads are skipped in the `--watch` loop (which makes no web probe).
 
 **Per-bench, per-process detail (stderr):** one sub-block per bench, headed by its
 index, path, label, and own aggregate, with a web line naming the host-reachable
@@ -1960,6 +2218,212 @@ cwcli status -w --interval 5 frappe-one   # refresh every 5s
 
 ---
 
+### `ui` - Open the Web UI
+
+Opens a local browser dashboard over your instances: every instance, bench, site and app in one place, live process health, a resumable log pane, Settings (with the `doctor` health check inside it), a command palette (Ctrl+K) that searches the cache, and the everyday lifecycle actions.
+Long work runs as detached jobs with a durable event log, so it continues when the tab closes and can be opened again from Jobs.
+A failed job has a Retry button on its page that starts a new job with the same settings, so a creation that failed at the image pull continues from the project directory it left behind.
+The passwords entered for a job are kept in the daemon's memory only (never in the job record or on disk) so Retry, and answering a decision the job stopped on, can reuse them; if the daemon has restarted, a creation reopens the form on its password step instead.
+A retry never carries a destructive confirmation over: a removal asks for its typed name again, and a job that discards local work (`apps checkout --reset`, `apps update --force`) has no Retry and must be started again to confirm it.
+A job that was interrupted, whose process vanished, that lost the output stream of a command inside the instance, or an `apps update` with a step whose outcome is unknown, has no Retry either, because its work may still be running inside the instance; its page says to review the last event before running it again.
+The daemon binds `127.0.0.1` only and is served by cwcli itself; nothing is installed or fetched, and no Node is needed because the UI ships prebuilt inside the package.
+
+```bash
+cwcli ui [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-p`, `--port INTEGER` | Port to listen on (default: 8765) |
+| `--foreground` | Run the daemon in this terminal (Ctrl-C to stop) instead of detached |
+| `--stop` | Stop the detached daemon |
+| `--no-browser` | Print the address instead of opening a browser |
+
+**How it runs:** `cwcli ui` starts the daemon detached if none is running (otherwise it reuses the live one, unless cwcli was reinstalled since that daemon started, in which case it restarts it onto the new code), then opens your browser on `http://127.0.0.1:8765/`.
+It also starts auto-inspect or the credential bridge when either is enabled with its boot unit but not running, and says so, or says why it could not.
+The page asks for the **administrator account**: the username is `admin` and the first password is `admin`, and that first sign-in (and every sign-in after a reset) has to choose a new password - at least 8 characters, not the default - before anything else in the UI answers.
+Sessions last 8 hours idle and 7 days at most; "Keep me signed in" makes both 30 days.
+Five failed sign-ins within ten minutes lock the address for a minute and refuse further wrong passwords for the username, while the username's correct password still signs in, so nobody can lock the owner out.
+Your account (in Settings) changes the password, lists the other signed-in browsers, signs them out, and signs out.
+Appearance (in Settings, or the sidebar's Appearance row) picks the gradient theme and light, dark or the system setting (the default), and turns the moving visual effects off; the choice is kept in this browser.
+If the password is lost, `cwcli admin reset-password` on the host puts the account back to `admin` / `admin` with the change forced again (see below).
+With LDAP / Active Directory sign-in turned on (Settings > Integrations, below), directory users sign in on the same page with their own directory password, and the local `admin` account keeps working beside them as the way in when the directory is unreachable or misconfigured.
+
+**Roles:** every signed-in person is an Admin, an Operator or a Viewer, and the daemon checks each request against the role it needs.
+A Viewer reads everything the UI shows except the contents of backup sets (no download).
+An Operator also runs the fleet: lifecycle actions, jobs, backups, transfers and schedules.
+An Admin also changes Settings, Integrations and each instance's backup settings (retention, the daily schedule and off-site copies), updates cwcli itself, and runs everything that destroys data or code: removing or moving instances, benches, sites and backup sets, restoring a set over a site, pruning local or off-site backups, checking out an app discarding local changes, and forcing an app update past its data-loss guard.
+A schedule that runs one of those (a prune) is created, changed, enabled or run by hand only by an Admin, and each scheduled run checks that the Admin who last saved it is still an Admin (a directory user is looked up in the directory again); otherwise the run is skipped and the schedule shows why.
+The local `admin` account and a programmatic client holding the bearer token are Admins; a directory user's role comes from their directory groups.
+The page hides what a role cannot do, and a request beyond the role is refused with `auth.role_forbidden`.
+Programmatic clients (scripts, the self-update restart) keep using the bearer token in `CWCLI_SERVE_TOKEN`; nothing about a sign-in is ever in a URL.
+`cwcli ui --stop` stops it.
+While the daemon runs it polls process health for every running instance; the web check only runs for an instance a page has open.
+That check is a bare TCP connect to the bench's web port, not an HTTP request, so polling writes nothing to the bench's web access log; the Bench page shows its verdict as `Listening` or `Not listening` next to the web port, or `unknown` while the latest health probe has failed and the page is showing the last successful probe's readings.
+It refuses any request whose `Host` is not this machine, so another site in your browser cannot read or drive it.
+
+**What it can do:** everything the CLI reads (`ls`, `status`, `inspect`, `where`, `doctor`, `logs`, `axi url`, `config show`) and the safe lifecycle set: start, stop and restart an instance or a bench, restart one process, set a bench label, unlock a site, take a site out of maintenance mode, widen the port range (the same core confirmation `cwcli scale` asks for, typed back as the instance name), and check out an app ref without `--reset`.
+These lifecycle changes run as jobs too, so their steps and outcome remain visible after navigation.
+When an action needs a stopped instance running, the page offers to start it first: an action on a bench, site or app starts that bench (`cwcli start <project> --bench <n>`), so a multi-bench instance never asks which bench, and an instance-level action starts only the containers, never a bench.
+Remove bench on a stopped instance starts only its containers, and stops them again if the removal does not complete.
+Restarting an instance from the page brings back exactly the benches that were serving (under cwcli's supervisor or `bench start`), unlike `cwcli restart <project>`, which brings back the first bench.
+The long-job forms cover `init`, `apps install`, `apps update`, `apps checkout`, `backup`, `migrate`, `run-tests`, `build`, `setup-wizard`, and `self-update`.
+`apps update` runs the same preflight as the CLI and shows every finding in the job view before the reset begins.
+A failed job leads with its plain cause (for example MariaDB rejecting the database root password, or git failing to authenticate) when cwcli recognizes one in the failing step's output, and otherwise says it did not and points at that output.
+Interrupt requests use the command's cleanup path; Detach only leaves the page, and an active record whose process disappears becomes `unknown` instead of being reported as failed or successful.
+On Windows a job that has not begun its cleanup five minutes after Interrupt, or has not finished it two minutes after beginning, is terminated; one that never began is marked `unknown` because its cleanup may not have run.
+Jobs keeps every active job and the 100 most recent finished ones; older finished records are pruned when a new job starts.
+The `self-update` job restarts the local daemon and the open page reloads after its protocol check sees the replacement.
+The guarded destructive verbs run as jobs too, each behind a typed confirmation of the exact name of what it destroys: remove an instance (`rm`: every site backed up first and the named volumes deletable only while the instance runs, mirroring `cwcli axi rm`, unless Force is ticked, which skips the verified backup like `cwcli rm --no-backup` after a red warning naming what is lost for good), drop a site (`rm-site`), remove a stopped bench (`rm-bench`), check out an app ref discarding local changes (`apps checkout --reset`, typed back as the app's name), and force a `frappe` update past the data-loss guard (`apps update` with Force ticked, typed back as the bench's name).
+A failed backup drops nothing, exactly as on the command line, and the job page shows bench's own reason.
+Settings is writable for an Admin: cache on/off, forget one remembered project or clear the whole cache (confirmed first), add, remove and prune bench search paths (the prune check names any stopped instance that keeps it from pruning), auto-inspect and its interval and boot hook, the persistent credential bridge and its boot unit, a Start (or Restart) button for either daemon while its feature is enabled, with the daemon log's last line shown while it is down, tips, and the agent SessionStart hooks `cwcli axi setup` installs; every control sits beside the terminal command that does the same.
+Schedules puts any of those jobs on a timetable (templates, a friendly recurrence picker with the cron underneath, one-off runs, recipes of chained steps, "after a successful job" and "when the instance starts" triggers, a week's timeline, and "Schedule this…" on every job's page); see `schedule` below.
+`cwcli restore` (the UI restores sets from the backup store instead), `apps uninstall`, `run`, `cwcli open`'s Docker shell (the UI opens VS Code, VS Code Insiders or Cursor only), an in-browser terminal, access from another machine and the shared multi-user mode are not in the UI; each needs its own decision first.
+
+**Integrations (Settings > Integrations):** connections to systems outside cwcli, each off until an Admin turns it on.
+Turning one on opens its setup, tests the connection, and turns it on only when the test passes; a change to an integration that is already on is applied only when the changed settings pass the test, so a typo never takes a working one down.
+Each integration shows one of four states: Off, Needs setup (the last attempt to turn it on failed its test), On, or Error (it is on, and its last use failed).
+Secrets are stored encrypted (AES-256-GCM) in `~/.cwcli/integrations.json` under a key in `~/.cwcli/keys/integrations.key`, both 0600; after a save the page shows only that a secret is set, and a new value replaces it.
+A change to where a secret is sent (the LDAP server URL, StartTLS, CA certificate or service account, or the S3 endpoint) is refused with `integration.secret_retype` unless the secret is typed again, so a stored secret never goes to a server it was not saved for.
+Two official integrations ship with cwcli, and an Admin can add community integrations from a repository (below).
+Each integration provides hook points that cwcli calls: **sign-in** (who may sign in to the web UI, and with which role) and **the backup target** (where encrypted off-site copies go).
+Only one integration serves a hook point at a time.
+Turning on a second one that provides it asks the Admin to choose: **Test and switch** runs the new one's test and, only if it passes, turns it on and turns the other off, keeping its settings; nothing switches silently.
+
+- **LDAP / Active Directory sign-in:** the server URL (`ldaps://` preferred, or `ldap://` with StartTLS; cwcli refuses to send passwords in clear text), the CA certificate that signed the directory's certificate (empty uses this machine's trusted CAs), Active Directory or OpenLDAP, a read-only service account and its password, the base DN, the user search filter (`{username}` is the typed name, escaped), the username, email and display-name attributes, and the allowed groups, each mapped to a role.
+  At every sign-in cwcli finds the user with the service account, reads their groups (Active Directory: nested groups too; OpenLDAP: `groupOfNames`, `groupOfUniqueNames` and `posixGroup`), checks the password by binding as the user, and refuses an account the directory reports as disabled and anyone outside the allowed groups.
+  Someone in several allowed groups gets the highest role, and a directory user can never take the local account's name.
+  Directory users have no password change in cwcli and are never asked to pick one; the usual rate limiting and lockout apply, and their jobs record their directory username.
+  The setup has a **Test connection** button and a **Look up a user** check that shows what sign-in would decide for a name (found, groups, disabled, role) without asking for a password.
+  Saving the settings or turning sign-in off signs every directory user out.
+- **S3 backup target:** one bucket (AWS, MinIO, Garage, Ceph) for every instance's encrypted off-site backup copies; the test lists the bucket and creates it when it does not exist.
+  Each instance still chooses whether its new backups are copied there (Backups > Retention and schedule, or `cwcli backups settings --copy-on-backup/--no-copy-on-backup`).
+  Upgrading from a version that set an S3 bucket per instance: cwcli turns the first such bucket (by instance name) into this integration once, and only the instances that were copying to that same bucket keep copying.
+  Copies of an instance that used a different bucket are paused, never silently: the S3 card here and the Backups page name the instance and its old endpoint and bucket until its copies are turned back on.
+  Every per-instance plaintext secret file (`~/.cwcli/backups/keys/s3-<instance>.secret`) is removed; type the secret key again in this integration if you set up that bucket here.
+  `cwcli backups s3 configure` sets up the same integration from a terminal.
+- **Community integrations:** **Add from a repository…** takes a GitHub, GitLab.com or self-hosted GitLab repository URL and an optional branch or tag.
+  cwcli fetches the repository and reads its declaration without building or running anything, then shows the trust screen: the integration's name, publisher, description, the hook points it declares, the repository, and the exact commit the branch or tag points at.
+  Nothing is installed until the Admin clicks **Install**, and then only that commit; if the branch moved in the meantime, cwcli refuses and asks for a new review.
+  A public repository needs no sign-in.
+  A private one is read with the sign-in this machine already has, the same way the credential bridge works: `gh` for GitHub, `glab` for GitLab.com and self-hosted GitLab.
+  When that sign-in is missing, the error names the command to run, for example `glab auth login --hostname gitlab.example.org`.
+  The card is marked **Community, not reviewed** and shows the repository and commit; it starts off and turns on through its own connection test like any other.
+  **Check for update** shows the installed and the latest commit with the trust screen, and **Update** installs only that reviewed commit and turns the integration off, keeping its settings and secrets, so the new code's test runs before it is on again; nothing updates by itself.
+  **Remove…** deletes the package, its settings and its secrets after the id is typed back.
+  See `integrations` below for the terminal commands, the declaration a repository needs, and where the code is installed.
+
+**Honest states:** the UI distinguishes `unknown` (not probed) from `offline`,
+labels cache-backed data as remembered versus verified, and never guesses a
+port - a site whose host port cannot be resolved reads "not serving".
+
+**Under WSL:** a Windows browser reaches `http://localhost:8765` through WSL's
+localhost forwarding; the address `cwcli ui` prints already works from there.
+
+**Example:**
+
+```bash
+cwcli ui                       # start (or reuse) and open the browser
+cwcli ui --no-browser          # print the address instead
+cwcli ui --stop                # stop the detached daemon
+cwcli ui --foreground -p 9000  # run in this terminal on port 9000
+```
+
+There is deliberately no `cwcli axi ui`: an agent does not stand up a
+browser-facing daemon.
+
+---
+
+### `admin` - The Web UI Administrator Account
+
+```bash
+cwcli admin reset-password [--username admin]
+```
+
+Recovery from the host when the web UI password is lost: the account goes back to `admin` / `admin`, the next sign-in has to choose a new password, and every signed-in browser is signed out.
+This local account always stays an Admin and always signs in with its own password, including while LDAP / Active Directory sign-in is on.
+The account store is `~/.cwcli/accounts.json` (0600; passwords are scrypt hashes, sessions are stored as hashes of their ids), or the shared state tree on a shared install, where the reset needs root like the rest of `cwcli setup`.
+There is deliberately no `cwcli axi` spelling: an agent must not reset a person's web UI credential.
+
+---
+
+### `integrations` - Community Integrations
+
+```bash
+cwcli integrations list [--json]
+cwcli integrations add URL [--ref BRANCH_OR_TAG] [--yes]
+cwcli integrations update ID [--check] [--yes]
+cwcli integrations remove ID [--yes]
+```
+
+`list` shows every integration, official and community, with its state; a community one also shows its repository, commit, publisher and who installed it.
+`add` fetches the repository (an `https://` GitHub, GitLab.com or self-hosted GitLab URL), prints what it declares and the exact commit, and installs that commit after you confirm; `--yes` confirms in a script, and without it a non-interactive run refuses.
+A public repository is read with no sign-in: cwcli switches off every git credential helper and prompt for that first attempt.
+Only when the host answers that a sign-in is required does git ask this machine's `gh` (GitHub) or `glab` (GitLab) sign-in, and a missing one fails with the command that fixes it.
+A URL that carries a user name or token is refused; cwcli stores no token.
+`update` shows the installed and the latest commit on the integration's branch or tag; `--check` stops there, otherwise it installs the latest commit after you confirm and turns the integration off until it is turned on again.
+`remove` deletes the package, its settings and its secrets.
+Every `add`, `update` and `remove` appends a line to `~/.cwcli/integrations-audit.log` with who did it, the URL and the commit.
+On a shared install only an Admin changes community integrations: root here, or an Admin in the web UI.
+There is deliberately no `cwcli axi` spelling: installing third-party code is a person's decision.
+
+A community integration is a Python package whose repository declares it in `pyproject.toml`, which cwcli reads before running anything; a repository without a valid declaration is refused before anything is installed:
+
+```toml
+[project]
+name = "cwcli-integration-localdir"
+version = "0.1.0"
+dependencies = []          # only your own; cwcli provides itself
+
+[project.entry-points."cwcli.integrations"]
+localdir = "cwcli_localdir:INTEGRATION"   # one per repository; the name is the integration's id
+
+[tool.cwcli.integration]
+name = "Local directory backup target"
+publisher = "Example Org"
+description = "Keeps off-site copies in a directory on this machine."
+provides = ["backup_target"]       # sign_in and/or backup_target
+```
+
+The entry point names a `caffeinated_whale_cli.core.integrations.Integration` (its settings fields, connection test, optional actions) whose `hooks` maps each hook point it provides to the function cwcli calls; cwcli refuses one whose id or hook points differ from the declaration or that lacks a hook's function, and shows the declared name and description.
+Once an Admin turns it on (its test runs first), cwcli calls it exactly where it calls the official integrations:
+
+- `sign_in(settings, secrets, username, password)` returns the user (a dict with `username`, `role` - `admin`, `operator` or `viewer` - and optionally `name` and `email`) or `None` for a wrong name or password.
+  It is asked for every name except the local `admin` account's, which always signs in locally; turning it off or changing it signs its users out.
+  An optional `current_role(settings, secrets, username)` lets a schedule confirm its owner is still an Admin; without it, an Admin-only schedule saved by one of its users is skipped with that reason.
+- `backup_target(settings, secrets)` returns the store off-site copies go to: an object with `location` (shown to people), `key(*parts)`, `ensure()`, `put_file(key, path)`, `put_bytes(key, data)`, `get_to_file(key, path)`, `get_bytes(key)`, `delete(key)` and `list(prefix)` (a list of `{"key": ...}`).
+  cwcli encrypts every part before it reaches the target, exactly as for the S3 bucket, and `cwcli backups s3 list/copy/fetch/prune` work with whichever target is on.
+
+A failure inside a hook reads as that integration's Error state, never as a crash: a sign-in that fails is "the directory could not check your sign-in", and a failing target is an off-site copy that failed.
+cwcli installs each package with pip into its own directory under `~/.cwcli/integrations/community/`, never into cwcli's environment or the system, using a private venv there for pip; cwcli's own packages take precedence over any copy a package brings along.
+The standalone Windows build cannot install packages.
+
+---
+
+### `schedule` - Scheduled Jobs
+
+```bash
+cwcli schedule add NAME --verb VERB --project NAME [--bench SEL] [--site NAME] [--process LABEL] (--daily HH:MM | --weekly "DAY HH:MM" | --cron "m h dom mon dow" | --at ISO) [--arg k=v]... [--allow-unattended] [--missed skip] [--start-if-stopped] [--in-window]
+cwcli schedule list [--json]
+cwcli schedule run ID
+cwcli schedule enable ID | disable ID | rm ID
+cwcli schedule daemon [--install-service]
+```
+
+A schedule starts an ordinary job on a timetable (every run is a job with `origin.schedule = <id>`, so Jobs, logs and Retry work unchanged).
+Schedulable: backup (every site or one), prune, off-site copy and prune, restore drill, app or core update, migrate, restart, one process, start, stop, stop a bench, developer mode, clear maintenance, build.
+Removals can never be scheduled.
+Backups, restarts, starts and stops run unattended freely; an update or migrate needs `--allow-unattended` (the "Allowed unattended" tick in the UI), and a scheduled core update still takes its automatic backup first.
+A missed run (the machine was off) runs once on wake unless the schedule says `--missed skip`.
+Guards at fire time: the instance's maintenance window (`--in-window`), the quiet hours, a stopped instance (started first with `--start-if-stopped`, else skipped), free disk and memory thresholds, and one job per instance at a time (retried the next minute).
+Windows, quiet hours and thresholds are set in the web UI (Schedules › Windows and guards); the store is `~/.cwcli/schedules.json`.
+The scheduler ticks inside `cwcli ui`; on a shared install `sudo cwcli schedule daemon --install-service` installs the machine-wide `cwcli-scheduler.service` so schedules fire with no UI open (both lock the store, so a slot never fires twice).
+`cwcli axi schedule list|add|run-now|remove` is the agent spelling.
+
+---
+
 ### `doctor` - Preflight Your Environment
 
 Checks whether cwcli can operate on this machine at all - Docker, cwcli's own
@@ -1980,13 +2444,6 @@ cwcli doctor [OPTIONS]
 
 **Read-only checks:** doctor never starts a container, installs anything, or
 writes a config file.
-There is one accepted shared-infrastructure exception before the checks run:
-building the command tree for `cwcli doctor` or `cwcli axi doctor` imports the
-pre-existing cache layer, which may idempotently create cwcli's private cache
-directory and apply mode `0700`.
-It does not touch project data.
-Making that initialization lazy is tracked separately as
-`cwcli-cache-dir-lazy-init`; this caveat should disappear when that lands.
 When a direct remedy is available, the finding includes the command or action
 to apply yourself.
 
@@ -1995,6 +2452,12 @@ Docker, cwcli, Storage, Transfer, and Git hosting, plus a cross-instance
 port-range collision check under Instances. Each check is `pass`, `warn`, or
 `fail`; an absent *optional* tool (sendme, `gh`, `glab`) is `warn`, never
 `fail`.
+`gh`/`glab` sign-in is checked per host the credential bridge sends to that
+tool (the bridge's allowed hosts, plus `github.com` for `gh`), and warns only
+when the tool is signed in to none of them; a signed-out host beside a
+signed-in one is listed with its `auth login --hostname` command.
+An enabled but stopped auto-inspect or credential-bridge daemon is a `warn`
+naming its start command; the web UI's Doctor view offers a Start button for it.
 
 **Exit codes:** `0` when every check is pass/warn (a warning never blocks -
 doctor is a chainable preflight gate), `1` when any check fails.
@@ -2483,7 +2946,7 @@ cwcli axi apps list frappe-one --site erp.localhost
 # prints as ONE TOON document. Blocks until it finishes (like axi backup) -
 # there is no progress stream, because an agent needs a verdict to branch on.
 cwcli axi apps update frappe-one erpnext
-cwcli axi apps update frappe-one frappe          # runs 'bench update --reset'
+cwcli axi apps update frappe-one frappe          # the core update: resets frappe alone
 
 # Put ONE branch, tag, or commit under test in an app already in the bench -
 # the gap 'apps install' (bench acquisition and site installation) and 'apps update' (the tracked
@@ -2540,6 +3003,11 @@ There is no human `cwcli url` yet.
 Use `cwcli open`'s banner for the host address and `cwcli status` for the HTTP observation.
 
 `cwcli axi apps update` blocks until the update finishes and emits ONE terminal document, exactly as `cwcli axi backup` does for a minutes-long `bench backup`: progress is deliberately not streamed, because N documents on stdout would break the one-TOON-document contract and an agent needs a verdict it can branch on rather than a progress bar (use `cwcli logs`/`cwcli status --watch` if you want live progress). Its exit code is `0` only when the report's `ok` is true; any failed phase, any stuck site, or any unknown outcome exits `1`, and an ambiguous multi-bench project is a `--bench` usage error (exit 2). A stopped project is likewise a usage error pointing at `cwcli start` (exit 2) - there is deliberately no `--yes` on this verb, because starting a container is UI-coupled and the core stays UI-pure about it, so an agent composes `cwcli axi start` then this verb, exactly as `cwcli axi unlock`/`cwcli axi backup` already document. **`failed_*` and `unknown_*` are not the same thing and must not be collapsed:** a `failed_*` item ran and failed, so retrying it is safe, while an `unknown_*` item's output stream was lost - its exit code is unknowable and **it may still be running**, so retrying it (a migration above all) can do real harm. Check before retrying. There is deliberately no `cwcli axi update`: the deprecated `cwcli update` spelling does not get an agent-facing verb. JSON output stays on the human commands (`cwcli ls --json`, `cwcli where --json`, `cwcli apps update --json`). `--force` is available here too and is **destructive**: an app whose git update hits a conflict is hard-reset to its remote tracking branch (discarding local changes) so the update completes, reported in the `force_reset_apps` field; it fires only on a conflict and never on a non-conflict failure.
+Updating `frappe` runs the same preflight as the human command before the core reset.
+Its findings are the `preflight` table (`severity,code,app,site,message,remedy`); branch on `code`, never on the message.
+A blocker sets `preflight_blocked: true` and exits 1 with nothing run, and `--no-preflight` is available here too, because it skips predictions rather than a safety gate.
+The data-loss guard runs here too, under `--no-preflight` as well: uncommitted or unpushed work in any app (or work that could not be checked) sets `data_loss_refused: true`, names the apps in `data_loss_apps`, and exits 1 with nothing run.
+`--force` accepts the loss; the reset then runs and `data_loss_apps` names the apps it was allowed to discard work in.
 
 `cwcli axi apps list` is the read that answers what is *on* the bench `cwcli axi benches` names: the bench's available apps, and with `--installed`/`--site` which apps are installed on which site (only the app name, never the version column `bench list-apps` prints). A site whose read FAILED is reported as `null` and exits `1`, never as an empty list - "has no apps" and "could not tell" are different facts, and only one of them is safe to act on. Like every other bench-scoped verb it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start` (exit 2). **`cwcli axi apps uninstall` deliberately does not exist:** letting an agent drop the tables of a real site is a product decision that deserves its own evidence, not something settled as a side effect of moving code onto the logic core. Use the human `cwcli apps uninstall` (it has `--json` and honest exit codes) until that decision is taken. `cwcli axi apps install` was held under that same shared rationale and now exists, scoped to the half of it that rationale never covered - see below.
 
@@ -2571,7 +3039,7 @@ It exits non-zero if a restart fails or the named site does not answer Frappe's
 
 `cwcli axi migrate <project>` runs `bench migrate` against **exactly one site**, under maintenance mode. It is the migrate on its own: `cwcli axi apps update` migrates too, but only as the tail of a `git pull` across every named app, so an agent that has just pinned a feature branch with `axi apps checkout` cannot use it without a pull that moves the ref it pinned. Understand what it does before pointing an agent at it: it applies every pending schema patch from every installed app to that site's **live database**, altering tables and running patch code the apps ship. It is not transactional across patches, so one that fails partway leaves the database partially migrated, and there is no rollback - recovery is from a backup. It deliberately does not take one for you (`apps update` does not either, and a backup you did not ask for is not a guard); run `cwcli axi backup <project> --site <site>` first when the data matters. Its guards each protect against something named: it resolves **one** site (explicit `--site`, else the bench default) and never fans out, so it cannot migrate a site you did not name, and the resolved site is in the output so you can always read back what it touched; a genuinely held migrate lock refuses the operation before maintenance mode is touched and names the matching `cwcli unlock` command; maintenance mode is then enabled, and a **failed enable refuses the migrate** rather than running it against a live-serving site; the disable runs even if the migrate blows up, and a site left in maintenance is reported as `maintenance_left_on` and fails the command, because that site is down. There is no `--skip-maintenance` and no `--yes` - a stopped project is a usage error pointing at `cwcli start`. bench's own output goes to stderr in full: the patch that failed names itself there and nowhere else.
 
-`cwcli axi run-tests <project> --site <site> --app <app>` runs that app's test suite against that site. **Both flags are required and neither has a default**, which is a deliberate break from `axi backup`, `axi unlock`, and `axi migrate` - they all fall back to the bench's default site. The reason is what this command actually is: it imports and executes the app's own test modules inside the container, against the named site's live database, and cwcli cannot bound what that code does because it *is* your repository's code. A Frappe test suite creates, modifies, and deletes records. Honestly stated, it is arbitrary Python from the repo under test, run against a live site - so point it at a dedicated test site. cwcli cannot tell a test site from one holding real data, so that is a practice it can state and not enforce. Making you name the site is the cheapest way to keep "I am willing for this site to be written to" an explicit act; requiring `--app` stops a bare run from executing every installed app's suite, Frappe's own included. This is **not** the general command passthrough cwcli deliberately does not offer: the difference is who writes the command. There is no `cwcli axi run`, and there will not be one - here you select an app whose tests already exist in the bench, and no flag on this command can express a second command. The runner's output goes to stderr in full and unparsed; cwcli reports only the honest pass/fail, because it does not own your test runner's output format.
+`cwcli axi run-tests <project> --site <site> --app <app>` runs that app's test suite against that site. **Both flags are required and neither has a default**, which is a deliberate break from `axi backup`, `axi unlock`, and `axi migrate` - they all fall back to the bench's default site. The reason is what this command actually is: it imports and executes the app's own test modules inside the container, against the named site's live database, and cwcli cannot bound what that code does because it *is* your repository's code. A Frappe test suite creates, modifies, and deletes records. Honestly stated, it is arbitrary Python from the repo under test, run against a live site - so point it at a dedicated test site. cwcli cannot tell a test site from one holding real data, so that is a practice it can state and not enforce. Making you name the site is the cheapest way to keep "I am willing for this site to be written to" an explicit act; requiring `--app` stops a bare run from executing every installed app's suite, Frappe's own included. This is **not** the general command passthrough cwcli deliberately does not offer: the difference is who writes the command. There is no `cwcli axi run`, and there will not be one - here you select an app whose tests already exist in the bench, and no flag on this command can express a second command. The runner's output goes to stderr in full and unparsed; cwcli reports only the honest pass/fail, because it does not own your test runner's output format. That pass/fail does not trust the exit code alone: Frappe v14/v15 exit 0 on a failed suite unless `CI` is set, so a run whose output ends in unittest's `FAILED (...)` summary, or that Frappe refused because `allow_tests` is off on the site, reports `ok: false`, exits non-zero, and names the reason.
 
 `--module <dotted.path>` narrows a run to one test module. It only ever reduces what runs, so unlike `--site` and `--app` it needs no guard of its own; it exists because iterating on a single failing module is the common case, and without it that dropped back to a raw `cwcli run`.
 
@@ -2579,7 +3047,11 @@ It exits non-zero if a restart fails or the named site does not answer Frappe's
 
 These are agent-only for now: there is no human `cwcli migrate`, `cwcli run-tests`, or `cwcli build` yet. Use `cwcli run <project> --site <site> migrate` for the human equivalent.
 
-`cwcli axi init` provisions a new instance, bench, and site the way `cwcli init` does, but non-interactively and as ONE terminal TOON document. It **blocks** for the full 10-20 minute run - the same block-and-emit-one-document shape as `cwcli axi apps update`, because a progress stream would break the one-TOON-document contract - narrating coarse phase labels to stderr; run `cwcli logs <project>` / `cwcli status <project>` from a second shell for live progress. Running several `axi init` calls in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout. After the bench+site is created, it starts the bench's dev services by default (the same `core.start` behind `cwcli start`/`cwcli axi start`), leaving a running bench rather than a created-but-idle one; `--no-start` creates without starting, for automation/CI, distinct from Docker container startup (stage 1 always brings the containers up regardless of this flag). A dev-services start failure degrades to a stderr warning rather than a non-zero exit, since the bench was already created. The site administrator password comes from the **`CWCLI_ADMIN_PASSWORD` environment variable (recommended)** or `--admin-password`; the flag wins if both are set, and with neither set the verb refuses with a usage error (exit 2) naming both - it never generates a password and never prompts. The env var keeps the secret off the process argv (visible in `ps`/shell history) that the flag exposes; the container-side `bench new-site` still receives it, so treat the value as one-time. The MariaDB root password takes the same shape via `CWCLI_DB_ROOT_PASSWORD` / `--db-root-password` (default `123`). The interactive decisions the human `cwcli init` prompts for become non-prompting errors: an existing bench with neither `--reuse-bench` nor `--no-reuse-bench` is a usage error (exit 2) naming both; a port conflict names `--port` (exit 1); containers that do not come up point at `cwcli status`/`cwcli logs` (exit 1); an invalid `--uid` (0, negative, or non-numeric) is rejected before any container work. `--uid` behaves as it does on `cwcli init` (including the root-host fallback, whose one-time warning is folded into the report's `warnings`). There is no `--auto-start` (compose `cwcli axi start` then re-run) and no `--verbose` (stdout is always TOON). `--bench` here is the NAME of the bench to create, distinct from the `--bench <index|label>` selector the other verbs use.
+`cwcli axi setup-wizard <project> <site> [--country <country>] [--currency <currency>] [--timezone <timezone>]` headlessly completes a site's Frappe setup wizard. A fresh site - whether created by `cwcli init`/`cwcli axi init` without `--complete-setup`, or by a bare `bench new-site` outside cwcli entirely - is left in the setup-wizard state: `frappe.is_setup_complete()` is `false` and the `desktop:home_page` default stays `setup-wizard`, so a non-System-Manager desk renders with no navbar. This runs the same whitelisted RPC a person finishing the wizard in a browser triggers - `frappe.desk.page.setup_wizard.setup_wizard.setup_complete`, called via `bench execute ... --kwargs` with the args dict the wizard UI would have submitted (System Settings' country/currency/timezone/language; omitted flags fall back to `United States`/`USD`/`UTC`/`English`). It is **idempotent by Frappe's own design**: `setup_complete` checks `frappe.is_setup_complete()` first and no-ops under an advisory lock when the site is already set up, so re-running it is always safe - the report's `already_complete` field says whether it found the site already done. No user is created: `email`/`full_name`/`password` are deliberately left out of the args dict, so the `Administrator` account `cwcli init`'s `--admin-password` already provisioned is left untouched. Like the other bench-scoped verbs it takes `--bench`, has no `--yes`, and reports a stopped project as a usage error naming `cwcli start`.
+
+`cwcli axi init` provisions a new instance, bench, and site the way `cwcli init` does, but non-interactively and as ONE terminal TOON document. It **blocks** for the full 10-20 minute run - the same block-and-emit-one-document shape as `cwcli axi apps update`, because a progress stream would break the one-TOON-document contract - narrating coarse phase labels to stderr; run `cwcli logs <project>` / `cwcli status <project>` from a second shell for live progress. Running several `axi init` calls in parallel can OOM-kill the host on a memory-constrained machine - serialize them instead. Adding a bench to an already-running instance never disturbs it or its other benches: the frappe container is never pulled, recreated, or restarted, so every already-serving bench keeps running throughout. Re-running init against a stopped instance starts its existing containers as they are, without pulling images or recreating them, so its benches keep their Python environments. If the re-run would change that instance's compose settings, such as a different `--port` on an instance still on the default port range (8000-8005), init refuses with exit 1 (`instance.settings_changed`), leaves the compose file unchanged, and names each change; remove the instance with `cwcli rm` (which backs it up) and run init again, or rerun init without the changed options. For an instance created on another `--port` or widened by `cwcli scale`, init does not compare `--port`. An instance whose frappe container has never started, such as one left by a first init that failed at `docker compose up`, has no bench to protect, so init neither refuses nor uses `--no-recreate` there: it pulls images and recreates the containers with the new options. After the bench+site is created, it starts the bench's dev services by default (the same `core.start` behind `cwcli start`/`cwcli axi start`), leaving a running bench rather than a created-but-idle one; `--no-start` creates without starting, for automation/CI, distinct from Docker container startup (stage 1 always brings the containers up regardless of this flag). A dev-services start failure degrades to a stderr warning rather than a non-zero exit, since the bench was already created. The site administrator password comes from the **`CWCLI_ADMIN_PASSWORD` environment variable (recommended)** or `--admin-password`; the flag wins if both are set, and with neither set the verb refuses with a usage error (exit 2) naming both - it never generates a password and never prompts. The env var keeps the secret off the process argv (visible in `ps`/shell history) that the flag exposes; the container-side `bench new-site` still receives it, so treat the value as one-time. The MariaDB root password takes the same shape via `CWCLI_DB_ROOT_PASSWORD` / `--db-root-password` (default: the instance's remembered password, else `123`); on a new instance it becomes MariaDB's own root password, as on `cwcli init`. The interactive decisions the human `cwcli init` prompts for become non-prompting errors: an existing bench with neither `--reuse-bench` nor `--no-reuse-bench` is a usage error (exit 2) naming both; a port conflict names `--port` (exit 1); containers that do not come up point at `cwcli status`/`cwcli logs` (exit 1); an invalid `--uid` (0, negative, or non-numeric) is rejected before any container work. `--uid` behaves as it does on `cwcli init` (including the root-host fallback, whose one-time warning is folded into the report's `warnings`). There is no `--auto-start` (compose `cwcli axi start` then re-run) and no `--verbose` (stdout is always TOON). `--bench` here is the NAME of the bench to create, distinct from the `--bench <index|label>` selector the other verbs use.
+
+`--complete-setup` runs the new site's Frappe setup wizard headlessly right after creation - the same operation `cwcli axi setup-wizard` performs standalone, sharing its exact implementation - so a fresh site does not land in the unfinished setup-wizard state a non-System-Manager desk renders with no navbar in. `--country`/`--currency`/`--timezone` tune it (require `--complete-setup`; each has a sensible default when omitted) and are usage errors on their own. Its outcome rides as a `setup_wizard` block inside the SAME `InitReport` document, not a second one; a failure there is never exit `0` even though the bench and site above it were already created successfully - the `setup_wizard` block still carries what happened.
 
 `cwcli axi rm <project> --yes` permanently removes an instance: its containers, named volumes (databases, sites, and files), own Docker Compose network, and local project directory.
 It is the agent form of `cwcli rm`, and it runs the same code.
@@ -2602,9 +3074,11 @@ There is deliberately **no `--no-backup`** here. That flag turns off the one gua
 `cwcli axi rm-site <project> <site> --yes` permanently drops ONE site - its database and its files - leaving the instance and every other site on it running.
 It is the per-site inverse of `cwcli axi init`: a workflow that creates a new site per task on a shared, already-running bench needs a way to drop it again at teardown, and unlike `cwcli axi rm` it carries none of the whole-instance blast radius, so it needs none of that verb's deferral history.
 `--yes` is required and means consent only, same as `cwcli axi rm`; there is no auto-start, so a stopped project is a usage error naming `cwcli start` (exit 2), exactly like every other bench-scoped verb.
-`bench drop-site` archives the dropped site's full directory - including `site_config.json` and its database credentials - inside the container's own `archived/sites/` folder before this verb ever sees it; left there it would grow, unpruned, forever.
-So this immediately copies that one archive out to the same managed host location `cwcli rm` uses (`archived_host_path` in the TOON report) and, only once that copy is verified on disk, deletes the in-container copy (`archive_pruned_in_container: true`).
-If the copy could not be verified, the in-container archive is left in place rather than deleted unbacked, and `ok: false` plus a warning names exactly what remains - a caller that only checks the exit code still learns its site's credentials may not be safely out of the container.
+The site is backed up before it is dropped, with the same verified gate `cwcli axi rm` uses: `bench backup --with-files`, this run's database dump and file archives copied out to the managed host archive, and the dump checked non-empty there.
+If that fails, nothing is dropped, and the error (exit 1) carries bench's own output.
+`bench drop-site --no-backup` then archives the dropped site's full directory - including `site_config.json` and its database credentials - inside the container's own `archived/sites/` folder; left there it would grow, unpruned, forever.
+So this copies that one archive out beside the verified backup (`archived_host_path` in the TOON report holds both) and, only once that copy is verified on disk, deletes the in-container copy (`archive_pruned_in_container: true`).
+If anything could not be verified, the in-container archive is left in place rather than deleted unbacked, and `ok: false` plus a warning names exactly what remains - a caller that only checks the exit code still learns it.
 
 #### Making agents aware of the surface
 
@@ -2710,6 +3184,7 @@ The CLI uses:
 - **Cache**: `~/.cwcli/cache/cwc-cache.db` - Project inspection cache
 - **Runtime**: `~/.cwcli/run/` - PID and log files for background services
 - **Archive**: `~/.cwcli/archive/` - Pre-deletion backups and config snapshots from `cwcli rm`, plus dropped-site archives from `cwcli rm-site` and `cwcli rm-bench`
+- **Backups**: `~/.cwcli/backups/<project>/<site>/<id>/` - The backup store managed by [`cwcli backups`](#backups---the-backup-store), outside every instance
 - **Transfers**: `~/.cwcli/tmp/` by default, or `$TMPDIR/cwcli/`, `$TEMP/cwcli/`, or `$TMP/cwcli/` when the first non-empty variable in that order is set. Temporary files used by `restore --send` and `restore --receive`; each attempt is removed when it finishes or fails
 
 **Relocating cwcli's data (`CWCLI_HOME`):**