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

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

@@ -0,0 +1,105 @@
+# resources list detailed reference
+
+> **Prerequisite**: Read [`../SKILL.md`](../SKILL.md) first.
+
+## Flag overview
+
+| Parameter | Required | Default | Description |
+|------|------|------|------|
+| `--profile` | No | active | Explicit target profile; uses `RebuildForProfile` after the P0-A correction to switch identity for the control-plane request |
+| `--modality` | No | `text` | `text` / `image` / `video` |
+
+## Dispatch logic
+
+```
+profile.Type:
+  platform   → ListEndpoints (PageAll) lists all active endpoints by modality
+               filtering (Endpoint.ModelReference.FoundationModel.name
+               → GetFoundationModel → task_types/filter_task_types;
+               unknown stays visible with modality_confidence=unknown and a stderr warning)
+  coding-plan
+    text     → ListCodingPlanVirtualModelID (Edition=personal, BizInfo=PlanTier)
+    image    → uses platform ListEndpoints + modality filter (S10, commit f69be53)
+    video    → same as image
+  coding-plan-team
+    text     → ListCodingPlanVirtualModelID (Edition=enterprise, BizInfo=seat tier)
+    image/video → platform Endpoint pool; invocation requires a compatible pay-as-you-go API key
+```
+
+## Endpoint modality contract
+
+The platform path uses this control-plane relationship:
+
+```text
+Endpoint ID
+  -> ModelReference.FoundationModel.name
+  -> GetFoundationModel
+  -> task_types / filter_task_types
+  -> text | image | video | unknown
+```
+
+- Endpoint names, FoundationModel names, and display names are identifiers, not capability evidence.
+- Dola, Dreamina, Seedream, Seedance, and future branding may appear in examples, but must never be used as image/video routing rules.
+- Missing, unknown, or conflicting task metadata produces `modality_confidence="unknown"`. The item remains visible with a warning for review, but selecting it as a modality default or generating through it still requires authoritative metadata or an explicit `--modality`.
+
+## Resolve an Endpoint
+
+When the user supplies an Endpoint and needs its binding, workflow, modality,
+or Region, run:
+
+```bash
+arkcli resources resolve <endpoint-id> --format json
+```
+
+Interpret the binding fields before the capability fields:
+
+- `endpoint_model_type="CustomModel"`: `model_id` and `custom_model_id` are
+  the same bound `cm-...` ID. `base_model_*` is lineage and the authoritative
+  source for task, API, and modality capabilities; it is not the Endpoint's
+  bound identity.
+- `endpoint_model_type="FoundationModel"`: `model_id` retains its existing
+  foundation-model meaning and `custom_model_id` is absent.
+- If Custom Model lineage metadata cannot be loaded, preserve the known
+  `model_id == custom_model_id`, keep capabilities unknown, and inspect
+  `resolution_warnings`. Never substitute `base_model_id` or guess from names.
+
+Use `supported_workflows`, `generation_modality`, and `requires_user_intent`
+only after the binding has been interpreted. `resource_region` is the
+authoritative Endpoint Region for a stateless Endpoint plus API key call.
+
+## Output format
+
+```json
+{
+  "profile": "<name>",
+  "type": "<platform | coding-plan>",
+  "modality": "<text|image|video>",
+  "items": [
+    {"id": "<id>"},
+    {"id": "<id>", "is_default": true}
+  ],
+  "current_default": "<id-or-empty>",
+  "item_count": <n>
+}
+```
+
+`is_default` appears only when items[].id matches `Resources.<modality>.Default` in profile.yaml.
+
+## Differences from the old list format (before 0.1.16)
+
+Version 0.1.16 removed all static `profile.AvailableTextModels` / `AvailableImageModels` / `AvailableVideoModels` lists (S2). All data is now fetched in real time through `resources list`. This means:
+
+- Logic in old scripts that reads `profile.yaml.available_text_models` no longer works.
+- When an Agent needs the "available model list", it MUST run `resources list` and cannot assume that profile.yaml contains it.
+- profile.yaml now stores only defaults (`Resources.<modality>.Default`), not available lists.
+
+## Difference from `arkcli api ListEndpoints`
+
+| Dimension | `arkcli resources list` | `arkcli api ListEndpoints` |
+|------|------------------------|----------------------------|
+| Entry point | Product command (shortcuts) | Raw API explorer |
+| Dispatch | Routes endpoint / plan / coding by profile.Type | Always ListEndpoints |
+| Output | Minimal `[{"id": ...}, ...]` | All Endpoint fields |
+| Identity scope | `RebuildForProfile` switches to the target identity | Uses the active profile |
+
+Agents should prefer `arkcli resources list` and fall back to `arkcli api ListEndpoints --params ...` only when full Endpoint fields (status / quota / created_at) are required.

package/skills/arkcli-shared/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: arkcli-shared
+version: 0.3.0
+description: "Shared Ark CLI execution protocol for BytePlus: first-use setup, authentication gates, command routing, structured output, safety, confirmation handling, version checks, and explicit upgrades. Trigger directly when the user asks whether Ark CLI is current, requests a live version refresh or upgrade, or when any other arkcli-* Skill needs common context."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli --help"
+---
+
+# Ark CLI shared protocol for BytePlus
+
+Read this file before using any other `arkcli-*` Skill. Keep common execution,
+authentication, output, and safety rules here instead of duplicating them in
+each capability Skill.
+
+## When To Trigger
+
+- before using any other BytePlus `arkcli-*` Skill;
+- on first use, before the owning capability is known;
+- when authentication, profile, output, confirmation, or command-routing rules
+  are needed by more than one capability;
+- when the user asks whether Ark CLI is current, requests a live registry
+  refresh, or explicitly asks to upgrade Ark CLI.
+
+## When NOT To Trigger
+
+Except for the version-check and explicit-upgrade workflow owned by
+[`references/update.md`](references/update.md), this shared protocol is not the
+final destination for a capability-specific task. After applying the common
+rules, continue with the owning BytePlus Skill. Do not use this file as a
+substitute for command-specific flags, output fields, or recovery guidance.
+
+## References
+
+Load detailed shared guidance only when needed:
+
+| Situation | Reference |
+|---|---|
+| Global flag or runtime override diagnosis | [`references/global-flags.md`](references/global-flags.md) |
+| Default model or Endpoint selection | [`references/profile-defaults.md`](references/profile-defaults.md) |
+| Version status, live refresh, or explicit Ark CLI upgrade | [`references/update.md`](references/update.md) |
+| Control-plane versus data-plane credential recovery | [`../arkcli-auth/references/auth-modes.md`](../arkcli-auth/references/auth-modes.md) |
+| Resolving resources owned by the current identity | [`../arkcli-auth/references/identity-resolution.md`](../arkcli-auth/references/identity-resolution.md) |
+| Account-opening and payment verification before billable writes | [`../arkcli-auth/references/realname-gate.md`](../arkcli-auth/references/realname-gate.md) |
+| Unclassified command failure | [`references/troubleshooting.md`](references/troubleshooting.md) |
+
+## Product boundary
+
+- This Skill set is for the standalone BytePlus product.
+- Do not switch to another tenant or reuse credentials, Regions, endpoints, or
+  local state from another product.
+- Ark CLI stores BytePlus state under `~/.arkcli-bp/`.
+- The control-plane Region is fixed to `ap-southeast-1`; another Region is
+  invalid and must not be used as a fallback.
+- The control-plane environment is `prod` by default. Use `--env stg` only
+  when the user explicitly requests the BytePlus staging environment.
+- BytePlus supports the `en_us` UI locale only.
+- Load [`references/update.md`](references/update.md) for version checks and
+  explicit upgrades. Route `update.mode` reads, writes, and automatic-gate
+  interpretation to [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md).
+
+## Command selection order
+
+Choose commands from the user's goal, not from an API action name.
+
+### Control plane vs data plane
+
+Different commands use different credentials. Passing `--api-key` / `--base-url` to a command that
+does not consume data-plane overrides fails fast, so do not treat them as universal credentials.
+
+| Capability | Plane | Credential | Constraint |
+|---|---|---|---|
+| Model catalog, Endpoint, custom model, Dataset, fine-tuning, usage/billing management | **Control plane** | BytePlus SSO-derived STS (`arkcli auth status` / `auth login`) | Does not consume `--api-key` / `--base-url`; an API key from `.env` is for inference only |
+| `+chat` / `+gen` / `+understand` / Managed Agent session and files / raw runtime calls | **Data plane** | Profile API key, plan seat key, or explicit `--api-key` (with `--base-url` when required) | Inference/session only; do not use it to change control-plane resources |
+
+Fine-tuning is a control-plane workflow, not a plan-model inference call. `train finetune create` rejects
+`--api-key`. Use `--train-file` / `--validation-file` so ArkCLI uploads local data to managed TOS, and do
+not route SFT / LoRA / DPO / RL to `+chat` or `+gen`.
+
+For explicit documentation requests, a documentation URL, or missing product
+knowledge delegated by an owning Skill, use [docs](../arkcli-docs/SKILL.md).
+Read the returned Markdown before answering. Do not replace resource operations,
+authentication, diagnosis or CLI help with documentation search.
+
+1. Prefer a product command: `arkcli <domain> <verb>` or
+   `arkcli +<workflow>`.
+2. Read the capability reference before executing a documented command.
+3. Use the API Explorer only when no product command covers the task.
+4. Execute read-only operations directly. Confirm user intent before writes,
+   deletion, credential rotation, or default-profile changes.
+
+Do not require an Endpoint for a one-off model trial. Use a task workflow such
+as chat or generation when that capability is available. Use Endpoint commands
+for stable production integration.
+
+## AI Skill invocation protocol
+
+Every `arkcli` command executed by an AI Agent through an `arkcli-*` Skill must
+use the complete single-command prefix below. It records the caller and owning
+Skill while freezing the installed CLI version for the whole Skill workflow:
+no implicit registry refresh, update notice, or automatic apply scheduling may
+run between commands.
+
+```bash
+ARKCLI_NO_UPDATE_NOTIFIER=1 \
+ARKCLI_CALLER_TYPE=ai_agent \
+ARKCLI_CALLER_NAME=<agent-id> \
+ARKCLI_SKILL_NAME=<current-arkcli-skill> \
+arkcli <command> ...
+```
+
+- Use a stable Agent ID such as `codex`, `claude-code`, `opencode`, `openclaw`,
+  `trae`, or `cursor`; use `unknown_agent` only when it cannot be determined.
+- Set `ARKCLI_SKILL_NAME` to the actual owning capability. Use
+  `arkcli-shared` only when this Skill directly owns a version check or explicit
+  upgrade; never use it for another capability's workflow.
+- Apply the full prefix to every `arkcli` command in a multi-command workflow,
+  not only the first command.
+- Despite its compatibility name, `ARKCLI_NO_UPDATE_NOTIFIER=1` suppresses all
+  implicit update activity: cache checks/refreshes, notices, and automatic
+  apply scheduling. It does not block an explicit user-requested
+  `arkcli update` or `arkcli update --check`.
+- Keep the variables scoped to one command; do not export them into unrelated
+  shell work.
+
+## Authentication gate
+
+Except for authentication commands, profile inspection, local Skill listing,
+and `arkcli update ...`, check authentication before a remote business command.
+
+**Pending authorization takes precedence over starting another login.** If this turn or the user supplies a previous `stage=authorize_pending` and the user has neither completed authorization nor returned a code, wait. Do not rerun any `auth login`, `config init`, or the original business command. One read-only `auth status` check is allowed: resume if the required valid credentials already exist; `logged_in=false` alone does not establish that the pending session expired or disappeared, so keep waiting. Restart Phase 1 only after an explicit CLI session-expired/missing error or an explicit user request to restart login.
+
+1. Run `arkcli auth status --format json`.
+2. If the session is valid, continue the original task.
+3. If the session is missing or expired, tell the user that BytePlus SSO is
+   starting, then run `arkcli auth login`.
+4. In a non-browser or non-interactive environment, use the two-phase flow:
+
+```bash
+arkcli auth login --no-browser
+arkcli auth login --no-browser --code <authorization-code>
+```
+
+5. After login succeeds, resume the original task. Authentication is an
+   intermediate step, not the final result.
+
+Do not print, persist, or echo full tokens, access keys, secret keys, or API
+keys.
+
+## Account verification gate
+
+Before model activation, deployment, inference Endpoint creation, fine-tuning
+creation, or Managed Agent creation, run:
+
+```bash
+arkcli auth status --format json
+```
+
+Read `byteplus_sso.identity.verified` before executing one of these billable
+writes:
+
+- `true`: continue.
+- `false`: stop, send the user to
+  `https://console.byteplus.com/user/basics/`, and wait for the user to finish
+  both account-opening and payment verification.
+- absent: the result is unknown; continue without claiming either state and
+  preserve any structured backend error.
+
+See
+[`../arkcli-auth/references/realname-gate.md`](../arkcli-auth/references/realname-gate.md)
+for the exact two-check contract and failure rules.
+
+## Output contract
+
+- Prefer `--format json` or `--format yaml` for automation.
+- Use `--transform` when the next step needs a stable field rather than the
+  full response.
+- Treat stdout as structured business output. Send explanations, diagnostics,
+  and errors to stderr.
+- Do not parse decorative or table-formatted text when structured output is
+  available.
+
+## Confirmation handling
+
+For destructive, credential-changing, or cost-sensitive operations:
+
+1. Confirm the exact target, scope, and cost or destructive impact before
+   adding `--yes` or otherwise authorizing the write.
+2. If Ark CLI returns `type="requires_confirmation"`, treat it as a normal
+   interaction boundary and show the action and its
+   impact to the user.
+3. After confirmation, repeat the same command with `--yes`.
+4. If the user declines, stop without changing state.
+
+## Guard Checklist
+
+- Do not use the API Explorer as the default entry point.
+- Do not retry business commands repeatedly before checking authentication and
+  configuration.
+- Do not treat login, model lookup, or profile selection as the user's final
+  outcome when the original task still has remaining steps.
+- Do not invent invocation-global `--project-name` or `--region` overrides.
+  Select or update a profile for runtime project and Region scope. Use a
+  command-local project/Region flag only when that exact command documents it
+  for its own resource or query semantics.
+- Do not infer BytePlus support from a similarly named command or Skill in
+  another product. Use the installed BytePlus command help and the matching
+  BytePlus capability Skill.

package/skills/arkcli-shared/references/global-flags.md

@@ -0,0 +1,77 @@
+# Global flags
+
+Read this reference when building a complex command or diagnosing profile,
+data-plane, environment, or output overrides. Command-specific flags remain
+authoritative in `arkcli <domain> <verb> --help`.
+
+| Flag | Purpose |
+|---|---|
+| `--profile` | Select the active profile for this command. |
+| `--api-key` | Override the ARK API key for this command. |
+| `--base-url` | Override the data-plane base URL. |
+| `--env` | Select the BytePlus control-plane environment: `prod` or `stg`. |
+| `--lang` | Select the UI locale. BytePlus accepts `en_us` only. |
+| `--ui-lang` | Unambiguous alias for the global UI locale when a command has a historical local `--lang` flag. BytePlus accepts `en_us` only. |
+| `--format` | Select `json`, `yaml`, `table`, `csv`, `jsonl`, or `pretty`. Automation should prefer `json` or `yaml`. |
+| `--transform` | Extract a stable field or subtree from structured output. |
+| `--page-all` | Follow all available pages. |
+| `--page-limit` | Limit automatic pagination. |
+| `--page-delay` | Set the delay between pages in milliseconds. |
+| `--debug` | Send diagnostic details to stderr. |
+
+`--dry-run` is not a global flag. Only a leaf command with Client Preview
+support registers it; verify the leaf command's `--help`. A supported preview
+emits local `preview.v1` output without network access, filesystem writes, or
+subprocesses. An unsupported leaf rejects the flag explicitly.
+
+## Override diagnosis
+
+When persisted profile values and runtime behavior differ:
+
+1. Run `arkcli auth status --format json` and `arkcli auth whoami --format json`
+   to inspect the masked runtime identity/Profile summary.
+2. Use `arkcli resources list --format json` for defaults and routing. Reserve
+   `profile show/list/keys list` for explicit Profile management after warning
+   that they may synchronize remote keys and write back the local key inventory
+   or default key.
+3. Check supported invocation flags and environment variables before changing
+   the profile. `--region`, `--project-name`, `ARK_REGION`, and
+   `ARK_PROJECT_NAME` are not runtime override mechanisms.
+4. Keep BytePlus local state under `~/.arkcli-bp/`; do not inspect or modify a
+   different product's state directory.
+
+## Important precedence rules
+
+```text
+profile:
+  --profile > ARK_PROFILE > config default_profile
+  > first platform profile > default sentinel
+
+project:
+  active profile project > bound identity fallback > default
+
+control-plane environment:
+  --env > ARK_CLIENT_ENV > active profile env > prod
+
+Region:
+  active profile region > BytePlus fixed ap-southeast-1
+
+temporary data-plane API key:
+  --api-key > ARK_API_KEY > active profile > bound identity
+
+temporary data-plane base URL:
+  --base-url > ARK_BASE_URL > active profile
+  > product/profile derivation > BytePlus default
+```
+
+An explicit unsupported environment, Region, or locale is an input error. Do
+not silently replace it with another product or Region.
+
+`--base-url` affects the data plane. `--env` selects the BytePlus control-plane
+environment. Do not use one as a substitute for the other.
+
+An explicit `--base-url` or `ARK_BASE_URL` must be accompanied by an explicit
+`--api-key` or `ARK_API_KEY`. This prevents a profile API key from being sent
+to an overridden endpoint. For `+chat`, `+understand`, and `+gen`, an explicit
+API key plus an endpoint ID may derive the missing BytePlus base URL from
+authoritative endpoint metadata.

package/skills/arkcli-shared/references/profile-defaults.md

@@ -0,0 +1,35 @@
+# Profile resource defaults
+
+Read this reference only when chat, generation, or deployment needs a default
+model or Endpoint. Ordinary read-only resource queries do not need it.
+
+Profiles may store a default resource per modality:
+
+- `text`
+- `image`
+- `video`
+
+The default may be a model ID or an Endpoint ID depending on the active
+profile and the capability contract. Never infer one form from the other.
+
+## Selection rules
+
+1. If the user passes `--model` or `--endpoint`, use the explicit value after
+   validating that the active BytePlus capability supports it.
+2. If the user omits the value, let Ark CLI resolve the profile default.
+3. If Ark CLI reports that no default exists, list compatible resources first,
+   then ask the user which one should become the default.
+4. Do not silently select a resource from another Region, project, account, or
+   product.
+
+## Drift prompt
+
+After a successful command that used an explicit resource different from the
+current default, offer to promote it:
+
+> This command used `<new>`, while the current `<modality>` default is `<old>`.
+> Set `<new>` as the new default?
+
+Only update the profile after the user confirms. Do not prompt after a failed
+command, when the command already used the default, or when the user has
+declined the same suggestion in the current session.

package/skills/arkcli-shared/references/troubleshooting.md

@@ -0,0 +1,49 @@
+# Troubleshooting and capability boundaries
+
+Read this reference when a command fails and the failure has not yet been
+classified.
+
+## Failure routing
+
+1. Classify the failure before retrying:
+   - authentication or expired credentials;
+   - runtime override or profile configuration;
+   - invalid arguments;
+   - missing model, Endpoint, or other resource;
+   - unsupported BytePlus capability;
+   - missing external dependency or permission.
+2. For authentication failures, run `arkcli auth status --format json` and use
+   the `arkcli-auth` Skill.
+3. For profile, Region, project, API key, or base URL confusion, use
+   `arkcli auth whoami --format json` for the current identity/Profile summary
+   and `arkcli resources list --format json` for defaults and routing. Use
+   `profile show/list/keys list` only for an explicit Profile-management task
+   after warning that they may synchronize remote keys and write back the local
+   key inventory or default key.
+4. For an unknown resource identifier, use the corresponding list or search
+   command instead of guessing.
+5. If the product command does not cover the task, inspect the installed
+   BytePlus command help and the matching BytePlus capability Skill before
+   considering the raw API explorer.
+
+## Error meaning
+
+Keep these outcomes distinct:
+
+- the product does not support the capability;
+- the current account lacks permission;
+- the resource does not exist or is outside the active scope;
+- the Region is unsupported;
+- an external service, SDK, or entitlement is not enabled.
+
+Do not reinterpret an authorization error as proof that the product lacks the
+capability. Do not reinterpret a missing BytePlus command as a permission
+issue.
+
+## Retry rules
+
+- Retry only operations documented as safe and idempotent.
+- Refresh authentication once when the status explicitly reports expiry.
+- Do not loop over business commands after repeated 401, 403, or scope errors.
+- For writes, preserve the original request and ask for confirmation before a
+  retry that could create duplicate resources or additional cost.

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

@@ -0,0 +1,117 @@
+# Version checks and explicit upgrades
+
+This reference only answers whether the installed BytePlus Ark CLI is current
+and applies an upgrade that the user explicitly requested. It does not access a
+business account, so do not run `auth status` first.
+
+The reading and writing of `update.mode`, its default, and automatic production
+gates belong to
+[`../../arkcli-config/SKILL.md`](../../arkcli-config/SKILL.md). Never infer
+active automatic consent from a discovered release or postinstall enrollment.
+The config Skill owns fresh-install pending evidence, registry-latest
+reconciliation, exact-receipt rotation, and persistent version pins.
+
+Every Agent invocation in this reference must retain the
+`ARKCLI_CALLER_TYPE=ai_agent` metadata below. Besides attribution, it ensures an
+AI Skill never consumes human enrollment grace, activates exact consent, or
+schedules automatic work. Do not remove caller metadata to imitate a human
+command.
+
+## Check only
+
+Read the zero-network local cache first:
+
+```bash
+ARKCLI_NO_UPDATE_NOTIFIER=1 \
+ARKCLI_CALLER_TYPE=ai_agent \
+ARKCLI_CALLER_NAME=<agent-id> \
+ARKCLI_SKILL_NAME=arkcli-shared \
+arkcli --format json update --check
+```
+
+Interpret `status`, not only the compatibility field `update_available`:
+
+| `status` | Meaning | Agent action |
+|---|---|---|
+| `unknown` | No valid cache exists for this distribution | Report unknown; use `--refresh` only when a live answer is needed |
+| `up_to_date` | Cache or registry confirms current is not older than latest | Report up to date and include `source` |
+| `update_available` | `latest` is strictly newer than `current` | Report the version delta; do not update automatically |
+
+`source` is `none`, `cache`, or `registry`; `checked_at` records the cache or
+query time. Refresh only when the user needs a live answer:
+
+```bash
+ARKCLI_NO_UPDATE_NOTIFIER=1 \
+ARKCLI_CALLER_TYPE=ai_agent \
+ARKCLI_CALLER_NAME=<agent-id> \
+ARKCLI_SKILL_NAME=arkcli-shared \
+arkcli --format json update --check --refresh
+```
+
+`--refresh` queries the npm registry embedded in the current binary. Preserve
+registry failures. Never present stale cache data as a live result, and never
+interpret `status=unknown` as no update or up to date.
+
+## Explicit upgrade
+
+Enter the write flow only when the user explicitly asks to upgrade in the
+current turn. Check first, show `current -> latest` and the distribution, then
+obtain confirmation. Add `--yes` to a non-interactive invocation only after
+that confirmation:
+
+```bash
+ARKCLI_NO_UPDATE_NOTIFIER=1 \
+ARKCLI_CALLER_TYPE=ai_agent \
+ARKCLI_CALLER_NAME=<agent-id> \
+ARKCLI_SKILL_NAME=arkcli-shared \
+arkcli update --yes
+```
+
+Explicit `arkcli update` and `arkcli update --check` remain available in every
+mode. `disabled` stops only silent installation. `disabled` still allows implicit checks and version notices.
+
+After a background automatic patch update commits and releases its update locks,
+the newly installed binary silently runs bare `+connect` once. The matching
+BytePlus CDN Skills have already been staged with that version, so this reads
+the local snapshot without `--refresh`. Output goes to `update-apply.log`.
+If Agent Skill sync fails, the CLI update remains committed; inspect the log
+and retry with `arkcli +connect`.
+
+For a persistent version pin, do not only downgrade with npm. Instruct the user
+to persist `arkcli config set update.mode disabled` before installing an exact
+version. A reinstall never reuses the old exact receipt: current latest
+preserves the mode and reissues consent for existing `automatic`, while
+non-latest persists `disabled`. Installing `@latest` does not turn `disabled`
+back into `automatic`; recover by installing latest and then explicitly setting
+automatic.
+
+`update` launches npm and is classified as `opaque_external_execution`; it
+does not support `--dry-run`. Do not invent Client Preview or bypass the
+product command with a raw API. Use the version delta and explicit confirmation
+as the safety boundary.
+
+Report success only when npm finishes, the package under the same npm global
+root equals `latest`, and the npm-managed target executable's `--version` also
+equals `latest`. Never report success after a command or verification failure.
+
+## Failure and platform routing
+
+- Missing npm: relay the CLI's manual command; do not install Node or npm.
+- npm prefix, Node, or NVM mismatch: stop and ask the user to activate the Node
+  environment that installed this Ark CLI. Never update a different PATH
+  prefix.
+- Non-npm running binary: explain that the current copy is unaffected. A
+  verified npm package still does not mean that copy changed.
+- On Windows, the immediate explicit-update result is only scheduled. Report
+  completion only after a new `arkcli --version` shows the target or
+  `update-apply.log` records `installed and verified`.
+- Preserve the previous installation, logs, and `.arkcli-update-*` recovery
+  directories after a Windows failure. Never describe failure as partial
+  success.
+- On macOS and Linux, explicit update retains manual npm-upgrade semantics. Do
+  not describe the automatic atomic-cutover path as part of the explicit
+  command.
+
+Do not simulate automatic updates with cron, a system service, or an Agent
+scheduled task. Never interrupt a normal business command or change its exit
+code because an update exists.