Skip to content

Comments

docs: replace Graphviz SVG diagrams with inline Mermaid#47

Merged
flyingrobots merged 4 commits intomainfrom
docs/mermaid-diagrams
Feb 22, 2026
Merged

docs: replace Graphviz SVG diagrams with inline Mermaid#47
flyingrobots merged 4 commits intomainfrom
docs/mermaid-diagrams

Conversation

@flyingrobots
Copy link
Member

@flyingrobots flyingrobots commented Feb 22, 2026

Summary

  • Replaced all 11 Graphviz SVG diagrams with inline Mermaid code blocks in README.md and GUIDE.md
  • Mermaid renders natively on GitHub with zero build step, eliminating transparency, font, and scaling issues with the old SVGs
  • Deleted 24 obsolete files: docs/diagrams/ (8 .dot + 8 .svg + style.dot), docs/images/*.{dot,svg} (6 files), and scripts/build-diagrams.sh
  • Bumped version to 11.5.2

Test plan

  • Verify Mermaid diagrams render correctly on GitHub (check README.md and docs/GUIDE.md)
  • Confirm no broken image/link references remain
  • Lint, typecheck, and all 3,889 unit tests pass (verified locally)

Summary by CodeRabbit

  • Documentation

    • Replaced Graphviz-based images with inline Mermaid diagrams across guides and README; expanded and clarified architecture, flow, patch anatomy, materialization, and ref-layout visuals.
    • Added a public changelog entry for version 11.5.3 detailing the diagram migration.
  • Chores

    • Bumped package version to 11.5.3.
    • Removed the obsolete diagram build tooling and archived diagram assets.

Mermaid renders natively on GitHub with zero build step,
eliminating transparency, font, and scaling issues with
the old Graphviz SVGs.

- Convert 8 fig-* diagrams to inline Mermaid in README + GUIDE
- Delete docs/diagrams/ (17 files), docs/images/*.{dot,svg} (6 files)
- Delete scripts/build-diagrams.sh
- Bump version to 11.5.2
@coderabbitai
Copy link

coderabbitai bot commented Feb 22, 2026

Warning

Rate limit exceeded

@flyingrobots has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 5 minutes and 55 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Migrates Graphviz-based diagrams to inline Mermaid blocks across README and GUIDE, removes generated diagram assets and the Graphviz build script, updates package and jsr versions to 11.5.3, and records the changes in CHANGELOG.md (notes for 11.5.3 and 11.5.2).

Changes

Cohort / File(s) Summary
Version Bumps
jsr.json, package.json
Bumped package/jsr top-level version from 11.5.1 to 11.5.3. No other metadata or API changes.
Documentation — README & Guide
README.md, docs/GUIDE.md
Replaced multiple centered HTML image blocks and SVG references with inline Mermaid diagram code blocks (How It Works, Multi-Writer Collaboration, Architecture, materialization pipeline, conflict resolution, checkpoints, Git ref layout, patch anatomy, etc.). Formatting/visuals only; no behavioral changes.
Documentation — Removed Assets
docs/diagrams/*, docs/images/*
Deleted docs/diagrams contents and specific docs/images SVGs (including three unreferenced diagram pairs) that were replaced by inline Mermaid; removed obsolete generated assets.
Changelog
CHANGELOG.md
Added unreleased notes for 11.5.3 (Mermaid diagram fixes) and 11.5.2 (Mermaid migration) and corrected wording about scope and deletions.
Build Script Removal
scripts/build-diagrams.sh
Removed script that built Graphviz .dot files into .svg; Graphviz-based build flow deleted.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through docs with nimble paws,

Swapped dots for Mermaid without a pause,
No build script scurries, images set free,
Diagrams now bloom in pure MD glee,
Pocket-sized rabbit, pleased as can be.

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title directly and clearly describes the main change: replacing Graphviz SVG diagrams with inline Mermaid diagrams across documentation files.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch docs/mermaid-diagrams

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions
Copy link

Release Preflight

  • package version: 11.5.2
  • prerelease: false
  • npm dist-tag on release: latest
  • npm pack dry-run: passed
  • jsr publish dry-run: passed

If you tag this commit as v11.5.2, release workflow will publish.

Patch anatomy: add eg-state-hash/eg-frontier-oid trailers and operation
parameter signatures. Materialize pipeline: add O(P) complexity note.
Data-storage diagram: add visibility annotations. Ref layout: add
elision nodes on leaf refs. CHANGELOG: correct 11.5.2 scope wording.

Bump 11.5.2 → 11.5.3.
@github-actions
Copy link

Release Preflight

  • package version: 11.5.3
  • prerelease: false
  • npm dist-tag on release: latest
  • npm pack dry-run: passed
  • jsr publish dry-run: passed

If you tag this commit as v11.5.3, release workflow will publish.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@jsr.json`:
- Line 3: The CHANGELOG contains a spurious 11.5.2 entry that does not exist in
the JSR registry while jsr.json shows "version": "11.5.3"; reconcile them by
either collapsing the CHANGELOG's 11.5.2 content into the 11.5.3 entry and
removing the 11.5.2 heading, or explicitly annotate the CHANGELOG entry for
11.5.2 as an npm-only/intermediate release (and add a note) so it’s clear why
it’s absent from JSR; ensure jsr.json's "version" value ("11.5.3") remains
accurate and consistent with the published JSR releases.

11.5.2 was never published to npm or JSR. Merging both entries under
11.5.3 eliminates the version gap that confused the registry history.

Resolves CodeRabbit review comment on jsr.json:3.
@flyingrobots
Copy link
Member Author

@coderabbitai review please 🥕

@coderabbitai
Copy link

coderabbitai bot commented Feb 22, 2026

@flyingrobots: I'll review the changes in this PR right away! 🥕

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@github-actions
Copy link

Release Preflight

  • package version: 11.5.3
  • prerelease: false
  • npm dist-tag on release: latest
  • npm pack dry-run: passed
  • jsr publish dry-run: passed

If you tag this commit as v11.5.3, release workflow will publish.

B-DIAG-1 through B-DIAG-3 (Mermaid migration checklist, rendering
smoke test, invisible-link fragility) and B-REL-1/B-REL-2 (version
consistency gate, preflight CHANGELOG cross-check). Sourced from
PR #47 review session.
@github-actions
Copy link

Release Preflight

  • package version: 11.5.3
  • prerelease: false
  • npm dist-tag on release: latest
  • npm pack dry-run: passed
  • jsr publish dry-run: passed

If you tag this commit as v11.5.3, release workflow will publish.

@flyingrobots flyingrobots merged commit bcea908 into main Feb 22, 2026
8 checks passed
@flyingrobots flyingrobots deleted the docs/mermaid-diagrams branch February 22, 2026 19:16
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