Skip to content

docs(readme): swap features for live demo, sharing, and token-use sections#140

Merged
naorsabag merged 8 commits into
masterfrom
docs/readme-live-demo-token-share
May 12, 2026
Merged

docs(readme): swap features for live demo, sharing, and token-use sections#140
naorsabag merged 8 commits into
masterfrom
docs/readme-live-demo-token-share

Conversation

@naorsabag
Copy link
Copy Markdown
Owner

@naorsabag naorsabag commented May 12, 2026

Summary

  • Rewrite the Why section to lead with the animated step-through + drill-down differentiation versus static Mermaid/PlantUML pictures (you walk it at your own pace, with Play / Pause / Prev / Next, and can drill into sub-flows).
  • Drop the Features list and add a dedicated Live demo section pointing at https://naorsabag.github.io/openhop/ as the no-install entry point.
  • Add a Sharing flows section that explains the URL-fragment share path through the Pages deploy (Save → hash-encoded URL → clipboard → anyone can open).
  • Add a Token use section with a 3-row table (simple-crud, auth-flow, order-flow) showing estimated YAML tokens, plus a ranged 5–15× claim against an agent's prose walkthrough. Estimates are framed as estimates (≈ 1 token / 4 chars), not measurements — happy to swap in real cl100k_base numbers in a follow-up if preferred.
  • Refresh the TOC to match (Live demo, Token use, Sharing anchors added).

No behavior or schema changes; README-only.

Test plan

  • Render the README on GitHub and check that TOC anchors land on the new sections.
  • Confirm the live demo link (https://naorsabag.github.io/openhop/) and the share-URL flow described in Sharing flows still match the playground behavior.
  • Eyeball the token-use table — confirm the step counts and file sizes are still accurate (they're tied to examples/*.yaml).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Updated README with “Live demo”, “Token use”, and “Sharing flows” sections
    • Reframed onboarding to emphasize an animated, multi-level data-flow experience with step-through playback and drill-down
    • Added token-light YAML guidance with per-step token sizing and prose-size comparisons
    • Documented playground URL-hash sharing (no upload) and direct-YAML fallback for larger flows

Review Change Stack

…tions

- Rewrite Why bullets to lead with the animated step-through + drill-down differentiation versus static Mermaid/PlantUML pictures.
- Drop the Features list and add a Live demo section pointing at the GitHub Pages playground.
- Add a Sharing flows section that documents the URL-fragment share path through the Pages deploy.
- Add a Token use section with an estimated-token table for three example flows and a ranged prose-comparison claim.
- Refresh the TOC to match.
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 12, 2026

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

Walkthrough

README.md content updated: top navigation links reorganized; the hero tagline added “Token-light”; the "Why" section rewritten to describe animated, step-through, multi-level YAML-rendered data-flows; new "Live demo" and "Token use" sections added; and a "Sharing flows" section documents URL-hash sharing and large-flow sharing guidance.

Changes

README Documentation Updates

Layer / File(s) Summary
Navigation, hero tagline, and 'Why' narrative
README.md
Top navigation now includes Live demo, Token use, Install, Quickstart, and Sharing. The hero tagline adds “Token-light”. The "Why" section is replaced with copy describing animated, step-through, multi-level data-flow diagrams authored in compact YAML and local-first/no-telemetry behavior.
Live demo and token guidance
README.md
Added "Live demo" with the playground URL and a "Token use" section explaining compact YAML sizing and per-step token guidance (~100 tokens per step); removed the previous Features list.
Sharing flows documentation
README.md
Added "Sharing flows" instructions describing playground URL-hash encoding (no upload) and advising to share very large flows by sending the YAML file directly.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • naorsabag/openhop#124: Overlapping README edits introducing local-first/no-telemetry messaging and URL-fragment (playground) sharing details.
  • naorsabag/openhop#87: Related README navigation and "Why" section rewrite emphasizing animated YAML data-flow presentation.
  • naorsabag/openhop#125: Similar edits to hero/navigation/demo copy and Live demo link updates.
🚥 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 summarizes the main change: replacing the 'Features' section with 'Live demo', 'Token use', and 'Sharing' sections in 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 docs/readme-live-demo-token-share

Warning

Review ran into problems

🔥 Problems

Timed out fetching pipeline failures after 30000ms


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.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
README.md (1)

1-242: ⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

CI pipeline blocked by Prettier formatting violations.

All CI jobs are failing because the README does not match Prettier's formatting rules. Run prettier --write README.md to fix before merging.

🤖 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 `@README.md` around lines 1 - 242, CI is failing because README.md doesn't
match Prettier formatting; run Prettier to reformat the file and commit the
result. Fix: run prettier --write README.md (or your repo's npm script like npm
run format) locally, review the changed README.md edits, stage and commit them
so the CI Prettier check passes; locate the README's top-level headings and
badge/image blocks (the "OpenHop" title and the badge/image sections) when
verifying the formatted output.
🤖 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.

Outside diff comments:
In `@README.md`:
- Around line 1-242: CI is failing because README.md doesn't match Prettier
formatting; run Prettier to reformat the file and commit the result. Fix: run
prettier --write README.md (or your repo's npm script like npm run format)
locally, review the changed README.md edits, stage and commit them so the CI
Prettier check passes; locate the README's top-level headings and badge/image
blocks (the "OpenHop" title and the badge/image sections) when verifying the
formatted output.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c4a875ee-373f-45ed-af0b-e7842952df6d

📥 Commits

Reviewing files that changed from the base of the PR and between d4fce83 and d9d4894.

📒 Files selected for processing (1)
  • README.md

@naorsabag naorsabag merged commit dd66868 into master May 12, 2026
7 checks passed
naorsabag added a commit that referenced this pull request May 13, 2026
Cuts the first release since v0.2.0 on 2026-05-11. The publish workflow
auto-publishes each package whose package.json version differs from the
registry, then tags v0.3.0 and creates the GitHub release.

Versions:
- @openhop/server  0.2.0 -> 0.3.0
- @openhop/web     0.2.0 -> 0.3.0
- openhop (CLI)    0.2.0 -> 0.3.0
- CLI's pinned deps on server + web also bumped to 0.3.0.

CHANGELOG: promotes the existing [Unreleased] block to [0.3.0] with the
two user-visible shipping changes since v0.2.0:
- Skill triggers broadened (#143) — diagram / visualization / walkthrough
  prompts about products, features, workflows, user journeys, etc. now
  route to OpenHop, not just code walkthroughs. Adds an explicit
  negative gate to keep generic explainer prompts ("how does TCP work?")
  from over-activating the skill.
- INSPECT panel defaults to bottom-dock on mobile (#142) — narrow
  viewports keep the canvas full-width when the user opens the
  inspector.

plumbing and not changelogged. #140 / #141 only touched the README and
do not ship in any tarball.
naorsabag added a commit that referenced this pull request May 13, 2026
* chore: bump @openhop/server @openhop/web openhop to 0.3.0

Cuts the first release since v0.2.0 on 2026-05-11. The publish workflow
auto-publishes each package whose package.json version differs from the
registry, then tags v0.3.0 and creates the GitHub release.

Versions:
- @openhop/server  0.2.0 -> 0.3.0
- @openhop/web     0.2.0 -> 0.3.0
- openhop (CLI)    0.2.0 -> 0.3.0
- CLI's pinned deps on server + web also bumped to 0.3.0.

CHANGELOG: promotes the existing [Unreleased] block to [0.3.0] with the
two user-visible shipping changes since v0.2.0:
- Skill triggers broadened (#143) — diagram / visualization / walkthrough
  prompts about products, features, workflows, user journeys, etc. now
  route to OpenHop, not just code walkthroughs. Adds an explicit
  negative gate to keep generic explainer prompts ("how does TCP work?")
  from over-activating the skill.
- INSPECT panel defaults to bottom-dock on mobile (#142) — narrow
  viewports keep the canvas full-width when the user opens the
  inspector.

plumbing and not changelogged. #140 / #141 only touched the README and
do not ship in any tarball.

* docs(changelog): add [0.3.0] link ref + point [Unreleased] at v0.3.0
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