glassbox 0.1.4 → 0.2.1

package/README.md

@@ -12,19 +12,34 @@ No accounts. No pull requests. No waiting. Just you, the diff, and a tight feedb
 
 <br>
 
+**Desktop app** (recommended) — download from [GitHub Releases](https://github.com/brianwestphal/glassbox/releases):
+
+| Platform | Download |
+|----------|----------|
+| macOS (Apple Silicon) | `.dmg` (arm64) |
+| macOS (Intel) | `.dmg` (x64) |
+| Linux | `.AppImage` / `.deb` |
+| Windows | `.msi` / `.exe` |
+
+After installing, open the app and click **Install CLI** to add the `glassbox` command to your PATH.
+
+**Or install via npm:**
+
 ```bash
 npm install -g glassbox
 ```
 
+Then, from any git repository:
+
 ```bash
 glassbox
 ```
 
-That's it. Opens in your browser. Works in any git repo.
+That's it. Data stays local. Works in any git repo.
 
 <br>
 
-<img src="assets/screenshot.png" alt="Glassbox reviewing a diff" width="720">
+<img src="assets/demo-guided-review.png" alt="Glassbox reviewing a diff with guided review notes" width="720">
 
 </div>
 
@@ -34,19 +49,21 @@ That's it. Opens in your browser. Works in any git repo.
 
 AI coding tools generate a lot of code fast. But "fast" doesn't mean "correct." The bottleneck isn't generation — it's **review**.
 
-Most developers review AI output by skimming files in their editor, mentally diffing what changed, and then either accepting it or rewriting it by hand. That's slow, error-prone, and throws away the most valuable signal: your expert judgment about *what specifically* was wrong and why.
+Most developers review AI output by skimming files in their editor, mentally diffing what changed, and then either accepting it or rewriting it by hand. That's slow, error-prone, and throws away the most valuable signal: your expert judgment about _what specifically_ was wrong and why.
 
 Glassbox gives you a proper diff viewer with annotation categories designed for AI feedback:
 
-| Category | What it tells the AI |
-|----------|---------------------|
-| **Bug** | "This is broken. Fix it." |
-| **Fix needed** | "This needs a specific change." |
-| **Style** | "I prefer it done this way." |
-| **Pattern to follow** | "This is good. Keep doing this." |
-| **Pattern to avoid** | "This is an anti-pattern. Stop." |
-| **Note** | Context for the AI to consider. |
-| **Remember** | A rule to persist to the AI's long-term config. |
+<img src="assets/demo-annotations.png" alt="Inline annotations with category badges" width="720">
+
+| Category              | What it tells the AI                            |
+| --------------------- | ----------------------------------------------- |
+| **Bug**               | "This is broken. Fix it."                       |
+| **Fix needed**        | "This needs a specific change."                 |
+| **Style**             | "I prefer it done this way."                    |
+| **Pattern to follow** | "This is good. Keep doing this."                |
+| **Pattern to avoid**  | "This is an anti-pattern. Stop."                |
+| **Note**              | Context for the AI to consider.                 |
+| **Remember**          | A rule to persist to the AI's long-term config. |
 
 When you're done, click **Complete Review** and tell your AI tool:
 
@@ -82,12 +99,89 @@ Then you run `glassbox` again. Your previous annotations carry forward — match
 - **Structured export** — markdown output with file paths, line numbers, categories, and instructions for AI consumption
 - **Automatic .gitignore prompt** — reminds you to exclude `.glassbox/` from version control
 - **Auto port selection** — if the default port is busy, it finds an open one
-- **Fully local** — no network calls, no accounts, no telemetry. Your code stays on your machine.
+- **Fully local** — no network calls (unless you opt into AI features), no accounts, no telemetry. Your code stays on your machine.
+- **AI-powered analysis** _(optional)_ — risk scoring, narrative reading order, and guided review to help you focus and learn as you review
+
+---
+
+## AI-Powered Review Intelligence
+
+> Entirely optional. Glassbox is fully functional without it.
+
+When reviewing a large diff, knowing _where to look first_ is half the battle. Glassbox can optionally connect to an AI provider to analyze your changes and surface what matters:
+
+### Risk Analysis
+
+Every file is scored across six dimensions — security, correctness, error handling, maintainability, architecture, and performance — on a 0.0 to 1.0 scale. Files are ranked by their highest-risk dimension, so a single critical issue won't hide behind low averages.
+
+When you open a file, inline risk notes highlight the specific lines and concerns the AI flagged, giving you a heads-up before you even start reading.
+
+<img src="assets/demo-risk-mode.png" alt="Risk mode with scores and inline risk notes" width="720">
+
+### Narrative Reading Order
+
+For large, multi-file changes, the AI determines the optimal reading order: types and interfaces first, then utilities, then business logic, then integration code. Each file gets walkthrough notes that explain what changed and how it connects to the rest of the diff — like having a colleague walk you through their PR.
+
+<img src="assets/demo-narrative-mode.png" alt="Narrative mode with reading order and walkthrough notes" width="720">
+
+### Guided Review
+
+If you're learning a new language, onboarding to an unfamiliar codebase, or new to programming, Guided Review generates educational annotations inline with the diff. Enable it in Settings and select the topics that apply to you — "Programming," "This codebase," or specific languages. Glassbox runs a separate analysis pass and inserts green "Learn" notes that explain concepts, idioms, and design decisions relevant to your experience level.
+
+Guided Review works in all three sidebar modes (folder, risk, and narrative) and runs independently of risk or narrative analysis. When enabled, risk and narrative analysis also adjust their output to be more detailed and educational.
+
+### How to use it
+
+Click the shield or book icon in the sidebar to switch from the default folder view to risk or narrative mode. If you haven't configured an API key yet, a settings dialog will prompt you. Analysis runs once and results are cached for the session. To enable Guided Review, open the Settings dialog (gear icon) and check "Enable guided review."
+
+<img src="assets/demo-settings.png" alt="Settings dialog with guided review configuration" width="480">
+
+### Supported providers
+
+| Provider      | Models                           | Env variable        |
+| ------------- | -------------------------------- | ------------------- |
+| **Anthropic** | Claude Sonnet 4, Claude Haiku 4  | `ANTHROPIC_API_KEY` |
+| **OpenAI**    | GPT-4o, GPT-4o Mini              | `OPENAI_API_KEY`    |
+| **Google**    | Gemini 2.5 Flash, Gemini 2.5 Pro | `GEMINI_API_KEY`    |
+
+You can switch providers and models in the settings dialog (gear icon in the sidebar).
+
+### API key storage
+
+Your API key never leaves your machine. Glassbox resolves keys in this order:
+
+1. **Environment variables** — if `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY` is set, it's used automatically. Nothing is stored.
+2. **OS keychain** — on macOS (Keychain), Linux (GNOME Keyring / KDE Wallet via `secret-tool`), or Windows (Credential Manager). Keys are encrypted by your operating system and tied to your user account.
+3. **Config file** — stored in `~/.glassbox/config.json` with `0600` permissions, base64-encoded. Use this as a fallback if your OS keychain isn't available.
+
+Keys entered through the settings dialog are stored in the OS keychain by default when available, and never sent anywhere except directly to the AI provider's API.
 
 ---
 
 ## Install
 
+### Desktop app (recommended)
+
+Download the latest release for your platform from [GitHub Releases](https://github.com/brianwestphal/glassbox/releases).
+
+On first launch, the app will prompt you to install the `glassbox` CLI command. This creates a symlink so you can launch the desktop app from any project directory. You can also install it manually:
+
+**macOS:**
+```bash
+sudo ln -sf "/Applications/Glassbox.app/Contents/Resources/resources/glassbox" /usr/local/bin/glassbox
+```
+
+**Linux:**
+```bash
+ln -sf /path/to/glassbox/resources/glassbox-linux ~/.local/bin/glassbox
+```
+
+The desktop app includes automatic updates — new versions are downloaded and applied in the background.
+
+### npm
+
+Alternatively, install via npm (runs in your browser instead of a native window):
+
 ```bash
 npm install -g glassbox
 ```
@@ -128,22 +222,37 @@ glassbox --resume
 
 ### All options
 
-| Flag | Description |
-|------|-------------|
-| *(no flag)* | Same as `--uncommitted` |
-| `--uncommitted` | Staged + unstaged + untracked changes |
-| `--staged` | Only staged changes |
-| `--unstaged` | Only unstaged changes |
-| `--commit <sha>` | Changes from a specific commit |
-| `--range <from>..<to>` | Changes between two refs |
-| `--branch <name>` | Current branch vs the named branch |
-| `--files <patterns>` | Specific files (comma-separated globs) |
-| `--all` | Entire codebase (all tracked files) |
-| `--port <number>` | Port to run on (default: 4173) |
-| `--resume` | Resume the latest in-progress review for this mode |
-| `--check-for-updates` | Check for a newer version on npm |
-| `--debug` | Show build timestamp and debug info |
-| `--help` | Show help |
+| Flag                   | Description                                        |
+| ---------------------- | -------------------------------------------------- |
+| _(no flag)_            | Same as `--uncommitted`                            |
+| `--uncommitted`        | Staged + unstaged + untracked changes              |
+| `--staged`             | Only staged changes                                |
+| `--unstaged`           | Only unstaged changes                              |
+| `--commit <sha>`       | Changes from a specific commit                     |
+| `--range <from>..<to>` | Changes between two refs                           |
+| `--branch <name>`      | Current branch vs the named branch                 |
+| `--files <patterns>`   | Specific files (comma-separated globs)             |
+| `--all`                | Entire codebase (all tracked files)                |
+| `--port <number>`      | Port to run on (default: 4183)                     |
+| `--resume`             | Resume the latest in-progress review for this mode |
+| `--browser`            | Open in browser instead of desktop window          |
+| `--check-for-updates`  | Check for a newer version on npm                   |
+| `--debug`              | Show build timestamp and debug info                |
+| `--help`               | Show help                                          |
+
+### Settings file
+
+Create `.glassbox/settings.json` in your project directory to configure per-project options:
+
+```json
+{
+  "appName": "Glassbox — My Project"
+}
+```
+
+| Key | Description |
+|-----|-------------|
+| `appName` | Custom window title and Dock name (defaults to "Glassbox — _folder name_") |
 
 ---
 
@@ -174,16 +283,19 @@ Point the tool at the file. The export includes an "Instructions for AI Tools" s
 
 ## Architecture
 
-| Layer | Technology |
-|-------|-----------|
-| CLI | TypeScript, Node.js |
-| Server | Hono |
-| Database | PGLite (embedded PostgreSQL) |
-| UI | Custom server-side JSX (no React), vanilla client JS |
-| Build | tsup (single-file bundle) |
-| Storage | `~/.glassbox/data/` |
+| Layer    | Technology                                           |
+| -------- | ---------------------------------------------------- |
+| Desktop  | Tauri v2 (native window, auto-updates)               |
+| CLI      | TypeScript, Node.js                                  |
+| Server   | Hono                                                 |
+| Database | PGLite (embedded PostgreSQL)                         |
+| UI       | Custom server-side JSX (no React), vanilla client JS |
+| Build    | tsup (single-file bundle)                            |
+| Storage  | `~/.glassbox/data/`                                  |
+
+Data stays local. The only network calls are an optional once-per-day npm update check and AI analysis requests if you opt in.
 
-Data stays local. The only network call is an optional once-per-day npm update check.
+> **Note:** We're actively developing and testing on macOS. Linux and Windows builds are provided but less tested — if you run into issues on those platforms, please [open an issue](https://github.com/brianwestphal/glassbox/issues).
 
 ## Development
 
@@ -192,10 +304,12 @@ git clone <repo-url>
 cd glassbox
 npm install
 
-npm run dev -- --uncommitted    # Run with tsx (no build step)
-npm run build                   # Build to dist/cli.js
-npm run clean                   # Remove dist and caches
-npm link                        # Symlink for global 'glassbox' command
+npm run dev              # Build client assets, then run via tsx
+npm run build            # Build to dist/cli.js
+npm run tauri:dev        # Run desktop app in dev mode
+npm run tauri:build      # Build desktop app for distribution
+npm run clean            # Remove dist and caches
+npm link                 # Symlink for global 'glassbox' command
 ```
 
 ## License