docs: sell-focused README + extracted developer guide#9
Conversation
Reframe the README around end users who download and use the app rather than developers building from source. Lead with the value proposition, hero screenshot, benefit-led feature list, install path (with the unsigned-app first-launch note), and a privacy/local-first section. Move all setup, run, CLI, and release commands into docs/development.md, and add docs/images/README.md documenting the expected screenshots.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request restructures the project documentation by updating the main README.md with a more engaging layout, adding visual assets, and moving development-specific instructions to a new docs/development.md file. A docs/images/README.md was also added to track screenshot requirements. The review feedback suggests using lowercase letters for keyboard shortcuts in the README to avoid confusion about holding the Shift key, and correcting a reference in the development guide that incorrectly implies go-fmt is used to format TypeScript and Vue files.
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.
- Use lowercase keyboard shortcuts in README (j/k/v/c) per convention - Drop misleading 'through go-fmt' in formatting note (it can't format TS/Vue)
# Conflicts: # README.md
1 participant
What
Reworks the project docs to sell the app to end users and separates the build/run instructions from the pitch.
README.md— rewritten as a product pitch (end-user first):.dmg+ planned Homebrew, with the unsigned-app first-launch note), privacy/local-first section, and a slim Build from source handoff that keeps the workspace-layout table.docs/development.md(new) — all setup, run, dev, backend CLI, formatting, review-data, and release commands moved out of the README.docs/images/README.md(new) — documents the five expected screenshot filenames the README references.Why
The previous README opened with architecture and
pnpmcommands — it read like setup docs and never showed what the app looks like. For an app whose goal is to win over people who download and use it, the pitch was buried. This leads with the value and moves the developer workflow to its own guide.Notes for reviewers
docs/images/*.png; those PNGs are not in this PR yet, so they render as broken until captures are added (filenames documented indocs/images/README.md). The hero capture exists and just needs saving todocs/images/hero.png.docs/development.md, and the README no longer contains build/run command blocks.