diff --git a/docs/image-analysis.md b/docs/image-analysis.md index 27217400..0e5b525d 100644 --- a/docs/image-analysis.md +++ b/docs/image-analysis.md @@ -8,7 +8,7 @@ Native Claude accounts keep Anthropic's own vision flow. 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. -If the managed runtime, auth, or proxy path is unavailable, CCS falls back to native `Read` instead of failing the whole launch. The old `Read` hook remains only as a compatibility fallback when it can be installed safely. +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 @@ -29,7 +29,8 @@ Important: |--------------|--------------| | Claude `default` / `account` | Native Claude vision / native `Read` | | Third-party settings / CLIProxy / Copilot | CCS local `ImageAnalysis` MCP tool when ready | -| Third-party when runtime unavailable | Native `Read` fallback | +| 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 @@ -79,18 +80,28 @@ 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 diff --git a/docs/project-overview-pdr.md b/docs/project-overview-pdr.md index 6563c273..d11bec1d 100644 --- a/docs/project-overview-pdr.md +++ b/docs/project-overview-pdr.md @@ -1,6 +1,6 @@ # CCS Product Development Requirements (PDR) -Last Updated: 2026-04-07 +Last Updated: 2026-04-08 ## Product Overview @@ -105,8 +105,10 @@ CCS provides: - Expose a CCS-managed local `ImageAnalysis` MCP tool for third-party profiles that need provider-backed vision - Resolve the provider route before launch and send requests directly to `/api/provider//v1/messages` - Use editable prompt templates for `default`, `screenshot`, and `document` analysis modes -- Keep the old `Read` hook as compatibility fallback only, not the primary user experience -- Fall back to native `Read` without failing the whole launch when the managed runtime is unavailable +- Suppress the old CCS-managed `Read` hook during healthy MCP launches so it cannot compete with the primary path +- Keep the old `Read` hook as compatibility fallback only when MCP provisioning fails but provider-backed analysis is still viable +- Auto-heal stale CCS-managed image hooks and missing isolated MCP sync through launch-time cleanup, dashboard provisioning, and `ccs doctor --fix` +- Fall back to native `Read` without failing the whole launch when managed runtime, auth, or proxy readiness is unavailable ### FR-008: Remote CLIProxy Support - Connect to remote CLIProxyAPI instances diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md index 163f4cb9..bd498842 100644 --- a/docs/project-roadmap.md +++ b/docs/project-roadmap.md @@ -1,6 +1,6 @@ # CCS Project Roadmap -Last Updated: 2026-04-07 +Last Updated: 2026-04-08 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-04-08**: **#929** Image Analysis hardening now makes the managed `ccs-image-analysis` MCP path authoritative on healthy Claude-target launches, suppresses stale CCS-managed image `Read` hooks instead of letting them compete with MCP, keeps the legacy hook available only as compatibility fallback when MCP provisioning fails, and extends self-heal to dashboard provisioning plus `ccs doctor --fix` so stale hook files and missing isolated MCP sync are repaired automatically. - **2026-04-07**: CLIProxy routing strategy is now a first-class CCS surface. Users can inspect and explicitly change `round-robin` vs `fill-first` from `ccs cliproxy routing` and from a native `/cliproxy` dashboard card. Local mode now persists the chosen startup default into CCS-managed CLIProxy config generation, while untouched installs remain on `round-robin`. CCS deliberately does not infer strategy from account composition. - **2026-04-06**: The dashboard login surface now distinguishes a real sign-in from a host-setup requirement. Remote/IP visitors no longer see a misleading blank credential form when dashboard auth is disabled or incomplete; they now get explicit guidance that CCS has no default credentials, should be enabled on the host with `ccs config auth setup`, or should be reopened via localhost when used on the same machine. The password field now includes a show/hide toggle, and the page exposes an explicit light/dark theme switch before sign-in. - **2026-04-04**: The GitHub README was reduced from a wall-of-text reference dump into a shorter conversion surface that keeps the hero, proof screenshots, and fast-start commands while delegating deeper installation, provider, feature, and CLI-reference content to `docs.ccs.kaitran.ca`. The docs site now includes a dedicated `Product Tour` page for the screenshot-led walkthrough.