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

package/skills/arkcli-train-finetune/references/export-deploy.md

@@ -0,0 +1,179 @@
+# Select, Export, and Deploy Fine-Tuning Artifacts
+
+This workflow supports two entry points:
+
+- The user provides an `mcj-...` and asks to select, export, and deploy artifacts based on training performance.
+- The user provides one or more `cm-...` resources and asks which inference types they support and how to deploy them.
+
+In addition to the shared skill, read the following skills when entering the corresponding stage:
+
+- Query custom models, quantize them, and prepare deployable versions: [`../../arkcli-custommodel/SKILL.md`](../../arkcli-custommodel/SKILL.md).
+- Create an online inference endpoint: [`../../arkcli-deploy/SKILL.md`](../../arkcli-deploy/SKILL.md).
+- Configure or subsequently manage an endpoint at a lower level: [`../../arkcli-infer-endpoint/SKILL.md`](../../arkcli-infer-endpoint/SKILL.md).
+
+Do not copy commands from memory. At each stage, read the references required by the corresponding skill and follow its write-operation, billing, and confirmation rules.
+
+## Command summary
+
+| Command | When to use | Common parameters |
+|---|---|---|
+| `arkcli train finetune metrics <mcj-id>` | Select the best-performing step | `--metric`, `--from-step`, `--to-step`, `--output` |
+| `arkcli train finetune artifacts list <mcj-id>` | List artifacts | Use `--format table` for human selection or `--lite` to skip secondary custom-model name queries |
+| `arkcli train finetune artifacts export <mcj-id>` | Export artifacts as `cm-*` custom models | Repeat `--artifact-name`; optionally use `--custom-model-name-prefix` |
+| `arkcli models custommodel get <cm-id>` | Retrieve custom model details | `--transform artifact_types,active_endpoints` |
+| `arkcli models custommodel available-quantizations <cm-id>` | Check whether a new deployable version can be created | Always run before quantization |
+| `arkcli models custommodel quantize <cm-id>` | Create a new quantized version | Use `--quantization`; asynchronously returns a new `cm-*` |
+| `arkcli infer endpoint capability get --custom-model-id <cm-id>` | Query supported inference types | Run before deployment |
+| `arkcli +deploy` | Create or reuse an endpoint | It does not support `--dry-run`; restate final inputs and execute only after confirmation |
+
+## A. Select the Best-Performing Step from an MCJ
+
+If the user directly provides a `cm-...`, skip to section C.
+
+### 1. Retrieve the job and available metrics
+
+```bash
+arkcli train finetune get <mcj-id>
+arkcli train finetune metrics <mcj-id>
+```
+
+Use `get` to confirm the fine-tuning type, training method, and job phase. If the job has not produced valid metrics or artifacts, explain its current phase and stop the export flow.
+
+For a job that uses full fine-tuning, stop the CLI export-and-deploy flow and explain that ArkCLI currently cannot deploy artifacts produced by full fine-tuning. The user must complete deployment in the console. Do not continue with `artifacts export`, custom model deployment, or `+deploy`.
+
+On the first `metrics` call, omit the metric name and obtain exact names from `available_metrics`. For a large result, write it to a file with `--output`, then calculate with a structured JSON tool rather than scanning a long series manually.
+When restricting the range with both `--from-step` and `--to-step`, `to-step` must be strictly greater than `from-step`.
+
+### 2. Select the performance metric used for ranking
+
+Apply the following priority. Every selected name must come from `available_metrics`.
+
+| Job type | First choice | Fallback |
+|---|---|---|
+| Non-RL | Minimize a loss metric in the test, eval, or validation scope | Minimize a loss metric in the train scope |
+| RL | Maximize `final_rewards.mean` in the test, eval, or validation scope | Maximize `final_rewards.mean` in the train scope |
+
+Matching rules:
+
+- Treat `test`, `eval`, and `validation` as evaluation scopes with equal priority. If multiple candidates exist, show their names and state which one is used.
+- For RL, recognize the `final_rewards` metric family, including names such as `final_rewards`, `final_rewards.mean`, `final_rewards.best@N`, and `final_rewards.worst@N`.
+- Prefer `final_rewards.mean`, then an exact `final_rewards`, because they represent aggregate rollout performance. Treat `best@N` and `worst@N` as supporting metrics; do not use either to rank artifacts unless the user explicitly chooses it.
+- Do not silently substitute accuracy, a generic reward, gradient norm, or another metric for the primary metric above.
+- If neither the preferred nor fallback metric exists, list the actual available metrics and ask the user to choose. Do not guess.
+
+Record:
+
+- The exact metric name and why it was selected.
+- The best metric value.
+- The corresponding step or steps.
+- Whether the metric belongs to an evaluation set or the training set.
+
+Retain every step tied at the best value. If the user requests top-k, sort in the correct metric direction and record the top-k steps. Do not treat neighboring steps as multiple "best-performing steps" by default.
+
+## B. Map the Best-Performing Step to an Artifact and Export It
+
+### 1. List artifacts
+
+```bash
+arkcli train finetune artifacts list <mcj-id>
+```
+
+Extract the step from the artifact name or structured fields. Automatically map only artifacts whose steps can be parsed reliably. If the step cannot be parsed, show the artifact list and ask the user to choose.
+
+For each best-performing step:
+
+1. Prefer an artifact with an exact step match.
+2. If no exact match exists, calculate the absolute distance to each exportable artifact step.
+3. Select the nearest artifact. If multiple artifacts tie at the same distance, retain every tied candidate.
+4. Show `metric step → artifact step → distance` explicitly. Never describe a nearest artifact as an exact match.
+
+Deduplicate artifacts mapped from different best-performing steps to avoid exporting the same artifact more than once.
+
+### 2. Obtain user confirmation
+
+Before export, display:
+
+- MCJ ID, fine-tuning type, and training method.
+- Selected performance metric, best value, and best-performing step.
+- Recommended artifact and mapping distance.
+- Current artifact export status.
+- Existing custom model ID, if already exported.
+
+Ask the user to confirm the final artifact or artifacts to export. Allow the user to add or remove candidates.
+
+### 3. Export
+
+Run the following only for user-confirmed artifacts that have not already been exported:
+
+```bash
+arkcli train finetune artifacts export <mcj-id> \
+  --artifact-name <artifact-1> \
+  --artifact-name <artifact-2>
+```
+
+If a naming prefix is needed, confirm it first and use only a parameter supported by the current `--help`. Reuse the existing `cm-...` for an already exported artifact; do not export it again.
+
+Explain that export registers an MCJ artifact as a custom model in the model registry; it does not download model weights. Record the custom model ID and status corresponding to each artifact.
+
+Common export statuses:
+
+- `Available`: available for export.
+- `Exported`: already exported; reuse `custom_model_id`.
+- `Exporting`: export is in progress; query again later.
+- `ExportFailed` / `Expired`: not directly deployable; show the status and ask the user how to proceed.
+
+## C. Query Custom Models and Deployable Versions
+
+For every user-provided or newly exported `cm-...`, read and follow the `arkcli-custommodel` skill.
+
+At minimum, run:
+
+```bash
+arkcli models custommodel get <cm-id>
+arkcli models custommodel get <cm-id> --transform artifact_types,active_endpoints
+arkcli infer endpoint capability get --custom-model-id <cm-id>
+```
+
+Summarize:
+
+- Custom model name, source, status, and base model.
+- Existing endpoints.
+- Inference types directly supported by the current model.
+- Additional inference types that may become available after creating a new version through quantization or another supported method.
+
+If the target inference type is not currently supported, follow the `arkcli-custommodel` skill:
+
+1. Query `available-quantizations` and the inference types each quantization method is expected to support.
+2. Explain the potential impact of quantization on accuracy, performance, and resource options.
+3. After user confirmation, create a new quantized `cm-...`.
+   - `custommodel quantize --dry-run` is a command-local Client Preview and emits `preview.v1`; it never sends the quantization request.
+4. Poll the new model until it reaches `ready`.
+5. Query the new `cm-...` again for details and its actual supported inference types.
+
+Do not create a new version merely because a quantization option exists. The source and quantized models are different resources; preserve a clear mapping between them.
+
+## D. Select and Deploy
+
+Show a deployment-candidate table containing at least:
+
+- Custom model ID and name.
+- Source artifact and step, when known.
+- Corresponding best metric and value, when known.
+- Whether it is the original or quantized version.
+- Currently supported inference types.
+- Existing running endpoint, if any.
+
+Ask the user:
+
+1. Which `cm-...` resource or resources to deploy.
+2. Which supported inference type to use for each model.
+3. The endpoint name and configuration required by that inference type.
+
+After the user chooses, read and follow the `arkcli-deploy` skill:
+
+1. Restate the final inputs and impact for each target.
+2. Show the endpoint to be created or reused, the selected inference type, and billing impact.
+3. Obtain final confirmation, then perform the deployment.
+4. Record every `cm-... → ep-...` mapping and endpoint status.
+
+Deploying multiple models creates multiple billable resources. Make the number of targets explicit. Never treat confirmation of artifact export as confirmation of endpoint deployment.

package/skills/arkcli-train-finetune/references/list.md

@@ -0,0 +1,79 @@
+# List Fine-Tuning Jobs
+
+Use this reference only for listing and filtering multiple jobs. If the user provides a job ID, read [`manage.md`](manage.md) instead.
+
+## Command and common filters
+
+```bash
+arkcli train finetune list [flags]
+```
+
+| Parameter | Description |
+|---|---|
+| `--name` | Fuzzy-filter by job name |
+| `--phase` | Filter by job phase; repeatable |
+| `--customization-type` | Filter by backend customization type; repeatable. Check `--help` when enum values are uncertain. |
+| `--create-time-after`, `--create-time-before` | Filter by creation time using RFC3339 |
+| `--mine` | Only include jobs created by the current SSO sub-user; server-side `TagFilters=[{Key:"sys:ark:createdBy", Values:["IAMUser/<uid>/<name>"]}]` |
+| `--page-size`, `--page-number` | Paginate manually. Page number defaults to 1 and must be `>=1`; page size defaults to 100 and must be in `1-100`. |
+| `--page-all`, `--page-limit` | Paginate automatically; always set a reasonable limit |
+| `--sort-by`, `--sort-order` | Sort results |
+| `--transform` | Extract a single field; use a JSON tool for complex projections |
+
+## Workflow
+
+1. Inspect parameters supported by the current version:
+
+```bash
+arkcli train finetune list --help
+```
+
+2. Combine filters according to the user's criteria:
+
+- Name.
+- Job phase.
+- Customization type.
+- Creation time range.
+- Creator. When the user says "mine / my jobs / jobs I created", add `--mine`; do not list the whole account and guess the creator locally.
+- Pagination and sorting.
+
+3. If the user requests all results, use the current CLI's automatic pagination parameters and set a reasonable page limit. Never fetch without a bound.
+
+For manual requests starting at page 2, the CLI first obtains `total_count` using the active filters. It returns a validation error when the requested page starts beyond the total; a final partially filled page remains valid.
+
+4. Return a concise table or summary that prioritizes:
+
+- Job ID.
+- Name.
+- Customization type or training method, as returned.
+- Current phase.
+- Creation or update time.
+
+Do not automatically call `get` for every listed job. Query a job only when the user requests details or the list response lacks a field needed to answer the request.
+
+## Command skeletons
+
+```bash
+arkcli train finetune list
+arkcli train finetune list --name <keyword>
+arkcli train finetune list --phase <phase>
+arkcli train finetune list --mine --page-all --page-size 100
+arkcli train finetune list \
+  --create-time-after <RFC3339> \
+  --create-time-before <RFC3339>
+```
+
+Obtain phase and customization-type enum values from the current `--help`; do not maintain a static list.
+
+`--mine` depends on an SSO sub-user identity and the `sys:ark:createdBy` resource tag. A degraded identity
+without an ARK IAM `UserID` gets an explicit unsupported error. Do not fake an empty tag or silently return
+account-wide rows as "mine".
+
+## Time handling
+
+- When the user provides relative time such as "today," "yesterday," or "the last week," convert it to explicit RFC3339 boundaries using the active profile or user timezone.
+- Include the actual absolute time range in the result to avoid timezone ambiguity.
+
+## Empty results
+
+For an empty result, state the filters actually used and suggest relaxing the filter most likely to be too restrictive. Do not interpret an empty list as a permission problem unless the CLI explicitly returns an authentication or authorization error.

package/skills/arkcli-train-finetune/references/manage.md

@@ -0,0 +1,140 @@
+# Retrieve and Manage a Fine-Tuning Job
+
+Use this reference for details, observation, and lifecycle operations when the job ID is known. To select an artifact by metrics, export a custom model, or continue to deployment, read [`export-deploy.md`](export-deploy.md) instead.
+
+## Command summary
+
+| Command | When to use | Common parameters |
+|---|---|---|
+| `arkcli train finetune get <job-id>` | Canonical command for retrieving full details | `--transform` |
+| `arkcli train finetune status <job-id>` | Retrieve status; semantically equivalent to the detail query | `--transform` |
+| `arkcli train finetune watch <job-id>` | Continuously monitor progress and metric changes | `--interval`, `--timeout`, `--quiet`, `--rich` |
+| `arkcli train finetune metrics <job-id>` | Retrieve metric curves | `--metric`, `--from-step`, `--to-step`, `--output` |
+| `arkcli train finetune logs <job-id>` | Retrieve training logs | `--tail`, `--since`, `--search`, `--follow`, `--output` |
+| `arkcli train finetune trajectory list/get <job-id>` | Retrieve rollout trajectories recorded for an RL job | `--limit`, `--step`, `--sample-id`, `--full`, `--output` |
+| `arkcli train finetune update <job-id>` | Update the name or description | `--name`, `--description` |
+| `arkcli train finetune pause/resume/stop/delete` | Perform lifecycle operations | Confirm before writing, deleting, or terminating; add `--yes` only when required |
+
+## Retrieve the current state first
+
+Before any write operation, run:
+
+```bash
+arkcli train finetune get <job-id>
+```
+
+Confirm that the job ID, current phase, and requested operation are compatible. Follow the current command's `--help` and backend error for phase restrictions; do not maintain a static phase matrix.
+
+Use the same direct `get` when the user asks why one named job cannot be found, and preserve the authoritative API error. Do not infer validity from date-like or readable parts of an `mcj-*` ID, search for similar jobs with `list`, or switch profile/project/region. If the user explicitly limits scope, stop after explaining the target error.
+
+## Details and process observation
+
+Choose the smallest command that satisfies the request:
+
+```bash
+arkcli train finetune get <job-id>
+arkcli train finetune watch <job-id>
+arkcli train finetune metrics <job-id>
+arkcli train finetune logs <job-id>
+arkcli train finetune trajectory list <job-id>
+```
+
+Inspect the corresponding `--help` before execution.
+
+- Use `get` for a one-time state query and `watch` to wait continuously for a terminal phase.
+- Query available metric names before filtering, then use the exact returned name.
+- When `metrics` uses both `--from-step` and `--to-step`, `to-step` must be strictly greater than `from-step`.
+- Logs and metrics can be large. Prefer filters, tailing, or `--output`; do not load the complete result into context.
+- For an RL job created with `--enable-trajectory`, use `trajectory list` for summaries and `trajectory get` for a specific rollout. This path does not depend on the fine-tuning SDK, but it requires an SSO-authenticated profile with access to the job's trajectory TLS topic. If access fails, report the authentication or TLS authorization error instead of describing trajectory inspection as unsupported on BytePlus.
+
+### Save logs for one named job
+
+When the user supplies both an MCJ ID and an output path, run this directly:
+
+```bash
+arkcli train finetune logs <mcj-id> --output <path>
+```
+
+This is a read-only, single-job query. Do not stop after viewing `logs --help`; do not run `train finetune list --page-all`, scan jobs with Python, or suggest switching profile/project. Preserve the original error and stop. Inspect the current `logs --help` only if the target command reports incompatible syntax, then retry the same target command.
+
+`--follow` polls continuously for an active job. If the job is already `Completed`, `Failed`, or `Terminated`, the CLI emits the current log snapshot and exits automatically. It also exits when an active job later becomes terminal and an idle poll has no new lines. A terminal job may use `--follow --format json` to return one bounded JSON snapshot; unbounded follow on an active job does not support single-document structured output.
+
+### Retrieve the complete trajectory for one named job
+
+```bash
+arkcli train finetune trajectory list <mcj-id> --full
+```
+
+The hierarchy must include `train finetune trajectory list`; never try `arkcli train trajectory` or wander through unrelated help trees. `--full` returns complete rollout content. Add `--output <path>` only when the user supplies a path or agrees because the result can be large. If the command reports that trajectory logging was disabled, no trajectory exists, or authentication/TLS access failed, preserve that error and stop. Do not inspect other jobs, profiles, or MCP configuration.
+
+## Troubleshoot a failed job
+
+After producing an effective Debug result with a concrete problem
+classification and next action, reuse the current `ARKCLI_SKILL_FLOW_ID` (or
+generate `ftf_<ULID>`), then run `arkcli train finetune _report-activity
+--action debug_success` with the shared prefix. Do not report a query alone.
+
+1. Run `get` and report the current phase, failure reason, and CLI-provided hint.
+2. Use `logs` with `--tail`, `--since`, or `--search` to isolate the relevant error; write large results to a file.
+3. Query `metrics` only when the job has produced valid metric data, and use exact metric names returned by the CLI.
+4. Compare the training and validation data, model version, customization type, and hyperparameters with the original creation configuration.
+5. Do not resubmit until the failure cause has been identified or the user explicitly accepts the remaining risk.
+
+## TLS configuration
+
+Use the complete `tls config` hierarchy to retrieve or manage fine-tuning TLS configuration:
+
+```bash
+arkcli train finetune tls config get
+arkcli train finetune tls config enable
+arkcli train finetune tls config disable
+arkcli train finetune tls config delete
+```
+
+No `tls update` operation is available. Do not omit `config` and write `arkcli train finetune tls get`.
+
+- `get` is read-only and can run without confirmation.
+- `enable` creates a potentially billable TLS resource. Explain the cost impact and obtain confirmation first.
+- `disable` stops new data from being written but retains existing data. Obtain confirmation first.
+- `delete` permanently removes existing trajectory, custom log, trace, and explainability data. Obtain separate confirmation; add `--yes` for non-interactive execution only after confirmation.
+
+## Job metadata
+
+Before updating the name or description, display the job ID, current value, and target value, then obtain confirmation:
+
+```bash
+arkcli train finetune update <job-id> --help
+arkcli train finetune update <job-id> --name <name>
+```
+
+Send only the fields the user requested to change.
+
+## Pause, resume, stop, and delete
+
+Inspect each current interface first:
+
+```bash
+arkcli train finetune pause --help
+arkcli train finetune resume --help
+arkcli train finetune stop --help
+arkcli train finetune delete --help
+```
+
+Rules:
+
+- Use `pause` when the user expects to continue the job later.
+- Use `resume` primarily to restore a `Paused` job, making it the reversible counterpart to `pause`. When the backend allows, it may also retry `Failed` or `Terminated`; still follow the current job phase and API result.
+- `stop` terminates the job irreversibly. Explain the impact clearly and obtain confirmation.
+- `delete` removes the job record. Display the target job ID, name, and current phase, then obtain separate confirmation. **Enforce the phase client-side:** only terminal phases (`Completed`, `Failed`, or `Terminated`) can be deleted. For a non-terminal phase, refuse locally and instruct the user to run `train finetune stop` first, avoiding a backend `phase_mismatch` after the user confirms.
+- If the agent environment requires `--yes`, add it only after user confirmation.
+- If the phase does not allow an operation, follow the CLI or backend hint. Do not bypass the restriction through repeated retries.
+
+## Training artifacts
+
+If the user only wants to view artifacts, run:
+
+```bash
+arkcli train finetune artifacts list <job-id>
+```
+
+If the user wants to select the best artifact, export it, or deploy it, stop this flow and read [`export-deploy.md`](export-deploy.md).

package/skills/arkcli-understand/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: arkcli-understand
+version: 1.0.1
+description: "arkcli +understand: a multimodal understanding workflow with 12 task-oriented sub-skills across image/video/audio/file modalities on the data-plane Responses API engine. Covers image captioning/OCR, bbox grounding, GUI action recognition, PDF/document field extraction, video summary/QA, joint audio-video understanding, ASR, speech translation, SRT alignment, speaker diarization, and meeting minutes. Platform profiles use their deployed Resources.Text.Default endpoint; plan profiles use each recipe's fallback model. Invoke for multimodal tasks with a specific output form, such as transcribing audio, locating objects, extracting PDF fields, summarizing video, generating subtitles, producing meeting minutes, or describing an image. Use +chat for open-ended visual conversations and +gen for image/video generation."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli +understand --help"
+---
+
+# arkcli +understand
+
+**CRITICAL — Before starting, you MUST use Read to open [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md), which contains authentication gates, API Key error recovery, configuration troubleshooting, and command selection order.**
+**CRITICAL — Before running `+understand`, you MUST use Read to open [`references/arkcli-understand.md`](references/arkcli-understand.md) (commands/flags/returns/errors) and [`references/sub-skills.md`](references/sub-skills.md) (purpose and expected output of all 12 sub-skills). Do not construct commands from memory.**
+
+## Core concepts
+
+- `+understand` is **not 12 implementations, but one engine plus a semantic layer**. The underlying engine is the same data-plane Responses API used by `+chat`; each sub-skill is a **recipe** `{modality, fallback model, built-in system prompt}`. When `--model` is omitted, a Platform Profile must use its deployed `Resources.Text.Default` endpoint; only plan profiles use the recipe fallback model.
+- Command form: `arkcli +understand <sub-skill> --input @file [prompt]`.
+  - If `args[0]` **matches the registry** (one of 12), it is the explicit sub-skill; remaining positional arguments become a prompt layered on the built-in prompt.
+  - If `args[0]` **does not match**, all positional arguments become the prompt, and the server automatically routes by the modality of the **first `--input` file** to that modality's default sub-skill.
+- **`--input` is required**: a sub-skill understands a particular file. Without `--input`, it immediately returns `missing_input`. A prompt alone cannot derive a recipe.
+- Return values are identical to `+chat`: arkcli's **flat** schema `{id, model, content, reasoning_content, usage}`, **not** the native nested Responses `output[].content[].text`. See "Return value" in [`references/arkcli-understand.md`](references/arkcli-understand.md).
+- Multimodal upload: image/video/doc use the SDK `file://` preprocessor and Files API automatically. **Audio is special**: it is inlined as a base64 data URL, with a **25 MB limit**. See the reference.
+- `--dry-run` resolves the local recipe, the active Profile's persisted default endpoint, an explicit model, and input-reference data and emits `preview.v1`. It never reads live Endpoint/model metadata, uploads files, calls Responses, creates usage or response IDs, or persists a response. Online-only values must be listed as `unresolved`; the plan is not server validation.
+
+## Quick decision: understand vs chat vs gen
+
+| User intent | Route |
+|---|---|
+| Multimodal understanding task with a **specific output form** (transcription / translation / subtitles / bbox localization / GUI actions / field extraction / chapter summary / multiple speakers / meeting minutes) | **`+understand`** (a matching sub-skill) |
+| Open-ended image/video conversation, follow-up questions, reasoning, multi-turn continuation (`--store`/`--previous-response-id`), tools (web_search/function), or strict JSON with `--text-format json_schema` | [`../arkcli-chat/SKILL.md`](../arkcli-chat/SKILL.md) |
+| **Generate** images/videos rather than understand existing material | [`../arkcli-gen/SKILL.md`](../arkcli-gen/SKILL.md) |
+
+One-line criterion: **if the task maps to a sub-skill below, use `+understand`; otherwise use `+chat` for open conversation and `+gen` for generation.**
+
+## Agent quick execution order
+
+1. Determine which sub-skill matches the user's task. If matched, specify the sub-skill explicitly instead of relying on automatic routing.
+2. Pass the authentication gate: if login state is uncertain, run `arkcli auth status`. Data-plane calls use an ARK API Key (`Authorization: Bearer`). On authentication failure, follow "API Key mode error recovery" in [`../arkcli-auth/references/auth-modes.md`](../arkcli-auth/references/auth-modes.md), run `arkcli auth apikey`, and **do not retry in place**.
+3. Prepare input: `--input @<file>` (repeatable). Local files use `@`; remote input uses `https://` / `tos://`.
+4. **Do not pass `--model` by default**: a Platform Profile uses the deployed `ep-xxx` in `Resources.Text.Default`, consistently with `+chat`; a plan profile uses the sub-skill's recipe fallback model. Only pass `--model` when the user explicitly requests another resource; it must be a complete versioned ID or `ep-xxx`. If uncertain, route to [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md).
+5. Add `--stream` for incremental output. To adjust instructions, use `--system-prompt-append "..."` (append) or `--system-prompt-override "..."` (replace the built-in prompt).
+6. Return to the user's original goal after execution; do not stop at an intermediate artifact.
+
+## Sub-skill quick reference (12 / 4 modalities)
+
+> The models below are recipe fallbacks for plan profiles. A Platform Profile does not invoke these bare names; it uses the Profile's deployed `Resources.Text.Default` endpoint. See Agent step 4 above when an override is required.
+
+| sub-skill | Modality | Plan recipe fallback model | Purpose |
+|---|---|---|---|
+| `image-caption` | image | `seed-2-0-lite` | Single/multiple image descriptions and OCR (preserve source text; do not paraphrase) |
+| `image-grounding` | image | `seed-2-0-lite` | Visual localization: output target bbox `(x1,y1,x2,y2)` + confidence |
+| `image-gui` | image | `seed-2-0-lite` | GUI screenshot → executable action sequence |
+| `doc-extract` | file | `seed-2-0-mini` | Extract structured JSON from PDF/doc by schema (missing values null; preserve page) |
+| `video-summary` | video | `seed-2-0-lite` | Video summary: overall / segment / chapter + key timestamps |
+| `video-qa` | video | `seed-2-0-lite` | Video Q&A using visuals + audio + timeline |
+| `vau` | video | `seed-2-0-lite` | Joint audiovisual understanding and audio-analysis report |
+| `asr` | audio | `seed-2-0-lite` | Speech transcription: plain text only, with no prefix/suffix/formatting |
+| `asr-align` | audio | `seed-2-0-lite` | Subtitle alignment: SRT by default (index + start/end + text) |
+| `asr-speakers` | audio | `seed-2-0-lite` | Multi-speaker transcription with `[spk0]` / `[spk1]` labels |
+| `ast` | audio | `seed-2-0-lite` | Speech translation into text |
+| `meeting-minutes` | audio | `seed-2-0-lite` | Structured Markdown minutes (topic/participants/key points/decisions/follow-ups) |
+
+See [`references/sub-skills.md`](references/sub-skills.md) for expected output and commands for each.
+
+## Automatic routing when sub-skill is omitted
+
+When `args[0]` does not match the registry, infer modality from the **first `--input` file extension** and fall back to its default sub-skill:
+
+| Inferred modality | Fallback sub-skill |
+|---|---|
+| image (`.jpg/.png/.webp/...`) | `image-caption` |
+| video (`.mp4/.mov/...`) | `video-qa` |
+| audio (`.mp3/.wav/.m4a/...`) | `asr` |
+| file (other extensions) | `doc-extract` |
+
+- Without `--input`, automatic routing is impossible (a prompt alone cannot derive a recipe) → `missing_sub_skill`.
+- Routing currently uses only file modality, not prompt keywords. For example, "draw a box around" does not automatically select `image-grounding`. Explicitly provide non-default sub-skills such as grounding / gui / summary / subtitles / translation.
+
+## Command overview
+
+| Command | Description |
+|---|---|
+| `arkcli +understand image-caption --input @photo.jpg "Describe this image"` | Image description |
+| `arkcli +understand image-caption --input @doc.png "Perform OCR and preserve the text exactly"` | OCR |
+| `arkcli +understand image-grounding --input @scene.jpg "Draw bounding boxes around all red cars"` | Visual bbox localization |
+| `arkcli +understand doc-extract --input @invoice.pdf "Extract the invoice number, amount, and date"` | Document field extraction |
+| `arkcli +understand video-summary --input @clip.mp4 "Summarize by chapter"` | Chapter-based video summary |
+| `arkcli +understand video-qa --input @clip.mp4 "How many cars appear in the video?"` | Video Q&A |
+| `arkcli +understand asr --input @speech.mp3` | Speech transcription (no prompt required) |
+| `arkcli +understand asr-align --input @speech.mp3` | Generate SRT subtitles |
+| `arkcli +understand asr-speakers --input @meeting.wav` | Multi-speaker transcription |
+| `arkcli +understand ast --input @speech.m4a "Translate into English"` | Speech translation |
+| `arkcli +understand meeting-minutes --input @meeting.m4a` | Meeting minutes |
+| `arkcli +understand "<prompt>" --input @photo.jpg` | Omit sub-skill → automatic routing by modality (here → image-caption) |
+| `arkcli +understand asr --input @speech.mp3 --stream` | Incremental streaming output |
+| `arkcli +understand image-caption --input @x.jpg --system-prompt-append "Answer in English"` | Append instructions after the built-in prompt |
+| `arkcli +understand image-caption --input @x.jpg "Describe the image" --dry-run` | Preview recipe/model/request summary without upload or inference |
+
+## Detailed documentation
+
+- All flags, `@file`/audio upload mechanisms, flat return schema, errors, raw API fallback, and relation to `+chat` → [`references/arkcli-understand.md`](references/arkcli-understand.md)
+- Purpose, **expected output form**, and example commands for all 12 sub-skills → [`references/sub-skills.md`](references/sub-skills.md)
+- Minimum evaluation/regression cases → [`references/evals.md`](references/evals.md)