Rewrite the README: per-feature sections, screenshots, and star history - #5381
Open
jbecke wants to merge 21 commits into
Open
Rewrite the README: per-feature sections, screenshots, and star history#5381jbecke wants to merge 21 commits into
jbecke wants to merge 21 commits into
Conversation
Break the flat feature bullet list into distinct sections for email, messages, tasks, docs, file storage, CRM, and agents. Each section gets a short benefits blurb and product screenshots; canvas, calls, and pull requests stay as a short list.
Add a Stack section with the backend/frontend/tooling detail, a quick-start code block, and the repository tree, all above the product sections. Rewrite the feature and concept sections as prose instead of stacked bold-link-colon bullet lists.
Hand-built SVG in light and dark variants with a star call-to-action in the top right; the whole chart links to the repo. Generator script lives next to the assets so the series can be extended later.
Link each feature section to its product docs page below the screenshots, drop the joke in the concepts intro, and move the funding sentence down next to hiring.
…oc copy Rebuild the star history SVG at 1:1 so the growth curve reads steeper. Cut the Stack prose roughly in half. Replace invented product copy with the positioning language from the internal comparison doc, and restore the original wording for the four cross-cutting concepts.
Derive the headline number from the series so the title, subtitle, endpoint label, and aria-label stay in sync on future updates.
Bring back Teo's intro and the funding line at the top, re-add the Why Macro section and the block table from the earlier README, and drop the redundant Also included list. The stack, quick start, and directory tree move to a Repository section above Security. Star chart updated to 713.
Drop the File storage section and the second image under Docs and CRM, split the Email list around its screenshot, split the Why Macro paragraph in two, and promote top-level sections to H1 so the levels are consistent. Add breathing room above the header nav, move the star ask above the chart, and halve the chart height.
Column one is now plain block names; the docs link moves to a second column. Add two line breaks above every H1 so sections are not packed together.
Reword the call to action for starring the repo to improve clarity.
Promote the remaining H2 sections to H1 so all sections render the same, and drop the padding above each from two line breaks to one.
Updated the README to enhance clarity on Macro's AI capabilities, team memory, and system integration.
Copy-edit pass over the README: spelling, doubled words, apostrophes in plurals (CRMs, DMs, CRDTs, PDFs), a bare URL turned into a link, and the iOS App Store link pointed at the US storefront to match the other one. Replace 'just test', which is not a recipe in this repo, with the actual setup_test_envs + cargo test invocation.
Composite a brand-orange play button onto each feature screenshot and wrap each image in a link so clicking it opens the Macro YouTube channel.
Contributor
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdded a Python script that renders light and dark SVG GitHub star-history charts from dated star-count data. Expanded the README with product details, feature documentation, setup instructions, repository information, security, licensing, and a GitHub star call-to-action containing the generated chart images. 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✨ Finishing Touches 💡 1⚔️ Resolve 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/readme/star-history.py:
- Around line 4-32: Update the SERIES data used by the chart to rely on
reproducible, verifiable star-history source values instead of
reverse-engineered estimates, preserving the date/count structure and known
final value; alternatively, clearly label the generated chart and its metadata
as an estimate rather than factual history.
- Around line 159-160: Update the output path construction near the final write
in the script to resolve from the directory containing __file__, so execution
from any current working directory writes star-history-{name}.svg beside the
script. Keep the existing filename and output-writing behavior unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: c8878ac7-307b-4c64-ba0c-65e7707bd598
⛔ Files ignored due to path filters (8)
.github/readme/agents-task-handoff.pngis excluded by!**/*.png.github/readme/crm-board.pngis excluded by!**/*.png.github/readme/docs-prd.pngis excluded by!**/*.png.github/readme/email-thread.pngis excluded by!**/*.png.github/readme/messages-channel.pngis excluded by!**/*.png.github/readme/star-history-dark.svgis excluded by!**/*.svg.github/readme/star-history-light.svgis excluded by!**/*.svg.github/readme/tasks-list.pngis excluded by!**/*.png
📒 Files selected for processing (2)
.github/readme/star-history.pyREADME.md
Comment on lines
+4
to
+32
| # Star counts reverse-engineered from the star-history.com chart, | ||
| # anchored to the known value of 713 on 2026-07-28. | ||
| SERIES = [ | ||
| (date(2025, 11, 18), 0), | ||
| (date(2025, 12, 1), 3), | ||
| (date(2025, 12, 6), 9), | ||
| (date(2025, 12, 11), 18), | ||
| (date(2025, 12, 16), 24), | ||
| (date(2025, 12, 24), 27), | ||
| (date(2026, 1, 1), 29), | ||
| (date(2026, 1, 16), 31), | ||
| (date(2026, 2, 1), 33), | ||
| (date(2026, 2, 16), 35), | ||
| (date(2026, 3, 1), 37), | ||
| (date(2026, 3, 16), 39), | ||
| (date(2026, 4, 1), 42), | ||
| (date(2026, 4, 9), 55), | ||
| (date(2026, 4, 16), 72), | ||
| (date(2026, 4, 23), 98), | ||
| (date(2026, 5, 1), 130), | ||
| (date(2026, 5, 10), 141), | ||
| (date(2026, 5, 20), 158), | ||
| (date(2026, 6, 1), 205), | ||
| (date(2026, 6, 10), 235), | ||
| (date(2026, 6, 20), 272), | ||
| (date(2026, 7, 1), 330), | ||
| (date(2026, 7, 10), 415), | ||
| (date(2026, 7, 17), 520), | ||
| (date(2026, 7, 28), 713), |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Use a verifiable source for the chart series.
Lines 4-5 state that the intermediate values are reverse-engineered and only the final value is known. The generated SVG presents every point as factual star history. Replace estimated values with reproducible source data, or label the chart as an estimate.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/readme/star-history.py around lines 4 - 32, Update the SERIES data
used by the chart to rely on reproducible, verifiable star-history source values
instead of reverse-engineered estimates, preserving the date/count structure and
known final value; alternatively, clearly label the generated chart and its
metadata as an estimate rather than factual history.
Comment on lines
+159
to
+160
| path = f".github/readme/star-history-{name}.svg" | ||
| open(path, "w").write("\n".join(o)) |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Resolve the output path from __file__.
Line 159 resolves the output path from the current working directory. Running python star-history.py inside .github/readme targets a nonexistent nested .github/readme/.github/readme/ directory.
Proposed fix
+from pathlib import Path
+
...
- path = f".github/readme/star-history-{name}.svg"
- open(path, "w").write("\n".join(o))
- return path
+ path = Path(__file__).resolve().with_name(f"star-history-{name}.svg")
+ path.write_text("\n".join(o), encoding="utf-8")
+ return str(path)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| path = f".github/readme/star-history-{name}.svg" | |
| open(path, "w").write("\n".join(o)) | |
| from pathlib import Path | |
| path = Path(__file__).resolve().with_name(f"star-history-{name}.svg") | |
| path.write_text("\n".join(o), encoding="utf-8") | |
| return str(path) |
🧰 Tools
🪛 ast-grep (0.45.0)
[warning] 159-159: File path is request-/variable-derived; validate and normalize to prevent path traversal.
Context: open(path, "w")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').
(open-filename-from-request)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/readme/star-history.py around lines 159 - 160, Update the output
path construction near the final write in the script to resolve from the
directory containing __file__, so execution from any current working directory
writes star-history-{name}.svg beside the script. Keep the existing filename and
output-writing behavior unchanged.
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.
Summary
A full rewrite of the README. Replaces PR #5247, which was closed before this work landed.
The old README was a flat bullet list of features with no screenshots and no build instructions. This version walks through each block with a screenshot, explains the positioning in our own words, and ends with a star history chart.
Docs and assets only — no code, no config.
README.mdplus nine files under.github/readme/.Structure
Hero → intro → Why Macro → Features (block table) → one section per block with a screenshot → How it all works together → hosted app → Agents & MCP → Repository (stack, quick start, directory tree) → Security → License → Community → Star us on GitHub.
Every top-level section is an
H1with consistent spacing.Screenshots
Six product screenshots live in
.github/readme/: email, channels, tasks, docs, CRM, and the agent task hand-off. Each carries a centred play-button overlay and links out to the Macro YouTube channel.Star history
star-history-{light,dark}.svgare hand-built rather than embedded from star-history.com, so the chart can carry a "Star this repo" button and match the brand colour. Served via<picture>so it follows the viewer's theme.The series is reverse-engineered from a star-history.com screenshot and anchored to a known 713 on 2026-07-28 — the shape is faithful and the endpoint exact, but intermediate values are interpolated. It is a static snapshot;
.github/readme/star-history.pyregenerates both files after editing theSERIESlist.Fixes worth flagging
just test, which is not a recipe in this repo —justfileand the four files undertooling/just/definerun_local,check, andclippybut notest. Replaced withjust setup_test_envs+cargo test./kw/); repointed to/us/to match the other.Verification
Generated by Claude Code