init codebase

docs/prd/cli.md

@@ -310,9 +310,100 @@ Last-Event-ID: <id>   (for reconnection)
 - Unread counts in sidebar (same as web)
 - Notification list accessible via slash command `/notifications`
 
-## 5. Test Cases
+## 5. Distribution & Packaging
 
-### 5.1 CLI Authentication
+### 5.1 bbin Packaging
+
+**Build:** Compile to an uberjar, then distribute via bbin (Babashka binary installer).
+
+```bash
+# Build uberjar
+clj -T:build uber          # produces target/ajet-chat-cli.jar
+
+# Install locally via bbin
+bbin install . --as ajet    # installs 'ajet' command from local project
+
+# Install from remote (for users)
+bbin install io.github.ajet/ajet-chat-cli --as ajet
+```
+
+**Binary:** The `ajet` command is a shell wrapper that invokes `java -jar` (or `bb` if Babashka-compatible). First run may be slow due to JVM startup; subsequent runs benefit from Drip or CDS caching.
+
+### 5.2 Babashka Compatibility
+
+**Goal:** CLI mode should be Babashka-compatible for fast startup. TUI mode requires JVM (clojure-tui dependency).
+
+**Constraints for Babashka compatibility:**
+- No `deftype` / `defrecord` (use maps + protocols sparingly)
+- No `gen-class`
+- Use `babashka.http-client` (not `clj-http`)
+- Use `clojure.data.json` (bb-compatible)
+- Avoid Java interop beyond what bb supports
+- All CLI commands (non-TUI) target < 100ms startup via bb
+
+**Fallback:** If Babashka compatibility proves too restrictive, ship as JVM uberjar with CDS (Class Data Sharing) for faster startup.
+
+### 5.3 Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error (API error, unexpected failure) |
+| 2 | Usage error (bad arguments, unknown command) |
+| 3 | Authentication error (not logged in, token expired) |
+| 4 | Permission error (403 from API) |
+| 5 | Not found (404 from API — channel, message, user doesn't exist) |
+| 130 | Interrupted (Ctrl+C / SIGINT) |
+
+### 5.4 Error Message UX
+
+All errors follow this format:
+```
+Error: <short description>
+
+  <details or suggestion>
+
+Hint: <actionable next step>
+```
+
+**Examples:**
+```
+Error: Not logged in
+
+  No session token found. You need to authenticate first.
+
+Hint: Run 'ajet login' to sign in
+```
+
+```
+Error: Channel not found: #nonexistent
+
+  The channel doesn't exist or you don't have access.
+
+Hint: Run 'ajet channels' to see available channels
+```
+
+```
+Error: Edit window expired
+
+  Messages can only be edited within 1 hour of creation.
+  This message was sent 3 hours ago.
+```
+
+### 5.5 Offline Behavior
+
+| Scenario | Behavior |
+|----------|----------|
+| Server unreachable | `Error: Cannot connect to server at chat.example.com` + hint to check config |
+| Timeout (> 10s) | `Error: Request timed out` + hint to retry |
+| TUI SSE disconnects | Status bar shows "Reconnecting..." + auto-retry with backoff |
+| TUI SSE reconnects | Catches up on missed events, no user action needed |
+
+---
+
+## 6. Test Cases
+
+### 6.1 CLI Authentication
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -323,7 +414,7 @@ Last-Event-ID: <id>   (for reconnection)
 | CLI-T5 | Expired token | Commands return clear "session expired, run ajet login" message |
 | CLI-T6 | No config exists | First run creates config dir and prompts for server URL |
 
-### 5.2 CLI Commands
+### 6.2 CLI Commands
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -351,7 +442,7 @@ Last-Event-ID: <id>   (for reconnection)
 | CLI-T28 | Unknown command | Prints help with suggestion |
 | CLI-T29 | No arguments | Prints usage/help |
 
-### 5.3 TUI Launch & Layout
+### 6.3 TUI Launch & Layout
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -362,7 +453,7 @@ Last-Event-ID: <id>   (for reconnection)
 | TUI-T5 | Online indicators | Online users have green dot in DM list |
 | TUI-T6 | Status bar | Shows keybindings and connection status |
 
-### 5.4 TUI Navigation
+### 6.4 TUI Navigation
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -377,7 +468,7 @@ Last-Event-ID: <id>   (for reconnection)
 | TUI-T15 | Esc closes panels | Thread panel or search closes on Esc |
 | TUI-T16 | Community switch | Click community in sidebar → channels update |
 
-### 5.5 TUI Messaging
+### 6.5 TUI Messaging
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -393,7 +484,7 @@ Last-Event-ID: <id>   (for reconnection)
 | TUI-T26 | Reply in thread | Type in thread input → reply sent |
 | TUI-T27 | Image paste | Not supported in TUI (CLI `--image` flag instead) |
 
-### 5.6 TUI Real-Time
+### 6.6 TUI Real-Time
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -404,7 +495,7 @@ Last-Event-ID: <id>   (for reconnection)
 | TUI-T32 | SSE reconnect | Connection lost → "Reconnecting..." → auto-reconnects |
 | TUI-T33 | Bell notification | Terminal bell on @mention or DM |
 
-### 5.7 TUI Rendering
+### 6.7 TUI Rendering
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -422,7 +513,7 @@ Last-Event-ID: <id>   (for reconnection)
 | TUI-T45 | Long message wrapping | Long messages wrap correctly within pane width |
 | TUI-T46 | Terminal resize | Layout reflows on terminal resize event |
 
-### 5.8 TUI Error Handling
+### 6.8 TUI Error Handling
 
 | ID | Test | Description |
 |----|------|-------------|