apex-code 0.5.0 → 0.5.2

package/docs/providers.md

@@ -1,154 +1,98 @@
-# Providers
+# Provider Authentication
 
 Apex Code supports subscription-based providers via OAuth and API key providers via environment variables or auth file. Built-in catalogs ship with Apex Code; configured providers may refresh newer catalogs and cache them in `~/.apex-code/agent/models-store.json` for offline use.
 
-## Table of Contents
+- Sign in through a browser or device flow backed by OAuth.
+- Provide an API key.
 
-- [Subscriptions](#subscriptions)
-- [API Keys](#api-keys)
-- [Auth File](#auth-file)
-- [Cloud Providers](#cloud-providers)
-- [llama.cpp](#llamacpp)
-- [Custom Providers](#custom-providers)
-- [Resolution Order](#resolution-order)
+Use `/login [provider]` to see the methods supported by a provider. Amazon Bedrock and Google Vertex AI can also use ambient cloud credentials.
 
-## Subscriptions
+## Authenticate interactively
 
-Use `/login` in interactive mode, then select a provider:
+Run `/login` and select a provider. Pi guides you through its OAuth or API-key flow and saves the resulting credential in [`auth.json`](configuration.md#agent-directory).
 
-- ChatGPT Plus/Pro (Codex)
-- Claude Pro/Max
-- GitHub Copilot
-- xAI (Grok/X subscription)
-- OpenRouter (OAuth-minted API key billed from OpenRouter credits)
-- Radius
+On a remote or headless machine, an OAuth callback may not reach the local process. When prompted, paste the final redirect URL or authorization code back into Pi.
 
 Use `/logout` to clear credentials. Tokens are stored in `~/.apex-code/agent/auth.json` and auto-refresh when expired. OpenRouter instead mints a user-controlled API key that does not expire automatically.
 
-### OpenAI Codex
+`auth.json` can contain API keys and OAuth tokens. Keep it private and do not commit it.
 
-- Requires ChatGPT Plus or Pro subscription
-- Officially endorsed by OpenAI: [Codex for OSS](https://developers.openai.com/community/codex-for-oss)
+Radius authentication uses its gateway catalog and caches refreshed model metadata for later offline startup. A custom Radius gateway configured in `models.json` uses its own catalog rather than inheriting the public `radius.pi.dev` catalog.
 
-### Claude Pro/Max
+## Use an API key from the environment
 
-Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party harness usage draws from [extra usage](https://claude.ai/settings/usage) and is billed per token, not against Claude plan limits.
-
-### GitHub Copilot
-
-- Press Enter for github.com, or enter your GitHub Enterprise Server domain
-- If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
-
-### xAI (Grok/X subscription)
-
-- Run `/login xai`, then select **Use a subscription**
-- `XAI_API_KEY` remains available through **Use an API key**
-
-### OpenRouter
-
-- Run `/login openrouter`, then select **Sign in with OpenRouter** to open the OpenRouter PKCE authorization flow
-- The authorization creates a user-controlled OpenRouter API key billed from your OpenRouter credits
-- On remote/headless machines (e.g. over SSH) the browser cannot reach the loopback callback; paste the final redirect URL (or the authorization code) into the login prompt instead
-- `OPENROUTER_API_KEY` remains available through **Use an API key**
-
-### Radius
-
-Radius is a dynamic `pi-messages` gateway. `/login radius` stores OAuth tokens in `auth.json`; the gateway catalog is refreshed independently and cached in `models-store.json`. Custom Radius gateways can be declared in `models.json` with `"oauth": "radius"` and a gateway `baseUrl`.
-
-## API Keys
-
-### Environment Variables or Auth File
-
-Use `/login` in interactive mode and select a provider to store an API key in `auth.json`, or set credentials via environment variable:
+Environment variables are useful in CI and anywhere Pi should not store the key. Set the variable before starting Pi:
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
 apex-code
 ```
 
-| Provider | Environment Variable | `auth.json` key |
-|----------|----------------------|------------------|
-| Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
-| Ant Ling | `ANT_LING_API_KEY` | `ant-ling` |
-| Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
-| OpenAI | `OPENAI_API_KEY` | `openai` |
-| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
-| NVIDIA NIM | `NVIDIA_API_KEY` | `nvidia` |
-| Google Gemini | `GEMINI_API_KEY` | `google` |
-| Amazon Bedrock | `AWS_BEARER_TOKEN_BEDROCK` | `amazon-bedrock` |
-| Mistral | `MISTRAL_API_KEY` | `mistral` |
-| Groq | `GROQ_API_KEY` | `groq` |
-| Cerebras | `CEREBRAS_API_KEY` | `cerebras` |
-| Cloudflare AI Gateway | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_GATEWAY_ID`) | `cloudflare-ai-gateway` |
-| Cloudflare Workers AI | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`) | `cloudflare-workers-ai` |
-| xAI | `XAI_API_KEY` | `xai` |
-| OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
-| Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
-| ZAI Coding Plan (Global) | `ZAI_API_KEY` | `zai` |
-| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` | `zai-coding-cn` |
-| OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
-| OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
-| Radius | `RADIUS_API_KEY` | `radius` |
-| Hugging Face | `HF_TOKEN` | `huggingface` |
-| Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
-| Together AI | `TOGETHER_API_KEY` | `together` |
-| Baseten | `BASETEN_API_KEY` | `baseten` |
-| Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
-| MiniMax | `MINIMAX_API_KEY` | `minimax` |
-| MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
-| Qwen Token Plan (existing catalog) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan` |
-| Qwen Token Plan (Individual) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan-individual` |
-| Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` | `qwen-token-plan-cn` |
-| Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
-| Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` | `xiaomi-token-plan-cn` |
-| Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` | `xiaomi-token-plan-ams` |
-| Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` | `xiaomi-token-plan-sgp` |
-
-Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/env-api-keys.ts).
-
-#### Auth File
+This table covers providers with a single primary API-key variable. Providers that need additional configuration or support ambient credentials are covered under [Cloud providers](#cloud-providers).
+
+| Provider | Environment variable |
+|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` |
+| Ant Ling | `ANT_LING_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| NVIDIA NIM | `NVIDIA_API_KEY` |
+| Google Gemini | `GEMINI_API_KEY` |
+| GitHub Copilot | `COPILOT_GITHUB_TOKEN` |
+| Mistral | `MISTRAL_API_KEY` |
+| Groq | `GROQ_API_KEY` |
+| Cerebras | `CEREBRAS_API_KEY` |
+| xAI | `XAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
+| ZAI Coding Plan (Global) | `ZAI_API_KEY` |
+| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` |
+| OpenCode Zen and Go | `OPENCODE_API_KEY` |
+| Radius | `RADIUS_API_KEY` |
+| Hugging Face | `HF_TOKEN` |
+| Fireworks | `FIREWORKS_API_KEY` |
+| Together AI | `TOGETHER_API_KEY` |
+| Baseten | `BASETEN_API_KEY` |
+| Kimi For Coding | `KIMI_API_KEY` |
+| Meta | `META_API_KEY` |
+| MiniMax | `MINIMAX_API_KEY` |
+| MiniMax (China) | `MINIMAX_CN_API_KEY` |
+| Moonshot AI (Global and China) | `MOONSHOT_API_KEY` |
+| Qwen Token Plan and Individual | `QWEN_TOKEN_PLAN_API_KEY` |
+| Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` |
+| Xiaomi MiMo | `XIAOMI_API_KEY` |
+| Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` |
+| Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` |
+| Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` |
+
+Anthropic also recognizes `ANTHROPIC_OAUTH_TOKEN` as an API credential and `ANTHROPIC_AUTH_TOKEN` as bearer authentication.
 
 Store credentials in `~/.apex-code/agent/auth.json`:
 
 ```json
 {
-  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
-  "ant-ling": { "type": "api_key", "key": "..." },
-  "openai": { "type": "api_key", "key": "sk-..." },
-  "deepseek": { "type": "api_key", "key": "sk-..." },
-  "nvidia": { "type": "api_key", "key": "nvapi-..." },
-  "google": { "type": "api_key", "key": "..." },
-  "opencode": { "type": "api_key", "key": "..." },
-  "opencode-go": { "type": "api_key", "key": "..." },
-  "together": { "type": "api_key", "key": "..." },
-  "qwen-token-plan":  { "type": "api_key", "key": "sk-sp-..." },
-  "qwen-token-plan-individual": { "type": "api_key", "key": "sk-sp-..." },
-  "qwen-token-plan-cn": { "type": "api_key", "key": "sk-sp-..." },
-  "xiaomi": { "type": "api_key", "key": "..." },
-  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
-  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
-  "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." }
+  "anthropic": {
+    "type": "api_key",
+    "key": "!security find-generic-password -ws 'anthropic'"
+  }
 }
 ```
 
-`qwen-token-plan-individual` uses the same international endpoint and `QWEN_TOKEN_PLAN_API_KEY` as
-`qwen-token-plan`, but limits the picker to the models documented for Individual subscriptions. The existing
-provider keeps its broader catalog for backward compatibility. When using `auth.json`, store the
-credential under the provider you select; an environment variable is shared by both international providers.
+Pi runs the command when the key is first needed and caches its standard output for the process lifetime. Empty output, a timeout, or a nonzero exit leaves the key unresolved until Pi restarts.
 
-The file is created with `0600` permissions (user read/write only). Auth file credentials take priority over environment variables.
+## Cloud Providers
+
+The providers below need additional settings or can use credentials supplied by their cloud platform.
 
-API key credentials can also include provider-scoped environment values. These values are used before process environment variables when resolving the credential key, provider/model headers, and provider configuration such as Cloudflare account IDs, Azure OpenAI settings, Vertex project/location, Bedrock settings, `PI_CACHE_RETENTION`, and `HTTP_PROXY`/`HTTPS_PROXY`.
+A stored API-key credential can include an `env` object. Its values take priority over the process environment for that provider:
 
 ```json
 {
-  "cloudflare-ai-gateway": {
+  "cloudflare-workers-ai": {
     "type": "api_key",
-    "key": "$CLOUDFLARE_API_KEY",
+    "key": "...",
     "env": {
-      "CLOUDFLARE_API_KEY": "...",
-      "CLOUDFLARE_ACCOUNT_ID": "account-id",
-      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
+      "CLOUDFLARE_ACCOUNT_ID": "account-id"
     }
   }
 }
@@ -188,37 +132,37 @@ OAuth credentials are also stored here after `/login` and managed automatically.
 
 ### Azure OpenAI
 
+Set an API key plus either a base URL or resource name:
+
 ```bash
 export AZURE_OPENAI_API_KEY=...
 export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
-# also supported: https://your-resource.cognitiveservices.azure.com
-# also supported: https://your-resource.openai.azure.com
-# root endpoints are auto-normalized to /openai/v1
-# or use resource name instead of base URL
+# Or:
 export AZURE_OPENAI_RESOURCE_NAME=your-resource
-
-# Optional
-export AZURE_OPENAI_API_VERSION=2024-02-01
-export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o
 ```
 
+Resource root URLs under `ai.azure.com`, `cognitiveservices.azure.com`, and `openai.azure.com` are normalized to the OpenAI API path.
+
 ### Amazon Bedrock
 
-Use `/login amazon-bedrock` to store a Bedrock API key, or configure one of the ambient AWS credential sources below:
+Bedrock can use a bearer token or an ambient AWS credential source:
 
 ```bash
-# Option 1: AWS Profile
+# Named profile
 export AWS_PROFILE=your-profile
 
-# Option 2: IAM Keys
+# IAM keys
 export AWS_ACCESS_KEY_ID=AKIA...
 export AWS_SECRET_ACCESS_KEY=...
+# Required for temporary credentials
+export AWS_SESSION_TOKEN=...
 
-# Option 3: Bearer Token
+# Bedrock bearer token
 export AWS_BEARER_TOKEN_BEDROCK=...
 
-# Optional region (defaults to us-east-1)
+# Region, when not supplied by the profile or AWS SDK configuration
 export AWS_REGION=us-west-2
+# AWS_DEFAULT_REGION is also supported
 ```
 
 Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`).
@@ -249,16 +193,16 @@ export AWS_BEDROCK_FORCE_HTTP1=1
 
 ### Cloudflare AI Gateway
 
-`CLOUDFLARE_API_KEY` can be set via `/login`. The account ID and gateway slug can be set as environment variables or in the API key credential's `env` object in `auth.json`.
+The gateway requires a token, account ID, and gateway ID:
 
 ```bash
-export CLOUDFLARE_API_KEY=...           # or use /login
+export CLOUDFLARE_API_KEY=...
 export CLOUDFLARE_ACCOUNT_ID=...
 export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
 apex-code --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"
 ```
 
-Routes to OpenAI, Anthropic, and Workers AI through Cloudflare AI Gateway. Workers AI uses the Unified API (`/compat`) and prefixed model IDs (`workers-ai/@cf/...`). OpenAI uses the OpenAI passthrough route (`/openai`) with native OpenAI model IDs such as `gpt-5.1`. Anthropic uses the Anthropic passthrough route (`/anthropic`) with native Anthropic model IDs such as `claude-sonnet-4-5`.
+The account and gateway IDs can come from the process environment or the credential's `env` object in `auth.json`.
 
 AI Gateway authentication uses `CLOUDFLARE_API_KEY` as `cf-aig-authorization`. Upstream authentication can be one of:
 
@@ -273,10 +217,10 @@ For normal Apex Code usage, prefer unified billing or stored BYOK. Inline BYOK r
 
 ### Cloudflare Workers AI
 
-`CLOUDFLARE_API_KEY` can be set via `/login`. `CLOUDFLARE_ACCOUNT_ID` can be set as an environment variable or in the API key credential's `env` object in `auth.json`.
+Workers AI requires a token and account ID:
 
 ```bash
-export CLOUDFLARE_API_KEY=...           # or use /login
+export CLOUDFLARE_API_KEY=...
 export CLOUDFLARE_ACCOUNT_ID=...
 apex-code --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"
 ```
@@ -285,17 +229,25 @@ Apex Code automatically sets `x-session-affinity` for [prefix caching](https://d
 
 ### Google Vertex AI
 
-Uses Application Default Credentials:
+Use a Google Cloud API key:
+
+```bash
+export GOOGLE_CLOUD_API_KEY=...
+```
+
+To use Application Default Credentials, configure a project and location:
 
 ```bash
-gcloud auth application-default login
 export GOOGLE_CLOUD_PROJECT=your-project
+# GCLOUD_PROJECT is also supported
 export GOOGLE_CLOUD_LOCATION=us-central1
 ```
 
-Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file.
+Then authenticate:
 
-## llama.cpp
+```bash
+gcloud auth application-default login
+```
 
 Apex Code supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage loaded models with `/llama`, and select a loaded model with `/model`.
 

package/docs/quickstart.md

@@ -2,7 +2,7 @@
 
 This page gets you from install to a useful first Apex Code session.
 
-## Install
+For native Windows setup, read [Windows Setup](windows.md). For Android, read [Termux Setup](termux.md).
 
 Apex Code is distributed as an npm package and installs the same way with npm, pnpm,
 Yarn, or Bun — all four resolve it from the same npm registry:
@@ -56,11 +56,11 @@ cd /path/to/project
 apex-code
 ```
 
-## Authenticate
+The working folder helps Apex Code discover relevant files, instructions, and configuration. Apex Code also uses it to group saved sessions.
 
 Apex Code can use subscription providers through `/login`, or API-key providers through environment variables or the auth file.
 
-### Option 1: subscription login
+The interface shows your conversation, an editor for prompts and commands, and a footer with the current folder, model, and session status. See [Use Apex Code in the terminal](usage.md) to learn how to add files, run commands, direct ongoing work, and manage results.
 
 Start Apex Code and run:
 
@@ -68,9 +68,9 @@ Start Apex Code and run:
 /login
 ```
 
-Then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot.
+Choose a provider, then follow the prompts to use a subscription or store an API key. Run `/model` afterward if you want to select a different available model.
 
-### Option 2: API key
+See [Choose a model and provider](models.md) for supported providers, environment-variable authentication, local models, and custom endpoints.
 
 Set an API key before launching Apex Code:
 
@@ -88,7 +88,7 @@ See [Providers](providers.md) for all supported providers, environment variables
 Once Apex Code starts, type a request and press Enter:
 
 ```text
-Summarize this repository and tell me how to run its checks.
+Summarize @meeting-notes.md and save the action items to action-items.md.
 ```
 
 By default, Apex Code gives the model four tools:
@@ -139,18 +139,18 @@ Images or text can be pasted with Ctrl+V (Alt+V on Windows); images can also be
 In interactive mode:
 
 ```text
-!npm run lint
+Explain how this repository is structured and how to run its checks.
 ```
 
-The command output is sent to the model. Use `!!command` to run a command without adding its output to the model context.
-
-### Switch models
+```text
+Compare @previous.csv with @current.csv and summarize the important changes.
+```
 
-Use `/model` or Ctrl+L to choose a model for the current session. Press Ctrl+S in the model picker to save the highlighted model as the startup default. Use `/thinking` to choose a thinking level for the current session, or Ctrl+S in that picker to save the startup default thinking level. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.
+Type `@` in the editor to search for a file instead of entering its full path. When Apex Code finishes, review its response and any changed files. Use version control or backups for important work. For untrusted or unattended work, use a container or another sandbox. See [Security](security.md).
 
-### Continue later
+## Continue later
 
-Sessions are saved automatically:
+Apex Code saves sessions automatically. Exit Apex Code, then resume the most recent session for the same working folder with:
 
 ```bash
 apex-code -c                  # Continue most recent session
@@ -181,4 +181,32 @@ Use `--mode json` for JSON event output or `--mode rpc` for process integration.
 - [Keybindings](keybindings.md) - shortcuts and customization.
 - [Apex Code Packages](packages.md) - install shared extensions, skills, prompts, and themes.
 
-Platform notes: [Windows](windows.md), [Termux](termux.md), [tmux](tmux.md), [Terminal setup](terminal-setup.md), [Shell aliases](shell-aliases.md).
+### Choose how to customize Apex Code
+
+Start with the least powerful mechanism that meets your need:
+
+| Need | Start with |
+|---|---|
+| Give Apex Code persistent instructions for a folder | [`AGENTS.md`](configuration.md#context-files) |
+| Reuse a prompt from the `/` menu | [Prompt template](prompt-templates.md) |
+| Add task-specific instructions and supporting files | [Skill](skills.md) |
+| Add executable tools, commands, or event handlers | [Extension](extensions.md) |
+| Build a custom terminal component | [Terminal UI](tui.md) |
+| Connect an unsupported model service | [Custom provider](custom-provider.md) |
+| Install or distribute several resources | [Apex Code package](packages.md) |
+
+## Update or uninstall Apex Code
+
+Update Apex Code with your package manager:
+
+```bash
+npm install --global apex-code
+```
+
+To uninstall an npm installation, run:
+
+```bash
+npm uninstall --global apex-code
+```
+
+Uninstalling leaves configuration, credentials, sessions, and installed packages in `~/.apex-code/agent/`.