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

package/skills/arkcli-agent/references/session-files.md

@@ -0,0 +1,149 @@
+# Session and Files
+
+`session resources list/get/add` are data-plane commands and accept explicit `--api-key` / `--base-url`. An explicit URL requires an explicit key and must target the MA data plane, not the BYOK model's BaseUrl. With only an explicit key, use the standard MA endpoint for the current product, Region and environment, not a plan route. Control-plane authentication for `session create/get` is unchanged.
+
+## Env / Session
+
+### Session Project Consistency
+
+When creating a Session through `session create`, `+new session`, or `+iterate`, the selected Agent, Environment, and other project-scoped dependencies must belong to the same Project as the Session. Overrides do not waive this requirement.
+
+- Check the selected Platform profile's project context with `auth status`, then verify actual `ProjectName` values from resource list/get responses. `account-wide` is a query scope, not a concrete Project or proof that returned resources share one.
+- If the target Project is unresolved, ownership is missing, or projects conflict, perform the relevant read or ask the user before creating. Do not infer ownership from names, account membership, visibility, or creation time. Do not invent a ProjectName for resources without project ownership.
+- Filter Environment candidates to the same Project before selecting, and explicitly pass `--environment-id` (or `--env-id` where supported). Do not rely on the latest account-wide environment. If no same-Project candidate exists, obtain confirmation to create one in the target Project instead of borrowing another project's resource.
+- Create with a verified project-scoped Platform profile. If none exists, follow the Profile skill; do not silently change the global default or invent a global `--project-name`. Read the Session back to verify its project and bindings; a successful preview does not establish project consistency.
+
+```bash
+arkcli agent env create --name arkcli-<domain>-env-<timestamp> --config '{Type: cloud, Networking: {Type: unrestricted}}' --format json
+arkcli agent session create --agent-id <agent-id> --environment-id <env-id> --title arkcli-<domain>-session-<timestamp> --format json
+arkcli agent session get <session-id> --format json
+```
+
+Session operations follow OpenTOP; Session resources/events/threads traverse the data plane directly.
+
+When creating a cloud environment online, an explicit `Networking: {Type: unrestricted}` must be specified; only `{Type: cloud}` will be validated by the backend as missing `config.networking`.
+
+### Session TOS Resource
+
+A Session can mount an existing TOS directory at creation time. The CLI appends a resource with `Type=tos`, `TosBucket=<bucket>`, and `TosKey=<prefix>/`.
+
+Use `--tos-path` only when the user explicitly asks for a TOS mount and provides the location. If the user asks for a mount without a location, request the complete `tos://<bucket>/<prefix>/` value instead of guessing it.
+
+```bash
+arkcli agent session create \
+  --agent-id agent-xxx \
+  --environment-id env-xxx \
+  --tos-path tos://my-bucket/analysis/ \
+  --format json
+```
+
+The protocol may be omitted as `my-bucket/analysis/`. The value must identify a directory: the prefix must be non-empty and end in `/`. Values such as `tos://bucket/`, `bucket`, or `bucket/path` fail local validation. If `--resource` is also provided, the TOS resource is appended to that array.
+
+`arkcli +new session` and `arkcli +iterate` support the same flag. It mounts an existing directory; it does not create a bucket, upload objects, or grant access. Confirm that the account has TOS access and permission to read the bucket and prefix.
+
+### Environment Setup Script
+
+An Environment initialization script is stored in `Config.SetupScript`. Pass the script directly or use `@` to read a local file:
+
+```bash
+arkcli agent env create \
+  --name arkcli-analysis-env \
+  --config '{Type: cloud, Networking: {Type: unrestricted}}' \
+  --setup-script @./bootstrap.sh \
+  --format json
+```
+
+`--setup-script` overrides `Config.SetupScript`. Complex configuration can still be supplied with `--config @./env.yaml` or `--file`. The CLI normalizes common lower-case and snake-case fields such as `setup_script` and `networking` to the OpenTOP request shape.
+
+### Session Overrides
+
+Before overriding runtime parameters, query the target model's [parameter metadata](model-config.md). Query again when changing models; do not inject defaults automatically.
+
+A Session may override an existing Agent or Environment for that Session only. Non-null fields such as Agent `System`, `Tools`, `McpServers`, `Skills`, and `Multiagent`, and Environment `Config`, use the service's replacement semantics. Supply complete arrays instead of expecting them to merge with the base Agent.
+
+```bash
+arkcli agent session create \
+  --agent-id agent-xxx \
+  --environment-id env-xxx \
+  --agent-overrides '{model: {id: dola-seed-2-1-pro-260628, thinking: enabled, reasoning_effort: low, service_tier: auto}, Tools: [...]}' \
+  --environment-overrides @./environment-overrides.yaml \
+  --format json
+```
+
+`--agent-overrides` maps to `AgentWithOverrides`; `--environment-overrides` maps to `Environment`. If an override omits `Id`, the CLI fills it from `--agent-id` or `--environment-id`. These are one-of request variants, so the CLI removes the corresponding `AgentId`/`AgentVersion` or `EnvironmentId` from the final request. Do not use `--agent` and `--agent-overrides` together. `arkcli +new session` and `arkcli +iterate` accept the same override flags.
+
+`AgentWithOverrides.Model` supports `Id/Provider/Protocol/BaseUrl/Headers/TokenLimits/InputModalities` and `Speed/Thinking/ReasoningEffort/ServiceTier`. Explicit connection fields are no longer filtered. See [BYOK](byok.md) for types, omission semantics, and request credentials. Use the selected model's capabilities; do not invent defaults or equate persistence with successful inference.
+
+The same model-structure normalization applies to `--agent-overrides`, `--agent-overrides @file`, and `AgentWithOverrides` supplied through the general `session create --file` payload. Explicit empty values such as `--agent-overrides=` or `--environment-overrides=` are invalid; ArkCLI returns a validation error and does not create a Session.
+
+### Environment Status Filtering
+
+Currently, `arkcli agent env list` **does not support the `--status` flag**. Do not generate the following command:
+
+```bash
+arkcli agent env list --status active
+```
+
+`ListEnvironments` does not support a `Status` filter field either; the `Environment` objects only have an optional `ArchiveTime`.
+
+To filter by status, fetch the full list first, then filter locally using the AI Agent in the `arkcli` CLI:
+
+```bash
+arkcli agent env list --page-all --format json
+```
+
+- `ArchiveTime` is non-empty: `archived`
+- `ArchiveTime` is empty or missing: `active`
+- Although the frontend domain type reserves `updating`, no reliable field is available for this state; do not claim support for `updating`.
+- Do not filter based on the default page; status filtering must be combined with `--page-all`, and be mindful of the global `--page-limit` affecting the results.
+
+`--page-all` defaults to `Limit=100`, and the next page is fetched using `NextPage` in the response. `--page-limit` limits the number of pages to request, not the number of results.
+
+## Other resources at Session creation
+
+Complex resources belong to `session create --resource`, not the file-only `session resources add`. For an already selected memory store, use an array such as `[{Type: memory_store, MemoryStoreId: ms-xxx, Name: user-memory}]`. Canonical field names are PascalCase and type values remain snake_case. The current CLI also normalizes supported aliases such as `memory_store_id`; snake_case is not inherently invalid. For a required-field error, inspect nesting, the real ID and the local Preview payload rather than guessing fields or creating a substitute resource.
+
+## Diagnostics and export
+
+- Use `arkcli +debug <session-id> --format json` for a known Session. Distinguish running, failed and waiting-for-confirmation states from the returned Session/events/resources/threads. Warnings indicate partial retrieval failures, not empty data.
+- On an explicit export request, use `arkcli +export <session-id> --output ./session-diagnostics.tar.gz`. This packages CLI-visible diagnostics, not a complete workspace, memory store or environment snapshot. Explain the manifest/notes, event count and warnings.
+- The archive lives on the CLI host. Inspect potentially sensitive messages/code/business data before delivery; a remote sandbox path is not a file on the user's computer. Do not automatically upload or publish diagnostics.
+
+## Files and Session Resources
+
+### Inspect Mounted Resources
+
+Read `agent session get <session-id>`, then `agent session resources list <session-id>`. Use `resources get` with the resource/file ID or mount-path selector from its help for a single item, and `agent file get <file-id>` for file metadata. Mounted resources are not a complete Sandbox directory tree, and file get does not download content. Do not invent filesystem traversal or internal storage commands when a public read API is unavailable.
+
+For memory mounts, use the returned store ID with `agent memory-store get`, `memories list`, and `memories get --view full`. The default basic view excludes content. After a path update, use the returned ID and Path instead of assuming the old ID remains valid. Never connect to OV internal storage or bypass resource/account authorization.
+
+- Upload local files to the Files API: `arkcli agent file upload --path ./data.csv --purpose user_data --wait-active`.
+- Register with URLs/TOS: `arkcli agent file upload --url https://... --purpose user_data` or `--url tos://bucket/path/file --tos '{bucket: b, prefix: arkfiles/}'`.
+- `agent file upload/delete` support command-local `--dry-run`. It emits a zero-network `preview.v1` plan and never uploads, polls, or deletes. Delete preview does not require `--yes`; real deletion still requires explicit confirmation and `--yes`.
+- Preprocess for videos/special files can include `--preprocess-configs`; an expiration time can be specified with `--expire-at <unix-seconds>`.
+- Wait for upload completion: `arkcli agent file wait <file-id>`.
+- List existing files: `arkcli agent file list --purpose user_data --limit 20`. Use `arkcli --page-all agent file list` for full traversal, with `limit=100` and fetching `has_more + last_id -> after` for subsequent requests.
+- When a user provides a local path and wants to mount it to an existing session, complete the following steps:
+
+```bash
+arkcli agent session resources add <session-id> --path ./data.csv --mount-path data.csv
+```
+
+This involves uploading the file, waiting for it to become active, and then adding the session resource.
+The `session resources add --path` command supports passing related parameters: `--purpose`, `--tos`, `--preprocess-configs`, `--expire-at`, `--wait-timeout`, and `--wait-interval`.
+
+Boundaries:
+
+- `session resources add` currently only supports `type=file`, `file_id`, and `mount_path`, and does not support the more complex `github_repository`/`memory_store` parameters in PRD.
+- The backend automatically prepends `mount_path` with `/mnt/session/uploads/`. The CLI will warn about this in stderr, but will not modify the user-provided path; for example, if the path is `reports/data.csv`, the final path becomes `/mnt/session/uploads/reports/data.csv`. Avoid providing `uploads/` or paths containing `..` to avoid overwriting or invalid paths.
+- `resources get` is a derived CLI capability: list resources and filter by `resource_id`, `file_id`, or `mount_path`.
+- Currently, the data plane does not have native resource update/delete capabilities; the CLI remains unsupported.
+- After `session resources add`, the backend copies the source file to the session-managed uploads path. Therefore, the `file_id` seen in `resources list` may differ from the source `file_id` passed during the addition.
+- Do not use ArkBFF/NodeBFF to fetch files; the CLI only connects directly to `/api/v3/files` for the data plane.
+
+## Example
+
+```bash
+arkcli agent file upload --path ./sales.csv --purpose user_data --wait-active --format json
+arkcli agent session resources add sess-xxx --path ./sales.csv --mount-path sales.csv --format json
+```

package/skills/arkcli-agent/references/session-upgrade.md

@@ -0,0 +1,61 @@
+# Upgrade an Existing Session
+
+Use `agent session upgrade` to change the model, Agent version, or runtime configuration of an **existing Session**. Updating the Agent resource does not automatically update its old Sessions; `+iterate` creates a new Session and is not a substitute. Use `session update` for title/tags only. Creation-time overrides are described in `session-files.md`.
+
+## Command and Input
+
+Consult [model parameter metadata](model-config.md) before configuring or changing runtime parameters. Metadata guides supported values; it does not replace upgrade baseline semantics or add client-side business validation.
+
+```bash
+arkcli agent session upgrade <session-id> \
+  --model <selected-model-id> \
+  --thinking enabled \
+  --reasoning-effort low \
+  --dry-run --format json
+```
+
+```bash
+arkcli agent session upgrade <session-id> \
+  --agent-version 4 \
+  --agent '{skills: [], mcp_servers: []}' \
+  --environment '{config: {env: {LOG_LEVEL: debug}, packages: {pip: [pytest]}}}' \
+  --compact \
+  --dry-run --format json
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `<session-id>` | Required; preserves the existing Session rather than creating one |
+| `--file <path>` | Local JSON/YAML request file; no implicit stdin or `--file -` support |
+| `--agent <object>` | Inline JSON/YAML or `@file`; fields: `type/id/version/model/system/tools/mcp_servers/skills/multiagent/display_name` |
+| `--environment <object>` | Inline JSON/YAML or `@file`; fields: `type/id/config` |
+| `--agent-version <int>` | Overrides `agent.version`; omitted or 0 preserves the current snapshot, not the latest version |
+| `--model <id-or-object>` | An ID replaces only `agent.model.id`; an object or `@file` replaces the model object in the request |
+| `--speed/--thinking/--reasoning-effort/--service-tier` | Overrides the corresponding snake_case model field, preserving explicit empty strings |
+| `--vault-ids <array>` | JSON/YAML array or `@file`; complete target user Vault set, not a delta; `[]` clears user bindings |
+| `--initial-events <array>` | JSON/YAML array or `@file`; optional or `[]`; the backend accepts only one fixed `/compact` event when nonempty |
+| `--compact[=false]` | true builds the fixed `/compact` event; false sets `initial_events: []`; conflicts with `--initial-events` |
+
+This uses data-plane `POST /api/v3/sessions/{id}/upgrades` and **snake_case**, not TOP CamelCase or creation-time `AgentWithOverrides`. Missing type values become `agent_with_upgrades` / `environment_with_upgrades`; explicit types are forwarded unchanged. IDs may be omitted to keep current bindings. Supplied Agent/Environment IDs must match the Session and cannot switch its bindings.
+
+Precedence: load `--file`, replace its entire agent/environment object when the respective flag is present, then apply version/model leaf flags. Event/Vault flags replace the corresponding arrays. The CLI preserves omitted values, `null`, `[]`, and empty strings. Apart from defaulting missing discriminators, it does not look up or merge remote snapshots or enforce business allowlists; report server errors without inventing unsupported fields.
+
+## Configuration Semantics
+
+- Supply at least one of `agent/environment/vault_ids`; initial events alone are not an upgrade target. This API does not expose top-level `title/tags/resources/checkpoint_id/environment_id`.
+- Without a version, patch the current Session Agent snapshot and preserve unprovided fields. With a positive version, start from that published version and apply explicit overrides; previous Session overrides are not automatically retained. Resolve an actual published version number when the user asks for the latest; neither omission nor the string `latest` means latest.
+- `tools/mcp_servers/skills` replace entire arrays; `[]` clears them and omitted/null preserves the baseline. No default tools or skills are injected.
+- Model fields: `id/provider/protocol/base_url/headers/token_limits/input_modalities` and the four runtime settings. Creation overrides support the same fields; upgrade emits snake_case without rewriting Header keys or values. See [BYOK](byok.md). Omitted fields are not filled from defaults.
+- Cloud networking replaces the policy; `config.env` merges by key and packages merge by package name, with supplied values/specs winning. Empty env/packages do not clear existing entries. Explicit setup_script replaces it, including an empty string. An environment ID alone does not reload the Environment resource's latest configuration; supply the desired config explicitly.
+- Self-hosted Sessions can upgrade their Agent, but cannot switch environment type or configure customer-owned sandbox networking/packages/env/setup_script. User TOS cannot be changed by upgrade.
+- On servers supporting Vault replacement, a nonempty `vault_ids` array replaces all user bindings: include every Vault to retain. Omission or request-file `null` preserves bindings; `[]` clears user bindings while server-managed authorization Vaults remain. The same set refreshes credentials. The server validates existence and account/project access; no Vault is created automatically. Show the binding diff and obtain confirmation, then read back after upgrading. Do not supply credential secrets. BytePlus deployment availability must be verified from the actual response; report older-server rejection without silently substituting another operation.
+
+## Execution and Verification
+
+1. Read the Session to identify current bindings/configuration and state. The server requires idle and rejects terminated/upgrading Sessions or a previous turn that has not normally ended. The CLI does not preempt these business checks or retry business errors.
+2. Use leaf-local `upgrade ... --dry-run --format json`. It is an offline plan, not model/resource validation. Explain the changes and possible sandbox preparation/compaction effects, obtain explicit confirmation, then execute without dry-run. There is no `--yes` flag on this command.
+3. Execution submits once and returns the actual Session object; it does not return a separate upgrade task or wait for completion. `upgrading` means accepted/in progress, not that the new model is already effective. Do not invent an `/upgrades/{upgrade_id}` query command.
+4. Separately read the Session until it leaves upgrading and verify model ID, version, runtime settings, and target configuration. Idle alone does not prove success. Diagnose mismatched configuration with events or `+debug`. After an ambiguous response/timeout, read back before considering another upgrade.
+5. Do not send messages, delete, interrupt, or repeat an upgrade while upgrading. If compact was requested with upgrade, do not send another compact. After configuration verification, obtain test authorization before sending a minimal inference message.
+
+Use the current product/profile API Key and project; an explicit base URL needs a paired explicit API Key. Standard Authorization/API Key fields are redacted in preview, but arbitrary environment variables/custom headers are not guaranteed to be secret-free. Never disclose real secrets in conversation, logs, or reports.

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

@@ -0,0 +1,87 @@
+# Skills
+
+## Skill Selection
+
+- BytePlus exposes TOP `custom`, `ark`, and `all` sources. `agent skill search/list` defaults to `--source custom`; `ark` queries Ark-provided skills and `all` omits `Source`. Only `market`, `skillhub`, and `skill_hub` are rejected before any remote request.
+- Market/SkillHub skill is **not available in BytePlus**. Ark skills can be discovered and attached, but they are read-only: update, delete, download, and protection changes are rejected by the CLI.
+- Custom skill: The default selection process for skills within the user's account involves pagination: fetch the first page of 100 items, and the AI agent within the CLI calls `ListSkillsForTop` to filter by name, description, and capability. If no suitable candidate is found, the `NextPage` is used to fetch the next page until a match is found or no further pages are available. Do not filter by `Name` on the server side or pull the entire catalog in one go. The internal CLI entry point is `ListSkillsForTop`, and the actual top-level action is `ListSkills`. Only use the `skill-...` IDs returned by this interface; `s-...` IDs are not used for custom skills.
+- When creating an Agent, a bare custom ID can be passed directly as `--skill skill-xxx`. The CLI omits `Version`, allowing the service to use the latest version; it never sends the literal string `latest`. A bare `--skill s-xxx` is rejected in BytePlus.
+- When uploading a custom skill, it goes through the data plane `POST /api/v3/skills`, not the top-level `CreateSkill`. A current profile with an available ARK API key is required.
+- `agent skill get <id>` and `versions` read custom or Ark skills through TOP. List summaries preserve `DisplayTitle`, `Source`, `UpdateTime`, `Name`, and `ProtectionEnabled`; Agent Skill responses preserve `UseLatest`, concrete `Version`, and `DisplayName`.
+- `agent skill create --protection-enabled` sets protection during upload. Use `agent skill set-protection <id> --enabled=true|false` for an existing custom skill; explicit `false` is preserved and sent through TOP `UpdateSkill`.
+- `agent skill update <id> --zip <file>` creates a new version through OpenTOP `CreateSkillVersion`; it does not modify an existing version in place. Use `agent skill versions <id>` to list versions.
+- `agent skill download <id> [--version <version>]` resolves the requested or latest version, obtains `PreSignedTOSURL` through `GetSkillVersion`, and downloads it with an ordinary unauthenticated GET. The default filename is `<skill-id>-v<version>.zip`.
+- `agent skill download ... --dry-run` previews version resolution, download, and local save steps without network or filesystem writes. If `--version` or `--output` is omitted, treat the corresponding `unresolved` value as a placeholder; never claim it was resolved online and never create or replace a file during Preview.
+- `agent skill delete <id>` calls `DeleteSkill`. It does not cascade to SkillVersions and may run only after every version has been deleted.
+- `agent skill delete <id> --version <version>` calls `DeleteSkillVersion` and deletes only that version. Before deleting the latest version, delete every non-latest version.
+- `agent skill create/update/delete` support command-local `--dry-run` for a zero-network preview of the upload or delete request. Delete preview does not require `--yes`, but it does not validate the online version dependency order. Real deletion still requires a complete version-list read and interactive confirmation or explicit `--yes`.
+- BytePlus does not expose a market skill selection flow. Custom/Ark selection uses `Items[].Id`, `Name`, `DisplayTitle`, `Description`, `Source`, and version fields from TOP `ListSkills`.
+- When selecting a custom skill, read the first page of complete `Items`, and compare `Id`, `Name`, `Description`, and `LatestVersion`. Do not rely solely on the service-end keywords or the first entry. If there are not enough relevant candidates, use `NextPage` to fetch the next page. The `AgentSkills` only contain `skill-...` custom skills. After confirming the candidates, they can be fetched directly or pass the bare `--skill <Items[].Id>`.
+- When multiple candidates are close, list them for the user to choose from. When the user requests automatic completion, select the skill with the highest relevance and the most explicit version.
+
+- Pagination selection prioritizes "on-demand fetching": the first page uses `--limit 100`, and the next page's `NextPage` is passed directly to `--page`. Only when the user requests a complete list or needs offline analysis of all skills, or when no pages are hit, use `--page-all`. It is subject to the global `--page-limit` and cannot treat truncated catalogs as complete candidates.
+
+- Do not mix `Items[].Id` and `LatestVersionStatus.VersionId`: for creating an Agent, pass `SkillId` and the semantic version `Version`, not `VersionId`.
+
+## Import from GitHub
+
+GitHub import uses only the public repository's default-branch HEAD. There are no private-repository, branch, or tag options:
+
+```bash
+arkcli agent skill github scan owner/repo --format json
+arkcli agent skill github import https://github.com/owner/repo --path skills/foo --path skills/bar --format json
+arkcli agent skill github import 'npx skills add owner/repo' --all --protection-enabled=true --format json
+arkcli agent skill github import owner/repo --selected @./selected.json --format json
+```
+
+- When constructing a command, prefer the input forms known to the service: `owner/repo`, a complete GitHub HTTPS URL, or a complete `npx skills add ...` string. These are invocation guidelines, not an Agent-side or CLI-side allowlist.
+- Once the user supplies repository input, do not parse, rewrite, or reject it in the Agent or CLI. Pass it unchanged to `ScanGithubSkill.Input` and let the service interpret and validate it. The CLI never starts a shell or executes npx from the input.
+- Repeat `--path`, or use `--all`; they conflict and selections must be valid scan candidates.
+- `--selected` reads an array of `{Path, ProtectionEnabled}` objects and conflicts with global `--protection-enabled`.
+- scan is read-only. import uses Workflow Client Preview; `--dry-run` sends no network requests and leaves scan-dependent values unresolved.
+- All item results (`ok`, `updated`, `skipped_duplicate`, `failed`) are printed. Any failed item makes the command exit nonzero after preserving the complete result.
+
+## Custom Skill Deletion Order
+
+Skill deletion has a strict dependency order. Before deleting anything, use `agent skill versions <id>` to fetch the complete version list and identify the latest version:
+
+1. To delete the entire Skill, delete every non-latest SkillVersion first, delete the latest SkillVersion next, confirm that the version list is empty, and then delete the Skill.
+2. To delete the latest SkillVersion, delete every non-latest SkillVersion first. Delete the latest version only after confirming that it is the only remaining version.
+3. To delete one non-latest SkillVersion, delete that version directly and then fetch the version list again to verify the result.
+
+Re-run `agent skill versions <id>` after every deletion. Do not assume that `DeleteSkill` cascades to versions, and do not call it while any SkillVersion remains. Run each destructive command separately and follow the interactive confirmation or `--yes` requirement.
+
+## Common Commands
+
+```bash
+arkcli agent skill search "Excel data analysis" --source custom --limit 10 --format json
+arkcli agent skill list --source custom --query "Excel data analysis" --limit 20 --format json
+arkcli agent skill list --source custom --name "My analysis data" --limit 20 --format json
+arkcli agent skill list --source custom --limit 100 --format json
+# If the previous page returns `NextPage` and no suitable candidate is found, continue:
+arkcli agent skill list --source custom --limit 100 --page '<NextPage>' --format json
+# Note: --source market is not supported on BytePlus; custom (default), ark, and all are supported.
+arkcli agent skill create --zip ./my-skill.zip --display-title "My Skill" --format json
+arkcli agent skill create --zip ./my-skill.zip --display-title "My Skill" --protection-enabled=true --format json
+arkcli agent skill set-protection skill-xxx --enabled=false --format json
+arkcli agent skill list --source ark --limit 100 --format json
+arkcli agent skill list --source all --limit 100 --format json
+arkcli agent skill github scan owner/repo --format json
+arkcli agent skill github import owner/repo --all --format json
+arkcli agent agent create --name arkcli-local-skill-agent --model <items[].model from agent model list> --skill-zip ./my-skill.zip --format json
+arkcli agent agent create --name arkcli-existing-custom-skill-agent --model <items[].model from agent model list> --skill skill-xxx --format json
+arkcli agent skill update skill-xxx --zip ./my-skill-v2.zip --format json
+arkcli --page-all agent skill versions skill-xxx --format json
+# Replace the placeholder with the selected entry's exact Version from the versions response:
+arkcli agent skill download skill-xxx --version '<Version-from-versions>' --output ./skill-selected-version.zip --format json
+# Omit --version when the user wants latest; the CLI resolves LatestVersion:
+arkcli agent skill download skill-xxx --output ./skill-latest.zip --format json
+# To delete a Skill, delete each non-latest version first:
+arkcli agent skill delete skill-xxx --version <non-latest-version> --yes --format json
+# Fetch versions again and delete latest only after it is the sole remaining version:
+arkcli --page-all agent skill versions skill-xxx --format json
+arkcli agent skill delete skill-xxx --version <latest-version> --yes --format json
+# Fetch versions again and delete the Skill only after the list is empty:
+arkcli --page-all agent skill versions skill-xxx --format json
+arkcli agent skill delete skill-xxx --yes --format json
+```

package/skills/arkcli-agent/references/todo-write.md

@@ -0,0 +1,31 @@
+# Todo Write planning tool
+
+Read this when the user explicitly requests a task-plan/todo tool. `todo_write` is built in and uses Agent create/update `--tool`; it is not a custom tool or a separate Todo CLI command. Product rollout and access remain subject to the BytePlus service; Volc availability is not proof of BytePlus availability.
+
+Use configuration name `todo_write` within `agent_toolset_multimodal_20260825`, never a base toolset such as `agent_toolset_20260701`. It needs no `Models` or tool-model discovery. Do not enable image/video tools just because the toolset name contains multimodal. Stop on permission or unsupported-toolset errors, preserve the error and RequestId, and do not switch toolsets or use Raw API to bypass the rejection.
+
+This is **one toolset entry, not the complete Tools array**. When adding this toolset for Todo only, explicitly disable its defaults to avoid enabling unrelated tools or triggering their model dependencies:
+
+```json
+{
+  "Type": "agent_toolset_multimodal_20260825",
+  "DefaultConfig": {
+    "Enabled": false,
+    "PermissionPolicy": {"Type": "always_allow"}
+  },
+  "Configs": [
+    {
+      "Name": "todo_write",
+      "Enabled": true,
+      "PermissionPolicy": {"Type": "always_allow"}
+    }
+  ]
+}
+```
+
+- Creation: explicit `--tool` replaces all default tools. Combine this entry with the complete base-tool configuration the user needs; passing this entry alone drops other tools.
+- Update: first run `arkcli agent agent get <agent-id> --format json`. If the toolset already exists, merge the Todo configuration into it without adding a duplicate or overwriting its DefaultConfig with this example. Preserve other tools, model bindings, and PermissionPolicy, even if the frontend hides permission controls.
+- Submit with `arkcli agent agent update <agent-id> --tool '<complete Tools JSON array>' --format json`, then read back. To disable Todo, set its Enabled to false while retaining other settings.
+- For runtime verification, create a Session bound to the updated Agent version; do not assume an existing Session inherits the update. Ask it to use Todo to maintain a plan and inspect tool events. An accepted configuration alone is not proof of a tool invocation.
+
+Runtime events may use `todo_write` or `TodoWrite` depending on BaseAgent; configuration always uses `todo_write`. Agent Loop executes it internally, so no custom-tool implementation or manually returned custom-tool result is needed.

package/skills/arkcli-api-explorer/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: arkcli-api-explorer
+version: 0.2.0
+description: Inspect or invoke locally registered BytePlus ArkCLI actions when product commands cannot cover a task. Use for registry errors or exact raw payloads. Public catalogs and OpenAPI schemas use arkcli-docs.
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli api --help"
+---
+
+# BytePlus Raw API Explorer
+
+Before using this Skill:
+
+1. Read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) for the
+   BytePlus product boundary, authentication, output, and confirmation rules.
+2. Read
+   [`references/arkcli-api.md`](references/arkcli-api.md) before constructing
+   any `arkcli api` invocation.
+
+Raw API Explorer is the final fallback, not the default command path.
+
+## When To Trigger
+
+- The user explicitly names an action, operation, registry entry, or raw
+  request contract.
+- `arkcli api ...` returns `unknown action` or rejects `--params`.
+- A contributor needs to confirm that a registered operation is visible and
+  routed to the expected protocol and target.
+- No stable product command covers a specialized data-plane operation.
+
+## When NOT To Trigger
+
+- Public API catalogs, identifiers, OpenAPI schemas or required request fields
+  belong to [`arkcli-docs`](../arkcli-docs/SKILL.md) and `docs apis list/spec`.
+  `api --list` only lists locally compiled actions, not the public API catalog
+  or complete OpenAPI schemas.
+- A stable product command or workflow covers the goal, including model
+  discovery, generation, deployment, Endpoint management, usage, profile, or
+  billing.
+- The problem is missing login, `401`, permissions, profile selection, Region,
+  or base URL. Diagnose authentication or configuration first.
+- The action contract is unknown. Do not guess a payload merely because an
+  action name appears in the registry.
+
+## Command selection order
+
+1. Check the owning product command and Skill.
+2. Use `arkcli <domain> --help` or `arkcli +<workflow> --help`.
+3. If no product command applies, list the local registry.
+4. Confirm the exact BytePlus request contract.
+5. Apply authentication, verification, and write guards.
+6. Invoke the registered action and extract only the fields the task needs.
+
+## Registry boundary
+
+```bash
+arkcli api --list
+arkcli api
+```
+
+Both commands list the actions compiled into the local binary, sorted by name.
+List mode is local and does not require authentication.
+
+A registry entry proves only that the client knows an operation descriptor. It
+does not prove that the active BytePlus account, service, Region, or product
+contract supports that action. Require a matching BytePlus capability Skill or
+an authoritative BytePlus API contract before invocation. Never switch to
+another product to make an action succeed.
+
+## Invocation contract
+
+```bash
+arkcli api <registered-action> --params '<json-object>'
+
+# Local client preview: validates and displays the descriptor and payload
+# without creating a transport or sending a request.
+arkcli api <registered-action> --params '<json-object>' --dry-run
+```
+
+- `<registered-action>` must exactly match a name from `arkcli api --list`.
+- `--params` is an optional JSON object string and defaults to `{}`.
+- Field names and casing come from the action request contract; do not infer
+  them from the action name.
+- `--dry-run` is a local flag of Raw API invoke mode. It emits a
+  `preview.v1` plan with a redacted `steps[0].payload` and does not contact
+  BytePlus services.
+- `arkcli api --list --dry-run` is invalid because list mode is already a
+  local registry read and has no remote request to preview.
+- Prefer `--format json` and a global `--transform` expression for stable
+  machine-readable output.
+
+Example of a data-plane fallback without a dedicated product command:
+
+```bash
+# Text embeddings (/embeddings); discover the versioned model id first:
+#   arkcli models list --modality embed
+arkcli api arkruntime.create_embeddings \
+  --params '{"model":"<text-embedding-model-id>","input":"BytePlus Ark"}' \
+  --transform 'data.0.embedding'
+```
+
+Replace the model placeholder with a versioned ID available to the active
+BytePlus profile (not a display name or bare family name). Vision/multimodal
+embedding models (e.g. `skylark-embedding-vision-*`) cannot use this action:
+they return 400 "does not support this api" and must go through
+`arkruntime.create_multimodal_embeddings` (`/embeddings/multimodal`).
+
+## Authentication and verification
+
+- Run `arkcli auth status --format json` before a remote control-plane action.
+- Data-plane actions require an active API key resolved through the selected
+  BytePlus profile.
+- Do not call account-opening or payment-verification actions directly. Use
+  the combined `byteplus_sso.identity.verified` contract exposed by
+  `arkcli auth status`.
+- A billable write must follow the shared BytePlus verification gate and
+  explicit confirmation rules.
+
+## Write guard
+
+Raw API invoke mode supports a command-local Client Preview:
+
+```bash
+arkcli api <action> --params '<json-object>' --dry-run --format json
+```
+
+Inspect `mode=client_preview`, `steps[0].target`, and
+`steps[0].payload`. Preview success does not prove authentication,
+permission, quota, account verification, Region support, or server-side
+validation.
+
+A `"DryRun":true` member inside `--params` is a backend request field, not the
+CLI Client Preview flag. Without CLI `--dry-run`, the command still creates a
+transport and sends a real network request.
+
+For create, update, delete, activation, credential rotation, or billing
+actions:
+
+1. Prefer the guarded product command when one exists.
+2. Resolve the exact action and payload.
+3. Run the exact invocation once with CLI `--dry-run` and inspect the plan.
+4. Show the target and impact to the user.
+5. Obtain explicit confirmation.
+6. Remove CLI `--dry-run` and invoke only the confirmed payload.
+
+## Pagination and output
+
+- `--page-all` has special Raw API behavior only for `apikey.list`.
+- Other actions are passed through once; `--page-all` does not invent or
+  mutate their pagination fields.
+- Use `--debug` only for diagnosis because it writes request and response
+  details to stderr.
+- Do not expose tokens or full keys in debug output or copied results.
+
+## Common errors
+
+| Error | Meaning | Recovery |
+|---|---|---|
+| `unknown action "..."` | The exact name is not registered | Run `arkcli api --list`; do not guess a replacement |
+| `invalid --params JSON: ...` | The payload is not a valid JSON object | Validate quoting, commas, and field casing |
+| Authentication or permission error | The action reached a remote boundary without usable credentials or permission | Return to `arkcli-auth`; do not retry blindly |
+| Unexpected response fields | The assumed contract was wrong or changed | Re-check the exact BytePlus contract before parsing |
+
+## Guard Checklist
+
+- Keep Raw API Explorer as the last fallback.
+- Require an exact registered action name and exact BytePlus payload contract.
+- Treat registry presence and product support as different facts.
+- Route authentication and configuration failures to their owning Skills.
+- Use command-local `--dry-run` to preview a raw action, but never treat it as
+  server validation or permission verification.
+- Never treat payload `"DryRun":true` as a local preview.
+- Confirm every write target and impact.
+- Use `auth status`, not direct verification actions, for the combined
+  BytePlus gate.
+- Preserve structured backend errors and request IDs.
+
+## References
+
+- [`references/arkcli-api.md`](references/arkcli-api.md) - detailed command,
+  parameter, pagination, authentication, and safety contract
+- [`references/evals.md`](references/evals.md) - trigger, fallback, and write
+  safety evaluations
+- [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md) - authentication and
+  verification recovery
+- [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md) - effective
+  profile, Region, project, and base URL diagnosis