docs: give the README a diagram, including the part that is not adopted - #10
Merged
Conversation
This repo had no diagram at all. The README explains the shared-workflow model in prose and then reports adoption in a table three paragraphs later, so the shape of the thing — one copy here, called from there — never lands visually. Adds one mermaid block after the "why it works" paragraph. It draws both branches, because only one of them is flattering: 2 of the 12 bricks (7 reusable workflows + 5 composite actions) have callers, at 6 call-sites across assay, edge-proc, edgeproc-core and privacy-core, all on the publish path. The other 10 have zero, and almamesh, aml-filter and edge-reco still hand-roll their CI. That dotted branch is exactly what the consumer-drift guard exists to measure, so the diagram links to it. Counts verified against the tree, not copied from the prose: 7 workflow files carry `on: workflow_call` (cloudflare-pages-deploy, frontend-gate, python-gate, python-publish, secret-scan, security-audit, ts-publish); ci.yml and consumer-drift.yml are this repo's own and are not callable. 5 composites in .github/actions/. 12 total, matching the README's "the other 4 composites and 6 reusable workflows". Mermaid rather than d2 because a `.d2` source plus a committed `.svg` is a build artifact that drifts (edgeproc-core had 5 `.d2` files and 1 stale `.svg`). Mermaid has no artifact and GitHub renders it natively. Claim touched: none — README only, no workflow, composite or guard changes. Rendered with mermaid-cli 11 before commit; parses. tests/lint-examples.sh and example-fidelity green (172 resolved, 0 missing, 0 unverifiable across 7 repos). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0186xrrT9mYfCZTVkk8HN12p
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
This repo had no diagram at all. Adds one mermaid block to the README, right after the "why it works" paragraph.
Why
The README explains the shared-workflow model in prose, then reports adoption in a table three paragraphs later. The shape of the thing — one copy here, called from there — never lands visually.
The diagram draws both branches, because only one of them is flattering:
ts-publish.yml(×3) andsetup-python-uv(×3), 6 call-sites across assay, edge-proc, edgeproc-core, privacy-core, all on the publish path.That dotted branch is precisely what the consumer-drift guard exists to measure, so the diagram links to it. A diagram that showed only the adopted path would be the same "measuring shape, not property" mistake the guard was built to catch.
Counts verified against the tree, not copied from the prose
on: workflow_call:cloudflare-pages-deploy,frontend-gate,python-gate,python-publish,secret-scan,security-audit,ts-publish.ci.ymlandconsumer-drift.ymlare this repo's own and are not callable..github/actions/.Why mermaid and not d2
A
.d2source plus a committed.svgis a build artifact that drifts. edgeproc-core had 5.d2files and 1.svg, last regenerated 7 months before its source was last edited (see hseshadr/edgeproc-core#17). Mermaid has no artifact and GitHub renders it natively with a zoom control.Evidence
mermaid-cli@11before committests/lint-examples.shclean (zizmor: no findings); example fidelity 172 resolved, 0 missing, 0 unverifiable across 7 consumer reposRender verification on github.com (branch
docs/readme-diagram, logged-in Chrome): seen with my own eyes — the diagram draws complete and legible, both the solid "in use today" branch and the dotted "nobody calls these yet" branch, and it fits the content column without clipping.🤖 Generated with Claude Code
https://claude.ai/code/session_0186xrrT9mYfCZTVkk8HN12p