feat: add OpenRouter support with catalog-driven model resolution and cost-based routing

.github/workflows/ci.yml

@@ -56,4 +56,4 @@ jobs:
         uses: golangci/golangci-lint-action@v7
         with:
           version: latest
-          args: --timeout 5m
+          args: --timeout 5m

.gitignore

@@ -12,3 +12,10 @@ dist/
 brag-output-**
 .DS_Store
 .kimchi
+.worktrees/
+.planning
+# Spartan AI config (contains API keys)
+.spartan/ai.env
+.claude
+
+router.test

.spartan/config.yaml

@@ -0,0 +1,58 @@
+# .spartan/config.yaml — Generated by /spartan:init-rules
+# Validate: /spartan:lint-rules
+# Auto-detect rules from code: /spartan:scan-rules
+
+# ─── Stack & Architecture ───────────────────────────────────────────
+
+stack: go-standard
+architecture: clean
+
+# ─── Rules ──────────────────────────────────────────────────────────
+
+rules:
+  shared: []
+    # Add rules that apply to both backend and frontend
+
+  backend:
+    - rules/auto-detected/ERROR_HANDLING.md
+    - rules/auto-detected/CONSTRUCTOR_PATTERN.md
+    - rules/auto-detected/CONTEXT_PROPAGATION.md
+    - rules/auto-detected/SLOG_LOGGING.md
+    - rules/auto-detected/TEST_HELPERS.md
+    - rules/auto-detected/JSON_RAWMESSAGE.md
+    - rules/auto-detected/SYNC_MUTEX.md
+
+  frontend: []
+    # Add frontend-specific rules
+
+# ─── File Type Mapping ──────────────────────────────────────────────
+
+file-types:
+  backend: [".go"]
+  frontend: []
+  migration: [".sql"]
+  config: [".yaml", ".yml", ".json", ".toml"]
+
+# ─── Review Stages ──────────────────────────────────────────────────
+
+review-stages:
+  - correctness
+  - stack-conventions
+  - test-coverage
+  - architecture
+  - database-api
+  - security
+  - documentation-gaps
+
+# ─── Build Commands ─────────────────────────────────────────────────
+
+commands:
+  test:
+    backend: "make test"
+    frontend: ""
+  build:
+    backend: "make build"
+    frontend: ""
+  lint:
+    backend: "make lint"
+    frontend: ""

CLAUDE.md

@@ -5,15 +5,31 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Commands
 
 ```bash
-make build   # Build binary to bin/routatic-proxy
+make build   # Build binary to bin/routatic-proxy (CGO disabled by default)
 make run     # Run without building
 make test    # Run tests with race detector
 make lint    # go vet + test
 make clean   # Remove build artifacts
 make install # Build and install to $GOPATH/bin
 make dist    # Cross-compile for all platforms
+
+## Build with tray support (Linux/macOS)
+# Linux: sudo dnf install libappindicator-gtk3-devel  # Fedora/RHEL
+# Linux: sudo apt install libayatana-appindicator3-dev  # Ubuntu/Debian
+CGO_ENABLED=1 make build
+
+## The 'ui' command opens the GUI dashboard
+./bin/routatic-proxy ui  # Browser-based on Linux, native window on macOS
 ```
 
+### Platform-specific notes
+
+**Linux:** The default build uses `CGO_ENABLED=0` and opens the GUI in your default browser via `xdg-open`. For system tray support, build with `CGO_ENABLED=1` after installing the `libappindicator-gtk3-devel` (Fedora/RHEL) or `libayatana-appindicator3-dev` (Ubuntu/Debian) package.
+
+**macOS:** The `ui` command opens a native window with system tray integration. Requires CGO with Cocoa headers. For builds without CGO, use `CGO_ENABLED=0 make build` which opens the browser-based GUI.
+
+**Windows:** The `ui` command is not supported. Use CLI only or run the proxy with `make run`.
+
 Run a single test: `go test ./internal/router/ -v`
 
 ## Architecture
@@ -55,6 +71,21 @@ If a model's upstream doesn't support Anthropic tool format (`type: "custom"` se
 4. Background (simple read-only ops, no tools) → Qwen3.7 Max
 5. Default → Kimi K2.6
 
+**Cost-based routing:** when `cost_routing.enabled` is set, `Selector` in `internal/router/selector.go` replaces the static primary model with automatic cheapest-model selection from the catalog. It applies `max_context_window` (hard cap on context window), `prefer_providers` (global provider filter, intersected with per-scenario preferences), and `penalty_per_provider` (per-provider cost penalty added during sort). Enabled via `cost_routing.enabled` or the legacy `enable_cost_based_routing` flag.
+
+**Catalog schema:** Models are keyed as `provider/model-name` (e.g., `opencode-go/glm-5.2`). The catalog (`~/.config/routatic-proxy/catalog/catalog.json`) contains:
+- `providers` — Provider definitions with `name`, `base_url`, `enabled`
+- `models` — Model definitions keyed by full key with fields:
+  - `id` — Full key (matches the map key)
+  - `name` — Display name
+  - `limit.context` — Context window size
+  - `rates.input`/`rates.output` — Cost per million tokens
+  - `tool_call` — Whether tools are supported
+  - `modalities.input`/`output` — Input/output types (`["text"]` or `["text", "image"]` for vision)
+  - `reasoning` — Whether reasoning mode is supported
+
+Resolution functions in `internal/catalog/resolve.go` extract the provider from the key prefix. `ResolvedModel.ModelID` is the model name only (without provider prefix); `ResolvedModel.CanonicalName` is the full key.
+
 For streaming, the router downgrades to fast models (Qwen3.7 Plus) for better TTFT.
 
 **Deprecated models:**

CONFIGURATION.md

@@ -21,6 +21,16 @@ For migration, `~/.config/oc-go-cc/config.json` is loaded when the new config fi
     "base_url": "https://api.anthropic.com"
   },
 
+  "enable_cost_based_routing": false,
+  "cost_routing": {
+    "enabled": true,
+    "prefer_providers": ["opencode-go", "aws-bedrock"],
+    "max_context_window": 1000000,
+    "penalty_per_provider": {
+      "openrouter": 0.05
+    }
+  },
+
   "models": {
     "default": {
       "provider": "opencode-go",
@@ -260,6 +270,45 @@ DeepSeek V4 users can set any scenario model to `deepseek-v4-pro` or `deepseek-v
 
 Routing priority: **Long Context** > **Think** > **Background** > **Default**
 
+## Cost-Based Routing
+
+When enabled, the proxy uses a catalog of model pricing data to automatically select the cheapest eligible model for each scenario, rather than always using the statically configured primary model.
+
+```json
+{
+  "cost_routing": {
+    "enabled": true,
+    "prefer_providers": ["opencode-go", "aws-bedrock"],
+    "max_context_window": 1000000,
+    "penalty_per_provider": {
+      "openrouter": 0.05
+    }
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | `bool` | Activates cost-aware model selection. Can also be set via the legacy `enable_cost_based_routing` top-level flag. |
+| `prefer_providers` | `string[]` | Restricts candidate providers globally. When set, only models on these providers are considered. Intersected with per-scenario `preferred_providers` when both are set. |
+| `max_context_window` | `int64` | Hard cap on candidate model context window. Models exceeding this size are excluded. `0` (default) means no cap. |
+| `penalty_per_provider` | `map[string]float64` | Per-provider cost penalty added to the effective cost during selection. Use this to bias away from providers without removing them entirely. |
+
+When enabled, `SelectCheapest` resolves all eligible provider/model pairs for the matched scenario, applies the max context window cap, filters by the preferred providers set, and sorts by effective cost (raw cost + penalty). The cheapest candidate wins. This replaces the static `models.<scenario>` primary model.
+
+```json
+{
+  "cost_routing": {
+    "penalty_per_provider": {
+      "opencode-go": 0.1,
+      "openrouter": 0.05
+    }
+  }
+}
+```
+
+Penalties are additive to the raw cost. A model on `opencode-go` with base cost 2.0 and a penalty of 0.1 has effective cost 2.1.
+
 ## Fallback Chains
 
 When a model request fails (network error, rate limit, server error), the proxy tries the next model in the fallback chain:

CONTRIBUTING.md

@@ -38,6 +38,25 @@
 4. Push to your fork and open a pull request against `main`
 5. Describe what your PR does and link any related issues
 
+### Pre-push Hooks
+
+This repository uses git hooks to ensure code quality. Install them once after cloning:
+
+```bash
+./scripts/install-hooks.sh
+```
+
+The pre-push hook runs these checks before allowing a push:
+- **Code formatting** (`gofmt`) — ensures consistent formatting
+- **Linting** (`go vet`) — catches common errors
+- **Tests** (`make test`) — runs all tests with race detector
+- **Build** (`make build`) — verifies the project compiles
+
+To bypass hooks temporarily (not recommended):
+```bash
+git push --no-verify
+```
+
 ## Code Style
 
 This project follows standard Go conventions:

Makefile

@@ -10,7 +10,7 @@ CMD = ./cmd/routatic-proxy
 # ── Development ────────────────────────────────────────────────────
 
 build:
-	go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) $(CMD)
+	CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) $(CMD)
 	@ln -sf $(BINARY) bin/$(LEGACY_BINARY)
 
 build-ui:
@@ -24,29 +24,27 @@ run:
 	go run -ldflags "$(LDFLAGS)" $(CMD)
 
 test:
-	go test ./... -v -race
+	go test ./internal/... ./pkg/... ./cmd/... -v -race
 
 vet:
 	go vet ./...
 
+GOBIN=$(shell go env GOPATH)/bin
+
 lint:
-	@which golangci-lint > /dev/null || (echo "golangci-lint not found, please install it: https://golangci-lint.run/usage/install/" && exit 1)
 	@echo "Running gofmt..."
 	@test -z "$$(gofmt -d . | tee /dev/stderr)" || (echo "gofmt check failed" && exit 1)
-	@echo "Running golangci-lint..."
-	golangci-lint run --timeout 5m
+	@echo "Running go vet..."
+	CGO_ENABLED=0 go vet ./...
+	@echo "Lint checks passed!"
 
 clean:
 	rm -rf bin/ dist/
 
 install: build
-	cp bin/$(BINARY) $(GOPATH)/bin/$(BINARY) 2>/dev/null || \
-		cp bin/$(BINARY) $(HOME)/go/bin/$(BINARY) 2>/dev/null || \
-		go install -ldflags "$(LDFLAGS)" $(CMD)
-	@INSTALL_DIR="$$(go env GOPATH 2>/dev/null)/bin"; \
-		if [ -x "$$INSTALL_DIR/$(BINARY)" ]; then \
-			ln -sf "$(BINARY)" "$$INSTALL_DIR/$(LEGACY_BINARY)"; \
-		fi
+	@mkdir -p $(GOBIN)
+	cp bin/$(BINARY) $(GOBIN)/$(BINARY)
+	ln -sf $(BINARY) $(GOBIN)/$(LEGACY_BINARY)
 
 # ── Docker ─────────────────────────────────────────────────────────
 

README.md

@@ -199,6 +199,7 @@ routatic-proxy --version          Show version
 | [MODELS.md](MODELS.md)                                       | Model capabilities, costs, and routing recommendations          |
 | [CONTRIBUTING.md](CONTRIBUTING.md)                           | Development setup, architecture, how it works                   |
 | [TROUBLESHOOTING.md](TROUBLESHOOTING.md)                     | Common issues and debug mode                                    |
+| [docs/fedora-setup.md](docs/fedora-setup.md)                 | Fedora 44 setup guide (installation, systemd, SELinux)          |
 | [docs/architecture.md](docs/architecture.md)                 | System design, request flow, module overview                    |
 | [docs/reference-api.md](docs/reference-api.md)               | HTTP API reference (endpoints, streaming, errors)               |
 | [docs/howto-add-model.md](docs/howto-add-model.md)           | Adding new models (zero code changes)                           |