# Changelog v0.1.88 - 2026-03-09

## 🎯 Release Overview

This is a significant stability and usability release that combines two important feature branches (0.1.88 + 0.1.89) into a single polished 0.2.0 release. The focus is on hardening the public launcher ecosystem, improving visual feedback through dynamic filter coloring, and delivering robust integration with Crush including proper proxy support and model selection persistence.

## ✨ Major Features

### 🛡️ Hardened Multi-Tool Launcher Ecosystem

**Public Z-Cycle (stable, battle-tested):**
- `OpenCode CLI` (default at startup)
- `OpenCode Desktop`
- `OpenClaw` (autonomous agent daemon)
- `Crush` (with new proxy & config improvements)
- `Goose` (lightweight agent)

**Internal Support (temporarily disabled from public cycle, pending hardening):**
- Aider, Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenHands, Amp, Pi

This narrowing from 13 to 5 public launchers in the Z-cycle reduces user confusion and ensures we only expose flows that have been thoroughly tested and validated in the field.

### 🎨 Dynamic Visual Feedback for Active Filters

**Tier Filter Badges:**
- S+ / S: Bright green [57, 255, 20]
- A+ / A: Gold [255, 224, 130]
- A- / B+: Orange [255, 171, 64]
- B / C: Red / Purple gradients
- Active tier always visible in both header badges and footer hotkeys

**Provider Filter Badges:**
- Each provider (NIM, Groq, Cerebras, etc.) now displays with its brand color
- Active provider instantly recognizable across the table
- Color coding helps users mentally organize multi-provider workflows

### 🧰 Crush Integration Overhaul

**Configuration Improvements:**
- Now writes `config.models.large` with actual selected model ID instead of relying on CLI argument parsing
- Sets `disable_default_providers: true` to force reliance on FCM's configured providers
- Model selection persists across Crush sessions via the config file

**Proxy Awareness:**
- Detects when proxy mode is enabled in Settings
- Routes requests through `http://127.0.0.1:<port>/v1` instead of direct provider
- Properly substitutes auth tokens and base URLs based on proxy vs. direct mode
- Provides user feedback on which config path is active

**Spawn Robustness:**
- Removed `--model` CLI argument (was causing parsing conflicts)
- All configuration now driven through `crush.json` for cleaner process spawning
- Fixed shell spawning: `shell: true` only on Windows; Unix systems use direct spawn

### 🧹 OpenCode Proxy Lifecycle

**New CLI Command:**
- `free-coding-models --clean-proxy` — Remove persisted `fcm-proxy` config from OpenCode safely
- Available in Settings screen (`P` key) under Maintenance

**Opt-In Architecture:**
- Proxy mode disabled by default
- Users explicitly enable in Settings (`P` key) → Proxy settings section
- Control over proxy persistence and preferred port
- `S` in Settings to sync proxy into OpenCode only when explicitly requested

### 📚 Documentation & Help Synchronization

**In-App Help Refreshed:**
- Z-cycle hotkey help now shows only hardened launchers (OpenCode CLI/Desktop, OpenClaw, Crush, Goose)
- CLI flag examples (`--opencode`, `--openclaw`, `--crush`, `--goose`) reflect public set
- Removed references to temporarily disabled launchers (Aider, Claude Code, etc.)

**JSDoc Header Updated:**
- Clarified startup behavior (no menu → direct OpenCode CLI)
- Documented ping cadence states: 2s startup burst (60s), 10s steady state, 30s idle fallback, forced 4s via W
- Removed "promptModeSelection" references
- Explained multi-tool action on Enter key press

**README Synchronized:**
- Model count, filter descriptions, and default behaviors match current implementation
- Hardened launcher set documented with Z-cycle order
- Proxy documentation updated with opt-in architecture

## 🔧 Technical Highlights

### Code Refactoring & Modularity
- Extracted TUI overlays and key handling into dedicated modules
- Shared integration helpers for OpenCode/OpenClaw flows
- Runtime state moved to shared locations for clearer ownership
- Improved color constants (ACTIVE_FILTER_BG_BY_TIER, PROVIDER_COLOR maps)

### Performance & Stability
- Rolling averages calculated from ALL successful pings (even 401 responses)
- Stability score refined: p95 (30%) + jitter (30%) + spike rate (20%) + reliability (20%)
- Ping cadence adapts: fast startup (2s/60s), steady state (10s), idle slowdown (30s/5m)
- Timeout models continuously retried, never abandoned

### Platform Compatibility
- Shell spawning fixed for cross-platform (Windows vs. Unix)
- Proper process isolation on non-Windows systems
- Environment variable substitution for all launchers

## 📊 Data Integrity Improvements

**Token Usage Tracking:**
- Request log overlay (`X` key) shows proxy-only transactions
- Per-exact-provider/model accounting (no contamination across providers)
- `Used` column aggregates prompt+completion tokens from startup logs
- Green dot shown when quota telemetry unavailable or unreliable

**Uptime & Health Metrics:**
- Health states: UP ✅, NO KEY 🔑, Timeout ⏳, Overloaded 🔥, Not Found 🚫
- Verdict combines avg latency + stability analysis
- Persistent favorites (`F` key) with ⭐ prefix
- Configured-only mode (`E` key) filters to providers with API keys

## 🎬 User Experience Polish

**Visual Clarity:**
- Tier and Provider filter values display directly inside highlighted pills
- Header badges show active tool mode (`Z Tool: [selected]`)
- Footer shortcut colors unified and consistent
- Provider-colored model names in the main table
- Selected row uses punchier pink-violet highlight

**Default Behavior:**
- Configured-only mode enabled by default (press `E` to toggle)
- Empty state tells users to press `P` to add first API key
- Terminal width warning shown (centered) when too narrow for table
- In-app help (`K` key) provides full reference

## ✅ Testing Checklist

- [ ] Z-cycle correctly loops through hardened launchers only
- [ ] Tier/Provider filter badges display with appropriate colors
- [ ] Crush launches successfully with direct provider config
- [ ] Crush launches successfully with FCM proxy when enabled
- [ ] `--clean-proxy` flag removes proxy config as expected
- [ ] Help overlay and flag examples show only stable launchers
- [ ] Filter state persists across all transitions
- [ ] Rolling averages update correctly on every ping
- [ ] Favorites saved and restored across restarts
- [ ] Config profiles capture and restore all settings

## 📦 Files Changed

- `CHANGELOG.md` — Unified 0.1.88 + 0.1.89 → 0.2.0 release notes
- `README.md` — Synchronized with hardened launcher set and current behavior
- `package.json` — Version bumped to 0.2.0
- `bin/free-coding-models.js` — Updated JSDoc; clarified startup and multi-tool behavior
- `src/overlays.js` — Cleaned up help overlay; only hardened launchers shown
- `src/render-table.js` — Added dynamic color support for Tier/Provider filter badges
- `src/tool-launchers.js` — Enhanced Crush config logic; added proxy detection and routing
- `src/tool-metadata.js` — Hardened launchers active; unstable launchers commented out

## 🚀 Next Steps

1. All 20 providers remain supported: NVIDIA NIM, Groq, Cerebras, SambaNova, OpenRouter, Hugging Face, Replicate, DeepInfra, Fireworks AI, Codestral, Hyperbolic, Scaleway, Google AI, SiliconFlow, Together AI, Cloudflare Workers AI, Perplexity, ZAI, DashScope (Alibaba), iFlow
2. 159 coding models across 8 tiers (S+, S, A+, A, A-, B+, B, C)
3. Proxy system available for unified account management when needed
4. Launcher ecosystem available for hardening on demand

---

**Release date:** 2026-03-09
**Commit:** 0.2.0 — Unified stable release