Skip to content

docs: rework README hero to lead with BYOK + OAuth framing#1055

Merged
Astro-Han merged 3 commits into
devfrom
claude/readme-rework
Jun 2, 2026
Merged

docs: rework README hero to lead with BYOK + OAuth framing#1055
Astro-Han merged 3 commits into
devfrom
claude/readme-rework

Conversation

@Astro-Han

@Astro-Han Astro-Han commented Jun 2, 2026

Copy link
Copy Markdown
Owner

Summary

Two changes:

  1. README hero rework (README.md, README_CN.md): Lead the English README hero with the open-source-alternative framing and BYOK + ChatGPT OAuth proposition. Fix the comparison target from Claude Desktop (chat app) to Claude Cowork (Anthropic's 2026-04 GA desktop agent — the actual same-category competitor in 2026) in both README and README_CN.
  2. Labeler plumbing fix (.github/labeler.yml): Route README files to the app routing label so README-only PRs can satisfy the pr-triage routing-label requirement without a manual label dance.

Why

For the README rework: The previous hero ("AI agent that works out of the box on your desktop") and the OpenCode-Zen-free-plan pitch optimize for non-technical Chinese-channel readers (Xiaohongshu / Zhihu). They soften the hook for the English audience that the upcoming outbound push targets: Codex App and Claude Cowork users with paid plans or developer-grade BYOK habits.

The new hero lines explicitly position PawWork against the two same-category 2026 desktop agents (Codex App, Claude Cowork) and surface BYOK + ChatGPT OAuth as the persistent value. BYOK is the main proposition; OAuth is an "including" enumeration that survives even if OpenAI later changes its OAuth policy (Anthropic already closed third-party OAuth reuse in 2026).

The OpenCode Zen free-plan pitch still appears in the "Less setup" bullet and the "Models, Plans, and Search" section, so non-technical English readers still find an on-ramp; only the hero is reframed.

README_CN.md keeps the existing Chinese-friendly framing (开箱即用 + OpenCode Zen 免费额度) because the Xiaohongshu / Zhihu audience profile matches that framing. The Chinese file only fixes the same factual error (Claude Desktop → Claude Cowork).

For the labeler fix: README.md / README_CN.md don't match any existing routing label glob (labeler only watches packages/** paths), but pr-triage requires every PR to carry one of app / ui / platform / harness / ci. Without this small labeler tweak, README-only PRs fail pr-triage even when documentation + priority labels are set correctly. README is product-facing documentation for the app shell, so the app routing label is the semantically correct home.

Related Issue

None. Driven by the outbound launch shaping session, not a tracked issue.

Human Review Status

Pending.

Review Focus

  • Whether "Open-source alternative to Codex App and Claude Cowork" is acceptable as the English hero subtitle.
  • Whether "Bring your own key, works with any model — including ChatGPT OAuth" reads correctly for English-speaking developers.
  • Whether dropping the OpenCode Zen free-plan pitch from the hero (but keeping it lower in the README) is the right balance for English readers.
  • Whether the Claude Desktop → Claude Cowork rename matches the 2026 product reality you want to reference.
  • Whether routing README files to the app label is the right home (vs documentation-as-routing, ci, or a new dedicated label).

Risk Notes

  • ChatGPT OAuth policy risk: if OpenAI later restricts third-party OAuth reuse the way Anthropic did, the "including ChatGPT OAuth" enumeration can be removed without touching the rest of the hero. BYOK is the main hook, so the framing survives.
  • Chinese / English narrative split is intentional. Two channel audiences with different paid-plan habits; tracked in the local outbound plan rather than reconciled at the README level.
  • No app code changed; no platform, packaging, signing, updater, or permissions impact.
  • Labeler change applies retroactively to any future README PR — semantics are stable, no migration needed.

How To Verify

Local diff review: README.md +4/-5, README_CN.md +1/-1, .github/labeler.yml +2/-0
Rendered preview: README.md hero shows the two-line subtitle on github.com PR preview; cover alt text updated to match.
Labeler effect verified by pr-triage rerun after the labeler.yml commit lands.
No code or asset changes; no build / typecheck / test required.

Screenshots or Recordings

Not needed. Text-only README and YAML changes; reviewers can use the PR file diff preview.

Checklist

  • Type labeldocumentation (author-applied).
  • Routing labelsapp (labeler will assign automatically after the labeler.yml commit lands).
  • Priority labelP3 (priority-triage bot assigned).
  • Human Review Status above is set to Pending.
  • I linked the related issue, or stated in Summary why there is no issue.
  • I described the review focus and any meaningful risks.
  • I listed the relevant verification steps and the key result for each.
  • I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope (the labeler change is the smallest plumbing fix that makes the README scope mergeable).
  • I manually checked visible UI or copy changes when needed, with screenshots or recordings (text-only change, PR diff preview is sufficient).
  • I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes (no platform impact; text-only).
  • I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant.
  • I reviewed the final diff for unrelated changes and suspicious dependency changes.
  • I am targeting dev, and my PR title and commit messages use Conventional Commits in English.

Summary by CodeRabbit

  • Documentation
    • Updated product positioning and description in README to emphasize compatibility with any model, including ChatGPT OAuth, and "Bring your own key" approach.
    • Updated Chinese README to reflect the new product positioning.

Lead the README hero with the open-source alternative framing and
BYOK + ChatGPT OAuth proposition. The previous hero ("AI agent that
works out of the box") and the OpenCode-Zen-free-plan pitch were
optimized for non-technical Chinese-channel users; they soften the
hook for the English audience (Codex / Claude Cowork users with paid
plans or developer-grade BYOK habits).

Also correct the comparison target from Claude Desktop (the chat app)
to Claude Cowork (Anthropic's 2026-04 GA desktop agent that is the
actual same-category competitor in 2026).

Keep the OpenCode Zen free-plan pitch in 'Less setup' and 'Models,
Plans, and Search' so that non-technical readers still find an
on-ramp; only the hero is reframed.

README_CN.md keeps the existing Chinese-friendly framing (open-box +
OpenCode Zen free plan); only fixes the same Claude Desktop ->
Claude Cowork factual error.

Cover image alt text follows the new hero.
@Astro-Han Astro-Han added the documentation Improvements or additions to documentation label Jun 2, 2026
@coderabbitai

coderabbitai Bot commented Jun 2, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

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: b00a660f-db1c-461f-a73e-8915b9db6b4f

📥 Commits

Reviewing files that changed from the base of the PR and between 043831b and ecb3127.

📒 Files selected for processing (3)
  • .github/labeler.yml
  • README.md
  • README_CN.md

📝 Walkthrough

Walkthrough

This pull request updates product positioning messaging across documentation and labeler configuration. The English and Chinese README introductions are refreshed to emphasize PawWork as a Claude Cowork alternative supporting any model with a bring-your-own-key approach, and the GitHub labeler configuration is expanded to track changes to these README files.

Changes

Product Positioning Refresh

Layer / File(s) Summary
Product messaging and labeler configuration updates
README.md, README_CN.md, .github/labeler.yml
English README intro reposition from open-source AI agent to Cowork alternative with bring-your-own-key emphasis; Chinese README updated to match Cowork reference; labeler config expanded to trigger app label on README documentation changes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

  • Astro-Han/pawwork#322: Modifies the same README documentation files to update PawWork's positioning messaging and Claude product references.
  • Astro-Han/pawwork#212: Updates README documentation positioning and product framing copy across README.md and README_CN.md.

Suggested labels

app

Poem

🐰 A readme refresh hops into view,
Cowork and Claude get the messaging true,
"Bring your own key," the new tune we sing,
With labeler rules to track everything! 🌟

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main change: reworking the README hero to lead with BYOK and OAuth framing, which is the primary documentation update in this PR.
Description check ✅ Passed The description is comprehensive and follows the template well, covering Summary, Why, Related Issue, Human Review Status, Review Focus, Risk Notes, How To Verify, Screenshots, and a fully completed Checklist.
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 claude/readme-rework

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.

@github-actions github-actions Bot added the P3 Low priority label Jun 2, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggested priority: P3 (only low-risk paths changed (README.md, README_CN.md)).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Code Review

This pull request updates the English and Chinese README files to position PawWork as an open-source alternative to Codex App and Claude Cowork, highlighting features like bringing your own API key and ChatGPT OAuth support. The review feedback suggests improving the English grammar in the tagline and clarifying the distinction between using ChatGPT Plus/Pro plans via OAuth versus bringing an OpenAI API key.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Comment thread README.md Outdated
Comment thread README.md Outdated
@Astro-Han Astro-Han added the app Application behavior and product flows label Jun 2, 2026
@github-actions github-actions Bot removed the app Application behavior and product flows label Jun 2, 2026
pr-triage requires every PR to carry one of app / ui / platform /
harness / ci routing labels, but the labeler rules only watched
package paths. README.md and README_CN.md are product-facing
documentation for the app shell, so they belong to the app routing
label rather than ci. Without this, README-only PRs fail pr-triage
even when documentation + priority labels are set correctly.

Adding the README files to the app rule keeps the routing semantics
consistent (README pitches the app product) and removes the manual
label dance for future docs-only PRs.

This change rides on the README rework PR because the rework is what
exposed the gap; the labeler diff is small, mechanical, and required
for the rework to merge.
@github-actions github-actions Bot added ci Continuous integration / GitHub Actions P2 Medium priority and removed P3 Low priority labels Jun 2, 2026
Two grammar / accuracy fixes from Gemini Code Assist review:

1. Hero subtitle had a comma splice that combined an imperative
   clause with a 3rd-person clause that has a different subject
   ("Bring your own key" -> you, "works with any model" -> PawWork).
   Split into two sentence fragments so the second clause reads as
   a product capability (subject implicit = PawWork), matching the
   first-line fragment style.

2. First paragraph said "Use your ChatGPT Plus/Pro plan for OpenAI"
   which is ambiguous because the plan flows through OAuth rather
   than as a direct OpenAI API key, and the line did not surface
   that OpenAI direct API keys are also supported via /connect ->
   Manually enter API Key. Clarify "via OAuth" and add OpenAI to
   the API-key provider list.
@Astro-Han Astro-Han merged commit 9843b0d into dev Jun 2, 2026
35 checks passed
@Astro-Han Astro-Han deleted the claude/readme-rework branch June 2, 2026 11:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci Continuous integration / GitHub Actions documentation Improvements or additions to documentation P2 Medium priority

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant