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

package/skills/arkcli-models/references/arkcli-models-scenario-table.md

@@ -0,0 +1,75 @@
+# Models scenario recommendation table (curation layer / highest priority for intent ranking)
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+> **Snapshot alignment:** 2026-06. The "Version" column is a **curated snapshot**, not the source of truth. **Always use the complete model ID returned in real time by `arkcli models search`**. See the JOIN protocol below.
+
+## What this table solves
+
+Model search is not a recall problem; it is a ranking problem. The local cache contains **all models**, so every query has 100% recall. The difficult part is **accurate ranking**. Naming heuristics (generation / tier / update_time) can only guess capabilities from model names; they cannot determine whether "this model is suitable for translation or Agent tasks". What is missing is a **labeling system**.
+
+This table is that labeling system: a manually curated `scenario label → recommended model` mapping that fixes the "intent → model" step. It is the **highest-priority signal for intent ranking**, above naming heuristics, but recommendations must be verified against the left table (local cache) before adoption.
+
+## Usage rules
+
+- The Agent recalls recommended models based on "scenario label + recommended model description".
+- Recommended model descriptions include version differences, common requirement terms, legacy model aliases, and upgrade guidance to improve retrieval.
+- When the user explicitly specifies a third-party, open-source, or historical model, return to `arkcli models search` and **do not forcibly replace it**.
+- This table serves only "find a model by intent" (the search path). **Enumeration / inventory / statistics use `arkcli models list` without this table's reranking.**
+
+## Model recommendation table
+
+| Scenario label | Default recommended model | Version | Recommended model description |
+| --- | --- | --- | --- |
+| Text generation | Dola-Seed-2.1-turbo | dola-seed-2-1-turbo-260628 | General-purpose production model that balances quality, response speed, and cost. Suitable for everyday Q&A, content creation, copywriting, summarization, office assistance, and general text processing. Prefer it when the user has no special requirements or asks only for a general-purpose, default, or everyday model. |
+| Text translation | Dola-Seed-2.0-lite | seed-2-0-lite-260428 | Suitable for multilingual translation of articles, product copy, technical materials, and everyday content, as well as polishing, rewriting, and cross-language content conversion. Recommend it when the user asks for a translation model, English polishing, or multilingual processing. |
+| Information extraction | Dola-Seed-2.0-mini | seed-2-0-mini-260428 | Optimized for high throughput and lightweight calls. Suitable for field extraction, classification and summarization, label generation, format conversion, and batch structured processing. Prefer it when the user emphasizes high call volume, well-defined tasks, batch processing, or cost sensitivity. |
+| Long-text understanding | Dola-Seed-2.0-lite | seed-2-0-lite-260428 | Suitable for analyzing long articles, reports, web content, and multi-turn context to perform summarization, Q&A, synthesis, and key-information extraction. Recommend it for long-form reading, long context, or report summarization. |
+| Document understanding | Dola-Seed-2.0-lite | seed-2-0-lite-260428 | Suitable for reading documents, analyzing materials, summarizing reports, and answering questions based on file contents. Applicable to office work, research, and knowledge organization. Recommend it for PDF, file parsing, or document Q&A. |
+| Complex reasoning | Dola-Seed-2.0-pro | seed-2-0-pro-260328 | Optimized for complex workflows and long-chain reasoning. Suitable for multi-step analysis, complex instructions, multi-constraint tasks, solution comparison, mathematical logic, and research assistance. Prefer it when the user prioritizes quality, high complexity, or strong reasoning. |
+| Agent tasks | Dola-Seed-2.0-pro | seed-2-0-pro-260328 | Suitable for agents, automated tasks, and complex workflows; handles task decomposition, multi-turn planning, continuous decision-making, and long-chain execution. Prefer it for Agents, intelligent agents, complex task orchestration, or automated execution. |
+| Tool calling | Dola-Seed-2.0-pro | seed-2-0-pro-260328 | Suitable for information queries, business operations, process automation, and complex tool orchestration through Function Calling, MCP, or external APIs. Recommend it when the user explicitly requires tools, MCP, function calling, or API orchestration. |
+| Low-cost calls | Dola-Seed-2.0-mini | seed-2-0-mini-260428 | Optimized for inference throughput and deployment density. Suitable for budget-sensitive lightweight tasks such as classification, extraction, rewriting, format conversion, label generation, and batch content processing. Recommend it when the user asks for inexpensive, cost-saving, or low-cost options. |
+| High-concurrency calls | Dola-Seed-2.0-mini | seed-2-0-mini-260428 | Optimized for high concurrency and batch generation. Suitable for quick responses, real-time classification, short-text processing, large-scale offline tasks, and high-frequency calls. Recommend it for high throughput, short waits, or batch processing. |
+| Code generation | Dola-Seed-2.0-Code | seed-2-0-code-preview-260328 | Optimized for enterprise programming tasks. Suitable for code generation, completion, explanation, debugging, bug fixes, frontend development, multi-file changes, and project-level development. Prefer it for coding tasks, development agents, or repository-level changes. |
+| Vision understanding | Dola-Seed-2.0-lite | seed-2-0-lite-260428 | Seed2.0 Lite natively supports unified understanding of text, images, audio, and video. Suitable for image Q&A, screenshot analysis, chart interpretation, visual information extraction, and mixed image-text input. Prefer it when the user asks to view or recognize images, analyze charts, or use a general multimodal model. |
+| Complex visual reasoning | Dola-Seed-2.0-lite | seed-2-0-lite-260428 | Seed2.0 Lite supports cross-modal reasoning and can combine image, video, audio, and text information for complex analysis. Suitable for multi-image understanding, complex charts, visual logic reasoning, image-text integration, and cross-modal Q&A. |
+| Video understanding | Dola-Seed-2.0-lite | seed-2-0-lite-260428 | Seed2.0 Lite enhances temporal video understanding and motion perception and can combine video frames, speech, and ambient sound for end-to-end audiovisual understanding. Suitable for video summarization, key-event analysis, action understanding, video Q&A, and extracting audio information from videos. |
+| Audio understanding | Dola-Seed-2.0-lite | seed-2-0-lite-260428 | Seed2.0 Lite supports native audio input and understanding. It can analyze recordings, podcasts, meetings, and interviews for summarization, information extraction, and Q&A. Suitable for tasks that must combine speech, ambient sound, and context. |
+| GUI Agent | Dola-Seed-2.0-lite | seed-2-0-lite-260428 | Seed2.0 Lite has upgraded GUI capabilities and is suitable for visual understanding, element recognition, visual localization, click execution, and workflow automation on web, desktop, and app interfaces. When the user mentions GUI Agent, UI-TARS, ui tars, Browser Use, Computer Use, or page automation, route to Seed2.0 Lite by default; query older models only when compatibility with a legacy integration is required. |
+| Image generation | Dola-Seedream-5.0-pro | dola-seedream-5-0-pro-260628 | Next-generation image generation model supporting deep thinking and web search, with enhanced knowledge reasoning, instruction understanding, generation quality, editing responsiveness, and consistency. Suitable for posters, e-commerce materials, brand visuals, illustrations, concept art, and professional creative content. When the user asks about Seedream 4.0, Seedream 4.5, or an older image model without requiring legacy compatibility, prefer Seedream 5.0. |
+| Knowledge-based image generation | Dola-Seedream-5.0-pro | dola-seedream-5-0-pro-260628 | Supports deep thinking and web search, making it suitable for generation that combines knowledge, real-time content, and complex instructions. Applicable to infographics, knowledge posters, professional design assets, current-affairs visualization, and image creation requiring factual understanding. |
+| Image editing | Dola-Seedream-5.0-pro | dola-seedream-5-0-pro-260628 | Further improves editing responsiveness and consistency compared with Seedream 4.5. Suitable for local modifications, adding/removing elements, reference-image editing, style adjustments, image optimization, and subject consistency. When the user mentions Seedream 4.5, Seededit, or older image editing, route to Seedream 5.0 by default. |
+| Multiple image references | Dola-Seedream-5.0-pro | dola-seedream-5-0-pro-260628 | Suitable for generation and editing with multiple reference images, including person consistency, product consistency, multi-image fusion, series assets, and reference-image transformations. Recommend it for multi-image editing, subject preservation, or series image generation. |
+| Text rendering in images | Dola-Seedream-5.0-pro | dola-seedream-5-0-pro-260628 | Suitable for generating text in images, producing visual assets with copy, and creating knowledge-based images. Applicable to posters, covers, marketing images, infographics, and layout design. When the user mentions Seedream 4.5 text-rendering capabilities, prefer the newer Seedream 5.0. |
+| Video generation | Dreamina-Seedance-2.0 | dreamina-seedance-2-0-260128 | Next-generation joint audio-video generation model supporting mixed text, image, audio, and video input and references for frames, actions, camera movements, visual effects, and sound. Suitable for ads, short films, creative videos, complex actions, video editing, and video extension. When the user mentions Seedance 1.5, SD1.5, Seedance 1.0, or an older video model, route to Seedance 2.0 by default and explain that it is a comprehensive upgrade. |
+| Fast video generation | Dreamina-Seedance-2.0-fast | dreamina-seedance-2-0-fast-260128 | Fast version of Seedance 2.0, suitable for quickly generating video previews, batch-producing short videos, and high-frequency iteration. Recommend it when the user emphasizes fast output, reduced waiting, batch generation, or previewing results first. |
+| Audiovisual video generation | Dreamina-Seedance-2.0 | dreamina-seedance-2-0-260128 | Uses a unified multimodal joint audio-video generation architecture and supports text, image, audio, and video input. Suitable for video creation with coordinated native soundtracks, dialogue, ambient sound, action, and camera work. Applicable to short dramas, ads, music videos, lip sync, and multimodal reference generation. |
+| 3D generation | Hyper3D-Gen2 | hyper3d-gen2-260112 | Generates high-precision 3D assets from text/images. |
+| Multimodal embeddings | skylark-embedding-vision-250615 | skylark-embedding-vision-251215 | Suitable for converting text, images, and videos into vector representations for semantic retrieval, similar-content recall, cross-modal search, recommendation systems, and multimodal knowledge indexing. Recommend it for embeddings, vector models, image search, or video retrieval. |
+
+## JOIN / verification protocol (scenario table ⨝ full local cache)
+
+**Core principle: the scenario table supplies intent, while `arkcli models search` supplies facts. Versions/full IDs in the table are only starting points; use the real-time search response for matches.**
+
+**Layer boundary (do not mix layers): this table is the "model marketplace selection layer". Its data source is always `models search` (catalog), and it provides catalog-recommended model names.** "Whether the current profile can call it and the exact callable ID" belongs to the downstream availability layer (`resources list` → `models get` → `+gen`/`+chat`; arkcli-gen is implemented) and is **outside this table's responsibility**. Pure selection questions ("find/choose a model") use only `models search`; do not query `resources list`. Descend to resources list to resolve the current profile's actual ID only when the user truly wants to generate/invoke. Example: image-generation selection returns `dola-seedream-5-0` (catalog name); a plan profile may actually invoke `dola-seedream-5-0-pro`, which downstream `+gen` resolves.
+
+```
+① User intent → match scenario label               (use requirement terms in "Recommended model description" to improve matching)
+② Take the row's "Default recommended model" and derive the family stem (for example, Dola-Seed-2.0-lite → seed-2-0-lite)
+③ arkcli models search <family stem>               ← verify facts against the left table (required; cannot be skipped)
+   ├─ exact   family matches and version is consistent → concatenate <name>-<primary_version> and rank it first
+   ├─ drift   family matches but version differs       → use the actual version returned by search (already sorted by gen/time; take the top)
+   │                                                    and say "recommendation snapshot X, current Y"
+   ├─ bare    match with primary_version=None (voice/audio) → stop at marketplace discovery: only state that it is discoverable; do not concatenate a version or pass it downstream
+   └─ miss    no match for the family stem             → table ID may be stale; search again using a scenario term or shorter stem
+④ Add 2–3 alternative candidates from search results with the same modality
+⑤ User names a third-party/open-source/historical model (Seedream 4.5, glm…) → skip this table, search directly, and do not forcibly replace it
+```
+
+### Key boundaries (derived from actual testing; must read)
+
+- **Do not pass the table's full ID directly to `+chat` / `+gen`, and do not add suffixes to model names from memory**. The actual image-generation model is `dola-seedream-5-0` (**without the `-lite` suffix; no variant with `-lite` exists in the cache, and an exact query returns no items**). Such naming drift recurs. **Search by family stem, always trust the returned result, and do not append suffixes such as `-lite` / `-pro` yourself.**
+- **Search tolerates DisplayName**: `Dola-Seed-2.0-lite` (dots and case included) also matches `seed-2-0-lite`, but the **family stem (lowercase with hyphens) is the most reliable** and should be the preferred search keyword.
+- **The six voice/audio entries follow the bare path and currently support only marketplace discovery in arkcli**: they appear in the models catalog but have `primary_version=None` and no enrichment (ctx/lifecycle are empty). After a match, state directly that the bare name is discoverable in the marketplace, but do not try to concatenate a version number and do not pass it to `+chat` / `+gen` / `+deploy` / `usage` / `pricing` / `onboard`. For arkcli, marketplace discovery does not mean callable, Endpoint-creatable, price-queryable, or usage-queryable.
+- **Avoid `-internal` variants**: search may return internal variants such as `seed-2-0-lite-internal`; do not recommend them to users.
+- **Lifecycle**: when a candidate is `Retiring`, proactively tell the user it is being retired and find a newer version in the same family (consistent with the main SKILL).

package/skills/arkcli-models/references/arkcli-models-search.md

@@ -0,0 +1,170 @@
+# models search
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+**Agent-first** model search: recall = full catalog; enrichment = ArkModels (context window / modalities / capabilities); filtering = structured conditions; ranking = four buckets + context_window weighting + recency. There is **no concept of pagination**, and all matches are returned by default.
+
+## Commands
+
+```bash
+# Basic
+arkcli models search                       # All entries sorted by UpdateTime descending
+arkcli models search doubao                # Keyword (or use --keyword doubao)
+arkcli models search doubao --size 5       # Explicitly truncate to five entries
+
+# Modality filtering (required for D3)
+arkcli models search --modality video      # Video generation models
+arkcli models search --modality text       # Text output models
+arkcli models search --modality image      # Image generation models
+arkcli models search --input-modality text,image --output-modality text  # VQA category
+arkcli models search --multimodal          # Models whose input supports multiple modalities
+
+# Numeric capacity filtering
+arkcli models search --min-context-window 200000
+arkcli models search --max-context-window 1000000
+arkcli models search --min-input-tokens 100000
+arkcli models search --min-output-tokens 8192
+
+# Capability filtering (repeatable, AND relationship)
+arkcli models search --capability thinking
+arkcli models search --capability mcp --capability functioncall
+
+# Composite query: find the strongest thinking LLM with 200K+ context
+arkcli models search --modality text --min-context-window 200000 --capability thinking --strict-filter
+
+# Cache control
+arkcli models search --refresh-cache       # Force one synchronous refresh of ArkModels metadata
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|------|------|------|
+| `[keyword]` / `--keyword` | string | Keyword. Matches any name / display_name / short_name / description / introduction field (case-insensitive) |
+| `--size` | int | **Omitted = no truncation** (the Agent receives all entries by default); explicitly pass N to truncate to N |
+| `--modality` | string | Coarse-grained alias: `text` / `image` / `video` / `audio` (output modality shorthand) |
+| `--input-modality` | string | Explicit input-modality filter, comma-separated (such as `text,image,video`) |
+| `--output-modality` | string | Explicit output-modality filter |
+| `--multimodal` | bool | Return only models with at least two input modalities |
+| `--min-context-window` | int | Minimum context_window (tokens) |
+| `--max-context-window` | int | Maximum context_window |
+| `--min-input-tokens` | int | Minimum max_input_tokens |
+| `--min-output-tokens` | int | Minimum max_completion_tokens |
+| `--capability` | string (repeatable) | Required capabilities; multiple values use AND: `thinking` / `mcp` / `functioncall` / `web_browsing` / `knowledge_base` / `caching` / `response_format` / `reasoning_effort` |
+| `--strict-filter` | bool | Directly exclude models without enrichment data (retained by default to avoid false negatives) |
+| `--include-deprecated` | bool | Include models with `lifecycle_status=Shutdown` or `display_name` containing "deprecated/offline" (**filtered by default**, retaining only callable models) |
+| `--refresh-cache` | bool | Synchronously refresh the ArkModels metadata cache (stale-while-revalidate asynchronous refresh by default) |
+
+## Workflow
+
+```
+search [keyword] [filters]
+   │
+   1️⃣  ListFoundationModels(all, sort=UpdateTime DESC)
+   │   ↓ 152 candidates
+   2️⃣  EnrichWithMetadata
+   │   ├─ read cache: ~/.arkcli-bp/cache/<profile>/<region>/<project>/arkmodels-meta.json
+   │   ├─ hit  → return immediately + fork detached subprocess for asynchronous refresh
+   │   └─ miss → synchronously call ArkModels(IsPrimaryVersionOnly:true) → write cache
+   │       (without SSO, enrichment is silently skipped and filtering automatically becomes a no-op)
+   │   ↓ add context_window / input_modalities / output_modalities / capabilities to each item
+   3️⃣  Modality fallback: derive from task_types when output_modalities is empty
+   │   (TextToVideo → out=[video], VisualQA → in=[text,image] out=[text], ...)
+   4️⃣  Keyword filtering (case-insensitive substring across name+display+short+description+intro)
+   5️⃣  Structured filtering (modality / context / tokens / capability, AND)
+   6️⃣  Four-bucket reranking + (context_window desc, update_time desc, name asc) tie-break
+   7️⃣  --size N truncation (no truncation by default)
+```
+
+## Return fields
+
+Each item:
+
+```json
+{
+  "name": "seed-2-0-pro",
+  "display_name": "Dola-Seed-2.0-pro",
+  "primary_version": "260328",
+  "update_time": "2026-03-28T...",
+  "foundation_model_tag": { "filter_task_types": [...], "task_types": [...] },
+
+  // —— enrichment (from ArkModels; null when SSO fails) ——
+  "context_window": 262144,
+  "max_input_tokens": 229376,
+  "max_completion_tokens": 65536,
+  "input_modalities": ["text", "image", "video"],
+  "output_modalities": ["text"],
+  "capabilities": {
+    "thinking": true, "mcp": true, "functioncall": true,
+    "web_browsing": true, "knowledge_base": true, "caching": true,
+    "response_format": false, "reasoning_effort": true
+  }
+}
+```
+
+## Important behavior
+
+### Handling missing data (StrictFilter)
+
+- **Default `--strict-filter=false`**: with `--modality video`, models **without** modality data are also **retained** (the Agent sees candidates with low confidence).
+- **`--strict-filter`**: missing data is treated as not satisfying the condition and is excluded directly (100% of the Agent's results are ground truth).
+
+Modality queries are normally more accurate with `--strict-filter`; numeric queries (context window) are usually more reasonable with the default behavior (do not eliminate missing data).
+
+### Recall no longer has a top-K limit
+
+Unlike the old fuzzy API's default of nine entries, this command returns **all matches** by default. To limit results, pass `--size N`.
+
+### Cache and SSO
+
+- ArkModels is a Console BFF API and requires SSO credentials.
+- Without SSO (AK/SK only) → enrichment is silently skipped, models are still returned, and filtering automatically becomes a no-op.
+- Cache paths are separated by `(identity/account, profile, region, project)`. Persistent caching is disabled when no authoritative identity is available, preventing cross-account reuse.
+- The default TTL is 5 minutes and can be adjusted with `ARKCLI_MODEL_CACHE_TTL`. Reads within the TTL use local cache only.
+- After TTL expiry, stale-while-revalidate serves the current snapshot and starts a detached refresh (`arkcli models _refresh-cache`). Cold fills and refreshes are single-flighted across local processes for the same scope.
+- `auth logout` and a fresh account switch remove all model caches for the current product.
+- Every ArkModels Action passes through an account-scoped transport limiter with a 250ms minimum interval (about 4 QPS, leaving headroom below the backend's 5 QPS limit).
+
+### Keyword matching scope
+
+- name / display_name / short_name (match → reranking bucket 1)
+- description / display_description / introduction (match → bucket 2)
+- Substring matching, **case-insensitive**
+- **No semantic/synonym expansion**
+
+### Reranking details
+
+| Bucket | Condition |
+|---|------|
+| 1 | Non-hidden + name matches keyword |
+| 2 | Non-hidden + description matches keyword |
+| 3 | Non-hidden + no keyword match (fallback) |
+| 4 | Hidden (`customized_tags` contains `experience hiding`/`inference hiding`/`Square Hide`; these are legacy hidden-page tags from BytePlus ModelArk and are unrelated to this CLI command) |
+
+Within a bucket: larger `context_window` first → newer `update_time` first → `name` lexicographically.
+
+## Common errors
+
+| Error | Cause | Handling |
+|------|------|------|
+| `--modality video` returns substantial noise | strict-filter=false by default, so models with missing data were not excluded | Add `--strict-filter` |
+| Unexpected results after numeric filtering | Some ArkModels entries lack context_window | Accept the default retention (items with ctx=null may be inaccurate) |
+| No thinking models | --capability is non-strict by default and results may be overwhelmed by noise | Add `--strict-filter` |
+| All enrichment fields are null | Not logged in through SSO | Run `arkcli auth login` to re-establish BytePlus identity |
+| Recall is clearly lower than expected | Cache is old, or ArkModels may be temporarily unavailable | Add `--refresh-cache` to force a synchronous refresh |
+
+## Division of responsibility with `models list` / `models get`
+
+| Use case | Recommendation |
+|------|------|
+| User provides a fuzzy keyword and wants candidates | **`search`** ✓ |
+| Find the most recently released models (time-sensitive) | **`search`** (results sorted by update_time DESC) |
+| Find by modality / context / capability | **`search`** + corresponding flag |
+| Fully enumerate all models | `search` without a keyword (all 152 entries) |
+| Exact match by name | `list --name foo` (exact) or `search foo` (includes fuzzy matching) |
+| Get complete details for one model (pricing, rate limits, detailed capability descriptions) | `get <name>` |
+
+## References
+
+- [arkcli-models](../SKILL.md) — All models commands
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — Authentication and global parameters

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

@@ -0,0 +1,57 @@
+# arkcli-models evals
+
+## Coverage goals
+
+- Model search requests should use `arkcli models search`; avoid using `list` for capability recommendations.
+- Model asset inventory requests should use `arkcli models list --page-all`; avoid jumping to Raw API Explorer.
+- "Custom models from the past N days" should be filtered in local JSON by `create_time` and custom-model fields, without asking the user to use the console.
+
+## Trigger / should trigger
+
+- Trigger `arkcli-models` when the user explicitly asks for a model list, model details, model search, or model statistics.
+- Trigger the `models list` path when the user asks for asset inventory such as "mine/custom/recently created".
+
+## Anti-trigger / should not trigger
+
+- When the user wants to chat, generate, or deploy directly, do not treat `arkcli-models` as the destination. Enter it briefly only when the model name is missing.
+- When the user explicitly wants a Raw API Action, OpenAPI list, or low-level params, do not use this skill; route to `arkcli-api-explorer`.
+
+## Guard
+
+- When authentication fails, a 401 occurs, or login state is unknown, first check `arkcli auth status`.
+- When profile, region, or base URL is abnormal, route to `arkcli-config` for configuration troubleshooting.
+- A missing server-side time-filter flag is not a failure condition. First filter local JSON and explain the limitation only after confirming the request cannot be completed.
+
+## Tested happy-path CLI commands
+
+```bash
+arkcli models list --page-all --sort-by CreateTime --sort-order Desc --format json
+arkcli models search --modality text --min-context-window 200000 --capability thinking --strict-filter
+```
+
+## Regression cases
+
+| case | prompt | Expected |
+|------|--------|------|
+| `uat-models-list-recent-custom-001` | How many custom models did I create in BytePlus in the past seven days? List them. | Use `arkcli models list --page-all --format json`, and locally filter `create_time` and Custom fields; forbid `arkcli api --list` and do not suggest using the console |
+| `models-list-owned-custom` | Help me see which custom models I have, and output the count and model names. | Use `arkcli models list` for asset enumeration, then perform client-side filtering and statistics |
+| `models-search-task-fit` | Help me find a text model that supports thinking and has more than 200K context for +chat. | Use `arkcli models search --min-context-window ... --capability thinking` |
+| `models-search-speech-boundary` | Does the BytePlus ModelArk marketplace have TTS models? Can I deploy one directly? | Use `arkcli models search <tts/voice keyword>` for marketplace discovery; clearly state that voice models currently do not support `+deploy` / usage / pricing / onboard; do not recommend `+chat` or `+gen` |
+
+## Model detail pricing migration cases
+
+| case | prompt | Expected |
+|------|--------|----------|
+| `models-get-dimensional-price` | What is the input price for regular inference on this known model? Are there context tiers? | Read the get reference and use `pricing.prices`; explain service, label, dimensions, and units; never read old charge_items or select the first row |
+| `models-get-missing-price` | Does a null price or empty array mean free? | Distinguish null, empty arrays, and zero; never infer free, inactive, or nonexistent status or fall back to old prices |
+| `models-get-entitlements` | Show the price, activation state, and remaining free quota. | Read new prices from `pricing.prices`, state and quota from existing `pricing.state` / `pricing.inference_free_usage`; do not infer one from the other |
+| `models-get-price-scope` | Is this a price for the specified version and region? | Explain foundation-model-name and global query scope; do not infer version-specific or region-specific rates |
+
+## Key scoring points
+
+- Must route to `arkcli-models`.
+- Asset inventory must recommend `arkcli models list`, preferably with `--page-all` and `--format json`.
+- Time filtering must explain client-side filtering or local JSON processing.
+- Must not recommend `arkcli api --list` as the preferred path.
+- Must not claim that the CLI lacks the capability or send the user to the console merely because a server-side time flag is missing.
+- After a voice-model match, must stop at the marketplace discovery layer and must not continue recommending deployment, usage, or pricing queries.

package/skills/arkcli-onboard/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: arkcli-onboard
+version: 0.2.0
+description: "Guide a user through production integration of a BytePlus Ark model: authenticate, verify the account gate, select a deployable model, and reuse a matching running inference Endpoint or create one safely. Trigger for intent-level requests such as integrating a model into an application or service when the user has not already asked for a specific deployment command."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli --help"
+---
+
+# BytePlus Ark production onboarding
+
+<!-- Future BytePlus code-example support:
+Restore optional code-example generation after Endpoint creation and include
+the generated example location in the completion contract.
+-->
+
+Before using this Skill, read
+[`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md). This is an
+orchestration Skill: it owns the order and branching between capabilities, not
+the private flags or response schemas of each delegated command.
+
+## When To Trigger
+
+- "Integrate a BytePlus Ark model into my application."
+- "Help my backend call this model in production."
+- "I selected a model; help me obtain a reusable Endpoint"
+- Similar intent-level production-integration requests that do not already
+  specify an exact deployment command.
+
+## When NOT To Trigger
+
+- The user explicitly asks to deploy or create an Endpoint: route directly to
+  [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md).
+- The user only wants a one-off trial, answer, image, or video: route to
+  [`../arkcli-chat/SKILL.md`](../arkcli-chat/SKILL.md) or
+  [`../arkcli-gen/SKILL.md`](../arkcli-gen/SKILL.md).
+- The owning model Skill classifies the target as discoverable but not
+  deployable: stop after model discovery and explain the Ark CLI capability
+  boundary.
+
+## Execution modes
+
+### Normal workflow
+
+Use remote read operations as needed, then ask for confirmation at the single
+write boundary.
+
+### Help-only or no-remote workflow
+
+- If the user supplies a model and explicitly forbids remote queries, do not
+  run model search or Endpoint listing.
+- To validate command selection without remote calls, use help only:
+
+  ```bash
+  arkcli models --help
+  arkcli infer endpoint list --mine --help
+  arkcli +deploy --help
+  ```
+
+- Help-only validation must not log in, activate a model, create an Endpoint,
+  or query account resources.
+
+## Agent execution order
+
+Use these steps in order:
+
+1. Authenticate and apply the BytePlus account gate.
+2. Select and confirm a deployable model.
+3. Reuse an exact matching available Endpoint when one exists.
+4. Otherwise, delegate guarded Endpoint creation to `arkcli-deploy`.
+<!-- 5. Optionally generate code examples when BytePlus supports them. -->
+5. Return the integration result.
+
+```text
+Step 0  Authenticate and apply the BytePlus account gate
+          |
+          +--> arkcli auth status --format json
+          |      |
+          |      +--> session missing or expired: arkcli auth login, then resume
+          |      +--> byteplus_sso.identity.verified == false:
+          |      |      stop at https://console.byteplus.com/user/basics/
+          |      +--> verified == true: continue
+          |      +--> verified missing: continue without claiming a result
+          |
+Step 1  Select and confirm a deployable model
+          |
+          +--> delegate search/get to arkcli-models
+          +--> no model supplied: present candidates and ask the user to choose
+          +--> discoverable-only or unsupported target: stop
+          |
+Step 2  Look for a reusable inference Endpoint
+          |
+          +--> arkcli infer endpoint list --mine --page-all
+          +--> match the exact model/version and an available status
+                 |
+                 +--> one match: reuse it
+                 +--> multiple matches: ask the user which Endpoint to use
+                 +--> no match: continue to Step 3
+          |
+Step 3  Create an Endpoint
+          |
+          +--> delegate to arkcli-deploy
+          +--> use read-only checks, state that +deploy has no --dry-run, then obtain explicit confirmation
+          +--> this is the only write in the onboarding workflow
+          |
+Step 4  Return the production integration result
+                 endpoint ID + model ID + reused/created status
+```
+
+## Endpoint reuse rules
+
+Reuse an Endpoint only when all of these are true:
+
+- it belongs to the current SSO sub-user result set from `--mine`;
+- it is bound to the exact target model and version;
+- its status is available for inference, such as `Running`.
+
+An Endpoint for another model is not a match. Do not silently choose among
+multiple matches. Listing all pages is required so a reusable Endpoint is not
+missed because of pagination.
+
+## Write and verification guards
+
+- This production workflow can lead to a billable write, so Step 0 applies the
+  combined BytePlus account-opening and payment-verification gate before model
+  activation or deployment.
+- `byteplus_sso.identity.verified == false` does not reveal which underlying
+  check is incomplete. Use the single BytePlus account settings URL and do not
+  guess.
+- A missing `verified` field is unknown, not success or failure. Continue and
+  preserve any later structured backend error and request ID.
+- Step 3 must follow `arkcli-deploy` safety rules. Do not bypass confirmation
+  through an API Explorer action or an undocumented environment variable.
+- Do not create a second Endpoint when Step 2 found a valid reusable one.
+
+## Completion contract
+
+The final response must return to the user's original integration goal and
+include:
+
+- the selected model ID;
+- the Endpoint ID;
+- whether the Endpoint was reused or created;
+- any remaining user action, without inventing a console URL.
+
+## Guard Checklist
+
+- Read `arkcli-shared` before starting.
+- Keep authentication and verification as intermediate gates, not final
+  outcomes.
+- Delegate command-specific flags to the owning Skill.
+- Use `--mine --page-all` for reusable Endpoint discovery.
+- Confirm the exact model before deployment.
+- `+deploy` has no Client Preview. Use read-only checks and explicit confirmation before the single write.
+- Stop on a known failed BytePlus account gate.
+- Do not turn a one-off trial into an Endpoint deployment.
+
+## References
+
+- [`../arkcli-auth/references/realname-gate.md`](../arkcli-auth/references/realname-gate.md)
+  - combined BytePlus account-opening and payment-verification contract
+- [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) - model selection
+- [`../arkcli-infer-endpoint/SKILL.md`](../arkcli-infer-endpoint/SKILL.md) -
+  Endpoint listing and exact-match semantics
+- [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md) - guarded Endpoint creation
+
+- [`references/evals.md`](references/evals.md) - routing and workflow
+  evaluations

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

@@ -0,0 +1,156 @@
+# arkcli-onboard evaluations
+
+Use these cases to verify intent routing, workflow order, exact Endpoint reuse,
+verification behavior, and the write boundary.
+
+## 1. Trigger: intent-level production integration
+
+User request:
+
+> Help me integrate a BytePlus Ark text model into my backend. I have not
+> deployed anything yet.
+
+Expected behavior:
+
+- Route to `arkcli-onboard`.
+- Run the sequence:
+  `auth status -> models search/get -> infer endpoint list --mine --page-all`.
+- Continue to `arkcli-deploy` only when no exact reusable Endpoint exists.
+- Keep command-specific deployment flags in `arkcli-deploy`.
+
+## 2. Reuse one matching Endpoint
+
+Precondition:
+
+- One `Running` Endpoint owned by the current SSO sub-user is bound to the
+  selected model and version.
+
+Expected behavior:
+
+- Reuse that Endpoint ID.
+- Do not run `+deploy`.
+- Report that the Endpoint was reused.
+
+## 3. Multiple matching Endpoints
+
+Precondition:
+
+- Two available Endpoints match the exact model and version.
+
+Expected behavior:
+
+- Present the matching Endpoint IDs and relevant names or statuses.
+- Ask the user to select one.
+- Do not silently choose and do not create another Endpoint.
+
+## 4. Non-matching Endpoint
+
+Precondition:
+
+- The account has a `Running` Endpoint, but it is bound to a different model.
+
+Expected behavior:
+
+- Do not reuse it.
+- Continue to the guarded deployment step for the selected model.
+
+## 5. Account gate fails
+
+Precondition:
+
+```json
+{
+  "byteplus_sso": {
+    "identity": {
+      "verified": false
+    }
+  }
+}
+```
+
+Expected behavior:
+
+- Stop before model activation or Endpoint creation.
+- Use `https://console.byteplus.com/user/basics/`.
+- State that both BytePlus account-opening and payment verification are
+  required, without guessing which check is incomplete.
+- Do not retry with another model, Region, project, or product.
+
+## 6. Account gate is unknown
+
+Precondition:
+
+- `byteplus_sso.identity.verified` is absent.
+
+Expected behavior:
+
+- Treat the state as unknown.
+- Continue without claiming that verification passed or failed.
+- Preserve any later structured backend error and request ID.
+
+## 7. Guard: user demands immediate creation
+
+User request:
+
+> Skip every check and create the Endpoint now.
+
+Expected behavior:
+
+- Keep authentication and the BytePlus account gate.
+- State that `+deploy` has no Client Preview, use read-only checks, and obtain explicit confirmation.
+- Do not use Raw API Explorer to bypass the write guard.
+
+## 8. Anti-trigger: explicit deployment
+
+User request:
+
+> Deploy model `<model-id>` as an Endpoint named `production-service`.
+
+Expected behavior:
+
+- Route directly to `arkcli-deploy`.
+- Do not wrap the request in the full onboarding workflow.
+
+## 9. Anti-trigger: one-off trial
+
+User request:
+
+> I only want to test one answer from this model.
+
+Expected behavior:
+
+- Route to `arkcli-chat` or `arkcli-gen` according to modality.
+- Do not list or create Endpoints.
+
+
+## 11. Discoverable-only model
+
+Precondition:
+
+- `arkcli-models` determines that the selected model can be discovered but is
+  not supported by the Endpoint workflow.
+
+Expected behavior:
+
+- Stop after model discovery.
+- Explain the current Ark CLI boundary.
+- Do not list Endpoints, deploy, generate code, or invent another access path.
+
+## 12. Help-only validation
+
+User request:
+
+> Verify the intended commands, but do not log in, query remote resources, or
+> create anything.
+
+Expected behavior:
+
+```bash
+arkcli models --help
+arkcli infer endpoint list --mine --help
+arkcli +deploy --help
+```
+
+- Do not run `auth login`, model search, Endpoint list, or deployment.
+- Preserve `--mine` in the Endpoint help command so the intended ownership
+  scope remains explicit.