diff --git a/apps/penpal/README.md b/apps/penpal/README.md
index 34f4be19..6a0fdbaf 100644
--- a/apps/penpal/README.md
+++ b/apps/penpal/README.md
@@ -16,30 +16,26 @@ A desktop app and local web server that **only** operates on markdown files insi
 - **MCP server** at `/mcp` for AI agents to participate in document review programmatically
 - **Agent presence** -- shows when an agent is actively monitoring a file
 
-## Quick Start
+## Install
 
-### Prerequisites
+### Homebrew (recommended)
 
-**just** - Command runner ([install guide](https://github.com/casey/just))
 ```bash
-brew install just
+brew install --cask block/tap/penpal
 ```
 
-Building requires Go, Node.js, and Rust.
+On first launch, Penpal will prompt you to install the CLI and Claude Code plugin.
 
-### Develop
+### Build from source
 
-```bash
-just dev           # Desktop app with Vite HMR + Go sidecar
-```
-
-### Install
+For development, you can build and install locally. Requires Go, Node.js, Rust, and [just](https://github.com/casey/just).
 
 ```bash
-just install       # Build .app, copy to /Applications, install Claude Code plugin
-just uninstall     # Remove .app and Claude Code plugin
+just install       # Build dev-branded .app and copy to /Applications
 ```
 
+Dev builds show "Penpal Dev" in the menu bar so you can distinguish them from Homebrew installs.
+
 ### CLI
 
 ```bash
@@ -52,12 +48,22 @@ penpal open thoughts/shared/plans/my-doc.md   # Open file in Penpal desktop app
 |---|---|
 | `just dev` | Desktop app with Vite HMR + Go sidecar |
 | `just build` | Build sidecar + frontend + desktop `.app` bundle |
-| `just build-sidecar` | Build Go sidecar binaries for desktop app |
+| `just build-go` | Build Go sidecar binaries for desktop app |
+| `just package` | Build + zip `.app` for distribution |
 | `just test` | Run all tests (Go + React) |
 | `just test-e2e` | Playwright end-to-end tests |
-| `just check` | Format Go code + tidy dependencies |
+| `just fmt` | Format Go code |
 | `just clean` | Remove build artifacts |
 
+### Releasing
+
+```bash
+just prepare 0.2.0   # Bump version, generate changelog for review
+just release 0.2.0   # Commit, tag, push → CI builds and publishes
+```
+
+`just prepare` updates the version in `Cargo.toml` and `package.json`, generates a changelog entry using Claude, and opens it in Penpal for review. `just release` commits the version bump, creates a `penpal/v*` tag, and pushes to trigger the CI release pipeline.
+
 ### Server options
 
 ```bash
diff --git a/apps/penpal/justfile b/apps/penpal/justfile
index 5d99139d..ce0ecbd7 100644
--- a/apps/penpal/justfile
+++ b/apps/penpal/justfile
@@ -123,6 +123,62 @@ test: ensure-deps
 # Verify everything without modifying files — for CI
 ci: ensure-deps fmt-check lint typecheck test
 
+# ============================================================================
+# Release
+# ============================================================================
+
+# Generate changelog entry for a release version
+changelog version:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    LAST_TAG=$(git describe --tags --match "penpal/v*" --abbrev=0 2>/dev/null || echo "")
+    if [ -n "$LAST_TAG" ]; then
+        COMMITS=$(git log --oneline "$LAST_TAG"..HEAD -- .)
+    else
+        COMMITS=$(git log --oneline -- .)
+    fi
+
+    if [ -z "$COMMITS" ]; then
+        echo "No commits found since last release."
+        exit 1
+    fi
+
+    echo "$COMMITS" | claude -p --dangerously-skip-permissions \
+        "These are commits since the last release. Prepend a new changelog section to CHANGELOG.md using v{{version}} as the heading. Group changes by theme and write human-readable descriptions, not raw commit messages. Match the existing style."
+
+    penpal open CHANGELOG.md
+    read -p "Press enter when done editing changelog..."
+
+# Bump version and generate changelog for review
+prepare version:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    # Update version in Cargo.toml (source of truth)
+    sed -i '' 's/^version = ".*"/version = "{{version}}"/' frontend/src-tauri/Cargo.toml
+    # Update version in package.json
+    cd frontend && npm version "{{version}}" --no-git-tag-version && cd ..
+
+    # Generate and review changelog
+    just changelog {{version}}
+
+    echo ""
+    echo "Version bumped to {{version}} and changelog updated."
+    echo "Review the changes, then run 'just release {{version}}' to ship."
+
+# Commit, tag, and push to trigger the release build
+release version:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    git add frontend/src-tauri/Cargo.toml frontend/package.json CHANGELOG.md
+    git commit -m "release: penpal v{{version}}"
+    git tag "penpal/v{{version}}"
+    git push origin main "penpal/v{{version}}"
+
+    echo "Pushed penpal/v{{version}} — CI will build and publish the release."
+
 # ============================================================================
 # Other
 # ============================================================================