docs(build): document internal build-worker signal (#10952)

.env.example

@@ -2584,6 +2584,11 @@ APP_LOG_TO_FILE=true
 # OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP=false
 
 # ─── Build profile (build-time only) ────────────────────────────────────────
+# Internal build-worker signal set automatically by
+# scripts/build/build-next-isolated.mjs. Do not set it for a normal runtime:
+# while it is `1`, SQLite entry points use build-safe fallbacks.
+# OMNIROUTE_BUILDING=1
+
 # Set to "minimal" before `npm run build` to physically remove four optional
 # privileged modules (MITM cert install, Zed keychain import, Cloud Sync,
 # 9router installer) from the standalone bundle. The resulting artifact is

docs/reference/ENVIRONMENT.md

@@ -85,6 +85,7 @@ OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These vari
 | `DATA_DIR`                             | `~/.omniroute/`      | `src/lib/db/core.ts`                                  | Root directory for SQLite DB, backups, and data files. Override for Docker volumes or custom paths.                                                                                                                                             |
 | `OMNIROUTE_ALLOW_DEFAULT_DATA_DIR`      | _(unset)_            | `src/lib/dataPaths.ts`                                | Escape hatch for the test-context DATA_DIR guard (#10428). Test runs with no `DATA_DIR` are redirected to a throwaway temp dir so they cannot open the operator's real database; set to `1` to opt back in to the real directory.                  |
 | `OMNIROUTE_BUILD_SHA`                   | _(unset)_            | `src/lib/monitoring/buildSha.ts`                      | Git SHA of the running artifact. Stamped by `npm run build:release`; injectable in containers that ship without the `dist/BUILD_SHA` sentinel. Surfaced as `system.buildSha` on `/api/monitoring/health`.                                          |
+| `OMNIROUTE_BUILDING`                    | _(set automatically)_ | `scripts/build/build-next-isolated.mjs`, `src/lib/buildPhase.ts` | Internal build-worker signal. The isolated Next.js build sets it to `1` so every spawned worker uses build-safe SQLite fallbacks even when the framework phase marker is absent. Do not set it for a normal runtime. |
 | `OMNIROUTE_RELEASE_REF`                 | `origin/main`        | `scripts/build/buildProvenance.ts`                    | Ref the pack-artifact provenance gate checks the build SHA against (#10427).                                                                                                                                                                     |
 | `OMNIROUTE_ALLOW_CANARY_BUILD`          | _(unset)_            | `scripts/build/buildProvenance.ts`                    | Set to `1` to allow packing a build whose SHA is not on the release line, recording it as a deliberate canary instead of failing the gate (#10427).                                                                                               |
 | `OMNIROUTE_SMOKE_API_KEY`               | _(unset)_            | `scripts/ops/deploy-canary.mjs`                       | API key for the canary-deploy smoke probe, sent as `Authorization: Bearer` on `/v1/chat/completions`. Only used by the deploy script (#10429), never by the server. Not related to the `OMNIROUTE_SMOKE_*` variables of the opt-in CLI smoke harness (`RUN_CLI_SMOKE=1`, `OMNIROUTE_SMOKE_BASE_URL/MODEL/API_KEY_ENV/TARGETS/TIMEOUT_MS` in `tests/integration/upstream-cli-smoke.int.test.ts`) — see [CLI Integrations → Real smoke sweep](../guides/CLI-INTEGRATIONS.md).                                                                               |