docs(ccs): refactor README and add comprehensive documentation structure

- Reduce README.md from 640 to 48 lines (92% reduction)
- Add 5 new documentation files: installation, configuration, usage, troubleshooting, contributing
- Follow YAGNI/KISS/DRY principles with essential info in README
- Preserve all content in organized docs/ structure
- Improve user experience with quick start focus

docs/configuration.md

@@ -0,0 +1,145 @@
+# CCS Configuration Guide
+
+## Automatic Configuration
+
+The installer auto-creates config and profile templates during installation:
+
+**macOS / Linux**: `~/.ccs/config.json`
+
+**Windows**: `%USERPROFILE%\.ccs\config.json`
+
+## Configuration Format
+
+### Basic Setup
+
+```json
+{
+  "profiles": {
+    "glm": "~/.ccs/glm.settings.json",
+    "default": "~/.claude/settings.json"
+  }
+}
+```
+
+### Advanced Setup (Multiple Profiles)
+
+```json
+{
+  "profiles": {
+    "glm": "~/.ccs/glm.settings.json",
+    "haiku": "~/.ccs/haiku.settings.json",
+    "custom": "~/.ccs/custom.settings.json",
+    "default": "~/.claude/settings.json"
+  }
+}
+```
+
+## Profile Configuration
+
+### GLM Profile Example
+
+**Location**: `~/.ccs/glm.settings.json`
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
+    "ANTHROPIC_AUTH_TOKEN": "your_glm_api_key",
+    "ANTHROPIC_MODEL": "glm-4.6",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.6"
+  }
+}
+```
+
+### Claude (Default) Profile
+
+- Uses `~/.claude/settings.json` (your existing Claude CLI config)
+- CCS never modifies this file (non-invasive approach)
+
+## How Configuration Works
+
+1. CCS reads profile name from command line (defaults to "default")
+2. Looks up settings file path in `~/.ccs/config.json`
+3. Executes `claude --settings <file> [remaining-args]`
+
+No magic. No file modification. Pure delegation. Works identically across all platforms.
+
+## Custom Config Location
+
+```bash
+export CCS_CONFIG=~/my-custom-config.json
+ccs glm
+```
+
+## Platform-Specific Notes
+
+### Windows Configuration
+
+Windows uses the same file structure and approach as Linux/macOS.
+
+**Config format** (`~/.ccs/config.json`):
+```json
+{
+  "profiles": {
+    "glm": "~/.ccs/glm.settings.json",
+    "default": "~/.claude/settings.json"
+  }
+}
+```
+
+### macOS / Linux Configuration
+
+Uses settings file paths with `~` expansion:
+
+```json
+{
+  "profiles": {
+    "glm": "~/.ccs/glm.settings.json",
+    "default": "~/.claude/settings.json"
+  }
+}
+```
+
+Each profile points to a Claude settings JSON file. Create settings files per [Claude CLI docs](https://docs.claude.com/en/docs/claude-code/installation).
+
+## Configuration Issues
+
+### Profile not found
+
+```
+Error: Profile 'foo' not found in ~/.ccs/config.json
+```
+
+**Fix**: Add profile to `~/.ccs/config.json`:
+```json
+{
+  "profiles": {
+    "foo": "~/.ccs/foo.settings.json"
+  }
+}
+```
+
+### Settings file missing
+
+```
+Error: Settings file not found: ~/.ccs/foo.settings.json
+```
+
+**Fix**: Create settings file or fix path in config.
+
+### Default profile missing
+
+```
+Error: Profile 'default' not found in ~/.ccs/config.json
+```
+
+**Fix**: Add "default" profile or always specify profile name:
+```json
+{
+  "profiles": {
+    "default": "~/.claude/settings.json"
+  }
+}
+```

docs/contributing.md

@@ -0,0 +1,182 @@
+# CCS Contributing Guide
+
+## Development Guidelines
+
+### Philosophy
+
+CCS follows these core principles:
+
+- **YAGNI**: No features "just in case"
+- **KISS**: Simple bash, no complexity
+- **DRY**: One source of truth (config)
+
+This tool does ONE thing well: map profile names to settings files.
+
+### Code Standards
+
+#### Compatibility Requirements
+
+- **Unix**: bash 3.2+ compatibility
+- **Windows**: PowerShell 5.1+ compatibility
+- **Dependencies**: Only jq (Unix) or built-in PowerShell (Windows)
+
+#### Code Style
+
+**Bash (Unix)**:
+- Use `#!/usr/bin/env bash` shebang
+- Quote variables: `"$VAR"` not `$VAR`
+- Use `[[ ]]` for tests, not `[ ]`
+- Follow existing indentation and naming patterns
+
+**PowerShell (Windows)**:
+- Use `CmdletBinding` and proper parameter handling
+- Follow PowerShell verb-noun convention
+- Use proper error handling with `try/catch`
+- Maintain compatibility with PowerShell 5.1+
+
+### Testing
+
+#### Platform Testing
+
+Test on all platforms before submitting PR:
+- macOS (bash)
+- Linux (bash)
+- Windows (PowerShell, CMD, Git Bash)
+
+#### Test Scenarios
+
+1. **Basic functionality**:
+   ```bash
+   ccs            # Should use default profile
+   ccs glm        # Should use GLM profile
+   ccs --version  # Should show version
+   ```
+
+2. **With arguments**:
+   ```bash
+   ccs glm --help
+   ccs /plan "test"
+   ```
+
+3. **Error handling**:
+   ```bash
+   ccs invalid-profile    # Should show error
+   ccs --invalid-flag     # Should pass through to Claude
+   ```
+
+### Submission Process
+
+#### Before Submitting
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes
+4. Test on all platforms
+5. Ensure existing tests pass
+
+#### Pull Request Requirements
+
+- Clear description of changes
+- Testing instructions if applicable
+- Link to relevant issues
+- Follow existing commit message style
+
+#### Commit Message Style
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+Examples:
+```
+fix(installer): handle git worktree detection
+feat(config): support custom config location
+docs(readme): update installation instructions
+```
+
+### Development Setup
+
+#### Local Development
+
+```bash
+# Clone your fork
+git clone https://github.com/yourusername/ccs.git
+cd ccs
+
+# Create feature branch
+git checkout -b your-feature-name
+
+# Make changes
+# Test locally with ./ccs
+
+# Run tests
+./test.sh  # if available
+```
+
+#### Testing Installer
+
+```bash
+# Test Unix installer
+./installers/install.sh
+
+# Test Windows installer (in PowerShell)
+.\installers\install.ps1
+```
+
+### Areas for Contribution
+
+#### Wanted Features
+
+1. **Additional profile support**:
+   - Custom profile validation
+   - Profile switching shortcuts
+
+2. **Enhanced error handling**:
+   - Better error messages
+   - Recovery suggestions
+
+3. **Documentation**:
+   - More examples
+   - Integration guides
+
+#### Bug Fixes
+
+- Installer issues on different platforms
+- Edge cases in config parsing
+- Windows-specific compatibility
+
+### Review Process
+
+1. **Automated checks**:
+   - Syntax validation
+   - Basic functionality tests
+
+2. **Manual review**:
+   - Code quality and style
+   - Platform compatibility
+   - Philosophy alignment
+
+3. **Testing**:
+   - Cross-platform verification
+   - Integration testing
+
+### Community
+
+#### Getting Help
+
+- GitHub Issues: Report bugs or request features
+- Discussions: Ask questions or share ideas
+
+#### Code of Conduct
+
+Be respectful, constructive, and focused on the project's philosophy of simplicity and reliability.
+
+---
+
+**Thank you for contributing to CCS!**
+
+Remember: Keep it simple, test thoroughly, and stay true to the YAGNI/KISS/DRY philosophy.

docs/installation.md

@@ -0,0 +1,139 @@
+# CCS Installation Guide
+
+## One-Liner Installation (Recommended)
+
+### macOS / Linux
+
+```bash
+# Short URL (via CloudFlare)
+curl -fsSL ccs.kaitran.ca/install | bash
+
+# Or direct from GitHub
+curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.sh | bash
+```
+
+### Windows PowerShell
+
+```powershell
+# Short URL (via CloudFlare)
+irm ccs.kaitran.ca/install.ps1 | iex
+
+# Or direct from GitHub
+irm https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.ps1 | iex
+```
+
+**Note**:
+- Unix installer supports both direct execution (`./install.sh`) and piped installation (`curl | bash`)
+- Windows installer requires PowerShell 5.1+ (pre-installed on Windows 10+)
+
+## Git Clone Installation
+
+### macOS / Linux
+
+```bash
+git clone https://github.com/kaitranntt/ccs.git
+cd ccs
+./installers/install.sh
+```
+
+### Windows PowerShell
+
+```powershell
+git clone https://github.com/kaitranntt/ccs.git
+cd ccs
+.\installers\install.ps1
+```
+
+**Note**: Works with git worktrees and submodules - the installer detects both `.git` directory and `.git` file.
+
+## Manual Installation
+
+### macOS / Linux
+
+```bash
+# Download script
+curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/ccs -o ~/.local/bin/ccs
+chmod +x ~/.local/bin/ccs
+
+# Ensure ~/.local/bin in PATH
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Windows PowerShell
+
+```powershell
+# Create directory
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.ccs"
+
+# Download script
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/kaitranntt/ccs/main/ccs.ps1" -OutFile "$env:USERPROFILE\.ccs\ccs.ps1"
+
+# Add to PATH (restart terminal after)
+$Path = [Environment]::GetEnvironmentVariable("Path", "User")
+[Environment]::SetEnvironmentVariable("Path", "$Path;$env:USERPROFILE\.ccs", "User")
+```
+
+## What Gets Installed
+
+```bash
+~/.ccs/
+├── ccs                     # Main executable
+├── config.json             # Profile configuration
+├── glm.settings.json       # GLM profile
+└── .claude/                # Claude Code integration
+    ├── commands/ccs.md     # /ccs meta-command
+    └── skills/             # Delegation skills
+```
+
+## Upgrade CCS
+
+### macOS / Linux
+
+```bash
+# From git clone
+cd ccs && git pull && ./install.sh
+
+# From curl install
+curl -fsSL ccs.kaitran.ca/install | bash
+```
+
+### Windows PowerShell
+
+```powershell
+# From git clone
+cd ccs
+git pull
+.\install.ps1
+
+# From irm install
+irm ccs.kaitran.ca/install.ps1 | iex
+```
+
+## Requirements
+
+### macOS / Linux
+- `bash` 3.2+
+- `jq` (JSON processor)
+- [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation)
+
+### Windows
+- PowerShell 5.1+ (pre-installed on Windows 10+)
+- [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation)
+
+### Installing jq (macOS / Linux only)
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt install jq
+
+# Fedora
+sudo dnf install jq
+
+# Arch
+sudo pacman -S jq
+```
+
+**Note**: Windows version uses PowerShell's built-in JSON support - no jq required.

docs/troubleshooting.md

@@ -0,0 +1,180 @@
+# CCS Troubleshooting Guide
+
+## Windows-Specific Issues
+
+### PowerShell Execution Policy
+
+If you see "cannot be loaded because running scripts is disabled":
+
+```powershell
+# Check current policy
+Get-ExecutionPolicy
+
+# Allow current user to run scripts (recommended)
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Or run with bypass (one-time)
+powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.ccs\ccs.ps1" glm
+```
+
+### PATH not updated (Windows)
+
+If `ccs` command not found after installation:
+
+1. Restart your terminal
+2. Or manually add to PATH:
+   - Open "Edit environment variables for your account"
+   - Add `%USERPROFILE%\.ccs` to User PATH
+   - Restart terminal
+
+### Claude CLI not found (Windows)
+
+```powershell
+# Check Claude CLI
+where.exe claude
+
+# If missing, install from Claude docs
+```
+
+## Installation Issues
+
+### BASH_SOURCE unbound variable error
+
+This error occurs when running the installer in some shells or environments.
+
+**Fixed in latest version**: The installer now handles both piped execution (`curl | bash`) and direct execution (`./install.sh`).
+
+**Solution**: Upgrade to the latest version:
+```bash
+curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.sh | bash
+```
+
+### Git worktree not detected
+
+If installing from a git worktree or submodule, older versions may fail to detect the git repository.
+
+**Fixed in latest version**: The installer now detects both `.git` directory (standard clone) and `.git` file (worktree/submodule).
+
+**Solution**: Upgrade to the latest version or use the curl installation method.
+
+## Configuration Issues
+
+### Profile not found
+
+```
+Error: Profile 'foo' not found in ~/.ccs/config.json
+```
+
+**Fix**: Add profile to `~/.ccs/config.json`:
+```json
+{
+  "profiles": {
+    "foo": "~/.ccs/foo.settings.json"
+  }
+}
+```
+
+### Settings file missing
+
+```
+Error: Settings file not found: ~/.ccs/foo.settings.json
+```
+
+**Fix**: Create settings file or fix path in config.
+
+### jq not installed
+
+```
+Error: jq is required but not installed
+```
+
+**Fix**: Install jq (see installation guide).
+
+**Note**: The installer creates basic templates even without jq, but enhanced features require jq.
+
+## Environment Issues
+
+### PATH not set
+
+```
+⚠️  Warning: ~/.local/bin is not in PATH
+```
+
+**Fix**: Add to `~/.bashrc` or `~/.zshrc`:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+Then `source ~/.bashrc` or restart shell.
+
+### Default profile missing
+
+```
+Error: Profile 'default' not found in ~/.ccs/config.json
+```
+
+**Fix**: Add "default" profile or always specify profile name:
+```json
+{
+  "profiles": {
+    "default": "~/.claude/settings.json"
+  }
+}
+```
+
+## Common Problems
+
+### Claude CLI not found
+
+```
+Error: claude command not found
+```
+
+**Solution**: Install Claude CLI from [official documentation](https://docs.claude.com/en/docs/claude-code/installation).
+
+### Permission denied (Unix)
+
+```
+Error: Permission denied: ~/.local/bin/ccs
+```
+
+**Solution**: Make the script executable:
+```bash
+chmod +x ~/.local/bin/ccs
+```
+
+### Config file not found
+
+```
+Error: Config file not found: ~/.ccs/config.json
+```
+
+**Solution**: Re-run installer or create config manually:
+```bash
+mkdir -p ~/.ccs
+echo '{"profiles":{"default":"~/.claude/settings.json"}}' > ~/.ccs/config.json
+```
+
+## Getting Help
+
+If you encounter issues not covered here:
+
+1. Check the [GitHub Issues](https://github.com/kaitranntt/ccs/issues)
+2. Create a new issue with:
+   - Your operating system
+   - CCS version (`ccs --version`)
+   - Exact error message
+   - Steps to reproduce
+
+## Debug Mode
+
+Enable verbose output to troubleshoot issues:
+
+```bash
+ccs --verbose glm
+```
+
+This will show:
+- Which config file is being read
+- Which profile is being selected
+- Which settings file is being used
+- The exact command being executed

docs/usage.md

@@ -0,0 +1,157 @@
+# CCS Usage Guide
+
+## Why CCS?
+
+**Built for developers with both Claude subscription and GLM Coding Plan.**
+
+### Two Real Use Cases
+
+#### 1. Task-Appropriate Model Selection
+
+**Claude Sonnet 4.5** excels at:
+- Complex architectural decisions
+- System design and planning
+- Debugging tricky issues
+- Code reviews requiring deep reasoning
+
+**GLM 4.6** works great for:
+- Simple bug fixes
+- Straightforward implementations
+- Routine refactoring
+- Documentation writing
+
+**With CCS**: Switch models based on task complexity, maximize quality while managing costs.
+
+```bash
+ccs           # Planning new feature architecture
+# Got the plan? Implement with GLM:
+ccs glm       # Write the straightforward code
+```
+
+#### 2. Rate Limit Management
+
+If you have both Claude subscription and GLM Coding Plan, you know the pain:
+- Claude hits rate limit mid-project
+- You manually copy GLM config to `~/.claude/settings.json`
+- 5 minutes later, need to switch back
+- Repeat 10x per day
+
+**CCS solves this**:
+- One command to switch: `ccs` (default) or `ccs glm` (fallback)
+- Keep both configs saved as profiles
+- Switch in <1 second
+- No file editing, no copy-paste, no mistakes
+
+### Features
+
+- Instant profile switching (Claude ↔ GLM)
+- Pass-through all Claude CLI args
+- Smart setup: detects your current provider
+- Auto-creates configs during install
+- No proxies, no magic—just bash + jq
+
+## Basic Usage
+
+### Switching Profiles
+
+```bash
+# Works on macOS, Linux, and Windows
+ccs           # Use Claude subscription (default)
+ccs glm       # Use GLM fallback
+```
+
+**Windows Note**: Commands work identically in PowerShell, CMD, and Git Bash.
+
+### With Arguments
+
+All args after profile name pass directly to Claude CLI:
+
+```bash
+ccs glm --verbose
+ccs /plan "add feature"
+ccs glm /code "implement feature"
+```
+
+### Utility Commands
+
+```bash
+ccs --version    # Show CCS version
+ccs --help       # Show Claude CLI help
+```
+
+## Task Delegation
+
+**CCS includes intelligent task delegation** via the `/ccs` meta-command:
+
+```bash
+# Delegate planning to GLM (saves Sonnet tokens)
+/ccs glm /plan "add user authentication"
+
+# Delegate coding to GLM
+/ccs glm /code "implement auth endpoints"
+
+# Quick questions with Haiku
+/ccs haiku /ask "explain this error"
+```
+
+**Benefits**:
+- ✅ Save tokens by delegating simple tasks to cheaper models
+- ✅ Use right model for each task automatically
+- ✅ Reusable commands across all projects (user-scope)
+- ✅ Seamless integration with existing workflows
+
+## Real Workflows
+
+### Task-Based Model Selection
+
+**Scenario**: Building a new payment integration feature
+
+```bash
+# Step 1: Architecture & Planning (needs Claude's intelligence)
+ccs
+/plan "Design payment integration with Stripe, handle webhooks, errors, retries"
+# → Claude Sonnet 4.5 thinks deeply about edge cases, security, architecture
+
+# Step 2: Implementation (straightforward coding, use GLM)
+ccs glm
+/code "implement the payment webhook handler from the plan"
+# → GLM 4.6 writes the code efficiently, saves Claude usage
+
+# Step 3: Code Review (needs deep analysis)
+ccs
+/review "check the payment handler for security issues"
+# → Claude Sonnet 4.5 catches subtle vulnerabilities
+
+# Step 4: Bug Fixes (simple)
+ccs glm
+/fix "update error message formatting"
+# → GLM 4.6 handles routine fixes
+```
+
+**Result**: Best model for each task, lower costs, better quality.
+
+### Rate Limit Management
+
+```bash
+# Working on complex refactoring with Claude
+ccs
+/plan "refactor authentication system"
+
+# Claude hits rate limit mid-task
+# → Error: Rate limit exceeded
+
+# Switch to GLM instantly
+ccs glm
+# Continue working without interruption
+
+# Rate limit resets? Switch back
+ccs
+```
+
+## How It Works
+
+1. Reads profile name (defaults to "default" if omitted)
+2. Looks up settings file path in `~/.ccs/config.json`
+3. Executes `claude --settings <path> [remaining-args]`
+
+No magic. No file modification. Pure delegation. Works identically across all platforms.

docs/version-management.md

@@ -43,7 +43,6 @@ This updates:
 - VERSION file
 - installers/install.sh (hardcoded version)
 - installers/install.ps1 (hardcoded version)
-- Creates git tag (if in git repo)
 
 ### Manual Method
 
@@ -68,12 +67,11 @@ If updating manually, update version in ALL three locations:
 
 When releasing a new version:
 
-- [ ] Update version using `./scripts/update-version.sh X.Y.Z`
+- [ ] Update version using `./scripts/bump-version.sh X.Y.Z`
 - [ ] Review changes: `git diff`
 - [ ] Update CHANGELOG.md with release notes
 - [ ] Commit changes: `git commit -am "chore: bump version to X.Y.Z"`
-- [ ] Create tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
-- [ ] Push: `git push && git push --tags`
+- [ ] Push: `git push`
 - [ ] Verify CloudFlare worker serves updated installer
 
 ## Version Display