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

package/skills/arkcli-chat/references/text-format.md

@@ -0,0 +1,167 @@
+---
+name: text-format
+description: arkcli +chat --text-format usage reference, makes the model output in the specified format (text / json_object / json_schema), with --text-schema for strong JSON Schema constraints.
+---
+
+# +chat Text Format
+
+Make the model output in a structured format. The three modes cover the full spectrum from "free text" to "strict JSON Schema".
+
+## When to use
+
+- **text**: Default; free text.
+- **json_object**: Makes the model output valid JSON without constraining shape; suitable for simple "return JSON" scenarios.
+- **json_schema**: Strict JSON Schema; required when an agent / downstream program needs a stable shape (reduces parsing failures).
+
+## Flag quick reference
+
+| flag | Purpose |
+|---|---|
+| `--text-format` | text \| json_object \| json_schema |
+| `--text-schema <path>` | JSON Schema file path; required in json_schema mode, ignored in other modes. |
+| `--text-schema-name` | Schema name; displayed when the server echoes it; the default value is `arkcli_response`. |
+| `--text-strict` | Strong constraint switch; only takes effect in json_schema mode. |
+
+With `--text-strict`, the CLI also enforces the response contract locally:
+
+1. The schema is compiled before the request. An invalid schema returns a validation error without a network call.
+2. Only a completed response is accepted. An incomplete response, including token truncation, exits non-zero with `invalid_response`.
+3. `content` must be a direct JSON value, without Markdown code fences or explanatory text.
+4. The JSON value must validate against the same schema. A mismatch exits non-zero with `invalid_response`.
+
+`--stream --text-strict` buffers events until the terminal event, validates the final content, and only then replays the events in order. Failed validation emits no partial JSON to stdout. Non-strict streaming and non-streaming behavior is unchanged.
+
+## Typical usage
+
+### json_object (simplest, makes the model output JSON)
+
+```bash
+arkcli +chat "What color are strawberries? Answer in JSON" --model ep-xxx \
+  --text-format json_object
+# The CLI returns an envelope; its .content string may contain {"color":"red"}.
+```
+
+### json_schema (strongly constrained shape)
+
+```bash
+cat > schema.json <<'JSON'
+{
+  "type": "object",
+  "properties": {
+    "color": {"type": "string", "description": "Color name"},
+    "hex":   {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"}
+  },
+  "required": ["color", "hex"]
+}
+JSON
+
+arkcli +chat "What color are strawberries? Provide the color name and hex" --model ep-xxx \
+  --text-format json_schema --text-schema schema.json --text-strict
+# The CLI returns an envelope; its .content string may contain {"color":"red","hex":"#FF3333"}.
+```
+
+### Multi-turn continuation + json_schema
+
+```bash
+RID=$(arkcli +chat "What color are strawberries?" --model ep --store \
+  --text-format json_schema --text-schema schema.json --text-strict \
+  --format json | jq -r .id)
+
+arkcli +chat "What about apples? Use the same format" --model ep --store \
+  --previous-response-id "$RID" \
+  --text-format json_schema --text-schema schema.json --text-strict
+```
+
+## Output format
+
+In non-streaming mode (when `+chat ...` does not include `--stream`), `ResponsesResult` adds a `text_format` echo:
+
+```json
+{
+  "id": "resp_...",
+  "model": "...",
+  "content": "{\"color\":\"red\",\"hex\":\"#FF3333\"}",
+  "usage": { ... },
+  "text_format": "json_schema"
+}
+```
+
+`text_format` is the format actually applied by the server, and you can also retrieve it with `chat get $RID` (autotest jsonschema_test asserts this parameter when running chat get).
+
+## Save the structured body
+
+`--text-format` constrains the model body; it does not remove the CLI envelope.
+Deliver the original `.content`, not the envelope, reasoning, or an answer
+rewritten by the Agent.
+
+Before invoking, resolve the admitted `MODEL`, the user's `PROMPT`, the matching
+`schema.json`, and the delivery path. This non-streaming strict example assumes
+the user requested a new `result.json`. If it already exists, resolve the path
+or overwrite intent before incurring usage. Add other verified parameters as
+requested and retain the admitted profile context.
+
+```bash
+test ! -e result.json && test ! -L result.json &&
+chat_response_file="$(mktemp ./arkcli-chat-response.XXXXXX)" &&
+arkcli +chat --model "$MODEL" --format json \
+  --text-format json_schema --text-schema schema.json --text-strict \
+  "$PROMPT" > "$chat_response_file" &&
+(set -C; jq -ej 'select(.status == "completed") | .content | select(type == "string" and length > 0)' \
+  "$chat_response_file" > result.json) &&
+jq empty result.json
+```
+
+This makes one model request. `jq -j` preserves the original body without adding
+a newline. The last command checks JSON syntax without rewriting whitespace or
+large integers. Local `set -C` prevents overwriting a file or symlink created
+during the request without changing the parent shell. The CLI still enforces
+schema and completion; a failed step must not be reported as successful delivery.
+Plain-text delivery does not require JSON syntax validation.
+If local extraction or writing fails, retain the captured response and repair
+only the local step; do not invoke the model again just to save the answer.
+Read `.id` or `.usage` from that file too, without enabling `--store` or calling
+`chat get` merely for local backup. Explicit continuation or regeneration is a
+separate request, not prohibited by this saving workflow.
+
+## Common errors
+
+| Symptom | Cause |
+|---|---|
+| `--text-format=json_schema requires --text-schema <path>` | json_schema mode is missing --text-schema |
+| `read --text-schema "X": no such file or directory` | Incorrect path or insufficient permissions |
+| `unsupported text.format.type "yaml"` | Format value is not text / json_object / json_schema |
+| `text.format.schema is required when type=json_schema` | Schema is omitted when using the raw API |
+| `invalid --text-schema for --text-strict` | The schema is not valid or cannot be compiled; no request was sent. |
+| `invalid_response` with `not completed` | The strict response was truncated; raise `--max-output-tokens` or request less output. |
+| `invalid_response` with `not a direct JSON value` | The content contains a Markdown fence, explanation, or invalid JSON. |
+| `invalid_response` with `did not match --text-schema` | The JSON does not match the schema; check the schema, model capability, and prompt. |
+
+## Equivalent to the raw API
+
+`+chat --text-format json_schema --text-schema f.json --text-strict --text-schema-name color` is equivalent to:
+
+```bash
+arkcli api arkruntime.create_responses --params '{
+  "model":"ep-xxx",
+  "input":"What color are strawberries?",
+  "text":{
+    "format":{
+      "type":"json_schema",
+      "schema":{...},
+      "name":"color",
+      "strict":true
+    }
+  }
+}'
+```
+
+## Autotest unlock checklist
+
+| Test case | Unlocked |
+|---|---|
+| `responseapi/jsonschema/TestJson1..3` | ✅ |
+| `responseapi/jsonschema/TestJsonCache1..3` | ✅ |
+| `responseapi/jsonschema/TestJsonSchema1..3` | ✅ |
+| `responseapi/jsonschema/TestJsonSchemaCache1..3` | ✅ |
+| `Test_ResponseCreate_TextFormat` (includes text + json_object) | ✅ |
+| `Test_Stream_TextFormat` | ✅ (streaming input parameters can be passed; echo uses PR-4 --include-events) |

package/skills/arkcli-chat/references/tools.md

@@ -0,0 +1,119 @@
+---
+name: tools
+description: arkcli +chat tools usage reference, including the JSON file protocol for custom tools and tool_choice / max_tool_calls tuning.
+---
+
+# +chat Tools
+
+PR-1 has the built-in `function` tool; `mcp` is left for PR-5b.
+
+## When to use
+
+- The user provides a function schema for the model to call → `function`
+- The user asks "Help me look up meeting minutes" → The current PR does not support this; prompt the user to use `arkcli api arkruntime.create_responses --params '...'` (raw API) or wait for PR-5b.
+
+## 4 new flags
+
+| flag | Type | Purpose |
+|---|---|---|
+| `--tools <type>` | repeatable string | Simple syntactic sugar; supports only the single-parameter `{"type":"<type>"}` form. No tools are currently supported. |
+| `--tools-file <path>` | string | Read a JSON file whose content is an array of tool objects in the full SDK form; function must use this method. |
+| `--tool-choice <mode>` | string | Tool calling policy: `auto` / `required` / `none`. If omitted, the server default is used. |
+| `--max-tool-calls <int>` | int | Maximum number of tool calls in a single session, to prevent uncontrollable behaviors.**Only takes effect for built-in tools**; when combined with a function tool (`--tools-file` or `--tools function:*`), arkcli intercepts it on the client side because the server reports `max_tool_calls only supported by build-in tools now`. |
+
+`--tools` and `--tools-file` can be used together and are merged with "sugar first, file later".
+
+## function (requires a JSON file)
+
+`tools.json`:
+
+```json
+[
+  {
+    "type": "function",
+    "name": "query_weather",
+    "description": "Query the weather for a city and return JSON",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "city": {"type": "string", "description": "City name, such as Beijing"}
+      },
+      "required": ["city"]
+    }
+  }
+]
+```
+
+Call:
+
+```bash
+arkcli +chat "What's the weather like in Beijing today?" \
+  --model ep-xxx \
+  --tools-file tools.json \
+  --tool-choice required
+```
+
+`function` object parameters (aligned with SDK `responses.ToolFunction`):
+
+| Parameter | Required |Description|
+|---|---|---|
+| `type` | ✅ | Must be `"function"` |
+| `name` | ✅ | Function name; the model uses it to identify the tool. |
+| `description` | Recommended | Function description for the model; the clearer it is, the more accurately the model can trigger it. |
+| `parameters` | Recommended | The parameters that describe the JSON Schema; write them directly as nested content, and arkcli internally serializes it into SDK Bytes. |
+| `strict` | Optional bool | Strict mode: forces parameters to conform to the schema |
+
+## Three tool_choice modes
+
+| mode | Meaning |
+|---|---|
+| `auto` | Server default; lets the model decide whether to call a tool. |
+| `required` | Forces at least one tool call. |
+| `none` | Prevents the model from calling tools even if tools are passed. |
+
+Complex function-specific tool_choice (`{"type":"function","name":"query_weather"}`) will be implemented in a later PR. For now, use `required` with a single tool to achieve the same effect.
+
+## Output format
+
+### Non-streaming (`+chat ...` without `--stream`)
+
+`ResponsesResult` has an additional `function_calls` parameter:
+
+```json
+{
+  "id": "resp_...",
+  "model": "...",
+  "content": "...",                  // The model's final text; it may be empty when a tool is triggered.
+  "reasoning_content": "...",
+  "usage": { ... },
+  "function_calls": [
+    {
+      "type": "function_tool_call",
+      "id": "call_...",
+      "name": "query_weather",
+      "arguments": "{\"city\":\"Beijing\"}",
+      ...
+    }
+  ]
+}
+```
+
+`function_calls[]` is passed through in the raw SDK form; different tool types have different parameters (`function_tool_call`, etc.). Use `jq '.function_calls[].type'` to distinguish them.
+
+### Streaming (`--stream`)
+
+Label lines such as `[Tool args] {"city":"Beijing"}` appear on stdout, inserted before or after `Response:` depending on the event order. Concatenating all chunks of `ChatStreamDelta.FunctionCallArgs` gives the complete args JSON.
+
+## Error handling
+
+| Symptom | Cause |
+|---|---|
+| `tool[N] type "X" not supported in this build` | A tool type supported only by PR-5b was used (`mcp`); use the raw API or wait for PR-5b. |
+| `function tool requires 'name'` | The function is missing the name parameter. |
+| `unsupported tool_choice "X"` | tool_choice is not auto/required/none. |
+| Model replies but does not trigger the tool. | The tool description is not clear enough, tool_choice=none, or the question is unrelated to the tool. |
+| Model repeatedly calls the same tool. | Add `--max-tool-calls` to limit it, or describe when to stop in the tool description. |
+
+## Integration with chat get
+
+After `--store` is added, even after streaming finishes, you can later use `chat get <id>` to get the complete `function_calls` list; `chat list-input-items <id>` can also show the complete tool call history (including result items such as `function_tool_call_output`).

package/skills/arkcli-config/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: arkcli-config
+version: 0.3.1
+description: "Diagnose BytePlus Ark CLI configuration precedence, effective profile, Region, project, base URL, API key, environment, UI language, persisted update mode, and local reset behavior. Use for unclear overrides, update opt-in/out, legacy config migration, inspection, or reset."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli config --help"
+---
+
+# BytePlus Ark CLI configuration
+
+Before using this Skill, read
+[`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md). It defines the
+BytePlus product boundary, authentication flow, output rules, and write
+confirmation requirements.
+
+Use this Skill for configuration diagnosis and the remaining `arkcli config`
+commands. Use [`../arkcli-profile/SKILL.md`](../arkcli-profile/SKILL.md) for
+profile creation, selection, deletion, project changes, resource defaults, and
+API key selection.
+
+## BytePlus configuration boundary
+
+- BytePlus state is stored under `$HOME/.arkcli-bp/`.
+- The control-plane Region is fixed to `ap-southeast-1`. Do not fall back to
+  another Region or product.
+- BytePlus supports the `en_us` UI locale only.
+- Do not read or edit files under `$HOME/.arkcli-bp/` directly. Use Ark CLI
+  commands so secrets remain masked and migrations remain intact.
+
+## When To Trigger
+
+- A command used the wrong profile, account, project, Region, base URL, or API
+  key.
+- The user needs to understand which flag, environment variable, profile, or
+  identity value won.
+- The user asks about `ARK_PROFILE`, `ARK_API_KEY`, `ARK_BASE_URL`, or
+  `ARK_CLIENT_ENV`, including whether legacy `ARK_REGION` or
+  `ARK_PROJECT_NAME` values still have an effect.
+- The user needs `arkcli config lang`, `arkcli config reset`, or a migration
+  from a deprecated `arkcli config` profile command.
+- The user explicitly wants to enable, disable, or restore automatic-update behavior.
+
+## When NOT To Trigger
+
+- Missing login, an expired session, `401`, or permission failure: use
+  [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+- Profile creation, switching, deletion, project selection, or API key
+  management: use [`../arkcli-profile/SKILL.md`](../arkcli-profile/SKILL.md).
+- A business task such as model discovery, generation, deployment, or usage:
+  diagnose configuration only if evidence points here, then return to the
+  owning business Skill.
+
+## Agent execution order
+
+1. Follow the shared authentication boundary and inspect the masked current context:
+
+   ```bash
+   arkcli auth status --format json
+   arkcli auth whoami --format json
+   ```
+
+2. For Chat/Gen defaults and routing, follow the Resources Skill:
+
+   ```bash
+   arkcli resources list --modality text --format json
+   ```
+
+3. Identify invocation-scoped flags and relevant environment variables without
+   printing secret values.
+4. Explain the winning source explicitly before proposing a change.
+5. After the configuration issue is resolved, return to the user's original
+   task.
+
+`profile show/list/keys list` may synchronize remote keys and write back the
+local key inventory or default key. Masked output does not imply no side
+effects. Do not use these commands for routine Chat/Gen admission or when the
+user requests no configuration/key changes; deprecated `config show/list`
+is not a workaround. Use `profile show` or `profile list` only for an explicit
+Profile inspection/management task, explaining the synchronization impact first.
+
+The Profile fields in `auth whoami` are a persisted-slice summary, not proof
+that a temporary key/base-URL override or data-plane request works. State
+unverified facts as unknown rather than changing configuration to fill gaps.
+
+## Resolution precedence
+
+Profile selection, from highest to lowest:
+
+```text
+--profile
+  > ARK_PROFILE
+  > config.yaml default_profile
+  > first supported platform profile by name
+  > "default"
+```
+
+Other effective values follow these product rules:
+
+| Value | Highest to lowest |
+|---|---|
+| API key | `--api-key` > `ARK_API_KEY` > active profile > bound identity; legacy fallback is used only when no identity is bound |
+| Base URL | `--base-url` > `ARK_BASE_URL` > active profile value > value derived from profile type and Region > BytePlus default |
+| Region | active profile > `ap-southeast-1`; BytePlus rejects any other persisted effective Region |
+| Project | active profile project > active identity fallback > `default` |
+| Environment | `--env` > `ARK_CLIENT_ENV` > active profile > `prod` |
+
+Do not infer product identity from these values. Product identity is compiled
+into the BytePlus binary.
+
+`--region`, `--project-name`, `ARK_REGION`, and `ARK_PROJECT_NAME` do not
+override runtime scope. Select or update a profile instead. For temporary
+data-plane calls, `--api-key`/`ARK_API_KEY` and
+`--base-url`/`ARK_BASE_URL` are the supported override pair; an explicit base
+URL must never reuse a profile API key.
+
+## Active commands
+
+| Command | Purpose | Safety |
+|---|---|---|
+| `arkcli config lang get` | Show the persisted effective UI locale | Read-only |
+| `arkcli config lang set en_us` | Persist the only locale supported by BytePlus | Writes `config.yaml` |
+| `arkcli config lang unset` | Remove the persisted locale and use the BytePlus build default | Writes `config.yaml` |
+| `arkcli config set update.mode automatic` | Explicitly enable automatic for this exact install; when recovering from non-latest, install latest first | Writes config and exact consent |
+| `arkcli config set update.mode disabled` | Stop silent installation while retaining implicit checks, notices, and manual update commands | Writes `config.yaml` |
+| `arkcli config reset` | Remove both local configuration files after an interactive confirmation | Destructive |
+
+`arkcli config reset` does not remove BytePlus SSO tokens, the identity store,
+or cached credentials. Use `arkcli auth logout` when the user explicitly wants
+to remove authentication state.
+
+The only public modes are `automatic` and `disabled`. `disabled` retains implicit version checks and update notices but never installs silently; explicit `arkcli update` and `arkcli update --check` also remain available. Missing mode values and legacy persisted `notify` values are presented as `disabled`. Legacy persisted `notify` values continue to read as `disabled`, but never recommend the legacy setter.
+
+The fail-closed Windows, macOS, and Linux transactions and all BytePlus production gates are open. A stable global npm postinstall compares the installed version with the registry's current `latest`: non-latest persists `disabled`; current latest preserves the mode and reissues exact-install authorization when the persisted mode is `automatic`. Postinstall never performs an immediate version replacement.
+
+### Fresh-install enrollment
+
+Only a stable global npm install that can prove `$HOME/.arkcli-bp` did not previously exist and whose installed version equals registry `latest` defaults to `automatic` with inert pending evidence.
+
+- The first successful eligible human business command completes pending -> grace -> active in one policy transaction.
+- After exact-install consent is revalidated as active, that invocation may schedule an automatic patch update.
+- Every CLI process started by npm `postinstall` (including its `+connect` invocation), and a user-run `+connect`, skips enrollment, implicit version checks, and automatic scheduling.
+- AI Skills, CI, non-TTY invocations, Client Preview, `config`, `update`, and internal maintenance commands neither consume enrollment nor schedule automatic work.
+- A committed update result appears once on stderr after the next successful human business command. It never changes stdout or the business exit code.
+
+Production automatic updates deliberately keep the 24/48/72-hour and 10%/50%/100% cohort admission disabled. The original rollout implementation and regression coverage remain in place, and the online Probe still requires two independent observations. Normal automatic updates still require exact consent, a live registry target/SRI/tarball check, a one-use reservation, backoff, and every staged-apply safety boundary.
+
+An npm reinstall never reuses the old exact-install receipt. If the installed version equals current `latest`, the existing mode is unchanged: `automatic` receives a new exact receipt, while `disabled` or legacy `notify` stays off. A non-latest install persists `disabled`. Registry failure leaves the mode unchanged and issues no receipt; `--ignore-scripts` performs no reconciliation. To recover from non-latest, install latest first and then run `arkcli config set update.mode automatic`. For a persistent version pin, run:
+
+```bash
+arkcli config set update.mode disabled
+npm i @byteplus/ark-cli@<exact-version> -g --registry https://registry.npmjs.org
+```
+
+For a deterministic pin even when the registry is unavailable, set `disabled` before installing the exact version. The policy lives in `$HOME/.arkcli-bp/config.yaml`, outside the npm package tree, and installing `@latest` does not change it back to `automatic`. `arkcli config reset` attempts to revoke exact consent before clearing configuration. A release published between npm resolving `@latest` and postinstall querying the registry can rarely cause a false non-latest classification.
+
+BytePlus rejects `zh_cn` even though the shared command parser recognizes that
+locale for other products.
+
+## Deprecated compatibility
+
+The following commands remain only for old scripts and are hidden from normal
+`arkcli config --help` output:
+
+| Deprecated | Use instead |
+|---|---|
+| `arkcli config init` | `arkcli profile create` |
+| `arkcli config list` | `arkcli profile list` |
+| `arkcli config show` | `arkcli profile show` |
+| `arkcli config switch <name>` | `arkcli profile use <name>` |
+| `arkcli config delete <name>` | `arkcli profile delete <name>` |
+
+Do not generate new automation with deprecated commands.
+
+## Guard Checklist
+
+- For routine admission, use `auth status/whoami` and `resources`; preserve the
+  user's no-configuration-change intent, including implicit key reconciliation.
+- Never echo a full token, API key, access key, or secret key.
+- Confirm the exact target before `profile use`, `profile delete`, project
+  changes, language changes, or `config reset`.
+- The entire `config` and `profile` domains reject `--dry-run`; restate the
+  exact mutation and obtain confirmation. Do not describe `profile show/list`
+  as a no-write substitute for preview.
+- Keep BytePlus on `ap-southeast-1`; do not retry through another product.
+- Return to the user's original business task after configuration is fixed.
+- Use only the allowlisted `update.mode` key; never treat `config set` as a generic YAML-path writer. `disabled` still permits implicit checks and notices, and it does not disable explicit `arkcli update` or `arkcli update --check`.
+
+## References
+
+- [`references/arkcli-config-init.md`](references/arkcli-config-init.md) -
+  migration from `config init` to BytePlus profile creation
+- [`references/arkcli-config-profile.md`](references/arkcli-config-profile.md) -
+  deprecated command mapping and active profile operations
+- [`references/evals.md`](references/evals.md) - trigger, routing, precedence,
+  and safety evaluations

package/skills/arkcli-config/references/arkcli-config-init.md

@@ -0,0 +1,89 @@
+# Migrating from `config init`
+
+`arkcli config init` is deprecated and hidden from normal help output. Create
+BytePlus profiles with `arkcli profile create`.
+
+## Product boundary
+
+The standalone BytePlus binary fixes these values at build time:
+
+| Setting | BytePlus value |
+|---|---|
+| Product identity | BytePlus |
+| State directory | `$HOME/.arkcli-bp/` |
+| Control-plane Region | `ap-southeast-1` |
+| UI locale | `en_us` |
+
+Do not copy a tenant selector, Region fallback, state path, or credentials from
+another product.
+
+## Supported profile types
+
+BytePlus profile creation accepts:
+
+- `platform`
+- `coding-plan`
+- `coding-plan-team`
+
+Inspect the exact current flags before constructing a command:
+
+```bash
+arkcli profile create --help
+```
+
+Preview a pay-as-you-go profile:
+
+```bash
+arkcli profile create \
+  --type platform \
+  --region ap-southeast-1 \
+  --project default \
+  --set-default \
+  --format json
+```
+
+After the user confirms the profile name, project, and default-profile change,
+execute the command only after that confirmation.
+
+For Coding Plan profiles, let Ark CLI detect the active subscription:
+
+```bash
+arkcli profile create --type coding-plan --set-default
+arkcli profile create --type coding-plan-team --set-default
+```
+
+Do not force `--plan-tier` unless the user explicitly supplies the tier and
+understands that it bypasses subscription detection. A team profile still
+requires a valid assigned seat.
+
+## Project resolution
+
+Project Name participates in the effective runtime scope:
+
+```text
+active profile.project
+  > active BytePlus identity fallback
+  > default
+```
+
+There is no global `--project-name` or `ARK_PROJECT_NAME` runtime override.
+The local `--project` flag on `profile create` persists the project in the new
+profile. Use `arkcli profile project [<project-name>]` to change the persisted
+project slice without adding a project override to a business command.
+
+## Credentials
+
+Do not place API keys directly into generated shell history unless the user
+explicitly requests an inline key. For routine admission, prefer the masked
+authenticated BytePlus identity summary:
+
+```bash
+arkcli auth whoami --format json
+```
+
+Use `arkcli profile apikey list --format json` only for explicit Profile key
+management after warning that it may synchronize remote keys and write back the
+local key inventory or default key.
+
+Never read or edit files under `$HOME/.arkcli-bp/` to change a project or API
+key.

package/skills/arkcli-config/references/arkcli-config-profile.md

@@ -0,0 +1,106 @@
+# Profile command migration and configuration scope
+
+Profile operations belong to `arkcli profile`. The `arkcli config` group now
+owns global UI language, the allowlisted `update.mode` policy, full
+configuration reset, and compatibility for legacy scripts.
+
+## Routine admission
+
+Use `arkcli auth status --format json` and `arkcli auth whoami --format json`
+for the masked current identity/Profile. Use `arkcli resources list --modality
+text --format json` for the current chat default and follow the Resources Skill
+for compatibility checks. These summaries do not prove a data-plane request
+will succeed; report missing evidence instead of inferring key validity.
+
+## Explicit Profile inspection and management
+
+`profile show/list/keys list` may synchronize remote keys and write back the
+local key inventory, clear an invalid key, or select another default key.
+Explain that impact before using them for an explicit Profile task. Do not use
+them for routine Chat/Gen admission or a no-configuration/key-change request,
+and do not bypass that boundary with deprecated `config show/list`.
+
+```bash
+# Show the effective active profile
+arkcli profile show --format json
+
+# Show one named profile
+arkcli profile show <profile-name> --format json
+
+# List all profiles
+arkcli profile list --format json
+```
+
+Structured profile output masks secrets but is not side-effect-free. Do not read
+`$HOME/.arkcli-bp/config.yaml`.
+
+## Profile writes
+
+```bash
+# Change the default profile
+arkcli profile use <profile-name> --format json
+
+# Preview creation
+arkcli profile create --type platform --format json
+
+# Delete after confirming the exact target
+arkcli profile delete <profile-name> --format json
+
+# Re-select the project after reviewing the replacement scope
+arkcli profile project <project-name>
+```
+
+`profile use` changes the top-level default-profile pointer. `profile delete`
+removes one local profile. `profile project` can replace project-scoped
+profiles, so inspect its output and confirm before using `--yes`.
+
+Use [`../SKILL.md`](../SKILL.md) for configuration precedence and
+[`../../arkcli-profile/SKILL.md`](../../arkcli-profile/SKILL.md) for the full
+profile workflow.
+
+## Active `config` commands
+
+```bash
+arkcli config lang get
+arkcli config lang set en_us
+arkcli config lang unset
+arkcli config set update.mode automatic
+arkcli config set update.mode disabled
+arkcli config reset
+```
+
+The only public update modes are `automatic` and `disabled`. `disabled` stops
+silent installation while retaining implicit version checks, notices, and
+explicit `arkcli update` / `arkcli update --check`. Legacy `notify` values in
+persisted configuration remain compatible inputs but are not settable.
+
+With the production gates open, a provably fresh BytePlus stable global npm
+install whose version equals registry `latest` starts inert enrollment bound to
+the exact install. The first successful eligible human business command
+completes grace and consent; after active revalidation it may schedule. A
+current-latest reinstall preserves the mode and reissues exact consent only for
+existing `automatic`; a non-latest install persists `disabled`.
+
+For a persistent version pin, set `disabled` before installing the exact
+`@byteplus/ark-cli` version. Installing `@latest` does not turn `disabled` back
+into `automatic`; recover by installing latest and then explicitly setting
+automatic. The policy lives in `$HOME/.arkcli-bp/config.yaml`, outside the npm
+package tree.
+
+BytePlus rejects `zh_cn`. `config reset` removes
+`$HOME/.arkcli-bp/config.yaml` and legacy
+`$HOME/.arkcli-bp/config.json`; it does not remove the BytePlus identity store
+or SSO tokens.
+
+## Deprecated mapping
+
+| Deprecated command | Active replacement |
+|---|---|
+| `arkcli config init` | `arkcli profile create` |
+| `arkcli config list` | `arkcli profile list` |
+| `arkcli config show` | `arkcli profile show` |
+| `arkcli config switch <name>` | `arkcli profile use <name>` |
+| `arkcli config delete <name>` | `arkcli profile delete <name>` |
+
+The deprecated commands may still execute for compatibility, but they are
+hidden from normal help and must not be used in new automation.