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

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

@@ -0,0 +1,259 @@
+# billing list
+
+> **Prerequisite**: Read [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first (authentication / global parameters).
+
+> **`billing list` vs `usage stats`**: stats shows "how many tokens were used" (near real time, aggregated by ARK BFF); billing shows "how much money was spent" (T+1 billing, BytePlus Billing Center).
+
+Query split bill details for a specified billing period (YYYY-MM) or month range.**Default full pagination**. If the service internal cap (~3,000 rows / 1 MB JSON) is hit, **soft truncation** is used (no hard fail): the data already fetched is returned normally + `is_truncated=true` + `partial_failures` marks which fan-outs were truncated + a strong warning is printed to stderr.`--limit/--offset` switches to explicit pagination mode (N rows per fan-out when spanning fan-outs).
+
+**Core discipline**: check `is_truncated` and `partial_failures` before using any returned row. When `is_truncated=true`, the result is incomplete and the agent must not sum it or choose a follow-up itself. Report the scale, present all four choices documented below, ask the user to select one, and stop. Run a follow-up command only after the user explicitly chooses.
+
+**Two-turn requirement**: the user choice must arrive in a new message after the agent has displayed the truncated result and four choices. Intent expressed in the original query—including “exact total”, “all records”, or an explicit desired final answer—is not a choice and cannot authorize `--output`, aggregation, pagination, or narrowing. Do not pre-plan a second command before the first result. When the first result is truncated, end the turn immediately after asking the question.
+
+> **Using `--start` alone = single-month query** (not an open interval through today).`billing list` uses month-level granularity, and the wire has a single `BillPeriod` parameter — to query a multi-month range, you must use `--end` (for example: `--start 2026-03 --end 2026-05`, simulated by client fan-out). This is different from the day-level `--start --end` in `usage stats`.
+
+## Commands
+
+```bash
+# Single-month summary (most common) — default: BytePlus ARK product allowlist (excluding subscriptions) + profile.project
+# Automatically injected (if profile.project is a specific ID, such as "auto-test"); profile.project="default" /
+# Account-wide resource sentinel / empty value skips injection = real account-wide query. A soft hint is printed to stderr.
+arkcli billing list --start 2026-05
+
+# Multi-month range (closed interval, up to 24 months)
+arkcli billing list --start 2026-03 --end 2026-05
+
+# By day / by each settlement detail
+arkcli billing list --start 2026-05 --interval day --day 2026-05-15
+arkcli billing list --start 2026-05 --interval detail
+
+# Single-value scope (choose one of three, mutually exclusive)
+arkcli billing list --start 2026-05 --endpoint ep-...
+arkcli billing list --start 2026-05 --apikey ark-...        # Automatically reverse-looks up the SID through the server
+arkcli billing list --start 2026-05 --apikey-sid apikey-... # advanced, skips reverse lookup
+
+# Account-dimension slicing (API-key attribution only)
+arkcli billing list --start 2026-05 --split-dim apikey      # Which API keys incurred cost; may still truncate
+
+# BytePlus does not support account-wide --split-dim endpoint.
+# To inspect one Endpoint, use the explicit resource filter instead:
+arkcli billing list --start 2026-05 --endpoint ep-...
+
+# My own costs (from the SSO subuser perspective)
+arkcli billing list --start 2026-05 --mine                  # Defaults to --mine-by=endpoint (infra ownership)
+arkcli billing list --start 2026-05 --mine --mine-by=apikey # Cost-causation view (which of my API keys spent money)
+
+# Other filters
+arkcli billing list --start 2026-05 --product ModelArk_subscription  # Isolate subscription bills
+arkcli billing list --start 2026-05 --bill-category consume-use --billing-mode 2
+arkcli billing list --start 2026-05 --ignore-zero
+```
+
+## Parameter
+
+| Parameter | Required |Description|
+|------|---|------|
+| `--start` | **Yes** | A single billing period `YYYY-MM` (within the past 24 months) |
+| `--end` | No| Range endpoint `YYYY-MM` (closed interval, omitted = single month, up to 24 months) |
+| `--day` | No| Billing date `YYYY-MM-DD`, **only `--interval=day\|detail` takes effect**, incompatible with `--end` |
+| `--interval` | No| `month` (default) / `day` / `detail` |
+| `--endpoint` / `--apikey` / `--apikey-sid` | No| Single-value scope, mutually exclusive among the three options (single SplitItemID value).`--apikey ark-*` is automatically reverse-looked up into a SID through the server; `--apikey-sid` skips reverse lookup |
+| `--split-dim` | No| Account-dimension slicing: `apikey` only in BytePlus. This is an attribution view, not a guaranteed row-reduction or grand-total shortcut. Account-wide `endpoint` is rejected; use `--endpoint <id>` for one Endpoint |
+| `--product` | No| BytePlus product code (repeatable). The default lock covers the API-key-splittable BytePlus ModelArk products in the "Product codes" section below; subscriptions = `ModelArk_subscription` (excluded from the default; pass explicitly to include) |
+| `--project` | No| Project ID (repeatable).**If not passed, the profile ProjectName is automatically used as the default value**; `--project=` (empty) = account-wide query |
+| `--instance-no` | No| Billing instance ID |
+| `--bill-category` | No| `consume-use` / `consume-new` / `consume-renew` / `consume-formalize` / `consume-modify` / `consume-trial` / `refund-terminate` / `refund-modify` / `transfer-manual` / `transfer-system` |
+| `--billing-mode` | No| `1` subscription / `2` pay-as-you-go / `3` contract / `4` fulfillment |
+| `--ignore-zero` | No| Skip rows with discounted price = 0 |
+| `--mine` | No| View only bills for resources under the current SSO subuser. The dimension is determined by `--mine-by`.**Mutually exclusive with `--endpoint` / `--apikey` / `--apikey-sid` / `--split-dim`**. Subscriptions are not included (no IAM ownership) |
+| `--mine-by` | No| `endpoint` (default, **infra ownership** — bills on EPs I deployed, including calls made by others) / `apikey` (**cost causation** — bills generated by keys I created). The two views cannot be added together. The former aggregates by infra, and the latter aggregates by payer |
+| `--limit` / `--offset` | No| Pagination mode (Limit 1-300, hard wire upper limit), returns a single page directly. During fan-out, this means **N rows per fan-out** (multi-month `--end` / multiple resources with `--mine`), and `partial_failures[]` marks `windowed sample` |
+| `--output` | No| Write the complete JSON (items + summary + partial_failures) to FILE, leaving only metadata on stdout to avoid blowing up the context. Automatically relaxes the internal cap to 300k rows |
+
+## Scope view capabilities
+
+Different scopes cover different bill subsets. **`ModelArk_subscription` (Coding Plan) can only be viewed at the account dimension. It is not visible in any IAM/EP/apikey dimension** (account-level ownership, no IAM owner).
+
+| View | ModelArk inference (default lock) | Subscriptions (`ModelArk_subscription`) |
+|---|---|---|
+| Bare run (default) | ✅ | ❌ (default Product lock filter) |
+| `--product ModelArk_subscription` | ❌ | ✅ |
+| `--product ModelArk --product ModelArk_subscription` | ✅ (only the specified subset) | ✅ |
+| `--endpoint` / `--apikey` / `--apikey-sid` / `--split-dim apikey` / `--mine` | Respective scopes | ❌ |
+
+**Cross-product coverage of `--mine-by=endpoint`**: SplitItemID `ep-...` is a cross-product unique primary key. Bills for endpoints created by `+deploy` are placed under different Product parameters depending on modality (LLM / image / video / managed agents / third-party, see the "Product codes" table); the service layer does not lock Product for scope-narrowed queries, allowing the wire to naturally hit across products by SplitItemID. Therefore, `--mine --mine-by=endpoint` also includes bills for image / video EPs. The same consumption appears once in each of the two mine views, so **they cannot be added together**.
+
+**`--mine` ≠ `PayerID`**:
+- `--mine` filters by **IAM subuser** UserID (the client first lists my resource IDs, and the service layer performs per-resource fan-out).
+- The wire `PayerID` / `OwnerID` is the **account owner ID** (10-digit integer), used in financial hosting scenarios.
+- In a single-account scenario, manually writing `--params '{"PayerID":[<my account ID>]}'` is a no-op (= account-wide query); use `--mine` to view your own data.
+
+## Product codes (BytePlus default lock)
+
+The default lock covers these BytePlus ModelArk inference products. Bare `billing list` runs are filtered to this set; to include subscriptions or other products, override with `--product`.
+
+| Product code | Description |
+|---|---|
+| `ModelArk` | LLM inference |
+| `ModelArk_open_source_llm` | Open-source LLM inference |
+| `ModelArk_video_generation` | Video generation |
+| `ModelArk_managed_agents` | Managed agents |
+| `Smart_Drawing_T2I` | Image generation (text-to-image) |
+| `hitem_third_party` | Third-party integration |
+| `rodin_third_party` | Third-party integration |
+
+Subscription (`ModelArk_subscription`, Coding Plan) is a separate product excluded from this default; pass `--product ModelArk_subscription` explicitly to view it (see "Scope view capabilities" above).
+
+## Return values
+
+```json
+{
+  "items": [
+    {
+      "BillPeriod":         "2026-05",
+      "BillingDate":        "2026-05-15",
+      "Product":            "ModelArk",
+      "ProductZh":          "BytePlus ModelArk LLM inference",
+      "SplitItemID":        "ep-...",
+      "SplitItemName":      "seed-pro-4k-prod",
+      "Currency":           "USD",
+      "OriginalBillAmount": "123.4500",
+      "PreferentialAmount": "10.0000",
+      "PayableAmount":      "113.4500",
+      "Count":              "1234567",
+      "Unit":               "thousand tokens"
+    }
+  ],
+  "total_records": 87881,
+  "returned": 3000,
+  "is_truncated": true,
+  "partial_failures": [
+    {
+      "period": "2026-05",
+      "total": 87881,
+      "returned": 3000,
+      "reason": "exceeds 10 pages cap (3000 rows scanned, total 87881 rows). Options: --output FILE for complete data; --split-dim apikey for API-key attribution (may still truncate); --endpoint/--apikey to narrow scope; --page-limit=N to raise the cap"
+    }
+  ]
+}
+```
+
+| Parameter | Meaning |
+|------|------|
+| `BillPeriod` / `BillingDate` | Billing period / billing date (BillingDate may be empty when interval=month) |
+| `Product` / `ProductZh` | Product code / Chinese name |
+| `SplitItemID` / `SplitItemName` | Split item ID / name (endpoint or apikey, depending on the scope) |
+| `Currency` | Usually `USD` |
+| `OriginalBillAmount` | Amount before discounts |
+| `PreferentialAmount` | Discount / resource pack deduction amount |
+| `PayableAmount` | **Payable amount** (= Original - Preferential, primary reconciliation parameter) |
+| `Count` / `Unit` | Metered value / unit |
+| `total_records` / `returned` / `is_truncated` | summary header: actual total count on the server / rows returned this time / whether it is truncated |
+| `partial_failures` | Soft truncation / sample marker array (hit the cap or windowed); each item contains `period` / `resource` / `total` / `returned` / `reason`. **Must check when `is_truncated=true`** |
+
+> Amount fields are strings. Use a decimal library for addition/comparison, not `parseFloat` (JSON number precision is lossy).
+
+## Soft truncation (cap / windowed) decisions
+
+When hitting the cap or explicitly using `--limit/--offset`, the service **does not hard fail**. It returns fetched data + a summary header + a strong warning in stderr. Nevertheless, `is_truncated=true` is a mandatory interaction boundary: report the incomplete result, present all four choices, and wait for the user. Do not pick or execute a recommendation automatically, even for a small result set or an exact-total request.
+
+Use this state test before every follow-up:
+
+```text
+may_continue = previous assistant turn reported this truncation and asked for a choice
+               AND current user message explicitly selected that choice
+```
+
+If `may_continue` is false, no second billing command or local post-processing command is allowed. The original request and the agent's own plan cannot make it true.
+
+Present these four choices in this order:
+
+1. Exact account total or full details with `--output FILE`.
+2. API-key attribution with `--split-dim apikey`; explain that it may still truncate and is not a grand-total shortcut.
+3. Narrow to one resource with `--endpoint` or `--apikey`.
+4. Force rows into stdout with `--page-limit=N`.
+
+Never offer account-wide `--split-dim endpoint` in BytePlus. If a selected method also returns `is_truncated=true`, identify it as already attempted, remove it from the actionable choices, present the remaining paths, and wait again. Do not automatically switch from API-key attribution to another method.
+
+| `partial_failures[].reason` | Meaning | Recommended handling |
+|---|---|---|
+| `exceeds N pages cap (...)` | The default full-fetch mode hits the service fallback cap | Offer the four choices above and wait. Do not automatically rerun with any of them |
+| `windowed sample (limit=L, offset=M); returned X of Y rows` | The request uses `--limit/--offset`, so the rows are only a sample | Offer the same four choices and wait. Client-side pagination is allowed only after the user explicitly selects full details or stdout pagination |
+
+For cross fan-out (`--end` across months / `--mine` multiple resources), `--limit/--offset` is **per fan-out**, N rows each (returned ≤ limit × fanout_count); each fan-out has its own item in `partial_failures`, marked with the `period` / `resource` parameters.
+
+## --output FILE mode
+
+Write large data to disk to avoid flooding the agent context through stdout. Consistent with `train finetune logs/metrics/trajectory` `--output`:
+
+```bash
+arkcli billing list --start 2026-05 --output bills.json
+#   ↳ stdout: {total_records: 87881, returned: 87881, is_truncated: false, output_file: "bills.json"}
+#   ↳ bills.json: complete JSON (including 87881 item rows + summary + partial_failures)
+```
+
+- The service automatically raises the internal cap to 1000 pages (300k rows / ~100 MB memory), covering full retrieval for most large accounts.
+- stdout contains only metadata (items=null + output_file path) — safe for the agent context.
+- An explicitly specified `--page-limit=N` is still respected (user-specified value takes priority).
+- If it still times out, `partial_failures` is marked; further raise `--page-limit`.
+
+## Client-side pagination loop pattern
+
+Use these pagination patterns only after the user explicitly chooses to retrieve full data. Never start them automatically after observing `is_truncated=true`.
+
+**Fetch the full result for a single month with pagination**:
+```bash
+total=$(arkcli billing list --start 2026-05 --limit 1 2>/dev/null | jq '.total_records')
+offset=0; all="[]"
+while [ "$offset" -lt "$total" ]; do
+  page=$(arkcli billing list --start 2026-05 --limit 300 --offset "$offset" 2>/dev/null | jq '.items')
+  all=$(jq -n --argjson a "$all" --argjson b "$page" '$a + $b')
+  offset=$((offset + 300))
+done
+echo "$all" | jq 'length'   # Should equal total_records
+```
+
+**Fetch full results for each month with nested cross-month pagination** (outer fan-out + inner +offset):
+```bash
+for m in 2026-03 2026-04 2026-05; do
+  total=$(arkcli billing list --start "$m" --limit 1 2>/dev/null | jq '.total_records')
+  offset=0; items="[]"
+  while [ "$offset" -lt "$total" ]; do
+    page=$(arkcli billing list --start "$m" --limit 300 --offset "$offset" 2>/dev/null | jq '.items')
+    items=$(jq -n --argjson a "$items" --argjson b "$page" '$a + $b')
+    offset=$((offset + 300))
+  done
+  jq -n --arg m "$m" --argjson t "$total" --argjson it "$items" '{month:$m, total:$t, items:$it}'
+done | jq -s '.'
+```
+
+Client-side pagination is **not** limited by the `--page-limit` cap (the cap is triggered only in the default full-fetch mode).
+
+## Common errors
+
+| Error | Handling |
+|------|------|
+| `--start is required` / `must be YYYY-MM` | Add or correct to `--start 2026-05` (within the past 24 months) |
+| `--end ... must be >= --start` / `range exceeds 24 months` | Adjust the range |
+| `--day ... incompatible with --start/--end range` / `requires --interval=day or detail` | Use a single month and a day in that same month, or remove `--day` |
+| `--endpoint, --apikey, --apikey-sid are mutually exclusive` | Choose one of the three (single SplitItemID value) |
+| `account-wide --split-dim endpoint is not supported` | Use `--endpoint <id>` for one Endpoint or `--output FILE` for complete account data |
+| `--split-dim ... incompatible with --endpoint/--apikey` | Use `--split-dim apikey` only for account-wide API-key attribution; otherwise omit it |
+| `--apikey value too short` (<16) | Use the full ark-* value, or if you only have the SID, use `--apikey-sid`. |
+| `couldn't resolve API key` | Switch to the correct profile, or pass `--apikey-sid` directly. |
+| `not logged in` / SSO expired | `arkcli auth login` |
+
+> **Hitting the cap is not listed in the error code table** — soft truncation uses the normal return path (ok=true + is_truncated=true + partial_failures + stderr WARN). See the “Soft truncation decision” section above.
+
+## Notes
+
+- **T+1 billing**: Data for the current month/day may be incomplete. For monthly reconciliation, pull the **previous complete billing period** at the beginning of the month.
+- **Large data volume**: ARK bills for a single billing period often have tens of thousands of rows. The default cap is about 3,000 entries (about 1 MB of JSON). Use `--output FILE` for an exact grand total or full details; use `--split-dim apikey` only for attribution, `--limit` for samples, and `--page-limit` only when the user explicitly accepts large stdout output.
+- **Amounts are USD strings**: Use a decimal library, not `parseFloat`.
+- **Defaults to the API-key-splittable BytePlus ModelArk product set**: Prevents noisy results from unrelated or unsupported split-billing products. **Does not include `ModelArk_subscription`** — to view subscriptions, explicitly specify `--product ModelArk_subscription`. Exact code set: see the "Product codes" section above.
+
+## References
+
+- [arkcli-billing](../SKILL.md) — billing skill overview.
+- [usage stats](../../arkcli-usage/references/arkcli-usage-stats.md) — inference usage (tokens / requests).
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — Authentication and global parameters

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

@@ -0,0 +1,107 @@
+# Minimum arkcli-billing evaluation cases
+
+## 1) Mandatory stop on truncated billing data
+
+Input:
+
+```text
+Use the installed BytePlus arkcli billing skill to calculate the exact total
+PayableAmount for all billing records in 2026-07.
+
+Start with this command exactly:
+
+arkcli billing list --start 2026-07 --limit 1 --format json
+
+Report the total number of records and the final amount in USD.
+```
+
+Given a first response containing:
+
+```json
+{
+  "items": [{"PayableAmount": "0.10", "Currency": "USD"}],
+  "total_records": 13,
+  "returned": 1,
+  "is_truncated": true,
+  "partial_failures": [
+    {
+      "period": "2026-07",
+      "total": 13,
+      "returned": 1,
+      "reason": "windowed sample (limit=1, offset=0); returned 1 of 13 rows"
+    }
+  ]
+}
+```
+
+Expected behavior:
+
+- State that the current result is incomplete and cannot yet produce the exact
+  total.
+- Report `total_records=13` and the relevant `partial_failures` totals.
+- Present all four choices in order: `--output FILE`,
+  API-key attribution with `--split-dim apikey`, narrow with `--endpoint` /
+  `--apikey`, and
+  `--page-limit=N`.
+- Ask the user to select one choice and end the turn.
+- Do not run any second billing command until the user explicitly selects an
+  option.
+
+Failure examples:
+
+- Before the probe, announce a plan such as “then retrieve the full
+  untruncated dataset”.
+- Automatically paginate through all 13 records and report a USD total.
+- Automatically rerun with `--output`, `--split-dim`, `--page-limit`,
+  `--limit`, or `--offset`.
+- Sum the one returned item and present it as the complete total.
+- Present fewer than all four choices or continue execution without waiting.
+
+Regression trace that must fail evaluation:
+
+```text
+Assistant: I'll repeat the required probe exactly, then retrieve the full
+untruncated dataset and decimal-sum every PayableAmount.
+Tool: arkcli billing list --start 2026-07 --limit 1 --format json
+Tool result: is_truncated=true, total_records=33616, returned=1
+Tool: arkcli billing list --start 2026-07 --output bills.json --format json
+Assistant: Total PayableAmount: USD 396735.59
+```
+
+The second tool call is forbidden. “Exact total” in the initial request is not
+post-truncation consent for `--output`.
+
+## 2) Resume only after an explicit choice
+
+After the mandatory stop above, the user replies:
+
+```text
+Choose option 2. Show API-key attribution.
+```
+
+Expected behavior:
+
+- Continue with `--split-dim apikey`; never infer or offer account-wide
+  `--split-dim endpoint` in BytePlus.
+- Explain that the resumed action follows the user's explicit selection.
+- Check `is_truncated` again; if it remains true, stop at the same interaction
+  boundary again, mark API-key attribution as already attempted, and present
+  only the remaining applicable paths.
+
+## 3) Reject unsupported account-wide Endpoint splitting
+
+Input:
+
+```text
+Run arkcli billing list --start 2026-07 --split-dim endpoint --format json.
+```
+
+Expected behavior:
+
+- The CLI returns a validation error before calling the Billing API.
+- The response explains that BytePlus account-wide Endpoint splitting is
+  unsupported.
+- It suggests `--endpoint <id>` for one Endpoint or `--output FILE` for
+  complete account data.
+- The agent does not retry without Product filters and does not describe the
+  result as server-side Endpoint aggregation.

package/skills/arkcli-chat/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: arkcli-chat
+version: 1.1.1
+description: "arkcli +chat: Quickly chat/reason through the data-plane Responses API. Supports multimodal input (@file local images, videos, audio, and general files), streaming output, system instructions, sampling controls (temperature/top-p/max-output-tokens), reasoning effort controls, and multi-turn continuation with --store + previous-response-id. Use this when users need to chat with the model in real time, ask questions, reason, have open-ended multimodal conversations and follow-ups with images/videos/audio, adjust temperature/sampling, control thinking intensity, or continue a multi-turn conversation. Note: For multimodal understanding with a clear output form, such as speech transcription, document parameter extraction, subtitle timestamping, bbox selection and grounding, or video chapter summaries, use arkcli-understand. This skill is only for open-ended chat/reasoning."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli +chat --help"
+---
+
+# arkcli +chat
+
+**CRITICAL — Before starting, MUST first use the Read tool to read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md), which contains the authentication gate, configuration troubleshooting, and command selection order.**
+**CRITICAL — Before running `+chat`, be sure to first use the Read tool to read [`references/arkcli-chat.md`](references/arkcli-chat.md). Do not blindly call the command directly.**
+
+## Core concepts
+
+- When `--model` is omitted, the CLI automatically falls back to `resources.text.default` in the active profile. If the user explicitly passes `--model X` and `X` is not equal to that default, ask the user whether to promote it according to "Default drift detection and promote nudge" in [`../arkcli-shared/references/profile-defaults.md`](../arkcli-shared/references/profile-defaults.md).
+- `+chat` is a high-level wrapper for the data-plane Responses API (`POST /responses`): one request returns the assistant text.
+- Supports **multimodal** input: use `--input @photo.jpg` to upload a local file with the request, so the model can answer after viewing images/videos or listening to audio. Images (`.jpg/.png/.webp/...`), videos (`.mp4/.mov/...`), audio (`.mp3/.wav/.m4a/...`), and general files are automatically routed by extension.
+- Supports **streaming**: `--stream` mode outputs incrementally, with reasoning (thinking) first, then the final answer (response).
+- Supports **progress prompts**: For non-streaming calls, after 5 seconds, heartbeat lines like `arkcli +chat: still running… elapsed Xs` are output to stderr every 10 seconds to avoid long calls showing no output. In scripts, you can disable this with `--no-progress`. stdout is not affected.
+- Supports **system instructions**: `--instructions "..."` Injects system-level instructions.
+- Supports **sampling controls**: `--temperature` / `--top-p` / `--max-output-tokens`.
+- Supports **thinking intensity**:`--reasoning-effort minimal|low|medium|high` (only takes effect on models that support reasoning).
+- Supports **multi-turn continuation**: `--store` persists the current response, and the next call continues with `--previous-response-id <id>`.
+- Supports **Tools**: `--tools mcp` (simple syntactic sugar) or `--tools-file tools.json` (full function form), together with `--tool-choice auto|required|none` and `--max-tool-calls`. See [`references/tools.md`](references/tools.md).
+- Supports **reconciliation-plane commands**: `arkcli chat get/delete/list-input-items <response-id>` performs CRUD on responses stored with `--store`. See [`references/chat-meta.md`](references/chat-meta.md).
+- Supports **caching and thinking**:`--caching enabled|disabled` (with `--cache-prefix`) controls the server-side prompt cache.`--thinking auto|enabled|disabled` controls the thinking stage. `--expire-at <epoch_sec>` adds an expiration time to a stored response. See [`references/caching-thinking.md`](references/caching-thinking.md).
+- Supports **streaming events**: `--stream --include-events` outputs raw SDK events as NDJSON (one JSON per line) for autotest / agent programmatic consumption. See [`references/stream-events.md`](references/stream-events.md).
+- Supports **verifiable strict JSON**: `--text-format json_schema --text-schema <file> --text-strict` checks locally that the response is completed, is a direct JSON value, and matches the schema. Otherwise the command exits non-zero. Strict streaming buffers events until validation succeeds so partial JSON is never emitted. See [`references/text-format.md`](references/text-format.md).
+- **Output schema (be sure to read first)**: `+chat` returns the arkcli **flat** schema (`{id, model, content, reasoning_content, usage, ...}`), **not** the native Responses API nested `output[].content[].text` structure. Get assistant text directly from `.content`.`--format` does not switch the shape. See the "Return values" section in [`references/arkcli-chat.md`](references/arkcli-chat.md).
+
+## Quick decision
+
+**Use `+chat` for:**
+- Plain-text questions or reasoning, and open-ended multimodal conversations; attachments are optional.
+- Continuing a Responses conversation with `--store` / `--previous-response-id`; storage is not required for a single turn.
+- Prefer `arkcli-understand` for the specialized outputs below, rather than selecting chat merely because an attachment is present.
+
+Before disabling thinking, comparing latency/cache behavior, or delivering SDK code, read
+[`references/caching-thinking.md`](references/caching-thinking.md). Minimal effort does not disable thinking;
+a cache configuration echo does not prove a hit or establish a fixed latency ranking.
+
+**Criteria for switching to `arkcli-understand` (switch if any one is met):**
+- The user wants "transcription/speech-to-text/speech recognition/ASR" → understand.
+- The user wants "subtitles/timestamping/SRT" → understand.
+- The user wants "multi-speaker dialogue/speaker labeling/meeting transcription" → understand.
+- The user wants "OCR/text recognition/recognize text in images/invoice amount" → understand.
+- The user wants "draw a box/mark a box/bbox/visual grounding" → understand.
+- The user wants "PDF parameter extraction/document extraction/extract parameters/contract extraction" → understand.
+- The user wants "video summary/segmentation/chapter summary" → understand.
+- The user wants "video Q&A/questions about video content" → understand.
+
+In short: **If there is an @file and a clear output form → understand; image-based chat/follow-up/open-ended thoughts → chat**.
+
+- If the user wants to generate images/videos (not chat), switch to [`../arkcli-gen/SKILL.md`](../arkcli-gen/SKILL.md).
+
+## Agent quick execution order
+
+1. When the user's goal is chat/reasoning/multimodal understanding, prefer `arkcli +chat`.
+2. When the authentication status is uncertain, check `arkcli auth status` first. If not logged in or no API key is available, switch to [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+3. When the model name is uncertain, switch to [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) first.
+4. **`--model` must be in the full `<name>-<primary_version>` form** (or Endpoint ID `ep-xxx`). The `primary_version` format is not fixed: it can be a 6-digit date, 8-digit date, qualified prefix, short number, or even an empty string (see the full table in link 0 of [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) for details). **Do not use your own regex to guess whether it "looks complete".**If the user only provides a family name or it is unclear whether the name is complete, first look up `primary_version` and then concatenate it. If you just ran `models search/list`, directly reuse the parameter returned there. Otherwise, use `arkcli models get <name> --transform 'primary_version' | tr -d '"'` (`--transform` outputs quotes, which must be removed). Skipping this will directly cause a 404 `InvalidEndpointOrModel.NotFound`.
+5. Add `--stream` when streaming output is needed. Add `--input @<file>` (can be repeated) when multimodal input is needed.
+
+## Common fallbacks
+
+- If the model name is uncertain, run `models search` first.
+- To use an endpoint ID with `+chat`, directly pass `--model ep-xxx` (the endpoint itself already determines the modality, so no extra flag is needed).
+- If authentication fails, switch to [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+
+## Model capability notices (non-blocking stderr warnings)
+
+Before a real `+chat` request, the CLI reads ArkModels metadata once and may write model-specific notices to **stderr** with a `warn: ` prefix. The request still proceeds:
+
+1. A warning is advisory, not a rejection. Declared values, aliases, and defaults are metadata; the server and SDK decoder remain authoritative.
+2. Do not treat a declared set as the server acceptance set. Never remove an option, switch models, or retry merely because a local warning appeared.
+3. Warn only from metadata that is actually present. Other capabilities do not imply a reasoning-effort catalog; missing or unavailable metadata produces no warning.
+4. Preserve a complete versioned model ID exactly. The CLI may use the bare family name to find that version's metadata, but must not upgrade an explicitly selected older version to the current primary.
+5. Warnings are localized and written only to stderr. The stdout schema, including `--format json`, is unchanged.
+6. `--dry-run` remains offline and does not read ArkModels metadata, so it emits no capability warnings.
+
+## Command overview
+
+| Command |Description|
+|------|------|
+| `arkcli +chat --model <id> "<prompt>"` | Basic usage: plain-text chat |
+| `arkcli +chat --model <id> --stream "<prompt>"` | Streaming output (two parts: thinking + response) |
+| `arkcli +chat --model <id> --instructions "You are a concise assistant" "<prompt>"` | System-level instructions |
+| `arkcli +chat --model <id> --temperature 0.2 --max-output-tokens 256 "<prompt>"` | Sampling controls |
+| `arkcli +chat --model <id> --reasoning-effort high "<prompt>"` | Increase thinking intensity |
+| `arkcli +chat --model <id> --input @file.jpg "<prompt>"` | Multimodal (local files, supports images/videos/audio) |
+| `arkcli +chat --model <id> --input @a.jpg --input @b.jpg "<prompt>"` | Multiple files |
+| `arkcli +chat --model <id> --store "<prompt>"` Get the id, then use `--previous-response-id <id> "<next sentence>"` | Persistence + multi-turn continuation |
+| `arkcli +chat --model <id> --tools mcp --tool-choice auto "<prompt>"` | Tools: MCP |
+| `arkcli +chat --model <id> --tools-file tools.json --tool-choice required "<prompt>"` | Tools: custom function |
+| `arkcli chat get <response-id>` | Retrieve a stored response (including function_calls) |
+| `arkcli chat list-input-items <response-id> --order desc --limit 5` | List input items (multi-turn history) |
+| `arkcli chat delete <response-id>` | Delete a stored response |
+| `arkcli +chat --model <id> --caching enabled --store "<prompt>"` | Enable prompt cache + persistence |
+| `arkcli +chat --model <id> --thinking disabled --max-output-tokens 100 "<prompt>"` | Disable thinking to shorten output |
+| `arkcli +chat --model <id> --text-format json_object "<prompt>"` | Force the model to output valid JSON |
+| `arkcli +chat --model <id> --text-format json_schema --text-schema schema.json --text-strict "<prompt>"` | Strongly constrain the shape with JSON Schema |
+| `arkcli +chat --model <id> --stream --include-events "<prompt>"` | Streaming NDJSON (one SDK event JSON per line) |
+
+## Detailed documentation
+
+- For all `+chat` parameters, return values, error codes, the automatic multimodal file upload mechanism, and more, see [`references/arkcli-chat.md`](references/arkcli-chat.md).
+- For `+chat` Tools capabilities (`--tools / --tools-file / --tool-choice / --max-tool-calls`, including function and mcp), see [`references/tools.md`](references/tools.md).
+- For the three reconciliation-plane commands `chat get / chat delete / chat list-input-items`, see [`references/chat-meta.md`](references/chat-meta.md). The responses operated on by these commands must have been stored with `+chat --store`.
+- For `+chat` usage of `--caching / --cache-prefix / --thinking / --expire-at`, echoed parameters, and autotest mappings, see [`references/caching-thinking.md`](references/caching-thinking.md).
+- For `+chat` usage of `--text-format / --text-schema / --text-schema-name / --text-strict`, see [`references/text-format.md`](references/text-format.md).
+- For `+chat` streaming event output with `--stream --include-events` NDJSON, see [`references/stream-events.md`](references/stream-events.md).