Skip to content

feat(docs): draw the wiring lane and the honesty lane - #5

Merged
HarperZ9 merged 1 commit into
mainfrom
feat/repo-art-and-diagrams
Sep 3, 2026
Merged

feat(docs): draw the wiring lane and the honesty lane#5
HarperZ9 merged 1 commit into
mainfrom
feat/repo-art-and-diagrams

Conversation

@HarperZ9

@HarperZ9 HarperZ9 commented Sep 3, 2026

Copy link
Copy Markdown
Owner

What this adds

Two diagrams and a repository mark on the plexus front page, rendered from a spec
rather than drawn by hand.

file what it shows
docs/art/wiring-lane.svg manifest, discover, capability, wiring, goal, plan, receipt, verify, ending in still holds or drifted
docs/art/honesty-lane.svg tool set, emits, consumes, match, leftover, loop, collision, report, ending in wired, colliding, or unmet
docs/art/plexus-header.svg the repository mark, seeded from the name so no two repositories share one

The honesty surface is the part hardest to picture from prose. Unmet inputs,
unconsumed outputs, feedback loops, and colliding organ ids read as four separate
bullet points, when they are four ways one comparison comes out.

The picture is derived, and a gate says so

docs/art/plexus.art.json is the source. tools/render_repo_art.py renders it;
tools/check_repo_art.py re-renders and compares bytes. Twelve gates run,
covering determinism, per-repository identity, wrapper truncation, return-edge
geometry, outcome-box fit, tagline width, no local paths or em-dashes, and every
committed illustration actually being shown somewhere.

tests/test_repo_art.py runs that gate under pytest and asserts on its receipt,
so python -m pytest -q covers the front page with no CI change. One of the
three tests feeds the outcome-box check a note too wide for its box and requires
a complaint, so a green suite means the gate can still fail.

Two mechanisms moved from the source into the text

Stage labels were written from src/plexus/mesh.py, plan.py, and receipt.py
rather than from the README, which surfaced two things the code does and the front
page did not say:

  • verify_plan rebuilds the receipt from the plan it just re-derived, not from
    the body saved in the file, so editing that body cannot make a plan agree with
    itself.
  • The receipt's method_version has to match before anything else is compared, so
    a plan written by an older plexus is reported as failing rather than silently
    re-interpreted under new rules.

Line endings

.gitattributes pins docs/art/* to LF. The gate compares committed bytes
against a fresh render, so per-platform normalization would make the comparison
depend on who checked the repository out.

Honest nulls

  • The four renderer scripts under tools/ are a copy of the same files in the
    sibling repositories, now the eleventh. That is real duplication and a real
    maintenance cost, taken deliberately so each repository stays dependency-free
    and can render its own artwork from a fresh clone with nothing installed.
  • The old .github/assets/zentropy-banner.png is no longer referenced by
    anything. It is left in place rather than deleted, in case something outside
    this repository links to it.
  • The diagrams describe the declared mesh. They do not change the standing caveat
    that every edge is self-reported by its producer and that plexus does not import,
    resolve, or run the source a manifest cites.
  • Local run: 74 passed, and python examples/tour.py exits 0.
  • The artwork has not been viewed as GitHub renders it. Static inspection says it
    will fall back to system fonts, which is inference rather than a look.

🤖 Generated with Claude Code

plexus computes a wiring graph, plans a pipeline over it, and reports what does
not connect. The README explains all three in text, and one of them, the honesty
surface, is the part hardest to picture from prose: unmet inputs, unconsumed
outputs, feedback loops, and colliding organ ids are four different absences and
they read as a list rather than as one comparison.

Two diagrams and a repository mark, rendered from docs/art/plexus.art.json by a
script. The picture is a pure function of a spec that diffs, and a gate
re-renders and compares bytes, so a stage name edited without a re-render fails
the suite instead of shipping a drawing of a version that no longer exists.

The stage labels come from src/plexus/mesh.py, plan.py, and receipt.py rather
than from the README, which surfaced two mechanisms the front page did not state.
verify_plan rebuilds the receipt from the plan it just re-derived rather than
from the saved body, so editing that body cannot make a plan agree with itself.
And the receipt's method version has to match before anything else is compared,
so a plan written by an older plexus fails rather than being re-interpreted under
new rules. Both are now in the text.

.gitattributes pins docs/art to LF, because the gate compares committed bytes to
a fresh render and per-platform normalization would make that comparison depend
on who checked the repository out.

tests/test_repo_art.py runs the gate under pytest and asserts on its receipt,
including one test that feeds the outcome-box check a note too wide for its box,
so a green suite means the gate can still fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@HarperZ9
HarperZ9 merged commit bf7d94c into main Sep 3, 2026
10 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