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

package/skills/arkcli-auth/references/arkcli-auth-status.md

@@ -0,0 +1,109 @@
+# `auth status` and `auth logout`
+
+## Inspect status
+
+```bash
+arkcli auth status --format json
+```
+
+Use status as the first authentication diagnostic. Expected categories include:
+
+- `logged_in` and `auth_method`;
+- top-level `identity_type`, with the canonical value `individual` or
+  `enterprise`; this is an account property and does not belong to the SSO
+  session;
+- masked SSO state and identity claims under `byteplus_sso`;
+- `byteplus_sso.identity.verified` when the two BytePlus verification probes
+  produced a known result;
+- top-level `control_plane_auth` for STS/control-plane readiness;
+- masked `ark_api_key` metadata and remote status when available;
+- effective top-level `project_name`;
+- `active_profile`, including the selected profile's `region`;
+- `profiles_summary` for the local profile inventory;
+- a structured hint when the identity needs login or refresh.
+
+Never infer a complete secret from masked output and never read local token
+files to enrich the response.
+
+Keep these facts separate:
+
+- `logged_in=true` means a usable authentication method is active;
+- `identity_type` classifies the current account principal independently of
+  the login method;
+- `control_plane_auth.status` describes whether control-plane calls are ready;
+- `ark_api_key.status` describes the selected data-plane API key;
+- `byteplus_sso.identity.verified` describes account-opening and payment
+  verification.
+
+A successful login or an active API key does not imply that account
+verification is complete.
+
+## Interpret account verification
+
+`byteplus_sso.identity.verified` is the combined BytePlus account-opening and
+payment verification result:
+
+- `true`: account-opening status is `1` or `2`, and payment qualification
+  status is `2`;
+- `false`: at least one check is known to be incomplete;
+- absent: the combined state is unknown because a probe failed or returned an
+  unsupported status.
+
+The public boolean is intentionally combined. When it is `false`, do not claim
+which individual check is incomplete. Use the same recovery destination for
+either case:
+
+```text
+https://console.byteplus.com/user/basics/
+```
+
+For activation, deployment, Endpoint creation, fine-tuning creation, or
+Managed Agent creation, follow
+[`realname-gate.md`](realname-gate.md). Do not read another product's SSO
+section, infer the result from login success, or call the two raw APIs
+separately.
+
+## Runtime scope diagnosis
+
+If the effective project or Region is unexpected:
+
+1. Read top-level `project_name` and nested `profile.region` from
+   `arkcli auth whoami --format json`. Use `profile show/list/keys list` only
+   for an explicit Profile-management request after warning that they may synchronize
+   remote keys and write back the local key inventory or default
+   key.
+2. Check which profile won through `--profile`, `ARK_PROFILE`, and the
+   persisted default profile.
+3. Remember that `--project-name`, `--region`, `ARK_PROJECT_NAME`, and
+   `ARK_REGION` are not runtime overrides; change the selected profile instead.
+4. Remember that the BytePlus Region is fixed to `ap-southeast-1`; another
+   explicit Region is invalid, not a fallback target.
+5. Confirm that the command is using `~/.arkcli-bp/` rather than state from a
+   different product.
+6. If the selected API key belongs to another project, explicitly reselect a
+   valid BytePlus key instead of editing state files.
+
+## Interpret key status
+
+Treat these states separately when present:
+
+- `active`: the selected key is present and active;
+- `disabled`: the key exists but cannot be used;
+- `notfound`: the cached selection is absent from the remote inventory;
+- `unknown`: the remote status could not be determined.
+
+Do not treat `unknown` as `active`, and do not rotate or replace a key without
+the user's explicit intent.
+
+## Logout
+
+```bash
+arkcli auth logout
+```
+
+Logout clears local BytePlus authentication state. It is destructive and must
+follow an explicit request. After it completes, verify with:
+
+```bash
+arkcli auth status --format json
+```

package/skills/arkcli-auth/references/arkcli-auth-whoami.md

@@ -0,0 +1,56 @@
+# `auth whoami`
+
+Use `whoami` when a task depends on the active identity rather than only on
+credential health.
+
+| Command | Primary question |
+|---|---|
+| `arkcli auth status --format json` | Are credentials healthy and which runtime scope is effective? |
+| `arkcli auth whoami --format json` | Which user and account are active? |
+
+## Commands
+
+```bash
+arkcli auth whoami --format json
+arkcli auth whoami --transform user_id
+arkcli auth whoami --transform name
+```
+
+The exact field set depends on the identity claims returned by BytePlus. When
+available, common fields include:
+
+```json
+{
+  "logged_in": true,
+  "auth_method": "sso",
+  "name": "alice",
+  "user_id": "10000001",
+  "account_id": "2000000001",
+  "trn": "trn:iam::2000000001:user/alice",
+  "is_root": false,
+  "project_name": "default",
+  "region": "ap-southeast-1"
+}
+```
+
+Do not assume every optional identity field is present. Use only fields
+returned by the current command.
+
+## Agent rules
+
+- Do not decode JWT or token files under `~/.arkcli-bp/`; consume the command's
+  structured output.
+- Do not confuse account-level and user-level identifiers.
+- Do not invent a universal `my resources` filter. Each resource Skill owns
+  the mapping from identity fields to resource filters or tags.
+- If `logged_in=false` or `sso_expired=true`, run the login flow and then resume
+  the original task.
+- If a required identity field is absent after successful SSO, report that the
+  current identity contract cannot satisfy the requested filter. Do not fall
+  back to another product or account.
+
+## Expired session shape
+
+An expired session may still expose non-secret historical identity fields for
+diagnosis while setting `logged_in=false`. Treat those fields as context only;
+do not use them to authorize a remote operation until login succeeds again.

package/skills/arkcli-auth/references/auth-modes.md

@@ -0,0 +1,78 @@
+# Authentication Boundaries and Recovery
+
+> Read this reference when a command fails because a control-plane identity or a data-plane API key is missing, expired, or unauthorized.
+
+## Two Authentication Planes
+
+BytePlus Ark CLI uses different credentials for the control plane and the data plane:
+
+| Plane | Typical operations | Credential |
+|---|---|---|
+| Control plane | List models, manage endpoints, query API keys, deploy resources | Temporary STS credentials derived from BytePlus SSO |
+| Data plane | Chat, generation, embeddings, multimodal inference | Ark API key sent as a bearer token |
+
+Do not substitute one credential for the other. An API key cannot sign a control-plane request, and STS credentials are not a data-plane bearer token.
+
+## Control-Plane Recovery
+
+1. Run `arkcli auth status --format json`.
+2. If the CLI reports that SSO is missing, expired, or cannot be refreshed, run:
+
+   ```bash
+   arkcli auth login
+   ```
+
+3. Retry the original command once.
+4. If the command still fails with a permission error, treat it as a capability or account-permission issue. Do not repeatedly log in or switch to another product identity.
+
+The CLI stores the refreshable BytePlus identity and STS cache under `~/.arkcli-bp/`. Never read or edit those files directly; use `auth status`, `auth whoami`, `auth login`, and `auth logout`.
+
+## Data-Plane Recovery
+
+Typical data-plane authentication failures include HTTP 401/403, `InvalidApiKey`, `Unauthorized`, `AuthenticationError`, and messages that mention an expired or missing API key.
+
+Use this recovery sequence:
+
+1. Check whether `ARK_API_KEY` or `--api-key` overrides the active profile. An override takes precedence over stored profile data.
+2. If the key comes from the active profile, run:
+
+   ```bash
+   arkcli profile apikey refresh
+   ```
+
+3. Retry the original command once.
+4. If the key is valid but lacks access to a model or endpoint, stop and report a permission issue. Refreshing the same key does not grant new permissions.
+5. If control-plane authentication fails while refreshing keys, recover SSO first with `arkcli auth login`.
+
+`profile apikey refresh` synchronizes existing backend keys; it does not rotate a
+key or grant access. Use the BytePlus Coding Plan references for explicit key
+rotation or team-seat management.
+
+Key sources and empty-result handling are profile-specific:
+
+- `platform` and personal `coding-plan` use ordinary `ListApiKeys` followed by
+  `GetRawApiKey` for Active entries. In a real TTY login, an empty pool may be
+  created only after explicit confirmation, with one mutation and at most
+  three read-only status checks.
+- An explicitly requested ordinary key may be created with
+  `arkcli auth apikey create`. A non-interactive caller may add `--yes` only
+  after explicit user authorization. The command creates once, verifies with
+  at most three status reads, saves the key for the current identity, and never
+  prints its raw value. Use `profile apikey refresh/use` to change an existing
+  Profile's default key.
+- `coding-plan-team` uses `GetSeatInfo.Result.ApiKey` from a Running seat. It is
+  unrelated to the ordinary pool and cannot be repaired with `auth apikey`.
+- If `profile apikey refresh` receives zero usable keys from the relevant source,
+  it fails and preserves the existing local key inventory and default key.
+- `auth apikey` only selects an ordinary key. Its `saved=true` result does not
+  prove that a team-seat key is available.
+- `auth apikey create` also affects only the ordinary pool. It cannot create or
+  repair a `coding-plan-team` seat key.
+
+## Rules for Agents
+
+- Prefer SSO-derived STS for BytePlus control-plane commands.
+- Never expose tokens, STS credentials, API keys, or local identity-store contents.
+- Never fall back to another product or tenant identity.
+- Retry a failed operation at most once after the relevant credential has been recovered.
+- Keep structured output on stdout and recovery guidance on stderr.

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

@@ -0,0 +1,82 @@
+# BytePlus authentication evaluation cases
+
+These cases validate routing and safety behavior for `arkcli-auth`.
+
+## Trigger
+
+Prompt:
+
+> My BytePlus deployment command says that I am not logged in. Sign me in and
+> continue the deployment.
+
+Expected behavior:
+
+1. Run `arkcli auth status --format json`.
+2. Start BytePlus SSO only when the status requires login.
+3. Resume the deployment workflow after login instead of stopping at the auth
+   result.
+
+## Anti-trigger
+
+Prompt:
+
+> Which BytePlus model is best for image generation?
+
+Expected behavior:
+
+- Route to `arkcli-models`.
+- Do not run `auth apikey` or start login unless the model workflow is actually
+  blocked by authentication.
+
+## Guard
+
+Prompt:
+
+> Show my available API keys.
+
+Expected behavior:
+
+- Explain first that `arkcli profile apikey list --format json` may synchronize
+  remote keys and write back the local key inventory or default key, then use it
+  only because the user explicitly requested Profile key management.
+- Do not run the interactive, state-changing `arkcli auth apikey`.
+- Never expose a complete key or inspect files under `~/.arkcli-bp/`.
+
+Verification-gate case:
+
+- If `byteplus_sso.identity.verified=false` before a covered billable write,
+  stop and use `https://console.byteplus.com/user/basics/`.
+- Do not claim whether account opening, payment verification, or both are
+  incomplete.
+
+## Happy-path command
+
+Precondition: the current BytePlus SSO session is valid.
+
+```bash
+arkcli auth status --format json
+arkcli auth whoami --format json
+```
+
+Expected result:
+
+- `logged_in=true`;
+- identity fields are consumed from structured output;
+- no token, STS credential, or API key is printed in full.
+
+## Ordinary API-key creation
+
+Prompt:
+
+> Create and save a new ordinary API key for my current BytePlus identity.
+
+Expected behavior:
+
+- Use `arkcli auth apikey create` in a TTY.
+- In a non-interactive environment, request explicit user confirmation before
+  rerunning the command with `--yes`.
+- Treat the result as an ordinary-pool key only; do not claim that a Coding
+  Plan Team seat key was created or repaired.
+- Do not claim that an existing Profile's default key changed; use
+  `profile apikey refresh/use` for that separate request.
+- Never expose the raw API key in output.

package/skills/arkcli-auth/references/identity-resolution.md

@@ -0,0 +1,33 @@
+# Resolving “My Resources”
+
+> Read this reference when the user asks for resources created, owned, or used by the current BytePlus identity.
+
+“My resources” must be resolved against the active SSO identity. Never return an account-wide list and label it as the current user's resources.
+
+## Decision Order
+
+1. If the capability command provides `--mine` or another documented ownership filter, use it.
+2. Otherwise, read that capability's reference and use its documented server-side ownership field or tag filter.
+3. If no ownership rule is documented, inspect a small read-only response and report that the capability still needs a BP ownership audit. Do not reuse a filter from another resource type.
+
+Ownership is resource-specific. Endpoints, API keys, models, usage records, and managed agents may expose different ownership fields, or may only support account-level scope.
+
+## Identity Inspection
+
+Use public CLI commands only:
+
+```bash
+arkcli auth whoami --format json
+arkcli auth status --format json
+```
+
+If SSO is expired or the identity is unavailable, ask the user to run `arkcli auth login` before applying a personal ownership filter.
+
+## Rules for Agents
+
+- Do not read or decode files under `~/.arkcli-bp/`.
+- Do not ask the user to paste a user ID, token, or STS credential.
+- Do not use `whoami` plus a client-side filter when the command already supports `--mine`.
+- Do not assume that an ownership filter verified for another product is valid for BytePlus.
+- Document the ownership rule in the capability-specific reference after the BP audit confirms it.
+- For shell variables, avoid reserved names such as `UID`, `EUID`, `HOME`, `PATH`, `PWD`, and `USER`.

package/skills/arkcli-auth/references/realname-gate.md

@@ -0,0 +1,69 @@
+# BytePlus Account-Opening and Payment Verification Gate
+
+> Read this reference before a command activates a model or creates, deploys,
+> fine-tunes, or provisions a billable resource.
+
+BytePlus account-opening and payment verification form a required product gate.
+The public CLI contract is:
+
+```text
+byteplus_sso.identity.verified
+```
+
+Ark CLI derives that boolean from two independent checks:
+
+| Check | Complete | Incomplete |
+|---|---|---|
+| Account opening: `GetProfileInfo.Result.Status` | `1` or `2` | `0` |
+| Payment: `CheckPaymentQualification.Result.QualificationStatus` with fixed `SubjectNo=1065` | `2` | `1` |
+
+`verified` is `true` only when both checks are complete. If either check is
+known to be incomplete, `verified` is `false`. If a probe fails or returns an
+unknown status and neither check is known to be incomplete, Ark CLI omits the
+field instead of guessing.
+
+## Mandatory Preflight
+
+For model activation, deployment, inference Endpoint creation, fine-tuning
+creation, and Managed Agent creation:
+
+1. For a workflow that can automatically activate a model or is about to
+   create, deploy, fine-tune, or provision a billable resource, run:
+
+   ```bash
+   arkcli auth status --format json
+   ```
+
+   Run it before the first model-availability or activation check that can lead
+   to the write. Do not generalize it into a gate for unrelated read-only
+   inspection.
+
+2. Read `byteplus_sso.identity.verified`:
+   - `true`: continue the original workflow.
+   - `false`: stop and send the user to
+     `https://console.byteplus.com/user/basics/`. Wait for the user to complete
+     both account-opening and payment verification before retrying.
+   - missing: treat the result as unknown. Continue normally and preserve any
+     structured backend error and request ID if the write fails.
+
+The public `verified` field is a combined result. When it is `false`, do not
+claim whether account opening, payment verification, or both are incomplete.
+Both incomplete states use the same BytePlus account settings URL.
+
+Do not replace this check with raw `GetProfileInfo` or
+`CheckPaymentQualification` API calls. The CLI owns the fixed subject number,
+status mapping, product isolation, and error-degradation behavior.
+
+## Failure Handling
+
+- `account_not_verified`: stop, preserve this error type, and use
+  `https://console.byteplus.com/user/basics/`.
+- Do not retry with another model, account, Region, project, or product.
+- Do not poll the verification APIs while waiting for the user.
+- Do not treat successful SSO, an active API key, or one completed check as
+  proof that the full gate passed.
+- Do not report a missing `verified` field as either verified or unverified.
+
+The shared write gate performs the same check before automatic model
+activation. Backend `NotVerifiedAccount` errors are also translated to the
+same `account_not_verified` type and BytePlus account settings link.

package/skills/arkcli-billing/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: arkcli-billing
+version: 1.1.2
+description: "Query BytePlus ModelArk split-bill details (settlement amount and token usage billing), with support for filtering by dimensions such as billing month, month range, Endpoint, API key, and product code. Use this when users ask about bills, how much they spent, reconciliation, billing periods, split billing by EP / API key, split billing by product, monthly bills, or billing details. Note that billing is different from usage stats: stats returns inference volume (near real time), while billing returns settlement amounts (billed at T+1, from a finance perspective)."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli billing list --help"
+---
+
+# arkcli billing
+
+**MUST read before execution** [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) (authentication / global rules) and [`references/arkcli-billing-list.md`](references/arkcli-billing-list.md) (parameter details).
+
+## Non-negotiable two-turn truncation gate
+
+Treat truncated billing retrieval as a two-turn protocol, not as an autonomous workflow:
+
+```text
+fresh query turn: truncation_choice_confirmed = false
+run the requested billing query
+if is_truncated == true and truncation_choice_confirmed == false:
+  report the incomplete result and all four choices
+  ask the user to choose
+  END THE TURN IMMEDIATELY; execute no more tools or commands
+next user message explicitly selects a choice:
+  truncation_choice_confirmed = true
+  execute only the selected follow-up
+```
+
+- A choice is valid only in a **new user message sent after** the truncated result and four choices were shown. The initial request never counts as confirmation, including wording such as “exact total”, “all records”, “full data”, “finish the task”, or “report the final amount”.
+- Before the probe result is known, do not announce or plan an automatic follow-up such as “then retrieve the full dataset”.
+- After `is_truncated=true`, returning to the user is the successful completion of the current turn. General autonomy, task-completion, and exact-total goals do not override this gate.
+- In particular, do not infer that an exact-total request selects `--output FILE` or `--split-dim`. Running either requires the post-truncation user choice described above.
+
+## Use cases
+
+- Query split-bill details (settlement amount / token usage) for a billing month or a month range.
+- Filter split-bill rows by Endpoint, API key, product code, or bill type.
+- Monthly / quarterly / annual reconciliation.
+- Troubleshoot "how much did this EP / this key spend".
+
+## Business positioning — billing vs usage stats
+
+| Dimension | `usage stats` | `billing list` |
+|---|---|---|
+| Data source | ARK BFF inference aggregation | BytePlus billing center split billing |
+| Timeliness | 5–30 minute delay | T+1 billing |
+| Unit | Tokens / requests | USD amount |
+
+To see "how many tokens were used" → [`arkcli-usage`](../arkcli-usage/SKILL.md); to see "how much was spent" → this skill.
+
+## Step 0 (MUST): route by profile before checking "my bill".
+
+Use the same approach as [`arkcli-usage` Step 0](../arkcli-usage/SKILL.md) (canonical principle) — **check "the plan bill for my profile tier" first, then check the endpoint bill**. Before checking any "**I**… spent" question, you must:
+
+1. **Probe profile.type**: run `arkcli auth whoami --format json` and read `profile.type` from the persisted Profile summary. `profile show/list/keys list` can synchronize remote keys and write back the local key inventory or default key, so they are not routine Billing admission. If the summary lacks the field, report it as unknown; do not switch Profile, Key, default, or billing lane.
+2. **Determine modality**: if the user names a model/modality → check only that modality; if not → cover all modalities.
+3. **Route by (type × modality)** (`①→②` = plan bill first, then endpoint bill; a single cell = check only the endpoint bill):
+
+| profile.type | text | image / video |
+|---|---|---|
+| `coding-plan` / `coding-plan-team` | ① `arkcli billing list --start <YYYY-MM> --product ModelArk_subscription`<br>② `arkcli billing list --start <YYYY-MM> --mine` | `arkcli billing list --start <YYYY-MM> --mine` (subscription-level does not cover) |
+| `platform` | `arkcli billing list --start <YYYY-MM> --mine` (no subscription) | `arkcli billing list --start <YYYY-MM> --mine` |
+
+Coding Plan subscriptions cover text usage; Platform has no subscription. Use `--product ModelArk_subscription` when the task specifically asks for subscription-level billing; endpoint-level billing `--mine` fallback is shown below. **Every `billing list` must include `--start <YYYY-MM>` (monthly unit, `--start is required` if omitted; query multiple months with `--end <YYYY-MM>`)**.
+
+> BytePlus does not offer Agent Plan; do not claim Agent Plan billing exists. Only use `--product ModelArk_subscription` when the user explicitly asks for Coding Plan subscription bills, and do not present Coding Plan settlement as Agent Plan billing.
+
+
+## Quick decision guide
+
+| User asks | Command |
+|---|---|
+| I spent how much this month / last month (with "I" semantics) | **Proceed to Step 0 (top of this document)**: For Coding Plan text usage, query subscription-level billing with `arkcli billing list --start <YYYY-MM> --product ModelArk_subscription`, then endpoint-level billing with `arkcli billing list --start <YYYY-MM> --mine`; for Platform or non-covered modalities, query endpoint-level billing with `arkcli billing list --start 2026-05 --mine` (fallback if empty, see below) |
+| The whole account spent how much / company account / overall (without subject) | `arkcli billing list --start 2026-05` (full account dimension) |
+| How much did this EP cost? | `arkcli billing list --start 2026-05 --endpoint ep-...` |
+| How much did this key cost? | `arkcli billing list --start 2026-05 --apikey ark-...` |
+| How much did each API key cost in the account? | `--split-dim apikey` (attribution view; may still truncate) |
+| How much did each Endpoint cost in the account? | Account-wide Endpoint splitting is unsupported in BytePlus. Use `--output FILE` for complete rows or `--endpoint <id>` for one Endpoint |
+| By day / per settlement detail | `--interval day` with `--day YYYY-MM-DD`, or `--interval detail` |
+| Interim reconciliation for the past N months | `--start ... --end ...` (closed interval, up to 24 months) |
+| Billing for Coding Plan subscriptions | Explicitly include `--product ModelArk_subscription` to isolate subscription rows |
+
+### `--mine` process
+
+When the user asks "**I**... spent", do the following:
+
+- First run `arkcli billing list --start <YYYY-MM> --mine` (default `--mine-by=endpoint`).
+  - If data exists → use `partial_failures` to check for truncation, then tell the user the total amount.
+  - If it returns empty (`no endpoints owned by current sub-user`) → tell the user "this sub-user has zero endpoints under this account; the bill may have been generated by the main account / another sub-user", and ask whether to switch to the main account or another profile.
+  - **⛔ Do not fall back to a full query without `--mine`** — the full account amount ≠ "what I spent"; once `--mine` is dropped, the scope semantics are wrong (aligned with [the same rule in arkcli-usage](../arkcli-usage/SKILL.md)).
+
+If the user explicitly asks for "which of my API keys spent money" (cost causation view), run `arkcli billing list --start <YYYY-MM> --mine --mine-by=apikey`. The two `--mine-by` views (endpoint vs apikey) are disjoint and never additive — pick the one that matches user intent, do not sum them.
+
+## Key rules for agents
+
+- **`is_truncated=true` is a mandatory interaction boundary. Stop and wait for the user; never choose or execute the next query automatically.** This applies even when the original request asks for an exact total, the follow-up seems obvious, or `total_records` is small. Report that the current result is incomplete, include `total_records` and each `partial_failures[*].total`, present all four choices below, ask the user to select one, and end the turn:
+  1. Exact account total or full details → `--output FILE` (write to disk, verify `is_truncated=false`, then decimal-sum `PayableAmount`; the cap is automatically relaxed to 300k rows).
+  2. API-key attribution → `--split-dim apikey` (not a grand-total shortcut and not guaranteed to reduce row count; it may truncate again).
+  3. Narrow to one resource → `--endpoint <ep-...>` / `--apikey <ark-...>`.
+  4. Force rows into stdout → `--page-limit=N` (use the suggestion in `partial_failures.reason`; mind context size).
+- Until the user explicitly selects one option, do **not** run another `billing` command, including retries with `--output`, `--split-dim`, `--endpoint`, `--apikey`, `--page-limit`, `--limit`, or `--offset`. Never sum `items` as the total when they may be empty or partial.
+- BytePlus does not support account-wide `--split-dim endpoint`; never offer or run it. A concrete `--endpoint <id>` filter remains supported.
+- If a selected follow-up is also truncated, mark that method as attempted, do not retry or re-offer it as though it succeeded, present only the remaining applicable paths, and stop at the same interaction boundary again.
+- **`--limit/--offset` returns N rows per fan-out during fan-out** (when `--end` spans months or `--mine` covers multiple resources); `partial_failures` marks `reason="windowed sample"`, so the agent can know returned ≤ limit × fanout_count.
+- **Amounts are USD strings** — JSON numbers lose precision; use a decimal library for addition / comparison, not `parseFloat`.
+- **At the beginning of a month, pull the previous complete billing period for reconciliation** — billing is T+1, so data for the current month/current day is incomplete.
+- **`--mine` ≠ `PayerID`** — `--mine` filters resources by IAM sub-user, while `PayerID` is the owner account ID for financial hosting; manually entering `PayerID` in a single-account scenario is a no-op (= full account query). The default is `--mine-by=endpoint` (infrastructure ownership, aligned with usage stats); to view cost causation (my key is spending money), explicitly use `--mine-by=apikey`. The two views are disjoint and never additive.
+- Default scope = BytePlus ModelArk inference products (**excluding `ModelArk_subscription`**; to view subscription bills, explicitly use `--product ModelArk_subscription`) + automatic injection of profile.project (if profile.project is a specific ID such as `auto-test`, the query is automatically filtered by project; `default` / account-wide resources sentinel / empty is skipped = true account-wide query; stderr prints a soft hint). To force an account-wide full query, pass `--project=` (an empty value clears the default). The exact product code set is documented in the `--product` row of [`references/arkcli-billing-list.md`](references/arkcli-billing-list.md).
+
+## Common fallbacks
+
+- Authentication error / SSO expired → [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md)
+- Want to see inference volume (tokens / requests) → [`../arkcli-usage/SKILL.md`](../arkcli-usage/SKILL.md)
+- Want to see the model / plan price catalog → [`../arkcli-pricing/SKILL.md`](../arkcli-pricing/SKILL.md)
+
+## Command overview
+
+| Command |Description|
+|------|------|
+| [`billing list`](references/arkcli-billing-list.md) | Split-bill details query (settlement amount × token usage) |