focalapi-cli 0.2.1 → 0.3.0

package/package.json

@@ -1,57 +1,57 @@
-{
-  "name": "focalapi-cli",
-  "version": "0.2.1",
-  "description": "让任意 AI Agent 直接调用 focalapi 创作模型的命令行工具",
-  "type": "module",
-  "bin": {
-    "focalapi": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "scripts",
-    "skills",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "dev": "tsx src/cli.ts",
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "postinstall": "node scripts/postinstall.cjs",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "keywords": [
-    "focalapi",
-    "ai",
-    "agent",
-    "cli",
-    "llm",
-    "image-generation",
-    "video-generation"
-  ],
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/focalapi/focalapi-cli.git"
-  },
-  "homepage": "https://github.com/focalapi/focalapi-cli#readme",
-  "bugs": {
-    "url": "https://github.com/focalapi/focalapi-cli/issues"
-  },
-  "dependencies": {
-    "commander": "^12.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "tsup": "^8.2.4",
-    "tsx": "^4.19.0",
-    "typescript": "^5.5.4",
-    "vitest": "^2.1.9"
-  }
-}
+{
+  "name": "focalapi-cli",
+  "version": "0.3.0",
+  "description": "让任意 AI Agent 直接调用 focalapi 创作模型的命令行工具",
+  "type": "module",
+  "bin": {
+    "focalapi": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "postinstall": "node scripts/postinstall.cjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "focalapi",
+    "ai",
+    "agent",
+    "cli",
+    "llm",
+    "image-generation",
+    "video-generation"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/focalapi/focalapi-cli.git"
+  },
+  "homepage": "https://github.com/focalapi/focalapi-cli#readme",
+  "bugs": {
+    "url": "https://github.com/focalapi/focalapi-cli/issues"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.2.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.9"
+  }
+}

package/scripts/postinstall.cjs

@@ -1,41 +1,41 @@
-#!/usr/bin/env node
-
-/**
- * Best-effort Agent integration after global npm installation.
- *
- * Run local connect only: do not access the network, read an API key, or change an Agent provider.
- * Missing Agents or integration failures never fail CLI installation; users can run focalapi connect later.
- */
-
-const { existsSync } = require('node:fs');
-const { join } = require('node:path');
-const { spawnSync } = require('node:child_process');
-
-if (process.env.FOCALAPI_SKIP_POSTINSTALL === '1' || process.env.CI === '1' || process.env.CI === 'true') {
-  process.exit(0);
-}
-
-const cli = join(__dirname, '..', 'dist', 'cli.js');
-if (!existsSync(cli)) process.exit(0);
-
-const result = spawnSync(process.execPath, [cli, 'connect', 'install', '--json'], {
-  encoding: 'utf8',
-  env: process.env,
-  windowsHide: true,
-});
-
-if (result.status === 0) {
-  try {
-    const output = JSON.parse(result.stdout || '{}');
-    const count = Array.isArray(output.installed) ? output.installed.length : 0;
-    if (count > 0) console.log(`focalapi-cli: 已自动接入 ${count} 个 Agent Skills 目录；重启 Agent 后生效。`);
-  } catch {
-    // Unparseable output after a successful connect must not fail installation.
-  }
-  process.exit(0);
-}
-
-if (!String(result.stderr).includes('未检测到本机 Agent')) {
-  console.warn('focalapi-cli: Agent Skills 自动接入未完成；请稍后运行 `focalapi connect`。');
-}
-process.exit(0);
+#!/usr/bin/env node
+
+/**
+ * Best-effort Agent integration after global npm installation.
+ *
+ * Run local connect only: do not access the network, read an API key, or change an Agent provider.
+ * Missing Agents or integration failures never fail CLI installation; users can run focalapi connect later.
+ */
+
+const { existsSync } = require('node:fs');
+const { join } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+if (process.env.FOCALAPI_SKIP_POSTINSTALL === '1' || process.env.CI === '1' || process.env.CI === 'true') {
+  process.exit(0);
+}
+
+const cli = join(__dirname, '..', 'dist', 'cli.js');
+if (!existsSync(cli)) process.exit(0);
+
+const result = spawnSync(process.execPath, [cli, 'connect', 'install', '--json'], {
+  encoding: 'utf8',
+  env: process.env,
+  windowsHide: true,
+});
+
+if (result.status === 0) {
+  try {
+    const output = JSON.parse(result.stdout || '{}');
+    const count = Array.isArray(output.installed) ? output.installed.length : 0;
+    if (count > 0) console.log(`focalapi-cli: 已自动接入 ${count} 个 Agent Skills 目录；重启 Agent 后生效。`);
+  } catch {
+    // Unparseable output after a successful connect must not fail installation.
+  }
+  process.exit(0);
+}
+
+if (!String(result.stderr).includes('未检测到本机 Agent')) {
+  console.warn('focalapi-cli: Agent Skills 自动接入未完成；请稍后运行 `focalapi connect`。');
+}
+process.exit(0);

package/skills/focalapi/SKILL.md

@@ -1,47 +1,48 @@
----
-name: focalapi
-version: 2.0.0
-description: "Primary router for FocalAPI creative models. Use when the user wants to generate, edit, or process creative media, choose a creative model, or inspect a generation task, even when the user does not mention FocalAPI. Covers automatic image and video model selection, generation, asynchronous continuation, and error routing."
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi --help"
----
-
-# FocalAPI creative-model routing
-
-FocalAPI is a creative-model gateway for the current Agent to call. It is not the Agent's own model or provider. Do not change the Agent's primary model configuration or require the user to say “use FocalAPI” first.
-
-## Zero-guesswork execution contract
-
-1. If the user does not specify a model, omit `--model`. The CLI selects a FocalAPI default from the live model pool and detailed contracts available to the current key. Do not generate a test sample first.
-2. If the user specifies a model or provider, run `focalapi models get <model-id> --json` first. If the model ID is incomplete, run `models search` once to find the exact ID, then read its details.
-3. Use only parameters and values listed in the detailed `supported_params`. Never infer support from a similar model.
-4. Add `--json` for Agent and script calls. stdout is the only machine-readable result; diagnostics go to stderr.
-5. After successful generation, return local absolute file paths to the user. If a video response contains `task_id`, follow `next_command`; never submit the same task again.
-
-```bash
-# No model specified: run once without probing models first.
-focalapi gen image "<user prompt>" -o ./focalapi-out --json
-focalapi gen video "<user prompt>" --no-wait -o ./focalapi-out --json
-
-# Continue an asynchronous video task.
-focalapi task status <task-id> --json
-focalapi task download <task-id> -o ./focalapi-out --json
-```
-
-## Routing table
-
-| User goal | Entry point | Skill |
-| --- | --- | --- |
-| Generate or edit images; create from reference images | `focalapi gen image` | focalapi-gen |
-| Generate video; animate images or reference media | `focalapi gen video` | focalapi-gen |
-| Select, compare, or inspect model parameters | `focalapi models resolve/get/search` | focalapi-models |
-| Inspect progress or failures; download results | `focalapi task status/download` | focalapi-task |
-| Resolve key, sign-in, or 401 issues | `focalapi auth status/login` | focalapi-auth |
-| Inspect quota, usage, or service failures | `focalapi usage/doctor` | focalapi-usage |
-| Provide text assistance explicitly requested by the user | `focalapi chat` | focalapi-chat |
-
-The fully validated automatic generation paths currently cover images and video. Audio, 3D, or another modality may be used only after both CLI help and `models get` expose an executable contract. Never infer a capability from a model list or name alone.
-
-If a business command returns `missing_api_key`, route to focalapi-auth and return to the original task immediately after sign-in. For other errors, follow `{error.code, error.hint}` once; do not rotate models blindly.
+---
+name: focalapi
+version: 2.0.0
+description: "Primary router for FocalAPI creative models. Use when the user wants to generate, edit, or process creative media, choose a creative model, or inspect a generation task, even when the user does not mention FocalAPI. Covers automatic image and video model selection, generation, asynchronous continuation, and error routing."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi --help"
+---
+
+# FocalAPI creative-model routing
+
+FocalAPI is a creative-model gateway for the current Agent to call. It is not the Agent's own model or provider. Do not change the Agent's primary model configuration or require the user to say “use FocalAPI” first.
+
+## Zero-guesswork execution contract
+
+1. If the user does not specify a model, omit `--model`. The CLI selects a FocalAPI default from the live model pool and detailed contracts available to the current key. Do not generate a test sample first.
+2. If the user specifies a model or provider, run `focalapi models get <model-id> --json` first. If the model ID is incomplete, run `models search` once to find the exact ID, then read its details.
+3. Use only parameters and values listed in the detailed `supported_params`. Never infer support from a similar model.
+4. Add `--json` for Agent and script calls. stdout is the only machine-readable result; diagnostics go to stderr.
+5. After successful generation, return local absolute file paths to the user. If a video response contains `task_id`, follow `next_command`; never submit the same task again.
+
+```bash
+# No model specified: run once without probing models first.
+focalapi gen image "<user prompt>" -o ./focalapi-out --json
+focalapi gen video "<user prompt>" --no-wait -o ./focalapi-out --json
+
+# Continue an asynchronous video task.
+focalapi task status <task-id> --json
+focalapi task download <task-id> -o ./focalapi-out --json
+focalapi task cancel <task-id> --json   # queued tasks only; cancelled tasks are refunded
+```
+
+## Routing table
+
+| User goal | Entry point | Skill |
+| --- | --- | --- |
+| Generate or edit images; create from reference images | `focalapi gen image` | focalapi-gen |
+| Generate video; animate images or reference media | `focalapi gen video` | focalapi-gen |
+| Select, compare, or inspect model parameters | `focalapi models resolve/get/search` | focalapi-models |
+| Inspect progress or failures; cancel queued tasks; download results | `focalapi task status/cancel/download` | focalapi-task |
+| Resolve key, sign-in, or 401 issues | `focalapi auth status/login` | focalapi-auth |
+| Inspect quota, usage, or service failures | `focalapi usage/doctor` | focalapi-usage |
+| Provide text assistance explicitly requested by the user | `focalapi chat` | focalapi-chat |
+
+The fully validated automatic generation paths currently cover images and video. Audio, 3D, or another modality may be used only after both CLI help and `models get` expose an executable contract. Never infer a capability from a model list or name alone.
+
+If a business command returns `missing_api_key`, route to focalapi-auth and return to the original task immediately after sign-in. For other errors, follow `{error.code, error.hint}` once; do not rotate models blindly.

package/skills/focalapi-auth/SKILL.md

@@ -1,28 +1,28 @@
----
-name: focalapi-auth
-version: 2.0.0
-description: "Handle focalapi-cli installation, first sign-in, key status, and 401/authentication errors. Trigger only during initial setup or when a business command explicitly returns missing_api_key or invalid_api_key. Return to the original creative task after authentication succeeds."
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi auth --help"
----
-
-# FocalAPI authentication
-
-```bash
-npm i -g focalapi-cli
-focalapi auth login --key <sk-key>
-focalapi auth status --json
-focalapi connect
-```
-
-Create a key at `https://focalapi.com/console/token`. Never reveal the complete key in a response, log, or echoed command. Prefer `FOCALAPI_API_KEY` in CI and sandbox environments.
-
-Do not run `auth status` before every business command. After an authentication error, follow this fixed path:
-
-- `missing_api_key`: sign in or set `FOCALAPI_API_KEY`.
-- `invalid_api_key`: ask the user to verify or create a key in the console, then sign in again.
-- `upstream_auth_failed`: the FocalAPI key may be valid. Preserve the request ID and escalate to the service operator; do not repeatedly replace the user's key.
-
-Retry the original business command immediately after authentication succeeds. Signing in is not the end of the task.
+---
+name: focalapi-auth
+version: 2.0.0
+description: "Handle focalapi-cli installation, first sign-in, key status, and 401/authentication errors. Trigger only during initial setup or when a business command explicitly returns missing_api_key or invalid_api_key. Return to the original creative task after authentication succeeds."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi auth --help"
+---
+
+# FocalAPI authentication
+
+```bash
+npm i -g focalapi-cli
+focalapi auth login --key <sk-key>
+focalapi auth status --json
+focalapi connect
+```
+
+Create a key at `https://focalapi.com/console/token`. Never reveal the complete key in a response, log, or echoed command. Prefer `FOCALAPI_API_KEY` in CI and sandbox environments.
+
+Do not run `auth status` before every business command. After an authentication error, follow this fixed path:
+
+- `missing_api_key`: sign in or set `FOCALAPI_API_KEY`.
+- `invalid_api_key`: ask the user to verify or create a key in the console, then sign in again.
+- `upstream_auth_failed`: the FocalAPI key may be valid. Preserve the request ID and escalate to the service operator; do not repeatedly replace the user's key.
+
+Retry the original business command immediately after authentication succeeds. Signing in is not the end of the task.

package/skills/focalapi-chat/SKILL.md

@@ -1,29 +1,29 @@
----
-name: focalapi-chat
-version: 2.0.0
-description: "Supplementary FocalAPI text and audio commands. Use only when the user explicitly requests text assistance through FocalAPI or when the live model contract confirms an available audio model. Route image and video creation to focalapi-gen."
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi chat --help"
----
-
-# Supplementary FocalAPI capabilities
-
-This Skill is not the default route for creative requests. Route images, video, image editing, and image-to-video work to `focalapi-gen`.
-
-When the user explicitly requests text assistance, get an available text model from the live list before calling it:
-
-```bash
-focalapi models list --json
-focalapi chat "<user text task>" -m <text-model-from-list> --json
-```
-
-Use audio commands only when both `focalapi models get <model-id> --json` and `focalapi audio --help` confirm an executable contract:
-
-```bash
-focalapi audio transcribe <file> -m <model-id> --json
-focalapi audio speech "<text>" -m <model-id> -o <file> --json
-```
-
-A name appearing in the model list does not prove that the CLI supports calling it. If the current key has no audio model contract, state that audio is unavailable; do not try a similar model or an external API.
+---
+name: focalapi-chat
+version: 2.0.0
+description: "Supplementary FocalAPI text and audio commands. Use only when the user explicitly requests text assistance through FocalAPI or when the live model contract confirms an available audio model. Route image and video creation to focalapi-gen."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi chat --help"
+---
+
+# Supplementary FocalAPI capabilities
+
+This Skill is not the default route for creative requests. Route images, video, image editing, and image-to-video work to `focalapi-gen`.
+
+When the user explicitly requests text assistance, get an available text model from the live list before calling it:
+
+```bash
+focalapi models list --json
+focalapi chat "<user text task>" -m <text-model-from-list> --json
+```
+
+Use audio commands only when both `focalapi models get <model-id> --json` and `focalapi audio --help` confirm an executable contract:
+
+```bash
+focalapi audio transcribe <file> -m <model-id> --json
+focalapi audio speech "<text>" -m <model-id> -o <file> --json
+```
+
+A name appearing in the model list does not prove that the CLI supports calling it. If the current key has no audio model contract, state that audio is unavailable; do not try a similar model or an external API.

package/skills/focalapi-gen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: focalapi-gen
-version: 2.0.0
+version: 2.2.0
 description: "Use FocalAPI for image and video generation, image editing, image-to-video, and reference-media creation. Trigger directly when the user asks to draw, generate or edit an image, create video, or animate media, even without naming FocalAPI. Select a model automatically by default and do not probe models first."
 metadata:
   requires:
@@ -32,7 +32,10 @@ focalapi gen video "<prompt>" -m <model-id> [contract-supported options] --no-wa
 ```
 
 - Use `--image <url...>` for image editing and reference images. Pass `--mask` only when the contract lists it.
-- Use `--image <url...>` for video reference images. Pass duration, resolution, aspect ratio, and audio options only as allowed by `supported_params`.
+- Use `--negative-prompt`, `--creativity`, `--prompt-extend`, `--style-references`, and `--moodboards` only when the image contract lists the corresponding field.
+- For video inputs, `--image <url...>` means reference images (Grok 1.5 reference-to-video, capped at 720p and 7 images) and `--first-frame <url>` means image-to-video from a single starting frame. The two flags are mutually exclusive and both are validated against the live contract before submission.
+- Pass duration, resolution, aspect ratio, and audio options only as allowed by `supported_params`.
+- Use `--content '<json-array>'` for models such as LTX 2.5, FLUX 3, Kling 3.0, and Vidu Q3 when the contract requires role-aware media content. LTX also exposes `--fps`; FLUX 3 exposes `--safety-tolerance` (0-4 text-to-video, capped at 2 once images are attached).
 - Never copy one model's `ratio`, `aspect_ratio`, `size`, or `resolution` to another model.
 - Use `gen gemini-image` only when the user explicitly selects a native Gemini image model. Continue to use the automatic `gen image` entry point for ordinary requests.
 
@@ -46,3 +49,8 @@ focalapi task download <task-id> -o ./focalapi-out --json
 ```
 
 `pending` and `running` are not failures. Keep checking the same `task_id` and never resubmit generation. On failure, read the structured `error.code` and `hint`, and fix only the explicit problem instead of rotating models blindly.
+
+Two transient outcomes need no parameter changes:
+
+- `capacity_exhausted` (HTTP 503): the platform queue is full. Retry the same command after roughly 10 seconds; do not switch models or shrink the request.
+- `expired` on a task: submission state stayed unknown past the 10-minute reconciliation window; the charge is refunded automatically. Resubmitting once is correct.

package/skills/focalapi-models/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: focalapi-models
-version: 2.0.0
+version: 2.1.0
 description: "Select FocalAPI creative models and inspect live parameter contracts. Use when the user does not specify a model, names a model or provider, compares models, or encounters a generation-parameter error. Use resolve to obtain a callable default and never infer capabilities from names or probe models one by one."
 metadata:
   requires:
@@ -47,3 +47,9 @@ Rules:
 2. Do not send generation requests to models one by one as an availability test. Discovery and detail queries are read-only preflight checks.
 3. If an explicitly selected model is unavailable, present available candidates or return to `models resolve`; never replace it silently.
 4. Return to the user's original generation task after the query instead of stopping at the model list.
+
+## Current verified creative families
+
+The maintained defaults currently prefer Seedream 5.0, GPT Image 2, Gemini 3.1 Image, Grok Imagine Image 2.0, Kling Image 3.0, Qwen Image 3.0, and Krea 2 for images. Video selection currently covers Seedance 2.5, Kling 3.0, Vidu Q3, Gemini Omni Flash, Grok Imagine Video 1.5, LTX 2.5, and FLUX 3.
+
+These names are routing context, not permission to guess a model ID. Use the exact canonical ID returned by `models resolve` or `models get`. Removed IDs, including the former Veo 3.1 preview models, must not be retried.

package/skills/focalapi-task/SKILL.md

@@ -1,25 +1,29 @@
----
-name: focalapi-task
-version: 2.0.0
-description: "Continue asynchronous FocalAPI image or video tasks and download their outputs. Use when a generation response contains task_id or next_command, or when the user asks about progress, failure reasons, or result files. Reuse the original task_id and never generate again."
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi task --help"
----
-
-# Complete asynchronous FocalAPI tasks
-
-After a generation command returns `task_id`, prefer the response's `next_command`:
-
-```bash
-focalapi task status <task-id> --json
-focalapi task download <task-id> -o ./focalapi-out --json
-```
-
-- `pending` or `running`: this is still the same valid task. Check it later and do not resubmit generation.
-- `success`: run download, verify that the file exists, and return its absolute path to the user.
-- `failed`: show the upstream error summary and hint. Generate again only when an explicit parameter or content issue requires it.
-- `unknown`: preserve the raw response and run `focalapi doctor --json`; never fabricate a success state.
-
-Polling must be bounded. When the user does not ask for blocking wait behavior, report the current status and `task_id`.
+---
+name: focalapi-task
+version: 2.1.0
+description: "Continue asynchronous FocalAPI image or video tasks, cancel queued tasks, and download their outputs. Use when a generation response contains task_id or next_command, or when the user asks about progress, failure reasons, cancellation, or result files. Reuse the original task_id and never generate again."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi task --help"
+---
+
+# Complete asynchronous FocalAPI tasks
+
+After a generation command returns `task_id`, prefer the response's `next_command`:
+
+```bash
+focalapi task status <task-id> --json
+focalapi task download <task-id> -o ./focalapi-out --json
+focalapi task cancel <task-id> --json
+```
+
+- `pending` or `running`: this is still the same valid task. Check it later and do not resubmit generation.
+- `success`: run download, verify that the file exists, and return its absolute path to the user.
+- `failed`: show the upstream error summary and hint. Generate again only when an explicit parameter or content issue requires it. A raw status of `expired` means the submission state stayed unknown past the reconciliation window; the charge was refunded automatically.
+- `cancelled`: the task was stopped; a cancelled queued task is refunded. Do not download or resubmit unless the user asks for a new attempt.
+- `unknown`: preserve the raw response and run `focalapi doctor --json`; never fabricate a success state.
+
+`task cancel` only works while a task is still queued (`pending`). A 409 `task_already_running` means generation already started and cannot be stopped — keep tracking with `task status`. Cancellation failures return explicit codes (`task_already_finished`, `task_cancel_failed`); follow `error.hint` instead of retrying blindly.
+
+Polling must be bounded. When the user does not ask for blocking wait behavior, report the current status and `task_id`.

package/skills/focalapi-usage/SKILL.md

@@ -1,26 +1,27 @@
----
-name: focalapi-usage
-version: 2.0.0
-description: "Inspect FocalAPI quota, usage, and billing, or diagnose network, authentication, and service errors. Use when the user asks about spend or balance, or when a failed business command needs an error-code-driven resolution. Do not add mandatory diagnostics before normal generation."
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi usage --help"
----
-
-# FocalAPI usage and diagnostics
-
-```bash
-focalapi usage --json
-focalapi auth status --json
-focalapi doctor --json
-```
-
-- For quota, balance, usage, or billing questions, run `usage`.
-- For `missing_api_key` or `invalid_api_key`, route to focalapi-auth.
-- For `insufficient_quota`, run `usage`, explain the shortfall, and do not add funds automatically.
-- For `network_error`, `timeout`, or 5xx errors, run `doctor` once and follow `checks[].hint`.
-- For `invalid_request`, return to the live `models get` parameter contract and do not resend the same request.
-- For `upstream_auth_failed`, preserve the request ID and escalate to the service operator; do not ask the user to replace the FocalAPI key.
-
-Do not run `doctor` or a free rehearsal before a normal business command that has not failed. The Agent should complete the user's creative goal directly and avoid unrelated calls.
+---
+name: focalapi-usage
+version: 2.0.0
+description: "Inspect FocalAPI quota, usage, and billing, or diagnose network, authentication, and service errors. Use when the user asks about spend or balance, or when a failed business command needs an error-code-driven resolution. Do not add mandatory diagnostics before normal generation."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi usage --help"
+---
+
+# FocalAPI usage and diagnostics
+
+```bash
+focalapi usage --json
+focalapi auth status --json
+focalapi doctor --json
+```
+
+- For quota, balance, usage, or billing questions, run `usage`.
+- For `missing_api_key` or `invalid_api_key`, route to focalapi-auth.
+- For `insufficient_quota`, run `usage`, explain the shortfall, and do not add funds automatically.
+- For `capacity_exhausted` (HTTP 503), wait about 10 seconds and retry the exact same command; the queue admission gate is full and parameters are not the problem.
+- For `network_error`, `timeout`, or 5xx errors, run `doctor` once and follow `checks[].hint`.
+- For `invalid_request`, return to the live `models get` parameter contract and do not resend the same request.
+- For `upstream_auth_failed`, preserve the request ID and escalate to the service operator; do not ask the user to replace the FocalAPI key.
+
+Do not run `doctor` or a free rehearsal before a normal business command that has not failed. The Agent should complete the user's creative goal directly and avoid unrelated calls.