@jacobbd/relay-ai 0.2.5 → 0.2.6

package/.markdown-link-check.json

@@ -0,0 +1,7 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^https://www\\.npmjs\\.com/package/"
+    }
+  ]
+}

package/AGENTS.md

@@ -150,9 +150,9 @@ In all cases `process.env['OPENCODE_API_KEY']` is set immediately so the key is
 - `--restore` globs `models-*.json` (CLI) and `app-models-*.json` (App); the new files are `models-favorites.json` and `app-models-favorites.json`.
 - Zen/Go favorites are skipped in Codex (use Claude or Desktop gateway).
 
-## Release status (v0.2.5)
+## Release status (v0.2.6)
 
-Current version is **v0.2.5** — native provider registry, agent boot flags (`--provider` / `--model`), `relay-ai --ai`, Codex favorites catalog, Codex App restore handling, reasoning capability metadata, and OpenCode cloud provider setup in `relay-ai providers add`.
+Current version is **v0.2.6** — official launch release with the native provider registry, complete Claude/Codex app help, unified OpenCode Zen / Go setup, duplicate-provider migration, stable post-import refreshes, agent boot flags (`--provider` / `--model`), `relay-ai --ai`, favorites catalogs, and reasoning capability metadata.
 
 **Known limitations (by design):**
 - Cost display in Codex is always inaccurate for non-Anthropic models.

package/CHANGELOG.md

@@ -1,13 +1,20 @@
 # Changelog
 
-## [0.2.5] - 2026-06-18 (Official Launch Release)
+## [0.2.6] - 2026-06-18 (Official Launch Release)
 
 ### Added
 - **Native provider registry** — Add, list, remove, refresh, and import providers with secure OS credential storage and templates for OpenRouter, Groq, Mistral, Together AI, Zen/Go, and SDK-backed custom endpoints.
 - **Claude Code and Codex launchers** — Launch registry models through `relay-ai`, including provider/model boot flags, local OpenCode provider discovery, recent models, search, pagination, and favorites catalogs for mid-session switching.
 - **Unified SDK gateway** — Route non-Anthropic providers through the Vercel AI SDK adapter while preserving Anthropic-compatible tool use, streaming, context windows, and model catalogs.
 - **Codex App integration** — Launch the desktop app with registry providers and restore Codex App model settings after interrupted sessions.
+- **Claude Desktop integration** — Launch Claude Desktop in third-party provider mode with automatic configuration backup and restore.
 - **Reasoning capability metadata** — Resolve reasoning controls from provider metadata, including OpenRouter `supported_parameters`, so models such as GLM 5.2 receive compatible reasoning options instead of stale defaults.
 - **Foreground server gateway** — Run `relay-ai server` for Claude Desktop or LAN usage, with registry-backed routing, password protection, and optional Vertex AI support.
 - **First-run setup** — Configure providers from an inline wizard or import existing OpenCode provider settings.
+- **Complete command help** — Document every top-level command and managed option, including `codex-app`, `claude-app`, Vertex, restore, config, trace, and agent-reference flags.
 
+### Fixed
+- **Unified OpenCode cloud setup** — Configure OpenCode Zen / Go once with their shared API key while preserving separate internal routes for overlapping model IDs and distinct upstream endpoints.
+- **Duplicate OpenCode providers** — Map OpenCode CLI IDs to Relay IDs, compare existing configurations during import, and automatically migrate or remove legacy `opencode` / `opencode-go` registry duplicates.
+- **Stable model refreshes** — Refresh imported providers sequentially against one shared registry so provider caches cannot overwrite each other.
+- **Accurate refresh reporting** — Treat imported catalogs as snapshots rather than live-refresh baselines, preventing misleading first-refresh model-count deltas.

package/README.md

@@ -8,7 +8,7 @@
 > Relay any model into any coding agent — launch tools, switch providers, and run local API gateways.
 
 [![npm version](https://img.shields.io/npm/v/@jacobbd/relay-ai)](https://www.npmjs.com/package/@jacobbd/relay-ai)
-[![License](https://img.shields.io/npm/l/@jacobbd/relay-ai)](https://github.com/jacob-bd/relay-ai/blob/main/LICENSE)
+[![License](https://img.shields.io/npm/l/@jacobbd/relay-ai)](LICENSE)
 [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?style=flat-square&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/jacobbd)
 
 **relay-ai** is an interactive CLI that launches AI coding tools and runs local API gateways on your machine. Currently, it supports **Claude Code**, **Claude Desktop (Cowork + Code)**, the **OpenAI Codex CLI**, and the **Codex desktop app (macOS + Windows)**.
@@ -30,7 +30,9 @@ Pick your backend:
 | `relay-ai models` | Manage favorite models for mid-session `/model` switching |
 | `relay-ai server` | Foreground API gateway (registry providers + optional Zen/Go) |
 | `relay-ai server --vertex` | Foreground Anthropic-compatible gateway to Claude on Vertex AI |
+| `relay-ai claude-app` | Launch Claude Desktop app with registry providers ([guide](docs/CLAUDE_DESKTOP_SETUP.md)) |
 | `relay-ai codex` | Launch OpenAI Codex CLI with registry providers ([guide](docs/CODEX.md)) |
+| `relay-ai codex-app` | Launch Codex desktop app with registry providers ([guide](docs/CODEX.md)) |
 | `relay-ai --ai` | Full agent reference for scripts and alef-agent ([guide](docs/AI-AGENTS.md)) |
 
 Bare `relay-ai` prints help and migration guidance. Use `relay-ai claude` for the wizard.
@@ -80,14 +82,48 @@ Bare `relay-ai` prints help and migration guidance. Use `relay-ai claude` for th
 
 ## Installation
 
+To install the CLI globally:
+
 ```bash
-# Install globally
 npm install -g @jacobbd/relay-ai
+```
+
+### Upgrading
 
-# Upgrade to the latest version
+To upgrade to the latest version:
+
+```bash
 npm update -g @jacobbd/relay-ai
 ```
 
+### Uninstallation
+
+To uninstall the CLI globally:
+
+```bash
+npm uninstall -g @jacobbd/relay-ai
+```
+
+> [!NOTE]
+> If you use a Node version manager like **NVM**, make sure you run the uninstall command using the active Node version that was used to install it (e.g., run `nvm use <version>` first).
+
+To fully remove the tool and all its configuration data, you can delete the configuration directory (`.relay-ai`) on your operating system:
+
+- **macOS / Linux**:
+  ```bash
+  rm -rf ~/.relay-ai
+  ```
+- **Windows**:
+  - In Command Prompt:
+    ```cmd
+    rmdir /s /q "%USERPROFILE%\.relay-ai"
+    ```
+  - In PowerShell:
+    ```powershell
+    Remove-Item -Recurse -Force "$env:USERPROFILE\.relay-ai"
+    ```
+
+
 ## Setup
 
 ### Configure providers

package/dist/cli.js

@@ -76,7 +76,7 @@ function classifyModelFormat(modelId, providerNpm) {
   if (lower.startsWith("gemini-")) return "unsupported";
   return "openai";
 }
-var VERSION = "0.2.5";
+var VERSION = "0.2.6";
 
 // src/provider-factory.ts
 var RESPONSES_ONLY_PREFIXES = [
@@ -1210,6 +1210,32 @@ import { dirname } from "path";
 // src/registry/types.ts
 var REGISTRY_SCHEMA_VERSION = 1;
 
+// src/registry/migrate.ts
+var LEGACY_CLOUD_PROVIDER_IDS = [
+  { legacyId: "opencode", id: "zen", name: "OpenCode Zen" },
+  { legacyId: "opencode-go", id: "go", name: "OpenCode Go" }
+];
+function migrateLegacyCloudProviders(registry) {
+  let changed = false;
+  for (const { legacyId, id, name } of LEGACY_CLOUD_PROVIDER_IDS) {
+    const legacyIdx = registry.providers.findIndex((provider) => provider.id === legacyId);
+    if (legacyIdx < 0) continue;
+    if (registry.providers.some((provider) => provider.id === id)) {
+      registry.providers.splice(legacyIdx, 1);
+    } else {
+      registry.providers[legacyIdx] = {
+        ...registry.providers[legacyIdx],
+        id,
+        templateId: id,
+        name,
+        api: {}
+      };
+    }
+    changed = true;
+  }
+  return changed;
+}
+
 // src/registry/validate.ts
 var PROVIDER_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 function isValidProviderId(id) {
@@ -1315,7 +1341,14 @@ function loadRegistry(path = getProvidersPath()) {
   }
   try {
     const raw = JSON.parse(readFileSync(path, "utf8"));
-    return parseRegistry(raw);
+    const registry = parseRegistry(raw);
+    if (migrateLegacyCloudProviders(registry)) {
+      try {
+        saveRegistry(registry, path);
+      } catch {
+      }
+    }
+    return registry;
   } catch {
     return { schemaVersion: REGISTRY_SCHEMA_VERSION, providers: [] };
   }
@@ -3298,7 +3331,6 @@ function localProviderToRegistry(provider, opts) {
       ...apiUrl ? { url: apiUrl } : {}
     },
     addedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    refreshedAt: (/* @__PURE__ */ new Date()).toISOString(),
     modelsCache: {
       fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
       models: provider.models.map(modelToCached)
@@ -3360,11 +3392,25 @@ async function resolveRefreshCredential(provider, resolveKey) {
 function oauthAuthRef(providerId) {
   return `keyring:oauth:provider:${providerId}`;
 }
+function normalizeImportProviderIdentity(provider) {
+  if (provider.id === "opencode") {
+    return { ...provider, id: "zen", name: "OpenCode Zen" };
+  }
+  if (provider.id === "opencode-go") {
+    return { ...provider, id: "go", name: "OpenCode Go" };
+  }
+  return provider;
+}
 function buildImportProviderList(raw, authEntries) {
   const oauthByProviderId = /* @__PURE__ */ new Map();
-  const apiProviders = normalizeProviders(raw);
-  const covered = new Set(apiProviders.map((p19) => p19.id));
-  const merged = [...apiProviders];
+  const covered = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const provider of normalizeProviders(raw)) {
+    const normalized = normalizeImportProviderIdentity(provider);
+    if (covered.has(normalized.id)) continue;
+    merged.push(normalized);
+    covered.add(normalized.id);
+  }
   for (const provider of raw) {
     if (provider.id === "opencode" || provider.id === "opencode-go") continue;
     if (covered.has(provider.id)) continue;
@@ -3973,6 +4019,15 @@ var PROVIDER_TEMPLATES = [
     supported: false,
     unsupportedReason: "Uses gcloud Application Default Credentials \u2014 not supported via API key import."
   },
+  {
+    id: "opencode-cloud",
+    name: "OpenCode Zen / Go",
+    authType: "api",
+    npm: "@ai-sdk/openai-compatible",
+    signupUrl: "https://opencode.ai/auth",
+    modelSource: "zen-go-api",
+    supported: true
+  },
   {
     id: "zen",
     name: "OpenCode Zen",
@@ -3980,7 +4035,8 @@ var PROVIDER_TEMPLATES = [
     npm: "@ai-sdk/openai-compatible",
     signupUrl: "https://opencode.ai/auth",
     modelSource: "zen-go-api",
-    supported: true
+    supported: true,
+    addable: false
   },
   {
     id: "go",
@@ -3989,7 +4045,8 @@ var PROVIDER_TEMPLATES = [
     npm: "@ai-sdk/openai-compatible",
     signupUrl: "https://opencode.ai/auth",
     modelSource: "zen-go-api",
-    supported: true
+    supported: true,
+    addable: false
   },
   // OAuth-gated subscription providers — use relay-ai providers auth <id> to sign in
   {
@@ -4004,11 +4061,16 @@ var PROVIDER_TEMPLATES = [
   }
 ];
 function listSupportedTemplates() {
-  return PROVIDER_TEMPLATES.filter((t) => t.supported && t.authType === "api");
+  return PROVIDER_TEMPLATES.filter((t) => t.supported && t.authType === "api" && t.addable !== false);
 }
 function listAddableTemplates(configuredIds = []) {
   const configured = new Set(configuredIds);
-  return listSupportedTemplates().filter((t) => !configured.has(t.id));
+  return listSupportedTemplates().filter((t) => {
+    if (t.id === "opencode-cloud") {
+      return !configured.has("zen") && !configured.has("go");
+    }
+    return !configured.has(t.id);
+  });
 }
 function getTemplateById(id) {
   return PROVIDER_TEMPLATES.find((t) => t.id === id);
@@ -4193,6 +4255,7 @@ async function importFromOpencode(options = {}) {
   const authEntries = authFile?.entries ?? {};
   const { providers: fetched, oauth } = buildImportProviderList(raw, authEntries);
   const registry = loadRegistry();
+  migrateLegacyCloudProviders(registry);
   const imported = [];
   const skipped = [];
   const keysSkipped = [];
@@ -5924,8 +5987,8 @@ function countUsableZenGoModels(models) {
 }
 async function resolveProvidersForDisplay() {
   const reg = loadRegistry();
-  const registryIds = new Set(reg.providers.map((p19) => p19.id));
   const entries = [];
+  const cloudProviders = reg.providers.filter((provider) => provider.id === "zen" || provider.id === "go");
   const opencodeKey = await readGlobalOpencodeCredential();
   let zenCount = 0;
   let goCount = 0;
@@ -5933,37 +5996,27 @@ async function resolveProvidersForDisplay() {
     const zenGo = await fetchZenGoModels(["zen", "go"]);
     zenCount = countUsableZenGoModels(zenGo.zenModels);
     goCount = countUsableZenGoModels(zenGo.goModels);
-    if (!registryIds.has("zen") && zenCount > 0) {
-      entries.push({
-        id: "zen",
-        name: "OpenCode Zen",
-        modelCount: zenCount,
-        enabled: true,
-        authLabel: "keychain (OpenCode API key)",
-        inRegistry: false,
-        cloudBuiltin: "zen"
-      });
-    }
-    if (!registryIds.has("go") && goCount > 0) {
-      entries.push({
-        id: "go",
-        name: "OpenCode Go",
-        modelCount: goCount,
-        enabled: true,
-        authLabel: "keychain (OpenCode API key)",
-        inRegistry: false,
-        cloudBuiltin: "go"
-      });
-    }
+  }
+  if (cloudProviders.length > 0 || zenCount + goCount > 0) {
+    entries.push({
+      id: "opencode-cloud",
+      name: "OpenCode Zen / Go",
+      modelCount: zenCount + goCount || cloudProviders.reduce(
+        (total, provider) => total + (provider.modelsCache?.models.length ?? 0),
+        0
+      ),
+      enabled: cloudProviders.length === 0 || cloudProviders.some((provider) => provider.enabled),
+      authLabel: cloudProviders[0] ? formatRegistryAuthLabel(cloudProviders[0]) : "keychain (OpenCode API key)",
+      inRegistry: cloudProviders.length > 0,
+      cloudBuiltin: "opencode"
+    });
   }
   for (const provider of reg.providers) {
-    let modelCount = provider.modelsCache?.models.length ?? 0;
-    if (provider.id === "zen" && zenCount > 0) modelCount = zenCount;
-    if (provider.id === "go" && goCount > 0) modelCount = goCount;
+    if (provider.id === "zen" || provider.id === "go") continue;
     entries.push({
       id: provider.id,
       name: provider.name,
-      modelCount,
+      modelCount: provider.modelsCache?.models.length ?? 0,
       enabled: provider.enabled,
       authLabel: formatRegistryAuthLabel(provider),
       inRegistry: true
@@ -7609,7 +7662,7 @@ async function refreshProviderModels(providerId, apiKey, registry = loadRegistry
       name: provider.name,
       ok: true,
       modelCount: enriched.length,
-      previousModelCount
+      previousModelCount: provider.refreshedAt ? previousModelCount : void 0
     };
   } catch (err) {
     return {
@@ -7970,13 +8023,14 @@ async function runProvidersImport() {
   if (result.imported.length > 0) {
     const refreshSpinner = p10.spinner();
     refreshSpinner.start("Fetching model capabilities from providers...");
-    await Promise.all(result.imported.map(async (provider) => {
+    const registry2 = loadRegistry();
+    for (const provider of result.imported) {
       const key = await resolveRefreshCredential(
         provider,
         async (pr) => resolveProviderCredential(pr.id, pr.authRef)
       );
-      await refreshProviderModels(provider.id, key);
-    }));
+      await refreshProviderModels(provider.id, key, registry2);
+    }
     refreshSpinner.stop("Model capabilities refreshed.");
   }
   return 0;
@@ -8021,8 +8075,8 @@ async function runProvidersRefreshModels(providerId) {
       p10.log.error(`${result.name}: ${result.reason ?? "Refresh failed."}`);
       return 1;
     }
-    const diff = (result.modelCount ?? 0) - (result.previousModelCount ?? 0);
-    const diffStr = diff > 0 ? ` (+${diff})` : diff < 0 ? ` (${diff})` : "";
+    const diff = result.previousModelCount === void 0 ? 0 : (result.modelCount ?? 0) - result.previousModelCount;
+    const diffStr = result.previousModelCount === void 0 ? "" : diff > 0 ? ` (+${diff})` : diff < 0 ? ` (${diff})` : "";
     p10.log.success(`${result.name}: ${result.modelCount} model${result.modelCount === 1 ? "" : "s"} updated${diffStr}.`);
     return 0;
   }
@@ -8036,8 +8090,8 @@ async function runProvidersRefreshModels(providerId) {
   if (ok.length > 0) {
     p10.log.success(`Updated ${ok.length} provider${ok.length === 1 ? "" : "s"}.`);
     for (const r of ok) {
-      const diff = (r.modelCount ?? 0) - (r.previousModelCount ?? 0);
-      const diffStr = diff > 0 ? ` (+${diff})` : diff < 0 ? ` (${diff})` : "";
+      const diff = r.previousModelCount === void 0 ? 0 : (r.modelCount ?? 0) - r.previousModelCount;
+      const diffStr = r.previousModelCount === void 0 ? "" : diff > 0 ? ` (+${diff})` : diff < 0 ? ` (${diff})` : "";
       p10.log.info(`  ${r.name}: ${r.modelCount} model${r.modelCount === 1 ? "" : "s"}${diffStr}`);
     }
   }
@@ -8148,19 +8202,25 @@ async function runTemplateAddFlow() {
     await migrateGlobalOpencodeCredential();
     const spinner10 = p10.spinner();
     spinner10.start(`Adding ${template.name}...`);
-    const stub = template.id === "zen" ? addZenRegistryStub() : addGoRegistryStub();
-    if (!stub.added && stub.reason) {
+    const zenStub = addZenRegistryStub();
+    const goStub = addGoRegistryStub();
+    if (!zenStub.added && !goStub.added) {
       spinner10.stop("");
-      p10.log.warn(stub.reason);
+      p10.log.warn("OpenCode Zen / Go is already configured.");
       return 0;
     }
     const registry = loadRegistry();
-    const refreshResult = await refreshProviderModels(template.id, apiKey2, registry);
+    const refreshResults = [
+      await refreshProviderModels("zen", apiKey2, registry),
+      await refreshProviderModels("go", apiKey2, registry)
+    ];
     spinner10.stop("");
-    if (refreshResult.ok) {
-      p10.log.success(`Added ${template.name} \u2014 ${fmtCount(refreshResult.modelCount ?? 0, "model")} updated.`);
+    const modelCount = refreshResults.reduce((total, result2) => total + (result2.modelCount ?? 0), 0);
+    const failed = refreshResults.filter((result2) => !result2.ok);
+    if (failed.length === 0) {
+      p10.log.success(`Added ${template.name} \u2014 ${fmtCount(modelCount, "model")} updated.`);
     } else {
-      p10.log.warn(`Added ${template.name}, but model refresh failed: ${refreshResult.reason ?? "Unknown error"}`);
+      p10.log.warn(`Added ${template.name}, but ${failed.length} catalog refresh${failed.length === 1 ? "" : "es"} failed.`);
     }
     return 0;
   }
@@ -8333,9 +8393,25 @@ async function runProvidersRemove(id, interactive = false) {
   }
   return 0;
 }
-async function runCloudBuiltinDetail(id) {
-  const name = id === "zen" ? "OpenCode Zen" : "OpenCode Go";
-  printCloudProviderPanel(name);
+async function runOpenCodeCloudDetail() {
+  const registry = loadRegistry();
+  const routes = registry.providers.filter((provider) => provider.id === "zen" || provider.id === "go");
+  printCloudProviderPanel("OpenCode Zen / Go");
+  if (routes.length === 0) return "back";
+  const choice = await p10.select({
+    message: "Manage an OpenCode catalog",
+    options: [
+      ...routes.map((provider) => ({
+        value: provider.id,
+        label: provider.name,
+        hint: `${provider.modelsCache?.models.length ?? 0} cached models`
+      })),
+      { value: "back", label: "Back", hint: "" }
+    ]
+  });
+  if (!p10.isCancel(choice) && choice !== "back") {
+    await runProviderDetail(String(choice));
+  }
   return "back";
 }
 function providerHubChoiceValue(entry) {
@@ -8450,7 +8526,7 @@ async function runProvidersHub() {
     }
     if (typeof choice === "string" && choice.startsWith("cloud:")) {
       const id = choice.slice("cloud:".length);
-      if (id === "zen" || id === "go") await runCloudBuiltinDetail(id);
+      if (id === "opencode") await runOpenCodeCloudDetail();
       continue;
     }
     if (typeof choice === "string" && choice.startsWith("provider:")) {
@@ -9895,13 +9971,21 @@ function codexHelpText() {
 
 ${pc13.bold("Usage:")}
   relay-ai codex [options] [codex-flags]
+  relay-ai codex --vertex
   relay-ai codex --restore
   relay-ai codex --config
+  relay-ai codex --help
+  relay-ai codex --version
 
 ${pc13.bold("Options:")}
   --trace      Write proxy debug logs to ~/.relay-ai/logs/ and show errors on exit
   --provider   Boot provider id (skip wizard when paired with --model or non-interactive)
   --model      Boot model id (skip wizard when paired with --provider or non-interactive)
+  --vertex     Use Claude models through Google Vertex AI
+  --restore    Remove interrupted-session overlay files
+  --config     Preview/write launch configuration without starting Codex
+  --help       Show this command help
+  --version    Show version
 
 ${pc13.bold("Description:")}
   Picks a provider and model from ~/.relay-ai/providers.json, writes a temporary
@@ -10947,9 +11031,19 @@ function codexAppHelpText() {
   return `${pc14.bold("relay-ai codex-app")} \u2014 launch Codex desktop app with your registry providers
 
 ${pc14.bold("Usage:")}
-  relay-ai codex-app
+  relay-ai codex-app [options]
+  relay-ai codex-app --vertex
   relay-ai codex-app --restore
   relay-ai codex-app --config
+  relay-ai codex-app --help
+  relay-ai codex-app --version
+
+${pc14.bold("Options:")}
+  --vertex     Use Claude models through Google Vertex AI
+  --restore    Restore Codex config after an interrupted app session
+  --config     Preview the generated Codex app configuration without launching
+  --help       Show this command help
+  --version    Show version
 
 ${pc14.bold("Description:")}
   Picks a provider and model from ~/.relay-ai/providers.json, patches ~/.codex/config.toml
@@ -10970,6 +11064,8 @@ ${pc14.bold("Preview (no writes):")}
 
 ${pc14.bold("Examples:")}
   relay-ai codex-app
+  relay-ai codex-app --vertex
+  relay-ai codex-app --config
   relay-ai codex-app --restore
   
 ${pc14.bold("Favorites:")}
@@ -11779,9 +11875,17 @@ function claudeAppHelpText() {
   return `${pc15.bold("relay-ai claude-app")} \u2014 launch Claude Desktop app in 3P mode with your registry providers
 
 ${pc15.bold("Usage:")}
-  relay-ai claude-app
+  relay-ai claude-app [options]
   relay-ai claude-app --trace
   relay-ai claude-app --restore
+  relay-ai claude-app --help
+  relay-ai claude-app --version
+
+${pc15.bold("Options:")}
+  --trace      Write proxy debug logs to ~/.relay-ai/logs/
+  --restore    Restore Claude Desktop config after an interrupted app session
+  --help       Show this command help
+  --version    Show version
 
 ${pc15.bold("Description:")}
   Picks a provider and model from ~/.relay-ai/providers.json, patches Claude Desktop config
@@ -12663,28 +12767,37 @@ function parseArgs(args) {
 }
 function rootHelpText() {
   return `${pc16.bold("relay-ai")} v${VERSION}
-Launch AI coding tools with OpenCode Zen, Go, or local providers (Groq, Mistral,
+Launch AI coding tools with OpenCode Zen / Go or local providers (Groq, Mistral,
 OpenAI, Gemini, Ollama, and more).
 
 ${pc16.bold("Usage:")}
   relay-ai claude [options] [claude-flags]
+  relay-ai claude-app [options]
+  relay-ai codex [options] [codex-flags]
+  relay-ai codex-app [options]
+  relay-ai server [options]
   relay-ai models
+  relay-ai favorites
   relay-ai providers
-  relay-ai codex [codex-flags]
-  relay-ai codex-app
-  relay-ai server
   relay-ai --help
   relay-ai --version
   relay-ai --ai              Full reference for AI agents (run this when unsure)
   relay-ai --ai --install    Install or upgrade agent skill when version changed
   relay-ai --ai --install --force  Reinstall skill even if already current
 
+${pc16.bold("Root options:")}
+  -h, --help       Show this help
+  -v, --version    Show version
+  --ai             Print the full reference for AI agents
+  --ai --install   Install or upgrade the relay-ai agent skill
+  --force          Reinstall the agent skill when used with --ai --install
+
 ${pc16.bold("Commands:")}
   claude      Launch Claude Code \u2014 pick a provider from your registry
   models      Manage favorite models for mid-session /model switching (max ${MAX_MODEL_CATALOG})
   favorites   Alias for models
   providers   Add, import, and manage your AI providers
-  server      Run a foreground API gateway (Zen, Go, and local providers)
+  server      Run a foreground API gateway (OpenCode Zen / Go and local providers)
   codex       Launch OpenAI Codex CLI with registry providers
   codex-app   Launch Codex desktop app with registry providers (macOS + Windows)
   claude-app  Launch Claude Desktop app with registry providers (macOS + Windows)
@@ -12696,8 +12809,10 @@ ${pc16.bold("Migration:")}
 ${pc16.bold("Examples:")}
   relay-ai claude
   relay-ai models
+  relay-ai providers
   relay-ai codex
   relay-ai codex-app
+  relay-ai claude-app
   relay-ai server
   relay-ai claude -c
   relay-ai claude --resume abc-123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacobbd/relay-ai",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "publishConfig": {
     "access": "public"
   },