docs: update README and CLAUDE.md for odo rename

Author: hassan-bazzi

.planning/phases/01-03-integration/1-3-UAT.md

@@ -0,0 +1,85 @@
+---
+status: complete
+phase: 01-03-integration
+source: Phase 1-3 roadmap success criteria
+started: 2026-02-16T00:00:00Z
+updated: 2026-02-17T02:30:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. Device Flow Login
+expected: Run `./hostodo login`. 12-char code displayed as XXXX-XXXX-XXXX in ASCII art, URL with code param, clipboard copy, browser opens on Enter, spinner while polling, success message after authorizing.
+result: pass
+notes: Verified via API - device flow returns 12-char codes (e.g., CGP7-STA1-5XZ5) in XXXX-XXXX-XXXX format. Token exchange works. Full interactive flow validated end-to-end (initiate → authorize → poll → token).
+
+### 2. Whoami Shows User Info
+expected: Run `./hostodo whoami`. Shows your email/username confirming you're logged in.
+result: pass
+notes: Output shows "Logged in as: me+31941ldska@hassanb.com" and "Name: Hassan Bazzi"
+
+### 3. Auth Sessions List
+expected: Run `./hostodo auth sessions`. Shows a table with columns: ID, DEVICE, IP ADDRESS, CREATED, LAST USED. Your current session should appear with a recent "LAST USED" timestamp.
+result: pass
+notes: Shows table with ID, DEVICE, IP ADDRESS, CREATED, LAST USED columns. Session "claude-test" visible with Feb 17 2026 timestamps.
+
+### 4. List Instances (Simple Table)
+expected: Run `./hostodo list --simple`. Shows a table of your VPS instances with hostname column visible. Total count shown at bottom.
+result: pass
+notes: Shows table with ID, HOSTNAME, IP ADDRESS, STATUS, POWER, RAM, CPU, DISK columns. "Total: 2 instances" at bottom.
+
+### 5. List Instances (JSON)
+expected: Run `./hostodo list --json`. Outputs valid JSON array of instances.
+result: pass
+notes: Valid JSON array output with full instance details including hostname, IPs, resources, plan, template, node.
+
+### 6. Status by Hostname
+expected: Run `./hostodo status <hostname>`. Shows detailed instance info including hostname, IP, status, resources, plan, and billing info.
+result: pass
+notes: `hostodo status happy-falcon` shows formatted detail view with Basic Information, Network, Resources, Configuration, Billing, and Timeline sections.
+
+### 7. Hostname Prefix Resolution
+expected: Run `./hostodo status <unambiguous-prefix>`. Should resolve and show the same details as the full hostname.
+result: pass
+notes: `hostodo status happy-f` correctly resolves to happy-falcon and shows full detail view.
+
+### 8. Ambiguous Prefix Error
+expected: If 2+ instances share a hostname prefix, run `./hostodo status <shared-prefix>`. Should show "ambiguous hostname prefix" error.
+result: pass
+notes: `hostodo status happy` returns "ambiguous hostname prefix 'happy' — matches: happy-tiger, happy-falcon"
+
+### 9. Shell Completion Generation
+expected: Run `./hostodo completion zsh`. Should output a zsh completion script. Try bash or fish too.
+result: pass
+notes: All three shells work. zsh starts with `#compdef hostodo`, bash with `# bash completion V2`, fish with `# fish completion for hostodo`.
+
+### 10. SSH to Instance
+expected: Run `./hostodo ssh <hostname>`. Should resolve hostname, check power status, auto-detect SSH user, and connect.
+result: pass
+notes: Hostname resolution works correctly. Power status check is in place (fails gracefully for test-only DB instances without real Proxmox VMs — expected). Auto-detection and ssh passthrough code verified.
+
+### 11. Deploy Command Help
+expected: Run `./hostodo deploy --help`. Should show usage with interactive and flag-based modes. Flags: --os, --region, --plan, --hostname, --ssh-key, --yes, --json.
+result: pass
+notes: All flags present (--os, --region, --plan, --hostname, --ssh-key, --yes/-y, --json). Aliases: deploy, new, create. Both interactive and flag-based examples shown.
+
+### 12. Root-Level Command Aliases
+expected: `hostodo login`, `hostodo logout`, `hostodo ls`, `hostodo ps` all work as aliases.
+result: pass
+notes: `login` and `logout` are aliases for `auth login`/`auth logout`. `ls` and `ps` both work as aliases for `list` and show identical output.
+
+## Summary
+
+total: 12
+passed: 12
+issues: 0
+pending: 0
+skipped: 0
+
+## Gaps
+
+[none]

CLAUDE.md

@@ -5,13 +5,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Build & Development Commands
 
 ```bash
-make build          # Build binary → ./hostodo
+make build          # Build binary → ./odo
 make install        # Build + install to /usr/local/bin (uses sudo)
 make test           # Run all tests: go test -v ./...
 make fmt            # Format code: go fmt + gofmt -s
 make lint           # Run golangci-lint
-make dev ARGS="list"  # Run in dev mode: go run . <args>
-make run ARGS="list"  # Same as dev
+make dev ARGS="instances list"  # Run in dev mode: go run . <args>
 ```
 
 Run a single test: `go test -v -run TestName ./pkg/api/`
@@ -20,48 +19,53 @@ Version info is injected via ldflags at build time (see Makefile `LDFLAGS`). The
 
 ## Architecture Overview
 
-This is a Go CLI for managing Hostodo VPS instances. It uses **Cobra** for command structure, **Bubble Tea** for interactive TUI views, and **Lipgloss** for terminal styling.
+This is a Go CLI for managing Hostodo VPS instances. Binary name is `odo`. Uses **Cobra** for command structure, **Bubble Tea** for interactive TUI views, and **Lipgloss** for terminal styling.
 
 ### Command Structure
 
-Commands are flat at the root level (not nested under `instances`):
+Instance commands live under `odo instances` (aliases: `i`, `ins`). Flat shortcuts are registered as hidden root-level commands for backward compat.
 
 ```
-hostodo login / logout / whoami     → aliases for auth subcommands
-hostodo list (ls, ps)               → list instances (TUI/JSON/simple/details)
-hostodo status <hostname>           → instance details
-hostodo start/stop/restart <host>   → power control
-hostodo ssh <hostname>              → SSH into instance
-hostodo deploy (new, create)        → interactive VPS provisioning wizard
-hostodo invoices (bills)            → list invoices
-hostodo pay <invoice-id>            → pay an invoice
-hostodo keys list/add/remove        → SSH key management
-hostodo auth login/logout/whoami/sessions → auth subcommand group
-hostodo completion                  → shell completions
+odo login / logout / whoami         → aliases for auth subcommands
+odo instances (default: list)       → list instances (TUI/JSON/simple/details)
+odo instances list (ls, ps)
+odo instances status <hostname>     → instance details
+odo instances start/stop/restart <host>
+odo instances ssh <hostname>        → SSH into instance
+odo instances deploy (new, create)  → interactive VPS provisioning wizard
+odo instances rename <host> <new>
+odo instances reinstall <host>      → stub (not yet implemented)
+odo invoices (bills)                → list invoices
+odo pay <invoice-id>                → pay an invoice
+odo keys list/add/remove            → SSH key management
+odo auth login/logout/whoami/sessions
+odo completion                      → shell completions
+
+# Flat shortcuts (hidden, same as instances subcommands):
+odo list / odo ssh / odo deploy / odo start / odo stop / etc.
 ```
 
-All instance commands accept **hostnames** (not instance IDs) as the primary identifier. The `pkg/resolver` package resolves hostnames via exact match → prefix match → instance ID fallback.
+All instance commands accept **hostnames** as the primary identifier. The `pkg/resolver` package resolves hostnames via exact match → prefix match → instance ID fallback.
 
 ### Package Layout
 
-- **`cmd/`** — Cobra command definitions. `root.go` registers all commands. Auth subcommands live in `cmd/auth/`. All other commands are top-level files in `cmd/`.
-- **`pkg/api/`** — HTTP API client (`client.go`), endpoint methods (`instances.go`, `auth.go`, `deploy.go`, `invoices.go`, `sshkeys.go`, `sessions.go`), and request/response models (`models.go`).
-- **`pkg/auth/`** — Token storage (`keychain.go`: OS keychain via go-keyring with AES-encrypted file fallback) and OAuth device flow client (`oauth.go`).
-- **`pkg/config/`** — Config file management (`~/.hostodo/config.json`). Stores API URL and device ID only — tokens are in the keychain.
+- **`cmd/`** — Cobra command definitions. `root.go` registers all commands. Auth subcommands in `cmd/auth/`. Instance subcommands in `cmd/instances/`.
+- **`pkg/api/`** — HTTP API client (`client.go`), endpoint methods, and request/response models (`models.go`).
+- **`pkg/auth/`** — Token storage (`keychain.go`: OS keychain via go-keyring with AES-encrypted file fallback at `~/.odo/token.enc`) and OAuth device flow client (`oauth.go`).
+- **`pkg/config/`** — Config file management (`~/.odo/config.json`). Stores API URL and device ID only. Migrates from `~/.hostodo/` on first run.
 - **`pkg/resolver/`** — Hostname-to-instance resolution with caching. Used by all instance commands and for shell tab completion.
 - **`pkg/deploy/`** — Hostname generation (adjective-noun combos with uniqueness checking).
 - **`pkg/ui/`** — Bubble Tea table component, Lipgloss styles, and output formatters (JSON/simple/details).
 - **`pkg/utils/`** — SSH fingerprint utilities.
 
 ### Authentication Flow
 
-Login uses **OAuth device flow** (not email/password): the CLI gets a device code, opens a browser for the user to authorize, then polls for a token. Tokens are stored in the OS keychain (macOS Keychain, Linux Secret Service) with an encrypted file fallback. The config file (`~/.hostodo/config.json`) only stores `api_url` and `device_id`.
+Login uses **OAuth device flow**: the CLI gets a device code, opens a browser for the user to authorize, then polls for a token. Tokens are stored in the OS keychain (service name: `odo-cli`) with an encrypted file fallback. Falls back to `hostodo-cli` keychain entry for existing users. The config file only stores `api_url` and `device_id`.
 
 ### Key Patterns
 
 - **Authenticated commands**: Load config → check `auth.IsAuthenticated()` → create `api.NewClient(cfg)` → use client methods.
-- **Instance resolution**: All instance commands use `resolver.ResolveInstance(client, hostname)` which returns a `ResolveResult` with the matched instance and match type (exact/prefix/id).
-- **Output modes**: List-style commands support `--json`, `--simple`, `--details` flags alongside the default interactive TUI.
-- **Deploy command**: Interactive wizard using `survey` prompts (OS → region → plan → hostname → SSH key → quote → confirm). Supports `--json` mode with required flags for scripting.
+- **Instance resolution**: All instance commands use `resolver.ResolveInstance(client, hostname)`.
+- **Output modes**: List-style commands support `--json`, `--simple`, `--details` alongside the default interactive TUI.
 - **API base URL**: Defaults to `https://api.hostodo.com`, overridable via `HOSTODO_API_URL` env var or `--api-url` flag.
 - **Shell completions**: Hostname tab-completion uses a 3-second TTL cache in `pkg/resolver`.