From 14dd34187d94fc07419175c17cd893e3f0081537 Mon Sep 17 00:00:00 2001
From: Tam Nhu Tran <kaitran.ntt@gmail.com>
Date: Sat, 14 Feb 2026 13:34:08 +0700
Subject: [PATCH] docs(kiro): document method-aware auth behavior

- add README Kiro auth-method examples and AWS default details

- update architecture docs for method-aware Kiro flow semantics

Refs #552

Refs #233
---
 README.md                   | 17 +++++++++++++++--
 docs/system-architecture.md | 24 +++++++++++++++++++-----
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index b4861825..b6a62ffe 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ Want to run the dashboard in Docker? See `docker/README.md`.
 The dashboard provides visual management for all account types:
 
 - **Claude Accounts**: Create isolated instances (work, personal, client)
-- **OAuth Providers**: One-click auth for Gemini, Codex, Antigravity
+- **OAuth Providers**: One-click auth for Gemini, Codex, Antigravity, Kiro, Copilot
 - **API Profiles**: Configure GLM, Kimi with your keys
 - **Health Monitor**: Real-time status across all profiles
 
@@ -93,7 +93,7 @@ The dashboard provides visual management for all account types:
 | **Codex** | OAuth | `ccs codex` | Code generation |
 | **Copilot** | OAuth | `ccs copilot` or `ccs ghcp` | GitHub Copilot models |
 | **Cursor IDE** | Local Token | `ccs cursor` | Cursor subscription models via local daemon |
-| **Kiro** | OAuth | `ccs kiro` | AWS CodeWhisperer (Claude-powered) |
+| **Kiro** | OAuth (AWS default) | `ccs kiro` | AWS CodeWhisperer (Claude-powered) |
 | **Antigravity** | OAuth | `ccs agy` | Alternative routing |
 | **OpenRouter** | API Key | `ccs openrouter` | 300+ models, unified API |
 | **Ollama** | Local | `ccs ollama` | Local open-source models, privacy |
@@ -141,6 +141,19 @@ ccs ollama    # Local Ollama (no API key needed)
 ccs glm       # GLM (API key)
 ```
 
+### Kiro Auth Methods
+
+`ccs kiro --auth` defaults to AWS Builder ID Device OAuth (best support for AWS org accounts).
+
+```bash
+ccs kiro --auth --kiro-auth-method aws           # AWS Builder ID device code (default)
+ccs kiro --auth --kiro-auth-method aws-authcode  # AWS Builder ID auth code
+ccs kiro --auth --kiro-auth-method google        # Google OAuth
+ccs kiro --auth --kiro-auth-method github        # Dashboard management OAuth flow
+```
+
+Dashboard parity: `ccs config` -> Accounts -> Add Kiro account -> choose `Auth Method`.
+
 ### Cursor IDE Quick Start
 
 ```bash
diff --git a/docs/system-architecture.md b/docs/system-architecture.md
index 10b55a2a..96726327 100644
--- a/docs/system-architecture.md
+++ b/docs/system-architecture.md
@@ -86,7 +86,7 @@ CCS v7.34 adds Image Analysis Hook for vision model proxying through CLIProxy wi
         v
   1. CLIProxy Hardcoded ----+---> gemini, codex, agy, kiro, ghcp
      (OAuth-based)          |     Zero-config OAuth providers
-                            |     (kiro: Auth Code, ghcp: Device Code)
+                            |     (kiro: method-aware, ghcp: Device Code)
                             |
   2. CLIProxy Variants -----+---> config.cliproxy section
      (User-defined)         |     Custom provider configurations
@@ -570,10 +570,10 @@ CCS v7.34 adds Image Analysis Hook for vision model proxying through CLIProxy wi
 |                      Authentication Flow                                   |
 +===========================================================================+
 
-  OAuth Providers - Authorization Code Flow (Gemini, Codex, AGY, Kiro)
-  --------------------------------------------------------------------
+  OAuth Providers - Authorization Code Flow (Gemini, Codex, AGY)
+  --------------------------------------------------------------
 
-  1. User runs: ccs gemini (or ccs kiro)
+  1. User runs: ccs gemini
         |
         v
   2. Check token cache (~/.ccs/cliproxy/auth/)
@@ -584,7 +584,6 @@ CCS v7.34 adds Image Analysis Hook for vision model proxying through CLIProxy wi
                     |
                     v
   3. Open browser for OAuth (localhost:PORT callback)
-        |         - Kiro uses port 9876
         v
   4. Callback with auth code
         |
@@ -595,6 +594,21 @@ CCS v7.34 adds Image Analysis Hook for vision model proxying through CLIProxy wi
   6. Cache token locally
 
 
+  Kiro OAuth - Method-Aware Flow (CLI + Dashboard parity)
+  -------------------------------------------------------
+
+  Supported methods:
+    - aws: Device Code (default, AWS org friendly)
+    - aws-authcode: Authorization Code via CLI flow
+    - google: Social OAuth via management API
+    - github: Social OAuth via management API (Dashboard flow)
+
+  Key behavior:
+    - Device Code method uses /start route (no callback port)
+    - Callback/social methods use /start-url + status polling
+    - Some management flows return state first, auth_url later
+
+
   OAuth Providers - Device Code Flow (GitHub Copilot/ghcp)
   --------------------------------------------------------