docs(readme): sync documentation with current codebase

- Update Go version requirement from 1.21 to 1.25
- Add token-store parameter and keyring storage backend documentation
- Correct backoff strategy from multiplicative to additive per RFC 8628
- Update binary paths, timeouts, and development commands
- Remove references to deleted filelock.go and nonexistent make targets
- Bump golangci-lint install version to v2.11.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: appleboy

.goreleaser.yaml

@@ -2,7 +2,6 @@ version: 2
 project_name: authgate-device-cli
 before:
   hooks:
-    - make generate
     - go mod tidy
 
 builds:

CLAUDE.md

@@ -24,7 +24,7 @@ make coverage
 go test -v -run TestFunctionName ./...
 
 # Run tests for specific file
-go test -v ./filelock_test.go filelock.go
+go test -v ./main_test.go main.go
 ```
 
 ### Linting and Formatting
@@ -47,8 +47,6 @@ make check-tools
 make build
 ./bin/device-cli -client-id=<id> -server-url=http://localhost:8080
 
-# Hot reload during development
-make dev                  # Uses air for live reload
 ```
 
 ### Other Commands
@@ -66,10 +64,12 @@ make build_linux_arm64
 
 ### File Structure
 
-- **main.go** (905 lines): Core application logic, contains all OAuth flow, HTTP client, token management, and CLI entry point
-- **filelock.go**: File locking mechanism for safe concurrent token file access
-- **polling_test.go**: Tests for device code polling with exponential backoff
-- **main_test.go**: Core functionality tests including concurrent token writes
+- **main.go**: Core application logic — OAuth flow, HTTP client, token management, and CLI entry point
+- **tui/displayer.go**: Output abstraction layer (`Displayer` interface) with `PlainDisplayer` (non-TTY), `ProgramDisplayer` (BubbleTea TUI), and `NoopDisplayer` (tests)
+- **tui/model.go**: BubbleTea model for interactive terminal UI
+- **tui/messages.go**: BubbleTea message types for TUI state transitions
+- **polling_test.go**: Tests for device code polling with additive backoff
+- **main_test.go**: Core functionality tests
 
 ### Configuration Loading
 
@@ -83,24 +83,13 @@ The `initConfig()` function is separated from `init()` to avoid conflicts with G
 
 ### Token Storage Architecture
 
-**Multi-client support**: A single JSON file (`TokenStorageMap`) stores tokens for multiple OAuth clients, keyed by `client_id`:
+Token storage is handled by the `credstore` package from `github.com/go-authgate/sdk-go`. The `-token-store` flag controls the backend:
 
-```json
-{
-  "tokens": {
-    "client-id-1": { "access_token": "...", "refresh_token": "...", ... },
-    "client-id-2": { "access_token": "...", "refresh_token": "...", ... }
-  }
-}
-```
-
-**Atomic writes**: Uses temp file + rename pattern to prevent corruption:
-
-1. Write new data to `<tokenfile>.tmp`
-2. Rename tmp file to actual file (atomic operation)
-3. On error, clean up temp file
+- **`auto`** (default): `SecureStore` wraps keyring with file fallback. Warns if keyring is unavailable.
+- **`keyring`**: Uses OS keyring via `TokenKeyringStore` (macOS Keychain, GNOME Keyring, Windows Credential Manager)
+- **`file`**: Uses `TokenFileStore` with JSON file at the configured path
 
-**File locking**: `saveTokens()` acquires an exclusive lock via `acquireFileLock()` to prevent race conditions during concurrent access. Lock files (`<tokenfile>.lock`) have stale lock detection (30s timeout) and automatic cleanup.
+**Multi-client support**: All backends store tokens keyed by `client_id`. The `credstore.Store[credstore.Token]` interface provides `Load(clientID)` and `Save(clientID, token)` methods.
 
 ### OAuth Flow Implementation
 
@@ -115,12 +104,12 @@ The main flow is orchestrated by `run()`:
 
 ### Device Code Polling
 
-`pollForTokenWithProgress()` implements RFC 8628 polling with exponential backoff:
+`pollForTokenWithProgress()` implements RFC 8628 polling with additive backoff:
 
 - Initial interval from server (default: 5s)
-- On `slow_down` error: multiply interval by 1.5, cap at 60s
-- Progress dots printed every 2s (UI update interval)
-- Two separate tickers: one for polling, one for UI updates
+- On `slow_down` error: adds 5s to interval per RFC 8628 §3.5, capped at 60s
+- Progress reported via `Displayer` interface (TUI or plain text)
+- Single ticker for polling
 - Handles errors: `authorization_pending`, `slow_down`, `expired_token`, `access_denied`
 
 ### HTTP Client Configuration
@@ -158,10 +147,6 @@ The function checks `ErrRefreshTokenExpired` for `invalid_grant` or `invalid_tok
 
 Tests use a separate `init()` function that sets defaults without calling `initConfig()`, avoiding flag parsing conflicts.
 
-### Concurrent Testing
-
-`TestSaveTokens_ConcurrentWrites` spawns 10 goroutines to verify file locking works correctly under concurrent access.
-
 ### Test Servers
 
 Tests use `httptest` to create mock OAuth servers, returning device codes and tokens.
@@ -175,11 +160,12 @@ The CLI automatically warns users when:
 - Using HTTP instead of HTTPS (tokens transmitted in plaintext)
 - CLIENT_ID is not a valid UUID format
 
-### Token File Security
+### Token Storage Security
 
-- Created with `0600` permissions (owner read/write only)
-- Should be added to `.gitignore` (already configured)
-- Stored at `.authgate-tokens.json` by default
+- Keyring backend: OS-level credential encryption (preferred)
+- File backend: created with `0600` permissions (owner read/write only)
+- Token files should be added to `.gitignore` (already configured)
+- Default file path: `.authgate-tokens.json`
 
 ### Version Information
 
@@ -196,7 +182,7 @@ goreleaser uses these to build versioned binaries with naming pattern:
 ### CI/CD
 
 - **Testing**: Runs on Ubuntu and macOS with Go 1.25 and 1.26
-- **Linting**: Uses golangci-lint v2.9 with config from `.golangci.yml`
+- **Linting**: Uses golangci-lint v2.11 with config from `.golangci.yml`
 - **Release**: goreleaser builds for multiple platforms (see `.goreleaser.yaml`)
 
 ## Go Modules
@@ -207,3 +193,7 @@ Requires Go 1.25+. Key dependencies:
 - `github.com/appleboy/go-httpretry`: HTTP retry logic
 - `github.com/joho/godotenv`: .env file loading
 - `github.com/google/uuid`: UUID validation
+- `github.com/go-authgate/sdk-go/credstore`: Token storage abstraction (file, keyring, auto)
+- `charm.land/bubbletea/v2`: Terminal UI framework
+- `charm.land/lipgloss/v2`: Terminal styling
+- `charm.land/bubbles/v2`: TUI components

Makefile

@@ -37,7 +37,7 @@ coverage: test
 
 ## install-golangci-lint: install golangci-lint if not present
 install-golangci-lint:
-	@command -v golangci-lint >/dev/null 2>&1 || curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $$($(GO) env GOPATH)/bin v2.7.2
+	@command -v golangci-lint >/dev/null 2>&1 || curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $$($(GO) env GOPATH)/bin v2.11.0
 
 ## fmt: format go files using golangci-lint
 fmt: install-golangci-lint

README.md

@@ -40,7 +40,7 @@ A CLI tool for authenticating with AuthGate server via OAuth 2.0 Device Authoriz
 
 ## Prerequisites
 
-- **Go 1.21+** — required to build from source
+- **Go 1.25+** — required to build from source
 - **AuthGate server** — must be running and accessible ([AuthGate Documentation](../../README.md))
 - **Default server address**: `http://localhost:8080`
 
@@ -52,13 +52,13 @@ A CLI tool for authenticating with AuthGate server via OAuth 2.0 Device Authoriz
 # 1. Clone and build
 git clone <repository-url>
 cd device-cli
-go build -o authgate-device-cli
+make build
 
 # 2. Get your Client ID from the AuthGate server startup logs:
 #    Client ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
 # 3. Run
-./authgate-device-cli -client-id=<your-client-id>
+./bin/device-cli -client-id=<your-client-id>
 ```
 
 ---
@@ -67,22 +67,30 @@ go build -o authgate-device-cli
 
 Priority order: **Flag > Environment Variable > `.env` file > default**
 
-| Parameter  | Flag          | Environment Variable | Default                 |
-| ---------- | ------------- | -------------------- | ----------------------- |
-| Client ID  | `-client-id`  | `CLIENT_ID`          | _(required)_            |
-| Server URL | `-server-url` | `SERVER_URL`         | `http://localhost:8080` |
-| Token File | `-token-file` | `TOKEN_FILE`         | `.authgate-tokens.json` |
+| Parameter   | Flag            | Environment Variable | Default                 |
+| ----------- | --------------- | -------------------- | ----------------------- |
+| Client ID   | `-client-id`    | `CLIENT_ID`          | _(required)_            |
+| Server URL  | `-server-url`   | `SERVER_URL`         | `http://localhost:8080` |
+| Token File  | `-token-file`   | `TOKEN_FILE`         | `.authgate-tokens.json` |
+| Token Store | `-token-store`  | `TOKEN_STORE`        | `auto`                  |
+
+**Token Store modes:**
+
+- `auto` (default): Tries OS keyring first, falls back to file if keyring is unavailable
+- `keyring`: Uses OS keyring only (macOS Keychain, GNOME Keyring, Windows Credential Manager)
+- `file`: Uses JSON file only
 
 **Example `.env` file:**
 
 ```env
 CLIENT_ID=abc-123
 SERVER_URL=http://localhost:8080
 TOKEN_FILE=.authgate-tokens.json
+TOKEN_STORE=auto
 ```
 
 ```bash
-./authgate-device-cli -h   # view all options
+./bin/device-cli -h   # view all options
 ```
 
 ---
@@ -157,7 +165,17 @@ Tokens are saved locally after first login. The CLI will:
 
 ## Token Storage
 
-Tokens are stored in `.authgate-tokens.json` (configurable). A single file supports **multiple Client IDs**.
+Tokens are managed by the `credstore` package from [`sdk-go`](https://github.com/go-authgate/sdk-go), which supports multiple storage backends:
+
+| Backend  | Description                                                        |
+| -------- | ------------------------------------------------------------------ |
+| `auto`   | Tries OS keyring first, falls back to file (default)               |
+| `keyring`| OS keyring: macOS Keychain, GNOME Keyring, Windows Credential Manager |
+| `file`   | JSON file at `.authgate-tokens.json` (configurable)                |
+
+A single store supports **multiple Client IDs**.
+
+When using file-based storage, the JSON format is:
 
 ```json
 {
@@ -182,33 +200,39 @@ Tokens are stored in `.authgate-tokens.json` (configurable). A single file suppo
 
 **Security properties:**
 
-- Created with `0600` permissions (owner read/write only)
-- Written atomically (temp file + rename) to prevent corruption
-- File locking prevents race conditions with concurrent processes
+- File-based storage: created with `0600` permissions (owner read/write only)
+- Keyring storage: uses OS-level credential encryption
+- Automatic fallback warning when OS keyring is unavailable
 
-> **Never commit this file to version control.** Add `.authgate-tokens.json` to `.gitignore`.
+> **Never commit token files to version control.** Add `.authgate-tokens.json` to `.gitignore`.
 
 ---
 
 ## Usage Examples
 
 ```bash
 # First run — prompts for browser authorization
-./authgate-device-cli -client-id=abc-123
+./bin/device-cli -client-id=abc-123
 
 # Subsequent runs — reuses saved tokens automatically
-./authgate-device-cli -client-id=abc-123
+./bin/device-cli -client-id=abc-123
 
 # Custom server URL
-./authgate-device-cli -client-id=abc-123 -server-url=https://auth.example.com
+./bin/device-cli -client-id=abc-123 -server-url=https://auth.example.com
 
-# Multiple clients — stored in same file by default
-./authgate-device-cli -client-id=abc-123
-./authgate-device-cli -client-id=xyz-789
+# Use OS keyring for token storage
+./bin/device-cli -client-id=abc-123 -token-store=keyring
 
-# Multiple clients — separate token files
-./authgate-device-cli -client-id=abc-123 -token-file=./work-tokens.json
-./authgate-device-cli -client-id=xyz-789 -token-file=./personal-tokens.json
+# Use file-only storage
+./bin/device-cli -client-id=abc-123 -token-store=file
+
+# Multiple clients — stored in same backend by default
+./bin/device-cli -client-id=abc-123
+./bin/device-cli -client-id=xyz-789
+
+# Multiple clients — separate token files (file mode)
+./bin/device-cli -client-id=abc-123 -token-store=file -token-file=./work-tokens.json
+./bin/device-cli -client-id=xyz-789 -token-store=file -token-file=./personal-tokens.json
 ```
 
 ---
@@ -220,7 +244,7 @@ The CLI handles all OAuth 2.0 Device Authorization Grant error codes defined in
 | Error                   | Meaning                                   | CLI Behaviour                                           |
 | ----------------------- | ----------------------------------------- | ------------------------------------------------------- |
 | `authorization_pending` | User has not authorized yet               | Continues polling, shows progress dots                  |
-| `slow_down`             | Server requests slower polling            | Triggers exponential backoff (×1.5 multiplier, max 60s) |
+| `slow_down`             | Server requests slower polling            | Adds 5s to polling interval per RFC 8628 §3.5 (max 60s) |
 | `expired_token`         | Device code expired (default: 30 minutes) | Stops polling, prompts to restart authentication        |
 | `access_denied`         | User explicitly denied authorization      | Stops and displays denial message                       |
 | Other errors            | Unexpected server errors                  | Stops and displays detailed error information           |
@@ -229,26 +253,26 @@ The CLI handles all OAuth 2.0 Device Authorization Grant error codes defined in
 
 ## Advanced Features
 
-### Polling with Exponential Backoff
+### Polling with Additive Backoff
 
 - **Initial interval**: 5 seconds (set by server)
-- **Progress indicator**: dots printed every 2 seconds; newline every 50 dots
-- **`slow_down` backoff**: interval multiplied by 1.5 on each signal, capped at 60s
+- **TUI progress**: interactive terminal UI when running in a TTY; plain text output otherwise
+- **`slow_down` backoff**: adds 5 seconds per signal (per RFC 8628 §3.5), capped at 60s
 
 ```txt
-Initial:        5.000s
-1st slow_down:  7.500s
-2nd slow_down: 11.250s
-3rd slow_down: 16.875s
+Initial:        5s
+1st slow_down: 10s
+2nd slow_down: 15s
+3rd slow_down: 20s
 ...
-Maximum:       60.000s
+Maximum:       60s
 ```
 
 ### Context and Cancellation
 
 - All operations respect Go context cancellation
 - Graceful shutdown on `Ctrl+C`
-- Request timeout: 30 seconds per HTTP call
+- Per-operation timeouts: device code 10s, token exchange 5s, verification 10s, refresh 10s
 
 ---
 
@@ -258,7 +282,7 @@ Maximum:       60.000s
 
 | Protection          | Detail                                              |
 | ------------------- | --------------------------------------------------- |
-| Request timeout     | 30 seconds (prevents indefinite hangs)              |
+| Request timeout     | Per-operation: 5–10 seconds (see Context section)   |
 | Minimum TLS version | TLS 1.2                                             |
 | HTTP warning        | Warns automatically when server URL uses plain HTTP |
 | Connection pooling  | Idle connection limits to manage resources          |
@@ -268,11 +292,11 @@ Maximum:       60.000s
 - **`SERVER_URL`**: Validates URL format and scheme (`http`/`https` only)
 - **`CLIENT_ID`**: Warns if value is not a valid UUID format
 
-### Token File
+### Token Storage Security
 
-- Permissions: `0600` (owner-only)
-- Atomic writes: temp file + rename pattern
-- File locking: prevents data corruption with concurrent access
+- **Keyring** (default when available): OS-level credential encryption
+- **File fallback**: `0600` permissions (owner-only)
+- CLI warns when OS keyring is unavailable and file storage is used
 
 ### Error Handling
 
@@ -308,7 +332,7 @@ The token was revoked or is invalid. Delete the token file and re-authenticate:
 
 ```bash
 rm .authgate-tokens.json
-./authgate-device-cli -client-id=<your-id>
+./bin/device-cli -client-id=<your-id>
 ```
 
 **`refresh failed`**
@@ -318,21 +342,29 @@ The CLI will automatically start a new device flow. Follow the browser authoriza
 Normal behavior — the server returned a `slow_down` signal. The CLI has automatically increased its polling interval. See [Error Reference](#error-reference).
 
 **`context deadline exceeded`**
-A request timed out (30s limit). Check your network connection and server availability.
+A request timed out. Check your network connection and server availability.
 
 ---
 
 ## Development
 
 ```bash
-# Run tests
-go test ./...
+# Run tests with coverage
+make test
+
+# Build binary (output: bin/device-cli)
+make build
+
+# Lint and format
+make lint
+make fmt
 
-# Build binary
-go build -o authgate-device-cli
+# Cross-platform builds
+make build_linux_amd64
+make build_linux_arm64
 
-# Build with version info
-go build -ldflags="-X main.version=1.0.0" -o authgate-device-cli
+# Clean build artifacts
+make clean
 ```
 
 ---