#13998·OmniRoute

docs: four stale/missing entries found via support triage (.env.example OpenCode headers + credential health interval, Windows PATH, skip-postinstall wording)

Author: diegosouzapwCreated Sep 17, 2026Updated Sep 17, 2026
Labelsdocumentation

Four documentation defects found while answering support questions on Discord and WhatsApp over the last two days. Each one sent a user down the wrong path, and all four are verified against the current tree (release/v3.8.51).

1. .env.example documents the old OpenCode header defaults, and the wrong on/off state

.env.example:715-722 says the defaults are opencode-cli/1.0.0 / cli / default and that synthesis is "OFF by default".

The code says otherwise. open-sse/executors/opencode.ts:1007-1021 enables synthesis unless the var matches 0|false|no|off, so it is ON by default, and the values are opencode / desktop / global. The values changed in #10571; docs/reference/ENVIRONMENT.md:344-347 is already correct, so only .env.example drifted.

This matters right now: it is the first thing anyone checks when debugging the OpenCode free-tier 403 in #13935.

2. .env.example documents CREDENTIAL_HEALTH_CHECK_INTERVAL as 5 minutes; the code default is 60

.env.example:289-292 — "Default: 300000 (5 minutes)".

src/lib/credentialHealth/scheduler.ts returns 3_600_000 (60 min) in both default branches. The env var is only honored when >= 10_000, which the file does document correctly. The neighbouring CREDENTIAL_HEALTH_CACHE_TTL at :295-298 is a different setting and its 300000 looks right — only the interval line is wrong.

3. No PATH guidance for Windows anywhere in the getting-started docs

A Windows beginner who runs npm install -g omniroute and then gets "omniroute is not recognized" finds nothing: README.md, docs/guides/SETUP_GUIDE.md, docs/guides/USER_GUIDE.md and docs/guides/TROUBLESHOOTING.md have no PATH section. TROUBLESHOOTING covers the npm 11 allowScripts case, antivirus and the readiness timeout, but not this.

Suggested: one short entry in TROUBLESHOOTING with the npm global prefix (npm config get prefix), where the shim lands on Windows, and how to add it to PATH.

4. Minor: the skip-postinstall flag reads broader than it is

README.md:1151-1156 presents OMNIROUTE_SKIP_POSTINSTALL=1 under "skip the post-install native warm-up". That is accurate — the gate lives in scripts/postinstall.mjs:12-18 — but users read it as skipping the whole postinstall, while the npm hook scripts/build/postinstall.mjs (the binary-copy/repair step) has no such gate and still runs. One clarifying clause would remove the ambiguity.