docs(readme): route user guides to canonical docs

2026-10-12 18:15:48 +00:00 · 2026-07-26 09:35:42 -04:00
1 parent fd45c51ed0
commit deb1ed0e67
@@ -94,7 +94,8 @@ The proxy also supports request-time `profile:model` selectors, scenario-based
 model routing through `proxy.routing`, and explicit activation helpers such as
 `ccs proxy activate --fish`.
-Guide: [OpenAI-Compatible Provider Routing](./docs/openai-compatible-providers.md)
+Guide:
 [OpenAI-Compatible Provider Routing](https://docs.ccs.kaitran.ca/features/proxy/openai-compatible-providers).
 ### Related Project: claude-code-router
@@ -166,7 +167,7 @@ CCS can provision first-class local tools like WebSearch and image analysis for
 third-party launches instead of leaving you to wire them by hand. Browser
 automation now has a first-class setup path as well. Deep dive:
 [WebSearch](https://docs.ccs.kaitran.ca/features/ai/websearch) |
-[Browser Automation](./docs/browser-automation.md).
+[Browser Automation](https://docs.ccs.kaitran.ca/features/workflow/browser-automation).
 ## Docs Matrix
@@ -183,7 +184,7 @@ reference material.
 | Compare OAuth providers, Claude accounts, and API profiles | [Provider Overview](https://docs.ccs.kaitran.ca/providers/concepts/overview) |
 | Learn the dashboard structure and feature pages | [Dashboard Overview](https://docs.ccs.kaitran.ca/features/dashboard/overview) |
 | Configure profiles, paths, and environment variables | [Configuration](https://docs.ccs.kaitran.ca/getting-started/configuration) |
-| Understand browser attach vs Codex browser tooling | [Browser Automation](./docs/browser-automation.md) |
+| Understand browser attach vs Codex browser tooling | [Browser Automation](https://docs.ccs.kaitran.ca/features/workflow/browser-automation) |
 | Keep OpenCode aligned with your live CCS setup | [OpenCode Sync Plugin](https://docs.ccs.kaitran.ca/features/workflow/opencode-sync) |
 | Browse every command and flag | [CLI Commands](https://docs.ccs.kaitran.ca/reference/cli-commands) |
 | Recover from install, auth, or provider failures | [Troubleshooting](https://docs.ccs.kaitran.ca/reference/troubleshooting) |
@@ -1,273 +1,61 @@
-# Browser Automation
+# Browser Automation Developer Contract
-Last Updated: 2026-05-11
+User setup and troubleshooting live in the canonical
 [Browser Automation guide](https://docs.ccs.kaitran.ca/features/workflow/browser-automation).
 This local file retains security-sensitive runtime invariants that contributors
 must preserve until the public guide covers them fully.
-CCS provides browser automation through two separate runtime paths:
+## Exposure And Runtime Ownership
- **Claude Browser Attach**: reuses a running Chrome/Chromium session through the CCS-managed local `ccs-browser` MCP runtime
+- Claude Browser Attach and Codex Browser Tools are separate lanes; they do not
- **Codex Browser Tools**: injects Playwright MCP tooling into Codex-target launches
+  promise a shared browser session.
 - New installs and upgrades without saved browser settings default both lanes
  to `enabled: false` and `policy: manual`.
 - `--browser` and `--no-browser` are one-run exposure overrides. They do not
  change saved policy.
 - CCS owns `mcpServers.ccs-browser`, the
  `~/.ccs/mcp/ccs-browser-server.cjs` runtime, and Codex `ccs_browser`
  overrides. Generic MCP editors are not the primary setup surface.
-These are related, but they are not the same implementation and they do not promise a shared browser session.
+## Attach Override Precedence
 On new installs, and on upgrades that do not already have explicit browser settings, both lanes
 start **disabled** and **manual** so browser tooling is not auto-exposed until you opt in.
 ## How Browser Automation Works
 ### Claude Browser Attach
 Claude-target CCS launches can provision a managed local MCP server named `ccs-browser`.
 That path is designed for workflows where you want Claude to interact with a browser session
 that already has useful authenticated state.
 Claude Browser Attach requires a browser launched in attach mode with remote debugging
 enabled. A recent Chrome update alone is not sufficient.
 ### Codex Browser Tools
 Codex-target CCS launches use a separate managed path: CCS injects Playwright MCP overrides
 for the `ccs_browser` runtime config entry.
 This is configured from the same Browser settings surface, but it is distinct from Claude
 Browser Attach.
 ## Configuration
 ### Via Dashboard
 Open `ccs config` -> `Settings` -> `Browser`.
 The Browser screen exposes two sections:
 - **Claude Browser Attach**
  - enable/disable the Claude attach lane
  - choose the Chrome user-data directory
  - set the expected DevTools port
  - review readiness and next-step guidance
  - copy a generated browser launch command
 - **Codex Browser Tools**
  - enable/disable CCS-managed browser tooling for Codex-target launches
  - review whether the detected Codex build supports managed browser overrides
 Browser policy controls are CLI-first in this release. The dashboard remains the shared setup and
 status surface, while `ccs browser policy` is the authoritative place to decide whether browser
 tooling is auto-exposed or kept manual by default. Fresh installs, plus upgrades without an
 existing browser section, surface both lanes as off/manual until you explicitly enable them.
 ### Via CLI
 ```bash
 ccs help browser
 ccs browser setup
 ccs browser status
 ccs browser doctor
 ccs browser policy
 ccs browser policy --all manual
 ```
 Use `ccs browser setup` for the primary one-command setup path. Use `ccs browser status` for
 the current state, `ccs browser doctor` for read-only troubleshooting guidance, and
 `ccs browser policy` to control default browser exposure. If you only want browser access for one
 run, keep policy manual and add `--browser` to that launch.
 ### Via Config File
 Edit `~/.ccs/config.yaml`:
 ```yaml
 browser:
  claude:
    enabled: false
    policy: manual
    user_data_dir: "~/.ccs/browser/chrome-user-data"
    devtools_port: 9222
  codex:
    enabled: false
    policy: manual
 ```
 Notes:
 - `claude.policy` and `codex.policy` accept `auto` or `manual`
 - `claude.user_data_dir` is a **Chrome user-data directory**, not a display-name browser profile
 - `claude.devtools_port` is the expected remote debugging port for attach mode
 - `codex.enabled` controls whether CCS injects browser tooling into Codex-target launches
 - New installs, plus upgrades without saved browser settings, default both lanes to `enabled: false` and `policy: manual`
 - `manual` keeps the lane configured but hidden until a launch explicitly opts in with `--browser`
 ## Runtime Policy Controls
 CCS now separates **lane enablement** from **default exposure policy**:
 - `enabled: false`
  - the lane is off; this is the default for both lanes on new installs and upgrades without saved browser settings
 - `enabled: true` + `policy: auto`
  - the lane is exposed automatically on matching launches
 - `enabled: true` + `policy: manual`
  - the lane stays configured, but CCS keeps browser tooling hidden unless the current launch uses
    `--browser`
 One-run launch overrides:
 ```bash
 ccs browser policy --all manual
 ccs glm --browser "inspect the page"
 ccs glm --no-browser "summarize the docs"
 ccs default --target codex --browser "use the browser tools for this run"
 ```
 - `--browser` forces browser tooling on for the current launch when that lane is enabled
 - `--no-browser` suppresses browser tooling for the current launch even when policy is `auto`
 ## Environment Variable Overrides
 CCS still supports environment-variable overrides for backward compatibility.
 | Variable | Description |
 |----------|-------------|
 | `CCS_BROWSER_USER_DATA_DIR` | Preferred override for Claude Browser Attach user-data dir |
 | `CCS_BROWSER_PROFILE_DIR` | Legacy alias for the same attach directory |
 | `CCS_BROWSER_DEVTOOLS_PORT` | Explicit DevTools port override |
 | `CCS_BROWSER_INTERCEPT_FULFILL_MODE=enabled` | Dangerous local-testing opt-in for Browser MCP response fulfillment; disabled by default |
 | `CCS_BROWSER_UPLOAD_ROOTS` | Optional `path.delimiter`-separated allowlist for local files that browser upload tools may read |
 | `CCS_BROWSER_DOWNLOAD_ROOTS` | Optional `path.delimiter`-separated allowlist for caller-provided browser download directories |
 If an override is active, Browser status surfaces should report that the current session is being
 managed externally by environment variables.
 Browser MCP request interception can continue or fail matched requests by default. Synthetic response
 fulfillment (`action: fulfill`) is more sensitive because it can serve caller-supplied response
 content inside the attached browser's target origin. CCS therefore hides and blocks fulfillment unless
 `CCS_BROWSER_INTERCEPT_FULFILL_MODE=enabled` is set for a trusted local test session.
 The saved browser policy still controls default exposure. Env overrides change the effective attach
 path/port for the current shell; they do not bypass `policy: manual`.
 Override precedence is:
 1. `CCS_BROWSER_USER_DATA_DIR`
-2. `CCS_BROWSER_PROFILE_DIR`
+2. legacy `CCS_BROWSER_PROFILE_DIR`
-3. the persisted `browser.claude.user_data_dir` config value
+3. persisted `browser.claude.user_data_dir`
-Config-backed Browser Attach always passes an explicit DevTools port to the runtime, even when the
+Config-backed attach always passes an explicit DevTools port, including the
-effective value is the default `9222`. Metadata-based port discovery is preserved only for the
+default `9222`. Metadata-based port discovery exists only for the legacy
-legacy `CCS_BROWSER_PROFILE_DIR` flow when `CCS_BROWSER_DEVTOOLS_PORT` is not set.
+profile-dir override when `CCS_BROWSER_DEVTOOLS_PORT` is unset.
-### Browser File Transfer Safety
+## Interception Safety
-Claude Browser Attach file-transfer tools intentionally use a deny-by-default filesystem boundary:
+Request interception may continue or fail matched requests by default.
 Synthetic fulfillment can serve caller-supplied content inside the target
 origin, so it must stay hidden and blocked unless
 `CCS_BROWSER_INTERCEPT_FULFILL_MODE=enabled` is explicitly set for a trusted
 local test.
- Downloads without an explicit `downloadPath` go to a CCS-created temporary session directory.
+## Event Observation Safety
 - A caller-provided `downloadPath` must be inside that temporary session directory or inside one of
  the directories listed in `CCS_BROWSER_DOWNLOAD_ROOTS`.
 - Local upload and drag-and-drop files must be inside the temporary session download directory or
  inside one of the directories listed in `CCS_BROWSER_UPLOAD_ROOTS`.
 - Hidden path segments and common secret locations/files, such as `.ssh`, `.aws`, `.ccs`,
  `.claude`, `.env`, and private-key filenames, are rejected even inside an allowed root.
 - Each file-transfer call is limited to 10 files, and each local file must be at most 10 MiB.
-Set upload/download roots only to purpose-built scratch directories. Do not point these variables at
+- `browser_wait_for_event` requires `urlIncludes` for network-request events.
-your home directory, a source checkout with secrets, or a real cloud/tooling config directory.
+- Download events require either `urlIncludes` or
  `suggestedFilenameIncludes`.
 - Returned navigation, request, and download URLs must redact query strings,
  fragments, and path-scoped bearer values before reaching the MCP caller.
-## Managed Runtime Files
+## File Transfer Safety
- `~/.claude.json` -> CCS manages `mcpServers.ccs-browser` for Claude Browser Attach
+Browser file transfer is deny-by-default:
 - `~/.ccs/mcp/ccs-browser-server.cjs` -> local Claude Browser Attach MCP runtime
 - `Codex runtime config overrides` -> CCS manages the `ccs_browser` MCP entry for Codex-target launches
-Do not treat the generic Codex MCP editor as the primary browser setup path. CCS-managed browser
+- implicit downloads use a CCS-created temporary session directory;
-entries should be configured from `Settings -> Browser`.
+- explicit download paths must remain inside that session directory or a
  `CCS_BROWSER_DOWNLOAD_ROOTS` allowlisted root;
 - uploads and drag-and-drop files must remain inside the session directory or a
  `CCS_BROWSER_UPLOAD_ROOTS` allowlisted root;
 - hidden segments and common secret locations/files (`.ssh`, `.aws`, `.ccs`,
  `.claude`, `.env`, private keys) remain denied inside allowed roots;
 - each call permits at most 10 files, each no larger than 10 MiB.
-## Primary Setup Flow
+Allowlist only purpose-built scratch directories. Never allowlist a home
-
+directory, source checkout containing secrets, or real tooling configuration
-The shortest supported setup path is:
+directory.
 ```bash
 ccs browser setup
 ```
 That flow:
 1. enables Claude Browser Attach in the saved CCS browser config
 2. leaves launch exposure under the saved policy, so `policy: manual` still requires `--browser`
 3. keeps the configured DevTools port normalized
 4. creates the configured browser user-data directory if needed
 5. prints the exact browser launch command for the current platform
 6. re-checks readiness and reports the next step if Chrome still needs manual attention
 ## Launching Chrome For Claude Attach
 Claude Browser Attach needs a browser launched with remote debugging.
 Typical examples:
 ```bash
 # macOS
 open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir="$HOME/.ccs/browser/chrome-user-data"
 # Linux
 google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.ccs/browser/chrome-user-data"
 # Windows
 chrome.exe --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\\.ccs\\browser\\chrome-user-data"
 ```
 Using a dedicated CCS browser data dir is recommended. It avoids profile-locking issues and keeps
 automation state separate from your daily browser profile.
 When Claude Browser Attach uses the recommended managed path (`~/.ccs/browser/chrome-user-data`),
 CCS now creates that directory automatically the first time it needs it. After that bootstrap step,
 the remaining requirement is a running Chrome session started with `--remote-debugging-port`.
 ## Troubleshooting
 ### Browser status says Claude Browser Attach is disabled
 Run `ccs browser setup`, enable Claude Browser Attach in `Settings -> Browser`, or edit the
 browser config block in `~/.ccs/config.yaml`.
 ### Browser status says the path is missing
 The configured Chrome user-data directory does not exist yet.
 1. Run `ccs browser setup`
 2. If Chrome still is not ready, use the generated launch command
 3. Rerun `ccs browser doctor`
 If you are using the CCS-managed default path, this usually means the path could not be created
 automatically and now needs manual attention.
 ### Browser status says no running browser session was found
 CCS could not find usable DevTools attach metadata for the configured user-data directory.
 1. Run `ccs browser setup`
 2. If needed, make sure Chrome was started with `--remote-debugging-port=<port>`
 3. Make sure it is using the same `user_data_dir` configured in CCS
 4. Rerun `ccs browser doctor`
 For the CCS-managed default path, this is the normal first-run state after CCS bootstraps the
 directory for you.
 ### Browser status says the DevTools endpoint is unreachable
 CCS found attach metadata, but the endpoint did not answer successfully.
 1. Run `ccs browser setup`
 2. If needed, restart the attach browser session
 3. Confirm the expected port matches the real remote debugging port
 4. Rerun `ccs browser status`
 ### Codex Browser Tools are unavailable
 Codex browser tooling depends on a Codex build that supports `--config` overrides.
 If CCS reports `unsupported_build`, upgrade Codex and rerun `ccs browser status`.
 ## Security Notes
 - Browser automation may operate inside authenticated browser sessions
 - Prefer a dedicated automation user-data dir instead of your everyday browser profile
 - Do not commit browser paths, secrets, or generated session state to version control
 - Treat `~/.ccs/config.yaml`, `~/.claude.json`, and the browser user-data directory as local machine state
 - `browser_wait_for_event` requires explicit scoping for network request events (`urlIncludes`) and download events (`urlIncludes` or `suggestedFilenameIncludes`)
 - Event details redact observed navigation, request, and download URLs before returning them to the MCP caller so observed browser metadata does not expose query strings, fragments, or path-scoped bearer values
@@ -1,119 +1,8 @@
-# Image Analysis Configuration Guide
+# Image Analysis
-CCS provides first-class image and PDF analysis for third-party Claude launches that do not have reliable native vision support.
+User setup, routing behavior, and troubleshooting live in the canonical
 [Image Analysis guide](https://docs.ccs.kaitran.ca/features/ai/image-analysis).
-## How Image Analysis Works
+Contributor implementation contracts are enforced by the source and focused
-
+tests under `src/utils/image-analysis/`, `src/utils/hooks/`, and
-Native Claude accounts keep Anthropic's own vision flow.
+`src/web-server/routes/`.
 Third-party profiles now use a CCS-managed local MCP tool named `ImageAnalysis` when the runtime is available. CCS also appends a short steering hint so Claude prefers that tool over `Read` for local image and PDF files.
 Healthy Claude-target launches suppress the legacy CCS `Read` hook so MCP stays authoritative. If the managed runtime cannot be provisioned, CCS keeps the old `Read` hook available only as a compatibility fallback when that path is still viable. If runtime/auth/proxy readiness is degraded beyond that, CCS falls back to native `Read` instead of failing the whole launch.
 ## Routing Model
 ImageAnalysis requests go straight to the CCS-managed provider route:
 ```text
 Claude -> ccs-image-analysis MCP -> CCS provider route -> /api/provider/<backend>/v1/messages
 ```
 Important:
 - CCS does not relay image analysis through Claude Code, another CLI, or a second model wrapper.
 - For bridge-backed settings profiles, CCS resolves the backend and provider path before launch.
 - CCS avoids leaking a profile's ordinary third-party `ANTHROPIC_BASE_URL` or token into image analysis unless that profile is explicitly using a CLIProxy bridge.
 ## Profile Behavior
 | Profile Type | Image Method |
 |--------------|--------------|
 | Claude `default` / `account` | Native Claude vision / native `Read` |
 | Third-party settings / CLIProxy / Copilot | CCS local `ImageAnalysis` MCP tool when ready |
 | Third-party when MCP provisioning fails but provider-backed analysis is still viable | Legacy CCS `Read` hook fallback |
 | Third-party when runtime/auth/proxy is unavailable | Native `Read` fallback |
 ## Configuration
 Configure via dashboard (`Settings -> Image`) or `~/.ccs/config.yaml`:
 ```yaml
 image_analysis:
  enabled: true
  timeout: 60
  fallback_backend: agy
  provider_models:
    agy: gemini-3-1-flash-preview
    codex: gpt-5.1-codex-mini
    ghcp: claude-haiku-4.5
 ```
 Useful commands:
 ```bash
 ccs config image-analysis
 ccs config image-analysis --enable
 ccs config image-analysis --disable
 ccs config image-analysis --set-fallback agy
 ccs config image-analysis --set-profile-backend glm agy
 ccs config image-analysis --clear-profile-backend glm
 ```
 ## Prompt Templates
 CCS installs editable prompt templates at:
 ```text
 ~/.ccs/prompts/image-analysis/
 ```
 Templates:
 - `default.txt`
 - `screenshot.txt`
 - `document.txt`
 CCS automatically selects `screenshot` for screenshot-like filenames, `document` for PDFs, and `default` otherwise.
 ## Runtime Environment
 Key runtime env vars:
 | Variable | Purpose |
 |----------|---------|
 | `CCS_IMAGE_ANALYSIS_SKIP` | Disable image analysis for the current launch |
 | `CCS_IMAGE_ANALYSIS_SKIP_HOOK` | Suppress only the legacy CCS `Read` hook while keeping MCP ImageAnalysis available |
 | `CCS_IMAGE_ANALYSIS_RUNTIME_BASE_URL` | Explicit CCS runtime base URL |
 | `CCS_IMAGE_ANALYSIS_RUNTIME_PATH` | Provider route such as `/api/provider/agy` |
 | `CCS_IMAGE_ANALYSIS_RUNTIME_API_KEY` | Explicit CCS runtime auth key |
 | `CCS_IMAGE_ANALYSIS_MODEL` | Force a single image-analysis model |
 | `CCS_DEBUG` | Verbose runtime logging |
 ## Self-Heal
 CCS now auto-heals stale managed image-analysis state in three places:
 - Healthy Claude launches remove stale CCS-managed image `Read` hooks from the active profile settings before launch.
 - `Settings -> Image` save/provisioning repairs managed MCP runtime files, syncs managed MCP entries into isolated Claude config dirs, and cleans stale CCS-managed image hooks from `~/.ccs/*.settings.json`.
 - `ccs doctor --fix` repairs invalid image-analysis config, removes stale CCS-managed image hooks, and resyncs managed `ccs-image-analysis` MCP entries into isolated configs.
 ## Troubleshooting
 ### Claude still uses `Read`
 - Confirm `ccs config image-analysis` shows `enabled: true`
 - Check the active profile resolves to a configured backend
 - Run `ccs doctor --fix` to repair stale managed hooks or missing managed MCP sync
 - Run with `CCS_DEBUG=1` to see runtime preparation details
 ### ImageAnalysis is not exposed
 - Verify CLIProxy auth for the resolved backend
 - Verify the local or remote CLIProxy target is reachable
 - Check `~/.claude.json` and inherited account configs for `ccs-image-analysis`
 ### I need to prove requests are going directly to the provider route
 Run with `CCS_DEBUG=1` and inspect the resolved runtime path. The request target should be provider-scoped, for example:
 ```text
 /api/provider/agy/v1/messages
 ```