Skip to content

docs: 0.5.0 truth pass, TUI scrollbar clipping fix, and media hygiene - #107

Merged
DLANSAMA merged 4 commits into
mainfrom
docs/0.5.0-truth-pass
Aug 5, 2026
Merged

docs: 0.5.0 truth pass, TUI scrollbar clipping fix, and media hygiene#107
DLANSAMA merged 4 commits into
mainfrom
docs/0.5.0-truth-pass

Conversation

@DLANSAMA

@DLANSAMA DLANSAMA commented Aug 5, 2026

Copy link
Copy Markdown
Owner

Draft until the plate tui GIF is recorded and wired into the README — everything else is done.

1. Docs truth pass

Not just stale numbers. Seven claims were actively false:

  • CONTRIBUTING.md listed four "main gaps to A+/1.0" — coverage ~82 vs 92, domain→cli extraction, single-sourced TLS pin, remaining schemas. All four had closed (B.4, B.5, generated schemas) and coverage is 89.
  • docs/quality-roadmap.md said schemas were "not complete for every command", contradicting docs/api.md and tests/contracts/test_schema_validation.py, which derive the list from build_parser() and fail if any command lacks one. Its own scoreboard row already said the opposite.
  • The same file framed the TUI as branch work that "has not reached CI yet". It shipped in 0.5.0.
  • docs/test-backlog.md gave the mutation floor as 40%; mutation.yml and run_mutation_baseline.sh both say 48. The same row asked for a mutmut re-run that had already happened and disproved its premise.
  • docs/manual.md's Linux detection table listed only the legacy Flatpak app id and no Flatpak profile paths — a partial regression of a defect a previous pass fixed in the prose only, 50 lines above.
  • docs/plans/interactive-mode-plan.md still read "Do not start Phase 1 until the 0.4.0 tag exists". plate go shipped in 0.4.0.
  • README.md told every reader to pip install 'platecli[tui]' — including the pipx and uv-tool users the install section had just created, for whom that installs Textual into the wrong environment and leaves plate tui failing. docs/troubleshooting.md already had it right.

Plus stale figures re-measured and, importantly, re-sourced: numbers now cite the run or machine they came from, because local Linux and CI Linux legitimately differ and "fixing" one to match the other is how they went stale before.

2. TUI: the scrollbar was clipping which material was detected

On a terminal short enough that the prepare form overflows, #prepare-inputs grows a vertical scrollbar — and Textual scrollbars take real cells rather than overlaying. The widest radio label is the AMS-detected material, PLA — easy, rigid, most models (detected in AMS) at 49 cells, +4 for the toggle and padding = 53, against a column offering 54. One cell of slack, which the scrollbar ate: the label rendered as (detected in AMS with the paren shaved off.

So the screen silently truncated the one thing that tells you which filament it found. Column widened to 62, which leaves 54 even while scrolling.

Found by recording the TUI and looking at the frames. Every existing assertion passed — the label string was intact; only its rendering was cut. The new test asserts the RadioSet has room for its widest button while the scrollbar is up, and fails when the column goes back to 60.

3. Media hygiene

docs/job-hero.mp4 (2.3 MB) is the raw full-length capture; the trimmed cut job-hero-post.mp4 (427 KB) is already committed and is what the launch material uses. The raw file was untracked and unignored — a trap the post-audit gameplan called out by name — and duly got swept into #102, a test-decomposition PR, by a git add. Untracked from HEAD and ignored going forward.

It stays in history, which is fine: I extracted frames and checked them — no IP, serial, or home path.

Gates

ruff / ruff format / mypy (88 files) / bandit (Medium 0, High 0 by severity)   clean
pytest -m "not live"    1420 passed, 1 deselected — coverage 89.09% (floor 83)
syntax / cli_help / ci_workflow / python_compat smokes                          ok
check_layers            Layer boundaries OK (1 allowlisted debt edge)
gen_schemas --check     docs/schemas up to date (26 schemas)
test_docs_consistency   6 passed
uv build + package_contents_smoke                                               ok

sdist doc set verified by extraction: docs/releasing.md correctly absent, and both edited AGENTS.md tables render as contiguous blocks rather than being split by a paragraph — a failure mode this repo has actually shipped.

Known, not fixed here

.pre-commit-config.yaml pins ruff-pre-commit v0.15.20 while ci.yml pins ruff@0.16.0, even though the file's own header calls itself "a local mirror of the lint job… to match CI exactly". Bumping a pinned formatter can reformat code, so that wants its own PR rather than riding along in a docs pass.

Audits every tracked doc against the 0.5.0 code and the release commit's own
CI run (31044588411 on 5b08720), and fixes what had gone false or stale.

Actively false, now corrected:
- CONTRIBUTING claimed the four 2026-07 audit gaps were open. All four had
  closed: B.4 cli helper extraction, B.5 single TLS pin helper, the remaining
  JSON schemas (generated now), and the camera bind/pin hardenings. It also
  cited ~82% coverage against a measured 89.
- quality-roadmap said "Phase D schemas largely landed but not complete for
  every command" while docs/api.md and a contract test say the opposite and
  enforce it. Schemas are complete and generated.
- quality-roadmap still framed the TUI as unmerged work on feat/tui that "has
  not reached CI yet". It shipped in 0.5.0 (#97 + #104).
- test-backlog put the mutation floor at 40 (it is 48) and asked for a mutmut
  re-run on slicer/output.py that already happened on 2026-08-04 and disproved
  the prediction it was based on.
- manual's OrcaSlicer detection table listed only the legacy Flatpak app id
  and no Flatpak profile paths at all, contradicting the prose two paragraphs
  above and the real candidate list in config.py.
- docs/plans/interactive-mode-plan.md still read "Draft for implementation"
  and told the reader not to start until 0.4.0 was tagged; plate go shipped in
  0.4.0. Marked implemented, historical text kept as written.

Stale or incomplete:
- Measured numbers refreshed with their source and date: 1419 passing / 1420
  collected, 89.1% branch coverage over 8120 statements on local Linux, and
  the full CI matrix (Windows 88.8% binding, macOS 89.1%, Linux 89.2-89.3%).
  Local and CI figures are cited separately, not reconciled.
- tui/ coverage row was one module behind (#104 added widgets/summary.py):
  now 14 of 18 at 100%, package minimum 95.8%.
- AGENTS module table was missing bambu.py and printer.py; its repo-only list
  was missing docs/releasing.md, docs/README.md and docs/plans/*.
- AGENTS and CONTRIBUTING gate lists omitted pip-audit, gen_schemas --check
  and check_layers, all blocking in the same CI job.
- releasing.md's dev-bump example still said 0.5.0.dev0.
- README told pipx / uv tool users to `pip install 'platecli[tui]'`, which
  installs into the wrong environment; and its agent section did not mention
  that go and tui refuse --json.

No grade was inflated: the scoreboard stays A- / A, coverage 89 against a
target of 92, per-module floors still unenforced, camera residuals still open.
On a terminal short enough that the prepare form overflows, #prepare-inputs
grows a vertical scrollbar, and a Textual scrollbar takes real cells rather
than overlaying. The longest radio label is the AMS-detected material —
"PLA — easy, rigid, most models  (detected in AMS)", 49 cells, plus 4 for the
toggle and its padding = 53 — against a column that offered 54. One cell of
slack, which the scrollbar consumed: the label rendered as "(detected in AMS"
with the closing paren shaved off, so the screen silently truncated the one
thing that tells you which filament it found.

Widening the column to 62 leaves 54 cells even while scrolling. Found by
recording the TUI and looking at the frames — every existing assertion passed,
because the label *string* was intact and only its rendering was cut. The new
test asserts the RadioSet has room for its widest button while the scrollbar is
up, and fails when the column goes back to 60.
…rward

docs/job-hero.mp4 is the full-length VHS capture of the hero run — 2.3 MB, most
of it the dead air while OrcaSlicer works. The postable cut that scripts/
trim_hero.sh produces from it (docs/job-hero-post.mp4, 427 KB) is already
committed and is what the launch material uses, so the raw file was pure repo
weight and no doc referenced it.

It was never meant to be tracked. It was untracked AND unignored, which the
post-audit gameplan explicitly called out as a trap, and it duly got swept into
#102 — a test-decomposition PR — by a `git add`. Ignoring it closes the trap.

The file stays on disk for re-cutting the video without re-running a real print;
it stays in history, which is fine: frames were extracted and checked and it
leaks no IP, serial, or home path. This only removes it from HEAD.
…t it shows

The 0.5.0 headline feature had no imagery at all, and the picture below its
README section was the `plate doctor` GIF — health-check output captioned as if
it illustrated the live dashboard. Meanwhile `plate doctor` is introduced 40
lines earlier with nothing beside it. Both are now under what they actually
show: doctor beside the `plate doctor` line, the new capture under "Watch the
printer while it works".

docs/tui.gif is a real printer mid-print, not a mockup and not --sim: the
dashboard at 13% with nozzle 219.9->220C, bed 60->60C and layer 4/240, then the
job monitor (including its "the print keeps going; nothing here can stop it"
line), then the two-column prepare screen. Frames were extracted and read
before committing — no IP, serial, access code or home path in any of them,
and the shell prompt is bare.

docs/tui.tape records how, and carries the two things that cost time here:
vhs Width/Height are PIXELS, not cells, so the obvious 1100px window is only
~93 columns and silently captures the NARROW single-column prepare layout
rather than the two-column one; and an idle printer records as a static 0%,
so the print has to be running before the tape is rolled.
@DLANSAMA
DLANSAMA marked this pull request as ready for review August 5, 2026 23:24
@DLANSAMA
DLANSAMA merged commit 15cb473 into main Aug 5, 2026
6 checks passed
@DLANSAMA
DLANSAMA deleted the docs/0.5.0-truth-pass branch August 5, 2026 23:48
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.

1 participant