fix: audit the docs against source instead of one review round at a time

Eight review rounds kept finding defects because I was patching what the last
round flagged and writing new prose in the process, which nothing then checked.
This is a full pass over the Compose files, the sim-setup CLI, and the chart.

The mirror inventory (Greptile's blocker): the bare device-plugin override
changes where the chart pulls from, to `<registry>/nvidia/k8s-device-plugin`,
while the inventory tells operators to mirror to `<registry>/nvcr.io/nvidia/...`.
Following both instructions produced an unpopulated path. Verified by rendering
the chart both ways; the header now names the override's destination.

Compose:
- Nine `docker compose` commands across troubleshooting, verify, and
  background-jobs had no `-f`. The repo ships no default compose file, so every
  one of them failed with "no configuration file provided".
- `simstudio` declares `env_file: .env` in all three files, so the LM Studio
  fix does not need a hand-edited `environment:` block — and hand-editing a
  managed Compose file makes `sim-setup update` refuse.
- `OLLAMA_URL` as a one-shot shell prefix reverts to the localhost default on
  the next `up -d`, pointing the container at itself. It belongs in `.env`.
- `pg_dump` through `exec` without `-T` corrupts the dump; the restore beside
  it already used `-T`.
- Live cross-process status is a Redis consequence, not a cron one.
- The local Compose file was missing from three "the file that started your
  install" lists and from the exposed-Postgres warning.
- No shipped Compose file defines a `pii` service.
- The rollback said "edit .env" but appended a second SIM_VERSION line.

sim-setup CLI — the table stated Compose behavior as universal:
- `down` runs `helm uninstall` on Kubernetes and removes only Postgres and
  Redis on a source checkout; both prompt first.
- `reset` archives four env files on anything but Compose, including when no
  install is detected.
- `--no-open` was described backwards: the link always prints, the flag skips
  the download prompt.
- `start`/`restart` print port-forward hints on Kubernetes, not equivalents.
- `--dir` is a global option and scopes the lifecycle commands.
- `--quick` only preselects the setup style; `add` and `desktop` have refusals
  worth knowing; the update hand-edit refusal is narrower than stated.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015BwsJTEQRzWJaY4BRCkPZt

Author: waleedlatif1

apps/docs/content/docs/platform/enterprise/data-retention.mdx

@@ -216,7 +216,8 @@ PII redaction runs against a standalone [Presidio](https://microsoft.github.io/p
 # Helm — setting pii.enabled wires this for you. Set it by hand only for an
 # external Presidio, substituting your release name and namespace.
 PII_URL=http://<release>-pii.<namespace>.svc.cluster.local:5001
-# Docker Compose — the PII service name on your network
+# Docker Compose — no shipped file defines a PII service. Add one to the
+# same project, then use its service name.
 # PII_URL=http://pii:5001
 ```
 

apps/docs/content/docs/platform/self-hosting/background-jobs.mdx

@@ -127,7 +127,7 @@ To drop a job you do not need, comment out its line in `docker/crontab` and rest
 
 Create a workflow with a Schedule trigger set to every minute, deploy it, and watch the Logs view. An execution should appear within ~2 minutes. If nothing appears:
 
-1. Check the scheduler's own logs — `docker compose logs cron`, or `kubectl get cronjobs -n simstudio` for a recent `LAST SCHEDULE`.
+1. Check the scheduler's own logs — `docker compose -f docker-compose.prod.yml logs cron`, or `kubectl get cronjobs -n simstudio` for a recent `LAST SCHEDULE`.
 2. Confirm the app and the scheduler share the same `CRON_SECRET`. A mismatch shows up as `401` in the scheduler log.
 3. A `202` means the endpoint accepted the run; it does not confirm a schedule was due, so check the Logs view.
 

apps/docs/content/docs/platform/self-hosting/docker.mdx

@@ -100,7 +100,7 @@ For nginx, Traefik, or a cloud load balancer — and for the GKE websocket timeo
 
 ## Ollama
 
-`docker-compose.ollama.yml` is a **development** stack, not a drop-in swap for `docker-compose.prod.yml`. It builds `simstudio`, `realtime`, and `migrations` from the source checkout instead of pulling published images, and it ships neither a `redis` service nor a `cron` service. Without an external Redis, pub/sub falls back to a process-local emitter and CLI authentication stops working entirely, since its approval store has no fallback; the idempotency store and execution progress markers do fall back to Postgres. And with no cron service, live cross-process status and every [background job](/platform/self-hosting/background-jobs) are missing. For production with local models, keep `docker-compose.prod.yml` and point `OLLAMA_URL` at an Ollama instance, as under [External Ollama](#external-ollama) below.
+`docker-compose.ollama.yml` is a **development** stack, not a drop-in swap for `docker-compose.prod.yml`. It builds `simstudio`, `realtime`, and `migrations` from the source checkout instead of pulling published images, and it ships neither a `redis` service nor a `cron` service. Without an external Redis, pub/sub falls back to a process-local emitter and CLI authentication stops working entirely, since its approval store has no fallback; the idempotency store and execution progress markers do fall back to Postgres. And with no cron service, every [background job](/platform/self-hosting/background-jobs) is missing. For production with local models, keep `docker-compose.prod.yml` and point `OLLAMA_URL` at an Ollama instance, as under [External Ollama](#external-ollama) below.
 
 Always pass a server profile alongside `setup`. With `--profile setup` on its own no Ollama server starts and `model-setup` waits forever.
 
@@ -125,12 +125,18 @@ docker compose -f docker-compose.ollama.yml exec ollama-cpu ollama pull llama3.2
 
 If Ollama runs on your host machine (not in Docker):
 
+Set it in the `.env` next to your Compose file. A one-shot shell prefix satisfies the interpolation for that command only, so the next `up -d` silently reverts to the `http://localhost:11434` default and the container points at itself:
+
 ```bash
-# macOS/Windows
-OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d
+# .env — macOS/Windows
+OLLAMA_URL=http://host.docker.internal:11434
 
 # Linux - use your host IP
-OLLAMA_URL=http://192.168.1.100:11434 docker compose -f docker-compose.prod.yml up -d
+# OLLAMA_URL=http://192.168.1.100:11434
+```
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
 ```
 
 <Callout type="warn">
@@ -156,27 +162,30 @@ Both the server root shown above and a URL ending in `/v1` are accepted. After r
 ```bash
 # Pick the file that started your install.
 COMPOSE_FILE=docker-compose.prod.yml
+# COMPOSE_FILE=docker-compose.local.yml
 # COMPOSE_FILE=docker-compose.ollama.yml
 docker compose -f "$COMPOSE_FILE" up -d --force-recreate simstudio
 ```
 
 ## The `sim-setup` CLI
 
-`npx sim-setup` also manages an existing install created from the production or local-development Compose files. It does not detect or manage an Ollama-stack install. Run it from the directory holding your `.env` and Compose file. The table drops the `npx` prefix for brevity — keep it unless you installed the package globally.
+`npx sim-setup` also manages an existing install created from the production or local-development Compose files. It does not detect or manage an Ollama-stack install. Run `doctor`, `config`, and the wizard from the directory holding your `.env` and Compose file; the lifecycle commands find a running stack wherever it was started. The table drops the `npx` prefix for brevity — keep it unless you installed the package globally.
 
 | Command | What it does |
 |---|---|
-| `sim-setup` | The setup wizard. `--quick` skips the prompts, `--dir <path>` picks the directory, `--mode compose\|dev\|k8s` picks the target (`dev` and `k8s` need a source checkout) |
+| `sim-setup` | The setup wizard. `--quick` takes the defaults and asks only the essential questions, `--mode compose\|dev\|k8s` picks the target (`dev` and `k8s` need a source checkout) |
 | `sim-setup status` | Show what is installed and healthy |
-| `sim-setup logs` | Follow logs. On a source checkout it prints where the logs are — the dev server streams in its own terminal — rather than following a stream |
-| `sim-setup start` / `stop` / `restart` | Bring the install up, down, or cycle it. On a source checkout this covers only the managed Postgres and Redis containers — the dev server is yours to start and stop. On Kubernetes it prints the equivalent `kubectl` commands instead of acting |
+| `sim-setup logs` | Follow logs. On Kubernetes it follows the app deployment only; on a source checkout it prints where the logs are — the dev server streams in its own terminal — rather than following a stream |
+| `sim-setup start` / `stop` / `restart` | Bring the install up, down, or cycle it. On a source checkout this covers only the managed Postgres and Redis containers — the dev server is yours to start and stop. On Kubernetes it acts on nothing: `stop` prints the `kubectl scale` equivalents, and `start` and `restart` print the port-forward commands for reaching the release |
 | `sim-setup update` | Pull or rebuild images and apply them. Compose installs only — it refuses on source checkouts and Kubernetes, which update through git and `helm upgrade` |
-| `sim-setup down` | Remove containers, keep the data |
-| `sim-setup reset` | Archive `.env` and wipe managed data. On Kubernetes it runs `helm uninstall`, which leaves the Postgres volumes behind — they come from a StatefulSet's `volumeClaimTemplates`, which Kubernetes never deletes. Delete those PVCs yourself to reset the data |
+| `sim-setup down` | After a confirmation prompt, remove containers and keep the data. On a source checkout it removes only the managed Postgres and Redis containers, keeping their volume. On Kubernetes it runs `helm uninstall` on the whole release |
+| `sim-setup reset` | After a confirmation prompt, archive the env files and wipe managed data. A Compose install archives the `.env` beside its Compose file; a source checkout, a Kubernetes install, and an invocation with no install detected all archive `apps/sim/.env`, `apps/realtime/.env`, `packages/db/.env`, and the root `.env`. On Kubernetes it runs `helm uninstall`, which leaves the Postgres volumes behind — they come from a StatefulSet's `volumeClaimTemplates`, which Kubernetes never deletes. Delete those PVCs yourself to reset the data |
 | `sim-setup config` | Show configured capabilities and integrations |
 | `sim-setup doctor` | Check the setup. `--fix` repairs what it can, `--json` prints machine-readable output |
-| `sim-setup add <feature>` | Configure one capability: `email`, `storage`, `sandbox`, `jobs`, `cache`, `knowledge`, `knowledge-embeddings`, `chat`, `llm`, or `integration <slug>` |
-| `sim-setup desktop` | Resolve the desktop installer for this deployment. `--url <url>` skips discovery, `--no-open` prints the link instead of opening it |
+| `sim-setup add <feature>` | Configure one capability: `email`, `storage`, `sandbox`, `jobs`, `cache`, `knowledge`, `knowledge-embeddings`, `chat`, `llm`, or `integration <slug>`. Writes to the `.env` beside your Compose file — recreate the app container to apply — or to `apps/sim/.env` on a source checkout. It refuses when no configuration is writable, when more than one is, and for Helm releases |
+| `sim-setup desktop` | Resolve the desktop installer for this deployment. `--url <url>` skips discovery, and is required when several detected configurations name different `NEXT_PUBLIC_APP_URL` origins. `--no-open` skips the "Download it now?" prompt — the link is printed either way |
+
+`--dir <path>` is accepted by every command, not just the wizard. On a standalone install it also scopes the lifecycle commands to that directory's install, which is how you disambiguate when more than one exists.
 
 ## Commands
 
@@ -194,6 +203,6 @@ npx sim-setup update
 <FAQ items={[
   { question: "Do scheduled workflows work on Docker Compose?", answer: "Yes. The cron service runs the same jobs the Helm chart schedules as Kubernetes CronJobs, using the schedules in docker/crontab. It needs CRON_SECRET — without it the service prints what to set and exits, and the rest of the stack keeps running."},
   { question: "Why is there a Redis container?", answer: "Redis backs pub/sub for live Chat task status and table events, plus shared caches. Pub/sub has no fallback that works across processes, so live status would not stream without it. The port is deliberately not published so it cannot collide with a local Redis."},
-  { question: "How do I back up and restore the database?", answer: "Back up with: docker compose -f docker-compose.prod.yml exec db pg_dump -U postgres simstudio > backup.sql. Restore with: docker compose -f docker-compose.prod.yml exec -T db psql -U postgres simstudio < backup.sql. The database data is persisted in a Docker volume named postgres_data."},
+  { question: "How do I back up and restore the database?", answer: "Back up with: docker compose -f docker-compose.prod.yml exec -T db pg_dump -U postgres simstudio > backup.sql. The -T matters — without it exec allocates a TTY and corrupts the redirected dump. Restore with: docker compose -f docker-compose.prod.yml exec -T db psql -U postgres simstudio < backup.sql. The database data is persisted in a Docker volume named postgres_data."},
   { question: "Can I customize the PostgreSQL credentials?", answer: "Yes. The docker-compose.prod.yml uses environment variable defaults: POSTGRES_USER (default: postgres), POSTGRES_PASSWORD (default: postgres), POSTGRES_DB (default: simstudio), and POSTGRES_PORT (default: 5432). Set these in your .env file to override them." },
 ]} />

apps/docs/content/docs/platform/self-hosting/security.mdx

@@ -257,7 +257,7 @@ The service bundles ~2.2 GB of spaCy models, so first start takes around three m
 ## The shipped Compose file publishes Postgres
 
 <Callout type="error">
-  `docker-compose.prod.yml` maps the database to the host: `${POSTGRES_PORT:-5432}:5432`, with `POSTGRES_USER` and `POSTGRES_PASSWORD` both defaulting to `postgres`. A plain `docker compose up -d` against that file, on a machine with a public interface, therefore exposes an open Postgres on 5432 with credentials anyone can guess. The Ollama stack maps the database the same way, so apply the fix to whichever file started your install.
+  `docker-compose.prod.yml` maps the database to the host: `${POSTGRES_PORT:-5432}:5432`, with `POSTGRES_USER` and `POSTGRES_PASSWORD` both defaulting to `postgres`. A plain `docker compose up -d` against that file, on a machine with a public interface, therefore exposes an open Postgres on 5432 with credentials anyone can guess. The local and Ollama stacks map the database the same way, so apply the fix to whichever file started your install.
 
   The [Docker guide](/platform/self-hosting/docker#1-configure-environment) tells you to generate `POSTGRES_PASSWORD` before the first start — do that, and additionally close the port:
 

apps/docs/content/docs/platform/self-hosting/troubleshooting.mdx

@@ -18,11 +18,15 @@ On a standalone Compose install, run it from the directory holding your `.env` a
 ## Database connection failed
 
 ```bash
+# The file that started your install — no bare `docker compose` works, the
+# repo ships no default docker-compose.yml.
+COMPOSE_FILE=docker-compose.prod.yml
+
 # Check database is running
-docker compose ps db
+docker compose -f "$COMPOSE_FILE" ps db
 
 # Test connection
-docker compose exec db psql -U postgres -c "SELECT 1"
+docker compose -f "$COMPOSE_FILE" exec db psql -U postgres -c "SELECT 1"
 ```
 
 Verify `DATABASE_URL` format: `postgresql://user:pass@host:5432/database`
@@ -59,12 +63,12 @@ Two things this does not cover:
 
 Sim identifies dynamically discovered LM Studio and vLLM models by their `vllm/` prefix. If the endpoint is unavailable and you manually enter the raw LM Studio model identifier, Sim treats that unknown identifier as an Ollama model.
 
-1. Set `VLLM_BASE_URL`, and `VLLM_API_KEY` too if you enabled LM Studio's API authentication — without the key, discovery requests omit the bearer token and fail. No Compose file sets either for you — `docker-compose.ollama.yml` only sets `OLLAMA_URL` — so add them to the `simstudio` service's `environment:` block (or to `.env` and interpolate them), then recreate the service and confirm it landed:
+1. Set `VLLM_BASE_URL`, and `VLLM_API_KEY` too if you enabled LM Studio's API authentication — without the key, discovery requests omit the bearer token and fail. No Compose file sets either for you — `docker-compose.ollama.yml` only sets `OLLAMA_URL` — so add them to the `.env` file next to your Compose file — `simstudio` declares `env_file: .env` in every shipped file — then recreate the service and confirm it landed:
 
-   Use the Compose file that started your installation — `docker-compose.prod.yml` for the documented production setup, or `docker-compose.ollama.yml` if you started from the Ollama stack:
+   Use the Compose file that started your installation — `docker-compose.prod.yml` for the documented production setup, `docker-compose.local.yml` for a source-built stack, or `docker-compose.ollama.yml` if you started from the Ollama stack:
 
    ```bash
-   COMPOSE_FILE=docker-compose.prod.yml   # or docker-compose.ollama.yml
+   COMPOSE_FILE=docker-compose.prod.yml   # or docker-compose.local.yml, docker-compose.ollama.yml
    docker compose -f "$COMPOSE_FILE" up -d --force-recreate simstudio
    docker compose -f "$COMPOSE_FILE" exec simstudio printenv VLLM_BASE_URL
    ```
@@ -79,15 +83,15 @@ Sim identifies dynamically discovered LM Studio and vLLM models by their `vllm/`
 ## WebSocket and realtime not working
 
 1. Verify reverse proxy routes `/socket.io` to the realtime service (default port 3002). `NEXT_PUBLIC_SOCKET_URL` is only needed if realtime is on a separate host.
-2. Verify realtime service is running: `docker compose ps realtime`
+2. Verify realtime service is running: `docker compose -f docker-compose.prod.yml ps realtime`
 3. Ensure reverse proxy passes WebSocket upgrades (see [Docker guide](/platform/self-hosting/docker))
 
 ## 502 Bad Gateway
 
 ```bash
-# Check app is running
-docker compose ps simstudio
-docker compose logs simstudio
+# Check app is running — use the file that started your install
+docker compose -f docker-compose.prod.yml ps simstudio
+docker compose -f docker-compose.prod.yml logs simstudio
 
 # Common causes: out of memory, database not ready
 ```
@@ -157,7 +161,7 @@ app:
 1. Check browser console for errors
 2. Verify `NEXT_PUBLIC_APP_URL` matches your actual domain
 3. Clear browser cookies and local storage
-4. Check that all services are running: `docker compose ps`
+4. Check that all services are running: `docker compose -f docker-compose.prod.yml ps`
 
 ## Windows-specific issues
 
@@ -209,7 +213,7 @@ Wrap it in `sh -c` with single quotes so `$CRON_SECRET` expands **inside the pod
 
 ## Gmail, Drive, and Outlook triggers never fire
 
-These are **polling** triggers, driven by the per-minute `/api/webhooks/poll/*` jobs. Check the scheduler is running them — `docker compose logs cron`, or `kubectl get cronjobs -n simstudio` for a recent `LAST SCHEDULE`.
+These are **polling** triggers, driven by the per-minute `/api/webhooks/poll/*` jobs. Check the scheduler is running them — `docker compose -f docker-compose.prod.yml logs cron`, or `kubectl get cronjobs -n simstudio` for a recent `LAST SCHEDULE`.
 
 Microsoft Teams chat triggers are the different case: they use a Microsoft Graph subscription capped at about three days, renewed by the twice-daily `renew-subscriptions` job. If Teams triggers work for a couple of days and then stop, that job is not running. See [Background Jobs](/platform/self-hosting/background-jobs).
 

apps/docs/content/docs/platform/self-hosting/upgrades.mdx

@@ -197,7 +197,7 @@ install uses:
 
 Inspect the result with `npx sim-setup logs`, which targets whichever Compose file the install uses.
 
-The CLI detects only those two files. An install started from `docker-compose.ollama.yml` is invisible to it — `update`, `logs`, and `status` all report no install — so upgrade that stack directly:
+The CLI detects only those two files. An install started from `docker-compose.ollama.yml` is invisible to it: `update`, `logs`, and `status` report no install, or — in a source checkout that also carries per-application env files — report that checkout's dev install instead. Upgrade that stack directly:
 
 ```bash
 # That file builds the app, realtime server, and migrator from source, so the
@@ -216,7 +216,7 @@ docker compose -f docker-compose.ollama.yml --profile "$PROFILE" up -d
   - **Kubernetes** — it does not upgrade Helm releases. Use `helm upgrade` after reading the chart and release notes.
   - **Source / dev** — update the checkout with git, run `bun install`, and restart `bun run dev:full`.
 
-  It also refuses to overwrite a managed Compose file you have edited by hand: preserve or remove your customizations first.
+  On a standalone `docker-compose.prod.yml` install it also refuses to overwrite its managed Compose file if you have edited it by hand, comparing the file against the hash it recorded in `.sim-setup.json`: preserve or remove your customizations first.
 </Callout>
 
 There is a short window where the app is unavailable while containers restart. Compose has no rolling-update mechanism — plan a maintenance window, or run Kubernetes if you need zero-downtime upgrades.
@@ -245,6 +245,7 @@ kubectl logs -n simstudio deploy/sim-app -c migrations --tail=200
 ```
 
 ```bash
+# Or the file that started your install.
 docker compose -f docker-compose.prod.yml logs migrations
 ```
 
@@ -269,9 +270,9 @@ helm rollback sim -n simstudio
 ```
 
 ```bash
-# Production Compose — edit .env so the pin persists, then restart.
-# Substitute the previous release tag from the releases page.
-echo "SIM_VERSION=<previous-release-tag>" >> .env
+# Production Compose — set SIM_VERSION in .env so the pin persists, replacing
+# any existing line rather than appending a second one. Substitute the previous
+# release tag from the releases page.
 docker compose -f docker-compose.prod.yml up -d
 ```