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

package/skills/arkcli-doctor/references/scope-metrics.md

@@ -0,0 +1,157 @@
+# BytePlus VMP metrics scope
+
+Use this reference when the user needs the live metric catalog, one ModelArk
+metric value, a time series, or explicit PromQL. Use model or Endpoint diagnosis
+for an overall health decision; metrics output does not assign health by itself.
+
+Follow the resource-first rule in the parent Skill before entering this scope.
+If the request contains an Endpoint ID or foundation-model name, run
+`doctor infer-endpoint` or `doctor model` first even when the user also names a
+metric. Use this metrics scope directly only when no resource identifier is
+present, or after the resource diagnosis when a separate raw metric value is
+still required.
+
+## Command families
+
+| Goal | Command | Remote access |
+|---|---|---|
+| List the live named-query catalog | `arkcli doctor metrics list --format json` | No; local embedded catalog only |
+| Describe one query and its parameters | `arkcli doctor metrics describe <query-id> --format json` | No; local embedded catalog only |
+| Run a named query | `arkcli doctor metrics <query-id> ... --format json|scalar|table` | Yes; BytePlus VMP |
+| Run raw PromQL | `arkcli doctor metrics raw --promql '<expr>' --format json|scalar|table` | Yes; BytePlus VMP |
+
+## Discover the live catalog
+
+Do not hardcode a query count or parameter list. The embedded BytePlus catalog
+can change by release.
+
+```bash
+arkcli doctor metrics list --format json
+arkcli doctor metrics describe request.error.rate --format json
+```
+
+These commands do not require login, a configured profile, VMP, or an auth
+preflight. Execute the requested catalog command once, return its result, and
+stop. Do not inspect configuration, command help, or VMP state after a
+successful local catalog read.
+
+`list` returns an array of:
+
+- `id`
+- `summary`
+- `metric_family`
+- `calc_kind`
+- `unit`
+
+`describe` additionally returns the PromQL `template`, declared `params` with
+types and defaults, output `unit`, and `aggregation_hint`. Use the exact
+parameter names from `describe`; unknown names are rejected.
+
+## Run a named query
+
+Apply the shared authentication gate, describe the query when its parameters
+are not already known, and then run it:
+
+```bash
+arkcli doctor metrics request.error.rate \
+  --param endpoint=ep-example \
+  --window 1h \
+  --format json
+```
+
+Do not use `--param endpoint_id=...` for this query; the catalog declares the
+parameter as `endpoint`.
+
+Useful flags:
+
+| Flag | Contract |
+|---|---|
+| `--param key=value` | Bind one declared catalog parameter; repeatable |
+| `--filter label=value` | Add a label matcher only when the template declares `${@filters}`; repeatable |
+| `--window <duration>` | Lookback window in Go duration syntax; default `1h` |
+| `--step <duration>` | Sample step; default is window/60 clamped to 10-60 seconds |
+| `--workspace-id <uuid>` | Query a specific BytePlus VMP workspace and skip telemetry workspace resolution |
+| `--format json` | Return rendered PromQL, window, and raw series |
+| `--format scalar` | Reduce the matrix using the catalog aggregation hint and return top-level `value`, `unit`, and `aggregation` |
+| `--format table` | Return one row per series with tags, latest, mean, and max |
+| `--auto-bind` | Reuse/create a workspace and bind ModelArk telemetry when only binding is missing; requires approval |
+
+Doctor metrics queries are read-only and do not register `--dry-run`. The local
+`metrics list` and `metrics describe` commands expose the catalog and request
+shape without VMP access. A named or raw query is the real remote diagnosis and
+must not be presented as a Client Preview.
+
+## Output interpretation
+
+Named and raw results share these fields:
+
+| Field | Meaning |
+|---|---|
+| `query_id` | Present for a named query; omitted for raw PromQL |
+| `promql` | Exact rendered or supplied query sent to VMP |
+| `window.start`, `window.end`, `window.step` | Effective UTC query bounds |
+| `series` | JSON matrix output |
+| `value`, `unit`, `aggregation` | Scalar output at the top level |
+| `table` | Per-series summary rows for table output |
+
+Preserve the rendered PromQL, workspace scope, label values, and time window
+when reporting a query issue. An empty `series`, empty `table`, or zero scalar
+after a successful query means no matching data for that selection or a
+legitimate zero; it is not proof that ModelArk is healthy or unhealthy.
+
+Before changing the query, verify:
+
+1. The query ID and declared parameter names.
+2. The Endpoint/model label values.
+3. The BytePlus VMP workspace and ModelArk telemetry binding.
+4. The selected window and expected traffic.
+5. The metric family for the workload modality.
+
+## Raw PromQL
+
+Use raw PromQL only when the live catalog cannot express the requested metric:
+
+```bash
+arkcli doctor metrics raw \
+  --promql 'sum(rate(ark_api_proxy_request_total[5m]))' \
+  --window 1h \
+  --format json
+```
+
+The expression must mention at least one `ark_*` metric. General cluster
+queries such as `node_*`, `kube_*`, or `up{}` are rejected. Raw mode bypasses
+catalog parameter validation and has no catalog unit; verify the expression
+carefully and do not use it as the default path.
+
+## VMP workspace and `--auto-bind`
+
+Without `--workspace-id`, arkcli resolves the workspace from ModelArk telemetry
+configuration and checks VMP subscription plus cross-service authorization.
+
+If only workspace binding is missing, explain the mutation and obtain approval:
+
+```bash
+arkcli doctor metrics request.error.rate \
+  --param endpoint=ep-example \
+  --auto-bind \
+  --format json
+```
+
+If VMP is disabled or the service-linked role is missing, do not add
+`--auto-bind`. Use the official BytePlus setup path:
+
+- https://docs.byteplus.com/en/docs/vmp/Quick-start
+- https://docs.byteplus.com/en/docs/ModelArk/1263493
+
+An explicit `--workspace-id` bypasses ModelArk telemetry workspace resolution.
+Use only a workspace the user supplied or that belongs to the active BytePlus
+account; never copy one from another product or account.
+
+## Boundaries
+
+- Catalog list and describe are local and read-only.
+- Named and raw queries are remote but read-only unless `--auto-bind` is added.
+- Metrics output is evidence, not a complete model or Endpoint health decision.
+- Do not hardcode the current catalog size.
+- Do not use raw PromQL when a named catalog query exists.
+- Do not query non-`ark_*` infrastructure metrics through this command.

package/skills/arkcli-doctor/references/scope-model.md

@@ -0,0 +1,130 @@
+# BytePlus foundation-model scope
+
+Use this reference when the user provides a BytePlus ModelArk foundation-model
+name and wants health, usage, error, Endpoint, or quota diagnosis. The model
+name outranks a standalone error-code lookup.
+
+## Commands
+
+```bash
+# Default 24-hour diagnosis.
+arkcli doctor model <model-name> --format json
+
+# Explicit window.
+arkcli doctor model <model-name> --window 6h --format json
+```
+
+`--window` uses Go duration syntax. Use `168h`, not `7d`.
+
+This diagnostic is read-only and supports neither `--fix` nor `--dry-run`.
+Apply remediation through the owning command after explicit confirmation.
+
+Run the Doctor command directly. Do not run `arkcli auth status`, start login,
+inspect a profile, call `arkcli models list`, call
+`arkcli infer endpoint list`, or add another preflight first. The model scope
+preserves the requested model and reports its own authentication, catalog,
+Endpoint-visibility, and VMP failures.
+
+## Output contract
+
+BytePlus uses only fields already present in the Volc `doctor model` schema.
+The scope combines foundation-model catalog visibility, usage, Endpoint APIs,
+rate-limit APIs, and BytePlus VMP operational evidence. It does not emit a
+BytePlus-only `activation` object or `report_suggestion`.
+
+`exists.ok=true` proves only catalog visibility. It does not prove that a model
+is activated for the account, that payment is current, or that inference will
+succeed.
+
+## Checks and schema
+
+| Output | Meaning |
+|---|---|
+| `model_name` | Exact requested foundation-model name |
+| `window.duration`, `start_time`, `end_time` | Effective diagnostic evidence window |
+| `exists.ok`, `not_found`, `reason` | Catalog visibility result |
+| `exists.modality` | `text`, `image`, `video`, or `unknown` from authoritative model tags |
+| `exists.vendor`, `display_name`, `primary_version` | Returned model metadata |
+| `endpoint_total.total` | Visible Endpoints serving the model |
+| `endpoint_state_distribution.buckets` | Endpoint lifecycle count and percent by state |
+| `usage.available` | Whether model usage was returned |
+| `usage.total_calls`, token fields, cache fields | Window totals for the applicable modality |
+| `top_endpoint_by_usage` | Top Endpoints from authoritative ModelArk usage data |
+| `errors.overall` or `errors.task` | Modality-specific error-code distribution |
+| `error_rate.overall`, `request`, or `task` | Modality-specific rate channels |
+| `top_endpoint_by_error_rate` | BytePlus VMP ranking using `ark_endpoint` and `base_model` labels |
+| `account_quota_pressure` | Applicable account-level limit, peak, percent, and level |
+
+## Analysis order
+
+1. Read `exists.ok`. If false, report `not_found` and `reason`, then stop.
+2. Read `exists.modality` before interpreting tokens, images, async tasks, or
+   concurrency.
+3. Read Endpoint count and state distribution. Zero visible Endpoints means no
+   visible deployed Endpoint in the active profile scope; it does not prove an
+   activation or payment state.
+4. Read `usage.available`, totals, and `top_endpoint_by_usage`. Text models rank
+   naturally by tokens; image and video models can fall back to call or task
+   count.
+5. Read the model-level error-rate channel, leading error codes, and
+   `top_endpoint_by_error_rate` for the same window.
+6. Load [`error-codes.md`](error-codes.md) for the exact leading code.
+7. Read only quota fields present for the modality and use their structured
+   `level` and `percent`.
+8. Drill into one Endpoint with `doctor infer-endpoint <id>` only when the model
+   result identifies a relevant candidate.
+
+## Operational interpretation
+
+| Finding | Next action |
+|---|---|
+| `exists.ok=false` | Check the exact name, fixed Region, and IAM visibility |
+| Many Endpoints are not running | Select the relevant Endpoint and use `doctor infer-endpoint`; lifecycle writes belong to `arkcli-infer-endpoint` |
+| One Endpoint dominates usage | Check that Endpoint's state, error rate, and quota pressure |
+| One Endpoint dominates error rate | Run `doctor infer-endpoint <id>` for resource-level evidence |
+| Model-wide error rate exceeds `threshold_percent` | Interpret the leading exact error codes and distinguish model/account causes from one Endpoint |
+| `level=critical95` or `warn80` | Reduce or redistribute traffic, or request the applicable BytePlus quota |
+| `ModelNotOpen` | Interpret the exact error with `error-codes.md`; do not invent an activation field |
+| `RequestBurstTooFast` | Ramp traffic gradually and retry idempotently with exponential backoff |
+
+## Modality routing
+
+| Modality | Error fields | Usage and quota interpretation |
+|---|---|---|
+| Text | `errors.overall`, `error_rate.overall` | Tokens, cache, RPM, and TPM when populated |
+| Image | `errors.overall`, `error_rate.overall` | Calls, images, and IPM when populated |
+| Video or async content generation | `errors.task`, `error_rate.request`, `error_rate.task` | Calls, tasks, create-task RPM, and concurrency when populated |
+| Unknown | Preserve returned fields and state the limitation | Do not guess a metric or quota family from the model name |
+
+An empty VMP series or zero peak is not proof of health. Check the workspace,
+labels, selected time window, usage availability, and whether that metric is
+populated for the modality.
+
+## VMP precheck and binding
+
+If VMP and the ModelArk service-linked role are ready but only the workspace
+binding is missing, explain the mutation and obtain approval before running:
+
+```bash
+arkcli doctor model <model-name> --window 24h --auto-bind --format json
+```
+
+The command may reuse the first workspace or create `ark_default`, then bind
+ModelArk telemetry. It does not enable VMP, grant IAM, activate the model, or
+make a payment. If VMP is disabled or the service-linked role is missing, stop
+at the official BytePlus setup path.
+
+## Boundaries
+
+- Read-only unless `--auto-bind` is explicitly approved.
+- Does not invoke the model and does not consume inference tokens.
+- Diagnoses foundation models, not custom-model training jobs.
+- Does not prove or change model activation or payment state.
+- Does not modify Endpoints.
+- Does not compare accounts, Regions, or products.
+- Does not support or suggest `doctor report`.
+
+Use [`scope-infer-endpoint.md`](scope-infer-endpoint.md) for one Endpoint and
+[`scope-account.md`](scope-account.md) for available-balance, IAM, VMP, or TOS
+readiness. Doctor does not determine payment qualification, bill status, or
+overdue state.

package/skills/arkcli-doctor/references/verify-origin.md

@@ -0,0 +1,102 @@
+# ModelArk Generation-Origin Verification
+
+## Scope
+
+Use:
+
+```bash
+arkcli doctor +verify-origin <media-url> [media-url...] --format json
+```
+
+The command checks whether 1-20 public image or video URLs contain technical
+features associated with the ModelArk generation process.
+
+It does not determine content truthfulness, copyright, ownership, legal
+certification, content safety, compliance, media quality, or playability.
+
+## One Confirmation for the Entire Batch
+
+Run the complete batch once without `--yes`:
+
+```bash
+arkcli doctor +verify-origin \
+  "https://example.com/a.mp4" \
+  "https://example.com/b.png" \
+  --format json
+```
+
+This call does not acquire the origin-verification invoker or call Create/Get.
+It returns one disclosure covering the entire batch:
+
+- 20 free calls per account, but remaining quota is unknown;
+- USD 0.015 per successful call after the free quota;
+- successful `True`, `False`, and `Null` results are billable;
+- authentication and rate-limit failures are not billable;
+- daily limit 1000;
+- Create and Get target 20 QPS.
+
+Show the disclosure and wait for explicit user confirmation. Then rerun the same
+batch with one `--yes`:
+
+```bash
+arkcli doctor +verify-origin \
+  "https://example.com/a.mp4" \
+  "https://example.com/b.png" \
+  --yes \
+  --format json
+```
+
+That single `--yes` authorizes every URL in the current batch. Never ask once
+per URL.
+
+## Execution and Recovery
+
+The CLI owns:
+
+```text
+CreateArkOfficialResultQuery
+  -> Result.QueryID
+  -> GetArkOfficialResult every 5 seconds
+  -> running continues
+  -> succeeded or failed terminates
+```
+
+Do not launch separate CLI processes, write a shell loop, call raw Actions, or
+poll in the Agent.
+
+Resume existing tasks without creating or reconfirming them:
+
+```bash
+arkcli doctor +verify-origin \
+  --query-id "<query-id-1>" \
+  --query-id "<query-id-2>" \
+  --format json
+```
+
+Each URL may be created at most once. A Get retry must preserve its QueryID and
+must never return to Create.
+
+## Authentication
+
+This is a control-plane OpenTOP workflow:
+
+- use BytePlus login-derived STS or configured AK/SK;
+- do not use an Ark data-plane API key;
+- do not pass global `--api-key` or `--base-url`;
+- do not retry through another product.
+
+## Exact Output Handoff
+
+The final response must contain only the complete CLI stdout JSON:
+
+- no summary, interpretation, or translation;
+- no extraction of only `Result` or `Message`;
+- no Markdown code fence, prefix, or suffix;
+- no `--transform`;
+- no YAML, table, CSV, or JSONL.
+
+Never convert:
+
+- `True` into legal or official certification;
+- `False` into certainty that ModelArk was not involved;
+- `Null` into `False`.

package/skills/arkcli-gen/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: arkcli-gen
+version: 2.0.1
+description: "Image/video generation entry point: Use arkcli +gen when the user wants to generate an image, draw an image, generate an image/video, generate an image or a video from a reference image, generate from a reference image/video/audio, or explicitly use Seedream/Seedance models to create new content.+gen generates based on the available resources of the current profile and the model supported_params. Images are returned synchronously. After a video is submitted, task_id/status is returned. Use --wait or arkcli gen get/list to poll and download the result."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli +gen --help"
+---
+
+# arkcli generation workflow (+gen)
+
+**CRITICAL: Before starting, you MUST first use the read tool to read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) (authentication gate, model lookup fallback, and shared security rules).**
+
+**CRITICAL: This is a three-step workflow, not a single command. To generate images/videos, you MUST execute in the order `Step 1 → Step 2 → Step 3`. Do not skip Step 1/2 and run `+gen` directly: it will fail because the model name format is wrong (404) or because parameters unsupported by the model are passed. Before running it, be sure to read [`references/arkcli-gen.md`](references/arkcli-gen.md).**
+
+## Why this is a workflow (core concept, understand before running)
+
+When the user says "generate a video/image", it is essentially **three independent things that must be done in order**:
+
+```
+1. Which models are available in the current profile: Model sources differ completely by profile (EP vs model name)
+2. Which parameters this model supports: Passing parameters without checking = guessing blindly = rejected by validation/backend
+3: Generate using the available parameters
+```
+
+Compressing these three steps into "directly guess a `+gen` command" is exactly where failures come from: an incorrect model name format causes a 404, and unsupported parameters are rejected.
+
+## Authoritative modality contract
+
+Production calls resolve generation capability in this fixed order:
+
+```text
+explicit --modality > output_modalities > task types > unknown
+```
+
+- For a versioned model ID, Ark CLI reads `output_modalities` from ArkModels, then falls back to `task_types` / `filter_task_types` from the FoundationModel.
+- For an `ep-*` ID, Ark CLI first reads `Endpoint.ModelReference.FoundationModel(name, version)`, then selects that exact model version and applies the same metadata contract.
+- **Model names and display names are identifiers, not capability evidence.** Dola, Dreamina, Seedream, Seedance, or any future branding must not determine image/video routing.
+- Missing or conflicting metadata resolves to `unknown`; pass `--modality image|video` explicitly instead of guessing.
+- `+gen --dry-run` is a local Client Preview. It never reads live model or
+  Endpoint metadata, calls generation APIs, downloads files, or opens an
+  application. Pass `--modality image|video` for an unknown model or Endpoint;
+  online-only routing is reported as `unresolved` with `fidelity=partial`.
+- Execute exactly one `arkcli +gen ... --dry-run` for one preview request.
+  After a successful `preview.v1` response, deliver it and stop immediately;
+  explain `steps`, `unresolved`, `fidelity`, and explicit parameters from that
+  response. Do not run `+gen --help`, change flags and retry, or repeat the same
+  dry-run to reconfirm a successful preview.
+
+## Use cases
+
+- "Generate an image" / "text-to-image" / "draw an X".
+- "Generate a video" / "text-to-video".
+- Image-to-image / image-edit / adding a reference image; image-to-video (I2V); reference-to-video (R2V); reference audio.
+- "Use this image as the first frame to generate a video" / "keep the motion from this reference video".
+
+## Workflow overview
+
+```
+User intent: "Generate X"
+  │
+  ▼ Step 1 (mandatory) List models available in the current profile  ──► arkcli resources list --modality image|video
+  │     platform    → List EPs (ep-xxx)           ┐
+  │                                            ├─ Select one and record it as $MODEL
+  │     coding-plan → List EPs (via platform)     ┘
+  │
+  ▼ Step 2 (mandatory, except EPs) Check available parameters for $MODEL  ──► arkcli models get $MODEL --transform supported_params
+  │     Model name + has sp → **only** use the listed parameters, with values within min/max/enum
+  │     Model name + empty sp (not configured or currently unparseable) → +gen applies modality fallback defaults (video 720p/5s; image leaves size unset)
+  │     EP (ep-xxx)            → Skip; do not force-fill parameters (unknown underlying capabilities); let the server decide.
+  │
+  ▼ Step 3 Generate based on available parameters  ──► arkcli +gen --model $MODEL [parameters allowed by Step 2] "prompt"
+  │
+  ▼ Step 4 (result handling)
+        Video = asynchronous: returns task_id + status=queued (**not a failure!**) → Use arkcli gen get <task_id> to poll; when it becomes succeeded, the result is automatically downloaded locally (local_path); add --wait for synchronous blocking (capped by --timeout, default 10m; raise it for long videos)
+        Image = synchronous: directly returns output_url + local_path
+```
+
+## Step 1(mandatory) List models available in the current profile
+
+```bash
+# List by target modality. The output items[].id is the candidate that can be used as --model.
+arkcli resources list --modality video   # or image
+```
+
+- **Platform differences (`resources list` already routes automatically by profile; just read items)**:
+  - `platform` profile → items are **inference endpoints (EPs)** (`ep-xxx`), and each EP binds a model internally.
+  - `coding-plan` profile → It does not contain vision models itself. `+gen image/video` automatically uses the platform data plane, and **`--model` must explicitly pass an EP on platform**.
+- `is_default: true` marks the current default for this modality. Prefer it when the user does not specify one.
+- **Select an ID and record it as `$MODEL`; use it throughout Step 2/3.**
+- If the user has already explicitly provided a model/EP, it is still recommended to use `resources list` to check that it is available in the current profile. If it differs from the default, handle it according to "Default drift detection and promote nudge" in [`../arkcli-shared/references/profile-defaults.md`](../arkcli-shared/references/profile-defaults.md).
+
+## Step 2 (mandatory, except EPs) Check available parameters for $MODEL
+
+```bash
+arkcli models get "$MODEL" --transform supported_params
+```
+
+- **`$MODEL` is a model name**: Get the `supported_params` list for this model (each item contains `name / type / support / min / max / enum / required`).
+  - > **MUST: Step 3 can only use parameters where `support=true` here, and values must be within the `min/max/enum` range.** Parameters not in the list (or with `support=false`) will be rejected by `+gen`.
+  - **You can directly use the ID returned by Step 1 `resources list`**: `models get` normalizes by DisplayName to the canonical hyphenated name. But normalization **only accepts the one form where "the dotted spelling == the lowercased DisplayName"** — it is not "any dotted name works". Step outside that and you get `not found`:
+    - ✅ `dreamina-seedance-2.0-fast` (its DisplayName is exactly `Dreamina-Seedance-2.0-fast`) → `dreamina-seedance-2-0-fast`
+    - ✅ `dola-seedream-5.0-pro` (DisplayName `Dola-Seedream-5.0-pro`) → `dola-seedream-5-0-pro`
+    - ❌ `dola-seedream-5.0-pro-260628` — **dotted spelling + date snapshot**: the DisplayName carries no date, so it does not match
+
+    **Rule**: any name with a date snapshot always uses the hyphenated form (`dola-seedream-5-0-pro-260628`); the dotted form is only for dateless family / variant names. If `not found` persists, check the canonical name with `arkcli models search <family name>` rather than guessing where the dots go.
+  - If the model is found but `supported_params` is empty / `null`, that version has no configured catalog or its upstream catalog is currently unparseable. Preserve any `warn: model supported_params enrichment failed: ...` line from stderr for troubleshooting. **Do not guess parameters manually**: `+gen` automatically applies built-in modality fallback defaults (video: `resolution=720p` / `duration=5` / `ratio=adaptive`) to fill parameters you did not specify. **Image tasks get no `size`** — the canvas follows the aspect ratio described in the prompt plus the server default, and pinning a 1:1 constant would override a ratio the prompt already states; pass `--size` explicitly when you need a fixed canvas. When the control-plane lookup *fails* (as opposed to the model simply having no catalog), stderr also carries a `warn: ...` line saying validation was skipped — it goes to stderr rather than the JSON payload, and appears even when generation fails. Go directly to Step 3.
+- **`$MODEL` is an EP (`ep-xxx`)**: Skip this step. It is normal that supported_params cannot be found for an EP. Also, `+gen` **does not** apply fallback defaults to EPs (the model behind the EP may support higher capabilities, and forcing defaults may downgrade it incorrectly). Degrade open directly and let the server decide.
+  - Only the `supported_params` lookup is skipped. A real `+gen` call still resolves image/video through `Endpoint -> ModelReference -> FoundationModel metadata`.
+  - Provide `--modality` only when authoritative metadata is unavailable or conflicting.
+
+## Step 3: Generate based on available parameters
+
+```bash
+# Text-to-image / text-to-video.
+arkcli +gen --model "$MODEL" "<prompt>"
+
+# With parameters confirmed in Step 2 (example: video 1080p + priority 9, provided that supported_params lists them).
+arkcli +gen --model "$MODEL" --resolution 1080p --priority 9 "<prompt>"
+
+# Image-to-image / image-to-video / reference assets: --input can be repeated.
+arkcli +gen --model "$MODEL" --input @ref.jpg "<prompt>"
+```
+
+- For the full parameter set, multimodal `--input` rules, and the new `--n/--priority/--wait/--timeout`, see [`references/arkcli-gen.md`](references/arkcli-gen.md).
+- **Artifacts are automatically downloaded to CWD by default** (or `--save-to <dir>`). The `local_path` in JSON is the persistent artifact. The presigned `output_url` expires after 24 hours, so prefer referencing `local_path`.`--save-to=""` disables this.
+- **Images are also archived into the product gallery by default.** Pass `--no-gallery` or set `ARKCLI_NO_GALLERY=1` to disable this.
+- **Automatically open artifacts with the system default application**: By default, artifacts are opened only when stdout is an interactive terminal (a person runs it directly in the terminal). When an agent / pipeline / CI captures stdout (non-TTY), **no window pops up**, and only `local_path` is returned.`--open` forces opening, and `--no-open` forces not opening. This only applies to local files that have already been saved (when an asynchronous video does not use `--wait`, there is no local file and nothing is opened). For multiple artifacts, only the first few are opened.
+- **🔑 You are an agent, so use `--open` by default**: When you (the AI agent) call arkcli, stdout is taken over by you = non-TTY, so the default auto behavior will not pop up a window. The user can only see the file path, not the finished artifact.**To let the user directly see the generated image/video, by default add `--open` to all `+gen` commands that generate images/videos for a real person and to `gen get` commands that poll to `succeeded`** (`--open` ignores TTY and forces opening on the user's desktop). Exceptions only apply when the user explicitly says "do not open it / in a script / batch / no pop-up", or when generating more than 4 images in one batch → in these cases, omit `--open` or explicitly use `--no-open`.
+
+## Step 4 (result handling) Asynchronous video generation / synchronous image generation
+
+| Modality | Default behavior | How you should read the result |
+|------|---------|---------------|
+| **Video** | **Asynchronous**: immediately returns `task_id` + `status: queued` | `queued` **is not a failure**. Use `arkcli gen get <task_id> --open` to poll until `succeeded`—**this `gen get` call will also download the artifact locally and return `local_path`** (default CWD, `<task-id>.mp4`). `--open` makes the finished artifact pop up directly on the user's desktop (you are an agent, non-TTY, so without it there is only a path). You do not need to manually curl `output_url`; **do not** resubmit `+gen` just because you did not get the video (that creates a new task) |
+| Video + `--wait` | Synchronous: blocks until completion before returning, **but gives up once it passes `--timeout` (default 10m)** | `arkcli +gen ... --wait --open`, directly get `output_url` / `local_path` and pop up the finished artifact.**Raise `--timeout` first for long videos** (e.g. `--timeout 30m`): in measurement, nearly half of seedance-2.0 requests did not finish rendering within 10m. Hitting the cap returns "the task is still running + task id", **not a failure** — keep polling with `gen get <task-id>` and **do not re-run `+gen`** |
+| **Image** | **Synchronous**: directly returns `output_url` + `local_path` | `arkcli +gen ... --open` makes the image pop up directly for the user to view |
+
+> **⚠️ Behavior change (2.0)**: The default video task behavior has changed from "automatically wait for completion" to "return task_id immediately after submission". To use the old synchronous blocking behavior, explicitly add `--wait`.
+
+> **⚠️ `--wait` has a cap**: it blocks for at most `--timeout` (default 10m) and then returns. Video rendering often takes longer (measured: nearly half of seedance-2.0 requests exceed 10m), so **pass `--timeout 30m` explicitly for long videos**. The JSON returned at the cap is a `type: timeout` error **carrying the task id** — this is **not a generation failure**, the task is still rendering server-side; keep polling with the `gen get <task-id>` from the hint and **never re-run `+gen`** (that creates a second billed task).
+
+## Quick decision
+
+- If the user wants to generate an image/video in one go → Use this workflow (Step 1→2→3).
+- If the user has not chosen a model yet → Step 1 `resources list` lists candidates; if the model family is uncertain → switch to [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md).
+- Image-to-image / reference assets → Add `--input @<file>` in Step 3 (repeatable).
+- If the user "does not see the video" after video generation → It is probably asynchronous `queued`. Use `arkcli gen get <task_id> --open` to poll. The call that reaches `succeeded` will automatically download the artifact locally (see the returned `local_path`) and pop up the finished artifact. Do not resubmit.
+- **Add `--open` by default when generating images/videos for a real person** → You are an agent (non-TTY). Without it, the user can only see the path, not the finished artifact. Omit it or use `--no-open` only for "do not open / in a script / batch >4 images".
+
+## Natural language trigger table for advanced flags
+
+| How the user says it | Corresponding flag / command |
+|---|---|
+| "Open it directly after generation / open it for me to see / pop it up when it is ready" | `arkcli +gen --open` (force opening with the system default application; it is already opened automatically by default in an interactive terminal) |
+| "Do not open automatically / no pop-up / I am running it in a script, do not open it" | `arkcli +gen --no-open` (force not opening) |
+| "Preview / do not actually submit / only view parameters / dry run / trial run / take a look first" | Run `arkcli +gen ... --dry-run --format json`; inspect `steps`, `unresolved`, and `fidelity`, and do not present a partial plan as server validation |
+| "Do not download / URL only / do not save locally / disable automatic download" | Add `--save-to=""` explicitly; retain it together with `--dry-run` so the preview verifies the no-download intent for a future real execution |
+| "Force execution / skip validation / I know it is unsupported but want to try it" | `arkcli +gen --force` |
+| "Coherent multiple images / in order / consistent style / 4-panel comic / sequential images" | `arkcli +gen --sequential` |
+| "My previous tasks / generation history / task list / task status" | `arkcli gen list` (list all asynchronous generation tasks) |
+| "Is that task finished / check progress / check status" | `arkcli gen get <task_id>`
+
+## Command overview
+
+| Command | Role |
+|------|------|
+| `arkcli resources list --modality image\|video` | **Step 1**: Models/EPs available in the current profile |
+| [`arkcli models get <model> --transform supported_params`](../arkcli-models/SKILL.md) | **Step 2**: Check available model parameters |
+| [`arkcli +gen`](references/arkcli-gen.md) | **Step 3**: Generate based on available parameters |
+| [`arkcli +gen --stream`](references/image-stream.md) | Streaming NDJSON output for image tasks |
+| [`arkcli gen get <task-id>`](references/gen-meta.md) | **Step 4**: Poll/query asynchronous video tasks |
+| [`arkcli gen list`](references/gen-meta.md) | List/filter asynchronous generation tasks |
+| [`arkcli gen delete <task-id>`](references/gen-meta.md) | Delete asynchronous generation tasks |
+
+## Common fallbacks
+
+- Model name reports `not found` → `models get`'s normalization only covers the one form where "the dotted spelling == the lowercased DisplayName" (see Step 2); it is not "any dotted name works". First **convert any name carrying a date snapshot to the hyphenated form** (`dola-seedream-5-0-pro-260628`); if it still reports this, check the canonical name with `arkcli models search <family name>`.
+- Parameter rejected (`param_not_supported`) → Go back to Step 2 and check `supported_params`. Use only the listed parameters. If you really need to force it, you can add `+gen --force` to skip validation (the server still makes the final decision).
+- **Content blocked by moderation** (`ContentRiskBlocked` / `*SensitiveContentDetected` / sensitive-content hit / copyright) → This is not a parameter issue, and `--force` cannot bypass it. Adjust the prompt / sensitive content in the input assets and retry. For structured blocking causes + fix guidance, switch to `arkcli doctor error <code>` in [`../arkcli-doctor/SKILL.md`](../arkcli-doctor/SKILL.md) (full coverage for all 5 video-generation blocking subtypes).
+- Authentication error → Switch to [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+
+## References
+
+- [arkcli-shared](../arkcli-shared/SKILL.md) — Authentication and global parameters (must read).
+- [arkcli-models](../arkcli-models/SKILL.md) — Detailed explanation of Step 2 model query / `supported_params`.
+- [references/arkcli-gen.md](references/arkcli-gen.md) — Full `+gen` parameters + multimodal + asynchronous semantics.