docs: visual flow diagrams for the entry-point docs (Tranche E)#21
Merged
CodeWithJuber merged 1 commit intoJul 6, 2026
Merged
Conversation
Adds two tasteful mermaid diagrams — a "one source → every tool + pre-action gate" flow in README.md and a "your day with Forge" loop in ONBOARDING.md — so the model is graspable at a glance, alongside the existing propose→verify diagram in the substrate README. Preserves the docs' established dry-precise, emoji-free voice; no prose rewritten. All 67 markdown files remain relative-link clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HGZUYFdUb4EViXV5tRid19
CodeWithJuber
marked this pull request as ready for review
July 6, 2026 09:23
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
2 participants
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 & why
The final tranche — a tasteful visual pass on the entry-point docs so the mental model is
graspable at a glance, without touching the docs' signature dry-precise voice.
README.md— a mermaid "one source → every tool + pre-action gate" flow, right under"The solution", showing
source/rules.json → forge sync → CLAUDE.md/AGENTS.md/.cursor/… + MCPand the substrate gating each task before the agent edits.
ONBOARDING.md— a mermaid "your day with Forge" loop:init → configured → work → substrate checks → guarded edit → cortex learns → next task is smarter.most-read docs each carry one clear diagram.
Voice preserved: no prose rewritten, no emoji added (the house style is deliberately
emoji-free) — the diagrams are the visual win, which reads as technical, not chirpy. All 67
markdown files remain relative-link clean and every mermaid fence is balanced.
Checklist
npm testpasses (Node 18/20/22) — 222 tests (docs-only change; nothing affected)npm run checkpasses (Biome lint + format)docs:)CHANGELOG.mdupdated under## [Unreleased]Risk & rollback
Verification
Mermaid fences balanced in all three docs; repo-wide relative-link check clean (the single flagged
link is a pre-existing placeholder inside an HTML comment). GitHub renders mermaid in Markdown
natively, so the diagrams display on the repo pages.
This completes the full improvement program (Tranches A → E) from the code + whitepaper review.
🤖 Generated with Claude Code
https://claude.ai/code/session_01HGZUYFdUb4EViXV5tRid19
Generated by Claude Code