docs(deploy): document pgbouncer rollout

progress.md

@@ -706,3 +706,20 @@
 - Added commit8 image verification to compose/k3s/offline deployment paths so CD fails if CI has not produced the required image.
 - Changed offline package defaults to use commit8 instead of tag names and to pull business images from the Gitea Registry.
 - Verification passed: workflow YAML parse, deploy script `bash -n`, and `sh -n` over all workflow run blocks.
+
+## 2026-05-03T03:03:09Z - Stable PgBouncer Deployment
+
+- Confirmed the existing repository topology uses application-side `pgxpool` and direct Postgres service names; no PgBouncer service/config existed before this change.
+- Started Phase 40 to add stable PgBouncer deployment with session pooling, app runtime traffic through PgBouncer, and migration jobs remaining direct to Postgres.
+- Added `pgbouncer` and `monitoring-pgbouncer` to production Docker Compose and k3s using `edoburu/pgbouncer:v1.24.1-p1`, `POOL_MODE=session`, and `AUTH_TYPE=scram-sha-256`.
+- Changed runtime app configs to target PgBouncer while keeping Docker/k3s migration jobs direct to `postgres` / `monitoring-postgres`.
+- Lowered application-side Postgres pools: tenant runtime uses 12 main / 8 monitoring connections per process; ops runtime uses 5 / 5.
+- Made deployment passwords flow from `POSTGRES_PASSWORD` / `OPS_POSTGRES_PASSWORD` placeholders and changed `DatabaseConfig.DSN()` to URL-escape credentials for stronger production passwords.
+- Included PgBouncer in offline packaging and docs.
+- Verification passed:
+  - `docker compose -f deploy/docker-compose.yaml --env-file deploy/.env.example config`
+  - `kubectl kustomize deploy/k3s` plus local YAML parse
+  - `bash -n deploy/scripts/package.sh`
+  - `git diff --check`
+  - `go test ./internal/shared/config ./internal/shared/repository/postgres ./internal/ops/config`
+  - Temporary PgBouncer container attached to existing `server_default` network returned `SELECT 1` through PgBouncer, then was removed.