No actionable comments were generated in the recent review. 🎉

Walkthrough

README.md was substantially rewritten: long overview, comparisons, extended help, and many sections were removed or condensed; installation instructions and troubleshooting commands were updated to use bundle exec; a short "Start Here" hub, concise requirements, and a trimmed Pro/help/footer were added.

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 I hopped through docs and snipped the fluff,
Trimmed the text till things were enough.
"Start Here" lights the path so bright,
bundle exec sets things right—
A leaner README, soft and fluff! ✨

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 help to get the list of available commands and usage tips.}

Greptile Summary

This PR refactors README.md from a 313-line marketing/reference doc into a ~145-line navigation landing page, moving detailed content (feature tables, comparison tables, upgrade guides, sponsor images) to the published docs site at reactonrails.com/docs. The core install steps, requirements, help channels, contributing, and license sections are preserved in a tighter form.

Confidence Score: 5/5

Safe to merge — docs-only change with no code modifications and all in-repo relative links verified.

All remaining findings are P2 or below. The install steps, requirements, help channels, contributing, and license sections are intact and accurate. The AGENTS_USER_GUIDE.md relative link resolves to a file that exists in the repo. No automated tests are affected.

No files require special attention.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[GitHub README] --> B{User Goal}
    B -->|New app| C[Install in 30 Seconds - create-react-on-rails-app]
    B -->|Existing app| D[Install in 30 Seconds - bundle add + generator]
    B -->|Learn more| E[Start Here links]
    B -->|Get help| F[Help section]
    B -->|Contribute| G[CONTRIBUTING.md]
    E --> H[reactonrails.com/docs]
    E --> I[reactonrails.com/examples]
    E --> J[CHANGELOG.md]
    F --> K[GitHub Discussions / Issues]
    F --> L[Slack / Commercial support]
    F --> M[AGENTS_USER_GUIDE.md]
    D --> N[react_on_rails:doctor]
    H --> O[Quick Start / API / Pro / Upgrades]

_{Reviews (1): Last reviewed commit: "Use the published docs URL for existing ..." | Re-trigger Greptile}

Review: Refocus GitHub README on docs navigation

The goal here is clear and well-executed — turning a 313-line marketing document into a 145-line navigation hub. The structure is logical, the install examples are cleaner (nice addition of bundle exec prefix), and the overall tone is appropriately minimal.

A few things worth checking before merging:

Potential broken link

The "Install into an existing Rails app" link points to .../docs/getting-started/existing-rails-app/, but the local source file is docs/oss/getting-started/installation-into-an-existing-rails-app.md. Other links in this section use filenames as slugs (e.g., create-react-on-rails-app/ matches create-react-on-rails-app.md, quick-start/ matches quick-start.md). If the docs site derives slugs from filenames, the published URL would be installation-into-an-existing-rails-app/, not existing-rails-app/. Worth verifying on the live site before this merges.

Supporter logos replaced with plain text

The old README rendered partner logos with dark-mode support (<picture>/<source> elements). The new version replaces this with a plain-text sentence. Sponsor agreements sometimes specify logo display as a condition — worth a quick check with stakeholders before dropping the visual branding.

Minor: "Start Here" duplicates the nav bar

Lines 38–45 repeat several links already in the <p align="center"> header (Documentation, Quick Start, Examples, Pro). Not wrong, but the duplication is slightly redundant on a page whose stated purpose is brevity.

Otherwise this is a solid, low-risk cleanup. The install flow, requirements, help links, and contributing section are all still present and accurate.

Review: README Refocus

Overall this is a clean, well-structured change. The landing-page approach is a good call — routing readers to the centralised docs site reduces drift between the README and the canonical docs. The addition of bundle exec and bin/dev in the install flow is a genuine improvement.

A few things worth addressing before merge:

Link verification

Several new absolute URLs point to reactonrails.com/docs/ paths that didn't exist in the old README:

• /docs/getting-started/create-react-on-rails-app/
• /docs/getting-started/existing-rails-app/
• /docs/getting-started/comparison-with-alternatives/
• /docs/pro/upgrading-to-pro/
• /examples/

These should be spot-checked to make sure they don't 404, especially the new ones. If the docs site has a different URL structure, readers hitting this README on GitHub will land on 404 pages before finding setup instructions.

Dropped upgrade workflow

The old README included this important note — running rails generate react_on_rails:install after upgrading to a new major version, along with a caution to review changes before applying. That guidance is now gone with no link replacement. The Changelog link is there, but an upgrade guide link (e.g. /docs/oss/upgrading/) would be worth adding to the "Start Here" section for existing users.

--template javascript option dropped

The old README surfaced the --template javascript flag for the new-app CLI. That is the only way to get a JavaScript (non-TypeScript) scaffold, and new users won't know it exists. Even a parenthetical or a pointer to the CLI docs page would prevent confusion.

Review: Refocus GitHub README on docs navigation

Overall: clean, well-executed improvement. Cutting from 313 → 145 lines reduces maintenance burden and keeps the GitHub surface area honest — a landing page that routes people to the docs site is the right long-term model. The restructured sections (Start Here, Install, Why, Pro, Requirements, Help) are logical and the prose is tighter than before.

A few small things worth considering before merge:

Minor issues

Section heading "Install in 30 Seconds" covers two different workflows
The heading implies a single quick path, but the section contains two scenarios: new app via npx and existing-app via bundle add. A reader scanning quickly may not realise they should pick just one. A neutral name like "Quick Install" (or splitting into two sub-sections) would be clearer.

No "now visit" signal after new-app creation
The old README had Visit http://localhost:3000/hello_world - done! after bin/dev. New users benefit from knowing there's something to see; removing it loses a small but concrete success marker. Even one line ("Then open http://localhost:3000/hello_world") would help.

--template javascript flag not mentioned
The old README noted --template javascript for JS-only setups. Users who prefer JavaScript over TypeScript won't know to pass this flag. A parenthetical on the npx line (e.g., # add --template javascript for a JS project) would cover it without cluttering the section.

npx create-react-on-rails-app version pinning
No functional issue, but the npx invocation always pulls the latest CLI release. If users want reproducibility they'd need npx create-react-on-rails-app@<version>. Probably fine for a README, but worth being intentional about.

Positives worth keeping

• Splitting the old one-liner bundle add … && rails g … into separate commands with bundle exec prefixes is a real usability improvement.
• bundle exec rake react_on_rails:doctor (vs bare rake) is more robust in multi-Ruby environments — good change.
• Supporters block is now wrapped in <p> tags with consistent height="44" — renders more predictably than the old bare <a> tags with <br> spacers.

Review: Refocus GitHub README on docs navigation

This is a well-executed docs-only change. Making the GitHub README a concise landing page that routes readers to reactonrails.com/docs/ is the right call — the old README was doing too many jobs at once (reference docs, marketing copy, comparison tables, forum links), and a shorter page reduces maintenance burden.

What works well:

• The "Start Here" link list is exactly what first-time visitors need.
• Splitting bundle add and bundle exec rails generate into separate lines is clearer than the one-liner.
• Adding bundle exec prefixes to both rails generate and rake commands is a good practice improvement.
• The bin/dev addition to both install flows is a real usability improvement over the old flow that left the server start implicit.
• Supporter logos at uniform heights look much cleaner.

Minor issues worth addressing (see inline comments):

1. Missing install verification step — the new app flow drops the "Visit http://localhost:3000/hello_world" confirmation line, which is the clearest signal to a first-timer that everything worked.
2. CI-tested version ranges removed from Requirements — these are genuinely useful for debugging environment mismatches and are easy to keep.
3. "Scout" vs "ScoutAPM" — the alt text for the ScoutAPM logo changed to Scout, which doesn't match their brand name.

Overall this is a net positive for the project. The inline suggestions below are all small — the structural decision is solid.

Review: Refocus GitHub README on docs navigation

Good structural decision — the landing-page-pointing-to-docs model is the right long-term approach for a README. Three items worth addressing before merge (inline comments attached):

Potentially breaking: URL slug mismatch on line 41
The existing-rails-app/ slug doesn't match the local source filename installation-into-an-existing-rails-app.md. The other four links in the "Start Here" block all match their filenames exactly. If the docs site derives slugs from filenames, new users clicking "Install into an existing Rails app" will hit a 404. Verify against the live site before merging.

Usability gap: --template javascript option dropped
The npx create-react-on-rails-app invocation no longer mentions --template javascript. Users who prefer plain JavaScript over TypeScript have no signal this flag exists. A single-line comment on the npx line covers it without clutter.

Minor branding: ScoutAPM alt text
The supporter logo alt text changed from ScoutAPM (old README) to Scout — their product name is ScoutAPM.

Positive call-out: The new install flow correctly adds cd my-app after the npx command — that step was missing in the old README and would cause bin/rails db:prepare to fail. Worth noting as a genuine bug fix.

Review: Refocus GitHub README on docs navigation

This is a clean, well-scoped change. Landing-page READMEs that route to a docs site are the right long-term model, and the restructured sections (Start Here, Install, Why, Pro, Requirements, Help) are all in the right places. The split of bundle add + bundle exec rails generate into separate lines with bundle exec prefixes, the addition of cd my-app in the new-app flow, and bundle exec rake react_on_rails:doctor are all genuine improvements over the old content.

Three items remain unresolved across the current review thread (inline comments added above):

1. URL slug mismatch (line 41) — existing-rails-app/ doesn't match the source filename installation-into-an-existing-rails-app.md. Every other link in the "Start Here" block maps filename-to-slug exactly; this one is the outlier. If the docs site derives slugs from filenames, new users clicking the most fundamental link will hit a 404. Needs verification on the live site (or a slug correction) before merge.

2. --template javascript not surfaced (line 57) — users who want plain JavaScript instead of TypeScript have no signal this flag exists from the README.

3. ScoutAPM alt text (line 150) — changed from ScoutAPM to Scout; their branded product name is ScoutAPM.