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

package/skills/arkcli-profile/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: arkcli-profile
+version: 0.2.1
+description: "Manage product-isolated BytePlus profiles: inspect and select profiles, create supported profile types, re-select project scope, synchronize API keys and Coding Plan models, and choose default resources."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli profile --help"
+---
+
+# BytePlus profiles
+
+Read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) before using this
+Skill.
+The entire profile domain manages local identity state and rejects
+`--dry-run`. Use `auth status/whoami` for ordinary admission and `resources`
+for resource/default discovery. Reserve `profile show/list/keys list` for an
+explicit Profile task: explain first that these commands can synchronize
+remote keys and write back the local key inventory or default key. Obtain
+explicit confirmation for mutations.
+
+A profile is a local BytePlus configuration slice that binds a profile type,
+the fixed BytePlus Region, project scope, identity, API keys, and default
+resources. Selecting a profile does not switch product or tenant.
+
+## Distinguish inspection from management
+
+- A read-only check of identity, default-resource visibility or credential compatibility is not Profile management, even when the user supplies a profile name or type. Load the Auth and Resources Skills and hand off to them. Missing information does not authorize `profile show/list/keys list`.
+- Before invoking `show/list/keys list` for an explicit Profile management task, send user-visible text stating both effects: online synchronization with the remote API key source, and possible writeback to local key inventory or the default key. For example: "This management query may synchronize remote API keys online and write back local key inventory or the default key."
+- Saying "I will explain" is only a plan. Tool descriptions, private reasoning and the final answer after execution do not replace this disclosure. Do not describe these management queries as purely read-only or claim that local keys were unchanged without evidence.
+
+## Supported profile types
+
+| Type | Purpose |
+|---|---|
+| `platform` | Pay-as-you-go Platform Endpoint and inference usage. |
+| `coding-plan` | Personal Coding Plan usage. |
+| `coding-plan-team` | Coding Plan Team usage through an assigned seat. |
+
+Do not suggest another profile type. The BytePlus Region is fixed to
+`ap-southeast-1`.
+
+## When To Trigger
+
+- listing profiles or identifying the active profile;
+- switching the local default profile;
+- creating or deleting a supported BytePlus profile;
+- changing the active project scope;
+- synchronizing or selecting profile API keys;
+- inspecting Coding Plan model defaults;
+- selecting a default text, image, or video resource.
+
+## When NOT To Trigger
+
+Use [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md) for login and credential
+health. Use [`../arkcli-resources/SKILL.md`](../arkcli-resources/SKILL.md) to
+list resources currently visible to a profile.
+Do not use profile mutation as a fallback for a missing resource, permission
+error, or unsupported capability.
+
+## Profile resolution
+
+The effective profile is selected in this order:
+
+```text
+--profile
+  > ARK_PROFILE
+  > config default_profile
+  > first valid platform profile
+  > default sentinel
+```
+
+For commands that accept `--profile <name>`, Ark CLI uses that profile's
+identity and configuration for the operation. It does not merely change the
+name of the output target.
+
+## Project scope
+
+BytePlus can operate in a named project or across the account:
+
+- `All account resources` is the user-facing account-wide option;
+- account-wide profile names use the `accountwide` segment, for example
+  `platform_ap-southeast-1_accountwide`;
+- the account-wide internal sentinel is an implementation detail and must not
+  be copied into commands or output explanations.
+
+First login selects account-wide by default. Manual `profile create` keeps its
+documented `default` project fallback unless the user selects or supplies
+another project.
+
+`arkcli profile project [<project-name>]` changes project scope without
+reauthenticating, but it is not a simple field update:
+
+```text
+existing platform profile
+  |
+  +-- delete
+  |
+  +-- create a fresh platform profile for the selected project
+  |
+  +-- refresh Coding Plan subscription and team-seat profiles
+        |
+        +-- update or create profiles available in the new project
+        +-- remove profiles not available in the new project
+```
+
+The command requires confirmation and does not support `--dry-run`. Without a
+positional project name, it loads the selectable BytePlus projects and includes
+`All account resources`.
+
+## Command map
+
+| Command | Behavior |
+|---|---|
+| `arkcli profile list` | List local profiles and identify the default. |
+| `arkcli profile show [profile]` | Show one profile with masked secrets and the derived data-plane URL. |
+| `arkcli profile use [profile]` | Change the local default profile. |
+| `arkcli profile create` | Create `platform`, `coding-plan`, or `coding-plan-team`. |
+| `arkcli profile delete <profile>` | Delete a local profile; use `--yes` only after confirmation. |
+| `arkcli profile rename <profile> --to <display-name>` | Change only the display label, not the internal profile key. |
+| `arkcli profile project [<project-name>]` | Replace the Platform project slice and refresh Coding Plan profiles. |
+| `arkcli profile apikey list|use|refresh` | Inspect, select, or synchronize the profile-specific ordinary or team-seat API key source; an empty refresh fails without clearing local keys. |
+| `arkcli profile models list|refresh` | Inspect or refresh Coding Plan model defaults. |
+| `arkcli profile set-default <id>` | Save a default resource for one modality. |
+
+## Guard Checklist
+
+1. For ordinary admission, do not inspect or change Profile state. Use:
+
+   ```bash
+   arkcli auth status --format json
+   arkcli auth whoami --format json
+   arkcli resources list --modality text --format json
+   ```
+
+2. When the user explicitly asks to inspect or manage Profile state, explain
+   the possible key synchronization and writeback before running:
+
+   ```bash
+   arkcli profile show --format json
+   arkcli profile list --format json
+   ```
+
+3. Before `create`, `delete`, or `project`, state the exact local configuration
+   impact and obtain confirmation.
+4. Before `use`, `rename`, `keys use`, `keys refresh`, `models refresh`, or
+   `set-default`, state the target profile.
+5. Use `--plan-tier lite|pro` only for a personal `coding-plan` profile when
+   the user explicitly needs to override subscription detection.
+6. Do not edit `~/.arkcli-bp/` or `config.yaml` directly.
+7. Treat API-key sources as profile-specific: `platform` and personal
+   `coding-plan` use the ordinary pool; `coding-plan-team` uses a Running
+   seat's key. `auth apikey` only selects from the ordinary pool and cannot
+   repair a team profile.
+
+## References
+
+- Create a profile:
+  [`references/arkcli-profile-create.md`](references/arkcli-profile-create.md)
+- Manage API keys:
+  [`references/arkcli-profile-keys.md`](references/arkcli-profile-keys.md)
+- Select a default resource:
+  [`references/arkcli-profile-set-default.md`](references/arkcli-profile-set-default.md)
+- Maintainer regression cases:
+  [`references/evals.md`](references/evals.md)
+
+Never change product, account, Region, or tenant as a fallback for a missing
+profile or resource.

package/skills/arkcli-profile/references/arkcli-profile-create.md

@@ -0,0 +1,92 @@
+# `arkcli profile create`
+
+Read [`../SKILL.md`](../SKILL.md) first.
+
+Profile creation writes local BytePlus configuration and may query the control
+plane for projects, API keys, subscriptions, or a Coding Plan Team seat. It
+does not replace BytePlus SSO.
+
+## Supported types
+
+| Type | Requirements |
+|---|---|
+| `platform` | A BytePlus identity; an API key is optional at creation time. |
+| `coding-plan` | An active personal Coding Plan subscription, detected automatically unless `--plan-tier` is supplied. |
+| `coding-plan-team` | An active Coding Plan Team seat. |
+
+No other profile type is supported by the BytePlus build.
+
+## Examples
+
+```bash
+# Create a Platform profile in the default project.
+arkcli profile create --type platform --set-default
+
+# Create a Platform profile for a named project.
+arkcli profile create \
+  --type platform \
+  --project my-project \
+  --set-default
+
+# Create a personal Coding Plan profile and use detected subscription data.
+arkcli profile create --type coding-plan --set-default
+
+# Override personal Coding Plan tier detection only when explicitly required.
+arkcli profile create \
+  --type coding-plan \
+  --plan-tier lite \
+  --set-default
+
+# Create a Coding Plan Team profile from the current assigned seat.
+arkcli profile create --type coding-plan-team --set-default
+
+# Fail instead of prompting when required input is missing.
+arkcli profile create \
+  --type platform \
+  --project default \
+  --no-interactive \
+  --set-default
+```
+
+The Region is fixed to `ap-southeast-1`; it normally does not need to be passed.
+
+## Flags
+
+| Flag | Required | Meaning |
+|---|---:|---|
+| `--type` | In non-interactive mode | `platform`, `coding-plan`, or `coding-plan-team`. |
+| `--region` | No | Fixed BytePlus Region: `ap-southeast-1`. |
+| `--project` | No | Named project; manual creation falls back to `default`. |
+| `--name` | No | Internal profile name; otherwise Ark CLI derives one. |
+| `--default-api-key` | No | API key to bind as the profile default. |
+| `--owner-trn` | No | Optional owner TRN; normally left empty for identity self-healing. |
+| `--plan-tier` | No | Personal Coding Plan override: `lite` or `pro`. |
+| `--set-default` | No | Make the new profile the local default. |
+| `--no-interactive` | No | Disable prompts and fail on missing required input. |
+
+Do not pass the internal account-wide sentinel to `--project`. To select
+`All account resources`, use the interactive project selector:
+
+```bash
+arkcli profile project
+```
+
+That command replaces the existing Platform profile, so follow the confirmation
+rules in the parent Skill.
+
+## Result and recovery
+
+- No API key: the profile may still be created, but data-plane commands remain
+  unavailable until a key is selected.
+- SSO or control-plane error: inspect
+  `arkcli auth status --format json`, recover BytePlus SSO if required, and
+  retry once.
+- Personal Coding Plan not detected: verify the subscription. Use
+  `--plan-tier lite|pro` only when the user intentionally overrides detection.
+- Coding Plan Team seat missing: obtain or assign a seat before creating the
+  team profile.
+- Existing or conflicting profile: inspect `arkcli profile list --format json`
+  before retrying with a different supported configuration.
+
+`arkcli config init` is a compatibility path. New BytePlus profile workflows
+should use `arkcli profile create`.

package/skills/arkcli-profile/references/arkcli-profile-keys.md

@@ -0,0 +1,135 @@
+# `arkcli profile apikey`
+
+Read [`../SKILL.md`](../SKILL.md) first.
+
+The `keys` subtree manages the API key inventory stored in one BytePlus
+profile:
+
+| Command | Remote call | Local change |
+|---|---:|---:|
+| `keys list` | Yes, reconciles against the profile's live key source | May write the reconciled inventory and select or clear the default when membership changed |
+| `keys use <index|api-key>` | No | Changes the profile's default API key |
+| `keys refresh` | Yes | Synchronizes the profile's available API keys |
+
+`arkcli auth apikey` is a separate interactive identity-level key-selection
+flow for the ordinary API-key pool. Do not substitute it for explicit Profile
+inventory management or a Coding Plan Team seat key; `saved=true` does not
+prove that a team profile is usable.
+
+## List keys
+
+Before executing `keys list`, explain that the command contacts the applicable
+remote key source, reconciles the live result with the local inventory, and may
+write the inventory or select/clear the local default. Masking protects output
+secrets; it does not make this operation side-effect free.
+
+```bash
+arkcli profile apikey list --format json
+arkcli profile apikey list \
+  --profile platform_ap-southeast-1_accountwide \
+  --format json
+```
+
+Keys are always masked in output. The response includes a numbered view for
+safe selection:
+
+```json
+{
+  "profile": "platform_ap-southeast-1_accountwide",
+  "default_api_key": "392****dab0",
+  "available_api_keys": [
+    "392****dab0",
+    "abc****1234"
+  ],
+  "keys": [
+    {
+      "index": 1,
+      "api_key": "392****dab0",
+      "is_default": true
+    },
+    {
+      "index": 2,
+      "api_key": "abc****1234",
+      "is_default": false
+    }
+  ]
+}
+```
+
+## Select the default key
+
+Prefer the 1-based index returned by `keys list`:
+
+```bash
+arkcli profile apikey use 2
+arkcli profile apikey use 2 --profile <profile-name>
+```
+
+A complete, unmasked key is also accepted for compatibility:
+
+```bash
+arkcli profile apikey use <complete-api-key>
+```
+
+The selected key must already exist in the profile's available-key inventory.
+Never pass a masked value as a key. On success, output contains the profile name
+and masked `new_default`.
+
+## Refresh keys
+
+```bash
+arkcli profile apikey refresh
+arkcli profile apikey refresh --profile <profile-name>
+```
+
+Refresh uses the target profile's BytePlus identity and the key source required
+by its type:
+
+| Profile type | Key source |
+|---|---|
+| `platform` | Platform API key inventory |
+| `coding-plan` | Platform API key inventory used by personal Coding Plan |
+| `coding-plan-team` | `GetSeatInfo.Result.ApiKey` from the assigned Running Coding Plan Team seat |
+
+It does not rotate, create, or revoke a backend key.
+If the applicable source returns zero usable keys, refresh fails and preserves
+the existing local available-key inventory and default key. It must not report
+success or clear local keys from an empty response.
+
+Example output:
+
+```json
+{
+  "profile": "platform_ap-southeast-1_accountwide",
+  "default_api_key": "392****dab0",
+  "available_api_keys": [
+    "392****dab0",
+    "abc****1234"
+  ],
+  "added_count": 1,
+  "removed_count": 0,
+  "refresh_status": "ok"
+}
+```
+
+## Recovery
+
+- SSO or STS expired: recover BytePlus login, then retry refresh once.
+- `ARK_API_KEY` or `--api-key` overrides the stored default: remove the runtime
+  override if it is unintended; refreshing the profile does not override it.
+- Coding Plan Team seat unavailable: restore or assign the seat before
+  refreshing the team profile. Do not use `auth apikey`; the ordinary pool is
+  unrelated to the seat key.
+- Ordinary key inventory empty: a real TTY login can ask whether to create one
+  all-resource key. Only explicit confirmation permits one creation followed
+  by at most three read-only status checks; non-interactive execution and
+  refusal perform no mutation. Manual recovery uses the BytePlus ARK ordinary
+  API-key management page.
+- Applicable remote source returns no usable key: refresh reports a
+  type-specific error and preserves the local keys.
+- Key lacks resource permission: select or create a backend key with the
+  required permission. Refresh alone cannot grant access.
+- Key removed remotely: refresh, inspect the new numbered list, and explicitly
+  select another available key.
+
+Never display a complete API key or read the local credential store directly.

package/skills/arkcli-profile/references/arkcli-profile-set-default.md

@@ -0,0 +1,81 @@
+# `arkcli profile set-default`
+
+Read [`../SKILL.md`](../SKILL.md) first.
+
+This command writes one default resource ID into a selected BytePlus profile.
+It does not create, deploy, activate, or purchase the resource.
+
+## Syntax and examples
+
+```bash
+arkcli profile set-default <id> \
+  [--profile <profile-name>] \
+  [--modality <text|image|video>]
+```
+
+```bash
+# Platform text Endpoint
+arkcli profile set-default ep-xxxxxxxx \
+  --profile platform_ap-southeast-1_accountwide \
+  --modality text
+
+# Personal Coding Plan text model
+arkcli profile set-default ark-code-latest \
+  --profile coding-plan_ap-southeast-1_personal \
+  --modality text
+
+# Coding Plan Team text model
+arkcli profile set-default ark-code-latest \
+  --profile coding-plan-team_ap-southeast-1_team \
+  --modality text
+```
+
+The modality defaults to `text`.
+
+## Inline availability verification
+
+By default, Ark CLI lists resources with the target profile's identity and
+accepts the ID only when it appears in that availability result:
+
+| Profile type | `text` verification | `image` or `video` verification |
+|---|---|---|
+| `platform` | Platform Endpoint inventory | Platform Endpoint inventory |
+| `coding-plan` | Personal Coding Plan model inventory | Platform Endpoint inventory in the same account |
+| `coding-plan-team` | Coding Plan Team model inventory | Platform Endpoint inventory in the same account |
+
+If verification rejects the ID, list valid values first:
+
+```bash
+arkcli resources list \
+  --profile <profile-name> \
+  --modality <text|image|video> \
+  --format json
+```
+
+`--skip-verify` bypasses only the control-plane availability check. Use it only
+after the user explicitly accepts that Ark CLI cannot verify the ID. It does
+not create the resource, grant permission, or change product support.
+
+## Output
+
+```json
+{
+  "profile": "coding-plan_ap-southeast-1_personal",
+  "modality": "text",
+  "new_default": "ark-code-latest",
+  "verified": true
+}
+```
+
+`verified=false` means the command was run with `--skip-verify`; it does not
+describe BytePlus account-opening or payment verification.
+
+## Recovery
+
+- Authentication or STS failure during inline verification: recover BytePlus
+  SSO and retry once.
+- ID not found: use `arkcli resources list` with the same profile and modality.
+- No saved default: pass `--model` explicitly to the original inference command
+  or select a valid resource after confirmation.
+- Wrong profile: rerun with an explicit `--profile`; do not switch product,
+  account, or Region as a fallback.

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

@@ -0,0 +1,93 @@
+# BytePlus profile evaluation cases
+
+These cases validate routing, product boundaries, and write guards for
+`arkcli-profile`.
+
+## Trigger
+
+Prompt:
+
+> Create a personal BytePlus Coding Plan profile and make it my default.
+
+Expected behavior:
+
+1. Identify the supported type as `coding-plan`.
+2. Explain that profile creation writes local configuration.
+3. Confirm the intended change.
+4. Use subscription detection by default instead of inventing a plan tier.
+
+## Anti-trigger
+
+Prompt:
+
+> Which Endpoint IDs can my current profile use?
+
+Expected behavior:
+
+- Route to `arkcli-resources`.
+- Do not mutate, recreate, or switch the profile.
+
+Prompt:
+
+> My BytePlus SSO session expired.
+
+Expected behavior:
+
+- Route to `arkcli-auth`.
+- Do not treat profile recreation as authentication recovery.
+
+## Guard
+
+Prompt:
+
+> Change my project to `project-b`.
+
+Expected behavior:
+
+- Explain that `profile project` deletes and recreates the Platform profile and
+  refreshes Coding Plan profiles for the new project.
+- Confirm the operation before using `--yes`.
+- Do not switch account, product, or Region.
+
+Delete case:
+
+- State the exact profile name before `profile delete`.
+- Never delete a profile merely to recover from a missing resource.
+
+## Happy-path command
+
+Read-only inspection requires no confirmation:
+
+```bash
+arkcli profile list --format json
+arkcli profile show --format json
+```
+
+Expected result:
+
+- the active profile is identifiable;
+- secrets remain masked;
+- account-wide scope is displayed as `All account resources`, never as its
+  internal sentinel.
+
+## API-key source isolation
+
+Prompt:
+
+> `profile apikey refresh` found no Coding Plan Team key, but `auth apikey`
+> returned `saved=true`. Did that repair the team profile?
+
+Expected behavior:
+
+- explain that `auth apikey` selects only from the ordinary API-key pool;
+- explain that `coding-plan-team` uses `GetSeatInfo.Result.ApiKey` from a
+  Running seat;
+- do not claim the team profile is repaired;
+- state that an empty team-seat result makes refresh fail while preserving the
+  existing local key inventory and default key.
+
+## Read-only admission and disclosure ordering
+
+- A user supplies a profile type and requests only identity/default-resource compatibility checks: hand off to Auth and Resources. An empty resource list leads to a missing-information report, not `profile show/list/keys list`.
+- For explicit Profile management, visible text before the first management command must actually state online key synchronization and possible local inventory/default writeback. A promise to explain later or a post-command final answer fails this contract.
+- Do not describe the completed management query as purely read-only or guarantee unchanged local keys without evidence.

package/skills/arkcli-resources/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: arkcli-resources
+version: 1.1.2
+description: "arkcli resources real-time control-plane queries: list resources and resolve an Endpoint into its authoritative bound model identity, base-model lineage, capabilities, workflows, and Region. Read-only; does not write profile.yaml."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli resources --help"
+---
+
+# arkcli resources
+
+**CRITICAL — Before starting, you MUST use the Read tool to read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md), which contains authentication gates, configuration troubleshooting, and command selection order.**
+
+## Usage principles
+
+- The `arkcli resources` domain is strictly read-only. Even when a create intent appears in the context of a resources list, first load [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md); this Skill must not create, update, or delete resources.
+- Keep an ordinary product intent such as "deploy this model and give me an Endpoint" on `arkcli +deploy`. That online workflow does not support Client Preview: **you must not run `arkcli +deploy --dry-run`**, and you must not silently downgrade the product workflow to raw CRUD just to obtain a preview.
+- After handing off to the Deploy Skill, perform only read-only checks, then restate the model, name, Region, configuration, and billing impact. Until the user gives a fresh explicit confirmation in the current turn, **you must not execute the real** `arkcli +deploy`. Never add `--yes`, pipe `echo Y`, or set `ARKCLI_ALLOW_HEADLESS_ACTIVATION` on the user's behalf.
+- Only when the user explicitly asks for raw CRUD, an exact CreateEndpoint request, or a CI/script preview should you route to [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md) and use the leaf command `arkcli infer endpoint create ... --dry-run`. A real execution still requires a new confirmation after the preview.
+- `arkcli resources list` is a read-only, real-time control-plane query. It calls the upstream service every time and has no local cache.
+- It is a discovery list, filtered by project, creator, and modality where applicable. An empty list or a missing current default does not prove that an Endpoint is absent or unusable.
+- For a read-only identity/default-resource check with no exact resource ID and an empty list, report the confirmed facts and missing information, then stop. Do not fall back to `profile show/list/keys list` to fill gaps. An empty list does not authorize configuration repair or key synchronization.
+- `invocable` and `required_overrides` describe Profile/resource compatibility; `invocable=true` does not prove that the API key is usable, unexpired, authorized, or has remaining quota. Confirm credential context separately and respect the actual data-plane result.
+- `arkcli resources resolve <ep-id>` checks `endpoint_model_type` before interpreting model references. For a Custom Model Endpoint, `model_id` and `custom_model_id` remain the bound `cm-...` identity; `base_model_*` is lineage and capability metadata only.
+- Dispatch follows profile.Type: platform → `ListEndpoints`; coding-plan text → `ListCodingPlanVirtualModelID` with the profile's `Edition + PlanTier (BizInfo)`.
+- `coding-plan-team` uses its team-seat key for plan text models. Image/video discovery uses the platform Endpoint pool, but invocation requires a compatible pay-as-you-go API key; a visible Endpoint does not make the seat key compatible.
+- This skill does not change defaults. When the user wants to change a default, use `profile set-default` from [`../arkcli-profile/SKILL.md`](../arkcli-profile/SKILL.md).
+- `--profile X` genuinely switches identity (P0-A correction): the control-plane request uses X's token / UserID, rather than making the request as active=A and merely displaying B's resources.
+
+## Applicable scenarios
+
+- The user asks which endpoints / models are available under the current profile.
+- The user gets `<id> is not in the available list` when running `profile set-default`; return here to view the actual available IDs.
+- The user gets `InvalidEndpointOrModel.NotFound` when running `+chat / +gen --model`; return here to confirm that the ID is visible under the active profile.
+- The user switched profiles and wants to know how the resources available under the new profile differ from the old profile.
+- The user supplies an `ep-...` ID and needs its authoritative model binding, workflow, generation modality, or Region.
+
+## Anti-trigger signals
+
+- The user wants to **find a model** / **choose a model** / asks "which model is strongest / offers the best value" → route to [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) (with enrichment + weighted ranking).
+- The user wants to **create an endpoint** → route to [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md) (`arkcli +deploy`); only inspect, restate, and request confirmation in this turn.
+- The user explicitly asks for a **raw CreateEndpoint / CI / exact request preview** → route to [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md) and use `infer endpoint create --dry-run`.
+- The user wants to **manage an endpoint** (start / stop / get / update / detailed list) → route to [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md).
+
+## Difference between resources and models
+
+| Dimension | `arkcli resources list` | `arkcli models ...` |
+|------|------------------------|----------------------|
+| Scope | Resource discovery and compatibility under the current profile | Full-platform foundation model catalog |
+| Output | Endpoint ID (`ep-xxx`) or plan model name | All foundation_model fields + ArkModels enrichment |
+| Dispatch | Switches endpoint / plan / coding APIs by profile.type | General ListFoundationModel |
+| Cache | None | Cache scoped by profile/region/project |
+| Primary purpose | Discover candidates and check Profile/resource compatibility | Find models, compare models, and verify capabilities |
+
+In short, `resources list` discovers resources and compatibility under the current profile; `models` describes the platform catalog. Neither proves a successful data-plane invocation.
+
+## Agent quick execution order
+
+1. If the user supplies an `ep-...` ID → `arkcli resources resolve <ep-id> --format json`; inspect `endpoint_model_type` and `model_id` before workflow fields.
+2. If the current profile is uncertain → `arkcli auth whoami --format json` (inspect `profile.name` and `profile.type`). Do not use `profile show/list` as routine read-only admission: they may reconcile and update the local key inventory. Missing identity fields require diagnosis, not an assumed profile.
+3. Text resources → `arkcli resources list --modality text --format json`.
+4. Image / video resources → `arkcli resources list --modality image --format json` / `--modality video`.
+5. Compare multiple profiles → run `--profile A --modality text` and `--profile B --modality text` separately.
+6. In the output, `is_default: true` marks the current profile's default. To switch the default, use `arkcli profile set-default`.
+7. If the user-selected or current default Endpoint is absent from discovery, resolve that same Endpoint under the same identity. Check its Region, Running status, intended workflow/API/modalities, and resolution warnings; separately verify the Profile/key lane. Do not bypass an explicit incompatible entry or required override. You must not create an Endpoint merely because a discovery list is empty, or silently change the model, Profile, or default.
+
+## Command overview
+
+| Command | Description |
+|------|------|
+| `arkcli resources list` | List available resource IDs for the specified modality under the current or specified profile (real-time). |
+| `arkcli resources resolve <endpoint-id>` | Resolve the Endpoint's authoritative bound identity, base-model lineage, candidate workflows, generation modality, and Region. |
+
+## Output format
+
+```json
+{
+  "profile": "platform_ap-southeast-1_default",
+  "type": "platform",
+  "modality": "text",
+  "items": [
+    {"id": "ep-20260424-aaaaa"},
+    {"id": "ep-20260424-bbbbb", "is_default": true},
+    {"id": "ep-20260424-ccccc"}
+  ],
+  "current_default": "ep-20260424-bbbbb",
+  "item_count": 3
+}
+```
+
+`is_default` appears only when `items[].id == current_default`. If the default is an empty string, no item has `is_default`.
+
+## Endpoint resolution contract
+
+- `endpoint_model_type="CustomModel"`: `model_id == custom_model_id == "cm-..."`. Read `base_model_*` only as lineage and the source of capability metadata; never replace the actual binding with `base_model_id`.
+- `endpoint_model_type="FoundationModel"`: `model_id` keeps the existing foundation-model meaning.
+- Read `supported_workflows`, `generation_modality`, and `requires_user_intent` to route the next task.
+- A non-empty `resolution_warnings` is fail-soft output. Do not guess a binding from ambiguous Custom Model and Foundation Model references.
+
+## Common errors
+
+- Under a coding-plan profile, image/video discovery uses the platform Endpoint pool. Check the pay-as-you-go key requirement before invoking an Endpoint. An empty list requires scope/permission diagnosis and exact resolution of a known target; creation is a separate user intent owned by Deploy Skill.
+- `plan profile is missing an active profile name` / `load plan tier ...` → The Coding Plan profile has no persisted tier for `BizInfo`. Inspect it with `arkcli profile show`, then refresh or recreate it through the Profile Skill; do not issue an unscoped model-list request.
+- `ListEndpoints: NotLogin / Unauthorized` → Login state/STS expired, or profile X supplied through `--profile X` has no token in the identity store; run `auth login` first.
+- `unsupported profile type "X" for resources list` → inspect the effective context with `auth whoami`, then route to Config/Profile Skill for diagnosis. Do not recreate or change the profile without user intent.
+
+## References
+
+- [`../arkcli-profile/SKILL.md`](../arkcli-profile/SKILL.md) — Use this after reviewing resources when you need to change a default.
+- [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) — Use this to find models or compare capabilities.
+- [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md) — Enter the creation workflow only when the user requests a new Endpoint.