@byteplus/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.46bd0d6dcc58

package/skills/arkcli-understand/references/arkcli-understand.md

@@ -0,0 +1,249 @@
+# +understand command reference
+
+> **Prerequisite:** Read [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) (authentication, API Key error recovery, global parameters, safety rules) and [`sub-skills.md`](sub-skills.md) (purpose and expected output of 12 sub-skills).
+
+`+understand` is a "one engine + semantic layer" multimodal understanding workflow built on the data-plane Responses API (`POST /responses`). It shares the same `CreateResponses` engine with `+chat`; every sub-skill provides an expert system prompt and a plan-profile fallback model. A Platform Profile instead uses its deployed `Resources.Text.Default` endpoint when `--model` is omitted.
+
+## Command form
+
+```bash
+arkcli +understand <sub-skill> --input @file [prompt]   # Explicit sub-skill
+arkcli +understand "<prompt>" --input @file             # Omit sub-skill → automatically route by --input modality
+```
+
+```bash
+# Image description (minimal)
+arkcli +understand image-caption --input @photo.jpg "Describe the main subject of the image in Chinese"
+
+# Visual localization (bbox output)
+arkcli +understand image-grounding --input @scene.jpg "Draw bounding boxes around all pedestrians in the image"
+
+# Document extraction (by fields)
+arkcli +understand doc-extract --input @invoice.pdf "Extract: invoice number / amount / invoice date"
+
+# Speech transcription (no prompt required; task instructions are built into the sub-skill)
+arkcli +understand asr --input @speech.mp3
+
+# Generate SRT subtitles
+arkcli +understand asr-align --input @speech.mp3
+
+# Chapter-based video summary
+arkcli +understand video-summary --input @clip.mp4 "Organize the output by chapter and provide a timestamp for each chapter"
+
+# Omit sub-skill: automatically route by first --input modality (here .mp3 → asr)
+arkcli +understand "Transcribe this recording" --input @speech.mp3
+
+# Incremental streaming output
+arkcli +understand asr --input @speech.mp3 --stream
+
+# Append instructions after the built-in prompt (does not replace the expert prompt)
+arkcli +understand image-caption --input @x.jpg --system-prompt-append "Answer in one sentence, in English"
+
+# Complete JSON output
+arkcli +understand asr --input @speech.mp3 --format json
+```
+
+## Positional argument parsing (sub-skill vs prompt)
+
+`+understand` requires at least one positional argument (`MinArgs=1`):
+
+- If `args[0]` matches the registry (one of 12), it is the sub-skill; `args[1:]` are joined as the prompt (layered on the built-in prompt as additional user requirements).
+- If `args[0]` does not match, all `args` are the prompt, and the server **automatically routes** by the modality of the first `--input` (image→image-caption / video→video-qa / audio→asr / file→doc-extract).
+- Many sub-skills such as `asr` / `asr-align` are fully defined by built-in prompts, so prompt may be omitted. However, the **number of positional arguments must still be ≥1**, so at least the sub-skill name is required.
+
+## Parameters
+
+> Strictly matches `arkcli +understand --help`. The `+understand` flag set is **smaller than `+chat`**: it replaces `+chat`'s `--instructions` with `--system-prompt-override/append`; it has **no** `--tools` / `--tools-file` / `--tool-choice` / `--caching` / `--cache-prefix` / `--text-format` / `--text-schema` / `--previous-response-id` / `--include-events` / `--expire-at`. Do not copy these flags from `+chat`.
+
+| Parameter | Required | Type | Description |
+|------|------|------|------|
+| `<sub-skill>` | Yes* | positional | One of 12 (see [`sub-skills.md`](sub-skills.md)). When omitted, route automatically using first `--input`, but total positional arguments must still be ≥1 |
+| `[prompt]` | No | positional | User requirements added above the built-in system prompt, such as extraction fields, a specific question, output language |
+| `--input` | Yes | string (repeatable) | Input such as `@photo.jpg`; extension routes to image/video/audio/file. **Without it, returns `missing_input`** |
+| `--model` | No | string | Explicit resource override and highest priority. When omitted, a Platform Profile uses its `Resources.Text.Default` `ep-xxx`; a plan profile uses the sub-skill fallback model. An explicit value must be a full versioned ID or `ep-xxx` |
+| `--stream` | No | bool | Streaming output in two sections: `Thinking:` + `Response:` |
+| `--system-prompt-override` | No | string | **Completely replace** built-in system prompt |
+| `--system-prompt-append` | No | string | **Append** extra instructions to built-in prompt |
+| `--temperature` | No | float | Sampling temperature, such as `0.7` |
+| `--top-p` | No | float | Nucleus sampling top_p, such as `0.9` |
+| `--max-output-tokens` | No | int | Reply token limit |
+| `--reasoning-effort` | No | string | Reasoning intensity: `minimal` / `low` / `medium` / `high` (only supported models) |
+| `--thinking` | No | string | Internal reasoning: `auto` / `enabled` / `disabled` |
+| `--store` | No | bool | Persist response (retrieve later with `arkcli chat get <id>`) |
+| `--no-progress` | No | bool | Disable stderr heartbeat for non-streaming calls (scripts) |
+| `--timeout` | No | duration | Total limit for local-file preparation and inference. Default: `2m`. Pass a longer value such as `10m` explicitly for large files. |
+| `--dry-run` | No | bool | Resolve the recipe, persisted Profile endpoint, explicit model, input references, and request summary locally. It does not read live metadata, upload files, call Responses, produce usage/response ID, or persist a response. |
+
+\* At least a sub-skill name or routable `--input` is required; otherwise `missing_sub_skill`.
+
+See [`../../arkcli-shared/references/global-flags.md`](../../arkcli-shared/references/global-flags.md) for global flags (`--profile` / `--api-key` / `--base-url` / `--format json` / `--transform` / `--debug`, and others).
+
+## Model/endpoint resolution order
+
+```text
+explicit --model
+  -> Platform Profile: active Profile.Resources.Text.Default (must be ep-xxx)
+  -> plan profile: sub-skill recipe fallback model
+```
+
+- A Platform Profile without `Resources.Text.Default` fails with guidance to configure a default resource; it must not silently fall back to a bare model name.
+- A missing default must not make the Agent switch Profiles, replace the sub-skill, or route to another business command.
+- `--dry-run` and real execution use the same resolved resource, but preview reads only local Profile configuration and performs no live Endpoint discovery.
+
+## System prompt resolution chain
+
+Every sub-skill has a built-in system prompt injected into Responses `instructions`:
+
+```
+Built-in prompt (by sub-skill)
+  → when --system-prompt-override is non-empty: replace entirely with override
+  → when --system-prompt-append is non-empty: append to previous result (one blank line between)
+```
+
+- To **fine-tune** a task (language/output constraints): use `--system-prompt-append` and preserve the expert prompt.
+- For **complete customization**: use `--system-prompt-override`, effectively reducing the sub-skill to `+chat` with a specified model + custom prompt.
+- The `[prompt]` positional argument is a **user message**, separate from the system prompt: the sub-skill defines "who you are/how to work"; prompt defines "what this request needs".
+
+## `@file` upload mechanism (audio is special)
+
+`--input @<path>` infers modality by extension:
+
+- `.jpg/.jpeg/.png/.webp/.gif/.bmp` → image
+- `.mp4/.mov/.webm/.mkv/.avi` → video
+- `.mp3/.wav/.m4a/.aac/.flac/.ogg` → audio
+- Others → file (such as `.pdf`)
+
+Supported references: `@<path>` (local, resolved to absolute `file://`), `<path>` (without prefix, equivalent to `@<path>`), `https://` / `http://` (remote URL), and constructed `file://` / `tos://` URLs.
+
+Local inputs use product-safe preparation paths:
+
+- **image / video / doc, aggregate size up to 45 MiB**: arkcli uses Responses-native inline forms (`image_url` / `video_url` data URLs and `input_file.file_data`). This avoids a separate Files API request on BytePlus plan endpoints while leaving headroom below the 64 MiB request-body limit after base64 expansion.
+- **image / video / doc above 45 MiB**: arkcli uploads through Files API and waits for file status before inference. Only `active` files are attached to Responses as `file_id`. A `failed` file returns its file-service code/message and exits non-zero before inference; arkcli never sends that failed file to the model.
+- **audio**: the SDK preprocessor **does not process audio**; arkcli inlines local audio as a **base64 data URL** before sending.
+
+`--timeout` covers both file preparation and Responses inference for streaming and non-streaming execution. A timeout returns the stable `understand_timeout` error type and exits non-zero. Agents must not treat it as success or wait without a bound.
+
+### Audio size constraints
+
+| Form | Limit | Current state |
+|---|---|---|
+| base64 (`@local-audio`, inline data URL) | **25 MB** | Current implementation; **oversize is not blocked or warned** (product decision), so large files may fail or be rejected |
+| Public URL (`https://...`) | 25 MB | The backend downloads it, so the URL must be reachable from the service environment |
+| Files API (file_id, 512 MB) | 512 MB | Pending SDK upgrade; unavailable now |
+
+> For audio **over 25 MB**, warn first and recommend splitting or reducing bitrate. Do not pretend large files will definitely work.
+
+## Return value
+
+> **Identical to `+chat`: arkcli flat schema, not native Responses `output[].content[].text`.** Read assistant text directly from `.content`. Global `--format` accepts only `json` and does not restore the native nested shape.
+
+`--dry-run` is the exception: it returns `preview.v1` rather than a model response and never includes model-response `id`, `content`, or `usage`:
+
+```json
+{
+  "dry_run": true,
+  "mode": "local",
+  "validation_level": "local",
+  "validated": true,
+  "plan": {
+    "operation": "arkruntime.create_responses",
+    "recipe": "image-caption",
+    "model": "dola-seed-2.0-lite",
+    "prompt": "Describe the image",
+    "inputs": [{"kind": "image", "source": "file:///abs/photo.jpg"}],
+    "stream": false,
+    "instructions_source": "recipe"
+  }
+}
+```
+
+**Default/`--format json` output**:
+
+```json
+{
+  "id": "resp_021776932247884ea9dc72e4279a1799608cb64438f5f0f125439",
+  "model": "seed-2-0-lite-260428",
+  "content": "...",
+  "reasoning_content": "...",
+  "usage": { "prompt_tokens": 88, "completion_tokens": 419, "total_tokens": 507 }
+}
+```
+
+- `content`: sub-skill output (transcription / bbox JSON / SRT / extraction JSON / minutes Markdown, and others), **flattened to a string**. See [`sub-skills.md`](sub-skills.md).
+- `reasoning_content`: reasoning process (non-empty only for reasoning models).
+- `id`: response ID; after `--store`, retrieve with `arkcli chat get <id>`.
+
+**Streaming output** (`--stream`):
+
+```
+Thinking:
+<reasoning deltas...>
+
+Response:
+<response deltas...>
+```
+
+Streaming prints directly without JSON and ends with a newline.
+
+### Parse with jq
+
+```bash
+# Extract main output (transcription / JSON / SRT ...)
+arkcli +understand asr --input @speech.mp3 | jq -r .content
+
+# JSON output such as bbox/extraction: content is a JSON string and requires a second parse
+arkcli +understand image-grounding --input @x.jpg "Draw bounding boxes around everyone" | jq -r .content | jq .
+
+# Extract token usage
+arkcli +understand asr --input @speech.mp3 | jq .usage
+```
+
+Do not use `jq '.output[].content[].text'`; the output is flat. Model-generated JSON is a string in `.content`; first extract it with `jq -r .content`, then parse again with `jq .`.
+
+## Common errors
+
+| Error code / message | Cause | Handling |
+|------|------|------|
+| `missing_sub_skill`: `understand needs a sub-skill or an input file to auto-route` | No sub-skill and no routable `--input` | Add a sub-skill or `--input @file` |
+| `unknown_sub_skill`: `unknown understand sub-skill "X"` | Misspelled/nonexistent sub-skill | Use one of 12 valid names in [`sub-skills.md`](sub-skills.md) |
+| `missing_input`: `<sub> requires an input file via --input` | Sub-skill given without input | Add `--input @your-file` |
+| `unroutable_input`: `cannot auto-route a "X" input` | No default mapping for inferred modality | Specify sub-skill explicitly |
+| `input file not found: <path>` | Path does not exist or is directory | Check path/current directory |
+| `understand_timeout` | File preparation or inference exceeded the client deadline | Validate the file and model modality first; pass `--timeout 10m` explicitly for a large file; retain `--debug` output for a repeatable failure |
+| `uploaded responses file <id> failed preprocessing` | Files API marked the local input as `failed` | Use the returned code/message to inspect file content/format; never retry the same failed `file_id` |
+| `ark runtime: API Key is required` | API Key not configured | `arkcli auth apikey` or set `ARK_API_KEY` |
+| `Error code: 403 - {"code":"AccessDenied",...}` | Data-plane authentication/permission | **Do not retry**; follow API Key recovery in [`../../arkcli-auth/references/auth-modes.md`](../../arkcli-auth/references/auth-modes.md) |
+| `Error code: 404 - InvalidEndpointOrModel.NotFound` | Unresolvable family name passed to `--model` | Use full `<name>-<primary_version>` or `ep-xxx`; see [`../../arkcli-models/SKILL.md`](../../arkcli-models/SKILL.md) |
+
+## Direct `arkcli api` call (raw fallback)
+
+The operation behind `+understand` is `+chat`'s `arkruntime.create_responses` / `arkruntime.create_responses_stream`. A sub-skill is a particular `model` + `instructions` and can be reproduced manually:
+
+```bash
+arkcli api arkruntime.create_responses --params '{
+  "model": "seed-2-0-lite-260428",
+  "instructions": "<Paste the built-in system prompt for the corresponding sub-skill here>",
+  "input": [{
+    "role": "user",
+    "content": [
+      {"type": "input_audio", "audio_url": "file:///abs/path/speech.mp3"},
+      {"type": "input_text", "text": "<Optional additional requirements>"}
+    ]
+  }]
+}'
+```
+
+In raw mode, arkcli no longer automatically inlines audio as base64. Construct a backend-accessible URL or data URL yourself. Prefer `+understand` whenever possible. See [`../../arkcli-api-explorer/SKILL.md`](../../arkcli-api-explorer/SKILL.md).
+
+## Relation to other commands
+
+- **[`arkcli +chat`](../../arkcli-chat/SKILL.md)**: Open conversation/reasoning, multi-turn continuation, tools, and `--text-format json_schema`. To follow up on `+understand`, use `--store`, then `+chat --previous-response-id <id>` (same engine).
+- **[`arkcli +gen`](../../arkcli-gen/SKILL.md)**: Image/video **generation**, not understanding existing material.
+- **[`arkcli models`](../../arkcli-models/SKILL.md)**: Query a full model version when overriding `--model`.
+
+## Security and privacy
+
+- `--input @<file>` uploads/inlines the **entire file** (Responses-native inline data for BytePlus image/video/doc up to 45 MiB, Files API above that threshold, and base64 for audio). Do not upload sensitive material casually; the service receives the complete content.
+- `--dry-run` only checks the file locally and prints its reference summary; it does not upload or inline the file. The JSON may contain an absolute local `file://` path, so redact logs before sharing.
+- `--debug` prints requests/responses (possibly base64 audio and file URLs) to stderr; redact logs before sharing.
+- Responses persisted with `--store` remain server-side; delete when needed with `arkcli chat delete <id>`.

package/skills/arkcli-understand/references/evals.md

@@ -0,0 +1,109 @@
+# Minimum arkcli-understand evaluation cases
+
+Goal: verify stable trigger, automatic routing, anti-trigger, write-operation, and privacy-guard behavior, while preventing common hallucinations (nonexistent flags, command spelling, and incorrect JSON paths).
+
+## 1) Trigger: understanding task with a specific output form
+
+Input:
+
+- "Transcribe this recording `@interview.mp3`."
+- "Draw boxes around everyone in `@scene.jpg` and return coordinates."
+
+Expected behavior:
+
+- Route to `arkcli-understand`.
+- Audio transcription → `arkcli +understand asr --input @interview.mp3`.
+- Bounding-box localization → `arkcli +understand image-grounding --input @scene.jpg "Draw bounding boxes around everyone"`; explain output bbox `(x1,y1,x2,y2)` + confidence and secondary parsing with `jq -r .content | jq .`.
+- **Do not** use `+chat` for these fixed-output tasks.
+
+## 2) Automatic routing: omit sub-skill
+
+Input:
+
+- "Understand what this audio `@speech.mp3` says" (no sub-skill named).
+
+Expected behavior:
+
+- `arkcli +understand "<prompt>" --input @speech.mp3`; explain automatic routing by audio modality to `asr`.
+- If the user truly wants translation / subtitles / multiple speakers, explain these are **not** selected automatically and require explicit `ast` / `asr-align` / `asr-speakers`.
+
+## 3) Anti-trigger: open-ended image conversation
+
+Input:
+
+- "Look at `@cat.jpg`, chat with me about it, and let me ask follow-up questions."
+
+Expected behavior:
+
+- Route to [`arkcli-chat`](../../arkcli-chat/SKILL.md): open conversation + multi-turn continuation (`--store` / `--previous-response-id`) belongs to `+chat`.
+- **Do not** force `+understand` (it is single-turn specialized understanding without `--previous-response-id`).
+
+## 4) Anti-trigger: generation, not understanding
+
+Input:
+
+- "Generate a cyberpunk cat image."
+
+Expected behavior:
+
+- Route to [`arkcli-gen`](../../arkcli-gen/SKILL.md).
+- **Do not** use `+understand` (it understands existing material; it does not generate).
+
+## 5) Guard: large audio / private upload
+
+Input:
+
+- "Transcribe `@2hours-meeting.wav` (about 300 MB)."
+
+Expected behavior:
+
+- First state that audio uses base64 inline with a **25 MB limit**. Oversized files are not blocked but will likely fail; recommend splitting / lowering bitrate / transcoding. **Do not** pretend that a large file will work directly.
+- Explain that `--input` uploads/inlines the complete file and sensitive material requires user confirmation.
+
+## 6) Guard: do not retry data-plane authentication failure
+
+Input (command response):
+
+- `Error code: 403 - {"code":"AccessDenied",...}` or `ark runtime: API Key is required`
+
+Expected behavior:
+
+- **Do not retry in place**. Follow "API Key mode error recovery" in [`../../arkcli-auth/references/auth-modes.md`](../../arkcli-auth/references/auth-modes.md), guide the user to run `arkcli auth apikey`, select a key, and return to the original task.
+
+## 7) Agent anti-hallucination checklist
+
+Any of the following from the Agent is a failure:
+
+- `arkcli understand ...` (missing `+`).
+- `arkcli +understand ...` without `--input` (unless demonstrating an error).
+- Using `--instructions` with `+understand` (it has no such flag; use `--system-prompt-override` / `--system-prompt-append`).
+- Using `--tools` / `--tools-file` / `--text-format` / `--previous-response-id` / `--include-events` with `+understand` (these are `+chat` flags).
+- Treating built-in catalog default `seed-2-0-lite` as a value sent directly to the data plane and manually adding a version. arkcli resolves the built-in name to its current primary version; a complete versioned ID is required **only when the user explicitly overrides `--model`**.
+- Parsing with `jq '.output[].content[].text'` (output is flat; use `jq -r .content`, then `| jq .` for JSON output).
+- Inventing nonexistent sub-skill names. The only valid names are `image-caption` / `image-grounding` / `image-gui` / `doc-extract` / `video-summary` / `video-qa` / `vau` / `asr` / `asr-align` / `asr-speakers` / `ast` / `meeting-minutes`.
+- Treating `vau` as automatic video routing default (the default is `video-qa`; `vau` must be explicit).
+
+## 8) Happy path (end-to-end; prerequisites required)
+
+Prerequisite: logged in according to `arkcli auth status` and ARK API Key configured.
+
+```bash
+# Image description (easiest to reproduce)
+arkcli +understand image-caption --input @<local-image> "Describe in one sentence" | jq -r .content
+```
+
+Check: exit code 0; `.content` is non-empty and describes the image. Run one corresponding happy path for each remaining modality (audio ≤25 MB).
+
+## 9) Supporting machine evaluation
+
+Machine-evaluation assets should be stored in `tests/skills/arkcli-understand/` (not under `skills/`). Rerun:
+
+```bash
+cd skill-creator
+python3 -m scripts.run_arkcli_skill_benchmark \
+  --skill-path ../skills/arkcli-understand \
+  --workspace /tmp/arkcli-understand-bench \
+  --iteration 1 \
+  --runs-per-config 2 \
+  --runtime claude
+```

package/skills/arkcli-understand/references/sub-skills.md

@@ -0,0 +1,137 @@
+# +understand sub-skill recipe catalog
+
+> **Prerequisite:** Read [`arkcli-understand.md`](arkcli-understand.md) first (commands/flags/returns/errors).
+
+The 12 sub-skills are 12 recipes `{modality, default model, built-in system prompt}` running on the same Responses engine. The "expected output" below comes from each sub-skill's built-in system prompt and guides the Agent when parsing `.content`.
+
+General rules:
+
+- **Do not override the default model** (verified working). Built-in catalog names are resolved to their current primary versions. A replacement `--model` must use a complete versioned ID or `ep-xxx`.
+- The `[prompt]` positional argument is an **additional user requirement** layered on the expert prompt (fields, target, language, granularity, and others).
+- To change output format/language while preserving expert capability, use `--system-prompt-append`; for complete customization, use `--system-prompt-override`.
+- JSON outputs (grounding / gui / doc-extract) are strings in `.content` and require secondary parsing with `jq -r .content | jq .`.
+
+---
+
+## Image modality (default model `seed-2-0-lite`)
+
+### `image-caption` — Image description / OCR
+- **Purpose**: Clear, structured description and analysis of one or multiple images; for OCR, fully preserve image text without paraphrasing.
+- **Expected output**: Natural-language description; verbatim text for OCR.
+- **Examples**:
+  ```bash
+  arkcli +understand image-caption --input @photo.jpg "Describe the main subject and scene"
+  arkcli +understand image-caption --input @receipt.png "Perform OCR and preserve all text and numbers exactly"
+  arkcli +understand image-caption --input @a.jpg --input @b.jpg "Compare the differences between these two images"
+  ```
+- **Automatic routing**: When sub-skill is omitted and the first `--input` is an image, falls back to this sub-skill.
+
+### `image-grounding` — Visual localization (bbox)
+- **Purpose**: Given an image and target description, precisely locate targets in the image.
+- **Expected output**: bbox coordinates `(x1, y1, x2, y2)` + confidence for every target. If the target does not exist, output empty array `[]`; do not fabricate.
+- **Examples**:
+  ```bash
+  arkcli +understand image-grounding --input @scene.jpg "Draw bounding boxes around all red vehicles"
+  arkcli +understand image-grounding --input @ui.png "Locate the login button" | jq -r .content | jq .
+  ```
+
+### `image-gui` — GUI action recognition
+- **Purpose**: Given a UI screenshot and operation goal, output an executable action sequence for a GUI agent.
+- **Expected output**: JSON array. Each step includes action type, target-element bbox where applicable, and required parameters such as typed text. Actions are limited to 12 types: `click` / `double-click` / `right-click` / `tap` / `long-press` / `scroll` / `swipe` / `drag` / `type` / `key` / `wait` / `screenshot`.
+- **Example**:
+  ```bash
+  arkcli +understand image-gui --input @screen.png "Enter arkcli in the search box and click Search"
+  ```
+
+---
+
+## Video modality
+
+### `video-summary` — Video summary (default `seed-2-0-lite`)
+- **Purpose**: Structurally summarize video using visuals + audio.
+- **Expected output**: User-selected granularity: `overall` / `segment` / `chapter`; each segment includes key timestamps (`HH:mm:ss`), visual points, dialogue points, and overall topic. Do not fabricate absent content.
+- **Example**:
+  ```bash
+  arkcli +understand video-summary --input @lecture.mp4 "Summarize by chapter and provide the start timestamp for each chapter"
+  ```
+
+### `video-qa` — Video Q&A (default `seed-2-0-lite`)
+- **Purpose**: Answer a specific user question accurately using visuals / audio / timeline.
+- **Expected output**: Direct answer first, with supporting evidence (visual description / dialogue / timestamp) when needed. If absent, clearly state that it is not covered; do not fabricate.
+- **Example**:
+  ```bash
+  arkcli +understand video-qa --input @clip.mp4 "How many people appear in the video, and what is each person doing?"
+  ```
+- **Automatic routing**: When sub-skill is omitted and the first `--input` is video, falls back to this sub-skill.
+
+### `vau` — Joint audiovisual understanding (default `seed-2-0-lite`)
+- **Purpose**: VAU (Video-Audio Understanding), deeply analyzes audio elements (voice / effects / music), acoustic characteristics, and narrative roles. Registered as video; **input remains a video file**.
+- **Expected output**: Clearly structured, detailed audio analysis report.
+- **Example**:
+  ```bash
+  arkcli +understand vau --input @film_clip.mp4 "Analyze the sound design in this video"
+  ```
+- **Note**: `vau` is not the default video route (`video-qa` is); specify it **explicitly**.
+
+---
+
+## Audio modality (default model `seed-2-0-lite`)
+
+> Audio is inlined as base64 with a **25 MB limit**. See [`arkcli-understand.md`](arkcli-understand.md).
+
+### `asr` — Speech transcription
+- **Purpose**: Pure ASR speech-to-text.
+- **Expected output**: **Only** transcription text: no introduction, explanation, or Markdown. Output an empty string for unclear/no speech.
+- **Examples**:
+  ```bash
+  arkcli +understand asr --input @speech.mp3
+  arkcli +understand asr --input @speech.mp3 | jq -r .content   # Retrieve transcription text directly
+  ```
+- **Automatic routing**: When sub-skill is omitted and the first `--input` is audio, falls back to this sub-skill.
+
+### `asr-align` — Subtitle alignment
+- **Purpose**: Timestamped transcription producing subtitles.
+- **Expected output**: **SRT** by default (index / start-end `HH:MM:SS,mmm --> HH:MM:SS,mmm` / text, with blank lines between entries); follow a user template if supplied.
+- **Examples**:
+  ```bash
+  arkcli +understand asr-align --input @speech.mp3                       # Default SRT
+  arkcli +understand asr-align --input @speech.mp3 "Output in WebVTT format"   # Custom template
+  ```
+
+### `asr-speakers` — Multi-speaker transcription
+- **Purpose**: Transcribe multi-person dialogue and label speakers.
+- **Expected output**: Speaker-labeled transcription: first speaker `[spk0]`, second `[spk1]`, and so on.
+- **Example**:
+  ```bash
+  arkcli +understand asr-speakers --input @meeting.wav
+  ```
+
+### `ast` — Speech translation
+- **Purpose**: Translate spoken audio content into text (AST).
+- **Expected output**: Translated text. The built-in prompt does not fix the target language; specify it with `[prompt]`, such as "translate into English".
+- **Example**:
+  ```bash
+  arkcli +understand ast --input @speech.m4a "Translate into English"
+  ```
+
+### `meeting-minutes` — Meeting minutes
+- **Purpose**: Produce structured minutes from meeting audio (the built-in prompt also supports meeting-video semantics).
+- **Expected output**: Markdown minutes containing meeting topic / participants (voiceprints labeled `spk0`, `spk1`, and others) / agenda and discussion points (chronological with timestamps) / decisions (Action Items with owner / deadline when identifiable) / follow-ups. Preserve key quotations and avoid subjective inference.
+- **Example**:
+  ```bash
+  arkcli +understand meeting-minutes --input @standup.m4a
+  ```
+
+---
+
+## File modality (default model `seed-2-0-mini`)
+
+### `doc-extract` — Document field extraction
+- **Purpose**: Extract structured information from PDF/documents.
+- **Expected output**: JSON following the user-specified schema (field names / meanings). Use `null` when absent; do not invent. Preserve source page number `page` for traceability in multi-page documents.
+- **Examples**:
+  ```bash
+  arkcli +understand doc-extract --input @invoice.pdf "Extract: invoice number / amount / invoice date / seller"
+  arkcli +understand doc-extract --input @contract.pdf "Extract Party A, Party B, contract amount, and signing date" | jq -r .content | jq .
+  ```
+- **Automatic routing**: When sub-skill is omitted and the first `--input` is a non-image/video/audio file such as `.pdf`, falls back to this sub-skill.

package/skills/arkcli-usage/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: arkcli-usage
+version: 1.3.3
+description: "ARK usage queries: `usage stats` (tokens/requests, 5–30 minute delay), `usage plan` / `usage balance --type plan` (plan quota snapshots), `usage balance` (free quota/media asset/plan balances), and `usage seats --with-usage` (team usage by seat). Trigger for usage, consumed amount, remaining quota, plan percentage, in-plan/out-of-plan, or per-seat consumption. Seat listing/binding/assignment is management and routes to arkcli-plans; this skill answers usage only. Verb routing: use/consume/how much → here; list/bind/assign → arkcli-plans. Anti-trigger: TTS/ASR/voice model usage is unsupported."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli usage stats --help"
+---
+
+# arkcli usage
+
+**CRITICAL — Before starting, you MUST use Read to open [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md), which contains authentication gates, configuration troubleshooting, and shared safety rules.**
+**CRITICAL — Before executing `usage stats`, use Read to open [`references/arkcli-usage-stats.md`](references/arkcli-usage-stats.md); do not invoke blindly.**
+**CRITICAL — Before executing `usage plan`, use Read to open [`references/arkcli-usage-plan.md`](references/arkcli-usage-plan.md); do not invoke blindly.**
+**CRITICAL — Before executing `usage balance`, use Read to open [`references/arkcli-usage-balance.md`](references/arkcli-usage-balance.md); do not invoke blindly.**
+**CRITICAL — Before executing `usage seats`, use Read to open [`references/arkcli-usage-seats.md`](references/arkcli-usage-seats.md); do not invoke blindly.**
+
+> **Data freshness (Must read first): `usage stats` uses an upstream BFF aggregation pipeline and has a 5–30 minute delay. It is intended for daily/aggregate analysis.** Do not use it for real-time budget monitoring, rate limiting, or alerts requiring second-level precision. For those scenarios, read per-request `.usage` returned by inference commands such as `+chat` / `+gen` (zero delay; see [arkcli-chat](../arkcli-chat/SKILL.md) and [arkcli-gen](../arkcli-gen/SKILL.md)).
+
+> **Agent Plan boundary**: BytePlus does not offer Agent Plan (`agent-plan` / `agent-plan-team`). When a user asks about **Agent Plan** quota, remaining, reset date, or per-seat usage, respond with "Agent Plan is not offered on BytePlus" and stop — do not silently answer with Coding Plan numbers and do not attempt any Agent Plan flag combination as a probe.
+
+> **Voice model boundary**: TTS / ASR / dubbing / reading / podcast / voice / real-time voice interaction are currently unsupported in arkcli. Do not answer their usage with `usage stats --model` or plan/balance commands; state directly that arkcli does not support querying voice model pricing or usage.
+
+> **Difference among stats / plan / balance:**
+> - `stats`: token-billed inference usage (any identity, 5–30 minute delay).
+> - `plan`: subscription quota snapshot (CodingPlan personal + team: percentage used / reset date).
+> - `balance`: "how much X remains" from a balance perspective (`--type free-quota / media-asset / plan`).
+> - `seats`: admin view of team-seat **usage** (per-seat usage / plan percentage; **usage only**). Seat listing/binding/assignment uses [`arkcli-plans`](../arkcli-plans/SKILL.md): `plans team seat-list / seat-assign`.
+>
+> "How much plan quota remains?" → `plan` or concise `balance --type plan`; "How many tokens did I use today?" → `stats`; "How much free quota/media capacity remains?" → `balance`; "**How much did each seat use / team-seat usage distribution?**" → `seats --with-usage`. Pure management ("who is bound / list seats / assign seats") → `arkcli-plans`.
+
+## Step 0: choose the metric, then verify the identity
+
+- Explicit Coding Plan quota questions use `usage plan --product coding-plan|coding-plan-team`. Subscription ownership belongs to the account/user, not the active profile type; a platform profile does not prove there is no subscription.
+- Platform Token/request usage uses `usage stats --start <YYYY-MM-DD>`; personal scope must retain `--mine`, including when adding grouping. Only query both buckets when the user asks for both; label them separately and do not sum quota percentages and Tokens.
+- Coding Plan has quota snapshots, not per-model/Harness or Endpoint/API Key attribution. State this boundary; do not append platform stats as a substitute. Agent Plan is not offered on BytePlus.
+- If "my usage" is ambiguous, clarify the metric from the current context before querying. Do not switch Profile, Key, Project or account scope to fill gaps. Reuse known identity context; when a missing summary is needed, use `arkcli auth whoami --format json`. Ordinary admission does not run `profile show/list/keys list`, which can synchronize and write back keys.
+- Stats require explicit `--start`; derive dates from the request and disclose a today-only default. Split long ranges according to the reference instead of silently shortening them.
+- Distinguish failed queries, successful empty records and nonempty zero totals. Check time range, aggregation delay, metric, identity and filters before concluding no usage. Recent missing records do not prove no call occurred.
+- Report metric, identity/scope, dates and freshness. Platform attribution uses actual `ModelEndpoint` / masked `AuthToken` evidence; do not retrieve plaintext keys merely to identify usage.
+
+## Applicable scenarios
+
+- View inference usage for today or a date range (**accepting 5–30 minute delay**).
+- View subscription plan quota consumption / reset time.
+- Group stats by model, endpoint, or API Key.
+- Analyze token trends and produce reconciliation reports.
+- **Not for voice model usage**: for TTS / ASR / voice-model usage, remaining quota, or calls, do not run this skill; state that it is unsupported.
+
+## Business positioning
+
+- This skill handles existing invocation results and consumption; it is an **offline / near-real-time** analysis entry.
+- It normally follows:
+  - An existing Endpoint whose usage is queried.
+  - A model already being called, analyzed by model / API Key.
+  - A subscribed plan whose remaining quota is queried.
+- It is not an Endpoint creation entry or a model trial entry.
+- **It is not a data source for real-time budget/rate-limit/alert controls**; use per-request `.usage`.
+
+## Quick decisions
+
+- "How much plan quota remains / percentage used / reset date / how many plans":
+  - `arkcli usage plan` (probes all two SKUs; only subscribed buckets issue usage requests).
+  - `arkcli usage plan --all`: query both buckets without subscription probing (diagnostics/Excel).
+  - `arkcli usage plan --product=X`: skip probing and query one.
+    - **This is the same data as `balance --type plan`**. `usage plan` provides the complete output (`subscribed` / `updated_at`), while `balance --type plan` provides a concise projection without metadata. Prefer `usage plan`; use `balance --type plan` only when reconciling plan balances together with free quota or media-asset capacity.
+- "My usage / tokens today / endpoint consumption":
+  - First choose the requested metric using Step 0. An explicit platform/Endpoint request does not need a plan query first.
+  - If the user names a voice model/TTS/ASR → **do not query usage**. Currently arkcli doesn't support querying the usage of audio models.
+  - **BytePlus:** first run `arkcli usage stats --start <YYYY-MM-DD> --mine` (endpoint dimension).
+    - `data_count > 0` → use `totals`.
+      - `data_count=0` (the user has no Endpoint or has not invoked models through an Endpoint recently) → immediately retry `arkcli usage stats --start <YYYY-MM-DD> --mine --mine-by=apikey`.
+    - **⛔ Never degrade to an account-wide query without `--mine`**. Whole-account data is not "my usage".
+- "How much did each APIKey use?": `arkcli usage stats --start <YYYY-MM-DD> --mine --mine-by=apikey`; split by `records[].AuthToken`.
+- "Remaining free tokens/model free quota/media capacity":
+  - `arkcli usage balance --type free-quota`.
+  - `arkcli usage balance --type media-asset`.
+- "How much team seats used / per-seat consumption / plan percentage by seat" (admin usage view):
+  - `arkcli usage seats --product coding-plan-team --with-usage`.
+  - Without `--with-usage`, only metadata is returned.
+  - Routing: this command answers only usage. "**List seats / inspect seat bindings / assign seats to employees**" routes to [`arkcli-plans`](../arkcli-plans/SKILL.md) and its `plans team seat-list / seat-assign` commands. Verbs "used/consumed/how much" stay here; "bind/list/assign" goes to plans.
+- If data looks wrong, check authentication/profile before questioning the data.
+
+## Agent quick execution order
+
+1. Confirm authentication; if uncertain, run `arkcli auth status`.
+2. Start with the smallest query, then add date ranges and grouping.
+3. For abnormal results, first check profile / region / API Key source.
+4. For endpoint usage, preferably confirm endpoint-id first.
+
+## Common fallbacks
+
+- Authentication error: [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+- Wrong query environment: [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md).
+- No Endpoint and preparing integration: [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md).
+  - Plan **price**, not usage: [`../arkcli-pricing/SKILL.md`](../arkcli-pricing/SKILL.md). `pricing plans` returns catalog pricing, while `usage plan` returns quota snapshots; they are different views.
+  - **Settlement amount/bill/money spent**, not tokens: [`../arkcli-billing/SKILL.md`](../arkcli-billing/SKILL.md). Its data source is the BytePlus billing center and is posted at T+1; `usage stats` uses near-real-time BFF inference aggregation.
+- Agent Plan quota, remaining balance, or per-seat usage: clearly state that Agent Plan is not supported, take no action, and do not use any Coding Plan commands as a substitute.
+- Voice/TTS/ASR usage or quota: state that arkcli does not support it; do not route to pricing/billing.
+
+## Command overview
+
+| Command | Description |
+|------|------|
+| [`usage stats`](references/arkcli-usage-stats.md) | Inference usage (tokens/requests, daily/hourly aggregation; token-billed inference view) |
+| [`usage plan`](references/arkcli-usage-plan.md) | Subscription quota snapshots (CodingPlan; usage, remaining quota, and reset time for 5h / weekly / monthly / session windows). Probes both SKUs by default |
+| [`usage balance`](references/arkcli-usage-balance.md) | Unified balance entry through `--type free-quota / media-asset / plan` (model free inference quota / media-asset capacity / plan balance) |
+| [`usage seats`](references/arkcli-usage-seats.md) | **Admin view** listing all enterprise plan seats (SeatID / bound sub-user / billing status). Sub-users normally receive `AccessDenied` |
+
+## Natural-language triggers
+
+| User says | Command |
+|---|---|
+| "remaining quota / balance / how much remains / percentage used / plan quota" | `arkcli usage plan` or `arkcli usage balance --type plan` |
+| "remaining free quota / model free quota / free tokens" | `arkcli usage balance --type free-quota` |
+| "my usage / tokens today / inference usage / token consumption" | `arkcli usage stats --start <YYYY-MM-DD> --mine` |
+
+## References
+
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) -- Create Endpoint first, then inspect endpoint usage
+- [arkcli-pricing](../arkcli-pricing/SKILL.md) -- Catalog pricing from `pricing plans` complements `usage plan` quota snapshots
+- [arkcli-shared](../arkcli-shared/SKILL.md) -- Authentication and global parameters