docs: update README positioning#212
Conversation
📝 WalkthroughWalkthroughRestructures README content to present PawWork as an examples-first AI agent (adds comparison, workflow, and focus sections), expands cross‑platform download/troubleshooting guidance, and revises acknowledgements. Adds docs-only detection and conditional skipping to CodeQL and E2E GitHub Actions; updates corresponding workflow tests. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Code Review
This pull request updates the documentation in README.md and README_CN.md to reposition PawWork as an AI Agent for everyday work, adding Windows support, detailed use cases, and a comparison table. Feedback was provided to improve the macOS installation instructions by suggesting more effective methods for bypassing Gatekeeper warnings than re-downloading the app.
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`:
- Around line 52-58: Add a short "Windows first launch" one-liner to README.md
mirroring the "macOS first launch" section that advises users how to bypass
common SmartScreen prompts (e.g., use "More info" → "Run anyway" or right-click
and select "Run as administrator" / "Open" as needed), and apply the same
sentence to README_CN.md for parity; locate the existing "macOS first launch"
heading and insert the Windows note directly below it so both platforms are
covered.
🪄 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: 2bbdba25-47c9-41f6-8b6a-7083f928eb66
📒 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). (2)
- GitHub Check: e2e-artifacts
- GitHub Check: analyze-js-ts
🔇 Additional comments (3)
README_CN.md (2)
3-49: Strong positioning rewrite with clear task-first narrative.This section is concise, credible, and aligned with the “everyday work AI agent” direction. The examples/comparison/workflow structure improves readability and intent clarity.
52-58: Download and macOS first-launch guidance is clear and actionable.Good improvement on installer specificity (
.dmg/.exe) and first-launch instructions.README.md (1)
3-49: Excellent repositioning and structure for the new product direction.The messaging is approachable without dumbing down for technical users, and the “Ask/Why/How/Current Focus” flow is strong.
603994c to
6d20aa0
Compare
bd6c723 to
b745597
Compare
There was a problem hiding this comment.
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 @.github/workflows/codeql.yml:
- Around line 44-100: The docs-only filter logic (functions and variables like
is_docs_path, docs_only, the EVENT_NAME case, BASE_SHA fallback, mapfile -t
changes and the git diff parsing loop) is duplicated across workflows; extract
that entire block into a single reusable location (a composite GitHub Action or
a shell script in .github/actions or .github/scripts) that exposes the result
via outputs (e.g., docs_only) and accepts inputs (BASE_SHA/HEAD_SHA), then
update this workflow to call the shared action/script and use its output instead
of inlining is_docs_path/docs_only/git diff logic so all workflows share the
same implementation and avoid drift.
- Around line 36-114: The PR modifies the CI workflow by adding the "filter"
step and the docs_only output used to conditionally skip CodeQL (see the filter
step, the docs_only variable and the if: checks on the Initialize CodeQL /
Analyze with CodeQL steps), which conflicts with the linked objective that
required docs-only content changes; either remove these workflow changes from
this branch (revert the added filter step and the if: conditions on the CodeQL
steps) and keep only documentation edits, or move the workflow changes into a
separate infra/workflow PR and reference that PR from the current one; ensure
you update or remove the docs_only variable and the conditional uses in
Initialize CodeQL and Analyze with CodeQL if you revert the workflow change.
🪄 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: 2f19ca41-9cce-413c-b848-7ba7d6b3212b
📒 Files selected for processing (6)
.github/workflows/codeql.yml.github/workflows/e2e-artifacts.ymlREADME.mdREADME_CN.mdpackages/opencode/test/config/e2e-artifacts-workflow.test.tspackages/opencode/test/github/codeql-workflow.test.ts
📜 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: unit-windows-opencode-session
- GitHub Check: unit-windows-app
- GitHub Check: typecheck
- GitHub Check: unit-windows-opencode-server-tools
- GitHub Check: unit-windows-desktop
- GitHub Check: unit-windows-opencode-config-project
- GitHub Check: unit-opencode
- GitHub Check: unit-desktop
- GitHub Check: unit-app
- GitHub Check: smoke-macos-arm64
- GitHub Check: analyze-js-ts
- GitHub Check: e2e-artifacts
🧰 Additional context used
📓 Path-based instructions (2)
packages/opencode/**/*.ts
📄 CodeRabbit inference engine (packages/opencode/AGENTS.md)
packages/opencode/**/*.ts: UseEffect.gen(function* () { ... })for Effect composition
UseEffect.fn("Domain.method")for named/traced effects andEffect.fnUntracedfor internal helpers; these accept pipeable operators as extra arguments to avoid unnecessary outer.pipe()wrappers
UseEffect.callbackfor callback-based APIs
PreferDateTime.nowAsDateovernew Date(yield* Clock.currentTimeMillis)when you need aDatein Effect code
UseSchema.Classfor multi-field data in Effect schemas
Use branded schemas (Schema.brand) for single-value types in Effect
UseSchema.TaggedErrorClassfor typed errors in Effect schemas
UseSchema.Defectinstead ofunknownfor defect-like causes in Effect code
InEffect.gen/Effect.fn, preferyield* new MyError(...)overyield* Effect.fail(new MyError(...))for direct early-failure branches
UsemakeRuntimefromsrc/effect/run-service.tsfor all services; it returns{ runPromise, runFork, runCallback }backed by a sharedmemoMapthat deduplicates layers
UseInstanceStatefromsrc/effect/instance-state.tsfor per-directory or per-project state that needs per-instance cleanup; do work directly in theInstanceState.makeclosure whereScopedCachehandles run-once semantics
UseEffect.addFinalizerorEffect.acquireReleaseinside theInstanceState.makeclosure for cleanup (subscriptions, process teardown, etc.)
UseEffect.forkScopedinside theInstanceState.makeclosure for background stream consumers — the fiber is interrupted when the instance is disposed
PreferFileSystem.FileSysteminstead of rawfs/promisesfor effectful file I/O in Effect services
PreferChildProcessSpawner.ChildProcessSpawnerwithChildProcess.make(...)instead of custom process wrappers in Effect services
PreferHttpClient.HttpClientinstead of rawfetchin Effect services
PreferPath.Path,Config,Clock, andDateTimeservices when those concerns are already inside Effect code
For backgroun...
Files:
packages/opencode/test/github/codeql-workflow.test.tspackages/opencode/test/config/e2e-artifacts-workflow.test.ts
packages/opencode/test/**/*.test.{ts,tsx}
📄 CodeRabbit inference engine (packages/opencode/test/AGENTS.md)
packages/opencode/test/**/*.test.{ts,tsx}: Use thetmpdirfunction fromfixture/fixture.tsto create temporary directories for tests with automatic cleanup. Useawait usingsyntax to ensure automatic cleanup when the variable goes out of scope.
When using thetmpdirfunction with git repository support, pass thegit: trueoption to initialize a git repo with a root commit.
Use theconfigoption intmpdirto write anopencode.jsonconfig file during test setup by passing a partial Config.Info object.
Use theinitoption intmpdirto define custom setup functions that can return extra data accessible viatmp.extra, and use thedisposeoption for custom cleanup logic.
UsetestEffect(...)fromtest/lib/effect.tsfor tests that exercise Effect services or Effect-based workflows.
Useit.effect(...)when the test should run withTestClockandTestConsole. Useit.live(...)when the test depends on real time, filesystem mtimes, child processes, git, locks, or other live OS behavior.
Prefer Effect-aware helpers fromfixture/fixture.tsover building manual runtimes in tests: usetmpdirScoped()for scoped temp directories,provideInstance(dir)(effect)for low-level binding without directory creation,provideTmpdirInstance(...)for single temp instance binding, orprovideTmpdirServer(...)for tests that also need the test LLM server.
Defineconst it = testEffect(...)near the top of the test file and keep the test body insideEffect.gen(function* () { ... }). Yield services directly withyield* MyService.Serviceoryield* MyTool.
Avoid customManagedRuntime,attach(...), or ad hocrun(...)wrappers in Effect tests whentestEffect(...)already provides the runtime.
When a test needs instance-local state, preferprovideTmpdirInstance(...)orprovideInstance(...)over manualInstance.provide(...)inside Promise-style tests.
Files:
packages/opencode/test/github/codeql-workflow.test.tspackages/opencode/test/config/e2e-artifacts-workflow.test.ts
🧠 Learnings (9)
📚 Learning: 2026-04-20T14:36:31.032Z
Learnt from: CR
Repo: Astro-Han/pawwork PR: 0
File: packages/opencode/test/AGENTS.md:0-0
Timestamp: 2026-04-20T14:36:31.032Z
Learning: Applies to packages/opencode/test/**/*.test.{ts,tsx} : When using the `tmpdir` function with git repository support, pass the `git: true` option to initialize a git repo with a root commit.
Applied to files:
packages/opencode/test/github/codeql-workflow.test.tspackages/opencode/test/config/e2e-artifacts-workflow.test.ts
📚 Learning: 2026-04-20T14:36:31.032Z
Learnt from: CR
Repo: Astro-Han/pawwork PR: 0
File: packages/opencode/test/AGENTS.md:0-0
Timestamp: 2026-04-20T14:36:31.032Z
Learning: Applies to packages/opencode/test/**/*.test.{ts,tsx} : Use `testEffect(...)` from `test/lib/effect.ts` for tests that exercise Effect services or Effect-based workflows.
Applied to files:
packages/opencode/test/github/codeql-workflow.test.tspackages/opencode/test/config/e2e-artifacts-workflow.test.ts
📚 Learning: 2026-04-22T08:49:47.800Z
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 126
File: packages/desktop-electron/src/main/index-sidecar-source.test.ts:3-11
Timestamp: 2026-04-22T08:49:47.800Z
Learning: In `packages/desktop-electron/src/main/index-sidecar-source.test.ts` (Astro-Han/pawwork), the test intentionally uses `expect(source).toContain` / `expect(source).not.toContain` string matching against the raw `index.ts` source text as a lightweight sidecar contract guard. The maintainer has explicitly chosen not to introduce an AST parser (e.g., `babel/parser` or acorn) for this purpose. Do not flag these string-based assertions as fragile or suggest converting them to AST-based matching.
Applied to files:
packages/opencode/test/github/codeql-workflow.test.tspackages/opencode/test/config/e2e-artifacts-workflow.test.ts
📚 Learning: 2026-04-20T14:36:31.032Z
Learnt from: CR
Repo: Astro-Han/pawwork PR: 0
File: packages/opencode/test/AGENTS.md:0-0
Timestamp: 2026-04-20T14:36:31.032Z
Learning: Applies to packages/opencode/test/**/*.test.{ts,tsx} : Use the `config` option in `tmpdir` to write an `opencode.json` config file during test setup by passing a partial Config.Info object.
Applied to files:
packages/opencode/test/github/codeql-workflow.test.tspackages/opencode/test/config/e2e-artifacts-workflow.test.ts
📚 Learning: 2026-04-23T08:51:00.819Z
Learnt from: Astro-Han
Repo: Astro-Han/pawwork PR: 186
File: packages/opencode/test/plugin/workspace-adaptor.test.ts:139-144
Timestamp: 2026-04-23T08:51:00.819Z
Learning: For pawwork tests under packages/opencode/test/**, auth.json teardown may intentionally combine `Filesystem.write` (from `packages/opencode/src/util/filesystem.ts`) with `node:fs/promises` `unlink` for cleanup. Do not flag this as inconsistent style; it is the established/intentional pattern because `Filesystem` does not provide a `remove`/`unlink` helper.
Applied to files:
packages/opencode/test/github/codeql-workflow.test.tspackages/opencode/test/config/e2e-artifacts-workflow.test.ts
📚 Learning: 2026-04-20T14:36:04.113Z
Learnt from: CR
Repo: Astro-Han/pawwork PR: 0
File: packages/app/e2e/AGENTS.md:0-0
Timestamp: 2026-04-20T14:36:04.113Z
Learning: Applies to packages/app/e2e/**/*.spec.ts : Test one feature per test file
Applied to files:
packages/opencode/test/config/e2e-artifacts-workflow.test.ts
📚 Learning: 2026-04-20T14:36:04.113Z
Learnt from: CR
Repo: Astro-Han/pawwork PR: 0
File: packages/app/e2e/AGENTS.md:0-0
Timestamp: 2026-04-20T14:36:04.113Z
Learning: Applies to packages/app/e2e/**/*.spec.ts : Test files should be named with the pattern `feature-name.spec.ts`
Applied to files:
packages/opencode/test/config/e2e-artifacts-workflow.test.ts
📚 Learning: 2026-04-20T14:36:04.113Z
Learnt from: CR
Repo: Astro-Han/pawwork PR: 0
File: packages/app/e2e/AGENTS.md:0-0
Timestamp: 2026-04-20T14:36:04.113Z
Learning: Applies to packages/app/e2e/**/*.spec.ts : Import test utilities from `../fixtures` instead of `playwright/test`
Applied to files:
packages/opencode/test/config/e2e-artifacts-workflow.test.ts
📚 Learning: 2026-04-20T14:36:31.032Z
Learnt from: CR
Repo: Astro-Han/pawwork PR: 0
File: packages/opencode/test/AGENTS.md:0-0
Timestamp: 2026-04-20T14:36:31.032Z
Learning: Applies to packages/opencode/test/**/*.test.{ts,tsx} : Define `const it = testEffect(...)` near the top of the test file and keep the test body inside `Effect.gen(function* () { ... })`. Yield services directly with `yield* MyService.Service` or `yield* MyTool`.
Applied to files:
packages/opencode/test/config/e2e-artifacts-workflow.test.ts
🔇 Additional comments (5)
README_CN.md (1)
3-77: 中文 README 的定位和平台引导更新到位。这版文案把“日常工作 Agent”的定位、任务示例和首启说明都讲清楚了，且与英文结构保持一致。
README.md (1)
3-77: README positioning rewrite is clear and execution-focused.The “Ask PawWork to…” flow, comparison table, and cross-platform first-launch notes improve clarity without overloading technical detail.
packages/opencode/test/github/codeql-workflow.test.ts (1)
16-55: Workflow test assertions are well aligned with the new docs-only gating behavior.Good coverage on step presence,
ifguards,env, and filter script intent..github/workflows/e2e-artifacts.yml (1)
41-166: E2E docs-only gating is implemented consistently across setup, execution, and artifact steps.The conditions are applied comprehensively, and non-docs failure diagnostics remain preserved.
packages/opencode/test/config/e2e-artifacts-workflow.test.ts (1)
15-68: Test coverage for docs-only skip behavior is thorough and aligned with workflow logic.The new assertions appropriately lock down
filtersemantics and conditional execution paths.
b745597 to
2c03238
Compare
Summary
README.mdandREADME_CN.mdaround PawWork as an open-source desktop AI agent for everyday workWhy
The current README was outdated and undersold PawWork's direction. It still read like a lightweight office tool, did not explain why PawWork goes beyond chat, and still listed macOS Apple Silicon only. This PR aligns the README copy with issue #134 and the current product direction.
Related Issue
Closes #134
How To Verify
git diff --check -- README.md README_CN.md rg -n "AI workflow|workbench|super app|fully autonomous|artifact|BYOK|Your data never leaves|Apple_Silicon|TODO: add screenshot|添加截图|普通话" README.md README_CN.mdManual checks:
Screenshots or Recordings
N/A. README copy only, no visible app UI change.
Checklist
dev, and my PR title and commit messages use Conventional Commits in English