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

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

@@ -0,0 +1,231 @@
+# arkcli-connect evaluations
+
+Use these cases to verify routing, authoritative catalog convergence, explicit
+path isolation, preview behavior, refresh source reporting, command grammar,
+and migration from historical catalog names.
+
+## 1. Trigger: install into detected agents
+
+User request:
+
+> Install the BytePlus Ark CLI Skills into the local AI agents on this machine.
+
+Expected behavior:
+
+- Route to `arkcli-connect`.
+- Start with:
+
+  ```bash
+  arkcli +connect list
+  ```
+
+- Explain that normal installation overwrites every exact current-catalog name,
+  regardless of ownership, digest, or local edits.
+- Explain that names absent from both the current catalog and previous manifest
+  remain untouched.
+- Run `arkcli +connect` after the user accepts the reported targets.
+- Do not invent `arkcli +connect install`.
+
+## 2. Trigger: isolated project installation
+
+User request:
+
+> Install only into this repository's `.claude/skills` directory.
+
+Expected behavior:
+
+```bash
+arkcli +connect --path .claude/skills
+```
+
+- Resolve the relative path from the current working directory.
+- Do not scan or modify global agent directories.
+- Treat `.claude/skills` as the exact target, not the project root.
+- Preserve unrelated user-managed `ark-` and `arkcli-` entries in that target.
+
+## 3. Trigger: list only
+
+User request:
+
+> Which agents are supported and detected? Do not install anything.
+
+Expected behavior:
+
+```bash
+arkcli +connect list
+```
+
+- Stop after listing.
+- Explain that list mode is local, read-only, and unauthenticated.
+- Do not install, purge, or uninstall.
+
+## 4. Guard: uninstall from all detected agents
+
+User request:
+
+> Remove every Ark CLI Skill installed by `+connect`.
+
+Expected behavior:
+
+  ```bash
+  arkcli +connect list
+  ```
+
+- Explain that default removal deletes only unchanged entries recorded in the
+  Ark CLI ownership manifest.
+- Explain that modified managed Skills and unrelated user-managed entries are
+  preserved.
+- Show affected agent paths.
+- Require explicit confirmation before `arkcli +connect uninstall`.
+
+## 5. Guard: uninstall from one directory
+
+User request:
+
+> Remove Ark CLI Skills only from `/workspace/project/.agents/skills`.
+
+Expected behavior:
+
+```bash
+arkcli +connect uninstall \
+  --path /workspace/project/.agents/skills
+```
+
+- Confirm the exact absolute path.
+- Do not scan other agents.
+- Execute only after confirmation; explain that `--dry-run` is unsupported.
+
+## 6. Anti-trigger: authentication failure
+
+User request:
+
+> My BytePlus business command returns 401. Is `+connect` broken?
+
+Expected behavior:
+
+- Route to `arkcli-auth`.
+- Explain that `+connect` performs local filesystem work and does not require
+  authentication.
+- Do not reinstall Skills as an authentication fix.
+
+## 7. Command hallucination checks
+
+The following commands are invalid and any recommendation is a failure:
+
+```text
+arkcli +connect install
+arkcli +connect install --agent <name>
+arkcli +connect setup
+arkcli +connect sync
+arkcli +connect remove
+```
+
+Valid actions are the empty parent action, `list`, and `uninstall`.
+
+## 8. BytePlus refresh
+
+User request:
+
+> Run `+connect --refresh` and confirm that it downloaded the latest remote
+> Skills.
+
+Expected behavior:
+
+- Explain that public BytePlus packages prefer the BytePlus CDN and fall back
+  to the BytePlus GitHub release bundle.
+- Explain that internal BytePlus builds may use the reviewed English bundle
+  embedded in the current binary.
+- Report only the source printed by the CLI: `cdn`, `github`, or `embedded`.
+- Do not report a successful remote download when the CLI reports `embedded`.
+
+## 9. Preserve recognized conflicts
+
+User request:
+
+> Install globally, but preserve external generation Skills that Ark CLI would
+> otherwise treat as routing conflicts.
+
+Expected behavior:
+
+```bash
+arkcli +connect list
+arkcli +connect --keep-conflicting
+```
+
+- Explain that the flag is for detected-agent installation.
+- Do not claim that scoped `--path` installation removes those external
+  conflicts.
+
+## 10. Automatic post-install setup
+
+User request:
+
+> Why did installing the BytePlus Ark CLI package also install Skills?
+
+Expected behavior:
+
+- Explain the interactive post-install `+connect` behavior.
+- Explain that CI and non-interactive installations skip.
+- Mention `ARKCLI_SKIP_POSTINSTALL=1` as the opt-out for future package
+  installation.
+- Explain that post-install uses the same authoritative-catalog transaction and
+  never performs a broad prefix purge.
+- Do not treat automatic connection as login or credential setup.
+
+## 11. Guard: explicit destructive legacy purge
+
+User request:
+
+> Remove every `ark-` and `arkcli-` Skill directory from one legacy target,
+> including entries not installed by Ark CLI.
+
+Expected behavior:
+
+```bash
+arkcli +connect uninstall \
+  --path /confirmed/legacy/skills \
+  --purge-prefix
+```
+
+- State that this deletes user-managed matching directories and symlinks.
+- Restate the exact target and require explicit confirmation.
+- Do not use `--purge-prefix` for normal uninstall or post-install.
+
+## 12. Offline command-surface checks
+
+```bash
+arkcli +connect --help
+arkcli +connect list --help
+arkcli +connect uninstall --help
+arkcli +connect list
+```
+
+Verify that:
+
+- `--path`, `--refresh`, and `--keep-conflicting` appear at the
+  correct command levels;
+- `--purge-prefix` appears only on `uninstall`;
+- empty `--path` is rejected;
+- preview mode performs no writes;
+- only `list` and `uninstall` are subcommands.
+
+## 13. Authoritative catalog convergence
+
+Fixture:
+
+- an ownership manifest owns an `arkcli-managed-agent` directory whose content
+  may have changed locally;
+- an older unowned or modified `arkcli-agent` directory exists;
+- the incoming BytePlus catalog contains `arkcli-agent`.
+
+Expected behavior:
+
+- the transaction succeeds without partial writes;
+- `arkcli-managed-agent` is retired;
+- the current `arkcli-agent` is installed and becomes the only managed agent
+  Skill name;
+- unrelated user-managed `ark-` and `arkcli-` entries remain unchanged.
+
+Repeat the same assertions for BytePlus candidate, integration, and stable
+builds. The install contract must not vary by package channel,
+embedded/CDN/GitHub source, old manifest product, digest, or local edits.

package/skills/arkcli-custommodel/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: arkcli-custommodel
+version: 0.1.0
+description: "Manage BytePlus ModelArk custom models identified by `cm-*`: list, inspect, upload, update, delete, quantize, and prepare deployment. Also use this skill whenever a user asks to chat, invoke, or test inference directly with a `cm-*` ID, so the Endpoint boundary is enforced before any deployment or inference action."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli models custommodel --help"
+---
+
+# arkcli models custommodel
+
+> **BytePlus capability status: pending audit.** This English file is a baseline translation, not proof that the capability is available in BP. Check the capability matrix before execution, and do not perform write operations until support, region, permissions, and dependencies have been confirmed.
+
+**CRITICAL — Before starting, MUST use the Read tool to read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md), which defines authentication gates, configuration troubleshooting, and shared safety rules.**
+**CRITICAL — Before running any `models custommodel` command, use the Read tool to read the corresponding reference document. Never invoke a command without reading its reference first.**
+**CRITICAL — Confirm user intent before any write operation (`upload`, `update`, `delete`, or `quantize`). Before deletion, confirm whether any endpoint still references the model.**
+**CRITICAL — This skill targets BytePlus. Before running control-plane commands, confirm that the active profile, project, and region all belong to the intended BytePlus environment.**
+
+## Guard Checklist and Operating Principles
+
+- Prefer `arkcli models custommodel ...` for custom model requests.
+- Although these are standard CLI-style commands, their implementation entry point remains under `shortcuts/models/`.
+- Fall back to [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md) only when no product command covers the request.
+- Do not use this skill to query the base model catalog. Route those requests to [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md).
+- For write operations and asynchronous jobs, explain the impact, polling method, and next steps. Do not stop after issuing a single command.
+
+## When To Trigger and Supported Scenarios
+
+- Import trained or fine-tuned weights from BytePlus Torch Object Storage (TOS) into the ModelArk model registry.
+- List custom models in the current account, including requests such as "Which custom models do I own?" or "What are their statuses?"
+- Inspect custom model details, artifact types, and active endpoint references.
+- Update a custom model's display name or description.
+- Delete an unused custom model.
+- Quantize a `ready` custom model to prepare it for `+deploy`.
+
+## When NOT To Trigger
+
+- Find platform-provided base models → use `search`, `list`, or `get` from [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md).
+- Invoke a custom model directly for inference → first use `+deploy`, then use `+chat` or `+gen`.
+- Create a fine-tuning job itself → route to [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md).
+- **Register a fine-tuning step (`global_step_N`) as a `cm-` resource** (that is, export a training artifact) → use `arkcli train finetune artifacts list / export` from [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md). **Do not** use this skill's `upload`: `upload` is for a user's own TOS files and calls the `UploadModel` Action, whereas MCJ outputs use `CreateCustomModel`. These are different APIs.
+- Manage an existing endpoint after obtaining its endpoint ID → route to [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md).
+
+## Direct inference boundary for `cm-*`
+
+- A request to chat, invoke, or test inference directly with a `cm-*` ID must still load this skill. Explain that `cm-*` identifies a custom-model resource and cannot be passed directly to `+chat` or `+gen`; inference requires a separate Endpoint.
+- The request alone does not authorize deployment, listing account Endpoints, or inference. Until the user separately asks to continue, do not run `arkcli +deploy`, `arkcli +chat`, `arkcli infer endpoint list`, or an ad hoc `jq` scan.
+- State the boundary and offer the next step only. After explicit authorization to deploy, route to [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md) and follow its confirmation flow.
+
+## Core concepts
+
+- Call resources managed by `arkcli models custommodel ...` **custom models** (`CustomModel`, with IDs such as `cm-xxxxx`). They are separate from the platform-provided base model resources (`FoundationModel`) queried through `search`, `list`, or `get` in [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md).
+- A custom model has one of two sources:
+  - `import` — weights imported from TOS with this skill's `upload` command through the `UploadModel` API.
+  - `customization` — a model produced by a fine-tuning job and exported through `train finetune artifacts export` in [`../arkcli-train-finetune/SKILL.md`](../arkcli-train-finetune/SKILL.md). This path uses the separate OpenAPI Action `CreateCustomModel` and is not interchangeable with `upload`.
+- The lifecycle is `preparation → processing → ready` on success, or `failed`. Export flows also use `exporting` and `exportfailed`.
+- Quantization is a separate flow. First run `available-quantizations <id>` and inspect `supported_inference_types_by_quantization` to predict the inference types supported by each quantization method. Then submit `quantize <id> --quantization <mode>`. The result is an **independent new `cm-xxxxx`**. The source model, quantized model, and deployed endpoint are three different resources; never mix their IDs.
+- A custom model ID (`cm-xxxxx`) is **not** in `<name>-<primary_version>` form and cannot be passed directly to `--model` for `+chat` or `+gen`. First obtain an endpoint through `arkcli +deploy`, then invoke the resulting `ep-xxx`. If the custom model already has a running endpoint, `+deploy` reuses it.
+
+## Quick decisions
+
+- The user asks for "my custom models" → read [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md) and run `arkcli models custommodel list --mine`.
+- The user wants a fuzzy search by name, ID, or base model display name → read [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md) and run `list --search <kw>`.
+- The user has a `cm-xxxxx` and wants its status, details, endpoint references, or artifact types → read [`references/arkcli-custommodel-get.md`](references/arkcli-custommodel-get.md) and use `get`.
+- The user wants to import weights from TOS → read [`references/arkcli-custommodel-upload.md`](references/arkcli-custommodel-upload.md). If the user has a `tos://...` URI, confirm the TOS URI, base model, and name. If no TOS URI is available, guide the user through enabling TOS and uploading the files; do not run `upload` yet.
+- The user wants to rename a model or change its description → read [`references/arkcli-custommodel-update.md`](references/arkcli-custommodel-update.md), confirm the change, and use `update`.
+- The user wants to delete a model → read [`references/arkcli-custommodel-delete.md`](references/arkcli-custommodel-delete.md), inspect `active_endpoints`, and delete only after confirmation.
+- The user wants to quantize a model → first read [`references/arkcli-custommodel-available-quantizations.md`](references/arkcli-custommodel-available-quantizations.md), then read [`references/arkcli-custommodel-quantize.md`](references/arkcli-custommodel-quantize.md).
+
+## List parameter and output contracts
+
+- `custommodel list --sort-order` accepts only lowercase `asc` or `desc`. Treat any other value as a local parameter error; do not call the API or blindly retry with another spelling.
+- With `--format table` or `--format csv`, each `result.items[]` model is one row. Do not interpret the paginated response root or the `result` map as a model record. Use JSON/YAML when complete pagination metadata is required.
+
+## Agent execution order
+
+1. If authentication state is uncertain, run `arkcli auth status` first.
+2. For "my custom models," run `custommodel list --mine` directly. **Do not apply the shared skill's default Tags filter** because the custom model service supports `--mine` natively.
+3. Before upload, require all three fields: `--name`, `--base-model <foundation-model-id>`, and `--tos tos://<bucket>/<prefix>`. The server rejects requests missing any of them.
+4. `upload` and `quantize` are asynchronous. After submission, poll with `custommodel get <id>`; **do not repeatedly submit `upload` or `quantize`**.
+5. Before `quantize`, always run `available-quantizations <id>`. Supported quantization methods vary by base model, and the server rejects unsupported values. If the user needs pay-as-you-go by token usage or Model Unit inference, inspect `supported_inference_types_by_quantization` first.
+6. `quantize --dry-run` emits local `preview.v1` and never calls `CreateQuantizedCustomModel`. Its `steps[].payload` describes only real request fields and must not contain a backend `DryRun` field. It is not server validation. Obtain explicit user confirmation before the real quantization request.
+7. `delete`, `update`, and `quantize` are write operations. Restate their impact before execution.
+8. `delete` prompts for [Y/N] confirmation by default. `--yes` skips the local confirmation, while `--dry-run` previews without deleting. Add `--yes` only after the user has explicitly confirmed the deletion target and impact.
+9. `get --transform` is a field allowlist specific to `custommodel get`, not the global GJSON transform expression. Do not use it for nested-path queries.
+
+## Common workflows
+
+### 1. Import a new custom model from TOS
+
+```
+auth status → custommodel upload --name X --base-model <fm-id> --tos tos://b/p
+            → custommodel get <id>  (poll until status=ready)
+            → custommodel get <id> --transform 'artifact_types'  (inspect artifact types)
+```
+
+### 2. Quantize a ready custom model
+
+```
+custommodel get <id>  (confirm status=ready)
+        → custommodel available-quantizations <id>  (inspect supported modes)
+        → custommodel quantize <id> --quantization <mode> --dry-run
+        → obtain user confirmation for the quantization target and impact
+        → custommodel quantize <id> --quantization <mode>
+        → custommodel get <new-id>  (the quantized result is a new cm-xxxxx; poll again)
+```
+
+### 3. Prepare a target for `+deploy`
+
+```
+custommodel list --mine --statuses ready  → select a target cm-xxxxx
+        → +deploy --model cm-xxxxx ...   (reuse a running endpoint if one exists; see ../arkcli-deploy/SKILL.md)
+```
+
+### 4. Remove an unused custom model
+
+```
+custommodel get <id> --transform 'active_endpoints'  (confirm that no endpoint references it)
+        → custommodel delete <id> --dry-run
+        → custommodel delete <id>  (interactive confirmation) or custommodel delete <id> --yes
+```
+
+## Anti-patterns
+
+- Do not use `arkcli models search` or `list` to find custom models. Those commands query only the `FoundationModel` catalog. Use `custommodel list --search <kw>` or `--mine` for imported or fine-tuned custom models.
+- Do not run `quantize` immediately after `upload`. Upload is asynchronous and progresses through `preparation → processing → ready`. Confirm `ready` with `custommodel get <id>`, then run `available-quantizations` followed by `quantize`.
+- Do not pass a mode to `quantize` unless `available-quantizations` returned it. Supported methods vary by base model.
+- Do not treat a successful `quantize --dry-run` response as a created or server-validated model. It is only a local request preview; run the command again without `--dry-run` after confirmation.
+- Do not pass `cm-xxxxx` directly to `--model` for `+chat` or `+gen`. First obtain an endpoint (`ep-xxx`) through `+deploy`; `+deploy` may reuse a running endpoint.
+- Do not add `--yes` merely for automation. Without `--yes`, the CLI prompts for [Y/N] confirmation. Use it only after the user confirms deletion of the target `cm-xxxxx` and understands the endpoint-reference risk.
+- Do not apply the shared Tags client-side filter to a request for "my" models. `custommodel list --mine` is a more accurate and efficient native server-side filter.
+- Do not poll status by calling `get` too frequently. Use an interval of at least 10 seconds to avoid rate limiting.
+
+## Command summary
+
+| Command | Description |
+|---|---|
+| `arkcli models custommodel list` | Paginate and filter on multiple dimensions |
+| `arkcli models custommodel get <id>` | Retrieve details or poll status |
+| `arkcli models custommodel upload` | Import from TOS asynchronously |
+| `arkcli models custommodel update <id>` | Update the name or description |
+| `arkcli models custommodel delete <id> [--yes] [--dry-run]` | Delete irreversibly; prompts by default, `--yes` skips confirmation, and `--dry-run` previews |
+| `arkcli models custommodel available-quantizations <id>` | Query available quantization methods before `quantize` |
+| `arkcli models custommodel quantize <id> --quantization <mode> [--dry-run]` | Quantize asynchronously; `--dry-run` previews locally without calling the backend |
+
+## Common fallbacks
+
+- Authentication failure → use [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+- The profile or region appears incorrect → use [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md).
+- The user wants a base model rather than a custom model → use [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md).
+- The user wants to deploy a custom model → use [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md).
+- A new capability is genuinely not covered by a product command → use [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md).
+
+## References
+
+- [`references/arkcli-custommodel-list.md`](references/arkcli-custommodel-list.md)
+- [`references/arkcli-custommodel-get.md`](references/arkcli-custommodel-get.md)
+- [`references/arkcli-custommodel-upload.md`](references/arkcli-custommodel-upload.md)
+- [`references/arkcli-custommodel-update.md`](references/arkcli-custommodel-update.md)
+- [`references/arkcli-custommodel-delete.md`](references/arkcli-custommodel-delete.md)
+- [`references/arkcli-custommodel-available-quantizations.md`](references/arkcli-custommodel-available-quantizations.md)
+- [`references/arkcli-custommodel-quantize.md`](references/arkcli-custommodel-quantize.md)
+- [`references/evals.md`](references/evals.md)
+- [arkcli-models](../arkcli-models/SKILL.md) — query base models; these are separate resources from custom models
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) — deploy a ready custom model as an endpoint
+- [arkcli-shared](../arkcli-shared/SKILL.md) — authentication, global flags, and safety rules

package/skills/arkcli-custommodel/references/arkcli-custommodel-available-quantizations.md

@@ -0,0 +1,29 @@
+# arkcli models custommodel available-quantizations
+
+Query available quantization methods. Always run this command before `quantize`.
+
+## Usage
+
+```bash
+arkcli models custommodel available-quantizations <id>
+```
+
+## Flags
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `<id>` | Yes | string | Custom model ID in `cm-xxxxx` form |
+
+## Output
+
+Returns JSON containing:
+
+- `quantizations`: available quantization methods, such as `["W8A8"]`; the exact set varies by base model.
+- `supported_inference_types_by_quantization`: a dictionary that predicts supported inference types before quantization. Each key is a quantization method, and its value lists the supported inference types, such as `{"W8A8":["token","model_unit"]}`.
+
+**Notes:**
+
+- This is a read-only command and can be run without confirmation.
+- Do not infer support from the available methods of another base model.
+- An empty list means the base model does not support quantization. Continue deploying the original model instead.
+- `supported_inference_types_by_quantization` comes from ModelArk `QuantSupportedMethods` metadata. If the backend omits the field, the dictionary may be empty. After creation, use `custommodel get <new-id> --transform artifact_types` as the final source of truth for supported inference types.

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

@@ -0,0 +1,37 @@
+# arkcli models custommodel delete
+
+Delete a custom model. This operation is destructive and irreversible.
+
+## Usage
+
+```bash
+arkcli models custommodel delete <id> [--yes] [--dry-run]
+```
+
+## Examples
+
+```bash
+# Preview the deletion request without deleting
+arkcli models custommodel delete cm-xxxxx --dry-run
+
+# Delete interactively with a [Y/N] confirmation prompt
+arkcli models custommodel delete cm-xxxxx
+
+# Delete non-interactively and skip the local confirmation prompt
+arkcli models custommodel delete cm-xxxxx --yes
+```
+
+## Flags
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `<id>` | Yes | string | Custom model ID in `cm-xxxxx` form |
+| `--yes` | No | bool | Skip the interactive [Y/N] confirmation |
+| `--dry-run` | No | bool | Command-local Client Preview; makes no request, deletes nothing, and skips confirmation |
+
+**Notes:**
+
+- Deletion is **irreversible**. The same ID will not be reused, and references from deployed endpoints will become invalid immediately.
+- Before deletion, run `custommodel get <id> --transform id,name,active_endpoints`, list all references, and restate the impact to the user.
+- Add `--yes` only after the user has explicitly confirmed deletion of the target `cm-xxxxx` and understands that a non-empty `active_endpoints` value means the operation will break an inference path.
+- If the user has not explicitly asked for deletion and only asks whether deletion is possible or requests a risk check, never execute the deletion.

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

@@ -0,0 +1,45 @@
+# arkcli models custommodel get
+
+Retrieve details or poll model status.
+
+## Usage
+
+```bash
+arkcli models custommodel get <id> [flags]
+```
+
+## Examples
+
+```bash
+# Retrieve full details
+arkcli models custommodel get cm-xxxxx
+
+# Retrieve only key fields to avoid a large JSON response
+arkcli models custommodel get cm-xxxxx --transform id,name,active_endpoints,artifact_types
+
+# Retrieve only status for polling
+arkcli models custommodel get cm-xxxxx --transform status
+```
+
+## Flags
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `<id>` | Yes | string | Custom model ID in `cm-xxxxx` form |
+| `--transform` | No | string list | Field allowlist. Accepts comma-separated values such as `id,name` or repeated flags. Select `CustomModel` fields such as `id`, `name`, `status`, or `foundation_model`, plus `active_endpoints` or `artifact_types`. This command's `--transform` selects a field subset; it is **not** the global GJSON expression. |
+
+## Understanding `--transform`
+
+The `--transform` flag on `custommodel get` is a command-specific field allowlist that reduces extra queries and response size. It is not the root command's GJSON-style `--transform` and does not support nested expressions such as `items.0.id`.
+
+Common selections:
+
+- `id,name,status,foundation_model`: retrieve basic identity and status fields without extra API calls.
+- `artifact_types`: query deployable artifacts and return `endpoint_supported_methods` and `supported_inference_types`.
+- `active_endpoints`: query endpoints that currently reference the custom model.
+
+## Output
+
+Returns JSON details. Common fields include `id`, `name`, `description`, `status`, `base_model`, `customization_type`, `source`, `active_endpoints` (the endpoints currently referencing the model), `artifact_types` (available artifact types), `create_time`, and `update_time`.
+
+**Note:** Before deletion, check `--transform active_endpoints`. A non-empty result means that deleting the model will break an existing inference path.

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

@@ -0,0 +1,65 @@
+# arkcli models custommodel list
+
+List custom models with pagination and multidimensional filters.
+
+## Usage
+
+```bash
+arkcli models custommodel list [flags]
+```
+
+## Examples
+
+```bash
+# List all custom models with default pagination
+arkcli models custommodel list
+
+# List only custom models created by the current SSO sub-user
+arkcli models custommodel list --mine
+
+# Filter by status; use comma-separated values or repeat the flag
+arkcli models custommodel list --statuses ready
+arkcli models custommodel list --statuses ready,processing
+
+# Filter by customization type
+arkcli models custommodel list --customization-types lora,sft
+
+# Filter by base model name or ID
+arkcli models custommodel list --base-models <byteplus-base-model-name>
+arkcli models custommodel list --base-model-ids fm-xxxxx
+
+# Fuzzy-search name, ID, or base model display name
+arkcli models custommodel list --search my-finetune
+
+# Paginate and sort
+arkcli models custommodel list --page 1,20 --sort-by CreateTime --sort-order desc
+
+# Paginate automatically
+arkcli models custommodel list --mine --page-all --page-delay 500
+```
+
+## Flags
+
+> Every multivalue filter of type `string list` accepts either comma-separated values (`--statuses ready,processing`) or repeated flags (`--statuses ready --statuses processing`). Both forms produce the same result.
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `--mine` | No | bool | Return only custom models created by the current SSO sub-user |
+| `--statuses` | No | string list | `preparation` / `processing` / `ready` / `failed` / `exporting` / `exportfailed` |
+| `--customization-types` | No | string list | `lora` / `sft` / `dpolora` / `dpo` / `grpolora` / `grpo` / `ppo` / `opdlora` / `opd` / `pretrain` |
+| `--supported-customization-types` | No | string list | Filter by customization types supported by the underlying base model |
+| `--base-models` | No | string list | Filter by base model name |
+| `--base-model-ids` | No | string list | Filter by base model ID |
+| `--sources` | No | string list | `import` / `customization` |
+| `--source-jobs` | No | string list | Filter by fine-tuning job ID |
+| `--search` | No | string | Fuzzy-search name, ID, or base model display name |
+| `--page` | No | string | Pagination expression in `<number,size>` form, such as `1,10`; spaces are not accepted |
+| `--sort-by` | No | string | Sort field; defaults to `CreateTime` |
+| `--sort-order` | No | string | Sort direction; only `asc` / `desc` are accepted; defaults to `desc` |
+
+## Output
+
+- `--format json` and `--format yaml` preserve the complete execution and pagination response.
+- `--format table` and `--format csv` expand the list to one row per `result.items[]` entry instead of rendering the whole `result` as a map.
+
+Each item commonly includes `id` (`cm-xxxxx`), `name`, `status`, `foundation_model`, `customization_type`, `source_type`, `create_time`, and `update_time`. Nested table cells such as `foundation_model` use compact JSON.

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

@@ -0,0 +1,59 @@
+# arkcli models custommodel quantize
+
+Quantize a custom model asynchronously.
+
+## Usage
+
+```bash
+arkcli models custommodel quantize <id> --quantization <mode> [flags]
+```
+
+## Examples
+
+```bash
+# Standard usage: first run available-quantizations to validate the mode and inspect the inference types it is expected to support
+arkcli models custommodel quantize cm-xxxxx --quantization int8
+
+# Client preview: inspect the request without creating a quantized model
+arkcli models custommodel quantize cm-xxxxx \
+  --quantization int8 \
+  --dry-run
+
+# Include a description
+arkcli models custommodel quantize cm-xxxxx \
+  --quantization int8 \
+  --description "int8 quantized for low-latency inference"
+```
+
+## Flags
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `<id>` | Yes | string | Source custom model ID; the model must have `status=ready` |
+| `--quantization` | Yes | string | Quantization method. **Select a value returned by `available-quantizations <id>`.** |
+| `--description` | No | string | Description for the quantized model, up to 300 characters |
+| `--dry-run` | No | bool | Command-local Client Preview that emits `preview.v1` without a network request |
+
+## Output
+
+Returns JSON containing a newly created `cm-yyyyy`, which differs from the source ID, and its initial status.
+
+**Notes:**
+
+- `--dry-run` never calls `CreateQuantizedCustomModel`, and `preview.v1.effects.network` must be `blocked`. The locally built `steps[].payload` must not contain a backend `DryRun` field; this is not server-side validation.
+- This is an **asynchronous** job. A successful response means only that the request was accepted. Poll the new ID with `custommodel get <new-id>` until it reaches `ready`.
+- The quantized result is an **independent new custom model**. The source remains unchanged, so both `cm-xxxxx` resources exist in the account.
+- Quantization can materially affect inference performance and accuracy. Before production use, consider deploying the source and quantized models to separate endpoints for comparison.
+- To determine whether a quantization method is expected to support pay-as-you-go by token usage or Model Unit inference, inspect `supported_inference_types_by_quantization` from `available-quantizations` before creation.
+
+## Resource relationships
+
+The quantization flow contains three resource types. Never mix their IDs.
+
+| Resource | ID form | Description |
+|---|---|---|
+| Source custom model | `cm-xxxxx` | Input to `quantize`; remains unchanged |
+| Quantized model | New `cm-yyyyy` | New model returned by `quantize`; continue polling it with `get` until `ready` |
+| Inference endpoint | `ep-xxxxx` | Created through `+deploy` from a ready source or quantized model; `+chat` and `+gen` should use an endpoint or invocable model ID |
+
+Before creation, use `supported_inference_types_by_quantization` from `available-quantizations` to predict supported inference types. After creation, use `supported_inference_types` from `custommodel get <new-id> --transform artifact_types` for final confirmation.