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

package/skills/arkcli-plans/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: arkcli-plans
+version: 1.2.0
+description: "Manages ARK plans (Coding Plan, personal + team): query holdings, buy, renew, list models, list enterprise seats (`plans team seat-list`), assign seats to employees (`plans team seat-assign`), rotate team-seat API keys (`plans team rotate-apikey`), and inspect seat bindings. Trigger terms: plan / buy / renew / list seats / view seat bindings / who is bound to which seat / assign employee seats / rotate team API key / team-seat admin view. Unbinding is not currently exposed by arkcli; route such requests here only to explain the limitation. Usage questions (remaining quota / percentage used / per-seat usage) go to [arkcli-usage](../arkcli-usage/SKILL.md). Verb routing: list / bind / assign / rotate → here; use / consumption / how much → arkcli-usage."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli plans --help"
+---
+
+# arkcli plans
+
+**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 shared safety rules.**
+**CRITICAL — Before executing any `plans buy` / `plans renew` / `plans team seat-assign` / `plans team rotate-apikey`, you MUST use the Read tool to read the corresponding `references/*.md`. Do not invoke them blindly.**
+
+## 🔒 Agreement gate (mandatory process for plans buy / plans renew)
+
+`plans buy` / `plans renew` on BytePlus **never place orders in-CLI**. Adding `--yes` does not trigger a charge; it returns a `payment_via_web` payload with a `subscribe_url` pointing to the BytePlus console subscription page, where the user completes the purchase in the browser. **When neither `--yes` nor `--estimate` is passed**, the CLI runs the review gate and returns:
+
+```json
+{
+  "status": "agreement_required",
+  "subscribe_url": "https://console.byteplus.com/ark/region:ark+ap-southeast-1/subscription/coding-plan",
+  "total_amount_usd": 10,
+  "original_amount_usd": 10,
+  "next_step": "Ask the user to open <subscribe_url> in the browser and finish the purchase on the BytePlus subscription page. Do not rerun this command with --yes."
+}
+```
+
+Note: BytePlus does **not** return the `agreements` array. The web subscription page handles agreement presentation and signing with the correct BytePlus legal documents; the CLI would only have Volc-region agreement text to show, which is wrong for BytePlus users. Amount fields are `total_amount_usd` / `original_amount_usd` (USD).
+
+**The Agent must strictly follow this sequence:**
+
+1. **The first call must omit `--yes`** to obtain price + `subscribe_url`.
+2. Display `total_amount_usd` and `original_amount_usd` to the user for transparency.
+3. Then present the `subscribe_url` and ask the user to complete the purchase in the browser on the BytePlus console. **Do not rerun the command with `--yes`** expecting an in-CLI charge — both `--yes` and the gate resolve to the same subscribe URL on BytePlus.
+
+**Violating this process means skipping user-facing price transparency.** The web page also enforces its own agreement UI before the user can pay.
+
+`--estimate` is the online price-quote path; it is not Client Preview. It neither places an order nor returns a `subscribe_url` (use the default gate path when you need the URL).
+
+## Business positioning
+
+`arkcli plans` manages ARK plans:
+- **Coding Plan** (`coding-plan` / `coding-plan-team`): programming assistance plans divided into tiers (lite/pro).
+
+Plans have two forms: **personal edition** (`personal`) and **enterprise / team edition** (`team`):
+
+| Form | Resource unit | Typical operations |
+|---|---|---|
+| personal | Individual subscription | View / buy / renew |
+| team | Enterprise seat | View / buy / renew / list seats / bind sub-users |
+
+> A personal account has one subscription; a team plan is managed at SeatID granularity, with each seat bound to one sub-user.
+
+> **This skill does not include plan usage / quota queries** ("how much has been used / how much remains / when it resets / breakdown by model"). `plans get` answers only "which plans do I **hold** + status (Effective/Running)", not "how much has been used". The quota view is in [`../arkcli-usage/`](../arkcli-usage/SKILL.md). See the routing table under "Quick decisions".
+
+> **Agent Plan boundary (BytePlus)**: BytePlus does not offer Agent Plan (`agent-plan` / `agent-plan-team`). When asked about Agent Plan, respond with "Agent Plan is not offered on BytePlus" and stop — never fall back to Coding Plan data as a stand-in, never invent an `agent-plan` invocation to "try".
+
+## Applicable scenarios
+
+- View plans held by the current account → `plans get`.
+- Place an order for a plan (personal / team) → `plans buy`.
+- Renew an existing plan → `plans renew`.
+- View the models and model specifications supported by a plan (context window, input/output token limits, and input modalities) → `plans model-list`.
+- Switch the ark-code-latest route target (Auto smart scheduling or a concrete shadow model) → `plans model-apply`.
+- List / filter enterprise seats → `plans team seat-list`.
+- Bind an enterprise seat to a sub-user → `plans team seat-assign`.
+- Rotate API keys for explicit Coding Plan Team SeatIDs → `plans team rotate-apikey`.
+
+## Quick decisions
+
+- User asks "What plans do I have / what have I subscribed to?": run `arkcli plans get` directly with no arguments (**holdings + status only, no usage**).
+- User asks **"How much have I used / how much remains / when does it reset / in-plan vs out-of-plan"**: this is **outside this skill**; route to [`../arkcli-usage/`](../arkcli-usage/SKILL.md):
+  - "How much of my plan remains / when does it reset?" → `arkcli usage plan` or `arkcli usage balance --type plan`.
+  - "Which model do I use most / in-plan versus out-of-plan ratio?" → `arkcli usage plan-details`.
+  - "Team-seat usage" → `arkcli usage seats --product coding-plan-team --with-usage`.
+- User asks "Which models does Coding Plan support / how large is the context window / what are the maximum input and output lengths / does it support image or video input?": run `arkcli plans model-list --plan <plan>`. Add `--mode direct` when only directly invocable ModelNames are needed, `--mode routing` when only `ark-code-latest` route targets are needed, or keep the default `--mode all` to compare both catalogs. `models[]` contains route targets, while `direct_models[].model_name` contains directly invocable ModelNames; both may expose `context_window`, `max_input_tokens`, `max_completion_tokens`, `input_modalities`, and `load`.
+- User wants to "switch the ark-code-latest underlying model / use Auto smart scheduling / pin a specific model": `arkcli plans model-apply --plan <plan> --model <model-id|output-name|auto>` (**write operation**, synced with the console; confirm valid targets with `plans model-list --mode routing` first).
+- User wants to buy a plan: read [buy.md](references/arkcli-plans-buy.md), collect `--plan`, `--type`, `--duration`, and team `--quantity`. Do not choose for the user.
+- User wants to renew: read [renew.md](references/arkcli-plans-renew.md), confirm `--plan`, duration, and existing team `--seat-ids`. Renewal keeps the current tier; do not pass purchase-only `--type` or `--quantity`. Preserve the BytePlus web-payment handoff above; never import the Volc charging workflow.
+- User wants to "**query seats / inspect team-seat bindings / see who is bound to which seat / list seats / see activated seats / team-seat admin view**" → `plans team seat-list --plan <coding-plan-team>` (**the default entry point for seat management**; the management view lists basic information + bindings, **without usage numbers**. To see each seat's token usage / plan percentage → `arkcli usage seats --with-usage`).
+- User wants to "assign a seat to an employee / allocate employee seats" → `plans team seat-assign`; first prepare a `seat-id=user-id` pairing list.
+- The user **knows only the employee username**, not the exact UserID: first run `arkcli iam userid --username <prefix>` to resolve `user_id`, then pass it to `seat-assign --bind seat-id=<user_id>`.
+- User wants to rotate one or more Coding Plan Team seat API keys → `plans team rotate-apikey --seat-ids <seat-id,...>`; BytePlus requires explicit SeatIDs and never performs an implicit self lookup. Read the rotate reference, warn that every old key becomes invalid immediately, and obtain explicit confirmation before adding `--yes`.
+
+## Agent quick execution order
+
+1. First confirm authentication status: `arkcli auth status`; if missing, use `../arkcli-auth/`.
+2. Execute read operations (`get` / `model-list` / `seat-list`) directly; consider the current identity only when the user asks about "mine".
+3. For **write operations (`buy` / `renew` / `seat-assign` / `rotate-apikey` / `model-apply`)**, always:
+   - Read the corresponding reference first.
+   - Confirm key fields with the user (plan / type / duration / SeatIDs / UserID pairings).
+4. Partial failure (per-item Success/Failed arrays) is a valid response. When the exit code is nonzero, **do not** immediately treat the entire operation as failed; first inspect `success_count` / `failed_count` in stdout.
+
+## Write-operation risk list (must read)
+
+| Command | Risk | Mandatory action |
+|---|---|---|
+| `plans buy` | Compliance step; **payment happens on the BytePlus web console**, not in CLI | First run without `--yes` through the review gate → show `total_amount_usd` + `subscribe_url` to the user → direct them to `subscribe_url` in the browser (where BytePlus web handles agreement UI). `--yes` also returns `subscribe_url` and does **not** charge the account. See [agreement gate process](#-agreement-gate-mandatory-process-for-plans-buy--plans-renew) |
+| `plans renew` | Same as buy: payment happens on the BytePlus web console | Same review gate as buy; team edition requires `--seat-ids`. `--yes` also returns `subscribe_url` without renewing anything in-CLI |
+| `plans model-apply` | Changes the plan's request routing (effective immediately, synced with the console) | `--model` is required when non-interactive; confirm valid targets with `plans model-list --mode routing` first; team plans error when the account holds no active seat |
+| `plans team seat-assign` | Modifies seat bindings | Explicit `--bind seat-id=user-id`; automatically calls IAM to resolve UserName |
+| `plans team rotate-apikey` | **Credential rotation**; old keys are invalidated immediately | Explicit `--seat-ids`; confirm all affected applications are ready for replacement keys before adding `--yes`; never paste returned plaintext keys into chat |
+
+## Command overview
+
+| Command | Type | Description |
+|---|---|---|
+| [`plans get`](references/arkcli-plans-get.md) | Read | List plans held by the current account (personal + team aggregation) |
+| [`plans buy`](references/arkcli-plans-buy.md) | Review + web redirect | Show price + `subscribe_url` so the user can complete the purchase on the BytePlus console (web handles agreement UI) |
+| [`plans renew`](references/arkcli-plans-renew.md) | Compliance + web redirect | Same as buy: `subscribe_url` points to the BytePlus console renewal page |
+| [`plans model-list`](references/arkcli-plans-model-list.md) | Read | Use `--mode all|direct|routing` to query both catalogs, direct ModelNames, or ark-code-latest route targets, with capability and load data |
+| [`plans model-apply`](references/arkcli-plans-model-apply.md) | Write | Set the ark-code-latest route target (auto or a concrete shadow model) |
+| [`plans team seat-list`](references/arkcli-plans-team-seat-list.md) | Read | List enterprise seats + multidimensional filtering |
+| [`plans team seat-assign`](references/arkcli-plans-team-seat-assign.md) | Write | Batch-bind enterprise seats to sub-users |
+| [`plans team rotate-apikey`](references/arkcli-plans-team-rotate-apikey.md) | Destructive write | Rotate API keys for explicitly selected Coding Plan Team seats |
+
+## Common fallbacks
+
+- Authentication error: route to [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+- Wrong region / project: route to [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md).
+- **View plan usage / quota (used / total / percent / reset_at / model breakdown)**: route to [`../arkcli-usage/SKILL.md`](../arkcli-usage/SKILL.md). This skill answers only "what is held", not "how much was used".
+- **View billing / settlement amounts**: route to [`../arkcli-billing/SKILL.md`](../arkcli-billing/SKILL.md). `plans` does not return monetary amounts.
+- Try a model without formal deployment: route to [`../arkcli-chat/SKILL.md`](../arkcli-chat/SKILL.md) / [`../arkcli-gen/SKILL.md`](../arkcli-gen/SKILL.md).
+- Fall back to [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md) when no product command exists.
+
+## References
+
+- [arkcli-shared](../arkcli-shared/SKILL.md) -- Authentication / global parameters / output rules
+- [arkcli-usage](../arkcli-usage/SKILL.md) -- Plan **usage / quota** views (`usage plan` / `usage plan-details` / `usage balance` / `usage seats --with-usage`), complementing this skill's holdings / purchases / seat management
+- [arkcli-billing](../arkcli-billing/SKILL.md) -- Plan **settlement amounts** (BytePlus billing-center breakdown, T+1)
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) -- Deploy an endpoint with `+deploy` after purchasing a plan
+- [arkcli-helper](../arkcli-helper/SKILL.md) -- **Inject / remove** Plan model/provider for an AI Agent
+- [Coding Plan Team API-key rotation](references/arkcli-plans-team-rotate-apikey.md) -- Destructive administrator rotation for explicit SeatIDs

package/skills/arkcli-plans/references/arkcli-plans-buy.md

@@ -0,0 +1,125 @@
+# plans buy
+
+> **Prerequisite:** Read [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+> **⚠️ BytePlus payment flow:** BytePlus does not yet support balance-based auto-pay via arkcli. Adding `--yes` **does not place an order or charge the account**; instead the command returns a `payment_via_web` payload with a `subscribe_url` pointing to the BytePlus console subscription page. The user must open that URL in a browser and complete the purchase on the web. **Do not choose for the user**: the user must explicitly provide `--plan`, `--type`, `--duration`, and `--quantity` for team plans.
+
+> **🔒 Review gate (mandatory process; the Agent must comply):** Without `--yes`, this command **does not place an order** and returns price + `subscribe_url`. The Agent **must**:
+> 1. Display `total_amount_usd` and `original_amount_usd` to the user for price transparency.
+> 2. Then present the `subscribe_url` and ask the user to complete the purchase in the browser. **Do not rerun the command with `--yes`** expecting an in-CLI charge — BytePlus does not support that path; both `--yes` and the gate resolve to the same subscribe URL.
+>
+> The BytePlus subscription page handles agreement presentation and signing with the correct BytePlus legal documents on the web; the CLI does **not** return an `agreements` array (see Return value below).
+
+## Three invocation forms
+
+| Form | Behavior | When to use |
+|---|---|---|
+| Neither `--yes` nor `--estimate` | **Review gate**: returns **price** (USD) + `subscribe_url` + `next_step`; internally uses EstimatePrice and **does not place an order** | Default guidance step; the Agent obtains "price + web URL" in one call |
+| `--estimate` (with or without `--yes`) | **Online price inquiry**: calls EstimatePrice, returns the price, and **does not place an order** | Overlaps with the gate; retained as a convenient scripting path for "price only" |
+| `--yes` without `--estimate` | **Web redirect** (BytePlus): returns `payment_via_web` payload with `subscribe_url`; **no order-side API is called**, no order or seat is created | The user has confirmed the price; direct them to the web console to complete the purchase |
+
+> **The gate returns pricing + subscribe URL together**. One call returns `total_amount_usd` + `original_amount_usd` + `subscribe_url`; show these to the user together and then hand off the URL.
+
+## Commands
+
+```bash
+# Step 1: Guidance (without --yes) — obtain the price + subscribe_url
+arkcli plans buy --plan coding-plan --type lite --duration 1
+
+# Step 2 (optional): Price inquiry
+arkcli plans buy --plan coding-plan --type lite --duration 1 --estimate
+
+# Step 3: After showing the user the price, hand off to the web page via subscribe_url
+arkcli plans buy --plan coding-plan --type lite --duration 1 --yes
+
+# Example for a team-edition tier
+arkcli plans buy --plan coding-plan-team --type pro --quantity 10 --yes
+```
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|------|------|------|------|
+| `--plan` | Yes | string | `coding-plan` / `coding-plan-team` |
+| `--type` | Yes | string | Tier: coding-plan* accepts `lite/pro` |
+| `--duration` | No | int | Subscription duration (months), 1–12, default 1 |
+| `--quantity` | Required for team | int | Number of seats (≥1); ignored when passed for personal edition |
+| `--yes` | No | bool | On BytePlus, returns the `payment_via_web` payload directly (no charge; equivalent to the gate for the subscribe_url purpose) |
+
+Compatibility between `--plan` and `--type`:
+
+| Plan family | Valid tiers |
+|---|---|
+| coding-plan / coding-plan-team | lite, pro |
+
+## Return value (review gate, default form)
+
+When neither `--yes` nor `--estimate` is passed:
+
+```json
+{
+  "status": "agreement_required",
+  "plan": "coding-plan",
+  "tier": "lite",
+  "duration": 1,
+  "echo": {"plan": "coding-plan", "tier": "lite", "duration": 1},
+  "total_amount_usd": 10,
+  "original_amount_usd": 10,
+  "subscribe_url": "https://console.byteplus.com/ark/region:ark+ap-southeast-1/subscription/coding-plan",
+  "confirm_text": "BytePlus balance-based auto-pay is not supported by arkcli yet...",
+  "next_step": "Ask the user to open <subscribe_url> in the browser and finish the purchase on the BytePlus subscription page. Do not rerun this command with --yes."
+}
+```
+
+Amount fields are always USD on BytePlus (`total_amount_usd` / `original_amount_usd`); `total_amount_cny` / `original_amount_cny` will never appear. There is intentionally **no `agreements` array** — the BytePlus subscription page handles agreement presentation and signing on the web with the correct BytePlus legal documents.
+
+## Return value (`--yes` / web redirect)
+
+After adding `--yes`, the CLI does **not** place an order or invoke any Create* API. Instead it returns:
+
+```json
+{
+  "status": "payment_via_web",
+  "plan": "coding-plan-team",
+  "tier": "pro",
+  "duration": 2,
+  "quantity": 5,
+  "subscribe_url": "https://console.byteplus.com/ark/region:ark+ap-southeast-1/subscription/coding-plan-enterprise",
+  "message": "BytePlus balance-based auto-pay is not supported by arkcli yet. Open the subscribe_url above in the browser to complete the purchase on the BytePlus console.",
+  "next_step": "Ask the user to open <subscribe_url> in the browser and finish the purchase on the BytePlus subscription page. Do not rerun this command with --yes."
+}
+```
+
+`quantity` is populated only for team plans. For team plans **no seats are created**: the CLI does not call `CreateSeatInfo` before redirecting, so there are no dangling seats to clean up.
+
+## Failure semantics
+
+BytePlus arkcli does not place orders, so the `payment_failed` envelope (which the Volc build emits when auto-pay fails after `CreateSubscribeTrade`) **does not exist here**. Failure modes are:
+
+- **Validation error** (e.g. `--quantity is required for team plans`): normal error, exit code = 1. Fix the arguments and retry.
+- **Auth / preflight error** (missing `arkcli auth login`, etc.): normal error, exit code = 1. Log in and retry. See [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md).
+- **Payment failure on the web**: after the user opens `subscribe_url`, if BytePlus web rejects the payment (e.g. account not opened, real-name pending, payment method missing), the console will surface the failure and the appropriate settings page. This is out of arkcli's control.
+
+## Common errors
+
+| Error | Cause | Handling |
+|---|---|---|
+| `--plan must be one of ...` | Plan key is misspelled | Strictly use `coding-plan` or `coding-plan-team` |
+| `--type %q not allowed for --plan %q` | Tier is incompatible with plan | See the table above |
+| `--quantity is required for team plans` | Team quantity omitted | Add `--quantity N` |
+| `--duration must be 1..12` | Out of range | Use 1–12 |
+
+## Notes
+
+- **No in-CLI charge**: BytePlus arkcli never invokes any Create-trade API. The purchase always happens on the web console.
+- **Use `--estimate` for pricing scripts** if you only need a price quote and want to skip the agreement + subscribe URL machinery.
+- After the user completes the purchase on the web console for a team plan, seats appear with `BillingStatus=Running` but are **not bound to sub-users**. Next use [`plans team seat-assign`](arkcli-plans-team-seat-assign.md) to assign them.
+- Rerunning `plans buy --yes` is safe on BytePlus: each call is a pure web-redirect stub that produces the same `subscribe_url`. It never places an order.
+
+## References
+
+- [arkcli-plans](../SKILL.md) -- Skill overview
+- [`plans renew`](arkcli-plans-renew.md) -- Renew an existing plan
+- [`plans get`](arkcli-plans-get.md) -- Query holdings after ordering
+- [`plans team seat-assign`](arkcli-plans-team-seat-assign.md) -- Bind sub-users after a team order
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

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

@@ -0,0 +1,84 @@
+# plans get
+
+> **Prerequisite:** Read [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+> **Scope limitation:** `plans get` answers only "which plans do I **hold** + status (Effective/Running/...)" and **does not answer "how much has been used / how much remains / when it resets / breakdown by model"**. For quota queries, use:
+> - `arkcli usage plan` — Full version with used / total / percent / reset_at + multiple periods (5h/daily/weekly/monthly)
+> - `arkcli usage balance --type plan` — Simplified version (same data source)
+>
+> See [`../../arkcli-usage/SKILL.md`](../../arkcli-usage/SKILL.md).
+
+Return all plans **actually held** by the current account in one call: an aggregation of Coding Plan personal + team editions. This is a read operation with no side effects.
+
+## Command
+
+```bash
+arkcli plans get
+```
+
+## Parameters
+
+No parameters. Both plan paths (`coding-plan` / `coding-plan-team`) are fetched concurrently.
+
+## Return value
+
+```json
+{
+  "plans": [
+    {
+      "key": "coding-plan",
+      "name": "Coding Plan",
+      "scope": "personal",
+      "tier": "lite",
+      "status": "Effective"
+    },
+    {
+      "key": "coding-plan-team",
+      "name": "Coding Plan Team",
+      "scope": "team",
+      "tier": "lite",
+      "status": "Running",
+      "seat_id": "seat-..."
+    }
+  ]
+}
+```
+
+| Field | Appears when | Meaning |
+|------|---------|------|
+| `key` | always | Stable identifier: coding-plan / coding-plan-team |
+| `scope` | always | personal / team |
+| `tier` | When held | Personal: lite/pro (coding); team: tier of the current user's seat |
+| `status` | When held | Personal: Effective / Pending / Expired, and others; team: Running |
+| `seat_id` | Team only | Current user's seat ID under this Scene (team edition only) |
+| `error` | API call fails | Diagnostic information passed through from the API; mutually exclusive with tier/status |
+
+**Plans not held / historical Reclaimed subscriptions / team plans without a seat** are filtered and do not appear in the array.
+
+## Behavior details
+
+- Internally fetches `ListSubscribeTrade` (personal) + `GetSeatInfo` (team) concurrently.
+- Failure of one plan does not block other plans: the failed item remains in the array with an `error` field.
+- The team edition recognizes only valid seats with `BillingStatus=Running`; historical seats (Pending/Expired/Reclaimed) are filtered.
+
+## Common errors
+
+| Error | Cause | Handling |
+|------|------|------|
+| `plans get: ark: API error: AuthFailure` | Not authenticated / token expired | `arkcli auth login` |
+| Output `{"plans":[]}` | The current account has no plans | Place an order with `plans buy` or check whether the account was switched |
+
+## Notes
+
+- This is the **only plans subcommand requiring no parameters**. When the user asks "What plans do I have / what have I subscribed to?", invoke it directly.
+- **To view usage / quota (used / total / percent / reset date)**: this command **does not return** those fields. Route to `arkcli usage plan` / `arkcli usage balance --type plan` / `arkcli usage plan-details` (see the scope limitation at the top).
+- It does not list other users' plans. The view always belongs to the current SSO identity.
+- The team edition shows only seats **held by the current user**. To view all team seats, use [`plans team seat-list`](arkcli-plans-team-seat-list.md) (basic information) or `arkcli usage seats --with-usage` (including seat usage).
+
+## References
+
+- [arkcli-plans](../SKILL.md) -- Skill overview
+- [`plans model-list`](arkcli-plans-model-list.md) -- See which models can be called under held plans
+- [`plans buy`](arkcli-plans-buy.md) / [`plans renew`](arkcli-plans-renew.md) -- Purchase / renew
+- [arkcli-usage](../../arkcli-usage/SKILL.md) -- Plan usage / quota (all fields absent from this command are here)
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-model-apply.md

@@ -0,0 +1,58 @@
+# plans model-apply
+
+> **Prerequisite:** Read [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Set the **ark-code-latest route target** of a Coding Plan: `auto` (smart scheduling — the platform picks the underlying model) or a concrete shadow model from the plan's model list. Uses the same backend Actions as the console's route-model confirmation, takes effect immediately, and stays in sync with the console. Write operation.
+
+## Commands
+
+BytePlus requires an explicit plan target; this command has no default plan.
+
+```bash
+# Interactive terminal: omit --model to open the route-target selector
+# (the currently active target is tagged [active] and pre-highlighted)
+arkcli plans model-apply --plan coding-plan
+
+# Non-interactive / agent: --model is required (model id, output name, or "auto")
+arkcli plans model-apply --plan coding-plan --model auto
+arkcli plans model-apply --plan coding-plan-team --model doubao-seed-code-251028
+```
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|-----------|----------|------|-------------|
+| `--plan` | Yes | string | `coding-plan` / `coding-plan-team` |
+| `--model` | Required when non-interactive | string | Route target: a model `model_id`, an `output_name`, or `auto`; may be omitted on an interactive terminal to open the selector |
+
+## Response
+
+```json
+{
+  "plan": "coding-plan",
+  "previous_selected_model_id": "doubao-seed-code-251028",
+  "applied": {
+    "model_id": "auto",
+    "output_name": "auto"
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `plan` | Echoes the input |
+| `previous_selected_model_id` | The shadow model id that ark-code-latest resolved to before this write (empty when unset) |
+| `applied.model_id` / `applied.output_name` | The route target just written; both fields are `auto` for smart scheduling |
+
+## Notes
+
+- **Valid targets come from `models[]` in the [`plans model-list --mode routing`](arkcli-plans-model-list.md) output**; an out-of-list `--model` fails with `does not support route target` plus the available options
+- Team plans (`coding-plan-team`) are scoped to the **current identity's seat**: the command errors when the account holds no active seat — subscribe a seat in the console first
+- After writing, the CLI re-reads the model list to verify; while the control plane is still syncing, a mismatch only prints a stderr `warn` and does not change the exit code — double-check with `plans model-list --mode routing`
+- This command only changes the route target; it does not touch local agent configuration. To switch the model used by local agents, see `helper configure --model` in [`../../arkcli-helper/SKILL.md`](../../arkcli-helper/SKILL.md)
+
+## See Also
+
+- [arkcli-plans](../SKILL.md) — skill overview
+- [`plans model-list --mode routing`](arkcli-plans-model-list.md) — query only valid route targets and the active one
+- [arkcli-shared](../../arkcli-shared/SKILL.md)

package/skills/arkcli-plans/references/arkcli-plans-model-list.md

@@ -0,0 +1,114 @@
+# plans model-list
+
+> **Prerequisite:** Read [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+List two model sets for a specified plan: `models` contains route targets behind
+`ark-code-latest`, while `direct_models` contains ModelNames that can be placed
+directly in an inference request or Agent configuration. Both sets may include
+load and capability metadata. Read operation.
+
+## Commands
+
+When the current identity holds exactly one active Coding Plan, omitting
+`--plan` auto-detects that plan. If both personal and team editions are active,
+the CLI asks for an explicit target instead of guessing.
+
+```bash
+# Auto-detect the only active Coding Plan
+arkcli plans model-list
+
+# View Coding Plan personal-edition models
+arkcli plans model-list --plan coding-plan
+
+# View Coding Plan team-edition models
+arkcli plans model-list --plan coding-plan-team
+
+# Query only directly invocable ModelNames (VirtualModelID only)
+arkcli plans model-list --plan coding-plan --mode direct
+
+# Query only ark-code-latest smart-routing candidates (LatestModel only)
+arkcli plans model-list --plan coding-plan --mode routing
+```
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|------|------|------|------|
+| `--plan` | No | string | Choose `coding-plan` or `coding-plan-team`; when omitted, auto-detect the only active Coding Plan and require an explicit value if multiple plans are active |
+| `--mode` | No | string | `all`, `direct`, or `routing`; defaults to `all`. `direct` fetches only direct ModelNames, while `routing` fetches only smart-routing candidates |
+
+## Return value
+
+```json
+{
+  "plan": "coding-plan-team",
+  "edition": "enterprise",
+  "tier": "pro",
+  "selected_model_id": "seed-2-0-pro-260215",
+  "models": [
+    {
+      "model_id": "seed-2-0-pro-260215",
+      "model_name": "Seed 2.0 Pro",
+      "output_name": "seed-2-0-pro",
+      "context_window": 262144,
+      "max_input_tokens": 229376,
+      "max_completion_tokens": 65536,
+      "input_modalities": ["text", "image", "video"],
+      "load": {"status": 1, "level": 2, "score": 0.46, "coverage": 0.92, "updated_at": 1789999999},
+      "selected": true
+    },
+    {
+      "model_id": "seed-pro-32k-260215",
+      "model_name": "Seed Pro 32K",
+      "output_name": "seed-pro-32k"
+    }
+  ],
+  "direct_models": [
+    {
+      "model_name": "seed-2.0-pro",
+      "context_window": 262144,
+      "max_input_tokens": 229376,
+      "max_completion_tokens": 65536,
+      "input_modalities": ["text", "image", "video"],
+      "load": {"status": 1, "level": 1}
+    }
+  ]
+}
+```
+
+| Field | Description |
+|------|------|
+| `plan` | Echo of the input argument |
+| `edition` | Plan API edition: `personal` for a personal plan or `enterprise` for a team plan |
+| `tier` | The active plan tier sent as `BizInfo` |
+| `selected_model_id` | Current backend model ID selected for the route; personal edition uses the subscription-level `Enabled` field, while team edition reads the user's seat mapping; omitted when unset |
+| `models[]` | Route candidates behind `ark-code-latest`; use these with `plans model-apply`, not as the direct ModelName catalog |
+| `models[].model_id` | Backend route-target ID for control-plane writes |
+| `models[].model_name` | Human-readable display name; do not use it as the invocation ID |
+| `models[].output_name` | Companion output name for route writes; do not infer direct invocation support from it |
+| `models[].selected` | `true` when this item is the current route target; omitted when false |
+| `direct_models[]` | Models directly invocable by the current plan, sourced from the VirtualModelID API |
+| `direct_models[].model_name` | Exact ModelName to put in an inference request or Agent configuration |
+| `*.context_window` | Context-window size in tokens; omitted when unavailable |
+| `*.max_input_tokens` | Maximum input-token length; omitted when unavailable |
+| `*.max_completion_tokens` | Maximum output-token length; omitted when unavailable |
+| `*.input_modalities` | Supported input modalities such as `text`, `image`, and `video` |
+| `*.load` | Server load snapshot; only `status=1` with `level=1/2/3` means low/medium/high load respectively |
+
+## Notes
+
+- With an explicit `--plan`, the CLI resolves that target's active tier. Without it, the CLI queries the current identity's Coding Plan subscriptions and selects only when exactly one is active; multiple active plans or any incomplete status lookup require an explicit target. Every model-list request still carries `Edition` and `BizInfo`.
+- `--mode all` queries both model interfaces. `--mode direct` queries only VirtualModelID and returns an empty `models` array. `--mode routing` queries only LatestModel and returns an empty `direct_models` array. Team routing may still read seat information to identify the selected route.
+- Personal and team editions use different sources for the current ark-code-latest selection:
+  - Personal: the server returns the model list + Enabled flag at subscription granularity.
+  - Team: reads `ExtraConfig.ArkCodeLatestMappingModelID` from the user's seat.
+- Do not mix the two lists: use `models[]` only for changing the `ark-code-latest` route, and use `direct_models[].model_name` for direct invocation or Agent configuration.
+- Model capability fields come directly from the plan model interface's `ModelCapability`. Missing fields are omitted; do not infer them from model names or overwrite them with another catalog.
+- The data represents models allowed during the subscription period and is not equivalent to all globally callable models. For trial models, use [`../arkcli-models/`](../../arkcli-models/SKILL.md).
+
+## References
+
+- [arkcli-plans](../SKILL.md) -- Skill overview
+- [`plans get`](arkcli-plans-get.md) -- First view which plans you hold
+- [arkcli-models](../../arkcli-models/SKILL.md) -- Model queries not limited to a plan
+- [arkcli-shared](../../arkcli-shared/SKILL.md)