@globant/coda-windows-x64 1.0.0

package/assets/docs/config-reference.md

@@ -0,0 +1,329 @@
+# Configuration Reference
+
+Reference for the most common configuration options. For how to set these up in practice, see [Configuration](#configuration). To see every block together in one annotated file you can copy from, see [config.json — A Complete Example](#config-json). Most of these can be changed from the UI — you rarely need to edit the files by hand.
+
+## Config file locations
+
+| File | Purpose |
+| --- | --- |
+| `~/.coda/config.json` | User-global settings |
+| `~/.coda/.secrets` | API keys (dotenv format, never commit) |
+| `~/.coda/mcp.json` | Global MCP server definitions |
+| `<project>/.coda/config.json` | Project-level overrides |
+| `<project>/coda.config.ts` | TypeScript config (takes priority) |
+| `<project>/.coda/mcp.json` | Project-level MCP servers |
+
+## activeProfile and profiles
+
+**`activeProfile`** and **`profiles`** are the current way CODA selects which AI backend to use. The setup wizard (`/providers` or `coda --reconfigure`) and `/switch-profile` (alias `/sp`) manage these for you.
+
+| Field | Description |
+| --- | --- |
+| `activeProfile` | ID of the currently-active profile (key into `profiles`). Set by the wizard or `/switch-profile`. |
+| `profiles` | Map of named, switchable provider targets keyed by a unique ID you choose. |
+
+Each profile has a `provider` type that determines its shape:
+
+### `glob-ai` profiles (Glob.AI OS / Globant)
+
+```jsonc
+{
+  "activeProfile": "work",
+  "profiles": {
+    "work": {
+      "provider": "glob-ai",
+      "label": "Globant Clients",
+      "instance": "clients",       // "clients" | "corp" | "saas-europe" | custom id
+      "auth": { "method": "oauth" },
+      "model": "anthropic/claude-opus-4-8",
+      "org": { "id": "org-123", "name": "My Org" },    // set by wizard after login
+      "project": { "id": "proj-456", "name": "My Project" }
+    }
+  }
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `provider` | Must be `"glob-ai"` |
+| `label` | Human-readable name shown in the UI |
+| `instance` | Preset environment: `"clients"`, `"corp"`, `"saas-europe"`, or a custom ID. Custom instances require a `baseUrl`. |
+| `auth` | Auth method: `{ "method": "oauth" }` (browser login, tokens in OS keyring) or `{ "method": "apikey", "secretRef": "ENV_VAR_NAME" }` |
+| `model` | Default model for this profile (optional) |
+| `org` / `project` | Selected org and project (written by wizard after login) |
+| `favoriteModels` | Array of model IDs shown as quick-switch options |
+| `fastModel` / `smartModel` / `deepModel` | Model IDs for the `"fast"`, `"smart"`, and `"deep"` agent shortcut tiers |
+
+### `openai-compat` profiles (any OpenAI-compatible API)
+
+```jsonc
+{
+  "activeProfile": "my-api",
+  "profiles": {
+    "my-api": {
+      "provider": "openai-compat",
+      "label": "My Custom API",
+      "baseUrl": "https://api.example.com/v1",
+      "auth": { "method": "apikey", "secretRef": "MY_API_KEY" },
+      "model": "my-model"
+    }
+  }
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `provider` | Must be `"openai-compat"` |
+| `label` | Human-readable name |
+| `baseUrl` | Base URL of the API endpoint |
+| `auth` | Must be `{ "method": "apikey", "secretRef": "ENV_VAR_NAME" }` |
+| `model` | Default model (optional) |
+
+### `ollama` profiles (local Ollama server)
+
+```jsonc
+{
+  "activeProfile": "local",
+  "profiles": {
+    "local": {
+      "provider": "ollama",
+      "label": "Local Ollama",
+      "baseUrl": "http://127.0.0.1:11434/v1",  // optional, this is the default
+      "auth": { "method": "none" },
+      "model": "llama3.1"
+    }
+  }
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `provider` | Must be `"ollama"` |
+| `label` | Human-readable name |
+| `baseUrl` | Ollama server URL (optional, defaults to `http://127.0.0.1:11434/v1`) |
+| `auth` | Must be `{ "method": "none" }` |
+| `model` | The model you've pulled in Ollama |
+
+Start Ollama first: `ollama serve` and `ollama pull <model>`. You can configure the same thing through the wizard: `/providers` → **Custom provider** → **Ollama** (see [Connect a Provider](#connect-provider)).
+
+---
+
+## providers (runtime client map — legacy)
+
+> **CODA no longer writes `provider` / `providers` to disk.** The on-disk config is profiles-only; at launch CODA derives an equivalent runtime provider-client map from your active profile. This section documents the legacy shape for older configs (which still work) and for reference — you don't add it by hand.
+
+Each entry maps a key (referenced by `provider`) to a typed config block:
+
+| Type | Required fields | Notes |
+| --- | --- | --- |
+| `geai` | `baseUrl`, `apiKey` (or OAuth) | Glob.AI OS gateway |
+| `openai-compat` | `baseUrl` | Any OpenAI-compatible API; `apiKey` optional |
+| `ollama` | — | `baseUrl` optional (defaults to `http://127.0.0.1:11434/v1`) |
+| `openai` | `apiKey` | OpenAI SDK |
+| `anthropic` | `apiKey` | Anthropic SDK |
+| `google` | `apiKey` | Google Generative AI SDK |
+| `groq` | `apiKey` | Groq SDK |
+| `openrouter` | `apiKey` | OpenRouter SDK |
+| `azure` | `resourceName`, `apiKey`, `apiVersion` | Azure OpenAI SDK |
+| `vertex` | project/region config | Google Vertex AI SDK |
+
+Every provider entry also accepts `fastModel`, `smartModel`, `deepModel`, and a `models` map for per-model capability overrides.
+
+Keep secrets out of `config.json` — store them in `~/.coda/.secrets` (dotenv format) and reference with `${VAR}`:
+
+```json
+{
+  "providers": {
+    "my-api": {
+      "type": "openai-compat",
+      "baseUrl": "https://api.example.com/v1",
+      "apiKey": "${MY_API_KEY}"
+    }
+  }
+}
+```
+
+## model (top-level)
+
+| Field | Description |
+| --- | --- |
+| `model` | Legacy fallback model id, paired with the deprecated top-level `provider`. Prefer setting `model` inside a profile (or switch live with `/model`). Not written to disk by current CODA. |
+
+## auth (Glob.AI OS login preferences)
+
+Applies to Glob.AI OS / Globant OAuth sign-in. The wizard manages these; you rarely edit them by hand.
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `auth.methodPreference` | `"access_token"` | Prefer OAuth access tokens (`"access_token"`) or a static API key (`"api_key"`) |
+| `auth.callbackTimeout` | `300` | Seconds to wait for the browser OAuth callback |
+| `auth.tokenRefreshThreshold` | (built-in) | Seconds before expiry at which an access token is proactively refreshed |
+| `auth.gamRedirectUri` | `http://localhost:XXXX/callback` | OAuth redirect URI. **Deprecated:** prefer `authDefaults` inside the provider entry |
+
+## mcp (inline servers)
+
+You can define [MCP](#tools-reference) servers inline instead of in `mcp.json`:
+
+| Field | Description |
+| --- | --- |
+| `mcp.servers` | Map of server id → server entry (`command`+`args` for stdio, or `url` for http; plus optional `env`, `headers`, `timeout`, `authorizationToken`). Merged with `~/.coda/mcp.json` and `<project>/.coda/mcp.json`. |
+
+## bash
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `autoApproveLevel` | `"low"` | Risk level auto-approved without confirmation: `"safe"`, `"low"`, `"medium"`, `"high"` |
+| `shellMode` | `"auto"` | Shell to use: `"auto"`, `"bash"`, `"powershell"`, `"wsl"` |
+
+## compaction
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `enabled` | `true` | Enable automatic pre-flight compaction |
+| `threshold` | `0.75` | Fraction of token budget that triggers compaction (0.3–0.9) |
+| `retainFraction` | `0.3` | Fraction of recent messages kept verbatim (0.1–0.9) |
+
+## reasoning
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `reasoning.enabled` | `false` | Opt in to sending thinking/reasoning tokens to reasoning-capable models. Off by default. |
+| `reasoning.effort` | `"medium"` | Thinking effort level: `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`. Change it live with `/effort` (see [Commands & Flags](#cli-reference)). Per-model support varies — some models accept only a subset, and some none at all. |
+
+## Other common settings
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `theme` | (unset) | UI theme: `"classic"` or `"modern"` (no schema default; the UI layer defaults to `"classic"`) |
+| `maxSteps` | `300` | Cap on agent loop steps per turn |
+| `agents.enabled` | `true` | Whether delegated agents and their tools are available |
+| `agents.maxConcurrent` | `6` | Cap on parallel agent runs (1–10) |
+| `agents.defaultModel` | — | **Legacy.** Default model for delegated runs. Kept for older configs; runs now use your main session model unless an agent definition sets `model`. |
+| `agents.fastModel` | — | Model ID used when a run requests the `"fast"` tier (overrides provider-level setting) |
+| `agents.smartModel` | — | Model ID used when a run requests the `"smart"` tier |
+| `agents.deepModel` | — | Model ID used when a run requests the `"deep"` tier |
+| `agents.disabledDefinitions` | — | Array of agent definition names to disable without deleting their files |
+| `checkpoints.enabled` | on (interactive) / off (headless) | Master switch for the checkpoints subsystem |
+| `errorHandling.posture` | `balanced` | How aggressively CODA retries on model/provider failures: `conservative` (fewer retries, fail fast), `balanced`, `aggressive` (more retries and failover attempts). See [How CODA Works](#how-it-works). |
+
+## tools
+
+| Field | Description |
+| --- | --- |
+| `tools.glob` | Enable/disable the file finder and tune its limits |
+| `tools.glob.max_results` | Max file paths returned per glob call (1–5000, default `100`) |
+| `tools.grep.backend` | Content-search engine: `"ripgrep"` (default, bundled) or `"fastgrep"` |
+| `tools.grep.index_path` | Path to a pre-built fgr index directory (fastgrep backend only) |
+| `tools.grep` | Enable/disable content search and cap result counts |
+
+## vision
+
+| Field | Description |
+| --- | --- |
+| `vision.model` | Model used by `examine_images` (Glob.AI OS profiles) |
+
+## checkpoints
+
+| Field | Description |
+| --- | --- |
+| `checkpoints.enabled` | Master switch (on interactive, off headless) |
+| `checkpoints.diskSoftCapMb` | Soft warning threshold for snapshot disk usage. Default **2048** (2 GiB) |
+| `checkpoints.diskHardCapMb` | Hard limit; checkpoints disable for the session once exceeded. Default **5120** (5 GiB) |
+| `checkpoints.maxWorktreeFiles` | Disable snapshots when the worktree exceeds this many files. Default **100000** |
+
+## skills
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `skills.descriptionMaxChars` | `200` | Max characters of each skill's description injected into the prompt (longer ones are truncated) |
+| `skills.warnThreshold` | `100` | Warn when the number of discovered skills exceeds this — large skill sets cost context |
+
+## logging
+
+| Field | Description |
+| --- | --- |
+| `logging.level` | Global default log level |
+| `logging.levels` | Per-service overrides (e.g. `{ "core.agent": "debug" }`) |
+| `logging.redact` | Extra redaction rules merged on top of the always-on built-ins |
+| `logging.rawViewer.enabled` | Gate for browsing raw logs (on in dev, off in release) |
+
+## Advanced blocks
+
+These exist for power users and rarely need hand-editing. Most can be reached through `/settings` or are tuned per provider.
+
+**`fallback`** — failover between providers/models:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `fallback.enabled` | `false` | Enable provider/model failover |
+| `fallback.provider` | — | Key of the fallback provider |
+| `fallback.model` | — | Model to use on the fallback provider (optional) |
+
+**`webSearch`** — web search tool settings:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `webSearch.provider` | `"brave"` | Search backend: `"exa"`, `"brave"`, or `"serper"` |
+| `webSearch.apiKey` | — | API key for the chosen search backend |
+
+**`session`** — session auto-rename behavior:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `session.autoRenameEnabled` | `true` | Automatically rename sessions based on content |
+| `session.autoRenameTimeoutMs` | `5000` | Timeout for the rename request (ms) |
+| `session.autoRenameMaxRetries` | `3` | Retry limit for auto-rename failures |
+
+**`composer`** — message queue behavior while the agent is busy:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `composer.whileBusy.delivery` | `"queue"` | What to do with messages sent while the agent is running: `"queue"` or `"steer"` |
+| `composer.queueSteer.enabled` | `true` | Enable queue/steer feature |
+| `composer.queueSteer.defaultMode` | `"later"` | Default mode when queuing: `"next"` (run next) or `"later"` (append to queue) |
+
+**`acp`** — agent communication protocol:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `acp.enabled` | `true` | Enable ACP headless mode (`coda --acp`) |
+
+**`autoupdate`** — automatic update behavior: `true` (auto-install), `"notify"` (notify only), or `false` (disable). Default `true`.
+
+**`extensions`** — array of extension file paths to load at startup (e.g. `[".coda/extensions/my-tool.ts"]`).
+
+**`reasoning`** — effort/thinking controls for reasoning-capable models.
+
+**`telemetry`** — OpenTelemetry export:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `telemetry.enabled` | `false` | Master switch for OTel export |
+| `telemetry.exporter` | `"otlp"` | Exporter: `"otlp"` (send to a collector) or `"console"` (print spans locally) |
+| `telemetry.otlpHost` | (build-injected) | Collector host/URL for the OTLP exporter |
+| `telemetry.otlpProtocol` | `"http"` | OTLP transport: `"http"` or `"grpc"` |
+| `telemetry.otlpUseTls` | `false` | Use HTTPS / gRPC TLS to the collector |
+| `telemetry.serviceName` | — | Custom `service.name` reported in traces |
+| `telemetry.tracesEnabled` | `true` | Emit traces |
+| `telemetry.metricsEnabled` | `true` | Emit metrics |
+
+Settings cascade in priority order: CLI flags override project config, which overrides your global config (see [Configuration](#configuration)).
+
+## Referencing secrets with `${VAR}`
+
+Keep keys out of `config.json` by storing them in `~/.coda/.secrets` (dotenv format) and referencing them with `${VAR}` interpolation:
+
+```jsonc
+// ~/.coda/.secrets
+// GEAI_API_KEY=sk-...
+
+// ~/.coda/config.json
+{ "providers": { "geai-corp": { "apiKey": "${GEAI_API_KEY}" } } }
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `LOG_LEVEL` | `info` | Log verbosity, Rust-style: a bare token sets the global floor, `service:level` overrides per service (e.g. `info,core.agent:debug`) |
+| `CODA_HOME` | `~/.coda` | Alternative home directory for config, secrets, sessions, logs, and checkpoints |

package/assets/docs/configuration.md

@@ -0,0 +1,105 @@
+# Configuration
+
+CODA is configured from within the tool itself — you normally don't edit files by hand. Commands like `/providers` and `/settings` write your choices to a layered config. This page explains how that works and where everything lives.
+
+## Connect a provider
+
+You don't need to run any command to get your first provider. The very first time you launch CODA, a setup wizard appears automatically and walks you through it:
+
+- **Pick a Glob.AI OS environment** — Clients, Corp, SaaS Europe, and so on.
+- **Choose how to authenticate** — **OAuth (recommended)**, which signs you in through your browser, or an **API key**.
+
+For a step-by-step walkthrough of that flow — including OAuth vs API key and custom providers — see [Connect a Provider](#connect-provider). API keys are stored in `~/.coda/.secrets`, separate from config and never committed to Git.
+
+To **add another provider or edit an existing one** later, open the wizard again from inside CODA:
+
+```text
+/providers
+```
+
+The same wizard is available from your terminal with `coda --reconfigure`.
+
+## Switch between providers
+
+If you've set up more than one provider (say, two Glob.AI OS instances, or a local Ollama for testing), switch between them right from the UI with `/providers` — no config files to edit.
+
+## Where settings live
+
+Settings cascade in priority order — project settings override user settings, and CLI flags override everything:
+
+| File | What it's for |
+| --- | --- |
+| `~/.coda/config.json` | Your personal defaults — provider, model, theme |
+| `~/.coda/.secrets` | API keys and credentials (never commit this) |
+| `<project>/.coda/config.json` | Project-level overrides (safe to commit if no secrets) |
+| `<project>/coda.config.ts` | TypeScript config — if present, it replaces the project `config.json` (the JSON is ignored) |
+| `~/.coda/mcp.json` | MCP servers available in all your projects |
+| `<project>/.coda/mcp.json` | MCP servers for this project only |
+| `~/.coda/sessions/<id>/mcp.json` | Per-session MCP overrides (written by `/mcp` commands within a session) |
+| `<project>/.coda/.env` or `<project>/.env` | Project-level secrets for `${VAR}` interpolation (merged with `~/.coda/.secrets`) |
+
+## Common settings to change
+
+Some settings can be adjusted from the settings panel. Open it from inside CODA:
+
+```text
+/settings
+```
+
+**Bash approval level** — open **Bash Tool Preferences** to control how many shell commands CODA can run without asking you first. There are four levels:
+
+- `safe` — only read-only commands run automatically; everything else asks.
+- `low` — the default; a conservative set of safe commands is auto-approved.
+- `medium` — more commands run without prompting.
+- `high` — everything is auto-approved except destructive operations.
+
+The same screen lets you pick the **shell** CODA uses (`auto`, `bash`, `powershell`, or `wsl`).
+
+**Compaction** — to keep context fresh, CODA can automatically condense older conversation before it runs out of room. Tune it under **Context Compaction**:
+
+- **Scope** — apply your changes globally or to the current project (project overrides global).
+- **Enable / disable** — turn automatic compaction on or off. With it off, you can still compact on demand with `/compact`.
+- **Threshold** — how full the context can get (as a percentage) before CODA condenses.
+- **Retain fraction** — how much of the most recent conversation is kept intact when condensing; older messages are summarized.
+
+**Chat input** — choose what happens when you send a message while CODA is already working: **Queue message** waits until the current turn finishes (default), while **Steer message** sends your message as the next input to guide the active flow. In `/settings`, this appears under **Composer**. See [Make Changes Safely](#guide-changes) for details.
+
+**Theme** — switch the look of the UI between `classic` and `modern` under **UI Theme**.
+
+## How settings cascade
+
+When the same key is set in more than one place, the most specific wins. From lowest to highest priority:
+
+1. **Built-in defaults** — what CODA ships with.
+2. **`~/.coda/config.json`** — your personal, machine-wide settings.
+3. **`<project>/.coda/config.json`** (or `<project>/coda.config.ts`, which replaces it) — project overrides.
+4. **CLI flags** — `--bash-security`, `--model`, `--profile`, and friends, for a single run.
+
+So a project can raise the bash level for everyone who clones it, and you can still override it for one run with `--bash-security` — without editing any file.
+
+## What's safe to commit
+
+- **Commit:** `<project>/.coda/config.json` (no secrets), `<project>/.coda/mcp.json`, `AGENTS.md`, shared skills/agents/workflows.
+- **Never commit:** `~/.coda/.secrets` (it lives in your home directory, not the repo) and your personal `~/.coda/config.json`.
+- **Think twice:** pinning the active `provider` or an elevated `bash.autoApproveLevel` in a project config affects every teammate — see [Collaborate with Your Team](#guide-collaborate).
+
+## A minimal `config.json`
+
+You rarely write this by hand, but it helps to know the shape:
+
+```json
+{
+  "activeProfile": "my-corp-profile",
+  "model": "claude-sonnet",
+  "theme": "modern",
+  "bash": { "autoApproveLevel": "low", "shellMode": "auto" },
+  "compaction": { "enabled": true, "threshold": 0.75 },
+  "agents": { "enabled": true, "maxConcurrent": 6 }
+}
+```
+
+> **Note:** The older `"provider"` key is still accepted for backward compatibility but `activeProfile` + `profiles` is the current mechanism used by the wizard and `/switch-profile`.
+
+API keys are *not* in here — they live in `~/.coda/.secrets` in dotenv format and can be referenced from config with `${VAR}` interpolation.
+
+See the full [Configuration Reference](#config-reference) for every available option, or [config.json — A Complete Example](#config-json) for one annotated file showing every block in context.

package/assets/docs/connect-provider.md

@@ -0,0 +1,77 @@
+# Connect a Provider
+
+The first time you launch CODA — before you can run a prompt — a setup wizard (titled **CODA setup**) walks you through connecting a **provider**: the AI backend CODA talks to. This page explains each choice so you land on the right one. You can reopen the wizard later — see **Reconfigure** below.
+
+## Step 1 — Choose how to connect
+
+- **Glob.AI OS (Globant environments)** — what most people at Globant want.
+- **Custom provider** — an OpenAI-compatible endpoint, or a local [Ollama](https://ollama.com) server.
+
+## Step 2 — Pick a Glob.AI OS environment
+
+> **Note:** The environment picker (this step) only appears when you launch `coda --globant`. Running plain `coda` skips the picker and defaults directly to **SaaS Europe**.
+
+Pick your environment: **Clients**, **Corp** (API key only — no browser OAuth), or **SaaS Europe**.
+
+## Step 3 — Authenticate
+
+- **OAuth (recommended)** — CODA opens your browser, you sign in with your Globant account, and the session is stored for you. No keys to copy or rotate. Back in CODA, if you have more than one project assigned in that environment, you'll be asked to **select your organization and project** so CODA knows which workspace to use.
+- **API Key** — paste or type your key (the input is hidden), then press **Enter**. Key-only environments skip straight here.
+
+API keys are stored in `~/.coda/.secrets`, separate from your config and never committed to Git.
+
+## Custom provider
+
+If you picked **Custom provider**, choose the type:
+
+- **OpenAI-compatible** — enter a profile name, the base URL, and an API key.
+- **Ollama** — point CODA at your local server (no API key needed). The default endpoint is `http://127.0.0.1:11434/v1`. For a copy-paste `config.json` example, see [Configuration Reference](#config-reference).
+
+## Switch between configured providers
+
+Each provider you set up is stored as a named **profile** (in the `profiles` map of `~/.coda/config.json`), and one of them is marked **active** via the top-level `activeProfile` key. The active profile decides which backend — and, for Glob.AI OS, which environment, organization, and project — CODA talks to.
+
+Once you have more than one profile configured, switch between them quickly with **`/switch-profile`** (alias **`/sp`**):
+
+```text
+/switch-profile              # opens the profile picker
+```
+
+`/switch-profile` only chooses among profiles you've **already configured** — it doesn't add or edit them. It saves your choice as `activeProfile` and reports `Active profile "…" set — applies on next launch`; the switch takes effect the next time you start CODA (there's no live re-target of the current session).
+
+To **add, edit, or remove** a profile instead of just selecting one, use `/providers` (see [Reconfigure](#reconfigure)).
+
+## Switching the active Glob.AI OS project
+
+If you authenticated with OAuth and your account has more than one project in the chosen environment, CODA asks you to select an **organization and project** during setup. To change that selection later without re-running the whole wizard, use `/project` inside a session — it switches the active Glob.AI OS project (OAuth only).
+
+## Check who you're signed in as
+
+To confirm the current authentication state from inside a session:
+
+```text
+/auth-status     (alias /whoami)
+```
+
+It shows the active provider, environment, and — for OAuth — the signed-in identity and selected project. To sign out of a Glob.AI OS session, run `/logout`.
+
+## Reconfigure
+
+To re-authenticate within an active session (e.g. after an OAuth session expires), run `/login` — it re-initiates browser OAuth without reopening the full wizard. For first-time provider setup or editing an existing provider, use `/providers` inside a session (changes take effect after a restart) or `coda --reconfigure` from your terminal. Use `/providers` to switch between configured providers anytime — the provider you configure or select there becomes the **active** one. `coda --reconfigure` edits a provider's settings *without* changing which provider is active.
+
+You can configure **more than one provider** and keep them side by side — for example a Glob.AI OS environment for day-to-day work and a local Ollama for offline testing. `/providers` lets you add, edit, remove, and switch between them. If you only want to *change which configured profile is active* (not add or edit one), `/switch-profile` (alias `/sp`) is the quicker path — see [Switch between configured providers](#switch-between-configured-providers). Either way, the change applies after a restart.
+
+### Switch a Glob.AI OS provider between OAuth and API key
+
+To change *how* you authenticate to the same environment — say, move from a pasted API key to browser OAuth, or the reverse — reopen the wizard with `/providers` (or `coda --reconfigure`), select that environment again, and pick the other authentication method. CODA replaces the stored credential: an OAuth session is captured for you, or a new key is written to `~/.coda/.secrets`. The change takes effect after a restart. To drop the current credential entirely, `/logout` signs out of the active Glob.AI OS session.
+
+## Troubleshooting
+
+- **The browser didn't open during OAuth** — copy the URL CODA prints and open it manually. Once you finish signing in, the session is captured automatically.
+- **"No project found" after OAuth** — your account may not be assigned to a project in that environment. Pick a different environment, or use `/project` after sign-in to select one.
+- **A key stopped working** — re-run `/providers` (or `coda --reconfigure`) and paste a fresh key. Keys live in `~/.coda/.secrets`; rotating one there is enough.
+- **Changes to `/providers` didn't take effect** — provider changes apply after a restart. Exit and relaunch CODA.
+
+## What's next
+
+With a provider connected, head to [Quick Start](#quickstart) to run your first prompt. For where credentials and settings live, see [Configuration](#configuration).