docs(configuration): document PUNKTFUNK_STANDBY_SINK_KEEP #452

2026-08-30T17:49:51Z

enricobuehler commented

2026-08-30 17:49:51 +00:00

main is red on the docs-drift job, and has been since #445 merged on 2026-08-29.

The failure

scripts/ci/check-docs-drift.sh gate 3 — the undocumented-env ratchet — fails on the current
main tip (560d91a8):

::error::new PUNKTFUNK_* vars are neither documented in docs-site nor in the baseline:
  PUNKTFUNK_STANDBY_SINK_KEEP

7d61c968 (feat(vdisplay/windows): standby sinks are neutralised by default, merged as #445)
added the knob at crates/pf-vdisplay/src/vdisplay/policy.rs:770 without either half of what the
ratchet asks for: no docs-site page mentions it, and it is not in
scripts/ci/docs-undocumented-env-baseline.txt.

The job is deliberately unfiltered — no paths: filter, by the reasoning in its own comment
that "docs drift arrives through commits that look unrelated to docs". So this is not one stale
job on one branch: every open PR cut from main since the 29th carries the same red gate, whatever
it touches.

The choice: docs, not the baseline

The ratchet accepts either. The baseline is documented as being for "a deliberately internal knob",
and this one is not internal. Its own doc comment is written at an operator:

Yes unless the operator opts out with PUNKTFUNK_STANDBY_SINK_KEEP

It changes behaviour a user can see on their own hardware — a standby TV that does or does not get
disabled for the duration of a stream — and there is a real reason to set it (a sink that must stay
awake). So it belongs on the page that owns the feature.

The row goes in the Windows host table of docs-site/content/docs/configuration.md, next to the
other topology knobs. The path is Windows-only: standby_sink_neutralise is consumed at
crates/pf-vdisplay/src/vdisplay/windows/manager.rs:1544 and the mechanism lives in
crates/pf-win-display/src/monitor_devnode.rs.

The row states the measured default honestly — median compose hole 6.3 s → 0.7 s over 16
alternating legs — including that it is an improvement and not a cure, which is what policy.rs
says and what #445's own numbers support. It also says the scope limit out loud, because that is the
part an operator will worry about: only externals belonging to no topology are ever picked, so a
laptop panel and active monitors are untouched.

Verification

Both steps of the docs-drift job, run against this branch:

Check	Result
`sh scripts/ci/check-docs-drift.sh`	exit 0
`sh scripts/ci/check-docs-links.sh`	exit 0

The gate is proven non-vacuous rather than merely green: the same script against the main tip in a
detached worktree exits 1 with the error quoted above, and against this branch exits 0. The
only difference between the two trees is the one added line.

Scope

One line, one file, docs only. No code, no baseline change, no CHANGELOG entry — the knob's
behaviour shipped in #445 and is unchanged here; this only gives it the page it was missing.

`main` is red on the `docs-drift` job, and has been since #445 merged on 2026-08-29. ## The failure `scripts/ci/check-docs-drift.sh` gate 3 — the undocumented-env ratchet — fails on the current `main` tip (`560d91a8`): ``` ::error::new PUNKTFUNK_* vars are neither documented in docs-site nor in the baseline: PUNKTFUNK_STANDBY_SINK_KEEP ``` `7d61c968` (*feat(vdisplay/windows): standby sinks are neutralised by default*, merged as #445) added the knob at `crates/pf-vdisplay/src/vdisplay/policy.rs:770` without either half of what the ratchet asks for: no docs-site page mentions it, and it is not in `scripts/ci/docs-undocumented-env-baseline.txt`. The job is deliberately **unfiltered** — no `paths:` filter, by the reasoning in its own comment that "docs drift arrives through commits that look unrelated to docs". So this is not one stale job on one branch: every open PR cut from `main` since the 29th carries the same red gate, whatever it touches. ## The choice: docs, not the baseline The ratchet accepts either. The baseline is documented as being for "a deliberately internal knob", and this one is not internal. Its own doc comment is written at an operator: > **Yes unless the operator opts out** with `PUNKTFUNK_STANDBY_SINK_KEEP` It changes behaviour a user can see on their own hardware — a standby TV that does or does not get disabled for the duration of a stream — and there is a real reason to set it (a sink that must stay awake). So it belongs on the page that owns the feature. The row goes in the **Windows host** table of `docs-site/content/docs/configuration.md`, next to the other topology knobs. The path is Windows-only: `standby_sink_neutralise` is consumed at `crates/pf-vdisplay/src/vdisplay/windows/manager.rs:1544` and the mechanism lives in `crates/pf-win-display/src/monitor_devnode.rs`. The row states the measured default honestly — median compose hole 6.3 s → 0.7 s over 16 alternating legs — including that it is an improvement and not a cure, which is what `policy.rs` says and what #445's own numbers support. It also says the scope limit out loud, because that is the part an operator will worry about: only externals belonging to no topology are ever picked, so a laptop panel and active monitors are untouched. ## Verification Both steps of the `docs-drift` job, run against this branch: | Check | Result | |---|---| | `sh scripts/ci/check-docs-drift.sh` | exit 0 | | `sh scripts/ci/check-docs-links.sh` | exit 0 | The gate is proven non-vacuous rather than merely green: the same script against the `main` tip in a detached worktree exits **1** with the error quoted above, and against this branch exits **0**. The only difference between the two trees is the one added line. ## Scope One line, one file, docs only. No code, no baseline change, no CHANGELOG entry — the knob's behaviour shipped in #445 and is unchanged here; this only gives it the page it was missing.

enricobuehler added 1 commit 2026-08-30 17:49:53 +00:00

docs(configuration): document PUNKTFUNK_STANDBY_SINK_KEEP

ci / bun-nix (pull_request) Successful in 33s

Details

ci / docs-drift (pull_request) Successful in 43s

Details

ci / web (pull_request) Successful in 57s

Details

ci / docs-site (pull_request) Successful in 1m13s

Details

ci / rust-arm64 (pull_request) Successful in 2m38s

Details

ci / rust (pull_request) Failing after 8m32s

Details

3d46a21381

The standby-sink opt-out shipped in 7d61c968 with no docs-site page owning
it, so the docs-drift ratchet in check-docs-drift.sh has failed on every
commit since. It is an operator-facing knob, not an internal one, so it
belongs in the Windows host table rather than the undocumented baseline.

enricobuehler merged commit c02c3ec11b into main

2026-08-30 20:54:05 +00:00

enricobuehler deleted branch fix/docs-drift-standby-sink-env

2026-08-30 20:54:22 +00:00

enricobuehler referenced this issue from a commit

2026-08-30 23:46:21 +00:00

chore(release): cut 0.34.0

enricobuehler referenced this pull request

2026-08-30 23:46:58 +00:00

chore(release): cut 0.34.0 #467

Sign in to join this conversation.