focalapi-cli 0.2.1 → 0.2.2

package/skills/focalapi/SKILL.md

@@ -1,47 +1,47 @@
----
-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
+```
+
+## 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.

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,48 +1,50 @@
----
-name: focalapi-gen
-version: 2.0.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:
-    bins: ["focalapi"]
-  cliHelp: "focalapi gen --help"
----
-
-# FocalAPI image and video generation
-
-## Default: select automatically and run once
-
-When the user does not specify a model, run:
-
-```bash
-focalapi gen image "<complete prompt>" -o ./focalapi-out --json
-focalapi gen video "<complete prompt>" --no-wait -o ./focalapi-out --json
-```
-
-The CLI selects a default from the live model pool and detailed contracts available to the current key. Do not generate separate samples with a low-cost model, test prompt, or multiple models. Doing so creates unnecessary cost and ambiguity.
-
-## Explicit models and advanced parameters
-
-When the user names a model, read its live contract once:
-
-```bash
-focalapi models get <model-id> --json
-focalapi gen image "<prompt>" -m <model-id> [contract-supported options] -o ./focalapi-out --json
-focalapi gen video "<prompt>" -m <model-id> [contract-supported options] --no-wait -o ./focalapi-out --json
-```
-
-- 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`.
-- 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.
-
-## Complete the result workflow
-
-Synchronous image results contain local absolute paths in `files`; return them directly to the user. For asynchronous results, run the returned `next_command`:
-
-```bash
-focalapi task status <task-id> --json
-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.
+---
+name: focalapi-gen
+version: 2.1.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:
+    bins: ["focalapi"]
+  cliHelp: "focalapi gen --help"
+---
+
+# FocalAPI image and video generation
+
+## Default: select automatically and run once
+
+When the user does not specify a model, run:
+
+```bash
+focalapi gen image "<complete prompt>" -o ./focalapi-out --json
+focalapi gen video "<complete prompt>" --no-wait -o ./focalapi-out --json
+```
+
+The CLI selects a default from the live model pool and detailed contracts available to the current key. Do not generate separate samples with a low-cost model, test prompt, or multiple models. Doing so creates unnecessary cost and ambiguity.
+
+## Explicit models and advanced parameters
+
+When the user names a model, read its live contract once:
+
+```bash
+focalapi models get <model-id> --json
+focalapi gen image "<prompt>" -m <model-id> [contract-supported options] -o ./focalapi-out --json
+focalapi gen video "<prompt>" -m <model-id> [contract-supported options] --no-wait -o ./focalapi-out --json
+```
+
+- Use `--image <url...>` for image editing and reference images. Pass `--mask` only when the contract lists it.
+- Use `--negative-prompt`, `--creativity`, `--prompt-extend`, `--style-references`, and `--moodboards` only when the image contract lists the corresponding field.
+- Use `--image <url...>` for video reference images. Pass duration, resolution, aspect ratio, and audio options only as allowed by `supported_params`.
+- Use `--content '<json-array>'` for models such as MiniMax H3, LTX 2.5, and FLUX 3 when the contract requires role-aware media content. LTX also exposes `--fps`; FLUX 3 exposes `--safety-tolerance`.
+- 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.
+
+## Complete the result workflow
+
+Synchronous image results contain local absolute paths in `files`; return them directly to the user. For asynchronous results, run the returned `next_command`:
+
+```bash
+focalapi task status <task-id> --json
+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.

package/skills/focalapi-models/SKILL.md

@@ -1,49 +1,55 @@
----
-name: focalapi-models
-version: 2.0.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:
-    bins: ["focalapi"]
-  cliHelp: "focalapi models --help"
----
-
-# FocalAPI model selection
-
-## Shortest path
-
-When the user does not specify a model, do not list every model or rank them yourself:
-
-```bash
-focalapi models resolve image --json
-focalapi models resolve video --json
-```
-
-`resolve` reads the live list available to the current key, then reads detailed contracts for candidate models and returns:
-
-- `model.id`: the exact ID accepted by generation commands;
-- `endpoint_type`: the generation endpoint verified by model details;
-- `model.supported_params`: available parameters, defaults, enumerations, and ranges;
-- `next_command`: the next command with no guessing required.
-
-Omitting `--model` from `focalapi gen image/video` uses the same selection logic internally.
-
-## User-selected models
-
-```bash
-focalapi models get <complete-model-id> --json
-```
-
-Search once only when the user provides an incomplete provider or family name:
-
-```bash
-focalapi models search <keyword> --json
-focalapi models get <selected-complete-id> --json
-```
-
-Rules:
-
-1. `models get` is authoritative for endpoints and parameters. A list summary may show only a protocol family and cannot be used to infer modality.
-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.
+---
+name: focalapi-models
+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:
+    bins: ["focalapi"]
+  cliHelp: "focalapi models --help"
+---
+
+# FocalAPI model selection
+
+## Shortest path
+
+When the user does not specify a model, do not list every model or rank them yourself:
+
+```bash
+focalapi models resolve image --json
+focalapi models resolve video --json
+```
+
+`resolve` reads the live list available to the current key, then reads detailed contracts for candidate models and returns:
+
+- `model.id`: the exact ID accepted by generation commands;
+- `endpoint_type`: the generation endpoint verified by model details;
+- `model.supported_params`: available parameters, defaults, enumerations, and ranges;
+- `next_command`: the next command with no guessing required.
+
+Omitting `--model` from `focalapi gen image/video` uses the same selection logic internally.
+
+## User-selected models
+
+```bash
+focalapi models get <complete-model-id> --json
+```
+
+Search once only when the user provides an incomplete provider or family name:
+
+```bash
+focalapi models search <keyword> --json
+focalapi models get <selected-complete-id> --json
+```
+
+Rules:
+
+1. `models get` is authoritative for endpoints and parameters. A list summary may show only a protocol family and cannot be used to infer modality.
+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, FLUX 3, and MiniMax H3.
+
+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,25 @@
----
-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.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`.

package/skills/focalapi-usage/SKILL.md

@@ -1,26 +1,26 @@
----
-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 `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.