docs: add README

Author: joshuap

README.md

@@ -0,0 +1,140 @@
+# hbtui
+
+A terminal dashboard for [Honeybadger.io](https://www.honeybadger.io), built with Rust.
+
+![hbtui screenshot](demo.gif)
+
+## Installation
+
+### From source
+
+```bash
+cargo install --path .
+```
+
+### Pre-built binaries
+
+Coming soon.
+
+## Usage
+
+```bash
+# With command-line flags
+hbtui -p <PROJECT_ID> --auth-token <TOKEN>
+
+# With environment variables
+export HONEYBADGER_PROJECT_ID=12345
+export HONEYBADGER_PERSONAL_AUTH_TOKEN=your_token
+hbtui
+
+# Custom dashboard file or directory
+hbtui -p 12345 -d ./my-dashboard.yml
+hbtui -p 12345 -d ./dashboards/
+```
+
+### Options
+
+| Flag               | Env Variable                      | Description                                           |
+| ------------------ | --------------------------------- | ----------------------------------------------------- |
+| `-p, --project-id` | `HONEYBADGER_PROJECT_ID`          | Honeybadger project ID (required)                     |
+| `--auth-token`     | `HONEYBADGER_PERSONAL_AUTH_TOKEN` | API auth token (required)                             |
+| `-d, --dashboards` | `HONEYBADGER_DASHBOARDS`          | Dashboard file or directory (default: `./dashboards`) |
+| `-h, --help`       |                                   | Print help                                            |
+| `-V, --version`    |                                   | Print version                                         |
+
+## Key Bindings
+
+| Key        | Action                            |
+| ---------- | --------------------------------- |
+| `q`        | Quit                              |
+| `r`        | Refresh current dashboard         |
+| `[` / `]`  | Previous / next dashboard         |
+| `1-9`      | Jump to dashboard by number       |
+| Arrow keys | Navigate widgets                  |
+| `Enter`    | Maximize selected widget          |
+| `Esc`      | Exit maximized view               |
+| `Up/Down`  | Filter by series (when maximized) |
+
+## Dashboards
+
+Dashboards are YAML files that define widgets powered by [Honeybadger Insights](https://docs.honeybadger.io/guides/insights/). See the [Dashboards guide](https://docs.honeybadger.io/guides/dashboards/#editing-dashboard-source) to learn how to export your dashboard YAML.
+
+### Example
+
+```yaml
+title: My Dashboard
+widgets:
+  - id: requests
+    type: insights
+    grid: { x: 0, y: 0, w: 6, h: 2 }
+    presentation:
+      title: Requests per Hour
+    config:
+      query: |
+        SELECT count(*) as count, bin(ts, 1h) as time
+        FROM requests
+        GROUP BY time
+        ORDER BY time
+      vis:
+        view: line
+        chart_config:
+          xField: time
+          yField: count
+
+  - id: errors
+    type: insights
+    grid: { x: 6, y: 0, w: 6, h: 2 }
+    presentation:
+      title: Errors by Class
+    config:
+      query: |
+        SELECT count(*) as count, class
+        FROM errors
+        GROUP BY class
+        ORDER BY count DESC
+        LIMIT 10
+      vis:
+        view: table
+```
+
+### Grid System
+
+Widgets are positioned on a 12-column grid:
+
+- `x`: Column position (0-11)
+- `y`: Row position (0+)
+- `w`: Width in columns (1-12)
+- `h`: Height in rows
+
+### Visualization Types
+
+| Type        | Description                         |
+| ----------- | ----------------------------------- |
+| `line`      | Time-series line chart              |
+| `histogram` | Bar chart (supports stacked series) |
+| `table`     | Data table                          |
+| `billboard` | Large single-value display          |
+
+### Chart Config
+
+```yaml
+chart_config:
+  xField: time # X-axis field
+  yField: count # Y-axis field
+  zField: status # Series grouping (optional)
+  yFieldUnit: milliseconds # Unit for Y-axis (optional)
+```
+
+## Development
+
+```bash
+cargo build          # Build
+cargo run -- --help  # Run with args
+cargo test           # Run tests
+cargo clippy         # Lint
+cargo fmt            # Format
+```
+
+## License
+
+MIT

demo.gif

@@ -0,0 +1,28 @@
+Output demo.gif
+Set Width 1920
+Set Height 1080
+Set FontSize 22
+Set Framerate 60
+# Hide the setup
+Hide
+Type "cargo run"
+Enter
+Sleep 2s
+Show
+# Record the demo
+Sleep 2s
+Type "]"  # Next dashboard
+Sleep 2s
+Right     # Next widget
+Sleep 2s
+Enter     # Maximize widget
+Sleep 1s
+Down      # Filter series
+Sleep 1s
+Down
+Sleep 1s
+Down
+Sleep 1s
+Escape    # Exit maximized
+Sleep 2s
+Type "q"  # Quit