@khanglvm/llm-router 1.0.6 → 1.0.8

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.8] - 2026-02-28
+
+### Changed
+- Added focused npm `keywords` metadata in `package.json` to improve package discoverability.
+
+## [1.0.7] - 2026-02-28
+
+### Added
+- Added `llm-router ai-help` to generate an agent-oriented operating guide with live gateway checks and coding-tool patch instructions.
+- Added tests covering `ai-help` discovery output and first-run setup guidance.
+
+### Changed
+- Rewrote `README.md` into a shorter setup and operations guide focused on providers, aliases, rate limits, and local/hosted usage.
+
 ## [1.0.6] - 2026-02-28
 
 ### Added

package/README.md

@@ -1,440 +1,188 @@
 # llm-router
 
-`llm-router` is a gateway api proxy for accessing multiple models across any provider that supports OpenAI or Anthropic formats.
+`llm-router` exposes unified API endpoint for multiple AI providers and models.
 
-It supports:
-- local route server `llm-router start`
-- Cloudflare Worker route runtime deployment `llm-router deploy`
-- CLI + TUI management `config`, `start`, `deploy`, `worker-key`
-- Seamless model fallback
+## Main feature
 
-## Install
-
-```bash
-npm i -g @khanglvm/llm-router
-```
-
-## Versioning
+1. Single endpoint, unified providers & models
+2. Support grouping models with rate-limit and load balancing strategy
+3. Configuration auto reload in real time, no interruption
 
-- Follows [Semantic Versioning](https://semver.org/).
-- Release notes live in [`CHANGELOG.md`](./CHANGELOG.md).
-- npm publishes are configured for the public registry package.
-
-Release checklist:
-- Update `README.md` if user-facing behavior changed.
-- Add a dated entry in `CHANGELOG.md`.
-- Bump the package version before publish.
-- Publish with `npm publish`.
-
-## Quick Start
+## Install
 
 ```bash
-# 1) Open config TUI (default behavior) to manage providers, models, fallbacks, and auth
-llm-router
-
-# 2) Start local route server
-llm-router start
+npm i -g @khanglvm/llm-router@latest
 ```
 
-Local endpoints:
-- Unified (Auto transform): `http://127.0.0.1:8787/route` (or `/` and `/v1`)
-- Anthropic: `http://127.0.0.1:8787/anthropic`
-- OpenAI: `http://127.0.0.1:8787/openai`
-
-## Usage Example
-
-```bash
-# Your AI Agent can help! Ask them to manage api router via this tool for you.
-
-# 1) Add provider + models + provider API key. You can ask your AI agent to do it for you, or manually via TUI or command line:
-llm-router config \
-  --operation=upsert-provider \
-  --provider-id=openrouter \
-  --name="OpenRouter" \
-  --base-url=https://openrouter.ai/api/v1 \
-  --api-key=sk-or-v1-... \
-  --models=claude-3-7-sonnet,gpt-4o \
-  --format=openai \
-  --skip-probe=true
-
-# 2) (Optional) Configure model fallback order for direct provider/model requests
-llm-router config \
-  --operation=set-model-fallbacks \
-  --provider-id=openrouter \
-  --model=claude-3-7-sonnet \
-  --fallback-models=openrouter/gpt-4o
-
-# 3) (Optional) Create a model alias with a routing strategy and weighted targets
-llm-router config \
-  --operation=upsert-model-alias \
-  --alias-id=chat.default \
-  --strategy=auto \
-  --targets=openrouter/claude-3-7-sonnet@2,openrouter/gpt-4o@1 \
-  --fallback-targets=openrouter/gpt-4o-mini
-
-# 4) (Optional) Add provider request-cap bucket (models: all)
-llm-router config \
-  --operation=set-provider-rate-limits \
-  --provider-id=openrouter \
-  --bucket-name="Monthly cap" \
-  --bucket-models=all \
-  --bucket-requests=20000 \
-  --bucket-window=month:1
-
-# 5) Set master key (this is your gateway key for client apps)
-llm-router config --operation=set-master-key --master-key=gw_your_gateway_key
-
-# 6) Start gateway with auth required
-llm-router start --require-auth=true
-```
+## Usage
 
-Claude Code example (`~/.claude/settings.local.json`):
+Copy/paste this short instruction to your AI agent:
 
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787/anthropic",
-    "ANTHROPIC_AUTH_TOKEN": "gw_your_gateway_key"
-  }
-}
+```text
+Run `llm-router ai-help` first, then set up and operate llm-router for me using CLI commands.
 ```
 
-## Smart Fallback Behavior
-
-`llm-router` can fail over from a primary model to configured fallback models with status-aware logic:
-- `429` (rate-limited): immediate fallback (no origin retry), with `Retry-After` respected when present.
-- Temporary failures (`408`, `409`, `5xx`, network errors): origin-only bounded retries with jittered backoff, then fallback.
-- Billing/quota exhaustion (`402`, or provider-specific billing signals): immediate fallback with longer origin cooldown memory.
-- Auth and permission failures (`401` and relevant `403` cases): no retry; fallback to other providers/models when possible.
-- Policy/moderation blocks: no retry; cross-provider fallback is disabled by default (`LLM_ROUTER_ALLOW_POLICY_FALLBACK=false`).
-- Invalid client requests (`400`, `413`, `422`): no retry and no fallback short-circuit.
+## Main Workflow
 
-## Model Alias Routing Strategies
+1. Add Providers + models into llm-router
+2. Optionally, group models as alias with load balancing and auto fallback support
+3. Start llm-router server, point your coding tool API and model to llm-router
 
-A model alias groups multiple models from different providers under one model name.
+## What Each Term Means
 
-Use `--strategy` when creating or updating a model alias:
+### Provider
+The service endpoint you call (OpenRouter, Anthropic, etc.).
 
-- `auto`: Recommended set-and-forget mode. Automatically routes using quota, cooldown, and health signals to reduce rate-limit failures.
-- `ordered`: Tries targets in list order.
-- `round-robin`: Rotates evenly across eligible targets.
-- `weighted-rr`: Rotates like round-robin, but favors higher weights.
-- `quota-aware-weighted-rr`: Weighted routing plus remaining-capacity awareness.
-
-Example:
-
-```bash
-llm-router config \
-  --operation=upsert-model-alias \
-  --alias-id=coding \
-  --strategy=auto \
-  --targets=rc/gpt-5.3-codex,zai/glm-5
-```
-
-Concrete model alias example with provider-specific caps:
-
-```bash
-llm-router config \
-  --operation=upsert-model-alias \
-  --alias-id=coding \
-  --strategy=auto \
-  --targets=rc/gpt-5.3-codex,zai/glm-5
-
-llm-router config \
-  --operation=set-provider-rate-limits \
-  --provider-id=rc \
-  --bucket-name="Minute cap" \
-  --bucket-models=gpt-5.3-codex \
-  --bucket-requests=60 \
-  --bucket-window=minute:1
-
-llm-router config \
-  --operation=set-provider-rate-limits \
-  --provider-id=zai \
-  --bucket-name="5-hours cap" \
-  --bucket-models=glm-5 \
-  --bucket-requests=600 \
-  --bucket-window=hour:5
-```
-
-## What Is A Bucket?
-
-A rate-limit bucket is a request cap for a time window.
+### Model
+The actual model ID from that provider.
 
+### Rate-Limit Bucket
+A request cap for a time window.
 Examples:
-- `40 req / 1 minute`
-- `600 req / 6 hours`
-
-Multiple buckets can apply to the same model scope at the same time. A candidate is treated as exhausted if any matching bucket is exhausted.
-
-## TUI Bucket Walkthrough
-
-Use the config manager and select:
-- `Manage provider rate-limit buckets`
-- `Create bucket(s)`
-
-The TUI now guides you through:
-- Bucket name (friendly label)
-- Model scope (`all` or selected models with multiselect checkboxes)
-- Request cap
-- Window unit (`minute`, `hour(s)`, `week`, `month`)
-- Window size (hours support `N`, other preset units lock to `1`)
-- Review + optional add-another loop for combined policies
-
-Internal bucket ids are generated automatically from the name when omitted and shown as advanced detail in review.
-
-## Combined-Cap Recipe (`40/min` + `600/6h`)
-
-```bash
-llm-router config \
-  --operation=set-provider-rate-limits \
-  --provider-id=openrouter \
-  --bucket-name="Minute cap" \
-  --bucket-models=all \
-  --bucket-requests=40 \
-  --bucket-window=minute:1
-
-llm-router config \
-  --operation=set-provider-rate-limits \
-  --provider-id=openrouter \
-  --bucket-name="6-hours cap" \
-  --bucket-models=all \
-  --bucket-requests=600 \
-  --bucket-window=hour:6
-```
-
-This keeps both limits active together for the same model scope.
-
-## Rate-Limit Troubleshooting
-
-- Check routing decisions with `LLM_ROUTER_DEBUG_ROUTING=true` and inspect `x-llm-router-skipped-candidates`.
-- `quota-exhausted` means proactive pre-routing skip happened before an upstream call.
-- For provider `429`, cooldown is tracked from `Retry-After` when present, or from `LLM_ROUTER_ORIGIN_RATE_LIMIT_COOLDOWN_MS`.
-- Local mode persists state by default (file backend), while Worker defaults to in-memory state.
-
-## Main Commands
+- `40 requests / minute`
+- `20,000 requests / month`
 
-```bash
-llm-router config
-llm-router start
-llm-router stop
-llm-router reload
-llm-router update
-llm-router deploy
-llm-router worker-key
-```
-
-## Non-Interactive Config (Agent/CI Friendly)
-
-```bash
-llm-router config \
-  --operation=upsert-provider \
-  --provider-id=openrouter \
-  --name="OpenRouter" \
-  --base-url=https://openrouter.ai/api/v1 \
-  --api-key=sk-or-v1-... \
-  --models=gpt-4o,claude-3-7-sonnet \
-  --format=openai \
-  --skip-probe=true
-
-llm-router config \
-  --operation=upsert-model-alias \
-  --alias-id=chat.default \
-  --strategy=auto \
-  --targets=openrouter/gpt-4o-mini@3,anthropic/claude-3-5-haiku@2 \
-  --fallback-targets=openrouter/gpt-4o
-
-llm-router config \
-  --operation=set-provider-rate-limits \
-  --provider-id=openrouter \
-  --bucket-name="Monthly cap" \
-  --bucket-models=all \
-  --bucket-requests=20000 \
-  --bucket-window=month:1
-```
-
-Alias target syntax:
-- `--targets` / `--fallback-targets`: `<routeRef>@<weight>` or `<routeRef>:<weight>`
-- route refs: direct `provider/model` or alias id
+### Model Load Balancer
+Decides how traffic is distributed across models in an alias group.
 
-Routing strategy values:
+Available strategies:
 - `auto` (recommended)
 - `ordered`
 - `round-robin`
 - `weighted-rr`
 - `quota-aware-weighted-rr`
 
-Rate-limit bucket window syntax:
-- `--bucket-window=month:1`
-- `--bucket-window=1w`
-- `--bucket-window=7day`
-
-Routing summary:
-
-```bash
-llm-router config --operation=list-routing
-```
+### Model Alias (Group models)
+A single model name that auto route/rotate across multiple models.
 
-Explicit schema migration with backup:
+Example:
+- alias: `opus`
+- targets:
+  - `openrouter/claude-opus-4.6`
+  - `anthropic/claude-opus-4.6`
 
-```bash
-llm-router config --operation=migrate-config --target-version=2 --create-backup=true
-```
+Your app can use `opus` model and `llm-router` chooses target models based on your routing settings.
 
-Automatic version handling:
-- Local config loads with silent forward-migration to latest supported schema.
-- Migration is persisted automatically on read when possible (best-effort, no interactive prompt).
-- Future/newer version numbers do not fail only because of version mismatch; known fields are normalized best-effort.
+## Setup using Terminal User Interface (TUI)
 
-Set local auth key:
+Open the TUI:
 
 ```bash
-llm-router config --operation=set-master-key --master-key=your_local_key
-# or generate a strong key automatically
-llm-router config --operation=set-master-key --generate-master-key=true
+llm-router
 ```
 
-Start with auth required:
+Then follow this order.
+
+### 1) Add Provider
+Flow:
+1. `Config manager`
+2. `Add/Edit provider`
+3. Enter provider name, endpoint, API key
+4. Enter model list
+5. Save
+
+### 2) Configure Model Fallback (Optional)
+Flow:
+1. `Config manager`
+2. `Set model silent-fallbacks`
+3. Pick main model
+4. Pick fallback models
+5. Save
+
+### 3) Configure Rate Limits (Optional)
+Flow:
+1. `Config manager`
+2. `Manage provider rate-limit buckets`
+3. `Create bucket(s)`
+4. Set name, model scope, request cap, time window
+5. Save
+
+### 4) Group Models With Alias (Recommended)
+Flow:
+1. `Config manager`
+2. `Add/Edit model alias`
+3. Set alias ID (example: `chat.default`)
+4. Select target models
+5. Save
+
+### 5) Configure Model Load Balancer
+Flow:
+1. `Config manager`
+2. `Add/Edit model alias`
+3. Open the alias you want to balance
+4. Choose strategy (`auto` recommended)
+5. Review alias targets
+6. Save
+
+### 6) Set Gateway Key
+Flow:
+1. `Config manager`
+2. `Set worker master key`
+3. Set or generate key
+4. Save
+
+## Start Local Server
 
 ```bash
-llm-router start --require-auth=true
+llm-router start
 ```
 
-## Cloudflare Worker Deploy
+Local endpoints:
+- Unified: `http://127.0.0.1:8787/route`
+- Anthropic-style: `http://127.0.0.1:8787/anthropic`
+- OpenAI-style: `http://127.0.0.1:8787/openai`
 
-Worker project name in `wrangler.toml`: `llm-router-route`.
+## Connect your coding tool
 
-### Option A: Guided deploy
+After setting master key, point your app/agent to local endpoint and use that key as auth token.
 
-```bash
-llm-router deploy
-```
+Claude Code example (`~/.claude/settings.local.json`):
 
-If `LLM_ROUTER_CONFIG_JSON` exceeds Cloudflare Free-tier secret size (`5 KB`), deploy now warns and requires explicit confirmation (default is `No`). In non-interactive environments, pass `--allow-large-config=true` to proceed intentionally.
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
+    "ANTHROPIC_AUTH_TOKEN": "gw_your_gateway_key",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "provider_name/model_name_1",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "provider_name/model_name_2",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "provider_name/model_name_3"
+  }
+}
+```
 
-`deploy` requires `CLOUDFLARE_API_TOKEN` for Cloudflare API access. Create a **User Profile API token** at <https://dash.cloudflare.com/profile/api-tokens> (do not use Account API Tokens), then choose preset/template `Edit Cloudflare Workers`. If the env var is missing in interactive mode, the CLI will show the guide and prompt for token input securely.
+## Real-Time Update Experience
 
-For multi-account tokens, set account explicitly in non-interactive runs:
-- `CLOUDFLARE_ACCOUNT_ID=<id>` or
-- `llm-router deploy --account-id=<id>`
+When local server is running:
+- open `llm-router`
+- change provider/model/load-balancer/rate-limit/alias in TUI
+- save
+- the running proxy updates instantly
 
-`llm-router deploy` resolves deploy target from CLI/TUI input (workers.dev or custom route), generates a temporary Wrangler config at runtime, deploys with `--config`, then removes that temporary file. Personal route/account details are not persisted back into repo `wrangler.toml`.
+No stop/start cycle needed.
 
-For custom domains, the deploy helper now prints a DNS checklist and connectivity commands. Common setup for `llm.example.com`:
-- Create a DNS record in Cloudflare for `llm` (usually `CNAME llm -> @`)
-- Set **Proxy status = Proxied** (orange cloud)
-- Use route target `--route-pattern=llm.example.com/* --zone-name=example.com`
-- Claude Code base URL should be `https://llm.example.com/anthropic` (**no `:8787`**; that port is local-only)
+## Cloudflare Worker (Hosted)
 
-```bash
-llm-router deploy --export-only=true --out=.llm-router.worker.json
-wrangler secret put LLM_ROUTER_CONFIG_JSON < .llm-router.worker.json
-wrangler deploy
-```
+Use when you want a hosted endpoint instead of local server.
 
-Rotate worker auth key quickly:
+Guided deploy:
 
 ```bash
-llm-router worker-key --master-key=new_key
-# or generate and rotate immediately
-llm-router worker-key --env=production --generate-master-key=true
+llm-router deploy
 ```
 
-If you intentionally need to bypass weak-key checks (not recommended), add `--allow-weak-master-key=true` to `deploy` or `worker-key`.
-
-Cloudflare hardening and incident-response checklist: see [`SECURITY.md`](./SECURITY.md).
-
-## Runtime Secrets / Env
-
-Primary:
-- `LLM_ROUTER_CONFIG_JSON`
-- `LLM_ROUTER_MASTER_KEY` (optional override)
-
-Also supported:
-- `ROUTE_CONFIG_JSON`
-- `LLM_ROUTER_JSON`
+You will be guided in TUI to select account and deploy target.
 
-Optional resilience tuning:
-- `LLM_ROUTER_ORIGIN_RETRY_ATTEMPTS` (default `3`)
-- `LLM_ROUTER_ORIGIN_RETRY_BASE_DELAY_MS` (default `250`)
-- `LLM_ROUTER_ORIGIN_RETRY_MAX_DELAY_MS` (default `3000`)
-- `LLM_ROUTER_ORIGIN_FALLBACK_COOLDOWN_MS` (default `45000`)
-- `LLM_ROUTER_ORIGIN_RATE_LIMIT_COOLDOWN_MS` (default `30000`)
-- `LLM_ROUTER_ORIGIN_BILLING_COOLDOWN_MS` (default `900000`)
-- `LLM_ROUTER_ORIGIN_AUTH_COOLDOWN_MS` (default `600000`)
-- `LLM_ROUTER_ORIGIN_POLICY_COOLDOWN_MS` (default `120000`)
-- `LLM_ROUTER_ALLOW_POLICY_FALLBACK` (default `false`)
-- `LLM_ROUTER_FALLBACK_CIRCUIT_FAILURES` (default `2`)
-- `LLM_ROUTER_FALLBACK_CIRCUIT_COOLDOWN_MS` (default `30000`)
-- `LLM_ROUTER_MAX_REQUEST_BODY_BYTES` (default `1048576`, min `4096`, max `20971520`)
-- `LLM_ROUTER_UPSTREAM_TIMEOUT_MS` (default `60000`, min `1000`, max `300000`)
+## Config File Location
 
-Optional browser access (CORS):
-- By default, cross-origin browser reads are denied unless explicitly allow-listed.
-- `LLM_ROUTER_CORS_ALLOWED_ORIGINS` (comma-separated exact origins, e.g. `https://app.example.com`)
-- `LLM_ROUTER_CORS_ALLOW_ALL=true` (allows any origin; not recommended for production)
-
-Optional source IP allowlist (recommended for Worker deployments):
-- `LLM_ROUTER_ALLOWED_IPS` (comma-separated client IPs; denies requests from all other IPs)
-- `LLM_ROUTER_IP_ALLOWLIST` (alias of `LLM_ROUTER_ALLOWED_IPS`)
-
-## Default Config Path
+Local config file:
 
 `~/.llm-router.json`
 
-Minimal shape:
-
-```json
-{
-  "version": 2,
-  "masterKey": "local_or_worker_key",
-  "defaultModel": "chat.default",
-  "modelAliases": {
-    "chat.default": {
-      "strategy": "auto",
-      "targets": [
-        { "ref": "openrouter/gpt-4o" },
-        { "ref": "anthropic/claude-3-5-haiku" }
-      ],
-      "fallbackTargets": [
-        { "ref": "openrouter/gpt-4o-mini" }
-      ]
-    }
-  },
-  "providers": [
-    {
-      "id": "openrouter",
-      "name": "OpenRouter",
-      "baseUrl": "https://openrouter.ai/api/v1",
-      "apiKey": "sk-or-v1-...",
-      "formats": ["openai"],
-      "models": [{ "id": "gpt-4o" }],
-      "rateLimits": [
-        {
-          "id": "openrouter-all-month",
-          "name": "Monthly cap",
-          "models": ["all"],
-          "requests": 20000,
-          "window": { "unit": "month", "size": 1 }
-        }
-      ]
-    }
-  ]
-}
-```
-
-Direct vs model alias routing:
-- Direct route: request `model=provider/model` and optional model-level `fallbackModels` applies.
-- Model alias route: request `model=alias.id` (or set as `defaultModel`) and the model alias `targets` + `strategy` drive balancing. `auto` is the recommended default for new model aliases.
-
-State durability caveats:
-- Local Node (`llm-router start`): routing state defaults to file-backed local persistence, so cooldowns/caps survive restarts.
-- Cloudflare Worker: default state is in-memory per isolate for now; long-window counters are best-effort until a durable Worker backend is configured.
+## Security
 
-## Smoke Test
+See [`SECURITY.md`](./SECURITY.md).
 
-```bash
-npm run test:provider-smoke
-```
+## Versioning
 
-Use `.env.test-suite.example` as template for provider-based smoke tests.
+- Semver: [Semantic Versioning](https://semver.org/)
+- Release notes: [`CHANGELOG.md`](./CHANGELOG.md)

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@khanglvm/llm-router",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Single gateway endpoint for multi-provider LLMs with unified OpenAI+Anthropic format and seamless fallback",
+  "keywords": [
+    "llm-router",
+    "llm-gateway",
+    "ai-proxy",
+    "openai-compatible",
+    "anthropic-compatible",
+    "model-routing",
+    "fallback",
+    "load-balancing",
+    "cloudflare-workers",
+    "agent-infra"
+  ],
   "type": "module",
   "main": "src/index.js",
   "bin": {

package/src/cli/router-module.js

@@ -90,6 +90,7 @@ const MODEL_ROUTING_STRATEGY_OPTIONS = [
 const MODEL_ALIAS_STRATEGIES = MODEL_ROUTING_STRATEGY_OPTIONS.map((option) => option.value);
 const DEFAULT_PROBE_REQUESTS_PER_MINUTE = 30;
 const DEFAULT_PROBE_MAX_RATE_LIMIT_RETRIES = 3;
+const DEFAULT_AI_HELP_GATEWAY_TEST_TIMEOUT_MS = 6000;
 const RATE_LIMIT_WINDOW_UNIT_ALIASES = new Map([
   ["s", "second"],
   ["sec", "second"],
@@ -4659,6 +4660,497 @@ async function runUpdateAction(context) {
   };
 }
 
+function toHomeRelativePath(value) {
+  const input = String(value || "").trim();
+  const home = String(process.env.HOME || "").trim();
+  if (!input || !home) return input;
+  if (!input.startsWith(`${home}/`)) return input;
+  return `~${input.slice(home.length)}`;
+}
+
+function collectEnabledModelRefsFromConfig(config) {
+  const providers = (config?.providers || []).filter((provider) => provider && provider.enabled !== false);
+  const refs = [];
+  for (const provider of providers) {
+    const providerId = String(provider?.id || "").trim();
+    if (!providerId) continue;
+    for (const model of (provider.models || [])) {
+      if (!model || model.enabled === false) continue;
+      const modelId = String(model.id || "").trim();
+      if (!modelId) continue;
+      refs.push(`${providerId}/${modelId}`);
+    }
+  }
+  return dedupeList(refs);
+}
+
+function quoteShellSingle(value) {
+  return `'${String(value || "").replace(/'/g, "'\"'\"'")}'`;
+}
+
+function buildCurlGuideCommand(url, {
+  method = "GET",
+  headers = [],
+  jsonBody
+} = {}) {
+  const parts = ["curl -sS"];
+  if (String(method || "").toUpperCase() !== "GET") {
+    parts.push(`-X ${String(method || "").toUpperCase()}`);
+  }
+  for (const header of headers) {
+    parts.push(`-H ${quoteShellSingle(header)}`);
+  }
+  if (jsonBody !== undefined) {
+    parts.push("-H 'content-type: application/json'");
+    parts.push(`--data ${quoteShellSingle(JSON.stringify(jsonBody))}`);
+  }
+  parts.push(quoteShellSingle(url));
+  return parts.join(" ");
+}
+
+async function runGatewayHttpProbe({
+  url,
+  method = "GET",
+  headers = {},
+  jsonBody,
+  timeoutMs = DEFAULT_AI_HELP_GATEWAY_TEST_TIMEOUT_MS
+} = {}) {
+  const requestHeaders = { ...(headers || {}) };
+  const requestInit = {
+    method: String(method || "GET").toUpperCase(),
+    headers: requestHeaders
+  };
+
+  if (jsonBody !== undefined) {
+    if (!requestHeaders["content-type"] && !requestHeaders["Content-Type"]) {
+      requestHeaders["content-type"] = "application/json";
+    }
+    requestInit.body = JSON.stringify(jsonBody);
+  }
+
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+    requestInit.signal = AbortSignal.timeout(timeoutMs);
+  }
+
+  try {
+    const response = await fetch(url, requestInit);
+    const rawText = await response.text();
+    return {
+      ok: response.ok,
+      status: response.status,
+      payload: parseJsonSafely(rawText),
+      rawText: String(rawText || "").trim().slice(0, 280)
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 0,
+      payload: null,
+      rawText: "",
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+function summarizeProbeMessage(probe) {
+  if (!probe) return "";
+  if (probe.error) return String(probe.error);
+  const payloadError = probe.payload?.error;
+  if (typeof payloadError === "string") return payloadError.trim();
+  if (payloadError && typeof payloadError === "object") {
+    if (payloadError.message) return String(payloadError.message).trim();
+    if (payloadError.type) return String(payloadError.type).trim();
+  }
+  if (probe.rawText) return String(probe.rawText).trim().slice(0, 140);
+  return "";
+}
+
+function formatProbeStatusLabel(probe, {
+  passStatuses = [200],
+  passWhenStatusIsNot = null
+} = {}) {
+  if (!probe) return "not-run";
+  if (probe.error) return `error (${probe.error})`;
+  const status = Number(probe.status || 0);
+  const isPass = passWhenStatusIsNot !== null
+    ? status !== passWhenStatusIsNot
+    : passStatuses.includes(status);
+  const message = summarizeProbeMessage(probe);
+  if (message) return `${isPass ? "pass" : "fail"} (status=${status}; ${message})`;
+  return `${isPass ? "pass" : "fail"} (status=${status})`;
+}
+
+async function runAiHelpGatewayLiveTests({
+  runtimeState,
+  authToken = "",
+  probeModel = "",
+  timeoutMs = DEFAULT_AI_HELP_GATEWAY_TEST_TIMEOUT_MS
+} = {}) {
+  if (!runtimeState) {
+    return {
+      ran: false,
+      reason: "local-server-not-running",
+      baseUrl: "",
+      tests: {}
+    };
+  }
+
+  const baseUrl = `http://${runtimeState.host}:${runtimeState.port}`;
+  const token = String(authToken || "").trim();
+  const headers = token
+    ? {
+        Authorization: `Bearer ${token}`,
+        "x-api-key": token
+      }
+    : {};
+
+  const modelId = String(probeModel || "").trim() || "chat.default";
+  const [health, openaiModels, claudeModels, codexResponses] = await Promise.all([
+    runGatewayHttpProbe({
+      url: `${baseUrl}/health`,
+      method: "GET",
+      headers,
+      timeoutMs
+    }),
+    runGatewayHttpProbe({
+      url: `${baseUrl}/openai/v1/models`,
+      method: "GET",
+      headers,
+      timeoutMs
+    }),
+    runGatewayHttpProbe({
+      url: `${baseUrl}/anthropic/v1/models`,
+      method: "GET",
+      headers,
+      timeoutMs
+    }),
+    runGatewayHttpProbe({
+      url: `${baseUrl}/openai/v1/responses`,
+      method: "POST",
+      headers,
+      jsonBody: {
+        model: modelId,
+        input: "ping"
+      },
+      timeoutMs
+    })
+  ]);
+
+  return {
+    ran: true,
+    reason: "completed",
+    baseUrl,
+    tests: {
+      health,
+      openaiModels,
+      claudeModels,
+      codexResponses
+    }
+  };
+}
+
+async function runAiHelpAction(context) {
+  const args = context.args || {};
+  const configPath = readArg(args, ["config", "configPath"], getDefaultConfigPath());
+  const skipLiveTest = toBoolean(readArg(args, ["skip-live-test", "skipLiveTest"], false), false);
+  const liveTestTimeoutMs = toPositiveInteger(
+    readArg(args, ["live-test-timeout-ms", "liveTestTimeoutMs"], DEFAULT_AI_HELP_GATEWAY_TEST_TIMEOUT_MS),
+    DEFAULT_AI_HELP_GATEWAY_TEST_TIMEOUT_MS,
+    { min: 500, max: 60_000 }
+  );
+  const explicitGatewayAuthToken = String(readArg(args, ["gateway-auth-token", "gatewayAuthToken"], "") || "").trim();
+  const config = await readConfigFile(configPath);
+
+  const providers = (config.providers || []).filter((provider) => provider && provider.enabled !== false);
+  const providerCount = providers.length;
+  const modelCount = providers.reduce((sum, provider) => {
+    const count = (provider.models || []).filter((model) => model && model.enabled !== false).length;
+    return sum + count;
+  }, 0);
+
+  const aliasEntries = Object.entries(config.modelAliases || {});
+  const aliasCount = aliasEntries.length;
+  const aliasStrategySummary = aliasEntries
+    .map(([aliasId, alias]) => `${aliasId}:${alias?.strategy || "ordered"}`)
+    .join(", ") || "(none)";
+  const rateLimitBucketCount = providers.reduce((sum, provider) => sum + (provider.rateLimits || []).length, 0);
+  const defaultModel = String(config.defaultModel || "smart");
+  const hasMasterKey = Boolean(String(config.masterKey || "").trim());
+
+  let runtimeState = null;
+  try {
+    runtimeState = await getActiveRuntimeState();
+  } catch {
+    runtimeState = null;
+  }
+  const serverRunning = Boolean(runtimeState);
+  const runtimeRequiresAuth = Boolean(runtimeState?.requireAuth);
+
+  let runtimeConfig = null;
+  const runtimeConfigPath = String(runtimeState?.configPath || "").trim();
+  if (runtimeConfigPath && runtimeConfigPath !== configPath) {
+    try {
+      runtimeConfig = await readConfigFile(runtimeConfigPath);
+    } catch {
+      runtimeConfig = null;
+    }
+  }
+
+  const runtimeMasterKey = String(runtimeConfig?.masterKey || "").trim();
+  const gatewayAuthToken = explicitGatewayAuthToken
+    || (runtimeConfigPath && runtimeConfigPath !== configPath ? runtimeMasterKey : "")
+    || String(config.masterKey || "").trim()
+    || runtimeMasterKey;
+
+  const directModelRefs = collectEnabledModelRefsFromConfig(config);
+  const aliasIds = aliasEntries.map(([aliasId]) => aliasId);
+  const modelDecisionOptions = dedupeList([
+    defaultModel && defaultModel !== "smart" ? defaultModel : "",
+    ...aliasIds,
+    ...directModelRefs
+  ]);
+  const probeModel = modelDecisionOptions[0] || "chat.default";
+
+  let liveTest = {
+    ran: false,
+    reason: skipLiveTest ? "skipped-by-flag" : "local-server-not-running",
+    baseUrl: serverRunning ? `http://${runtimeState.host}:${runtimeState.port}` : "",
+    tests: {}
+  };
+  if (!skipLiveTest && serverRunning) {
+    liveTest = await runAiHelpGatewayLiveTests({
+      runtimeState,
+      authToken: gatewayAuthToken,
+      probeModel,
+      timeoutMs: liveTestTimeoutMs
+    });
+  }
+
+  const healthProbe = liveTest.tests?.health || null;
+  const openaiModelsProbe = liveTest.tests?.openaiModels || null;
+  const claudeModelsProbe = liveTest.tests?.claudeModels || null;
+  const codexResponsesProbe = liveTest.tests?.codexResponses || null;
+
+  const claudePatchGate = !liveTest.ran
+    ? "pending-live-test"
+    : (claudeModelsProbe?.status === 200 ? "ready" : "blocked");
+  const openCodePatchGate = !liveTest.ran
+    ? "pending-live-test"
+    : (openaiModelsProbe?.status === 200 ? "ready" : "blocked");
+  let codexPatchGate = "pending-live-test";
+  if (liveTest.ran) {
+    if (codexResponsesProbe?.error) {
+      codexPatchGate = "blocked";
+    } else if (codexResponsesProbe?.status === 404) {
+      codexPatchGate = "blocked-responses-endpoint-missing";
+    } else if ([401, 403].includes(Number(codexResponsesProbe?.status || 0))) {
+      codexPatchGate = "blocked-auth";
+    } else {
+      codexPatchGate = "ready";
+    }
+  }
+
+  const suggestions = [];
+  if (providerCount === 0) {
+    suggestions.push("Add first provider with at least one model. Run: llm-router config --operation=upsert-provider --provider-id=<id> --name=\"<name>\" --base-url=<url> --api-key=<key> --models=<model1,model2>");
+  } else {
+    const providersWithoutModels = providers
+      .filter((provider) => (provider.models || []).filter((model) => model && model.enabled !== false).length === 0)
+      .map((provider) => provider.id);
+    if (providersWithoutModels.length > 0) {
+      suggestions.push(`Add models to provider(s) with empty model list: ${providersWithoutModels.join(", ")}. Run: llm-router config --operation=upsert-provider --provider-id=<id> --models=<model1,model2>`);
+    }
+  }
+
+  if (modelCount > 0 && aliasCount === 0) {
+    suggestions.push("Create a model alias/group for stable app routing. Run: llm-router config --operation=upsert-model-alias --alias-id=chat.default --strategy=auto --targets=<provider/model,...>");
+  }
+
+  if (aliasCount > 0) {
+    const nonAutoAliases = aliasEntries
+      .filter(([, alias]) => String(alias?.strategy || "ordered") !== "auto")
+      .map(([aliasId]) => aliasId);
+    if (nonAutoAliases.length > 0) {
+      suggestions.push(`Review load-balancer strategy for alias(es): ${nonAutoAliases.join(", ")}. Recommended default: auto.`);
+    }
+  }
+
+  if (providerCount > 0 && rateLimitBucketCount === 0) {
+    suggestions.push("Add at least one provider rate-limit bucket for quota safety. Run: llm-router config --operation=set-provider-rate-limits --provider-id=<id> --bucket-name=\"Monthly cap\" --bucket-models=all --bucket-requests=<n> --bucket-window=month:1");
+  }
+
+  if (!hasMasterKey) {
+    suggestions.push("Set master key for authenticated access. Run: llm-router config --operation=set-master-key --generate-master-key=true");
+  }
+
+  if (!serverRunning) {
+    suggestions.push(`Start local proxy server. Run: llm-router start${hasMasterKey ? " --require-auth=true" : ""}`);
+  } else {
+    suggestions.push(`Local proxy is running on http://${runtimeState.host}:${runtimeState.port}. Apply config changes with llm-router config; updates hot-reload automatically.`);
+  }
+
+  if (serverRunning && skipLiveTest) {
+    suggestions.push("Run live llm-router API test before patching coding-tool config. Re-run: llm-router ai-help --skip-live-test=false");
+  }
+
+  if (liveTest.ran && claudePatchGate !== "ready") {
+    suggestions.push("Claude/OpenCode patch gate is blocked. Fix llm-router auth/provider/model readiness, then re-run llm-router ai-help.");
+  }
+  if (liveTest.ran && codexPatchGate === "blocked-responses-endpoint-missing") {
+    suggestions.push("Codex CLI requires OpenAI Responses API. Current llm-router endpoint does not expose /openai/v1/responses; do not patch Codex until this gate is resolved.");
+  }
+
+  if (suggestions.length === 0) {
+    suggestions.push("No blocking setup gaps detected. Review routing summary with: llm-router config --operation=list-routing");
+  }
+
+  const runtimeConfigPathForDisplay = runtimeConfigPath ? toHomeRelativePath(runtimeConfigPath) : "";
+  const gatewayBaseUrlForGuide = liveTest.baseUrl || (serverRunning ? `http://${runtimeState.host}:${runtimeState.port}` : "http://127.0.0.1:8787");
+  const authGuideHeaders = runtimeRequiresAuth ? ["Authorization: Bearer <master_key>"] : [];
+
+  const lines = [
+    "# AI-HELP",
+    "ENTITY: llm-router",
+    "MODE: cli-automation",
+    "PROFILE: agent-guide-v2",
+    "",
+    "## INTRO",
+    "Use this output as an AI-agent operating brief for llm-router.",
+    "The agent should auto-discover commands, inspect current state, configure llm-router on your behalf, run live API gates, and only then patch coding tool configs.",
+    "",
+    "## WHAT AGENT CAN DO WITH LLM-ROUTER",
+    "- explain llm-router capabilities and current setup readiness",
+    "- set provider, model list, model alias/group, and rate-limit buckets via CLI",
+    "- validate local llm-router endpoint health/model-list/routes with real API probes",
+    "- patch coding tools (Claude Code, Codex CLI, OpenCode) after pre-patch gates pass",
+    "",
+    "## DISCOVERY COMMANDS",
+    "- llm-router -h",
+    "- llm-router config -h",
+    "- llm-router start -h",
+    "- llm-router deploy -h",
+    "",
+    "## CURRENT STATE",
+    `- config_path=${configPath}`,
+    `- providers=${providerCount}`,
+    `- models=${modelCount}`,
+    `- model_aliases=${aliasCount}`,
+    `- alias_strategies=${aliasStrategySummary}`,
+    `- rate_limit_buckets=${rateLimitBucketCount}`,
+    `- default_model=${defaultModel}`,
+    `- master_key_configured=${hasMasterKey}`,
+    `- local_server_running=${serverRunning}`,
+    serverRunning ? `- local_server_endpoint=http://${runtimeState.host}:${runtimeState.port}` : "",
+    runtimeState ? `- local_server_require_auth=${runtimeRequiresAuth}` : "",
+    runtimeConfigPathForDisplay ? `- local_server_config_path=${runtimeConfigPathForDisplay}` : "",
+    "",
+    "## MODEL/GROUP DECISION INPUT (REQUIRED BEFORE PATCHING TOOL CONFIG)",
+    "- Ask user to choose target_tool: claude-code | codex-cli | opencode",
+    "- Ask user to choose target_model_or_group for that tool",
+    `- available_alias_groups=${aliasIds.join(", ") || "(none)"}`,
+    `- available_direct_models=${directModelRefs.join(", ") || "(none)"}`,
+    `- decision_options_preview=${modelDecisionOptions.slice(0, 12).join(", ") || "(none)"}`,
+    "- If user chooses an alias/group, keep alias id unchanged so llm-router balancing still works.",
+    "",
+    "## PRE-PATCH API GATE (MUST PASS BEFORE EDITING TOOL CONFIG)",
+    `- live_test_mode=${skipLiveTest ? "skipped-by-flag" : (liveTest.ran ? "executed" : "pending-local-server")}`,
+    `- live_test_timeout_ms=${liveTestTimeoutMs}`,
+    `- gateway_base_url=${gatewayBaseUrlForGuide}`,
+    `- health_probe=${liveTest.ran ? formatProbeStatusLabel(healthProbe, { passStatuses: [200] }) : "not-run"}`,
+    `- openai_models_probe=${liveTest.ran ? formatProbeStatusLabel(openaiModelsProbe, { passStatuses: [200] }) : "not-run"}`,
+    `- claude_models_probe=${liveTest.ran ? formatProbeStatusLabel(claudeModelsProbe, { passStatuses: [200] }) : "not-run"}`,
+    `- codex_responses_probe=${liveTest.ran ? formatProbeStatusLabel(codexResponsesProbe, { passWhenStatusIsNot: 404 }) : "not-run"}`,
+    `- patch_gate_claude_code=${claudePatchGate}`,
+    `- patch_gate_opencode=${openCodePatchGate}`,
+    `- patch_gate_codex_cli=${codexPatchGate}`,
+    "- Rule: Do NOT patch any coding-tool config until required gate is ready.",
+    "",
+    "## LIVE TEST COMMANDS (RUN BEFORE PATCHING TOOL CONFIG)",
+    runtimeRequiresAuth ? "- export LLM_ROUTER_MASTER_KEY='<master_key>'" : "- Local auth currently disabled; auth header is optional.",
+    `- ${buildCurlGuideCommand(`${gatewayBaseUrlForGuide}/health`, { method: "GET", headers: authGuideHeaders })}`,
+    `- ${buildCurlGuideCommand(`${gatewayBaseUrlForGuide}/openai/v1/models`, { method: "GET", headers: authGuideHeaders })}`,
+    `- ${buildCurlGuideCommand(`${gatewayBaseUrlForGuide}/anthropic/v1/models`, { method: "GET", headers: authGuideHeaders })}`,
+    `- ${buildCurlGuideCommand(`${gatewayBaseUrlForGuide}/openai/v1/responses`, {
+      method: "POST",
+      headers: authGuideHeaders,
+      jsonBody: { model: "<target_model_or_group>", input: "ping" }
+    })}  # required for Codex CLI compatibility`,
+    "",
+    "## LLM-ROUTER CONFIG WORKFLOWS (CLI)",
+    "1. Upsert provider + models:",
+    "   llm-router config --operation=upsert-provider --provider-id=<id> --name=\"<name>\" --endpoints=<url1,url2> --api-key=<key> --models=<model1,model2>",
+    "2. Upsert model alias/group:",
+    "   llm-router config --operation=upsert-model-alias --alias-id=<alias> --strategy=auto --targets=<provider/model,...>",
+    "3. Set provider rate limit bucket:",
+    "   llm-router config --operation=set-provider-rate-limits --provider-id=<id> --bucket-name=\"Monthly cap\" --bucket-models=all --bucket-requests=<n> --bucket-window=month:1",
+    "4. Review final routing summary:",
+    "   llm-router config --operation=list-routing",
+    "",
+    "## CODING TOOL PATCH PLAYBOOK",
+    "### Claude Code",
+    "- patch_target_priority=.claude/settings.local.json (project) -> ~/.claude/settings.json (user)",
+    "- required_gate=patch_gate_claude_code=ready",
+    "- set env keys: ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL",
+    "```json",
+    "{",
+    "  \"env\": {",
+    `    \"ANTHROPIC_BASE_URL\": \"${gatewayBaseUrlForGuide}/anthropic\",`,
+    "    \"ANTHROPIC_AUTH_TOKEN\": \"<master_key>\",",
+    "    \"ANTHROPIC_MODEL\": \"<target_model_or_group>\"",
+    "  }",
+    "}",
+    "```",
+    "",
+    "### Codex CLI",
+    "- patch_target_priority=.codex/config.toml (project) -> ~/.codex/config.toml (user)",
+    "- required_gate=patch_gate_codex_cli=ready",
+    "- hard requirement: Codex uses OpenAI Responses API; /openai/v1/responses must be reachable",
+    "```toml",
+    "model_provider = \"llm_router\"",
+    "model = \"<target_model_or_group>\"",
+    "",
+    "[model_providers.llm_router]",
+    "name = \"llm-router\"",
+    `base_url = \"${gatewayBaseUrlForGuide}/openai/v1\"`,
+    "wire_api = \"responses\"",
+    "env_http_headers = { Authorization = \"LLM_ROUTER_AUTH_HEADER\" }",
+    "```",
+    "- export env before launching Codex: export LLM_ROUTER_AUTH_HEADER='Bearer <master_key>'",
+    "",
+    "### OpenCode",
+    "- patch_target_priority=./opencode.json (project) -> ~/.config/opencode/opencode.json (user)",
+    "- required_gate=patch_gate_opencode=ready",
+    "```json",
+    "{",
+    "  \"model\": \"<target_model_or_group>\",",
+    "  \"small_model\": \"<target_model_or_group>\",",
+    "  \"provider\": {",
+    "    \"llm-router\": {",
+    "      \"options\": {",
+    `        \"baseURL\": \"${gatewayBaseUrlForGuide}/openai\",`,
+    "        \"apiKey\": \"<master_key>\"",
+    "      }",
+    "    }",
+    "  }",
+    "}",
+    "```",
+    "",
+    "## NEXT SUGGESTIONS",
+    ...suggestions.map((item, index) => `${index + 1}. ${item}`),
+    "",
+    "## UPDATE RULE",
+    "When local server is running, llm-router config changes are hot-reloaded in memory (no manual restart required).",
+    "Agent policy: always run live API gate checks first, then patch tool configs only after gate status is ready."
+  ].filter(Boolean);
+
+  return {
+    ok: true,
+    mode: context.mode,
+    exitCode: EXIT_SUCCESS,
+    data: lines.join("\n")
+  };
+}
+
 async function runDeployAction(context) {
   const args = context.args || {};
   const configPath = readArg(args, ["config", "configPath"], getDefaultConfigPath());
@@ -5352,6 +5844,44 @@ const routerModule = {
       },
       run: runUpdateAction
     },
+    {
+      actionId: "ai-help",
+      description: "Print AI-agent guide with llm-router setup workflows, live API gates, and coding-tool patch playbooks.",
+      tui: { steps: ["print-ai-help"] },
+      commandline: {
+        requiredArgs: [],
+        optionalArgs: [
+          "config",
+          "skip-live-test",
+          "live-test-timeout-ms",
+          "gateway-auth-token"
+        ]
+      },
+      help: {
+        summary: "AI guide for setup + operation: state snapshot, provider/alias/rate-limit workflows, live gateway tests, and patch rules for Claude/Codex/OpenCode.",
+        args: [
+          { name: "config", required: false, description: "Path to config file used for state-aware suggestions.", example: "--config=~/.llm-router.json" },
+          { name: "skip-live-test", required: false, description: "Skip live llm-router API probes in ai-help output.", example: "--skip-live-test=true" },
+          { name: "live-test-timeout-ms", required: false, description: `HTTP timeout for ai-help live probes (default ${DEFAULT_AI_HELP_GATEWAY_TEST_TIMEOUT_MS}ms).`, example: "--live-test-timeout-ms=8000" },
+          { name: "gateway-auth-token", required: false, description: "Override auth token for live probes when runtime config differs from selected --config.", example: "--gateway-auth-token=gw_..." }
+        ],
+        examples: [
+          "llm-router ai-help",
+          "llm-router ai-help --config=~/.llm-router.json",
+          "llm-router ai-help --skip-live-test=true",
+          "llm-router ai-help --live-test-timeout-ms=8000"
+        ],
+        useCases: [
+          {
+            name: "agent setup brief",
+            description: "Generate a machine-readable operating guide so AI agents can configure llm-router, run pre-patch API gates, and patch tool configs safely.",
+            command: "llm-router ai-help"
+          }
+        ],
+        keybindings: []
+      },
+      run: runAiHelpAction
+    },
     {
       actionId: "config",
       description: "Config manager for providers/models/master-key/startup service.",