docs: sell-focused README + extracted developer guide

README.md

@@ -1,142 +1,124 @@
-# Git Diff Review
-
-Git Diff Review is a native macOS app for reviewing local Git changes before
-they are committed. It gives a GitHub-style review surface for a working tree:
-file navigation, staged/unstaged/untracked diffs, split or unified views,
-viewed-file tracking, review notes, and inline comments stored locally.
+<div align="center">
 
-The desktop app is built with Electron, Vue, and TypeScript. A Go backend reads
-repository state through Git, serves a local HTTP API over a Unix socket, and
-persists review sessions in SQLite.
+<img src="packages/ui/public/icon-512.png" alt="Git Diff Review" width="120" />
 
-## What It Does
+# Git Diff Review
 
-- opens any local Git repository;
-- shows changed files with additions, deletions, status, and rename metadata;
-- renders staged, unstaged, and untracked patches;
-- supports split and unified diff modes;
-- can hide whitespace-only diff noise;
-- tracks viewed files per repository in local storage;
-- creates local review sessions with rich-text summaries;
-- stores inline review comments and timeline events in SQLite;
-- runs as a packaged macOS app or as a local development stack.
+**Review your local Git changes like a pull request — before you commit.**
+**On your machine. Nothing leaves it.**
 
-This is a local review tool. It does not publish comments to GitHub, create pull
-requests, or modify the repository contents.
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Platform: macOS (Apple Silicon)](https://img.shields.io/badge/platform-macOS%20(Apple%20Silicon)-black)
+[![Latest release](https://img.shields.io/github/v/release/oullin/git-diff?label=download)](https://github.com/oullin/git-diff/releases)
 
-## Workspace Layout
+![Git Diff Review reviewing a working tree](docs/images/hero.png)
 
-| Path                  | Role                                                         |
-| --------------------- | ------------------------------------------------------------ |
-| `packages/ui`         | Electron/Vue desktop app and renderer UI.                    |
-| `packages/bridge`     | TypeScript HTTP client used by Electron.                     |
-| `packages/domain`     | Shared DTOs + framework-agnostic diff logic, consumed by `ui` and `bridge`. |
-| `packages/api`        | Go backend that reads Git diffs and stores reviews.          |
-| `packages/tools`      | Turbo cache wrapper and unsigned macOS release helper.       |
+</div>
 
-## Requirements
+Git Diff Review is a native macOS app that gives you a full GitHub-style review
+surface for your **local working tree**. Open any repository, walk every changed
+file, read the diff in split or unified view, mark files as you review them, leave
+yourself notes and inline comments — then commit with confidence. It never pushes
+your code anywhere.
 
-- macOS
-- Git
-- Go
-- Node.js with Corepack
-- pnpm `10.33.0`
+## Why you need it
 
-Enable pnpm through Corepack if needed:
+You commit changes you never actually re-read. `git diff` in the terminal is
+cramped and easy to skim past. Opening a real pull request just to review your own
+work is heavyweight — and it forces your code onto a server before it's ready.
 
-```sh
-corepack enable
-corepack prepare pnpm@10.33.0 --activate
-```
+Git Diff Review gives you the **pull-request review experience, locally**:
 
-## Quick Start
+- Catch the debug log, the stray `TODO`, the half-finished refactor *before* it
+  lands in history.
+- Review with the same muscle memory you already have from GitHub — file list,
+  viewed checkboxes, split diffs, inline comments.
+- Keep everything on your machine. No cloud, no sign-up, no telemetry.
 
-From the repository root:
+## What you get
 
-```sh
-pnpm install
-pnpm build
-pnpm --filter ui start
-```
+- **A real review surface.** Navigate changed files with status badges and
+  addition/deletion counts, jump between hunks, and search files across all your
+  repos at once.
+- **Staged, unstaged, and untracked** — see every kind of change, with rename
+  detection and whitespace noise you can hide.
+- **Split or unified diffs** with syntax highlighting, your choice per session.
+- **Viewed-file tracking.** Tick files off as you go (`0/14 viewed`) so you never
+  lose your place in a large change.
+- **Notes and inline comments.** Write a rich-text review summary and drop inline
+  comments on specific lines — stored locally and kept across sessions.
+- **Branch, commit, and PR context.** Switch branches, pin a commit to review
+  against, and browse pull requests and history without leaving the app.
+- **AI walkthroughs (optional).** Generate a guided walkthrough of a change to get
+  oriented fast.
+- **Keyboard-driven.** `j`/`k` to navigate, `v` to mark viewed, `c` to comment,
+  `⌘↵` to submit — review without touching the mouse.
+- **Native and local.** A fast Electron + Vue interface backed by a Go engine that
+  reads Git directly and stores your reviews in local SQLite.
 
-For active development:
+## See it in action
 
-```sh
-pnpm dev
-```
+| | |
+| --- | --- |
+| ![File navigation and status badges](docs/images/file-navigation.png) | ![Split diff view](docs/images/split-view.png) |
+| **Walk every changed file** with status, counts, and viewed tracking. | **Read split or unified diffs** with syntax highlighting. |
+| ![Review notes and inline comments](docs/images/review-notes.png) | ![AI walkthrough](docs/images/walkthrough.png) |
+| **Leave notes and inline comments** as you review. | **Generate an AI walkthrough** to get oriented fast. |
 
-The dev command starts the Vite renderer, compiles Electron, starts the Go
-backend, waits for the local socket API, and launches Electron.
+> Screenshots live in [`docs/images/`](docs/images/). See that folder's README for
+> what each capture should show.
 
-## Backend CLI
+## Install
 
-The Electron app normally starts the backend automatically. To inspect the
-backend directly:
+> **macOS on Apple Silicon.** The app is currently in beta and distributed
+> unsigned, so macOS Gatekeeper needs one extra click on first launch.
 
-```sh
-cd packages/api
-go run ./cmd help
-go run ./cmd serve-http --socket /tmp/git-diff.sock
-```
+**Download the app**
 
-To point the Electron app at an already-running backend, set
-`API_BRIDGE_SOCKET` to the socket path before launching it.
+1. Grab the latest `.dmg` from the
+   [Releases page](https://github.com/oullin/git-diff/releases).
+2. Open it and drag **Git Diff Review** to Applications.
+3. On first launch, **right-click the app → Open**, then confirm. (macOS blocks
+   unsigned apps on a normal double-click; right-click → Open only needs doing
+   once.)
 
-## Development Commands
+**Homebrew** _(planned)_
 
 ```sh
-pnpm build
-pnpm test
-pnpm lint
-pnpm format:check
-pnpm check
+brew install --cask oullin/tap/git-diff
 ```
 
-Useful package-level commands:
+## Your code stays yours
 
-```sh
-pnpm --filter ui build
-pnpm --filter ui test
-pnpm --filter ui dev
-go test ./packages/api/...
-```
-
-## Review Data
-
-Review sessions, comments, events, and preferences are local. By default the Go
-backend stores the review database under:
+Git Diff Review reads your repository state through Git and serves a local API over
+a Unix socket — it talks only to your machine. Review sessions, comments, events,
+and preferences are stored in a local SQLite database at:
 
 ```text
 ~/Library/Application Support/git-diff/reviews.sqlite3
 ```
 
-Viewed-file state is stored by the renderer per repository root.
+It **does not** publish comments to GitHub, create pull requests, or modify your
+repository contents. It's a review surface, nothing more.
 
-## Release
+## Build from source
 
-Releases are built with [Electron Forge](https://www.electronforge.io/). Tag a
-version to cut a release in CI:
-
-```sh
-git tag v0.1.1 && git push origin v0.1.1
-```
-
-The `Release` workflow builds the unsigned macOS arm64 `.dmg` + `.zip`, publishes
-a GitHub Release, and opens a Homebrew cask bump PR against `oullin/homebrew-tap`
-on final (non-prerelease) tags. See [docs/distribution.md](docs/distribution.md).
-
-To build the same artifacts locally:
-
-```sh
-pnpm release:mac:unsigned   # builds the Go API + renderer, then `electron-forge make`
-```
+Git Diff Review is a pnpm + Turbo monorepo pairing an Electron/Vue/TypeScript
+desktop app with a Go backend.
 
-The Electron package is configured (in `packages/ui/forge.config.ts`) with:
+| Path              | Role                                                                        |
+| ----------------- | --------------------------------------------------------------------------- |
+| `packages/ui`     | Electron/Vue desktop app and renderer UI.                                   |
+| `packages/bridge` | TypeScript HTTP client used by Electron.                                    |
+| `packages/domain` | Shared DTOs + framework-agnostic diff logic, consumed by `ui` and `bridge`. |
+| `packages/api`    | Go backend that reads Git diffs and stores reviews.                         |
+| `packages/tools`  | Turbo cache wrapper and unsigned macOS release helper.                      |
 
-- app id: `io.gocanto.git-diff`
-- product name: `Git Diff Review`
-- GitHub release target: `oullin/git-diff`
+To set up the toolchain, run it locally, and learn the development commands, see
+**[docs/development.md](docs/development.md)**. Releases are built with
+[Electron Forge](https://www.electronforge.io/) — for tagging, packaging, signing,
+and the release pipeline, see **[docs/distribution.md](docs/distribution.md)**.
 
 ## License
 
-See [LICENSE](LICENSE).
+[MIT](LICENSE) © Gus Canto

docs/development.md

@@ -0,0 +1,123 @@
+# Development
+
+How to set up the toolchain, run Git Diff Review locally, and work in the
+monorepo. For the product overview and install instructions, see the
+[README](../README.md). For packaging and releases, see
+[distribution.md](distribution.md).
+
+## Requirements
+
+- macOS
+- Git
+- Go
+- Node.js with Corepack
+- pnpm `10.33.0`
+
+Enable pnpm through Corepack if needed:
+
+```sh
+corepack enable
+corepack prepare pnpm@10.33.0 --activate
+```
+
+## Quick start
+
+From the repository root:
+
+```sh
+pnpm install
+pnpm build
+pnpm --filter ui start
+```
+
+## Active development
+
+```sh
+pnpm dev
+```
+
+The dev command starts the Vite renderer, compiles Electron, starts the Go
+backend, waits for the local socket API, and launches Electron.
+
+## Backend CLI
+
+The Electron app normally starts the backend automatically. To inspect the
+backend directly:
+
+```sh
+cd packages/api
+go run ./cmd help
+go run ./cmd serve-http --socket /tmp/git-diff.sock
+```
+
+To point the Electron app at an already-running backend, set `API_BRIDGE_SOCKET`
+to the socket path before launching it.
+
+## Development commands
+
+```sh
+pnpm build
+pnpm test
+pnpm lint
+pnpm format:check
+pnpm check
+```
+
+Useful package-level commands:
+
+```sh
+pnpm --filter ui build
+pnpm --filter ui test
+pnpm --filter ui dev
+go test ./packages/api/...
+```
+
+## Formatting
+
+Format changed sources (Go + TS/Vue):
+
+```sh
+pnpm format      # or: make format
+```
+
+To format the entire repo, use `pnpm format-all` (`make format-all`). Run the
+formatter after each change so commits stay clean.
+
+## Review data
+
+Review sessions, comments, events, and preferences are local. By default the Go
+backend stores the review database under:
+
+```text
+~/Library/Application Support/git-diff/reviews.sqlite3
+```
+
+Viewed-file state is stored by the renderer per repository root.
+
+## Release
+
+Releases are built with [Electron Forge](https://www.electronforge.io/). Tag a
+version to cut a release in CI:
+
+```sh
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+The `Release` workflow builds the unsigned macOS arm64 `.dmg` + `.zip`, publishes
+a GitHub Release, and opens a Homebrew cask bump PR against `oullin/homebrew-tap`
+on final (non-prerelease) tags.
+
+To build the same artifacts locally:
+
+```sh
+pnpm release:mac:unsigned   # builds the Go API + renderer, then `electron-forge make`
+```
+
+The Electron package is configured (in `packages/ui/forge.config.ts`) with:
+
+- app id: `io.gocanto.git-diff`
+- product name: `Git Diff Review`
+- GitHub release target: `oullin/git-diff`
+
+See [distribution.md](distribution.md) for the full signing, notarization, and
+Homebrew release flow.

docs/images/README.md

@@ -0,0 +1,17 @@
+# Screenshots
+
+Images referenced by the [project README](../../README.md). Drop the real
+captures here using the exact filenames below so the README renders them
+automatically. Use PNG, retina resolution (capture at 2x), and a light UI theme
+for consistency.
+
+| File                  | What it should show                                                            |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `hero.png`            | The main review window: file list, a split diff, branch/commit bar, toolbar.   |
+| `file-navigation.png` | The changed-files sidebar with status badges, +/- counts, and viewed checkboxes. |
+| `split-view.png`      | A diff in split (or unified) view with syntax highlighting.                    |
+| `review-notes.png`    | A review summary and/or an inline comment on a line.                           |
+| `walkthrough.png`     | The "Generate walkthrough" AI feature in use.                                  |
+
+Until a file is added, its link in the README will show as a broken image — that
+is expected and resolves the moment the PNG lands here.