Skip to content

docs(env): refresh ENVIRONMENT.md — document all 34 drifted env vars#353

Merged
JustVugg merged 1 commit into
JustVugg:devfrom
woolcoxm:docs/environment-refresh-dev
Jul 17, 2026
Merged

docs(env): refresh ENVIRONMENT.md — document all 34 drifted env vars#353
JustVugg merged 1 commit into
JustVugg:devfrom
woolcoxm:docs/environment-refresh-dev

Conversation

@woolcoxm

Copy link
Copy Markdown
Contributor

What

docs/ENVIRONMENT.md claims to be "generated from source by scanning every getenv() site" — but it had drifted far behind the code. Running the exact reconciliation procedure documented in MAINTAINING-DOCS.md, I found 34 engine env vars read by the code but undocumented, and nothing stale to remove.

# in code, NOT documented  ->  34 vars (before this PR)
comm -23 <(git grep -hoE 'getenv\("[A-Za-z0-9_]+"\)' -- 'c/*.c' 'c/*.cu' 'c/*.mm' | sed 's/getenv("\([^"]*\)")/\1/' | sort -u) \
         <(perl -ne 'while(/`([A-Z][A-Z0-9_]{1,})`/g){print "$1\n"}' docs/ENVIRONMENT.md | sort -u)

What changed

Added all 34 vars to the correct sections. Defaults and effects are taken from the source (the ternary default + inline comment at each call site), per the maintenance rules — nothing invented.

Performance / tuning (11):
COLI_NUMA, PILOT_TWO, COUPLE / COUPLE_K / COUPLE_D, ROUTE_TRACE, COLI_NO_FUSED_PAIR, DISK_SPLIT, I4S, SPEC_PIN, COLI_RAM_OVERCOMMIT

CUDA (16):
COLI_CUDA_ATTN_SHARD, COLI_CUDA_PIPE / _PIPE_SHARD / _PIPE_S_MIN, COLI_CUDA_MTP, COLI_CUDA_ASYNC, COLI_CUDA_DUAL_PROJ, COLI_CUDA_W4_PACKED, COLI_CUDA_TC_INT4 / _TC_MIN_ROWS / _TC_W4A16 / _TC_W4A16_MIN, COLI_CUDA_SHARED_W4A16 / _SHARED_W4A16_MIN_ROWS, COLI_METAL_UNTRACKED

Advanced / debug (7):
SCHEMA, EXPERT_BUDGET / EXPERT_BUDGET_EXPERIMENTAL (noting the #303 quarantine), TOKENS, SCORE_PREFIX, REPIN_VERBOSE, PPL (olmoe-only), COLI_PROMPT (in the CLI section)

Also bumped the "Generated from" line to dev @ d5327e2 and noted the scan now covers olmoe.c, backend_cuda.cu, backend_metal.mm (not just glm.c).

Verification

The code-vs-doc diff is now empty — all 111 distinct C env vars are documented:

comm -23 code_vars.txt doc_vars.txt   # (empty)

The reverse diff (doc vars not in C code) is 14 entries, all legitimate: 11 Python-side vars (COLI_API_KEY, COLI_DEBUG, …) correctly placed in the "Server / CLI" section (they're read by coli / openai_server.py, not the C engine), plus 3 prose constants named inside descriptions (IOSQE_ASYNC, O_DIRECT, and the VAR format placeholder).

Docs-only change; no build/test impact.

ENVIRONMENT.md says it is "generated from source by scanning every
getenv() site", but it had drifted far behind the code. Reconciling the
doc against the C sources (the MAINTAINING-DOCS.md procedure) found 34
engine env vars read by the code but undocumented, and nothing stale.

Added (defaults/effects taken from source, per the maintenance rules -
nothing invented):

Performance/tuning (11): COLI_NUMA, PILOT_TWO, COUPLE/COUPLE_K/COUPLE_D,
  ROUTE_TRACE, COLI_NO_FUSED_PAIR, DISK_SPLIT, I4S, SPEC_PIN,
  COLI_RAM_OVERCOMMIT

CUDA (16): COLI_CUDA_ATTN_SHARD, COLI_CUDA_PIPE/_PIPE_SHARD/_PIPE_S_MIN,
  COLI_CUDA_MTP, COLI_CUDA_ASYNC, COLI_CUDA_DUAL_PROJ, COLI_CUDA_W4_PACKED,
  COLI_CUDA_TC_INT4/_TC_MIN_ROWS/_TC_W4A16/_TC_W4A16_MIN,
  COLI_CUDA_SHARED_W4A16/_SHARED_W4A16_MIN_ROWS, COLI_METAL_UNTRACKED

Advanced/debug (7): SCHEMA, EXPERT_BUDGET/_EXPERIMENTAL, TOKENS,
  SCORE_PREFIX, REPIN_VERBOSE, PPL (olmoe-only), COLI_PROMPT (CLI section)

Also bumped the "Generated from" line to dev @ d5327e2 and noted the scan
now covers olmoe.c, backend_cuda.cu, backend_metal.mm (not just glm.c).

Verified: the code-vs-doc diff is now empty - all 111 distinct C env vars
are documented. The reverse diff (doc vars not in C code) is 14 entries,
all legitimate: 11 Python-side vars correctly in the Server/CLI section,
plus 3 prose constants (IOSQE_ASYNC, O_DIRECT, the VAR format word).
@JustVugg
JustVugg merged commit d6d28f0 into JustVugg:dev Jul 17, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants