Add Ratatui terminal application

README.md

@@ -1,8 +1,8 @@
 # Gotcha
 
 Gotcha is a lightweight Gitea and Forgejo client with a reusable Rust core, a
-CLI, and a native iOS application. The iOS interface is UIKit/Swift; UniFFI
-exposes the Rust application logic to Swift.
+CLI, a Ratatui terminal interface, and a native iOS application. The iOS
+interface is UIKit/Swift; UniFFI exposes the Rust application logic to Swift.
 
 On the icon: git in a tea cup. it is obvious, isn't it?
 
@@ -20,6 +20,7 @@ not necessarily the app to use when you manage or frequent a large instance.
 - `gotcha_gitea`: reusable asynchronous Gitea/Forgejo API client with the
   complete typed Gitea 1.25-compatible API and model surface
 - `gotcha`: CLI for typed common operations and arbitrary API requests
+- `gotcha-tui`: paned, keyboard-and-mouse terminal application
 - `gotcha-app`: Rust application core and UniFFI API used by iOS
 - `ios`: native UIKit application for activity, repositories, favorites,
   issues, milestones, pull requests, commit history, changed files, and diffs; bundle
@@ -88,12 +89,35 @@ derives the `owner/repository` scope. Use `--server gitea.example.com` when sele
 ambiguous, or `--url`/`GITEA_URL` for an unconfigured server. Tokens are never
 accepted as command-line arguments or environment variables.
 
+## Terminal UI
+
+Build and run the standalone TUI with an existing CLI server profile:
+
+```sh
+cargo run -p gotcha-tui
+cargo run -p gotcha-tui -- --server gitea.example.com
+```
+
+The five numbered panes mirror the iPhone app: Home, Issues, Repositories,
+pull requests, and Milestones. Use `j`/`k` or the arrow keys to select rows,
+Enter to open, Backspace to return, `/` for list filters, and `a`, `e`, `c`,
+`x`, and `d` for mutations. Use `n`/`p` for API result pages; scrolling the
+mouse wheel past a page boundary does the same. Repository lists support `*` favorites, commit
+lists support `b` branch switching, and Home supports `v` activity filters.
+Editors use Tab between fields and Ctrl-S to save. Mouse selection,
+double-click, and wheel scrolling work in ordinary terminals and Herdr.
+
+Overview panes refresh every five seconds by default. Press `,` to change the
+interval or set it to zero. Refresh waits while an editor or confirmation is
+open and after keyboard or mouse activity so it does not move the current
+selection during interaction.
+
 ## Architecture
 
 `gotcha_gitea` owns Gitea/Forgejo access, authentication, validation,
-mutations, and relationships between server objects. The CLI is a terminal presentation layer:
-it parses arguments and YAML, invokes shared client operations, and formats the
-results. `gotcha-app` owns application state, preferences, favorites,
+mutations, relationships between server objects, and shared CLI/TUI server
+configuration. The CLI and TUI are terminal presentation layers that invoke
+shared client operations. `gotcha-app` owns application state, preferences, favorites,
 Keychain-backed credentials, and view-ready UniFFI records. UIKit owns native
 navigation, controls, layout, and other platform presentation behavior.