docs: shorten README and fix review auth

.github/workflows/opencode.yml

@@ -33,6 +33,8 @@ jobs:
     permissions:
       contents: read
       id-token: write
+      issues: write
+      pull-requests: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -44,6 +46,7 @@ jobs:
         uses: anomalyco/opencode/github@latest
         env:
           DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           model: deepseek/deepseek-v4-pro
-          # github_token: xxxx
+          use_github_token: true

README.md

@@ -1,171 +1,84 @@
-# Binge Docs
+# Binge Docs 🎧
 
-Listen to official documentation directly from your terminal.
+Listen to official FastAPI and Typer documentation from your terminal.
+Binge Docs removes visual content, then streams the useful prose through
+Kokoro.
 
-```bash
-binge-docs fastapi
-binge-docs typer
-```
-
-Choose a built-in documentation source, search for a page, and start
-listening. Binge Docs downloads the selected official page, removes visual
-content such as code blocks and tables, and streams the remaining prose
-through Kokoro.
-
-## Requirements
-
-- Python 3.10 through 3.13
-- An internet connection for the first catalog, page, and model downloads
-- A working audio output device
-- PortAudio when required by your operating system
+## 🚀 Install
 
-On Debian or Ubuntu, install PortAudio before installing Binge Docs:
+Requires Python 3.10–3.13, internet access for initial downloads, and audio
+output.
 
 ```bash
-sudo apt-get install portaudio19-dev
+uv tool install .
 ```
 
-## Install
-
-Clone this repository and install it with `uv`:
+On Debian or Ubuntu, install PortAudio first:
 
 ```bash
-uv tool install .
+sudo apt-get install portaudio19-dev
 ```
 
-For local development:
+For development:
 
 ```bash
 uv sync
 uv run binge-docs --help
 ```
 
-The first playback downloads approximately 120 MB of Kokoro model files into
-your operating system's user cache.
-
-## Built-In Sources
+The first playback downloads about 120 MB of Kokoro model files.
 
-Binge Docs currently ships with:
+## 📚 Listen
 
-- FastAPI via `binge-docs fastapi`
-- Typer via `binge-docs typer`
-
-## Choose A Page
-
-Start the interactive FastAPI browser:
+Browse a built-in source interactively:
 
 ```bash
 binge-docs fastapi
-```
-
-Or browse Typer:
-
-```bash
 binge-docs typer
 ```
 
-First choose a section such as Tutorial, Advanced, Deployment, How-To, or
-Reference. Typer uses sections such as Features, Learn, Reference, Resources,
-About, and Release Notes. Then type in the page picker to filter the available
-pages.
-
-During playback:
-
-- Press `space` to pause or resume
-- Press `+` or `-` to change speed for upcoming audio
-- Press `q` to stop cleanly
-- Press `Ctrl+C` to force stop
-
-## Open A Page Directly
-
-Skip the menus with a page slug:
+Open a page directly with a slug or official URL:
 
 ```bash
 binge-docs fastapi --page tutorial/first-steps
-binge-docs typer --page tutorial/first-steps
+binge-docs typer --page https://typer.tiangolo.com/tutorial/first-steps/
 ```
 
-A full official URL also works:
+Use `--voice` and `--speed` to customize playback:
 
 ```bash
-binge-docs fastapi \
-  --page https://fastapi.tiangolo.com/tutorial/first-steps/
-
-binge-docs typer \
-  --page https://typer.tiangolo.com/tutorial/first-steps/
+binge-docs fastapi --page tutorial/first-steps --voice bf_emma --speed 1.2
 ```
 
-Direct page selection is required when the command is run without an
-interactive terminal.
+Speed must be between `0.5` and `2.0`. Defaults are `af_heart` and `1.0`.
 
-## Voice And Speed
+## ⌨️ Controls
 
-Use a supported US or UK English voice:
+- `space`: pause or resume
+- `+` / `-`: change speed for upcoming audio
+- `q`: stop cleanly
+- `Ctrl+C`: force stop
 
-```bash
-binge-docs fastapi \
-  --page tutorial/first-steps \
-  --voice bf_emma \
-  --speed 1.2
-
-binge-docs typer \
-  --page tutorial/first-steps \
-  --voice bf_emma \
-  --speed 1.2
-```
+## 🛠️ Commands
 
-List all supported voices:
-
-```bash
+```text
+binge-docs fastapi [--page PAGE] [--voice VOICE] [--speed SPEED]
+binge-docs typer [--page PAGE] [--voice VOICE] [--speed SPEED]
 binge-docs voices
-```
-
-Playback speed must be between `0.5` and `2.0`. The default voice is
-`af_heart`, and the default speed is `1.0`.
-
-## Model Setup
-
-Models download automatically on first playback. To download them in advance
-or verify and repair existing files, run:
-
-```bash
 binge-docs setup
+binge-docs --version
 ```
 
-Downloads are pinned and verified with SHA-256 checksums before use.
-
-## Offline Behavior
+`binge-docs setup` downloads or repairs checksum-verified model files.
 
-Each built-in source keeps its own catalog and page cache for 24 hours. After
-that, Binge Docs tries to refresh the cached content. If the refresh fails, it
-uses the stale copy and displays an offline warning.
+## 💾 Offline Use
 
-A page that has never been opened cannot be played offline.
+Catalogs and pages are cached for 24 hours. If a refresh fails, Binge Docs
+uses stale cached content with a warning. Pages that have never been opened
+cannot be played offline.
 
-## What Gets Read
+## 🔎 What Gets Read
 
-Binge Docs reads:
-
-- Headings
-- Paragraphs
-- Lists and blockquotes
-- Notes, tips, and warnings
-- Link labels and inline code
-
-It skips:
-
-- Navigation and page metadata
-- Code blocks and terminal output
-- Tables and images
-- Duplicate tab variants
-- Scripts and visual controls
-
-## Commands
-
-```text
-binge-docs fastapi [--page PAGE] [--voice VOICE] [--speed SPEED]
-binge-docs typer [--page PAGE] [--voice VOICE] [--speed SPEED]
-binge-docs voices
-binge-docs setup
-binge-docs --version
-```
+Binge Docs reads headings, prose, lists, notes, link labels, and inline code.
+It skips navigation, code blocks, terminal output, tables, images, scripts,
+and other visual controls.