docs: explain why to choose @statelyai/graph in README

[davidkpiano]

• Adds a concise "Why @statelyai/graph?" section: plain-JSON graphs, unified diagram model (mixed edge modes, nesting, ports, geometry), benchmark-backed speed, contract-tested iterative algorithms, 14 formats + 8 layout engines + XState adapter, typed data.
• Mentions the library powers Stately.ai's visual tooling.
• Adds a patch changeset: npm only refreshes the README on publish, and docs: simplify README #44 merged after 2.5.0 was released, so this ships the new README as 2.5.1.

Claims verified against src/, package.json#exports, tests/contracts.test.ts, and docs/benchmarks.md.

---

Summary by CodeRabbit

• Documentation
  • Updated the README introduction to better explain what the package offers, including JSON-shaped graphs, tree-shakable operations, supported features, benchmarks, algorithms, format conversions, layout engines, and generic typing.
  • Moved the documentation and contribution links to follow the quick-start example.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0e329945-697c-4277-9c3c-c05c3c8b64ff

📥 Commits

Reviewing files that changed from the base of the PR and between d34173f and 7076101.

📒 Files selected for processing (2)

• .changeset/readme-why.md
• README.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The README introduction now describes graph structure, operations, features, benchmarks, algorithms, adapters, and typing. Documentation and contribution links follow the quick-start example. A patch changeset records the README update.

Changes

README update

Layer / File(s)	Summary
README content and release entry .changeset/readme-why.md, README.md	The README introduction now describes package features and removes the previous capability list. Documentation and contribution links appear after the quick-start example. A patch changeset records the update.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 70761

The README update is included in the package release, and the reviewed capability claims are supported by the available repository evidence. No material merge risk remains.

Architecture Summary

Architecture risk: 🔵 Low · up to 70761

The change affects 1 system.

Changed systems: README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: The introduction replaces the general library description and separate plain-object statement with claims about graph data shape, standalone operations, supported features, benchmarks, algorithms, adapters, and typing. The former “What it provides” list is removed.
• observed — Modified behavior in README.md: The documentation and contribution links are moved here from the removed capability overview.
• observed — Modified behavior in .changeset/readme-why.md: Adds a patch Changeset for @statelyai/graph describing the README update and its publication to npm.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the README update and its purpose: explaining why to choose @statelyai/graph.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 1 potential issue.