multi-forge 0.2.0__py3-none-any.whl

forge/_extensions/skills/qa/resources/checklist/3-auth.md

@@ -0,0 +1,234 @@
+<!-- prereq: 0.3 -->
+
+## 3. Authentication (`forge authentication`)
+
+Tests credential storage/resolution in `$FORGE_HOME/credentials.yaml` (named profiles).
+
+> **Note:** These steps test Forge's credential management UI only. The keys stored via `forge authentication login` are
+> NOT used by the proxy or Claude Code. The proxy gets its backend keys from environment variables injected at container
+> start (`/etc/profile.d/forge-qa.sh`). You can use placeholder values (e.g., `sk-ant-manual-test-12345`) for all login
+> prompts.
+
+### 3.1 Login — Store Credentials
+
+<!-- human:guided -->
+
+In a **shell inside the QA container** (`docker exec -it $CONTAINER bash -l` — the container name is printed by
+`start-container.sh`, usually `forge-qa`), run the command below. Enter a test API key when prompted (e.g.,
+`sk-ant-manual-test-12345`). Input will be hidden.
+
+```
+# Store credentials for a single credential
+forge authentication login -c anthropic-api
+
+# Expected: prompts for ANTHROPIC_API_KEY (input hidden)
+# Enter a test key, e.g.: sk-ant-manual-test-12345
+```
+
+- [ ] Prompts for API key with hidden input (characters not echoed)
+- [ ] Shows "Credentials saved to $FORGE_HOME/credentials.yaml"
+- [ ] File created with 0o600 permissions (`ls -la $FORGE_HOME/credentials.yaml`)
+
+### 3.2 Login — Named Profiles
+
+<!-- human:guided -->
+
+In the **container shell**, store credentials under a named profile. Enter a different test key (e.g.,
+`sk-ant-work-key-99999`).
+
+```
+# Store credentials in a named profile
+forge authentication login -c anthropic-api --profile work
+# Enter a different key, e.g.: sk-ant-work-key-99999
+
+# Verify both profiles exist
+forge authentication profiles
+```
+
+- [ ] `work` profile created separately from `default`
+- [ ] `forge authentication profiles` shows both profiles with key counts
+- [ ] Active profile marked with "← active"
+
+### 3.3 Login — Keep Existing Values
+
+<!-- human:guided -->
+
+In the **container shell**, re-run login for the same credential. The existing value appears as a masked default (e.g.,
+`ANTHROPIC_API_KEY [sk-a…5678]`). Press Enter to keep it.
+
+```
+# Re-run login for same credential — existing value shown as masked default
+forge authentication login -c anthropic-api
+
+# Expected: shows existing value like "ANTHROPIC_API_KEY [sk-a…5678]"
+# Press Enter to keep existing value
+```
+
+- [ ] Existing value shown as masked default (first 4 + last 4 chars)
+- [ ] Pressing Enter preserves the existing value (not overwritten)
+
+### 3.4 Status — Dual-View Output
+
+<!-- auto -->
+
+```bash
+# Check credential status
+forge authentication status
+
+# Expected output has two sections:
+#   Configured capabilities:
+#     * anthropic-api ...  (file:default)
+#
+#   Credential details:
+#     anthropic-api
+#       * ANTHROPIC_API_KEY = sk-a…5678  (file:default)
+```
+
+- [ ] Shows "Configured capabilities:" section with configured credentials
+- [ ] Shows "Not configured (set up if needed):" section for unconfigured credentials
+- [ ] Shows "Credential details:" section with per-variable source attribution
+- [ ] Values are masked (never shown in full)
+- [ ] All 5 credentials displayed (openrouter, anthropic-api, openai-api, gemini-api, litellm-remote)
+- [ ] Unconfigured credentials show "not configured" (not "MISSING")
+
+### 3.5 Status — Env Overrides File
+
+<!-- auto -->
+
+```bash
+# Set env var that also exists in file
+export ANTHROPIC_API_KEY=sk-ant-from-env-override
+forge authentication status
+
+# Expected: shows (env) source, not (file:default)
+unset ANTHROPIC_API_KEY
+```
+
+- [ ] Env var takes precedence — shown as `(env)` not `(file:default)`
+- [ ] After unsetting env var, status shows `(file:default)` again
+
+### 3.6 Status — Named Profile
+
+<!-- auto -->
+
+```bash
+# Check status for a specific profile
+forge authentication status --profile work
+```
+
+- [ ] Shows `(file:work)` for keys stored in work profile
+- [ ] Keys not in work profile shown as "not configured" (even if in default)
+
+### 3.7 Profiles — List and Active Marker
+
+<!-- auto -->
+
+```bash
+# List all profiles
+forge authentication profiles
+
+# Change active profile via env var
+FORGE_PROFILE=work forge authentication profiles
+```
+
+- [ ] Shows profile names with key counts
+- [ ] Default profile marked "← active" by default
+- [ ] `FORGE_PROFILE=work` changes active marker to work
+
+### 3.8 Logout — Remove Profile
+
+<!-- auto -->
+
+```bash
+# Remove a profile (with confirmation)
+printf 'y\n' | forge authentication logout --profile work
+
+# Verify removed
+forge authentication profiles
+```
+
+- [ ] Confirmation prompt shown (unless `-y` used)
+- [ ] Profile removed from credentials file
+- [ ] Other profiles unaffected
+
+### 3.9 Logout — Skip Confirmation
+
+<!-- human:guided -->
+
+In the **container shell**, create a temp profile (enter any test key when prompted), then remove it with `-y`.
+
+```
+# Re-create and remove without confirmation
+forge authentication login -c anthropic-api --profile temp
+# Enter any test key
+
+forge authentication logout --profile temp -y
+forge authentication profiles
+```
+
+- [ ] `-y` flag skips confirmation
+- [ ] Profile removed immediately
+
+### 3.10 Credential File Security
+
+<!-- auto -->
+
+```bash
+# Check file permissions
+ls -la $FORGE_HOME/credentials.yaml
+# Expected: -rw------- (0o600)
+
+# Check file content structure without exposing secrets
+python3 -c "
+import yaml, sys
+with open('$FORGE_HOME/credentials.yaml') as f:
+    data = yaml.safe_load(f)
+print('version:', data.get('version'))
+print('profiles:', list(data.get('profiles', {}).keys()))
+for name, profile in data.get('profiles', {}).items():
+    masked = {k: v[:6] + '...' if isinstance(v, str) and len(v) > 6 else v for k, v in profile.items()}
+    print(f'  {name}: {masked}')
+"
+```
+
+- [ ] Permissions are 0o600 (owner read/write only)
+- [ ] File has `version: 1` field
+- [ ] Profile names map to flat key-value pairs (values masked)
+
+### 3.11 Credential Resolution in CredentialManager
+
+<!-- auto -->
+
+```bash
+# Verify file-based credentials are actually used by the system
+# Unset env var, rely on file-based credential
+unset ANTHROPIC_API_KEY
+
+# If you have a valid key stored via forge authentication login:
+# Starting a session or proxy that needs ANTHROPIC_API_KEY should work
+# without the env var set (it reads from $FORGE_HOME/credentials.yaml)
+forge authentication status --profile default
+# Should show: * ANTHROPIC_API_KEY = sk-a…xxxx  (file:default)
+```
+
+- [ ] Credential available via file when env var is unset
+- [ ] `forge authentication status` confirms file source
+
+### 3.12 Retired Credential Names
+
+<!-- auto -->
+
+```bash
+# Old 'anthropic' name should produce migration guidance
+forge authentication login -c anthropic 2>&1 || true
+# Expected: exit 1, yellow message mentioning 'anthropic-api'
+
+# Old 'litellm-local' name should explain it's not a credential
+forge authentication login -c litellm-local 2>&1 || true
+# Expected: exit 1, message mentioning gemini-api, openai-api, anthropic-api
+```
+
+- [ ] `anthropic` produces clear migration message pointing to `anthropic-api`
+- [ ] `litellm-local` explains it's not a credential and lists provider alternatives
+
+---

forge/_extensions/skills/qa/resources/checklist/4-proxy.md

@@ -0,0 +1,481 @@
+<!-- prereq: 0.3 -->
+
+## 4. Proxy Management
+
+Default QA runs this section through the OpenRouter provider profile. It requires the selected provider credentials
+(`OPENROUTER_API_KEY` by default), not remote LiteLLM infrastructure unless QA was started with
+`--provider-profile remote-litellm`. LiteLLM template list/show checks below are metadata-only.
+
+### 4.1 List Proxies and Templates
+
+<!-- auto -->
+
+```bash
+# List existing proxies (none yet)
+forge proxy list
+
+# Expected: "No proxies found." + tip to run 'forge proxy template list'
+# Templates are listed via the template subcommand, not inline in proxy list.
+
+# List available templates
+forge proxy template list
+```
+
+- [ ] `forge proxy list` shows "No proxies found." when none exist
+- [ ] `forge proxy list` shows tip to run `forge proxy template list`
+- [ ] `forge proxy template list` shows available templates (18 user-facing: litellm-anthropic, litellm-anthropic-local,
+  litellm-gemini, litellm-gemini-flash-local, litellm-gemini-local, litellm-openai, litellm-openai-codex-local,
+  litellm-openai-local, openrouter-anthropic, openrouter-deepseek, openrouter-gemini, openrouter-gemini-flash,
+  openrouter-glm, openrouter-kimi, openrouter-minimax, openrouter-openai, openrouter-openai-codex, openrouter-qwen)
+- [ ] Internal test-only templates (e.g., litellm-gemini-test) are hidden from the default list
+
+### 4.2 Create a Proxy
+
+<!-- auto -->
+
+```bash
+# Clean up from previous runs
+forge proxy delete "$FORGE_QA_GEMINI_PROXY" --force 2>/dev/null || true
+forge proxy delete "$FORGE_QA_OPENAI_PROXY" --force 2>/dev/null || true
+forge proxy delete "$FORGE_QA_ANTHROPIC_PROXY" --force 2>/dev/null || true
+forge proxy delete openrouter-gemini --force 2>/dev/null || true
+forge proxy delete openrouter-openai --force 2>/dev/null || true
+forge proxy delete openrouter-deepseek --force 2>/dev/null || true
+forge proxy delete openrouter-minimax --force 2>/dev/null || true
+forge proxy delete test-proxy-nostart --force 2>/dev/null || true
+
+# Create named role proxies used by downstream session/review steps.
+forge proxy create "$FORGE_QA_GEMINI_TEMPLATE" --name "$FORGE_QA_GEMINI_PROXY"
+
+# Create a named review proxy with per-tier overrides
+forge proxy create "$FORGE_QA_OPENAI_TEMPLATE" --name "$FORGE_QA_OPENAI_PROXY" --opus-reasoning high
+
+# Create workflow-default aliases so section 14 exercises production default proxy IDs.
+# In remote-litellm profile these names intentionally point at remote LiteLLM-backed proxies.
+forge proxy create "$FORGE_QA_GEMINI_TEMPLATE" --no-start --name openrouter-gemini
+forge proxy create "$FORGE_QA_OPENAI_TEMPLATE" --no-start --name openrouter-openai
+
+# Workflow proxies for cheap models (openrouter profile only).
+# Started directly with canonical names so models.py proxy lookup matches the running port.
+if [ -n "${FORGE_QA_DEEPSEEK_TEMPLATE:-}" ]; then
+  forge proxy create "$FORGE_QA_DEEPSEEK_TEMPLATE" --name openrouter-deepseek
+fi
+if [ -n "${FORGE_QA_MINIMAX_TEMPLATE:-}" ]; then
+  forge proxy create "$FORGE_QA_MINIMAX_TEMPLATE" --name openrouter-minimax
+fi
+
+# Create config only (don't start the server)
+forge proxy create "$FORGE_QA_OPENAI_TEMPLATE" --no-start --name test-proxy-nostart
+
+# List proxies again
+forge proxy list
+```
+
+- [ ] Named role proxies from `$FORGE_QA_*_TEMPLATE` created successfully (or note if skipped)
+- [ ] Named role proxies, workflow aliases, and `test-proxy-nostart` appear in the list with expected base_url/port
+  information
+- [ ] Per-tier overrides applied to `$FORGE_QA_OPENAI_PROXY`
+- [ ] Workflow proxies (`openrouter-deepseek`, `openrouter-minimax`) started for openrouter profile (or skipped for
+  remote-litellm)
+
+### 4.3 Show Proxy Details
+
+<!-- prereq: 4.2 -->
+
+<!-- auto -->
+
+```bash
+# Show details of a specific proxy (created in 4.2)
+forge proxy show test-proxy-nostart
+```
+
+- [ ] Shows template, base_url, tier mappings
+- [ ] Shows proxy configuration YAML (port, tiers, provider settings)
+
+### 4.4 Proxy Edit and Validate
+
+<!-- prereq: 4.2 -->
+
+<!-- human:guided -->
+
+In the **container shell**, run these commands to view, edit, validate, and delete a proxy. The `edit` command opens
+`$EDITOR` — verify it launches.
+
+```
+# View proxy config
+forge proxy show <proxy_id>
+
+# Edit proxy config (opens in $EDITOR)
+forge proxy edit <proxy_id>
+
+# Validate proxy config
+forge proxy validate <proxy_id>
+
+# Delete a proxy
+forge proxy delete <proxy_id>
+```
+
+- [ ] `show` displays full proxy configuration
+- [ ] `edit` opens proxy.yaml in editor
+- [ ] `validate` reports config health
+- [ ] `delete` removes proxy and cleans up registry
+
+### 4.5 Proxy Clean
+
+<!-- auto -->
+
+```bash
+# Clean up stale proxies (dead processes)
+forge proxy clean
+```
+
+- [ ] Clean removes stale entries (or reports none found)
+
+### 4.6 Launch Session with Host Proxy
+
+<!-- prereq: 2.4, 4.2 -->
+
+<!-- requires: api_key -->
+
+<!-- human:guided -->
+
+In the **container shell**, create a session bound to a proxy, then launch Claude through the proxy.
+
+```
+# Clean up from previous runs
+forge session delete proxy-session --force 2>/dev/null || true
+
+# Create a session bound to the proxy created in 4.2 (accepts proxy_id or template name)
+forge session start proxy-session --proxy "$FORGE_QA_OPENAI_PROXY" --no-launch
+
+# Verify session recorded proxy identity
+cat .forge/sessions/proxy-session/forge.session.json | jq '.intent.proxy'
+# Should show template and base_url fields
+```
+
+- [ ] `--proxy` binds session to the named proxy
+- [ ] Session manifest `.intent.proxy` shows template and base_url
+
+Now launch Claude through the named proxy. This opens an interactive Claude session — exit with Ctrl-C or `/exit` when
+done verifying.
+
+```
+# Launch Claude through the running proxy created in 4.2
+forge claude start --proxy "$FORGE_QA_OPENAI_PROXY" -- --debug
+# Claude should start with ANTHROPIC_BASE_URL pointing to the proxy
+# Verify by checking the status line or running: echo $ANTHROPIC_BASE_URL inside Claude
+# Exit Claude when done (Ctrl-C or /exit)
+```
+
+- [ ] `forge claude start --proxy` starts Claude routed through the named proxy
+- [ ] Status line shows proxy info (template, tier mappings) when running with proxy
+
+### 4.7 Live % Commands in Proxy Session
+
+<!-- prereq: 2.4, 4.2 -->
+
+<!-- requires: api_key -->
+
+<!-- human:guided -->
+
+Now launch Claude (or reuse the session from 4.6):
+
+```
+forge claude start --proxy "$FORGE_QA_OPENAI_PROXY" -- --debug
+```
+
+In the **live Claude session**, type these prompts:
+
+```
+%help
+%session list
+%proxy list
+%proxy show qa-openai
+```
+
+- [ ] `%help` returns help text listing available `%` commands
+- [ ] `%session list` shows sessions (including proxy-session)
+- [ ] `%proxy list` shows proxies from inside the session
+- [ ] `%proxy show` displays proxy details (template, tier mappings)
+- [ ] Commands are intercepted by `UserPromptSubmit` hook (not passed to Claude as prompts)
+
+Exit the Claude session when done.
+
+### 4.8 Proxy Delete UX (Confirmation + Smart-Pointer Semantics)
+
+<!-- prereq: 4.2, 4.6 -->
+
+<!-- human:guided -->
+
+Test that `forge proxy delete` requires confirmation, shows the related shared-port items, and uses smart-pointer
+semantics (only kills the server when deleting the last registry entry for that port).
+
+In the **container shell**:
+
+```
+# Clean up from previous runs
+forge proxy delete delete-test-proxy --force 2>/dev/null || true
+
+# Create an alias on the same shared port as the QA OpenAI proxy
+forge proxy create "$FORGE_QA_OPENAI_TEMPLATE" --no-start --name delete-test-proxy
+
+# Try to delete the alias -- should prompt for confirmation and list the related proxy entry
+forge proxy delete delete-test-proxy
+# Choose N to cancel
+# Expected:
+# - confirmation prompt appears
+# - related proxies on the same port are listed (including qa-openai)
+# - no false warning about proxy-session/proxy-session-url just because they share port 8085
+
+# Verify alias still exists after cancelling
+forge proxy list
+# Expected: delete-test-proxy still listed
+
+# Now confirm deletion of the alias
+forge proxy delete delete-test-proxy
+# Choose y to confirm
+# Expected:
+# - "Deleted proxy 'delete-test-proxy'"
+# - shared server references are kept alive via qa-openai
+
+# Verify alias gone but qa-openai still present
+forge proxy list
+
+# Finally test deleting the primary QA proxy while shared-port aliases remain
+forge proxy delete "$FORGE_QA_OPENAI_PROXY"
+# Choose N to cancel
+# Expected:
+# - warning lists sessions that reference qa-openai (for example proxy-session / proxy-session-url)
+# - prompt makes clear other proxies share this port
+```
+
+- [ ] `forge proxy delete` prompts for confirmation (not auto-deleted)
+- [ ] Deleting a non-terminal alias lists the related proxy entries sharing that port
+- [ ] Choosing N cancels the delete; alias still in `forge proxy list`
+- [ ] Choosing y deletes the alias while keeping the shared server alive
+- [ ] Deleting the primary QA proxy lists related sessions and same-port aliases
+- [ ] No false warnings about sessions when deleting a non-terminal alias that merely shares the same port
+
+### 4.9 Template Management
+
+<!-- auto -->
+
+```bash
+# List available templates
+forge proxy template list
+
+# Show a template
+forge proxy template show litellm-openai-local
+
+# Raw YAML output (no syntax highlighting)
+forge proxy template show litellm-openai-local --raw
+```
+
+- [ ] `forge proxy template list` shows all templates with source labels (built-in / customized)
+- [ ] `forge proxy template show` displays template YAML
+- [ ] `--raw` outputs plain YAML
+
+### 4.10 Show Raw YAML for a Proxy Instance
+
+<!-- prereq: 4.2 -->
+
+<!-- auto -->
+
+```bash
+# Show raw YAML for an existing proxy instance (created earlier)
+forge proxy show test-proxy-nostart --raw
+```
+
+- [ ] Proxy instance YAML printed (no syntax highlighting)
+- [ ] YAML includes the expected template/provider fields
+
+### 4.11 Set and Validate Proxy Config (No Editor)
+
+<!-- prereq: 4.2 -->
+
+<!-- auto -->
+
+```bash
+# Mutate a single value via CLI (no interactive editor)
+forge proxy set test-proxy-nostart default_tier=opus
+
+# Validate after mutation
+forge proxy validate test-proxy-nostart
+```
+
+- [ ] `forge proxy set` succeeds
+- [ ] `forge proxy validate` reports config is valid
+
+### 4.12 Stop a Non-Running Proxy (Shared-Port Semantics)
+
+<!-- prereq: 4.2 -->
+
+<!-- auto -->
+
+```bash
+# test-proxy-nostart shares a port with the running QA OpenAI proxy.
+# Smart-pointer semantics prevent stopping the shared server without --force.
+forge proxy stop test-proxy-nostart 2>&1 || true
+
+# Verify: error about shared port, not a silent no-op
+forge proxy stop test-proxy-nostart 2>&1; echo "EXIT=$?"
+```
+
+- [ ] Command refuses to stop: reports other proxies share the port
+- [ ] Exit code is non-zero (shared-port conflict)
+
+### 4.13 Proxy Metrics (Running Proxy)
+
+<!-- prereq: 4.2 -->
+
+<!-- auto -->
+
+```bash
+# Metrics for a running proxy (QA Gemini proxy created in 4.2)
+forge proxy metrics "$FORGE_QA_GEMINI_PROXY"
+
+# JSON output
+forge proxy metrics "$FORGE_QA_GEMINI_PROXY" --json
+
+# All proxies
+forge proxy metrics --all
+
+# All proxies JSON (must be a single valid JSON object)
+forge proxy metrics --all --json
+```
+
+- [ ] `forge proxy metrics` displays request counts, token totals, per-tier breakdown
+- [ ] Per-tier breakdown includes avg latency
+- [ ] `--json` outputs valid parseable JSON
+- [ ] `--all --json` outputs a single valid JSON object (not one per proxy)
+- [ ] Unreachable proxies show `null` in `--all --json` output
+
+### 4.14 Proxy Metrics (Not Found / Shared-Port)
+
+<!-- auto -->
+
+```bash
+# Metrics for a non-existent proxy (not in registry)
+forge proxy metrics nonexistent-proxy 2>&1; echo "EXIT=$?"
+
+# Metrics for test-proxy-nostart: shares a port with qa-openai,
+# so smart-pointer semantics mean it reports metrics from the shared server.
+forge proxy metrics test-proxy-nostart
+```
+
+- [ ] Non-existent proxy shows error and exits non-zero
+- [ ] Shared-port proxy (test-proxy-nostart) returns metrics from the shared server (exit 0)
+
+### 4.15 Backend List (Proxy Dependency)
+
+<!-- auto -->
+
+```bash
+# List running backend instances (LiteLLM, etc.)
+forge backend list
+```
+
+- [ ] Shows "No backends found." (or lists running backends)
+- [ ] Command suggests `forge backend create litellm` when empty
+
+### 4.16 Backend Create (LiteLLM Config)
+
+<!-- auto -->
+
+```bash
+# Create backend config (shared by all instances)
+forge backend create litellm
+
+# Show config + status (even if not running)
+forge backend show litellm-4000 --raw
+```
+
+- [ ] Backend config created (or reports it already exists)
+- [ ] `forge backend show` displays config YAML
+
+### 4.17 OpenRouter Templates
+
+<!-- auto -->
+
+```bash
+# List all templates -- should now include OpenRouter alongside LiteLLM
+forge proxy template list
+
+# Show each OpenRouter template
+forge proxy template show openrouter-anthropic
+forge proxy template show openrouter-openai
+forge proxy template show openrouter-openai-codex
+forge proxy template show openrouter-deepseek
+forge proxy template show openrouter-gemini
+forge proxy template show openrouter-gemini-flash
+forge proxy template show openrouter-glm
+forge proxy template show openrouter-kimi
+forge proxy template show openrouter-minimax
+forge proxy template show openrouter-qwen
+```
+
+- [ ] `forge proxy template list` shows 18 user-facing templates total (8 litellm + 10 openrouter)
+- [ ] `openrouter-anthropic` maps tiers to Claude models (haiku=claude-haiku-4.5, sonnet=claude-sonnet-4.6,
+  opus=claude-opus-4.6)
+- [ ] `openrouter-deepseek` maps tiers to DeepSeek models (haiku=deepseek-v4-flash, sonnet/opus=deepseek-v4-pro)
+- [ ] `openrouter-glm` maps tiers to GLM models (haiku=glm-4.7-flash, sonnet/opus=glm-5.1)
+- [ ] `openrouter-kimi` maps tiers to Gemma/Kimi models (haiku=gemma-4-31b-it, sonnet/opus=kimi-k2.6)
+- [ ] `openrouter-minimax` maps tiers to Gemma/MiniMax models (haiku=gemma-4-31b-it, sonnet/opus=minimax-m2.7)
+- [ ] `openrouter-qwen` maps tiers to Qwen models (haiku=qwen3.6-flash, sonnet=qwen3.6-plus, opus=qwen3.6-max-preview)
+- [ ] `openrouter-openai` maps tiers to GPT models (haiku=gpt-5.4-mini, sonnet=gpt-5.5, opus=gpt-5.5)
+- [ ] `openrouter-openai-codex` maps tiers to Codex models (haiku=gpt-5.1-codex-mini, sonnet=gpt-5.3-codex,
+  opus=gpt-5.5)
+- [ ] `openrouter-gemini` maps tiers to Gemini models (haiku=gemini-2.5-flash, sonnet=gemini-3.1-pro-preview,
+  opus=gemini-3.1-pro-preview)
+- [ ] `openrouter-gemini-flash` maps all tiers to gemini-2.5-flash with tier_overrides for reasoning_effort
+  (low/medium/high)
+- [ ] Each OpenRouter template has a distinct default_port (8095-8104)
+
+### 4.18 OpenRouter Proxy Create
+
+<!-- auto -->
+
+```bash
+# Clean up from previous runs
+forge proxy delete openrouter-test --force 2>/dev/null || true
+
+# Create an OpenRouter proxy without starting it (no OPENROUTER_API_KEY needed for config-only)
+forge proxy create openrouter-anthropic --name openrouter-test --no-start
+
+# Show proxy details
+forge proxy show openrouter-test
+
+# Show raw YAML
+forge proxy show openrouter-test --raw
+```
+
+- [ ] OpenRouter proxy created from template (exit 0)
+- [ ] `forge proxy show` or `forge proxy validate` displays `Provider: openrouter`
+- [ ] Raw YAML shows `provider: openrouter` and tier mappings with `anthropic/` prefixed model IDs
+- [ ] Proxy uses port 8095 (openrouter-anthropic default)
+
+### 4.19 Model Alternatives
+
+<!-- prereq: 4.18 -->
+
+<!-- auto -->
+
+```bash
+# Check model_alternatives in the openrouter-anthropic template
+forge proxy template show openrouter-anthropic --raw | grep -A3 model_alternatives
+
+# Check instance inherits alternatives
+forge proxy show openrouter-test --raw | grep -A3 model_alternatives
+
+echo "---"
+
+# Clean up
+forge proxy delete openrouter-test --force 2>/dev/null || true
+```
+
+- [ ] Template YAML includes `model_alternatives` section under opus tier
+- [ ] Opus alternative maps `claude-opus-4-7` to `anthropic/claude-opus-4.7`
+- [ ] Proxy instance inherits `model_alternatives` from template
+- [ ] `openrouter-test` proxy cleaned up
+
+---