docs(channels): document official Claude channel support

docs/codebase-summary.md

@@ -1,8 +1,8 @@
 # CCS Codebase Summary
 
-Last Updated: 2026-03-18
+Last Updated: 2026-03-24
 
-Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, v7.14 Hybrid Quota Management, v7.34 Image Analysis Hook, and account-context validation hardening.
+Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, v7.14 Hybrid Quota Management, v7.34 Image Analysis Hook, account-context validation hardening, and Official Claude Channels runtime support.
 
 ## Repository Structure
 
@@ -84,6 +84,10 @@ src/
 │   ├── unified-config-loader.ts  # Central config loader (546 lines)
 │   └── migration-manager.ts  # Config migration logic
 │
+├── channels/                 # Official Claude channel integration
+│   ├── official-channels-runtime.ts  # Runtime gating, plugin specs, setup guidance
+│   └── official-channels-store.ts    # Claude channel token/env storage helpers
+│
 ├── cliproxy/                 # CLIProxyAPI integration (heavily modularized)
 │   ├── index.ts              # Barrel export (137 lines, extensive)
 │   ├── auth/                 # OAuth handlers, token management
@@ -174,6 +178,7 @@ src/
     │   ├── index.ts
     │   ├── accounts-route.ts
     │   ├── auth-route.ts
+    │   ├── channels-routes.ts
     │   ├── cliproxy-route.ts
     │   ├── copilot-route.ts
     │   ├── doctor-route.ts
@@ -229,6 +234,15 @@ src/
 - `plugins/marketplaces/`, `plugins/cache/`, and `installed_plugins.json` stay shared through the `~/.ccs/shared/` topology.
 - `known_marketplaces.json` is now instance-local under `~/.ccs/instances/<profile>/plugins/` so Claude Code validates `installLocation` against the active `CLAUDE_CONFIG_DIR` instead of a last-writer-wins shared file.
 
+### Official Claude Channels
+
+- Runtime contract lives in `src/channels/official-channels-runtime.ts` and is consumed from `src/ccs.ts`, `src/commands/config-channels-command.ts`, and `src/web-server/routes/channels-routes.ts`.
+- Canonical config lives under `channels.*` in `~/.ccs/config.yaml`; legacy `discord_channels.*` remains read-compatible only when canonical fields are absent.
+- Telegram and Discord bot tokens are intentionally written into Claude-managed machine state under `~/.claude/channels/<channel>/.env`, unless the official `*_STATE_DIR` environment override redirects that channel elsewhere.
+- iMessage is tokenless, macOS-only, and still depends on Claude-side plugin install plus OS permissions.
+- Auto-enable is gated on Bun availability, verified Claude Code v2.1.80+, verified `claude.ai` auth, native Claude `default/account` sessions, and per-channel setup readiness.
+- The dashboard channels section surfaces Bun/version/auth/state-scope status from `/api/channels`, preserves token drafts when save-follow-up refresh fails, and keeps unsupported selected iMessage visible only so it can be turned off.
+
 ### Target Adapter Module
 
 The targets module provides an extensible interface for dispatching profiles to different CLI implementations.
@@ -420,6 +434,7 @@ ui/src/
 │   │   ├── hooks/
 │   │   │   ├── index.ts
 │   │   │   ├── context-hooks.ts
+│   │   │   ├── use-official-channels-config.ts
 │   │   │   ├── use-settings-tab.ts
 │   │   │   ├── use-proxy-config.ts
 │   │   │   ├── use-websearch-config.ts
@@ -429,6 +444,7 @@ ui/src/
 │   │   │   ├── section-skeleton.tsx
 │   │   │   └── tab-navigation.tsx
 │   │   └── sections/
+│   │       ├── channels.tsx
 │   │       ├── globalenv-section.tsx
 │   │       ├── websearch/
 │   │       │   ├── index.tsx

docs/project-overview-pdr.md

@@ -1,6 +1,6 @@
 # CCS Product Development Requirements (PDR)
 
-Last Updated: 2026-03-19
+Last Updated: 2026-03-24
 
 ## Product Overview
 
@@ -8,7 +8,7 @@ Last Updated: 2026-03-19
 
 **Tagline**: The universal AI profile manager for Claude Code
 
-**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter, Qwen, Kimi, DeepSeek) with a React-based dashboard for configuration management. Supports both local and remote CLIProxyAPI instances with hybrid quota management.
+**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter, Qwen, Kimi, DeepSeek) with a React-based dashboard for configuration management. Supports both local and remote CLIProxyAPI instances, hybrid quota management, and official Claude channel runtime setup for Telegram, Discord, and iMessage.
 
 **Current Version**: v7.34.x (Image Analysis Hook + Performance Improvements)
 
@@ -37,6 +37,7 @@ CCS provides:
 5. **Visual Dashboard**: React SPA for configuration management
 6. **Automatic WebSearch**: Real backend fallback chain for third-party providers
 7. **Usage Analytics**: Token tracking, cost analysis, model breakdown
+8. **Official Claude Channels**: Runtime auto-enable plus dashboard token/config flow for Telegram, Discord, and macOS-only iMessage
 
 ---
 
@@ -129,6 +130,16 @@ CCS provides:
 - Security: single-quoted output, key sanitization, shell-specific escaping
 - Cross-platform compatibility (macOS, Linux, Windows)
 
+### FR-012: Official Claude Channels
+- Support Telegram, Discord, and iMessage selection via `ccs config channels` and the dashboard
+- Auto-inject `--channels` only for native Claude `default` and `account` sessions
+- Store Telegram/Discord bot tokens in Claude's own `~/.claude/channels/<channel>/.env` state or the official `*_STATE_DIR` override path when one is configured
+- Treat iMessage as macOS-only, tokenless, and dependent on Claude-side install plus OS permissions
+- Require Bun, Claude Code v2.1.80+, and verified `claude.ai` auth before runtime auto-enable
+- Keep `--dangerously-skip-permissions` optional and never add it when the user already made an explicit permission choice
+- Surface platform/auth/version/setup blockers clearly in both CLI and dashboard flows
+- Preserve dashboard token drafts when save/refresh fails, and let already-selected unsupported iMessage entries be turned off without allowing re-enable on unsupported platforms
+
 ---
 
 ## Non-Functional Requirements
@@ -172,11 +183,13 @@ CCS provides:
 - CLIProxyAPI binary (auto-managed)
 - Exa/Tavily/Brave API keys for higher-quality WebSearch
 - Gemini CLI for legacy WebSearch fallback
+- Bun plus Claude Code v2.1.80+ with `claude.ai` auth for Official Channels auto-enable
 
 ### TR-003: Configuration
 - YAML-based config (`~/.ccs/config.yaml`)
 - JSON settings per profile
 - Environment variable overrides
+- Official channel bot tokens stored in Claude-managed `~/.claude/channels/<channel>/.env`
 
 ---
 

docs/project-roadmap.md

@@ -1,6 +1,6 @@
 # CCS Project Roadmap
 
-Last Updated: 2026-03-23
+Last Updated: 2026-03-24
 
 Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans.
 
@@ -41,6 +41,7 @@ All major modularization work is complete. The codebase evolved from monolithic
 
 ### Recent Fixes
 
+- **2026-03-24**: Official Claude Channels now follow Anthropic's actual runtime contract. CCS blocks auto-enable unless Bun is available, Claude Code is verified at v2.1.80+, and `claude.ai` auth is verified; treats `--allow-dangerously-skip-permissions` as an explicit override; keeps Telegram/Discord bot tokens in Claude's shared `~/.claude/channels/` state (or official `*_STATE_DIR` overrides); and upgrades the dashboard/CLI status flow with Bun/version/auth/state-scope guidance, safer token draft retention on refresh failures, and a non-macOS iMessage toggle that can still be turned off when already selected.
 - **2026-03-23**: CLIProxy providers that do not expose an email no longer require a user-supplied nickname on first auth. CCS now derives a stable internal account identifier for Kiro/Copilot-style flows, preserves later rename support, hardens account discovery/registry sync around that identifier, and updates AI Provider CRUD to use stable entry IDs instead of dashboard list indexes.
 - **2026-03-23**: Sensitive dashboard management routes now fail closed to localhost-only access whenever dashboard auth is disabled. Remote access remains available after `ccs config auth setup`, but AI Provider management, CLIProxy auth/status helpers, and other write-capable settings endpoints no longer trust unauthenticated non-loopback requests.
 - **2026-03-19**: **#649** CCS splits CLIProxy provider-key authoring into a dedicated `CLIProxy -> AI Providers` dashboard route. `/cliproxy` now stays focused on OAuth accounts and variants, `/cliproxy/ai-providers` owns Gemini/Codex/Claude/Vertex/OpenAI-compatible key management, and `/providers` stays reserved for CCS-native API Profiles.