feat: Add CI/CD, autocompletion, troubleshooting docs, and update README

Author: claudlos

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  test-python:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+        cache: 'pip'
+        
+    - name: Install dependencies
+      run: |
+        cd pipeline
+        python -m pip install --upgrade pip
+        pip install -r requirements-dev.txt
+        pip install -e .
+        
+    - name: Test with pytest
+      run: |
+        cd pipeline
+        pytest tests/ -v -p no:anchorpy --cov=cloding --cov-report=xml

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Deploy VitePress site to Pages
+
+on:
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not configured
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: npm install
+      - name: Build with VitePress
+        run: npm run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pypi.yml

@@ -0,0 +1,36 @@
+name: Publish Python Package to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python distribution to PyPI
+    runs-on: ubuntu-latest
+
+    # Required for PyPI trusted publishing
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install pypa/build
+        run: python -m pip install build --user
+
+      - name: Build a binary wheel and a source tarball
+        run: |
+          cd pipeline
+          python -m build
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: pipeline/dist/

README.md

@@ -11,26 +11,55 @@ Cloding is a universal wrapper that lets you run Claude Code, Gemini CLI, Codex
 ╚█████╔╝███████╗╚█████╔╝██████╔╝██║██║░╚████║╚██████╔╝
 ░╚════╝░╚══════╝░╚════╝░╚═════╝░╚═╝╚═╝░░╚═══╝░╚═════╝
 
+---
+
 **Code with any LLM in a Docker sandbox. Configurable multi-stage code orchestration**
 
-Claude Opus 4.6 costs $5/$25 per Mtok.
-Qwen 3 Coder Next costs $0.12/$0.75 per Mtok.
-That's 42x cheaper on input, 33x cheaper on output.
+Claude Opus 4.6 costs $5/$25 per Mtok.  
+Qwen 3 Coder Next costs $0.12/$0.75 per Mtok.  
+*That's 42x cheaper on input, 33x cheaper on output.*
 
 Run multiple coding CLIs from one command, with model shortcuts and optional pipeline orchestration.
 
-Supported tools:
+**Supported tools:**
 - Claude Code (`claude`)
 - Gemini CLI (`gemini`)
 - Codex CLI (`codex`)
 - GitHub Copilot CLI (`copilot`)
 - OpenCode (`opencode`, via custom model entries)
 
+---
+
+## Capabilities
+
+Cloding enhances your development workflow through:
+
+### Universal Access
+Seamlessly switch between leading AI coding assistants using a single, unified interface.
+
+### Cost Control
+Leverage deeply discounted models via OpenRouter while maintaining high performance. Avoid expensive subscription lock-ins.
+
+### Container Security
+Run AI-generated code safely. The built-in Docker mode executes tools in an isolated sandbox with configurable CPU/memory limits, preventing untrusted code from accessing your host system.
+
+### Advanced Automation
+The Python-based orchestrator enables multi-stage workflows:
+- **Plan:** Analyze requirements and design solutions.
+- **Explore:** Gather context from large codebases.
+- **Code:** Implement the planned changes.
+- **Review:** Automatically verify and refine the code.
+
+### Extensive Documentation
+Read our comprehensive [documentation site](https://claudlos.github.io/cloding/) for in-depth walkthroughs and a dedicated [Troubleshooting guide](https://claudlos.github.io/cloding/troubleshooting).
+
+---
+
 ## Installation
 
-### Standalone Binary (recommended)
+### Standalone Binary (Recommended)
 
-No Node.js required — download a single binary:
+No Node.js required — download a single standalone binary:
 
 **macOS / Linux:**
 
@@ -46,33 +75,50 @@ irm https://raw.githubusercontent.com/claudlos/cloding/master/install.ps1 | iex
 
 ### npm
 
-If you already have Node.js 18+:
+If you already have Node.js 18+ installed:
 
 ```bash
 npm install -g cloding
 ```
 
+**Installing Node.js 18+**  
+If you don't have Node.js installed, you can quickly install the latest version using the following commands:
+
+**macOS / Linux (via nvm):**
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+nvm install node
+```
+
+**Windows (PowerShell via winget):**
+```powershell
+winget install OpenJS.NodeJS
+```
+*(Alternatively, you can download the official installer directly from [nodejs.org](https://nodejs.org/))*
+
+---
+
 ## Quick Start
 
 ```bash
-# Set your OpenRouter API key
+# 1. Set your OpenRouter API key
 export OPENROUTER_API_KEY=sk-or-v1-your-key-here
 
-# Install all CLI tools (Claude Code, Gemini, Codex, Copilot, OpenCode)
+# 2. Install all CLI tools (Claude Code, Gemini, Codex, Copilot, OpenCode)
 cloding setup
 
-# Start coding
+# 3. Start coding!
 cloding
 ```
 
-Basic usage:
+### Basic usage:
 
 ```bash
 cloding                              # interactive (default: qwen)
-cloding -m sonnet                    # choose shortcut
+cloding -m sonnet                    # choose a specific shortcut
 cloding -p "fix failing tests"       # one-shot prompt
 cloding --list-models                # list shortcuts and prices
-cloding -h                           # help
+cloding -h                           # view help
 ```
 
 ## Setup Command

bin/cloding.js

@@ -62,15 +62,20 @@ function forwardSignals(child) {
 // .env loader (no dependencies)
 // ──────────────────────────────────────────────
 function loadEnvFile() {
-  // Search for .env in: cwd, then user home, then cloding package root
+  // Search for .env files in decreasing order of priority. We load them in
+  // reverse so that highest priority (cwd/.env) overwrites global configs.
   const candidates = [
-    path.join(process.cwd(), ".env"),
-    path.join(os.homedir(), ".env"),
     path.join(__dirname, "..", ".env"),
+    path.join(os.homedir(), ".clodingrc"),
+    path.join(os.homedir(), ".env"),
+    path.join(process.cwd(), ".env"),
   ];
 
+  let loadedPaths = [];
+
   for (const envPath of candidates) {
     if (fs.existsSync(envPath)) {
+      loadedPaths.push(envPath);
       const lines = fs.readFileSync(envPath, "utf8").split("\n");
       for (const line of lines) {
         const trimmed = line.trim();
@@ -86,16 +91,15 @@ function loadEnvFile() {
         ) {
           val = val.slice(1, -1);
         }
-        // Don't override existing env vars (check existence, not truthiness —
-        // empty string values like ANTHROPIC_API_KEY="" must be preserved)
+        // Overwrite existing parsed env vars from earlier (lower-priority) files,
+        // but don't overwrite true environment variables passed to the process.
         if (!(key in process.env)) {
           process.env[key] = val;
         }
       }
-      return envPath;
     }
   }
-  return null;
+  return loadedPaths.length > 0 ? loadedPaths : null;
 }
 
 // ──────────────────────────────────────────────
@@ -152,6 +156,8 @@ function parseArgs(argv) {
     docker: false,
     dockerSubcommand: null,
     dockerArgs: [],
+    completion: false,
+    listModelsRaw: false,
     claudeArgs: [], // passthrough args for claude CLI
   };
 
@@ -178,6 +184,11 @@ function parseArgs(argv) {
       break;
     }
 
+    if (arg === "completion") {
+      args.completion = true;
+      break;
+    }
+
     switch (arg) {
       case "-m":
       case "--model":
@@ -198,6 +209,9 @@ function parseArgs(argv) {
       case "--list-models":
         args.listModels = true;
         break;
+      case "--list-models-raw":
+        args.listModelsRaw = true;
+        break;
       case "-v":
       case "--version":
         args.version = true;
@@ -236,6 +250,23 @@ function printVersion() {
   }
 }
 
+function printCompletionScript() {
+  console.log(`_cloding_completion() {
+    local cur prev
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+    if [[ "$prev" == "-m" || "$prev" == "--model" ]]; then
+        COMPREPLY=( $(compgen -W "$(cloding --list-models-raw 2>/dev/null)" -- "$cur") )
+        return 0
+    fi
+    
+    COMPREPLY=( $(compgen -W "docker pipeline setup completion --list-models -h -v -m -p" -- "$cur") )
+}
+complete -F _cloding_completion cloding
+`);
+}
+
 function printHelp() {
   console.log(`
 cloding — Claude Code with any model via OpenRouter
@@ -248,6 +279,7 @@ USAGE:
   cloding setup                      Detect and install all CLI tools
   cloding pipeline "Add auth"        Run the full pipeline (requires Python)
   cloding docker <command>           Docker container management
+  cloding completion                 Print bash/zsh completion script
 
 OPTIONS:
   -m, --model <name|id>   Model shortcut or full OpenRouter model ID
@@ -1392,6 +1424,16 @@ function main() {
     process.exit(0);
   }
 
+  if (args.listModelsRaw) {
+    console.log(Object.keys(models).join(" "));
+    process.exit(0);
+  }
+
+  if (args.completion) {
+    printCompletionScript();
+    process.exit(0);
+  }
+
   // ── Setup mode ──
   if (args.setup) {
     handleSetup(args);

docs/.vitepress/config.mts

@@ -47,6 +47,7 @@ export default defineConfig({
         items: [
           { text: 'CLI Reference', link: '/cli' },
           { text: 'Custom Models', link: '/custom-models' },
+          { text: 'Troubleshooting', link: '/troubleshooting' },
         ]
       }
     ],