scalemax 0.1.38 → 0.1.39

package/README.md

@@ -1,382 +1,382 @@
-# ScaleMax CLI
-
-Universal installer for configuring AI coding clients to use the ScaleMax OpenAI- and Anthropic-compatible API gateway.
-
-ScaleMax CLI is designed to be run from any machine with Node.js installed:
-
-```bash
-npx scalemax
-```
-
-It detects supported AI coding clients, safely backs up existing config files, and writes ScaleMax-compatible configuration using your ScaleMax API key.
-
-## Requirements
-
-- Node.js `18.19` or newer
-- macOS, Linux, or Windows
-- A ScaleMax API key
-- Network access to `https://api.scalemax.pro`
-
-The CLI identifies whether the supplied key belongs to the API-credit surface or the token-pack surface. It then stores and configures the matching base URL automatically; users do not need to choose it manually.
-
-## Installation
-
-### One-time run with npx
-
-```bash
-npx scalemax
-```
-
-### Always use the latest published version
-
-```bash
-npx scalemax@latest
-```
-
-### Global install
-
-```bash
-npm install -g scalemax
-scalemax
-```
-
-## Quick Start
-
-```bash
-npx scalemax
-```
-
-If no ScaleMax configuration exists, the installer prompts:
-
-```text
-Enter your ScaleMax API key:
-```
-
-If configuration already exists, the installer preserves the existing flow:
-
-```text
-✓ Existing ScaleMax configuration detected.
-
-API key:
-••••••••••••••••abcd
-
-1. Keep existing key
-2. Replace with new key
-3. Remove configuration
-4. Exit
-```
-
-After authentication, ScaleMax CLI detects installed clients and lets you configure one client or all detected clients.
-
-## Commands
-
-```bash
-scalemax              Interactive installer
-scalemax login        Store or replace your ScaleMax API key
-scalemax logout       Remove stored ScaleMax API key
-scalemax doctor       Run diagnostics
-scalemax models       List available ScaleMax models
-scalemax helper-bot   Open the ScaleMax-only support assistant
-scalemax claude-tools Install bounded GitHub skill tools for Claude
-scalemax update       Reconfigure detected clients with the stored key
-scalemax remove       Remove ScaleMax-generated client configuration
-scalemax --help       Show help
-scalemax --version    Show installed version
-```
-
-## Authentication
-
-ScaleMax CLI stores your API key in a user-level configuration file:
-
-- macOS: `~/Library/Application Support/scalemax/config.json`
-- Linux: `$XDG_CONFIG_HOME/scalemax/config.json` or `~/.config/scalemax/config.json`
-- Windows: `%APPDATA%\scalemax\config.json`
-
-The file is written with private permissions where supported. The API key is never printed; existing keys are displayed only as a masked value such as `••••••••••••••••abcd`.
-
-For CI or non-interactive checks, you may provide the key through the environment:
-
-```bash
-SCALEMAX_API_KEY=sm_live_xxx scalemax models
-```
-
-## ScaleMax Helper Bot
-
-Start an interactive ScaleMax installation, configuration, authentication, and troubleshooting session:
-
-```bash
-npx scalemax@latest helper-bot
-```
-
-Or ask one small question and exit:
-
-```bash
-npx scalemax@latest helper-bot "Why is my ScaleMax API key rejected in Codex?"
-```
-
-The helper uses the same stored key as the installer, verifies authentication, and detects the API-credit or token-pack base URL automatically. General support questions default to `gpt-5.4` when that model is available to the key; each response is capped at 512 tokens and interactive history is bounded to the latest two turns. To choose a different model from `scalemax models`, use:
-
-```bash
-npx scalemax@latest helper-bot --model fable-5 "Help me configure ScaleMax in Cursor"
-```
-
-Recognized setup, repair, and verification requests execute the CLI's allowlisted client operations directly. Requests such as `setup all providers`, `fix Hermes request failed`, `configure Claude Code`, `verify OpenCode`, and `setup vs code roo extension for claude` are handled by the controller before any model request. The controller detects the relevant client, runs a safe installer when the client has one, verifies existing ScaleMax configuration, repairs ScaleMax-managed files when verification fails, re-verifies, and reports each step.
-
-For Claude tool access, run `scalemax claude-tools`, or ask helper-bot to `install GitHub skill tools for Claude Desktop and Claude Code`. Claude Code receives Anthropic's official `example-skills@anthropic-agent-skills` plugin plus public-GitHub read permissions. Claude Desktop/Cowork receives a local MCP server with only three tools: `github_fetch`, `github_tree`, and `github_install_skill`. The MCP server accepts only public GitHub HTTPS hosts, limits downloads, rejects unsafe archive paths and symlinks, refuses to replace an existing skill, and can write only beneath `~/Claude/skills`. It does not expose a general shell, arbitrary URLs, or unrestricted filesystem access. Restart Claude Desktop after installation and use Cowork or Code; a normal Chat tab does not expose local tools.
-Only install skills from repositories you trust: a `SKILL.md` is instruction content that Claude may follow after installation, even though the bridge itself cannot execute arbitrary repository code.
-
-For Roo Code, helper-bot can install VS Code on Windows with the fixed Microsoft winget package, install the official Roo Code extension, write OpenAI and Claude ScaleMax profiles when the key exposes those families, and verify the import handoff. For DeepSeek V4 Flash, helper-bot creates an agent profile only when authenticated discovery reports `capabilities.tools=true`; otherwise it installs Continue's safe Chat/Edit fallback. For general troubleshooting that cannot be completed by a fixed client action, helper-bot sends a small `gpt-5.4` request grounded with bundled ScaleMax documentation about stored authentication, credit/token base URLs, provider scope, client setup, and common errors. The language model never generates or executes shell commands; only fixed ScaleMax client detection, installation, configuration, verification, and rollback operations are available to the controller.
-
-The helper refuses unrelated requests and redacts ScaleMax-style secrets from prompts, provider output, errors, and progress notifications. Use `/status` for non-secret connection details, `/help` for commands, and `/quit` to exit.
-
-## Supported clients
-
-`scalemax` supports this client set whether it is run through a global install or with `npx`:
-
-- Codex
-- Cursor
-- Roo Code (VS Code)
-- Cline (CLI and VS Code)
-- Continue (VS Code)
-- TRAE SOLO
-- Claude Code
-- OpenCode
-- OpenClaw
-- Hermes
-- Cherry Studio
-- API Code
-
-For clients without a stable official config file, the installer writes a ScaleMax setup guide under `~/.scalemax/` instead of modifying private app storage.
-
-### Codex
-
-ScaleMax configures the official Codex custom-provider interface in `~/.codex/config.toml` with `wire_api = "responses"`, and stores the selected key in Codex's private `~/.codex/auth.json`. Detection is semantic: unrelated or ChatGPT-authenticated Codex files are not reported as ScaleMax-configured. Only authenticated Codex/OpenAI-family models are eligible, the generated files are private, and verification performs a minimal `/v1/responses` request before reporting success.
-
-### Claude Code
-
-ScaleMax updates `~/.claude/settings.json` with `ANTHROPIC_BASE_URL=https://api.scalemax.pro`, gateway model discovery, and a cached `apiKeyHelper` that reads a private `~/.claude/scalemax.key` file. The raw key is not stored in the settings JSON. Because Claude Code's gateway discovery only accepts IDs beginning with `claude` or `anthropic`, a catalog that includes Fable also receives a managed `ANTHROPIC_CUSTOM_MODEL_OPTION=fable-5` entry (with a friendly name and description), making `/model fable-5` selectable; any prior custom picker values are restored when ScaleMax configuration is removed. The Anthropic base URL intentionally has no `/v1` suffix because Claude Code adds `/v1/messages` itself. The CLI preserves unrelated settings, selects a live main model from the authenticated catalog (preferring `claude-opus-5`), pins authenticated Haiku for lightweight background work when available, and sets `CLAUDE_CODE_DISABLE_THINKING=1` because third-party Anthropic-compatible providers do not support Claude Code's proprietary extended-thinking control envelope. The ScaleMax gateway separately locks native Claude requests to provider-side `low` effort. Fable uses its verified translated controls and supports `low`, `medium`, `high`, and `max`, with `low` as the default. Haiku 4.5 omits the unsupported effort field. It verifies a one-token Messages request and, if verification fails, removes only the ScaleMax-managed changes. Claude Code picker aliases such as `claude-opus-5[1m]` are normalized by the gateway.
-
-### OpenCode
-
-ScaleMax merges a named `scalemax` provider into `~/.config/opencode/opencode.json` (or the platform-equivalent config directory). It uses `https://api.scalemax.pro/v1`, reads its credential from the private `~/.config/opencode/scalemax.key` file through OpenCode's `{file:...}` substitution, keeps unrelated providers and the user's non-ScaleMax default model, and exposes only authenticated Codex/OpenAI-family models. A fresh ScaleMax setup uses an authenticated GPT mini model as `small_model` when available. Each generated model has an explicit output limit of at most 4096 tokens so OpenCode does not send an unsupported default limit. Its `tool_call` flag is taken from the authenticated ScaleMax model catalog; run `scalemax update` after a catalog or client update so agent tools stay aligned with the current route.
-
-### OpenClaw
-
-ScaleMax partitions OpenClaw models into native `openai-responses` (`scalemax-codex`, `/v1`), OpenAI-compatible `openai-completions` (`scalemax-deepseek`, `/v1`), and `anthropic-messages` (`scalemax-claude`, origin) providers. `deepseek-v4-flash` is always isolated in the Chat Completions provider and never advertised through Responses. Its agent flags come only from authenticated catalog discovery: tools, forced `tool_choice`, reasoning, reasoning effort, streamed usage, and `reasoning_content` replay are each enabled only when the exact model advertises that capability. In particular, a tool-capable route is never forced to replay reasoning content unless `capabilities.reasoning_replay=true`; a fallback route remains explicitly tool-free. The API key and compatibility User-Agent are OpenClaw file-backed SecretRefs stored in private `0600` files under `~/.openclaw/secrets/`; neither value is embedded in the main provider JSON. Migration removes the obsolete mixed provider, preserves the active model family, and scrubs plaintext credentials from generated ScaleMax agent registries even when they contain an older key. Output is capped at 4096 tokens, private-network routing is denied for the public gateway, and unrelated providers and agent settings are preserved.
-
-### Hermes
-
-ScaleMax creates family-specific Hermes providers in `~/.hermes/config.yaml` and stores one credential in `~/.hermes/.env` with private permissions. `scalemax-codex` uses Hermes's `codex_responses` transport at `/v1`; `scalemax-claude` uses `anthropic_messages` at the gateway origin; and an authenticated tool-capable `deepseek-v4-flash` route receives a separate `scalemax-deepseek` Chat Completions provider. A text-only DeepSeek route fails closed for Hermes agent mode. All providers use a scoped `ScaleMax-Hermes/1.0` user agent and a 4096-token output cap. Existing non-ScaleMax providers and defaults are preserved, and the obsolete mixed provider is migrated safely.
-
-### Roo Code (VS Code)
-
-Roo Code stores provider profiles and secrets in VS Code extension storage, so ScaleMax does not mutate its private database. Instead, the CLI writes a private `0600` Roo settings-import file at `~/.scalemax/roo-code-import.json` and points the supported `roo-cline.autoImportSettingsPath` VS Code setting at it. Codex, Claude, and tool-capable DeepSeek profiles remain separate. DeepSeek is offered only when authenticated discovery reports `capabilities.tools=true`; otherwise Roo fails closed and points the user to Continue Chat/Edit. Reload VS Code once so Roo imports supported profiles into its SecretStorage. CLI verification intentionally reports the handoff as verified, not the extension runtime, until that reload occurs.
-
-### Cline (CLI and VS Code)
-
-ScaleMax supports the verified Cline CLI `3.0.47` and VS Code extension `4.0.12` formats. The CLI surface uses Cline's built-in `openai-native` provider and Responses protocol. The extension uses its built-in OpenAI-compatible provider. Both receive the raw ScaleMax key and the matching credit or token base URL; ScaleMax never writes a custom `Authorization` or `x-api-key` header because Cline generates `Authorization: Bearer …` itself. Configuration is attempted only while Cline and VS Code are stopped, preserves unrelated state, uses private atomic files with backups and rollback, and fails closed on unknown versions or malformed/symlinked state.
-
-### Continue (VS Code)
-
-Continue is the universal VS Code Chat/Edit route for `deepseek-v4-flash`. The CLI installs the official `Continue.continue` extension when VS Code is available, merges an OpenAI-compatible model into `~/.continue/config.yaml`, sets `useResponsesApi: false`, and keeps the authenticated ScaleMax key in private `~/.continue/.env` rather than the YAML. Existing Continue models and environment entries are preserved. Reload VS Code and select **ScaleMax DeepSeek V4 Flash**. For agent workflows, prefer Roo/OpenClaw/Hermes when the authenticated catalog reports `capabilities.tools=true`.
-
-### Cursor BYOK routing on macOS
-
-Cursor can send named models through its own plan-gated router unless its local BYOK runtime is active. When you select Cursor, `npx scalemax`:
-
-1. Fetches the complete authenticated model list from `https://api.scalemax.pro/v1/models`.
-2. Asks before closing Cursor and modifying the application.
-3. Verifies one known semantic patch anchor in each of three Cursor bundles before writing anything.
-4. Stores backups outside `Cursor.app`, records SHA-256 hashes, and rolls back all files if any step fails.
-5. Enables Cursor's local BYOK runtime without hard-coding GPT-5.5.
-6. Stores the ScaleMax key in Cursor's native macOS protected-secret format and sets `useOpenAIKey=true` with `openAIBaseUrl=https://api.scalemax.pro/v1`.
-7. Synchronizes every live ScaleMax model into Cursor's local-provider catalog while preserving the user's currently selected model.
-
-Automatic Cursor patching is currently verified on macOS only. Unknown, partial, or changed Cursor bundle signatures fail closed without modifying the app. Cursor updates can replace the patched bundles; rerun `npx scalemax@latest` after an update. `scalemax remove` restores only bundle versions and protected-state values managed by ScaleMax, and refuses to overwrite files changed afterward.
-
-For explicitly approved non-interactive automation, set `SCALEMAX_CURSOR_PATCH_CONSENT=1`. Without it, non-interactive Cursor modification is skipped safely.
-
-## Examples
-
-List models:
-
-```bash
-npx scalemax models
-```
-
-The model list is fetched live from `https://api.scalemax.pro/v1/models` every time, so disabled or unsupported models disappear immediately without manual cache cleanup.
-The CLI authenticates the key before loading its model catalog. Safe GET checks receive one short, jittered retry on transient network, rate-limit, or server failures; model-generation POST requests are never retried by the installer. CLI requests honor `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` and automatically try the usable IPv4 or IPv6 route.
-
-Run diagnostics:
-
-```bash
-npx scalemax doctor
-```
-
-Configure all detected clients after login:
-
-```bash
-npx scalemax update
-```
-
-Remove ScaleMax-generated client config and restore backups when available:
-
-```bash
-npx scalemax remove
-```
-
-## Updating
-
-With npx:
-
-```bash
-npx scalemax@latest
-```
-
-With a global install:
-
-```bash
-npm update -g scalemax
-# or
-npm install -g scalemax@latest
-```
-
-## Removing configuration
-
-Remove only the stored ScaleMax API key:
-
-```bash
-scalemax logout
-```
-
-Remove ScaleMax-generated client configuration files and restore backups when possible:
-
-```bash
-scalemax remove
-```
-
-## Troubleshooting
-
-### `No ScaleMax API key found`
-
-Run:
-
-```bash
-scalemax login
-```
-
-### `API check failed: HTTP 401`
-
-Your key is missing, expired, inactive, or mistyped. Run:
-
-```bash
-scalemax login
-```
-
-Then paste a valid ScaleMax API key.
-
-### `npx` runs an old version
-
-Force latest:
-
-```bash
-npx scalemax@latest
-```
-
-Or clear the npm cache:
-
-```bash
-npm cache verify
-```
-
-### `Could not reach the ScaleMax API`
-
-Use the latest CLI first:
-
-```bash
-npx scalemax@latest
-```
-
-ScaleMax automatically honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`
-when a workplace or ISP requires an outbound proxy. It also falls back between
-IPv4 and IPv6. If the error specifically reports DNS or TLS, correct the
-device DNS/system clock or disable HTTPS inspection for `api.scalemax.pro`,
-then rerun the command. Never disable TLS verification.
-
-### Client config looks wrong
-
-Run:
-
-```bash
-scalemax doctor
-```
-
-Then reconfigure:
-
-```bash
-scalemax update
-```
-
-### Remove and start over
-
-```bash
-scalemax remove
-scalemax logout
-npx scalemax@latest
-```
-
-## Release process for maintainers
-
-See `RELEASE.md` in the repository. In short:
-
-```bash
-npm run version:patch   # or version:minor / version:major
-npm run prepublishOnly
-npm publish
-```
-
-Never publish over an existing npm version. Use semantic versioning for every release.
-
-## Safety guarantees
-
-- Existing client configuration files are backed up before writes.
-- Writes are atomic.
-- Identical configurations are not rewritten or backed up again.
-- Invalid JSON/JSON5 client files fail closed instead of being replaced; valid JSON5 values are merged safely.
-- Backup directories are user-only and backup files are written with private permissions.
-- API keys are masked in terminal output.
-- Codex, Claude Code, OpenCode, OpenClaw, Hermes, and the Roo Code import handoff keep generated client credentials in private files rather than shared provider configuration blocks.
-- The published npm package contains only runtime files: `dist/`, `README.md`, `LICENSE`, and `package.json`.
-- Tests, TypeScript source, scripts, local caches, `.env` files, tarballs, and `node_modules` are excluded from the published package.
-
-## FAQ
-
-### Does `npx scalemax` install anything permanently?
-
-`npx` downloads and runs the CLI package. The CLI itself writes ScaleMax configuration only after you choose to configure clients.
-
-### Can I use it without global install?
-
-Yes. Use:
-
-```bash
-npx scalemax@latest
-```
-
-### Can I use a different API key later?
-
-Yes. Run:
-
-```bash
-scalemax login
-```
-
-or rerun the installer and choose `Replace with a new key`.
-
-### Does it support Windows?
-
-Yes. The CLI uses Windows-aware config paths and writes `%APPDATA%\scalemax\config.json` for ScaleMax key storage.
-
-### What endpoint does it configure?
-
-API-credit keys use `https://api.scalemax.pro/v1` for OpenAI-compatible clients and `https://api.scalemax.pro` for Anthropic-compatible clients. Token-pack keys use `https://api.scalemax.pro/token/v1` and `https://api.scalemax.pro/token` respectively. The CLI detects the key type and configures the correct surface automatically; the two key types are intentionally not interchangeable.
+# ScaleMax CLI
+
+Universal installer for configuring AI coding clients to use the ScaleMax OpenAI- and Anthropic-compatible API gateway.
+
+ScaleMax CLI is designed to be run from any machine with Node.js installed:
+
+```bash
+npx scalemax
+```
+
+It detects supported AI coding clients, safely backs up existing config files, and writes ScaleMax-compatible configuration using your ScaleMax API key.
+
+## Requirements
+
+- Node.js `18.19` or newer
+- macOS, Linux, or Windows
+- A ScaleMax API key
+- Network access to `https://api.scalemax.pro`
+
+The CLI identifies whether the supplied key belongs to the API-credit surface or the token-pack surface. It then stores and configures the matching base URL automatically; users do not need to choose it manually.
+
+## Installation
+
+### One-time run with npx
+
+```bash
+npx scalemax
+```
+
+### Always use the latest published version
+
+```bash
+npx scalemax@latest
+```
+
+### Global install
+
+```bash
+npm install -g scalemax
+scalemax
+```
+
+## Quick Start
+
+```bash
+npx scalemax
+```
+
+If no ScaleMax configuration exists, the installer prompts:
+
+```text
+Enter your ScaleMax API key:
+```
+
+If configuration already exists, the installer preserves the existing flow:
+
+```text
+✓ Existing ScaleMax configuration detected.
+
+API key:
+••••••••••••••••abcd
+
+1. Keep existing key
+2. Replace with new key
+3. Remove configuration
+4. Exit
+```
+
+After authentication, ScaleMax CLI detects installed clients and lets you configure one client or all detected clients.
+
+## Commands
+
+```bash
+scalemax              Interactive installer
+scalemax login        Store or replace your ScaleMax API key
+scalemax logout       Remove stored ScaleMax API key
+scalemax doctor       Run diagnostics
+scalemax models       List available ScaleMax models
+scalemax helper-bot   Open the ScaleMax-only support assistant
+scalemax claude-tools Install bounded GitHub skill tools for Claude
+scalemax update       Reconfigure detected clients with the stored key
+scalemax remove       Remove ScaleMax-generated client configuration
+scalemax --help       Show help
+scalemax --version    Show installed version
+```
+
+## Authentication
+
+ScaleMax CLI stores your API key in a user-level configuration file:
+
+- macOS: `~/Library/Application Support/scalemax/config.json`
+- Linux: `$XDG_CONFIG_HOME/scalemax/config.json` or `~/.config/scalemax/config.json`
+- Windows: `%APPDATA%\scalemax\config.json`
+
+The file is written with private permissions where supported. The API key is never printed; existing keys are displayed only as a masked value such as `••••••••••••••••abcd`.
+
+For CI or non-interactive checks, you may provide the key through the environment:
+
+```bash
+SCALEMAX_API_KEY=sm_live_xxx scalemax models
+```
+
+## ScaleMax Helper Bot
+
+Start an interactive ScaleMax installation, configuration, authentication, and troubleshooting session:
+
+```bash
+npx scalemax@latest helper-bot
+```
+
+Or ask one small question and exit:
+
+```bash
+npx scalemax@latest helper-bot "Why is my ScaleMax API key rejected in Codex?"
+```
+
+The helper uses the same stored key as the installer, verifies authentication, and detects the API-credit or token-pack base URL automatically. General support questions default to `gpt-5.4` when that model is available to the key; each response is capped at 512 tokens and interactive history is bounded to the latest two turns. To choose a different model from `scalemax models`, use:
+
+```bash
+npx scalemax@latest helper-bot --model fable-5 "Help me configure ScaleMax in Cursor"
+```
+
+Recognized setup, repair, and verification requests execute the CLI's allowlisted client operations directly. Requests such as `setup all providers`, `fix Hermes request failed`, `configure Claude Code`, `verify OpenCode`, and `setup vs code roo extension for claude` are handled by the controller before any model request. The controller detects the relevant client, runs a safe installer when the client has one, verifies existing ScaleMax configuration, repairs ScaleMax-managed files when verification fails, re-verifies, and reports each step.
+
+For Claude tool access, run `scalemax claude-tools`, or ask helper-bot to `install GitHub skill tools for Claude Desktop and Claude Code`. Claude Code receives Anthropic's official `example-skills@anthropic-agent-skills` plugin plus public-GitHub read permissions. Claude Desktop/Cowork receives a local MCP server with only three tools: `github_fetch`, `github_tree`, and `github_install_skill`. The MCP server accepts only public GitHub HTTPS hosts, limits downloads, rejects unsafe archive paths and symlinks, refuses to replace an existing skill, and can write only beneath `~/Claude/skills`. It does not expose a general shell, arbitrary URLs, or unrestricted filesystem access. Restart Claude Desktop after installation and use Cowork or Code; a normal Chat tab does not expose local tools.
+Only install skills from repositories you trust: a `SKILL.md` is instruction content that Claude may follow after installation, even though the bridge itself cannot execute arbitrary repository code.
+
+For Roo Code, helper-bot can install VS Code on Windows with the fixed Microsoft winget package, install the official Roo Code extension, write OpenAI and Claude ScaleMax profiles when the key exposes those families, and verify the import handoff. For DeepSeek V4 Flash, helper-bot creates an agent profile only when authenticated discovery reports `capabilities.tools=true`; otherwise it installs Continue's safe Chat/Edit fallback. For general troubleshooting that cannot be completed by a fixed client action, helper-bot sends a small `gpt-5.4` request grounded with bundled ScaleMax documentation about stored authentication, credit/token base URLs, provider scope, client setup, and common errors. The language model never generates or executes shell commands; only fixed ScaleMax client detection, installation, configuration, verification, and rollback operations are available to the controller.
+
+The helper refuses unrelated requests and redacts ScaleMax-style secrets from prompts, provider output, errors, and progress notifications. Use `/status` for non-secret connection details, `/help` for commands, and `/quit` to exit.
+
+## Supported clients
+
+`scalemax` supports this client set whether it is run through a global install or with `npx`:
+
+- Codex
+- Cursor
+- Roo Code (VS Code)
+- Cline (CLI and VS Code)
+- Continue (VS Code)
+- TRAE SOLO
+- Claude Code
+- OpenCode
+- OpenClaw
+- Hermes
+- Cherry Studio
+- API Code
+
+For clients without a stable official config file, the installer writes a ScaleMax setup guide under `~/.scalemax/` instead of modifying private app storage.
+
+### Codex
+
+ScaleMax configures the official Codex custom-provider interface in `~/.codex/config.toml` with `wire_api = "responses"`, and stores the selected key in Codex's private `~/.codex/auth.json`. Detection is semantic: unrelated or ChatGPT-authenticated Codex files are not reported as ScaleMax-configured. Only authenticated Codex/OpenAI-family models are eligible, the generated files are private, and verification performs a minimal `/v1/responses` request before reporting success.
+
+### Claude Code
+
+ScaleMax updates `~/.claude/settings.json` with `ANTHROPIC_BASE_URL=https://api.scalemax.pro`, gateway model discovery, and a cached `apiKeyHelper` that reads a private `~/.claude/scalemax.key` file. The raw key is not stored in the settings JSON. Because Claude Code's gateway discovery only accepts IDs beginning with `claude` or `anthropic`, catalogs that include Fable or Auto also receive a managed custom picker entry (`ANTHROPIC_CUSTOM_MODEL_OPTION=fable-5` or `auto`, with friendly names and descriptions), making `/model fable-5` and `/model auto` selectable; any prior custom picker values are restored when ScaleMax configuration is removed. The Anthropic base URL intentionally has no `/v1` suffix because Claude Code adds `/v1/messages` itself. The CLI preserves unrelated settings, selects a live main model from the authenticated catalog (preferring `claude-opus-5`), pins authenticated Haiku for lightweight background work when available, and sets `CLAUDE_CODE_DISABLE_THINKING=1` because third-party Anthropic-compatible providers do not support Claude Code's proprietary extended-thinking control envelope. The ScaleMax gateway separately locks native Claude requests to provider-side `low` effort. Fable uses its verified translated controls and supports `low`, `medium`, `high`, and `max`, with `low` as the default. Haiku 4.5 omits the unsupported effort field. It verifies a one-token Messages request and, if verification fails, removes only the ScaleMax-managed changes. Claude Code picker aliases such as `claude-opus-5[1m]` are normalized by the gateway.
+
+### OpenCode
+
+ScaleMax merges a named `scalemax` provider into `~/.config/opencode/opencode.json` (or the platform-equivalent config directory). It uses `https://api.scalemax.pro/v1`, reads its credential from the private `~/.config/opencode/scalemax.key` file through OpenCode's `{file:...}` substitution, keeps unrelated providers and the user's non-ScaleMax default model, and exposes only authenticated Codex/OpenAI-family models. A fresh ScaleMax setup uses an authenticated GPT mini model as `small_model` when available. Each generated model has an explicit output limit of at most 4096 tokens so OpenCode does not send an unsupported default limit. Its `tool_call` flag is taken from the authenticated ScaleMax model catalog; run `scalemax update` after a catalog or client update so agent tools stay aligned with the current route.
+
+### OpenClaw
+
+ScaleMax partitions OpenClaw models into native `openai-responses` (`scalemax-codex`, `/v1`), OpenAI-compatible `openai-completions` (`scalemax-deepseek`, `/v1`), and `anthropic-messages` (`scalemax-claude`, origin) providers. `deepseek-v4-flash` is always isolated in the Chat Completions provider and never advertised through Responses. Its agent flags come only from authenticated catalog discovery: tools, forced `tool_choice`, reasoning, reasoning effort, streamed usage, and `reasoning_content` replay are each enabled only when the exact model advertises that capability. In particular, a tool-capable route is never forced to replay reasoning content unless `capabilities.reasoning_replay=true`; a fallback route remains explicitly tool-free. The API key and compatibility User-Agent are OpenClaw file-backed SecretRefs stored in private `0600` files under `~/.openclaw/secrets/`; neither value is embedded in the main provider JSON. Migration removes the obsolete mixed provider, preserves the active model family, and scrubs plaintext credentials from generated ScaleMax agent registries even when they contain an older key. Output is capped at 4096 tokens, private-network routing is denied for the public gateway, and unrelated providers and agent settings are preserved.
+
+### Hermes
+
+ScaleMax creates family-specific Hermes providers in `~/.hermes/config.yaml` and stores one credential in `~/.hermes/.env` with private permissions. `scalemax-codex` uses Hermes's `codex_responses` transport at `/v1`; `scalemax-claude` uses `anthropic_messages` at the gateway origin; and an authenticated tool-capable `deepseek-v4-flash` route receives a separate `scalemax-deepseek` Chat Completions provider. A text-only DeepSeek route fails closed for Hermes agent mode. All providers use a scoped `ScaleMax-Hermes/1.0` user agent and a 4096-token output cap. Existing non-ScaleMax providers and defaults are preserved, and the obsolete mixed provider is migrated safely.
+
+### Roo Code (VS Code)
+
+Roo Code stores provider profiles and secrets in VS Code extension storage, so ScaleMax does not mutate its private database. Instead, the CLI writes a private `0600` Roo settings-import file at `~/.scalemax/roo-code-import.json` and points the supported `roo-cline.autoImportSettingsPath` VS Code setting at it. Codex, Claude, and tool-capable DeepSeek profiles remain separate. DeepSeek is offered only when authenticated discovery reports `capabilities.tools=true`; otherwise Roo fails closed and points the user to Continue Chat/Edit. Reload VS Code once so Roo imports supported profiles into its SecretStorage. CLI verification intentionally reports the handoff as verified, not the extension runtime, until that reload occurs.
+
+### Cline (CLI and VS Code)
+
+ScaleMax supports the verified Cline CLI `3.0.47` and VS Code extension `4.0.12` formats. The CLI surface uses Cline's built-in `openai-native` provider and Responses protocol. The extension uses its built-in OpenAI-compatible provider. Both receive the raw ScaleMax key and the matching credit or token base URL; ScaleMax never writes a custom `Authorization` or `x-api-key` header because Cline generates `Authorization: Bearer …` itself. Configuration is attempted only while Cline and VS Code are stopped, preserves unrelated state, uses private atomic files with backups and rollback, and fails closed on unknown versions or malformed/symlinked state.
+
+### Continue (VS Code)
+
+Continue is the universal VS Code Chat/Edit route for `deepseek-v4-flash`. The CLI installs the official `Continue.continue` extension when VS Code is available, merges an OpenAI-compatible model into `~/.continue/config.yaml`, sets `useResponsesApi: false`, and keeps the authenticated ScaleMax key in private `~/.continue/.env` rather than the YAML. Existing Continue models and environment entries are preserved. Reload VS Code and select **ScaleMax DeepSeek V4 Flash**. For agent workflows, prefer Roo/OpenClaw/Hermes when the authenticated catalog reports `capabilities.tools=true`.
+
+### Cursor BYOK routing on macOS
+
+Cursor can send named models through its own plan-gated router unless its local BYOK runtime is active. When you select Cursor, `npx scalemax`:
+
+1. Fetches the complete authenticated model list from `https://api.scalemax.pro/v1/models`.
+2. Asks before closing Cursor and modifying the application.
+3. Verifies one known semantic patch anchor in each of three Cursor bundles before writing anything.
+4. Stores backups outside `Cursor.app`, records SHA-256 hashes, and rolls back all files if any step fails.
+5. Enables Cursor's local BYOK runtime without hard-coding GPT-5.5.
+6. Stores the ScaleMax key in Cursor's native macOS protected-secret format and sets `useOpenAIKey=true` with `openAIBaseUrl=https://api.scalemax.pro/v1`.
+7. Synchronizes every live ScaleMax model into Cursor's local-provider catalog while preserving the user's currently selected model.
+
+Automatic Cursor patching is currently verified on macOS only. Unknown, partial, or changed Cursor bundle signatures fail closed without modifying the app. Cursor updates can replace the patched bundles; rerun `npx scalemax@latest` after an update. `scalemax remove` restores only bundle versions and protected-state values managed by ScaleMax, and refuses to overwrite files changed afterward.
+
+For explicitly approved non-interactive automation, set `SCALEMAX_CURSOR_PATCH_CONSENT=1`. Without it, non-interactive Cursor modification is skipped safely.
+
+## Examples
+
+List models:
+
+```bash
+npx scalemax models
+```
+
+The model list is fetched live from `https://api.scalemax.pro/v1/models` every time, so disabled or unsupported models disappear immediately without manual cache cleanup.
+The CLI authenticates the key before loading its model catalog. Safe GET checks receive one short, jittered retry on transient network, rate-limit, or server failures; model-generation POST requests are never retried by the installer. CLI requests honor `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` and automatically try the usable IPv4 or IPv6 route.
+
+Run diagnostics:
+
+```bash
+npx scalemax doctor
+```
+
+Configure all detected clients after login:
+
+```bash
+npx scalemax update
+```
+
+Remove ScaleMax-generated client config and restore backups when available:
+
+```bash
+npx scalemax remove
+```
+
+## Updating
+
+With npx:
+
+```bash
+npx scalemax@latest
+```
+
+With a global install:
+
+```bash
+npm update -g scalemax
+# or
+npm install -g scalemax@latest
+```
+
+## Removing configuration
+
+Remove only the stored ScaleMax API key:
+
+```bash
+scalemax logout
+```
+
+Remove ScaleMax-generated client configuration files and restore backups when possible:
+
+```bash
+scalemax remove
+```
+
+## Troubleshooting
+
+### `No ScaleMax API key found`
+
+Run:
+
+```bash
+scalemax login
+```
+
+### `API check failed: HTTP 401`
+
+Your key is missing, expired, inactive, or mistyped. Run:
+
+```bash
+scalemax login
+```
+
+Then paste a valid ScaleMax API key.
+
+### `npx` runs an old version
+
+Force latest:
+
+```bash
+npx scalemax@latest
+```
+
+Or clear the npm cache:
+
+```bash
+npm cache verify
+```
+
+### `Could not reach the ScaleMax API`
+
+Use the latest CLI first:
+
+```bash
+npx scalemax@latest
+```
+
+ScaleMax automatically honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`
+when a workplace or ISP requires an outbound proxy. It also falls back between
+IPv4 and IPv6. If the error specifically reports DNS or TLS, correct the
+device DNS/system clock or disable HTTPS inspection for `api.scalemax.pro`,
+then rerun the command. Never disable TLS verification.
+
+### Client config looks wrong
+
+Run:
+
+```bash
+scalemax doctor
+```
+
+Then reconfigure:
+
+```bash
+scalemax update
+```
+
+### Remove and start over
+
+```bash
+scalemax remove
+scalemax logout
+npx scalemax@latest
+```
+
+## Release process for maintainers
+
+See `RELEASE.md` in the repository. In short:
+
+```bash
+npm run version:patch   # or version:minor / version:major
+npm run prepublishOnly
+npm publish
+```
+
+Never publish over an existing npm version. Use semantic versioning for every release.
+
+## Safety guarantees
+
+- Existing client configuration files are backed up before writes.
+- Writes are atomic.
+- Identical configurations are not rewritten or backed up again.
+- Invalid JSON/JSON5 client files fail closed instead of being replaced; valid JSON5 values are merged safely.
+- Backup directories are user-only and backup files are written with private permissions.
+- API keys are masked in terminal output.
+- Codex, Claude Code, OpenCode, OpenClaw, Hermes, and the Roo Code import handoff keep generated client credentials in private files rather than shared provider configuration blocks.
+- The published npm package contains only runtime files: `dist/`, `README.md`, `LICENSE`, and `package.json`.
+- Tests, TypeScript source, scripts, local caches, `.env` files, tarballs, and `node_modules` are excluded from the published package.
+
+## FAQ
+
+### Does `npx scalemax` install anything permanently?
+
+`npx` downloads and runs the CLI package. The CLI itself writes ScaleMax configuration only after you choose to configure clients.
+
+### Can I use it without global install?
+
+Yes. Use:
+
+```bash
+npx scalemax@latest
+```
+
+### Can I use a different API key later?
+
+Yes. Run:
+
+```bash
+scalemax login
+```
+
+or rerun the installer and choose `Replace with a new key`.
+
+### Does it support Windows?
+
+Yes. The CLI uses Windows-aware config paths and writes `%APPDATA%\scalemax\config.json` for ScaleMax key storage.
+
+### What endpoint does it configure?
+
+API-credit keys use `https://api.scalemax.pro/v1` for OpenAI-compatible clients and `https://api.scalemax.pro` for Anthropic-compatible clients. Token-pack keys use `https://api.scalemax.pro/token/v1` and `https://api.scalemax.pro/token` respectively. The CLI detects the key type and configures the correct surface automatically; the two key types are intentionally not interchangeable.