Skip to content

docs(readme): rewrite hero per launch-plan V1 audit#125

Merged
naorsabag merged 2 commits into
masterfrom
docs/readme-v1-hero-fixes
May 11, 2026
Merged

docs(readme): rewrite hero per launch-plan V1 audit#125
naorsabag merged 2 commits into
masterfrom
docs/readme-v1-hero-fixes

Conversation

@naorsabag
Copy link
Copy Markdown
Owner

@naorsabag naorsabag commented May 11, 2026

Summary

Closes two of the three V1 "fresh-eyes audit" findings from openhop-launch/03-readme-and-landing.md:

  • Passive tagline → active voice. "Animated diagrams your AI agent can write" assumed the reader already knew what an "agent" did. Replaced with the doc's skeleton tagline "Your AI walks you through your code, one step at a time" + a one-line descriptor.
  • Broken #install anchor in the NOTE block repointed to #install-options so the in-page link actually scrolls.

Also renamed ## Try it in 60 seconds## Try it in 30 seconds and updated the matching nav anchor.

Not in this PR (reverted after author review)

  • Hero command swap (initdemo). Initially included per the doc's "don't lead with install instructions" Do, but reverted on author preference — install-first is intentional here.

Deferred (separate follow-up PRs)

  • Quantified claim block (~Nx fewer tokens) — needs a measured ratio + docs/token-comparison.md worked example.
  • #262626 custom badges — V3 dark-mode finding.
  • Self-referential OpenHop-of-OpenHop diagram — V1 dogfood opportunity that replaces the mermaid How it works block.

Test plan

  • All in-page anchors resolve — verified statically.
  • CI green on the new branch.
  • Manual read-through on github.com renders correctly.

🤖 Generated with Claude Code

Three V1 fresh-eyes findings from openhop-launch/03-readme-and-landing.md:

- Passive tagline replaced with the active-voice "walks you through your
  code, one step at a time" line from the doc's skeleton. The previous
  copy assumed the reader already knew what an "agent" did in this
  context.
- Hero command swapped from `npx openhop init` to `npx openhop demo` so
  the lead is "see it work," not "install it." Install moved to a
  follow-up block so the path is demo -> install -> use, matching the
  doc's "don't lead with install instructions" rule.
- Stale `#install` anchor in the NOTE block repointed to
  `#install-options` so the in-page link actually scrolls.

Skipping the quantified-claim slot for now (needs a measured ratio
backed by docs/token-comparison.md).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 11, 2026

Walkthrough

This PR updates the README to refocus marketing messaging on the AI-driven step-by-step code walkthrough experience and replaces the 60-second quickstart with a streamlined 30-second demo workflow using npx openhop demo and npx openhop init commands.

Changes

README Marketing & Quickstart Update

Layer / File(s) Summary
Hero Copy & Value Proposition
README.md
Hero text rewritten to emphasize "Your AI walks you through your code, one step at a time" with animated, multi-level YAML-described data flows.
Navigation Link Update
README.md
Quickstart navigation link updated to point to the new 30-second quickstart anchor.
Quickstart Section Expansion
README.md
60-second quickstart replaced with 30-second demo workflow: npx openhop demo command, expanded description of spawning locally, OAuth flow, and live animation, added npx openhop init setup instructions, and updated NOTE about auto-detecting supported agent clients.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

  • naorsabag/openhop#124: Both PRs modify README.md hero/navigation and install/quickstart content with overlapping documentation edits to the same README sections.
  • naorsabag/openhop#88: Both PRs rework the 60s→30s quickstart, navigation/heading/quickstart wording, and demo/init instructions.
  • naorsabag/openhop#87: Both PRs modify README prose and navigation for project marketing, quickstart, and how the agent emits YAML/animated flows.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main change: rewriting the README hero section based on the V1 launch audit, which is the primary objective of this PR.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/readme-v1-hero-fixes

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.

Reverting the demo->init->demo-flow-explanation block per author
preference. Keeping the tagline rewrite, "30 seconds" heading rename,
and the #install-options anchor fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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