Skip to content

docs: hand-placed figures replace the last mermaid diagrams - #90

Merged
addisdev merged 1 commit into
developfrom
docs/figures-no-mermaid
Oct 16, 2026
Merged

addisdev merged 1 commit into
developfrom
docs/figures-no-mermaid

Conversation

@addisdev

Copy link
Copy Markdown
Owner

Replaces the last three mermaid diagrams in the docs with hand-placed figures, brings the workloads figure up to the catalog, and re-shoots the Devices screen and adds a Findings screen from the live brain. No mermaid is left under docs/, and CI now keeps it that way.

Before / after

Page Before After
explore/index.md mermaid flowchart TD, in GitHub's/Material's theme explore-night.png: the walk, the replay, and the verdict loop that switches a check off
explore/how-it-works.md mermaid sequenceDiagram explore-step.png: one mission across executor, device, model, judge and collector
explore/internals.md mermaid flowchart TB with subgraph explore-code.png: the code map, plus the "pixels outside model.ts" rule
README, workloads/index.md workloads.png: 28 workloads; README said "the figure predates six of them" workloads.png: all 34 shipped catalog entries; the aside is gone
dashboard.md devices.png: a throwaway laptop + simulator, generic glyphs devices.png: the PR #69 drawings on the real shelf (MacBooks, Galaxy, Roku in front of a TV, a sim)
dashboard.md, explore/findings.md no Findings picture findings.png

Every label was checked against the code rather than the old diagrams: two replays (replay_attempts), filed on at least 1 of 2 or a crash log (fileable()), precision under 30% once ten are judged (PRECISION_FLOOR), and pilot/vision as the gateway defaults. The old diagrams had two claims I did not keep: "the model" as the only model (the judge is one too), and an implied "same model never judges", which the code defaults but does not enforce. Figures follow the house rules: 2x PNG on their own charcoal ground, brand.css + symbols.js, nothing under 14 px at 1x.

The dashboard shots

npm run shoot:dash cannot capture either: its throwaway collector has one machine agent (so no shelf to draw) and no explore night (so no findings), and seeding either would be inventing data. Its three images (first-result, alerts, visual) show neither screen, so I did not re-run it.

Instead, a new read-only npm run shoot:live -- --url <brain> opens two pages on the running brain and writes nothing to it:

  • Devices filtered to status=online (5 of 20 registered). The full list is 15 offline, which brand.md already records reading as abandoned.
  • Findings filtered to app=bug-garden, the fixture app with planted defects. Real GreenFolio findings were left out on purpose; publishing a shipping app's open bugs is your call.

Both filters show in the picture. The banner's four open alerts are real (shelf devices that have not checked in). brand.md says all of this.

CI and config

  • docs.yml has a new No mermaid step that fails on a mermaid fence in any docs/**/*.md. Tested against a scratch file containing one.
  • mkdocs.yml drops the mermaid custom_fences and keeps plain pymdownx.superfences, which tabs and admonitions need.

Verified

  • mkdocs build --strict passes on top of Docs catch up with 0.8.0 and the explore work #88, and all six images resolve in the built site.
  • tsc --noEmit in collector/ is clean.
  • npm test in collector/ passes (ALL PASS, 1116 ok, with the one usual skip: no runner-android APK built). shoot:live is not part of the suite; I ran it by hand to make the two captures.

Rebased onto develop after #88 merged, so there are no conflicts with it.

🤖 Generated with Claude Code

The explore docs' night flowchart, one mission's sequence and the code map
were the only mermaid left. They are now figures in docs/figures/
(explore-night, explore-step, explore-code) on brand.css and symbols.js,
rendered by `npm run assets` to PNG at 2x, every label checked against the
code (replay_attempts 2, PRECISION_FLOOR 0.3 with ten judged, the pilot and
vision gateway defaults, fileable() filing crash logs unreplayed).

The docs workflow now fails on a mermaid fence under docs/, and mkdocs.yml
drops the mermaid custom fence.

workloads.html shows all 34 shipped catalog entries (adds enrol, explore,
upgrade-test, size-report, tvloop, llm-eval), so the README loses its
"the figure predates six of them" aside.

devices.png (the PR #69 device drawings) and a new findings.png come from
the lab's running brain via a new read-only `npm run shoot:live`, filtered
to online devices and the bug-garden fixture app; brand.md records why a
throwaway collector cannot honestly make either.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@addisdev

Copy link
Copy Markdown
Owner Author

Reviewed the rendered figures (explore-night, explore-step, Findings capture): accurate to the code and on-brand, live data only. CI green. Merging.

@addisdev
addisdev merged commit 90994c8 into develop Oct 16, 2026
19 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.

1 participant