docs: sync agent guide with AGENTS

CLAUDE.md

@@ -1,563 +1,124 @@
-# Agent Guidelines
+# CCS CLI Agent Guide
 
-AI-facing guidance for agent tooling when working with this repository.
+Canonical agent instructions for `/Users/kaitran/CloudPersonal/ccs/cli`.
+`AGENTS.md` must stay a symlink to this file.
 
-## Critical Constraints (NEVER VIOLATE)
+## Scope
 
-### Test Isolation (MANDATORY)
+CCS is a TypeScript/Bun CLI and dashboard for managing Claude Code, Codex,
+Factory Droid, CLIProxy, and compatible provider profiles.
 
-**NEVER touch the user's real `~/.ccs/` or `~/.claude/` directories during tests.**
+## Non-Negotiables
 
-- All code accessing CCS paths MUST use `getCcsDir()` from `src/utils/config-manager.ts`
-- This function respects `CCS_HOME` env var for test isolation
-- **WRONG:** `path.join(os.homedir(), '.ccs', ...)`
-- **CORRECT:** `path.join(getCcsDir(), ...)`
+- Default branch is `dev`. Feature/fix branches start from `dev`; production
+  hotfixes start from `main` only when explicitly needed.
+- Never touch the user's real `~/.ccs/` or `~/.claude/` in tests. Use
+  `getCcsDir()` from `src/utils/config-manager.ts`; it respects `CCS_HOME`.
+- Do not commit directly to `dev` or `main`.
+- Do not manually bump versions or create release tags. Semantic-release owns
+  versions, changelog, tags, npm publish, and GitHub releases.
+- CLI terminal output must be ASCII only: `[OK]`, `[!]`, `[X]`, `[i]`.
+- Respect `NO_COLOR` and TTY-aware output.
 
-Tests set `process.env.CCS_HOME` to a temp directory. Code using `os.homedir()` directly will modify the user's real files.
+## Architecture
 
-## CI-First Protocol (MANDATORY)
+- `src/` - TypeScript CLI/server source.
+- `lib/ccs`, `lib/ccs.ps1` - bootstrap wrappers; no help text here.
+- `ui/src/` - React dashboard.
+- `dist/` and `dist/ui/` - build outputs.
+- `docs/` - local development and architecture docs.
+- Docker support lives under `docker/` and related commands.
 
-**A task is NOT complete until CI is green. After every `git push`, the AI agent MUST block on CI until it passes.**
+Profile resolution priority:
 
-### Required Sequence
-1. `git push`
-2. **Immediately** run `gh pr checks --watch` (or `gh run watch`) and block until all checks complete.
-3. If **green** → task may proceed to next step / be declared done.
-4. If **red**:
-   - Pull failing logs: `gh run view --log-failed` (or `gh pr checks <n>` to identify the failing job, then `gh run view <run-id> --log-failed`).
-   - Fix the root cause locally. Do NOT retry blindly.
-   - Commit and push again. Re-watch CI.
-5. Applies to initial `gh pr create` AND every subsequent push on an open PR.
+1. Built-in CLIProxy providers: Gemini, Codex, Antigravity.
+2. User-defined `config.cliproxy` providers.
+3. Settings-based `config.profiles`.
+4. Account-based `profiles.json` with isolated `CLAUDE_CONFIG_DIR`.
 
-### Fallback (when `--watch` is unavailable or flaky)
-Poll with short sleep until no check is `pending` / `in_progress`:
-```bash
-until [ "$(gh pr checks <n> --json state -q '[.[] | select(.state == "IN_PROGRESS" or .state == "PENDING" or .state == "QUEUED")] | length')" = "0" ]; do
-  sleep 10
-done
-gh pr checks <n>
-```
+All env values written into settings must be strings.
 
-### Absolute rule
-AI MUST NOT declare a task done, close a session, or move to the next task while CI is red or still running. Leaving a PR red and moving on is the primary failure mode this protocol prevents.
+## User-Facing Change Checklist
 
-### Dev Release vs Push CI
+- Update the matching `--help` handler when CLI behavior changes.
+- Keep README concise; do not remove `## Community Projects` or
+  `## Star History` unless explicitly asked.
+- Use neutral broad examples such as `ccs`, `ccs codex`, `ccs glm`, or
+  `ccs <provider>` unless the page is provider-specific.
+- If CLI commands, config, providers, install steps, or user workflows change,
+  update the public CCS docs in `/Users/kaitran/CloudPersonal/ccs/docs`.
 
-- `CI` is the pull-request quality gate for contributor branches.
-- `Push CI` is the post-merge quality signal for `dev`.
-- `Dev Release` publishes the `@dev` package after `dev` changes land.
-- A red `Dev Release` does **not** automatically mean contributor code failed. Check `Push CI` first.
-- Verified on `2026-04-22` via `gh api repos/kaitranntt/ccs/branches/dev/protection`: `dev` currently requires `typecheck`, `lint`, `format`, `build`, and `test`, has no branch restrictions, and has no required PR-review gate.
-- `dev-release.yml` currently pushes with `PAT_TOKEN` because `dev` is protected by those required status checks. Do not switch it back to `github.token` unless branch protection changes with it.
+Help locations:
 
-### Self-Hosted Runner Policy
+- `ccs --help`: `src/commands/help-command.ts`
+- `ccs api --help`: `src/commands/api-command.ts`
+- `ccs cleanup --help`: `src/commands/cleanup-command.ts`
+- `ccs cliproxy --help`: `src/commands/cliproxy-command.ts`
+- `ccs config --help`: `src/commands/config-command.ts`
+- `ccs copilot --help`: `src/commands/copilot-command.ts`
+- `ccs cursor --help`: `src/commands/cursor-command.ts`
+- `ccs doctor --help`: `src/commands/doctor-command.ts`
+- `ccs docker --help`: `src/commands/docker/help-subcommand.ts`
+- `ccs env --help`: `src/commands/env-command.ts`
+- `ccs migrate --help`: `src/commands/migrate-command.ts`
+- `ccs persist --help`: `src/commands/persist-command.ts`
+- `ccs setup --help`: `src/commands/setup-command.ts`
 
-- Keep active CCS workflows on local self-hosted runners by default. Do **not** move jobs to `ubuntu-latest`, `macos-latest`, or other GitHub-hosted runners as the first security fix.
-- For this public repo, standard GitHub-hosted runners may not consume billable minutes, but the project policy is still local-runner-first to keep compute predictable and avoid future quota surprises across repos.
-- Make self-hosted use secure by gating untrusted PR triggers, avoiding checkout of untrusted code in privileged `pull_request_target` jobs, setting `persist-credentials: false`, and scoping PAT-backed credentials to the exact release/sync push step.
-- If a workflow truly needs GitHub-hosted runners, document the exception in this file and add a regression test for the exception.
+## Validation
 
-## Core Function
-
-Multi-provider profile and runtime manager for Claude Code, Factory Droid,
-Codex CLI, and other compatible targets. See README.md for user documentation.
-
-## README Preservation
-
-When editing `README.md`, keep the file concise and funnel detailed usage into
-the docs site, but **do not remove the `## Community Projects` section** or the
-`## Star History` section unless the user explicitly asks for those sections to
-be deleted. Treat both as protected README content.
-
-When a contributor adds a useful community integration section to `README.md`,
-prefer preserving the attribution in `## Community Projects` and moving the
-setup substance into a docs page, rather than deleting the contribution.
-
-Outside provider-specific Gemini and Antigravity docs, avoid using `ccs gemini`
-or `ccs agy` as the primary hero example, default starter route, or generic
-workflow example. Prefer `ccs`, `ccs codex`, `ccs kiro`, `ccs glm`, Droid
-examples, or neutral `ccs <provider>` placeholders when the page is about a
-broader topic.
-
-## Design Principles (ENFORCE STRICTLY)
-
-### Technical Excellence
-- **YAGNI**: No features "just in case"
-- **KISS**: Simple bash/PowerShell/Node.js only
-- **DRY**: One source of truth (config.yaml)
-
-### User Experience (EQUALLY IMPORTANT)
-- **CLI-Complete**: All features MUST have CLI interface
-- **Dashboard-Parity**: Configuration features MUST also have Dashboard interface
-- **Execution is CLI**: Running profiles happens via terminal, not dashboard buttons
-- **UX > Brevity**: Error messages and help text prioritize user success over terseness
-- **Progressive Disclosure**: Simple by default, power features accessible but not overwhelming
-
-### When Principles Conflict
-- **UX > YAGNI** for user-facing features (if users need it, it's not "just in case")
-- **KISS applies to BOTH** code AND user experience (simple journey, not just simple code)
-- **DRY applies to BOTH** code AND interface patterns (consistent behavior across CLI/Dashboard)
-
-## Common Mistakes (AVOID)
-
-| Mistake | Consequence | Correct Action |
-|---------|-------------|----------------|
-| Running `validate` without `format` first | format:check fails | Run `bun run format` BEFORE validate |
-| Treating `Dev Release` as the contributor quality signal | Publish failures on `dev` look like broken code | Check PR `CI` on the branch and `Push CI` on `dev` first |
-| Using `chore:` for dev→main PR | No npm release triggered | Use `feat:` or `fix:` prefix |
-| Committing directly to `main` or `dev` | Bypasses CI/review | Always use PRs |
-| Manual version bump or git tag | Conflicts with semantic-release | Let CI handle versioning |
-| Forgetting `--help` update | CLI docs out of sync | Update `src/commands/help-command.ts` |
-| Forgetting docs update | User docs out of sync | Update `docs/` and CCS docs submodule |
-
-## GitHub Issue Operations (CCS-Specific)
-
-These rules apply when the task is issue triage, backlog cleanup, labels, comments, Projects, or milestones for this repo.
-
-### Scope Boundary
-
-- Treat issue triage as a **GitHub-only workflow** unless the user explicitly asks for implementation.
-- Do **NOT** create a worktree, branch, PR, or run `/fix`, `/cook`, or `kai:maintainer` just to tag issues, post follow-up comments, close duplicates, or clean up backlog state.
-- Escalate into code workflow only when:
-  - the user explicitly asks to fix/implement an issue, or
-  - triage proves the same task now requires code changes.
-
-### Read Before Mutating
-
-- Always inspect live issue state first with `gh issue view <n> --json ...` or `gh api`.
-- Never rely on stale memory, screenshots, or issue titles alone.
-- Before closing as resolved, cross-check repo evidence in at least one of:
-  - `README.md`
-  - `docs/`
-  - `CHANGELOG.md`
-  - relevant source/help handlers
-- If the `gh` query would touch Projects fields, verify token scope first. Missing `read:project` is a real blocker, not something to hand-wave around.
-
-### Labeling Standard
-
-- Every **open** issue should end triage with:
-  - one primary type label: `bug`, `enhancement`, `question`, `documentation`, `duplicate`, `invalid`, or `wontfix`
-  - one area label:
-    - `area:cli-runtime`
-    - `area:dashboard-ui`
-    - `area:config-auth`
-    - `area:provider-integration`
-    - `area:install-packaging`
-    - `area:documentation`
-    - `area:contributor-workflow`
-- Add routing labels only when they materially change handling:
-  - `upstream-blocked`
-  - `needs-repro`
-  - `needs-split`
-  - `docs-gap`
-- Use release-state labels for shipped work:
-  - `pending-release`
-  - `released-dev`
-  - `released`
-- Do **NOT** create or use status labels like `todo`, `doing`, `blocked`, `done`.
-- Do **NOT** create provider-name labels unless there is a proven long-term need. Provider names belong in titles/issues, not label spam.
-
-### Commenting Rules
-
-- Keep issue comments short, technical, and neutral.
-- State the decision plainly: close, keep open, retag, needs repro, duplicate, blocked upstream.
-- Include exact evidence when relevant: version, doc path, changelog release, canonical issue, upstream link.
-- Do **NOT** reference internal plans, local report files, agent prompts, or private reasoning.
-- Post **one** maintainer follow-up comment per triage pass. If accidental duplicates are created, delete them with `gh api repos/<owner>/<repo>/issues/comments/<id> -X DELETE`.
-
-### Closure Rules
-
-- Close immediately when:
-  - the issue is an obvious duplicate and you can point to the canonical issue
-  - the feature/fix is clearly shipped and documented
-  - a previously `pending-release` issue is now clearly past release and no longer needs tracking
-- Keep open and retag when:
-  - upstream dependency still blocks CCS adoption -> `upstream-blocked`
-  - latest-release behavior is unclear -> `needs-repro`
-  - issue contains multiple independent asks -> `needs-split`
-  - feature likely exists but discoverability/docs are weak -> `docs-gap`
-- Do **NOT** close just because an issue is old, vague, or inconvenient. Close only with evidence.
-
-### Projects And Milestones
-
-- Preferred project model for this repo: one project, `CCS Backlog`.
-- Use Projects for workflow state and priority. Use labels for meaning and routing.
-- Milestones are for real ship windows only, not generic categorization buckets.
-- If `gh` token lacks `read:project`, say so explicitly and stop short of pretending Projects data is available.
-- Active project:
-  - owner: `kaitranntt`
-  - number: `3`
-  - URL: `https://github.com/users/kaitranntt/projects/3`
-- Active project fields:
-  - `Status` -> use for work state (`Todo`, `In Progress`, `Done`)
-  - `Priority` -> `P1` for bugs, `P2` default backlog, `P3` for broad `needs-split` buckets unless explicitly reprioritized
-  - `Follow-up` -> `Ready`, `Needs repro`, `Blocked upstream`, `Needs split`, `Docs follow-up`
-  - `Next review` -> date only for issues that need a follow-up checkpoint
-- When triaging an open issue, make sure it exists in `CCS Backlog` and the project fields match the routing labels.
-- Do **NOT** create a second backlog project unless the user explicitly wants a project split and gives a reason.
-- Current automation path:
-  - workflow file: `.github/workflows/sync-ccs-backlog-project.yml`
-  - sync script: `scripts/github/ccs-backlog-sync.mjs`
-  - required Actions secret: `CCS_PROJECT_AUTOMATION_TOKEN`
-- Automation mapping must stay aligned with labels:
-  - `upstream-blocked` -> `Follow-up=Blocked upstream`
-  - `needs-repro` -> `Follow-up=Needs repro`
-  - `needs-split` -> `Follow-up=Needs split`
-  - `docs-gap` -> `Follow-up=Docs follow-up`
-  - otherwise -> `Follow-up=Ready`
-
-### New Or Updated Issue Creation
-
-- When creating issues for this repo:
-  - assign `@kaitranntt`
-  - use conventional issue titles: `bug: ...`, `feat: ...`, `docs: ...`
-  - keep bodies factual and technical
-  - avoid personal info and internal-only context
-
-## Quality Gates (MANDATORY)
-
-Quality gates MUST pass before pushing. **Both projects have identical workflow.**
-
-### Pre-Commit Sequence (FOLLOW THIS ORDER)
+Format before validating:
 
 ```bash
-# Main project (from repo root)
-bun run format              # Step 1: Fix formatting
-bun run lint:fix            # Step 2: Fix lint issues
-bun run validate            # Step 3: Fast gate (typecheck + lint + format + test:fast)
-bun run validate:ci-parity  # Step 4: PR-CI parity gate (branch check + build + full tests + e2e)
-
-# UI project (if UI changed)
-cd ui
-bun run format              # Step 1: Fix formatting
-bun run lint:fix            # Step 2: Fix lint issues
-bun run validate            # Step 3: Final check (must pass)
+cd /Users/kaitran/CloudPersonal/ccs/cli && bun run format
+cd /Users/kaitran/CloudPersonal/ccs/cli && bun run lint:fix
+cd /Users/kaitran/CloudPersonal/ccs/cli && bun run validate
 ```
 
-**WHY THIS ORDER:**
-- `validate` runs `format:check` which only VERIFIES—won't fix
-- If format:check fails, you skipped step 1
-- `validate` now uses read-only `lint`, so autofix still belongs in step 2
-- PR CI and `validate:ci-parity` both run non-mutating checks only
+Before requesting review or merge, run:
 
-### What Each Gate Runs
-
-| Project | Command | Runs |
-|---------|---------|------|
-| Main | `bun run validate` | typecheck + lint + format:check + test:fast |
-| Main | `bun run validate:ci-parity` | base branch check + typecheck + lint + format:check + build:all + test:all + test:e2e |
-| UI | `bun run validate` | typecheck + lint:fix + format:check |
-
-### ESLint Rules (ALL errors)
-
-| Rule | Level | Notes |
-|------|-------|-------|
-| `@typescript-eslint/no-unused-vars` | error | Ignore `_` prefix |
-| `@typescript-eslint/no-explicit-any` | error | Use proper types or `unknown` |
-| `@typescript-eslint/no-non-null-assertion` | error | No `!` assertions |
-| `prefer-const`, `no-var`, `eqeqeq` | error | Code quality |
-| `react-hooks/*` (UI only) | recommended | Hooks rules |
-| `react-refresh/*` (UI only) | vite | Fast refresh |
-
-### TypeScript Options (strict mode)
-
-| Option | Value | Notes |
-|--------|-------|-------|
-| `strict` | true | All strict flags enabled |
-| `noUnusedLocals` | true | No unused variables |
-| `noUnusedParameters` | true | No unused params |
-| `noImplicitReturns` | true | All paths must return |
-| `noFallthroughCasesInSwitch` | true | Explicit case handling |
-
-### Automatic Enforcement
-
-- `prepack` runs `build:all`
-- PR `CI` runs `typecheck`, `lint`, `format`, `build`, `test:all`, and `test:e2e`
-- `Push CI` runs the same quality suite on `dev` after merge, separate from release publishing
-- `Dev Release` still runs build + fast validation + slow tests + e2e before publishing and still requires `PAT_TOKEN` to push back to protected `dev`
-- husky `pre-commit` runs quick lint/type/format checks
-- husky `pre-push` runs the full `bun run validate:ci-parity` gate on `main`/`dev`/hotfix branches
-- husky `pre-push` runs a faster feature-branch gate (`typecheck` + `lint` + `format:check` + `test:fast`) plus targeted checks based on changed files
-
-### Maintainability Gate Status
-
-- The historical maintainability baseline gate is retired from the active CCS workflow.
-- `validate`, `validate:ci-parity`, PR `CI`, `Push CI`, and release workflows do **not** invoke `maintainability:check`.
-- Older roadmap references to `maintainability:baseline` / `maintainability:check` are historical context, not current repo commands.
-
-## Critical Constraints (NEVER VIOLATE)
-
-1. **NO EMOJIS in CLI output** - Terminal output uses ASCII only: [OK], [!], [X], [i]
-   - **Scope:** CCS CLI terminal output (`src/` code that prints to stdout/stderr)
-   - **Does NOT apply to:** PR descriptions, commit messages, documentation, comments, AI conversations
-2. **TTY-aware colors** - Respect NO_COLOR env var
-3. **Non-invasive** - NEVER modify external tool settings (`~/.claude/settings.json`) without explicit user request and confirmation (exception: `ccs persist` command)
-4. **Cross-platform parity** - bash/PowerShell/Node.js must behave identically
-5. **CLI documentation** - ALL CLI changes MUST update respective `--help` handler (see table below)
-6. **Idempotent** - All install operations safe to run multiple times
-7. **Dashboard parity** - Configuration features MUST work in both CLI and Dashboard
-
-### Help Location Reference
-
-| Command | Help Handler Location |
-|---------|----------------------|
-| `ccs --help` | `src/commands/help-command.ts` |
-| `ccs api --help` | `src/commands/api-command.ts` → `showHelp()` |
-| `ccs cleanup --help` | `src/commands/cleanup-command.ts` → `printHelp()` |
-| `ccs cliproxy --help` | `src/commands/cliproxy-command.ts` → `showHelp()` |
-| `ccs config --help` | `src/commands/config-command.ts` → `showHelp()` |
-| `ccs copilot --help` | `src/commands/copilot-command.ts` → `handleHelp()` |
-| `ccs cursor --help` | `src/commands/cursor-command.ts` → `handleHelp()` |
-| `ccs doctor --help` | `src/commands/doctor-command.ts` → `showHelp()` |
-| `ccs docker --help` | `src/commands/docker/help-subcommand.ts` → `showHelp()` |
-| `ccs migrate --help` | `src/commands/migrate-command.ts` → `printMigrateHelp()` |
-| `ccs env --help` | `src/commands/env-command.ts` → `showHelp()` |
-| `ccs persist --help` | `src/commands/persist-command.ts` → `showHelp()` |
-| `ccs setup --help` | `src/commands/setup-command.ts` → `showHelp()` |
-
-**Note:** `lib/ccs` and `lib/ccs.ps1` are bootstrap wrappers only—they delegate to Node.js and contain no help text.
-
-## Documentation Requirements (MANDATORY)
-
-**Documentation is a first-class citizen. ALL user-facing changes require docs updates.**
-
-### Local Documentation (`docs/`)
-
-Update local `docs/` folder for:
-- Architecture changes
-- Internal API documentation
-- Development guides
-
-### CCS Docs Submodule (Owner Only)
-
-**For @kaitranntt (repository owner):** When adding/changing CLI commands or config options, you MUST also update the CCS docs submodule at `~/CloudPersonal/ccs/docs/`:
-
-| Change Type | Files to Update |
-|-------------|-----------------|
-| New CLI command/flag | `reference/cli-commands.mdx` |
-| New config option | `reference/config-schema.mdx` |
-| Provider feature | `providers/<provider>.mdx` |
-| New feature | `features/<feature>.mdx` |
-
-**Workflow for docs submodule:**
 ```bash
-cd ~/CloudPersonal/ccs/docs/
-git checkout main && git pull
-# Make changes
-git add -A && git commit -m "docs: <description>"
-git push origin main
+cd /Users/kaitran/CloudPersonal/ccs/cli && bun run validate:ci-parity
 ```
 
-**For external contributors:** Document changes in PR description. Owner will sync to CCS docs.
+If UI changed:
 
-### Pre-Commit Docs Checklist
-
-- [ ] Respective `--help` updated (see Help Location Reference table)
-- [ ] Local `docs/` updated if architecture changed
-- [ ] CCS docs submodule updated (owner) or PR description includes docs (contributor)
-
-## Feature Interface Requirements
-
-| Feature Type | CLI | Dashboard | Example |
-|--------------|-----|-----------|---------|
-| Profile creation | ✓ | ✓ | `ccs auth create`, Dashboard "Add Account" |
-| Profile switching | ✓ | ✓ | `ccs <profile>` (execution is CLI-only) |
-| API key config | ✓ | ✓ | `ccs api create`, Dashboard API Profiles |
-| Health check | ✓ | ✓ | `ccs doctor`, Dashboard Live Monitor |
-| OAuth auth flow | ✓ | ✓ | Browser opens from CLI or Dashboard |
-| Analytics/monitoring | ✗ | ✓ | Dashboard Analytics (visual by nature) |
-| WebSearch config | ✓ | ✓ | CLI flags, Dashboard Settings |
-| Remote proxy config | ✓ | ✓ | CLI flags, Dashboard Settings |
-
-## File Structure
-
-```
-src/           → TypeScript source (main project)
-dist/          → Compiled JavaScript (npm package)
-lib/           → Native shell scripts (bash, PowerShell)
-ui/src/        → React components, hooks, pages
-ui/src/components/ui/ → shadcn/ui components
-dist/ui/       → Built UI bundle (served by Express)
-```
-
-## Key Technical Details
-
-### Profile Mechanisms (Priority Order)
-
-1. **CLIProxy hardcoded**: gemini, codex, agy → OAuth-based, zero config
-2. **CLIProxy variants**: `config.cliproxy` section → user-defined providers
-3. **Settings-based**: `config.profiles` section → GLM, legacy GLMT compatibility, Kimi
-4. **Account-based**: `profiles.json` → isolated instances via `CLAUDE_CONFIG_DIR`
-
-### Settings Format (CRITICAL)
-
-All env values MUST be strings (not booleans/objects) to prevent PowerShell crashes.
-
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://api.example.com/anthropic",
-    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
-    "ANTHROPIC_MODEL": "model-name"
-  }
-}
-```
-
-### Shared Data Architecture
-
-Symlinked from `~/.ccs/shared/`: commands/, skills/, agents/
-Profile-specific: settings.json, sessions/, todolists/, logs/
-Windows fallback: Copies if symlinks unavailable
-
-## Code Standards
-
-### Architecture
-- `lib/ccs`, `lib/ccs.ps1` - Bootstrap scripts (delegate to Node.js via npx)
-- `src/*.ts` → `dist/*.js` - Main implementation (TypeScript)
-
-### Bash (lib/*.sh)
-- bash 3.2+, `set -euo pipefail`, quote all vars `"$VAR"`, `[[ ]]` tests
-- NO external dependencies
-
-### PowerShell (lib/*.ps1)
-- PowerShell 5.1+, `$ErrorActionPreference = "Stop"`
-- Native JSON only, no external dependencies
-
-### TypeScript (src/*.ts)
-- Node.js 18+, Bun 1.0+, TypeScript 5.3, strict mode
-- `child_process.spawn`, handle SIGINT/SIGTERM
-
-### Terminal Output
-- ASCII only: [OK], [!], [X], [i] (NO emojis in CLI output)
-- TTY detect before colors, respect NO_COLOR
-- Box borders for errors: ╔═╗║╚╝
-
-## Conventional Commits (MANDATORY)
-
-**ALL commits MUST follow conventional commit format. Non-compliant commits are rejected by husky.**
-
-### Format
-```
-<type>(<scope>): <description>
-```
-
-### Types (determines version bump)
-
-| Type | Version Bump | Use For |
-|------|--------------|---------|
-| `feat:` | MINOR | New features |
-| `fix:` | PATCH | Bug fixes |
-| `perf:` | PATCH | Performance |
-| `feat!:` | MAJOR | Breaking changes |
-| `docs:`, `style:`, `refactor:`, `test:`, `chore:`, `ci:`, `build:` | None | Non-release |
-
-### Examples
 ```bash
-# Good
-git commit -m "feat(cliproxy): add OAuth token refresh"
-git commit -m "fix(doctor): handle missing config gracefully"
-
-# Bad - REJECTED
-git commit -m "added new feature"
-git commit -m "Fixed bug"
+cd /Users/kaitran/CloudPersonal/ccs/cli/ui && bun run format && bun run validate
 ```
 
-## Branching Strategy
+After every push to a PR, watch CI until it finishes. If checks fail, inspect
+logs, fix root cause, push again, and re-watch.
 
-### Hierarchy
-```
-main (production) ← dev (integration) ← feat/* | fix/* | docs/*
-     ↑
-     └── hotfix/* (critical only, skips dev)
-```
+## Issue Triage
+
+Issue triage is GitHub-only unless implementation is explicitly requested.
+Always inspect live state first:
 
-### Standard Workflow
 ```bash
-git checkout dev && git pull origin dev
-git checkout -b feat/my-feature
-# ... develop with conventional commits ...
-git push -u origin feat/my-feature
-gh pr create --base dev --title "feat(scope): description"
-# After testing in @dev:
-gh pr create --base main --title "feat(release): promote dev to main"
+cd /Users/kaitran/CloudPersonal/ccs/cli && gh issue view <number> --json title,body,state,labels,assignees,comments
 ```
 
-### Hotfix Workflow (Production Emergencies Only)
-```bash
-git checkout main && git pull origin main
-git checkout -b hotfix/critical-bug
-# ... fix ...
-gh pr create --base main --title "fix: critical issue"
-# Then sync: git checkout dev && git merge main && git push
-```
+For open issues, prefer one type label and one area label. Use routing labels
+only when they affect handling: `upstream-blocked`, `needs-repro`,
+`needs-split`, `docs-gap`. Do not close issues on age, intuition, or vague
+titles; close only with evidence from README, docs, changelog, source, or a
+canonical duplicate.
 
-### Rules
-1. **NEVER** commit directly to `main` or `dev`
-2. Feature branches from `dev`, hotfixes from `main`
-3. dev→main PRs MUST use `feat:` or `fix:` (not `chore:`)
-4. Delete branches after merge
+## Release Signals
 
-## Automated Releases (DO NOT MANUALLY TAG)
+- PR `CI` is the contributor quality gate.
+- `Push CI` is the post-merge signal for `dev`.
+- `Dev Release` publishes the `@dev` npm package.
+- A red `Dev Release` is not automatically contributor failure; check PR `CI`
+  and `Push CI` first.
 
-**Releases are FULLY AUTOMATED via semantic-release. NEVER manually bump versions or create tags.**
+Use `feat:` or `fix:` for dev-to-main promotion PRs so release automation runs.
 
-| Branch | npm Tag | When |
-|--------|---------|------|
-| `main` | `@latest` | Merge PR to main |
-| `dev` | `@dev` | Push to dev branch |
+## Design Standards
 
-**CI handles:** version bump, CHANGELOG.md, git tag, npm publish, GitHub release.
-
-## Development
-
-### Testing (REQUIRED before PR)
-```bash
-bun run test              # All tests
-bun run test:npm          # npm package tests
-bun run test:native       # Native install tests
-bun run test:unit         # Unit tests
-```
-
-### Local Development
-```bash
-bun run dev               # Build + start config server (http://localhost:3000)
-bun run dev:symlink       # Symlink global 'ccs' → dev dist/ccs.js (fast iteration)
-bun run dev:unlink        # Restore original global ccs
-./scripts/dev-install.sh  # Build, pack, install globally (full install)
-rm -rf ~/.ccs             # Clean environment
-```
-
-**IMPORTANT:** Use `bun run dev` at CCS root for always up-to-date code. Do NOT use `ccs config` during development as it uses the globally installed version.
-
-## Two-Tier Pre-Push Checklist
-
-Optimized for iterative push-then-review workflow. Do NOT run the full gate on every push — CI is the safety net. Run the full gate once before asking for review / merge.
-
-### Tier 1 — Iterative push (feature branch)
-Husky `pre-push` auto-runs: `typecheck + lint + format:check + test:fast` plus targeted checks based on changed files. AI does **nothing extra** at push time.
-
-**After push (MANDATORY):** follow the [CI-First Protocol](#ci-first-protocol-mandatory) — watch CI until green. Do not move on while CI is red.
-
-### Tier 2 — Before requesting review / merge
-Run ONCE, not per push:
-- [ ] `bun run validate:ci-parity` — branch freshness + build + full non-e2e tests + e2e
-- [ ] `gh pr checks <n>` — all checks green
-- [ ] If UI changed: `cd ui && bun run format && bun run validate`
-- [ ] If touching command routing, proxy flows, workflows, or release logic: `bun run test:e2e`
-
-### Code / Docs / Standards (verify before merge)
-- [ ] Conventional commit format (`feat:`, `fix:`, etc.)
-- [ ] Respective `--help` updated (see Help Location Reference) — if CLI changed
-- [ ] Tests added/updated — if behavior changed
-- [ ] README.md updated — if user-facing
-- [ ] CCS docs updated (owner: `~/CloudPersonal/ccs/docs/`) — if CLI/config changed
-- [ ] Local `docs/` updated — if architecture changed
-- [ ] CLI output ASCII only (NO emojis in terminal output), NO_COLOR respected
-- [ ] YAGNI/KISS/DRY alignment verified
-- [ ] No manual version bump or tags
-
-## Error Handling Principles
-
-- Validate early, fail fast with clear messages
-- Show available options on mistakes
-- Never leave broken state
+- YAGNI, KISS, DRY.
+- CLI-complete: core configuration features need CLI coverage.
+- Dashboard parity: configuration features usually need dashboard coverage too.
+- Execution remains CLI-first; dashboard should not replace terminal profile
+  launch flows.
+- Error messages should help users recover, not just report failure.