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

package/skills/arkcli-custommodel/references/arkcli-custommodel-update.md

@@ -0,0 +1,47 @@
+# arkcli models custommodel update
+
+Update a custom model's name or description.
+
+## Usage
+
+```bash
+arkcli models custommodel update <id> [flags]
+```
+
+## Examples
+
+```bash
+# Update the name
+arkcli models custommodel update cm-xxxxx --name new-display-name
+
+# Update the description
+arkcli models custommodel update cm-xxxxx --description "updated for v2 release"
+
+# Update both fields
+arkcli models custommodel update cm-xxxxx --name v2 --description "..."
+```
+
+## Flags
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `<id>` | Yes | string | Custom model ID in `cm-xxxxx` form |
+| `--name` | No* | string | New account-unique name. It must begin with an ASCII letter; subsequent characters may be Chinese characters, ASCII letters, digits, underscores, or hyphens. |
+| `--description` | No* | string | New description, up to 300 characters |
+
+*Pass at least one of `--name` or `--description`.
+
+**Note:** This command changes **display properties only**. It cannot change the base model, customization type, quantization method, or status. Changing `--name` does not affect deployed endpoint references because endpoints reference the model by ID.
+
+## Output
+
+On success, `result` contains only `id` and the fields changed by this request:
+
+```json
+{
+  "id": "cm-xxxxx",
+  "name": "new-display-name"
+}
+```
+
+The response contains both `name` and `description` only when both fields were changed. It does not return unchanged fields or the complete model details.

package/skills/arkcli-custommodel/references/arkcli-custommodel-upload.md

@@ -0,0 +1,64 @@
+# arkcli models custommodel upload
+
+Import a custom model from TOS asynchronously.
+
+> **Prerequisite: Activate BytePlus Torch Object Storage (TOS) and upload the model weights to a bucket before using the resulting `tos://<bucket>/<prefix>` URI with `--tos`.**
+>
+> - BytePlus TOS quick start: <https://docs.byteplus.com/en/docs/tos/docs-quick-start_1>
+> - BytePlus TOS file upload guide: <https://docs.byteplus.com/en/docs/tos/docs-uploading-a-file>
+>
+> Follow one of these paths:
+>
+> - The user provides `tos://<bucket>/<prefix>`: confirm `--name`, `--base-model`, and `--tos`, then run `upload` after confirming the write operation.
+> - The user has no TOS URI: **do not** run `upload`. Share the two links above and ask the user to enable TOS, create a bucket, upload the weights, and return with the URI.
+>
+> The bucket region must match the current BytePlus ModelArk region.
+
+## Usage
+
+```bash
+arkcli models custommodel upload --name <name> --base-model <foundation-model-id> --tos tos://<bucket>/<prefix> [flags]
+```
+
+## Examples
+
+```bash
+# Minimal request with all three required parameters
+arkcli models custommodel upload \
+  --name my-finetune-v1 \
+  --base-model <byteplus-foundation-model-id> \
+  --tos tos://my-bucket/finetune/v1/
+
+# Include a description and quantize during upload
+arkcli models custommodel upload \
+  --name my-finetune-v1-int8 \
+  --base-model <byteplus-foundation-model-id> \
+  --tos tos://my-bucket/finetune/v1/ \
+  --quantization int8 \
+  --description "lora-sft on customer support corpus, int8 quantized"
+
+```
+
+`upload` starts an asynchronous import that depends on TOS state and cannot
+produce a reliable offline plan, so it does not register `--dry-run`. Restate
+and confirm `name/base-model/tos/quantization` before real execution.
+
+## Flags
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `--name` | Yes | string | Account-unique custom model name. It must begin with an ASCII letter; subsequent characters may be Chinese characters, ASCII letters, digits, underscores, or hyphens. |
+| `--base-model` | Yes | string | BytePlus base model ID. Query it with `arkcli models search` under the target BytePlus profile; do not hard-code a model version that may become outdated. |
+| `--tos` | Yes | string | TOS URI in `tos://<bucket>/<prefix>` form pointing to the weight directory. Create the bucket and upload the weights in the TOS console first. |
+| `--quantization` | No | string | Quantization method to apply during upload; the model can also be quantized later with `quantize` |
+| `--description` | No | string | Description, up to 300 characters |
+
+## Output
+
+Returns JSON containing the new `cm-xxxxx` and its initial status, usually `preparation`.
+
+**Notes:**
+
+- This is an **asynchronous** job. A successful response means only that the request was accepted, not that the weights are ready. Poll with `custommodel get <id>` until `status=ready` before deployment or quantization.
+- The TOS bucket and current BytePlus ModelArk environment must be in the same region. Cross-region imports fail.
+- If `--quantization` is provided during upload, the registry contains both the original and quantized `cm-xxxxx` models.

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

@@ -0,0 +1,59 @@
+# arkcli-custommodel evals
+
+## Coverage goals
+
+- Route custom model requests to `arkcli models custommodel ...`, not to base model commands such as `arkcli models search/list`.
+- For "my custom models," prefer `custommodel list --mine` over the shared skill's client-side Tags filter.
+- Confirm intent before write operations such as upload, deletion, or quantization, and poll asynchronous jobs with `get`.
+- Check `active_endpoints` before deletion to avoid breaking an existing inference path.
+
+## Triggers
+
+- Trigger `arkcli-custommodel` when the user explicitly asks about custom models, imported models, or fine-tuning artifacts.
+- Trigger the `upload` path when the user wants to import weights from BytePlus TOS into the ModelArk model registry.
+- Trigger the `available-quantizations` → `quantize` path when the user wants to quantize a ready custom model.
+
+## Anti-triggers
+
+- Do not use this skill when the user wants platform-provided base models, model versions, context-window information, or capability recommendations. Route to `arkcli-models`.
+- Do not pass `cm-xxxxx` directly to `+chat` or `+gen` for chat, image generation, or video generation. Route to `arkcli-deploy` first to create an endpoint.
+- Do not remain in this skill when the user wants to manage an existing endpoint. Route to `arkcli-infer-endpoint`.
+- Do not assume this skill creates fine-tuning jobs. Route those requests to `arkcli-train-finetune`.
+
+## Guards
+
+- If authentication state is unknown, run `arkcli auth status` first.
+- Before `upload`, `update`, `delete`, or `quantize`, restate the impact and obtain confirmation.
+- Before `delete`, run `arkcli models custommodel get <id> --transform id,name,active_endpoints`.
+- Before `quantize`, confirm that the source model has `status=ready`, then run `available-quantizations <id>`.
+- Use `quantize --dry-run` only for local request preview, never server-side validation, then obtain user confirmation before the real quantization request.
+- After `upload` or `quantize`, do not resubmit the command. Poll with `get` instead.
+
+## Tested happy-path CLI commands
+
+```bash
+arkcli models custommodel list --mine --statuses ready --format json
+arkcli models custommodel get cm-xxxxx --transform id,name,status,active_endpoints,artifact_types
+arkcli models custommodel available-quantizations cm-xxxxx
+```
+
+## Regression cases
+
+| Case | Prompt | Expected behavior |
+|---|---|---|
+| `custommodel-list-mine` | Show me my ready custom models. | Read the shared skill and list reference; run `arkcli models custommodel list --mine --statuses ready`; do not use `arkcli models list/search` as the primary path. |
+| `custommodel-list-invalid-sort-order` | List the first page of custom models with `--sort-order invalid`. | Explain that `--sort-order` accepts only lowercase `asc` or `desc`; do not send a request or pass the invalid value to the backend. |
+| `custommodel-list-tabular-output` | List custom models as a table. How should each result be read? | Read the list reference; interpret each `result.items[]` model as one row and never describe the paginated `result` as a Go map. Use JSON/YAML when total/page metadata is required. |
+| `custommodel-upload-tos` | Import the weights at tos://bucket/path/ as a custom model. | Read the upload reference; confirm `--name`, `--base-model`, and `--tos`; confirm the write operation before execution; instruct the user to poll with `get` afterward. |
+| `custommodel-delete-guard` | Delete cm-abc. | Read the delete and get references; inspect `active_endpoints` and restate the impact; optionally preview with `--dry-run`; delete only after confirmation and use `--yes` only in a non-interactive flow. |
+| `custommodel-quantize-ready` | Quantize cm-abc to int8. | Use `get` to confirm `ready`; run `available-quantizations cm-abc`; verify that int8 is available; preview with `quantize --dry-run`; require zero network effects and no backend `DryRun` in the payload; never call it server validation; obtain confirmation before the real `quantize`; poll the new ID with `get`. |
+| `custommodel-direct-chat-anti` | Run +chat directly with cm-abc. | Load `arkcli-custommodel`; do not run `+chat`, `+deploy`, `infer endpoint list`, or an ad hoc `jq` scan; explain that `cm-*` cannot be invoked directly and requires an Endpoint; route to `arkcli-deploy` only after separate deployment authorization. |
+
+## Scoring criteria
+
+- Route to `arkcli-custommodel` and read the corresponding reference before each specific command.
+- Do not replace custom model commands with base model catalog commands.
+- Do not skip write-operation confirmation.
+- Use `quantize --dry-run` only for local preview; it neither contacts the server nor creates a quantized model.
+- Do not skip the endpoint-reference check before deletion.
+- Do not pass `cm-xxxxx` directly as the inference model for `+chat` or `+gen`.

package/skills/arkcli-datasets/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: arkcli-datasets
+description: Use ArkCLI to create, validate, inspect, update, delete, version, and download datasets. Trigger for Dataset, ds-*, dsv-*, reusable training or validation data, schema validation, and dataset-backed fine-tuning jobs.
+---
+
+# ArkCLI Datasets
+
+Read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) first and follow its authentication, output, safety, Client Preview, and confirmation rules.
+
+## Scope
+
+- Create a Dataset and its first `V1`, or create a new version for an existing Dataset.
+- Use local `.jsonl` files or map objects from one TOS bucket.
+- Resolve the exact `DatasetSchema` from a foundation model fine-tuning configuration and run server-side validation.
+- Inspect, update, delete, version, and download Dataset resources.
+- Produce stable `<dataset-id>:<version-id>` references for `train finetune create`.
+
+Use [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md) when the task only manages fine-tuning jobs. Do not replace an available `dataset` product command with Raw API calls.
+
+## Guards
+
+1. Run `arkcli auth status` first and recover authentication through the shared skill if needed.
+2. Read the target leaf command's `--help` before execution and follow the installed CLI version.
+3. `--dataset-format` accepts only `LLMSft`, `LLMPretrain`, `LLMDPO`, `LLMRL`, `EmbeddingSft`, `ImageGenSft`, or `VideoGenSft`. Never send display labels or another backend SchemaType.
+4. `--local` and `--tos-uri` are mutually exclusive. Local inputs must be `.jsonl` and are limited to 20 files. Multiple TOS URIs must use one bucket. Every `--tos-uri` prefix must be listable by the current identity and contain at least one `.jsonl` object. Never reuse a `ds-ds/*` upload staging path; use registered storage under `ark/dataset/<dataset-id>/<dataset-version-id>/` or another readable data path.
+5. Create and version-create validate every input first. Omit `AccountID` from `ValidateDataset.StorageRawLocation.Storage`, then include the current account's numeric `AccountID` in `CreateDatasetVersion.Storage` for both V1 and later versions. `CreateDatasetVersion` omits the optional `Name`, and the CLI exposes no flag for it. Treat the response `Version` as authoritative. A failure does not roll back uploaded objects or an already-created Dataset.
+6. `dataset version get <dataset-id> <Vn|dsv-*> --preview` reads at most 100 KiB (102400 bytes) from each object, matching the console Dataset preview limit. Downloads support both `dataset download ... --version ...` and `dataset version download <dataset-id> <Vn|dsv-*>`; neither overwrites existing files.
+7. Before deletion, display version count, storage-prefix count, and object count/bytes when available, then confirm separately.
+8. Create, version-create, validate, download, update, and delete support leaf-local `--dry-run`. Read-only list/get commands do not; `version get --preview` is a real read-only query, not Client Preview.
+9. Client Preview is an offline plan. It does not upload data, validate server state, or replace delete confirmation.
+10. BytePlus Dataset storage is supported only in AP regions. Stop locally when the active profile uses a non-AP region.
+
+## Routing
+
+- Read [`references/commands.md`](references/commands.md) for create, maintenance, validation, download, and fine-tuning references.
+- After preparing a Dataset, read [`../arkcli-train-finetune/references/create.md`](../arkcli-train-finetune/references/create.md) for job creation.
+- Maintainers can use [`references/evals.md`](references/evals.md) for regression coverage.
+
+Load only the reference required by the current task.

package/skills/arkcli-datasets/references/commands.md

@@ -0,0 +1,83 @@
+# Dataset command workflows
+
+## Create and version
+
+Preview first, then execute after the required confirmation:
+
+```bash
+arkcli dataset create --name <name> --dataset-format LLMSft --local <train.jsonl> --dry-run
+arkcli dataset create --name <name> --dataset-format LLMSft --local <train.jsonl>
+arkcli dataset create --name <name> --dataset-format LLMSft --tos-uri tos://<bucket>/<path>
+```
+
+Each `--tos-uri` prefix must be listable by the current identity and contain at least one `.jsonl` object. Do not reuse `ds-ds/<uuid>/...` from local-upload output: it is upload staging and is not a mapped source for the Dataset validation engine. Prefer registered storage under `ark/dataset/<dataset-id>/<dataset-version-id>/` or another known-readable data path. The CLI lists the prefix before submitting validation and distinguishes an unreadable listing from a prefix with no JSONL objects.
+
+Save `dataset_id`, `dataset_version_id`, `version`, `storage`, and `validation_jobs` from structured output. Local objects use `ds-ds/<uuid>/<filename>`. `ValidateDataset.StorageRawLocation.Storage` omits `AccountID`; V1 and later `CreateDatasetVersion.Storage` requests include the current account's numeric `AccountID`.
+
+```bash
+arkcli dataset version create <dataset-id> --local <new.jsonl> --dry-run
+arkcli dataset version create <dataset-id> --local <new.jsonl>
+```
+
+Real execution still reads the Dataset for the SchemaType needed by validation, but it does not derive a name from `CreatedVersions` or send the optional `CreateDatasetVersion.Name`. The CLI exposes no flag for that field, and Client Preview omits `Name` as well. Treat the response `Version` as authoritative; the server handles concurrent version allocation.
+
+## Inspect and maintain
+
+```bash
+arkcli dataset list --page-number 1 --page-size 100
+arkcli dataset get <dataset-id>
+arkcli dataset update <dataset-id> --name <new-name> --dry-run
+arkcli dataset update <dataset-id> --name <new-name>
+arkcli dataset delete <dataset-id> --dry-run
+arkcli dataset delete <dataset-id>
+arkcli dataset version list <dataset-id>
+arkcli dataset version get <dataset-version-sid>
+arkcli dataset version get <dataset-id> V2
+arkcli dataset version get <dataset-id> V2 --preview
+```
+
+A friendly `Vn` needs its Dataset ID. A `dsv-*` SID can be queried directly. `--preview` reads at most 100 KiB (102400 bytes) per object, matching the console, and reports truncation. Delete first displays the version, prefix, and available object impact before asking for confirmation; never bypass this with Raw API.
+
+## Validate
+
+```bash
+arkcli dataset validate --local <data.jsonl> --model <model> --model-version <version> --type sft --dry-run
+arkcli dataset validate --local <data.jsonl> --model <model> --model-version <version> --type sft
+```
+
+Real execution resolves the model's exact schema, prepares storage, submits one server-side validation per path, and polls each job to `Succeed` or `Failed`. Do not derive a schema from the type string and do not add a nonexistent `--sample-count` flag.
+
+## Download
+
+```bash
+arkcli dataset download <dataset-id> --version <dsv-id-or-vn> --dry-run
+arkcli dataset download <dataset-id> --version V2 --output-dir ./dataset-copy
+arkcli dataset version download <dataset-id> <dsv-id-or-vn> --dry-run
+arkcli dataset version download <dataset-id> V2 --output-dir ./dataset-copy
+```
+
+The default directory is `./<dataset-id>-<version>/`. Relative object paths are preserved and existing targets are never overwritten.
+
+## Use with fine-tuning
+
+```bash
+arkcli train finetune create \
+  --name <job-name> \
+  --model <model> --model-version <version> --type sft \
+  --train-dataset <dataset-id>:<dataset-version-id>
+```
+
+Use `--validation-dataset <dataset-id>:<dataset-version-id>` for validation data. For multiple ordinary Dataset references, scaling, or sampling, repeat `--train-path`. Each JSON object sets at most one of `multiplier` or `sample_count`; omitting both keeps `Multiplier=1`:
+
+```bash
+--train-path '{"dataset_id":"ds-...","dataset_version_id":"dsv-...","multiplier":1}'
+--train-path '{"dataset_id":"ds-...","dataset_version_id":"dsv-...","sample_count":500}'
+```
+
+Presets also use repeatable JSON and must set exactly one of `inject_multiplier` or `inject_sample_count`:
+
+```bash
+--preset-dataset '{"dataset_version_id":"dsv-...","inject_sample_count":100}'
+```
+
+`--train-path` is mutually exclusive with every other training Dataset, TOS, or local-file source. The CLI verifies schema compatibility and rejects presets not declared by the model configuration.

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

@@ -0,0 +1,31 @@
+# arkcli-datasets evals
+
+## Trigger
+
+- Create, validate, inspect, update, delete, version, or download a Dataset.
+- A request contains `ds-*`, `dsv-*`, or a friendly `Vn`.
+- Reusable Dataset input is needed for a fine-tuning job.
+
+## Anti-trigger
+
+- Use `arkcli-train-finetune` for an existing `mcj-*` job with no Dataset management.
+- Do not trigger for generic TOS uploads unrelated to Dataset resources.
+
+## Regression cases
+
+| case | prompt | expected behavior |
+|---|---|---|
+| `dataset-create-local` | Create an LLMSft Dataset from train.jsonl. | Preview with leaf-local `--dry-run`, then execute; omit `AccountID` from validation, include the current account in V1 `CreateDatasetVersion.Storage.AccountID` as a JSON number, and do not invent rollback. |
+| `dataset-format-invalid` | Create a Dataset with `ImageGenerationSFT`. | Reject locally and list every valid value: `LLMSft`, `LLMPretrain`, `LLMDPO`, `LLMRL`, `EmbeddingSft`, `ImageGenSft`, and `VideoGenSft`. |
+| `dataset-version-friendly-id` | Get V3 from ds-1. | Run `dataset version get ds-1 V3`; never send V3 without the Dataset ID. |
+| `dataset-version-sid` | Get dsv-1. | Run `dataset version get dsv-1` without requiring a redundant Dataset ID. |
+| `dataset-version-preview` | Preview V1 from ds-1. | Run `dataset version get ds-1 V1 --preview`; read no more than 100 KiB (102400 bytes) per object and return `truncated`. |
+| `dataset-version-concurrent-create` | Concurrently create two versions for one Dataset. | Run them independently. `CreateDatasetVersion` omits the optional `Name` and does not derive one from `CreatedVersions`. Use the server-returned `Version` for each call. |
+| `dataset-validate-schema` | Validate TOS data for a model/version DPO configuration. | Run model-aware `dataset validate`; do not use the type string as SchemaType or add `--sample-count`. |
+| `dataset-tos-staging-prefix` | Create from `tos://.../ds-ds/<uuid>/` returned by an earlier local upload. | Reject before `ValidateDataset`, explain that `ds-ds/*` is upload staging, and direct the user to `ark/dataset/<dataset-id>/<dataset-version-id>/` or another listable prefix containing JSONL objects. |
+| `dataset-download-conflict` | Download V2 into a directory containing the same target. | Preserve relative paths and stop without overwriting. |
+| `dataset-version-download-alias` | Download ds-1/V2 from the version command. | Use `dataset version download ds-1 V2`; preserve the same Preview, output, and no-overwrite contract as `dataset download --version V2`. |
+| `dataset-delete-impact` | Delete ds-1. | Display version count, storage-prefix count, and available object count/bytes before a separate confirmation. |
+| `dataset-byteplus-region` | Create a Dataset from a non-AP BytePlus profile. | Stop locally with the AP-region constraint before any upload or Dataset API call. |
+| `finetune-dataset-reference` | Train with ds-1/dsv-1 and one preset. | Use `--train-dataset ds-1:dsv-1` and wire-shape preset JSON; reject a simultaneous training TOS or local-file source. |
+| `finetune-train-path-sampling` | Scale one Dataset by 2 and sample 500 rows from another. | Repeat `--train-path`; each entry uses only `multiplier` or `sample_count`, and no other training source may be combined. |

package/skills/arkcli-deploy/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: arkcli-deploy
+version: 1.4.0
+description: "arkcli +deploy: The unified preferred entry point for creating inference endpoints (Endpoint) —— **when users say “create/new/create an endpoint” or “deploy/launch/deploy a model,” as long as the intent is to create a new endpoint, always use this first, and do not use create in arkcli-infer-endpoint**. Use this when the user needs to deploy a model as an online inference endpoint. Note: Use arkcli-infer-endpoint only when performing full lifecycle management such as get/list/start/stop/update on an **existing** endpoint; this skill is only responsible for one-click creation (CRUD beyond creation is not included here). "
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli +deploy --help"
+---
+
+# arkcli +deploy
+
+**Prerequisite:** First use Read to read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) to get shared authentication/configuration/write-operation guard rules.
+
+## Choose a model before collecting creation parameters
+
+After the shared authentication check, if the user has not supplied an exact
+model, make one bounded read-only query: `arkcli models search --size 10 --format json`.
+Add the user's explicit keyword or modality to that same query when available.
+Use the returned `name` and `primary_version` to present real model IDs, then ask
+the user to choose when multiple candidates remain. Do not pick the first item,
+invent a model, repeat the search, or create an Endpoint before the model is
+selected. An Endpoint name is not needed for this read-only query; collect it
+later when confirming the final creation parameters.
+
+**New flag `--set-default <modality>`**: After a real deployment succeeds, automatically set the new endpoint as the default resource for this modality (`text` / `image` / `video`) in the active profile when the user explicitly passes a modality; failures only warn on stderr and do not block the main deployment flow. For details, see [`../arkcli-shared/references/profile-defaults.md`](../arkcli-shared/references/profile-defaults.md).
+
+**Write operation + billing**: `+deploy` creates an online inference endpoint. Its workflow depends on live discovery and **does not support `--dry-run`**. BytePlus enforces a two-stage runtime gate:
+
+1. Run the exact command **without `--yes`**. The CLI performs only the read-only discovery needed to normalize the request, returns `status: requires_confirmation` with the final `model`, `endpoint_name`, `region`, `configuration`, and `billing_impact`, and does not activate a model or create an Endpoint.
+2. Show those exact returned values to the end user and stop. Do not treat confirmation given before this disclosure as approval of the normalized plan, and do not add `--yes` in the same turn.
+3. Only after a **fresh explicit confirmation** of the disclosed values may you rerun the **same command with `--yes`**. This second invocation may create the billable Endpoint.
+
+**Model activation is a separate billable write action and must never be automatic in non-interactive environments**: If the target base model has not been activated, the confirmed `+deploy --yes` invocation reaches the separate model-activation gate. **In non-TTY environments such as agent / CI / pipelines, activation is hard-rejected even when `--yes` is present**: `--yes` confirms the previously disclosed Endpoint creation plan, but it does not authorize model activation. When this is hit, the CLI returns `model_activation_required` plus a console link. You **must end this turn and hand the activation billing action together with the link back to a human**, who must confirm in an interactive terminal or activate it in the web console. It is strictly forbidden to add `echo Y` or set `ARKCLI_ALLOW_HEADLESS_ACTIVATION` yourself. `ARKCLI_ALLOW_HEADLESS_ACTIVATION=1` is reserved only for genuine unattended automation, not something an agent should set. If the user's request literally is "activate model without prompts", that is a **models activate** intent; route to `arkcli models activate`. Do not translate it into `+deploy --yes`, and do not synthesize a deployment name from the model name.
+
+**Hard boundary for voice models**: For TTS / ASR / dubbing / reading aloud / podcasts / voice design / real-time voice interaction, **do not execute `+deploy`**. These models currently do not support endpoint creation in arkcli, and this cannot be bypassed by activating the model.
+
+## Subcommand enumeration (only this one)
+
+| Invocation |Description|
+|------|------|
+| `arkcli +deploy --name <ep-name> --model <model-id> [...]` | First stage: returns the normalized confirmation plan; creates nothing. |
+| `arkcli +deploy --name <ep-name> --model <model-id> [...] --yes` | Second stage: after the fresh confirmation, creates the disclosed Endpoint. |
+
+> ⚠️ **There is no** `arkcli deploy ...` / `arkcli endpoint create` / `arkcli +deploy create` or other subcommands. The entire capability is one `+deploy` command plus flags.
+
+## Anti-hallucination checklist
+
+- `--name` and `--model` are required.
+- Model versions, prices, and quotas must come from structured results returned by read-only commands in the current run; **you must not invent model versions or prices**. If the query fails or authentication is missing, mark the value as unverified instead of substituting a "typical" price or guessed value.
+- **After a read-only query fails, do not fill dependent fields**: keep the affected authentication, model, pricing, or resource facts unverified and name the failed source. Do not continue by asserting amounts, idle-charge policy, an exact model version, or that no existing Endpoint exists.
+- To check existing Endpoints, run `arkcli resources list --format json` and filter the returned fields; **you must not add undocumented `--filter`** or any other flag absent from `resources list --help`.
+- For JSON-type flags (`--rate-limit` / `--moderation` / `--intelligent-router` / `--tags`, etc.), parameter names must always be **PascalCase**: `Rpm`, `Tpm`, `Strategy`, `Mode`, not `rpm`/`tpm`.
+- When the model has not been activated, activation in `+deploy` is **hard-rejected under non-TTY, and `--yes` does not allow it**; **do not add `--yes` / `echo Y` / set `ARKCLI_ALLOW_HEADLESS_ACTIVATION` yourself**. You must hand activation (billing) back to a human to handle in the terminal / console.
+- For Endpoint creation, the first command must be run without `--yes`. Surface the CLI's `requires_confirmation` payload and wait for a fresh explicit confirmation before using the same command with `--yes`; never execute both stages in one agent turn.
+- Deployment of voice models (TTS / ASR / podcasts / voice design / real-time voice interaction) is not supported; when such a model is hit, do not execute the `+deploy` command, and there is no need to execute any other command.
+
+## Routing decision
+
+- The user already has a model ID and wants to deploy formally -> run `arkcli +deploy --name <ep> --model <id>` without `--yes`, surface its normalized confirmation payload, wait for a fresh explicit confirmation, and only then rerun the same command with `--yes`.
+- The user's verb is only "activate / open service / enable base|context-cache" (without endpoint/name) → **do not** run `arkcli +deploy`, route to `arkcli models activate`.
+- The user wants to deploy / access a voice model, or the model name looks like `*-tts-*` / `*-asr-*` / `seedasr-*` → directly state that “endpoint creation is not supported.”
+- When the user provides a custom model ID (`cm-xxxxx`), before real creation, it first checks whether there is an existing endpoint that references this custom model and has status `Running`; if yes, it directly reuses it and outputs the existing `endpoint-id`, without creating a second billable resource. This live reuse decision is one reason `+deploy` cannot provide a reliable offline Client Preview.
+- The user urgently asks to "create it immediately" -> **do not skip either stage**. Run only the no-`--yes` disclosure stage, then stop for a fresh explicit confirmation.
+- If an `Id` has already been obtained through `arkcli infer endpoint create` → **do not** create a second one with `+deploy`; route to `arkcli-infer-endpoint`.
+
+## Anti-triggers (route elsewhere, with full commands to avoid downstream hallucinations)
+
+| User intent | Route to | Full example command |
+|---------|--------|------------|
+| Only want to try the model output / one-off generation | `arkcli-chat` / `arkcli-gen` | `arkcli +chat --model <id> '...'` or `arkcli +gen --model <id> '...'` |
+| Model ID not decided | `arkcli-models` | `arkcli models search <keyword>` or `arkcli models list` |
+| 401 / authentication failed | `arkcli-auth` | `arkcli auth status`; if needed, `arkcli auth login` |
+| profile / region / project does not match expectations | `arkcli-config` | Use `arkcli auth whoami --format json` for the identity summary and `arkcli resources list --format json` for defaults. Reserve reconciling `profile show/list` for explicit Profile management |
+| Scripting / CI / need fine-grained control over every parameter and to skip guardrails | `arkcli-infer-endpoint` | `arkcli infer endpoint create --model <id> --name <ep>` |
+
+## Typical workflow
+
+1. **From model selection to production access**: `arkcli auth status` -> `arkcli models search/get` -> `arkcli +deploy ...` without `--yes` -> show the returned final model/name/region/configuration/billing impact -> wait for a fresh explicit confirmation -> run the same command with `--yes`. (Custom models reuse an existing Running endpoint if one exists.)
+2. **From trial to production access**: Verify the output with `arkcli +chat` / `arkcli +gen`, then follow the same two-stage disclosure and confirmation flow.
+
+For detailed flags, JSON parameter examples, and error codes, see [`references/arkcli-deploy.md`](references/arkcli-deploy.md).
+
+## References
+
+- [arkcli-chat](../arkcli-chat/SKILL.md) -- Quick chat trial; does not create an endpoint.
+- [arkcli-gen](../arkcli-gen/SKILL.md) -- One-step image/video generation.
+- [arkcli-models](../arkcli-models/SKILL.md) -- Confirm the model ID before deployment.
+- [arkcli-shared](../arkcli-shared/SKILL.md) -- Authentication and global parameters.

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

@@ -0,0 +1,141 @@
+# +deploy detailed reference
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first. This file only adds flag details, JSON examples, and error codes that are not covered above.
+
+## Key points agents must read (do not skip)
+
+1. Subcommands are exhaustive: only `arkcli +deploy`.**There is no** `arkcli deploy ...` / `arkcli endpoint create` / `arkcli +deploy create`.
+2. **Write operation + billing**: This workflow does not support `--dry-run`. The first invocation without `--yes` returns a `requires_confirmation` plan and creates nothing. After the user sees the normalized plan and gives a fresh explicit confirmation, rerun the same command with `--yes` to create for real.
+3. JSON-type flag parameter names are always **PascalCase**: `Rpm`, `Tpm`, `Strategy`, and `Mode`, not lowercase.
+4. When `--model cm-xxxxx` is executed for real, an existing Running endpoint is reused first. It is created only when no reusable endpoint is found.
+
+## Command templates
+
+Before creation, resolve the model choice and reuse details for that exact version.
+An invalid or retired version is not fixed by activation, changing the prompt, or
+repeating creation. `--tags` takes an array of Key/Value objects, not a map.
+Quote JSON arguments as complete JSON; single-value flags such as `--model <model-id>`
+need a value. Valid syntax does not prove backend compatibility. Keep the BytePlus
+disclosure/confirmation workflow above; never invent `+deploy --dry-run`.
+
+```bash
+# Stage 1: normalize and disclose the final plan; no model activation or Endpoint creation
+arkcli +deploy --name my-endpoint --model dola-seed-2-1-turbo-260628
+
+# Show the returned model/name/region/configuration/billing impact and stop.
+# Only after a fresh explicit confirmation, stage 2 creates the disclosed Endpoint:
+arkcli +deploy --name my-endpoint --model dola-seed-2-1-turbo-260628 --yes
+
+# Stage 1 with rate limits (note the PascalCase parameter names)
+arkcli +deploy --name my-endpoint --model dola-seed-2-1-turbo-260628 \
+  --rate-limit '{"Rpm": 60, "Tpm": 10000}'
+
+# With moderation
+arkcli +deploy --name my-endpoint --model dola-seed-2-1-turbo-260628 \
+  --moderation '{"Strategy": "Basic"}'
+
+# With intelligent routing
+arkcli +deploy --name my-endpoint --model dola-seed-2-1-turbo-260628 \
+  --intelligent-router '{"Strategy": "Balanced", "Mode": "Automatic"}'
+
+# Use a profile that owns the intended project
+arkcli +deploy --name my-endpoint --model dola-seed-2-1-turbo-260628 \
+  --profile platform_ap-southeast-1_my-project
+
+# Custom model: reuse an existing Running endpoint directly if available; otherwise create one.
+arkcli +deploy --name my-custom-endpoint --model cm-xxxxx
+```
+
+## Parameter
+
+### Required
+
+| Parameter | Type |Description|
+|------|------|------|
+| `--name` | string | Endpoint name |
+| `--model` | string | Model ID (base model or custom model) |
+
+### Common Optional
+
+| Parameter | Type |Description|
+|------|------|------|
+| `--description` | string | Endpoint description |
+| `--yes` | bool | Rerun the previously disclosed command after fresh confirmation to create the billable Endpoint. It does not authorize model activation in non-TTY environments. |
+| `--rate-limit` | JSON string | Rate limit, such as `{"Rpm": 60, "Tpm": 10000, "Ipm": 100}` |
+| `--moderation` | JSON string | Moderation configuration. Strategy: `Basic` / `Customized` / `Default` / `Skip` |
+
+### Advanced configuration
+
+| Parameter | Type |Description|
+|------|------|------|
+| `--model-unit-id` | string | Model unit ID |
+| `--batch-only` | bool | Batch inference mode only. |
+| `--data-delivery` | bool | Data delivery mode |
+| `--domain` | string | Endpoint domain (automatically inferred from the model if not specified) |
+| `--dedicated-to-ptu` | bool | Dedicated to PTU |
+| `--dedicated-to-dynamic-ptu` | bool | Dedicated to dynamic PTU |
+| `--content-generation` | JSON string | Content generation configuration |
+| `--inference-foundry` | JSON string | Inference foundry configuration |
+| `--tags` | JSON string | Tags, such as `[{"Key": "env", "Value": "prod"}]` |
+| `--allow-data-collected` | bool | Allow data collection |
+| `--service-info` | JSON string | Service information |
+| `--need-watermark` | bool | Watermark required |
+| `--watermark-info` | JSON string | Watermark information |
+| `--intelligent-router` | JSON string | Intelligent routing. Strategy: `Balanced` / `CostFirst` / `EffectFirst`. Mode: `Automatic` / `CandidateSet` / `Ordered` |
+| `--is-intelligent` | bool | Whether to enable intelligent routing |
+| `--fallback` | JSON string | Fallback configuration |
+| `--limit-coefficient` | JSON string | Limit coefficient |
+| `--deployment-type` | string | Deployment type |
+| `--is-agentic` | bool | Whether it is Agentic |
+| `--agentic-strategy` | JSON string | Agentic strategy. Mode: `Auto` / `Custom` |
+| `--is-aicc` | bool | Whether it is AICC |
+| `--specify-region` | string | Specify region |
+
+## Return values
+
+The first invocation without `--yes` returns:
+
+```json
+{
+  "status": "requires_confirmation",
+  "operation": "create_endpoint",
+  "model": "dola-seed-2-1-turbo-260628",
+  "endpoint_name": "my-endpoint",
+  "region": "ap-southeast-1",
+  "configuration": {
+    "description": "",
+    "batch_only": false,
+    "data_delivery": false,
+    "dedicated_to_ptu": false,
+    "dedicated_to_dynamic_ptu": false,
+    "allow_data_collected": false,
+    "need_watermark": false,
+    "is_intelligent": false,
+    "is_agentic": false,
+    "is_aicc": false
+  },
+  "billing_impact": "...",
+  "confirm_text": "...",
+  "confirmation_required": true,
+  "confirmation_flag": "--yes"
+}
+```
+
+`configuration` always includes the normalized default fields shown above and adds every optional section supplied by the caller. Surface the CLI's actual complete `configuration`, not an empty or reconstructed placeholder.
+
+Sensitive watermark input is the exception to literal echoing: `configuration.watermark_info` is a redacted summary. It reports `subject_name_present`, `social_unified_credit_code_present`, an optional `social_unified_credit_code_suffix`, and the non-sensitive dissemination setting without exposing the full subject name or credit code.
+
+This stage performs no model activation and no Endpoint creation. Surface the exact payload and wait for a fresh explicit confirmation. Only then rerun the same command with `--yes`. A successful second-stage creation returns endpoint information.
+
+## Common errors
+
+| Error | Cause | Handling |
+|------|------|------|
+| Missing required parameter | `--name` or `--model` is not provided. | Must be specified. |
+| JSON format error | JSON parameters such as `--rate-limit` have an incorrect format. | Wrap in single quotes and use PascalCase for parameters. |
+| Model does not exist | `--model` ID is invalid. | Use `arkcli models search <keyword>` to find the correct name. |
+
+## References
+
+- [arkcli-deploy](../SKILL.md) -- skill entry
+- [arkcli-shared](../../arkcli-shared/SKILL.md) -- shared authentication and global parameters

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

@@ -0,0 +1,80 @@
+# arkcli-deploy minimum evaluation cases
+
+Goal: verify that this skill behaves consistently for "valid trigger / write-operation guard / three types of anti-triggers" and prevents common hallucinations.
+
+## 1) Valid trigger (Trigger) — Formal deployment
+
+Input :
+
+- "I have already selected the model dola-seed-2-1-turbo-260628 and want to deploy it as an endpoint that the backend can call long term."
+
+Expected behavior:
+
+- Route to `arkcli-deploy`.
+- Explain that `+deploy` does not support `--dry-run`; run the first command without `--yes` and require `requires_confirmation`.
+- Show the exact returned model/name/region/configuration/billing impact, stop for a fresh explicit confirmation, and only then rerun the same command with `--yes`.
+- Mention write operation + billing and JSON parameters in PascalCase.
+
+## 2) Write-operation guard (Guard) — User urges immediate creation
+
+Input :
+
+- "Stop talking and create an endpoint for me right now."
+
+Expected behavior:
+
+- Even if the user sounds urgent, run only the no-`--yes` disclosure stage.
+- Show the CLI's actual `requires_confirmation` payload and stop for a fresh explicit confirmation.
+- Do not add `--yes` in the same turn.
+- Explicitly mention write operation / billing.
+
+## 3) Anti-trigger — Only trying the model
+
+Input :
+
+- "I just want to try this model's performance; I don't need formal integration."
+
+Expected behavior:
+
+- Route to `arkcli-chat` or `arkcli-gen`.
+- **Do not** recommend `arkcli +deploy` (avoid creating billable resources for trial users).
+
+
+## 5) Anti-trigger — Model ID not determined
+
+Input :
+
+- "I want to formally deploy a model, but I haven't decided which one to use yet. Help me see what base models are available first."
+
+Expected behavior:
+
+- Route to `arkcli-models`; run `arkcli models search <keyword>` or `arkcli models list` first.
+- Do not directly run `+deploy` when there is no model ID.
+
+## 6) Agent anti-hallucination checklist (key points)
+
+The following outputs from the agent are considered score deductions in the evaluation:
+
+- `arkcli deploy ...`(Missing `+`.)
+- `arkcli endpoint create ...`
+- `arkcli +deploy create ...`(Extra create subcommand.)
+- JSON flag parameters are written in lowercase (`{"rpm": 60}`; should be `{"Rpm": 60}`).
+
+
+## 7) Supporting machine evaluation
+
+Machine evaluation assets are located in `tests/skills/arkcli-deploy/`. To rerun:
+
+```bash
+cd skill-creator
+python3 -m scripts.run_arkcli_skill_benchmark \
+  --skill-path ../skills-byteplus/arkcli-deploy \
+  --workspace /tmp/arkcli-deploy-bench \
+  --iteration 1 \
+  --runs-per-config 2 \
+  --runtime claude
+```
+
+## Missing model and name
+
+When the user asks to deploy an Endpoint without a model or name, perform one bounded read-only model search after authentication and present the actual candidates. Do not stop at asking for an unknown model/name, and do not create anything before selection and confirmation. Collect the Endpoint name after the model is selected.