diff --git a/docs/cursor-integration.md b/docs/cursor-integration.md deleted file mode 100644 index b8cdd0c8..00000000 --- a/docs/cursor-integration.md +++ /dev/null @@ -1,165 +0,0 @@ -# Cursor IDE Integration - -This guide covers the deprecated CCS-owned Cursor IDE bridge, including auth import, local daemon lifecycle, live probe checks, and dashboard controls. - -`ccs cursor` now belongs to the CLIProxy-backed Cursor provider path. -Use `ccs legacy cursor` for the deprecated local bridge documented here. - -## What It Provides - -- OpenAI-compatible local endpoint powered by Cursor credentials. -- Anthropic-compatible local endpoint at `/v1/messages` for Claude-native clients. -- Cursor model list and chat completions via the local CCS daemon. -- Dedicated dashboard page: `ccs config` -> `Deprecated` -> `Cursor IDE (Legacy)`. - -## What This Runtime Actually Does - -`ccs legacy cursor` does not launch Cursor IDE itself. - -The current workflow is: -1. import Cursor credentials from local SQLite or manual input -2. run a local CCS daemon on `127.0.0.1:` -3. launch Claude Code against that daemon -4. have CCS translate requests to Cursor upstream - -Treat this as a CCS-managed Cursor bridge, not a generic CLIProxy-backed provider path. - -## Prerequisites - -- Cursor IDE installed and logged in. -- CCS installed and configured (`ccs config` works). -- For auto-detect auth on macOS/Linux: `sqlite3` available in PATH. - -## CLI Workflow - -### 1) Enable integration - -```bash -ccs legacy cursor enable -``` - -### 2) Import credentials - -Auto-detect from Cursor local SQLite state: - -```bash -ccs legacy cursor auth -``` - -Manual fallback: - -```bash -ccs legacy cursor auth --manual --token --machine-id -``` - -### 3) Start daemon - -```bash -ccs legacy cursor start -``` - -### 4) Run a live probe - -```bash -ccs legacy cursor probe -``` - -Use this to verify that the current build can complete one real authenticated request through the local daemon. - -### 5) Run Cursor-backed Claude - -```bash -ccs legacy cursor "explain this repo" -``` - -### 6) Verify status - -```bash -ccs legacy cursor status -``` - -Use `ccs legacy cursor` with bare or normal Claude args to run through the local Cursor proxy. -The admin namespace remains available for setup and inspection: - -```bash -ccs legacy cursor help -``` - -### 7) Stop daemon - -```bash -ccs legacy cursor stop -``` - -## Supported Cursor Provider Path - -For the supported CLIProxy-backed Cursor provider, use: - -```bash -ccs cursor --auth -ccs cursor --accounts -ccs cursor --config -ccs cursor "task" -``` - -## Runtime Defaults - -- Default port: `20129` -- `ghost_mode`: enabled -- `auto_start`: disabled -- Model list resolution: authenticated live fetch when available, with cached/default fallback. -- Request model validation: if a requested model is not present in the available Cursor model catalog, daemon falls back to the resolved default model. -- Daemon API surface: `POST /v1/chat/completions`, `POST /v1/messages`, and `GET /v1/models`. -- Live verification: `ccs legacy cursor probe` or `POST /api/cursor/probe` - -These values are managed in unified config and can be updated from CLI or dashboard. - -## Dashboard Usage - -Open dashboard: - -```bash -ccs config -``` - -Then navigate to `Cursor IDE (Legacy)` in the `Deprecated` section. - -Available controls: - -- Integration toggle (`enabled`) -- Auth actions (auto-detect, manual import) -- Daemon actions (start/stop) -- Runtime config (port, auto-start, ghost mode) -- Models list with searchable combobox filtering for large catalogs -- Raw editor for `~/.ccs/cursor.settings.json` - -## Raw Settings and Unified Config Sync - -Raw settings are stored in: - -`~/.ccs/cursor.settings.json` - -When raw settings include a local `ANTHROPIC_BASE_URL` port override, CCS synchronizes that port back into unified config so CLI and dashboard remain consistent. - -## Troubleshooting - -### `Not authenticated` or `expired` in `ccs cursor status` - -- Re-run `ccs legacy cursor auth` (or manual auth command). - -### `ccs legacy cursor probe` fails even though status is green - -- `status` proves local config/auth/daemon readiness only. -- `probe` proves the live runtime path. -- If `probe` fails with upstream protocol errors, inspect the current CCS build first rather than assuming the local daemon is healthy. - -### Auto-detect fails - -- Ensure Cursor is logged in. -- Confirm `sqlite3` is installed or use manual import. -- Use manual auth import if needed. - -### Daemon fails to start - -- Check if port `20129` is in use. -- Change port in dashboard config tab, then retry `ccs legacy cursor start`. diff --git a/docs/dashboard-auth-cli.md b/docs/dashboard-auth-cli.md deleted file mode 100644 index 891a42ee..00000000 --- a/docs/dashboard-auth-cli.md +++ /dev/null @@ -1,267 +0,0 @@ -# Dashboard Authentication CLI - -Last Updated: 2026-05-05 - -CLI commands for managing CCS dashboard authentication. - -## Overview - -The CCS dashboard (`ccs config`) can be protected with username/password authentication. This is useful whenever the dashboard is reachable from another device, such as when you explicitly bind it beyond loopback with `ccs config --host 0.0.0.0`. - -Authentication is **disabled by default** for backward compatibility, while `ccs config` binds to `localhost` by default. Use the CLI to configure and enable auth before exposing the dashboard to other devices. - -CCS does **not** ship a default dashboard username or password. When someone opens the dashboard from a non-loopback/IP address before auth is enabled, the UI now shows a setup state instead of an ambiguous login form. The host owner must run `ccs config auth setup`, or the user should switch back to the localhost URL if they are on the same machine. - -Docker note: the integrated `ccs docker` stack stores its config inside the running container volume, not in the outer shell's `~/.ccs`. For Docker deployments, run auth setup inside the container: - -```bash -docker exec -it ccs-cliproxy ccs config auth setup -``` - -When auth stays disabled, CCS now applies a localhost-only fallback on sensitive management endpoints. Remote devices can still open the dashboard UI when you intentionally bind it beyond loopback, but write-capable routes such as AI Provider management and CLIProxy auth/status helpers reject non-loopback requests until you enable dashboard auth. - -## Account Context Modes (Related Feature) - -Dashboard auth and account context metadata are separate: - -- `dashboard_auth`: protects dashboard access with username/password -- `accounts..context_mode/context_group`: controls isolated vs shared account context -- `accounts..shared_resource_mode`: controls plugins/commands/skills/agents/settings.json sharing - -Account context is isolation-first. The recommended two-account route is: - -```bash -ccs auth create work -ccs auth create personal -ccs work -ccs personal -``` - -Only enable history sync when both accounts should share local continuity while tokens stay separate: - -| Mode | Default | Requirement | -|------|---------|-------------| -| `isolated` | Yes | No `context_group` required | -| `shared` | No (opt-in) | Valid non-empty `context_group` | - -Shared continuity depth: - -- `standard` (default): shares project workspace context only -- `deeper` (advanced opt-in): also syncs `session-env`, `file-history`, `shell-snapshots`, `todos` - -`ccs auth show ` reports credential isolation, shared resource mode, settings sync state, history lane, and whether plain `ccs` currently uses the same resume lane. - -Non-bare account profiles share Claude-local resources with native Claude: - -```text -~/.ccs/instances//settings.json -> ~/.ccs/shared/settings.json -> ~/.claude/settings.json -``` - -This keeps ordinary Claude settings, plugins, commands, skills, and agents in sync without copying account tokens. Existing accounts can opt out or back in: - -```bash -ccs auth resources work --mode profile-local -ccs auth resources work --mode shared -``` - -Local history is separate: if users want future plain `ccs` and `ccs ck` sessions to resume from the same account lane, run `ccs auth default ck` after backing up the current native lane with `ccs auth backup default`. - -`context_group` normalization and validation: - -- trim + lowercase + collapse internal whitespace to `-` -- allowed characters: lowercase letters, numbers, `_`, `-` -- must start with a letter -- max length: 64 -- shared mode requires non-empty value after normalization -- `continuity_mode` is only valid when mode is `shared` - -`PUT /api/config` behavior for account context: - -- rejects invalid unified payloads -- rejects explicit `context_mode: shared` with invalid/empty `context_group` -- rejects invalid `continuity_mode` values -- normalizes valid shared `context_group` before save -- defaults missing shared `continuity_mode` to `standard` -- rejects `context_group` when mode is not `shared` -- rejects `continuity_mode` when mode is not `shared` - -Dashboard accounts context editing: - -- `PUT /api/accounts/:name/context` updates context mode/group/continuity for existing auth accounts -- rejects CLIProxy OAuth account keys for this route -- applies normalization/validation rules above - -Shared resource editing: - -- `PUT /api/accounts/:name/shared-resources` updates `shared_resource_mode` for existing auth accounts -- accepts only `shared` or `profile-local` -- rejects CLIProxy OAuth account keys for this route -- reconciles the account instance after metadata is updated -- Dashboard -> Accounts exposes this as a separate Resources action so it is not confused with History Sync. -- Dashboard -> Shared Resources shows the shared hub inventory for commands, skills, agents, plugins, and `settings.json`. -- The Plugins tab is registry-oriented: installed plugin entries come from `installed_plugins.json`, while internal cache/data/marketplace folders stay hidden unless a real plugin entry exists. -- Shared `settings.json` is read-only in the Shared Resources page and still edited through the settings surfaces that own those values. - -## Commands - -### `ccs config auth setup` - -Interactive wizard to configure dashboard login. - -```bash -$ ccs config auth setup - -╭─────────────────────────────────╮ -│ Dashboard Auth Setup │ -╰─────────────────────────────────╯ - -[i] Configure username and password for dashboard access. - Password will be hashed with bcrypt before storage. - -Username -Enter username: admin - -Password - Minimum 8 characters -Enter password: ******** -Confirm password: ******** - -[i] Hashing password... - -[OK] Dashboard authentication configured - -[i] Settings saved to ~/.ccs/config.yaml -[i] Username: admin -[i] Session timeout: 24 hours - - Start dashboard: ccs config - Show status: ccs config auth show - Disable auth: ccs config auth disable -``` - -### `ccs config auth show` - -Display current authentication status. - -```bash -$ ccs config auth show - -╭─────────────────────────────────╮ -│ Dashboard Auth Status │ -╰─────────────────────────────────╯ - -Configuration -[OK] Authentication: Enabled -[OK] Username: admin -[i] Session timeout: 24 hours - -Commands - ccs config auth setup Configure authentication - ccs config auth disable Disable authentication - ccs config Open dashboard -``` - -### `ccs config auth disable` - -Disable dashboard authentication with confirmation. - -```bash -$ ccs config auth disable - -╭─────────────────────────────────╮ -│ Disable Dashboard Auth │ -╰─────────────────────────────────╯ - -[!] This will disable login protection for the dashboard. -[i] Anyone with network access will be able to view the dashboard. - -Disable authentication? [y/N]: y - -[OK] Dashboard authentication disabled - -[i] Credentials preserved - re-enable with: ccs config auth setup -``` - -### `ccs config auth --help` - -Display usage information. - -## Environment Variables - -Environment variables override `config.yaml` values: - -| Variable | Description | -|----------|-------------| -| `CCS_DASHBOARD_AUTH_ENABLED` | Enable/disable auth (`true`/`false`) | -| `CCS_DASHBOARD_USERNAME` | Username | -| `CCS_DASHBOARD_PASSWORD_HASH` | Bcrypt password hash | - -### Generating a Password Hash - -Use bcrypt to generate a hash: - -```bash -# Using Node.js -node -e "console.log(require('bcrypt').hashSync('your-password', 10))" - -# Using npx -npx bcrypt-cli hash "your-password" -``` - -## Configuration - -Settings are stored in `~/.ccs/config.yaml`: - -```yaml -# Dashboard Auth: Optional login protection for CCS dashboard -# Generate password hash: npx bcrypt-cli hash "your-password" -# ENV override: CCS_DASHBOARD_AUTH_ENABLED, CCS_DASHBOARD_USERNAME, CCS_DASHBOARD_PASSWORD_HASH -dashboard_auth: - enabled: true - username: "admin" - password_hash: "$2b$10$..." - session_timeout_hours: 24 -``` - -## Security Notes - -1. **Bcrypt hashing**: Passwords are hashed with bcrypt (10 rounds) before storage -2. **Session cookies**: Sessions use HTTP-only cookies (not accessible via JavaScript) -3. **Rate limiting**: Login attempts are rate-limited (5 per 15 minutes) -4. **Fail-closed remote writes**: When auth is disabled, sensitive management routes allow localhost only -5. **File permissions**: Config file is created with 0o600 permissions - -## Troubleshooting - -### "Authentication not configured" - -Run `ccs config auth setup` to configure credentials. - -If you are using the integrated Docker stack, run that command inside `ccs-cliproxy`. Running it on the outer host shell updates a different config directory and will not unlock the running dashboard. - -### Forgot password - -Run `ccs config auth setup` again to set a new password. - -### ENV override not working - -Ensure the variable is exported: - -```bash -export CCS_DASHBOARD_AUTH_ENABLED=true -export CCS_DASHBOARD_USERNAME=admin -export CCS_DASHBOARD_PASSWORD_HASH='$2b$10$...' -``` - -### Session expired immediately - -Check `session_timeout_hours` in config. Default is 24 hours. - -### "Invalid ... context_group ..." - -This error comes from `PUT /api/config` when an account explicitly sets shared mode with an invalid group. Use a canonical group value (for example: `team-alpha`). - -## See Also - -- [Dashboard Auth Feature](https://ccs.kaitran.ca/features/dashboard-auth) - Full documentation -- [Config Schema](https://ccs.kaitran.ca/reference/config-schema) - All config options diff --git a/docs/session-sharing-technical-analysis.md b/docs/session-sharing-technical-analysis.md deleted file mode 100644 index f3aa0966..00000000 --- a/docs/session-sharing-technical-analysis.md +++ /dev/null @@ -1,216 +0,0 @@ -# Session Sharing Technical Analysis - -Last Updated: 2026-05-05 - -## Summary - -CCS supports practical cross-account continuity by sharing workspace context files between selected accounts, while keeping credentials isolated per account. - -This is implemented as a context policy per account: - -- `isolated` (default): account keeps its own workspace context -- `shared` + `standard` (default): account workspace context is linked to a shared context group -- `shared` + `deeper` (advanced opt-in): account also shares continuity artifacts - -## Recommended Two-Account Route - -Use `ccs auth` account profiles when you want two real Claude accounts and want to choose which one runs each session: - -```bash -ccs auth create work -ccs auth create personal - -ccs work -ccs personal -``` - -This keeps usage and credentials isolated. Each account owns its own Claude config directory, login state, and `.anthropic` credentials. - -Shared Resources are separate from History Sync. By default, non-bare account profiles inherit Claude-local resources from native Claude: - -```text -~/.ccs/instances//settings.json - -> ~/.ccs/shared/settings.json - -> ~/.claude/settings.json -``` - -This covers ordinary Claude Code `settings.json`, commands, skills, agents, and plugins. It is not token sharing. `ccs auth show ` reports `Resources`, `Settings`, `History`, and `Plain ccs` lanes so users can see whether shared resources and resume history are aligned. - -For existing accounts, change Shared Resources from the CLI: - -```bash -ccs auth resources work --mode profile-local -ccs auth resources work --mode shared -``` - -- `shared`: link plugins, commands, skills, agents, and `settings.json` from the shared Claude resource layout. -- `profile-local`: detach those shared resources for the account. This is the existing `--bare` behavior exposed as an existing-account setting. - -Only opt in to shared history when both accounts should see the same local continuity: - -```bash -ccs auth create work2 --share-context --context-group daily --deeper-continuity -``` - -For existing History Sync, use Dashboard -> Accounts -> Sync on both accounts, set both to `shared`, and use the same `History Sync Group`. Use `deeper` only when users expect stronger local handoff beyond project context. History Sync does not control plugins or `settings.json`; use `ccs auth resources` for that. - -## Why This Is Safe Enough - -CCS only shares workspace context paths (project/session context files). It does **not** merge or copy authentication credentials between accounts. - -Credential storage remains per account instance. - -## Implementation Model - -Account metadata is stored in `~/.ccs/config.yaml`: - -```yaml -accounts: - work: - created: "2026-02-24T00:00:00.000Z" - last_used: null - shared_resource_mode: "shared" - context_mode: "shared" - context_group: "team-alpha" - continuity_mode: "deeper" -``` - -Rules: - -- `shared_resource_mode` controls commands, skills, agents, plugins, and `settings.json` (`shared` or `profile-local`) -- `context_mode` must be `isolated` or `shared` -- `context_group` is required when `context_mode=shared` -- `continuity_mode` is valid only when `context_mode=shared` (`standard` or `deeper`) -- group normalization: trim, lowercase, internal spaces -> `-` -- group must start with a letter and only include `[a-zA-Z0-9_-]` -- max length: `64` - -Deeper continuity links these directories per context group: - -- `session-env` -- `file-history` -- `shell-snapshots` -- `todos` - -`.anthropic` and account credentials remain isolated. - -## Cross-Profile Inheritance (API / CLIProxy / Copilot) - -You can explicitly map non-account profiles (including `default`) to reuse continuity artifacts from an account profile: - -```yaml -continuity: - inherit_from_account: - glm: pro - gemini: pro - copilot: pro -``` - -Behavior: - -- Applies only when running Claude target (`ccs ` or `--target claude`) -- Does not change provider credentials or API routing -- Reuses `CLAUDE_CONFIG_DIR` from mapped account profile after normal account context policy resolution -- Invalid/missing mapped accounts are skipped safely - -### Resume Lane Note - -Resume follows the active `CLAUDE_CONFIG_DIR`, not just the continuity group: - -- plain `ccs -r` resumes the lane plain `ccs` is using right now -- `ccs -r` resumes only that account lane -- those two commands can point at different continuity inventories - -That means `shared + deeper` on an account does **not** automatically make old plain-`ccs` resume history appear inside `ccs -r`. - -If you want future plain `ccs` sessions to use an account lane, either: - -```bash -ccs auth default work -``` - -or map the default profile explicitly: - -```yaml -continuity: - inherit_from_account: - default: work -``` - -Example with an existing `ck` account: - -```bash -ccs auth show ck -ccs auth backup default -ccs auth default ck -``` - -`ccs auth default ck` makes future plain `ccs` sessions use the `ck` account lane, so future `ccs` and `ccs ck` resume from the same local inventory. It does not automatically import old native `~/.claude/projects` history into `ck`; keep using `ccs -r` for the old native lane until you intentionally migrate that local history. - -## User Workflows - -### New account with shared context - -```bash -ccs auth create work2 --share-context -ccs auth create backup --share-context --context-group sprint-a -ccs auth create backup2 --share-context --context-group sprint-a --deeper-continuity -``` - -### Existing account - -History Sync: - -- Open `ccs config` -- Go to `Accounts` -- Click the pencil icon (`Edit History Sync`) -- Choose `isolated` or `shared`, set group, and (optionally) choose deeper continuity - -Shared Resources: - -```bash -ccs auth resources work --mode profile-local -ccs auth resources work --mode shared -``` - -Dashboard: - -- Open `ccs config` -- Go to `Accounts` -- Use `Resources` to switch an existing account between `shared` and `profile-local` -- Go to `Shared Resources` to inspect the shared commands, skills, agents, plugins, and `settings.json` hub - -No account recreation required for this workflow. - -### Backup Before Changing Sync - -CCS can back up local continuity artifacts before you change settings: - -```bash -ccs auth backup work -ccs auth backup default -``` - -- `ccs auth backup work` backs up the selected account lane -- `ccs auth backup default` backs up the lane plain `ccs` would use right now -- this is a local continuity backup, not a guaranteed export of all upstream Claude-hosted resume state - -## Current Limitations - -- Shared context is local filesystem sharing. It does not bypass remote provider permission models. -- Session continuity still depends on what the upstream tool/provider stores and allows. -- Context sharing should only be enabled for accounts you intentionally trust to share workspace history. -- Shared Resources inspection is read-only in the dashboard. Editing individual files still belongs to the owning command, skill, plugin, or settings surface. - -## Alternative: CLIProxy Claude Pool - -For users who prefer lower manual account switching, use CLIProxy Claude pool instead: - -- Authenticate pool accounts via `ccs cliproxy auth claude` -- Manage account pool behavior in `ccs config` -> `CLIProxy Plus` - -## Validation Checklist - -- Confirm account row shows `shared ()` in Dashboard Accounts table -- Switch between accounts in the same group and verify workspace continuity -- Run `ccs doctor` if symlink/context health looks inconsistent