fix: fail closed on unusable Codex auth during sandbox auth merge

When reusing a Codex sandbox, the workspace-restore step now performs
an auth-merge check before adopting the sandbox's auth.json. The merge
fails closed when:

- host or sandbox Codex auth is unusable (missing token or account)
- the subscription payload shapes differ between host and sandbox
- subscription account identities do not match

Additional hardening: node absence on PATH during the embedded decision
script now exits non-zero instead of silently falling through. Co-change
comments link parseAuth (the embedded script) to hasUsableAuthPayload
(codex-home.ts) so a future auth-format change cannot silently diverge
between the two implementations.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

docs/cli/setup-commands.md

@@ -0,0 +1,131 @@
+---
+title: Setup Commands
+summary: Onboard, run, doctor, and configure
+---
+
+Instance setup and diagnostics commands.
+
+## `paperclipai run`
+
+One-command bootstrap and start:
+
+```sh
+pnpm paperclipai run
+```
+
+Does:
+
+1. Auto-onboards if config is missing
+2. Runs `paperclipai doctor` with repair enabled
+3. Starts the server when checks pass
+
+Choose a specific instance:
+
+```sh
+pnpm paperclipai run --instance dev
+```
+
+## `paperclipai onboard`
+
+Interactive first-time setup:
+
+```sh
+pnpm paperclipai onboard
+```
+
+If Paperclip is already configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to change settings on an existing install.
+
+First prompt:
+
+1. `Quickstart` (recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)
+2. `Advanced setup`: full interactive configuration
+
+Start immediately after onboarding:
+
+```sh
+pnpm paperclipai onboard --run
+```
+
+Non-interactive defaults + immediate start (opens browser on server listen):
+
+```sh
+pnpm paperclipai onboard --yes
+```
+
+On an existing install, `--yes` now preserves the current config and just starts Paperclip with that setup.
+
+## `paperclipai doctor`
+
+Health checks with optional auto-repair:
+
+```sh
+pnpm paperclipai doctor
+pnpm paperclipai doctor --repair
+```
+
+Validates:
+
+- Server configuration
+- Database connectivity
+- Secrets adapter configuration, including AWS Secrets Manager non-secret env
+  config when selected
+- Storage configuration
+- Missing key files
+
+## `paperclipai configure`
+
+Update configuration sections:
+
+```sh
+pnpm paperclipai configure --section server
+pnpm paperclipai configure --section secrets
+pnpm paperclipai configure --section storage
+```
+
+`--section secrets` updates the deployment-level provider used as the fallback
+for secrets that do not target a specific company vault. Per-company provider
+vaults (named instances, default vault selection, multiple vaults per provider,
+coming-soon GCP/Vault) live in the board UI under
+`Company Settings → Secrets → Provider vaults` and the
+`/api/companies/{companyId}/secret-provider-configs` API.
+
+## `paperclipai env`
+
+Show resolved environment configuration:
+
+```sh
+pnpm paperclipai env
+```
+
+This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` and `PAPERCLIP_BIND_HOST` when configured.
+
+## `paperclipai allowed-hostname`
+
+Allow a private hostname for authenticated/private mode:
+
+```sh
+pnpm paperclipai allowed-hostname my-tailscale-host
+```
+
+## Local Storage Paths
+
+| Data | Default Path |
+|------|-------------|
+| Config | `~/.paperclip/instances/default/config.json` |
+| Database | `~/.paperclip/instances/default/db` |
+| Logs | `~/.paperclip/instances/default/logs` |
+| Storage | `~/.paperclip/instances/default/data/storage` |
+| Secrets key | `~/.paperclip/instances/default/secrets/master.key` |
+
+Override with:
+
+```sh
+PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
+```
+
+Or pass `--data-dir` directly on any command:
+
+```sh
+pnpm paperclipai run --data-dir ./tmp/paperclip-dev
+pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev
+```