docs(readme): layer in spec-03 beats — npm badge, Tier-1/Tier-2 split, hyperlinked clients

[naorsabag]

Summary

W4 from READINESS-AUDIT.md called for the launch-doc-spec-03 README beats. This adds the load-bearing pieces without depending on services we haven't stood up yet.

• npm version badge in the hero bar, linked to https://www.npmjs.com/package/openhop. Shields.io renders gracefully pre-publish; auto-flips to the live version once B4 lands.
• "Works with" badges split into two tiers:
  • Tier-1 — npx openhop init: Claude Code, Cursor, Windsurf, Cline, Continue.dev (advisory). Each badge hyperlinked to the client's official skills/rules docs URL (cited in packages/cli/src/init.ts:70-84).
  • Tier-2 — npx openskills install naorsabag/openhop: Codex CLI, Gemini CLI, JetBrains Junie, GitHub Copilot, OpenCode, Goose, Antigravity. Each linked to the client homepage. Aider gets a CLI only* footnote since it has no skill surface.
• Install table gains a Tier-1 / "everything else" row pair mirroring the badge split.

Deferred (still not in this PR): Discord link (no Discord registered yet).

Test plan

• npm run format:check clean.
• All Tier-1 docs URLs and Tier-2 homepage URLs return 200 from a sandbox probe.
• All shields.io badge URLs render.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added an npm version badge to the top status badges.
  • Updated “Works with” badges to list only Claude Code, Cursor, and OpenAI Codex.
  • Reworked Install guidance into a clearer command table covering: one-shot demo, client auto-detect install (npx openhop init), universal install via OpenSkills (npx openskills install ...), long-lived server, and run-from-source instructions.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 157fc011-ff46-4d94-9f58-9a654a1ef275

📥 Commits

Reviewing files that changed from the base of the PR and between c436bd7 and 645f3e4.

📒 Files selected for processing (1)

• README.md

✅ Files skipped from review due to trivial changes (1)

• README.md

---

Walkthrough

Updated README.md: added an npm version badge; pruned the “Works with” badges to Claude Code, Cursor, and OpenAI Codex; and restructured the Install section into separate rows for one-shot demo, long-lived server, client auto-detect install (npx openhop init), OpenSkills universal install (npx openskills install naorsabag/openhop), and running from source. (50 words)

Changes

README: Badge and Install restructuring

Layer / File(s)	Summary
Header badges README.md	Added an npm version badge and reduced the “Works with” badge set to Claude Code, Cursor, and OpenAI Codex (removed Windsurf, Cline, Continue.dev).
Install structure README.md	Replaced the previous simple scenario/command table with a more granular command matrix separating one-shot demo, long-lived server, client auto-detected skill install (npx openhop init), and OpenSkills universal install (npx openskills install naorsabag/openhop).
Install scenarios table README.md	Added explicit rows for one-shot demo (npx openhop demo), server (npx openhop serve), skill install variants, and contributor “run from source” instructions (git clone … && npm install && npm run dev).
Copy / formatting README.md	Adjusted wording and layout to clarify command usage and footnotes for the new install matrix.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• naorsabag/OpenHop#62: Modifies README badges and Install/instructions sections in overlapping areas.

🚥 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 accurately reflects the main changes: adding an npm badge, introducing a Tier-1/Tier-2 split for client support tiers, and adding hyperlinked client references to the README.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/w4-readme-spec03-beats

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Line 84: Replace the non-executable placeholder "git clone …" in the README
table row labeled "Run from source (contributors)" with a concrete,
copy-pasteable git clone command that includes the repository HTTPS URL
(including the .git suffix) so contributors can directly run clone then install
then start dev; keep the existing sequence of commands (clone, npm install, npm
run dev) and ensure the table cell content is a single executable command
string.
- Line 82: Update the Tier 1 install table row that currently reads "| **Install
the skill — Tier 1**          | `npx openhop init` — auto-detects Claude Code,
Cursor, Windsurf, Cline, Continue.dev and drops `SKILL.md` in place |" to make
Continue.dev's behavior advisory instead of implying full auto-detection parity;
change the phrasing after `npx openhop init` to list Continue.dev as "advisory"
or "recommended (advisory)" rather than "auto-detects", e.g., keep auto-detect
wording for Claude Code, Cursor, Windsurf, Cline and append a clause like
"Continue.dev — advisory (may require manual setup)" so readers are not misled
about automation, ensuring `SKILL.md` mention remains.

🪄 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: 3195e419-b409-4a63-81e3-6991ed763392

📥 Commits

Reviewing files that changed from the base of the PR and between 1e68cf7 and b07271e.

📒 Files selected for processing (1)

• README.md

[naorsabag]

Both nits addressed in b7efb08:

• Tier-1 install row now says "Cline (Continue.dev support is advisory)" so the row matches the badge's advisory mark.
• Contributor row uses the real git clone https://github.com/naorsabag/OpenHop.git && cd OpenHop && … command instead of the git clone … placeholder.

[coderabbitai]

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 `@README.md`:
- Line 66: Update the Tier-1 install row and badge bar to include Continue.dev
with the advisory note: modify the table cell containing the install text
"Claude Code, Cursor, Windsurf, Cline" (the string used with the `npx openhop
init` install guidance) to add "Cline (Continue.dev support is advisory)" or
append "Continue.dev (advisory)" next to Cline, and ensure the top badge bar
includes a Tier-1 mention for Continue.dev with the same advisory wording so the
README text and badges match the PR summary.
- Around line 28-30: Update the README badge bar so it matches the install-table
and feature descriptions: either replace the Codex badge with Windsurf and Cline
badges (so the badge bar lists "Windsurf" and "Cline" alongside Claude Code and
Cursor) or add a short clarifying sentence next to the badge bar explaining that
badges are not strictly the Tier-1 "npx openhop init" clients and that Codex is
shown for historical/third-party reasons; adjust the badge alt text and links
for the chosen badges and ensure consistency with the "npx openhop init" and
"npx openskills install" references elsewhere (search for "Codex", "Windsurf",
"Cline", "npx openhop init", and "npx openskills install" to find the badge bar
and install table to update).

🪄 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: f7177af9-075a-4351-a946-635520080a91

📥 Commits

Reviewing files that changed from the base of the PR and between b7efb08 and f9aa3fd.

📒 Files selected for processing (1)

• README.md

[naorsabag]

Round 2 review:

• README:66 (Continue.dev advisory note) — addressed in c436bd7. The init row now reads (Claude Code, Cursor, Windsurf, Cline; Continue.dev advisory). init.ts does detect Continue.dev (advisory), so dropping it from the parenthesized list was a mistake when I collapsed the tier framing.
• README:30 (badge selection mismatch with install table) — intentionally not actioned. The badge bar is a 3-client showcase (Claude Code, Cursor, Codex) chosen for recognizability, not a Tier-1 list. The exhaustive client list lives in the install table immediately below. Swapping Codex for Windsurf/Cline would lose the OpenAI signal that matters for adoption; adding clarifying prose to the badge bar would re-introduce the noise that the tier-collapse just removed. Will revisit if a real reader misreads it.