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

package/skills/arkcli-usage/references/arkcli-usage-balance.md

@@ -0,0 +1,196 @@
+# usage balance
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+> **Difference from `stats` / `plan`:**
+> - `stats`: **consumption view** (tokens/calls already used).
+> - `plan`: subscription quota **snapshot** (used / total / reset).
+> - `balance`: **balance view**, unified entry for "how much X remains".
+>
+> Use `balance` when the user asks "how much X remains", routing by `--type`.
+>
+> **`balance --type plan` and `usage plan` expose the same data** (both call `QueryPlanUsage`, probe two SKUs, and share flags). Projection differs:
+> - `balance --type plan`: concise projection (removes `subscribed` / `updated_at` and adds a `"not subscribed"` hint).
+> - `usage plan`: complete projection (includes `subscribed: true/false`, CodingPlan `updated_at`, and other metadata).
+>
+> Use `balance --type plan` for a balance-oriented view together with free quota or media-asset capacity. Use `usage plan` for a complete plan quota snapshot together with stats.
+
+`arkcli usage balance` is a dispatcher; `--type` selects the data source and is **required**.
+
+## Commands
+
+```bash
+# Free model inference quota/resource-pack balance (ListModelChargeItems)
+arkcli usage balance --type free-quota
+arkcli usage balance --type free-quota --model dola-seed-2-1-turbo
+arkcli usage balance --type free-quota --modality LLM --page-size 20
+
+# Media asset library capacity (/open/GetAssetQuota)
+arkcli usage balance --type media-asset
+arkcli usage balance --type media-asset --project my-project
+
+# Subscription plan balance (QueryPlanUsage, concise output)
+arkcli usage balance --type plan
+arkcli usage balance --type plan --product coding-plan
+arkcli usage balance --type plan --all
+```
+
+## Parameter allowlist
+
+`--type` is required. Other flags are grouped by type. Passing a flag for the wrong type returns `ErrValidation` instead of being silently ignored, so users are not led to believe that an ineffective filter was applied.
+
+| `--type` | Allowed extra flags |
+|---|---|
+| `free-quota` | `--model` `--modality` `--page-number` `--page-size` |
+| `media-asset` | `--project` |
+| `plan` | `--product` `--all` `--seat` |
+
+### `--type free-quota`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `--model` | string | One foundation model; omitted lists all activated models |
+| `--modality` | string | Backend `FoundationModelDomain` enum: `LLM` / `ComputerVision` / `Audio` / `Embedding` / `Router` (**aliases are not accepted**) |
+| `--page-number` | int | 1-based page number |
+| `--page-size` | int | Default 50 |
+
+### `--type media-asset`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `--project` | string | Project name; defaults to the current `profile.ProjectName` |
+
+### `--type plan`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `--product` | string | `coding-plan` / `coding-plan-team` |
+| `--all` | bool | Query all products even if unsubscribed; mutually exclusive with `--product` |
+| `--seat` | string | Team only; filter one seat |
+
+## Return value
+
+### `--type free-quota`
+
+```json
+{
+  "page_number": 1,
+  "page_size": 50,
+  "total_count": 7,
+  "items": [
+    {
+      "model": "dola-seed-2-1-turbo",
+      "display_name": "Dola-Seed-2.1-turbo",
+      "vendor": "Dola",
+      "state": "Available",
+      "is_overdue": false,
+      "free_usage": { "total": 500000, "consumed": 12345, "remaining": 487655 },
+      "resource_packs": [
+        {
+          "type": "FreeInference",
+          "total": 500000, "consumed": 12345, "remaining": 487655,
+          "reclaimed": 0, "sync_time": "2026-06-04T12:00:00Z"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Key definitions**:
+
+- `free_usage.remaining = total - consumed` is already calculated; do not have the Agent recalculate it.
+- Model rows with both `free_usage` and `resource_packs` empty are omitted. `pricing models` provides the complete model table.
+- `resource_packs[].type` currently has only two BytePlus values: `FreeInference` (free inference) / `DataPermission` (data permission). There is no fine-tune resource pack. `Finetune` / `LoraFinetune` are unit-pricing types in `pricing models` under `ChargeItems.Type`, not balance dimensions.
+- A resource pack's `remaining` may be negative after expiration or downgrade when `consumed > total`; do not clamp it.
+
+### `--type media-asset`
+
+```json
+{
+  "tier": "advanced_monthly",
+  "assets":      { "total": 100000, "used": 23456, "remaining": 76544, "percent": 23.456 },
+  "asset_groups":{ "total": 100,    "used": 12,    "remaining": 88,    "percent": 12.0 },
+  "shared_pool": { "total": 1000000,"used": 0,     "remaining": 1000000,"percent": 0 },
+  "write_qpm": 600,
+  "capabilities": { "liveness_writable": true, "aigc_readable": true },
+  "projects": [
+    { "project_name": "default", "used": 23456, "allocated": false, "allocation": 0 }
+  ],
+  "updated_at_ms": 1717488000123
+}
+```
+
+**Key definitions**:
+
+- `tier`: `free` / `advanced` / `premium` / `advanced_monthly` / `premium_monthly`; monthly and annual subscriptions share these display values. An empty value means that the account has no media-asset subscription and the backend returned a zero-capacity free tier.
+- **`used > total` is valid** after an expired subscription is downgraded: `tier` becomes `free`, while `used` retains its previous value. `percent` may exceed 100 and `remaining` may be negative; do not clamp either.
+- `shared_pool` is omitted for accounts without the shared pool enabled because all its values are zero.
+- `capabilities` lists only enabled capabilities; an empty map means that all capabilities are disabled.
+- `projects[]` contains data only for enterprise accounts with project-level quota allocation enabled; it is normally empty for personal accounts.
+
+### `--type plan`
+
+```json
+{
+  "viewer": {
+    "auth_method": "sso",
+    "user_id": "12345",
+    "user_name": "alice",
+    "is_root": false,
+    "profile": "my-profile",
+    "tenant": "byteplus",
+    "region": "ap-southeast-1"
+  },
+  "items": [
+    {
+      "product": "coding-plan",
+      "edition": "personal",
+      "error": "not subscribed"
+    }
+  ]
+}
+```
+
+**Key definitions**:
+
+- **Top-level `viewer`**: identity summary for distinguishing the sub-user's own view, the root-account view, and another identity's view across SSO / AK/SK / API Key authentication. See the [`usage plan` viewer section](arkcli-usage-plan.md#viewer-fields-identity-summary).
+- **Probes both SKUs by default** (personal × 1 + team × 1), retrieving every plan balance under the account in one operation. Pass `--product=X` to query only one.
+- This output is **more concise than `usage plan`**: it removes the `subscribed` / `update_timestamp` metadata fields but retains `error` to distinguish "not subscribed", `AccessDenied`, and "no seat bound".
+- `error: "not subscribed"` is a balance-layer hint. The raw backend response is `Subscribed=false` with empty periods, which is not sufficiently clear for users.
+- **Team plans automatically resolve the caller's seat**: when `--seat` is omitted, the service calls `GetSeatInfo` to find the bound seat. If the plan is subscribed but no seat is assigned, it returns `error: "no seat bound to caller for ..."` to distinguish this case from "not subscribed".
+- The `coding-plan` backend returns only `percent`; `used` / `total` are omitted through JSON `omitempty`.
+- `periods[].reset_at` uses the same schema as `usage plan` and is returned in **RFC3339 Beijing time (UTC+08:00)**. It is omitted when the window contains no data.
+
+## Agent decisions
+
+| User asks | Command |
+|---|---|
+| Which models still have free quota | `arkcli usage balance --type free-quota` |
+| How many tokens model X has left | `arkcli usage balance --type free-quota --model X` |
+| Media capacity remaining/full | `arkcli usage balance --type media-asset` |
+| Plan remaining/reset date | `arkcli usage balance --type plan` |
+| Specific product balance | `arkcli usage balance --type plan --product coding-plan-team` |
+| Admin view of another seat | `arkcli usage balance --type plan --product coding-plan-team --seat <id>` |
+
+## Common errors
+
+| Error | Cause | Handling |
+|---|---|---|
+| `--type is required` | `--type` was omitted | Choose one of `free-quota` / `media-asset` / `plan` |
+| `--product is not valid for --type free-quota` | A flag was passed across types | Check that each flag matches `--type` in the allowlist above |
+| Empty `tier` + all values zero | Account has no media-asset subscription | The backend returned a valid zero-capacity free tier; subscribe through the BytePlus ModelArk console if needed |
+| `foundation model "X" not found in pricing list` (exit=2) | `--model X` is misspelled or absent from the pricing list | Check the spelling, or omit `--model` to list supported names |
+| `free-quota` returns `items: []` | `--modality` used an alias such as `text` / `video` instead of a backend enum; this path applies when `--model` is omitted | Pass `LLM` / `ComputerVision` instead |
+| Plan row has `error: "no seat bound"` | Team plan is subscribed but the caller has no assigned seat | Contact an admin to assign a seat, or explicitly pass `--seat <id>` |
+
+## Relation to other commands
+
+- **Unit price** → [`arkcli pricing models`](../../arkcli-pricing/references/arkcli-pricing-models.md)
+- **Complete subscription quota snapshot with `subscribed` and timestamps** → [`usage plan`](arkcli-usage-plan.md)
+
+## References
+
+- [arkcli-usage](../SKILL.md) — Usage overview
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — Authentication/global parameters
+- [arkcli-pricing](../../arkcli-pricing/SKILL.md) — Pricing catalog view

package/skills/arkcli-usage/references/arkcli-usage-plan.md

@@ -0,0 +1,153 @@
+# usage plan
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+> **Difference from `stats` / `billing`:**
+> - `usage stats`: token-billed **inference usage** (time series, 5–30 minute delay).
+> - `billing list`: monthly **settlement amount** (BytePlus billing-center breakdown, T+1).
+> - `usage plan`: **subscription plan quota snapshot** for CodingPlan (real-time "My plans" backend data, matching BytePlus ModelArk console 1:1).
+>
+> "How many tokens/requests did I use?" → stats; "How much money?" → billing; "How much plan quota remains / percentage used / reset date?" → **plan**.
+
+Query subscription quota snapshots. A plan is not queried as a time series; it returns **used / total / reset time for the current effective subscription by window (5h / weekly / monthly / session)**.
+
+## Commands
+
+```bash
+# Default: concurrently probe both products (personal × 1 + team × 1);
+# issue usage requests only for detected buckets, returning all active subscription balances
+arkcli usage plan
+
+# Human-readable quota card only (no JSON; ANSI-free when piped)
+arkcli usage plan --render
+
+# Explicit product (skip discovery and query one bucket)
+arkcli usage plan --product coding-plan
+arkcli usage plan --product coding-plan-team
+
+# Force both buckets (personal + team) regardless of subscription (diagnostic / Excel view)
+arkcli usage plan --all
+
+# Query a specified team seat (bypass automatic caller-seat resolution through GetSeatInfo)
+arkcli usage plan --product coding-plan-team --seat seat-001
+```
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|------|------|------|------|
+| `--product` | No | string | Explicit product ID: `coding-plan` / `coding-plan-team`; omitted means automatic subscription discovery |
+| `--all` | No | bool | Force both products, including unsubscribed buckets. **Mutually exclusive with `--product`** |
+| `--seat` | No | string | Team product only. Omitted: service calls `GetSeatInfo` to find caller seat; provided: skip RPC and use this SeatID (admin view) |
+| `--render` | No | bool | Print only the human-readable quota card, never JSON. Uses color on a TTY and plain Unicode bars in pipes; cannot be combined with explicit `--format` or `--transform` |
+
+## Default behavior (no `--product` / `--all`)
+
+Without a product, behavior is unified (`profile.Type` no longer derives one bucket; since V2, all subscriptions are probed because one identity may hold multiple products):
+
+1. Probe the two buckets' subscription status concurrently:
+   - **Personal × 1** via `ListSubscribeTrade` (`ResourceNames=[""]`).
+   - **Team × 1** via `GetSeatInfo(Scene="")`. The enterprise edition is not exposed through `ListSubscribeTrade` and returns null in testing, so caller-seat binding status is used instead.
+2. Send usage RPC for detected buckets:
+   - `coding-plan` personal → `GetCodingPlanUsage`.
+   - `coding-plan-team` → use resolved SeatID → `GetSeatInfoUsage(SeatID=id, Scene="")`.
+3. Failure in one bucket does not block others (per-bucket error isolation).
+
+> **One extra RPC for zero-flag UX**: concurrent `ListSubscribeTrade × 1 + GetSeatInfo × 1` takes ~50 ms, much less than querying products serially. Pass `--product` to skip discovery.
+>
+> **Silent team-bucket rule**: if caller has no seat, the team bucket does **not appear** in default discovery, preventing misleading "no seat bound" for admins without enterprise purchase. Use `--all` to show both buckets including the error row.
+
+## Return value
+
+JSON shape (top-level `viewer` + `items`):
+
+```json
+{
+  "viewer": {
+    "auth_method": "sso",
+    "is_root": false,
+    "user_id": "12345",
+    "user_name": "alice",
+    "account_id": "210000",
+    "profile": "my-profile",
+    "tenant": "byteplus",
+    "region": "ap-southeast-1",
+    "project_name": "default"
+  },
+  "items": [
+    {
+      "product": "coding-plan",
+      "edition": "personal",
+      "tier": "lite",
+      "subscribed": true,
+      "periods": [...]
+    },
+    {
+      "product": "coding-plan-team",
+      "edition": "team",
+      "tier": "lite",
+      "seat_id": "seat-001",
+      "subscribed": true,
+      "periods": [...]
+    }
+  ]
+}
+```
+
+### `viewer` fields (identity summary)
+
+```
+viewer.auth_method  = sso | aksk | apikey | none
+viewer.is_root      = SSO root account (JWT trn contains :root)
+viewer.user_id      = SSO sub-user ID (normally empty for AK/SK / APIKey)
+viewer.user_name    = SSO sub-user name
+viewer.account_id   = JWT sub claim
+viewer.profile      = current active profile name
+viewer.tenant       = byteplus
+viewer.region       = active region
+viewer.project_name = active project
+```
+
+**Purpose**: Sub-user and root views are easily confused. `viewer` tells the user/Agent "whose data this is":
+- Sub-user SSO → `is_root=false`; user_id/name identify the sub-user, and the view shows that user's bound seat.
+- Root SSO → `is_root=true`; root/account subscription view.
+- AK/SK → `auth_method=aksk`, user_id normally empty; backend resolves IAM identity from AK/SK.
+- APIKey → `auth_method=apikey`; scope follows the identity bound to the API Key.
+
+### Field descriptions
+
+| Field | Description |
+|---|---|
+| `product` | `coding-plan` / `coding-plan-team`, matching `profile.Type` |
+| `edition` | `personal` / `team` |
+| `tier` | Actual subscription tier (`lite/pro`) returned by backend; CodingPlan often absent |
+| `subscribed` | Whether current identity has an active subscription; for CodingPlan, `QuotaUsage` non-empty |
+| `periods[].label` | CodingPlan: `session` / `weekly` / `monthly`, sorted canonically |
+| `periods[].used` / `total` | The CodingPlan backend returns only `Percent`; `used` / `total` are omitted through JSON `omitempty` |
+| `periods[].percent` | Percentage used (0–100). CodingPlan passes the backend `Percent` through directly |
+| `periods[].reset_at` | Next reset time in **RFC3339 Beijing time (UTC+08:00)**. Internally, the service normalizes backend seconds to epoch milliseconds before the output layer formats them; a no-data sentinel is omitted |
+| `updated_at` | CodingPlan only; backend `UpdateTimestamp` epoch ms |
+| `error` | Per-bucket failure reason; one bucket does not block others. A team-product `NotImpl` error also uses this field |
+
+## Error handling
+
+- **AccessDenied/network**: written to corresponding `items[].error`; other buckets unaffected.
+- **Unsubscribed**: empty CodingPlan `QuotaUsage` → `subscribed:false`.
+- **Team subscribed but caller has no seat**: `subscribed:true` + `error:"no seat bound to caller for ..."`; pass `--seat <id>` to bypass.
+- **Product typo**: outside the `coding-plan` / `*-team` set → `ErrValidation` immediately, without sending a request.
+- **`--all` + `--product`**: mutually exclusive ErrValidation.
+- **All auto-discovery fails**: returns `auto-discover subscriptions: <err>` (for example, backend rejection such as `MissingParameter.ResourceNames`); use explicit `--product`.
+
+## AI Agent decision path
+
+- "How much plan used/remains?" → `arkcli usage plan`.
+- "How many plans do I have?" → `arkcli usage plan --all`; buckets with `subscribed=true` are held.
+- "Admin view of another team seat" → `arkcli usage plan --product coding-plan-team --seat <id>`.
+- "Why are plan items empty?" → probably no products under current identity; route to [arkcli-pricing](../../arkcli-pricing/SKILL.md) for catalog pricing.
+
+## API alignment
+
+- CodingPlan personal: `/open/GetCodingPlanUsage`.
+- CodingPlan team: `/open/GetSeatInfoUsage`.
+- Auto-discovery uses a `ListSubscribeTrade` payload for personal × 1. The enterprise edition is not exposed through `ListSubscribeTrade`, so `GetSeatInfo(Scene)` probes the caller's seat-binding status instead.
+- Team SeatID resolution: `/open/GetSeatInfo` without a SeatID resolves the bound seat from caller identity + Scene. Scene **must be an empty string** (CodingPlan enterprise; this is the backend default). Early use of `coding_plan` returned an empty SeatID without an error.

package/skills/arkcli-usage/references/arkcli-usage-seats.md

@@ -0,0 +1,199 @@
+# usage seats
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+> **Difference from other commands:**
+> - `usage plan` / `balance --type plan`: the **caller's own** subscription balance (a sub-user views their own seat).
+> - `usage seats`: **admin view** listing **all seats** in a team.
+>
+> Sub-users normally receive `AccessDenied`; admin/root SSO is required.
+
+## Commands
+
+```bash
+arkcli usage seats --product coding-plan-team \
+  [--biz-info lite|pro] \
+  [--billing-status Pending|Running|Expired|Reclaimed] \
+  [--seat-status Idle|Active] \
+  [--user-id <id>] [--user-name <name>] [--seat-id <id>] \
+  [--project <project>] [--with-usage]
+
+# List all CodingPlan team seats
+arkcli usage seats --product coding-plan-team
+
+# Filter by BizInfo tier
+arkcli usage seats --product coding-plan-team --biz-info lite
+
+# Filter by BillingStatus (prepare reclaimed seats for cleanup)
+arkcli usage seats --product coding-plan-team --billing-status Reclaimed
+
+# Query the seat bound to a specified sub-user
+arkcli usage seats --product coding-plan-team --user-id 12345
+arkcli usage seats --product coding-plan-team --user-name alice
+
+# Multiple users (client-side parallel fan-out and merge)
+arkcli usage seats --product coding-plan-team --user-name alice --user-name bob --user-name charlie
+
+# Cross-field combination = AND (Alice's seats whose status is Running)
+arkcli usage seats --product coding-plan-team --user-name alice --billing-status Running
+
+# Single page (disable auto-pagination)
+arkcli usage seats --product coding-plan-team --page-number 1 --page-size 50
+
+# === --with-usage: also retrieve each seat's usage ===
+arkcli usage seats --product coding-plan-team --with-usage  # Percent only (CodingPlan backend exposes only percentage)
+```
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `--product` | Yes | string | Team plan ID: `coding-plan-team`. **Personal plans are unsupported** because they have no seat concept |
+| `--biz-info` | No | string | Tier filter: `lite/pro` (CodingPlan) |
+| `--billing-status` | No | string slice | Billing status filter (repeatable): `Pending` / `Running` / `Expired` / `Reclaimed` |
+| `--seat-status` | No | string | Seat status: `Idle` / `Active`. `Idle` means unbound and available; `Active` means bound |
+| `--user-id` | No | string slice | Filter by sub-user ID (repeatable; more than one value triggers client-side parallel fan-out) |
+| `--user-name` | No | string slice | Filter by sub-user name (repeatable; more than one value triggers client-side parallel fan-out) |
+| `--seat-id` | No | string slice | Specify a SeatID (repeatable; sent as a native wire array in one call) |
+| `--project` | No | string | Project filter; defaults to the active profile's project when omitted |
+| `--page-size` | No | int | Page size; default 100 |
+| `--page-number` | No | int | 1-based page number; **explicitly setting it disables auto-pagination** and retrieves only that page |
+| `--sort-by` / `--sort-order` | No | string | Sort field / ascending or descending order |
+| `--with-usage` | No | bool | **Team products only**: join each seat's usage. CodingPlan team uses `ListSeatInfoUsages` and returns `coding_usage{periods[session/weekly/monthly with percent/reset_at]}`. `reset_at` is returned in RFC3339 Beijing time (UTC+08:00) |
+
+Unknown seat or billing status values fail validation and never degrade to an unfiltered query.
+
+## Default behavior: auto-pagination
+
+Without `--page-number`, the service layer automatically follows `NextToken` until the last page (maximum 30 pages × 100 = 3,000 seats). Reaching the limit reports an error and directs the user to paginate manually.
+
+## Multi-value filter semantics
+
+Different flags have an **AND** relationship: each flag is a narrowing filter, as in a SQL `WHERE` clause or kubectl `-l`. Multiple values for the same flag have an **OR** relationship.
+
+| Example | Semantics | Wire calls |
+|---|---|---|
+| `--seat-id sa --seat-id sb` | seat ∈ {sa, sb} | One native `Filter.SeatIDs:["sa","sb"]` call |
+| `--user-name a --user-name b` | user = a OR user = b | **Two parallel calls** (client-side fan-out; wire `Filter.UserName` is scalar and does not accept an array) |
+| `--seat-id sa --user-name a` | seat ∈ {sa} AND user = a | One call |
+| `--seat-id sa --user-name a --user-name b` | seat ∈ {sa} AND user ∈ {a,b} | Two calls, each with same SeatIDs |
+| `--user-name alice --billing-status Reclaimed` | user = alice AND billing = Reclaimed | One call |
+
+Equivalent SQL: `WHERE seat_id IN (...) AND user_name IN (...) AND billing_status IN (...)`.
+
+### The union you do not get—intentionally
+
+```bash
+# Does not return the union of seat sa plus all of Alice's seats
+arkcli usage seats --seat-id sa --user-name alice
+# Actual: only sa, and only if it belongs to Alice
+```
+
+To request the union of "seat sa **or** Alice's seats", run two commands and merge the results on the client:
+
+```bash
+{ arkcli usage seats --product ... --seat-id sa
+  arkcli usage seats --product ... --user-name alice; } | jq -s '...'
+```
+
+The CLI intentionally avoids implicit OR. Its filter safety contract is that filters can only narrow results; unexpectedly broadening results can cause incorrect statistics or cleanup.
+
+### What fan-out means
+
+You only need this detail when working directly with the wire API. Wire `Filter.UserID / UserName` fields are scalar, and arrays are rejected with `InvalidParameter`. For multiple users, the service layer starts N goroutines, sends one scalar RPC for each user, deduplicates the client-side results by `SeatID`, and merges them. Consequences:
+
+- **Latency** = the slowest of N concurrent requests, not their sum.
+- **Backend load** = N times. Dozens of users are acceptable; for hundreds, use `--all` and filter on the client.
+- **Consistency** = separate calls have a seconds-level time window, so a race is theoretically possible if a seat is unbound during the query. This is acceptable for admin inventory.
+- If any user query fails, the entire request fails and identifies which user failed; no partial results are returned.
+
+## Return value
+
+```json
+{
+  "items": [
+    {
+      "seat_id": "seat-001",
+      "account_id": "210000",
+      "project_name": "default",
+      "biz_info": "lite",
+      "billing_status": "Running",
+      "seat_status": "Active",
+      "identity_type": "IAMUser",
+      "instance_id": "inst-xxx",
+      "order_time": 1700000000000,
+      "expired_time": 1717000000000,
+      "create_time": 1700000000000,
+      "update_time": 1716000000000
+    }
+  ],
+  "total": 30,
+  "biz_summaries": [
+    { "biz_info": "lite", "total_count": 30, "active_count": 25 }
+  ]
+}
+```
+
+### Fields
+
+| Field | Meaning |
+|---|---|
+| `seat_id` | Unique seat identifier |
+| `biz_info` | Tier |
+| `billing_status` | Billing status (`Running` is billed; `Reclaimed` has been reclaimed) |
+| `seat_status` | Binding status: `Idle` is unbound and available; `Active` is bound |
+| `identity_type` | Bound identity type (e.g. `IAMUser`) |
+| `order_time` / `expired_time` | Order / expiration time in epoch milliseconds |
+| `total` | Total number of records matching the filters according to the backend |
+| `biz_summaries[]` | Summary by tier; for example, 30 `lite` seats purchased and 25 activated |
+
+> **BytePlus seat item does not carry `user_id`, `user_name`, or `bind_count`.** The `identity_type` field indicates the identity class, but the seat listing itself does not expose which named sub-user is bound to each seat, nor the current-month binding count. Consumers that need "which seat belongs to which employee" must correlate `seat_id` with an external identity source (organization roster, IAM API), or filter with `--user-id` / `--user-name` (see next section for filter-side caveats).
+
+## Admin workflows
+
+**Scenario 1**: View the team's overall subscription status
+
+```bash
+arkcli usage seats --product coding-plan-team
+# Use biz_summaries to see how many seats were purchased and activated in each tier
+```
+
+**Scenario 2**: Find reclaimed (expired) seats for processing
+
+```bash
+arkcli usage seats --product coding-plan-team --billing-status Reclaimed
+```
+
+**Scenario 3**: Find the seats bound to a specific sub-user
+
+```bash
+arkcli usage seats --product coding-plan-team --user-name alice
+```
+
+The filter narrows the returned list to seats bound to Alice, but the returned rows themselves do **not** carry `user_name` — the caller only sees `seat_id` and cannot use the response alone to confirm "this specific seat belongs to Alice" for a multi-seat result set. If the user needs a seat→employee mapping in the output, correlate with an external identity source.
+
+**Scenario 4**: Check the current state of specified SeatIDs
+
+```bash
+arkcli usage seats --product coding-plan-team --seat-id seat-001 --seat-id seat-002
+```
+
+## Common errors
+
+| Error | Cause | Handling |
+|---|---|---|
+| `--product is required and must be a team plan` | Missing or set to a personal plan | Pass `coding-plan-team` |
+| `AccessDenied` | Caller is not an admin | Ask an admin to run the command, or have the sub-user use `usage plan` to view their own seat |
+| `exceeded auto-paginate limit (30 pages)` | Team has more than 3,000 seats | Paginate manually with `--page-number` |
+
+## Relation to other commands
+
+- Sub-user's own seat → [`usage plan`](arkcli-usage-plan.md) / [`usage balance --type plan`](arkcli-usage-balance.md)
+- Account-level model free quota → [`usage balance --type free-quota`](arkcli-usage-balance.md)
+
+## API alignment
+
+- Wire path: `/open/ListSeatInfos` (OpenAPI). `--with-usage` makes an additional call:
+  - CodingPlan team → `/open/ListSeatInfoUsages` (SeatIDs are required, collected from `ListSeatInfos`, and passed in batches of no more than 1,000).
+- Pagination uses `NextToken` (cursor), not PageNum.
+- On BytePlus, `ListSeatInfos` returns seat metadata (`seat_id`, tier, status, lifecycle timestamps) but omits identity-detail fields such as the bound sub-user's ID/name and the current-month binding count. `--user-id` / `--user-name` still filter at the wire level, but the response body does not echo those values back.