Skip to content

docs: correct the two places the user-facing docs are wrong (#206, #207) - #238

Merged
BernardJen merged 1 commit into
mainfrom
docs/user-guide-and-commands
Aug 18, 2026
Merged

docs: correct the two places the user-facing docs are wrong (#206, #207)#238
BernardJen merged 1 commit into
mainfrom
docs/user-guide-and-commands

Conversation

@BernardJen

Copy link
Copy Markdown
Contributor

Closes #206 and #207.

#206 — wrong, not merely stale

docs/USER_GUIDE.md described the screensaver as "a bouncing logo". There are 30.
README.md's feature list carried the same line. The guide's shortcut table also omitted
V, + and - entirely, so an operator reading it could not discover the screensaver
controls at all — which is exactly how the omission surfaced: the owner had to ask for
those keys rather than read them.

  • README feature line rewritten.
  • User guide's Screensaver section rewritten, including that each saver looks different
    every activation because its choices are clock-seeded.
  • V, + and - added to the shortcut table.
  • All 30 listed in rotation order, which is the order + and - step through.
  • The split-flap board's status explained: it is the no-signal display, appears
    immediately rather than after five minutes, and cannot be reached by stepping. That
    distinction was documented nowhere a user would look.
  • Weather and Art-Net covered at an operator's level, both flagged off by default, detail
    left in README rather than duplicated.

The list came from registry.js, not from the issue — the issue says explicitly to
check against code because the issue will itself age. Cross-checked against
structure-baselines.js, the other generated list, as an independent count.

#207 — two workflows documented nowhere

.claude/CLAUDE.md's command block omitted npm run bench and npm run baselines, so the
only way to find them was to read package.json.

  • Both added, with the baselines caveat stated where someone will hit it: it rewrites all
    30 entries, so a single-saver redesign should edit one line by hand.
  • The SwiftShader-versus-real-GPU contrast between shadercheck and bench spelled out —
    including that getting it backwards is what led several PRs to claim frame cost could not be
    measured headlessly when it could.
  • Preview harness keys documented in prose. Verified against the key handler rather than
    copied from the issue
    , which turned up four the issue omitted — R, the arrow keys, H
    and F — and one genuine collision worth a warning: +/- step savers in the shipped app
    but adjust bloom in the harness.

The documented selector example did not work

CLAUDE.md's one worked example of the preview flag was white-particles, and the matcher
stripped whitespace but not hyphens, so it silently fell through to the first saver. The
worst kind of doc error — it teaches the reader the feature is broken.

Fixed in the matcher, not the prose, because white-particles is what a reader will type
and it matches the file on disk. All four forms now resolve: white-particles,
whiteparticles, White Particles, white_particles.

Verified end to end rather than from the regex: navigating to #white-particles logs
[Screensaver] Started: White Particles with no fallback warning.

A test, because the list has already gone stale twice

#206 suggests generating the list from registry.js. test/docs-screensaver-list.test.js is
the cheaper half — it needs nobody to remember to run a script, and it fails in CI the moment
prose and code disagree. It resolves the registry order from source and checks:

  • the documented list matches the registry exactly, in order (order matters, since the
    guide claims it is the +/- order);
  • the stated count is right in both files;
  • neither file says "bouncing logo";
  • the V and +/- rows are present;
  • the split-flap board is not in the rotation.

Fault-injected both ways — dropping a saver from the list, and reintroducing the
bouncing-logo line — and each fails it.

Verification

  • Branched from main (3201dbd).
  • npm run lint clean.
  • npm test412 passed (407 + 5 new).
  • Selector fix confirmed live in the preview harness.

Not verified / left open

#206 -- WRONG, NOT MERELY STALE

docs/USER_GUIDE.md described the screensaver as "a bouncing logo". There are 30.
README.md's feature list carried the same line. The guide's shortcut table also
omitted V, + and - entirely, so an operator reading it could not discover the
screensaver controls at all -- which is how the omission was noticed: the owner had
to ask for those keys rather than read them.

- README feature line rewritten: 30 GPU-rendered savers, random pick on activation,
  10-minute rotation, weather and Art-Net off by default.
- User guide's Screensaver section rewritten, including that each saver also looks
  different every activation because its choices are clock-seeded.
- V, + and - added to the shortcut table.
- All 30 listed in rotation order, which is the order + and - step through.
- The split-flap board's status explained: it is the no-signal display, appears
  immediately rather than after five minutes, and cannot be reached by stepping.
  That distinction was documented nowhere a user would look.
- Weather and Art-Net covered at an operator's level, both flagged off by default,
  with the detail left in README rather than duplicated.

The list came from registry.js, not from the issue -- the issue says explicitly to
check against code because the issue will itself age. Cross-checked against
structure-baselines.js, the other generated list, as an independent count.

#207 -- TWO WORKFLOWS DOCUMENTED NOWHERE

.claude/CLAUDE.md's command block omitted npm run bench and npm run baselines, so
the only way to find them was to read package.json.

- Both added, with the baselines caveat stated where someone will hit it: it
  rewrites all 30 entries, so a single-saver redesign should edit one line by hand.
- The SwiftShader-versus-real-GPU contrast between shadercheck and bench spelled
  out, including that getting it backwards is what led several PRs to claim frame
  cost could not be measured headlessly when it could.
- Preview harness keys documented in prose rather than only in the HUD legend.
  Verified against the key handler rather than copied from the issue, which turned
  up four the issue omitted -- R, the arrow keys, H and F -- and one genuine
  collision worth a warning: + and - step savers in the shipped app but adjust
  bloom in the harness.

THE DOCUMENTED SELECTOR EXAMPLE DID NOT WORK

CLAUDE.md's one worked example of the preview flag was white-particles, and the
matcher stripped whitespace but not hyphens, so it silently fell through to the
first saver. Fixed in the matcher rather than in the prose, because white-particles
is what a reader will type -- it matches the file on disk. Verified end to end:
#white-particles now logs "Started: White Particles" with no fallback warning.

A TEST, BECAUSE THE LIST HAS ALREADY GONE STALE TWICE

#206 suggests generating the list from registry.js. test/docs-screensaver-list.test.js
is the cheaper half: it resolves the registry order from source, compares it to the
marked block in the guide, and also checks the stated count, the absence of "bouncing
logo" in both files, the presence of the V/+/- rows, and that the split-flap board is
not in the rotation. Fault-injected both ways -- dropping a saver from the list and
reintroducing the bouncing-logo line each fail it.
@BernardJen
BernardJen merged commit ce099d9 into main Aug 18, 2026
1 check passed
@BernardJen
BernardJen deleted the docs/user-guide-and-commands branch August 18, 2026 10:12
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.

docs: the user guide still calls 30 screensavers "a bouncing logo", and hides V / + / -

1 participant