From f462b9fed107e506488356dc7384fa22485e40cf Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Fri, 27 Mar 2026 11:07:01 -0400 Subject: [PATCH] docs(websearch): document inline provider key flow - update the WebSearch guide for dashboard-managed Exa, Tavily, and Brave keys - record the dashboard readiness and secret-management change in the project roadmap --- docs/project-roadmap.md | 3 ++- docs/websearch.md | 14 +++++++++----- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md index 47e4433a..80526d0c 100644 --- a/docs/project-roadmap.md +++ b/docs/project-roadmap.md @@ -1,6 +1,6 @@ # CCS Project Roadmap -Last Updated: 2026-03-24 +Last Updated: 2026-03-27 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-27**: WebSearch dashboard cards now manage Exa, Tavily, and Brave API keys inline instead of relying on a separate manual env step. CCS stores those secrets through `global_env`, reflects masked key state in `/api/websearch`, and counts dashboard-managed keys as ready in the WebSearch status flow. - **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. diff --git a/docs/websearch.md b/docs/websearch.md index 6a6803c9..914200b1 100644 --- a/docs/websearch.md +++ b/docs/websearch.md @@ -1,6 +1,6 @@ # WebSearch Configuration Guide -Last Updated: 2026-03-23 +Last Updated: 2026-03-27 CCS provides automatic web search for third-party profiles that cannot access Anthropic's native WebSearch API. @@ -64,7 +64,8 @@ The new flow matches the `goclaw` model more closely: web search is treated as a Open `ccs config` → `Settings` → `WebSearch`. - Enable Exa, Tavily, Brave, or DuckDuckGo in the backend chain -- Export the matching API key first for Exa, Tavily, or Brave +- Set or rotate Exa, Tavily, and Brave API keys directly inside each provider card +- Saved keys are persisted in `global_env` and injected at runtime, so readiness updates from the same screen - Review whether any legacy fallback CLIs are still enabled in config ### Via Config File @@ -119,7 +120,7 @@ That is expected. DuckDuckGo is the default zero-setup backend. ### Exa, Tavily, or Brave is enabled but not ready -Export the matching API key in the environment that launches CCS, then refresh status: +Set the matching API key in the WebSearch dashboard card, or export it in the environment that launches CCS, then refresh status: ```bash export EXA_API_KEY="your-api-key" @@ -128,6 +129,8 @@ export EXA_API_KEY="your-api-key" ccs config ``` +If the dashboard says the key is stored but still not ready, check whether `Settings -> Global Env` is disabled. WebSearch reuses that injection path for dashboard-managed keys. + ### I still want Gemini/OpenCode/Grok fallback Those providers remain supported, but they are no longer the primary path. Enable them explicitly in `config.yaml` if you want them as last-resort fallback. @@ -141,6 +144,7 @@ Those providers remain supported, but they are no longer the primary path. Enabl ## Security Considerations -- API keys stay in environment variables, not in dashboard state +- API keys entered from the dashboard are stored in `~/.ccs/config.yaml` under `global_env` and injected as environment variables at runtime +- Shell-exported keys still work and are detected as external environment input - Never commit API keys to version control -- Use shell profile or `.env` tooling with proper permissions +- Use the dashboard only on trusted machines, and protect `~/.ccs/config.yaml` with normal user-level filesystem permissions