docs: align env and troubleshooting docs with the code (#12404)

Four documentation claims contradicted the code: .env.example called OMNIROUTE_USE_TURBOPACK dev-only and said the production build still uses webpack (it reads the same flag and defaults to Turbopack); the README's Bun section said `bun run build` auto-detects Bun and switches to Webpack (only `bun run dev` does — the production bundler is decided by the flag alone); TROUBLESHOOTING.md gave OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT a default of 1 when unset means no request-count cap; and it quoted the pre-#12223 wording of the structural 503 chat_admission_busy message. The Retry-After bullet in the same section is deliberately untouched because #12395 rewrites it.

Validated in a combined worktree with all 25 PRs of this batch boarded together: typecheck:core clean, 443/443 node-runner tests plus 14/14 vitest across every test file the batch touches, and check-changelog-integrity, check:cycles (418 files), check:provider-consistency (272 REGISTRY entries, 355 canonical providers), check:docs-counts, check:docs-sync (42 locales) and check-file-size all green.

Thanks @pacocartones.

.env.example

@@ -240,7 +240,7 @@ PORT=20128
 # Used by: src/app/api/v1/relay/chat/completions/route.ts
 # RELAY_IP_PER_MINUTE=30
 
-# Bundler selection for `npm run dev`. Set to 0 to fall back to webpack.
+# Bundler selection for `npm run dev` and `npm run build`. Set to 0 to fall back to webpack.
 # Default is 1 (Turbopack). PR #4092 had forced webpack because earlier
 # Turbopack 16.2.x panicked on the OmniRoute module graph with "internal error:
 # entered unreachable code: there must be a path to a root"
@@ -250,8 +250,9 @@ PORT=20128
 # /api/v1/models, /api/mcp) and repeated HMR rebuilds: zero panics. Turbopack
 # also keeps dev memory far lower on the edit→rebuild loop (HMR rebuild RSS stays
 # ~flat vs webpack's monotonic growth), which mitigates the dev-server OOM on
-# this 60+ route app. The production build still uses webpack (build pipeline is
-# unaffected by this dev-only flag).
+# this 60+ route app. The production build (scripts/build/build-next-isolated.mjs)
+# reads the same flag: Turbopack by default, 0 builds with webpack (`npm run
+# build:contributor` sets it for you).
 OMNIROUTE_USE_TURBOPACK=1
 
 # Disable systemd sd_notify (Type=notify / WatchdogSec=) even when running

README.md

@@ -1020,7 +1020,7 @@ Full table: [Docker Guide — runtime RAM](docs/guides/DOCKER_GUIDE.md#runtime-r
 Standard `bun install` and global installation (`bun install -g omniroute`) are supported via Bun runtime detection:
 
 - **Built-in `bun:sqlite`**: OmniRoute uses Bun's built-in `bun:sqlite` driver when running under Bun, falling back to `better-sqlite3` on Node.js or `sql.js`.
-- **Automatic Webpack bundler selection**: Development (`bun run dev`) and production builds (`bun run build`) automatically detect Bun and disable Turbopack in favor of Webpack to prevent native V8 binding incompatibilities.
+- **Automatic Webpack bundler selection in dev**: Development (`bun run dev`) automatically detects Bun and disables Turbopack in favor of Webpack to prevent native V8 binding incompatibilities. Production builds (`bun run build`) follow `OMNIROUTE_USE_TURBOPACK` exactly as on Node: Turbopack by default, `OMNIROUTE_USE_TURBOPACK=0` to build with Webpack (`Dockerfile.bun` exposes it as a `--build-arg`).
 - **Dedicated Bun Dockerfile**: Multi-stage `Dockerfile.bun` for native Bun production deployments (`docker build -f Dockerfile.bun -t omniroute:bun .`).
 
 ```bash

changelog.d/maintenance/12404-env-and-troubleshooting-drift.md

@@ -0,0 +1 @@
+- **docs(env):** align `.env.example`, the README Bun section, and the troubleshooting guide with the code: `OMNIROUTE_USE_TURBOPACK` also governs `npm run build` (not dev-only), `bun run build` follows that flag instead of auto-selecting Webpack, `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` is unset by default (no request-count cap), and the structural `503 chat_admission_busy` message matches `chatAdmissionResponses.ts` (#12404 — thanks @pacocartones)

docs/guides/TROUBLESHOOTING.md

@@ -52,7 +52,7 @@ Common problems and solutions for OmniRoute.
 
 ```bash
 export OMNIROUTE_ROTATE_ON_400=true           # hop to another model/provider on 400/401 (skips broken passthrough models)
-export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # raise the heavyweight admission ceiling (default 1) so long-context bursts are not rejected
+export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # explicit heavyweight admission ceiling (unset by default: no request-count cap, see note below)
 export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # longer bounded wait for heavyweight capacity instead of an immediate retryable 503
 ```
 
@@ -556,8 +556,8 @@ The byte-based response body is:
 ```
 
 The structure-based response uses the same type and code, with the message
-`Structurally heavy chat request capacity is busy; retry shortly.` and
-`reason: "structure_limit"`.
+`Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly.`
+and `reason: "structure_limit"`.
 At the default thresholds, a request is structurally heavy when it has at least `200` messages,
 at least `64` tools, or at least `32,000` estimated tokens, or when bounded structure estimation
 exhausts its bounds of `10,000` visited nodes or depth `12`.