docs: refresh README positioning#322
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📜 Recent review details⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)
🧰 Additional context used🧠 Learnings (4)📓 Common learnings📚 Learning: 2026-04-24T17:08:46.780ZApplied to files:
📚 Learning: 2026-04-29T04:23:45.886ZApplied to files:
📚 Learning: 2026-04-28T03:01:37.478ZApplied to files:
🔇 Additional comments (9)
📝 WalkthroughWalkthroughREADME.md and README_CN.md updated to reposition PawWork as an open-source alternative to Codex App and Claude Desktop. Content restructured with new "Why PawWork", "What You Can Ask PawWork To Do", "Models, Plans, and Search", and "How It Works" flows; build instruction changed to Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Review rate limit: 1/3 review remaining, refill in 22 minutes and 27 seconds. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 27: Update the phrase "Open source control" to the hyphenated form
"Open-source control" in the README; locate the section/heading containing the
exact text "Open source control" and replace it with "Open-source control" so
the compound adjective is correctly hyphenated.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: b3c02ec5-c21e-4de9-a4d5-e0b49083feb1
⛔ Files ignored due to path filters (2)
assets/readme/pawwork-home.pngis excluded by!**/*.pngassets/readme/pawwork-session.svgis excluded by!**/*.svg
📒 Files selected for processing (2)
README.mdREADME_CN.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)
- GitHub Check: smoke-macos-arm64
- GitHub Check: unit-windows-opencode-session
- GitHub Check: unit-windows-opencode-server-tools
- GitHub Check: unit-windows-app
- GitHub Check: unit-windows-desktop
- GitHub Check: unit-windows-opencode-config-project
- GitHub Check: unit-desktop
- GitHub Check: typecheck
- GitHub Check: unit-app
- GitHub Check: unit-opencode
- GitHub Check: analyze-js-ts
- GitHub Check: e2e-artifacts
🧰 Additional context used
🧠 Learnings (4)
📓 Common learnings
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 224
File: packages/app/src/i18n/zh.ts:0-0
Timestamp: 2026-04-24T17:08:46.780Z
Learning: In Astro-Han/pawwork PR `#224`, the first-occurrence `PawWork 爪印` branding rule originally specified in issue `#196` was superseded by an updated Chinese-branding spec. On all zh UI surfaces in `packages/app/src/i18n/zh.ts` (e.g., `dialog.model.unpaid.freeModels.title`, `session.new.subtitle`, `sidebar.gettingStarted.line1`), the correct and intentional target is fully localized `爪印` branding — no `PawWork` prefix. Do NOT flag these strings as missing the first-occurrence `PawWork 爪印` rule in future reviews.
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 270
File: packages/opencode/src/tool/edit.ts:48-48
Timestamp: 2026-04-28T08:14:31.436Z
Learning: In `packages/opencode/src/tool/edit.ts` (Astro-Han/pawwork), the `filePath` schema description (`"The absolute path to the file to modify"`) is upstream-inherited from `dev:packages/opencode/src/tool/edit.ts:48`. The runtime actually accepts relative paths (resolved via `Instance.directory` at lines 79-81), but the description fix is intentionally deferred to a single PawWork-authored description-cleanup PR that will also cover the identical mismatch in `packages/opencode/src/tool/write.ts:24`. Do NOT re-flag the too-narrow `filePath` description in upstream-sync PRs; flag it only in the dedicated description-cleanup PR.
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 224
File: packages/desktop-electron/electron-builder.config.ts:14-18
Timestamp: 2026-04-24T17:12:26.774Z
Learning: In Astro-Han/pawwork, the `localizedMacDisplayNameByChannel` map in `packages/desktop-electron/electron-builder.config.ts` is intentionally kept separate from `localizedAppDisplayName` in `packages/desktop-electron/src/main/app-display-name.ts`. The former is a build-time packaging helper; the latter is a runtime UI helper that localizes the current app name by locale. Coupling them would introduce a build-time dependency on runtime main logic. Do not suggest deduplicating or sharing this mapping — the explicit local table is covered by focused regression tests in `electron-builder-app-update.test.ts`.
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 98
File: packages/desktop-electron/src/main/menu-labels.ts:1-2
Timestamp: 2026-04-22T05:32:29.012Z
Learning: In Astro-Han/pawwork, the app i18n layer (`packages/app/src/i18n/`) only contains `en.ts` and `zh.ts`, and `normalizeLocale` (in `packages/app/src/context/language.tsx`) only returns `"en"` or `"zh"`. The desktop `MenuLocale = "en" | "zh"` union in `packages/desktop-electron/src/main/menu-labels.ts` is intentionally limited to these two locales and is not a broader restriction — do not flag it as overly restrictive or suggest adding other locales.
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 126
File: packages/ui/src/theme/context.tsx:11-16
Timestamp: 2026-04-22T09:32:58.310Z
Learning: In Astro-Han/pawwork (`packages/ui/src/theme/context.tsx` and related files), the renaming of localStorage theme keys from `opencode-*` to `pawwork-*` (THEME_ID, COLOR_SCHEME, THEME_CSS_LIGHT, THEME_CSS_DARK) is intentional and should NOT include a migration path from the old keys. Migrating would re-couple PawWork and OpenCode browser storage namespaces, which the PR is explicitly designed to avoid. A reset to the PawWork default theme on upgrade is acceptable by design.
📚 Learning: 2026-04-24T17:08:46.780Z
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 224
File: packages/app/src/i18n/zh.ts:0-0
Timestamp: 2026-04-24T17:08:46.780Z
Learning: In Astro-Han/pawwork PR `#224`, the first-occurrence `PawWork 爪印` branding rule originally specified in issue `#196` was superseded by an updated Chinese-branding spec. On all zh UI surfaces in `packages/app/src/i18n/zh.ts` (e.g., `dialog.model.unpaid.freeModels.title`, `session.new.subtitle`, `sidebar.gettingStarted.line1`), the correct and intentional target is fully localized `爪印` branding — no `PawWork` prefix. Do NOT flag these strings as missing the first-occurrence `PawWork 爪印` rule in future reviews.
Applied to files:
README.mdREADME_CN.md
📚 Learning: 2026-04-28T08:14:31.436Z
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 270
File: packages/opencode/src/tool/edit.ts:48-48
Timestamp: 2026-04-28T08:14:31.436Z
Learning: In `packages/opencode/src/tool/edit.ts` (Astro-Han/pawwork), the `filePath` schema description (`"The absolute path to the file to modify"`) is upstream-inherited from `dev:packages/opencode/src/tool/edit.ts:48`. The runtime actually accepts relative paths (resolved via `Instance.directory` at lines 79-81), but the description fix is intentionally deferred to a single PawWork-authored description-cleanup PR that will also cover the identical mismatch in `packages/opencode/src/tool/write.ts:24`. Do NOT re-flag the too-narrow `filePath` description in upstream-sync PRs; flag it only in the dedicated description-cleanup PR.
Applied to files:
README.md
📚 Learning: 2026-04-22T09:32:58.310Z
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 126
File: packages/ui/src/theme/context.tsx:11-16
Timestamp: 2026-04-22T09:32:58.310Z
Learning: In Astro-Han/pawwork (`packages/ui/src/theme/context.tsx` and related files), the renaming of localStorage theme keys from `opencode-*` to `pawwork-*` (THEME_ID, COLOR_SCHEME, THEME_CSS_LIGHT, THEME_CSS_DARK) is intentional and should NOT include a migration path from the old keys. Migrating would re-couple PawWork and OpenCode browser storage namespaces, which the PR is explicitly designed to avoid. A reset to the PawWork default theme on upgrade is acceptable by design.
Applied to files:
README.md
🪛 LanguageTool
README.md
[uncategorized] ~27-~27: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...viders, and supported coding plans. - Open source control: inspect the code, choose you...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🔇 Additional comments (5)
README_CN.md (3)
11-14: 定位与模型账号说明清晰且与目标一致。这几段把“开箱即用 + 开源替代 + 免费额度 + BYOK/OAuth + 提供商范围”讲清楚了，和本次 README 更新目标对齐。
Also applies to: 59-64
67-71: 下载与平台说明准确。macOS 已签名/公证、Windows x64 未签名与 SmartScreen 提示都表达得清楚，减少了用户首次下载时的歧义。
78-83: 源码运行命令修正正确。
bun run dev:desktop放在仓库根目录执行，和 issue 里要求的修正一致。README.md (2)
11-14: Core positioning and plans/search messaging are well structured.This cleanly delivers the out-of-the-box positioning, free-start flow, and BYOK/OAuth/provider scope expected by the linked objective.
Also applies to: 59-63
67-70: Download/build instructions look correct and actionable.Platform notes are clear, and the source command update to
bun run dev:desktopfrom repo root is correct.Also applies to: 78-83
There was a problem hiding this comment.
Code Review
This pull request updates the README and README_CN.md files to better reflect the current state of the PawWork project, including new features, model support, and installation instructions. The review feedback suggests several improvements to the Chinese documentation to enhance professional tone, consistency, and clarity, such as using more formal terminology and ensuring consistent verb-first structures in lists.
Summary
Rewrites the English and Chinese README positioning around PawWork as an open-source desktop AI agent that works out of the box.
Adds a real homepage screenshot and keeps a session screenshot placeholder so the README has visual context without blocking on a second capture.
Why
The existing README was outdated against #281: it underplayed coding tasks, used stale build instructions, did not explain the current model/provider story, and described Windows support too broadly.
This refresh aligns the README with the current product direction: Codex App / Claude Desktop alternative, OpenCode Zen free quota, built-in search, task cards, multi-provider model support, and clearer macOS / Windows release notes.
Related Issue
Closes #281
How To Verify
No runtime tests were run because this is a documentation-only change.
Screenshots or Recordings
The README now includes
assets/readme/pawwork-home.pngandassets/readme/pawwork-session.svg.Checklist
dev, and my PR title and commit messages use Conventional Commits in EnglishSummary by CodeRabbit