o-switcher 0.1.0

package/docs/architecture.md

@@ -0,0 +1,511 @@
+# O-Switcher Architecture
+
+## C4 Level 1: System Context
+
+Who uses O-Switcher and what it connects to.
+
+```mermaid
+C4Context
+    title O-Switcher — System Context
+
+    Person(developer, "Developer", "Uses OpenCode for AI-assisted coding")
+    
+    System(opencode, "OpenCode Runtime", "AI coding assistant with plugin system")
+    System(oswitcher, "O-Switcher", "Routing and execution resilience layer. Routes LLM requests to healthy targets with retry, failover, and circuit breaking")
+    
+    System_Ext(anthropic, "Anthropic API", "Claude models")
+    System_Ext(openai, "OpenAI API", "GPT models")
+    System_Ext(google, "Google AI API", "Gemini models")
+    System_Ext(bedrock, "AWS Bedrock", "Multi-provider gateway")
+    
+    Rel(developer, opencode, "Writes code with", "CLI / IDE")
+    Rel(opencode, oswitcher, "Routes LLM requests through", "Plugin hooks / SDK")
+    Rel(oswitcher, anthropic, "Sends requests", "HTTPS")
+    Rel(oswitcher, openai, "Sends requests", "HTTPS")
+    Rel(oswitcher, google, "Sends requests", "HTTPS")
+    Rel(oswitcher, bedrock, "Sends requests", "HTTPS")
+```
+
+## C4 Level 2: Container
+
+Internal modules of O-Switcher.
+
+```mermaid
+C4Container
+    title O-Switcher — Containers
+
+    Person(developer, "Developer")
+    System_Ext(opencode, "OpenCode Runtime")
+
+    Container_Boundary(oswitcher, "O-Switcher") {
+        Container(plugin, "Plugin Entry", "TypeScript", "chat.params + event hooks. Entry point for OpenCode plugin system")
+        Container(config, "Config & Registry", "Zod 4", "Config validation, target registry with health scores and state")
+        Container(errors, "Error Classifier", "TypeScript", "10 error classes, dual-mode: direct HTTP + heuristic events")
+        Container(routing, "Routing Engine", "cockatiel + p-queue", "Policy engine, circuit breaker, admission control, failover orchestrator")
+        Container(execution, "Execution Layer", "TypeScript", "Mode adapters, stream stitcher, audit collector")
+        Container(operator, "Operator Surface", "TypeScript", "7 runtime commands, config reload, server auth")
+        Container(audit, "Audit Trail", "pino", "Structured NDJSON logs with request correlation and credential redaction")
+    }
+
+    System_Ext(providers, "LLM Providers", "Anthropic, OpenAI, Google, Bedrock")
+
+    Rel(developer, opencode, "Uses")
+    Rel(opencode, plugin, "Loads plugin", "chat.params / event hooks")
+    Rel(plugin, config, "Reads config")
+    Rel(plugin, routing, "Routes requests")
+    Rel(routing, errors, "Classifies failures")
+    Rel(routing, execution, "Dispatches to adapter")
+    Rel(execution, providers, "HTTP/SSE requests")
+    Rel(execution, audit, "Emits audit events")
+    Rel(operator, config, "Reloads config")
+    Rel(operator, routing, "Pauses/drains targets")
+```
+
+## C4 Level 3: Components — Routing Engine
+
+The core decision-making layer.
+
+```mermaid
+C4Component
+    title O-Switcher — Routing Engine Components
+
+    Container_Boundary(routing, "Routing Engine") {
+        Component(policy, "Policy Engine", "selectTarget()", "Filter-then-score: 7 exclusion types, weighted scoring, deterministic tie-breaking")
+        Component(circuit, "Circuit Breaker", "cockatiel wrapper", "Dual-trigger hysteresis: consecutive failures + sliding window rate. Per-target FSM: Closed → Open → HalfOpen")
+        Component(admission, "Admission Controller", "p-queue", "3-layer: hard reject → backpressure detection → concurrency gating")
+        Component(failover, "Failover Orchestrator", "nested loops", "Outer: failover across targets (budget=2). Inner: retry per target (budget=3). Max 6 attempts")
+        Component(cooldown, "Cooldown Manager", "adaptive", "Retry-After priority, error-class-specific duration, 10-25% jitter")
+        Component(concurrency, "Concurrency Tracker", "Map-based", "Per-target in-flight count with acquire/release/headroom")
+        Component(events, "Event Bus", "eventemitter3", "Typed events: circuit_state_change, target_excluded, health_updated, admission_decision, cooldown_set/expired")
+    }
+
+    Container_Ext(registry, "Target Registry")
+    Container_Ext(classifier, "Error Classifier")
+    Container_Ext(executor, "Execution Layer")
+
+    Rel(admission, policy, "Selects target via")
+    Rel(failover, policy, "Re-selects on failover")
+    Rel(failover, circuit, "Records success/failure")
+    Rel(failover, cooldown, "Sets cooldown on RateLimited")
+    Rel(policy, registry, "Reads target state")
+    Rel(policy, circuit, "Checks allowRequest()")
+    Rel(circuit, events, "Emits state changes")
+    Rel(admission, events, "Emits admission decisions")
+    Rel(cooldown, events, "Emits cooldown set/expired")
+    Rel(failover, classifier, "Classifies errors")
+    Rel(failover, executor, "Calls AttemptFn")
+```
+
+## C4 Level 3: Components — Execution Layer
+
+Stream handling and audit.
+
+```mermaid
+C4Component
+    title O-Switcher — Execution Layer Components
+
+    Container_Boundary(execution, "Execution Layer") {
+        Component(orchestrator, "Execution Orchestrator", "createExecutionOrchestrator()", "Wires adapter + failover + stitcher + audit. Produces ExecutionResult with provenance")
+        Component(adapters, "Mode Adapters", "plugin / server / SDK", "Three implementations of ModeAdapter interface. Plugin: heuristic detection. Server/SDK: direct HTTP")
+        Component(factory, "Adapter Factory", "createAdapterFactory()", "Selects adapter by DeploymentMode detected at startup")
+        Component(buffer, "Stream Buffer", "createStreamBuffer()", "Append-only chunk accumulator. Tracks confirmed boundary for resume")
+        Component(stitcher, "Stream Stitcher", "createStreamStitcher()", "Multi-segment assembly with provenance metadata and continuation boundaries")
+        Component(collector, "Audit Collector", "createAuditCollector()", "Accumulates attempts + segments, flushes to pino NDJSON on request completion")
+    }
+
+    Container_Ext(failover, "Failover Orchestrator")
+    Container_Ext(providers, "LLM Providers")
+    Container_Ext(pino, "Pino Logger")
+
+    Rel(orchestrator, factory, "Gets adapter for mode")
+    Rel(orchestrator, failover, "Runs retry-failover loop")
+    Rel(orchestrator, stitcher, "Assembles segments")
+    Rel(orchestrator, collector, "Records audit trail")
+    Rel(adapters, providers, "HTTP/SSE requests")
+    Rel(adapters, buffer, "Appends chunks")
+    Rel(collector, pino, "Flushes NDJSON")
+    Rel(stitcher, buffer, "Reads confirmed chunks")
+```
+
+## Sequence: Happy Path (Success on First Target)
+
+```mermaid
+sequenceDiagram
+    participant OC as OpenCode
+    participant PL as Plugin (chat.params)
+    participant AD as Admission Controller
+    participant PE as Policy Engine
+    participant CB as Circuit Breaker
+    participant EX as Executor
+    participant PR as LLM Provider
+    participant AU as Audit Collector
+
+    OC->>PL: chat.params hook (model, provider, message)
+    PL->>AD: admit(request_id, context)
+    AD->>AD: checkHardRejects() → pass
+    AD->>AD: backpressure check → ok
+    AD-->>PL: admitted
+
+    PL->>PE: selectTarget(snapshot, capabilities)
+    PE->>PE: filter: 7 exclusion checks
+    PE->>CB: allowRequest(target-1)?
+    CB-->>PE: true (Closed)
+    PE->>PE: score: w1*health - w2*latency - w3*failure + w4*priority
+    PE-->>PL: SelectionRecord {selected: target-1, score: 0.85}
+
+    PL->>EX: execute(target-1, request)
+    EX->>PR: HTTP POST /chat/completions
+    PR-->>EX: 200 OK (streaming chunks)
+    EX->>EX: StreamBuffer.append(chunks)
+    EX-->>PL: success {value, latency_ms: 1200}
+
+    PL->>CB: recordSuccess()
+    PL->>AU: recordAttempt(target-1, success)
+    AU->>AU: flush to pino NDJSON
+
+    PL-->>OC: output (params unchanged, target healthy)
+```
+
+## Sequence: Retry + Failover
+
+```mermaid
+sequenceDiagram
+    participant OC as OpenCode
+    participant FO as Failover Orchestrator
+    participant PE as Policy Engine
+    participant CB as Circuit Breaker
+    participant EX as Executor
+    participant T1 as Target 1 (Anthropic)
+    participant T2 as Target 2 (OpenAI)
+    participant CD as Cooldown Manager
+    participant AU as Audit
+
+    OC->>FO: execute(request)
+    
+    Note over FO: Outer loop: failover_no=0
+
+    FO->>PE: selectTarget(exclude: ∅)
+    PE-->>FO: target-1 (score: 0.85)
+    
+    Note over FO: Inner loop: attempt 1/3
+
+    FO->>EX: attemptFn(target-1)
+    EX->>T1: POST /chat
+    T1-->>EX: 429 Too Many Requests (Retry-After: 5s)
+    EX-->>FO: fail {error_class: RateLimited, retry_after_ms: 5000}
+
+    FO->>CB: recordFailure(target-1)
+    FO->>CD: setCooldown(target-1, 5500ms)
+    FO->>AU: recordAttempt(retry)
+
+    Note over FO: Inner loop: attempt 2/3 (after backoff)
+
+    FO->>EX: attemptFn(target-1)
+    EX->>T1: POST /chat
+    T1-->>EX: 429 Too Many Requests
+    EX-->>FO: fail {error_class: RateLimited}
+
+    FO->>CB: recordFailure(target-1)
+    FO->>AU: recordAttempt(retry)
+
+    Note over FO: Inner loop: attempt 3/3
+
+    FO->>EX: attemptFn(target-1)
+    EX->>T1: POST /chat
+    T1-->>EX: 429 Too Many Requests
+    EX-->>FO: fail {error_class: RateLimited}
+
+    FO->>CB: recordFailure(target-1)
+    FO->>AU: recordAttempt(failover)
+
+    Note over FO: Retry budget exhausted → FAILOVER<br/>Outer loop: failover_no=1
+
+    FO->>PE: selectTarget(exclude: {target-1})
+    PE-->>FO: target-2 (score: 0.72)
+
+    Note over FO: Inner loop: attempt 1/3
+
+    FO->>EX: attemptFn(target-2)
+    EX->>T2: POST /chat
+    T2-->>EX: 200 OK (streaming)
+    EX-->>FO: success {value, latency_ms: 800}
+
+    FO->>CB: recordSuccess(target-2)
+    FO->>AU: recordAttempt(success)
+    FO-->>OC: FailoverResult {outcome: success, target: target-2, retries: 3, failovers: 1}
+```
+
+## Sequence: Stream Interruption + Resume
+
+```mermaid
+sequenceDiagram
+    participant FO as Failover Orchestrator
+    participant EX as Executor
+    participant BF as Stream Buffer
+    participant T1 as Target 1
+    participant T2 as Target 2
+    participant ST as Stream Stitcher
+    participant AU as Audit
+
+    FO->>EX: attemptFn(target-1)
+    EX->>T1: POST /chat (streaming)
+    
+    T1-->>EX: chunk 1: "Here is the"
+    EX->>BF: append(chunk 1) ✓ confirmed
+    T1-->>EX: chunk 2: " implementation"
+    EX->>BF: append(chunk 2) ✓ confirmed
+    T1-->>EX: chunk 3: " of the"
+    EX->>BF: append(chunk 3) ✓ confirmed
+    T1--xEX: CONNECTION RESET (stream interrupted)
+
+    EX-->>FO: fail {error_class: InterruptedExecution}
+    
+    Note over BF: confirmed: "Here is the implementation of the"<br/>confirmedCharCount: 34
+
+    FO->>ST: addSegment(segment_id=0, buffer, target-1, "same_target_resume")
+    FO->>AU: recordAttempt(failover, InterruptedExecution)
+
+    Note over FO: FAILOVER → target-2
+
+    FO->>EX: attemptFn(target-2)
+    EX->>T2: POST /chat (with context: continue from "...of the")
+    T2-->>EX: chunk 4: " sorting algorithm"
+    EX->>BF: append(chunk 4) ✓ confirmed
+    T2-->>EX: chunk 5: " using quicksort..."
+    EX->>BF: append(chunk 5) ✓ confirmed
+    T2-->>EX: [DONE]
+    EX-->>FO: success
+
+    FO->>ST: addSegment(segment_id=1, buffer, target-2, "cross_model_continuation")
+    
+    ST->>ST: assemble()
+    Note over ST: StitchedOutput:<br/>text: "Here is the implementation of the[→target-2] sorting algorithm using quicksort..."<br/>segments: [{target-1, chars 0-34}, {target-2, chars 34-72}]<br/>continuation_boundaries: [{offset: 34, non_deterministic: true}]
+
+    FO->>AU: flush(request_id, 2 segments, 2 targets)
+```
+
+## Sequence: Circuit Breaker State Transitions
+
+```mermaid
+sequenceDiagram
+    participant RQ as Requests
+    participant CB as Circuit Breaker
+    participant DB as DualBreaker
+    participant EB as Event Bus
+
+    Note over CB: State: CLOSED (Active)
+
+    RQ->>CB: recordFailure()
+    CB->>DB: failure(Closed) → false (1/5 consecutive)
+    RQ->>CB: recordFailure()
+    CB->>DB: failure(Closed) → false (2/5)
+    RQ->>CB: recordFailure()
+    CB->>DB: failure(Closed) → false (3/5)
+    RQ->>CB: recordFailure()
+    CB->>DB: failure(Closed) → false (4/5)
+    RQ->>CB: recordFailure()
+    CB->>DB: failure(Closed) → TRUE (5/5 consecutive threshold!)
+
+    CB->>EB: emit circuit_state_change {from: Active, to: CircuitOpen}
+
+    Note over CB: State: OPEN (CircuitOpen)<br/>Rejects all requests for 30s
+
+    RQ->>CB: allowRequest() → false ❌
+    RQ->>CB: allowRequest() → false ❌
+
+    Note over CB: 30 seconds pass (half_open_after_ms)
+
+    Note over CB: State: HALF-OPEN (CircuitHalfOpen)<br/>Allows 1 probe request
+
+    RQ->>CB: allowRequest() → true ✓ (probe)
+    RQ->>CB: recordSuccess()
+    CB->>DB: success(HalfOpen)
+
+    CB->>EB: emit circuit_state_change {from: CircuitHalfOpen, to: Active}
+
+    Note over CB: State: CLOSED (Active)<br/>Normal routing resumed
+```
+
+## Sequence: Admission Control Flow
+
+```mermaid
+sequenceDiagram
+    participant RQ as Request
+    participant AC as Admission Controller
+    participant HR as Hard Reject Layer
+    participant BP as Backpressure Layer
+    participant PQ as p-queue Layer
+
+    RQ->>AC: admit(request_id, context)
+
+    AC->>HR: checkHardRejects(context)
+    
+    alt No eligible targets
+        HR-->>AC: REJECTED "no eligible targets"
+        AC-->>RQ: ❌ rejected
+    else Operator paused
+        HR-->>AC: REJECTED "operator pause active"
+        AC-->>RQ: ❌ rejected
+    else Budgets exhausted
+        HR-->>AC: REJECTED "retry/failover budget exhausted"
+        AC-->>RQ: ❌ rejected
+    else All checks pass
+        HR-->>AC: null (no hard reject)
+    end
+
+    AC->>BP: check queue.size > backpressure_threshold?
+    
+    alt Queue depth > threshold
+        BP-->>AC: DEGRADED "backpressure: N pending > threshold"
+        AC-->>RQ: ⚠️ degraded (still executes, but signals pressure)
+    else Queue normal
+        BP-->>AC: ok
+    end
+
+    AC->>PQ: check total capacity
+    
+    alt Queue full (size >= queueLimit + concurrencyLimit)
+        PQ-->>AC: REJECTED "queue full"
+        AC-->>RQ: ❌ rejected
+    else Capacity available
+        PQ-->>AC: ADMITTED
+        AC-->>RQ: ✅ admitted
+    end
+```
+
+## Data Flow: Request Lifecycle
+
+```mermaid
+flowchart TD
+    A[OpenCode sends request] --> B{Admission Control}
+    B -->|rejected| Z[Return error to user]
+    B -->|degraded| C[Select Target with degraded flag]
+    B -->|admitted| C
+    
+    C --> D[Policy Engine: filter + score]
+    D --> E{Eligible targets?}
+    E -->|none| Z
+    E -->|found| F[Best target selected]
+    
+    F --> G[Execute via Mode Adapter]
+    G --> H{Result?}
+    
+    H -->|success| I[Record success on circuit breaker]
+    I --> J[Update health score +1]
+    J --> K[Flush audit trail]
+    K --> L[Return result with provenance]
+    
+    H -->|RateLimited| M[Set adaptive cooldown]
+    M --> N{Retry budget left?}
+    N -->|yes| O[Backoff + retry same target]
+    O --> G
+    N -->|no| P{Failover budget left?}
+    
+    H -->|ModelUnavailable| P
+    
+    H -->|TransientServerFailure| N
+    
+    H -->|AuthFailure / PermissionFailure| Q[Abort immediately]
+    Q --> R[Update target state]
+    R --> K
+    
+    P -->|yes| S[Exclude failed target]
+    S --> D
+    P -->|no| T[All budgets exhausted]
+    T --> K
+    
+    H -->|InterruptedExecution| U[Save confirmed chunks to buffer]
+    U --> V[Record segment provenance]
+    V --> P
+
+    style Z fill:#f66,color:#fff
+    style L fill:#6f6,color:#000
+    style Q fill:#f66,color:#fff
+    style T fill:#f96,color:#000
+```
+
+## Module Dependency Graph
+
+```mermaid
+graph TB
+    subgraph "Layer 4: Entry Points"
+        plugin[src/plugin.ts<br/>OpenCode Plugin Entry]
+    end
+
+    subgraph "Layer 3: Operator Surface"
+        commands[operator/commands.ts<br/>7 operator commands]
+        reload[operator/reload.ts<br/>Config reload diff-apply]
+        tools[operator/plugin-tools.ts<br/>Plugin tool wrappers]
+        auth[operator/server-auth.ts<br/>Bearer token auth]
+    end
+
+    subgraph "Layer 2: Execution"
+        orchestrator[execution/orchestrator.ts<br/>Execution orchestrator]
+        adapters[execution/adapters/<br/>Plugin / Server / SDK]
+        stitcher[execution/stream-stitcher.ts<br/>Multi-segment assembly]
+        buffer[execution/stream-buffer.ts<br/>Chunk buffer]
+        collector[execution/audit-collector.ts<br/>Audit collector]
+    end
+
+    subgraph "Layer 1: Routing (pure functions)"
+        policy[routing/policy-engine.ts<br/>Filter-then-score]
+        failover[routing/failover.ts<br/>Nested retry-failover]
+        admission[routing/admission.ts<br/>Layered admission]
+        cb[routing/circuit-breaker.ts<br/>Circuit breaker FSM]
+        cooldown[routing/cooldown.ts<br/>Adaptive cooldown]
+        concurrency[routing/concurrency-tracker.ts<br/>Per-target tracking]
+        events[routing/events.ts<br/>Typed event bus]
+    end
+
+    subgraph "Layer 0: Foundation"
+        config[config/schema.ts<br/>Zod validation]
+        registry[registry/registry.ts<br/>Target state]
+        errors[errors/taxonomy.ts<br/>10 error classes]
+        classifier[errors/classifier.ts<br/>Dual-mode classifier]
+        retry[retry/retry-policy.ts<br/>Bounded retry]
+        backoff[retry/backoff.ts<br/>Exponential backoff]
+        logger[audit/logger.ts<br/>Pino + redaction]
+        mode[mode/types.ts<br/>Deployment modes]
+    end
+
+    plugin --> orchestrator
+    plugin --> commands
+    plugin --> config
+
+    commands --> registry
+    reload --> config
+    reload --> registry
+    tools --> commands
+    auth -.-> tools
+
+    orchestrator --> failover
+    orchestrator --> adapters
+    orchestrator --> stitcher
+    orchestrator --> collector
+    adapters --> buffer
+
+    failover --> policy
+    failover --> cb
+    failover --> cooldown
+    failover --> concurrency
+    admission --> policy
+    policy --> registry
+    policy --> cb
+    cb --> events
+    cooldown --> events
+    cooldown --> backoff
+
+    failover --> retry
+    failover --> errors
+    retry --> backoff
+    classifier --> errors
+
+    collector --> logger
+    orchestrator --> logger
+
+    style plugin fill:#4a9eff,color:#fff
+    style policy fill:#2ecc71,color:#fff
+    style failover fill:#2ecc71,color:#fff
+    style cb fill:#e74c3c,color:#fff
+    style registry fill:#f39c12,color:#fff
+    style logger fill:#9b59b6,color:#fff

package/docs/examples.md

@@ -0,0 +1,190 @@
+# Examples
+
+## Basic: Just Add the Plugin
+
+```json
+{
+  "plugin": ["@apolenkov/o-switcher@latest"]
+}
+```
+
+That's it. O-Switcher reads your OpenCode providers and handles failures automatically.
+
+## Multiple API Keys (Rate Limit Distribution)
+
+Register the same provider multiple times in `opencode.json`:
+
+```json
+{
+  "provider": {
+    "openai-work": {
+      "api": "openai",
+      "apiKey": "sk-proj-work-111..."
+    },
+    "openai-personal": {
+      "api": "openai",
+      "apiKey": "sk-proj-personal-222..."
+    },
+    "openai-backup": {
+      "api": "openai",
+      "apiKey": "sk-proj-backup-333..."
+    }
+  },
+  "plugin": ["@apolenkov/o-switcher@latest"]
+}
+```
+
+When `work` key hits rate limit → switches to `personal` → then `backup`.
+
+## Multiple Providers (Cross-Provider Failover)
+
+```json
+{
+  "provider": {
+    "anthropic": {
+      "apiKey": "sk-ant-..."
+    },
+    "openai": {
+      "apiKey": "sk-proj-..."
+    }
+  },
+  "plugin": ["@apolenkov/o-switcher@latest"]
+}
+```
+
+If Anthropic is down → requests go to OpenAI. Note: in plugin-only mode, cross-provider failover is limited to parameter adjustment. Full cross-provider redirect requires server-companion mode.
+
+## Custom Retry Settings
+
+```json
+{
+  "plugin": ["@apolenkov/o-switcher@latest"],
+  "switcher": {
+    "retry": 5,
+    "timeout": 60000
+  }
+}
+```
+
+5 retry attempts, 60 second timeout.
+
+## Accumulating Keys via CLI
+
+```bash
+# First login — O-Switcher saves the credential
+opencode auth login openai
+
+# Second login — O-Switcher saves the new one too
+# (OpenCode overwrites, but O-Switcher keeps both)
+opencode auth login openai
+
+# Check your profiles
+# In OpenCode, use the profiles-list tool
+```
+
+## Analyzing Logs
+
+O-Switcher logs everything as NDJSON. Pipe through `jq`:
+
+```bash
+# How many failovers today?
+opencode 2>&1 | jq 'select(.msg == "failover_start")' | wc -l
+
+# Which profile gets rate limited most?
+opencode 2>&1 | jq 'select(.event == "cooldown_set") | .target_id' | sort | uniq -c | sort -rn
+
+# Average retries per request
+opencode 2>&1 | jq 'select(.msg == "request_summary") | .total_retries' | awk '{s+=$1; n++} END {print s/n}'
+
+# Circuit breaker flapping (opens and closes)
+opencode 2>&1 | jq 'select(.event == "circuit_state_change") | {target: .target_id, from: .from, to: .to}'
+
+# Requests that failed completely (no successful target)
+opencode 2>&1 | jq 'select(.msg == "request_summary") | select(.outcome == "failure")'
+```
+
+## Manual Target Control
+
+```json
+{
+  "plugin": ["@apolenkov/o-switcher@latest"],
+  "switcher": {
+    "targets": [
+      {
+        "target_id": "claude-primary",
+        "provider_id": "anthropic",
+        "capabilities": ["chat"],
+        "enabled": true,
+        "operator_priority": 10,
+        "policy_tags": ["primary"]
+      },
+      {
+        "target_id": "gpt-backup",
+        "provider_id": "openai",
+        "capabilities": ["chat"],
+        "enabled": true,
+        "operator_priority": 1,
+        "policy_tags": ["backup"]
+      },
+      {
+        "target_id": "gemini-fallback",
+        "provider_id": "google",
+        "capabilities": ["chat"],
+        "enabled": true,
+        "operator_priority": 0,
+        "policy_tags": ["fallback"]
+      }
+    ]
+  }
+}
+```
+
+Priority: Claude (10) → GPT (1) → Gemini (0). Health scores adjust over time.
+
+## Conservative Circuit Breaker
+
+For critical workloads — slower to open, faster to recover:
+
+```json
+{
+  "switcher": {
+    "circuit_breaker": {
+      "failure_threshold": 10,
+      "failure_rate_threshold": 0.7,
+      "sliding_window_size": 20,
+      "half_open_after_ms": 15000,
+      "success_threshold": 1
+    }
+  }
+}
+```
+
+## Aggressive Circuit Breaker
+
+For fast failover — quick to open on failures:
+
+```json
+{
+  "switcher": {
+    "circuit_breaker": {
+      "failure_threshold": 2,
+      "failure_rate_threshold": 0.3,
+      "sliding_window_size": 5,
+      "half_open_after_ms": 5000,
+      "success_threshold": 1
+    }
+  }
+}
+```
+
+## Local Development
+
+```bash
+git clone https://github.com/apolenkov/o-switcher.git
+cd o-switcher
+npm install
+npm run build
+
+# Use local path in your project's opencode.json:
+# "plugin": ["/path/to/o-switcher"]
+```