@subimpact/e 0.0.0-stage → 0.99.2

package/docs/providers.md

@@ -0,0 +1,190 @@
+# Provider Authentication
+
+Most hosted providers support one or both of these authentication methods:
+
+- Sign in through a browser or device flow backed by OAuth.
+- Provide an API key.
+
+Use `/login [provider]` to see the methods supported by a provider. Amazon Bedrock and Google Vertex AI can also use ambient cloud credentials.
+
+## Authenticate interactively
+
+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).
+
+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.
+
+Run `/logout` and select a provider to remove its stored credential. This does not unset environment variables, remove authentication from `models.json`, or revoke the credential at the provider.
+
+`auth.json` can contain API keys and OAuth tokens. Keep it private and do not commit it.
+
+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.
+
+## Use an API key from the environment
+
+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-...
+pi
+```
+
+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` |
+| TypeSafe ([classifier models](models.md#use-classifier-models)) | `TYPESAFE_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.
+
+With no key or token set, Anthropic uses workload identity federation when `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID` and `ANTHROPIC_IDENTITY_TOKEN_FILE` are set: the Anthropic SDK exchanges the identity token for a short-lived access token and refreshes it itself (re-reading the identity token file, so keep that file fresh for long sessions). `ANTHROPIC_SERVICE_ACCOUNT_ID` and `ANTHROPIC_WORKSPACE_ID` are passed through when set.
+
+## Load an API key from a command
+
+To use a secret manager without writing the resolved key to disk, set a provider's `key` in `auth.json` to a command prefixed with `!`:
+
+```json
+{
+  "anthropic": {
+    "type": "api_key",
+    "key": "!security find-generic-password -ws 'anthropic'"
+  }
+}
+```
+
+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.
+
+## Cloud Providers
+
+The providers below need additional settings or can use credentials supplied by their cloud platform.
+
+A stored API-key credential can include an `env` object. Its values take priority over the process environment for that provider:
+
+```json
+{
+  "cloudflare-workers-ai": {
+    "type": "api_key",
+    "key": "...",
+    "env": {
+      "CLOUDFLARE_ACCOUNT_ID": "account-id"
+    }
+  }
+}
+```
+
+### 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
+# Or:
+export AZURE_OPENAI_RESOURCE_NAME=your-resource
+```
+
+Resource root URLs under `ai.azure.com`, `cognitiveservices.azure.com`, and `openai.azure.com` are normalized to the OpenAI API path.
+
+### Amazon Bedrock
+
+Bedrock can use a bearer token or an ambient AWS credential source:
+
+```bash
+# Named profile
+export AWS_PROFILE=your-profile
+
+# IAM keys
+export AWS_ACCESS_KEY_ID=AKIA...
+export AWS_SECRET_ACCESS_KEY=...
+# Required for temporary credentials
+export AWS_SESSION_TOKEN=...
+
+# Bedrock bearer token
+export AWS_BEARER_TOKEN_BEDROCK=...
+
+# Region, when not supplied by the profile or AWS SDK configuration
+export AWS_REGION=us-west-2
+# AWS_DEFAULT_REGION is also supported
+```
+
+Pi also supports ECS task credentials and IRSA through the standard `AWS_CONTAINER_CREDENTIALS_*` and `AWS_WEB_IDENTITY_TOKEN_FILE` variables.
+
+### Cloudflare AI Gateway
+
+The gateway requires a token, account ID, and gateway ID:
+
+```bash
+export CLOUDFLARE_API_KEY=...
+export CLOUDFLARE_ACCOUNT_ID=...
+export CLOUDFLARE_GATEWAY_ID=...
+```
+
+The account and gateway IDs can come from the process environment or the credential's `env` object in `auth.json`.
+
+`CLOUDFLARE_API_KEY` authenticates Pi to the gateway. Upstream access can use Cloudflare unified billing, credentials stored in the gateway, or an `Authorization` header configured for the provider in `models.json`.
+
+### Cloudflare Workers AI
+
+Workers AI requires a token and account ID:
+
+```bash
+export CLOUDFLARE_API_KEY=...
+export CLOUDFLARE_ACCOUNT_ID=...
+```
+
+The account ID can also be stored in the credential's `env` object.
+
+### Google Vertex AI
+
+Use a Google Cloud API key:
+
+```bash
+export GOOGLE_CLOUD_API_KEY=...
+```
+
+To use Application Default Credentials, configure a project and location:
+
+```bash
+export GOOGLE_CLOUD_PROJECT=your-project
+# GCLOUD_PROJECT is also supported
+export GOOGLE_CLOUD_LOCATION=us-central1
+```
+
+Then authenticate:
+
+```bash
+gcloud auth application-default login
+```
+
+To use a service-account key file instead, set `GOOGLE_APPLICATION_CREDENTIALS` along with the project and location.

package/docs/quickstart.md

@@ -0,0 +1,122 @@
+# Quickstart
+
+Pi runs in your terminal and works with files on your machine. To use it, you need access to a model through a supported provider. This can be a subscription, an API key, or a local model.
+
+For native Windows setup, read [Windows Setup](windows.md). For Android, read [Termux Setup](termux.md).
+
+## 1. Install Pi
+
+On macOS or Linux, you can use the installer:
+
+```bash
+curl -fsSL https://pi.dev/install.sh | sh
+```
+
+Alternatively, install Pi from npm. This requires Node.js 22.19 or newer:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
+Pi does not require dependency lifecycle scripts for a normal npm installation.
+
+Verify the installation:
+
+```bash
+pi --version
+```
+
+## 2. Start Pi
+
+Change to the folder you want Pi to work with, then start it:
+
+```bash
+cd /path/to/folder
+pi
+```
+
+The working folder helps Pi discover relevant files, instructions, and configuration. Pi also uses it to group saved sessions.
+
+<p align="center"><img src="images/interactive-mode.png" alt="Pi running in a terminal with a conversation, input editor, and status footer" width="750"></p>
+
+The interface shows your conversation, an editor for prompts and commands, and a footer with the current folder, model, and session status. See [Use Pi in the terminal](usage.md) to learn how to add files, run commands, direct ongoing work, and manage results.
+
+## 3. Choose a model
+
+A **model** generates Pi's responses. A **provider** is the service or account Pi uses to access that model.
+
+In Pi, run:
+
+```text
+/login
+```
+
+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.
+
+See [Choose a model and provider](models.md) for supported providers, environment-variable authentication, local models, and custom endpoints.
+
+## 4. Give Pi a task
+
+Pi shows each file read, search, command, and edit it performs. It does not ask before every tool call.
+
+Enter a task that matches your work, for example:
+
+```text
+Summarize @meeting-notes.md and save the action items to action-items.md.
+```
+
+```text
+Explain how this repository is structured and how to run its checks.
+```
+
+```text
+Compare @previous.csv with @current.csv and summarize the important changes.
+```
+
+Type `@` in the editor to search for a file instead of entering its full path. When Pi 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
+
+Pi saves sessions automatically. Exit Pi, then resume the most recent session for the same working folder with:
+
+```bash
+pi --continue
+```
+
+Use `/resume` to choose another saved session. See [Continue or branch a session](sessions.md) for session naming, branching, compaction, export, and sharing.
+
+## Next steps
+
+- [Use Pi interactively](usage.md) to learn input, commands, shortcuts, and queued messages.
+- [Add instructions](configuration.md#context-files) that Pi should follow whenever it works in a folder.
+- [Choose a model and provider](models.md).
+
+### Choose how to customize Pi
+
+Start with the least powerful mechanism that meets your need:
+
+| Need | Start with |
+|---|---|
+| Give Pi 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 | [Pi package](packages.md) |
+
+## Uninstall Pi
+
+If you installed Pi with npm, run:
+
+```bash
+npm uninstall -g @earendil-works/pi-coding-agent
+```
+
+If you used the installer, run it again and choose **Uninstall Pi**:
+
+```bash
+curl -fsSL https://pi.dev/install.sh | sh
+```
+
+Neither method removes configuration, credentials, sessions, or installed Pi packages from `~/.pi/agent/`.