docs: document ZERO_APP_ID replication slot pitfall for local dev

contents/docs/deployment.mdx

@@ -351,3 +351,24 @@ To upgrade Zero to a new major version, first deploy the new zero-cache, then th
 ### Configuration
 
 The zero-cache image is configured via environment variables. See [zero-cache Config](/docs/zero-cache-config) for available options.
+
+## Local Development Against a Shared Database
+
+If you run `zero-cache` locally pointing at the same upstream Postgres as a
+deployed instance (e.g. to test against a staging or production database), you
+**must** set a distinct [`ZERO_APP_ID`](/docs/zero-cache-config#app-id) in
+your local environment:
+
+```bash
+# local .env only
+ZERO_APP_ID=zero_dev
+```
+
+Without this, the local instance will call `pg_terminate_backend` to steal the
+shared replication slot, crashing the deployed instance. When the deployed
+instance is then restarted or redeployed, it must perform a full re-sync of all
+replicated tables from Postgres, incurring unnecessary egress costs.
+
+Leave `ZERO_APP_ID` unset in production (defaults to `zero`). The two
+environments then hold independent replication slots and can run simultaneously —
+no separate dev database needed.

contents/docs/zero-cache-config.mdx

@@ -46,6 +46,22 @@ flag: `--app-id`<br/>
 env: `ZERO_APP_ID`<br/>
 default: `zero`
 
+<Note
+  type="warning"
+  heading="Avoid replication slot conflicts when running zero-cache locally"
+  slug="app-id-local-dev"
+>
+  If you run `zero-cache` locally against the same Postgres database as a
+  deployed instance, you **must** set a different `ZERO_APP_ID` locally (e.g.
+  `ZERO_APP_ID=zero_dev`). Two instances sharing the same App ID fight over the
+  exclusive Postgres replication slot — the newer instance calls
+  `pg_terminate_backend` to steal the slot, crashing the other.
+
+  With distinct App IDs, local and production use separate replication slots
+  (`zero_dev_0_...` vs `zero_0_...`) and can run simultaneously against the
+  same Postgres without conflict. You do not need a separate dev database.
+</Note>
+
 ### App Publications
 
 Postgres PUBLICATIONs that define the tables and columns to replicate. Publication names may not begin with an underscore, as zero reserves that prefix for internal use.