@globant/coda-darwin-x64 1.3.0 → 1.4.0

package/assets/agents/coda-help.md

@@ -51,6 +51,7 @@ Notation: every entry points to `file.md › § "Exact Heading"`. All files live
 | Where are config / secrets / sessions / logs stored? | `config-reference.md` › § "Config file locations"; `faq.md` › § "Where are my config, sessions, and logs stored?" |
 | Store API keys safely / `${VAR}` / `secretRef` secrets? | `config-json.md` › § "Secrets: keep keys out of the file"; `config-reference.md` › § "Referencing secrets with `${VAR}`" |
 | How do I switch models? | `cli-reference.md` › § "Configuration" (`/switch-model`); `shortcuts.md` › § "Model switching" |
+| How do I copy CODA's response / a past response / test the `/copy` command? | `cli-reference.md` › § "Session management" (`/copy`); shortcut → `shortcuts.md` › § "Transcript navigation" (`Ctrl+Shift+C`) |
 | How do I let bash run everything / change approval level / permission mode (`read-only`/`default`/`auto`, Ctrl+P)? | `permissions.md` › § "Permission modes", § "Where to set it"; headless: § "Approvals in headless (batch) mode" |
 | How do I allow / always-allow / never-allow a command (`propose_policy`, "allow pnpm build")? | `permissions.md` › § "The easy way to change permissions: just ask the agent", § "How `propose_policy` works", § "What you actually approve" |
 | Stop CODA suggesting rule changes / disable `propose_policy` (`permissions.proposePolicy`, `CODA_PROPOSE_POLICY`, `disableProposePolicy`)? | `permissions.md` › § "Turning `propose_policy` off"; `config-reference.md` › § "permissions" |

package/assets/docs/add-mcp-server-skill.md

@@ -0,0 +1,135 @@
+# Configure an MCP Server with CODA
+
+When you ask CODA to add, register, install, or configure an MCP server, it can load the bundled **`configure-mcp`** skill. The skill turns a package name, command, Git repository, local binary, or remote HTTP endpoint into a valid MCP configuration without overwriting your other servers.
+
+## Ask in plain language
+
+Examples:
+
+```text
+Add the Playwright MCP server to this project.
+```
+
+```text
+Configure https://api.example.com/mcp globally. Read its token from API_TOKEN.
+```
+
+```text
+Install the MCP server from this repository and show me the available setup choices: <repository-url>
+```
+
+CODA inspects the input, asks which scope or installation method you want when that is unclear, and writes only after it can derive a valid server transport.
+
+## Choose the scope
+
+| Scope | Configuration file | Use it when |
+| --- | --- | --- |
+| **Project** | `<project>/.coda/mcp.json` | The server belongs to this project and the config should be shared with teammates. |
+| **Global** | `~/.coda/mcp.json` | The server is personal and should be available in every project on this machine. |
+
+If you do not specify a scope, CODA asks. When both scopes contain the same server name, the project definition wins.
+
+## Supported inputs
+
+The bundled skill accepts package names, executable commands, local binaries, Git repositories, and remote HTTP endpoints. A `.zip` archive is not a direct skill input; unpack it first, then point CODA at the extracted command or repository instructions.
+
+### Remote HTTP endpoint
+
+An HTTP MCP server uses `url` and may include headers, a bearer-token reference, a timeout, and environment variables:
+
+```jsonc
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "https://api.example.com/mcp",
+      "authorizationToken": "Bearer ${API_TOKEN}",
+      "headers": { "X-Project": "${PROJECT_ID}" },
+      "timeout": 30
+    }
+  }
+}
+```
+
+### Package, command, or local binary
+
+A local stdio server uses `command` with optional arguments, environment variables, and a working directory:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+Common launchers include `npx`, `uvx`, `node`, and a direct executable path.
+
+### Git repository
+
+A repository can document several installation methods. CODA reads its setup instructions, presents the viable choices, and lets you pick—for example a package launcher, a hosted HTTP endpoint, or a local build. A temporary clone is removed when the selected runtime does not need it.
+
+If no command or URL can be derived, CODA writes nothing and asks you for a package name, executable command, repository, or HTTP endpoint.
+
+## Entry rules
+
+Each server entry must have exactly one transport:
+
+- `command` for a local stdio subprocess; or
+- `url` for Streamable HTTP.
+
+Do not set both. Useful optional fields are:
+
+| Field | Applies to | Purpose |
+| --- | --- | --- |
+| `args` | stdio | Command arguments. |
+| `cwd` | stdio | Working directory for the subprocess. |
+| `env` | both | Environment variables passed to the server. |
+| `headers` | HTTP | Extra request headers. |
+| `authorizationToken` | HTTP | Shorthand for the Authorization header. |
+| `timeout` | HTTP | Request timeout in seconds. |
+
+Session-level overrides can also use `{ "disabled": true }` to switch off a server inherited from a higher scope. For ordinary project/global entries, enable or disable the server from the `/mcp` manager.
+
+## Keep secrets out of the file
+
+Never put a real token or API key directly in `mcp.json`. Use `${VAR}` or `${VAR:-default}` and define the value in your environment, `~/.coda/.secrets`, or a project environment file that is excluded from version control.
+
+For example:
+
+```json
+{
+  "authorizationToken": "Bearer ${GITHUB_TOKEN}"
+}
+```
+
+CODA preserves existing server entries. If the chosen name already exists, it shows the current entry and asks before replacing only that key.
+
+## Activate and verify
+
+After the file is written:
+
+1. Open `/mcp`.
+2. Choose **Reload MCP servers**.
+3. Check the server status and view its discovered tools.
+
+Restarting CODA also loads the change. `/skills refresh` reloads skill definitions; it does not reload MCP connections.
+
+Once the server is connected, describe the task normally. CODA can select its MCP tools when they are relevant, subject to the same authorization rules as other tools.
+
+## Troubleshooting
+
+- **Invalid JSON** — fix the existing file first; CODA does not overwrite malformed configuration.
+- **Duplicate server name** — choose a different name or approve replacement of that one entry.
+- **No transport found** — provide the exact executable command, package name, or HTTP endpoint.
+- **Git setup is ambiguous** — choose one of the installation methods found in the repository documentation.
+- **A credential is required** — provide the environment-variable name, never the secret value in the config.
+- **The server does not appear** — reload it from `/mcp`, then inspect its status and error details.
+
+## See also
+
+- [Extend CODA](#guide-extend) — MCP, skills, extensions, plugins, and workflows.
+- [Configuration](#configuration) — where configuration and secrets live.
+- [Permissions & Approvals](#permissions) — authorization for MCP tool calls.

package/assets/docs/agents.md

@@ -128,7 +128,7 @@ Agent behavior is controlled by the `agents` block in your config (global and/or
 | --- | --- |
 | `agents.enabled` | When `false`, agent tools and the run manager aren't wired up. Default **true** |
 | `agents.maxConcurrent` | Cap on parallel runs (valid range **1–10**). Default **6** |
-| `agents.defaultModel` | Override the inherited model for all delegated runs (optional) |
+| `agents.defaultModel` | Legacy configuration field retained for compatibility; delegated runs now inherit the main session model unless a definition or tool call chooses another model |
 | `agents.fastModel` | Model ID used when a run requests the `"fast"` tier at the agents level (overrides provider value) |
 | `agents.smartModel` | Model ID used when a run requests the `"smart"` tier |
 | `agents.deepModel` | Model ID used when a run requests the `"deep"` tier |

package/assets/docs/cli-reference.md

@@ -10,6 +10,7 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `/new` | Start a fresh session (old one is saved) |
 | `/exit` (alias `/quit`) | Exit CODA; prints `coda --session-id <id>` so you can resume later |
 | `/clear` | Permanently wipe the current session's message history (the session itself stays) |
+| `/copy` (or `/copy N`) | Copy CODA's last response to the clipboard; `/copy N` copies the Nth-most-recent response (assistant messages only). Complements the [`Ctrl+Shift+C`](#shortcuts) shortcut, which copies only the last fenced code block |
 
 ## Files and changes
 
@@ -86,6 +87,7 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `coda --timeout <ms>` | Abort a headless run after the given time |
 | `coda --checkpoints[=true\|false]` | Force checkpoints on or off for this run |
 | `coda --model <name>` / `-m` | Use a specific model for this run |
+| `coda --reasoning-effort <level>` | Set the thinking effort for THIS run only — `none\|minimal\|low\|medium\|high\|xhigh\|max` (case-insensitive). Applied in memory; never written to config. Overrides a persisted `reasoning.effort` at launch and is inherited by subagents. An invalid value fails fast; a level the model can't honor prints a stderr warning and is not applied (no silent fallback) |
 | `coda -e <path>` | Load an extra extension file for this run |
 | `coda --mcp-config <path>` | Point at a specific `mcp.json` for this run |
 | `coda --system-prompt <text>` | Replace the built-in base system prompt for this run |

package/assets/docs/config-json.md

@@ -11,7 +11,7 @@ For a field-by-field table of the most common keys, see [Configuration Reference
 | `~/.coda/config.json` | Your user-global settings (apply in every project) |
 | `<project>/.coda/config.json` | Project overrides (commit to share with the team) |
 
-Settings cascade in priority order: **CLI flags → project config → global config → built-in defaults**. A project file only needs the keys it wants to override; everything else falls back to your global file and then to defaults.
+Most settings cascade in priority order: **CLI flags → project config → global config → built-in defaults**. Permission rules accumulate across scopes, and a project cannot raise the starting permission mode above your user-level default. A project file only needs the keys it wants to change.
 
 > **Every block below is optional.** A real `config.json` only contains the keys you actually set — most commonly `activeProfile` and a `profiles` map (the wizard writes these). The example here is intentionally exhaustive so you can copy the one block you need.
 
@@ -23,12 +23,13 @@ Settings cascade in priority order: **CLI flags → project config → global co
   // This is the ONLY provider config CODA writes to disk. "activeProfile" names
   // the profile currently in use; "profiles" is the map of switchable targets.
   // Both are managed by /providers and /switch-profile — you rarely hand-edit
-  // them. Each profile's "provider" is one of: "glob-ai" | "openai-compat" | "ollama".
+  // them. Each profile's "provider" is one of:
+  // "glob-ai" | "glob-ai-os" | "openai-compat" | "ollama".
   "activeProfile": "geai-oauth",
   "profiles": {
     // Glob.AI OS via OAuth (browser login). Tokens live in the OS keyring, so
-    // no key is stored here. "instance" is a preset ("clients" | "corp" |
-    // "saas-europe") or a custom id (a custom id also needs its own "baseUrl").
+    // no key is stored here. "instance" is a known preset or a custom id;
+    // a custom id also needs its own "baseUrl".
     "geai-oauth": {
       "provider": "glob-ai",
       "label": "Glob.AI OS (OAuth)",
@@ -65,7 +66,8 @@ Settings cascade in priority order: **CLI flags → project config → global co
   // tools). Default 300. Raise for very long autonomous runs; lower to cap cost.
   "maxSteps": 300,
 
-  // Background update check: true (check + notify), false (off), or "notify".
+  // Background update check: true or "notify" checks and notifies; false disables it.
+  // Installation still happens only when you run /upgrade or coda upgrade.
   "autoupdate": "notify",
 
   // Error-recovery posture: "balanced" (default), "conservative", "aggressive".
@@ -106,14 +108,23 @@ Settings cascade in priority order: **CLI flags → project config → global co
   },
 
   // ── Reasoning (thinking) effort ───────────────────────────────────────
-  // effort: "low" | "medium" | "high" | "xhigh" | "max". Per-model support
-  // varies. Change live with /effort.
+  // effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max".
+  // Per-model support varies. Change live with /effort.
+  //
+  // Headless note: the `coda --reasoning-effort <level>` shell flag sets the
+  // effort for a SINGLE run IN MEMORY ONLY — it is deliberately NOT written to
+  // this `reasoning` block, so it never collides with (or clobbers) the
+  // persisted value here. At launch the flag overrides this value for that run;
+  // the file is left exactly as-is, which is what lets two concurrent headless
+  // runs use different efforts without racing on config.json.
   "reasoning": {
     "enabled": true,  // Default: false
     "effort": "medium"
   },
 
-  // ── Compaction (auto context trimming) ────────────────────────────────
+  // ── Compaction (automatic context reduction) ──────────────────────────
+  // When reduction is needed, stale tool output is moved aside first.
+  // threshold controls when older messages may also be summarized.
   "compaction": {
     "enabled": true,
     "threshold": 0.75,
@@ -153,16 +164,14 @@ Settings cascade in priority order: **CLI flags → project config → global co
   },
 
   // ── Vision (examine_images) ───────────────────────────────────────────
-  // A LiteLLM-style model id. Set useMainAgentModel:true to reuse the chat model.
+  // A LiteLLM-style model id. With Ollama, the product-default vision model
+  // follows the main model unless useMainAgentModel is explicitly false.
   "vision": {
     "model": "openai/gpt-5.4"
   },
 
-  // ── Web search tool ───────────────────────────────────────────────────
-  "webSearch": {
-    "provider": "brave",            // "exa" | "brave" | "serper"
-    "apiKey": "${BRAVE_API_KEY}"
-  },
+  // The legacy webSearch block is accepted for compatibility but is not used
+  // by the current Glob.AI OS-backed web_search tool. Leave it out.
 
   // ── Web fetch tool ────────────────────────────────────────────────────
   // Backend priority: the FIRST entry is the primary, the rest are fallbacks.
@@ -205,23 +214,13 @@ Settings cascade in priority order: **CLI flags → project config → global co
   // ── Composer (input area) behavior while CODA is busy ─────────────────
   "composer": {
     "whileBusy": { "delivery": "queue" },   // "queue" | "steer"
-    "queueSteer": { "enabled": true, "defaultMode": "later" }  // defaultMode: "next" | "later"
+    "queueSteer": { "enabled": true }
   },
 
-  // ── MCP servers (inline) ──────────────────────────────────────────────
-  // Optional. You can also declare these in ~/.coda/mcp.json or
-  // <project>/.coda/mcp.json (all tiers are merged). stdio uses command+args;
-  // http uses url. See #tools-reference.
-  "mcp": {
-    "servers": {
-      "github": {
-        "transport": "stdio",
-        "command": "npx",
-        "args": ["-y", "@modelcontextprotocol/server-github"],
-        "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
-      }
-    }
-  },
+  // ── MCP servers ───────────────────────────────────────────────────────
+  // Put active server definitions in ~/.coda/mcp.json or
+  // <project>/.coda/mcp.json. Leave the unused legacy "mcp" config block out.
+  // See #add-mcp-server-skill.
 
   // ── Editor / IDE integration (ACP) ────────────────────────────────────
   "acp": { "enabled": true },
@@ -238,16 +237,15 @@ Settings cascade in priority order: **CLI flags → project config → global co
     "rawViewer": { "enabled": false }
   },
 
-  // ── Telemetry (OpenTelemetry export) ──────────────────────────────────
+  // ── Telemetry (Glob.AI OS platform gateway only) ──────────────────────
+  // The destination is derived from the authenticated provider and cannot be
+  // set here. Use /settings → Telemetry for the normal off/basic/full control.
   "telemetry": {
-    "enabled": false,
-    "exporter": "otlp",
-    "otlpProtocol": "http",         // "http" | "grpc"
-    "otlpHost": "http://localhost:4318",  // collector; omit to use the build default
-    "otlpUseTls": false,          // true for HTTPS/gRPC TLS
-    "serviceName": "coda",        // custom service name in traces
-    "tracesEnabled": true,
-    "metricsEnabled": true
+    "level": "basic",              // "off" | "basic" | "full"
+    "exporter": "otlp",            // or "console" for local diagnostics
+    "otlpProtocol": "http",
+    "otlpUseTls": true,
+    "serviceName": "coda"
   }
 }
 ```
@@ -256,12 +254,12 @@ Settings cascade in priority order: **CLI flags → project config → global co
 
 ## Secrets: keep keys out of the file
 
-Never paste raw API keys into `config.json`. Store them in `~/.coda/.secrets` (dotenv format). API-key profiles reference a secret by **name** via `auth.secretRef`; other blocks (like `webSearch`) use `${VAR}` interpolation:
+Never paste raw API keys into `config.json`. Store them in `~/.coda/.secrets` (dotenv format). API-key profiles reference a secret by **name** via `auth.secretRef`; other compatible string fields use `${VAR}` interpolation:
 
 ```bash
 # ~/.coda/.secrets
 MY_API_KEY=sk-...
-BRAVE_API_KEY=...
+MCP_TOKEN=...
 ```
 
 ```jsonc
@@ -287,15 +285,15 @@ The `.secrets` file is never committed and its values are scrubbed from logs bef
 | --- | --- |
 | Switch the active model | `profiles.<id>.model` (or `/model` live) |
 | Add a provider | A new entry under `profiles` (use `/providers`); API-key ones reference a `secretRef` in `.secrets` |
-| Switch which provider is active | `activeProfile` (or `/switch-profile` / `/sp` live) |
+| Switch which provider is active | `activeProfile`, or `/switch-profile` / `/sp` for the next launch |
 | Switch OAuth ↔ API key | the profile's `auth` block (`{ "method": "oauth" }` vs `{ "method": "apikey", "secretRef": "VAR" }`) |
-| Let commands run more without asking | `permissions.defaultMode: "auto"`, or add `permissions.allow` rules — see [Permissions & Approvals](#permissions) |
+| Let commands run more without asking | Set your user-level `permissions.defaultMode` to `"auto"`, or add narrow `permissions.allow` rules — see [Permissions & Approvals](#permissions) |
 | Change thinking effort | `reasoning.effort` (or `/effort` live) |
 | Cap or widen parallel agents | `agents.maxConcurrent` (1–10) |
 | Turn off a noisy bundled agent | add its name to `agents.disabledDefinitions` |
 | Use the faster search engine | `tools.grep.backend: "fastgrep"` |
 | Set the web-fetch backend priority | `webfetch.order` — e.g. `["client","anthropic"]` (default) or `["anthropic","client"]`; `[]` disables the tool |
-| Add an MCP server | `mcp.servers` here, or `~/.coda/mcp.json` — see [Tools Reference](#tools-reference) |
+| Add an MCP server | `~/.coda/mcp.json` or `<project>/.coda/mcp.json` — see [Configure an MCP Server](#add-mcp-server-skill) |
 | Quiet or verbose logs | `logging.level` / `logging.levels` |
 | Disable update checks | `autoupdate: false` |
 
@@ -310,7 +308,7 @@ A couple of settings are controlled by env vars instead of (or on top of) the fi
 
 ## The legacy `providers` map
 
-Older configs (and the runtime, internally) use a top-level **`provider`** string plus a **`providers`** map keyed by provider *type* (`geai`, `openai-compat`, `ollama`, `openai`, `anthropic`, `google`, `groq`, `openrouter`, `azure`, `vertex`). **CODA no longer writes these to disk** — at launch it derives an equivalent runtime map from your active profile. You don't need to add them by hand.
+Older configs (and the runtime, internally) use a top-level **`provider`** string plus a **`providers`** map keyed by provider *type* (`geai`, `openai-compat`, `ollama`, `openai`, `anthropic`, `google`, `groq`, `openrouter`, `azure`, `vertex`). **CODA no longer writes these to disk** — at launch it derives an equivalent runtime map from your active profile. You don't need to add them by hand. The legacy schema still accepts `vertex`, but Vertex AI cannot run yet.
 
 If you're maintaining a config that still uses the old shape, it continues to work, but migrate to `activeProfile` + `profiles` (run `/providers`) when you can. A legacy entry looks like:
 

package/assets/docs/config-reference.md

@@ -9,7 +9,7 @@ Reference for the most common configuration options. For how to set these up in
 | `~/.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.json` | Project-level settings. Most values override user config; permission rules accumulate and the starting mode can only become more restrictive. |
 | `<project>/.coda/mcp.json` | Project-level MCP servers |
 
 ## activeProfile and profiles
@@ -32,7 +32,7 @@ Each profile has a `provider` type that determines its shape:
     "work": {
       "provider": "glob-ai",
       "label": "Globant Clients",
-      "instance": "clients",       // "clients" | "corp" | "saas-europe" | custom id
+      "instance": "clients",       // known preset or custom id
       "auth": { "method": "oauth" },
       "model": "anthropic/claude-opus-4-8",
       "org": { "id": "org-123", "name": "My Org" },    // set by wizard after login
@@ -46,13 +46,33 @@ Each profile has a `provider` type that determines its shape:
 | --- | --- |
 | `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`. |
+| `instance` | Known presets include `"clients"`, `"corp"`, `"saas-europe"`, `"saas-us"`, and `"beta"`; custom IDs require a `baseUrl`. The normal wizard may show only the environments intended for your setup. |
 | `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 |
-| `strictPin` | When `true`, never auto-heal this profile's model if it's retired on the provider — always ask instead (see "modelResilience" below and [How it works](#how-it-works) › "Error recovery"). Default `false`. |
+| `strictPin` | When `true`, never auto-heal this profile's retired model. Interactive launches already ask through the model picker; this mainly keeps headless/ACP paths from selecting a recommended replacement automatically. Default `false`. |
+
+### `glob-ai-os` profiles (custom Glob.AI OS platform gateway)
+
+Use `glob-ai-os` when your administrator gives you a platform-gateway URL rather than one of the `glob-ai` presets:
+
+```jsonc
+{
+  "profiles": {
+    "my-os": {
+      "provider": "glob-ai-os",
+      "label": "My Glob.AI OS",
+      "baseUrl": "https://identity.example.com",
+      "ingestBaseUrl": "https://gateway.example.com",
+      "auth": { "method": "oauth" }
+    }
+  }
+}
+```
+
+`baseUrl` is required. `ingestBaseUrl`, `signInUrl`, organization/project selections, model, favorite models, and tier models are optional. Telemetry is available only on this platform-gateway profile type.
 
 ### `openai-compat` profiles (any OpenAI-compatible API)
 
@@ -125,13 +145,13 @@ Each entry maps a key (referenced by `provider`) to a typed config block:
 | `groq` | `apiKey` | Groq SDK |
 | `openrouter` | `apiKey` | OpenRouter SDK |
 | `azure` | `resourceName`, `apiKey`, `apiVersion` | Azure OpenAI SDK |
-| `vertex` | project/region config | Google Vertex AI SDK |
+| `vertex` | project/region config | Accepted by the legacy schema, but Vertex AI cannot run yet |
 
 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
+```jsonc
 {
   "providers": {
     "my-api": {
@@ -160,13 +180,9 @@ Applies to Glob.AI OS / Globant OAuth sign-in. The wizard manages these; you rar
 | `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)
+## mcp.json files
 
-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`. |
+Put MCP server entries in `~/.coda/mcp.json` or `<project>/.coda/mcp.json`; session overrides live under `~/.coda/sessions/<sessionId>/mcp.json`. The old inline `mcp.servers` block in `config.json` is accepted for compatibility but no longer controls runtime connections. See [Configure an MCP Server](#add-mcp-server-skill).
 
 ## bash
 
@@ -197,9 +213,9 @@ Admin-only managed-policy lockdown keys (set in a managed policy, not personal c
 
 | 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) |
+| `enabled` | `true` | Enable automatic pre-flight context reduction |
+| `threshold` | `0.75` | Fraction of the conversation budget that permits summary condensation (0.3–0.9). Large, stale tool output can start moving aside at 0.65, or at this threshold when it is lower. |
+| `retainFraction` | `0.3` | Fraction of recent messages kept verbatim when condensation runs (0.1–0.9) |
 
 ## reasoning
 
@@ -210,7 +226,7 @@ Admin-only managed-policy lockdown keys (set in a managed policy, not personal c
 
 ## modelResilience
 
-Controls how CODA heals a configured model that's been retired or renamed on the provider (see [How it works](#how-it-works) › "Error recovery"). A retired model is auto-healed to the closest same-provider/family replacement; per-profile `strictPin` (above) opts out.
+Controls recommendations when a configured model has been retired or renamed (see [How CODA Works](#how-it-works) › "Error recovery"). CODA finds the closest same-provider/family replacement. Interactive sessions open the model picker with that recommendation; headless runs apply it only with `CODA_MODEL_AUTOHEAL=1`, while ACP can use it for the current run. Per-profile `strictPin` opts out of automatic replacement.
 
 | Field | Default | Description |
 | --- | --- | --- |
@@ -247,7 +263,8 @@ Controls how CODA heals a configured model that's been retired or renamed on the
 
 | Field | Description |
 | --- | --- |
-| `vision.model` | Model used by `examine_images` (Glob.AI OS profiles) |
+| `vision.model` | Model used by `examine_images` for Glob.AI OS; Ollama can use this value or follow the main model according to `vision.useMainAgentModel` |
+| `vision.useMainAgentModel` | For Ollama, leave unset/`true` to follow the main model while `vision.model` is still the product default; set `false` to force `vision.model` |
 
 ## webfetch
 
@@ -300,12 +317,7 @@ These exist for power users and rarely need hand-editing. Most can be reached th
 | `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 |
+**`webSearch`** — unused compatibility schema for alternate search backends. Leave it out of normal configs: the built-in `web_search` tool uses the active Glob.AI OS credentials instead.
 
 **`session`** — session auto-rename behavior:
 
@@ -320,8 +332,8 @@ These exist for power users and rarely need hand-editing. Most can be reached th
 | 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) |
+| `composer.queueSteer.enabled` | `true` | Enable queue/steer behavior |
+| `composer.queueSteer.defaultMode` | `"later"` | Legacy input migrated to `whileBusy.delivery`: `"next"` → `"steer"`, `"later"` → `"queue"` |
 
 **`acp`** — agent communication protocol:
 
@@ -329,26 +341,27 @@ These exist for power users and rarely need hand-editing. Most can be reached th
 | --- | --- | --- |
 | `acp.enabled` | `true` | Enable ACP headless mode (`coda --acp`) |
 
-**`autoupdate`** — automatic update behavior: `true` (auto-install), `"notify"` (notify only), or `false` (disable). Default `true`.
+**`autoupdate`** — background update-check behavior: `true` or `"notify"` checks and notifies; `false` disables the check. Updates are installed only when you run `/upgrade` or `coda upgrade`. 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:
+**`telemetry`** — OpenTelemetry export. It is available only when the active Glob.AI OS profile uses the platform gateway; the destination is derived from that authenticated profile and cannot be set in `config.json`:
 
 | 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.level` | `"basic"` on the platform gateway; `"off"` elsewhere | Consent level: `"off"`, `"basic"`, or `"full"`. You can change it under `/settings` → **Telemetry**. |
+| `telemetry.enabled` | Legacy/raw override | Prefer `telemetry.level`. To disable export, set `level: "off"`; do not rely on `enabled: false` alone. |
+| `telemetry.exporter` | `"otlp"` | Exporter: `"otlp"` or `"console"` |
 | `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 |
+| `telemetry.otlpUseTls` | `true` | Use TLS for OTLP export; credentialed cleartext export is refused |
+| `telemetry.serviceName` | `"coda"` | `service.name` reported by the SDK |
+| `telemetry.tracesEnabled` | unset | Advanced override; otherwise follows `telemetry.level` |
+| `telemetry.metricsEnabled` | unset | Advanced override; otherwise follows `telemetry.level` |
+| `telemetry.logsEnabled` | unset | Advanced override; otherwise follows `telemetry.level` |
 
-Settings cascade in priority order: CLI flags override project config, which overrides your global config (see [Configuration](#configuration)).
+Settings normally cascade in priority order: CLI flags override project config, which overrides your global config. Permission rules accumulate across layers, and a project cannot raise the starting permission mode above your user-level default. See [Configuration](#configuration).
 
 ## Referencing secrets with `${VAR}`
 
@@ -368,6 +381,7 @@ Keep keys out of `config.json` by storing them in `~/.coda/.secrets` (dotenv for
 | --- | --- | --- |
 | `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 |
+| `CODA_NPM_REGISTRY` | public npm | HTTPS registry mirror used by native install and upgrade checks/downloads |
 | `CODA_PROPOSE_POLICY` | unset | Overrides `permissions.proposePolicy` without editing config (dev/QA). A truthy value (`1`, `true`, `yes`, `on`) forces it **on**; any other set value (e.g. `0`, `false`, `off`) forces it **off** — so it can override in either direction, winning over config. Blank/unset defers to config (default on). An administrator's `disableProposePolicy` still wins over it. |
 | `CODA_MODEL_AUTOHEAL` | unset | In a headless/batch run, set (e.g. `1`) to let CODA auto-heal a retired model to its recommended replacement instead of exiting non-zero. Interactive runs use the picker and ignore this; a `strictPin` profile is never healed. |
 | `CODA_FETCH_BLOCKED_URLS` | unset | Comma-separated URLs/hosts/extensions the `webfetch` client backend must never fetch (e.g. `competitor.com,tracker.io,.pdf`). Merged with `webfetch.blockedUrls`. |

package/assets/docs/configuration.md

@@ -25,7 +25,7 @@ If you've set up more than one provider (say, two Glob.AI OS instances, or a loc
 
 ## Where settings live
 
-Settings cascade in priority order — project settings override user settings, and CLI flags override everything:
+Most settings cascade in priority order — project settings override user settings, and CLI flags override everything. Permission rules accumulate across scopes, and project config cannot raise the starting permission mode:
 
 | File | What it's for |
 | --- | --- |
@@ -45,37 +45,41 @@ Some settings can be adjusted from the settings panel. Open it from inside CODA:
 /settings
 ```
 
-**Permission mode** — how much CODA runs without asking is set by the session's permission mode: **read-only** (reads only), **default** (asks before risky actions), or **auto** (hands-off). Cycle it with **Ctrl+P**, or set the default with `permissions.defaultMode`. See [Permissions & Approvals](#permissions).
+**Permission mode** — how much CODA runs without asking is set by the session's permission mode: **read-only** (reads only), **default** (asks before risky actions), or **auto** (hands-off). Cycle it with **Ctrl+P**, or set the user default with `permissions.defaultMode` in `~/.coda/config.json`. See [Permissions & Approvals](#permissions).
 
 **Shell** — pick the **shell** CODA uses (`auto`, `bash`, `powershell`, `wsl`, or an explicit path) under **Bash Tool Preferences**. Only shells your host actually has are offered, so you can't select one that won't run (for example, `wsl` doesn't appear off Windows). If a *configured* shell isn't available on this host — say a `config.json` synced from Windows that asks for `wsl` on macOS — CODA neither fails to start nor silently runs a different shell: it falls back to a working shell and shows a banner naming what it's running instead and why, with a pointer to change it. The banner clears the moment you pick a shell that works. Press **Enter** to confirm and close, **Esc** to step back to the menu.
 
-**Compaction** — to keep context fresh, CODA can automatically condense older conversation before it runs out of room. Tune it under **Context Compaction**:
+**Compaction** — to keep context fresh, CODA checks before each model call whether the conversation still fits. When reduction is needed, it can first move stale tool output aside and later condense older conversation at the configured threshold. 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.
+- **Enable / disable** — turn automatic reduction on or off. With it off, you can still compact on demand with `/compact`.
+- **Threshold** — how full the context can get before summary condensation begins. Large, stale tool output can start moving aside at **65%** of the conversation budget (or at your lower condensation threshold).
 - **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**.
 
+**Autonomy** — enable or tune `/goal` and `/loop`, including goal judging and loop duration limits.
+
+**Telemetry** — on an authenticated Glob.AI OS platform-gateway profile, choose **Off**, **Basic**, or **Full**. Basic sends operational metadata without prompt bodies; Full also permits redacted prompt text. Other provider types keep telemetry off.
+
 ## 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`** — project overrides.
+3. **`<project>/.coda/config.json`** — project overrides, except that a project cannot raise the starting permission mode above your user-level default.
 4. **CLI flags** — `--model`, `--profile`, `--auto-approve` (headless), and friends, for a single run.
 
-So a project can set the permission mode (`permissions.defaultMode`) for everyone who clones it, and a headless run can override the approval posture with `--auto-approve none|all` — without editing any file.
+A project can make the starting permission mode more restrictive for everyone who clones it, but it cannot silently raise autonomy. For a one-off headless run, `--auto-approve none|all` chooses fail-closed default mode or unattended auto mode without editing a 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 `permissions.defaultMode` (e.g. `"auto"`) in a project config affects every teammate — see [Collaborate with Your Team](#guide-collaborate).
+- **Think twice:** pinning the active `provider` or shared permission rules affects teammates. A project `permissions.defaultMode` can tighten their starting mode, but it cannot raise autonomy above their user-level default — see [Collaborate with Your Team](#guide-collaborate).
 
 ## A minimal `config.json`
 

package/assets/docs/connect-provider.md

@@ -81,9 +81,9 @@ coda configure \
 | Flag | Purpose |
 | --- | --- |
 | `--profile-name NAME` | Profile ID in `~/.coda/config.json` (required) |
-| `--provider PROVIDER` | `glob-ai` \| `openai-compat` \| `ollama` (required) |
-| `--instance INSTANCE` | glob-ai only: `clients` \| `corp` \| `saas-europe` (default: `clients`) |
-| `--base-url URL` | Required for `openai-compat`; optional for `ollama` |
+| `--provider PROVIDER` | `glob-ai` \| `glob-ai-os` \| `openai-compat` \| `ollama` (required) |
+| `--instance INSTANCE` | `glob-ai` only: `clients` \| `corp` \| `saas-europe`, or a custom name with `--base-url` (default: `clients`) |
+| `--base-url URL` | Required for `openai-compat` and `glob-ai-os`, for a custom `glob-ai` instance, and optional for `ollama` |
 | `--api-key KEY` | Pass key on the command line (appears in shell history — prefer `--api-key-stdin`) |
 | `--api-key-stdin` | Read key from stdin — safe for scripts and CI |
 | `--force` | Overwrite an existing profile and rotate its API key |