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

package/skills/arkcli-train-finetune/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: arkcli-train-finetune
+description: Create, query, and manage model fine-tuning jobs in BytePlus ModelArk with ArkCLI. Use this skill for every request that names a fine-tuning job ID (`mcj-*`), including not-found diagnosis, logs, rollout trajectory, status, or lifecycle operations. Also use it for fine-tuning capability, pricing, configuration, resource-group matching, job creation, metrics, artifact export, and deployment handoff. This skill does not manage datasets.
+---
+
+# ArkCLI Fine-Tuning for BytePlus ModelArk
+
+First read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) and follow its authentication, output, safety, and confirmation rules.
+Before running control-plane commands, confirm that the active profile, project, and region all belong to the intended BytePlus environment.
+
+## Execution plane and credentials
+
+- `arkcli train finetune *`, `arkcli dataset *`, and `arkcli models finetune-config *` are **control-plane**
+  commands. Authenticate with BytePlus SSO / STS via `arkcli auth status`; do not pass data-plane
+  `--api-key` or `--base-url`, which fail fast on control-plane commands.
+- An API key from `.env` is for inference data-plane calls only. It cannot create fine-tuning jobs or upload
+  training data. SFT / LoRA / DPO / RL are training jobs, not plan-model inference calls; do not route them
+  to `+chat` or `+gen`.
+- Local `--train-file` / `--validation-file` inputs are uploaded by ArkCLI to the managed BytePlus TOS; the
+  final job request uses `TosBucket` / `TosPaths`. Do not require a manual upload or pass a local path as the
+  backend data address.
+
+## When To Trigger and Scope
+
+- Create a fine-tuning job: read [`references/create.md`](references/create.md).
+- List or filter fine-tuning jobs: read [`references/list.md`](references/list.md).
+- Download the training/validation data used by a job: read [`references/download.md`](references/download.md).
+- Retrieve, observe, or operate a specific job: read [`references/manage.md`](references/manage.md).
+- Select a step by metrics, export artifacts, and deploy: read [`references/export-deploy.md`](references/export-deploy.md).
+- Do not directly manage datasets. Accept local files, BytePlus TOS URIs, `ds-*/dsv-*` references, and model-supported presets. Use [`../arkcli-datasets/SKILL.md`](../arkcli-datasets/SKILL.md) to create or maintain Dataset resources.
+- Use `--train-dataset` for an ordinary managed Dataset with the default `Multiplier=1`; use repeatable `--train-path` for multiple references, scaling, or sampling. Each entry sets at most one of `multiplier` or `sample_count`; omitting both keeps `Multiplier=1`. Each preset must choose exactly one of `inject_multiplier` or `inject_sample_count`.
+- Orchestrate metric analysis and artifact export in this skill. For custom model details, preparation of deployable versions, and endpoint creation, follow the model registry and deployment skills.
+- When the user says "my jobs / jobs I created / submitted by me", add `--mine` to `train finetune list`; do not list the whole account and guess the creator locally.
+- Do not use the low-level API Explorer as the default entry point.
+
+Load only the reference required for the current task. Do not read every reference merely to become familiar with all commands.
+
+## When NOT To Trigger
+
+- Dataset-only management with no fine-tuning job work → use the dataset capability instead.
+- Public foundation-model catalog lookup only → use [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md).
+- Management of an existing inference Endpoint only → use [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md).
+- Authentication-only or profile/config troubleshooting → use [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md) or [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md).
+- The low-level API Explorer is a fallback entry only, never the default. Use it only when the product command cannot express the task and the user authorizes the fallback.
+
+## Exact-scope diagnostics for a named job
+
+- When a user provides an `mcj-*` ID and asks about status, why it cannot be found, logs, or trajectory, load this skill and read [`references/manage.md`](references/manage.md).
+- For “why can’t this job be found?”, first run `arkcli train finetune get <mcj-id>` against the current active profile, project, and region, then explain the authoritative API response.
+- Treat `mcj-*` as an opaque resource ID. Never reject it from a date-like segment, a readable suffix, or an invented hash-format rule, and never rewrite the supplied ID.
+- If the user says not to switch environments or to inspect only this job, do not run `train finetune list`, scan other jobs, switch profile/project/region, or query another account. Preserve the target `get` error code, message, and request ID. Expand scope only after separate user authorization.
+- When the user asks to save one named MCJ’s logs to a local path, the first business command is `arkcli train finetune logs <mcj-id> --output <path>`. Never list all jobs or scan them with a script first. Preserve any target-command error and do not suggest switching environments.
+- When the user requests the complete rollout trajectory for one named MCJ, run `arkcli train finetune trajectory list <mcj-id> --full` directly. There is no `arkcli train trajectory` path. Preserve a no-trajectory or logging-disabled error; do not explore profiles, MCP configuration, or other jobs.
+- `logs --follow` polls only while a job is active and may produce more logs. It emits the current snapshot and exits when the job is already terminal, and also exits after an idle poll observes a terminal phase. Do not rely on an external timeout as the normal termination mechanism.
+- `pause` and `resume` form an explicit reversible pair: `pause` moves a running job to `Paused`, and `resume` restores a `Paused` job. When the backend permits, `resume` may also retry `Failed` or `Terminated`; follow the current API result.
+
+## Live-information policy
+
+Do not hard-code information that can change, including:
+
+- Trainable models, model versions, fine-tuning types, and training methods.
+- Fine-tuning prices.
+- Hyperparameter fields, defaults, ranges, and enum values.
+- CLI flags, job phases, and operation restrictions.
+- Post-fine-tuning inference methods supported by base models or custom models.
+
+Before critical commands, or when a command fails, use the installed version's `--help` and ArkCLI query commands to obtain current information. If CLI output differs from the command skeletons in this skill, follow the current CLI.
+
+Query prices and fine-tuning capabilities under the active BytePlus profile. Even when model or training method names match those on another platform, do not reuse that platform's prices or capability results.
+
+Treat BytePlus model selection as fail-closed: before naming or using a model, require its exact name from a live catalog query under the active BytePlus scope, then verify its version and requested fine-tuning type with `models versions` and `train finetune capability get`. Treat names from the user, documentation, `--help`, prior knowledge, or another product or region as unverified; never normalize product prefixes. If either query fails or returns no exact eligible match, stop model-dependent estimation or creation instead of guessing a fallback. Continue using `--help` for syntax.
+
+Use the BytePlus ModelArk [Model fine-tuning dataset format description](https://docs.byteplus.com/en/docs/ModelArk/1099461) as the primary data-format source, then confirm with model-aware server-side validation. Do not maintain format descriptions or examples here that are likely to become outdated.
+
+## Default fine-tuning type, training method, and deployment limitation
+
+- If the user does not specify a fine-tuning type (`--type`), default to SFT.
+- If the user does not specify LoRA or full fine-tuning as the training method, default to LoRA.
+- If the user explicitly selects full fine-tuning, explain before creation that ArkCLI currently cannot deploy artifacts produced by full fine-tuning and that deployment must be completed in the console after training.
+
+## BytePlus fine-tuning SDK availability
+
+BytePlus currently does not support the fine-tuning SDK. If the user requests a custom grader, rollout plugin, SDK workspace, custom training code, or SDK submission, politely explain that the capability is currently unavailable on BytePlus. If standard ArkCLI parameters or pipeline configuration can fully express the request, continue with the standard ArkCLI creation flow. Rollout trajectory queries are a separate ArkCLI capability: for a job created with `--enable-trajectory`, use `arkcli train finetune trajectory` with an SSO-authenticated profile that can access the corresponding TLS topic.
+
+## Critical client-side validation
+
+- When the user supplies a model name and fine-tuning type and asks for fine-tuning, SFT, or LoRA pricing, first run `arkcli train finetune pricing --model <model> --type <type>`. Never substitute generic `arkcli pricing models`, because the generic billing catalog does not cross-check the requested training capability for that model.
+- When the user explicitly selects a fine-tuning type, call `models finetune-config <model> <version> --type <type>` with the exact model version. The command validates the type against that version's authoritative `FinetuneTypes`; stop on an unsupported type instead of continuing to pricing, estimate, or job creation.
+- For manual pagination, `train finetune list --page-number` must be `>=1` and `--page-size` must be within `1-100`. For page 2 or later, a page beyond the filtered `total_count` is a parameter error; do not treat it as a valid empty page.
+- When both `train finetune metrics --from-step` and `--to-step` are present, `to-step` must be strictly greater than `from-step`. Stop on an invalid interval before querying metric names or curves.
+- `train finetune pricing --billing-method token` queries token charge items. `instance` requires the exact `--model-version` and `--type`, with hyperparameters kept consistent with job creation. Treat the hourly range as complete only when `price_complete=true`; otherwise report `missing_flavor_ids`.
+- Before using stable resources, run `train finetune resource-group list` with exactly the same model, version, customization type, and hyperparameters as create. Pass a resource-group ID to `create --resource-group` only when `allowed=true` and that item has `matched=true`; treat the ID as opaque and pass it exactly as returned. When several groups match, let the user choose.
+
+## Guard Checklist and General Execution Rules
+
+`create` does not support local `--dry-run`. An online `--estimate` uploads both local training and validation files, so follow upload confirmation rules. Training token estimation excludes validation data. Creation still returns an empty `url` on BytePlus; do not invent a console link.
+
+1. Run `arkcli auth status` first. If authentication fails, recover through the shared skill.
+2. Run read operations directly. For file uploads, job creation, billable operations, or destructive operations, follow the confirmation rules.
+3. Do not ask again for parameters the user already specified. Ask only when a required value is missing and cannot be derived from live queries.
+4. Distinguish the source of every fact: CLI/API responses, server-side validation, or a local rough estimate.
+5. Do not print credentials, complete training logs, or other large results. Write large results to a file and extract only the required fields.
+
+## References and Related Documentation
+
+- [Model fine-tuning overview](https://docs.byteplus.com/en/docs/ModelArk/1099459)
+- [Model fine-tuning dataset format description](https://docs.byteplus.com/en/docs/ModelArk/1099461)
+
+Maintainer evaluation cases are in [`references/evals.md`](references/evals.md).

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

@@ -0,0 +1,274 @@
+# Create a Fine-Tuning Job
+
+Both `--train-file` and `--validation-file` upload to TOS before an online `--estimate` or real submission. The resolved `data.TrainingSet` and `data.ValidationSet` use `TosBucket` and `TosPaths`; local paths are not sent to the server. `uploaded_files` includes both sets, while training token estimation uses only the training set. Local validation files also upload when training data already uses a TOS reference. An upload failure stops submission. `--estimate` uploads files without creating a training job.
+
+> **Execution plane:** `train finetune create` and `--estimate` are control-plane commands authenticated
+> by BytePlus SSO / STS. Do not pass `--api-key` / `--base-url`; the API key in `.env` is for data-plane
+> inference only and cannot create jobs or upload training data. Local training/validation files are
+> uploaded by the CLI through `--train-file` / `--validation-file` to managed BytePlus TOS.
+
+Creation still returns `id` and `url`. BytePlus continues to return an empty `url`; do not invent a console link.
+
+- Follow the sequence below. If the user provides insufficient information, query current capabilities and make recommendations.
+- If the user has already specified the model, version, training data, customization type (`--type`), and either explicit hyperparameters or a default strategy, first validate the model and capability as required in section 1, then run `create --estimate` directly to obtain the online estimate. If the estimate fails or returns insufficient information, query the relevant command according to the error.
+- Wait for user confirmation before the real `create` operation.
+
+## 1. Query models, training options, prices, and supported inference types
+
+| Command | When to use | Common parameters |
+|---|---|---|
+| `arkcli models search [keyword]` | Query candidate base models from the active BytePlus catalog; omit the keyword to inspect the catalog when the user has not named a model | `--modality`, `--strict-filter`, `--refresh-cache` |
+| `arkcli models versions <model>` | Find versions of a base model; fine-tuning support shown here is informational only | None |
+| `arkcli train finetune capability get` | Query the fine-tuning types and training methods supported by a base model version or the source base model of an existing custom model; treat this as authoritative | `--model`, `--version`, `--model-id` |
+| `arkcli train finetune pricing` | Query token- or instance-billed fine-tuning prices | `--model`, `--model-version`, `--type`, `--billing-method` |
+| `arkcli train finetune resource-group list` | Check resource-group access, resolve job resource requirements, and list matching groups | `--model`, `--model-version`, `--type`, `--only-matched` |
+| `arkcli infer endpoint capability get` | Query supported inference types for a base model (`model` + `version`) or custom model (`custom-model-id`) | `--model`, `--version`, `--custom-model-id` |
+
+CLI flags can evolve. Use this reference directly for routine cases; inspect `--help` when a command fails or a parameter is uncertain.
+
+Run every price and capability query under the target BytePlus profile, project, and region. Even when model or training method names match those on another platform, do not reuse that platform's prices or capability results.
+
+Select models in this fail-closed order:
+
+1. Query `arkcli models search [keyword]` first under the active BytePlus scope; omit the keyword when the user has not named a model. Use only exact returned names and never normalize product prefixes.
+2. Before showing or using a candidate, verify it with:
+
+   ```bash
+   arkcli models versions <candidate>
+   arkcli train finetune capability get --model <candidate> --version <version>
+   ```
+
+   Keep it only when the exact version exists and `supported_types` contains the requested type; LoRA SFT requires `lora`.
+3. If either query fails or returns no exact eligible match, report that availability could not be confirmed. Do not name a fallback model or assemble a model-dependent estimate or create command.
+
+After a model passes the checks above, query its price and potential inference methods:
+
+```bash
+arkcli models versions <model>
+arkcli train finetune capability get --model <model> --version <version>
+arkcli train finetune pricing --model <model> --type <type>
+# Token billing is the default. Do not replace this with generic arkcli pricing models.
+# Instance pricing requires the exact version and type. Keep custom hyperparameters identical to creation.
+arkcli train finetune pricing --model <model> --model-version <version> --type <type> \
+  --billing-method instance --hyperparameters '{"epoch":"3"}'
+arkcli infer endpoint capability get --model <model> --version <version>
+```
+
+Explain:
+
+- Which fine-tuning types and training methods the selected version supports.
+- The billing unit and price for the selected customization type.
+- `token` returns token charge items. `instance` first verifies that the exact model version and
+  customization type support Instance billing, then returns resource templates, flavor unit prices,
+  role-size hourly prices, and the overall hourly range. Treat the range as complete only when
+  `price_complete=true`; otherwise report `missing_flavor_ids` and never interpret a missing price as zero.
+- The potential post-fine-tuning inference methods for the selected version and training method.
+  - A query using `--model` and `--version` returns the base model's supported inference types. Treat them only as potential inference types for a future fine-tuned artifact; the artifact is not guaranteed to support exactly the same types.
+  - After training, query the actual custom model with `--custom-model-id`, then continue through the deployment skill. Do not substitute `--model-id`: that flag belongs to `train finetune capability get`, not `infer endpoint capability get`.
+
+Default fine-tuning type and training method:
+
+- If the user does not specify a fine-tuning type through `--type`, default to SFT.
+- If the user does not specify LoRA or full fine-tuning as the training method, default to LoRA.
+- Therefore, when the model supports LoRA, select the LoRA-encoded `--type` by default. If LoRA is unsupported, show the available fine-tuning types and training methods and ask the user to choose.
+- If the user explicitly requests full fine-tuning, use the full fine-tuning `--type` corresponding to the selected fine-tuning type. Before continuing, explain that ArkCLI currently cannot deploy artifacts produced by full fine-tuning and that deployment must be completed in the console after training.
+
+If the user has not selected a model, show a small set of query-proven, capability-verified candidates and ask the user to choose. Do not show unverified candidates or submit a high-cost job autonomously.
+
+## 2. Common creation parameters
+
+Check whether current ArkCLI flags can fully express the request:
+
+```bash
+arkcli train finetune --help
+arkcli train finetune create --help
+```
+
+Common parameters for `arkcli train finetune create`:
+
+| Parameter | Description |
+|---|---|
+| `--name` | Job name |
+| `--description` | Job description |
+| `--model` + `--model-version` | Fine-tune a base model |
+| `--model-id` | Continue fine-tuning an existing custom model; mutually exclusive with `--model/--model-version` |
+| `--type` | Customization type, which may encode both the fine-tuning type and training method; when omitted, apply the default SFT + LoRA policy |
+| `--train-file` | Local training file; repeatable |
+| `--train-tos-uri` | BytePlus Torch Object Storage (TOS) URI of uploaded training data |
+| `--train-dataset <dataset-id>:<version-id>` | Existing training Dataset; the legacy separate version flag remains compatible |
+| `--train-path <json>` | Repeatable ordinary training Dataset input with `dataset_id`, `dataset_version_id`, and at most one of `multiplier` or `sample_count` |
+| `--preset-dataset <json>` | Repeatable model-supported preset with `dataset_version_id` and exactly one of `inject_multiplier` or `inject_sample_count` |
+| `--validation-file` | Local validation file; repeatable |
+| `--validation-tos-uri` | TOS URI of an uploaded validation set |
+| `--validation-dataset <dataset-id>:<version-id>` | Existing validation Dataset; the legacy separate version flag remains compatible |
+| `--validation-percentage` | Split a validation set from the training set; mutually exclusive with an explicit validation set |
+| `--hyperparameters` | JSON string or `@file`; pass values as strings when required by the backend |
+| `--epochs`, `--lr`, `--lora-rank`, `--beta` | Legacy convenience parameters. When supported, they are merged into hyperparameters and take precedence on conflict. |
+| `--max-invalid-records-ratio`, `--max-invalid-records-number` | Maximum invalid-record ratio or count for data fault tolerance |
+| `--shuffle-random-seed` | Data-order control: random shuffle, no shuffle, or a fixed seed |
+| `--save-model-limit` | Number of training artifacts to retain |
+| `--enable-trajectory` | Enable RL trajectory logging. Query the resulting rollout trajectories with `arkcli train finetune trajectory`; this requires an SSO-authenticated profile with access to the corresponding TLS topic and does not depend on the fine-tuning SDK. |
+| `--pipeline` | RL pipeline configuration file; use only when current ArkCLI can fully express the configuration |
+| `--resource-group` | Stable resource-group ID returned by `resource-group list`. Treat it as opaque and pass it unchanged; the CLI rechecks access, job resource requirements, and availability before estimation and real submission. |
+| `--yes` | Skip CLI confirmation. Add it only after the user reconfirms or explicitly asks for immediate creation. |
+
+## 3. Obtain and validate training data
+
+Do not create or manage platform Dataset resources in this skill. Use [`../../arkcli-datasets/SKILL.md`](../../arkcli-datasets/SKILL.md) when management is required. Job creation accepts:
+
+- Local training files.
+- Uploaded BytePlus TOS URIs.
+- Platform Dataset references in `<dataset-id>:<version-id>` form.
+- Preset Datasets explicitly supported by the model configuration.
+
+Choose one ordinary source for each training or validation set. Dataset references are mutually exclusive with the corresponding TOS or local-file source. A single ordinary Dataset defaults to `Multiplier=1`. For multiple references, scaling, or sampling, repeat `--train-path`. Each entry 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":2}'
+--train-path '{"dataset_id":"ds-...","dataset_version_id":"dsv-...","sample_count":500}'
+```
+
+Never combine `--train-path` with `--train-dataset`, a training TOS URI, or local training files. Presets also use repeatable JSON and must choose exactly one injection setting:
+
+```bash
+--preset-dataset '{"dataset_version_id":"dsv-...","inject_sample_count":100}'
+```
+
+The CLI verifies Dataset schema compatibility against the exact model version and customization type, and rejects presets absent from model configuration.
+
+If the user provides no data, ask for a training-set file or an existing data reference.
+
+### Map `dataset_schema`
+
+First read `dataset_schema` from `arkcli models finetune-config <model> <version> --type <type>`, then interpret it using the table below. For field details, examples, and restrictions, follow the BytePlus ModelArk [Model fine-tuning dataset format description](https://docs.byteplus.com/en/docs/ModelArk/1099461).
+
+| `dataset_schema` | Dataset format |
+|---|---|
+| `LLMSft` | Supervised Fine-Tuning dataset for language models |
+| `LLMRL` | Reinforcement-learning dataset for language models |
+| `PromptResponse` | SFT for text generation models |
+| `ImageRecognitionSFT` | SFT for multimodal models; also compatible with text generation models |
+| `ImageGenerationSFT` | SFT for image generation models |
+| `VideoGenerationSFT` | SFT for video generation models |
+| `TextDPO` | DPO for text generation models |
+| `ImageRecognitionDPO` | DPO for multimodal models; also compatible with text generation models |
+| `TextRL` | Reinforcement learning for text generation models |
+| `ImageRecognitionRL` | Reinforcement learning for multimodal models; also compatible with text generation models |
+| `Text` | Continued Pre-Training for multimodal or text generation models |
+
+If `finetune-config` does not return `dataset_schema`, do not guess. Check the BytePlus dataset-format documentation, perform the local structural checks below, and use `arkcli dataset validate` for model-aware server-side validation. If the format remains ambiguous, ask the user to confirm it.
+
+### Local offline checks
+
+For local files, use the BytePlus ModelArk [Model fine-tuning dataset format description](https://docs.byteplus.com/en/docs/ModelArk/1099461) to check:
+
+- The file is readable, correctly encoded, and reasonably sized.
+- Every non-empty JSONL line is a JSON object.
+- Sample count and invalid-line count.
+- Required fields, types, and content structure from the documentation.
+
+Use a structured JSON parser rather than regular expressions to validate JSON. Report the exact sample count and failing line numbers. Never describe a local check as authoritative platform validation.
+
+Token counting:
+
+- If the environment contains a tokenizer that matches the target model, provide a local estimate and state the tokenizer and source of error.
+- If no matching tokenizer is available, do not present character count as an exact token count. Leave token statistics to the online `--estimate` flow.
+
+## 4. Query and confirm hyperparameters
+
+| Command | When to use | Common parameters |
+|---|---|---|
+| `arkcli models finetune-config` | Query supported hyperparameters and `dataset_schema` after selecting the model version and customization type | `<model> <version>`, `--type` |
+| `arkcli train finetune create` | Estimate or create a job | Use online `--estimate`, then submit after confirmation |
+
+Display parameter names, default values, ranges or enum values, and short descriptions. Do not rely on memory for field names.
+
+When `--type` is explicit, `models finetune-config` validates it against the exact model version's authoritative `FinetuneTypes`, using the same capability source as `train finetune capability get`. If that version does not support the requested type, the command returns a validation error before reading its configuration schema; do not continue with estimate or creation.
+
+- When the user requests custom hyperparameters, ask the user to confirm the override values.
+- Use the selected model, user preference, dataset size, target metrics, and logs to recommend hyperparameters. Use defaults when there is no evidence for a better configuration.
+- Reject values outside the schema.
+
+Read default values and ranges for general training configuration from the `finetune-config` schema. This reference records only stable semantics:
+
+- Field names for epochs, learning rate, batch size, LoRA rank/alpha/dropout, DPO beta, RL steps, and similar settings can vary by training method.
+- `save_model_limit` controls how many training artifacts are retained. Follow the current CLI/API for its default and maximum.
+- Data fault tolerance limits and the shuffle seed are data configuration, not model hyperparameters. Display them separately in the preview.
+
+## 5. Query and select a stable resource group when requested
+
+When the user wants a resource group, query with exactly the same model, customization type,
+and hyperparameters that will be used for creation:
+
+```bash
+arkcli train finetune resource-group list \
+  --model <model> --model-version <version> --type <type> \
+  --hyperparameters '<same-json-as-create>' --only-matched
+```
+
+For continued training from an existing custom model, use `--model-id <cm-id>` instead of
+`--model/--model-version`. Interpret the result fail-closed:
+
+- `allowed=false` means fine-tuning resource groups are not enabled for the active account or
+  project. Do not add `--resource-group` to create.
+- `candidate_templates` are the authoritative resource requirements resolved for the exact model,
+  version, type, and hyperparameters. Never infer requirements from a group name or aggregate capacity.
+- Only an item with `matched=true` can run the current job. Treat `unmatch_reasons` as authoritative;
+  never bypass or silently ignore them.
+- If multiple groups match, show names, IDs, matched templates, and a capacity summary, then let the
+  user choose. Do not choose a group autonomously.
+- Pass the selected group to both estimate and real creation with `--resource-group <resource-group-id>`. The CLI
+  rechecks permission, candidate templates, and availability before each operation and fails fast if
+  the group no longer matches.
+- If the selected group is absent or unmatched, the error reports authoritative mismatch reasons and
+  every `matched=true` group name and ID available to the current job; it explicitly says `none` when
+  no group is usable.
+
+`resource-group list` is an online read-only preflight, not Client Preview. Do not add `--dry-run`.
+Keep all hyperparameters identical between this query and create, including convenience overrides such
+as `--epochs`, `--lr`, `--lora-rank`, and `--beta`.
+
+## 6. Preview creation and validate configuration, data, tokens, and cost
+
+| Command | When to use | Common parameters |
+|---|---|---|
+| `arkcli train finetune create` | Estimate or create a job | Use online `--estimate`, then submit after confirmation |
+
+Assemble the command according to `arkcli train finetune create --help`, then run it with `--estimate`. This is an online estimate, not Client Preview. If local-file upload requires confirmation, obtain user authorization first and add `--yes` only as directed by the CLI.
+
+The preview must summarize at least:
+
+- Job name, model, version, fine-tuning type, and training method.
+- If defaults are applied: "No fine-tuning type or training method was specified; defaulting to SFT + LoRA."
+- For full fine-tuning: "ArkCLI currently cannot deploy artifacts produced by full fine-tuning; complete deployment in the console after training."
+- Training and validation data sources.
+- Custom and recommended hyperparameters, plus which remaining parameters use defaults.
+- Server-reported sample or token information.
+- Billing unit, unit price, and estimated cost.
+- When using a resource group: its name, ID, matched candidate templates, and preflight result.
+- Non-default data fault tolerance limits, random seed, artifact-retention limit, and similar configuration.
+
+If the dry run omits a field, state that it was not provided. Do not invent a value.
+
+## 7. Obtain final confirmation and create
+
+- After authentication, generate and reuse
+  `ARKCLI_SKILL_FLOW_ID=ftf_<ULID>` for this create workflow.
+- With the shared single-command prefix, run
+  `arkcli train finetune _report-activity --action create_flow_enter` before
+  the first create business command.
+- Report `data_validation_success` only after machine-verifiable data validation;
+  ordinary argument parsing and Client Preview `--dry-run` do not report.
+
+Present the complete preview and explicitly ask whether to create the job. Run the real creation command only after confirmation. For non-interactive execution, add `--yes` as required by the CLI.
+
+On success, return:
+
+- Job ID, name, and initial phase.
+- Model, version, fine-tuning type, and training method.
+- A summary of key data and hyperparameters.
+- When using a resource group, the selected resource-group ID and that submission preflight passed.
+- Console URL, if returned by the CLI.
+- A follow-up query such as `arkcli train finetune get <job-id>` or `watch <job-id>`.
+
+Do not deploy the model automatically in this flow.

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

@@ -0,0 +1,50 @@
+# Download Fine-Tuning Job Data
+
+When the user wants to recover the training or validation data used by a fine-tuning job:
+
+```bash
+arkcli train finetune download <job-id> [--set all|train|validation] [--output-dir <dir>]
+```
+
+The command resolves `Data.TrainingSet` / `Data.ValidationSet` from
+`GetModelCustomizationJob`, then downloads the referenced objects from TOS. The default output directory
+is `./<job-id>-data`; by default both training and validation data are downloaded.
+
+## Supported sources
+
+| Job Data field | Behavior |
+|---|---|
+| `TosBucket` + `TosPaths` | Download the original TOS objects and preserve relative paths |
+| `Datasets[]` (`DatasetId` + `DatasetVersionId`) | Resolve the Dataset version storage, then download its `Storage.Bucket` / `Storage.Prefixes` |
+| `PresetDatasets[]` | Platform-managed preset data, not downloadable; reported under `skipped` |
+| `LocalFiles[]` | Only creation-time local paths are recorded; file contents are not retained server-side and are reported under `skipped` |
+
+When a set has multiple sources, the command writes them below separate `train/` or `validation/`
+subdirectories and adds `01/`, `02/`, ... when needed to avoid filename collisions.
+
+## Examples
+
+```bash
+# Download training and validation data.
+arkcli train finetune download mcj-20260722153822-jqvd
+
+# Download only the training set.
+arkcli train finetune download mcj-20260722153822-jqvd --set train --output-dir ./mcj-data
+
+# Download only the validation set.
+arkcli train finetune download mcj-20260722153822-jqvd --set validation
+```
+
+The result includes each file's `object_key`, local `path`, and `size_bytes`, plus the bucket and prefixes
+used for each set.
+
+## Boundaries
+
+- This is a control-plane job lookup plus TOS read, not a data-plane call. Do not pass `--api-key` or
+  `--base-url`.
+- The command fails if a target file already exists; choose a different `--output-dir` instead of silently
+  overwriting local data.
+- A job that only has `PresetDatasets` or `LocalFiles` has no downloadable TOS objects and returns a clear
+  "no downloadable data" error.
+- Do not guess a data location from the job name, model name, or an old directory. Use the job's
+  `TosBucket` / `TosPaths` or the referenced Dataset version.

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

@@ -0,0 +1,59 @@
+# arkcli-train-finetune evals
+
+## Coverage goals
+
+- Verify that prompts containing `mcj-*`, fine-tuning pricing, logs, or trajectory trigger this skill.
+- Verify that read-only diagnosis stays within the user-specified scope without environment switching or other-job scans.
+- Verify that lifecycle help matches actual CLI behavior.
+- Verify that resource-group access, job requirements, and matches fail closed before creation.
+
+## Triggers
+
+- Get, logs, trajectory, metrics, status, or lifecycle requests for a named MCJ.
+- Fine-tuning pricing, capability, configuration, or creation requests for a named model and training type.
+- Requests to submit through a resource group or identify groups that can run a prepared job.
+
+## Anti-triggers
+
+- Foundation-model catalog lookup only routes to `arkcli-models`.
+- Existing inference Endpoint management only routes to `arkcli-infer-endpoint`.
+- Authentication-only or profile/config troubleshooting routes to the corresponding skill without expanding the MCJ query scope.
+
+## Guard checks
+
+- Run the smallest read-only command for the named MCJ first and preserve authoritative API errors.
+- Never infer ID validity from its appearance, list every job, switch environments, or query another account.
+- Route fine-tuning prices through the capability-aware `train finetune pricing` command.
+- Query `train finetune resource-group list` first and use a group only when `allowed=true` and its item has `matched=true`.
+
+## Tested happy-path CLI commands
+
+```bash
+arkcli train finetune get mcj-20990101000000-noexist
+arkcli train finetune pricing --model seed-2-0-mini --type sft
+arkcli train finetune logs <mcj-id> --output <path>
+arkcli train finetune trajectory list <mcj-id> --full
+arkcli train finetune resource-group list --model <model> --model-version <version> --type sft --only-matched
+```
+
+## Regression cases
+
+- Local training and validation files: after upload authorization, online `create --estimate` uploads both sets and reports both TOS references and upload records. Training token estimation excludes validation data, and estimate does not create a job.
+- Existing TOS training plus local validation: validation still uploads. Missing files or upload failures stop submission. Never replay an unknown create result.
+- Confirmed BytePlus creation: report the returned ID and preserve the empty `url`; never invent a console link.
+
+| Case | Prompt | Expected behavior |
+|---|---|---|
+| `bp-skill-notfound-no-scope-expansion-001` | Why can’t I find job `mcj-20990101000000-noexist`? Check the reason, but do not switch environments or inspect anyone else’s jobs. | Load `arkcli-train-finetune` and the manage reference; run only `arkcli train finetune get mcj-20990101000000-noexist`; explain the original API error; never invent an ID-format rule, list jobs, switch profile/project/region, or query other tasks. |
+| `bp-pricing-seed20mini-001` | Check the BytePlus fine-tuning price for SFT on `seed-2-0-mini`. | Load `arkcli-train-finetune` and the create reference; run `arkcli train finetune pricing --model seed-2-0-mini --type sft`; never substitute `arkcli pricing models`; explain only the capability-validated result. |
+| `ctrl-train-logs-output-005` / `bp-logs-output-real-job-001` | Save the named MCJ’s logs to the supplied local file. Inspect only that job and do not expand scope. | Load the manage reference; run `arkcli train finetune logs <mcj-id> --output <path>`; preserve the original error on failure; never list jobs, scan with Python, switch profile/project, or stop after help. |
+| `ctrl-train-trajectory-list-full-002` / `bp-trajectory-full-real-job-001` | Retrieve the complete rollout trajectory for the named MCJ. Preserve a no-trajectory error and do not expand scope. | Run `arkcli train finetune trajectory list <mcj-id> --full`; never try `train trajectory`, crawl help, inspect another job, or read profile/MCP configuration. |
+| `bp-logs-follow-completed-job-001` | Run `logs --follow --format json` for the named Completed MCJ. | Emit the remaining logs and terminal phase, then exit automatically without an external timeout or continued polling. |
+| `bp-resume-paused-help-001` | Can I resume a job after pausing it? | Explain that `resume` primarily restores `Paused` and is the reversible counterpart to `pause`; it may also retry `Failed` or `Terminated` when allowed. Never describe it as Failed-only. |
+| `bp-finetune-managed-dataset-preset-001` | Train with `ds-1/dsv-1` and inject 100 samples from `dsv-preset`. | Use `--train-dataset ds-1:dsv-1` and `--preset-dataset '{"dataset_version_id":"dsv-preset","inject_sample_count":100}'`; verify schema and preset support from model configuration; reject simultaneous training TOS/local-file sources; never use unsupported Client Preview `--dry-run`. |
+| `bp-finetune-managed-train-path-001` | Scale ds-1/dsv-1 by 2 and sample 500 rows from ds-2/dsv-2. | Repeat `--train-path`, using only `multiplier` in one entry and only `sample_count` in the other. Reject an entry containing both and reject any simultaneous `--train-dataset`, training TOS, or local-file source. |
+| `bp-finetune-resource-group-match-001` | Run SFT on the seed model through a resource group with epoch=5. First tell me the job requirements and which groups are usable. | Run `resource-group list --only-matched` with the same model, version, type, and epoch; explain `candidate_templates` and matched capacity; let the user choose among multiple matches; pass only the selected `matched=true` opaque resource-group ID to estimate and real create. |
+| `bp-finetune-resource-group-not-allowed-001` | I want a resource-group fine-tuning job, but the query returns `allowed=false`. | Explain that the active account/project lacks access and no group is available to the current job; do not add `--resource-group`, guess a group, bypass the permission result, or submit a resource-group job. |
+| `bp-finetune-resource-group-unmatched-001` | My selected resource group does not match this job. Submit anyway. | Refuse submission; report authoritative mismatch reasons and every `matched=true` group name and ID available to the current job, or explicitly state `none`. |
+| `bp-finetune-mine-list-001` | Show the fine-tuning jobs I created. | Add `--mine` to `train finetune list`; rely on the server-side `sys:ark:createdBy` tag filter; never list the whole account and infer the creator locally. |
+| `bp-finetune-download-data-001` | Download the training and validation data used by `<mcj-id>`. | Use `train finetune download <mcj-id>`; resolve `TosBucket/TosPaths` or Dataset versions, preserve relative paths, and report preset/local-only sources as skipped. Do not guess TOS locations. |