feat(ui): add read-only interactive issue browser

README.md

@@ -69,9 +69,12 @@ docket next
 
 # View the Kanban board
 docket board
+
+# Browse issues in the interactive terminal UI
+docket tui
 ```
 
-**AI agents:** add `--json` to any command for structured, machine-readable output:
+**AI agents:** add `--json` to supported non-interactive commands for structured, machine-readable output:
 
 ```bash
 docket next --json
@@ -81,14 +84,16 @@ docket issue list --json -s todo -s in-progress
 ## Why Docket?
 
 - **No servers, no network** — everything is a local SQLite file in `.docket/`. Works offline, on planes, in CI.
-- **AI-native from day one** — every command supports `--json` with a consistent envelope. Agents can create, query, plan, and update issues without parsing human text.
+- **AI-native from day one** — machine-readable commands support `--json` with a consistent envelope. Agents can create, query, plan, and update issues without parsing human text.
 - **Dependency-aware planning** — `docket next` and `docket plan` use a DAG to surface only unblocked, work-ready issues. No stale sprint boards.
 - **Zero configuration** — `docket init` and you're done. No accounts, no tokens, no YAML.
 - **Portable data** — the `.docket/` directory travels with your repo. Clone it, fork it, archive it.
 
 ## AI Agent Integration
 
-Every command supports `--json` for structured, machine-readable output. All JSON responses use a consistent envelope:
+Most commands support `--json` for structured, machine-readable output. All JSON responses use a consistent envelope:
+
+`docket tui` is the exception: it opens a read-only interactive terminal UI, requires a real TTY, and rejects `--json`.
 
 **Success:** `{"ok": true, "data": { ... }, "message": "..."}`
 
@@ -117,6 +122,33 @@ Run `docket next --json` to find work. Move issues to `in-progress` before start
 
 Any agent that can run shell commands works with Docket. Point it at `docket next --json` to discover work items, and use `docket issue show <id> --json` to get full context before starting a task. The consistent JSON envelope (`ok`, `data`, `error`, `code`) makes parsing straightforward in any language.
 
+### Interactive UI
+
+Use `docket tui` when you want an interactive browser instead of command output. It opens a read-only terminal UI for list and board browsing, auto-refreshes by default, supports `p` to pause or resume polling, supports list sorting with `s` (cycle sort field) and `S` (toggle sort direction), requires an interactive terminal, and does not support `--json`.
+
+If you need to debug terminal-specific behavior, set `DOCKET_TUI_DEBUG_LOG=/tmp/docket-tui.log` before running `docket tui`.
+
+#### TUI Keybinds
+
+| Key | Action |
+|-----|--------|
+| `1` | Switch to list view |
+| `2` | Switch to board view |
+| `j` / `k` | Move selection in the focused pane |
+| `J` / `K` | Move detail selection while browse stays focused |
+| `s` | Cycle list sort field |
+| `S` | Toggle list sort direction |
+| `o` | Drill into the selected epic |
+| `tab` | Switch between browse and detail panes |
+| `enter` | Expand detail or open the selected sub-issue |
+| `h` / `l` | Switch board column or detail region |
+| `u` | Go to parent issue or back |
+| `ctrl+u` / `ctrl+d` | Half-page scroll in detail |
+| `r` | Refresh current view |
+| `p` | Pause or resume auto-refresh |
+| `?` | Toggle help |
+| `q` | Quit |
+
 <details>
 <summary>Verbose JSON examples</summary>
 
@@ -222,6 +254,8 @@ docket issue list --json -s todo -s in-progress -p high
 --quiet, -q   Suppress non-essential output
 ```
 
+`docket tui` is interactive-only and rejects `--json`.
+
 ### Issue Commands (`docket issue` / `docket i`)
 
 | Command | Description |
@@ -290,6 +324,7 @@ docket issue list --json -s todo -s in-progress -p high
 | `docket config` | Show current configuration (database path, schema version, etc.) |
 | `docket version` | Print version, commit, and build date |
 | `docket stats` | Show summary statistics for the issue database |
+| `docket tui` | Browse issues in an interactive terminal UI |
 
 ### Export / Import
 

docs/spec/architecture.md

@@ -76,7 +76,7 @@ SQLite (modernc.org/sqlite) -- .docket/issues.db
 
 Built on **spf13/cobra**. The root command (`docket`) defines:
 
-- Global flags: `--json` (structured output), `--quiet` (suppress non-essential output)
+- Global flags: `--json` (structured output), `--quiet` (suppress non-essential output). Interactive commands can reject unsupported flags at runtime; `docket tui` rejects `--json`.
 - `PersistentPreRunE`: Resolves config, opens SQLite DB, runs migrations. Commands annotated with `skipDB` bypass DB initialization (e.g., `init`).
 - `PersistentPostRunE`: Closes the DB connection.
 - Version info injected via ldflags at build time (`version`, `commit`, `buildDate`).
@@ -87,6 +87,7 @@ Built on **spf13/cobra**. The root command (`docket`) defines:
 |---------|-------------|-------------|
 | `init` | -- | Create `.docket/` directory and initialize schema |
 | `board` | -- | Kanban board view (columns by status) |
+| `tui` | -- | Read-only interactive terminal UI for browsing issues |
 | `plan` | -- | DAG-based execution plan with phased grouping |
 | `next` | -- | Work-ready issues (unblocked leaf tasks) |
 | `stats` | -- | Summary statistics (counts by status/priority/label) |

docs/spec/review-strategy.md

@@ -69,15 +69,16 @@ The following dimensions are weighted by their relevance to the docket project,
 - Review must verify: migration idempotency, rollback safety, data preservation across versions
 
 **JSON API Contract Stability (Critical)**
-- Every command supports `--json` with a documented envelope (`{"ok": true, "data": ..., "message": ...}`)
+- Non-interactive commands support `--json` with a documented envelope (`{"ok": true, "data": ..., "message": ...}`)
 - AI agents depend on stable JSON shapes — breaking changes silently break agent workflows
+- Interactive commands like `docket tui` are exceptions and must fail clearly when `--json` is unsupported
 - Error codes (`GENERAL_ERROR`, `NOT_FOUND`, `VALIDATION_ERROR`, `CONFLICT`) are part of the contract
 - The QA suite has dedicated sections (Q, R) for contract and exit code validation
 - Review must verify: no field renames/removals without versioning, exit codes match documented behavior
 
 **CLI UX Consistency (High)**
 - One-file-per-command pattern in `internal/cli/` must be maintained
-- All commands must support `--json` and `--quiet` flags via `getWriter()`
+- Non-interactive commands should support `--json` and `--quiet` via `getWriter()`; interactive commands must document and enforce any exceptions
 - Interactive forms (via `charmbracelet/huh`) must degrade gracefully in non-TTY contexts
 - Review must verify: new commands follow established patterns, help text is consistent
 

go.mod

@@ -4,11 +4,14 @@ go 1.26.0
 
 require (
 	github.com/ALT-F4-LLC/vorpal/sdk/go v0.0.0-20260320211915-9fb550947a7e
+	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/glamour v1.0.0
 	github.com/charmbracelet/huh v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
 	github.com/dustin/go-humanize v1.0.1
+	github.com/muesli/termenv v0.16.0
 	github.com/spf13/cobra v1.10.2
+	golang.org/x/sys v0.42.0
 	golang.org/x/term v0.41.0
 	modernc.org/sqlite v1.47.0
 )
@@ -21,15 +24,13 @@ require (
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
 	github.com/charmbracelet/bubbles v1.0.0 // indirect
-	github.com/charmbracelet/bubbletea v1.3.10 // indirect
 	github.com/charmbracelet/colorprofile v0.4.3 // indirect
 	github.com/charmbracelet/x/ansi v0.11.6 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
 	github.com/charmbracelet/x/exp/slice v0.0.0-20260316093931-f2fb44ab3145 // indirect
 	github.com/charmbracelet/x/exp/strings v0.1.0 // indirect
 	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/clipperhouse/displaywidth v0.11.0 // indirect
-	github.com/clipperhouse/stringish v0.1.1 // indirect
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
 	github.com/dlclark/regexp2 v1.11.5 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
@@ -45,7 +46,6 @@ require (
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/reflow v0.3.0 // indirect
-	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
@@ -55,9 +55,8 @@ require (
 	github.com/yuin/goldmark-emoji v1.0.6 // indirect
 	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 // indirect
 	golang.org/x/net v0.52.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/text v0.35.0 // indirect
+	golang.org/x/tools v0.43.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7 // indirect
 	google.golang.org/grpc v1.79.3 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect