docs: say wrapping can cost the reading order - #25

Merged

No1Joon merged 1 commit into

main from

docs/wrap-reading-order

Sep 5, 2026

Merged

docs: say wrapping can cost the reading order #25
No1Joon merged 1 commit into
main from
docs/wrap-reading-order

Conversation

@No1Joon

@No1Joon No1Joon commented Sep 5, 2026

Copy link

Copy Markdown

Owner

docs/agents.md offers wrap: true for a long diagram and names one price — the detour an edge pays between two rows of the fold. It does not say the other one.

The fold follows the layout's layer index, not the chain, so the main chain need not stay contiguous. Measured over the bundled examples and the agent-run diagrams, all forced to wrap: true — four of six send a reader backwards up the page, enterprise and growth among them:

examples/enterprise.yaml 2 inversions
examples/growth.yaml 2 inversions
codex round 2 2 inversions
agy round 2 1 inversion — the chain ends at rank 0
examples/startup.yaml reads in order
examples/web-app.yaml reads in order

This records a measurement that is already in hand (#22 carries the method and the per-node ranks); it does not propose a new shape to draw instead. Both prices are now named in docs/agents.md, docs/agents.ko.md, and packages/cli/AGENTS.md — the last is the copy that ships in the npm tarball, which is why this carries a patch changeset.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WFgzmVUfEC4BFMoHpLQ7rU

@No1Joon


 docs: say wrapping can cost the reading order

0fdd7f4

`wrap: true` folds on the layout's layer index rather than on the chain,
so the main chain need not stay contiguous. Of six diagrams measured
under it, four send a reader backwards up the page — enterprise and
growth among them, both bundled examples.
The guidance offered wrapping for a long diagram and named only the
detour it charges between rows, so an agent had no reason to look at
whether the picture still reads. Both prices are named now, in the docs
and in the copy the CLI ships.