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

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

@@ -0,0 +1,154 @@
+# arkcli-config evaluations
+
+Use these cases to verify routing, precedence explanations, BytePlus product
+isolation, and write guards.
+
+## 1. Trigger: wrong effective endpoint
+
+User request:
+
+> My BytePlus command reached the wrong base URL. Check which configuration
+> source won.
+
+Expected behavior:
+
+- Route to `arkcli-config`.
+- Start with `arkcli auth status --format json` and `arkcli auth whoami --format json`;
+  follow the Resources Skill for Chat/Gen defaults and routing.
+- `profile show/list/keys list` may synchronize and write back keys. Do not use
+  them for routine admission or a no-configuration/key-change request.
+- Explain `--base-url > ARK_BASE_URL > profile > derived/default`.
+- Inspect relevant invocation flags and environment variable presence without
+  printing secret values.
+- Do not change configuration before identifying the winning source.
+
+## 2. Trigger: profile precedence
+
+User request:
+
+> `--profile` and `ARK_PROFILE` name different profiles. Which one is active?
+
+Expected behavior:
+
+- State the complete order:
+  `--profile > ARK_PROFILE > default_profile > first platform profile > "default"`.
+- Use the current invocation and masked `auth whoami` context as evidence;
+  distinguish persisted Profile values from unverified temporary overrides.
+- Do not read `$HOME/.arkcli-bp/config.yaml` directly.
+
+Composition regression: "What is my current default chat model, and can I use it?
+Only inspect; do not send requests or change configuration or keys."
+Require actual shared/Config/Resources Skill loading and context/default queries,
+no key-reconciling Profile commands and no Chat/Gen execution. The answer must
+separate known routing compatibility from untested key usability, permission,
+quota and actual inference. Score evidence and actions, not fixed answer phrases.
+
+## 3. Anti-trigger: authentication failure
+
+User request:
+
+> My command returns 401. Should I reset the config?
+
+Expected behavior:
+
+- Route first to `arkcli-auth`.
+- Run `arkcli auth status --format json`.
+- Do not reset configuration unless later evidence shows a configuration
+  problem and the user explicitly requests the reset.
+
+## 4. Anti-trigger: profile management
+
+User request:
+
+> Create a Coding Plan Team profile and make it active.
+
+Expected behavior:
+
+- Route to `arkcli-profile`.
+- Do not use deprecated `arkcli config init` or `arkcli config switch`.
+- Preserve the BytePlus profile type boundary.
+
+## 5. Guard: full configuration reset
+
+User request:
+
+> Delete all local BytePlus configuration.
+
+Expected behavior:
+
+- Explain that the operation removes `$HOME/.arkcli-bp/config.yaml` and legacy
+  `$HOME/.arkcli-bp/config.json`.
+- Explain that SSO tokens and identity-store credentials are not removed.
+- Explain that `config/profile` do not support `--dry-run`.
+- Execute `arkcli config reset` only after explicit confirmation.
+
+## 6. BytePlus locale boundary
+
+User request:
+
+> Persist Chinese output for BytePlus.
+
+Expected behavior:
+
+- Explain that BytePlus supports `en_us` only.
+- Do not attempt to persist `zh_cn`.
+- Offer `arkcli config lang get`, `arkcli config lang set en_us`, or
+  `arkcli config lang unset` as appropriate.
+
+## 7. BytePlus Region boundary
+
+User request:
+
+> This call failed in `ap-southeast-1`; retry it in another Region.
+
+Expected behavior:
+
+- Refuse the Region fallback.
+- Keep the control-plane Region at `ap-southeast-1`.
+- Diagnose the original failure without switching product, state directory, or
+  credentials.
+
+## 8. Offline command-surface checks
+
+These checks must not contact a remote service:
+
+```bash
+arkcli config --help
+arkcli config lang --help
+arkcli config reset --help
+arkcli profile create --help
+```
+
+Verify that:
+
+- `config --help` exposes active `lang` and `reset` commands;
+- `config reset --dry-run` fails as an unknown flag;
+- deprecated profile-management commands are not recommended;
+- `profile create --help` lists only BytePlus-supported profile types;
+- help-only inspection does not remove files; never invent a reset preview flag.
+
+## 9. Persisted update mode
+
+User request:
+
+> Enable guarded automatic updates for BytePlus Ark CLI.
+
+Expected behavior:
+
+- Explain that this is a persisted local configuration write.
+- Run `arkcli config set update.mode automatic` after the explicit request.
+- Explain that the only public modes are `automatic` and `disabled`; missing values and legacy `notify` values are presented as `disabled`.
+- The BytePlus Windows/macOS/Linux production gates are open; explicit `automatic` must persist config and establish exact-install consent rather than reporting success after only one of those writes.
+- Explain that `disabled` stops silent installation while retaining implicit version checks, update notices, and explicit manual update commands.
+- Never recommend the legacy `notify` setter; legacy persisted values remain compatible inputs only.
+
+After the production gate opens, default enrollment must also satisfy these rules:
+
+- Only a provably fresh BytePlus stable global npm install whose version equals registry `latest` enters `fresh_pending`.
+- The first successful eligible human business command completes grace and exact consent in one policy transaction; after active revalidation that invocation may schedule.
+- AI Skills, CI, non-TTY, Preview, config/update, and internal maintenance commands do not consume grace or schedule.
+- A current-latest reinstall preserves the mode and reissues exact consent only for existing `automatic`; a non-latest install persists `disabled`. Registry failure changes no mode and issues no consent; `--ignore-scripts` does not reconcile.
+- Persistently pin by setting `disabled` before installing `@byteplus/ark-cli@<exact-version>`. Installing `@latest` does not turn `disabled` back into `automatic`; recovery is latest first, then an explicit automatic setting.
+- Report a committed automatic result once on stderr after a human business command. Never pollute stdout or change the business exit code.
+- Explain that explicit `arkcli update` and `arkcli update --check` work in every mode.
+- Never edit `$HOME/.arkcli-bp/config.yaml` directly or create a scheduled task.

package/skills/arkcli-connect/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: arkcli-connect
+version: 0.4.0
+description: "Install, inspect, refresh, or uninstall BytePlus Ark CLI Skills for supported local AI agents or one explicit Skills directory. Use for managed Skill updates, project-scoped installation, automatic public-package post-install setup, remote or embedded Skill refresh, and explicit legacy prefix cleanup."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli +connect --help"
+---
+
+# Connect BytePlus Ark CLI Skills
+
+Before using this Skill, read
+[`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) for common safety and
+product-isolation rules.
+
+`arkcli +connect` copies the Skills available to the current BytePlus build into
+supported local AI agent directories. Internal builds may embed Skills. Public
+npm builds download their reviewed English Skills from the package manifest,
+with CDN as primary and GitHub Release as fallback. Installation is local and
+does not require BytePlus authentication.
+
+## When To Trigger
+
+- Install BytePlus Ark CLI Skills into detected local AI agents.
+- Install them into a project-level or custom Skills directory.
+- List supported agents and local detection status.
+- Preview or remove installed Ark CLI Skills.
+- Explain why package installation automatically connected Skills.
+- Explain `--refresh` or `--keep-conflicting`.
+
+## When NOT To Trigger
+
+- `401`, login, token, or permission failures: use
+  [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+- Profile, Region, project, base URL, or API key selection: use
+  [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md) or
+  [`../arkcli-profile/SKILL.md`](../arkcli-profile/SKILL.md).
+- Model invocation or code generation: use the owning business Skill.
+- Agent runtime, model-provider, or MCP configuration: `+connect` installs
+  Skills only and does not configure those systems.
+
+## Command surface
+
+| Command | Behavior |
+|---|---|
+| `arkcli +connect list` | List supported agents, paths, and detection status; read-only |
+| `arkcli +connect` | Install into all detected agent Skill directories |
+| `arkcli +connect --path <skills-dir>` | Install only into one explicit Skills directory |
+| `arkcli +connect uninstall` | Remove unchanged Skills recorded in the ArkCLI ownership manifest from all detected agents |
+| `arkcli +connect uninstall --path <skills-dir>` | Remove unchanged managed Skills only from one explicit directory |
+| `arkcli +connect uninstall --purge-prefix` | Destructively remove every `ark-` or `arkcli-` directory or symlink from detected targets |
+| `arkcli +connect uninstall --path <skills-dir> --purge-prefix` | Apply destructive prefix cleanup only to one explicit directory |
+
+Installation is the default action. The only subcommands are `list` and
+`uninstall`. Do not invent `install`, `setup`, `sync`, or `remove`
+subcommands. `--path` is a flag, not a subcommand.
+
+## Agent execution order
+
+1. If the user only asks what is supported, run `arkcli +connect list` and
+   stop.
+2. `+connect` does not support `--dry-run`; inspect targets with `list`.
+3. Explain that installation makes the current catalog authoritative, while
+   normal uninstall removes only unchanged ownership-manifest entries.
+4. Require an additional explicit confirmation before any `--purge-prefix`
+   command because it includes user-managed entries.
+5. Run the exact confirmed command.
+6. Report installed, purged, skipped, or removed counts and paths.
+
+## Managed ownership contract
+
+Each target contains `.arkcli-managed-skills.json`, which records the exact
+Skill names, product, and tree digests written by ArkCLI.
+
+Normal installation:
+
+- overwrites every exact current-catalog name, regardless of previous owner,
+  digest, product, or local edits;
+- removes every previously manifest-owned name that is absent from the current
+  catalog, even when its bytes changed;
+- preserves every different name that is neither in the current catalog nor
+  in the previous manifest;
+- stages, backs up, installs, and updates the manifest as one rollback-safe
+  transaction.
+
+The manifest digests remain provenance and protect normal uninstall. They no
+longer block installation. Local customization under an official catalog name
+is intentionally ephemeral; use a different Skill name to preserve it.
+
+The historical `arkcli-managed-agent` alias is retired through this general
+rule when an old manifest owns it, while the canonical `arkcli-agent` is
+installed from the current catalog. There is no BytePlus-only install bypass.
+
+Use `uninstall --purge-prefix` only for an explicitly confirmed legacy cleanup.
+That mode restores the old broad prefix deletion and can remove user content.
+
+## `--path` isolation
+
+```bash
+arkcli +connect --path .claude/skills
+```
+
+- The value is the exact Skills directory, not a project root.
+- Relative paths resolve from the current working directory.
+- Absolute paths are used unchanged.
+- Only that directory is created and its current catalog plus previous
+  manifest are converged.
+- Other different-name entries remain untouched.
+- The command does not scan global agents, clean legacy private agent
+  directories, or remove external conflicting Skills outside the target.
+
+## Detected-agent installation
+
+Default installation:
+
+- detects supported agents from local filesystem paths;
+- deduplicates agents that share one Skills directory;
+- prefers an agent-specific detection home, such as Codex or Pi, when choosing
+  the representative name for a shared target;
+- installs each unique target path once;
+- cleans legacy private Ark CLI copies that would otherwise create duplicate
+  Skill names;
+- may remove specifically recognized external generation Skills that conflict
+  with Ark CLI routing.
+
+Use `arkcli +connect --keep-conflicting` only when the user explicitly wants to
+preserve those recognized external Skills. This flag applies to detected-agent
+installation; isolated `--path` installation does not remove them.
+
+Do not hardcode the supported-agent list in an answer. Use:
+
+```bash
+arkcli +connect list
+```
+
+## BytePlus `--refresh`
+
+Delivery mode depends on the build:
+
+- public npm BytePlus: refresh the package-local Skill tree from CDN primary,
+  then GitHub Release fallback when configured;
+- internal BytePlus: report embedded mode and continue with the embedded tree.
+
+Do not guess. Report the source printed by the CLI, such as `cdn`, `github`, or
+`embedded`, and never claim a successful download for an embedded build.
+
+## Uninstall guard
+
+Normal `uninstall` removes only manifest-owned, digest-unchanged Skills. It
+preserves unowned and user-modified entries. `--purge-prefix` is the separate
+destructive compatibility path.
+
+Always:
+
+1. run `arkcli +connect list` for global scope or resolve the exact `--path`;
+2. inspect the exact target with `list`;
+3. show the affected paths and whether managed-only or prefix purge applies;
+4. obtain explicit confirmation for prefix purge;
+5. execute the exact confirmed command.
+
+## Automatic package setup
+
+The package post-install script can run `+connect` automatically when it has
+an interactive controlling terminal. It silently skips CI, non-interactive
+sessions, unsupported platforms, or missing binaries. Set
+`ARKCLI_SKIP_POSTINSTALL=1` before package installation to disable automatic
+connection.
+
+Automatic post-install always uses the same authoritative-catalog transaction
+and never enables `--purge-prefix`. It is non-blocking for package installation.
+On success, its compact summary reports the unique target count and the
+representative agent names without per-target path progress. A filesystem or
+connection failure does not imply a BytePlus authentication failure.
+
+## Guard Checklist
+
+- Use `list` for read-only discovery.
+- Never generate `--dry-run` for this domain; use `list` and explicit confirmation.
+- Overwrite every exact official catalog name during install; preserve only
+  unrelated different-name entries.
+- Preserve modified manifest-owned entries during normal uninstall.
+- Treat `--purge-prefix` as an explicit destructive compatibility operation.
+- Confirm global versus explicit `--path` scope.
+- Never translate `--path` into an agent selector.
+- Do not invent subcommands.
+- Do not require login.
+- Distinguish public remote refresh from internal embedded mode using actual CLI output.
+- Do not use `+connect` to diagnose a business-command `401`.
+
+## References
+
+- [`references/arkcli-connect.md`](references/arkcli-connect.md) - detailed
+  paths, cleanup, post-install, and error behavior
+- [`references/evals.md`](references/evals.md) - routing, preview, uninstall,
+  and anti-hallucination evaluations

package/skills/arkcli-connect/references/arkcli-connect.md

@@ -0,0 +1,165 @@
+# `+connect` detailed reference
+
+Read [`../SKILL.md`](../SKILL.md) first.
+
+## Exact command grammar
+
+```text
+arkcli +connect [flags]
+arkcli +connect list
+arkcli +connect uninstall [flags]
+```
+
+Valid parent flags:
+
+- `--path <skills-dir>`
+- `--refresh`
+- `--keep-conflicting`
+
+Valid uninstall flags:
+
+- `--path <skills-dir>`
+- `--purge-prefix`
+
+There is no `install`, `setup`, `sync`, or `remove` subcommand.
+
+## Default installation
+
+```bash
+arkcli +connect
+```
+
+The default workflow:
+
+1. detects supported agents from local directories;
+2. maps each detected agent to its Skills directory;
+3. deduplicates shared directory paths;
+4. prefers an agent-specific detection home, such as Codex or Pi, when choosing
+   the representative name for a shared target;
+5. reads the Ark CLI ownership manifest and stages the complete current catalog;
+6. removes recognized routing conflicts unless `--keep-conflicting` is set;
+7. atomically overwrites every current-catalog name and retires names that left
+   the catalog;
+8. cleans duplicate legacy private copies where required;
+9. reports the result for each unique target path.
+
+Detection and installation paths may differ for agents that consume a shared
+Skills directory. Always use `arkcli +connect list` instead of assuming a
+path.
+
+## Explicit directory mode
+
+```bash
+cd /path/to/project
+arkcli +connect --path .claude/skills
+```
+
+The result is similar to:
+
+```text
+/path/to/project/.claude/skills/arkcli-auth/SKILL.md
+/path/to/project/.claude/skills/arkcli-chat/SKILL.md
+/path/to/project/.claude/skills/arkcli-shared/SKILL.md
+/path/to/project/.claude/skills/.arkcli-managed-skills.json
+```
+
+Explicit directory mode:
+
+- resolves a relative value from the current working directory;
+- accepts an absolute value unchanged;
+- creates the target directory when installing;
+- overwrites every exact current-catalog name inside that directory;
+- retires previous manifest names that left the catalog;
+- preserves unrelated different-name `ark-` and `arkcli-` directories;
+- does not scan global agents;
+- does not clean legacy private directories;
+- does not remove external conflicts outside the directory;
+- does not change agent runtime or MCP configuration.
+
+An empty `--path` is rejected and must never fall back to global installation
+or uninstallation.
+
+## Ownership and cleanup details
+
+Each target contains `.arkcli-managed-skills.json`. The manifest records the
+exact managed Skill names and their full-tree SHA-256 digests.
+
+Install and uninstall intentionally use different digest policies:
+
+- install treats the current CLI catalog as authoritative and overwrites every
+  exact current-catalog name, regardless of ownership or local changes;
+- install retires every previous manifest name absent from the current catalog,
+  regardless of local changes;
+- install preserves a different name that is in neither the current catalog nor
+  the previous manifest, even when it begins with `ark-` or `arkcli-`;
+- install stages the full incoming tree before moving current paths to backup;
+  any failure rolls the whole catalog and manifest back;
+- normal uninstall still requires the current digest to match the recorded
+  digest and preserves modified managed entries.
+
+`arkcli-managed-agent` to `arkcli-agent` follows the same catalog transaction:
+an old manifest-owned alias leaves the catalog and is retired, while the
+canonical current name is overwritten with the selected bundle. The outcome
+does not depend on the old manifest product or digest.
+
+For intentional legacy cleanup, use:
+
+```bash
+arkcli +connect uninstall --purge-prefix
+arkcli +connect uninstall --path /exact/skills/dir --purge-prefix
+```
+
+`--purge-prefix` is destructive: it removes every directory or symlink whose
+name begins with `ark-` or `arkcli-`, including user-managed entries. The flag
+is the explicit opt-in to that broad cleanup. Symlinks are unlinked without
+following and deleting their source target.
+
+## Safety boundary
+
+The entire `+connect` domain rejects `--dry-run`. Use `+connect list` to
+inspect detected targets. Restate the exact path and broad cleanup impact
+before any `uninstall --purge-prefix` command.
+
+## BytePlus refresh behavior
+
+Public BytePlus npm packages use the reviewed English Skill manifest published
+with the release. `arkcli +connect --refresh` prefers the BytePlus CDN bundle
+and falls back to the BytePlus GitHub release bundle. Internal BytePlus builds
+may use the English bundle embedded in the current binary.
+
+The CLI output is authoritative: report the actual selected source as `cdn`,
+`github`, or `embedded`. Do not claim a remote refresh when the CLI reports
+`embedded`.
+
+## Post-install behavior
+
+The package post-install script:
+
+1. skips when `ARKCLI_SKIP_POSTINSTALL=1` or a CI environment is detected;
+2. validates the platform binary;
+3. attempts to open an interactive controlling terminal;
+4. runs the binary with `+connect` when that terminal is available;
+5. reports the unique target count and representative agent names in the
+   compact success line without per-target path progress;
+6. treats connection failure as non-blocking for package installation.
+
+Piped and other non-interactive installations skip automatically. The
+post-install path uses the same authoritative-catalog transaction and never
+opts into `--purge-prefix`.
+
+## Common messages and errors
+
+| Message or error | Meaning | Recovery |
+|---|---|---|
+| `No AI agents detected` | No supported local agent directory was found | Install an agent or use an explicit `--path` |
+| `No skills found locally` | No valid local or refreshed Skill bundle is available | Install a complete package or retry refresh when the configured source is available |
+| `managed skill was modified` during uninstall | A previously managed Skill no longer matches its recorded digest | Normal uninstall preserves it; use a separately confirmed `--purge-prefix` only when broad deletion is intended |
+| `--path must not be empty` | An explicit path flag had no value | Supply the exact Skills directory |
+| `permission denied` | The target directory is not writable | Fix permissions or choose an authorized directory |
+| `copy ...: not a directory` | A regular file blocks a Skill directory name | Move the blocking file, then retry |
+
+Do not route these local filesystem failures to BytePlus authentication.
+
+`arkcli-managed-agent` is not a current installable Skill name. If an old
+manifest owns it, the next install retires it under the general catalog rule.
+Current BytePlus embedded, CDN, and GitHub bundles publish only `arkcli-agent`.