docs(help): add kiro idc flag guidance

- add a dedicated 'ccs help kiro' topic with IDC and paste-callback examples

- link the providers help topic to the new Kiro-specific help surface

src/commands/command-catalog.ts

@@ -2,7 +2,7 @@ import { COPILOT_SUBCOMMANDS } from '../copilot/constants';
 import { CURSOR_SUBCOMMANDS } from '../cursor/constants';
 import { CLIPROXY_PROVIDER_IDS } from '../cliproxy/provider-capabilities';
 
-export type HelpTopicName = 'profiles' | 'providers' | 'completion' | 'targets';
+export type HelpTopicName = 'profiles' | 'providers' | 'kiro' | 'completion' | 'targets';
 
 export interface HelpTopicEntry {
   name: HelpTopicName;
@@ -25,6 +25,7 @@ export interface ShortcutEntry {
 export const ROOT_HELP_TOPICS: readonly HelpTopicEntry[] = [
   { name: 'profiles', summary: 'Account profiles, API profiles, and CLIProxy variants' },
   { name: 'providers', summary: 'Built-in OAuth providers and runtime shortcuts' },
+  { name: 'kiro', summary: 'Kiro auth methods, IDC flags, and callback guidance' },
   { name: 'completion', summary: 'Shell completion install, refresh, and testing' },
   { name: 'targets', summary: 'Claude, Droid, and Codex target routing' },
 ] as const;

src/commands/help-command.ts

@@ -78,6 +78,7 @@ async function showProvidersHelp(writeLine: HelpWriter): Promise<void> {
       },
       { name: 'ccs api create --preset <id>', summary: 'Create an API-backed provider profile' },
       { name: 'ccs config', summary: 'Use the dashboard for provider and model setup' },
+      { name: 'ccs help kiro', summary: 'Kiro-specific auth methods and IDC flags' },
     ],
     writeLine
   );
@@ -85,6 +86,74 @@ async function showProvidersHelp(writeLine: HelpWriter): Promise<void> {
   writeLine('');
 }
 
+async function showKiroHelp(writeLine: HelpWriter): Promise<void> {
+  await initUI();
+  writeLine(header('CCS Kiro Help'));
+  writeLine('');
+  writeLine('  Kiro supports Builder ID, IDC, and management-only social OAuth flows.');
+  writeLine('');
+  writeCommandTable(
+    'Authentication Methods',
+    [
+      { name: 'ccs kiro --auth', summary: 'Default AWS Builder ID device-code flow' },
+      {
+        name: 'ccs kiro --auth --kiro-auth-method aws-authcode',
+        summary: 'AWS Builder ID auth-code flow via local callback server',
+      },
+      {
+        name: 'ccs kiro --auth --kiro-auth-method idc',
+        summary: 'IAM Identity Center flow; requires IDC start URL',
+      },
+      {
+        name: 'ccs config',
+        summary: 'Dashboard flow for GitHub OAuth and account management',
+      },
+    ],
+    writeLine
+  );
+  writeCommandTable(
+    'Kiro Flags',
+    [
+      {
+        name: '--kiro-auth-method <aws|aws-authcode|google|github|idc>',
+        summary: 'Select the Kiro auth method',
+      },
+      { name: '--kiro-idc-start-url <url>', summary: 'Required IDC start URL when using `idc`' },
+      { name: '--kiro-idc-region <region>', summary: 'Optional IDC region override' },
+      { name: '--kiro-idc-flow <authcode|device>', summary: 'IDC flow type; defaults to authcode' },
+      {
+        name: '--paste-callback',
+        summary: 'Paste the final callback URL for callback-based CLI auth flows',
+      },
+      { name: '--import', summary: 'Import an existing Kiro IDE token instead of starting OAuth' },
+    ],
+    writeLine
+  );
+  writeCommandTable(
+    'Examples',
+    [
+      { name: 'ccs kiro --auth', summary: 'Start the default Builder ID device flow' },
+      {
+        name: 'ccs kiro --auth --kiro-auth-method aws-authcode --paste-callback',
+        summary: 'Use auth-code flow and paste the callback URL manually',
+      },
+      {
+        name: 'ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start',
+        summary: 'Start IDC auth with the default authcode flow',
+      },
+      {
+        name: 'ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start --kiro-idc-flow device',
+        summary: 'Use IDC device-code flow instead of authcode',
+      },
+    ],
+    writeLine
+  );
+  writeLine(
+    `  ${dim('GitHub OAuth is dashboard-only: ccs config -> Accounts -> Add Kiro account')}`
+  );
+  writeLine('');
+}
+
 async function showTargetsHelp(writeLine: HelpWriter): Promise<void> {
   await initUI();
   writeLine(header('CCS Targets Help'));
@@ -176,6 +245,10 @@ export async function handleHelpRoute(
     await showProvidersHelp(writeLine);
     return;
   }
+  if (topic === 'kiro') {
+    await showKiroHelp(writeLine);
+    return;
+  }
   if (topic === 'targets') {
     await showTargetsHelp(writeLine);
     return;

tests/unit/commands/help-command-parity.test.ts

@@ -46,11 +46,23 @@ describe('help command parity', () => {
 
     expect(rendered.includes('Built-in OAuth Providers')).toBe(true);
     expect(rendered.includes('ccs cliproxy --help')).toBe(true);
+    expect(rendered.includes('ccs help kiro')).toBe(true);
     expect(rendered.includes('gemini')).toBe(true);
     expect(rendered.includes('codex')).toBe(true);
     expect(rendered.includes('ghcp')).toBe(true);
   });
 
+  test('kiro topic documents IDC and callback flags', async () => {
+    const rendered = await renderLines((writeLine) => handleHelpRoute(['kiro'], writeLine));
+
+    expect(rendered.includes('CCS Kiro Help')).toBe(true);
+    expect(rendered.includes('--kiro-idc-start-url <url>')).toBe(true);
+    expect(rendered.includes('--kiro-idc-region <region>')).toBe(true);
+    expect(rendered.includes('--kiro-idc-flow <authcode|device>')).toBe(true);
+    expect(rendered.includes('--paste-callback')).toBe(true);
+    expect(rendered.includes('GitHub OAuth is dashboard-only')).toBe(true);
+  });
+
   test('completion topic documents install and verification paths', async () => {
     const rendered = await renderLines((writeLine) => handleHelpRoute(['completion'], writeLine));