@globant/coda-darwin-x64 1.2.0 → 1.4.0

package/assets/docs/config-json.md

@@ -10,9 +10,8 @@ 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) |
-| `<project>/coda.config.ts` | TypeScript config — takes priority over JSON if present |
 
-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.
 
@@ -24,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)",
@@ -66,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".
@@ -107,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,
@@ -154,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.
@@ -206,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 },
@@ -239,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"
   }
 }
 ```
@@ -257,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
@@ -288,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` |
 
@@ -311,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,8 +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.ts` | TypeScript config (takes priority) |
+| `<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
@@ -33,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
@@ -47,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)
 
@@ -126,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": {
@@ -161,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
 
@@ -198,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
 
@@ -211,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 |
 | --- | --- | --- |
@@ -232,6 +247,7 @@ Controls how CODA heals a configured model that's been retired or renamed on the
 | `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). |
+| `errorHandling.streamIdleTimeoutMs` | posture-derived (`240000` for `balanced`) | Streaming inactivity timeout in milliseconds: the max gap between successive stream chunks before the request is aborted. Overrides the posture default. Raise it further (e.g. `360000`) for reasoning-heavy models or large-context turns that legitimately go silent while the model produces its first token. A non-positive value disables the idle timeout. |
 
 ## tools
 
@@ -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,14 +25,13 @@ 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 |
 | --- | --- |
 | `~/.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) |
@@ -46,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`** (or `<project>/coda.config.ts`, which replaces it) — 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 |

package/assets/docs/extensions.md

@@ -23,7 +23,7 @@ The rest of this page is a **reference** for when you want to understand what CO
 
 An extension is a TypeScript file that exports an `activate` (or `default`) function receiving the `ExtensionAPI`. It lives in `.coda/extensions/` (project) or `~/.coda/extensions/` (global) — no configuration needed.
 
-```typescript
+```ts
 import { z, type ExtensionAPI, type AgentTool, type ToolContext } from "@globant/coda-core";
 
 export default function activate(api: ExtensionAPI): void {
@@ -41,16 +41,16 @@ Extensions are auto-discovered, highest priority first:
 | --- | --- | --- |
 | 1 | `.coda/extensions/*.ts` | Project-level (highest) |
 | 2 | `~/.coda/extensions/*.ts` | User-global |
-| 3 | `config.json` → `extensions[]` | Configured paths |
-| 4 | `-e ./path.ts` | CLI flag |
+| 3 | `config.json` → `extensions[]`, including any `-e ./path.ts` values merged by the CLI | Configured or one-run paths |
+| 4 | Enabled plugin extension directories | Plugin-provided |
 
-Subdirectory extensions are also discovered. For a folder, CODA resolves the entry file in this order: `package.json` `coda.extensions` → `package.json` `main` → `main.ts` → `<folder-name>.ts` → `index.ts` / `index.js`. To see what's loaded, run `/extensions` inside CODA.
+Duplicate resolved paths are loaded once, preserving the first source in this order. Within the combined `extensions[]` list, configured paths appear before `-e` paths. Subdirectory extensions are also discovered. For a folder, CODA resolves the entry file in this order: `package.json` `coda.extensions` → `package.json` `main` → `main.ts` → `<folder-name>.ts` → `index.ts` / `index.js`. To see what's loaded, run `/extensions` inside CODA.
 
 ## Registering a tool
 
 Tools are functions the agent can call. Use Zod for the parameter schema.
 
-```typescript
+```ts
 const myTool: AgentTool<MyParams, string> = {
   name: "my_tool",
   description: "Clear description of what the tool does and when to use it",
@@ -88,7 +88,7 @@ Inside `execute`, the `ToolContext` gives you what you need:
 
 Commands are invoked by the user as `/name args`.
 
-```typescript
+```ts
 api.registerCommand("deploy", {
   description: "Deploy the application to staging or production",
   getArgumentCompletions: (prefix) => {
@@ -136,15 +136,15 @@ The handler context (`ExtensionCommandContext`) lets you drive the session:
 
 ```text
 model, models, clear, compact, exit, help, mcp, providers, settings,
-skills, agents, extensions, plugin, plugins, reload-plugins,
-init, timeline, rewind, checkpoint-status
+skills, agents, extensions, plugin, plugins, reload-plugins, usage,
+permissions, init, timeline, rewind, checkpoint-status
 ```
 
 ## Subscribing to lifecycle hooks
 
 Hooks let you react to (or modify) what CODA does at key moments.
 
-```typescript
+```ts
 api.on("session_start", async ({ sessionId }) => {
   console.error("Session started:", sessionId);
 });
@@ -169,20 +169,15 @@ api.on("context", async (context) => {
 | `tool_result` | `ToolResultEvent` | Modify a tool result |
 | `session_before_compact` | — | Before compaction (return `{ cancel: true }` to cancel) |
 | `session_compact` | — | After compaction completes |
-| `session_before_switch` | `{ sessionId }` | Before switching to a different session |
-| `session_switch` | `{ sessionId }` | After a session switch completes |
 | `session_before_fork` | `{ entryId }` | Before forking from a timeline entry |
 | `session_fork` | `{ sessionId }` | After a fork completes |
-| `session_before_tree` | — | Before the session tree is traversed |
-| `session_tree` | — | After the session tree traversal |
-| `message_start` | `MessageEvent` | When a new message begins streaming |
 | `message_update` | `MessageEvent` | On each incremental message update |
-| `message_end` | `MessageEvent` | When a message finishes streaming |
 | `tool_execution_start` | `ToolExecutionEvent` | When a tool starts executing |
 | `tool_execution_update` | `ToolExecutionEvent` | On tool execution progress update |
 | `tool_execution_end` | `ToolExecutionEvent` | When a tool finishes executing |
-| `resources_discover` | — | When CODA discovers extension resources |
-| `user_bash` | `UserBashEvent` | When the user runs a shell command via the bash tool |
+| `resources_discover` | `{ cwd, reason }` | At session start. Returned resource paths are currently diagnostic only. |
+
+The API type also reserves `session_before_switch`, `session_switch`, `session_before_tree`, `session_tree`, `message_start`, `message_end`, and `user_bash`, but the current CLI/runtime does not emit them. Do not depend on those names until they are wired.
 
 > **`context` hook — important invariant:** The `context` payload also contains a `messageIds` field — a parallel array to `messages` where `messageIds[i]` is the DB row id for `messages[i]` (or `null` for synthetic messages). The invariant `messages.length === messageIds.length` is load-bearing. If your hook appends, inserts, or reorders `payload.messages`, you **must** apply the same operation to `payload.messageIds`, pushing `null` for synthetic entries.
 
@@ -190,23 +185,25 @@ The `input` hook returns one of three actions to control the message: `{ action:
 
 ## Intercepting tool calls
 
-Use the `tool_call` hook to block dangerous commands or rewrite inputs before they run:
+Use the `tool_call` hook to return an authorization decision or rewrite the input before policy is evaluated:
 
-```typescript
+```ts
 api.on("tool_call", async ({ toolName, input }) => {
-  if (toolName === "bash" && input.command?.includes("rm -rf /")) {
-    return { deny: true, reason: "Blocked destructive command" };
+  if (toolName === "bash" && input.command?.startsWith("deploy ")) {
+    return { decision: "ask", reason: "Confirm deployment command" };
   }
 });
 ```
 
-The hook can return `{ deny: true, reason }` to cancel the call with an error, or `{ block: true, reason }` to pause it and wait for explicit user approval before proceeding. Returning nothing (or `undefined`) lets the call proceed normally.
+Return `decision: "allow"`, `"ask"`, or `"deny"`, with an optional `reason`. You can also return `updatedInput`; CODA sends that rewritten input back through the authorization engine before execution. Returning nothing lets normal policy decide.
+
+> **Migrating an older extension:** legacy `{ deny: true }` and `{ block: true }` responses are still accepted, but both now mean `deny`. If you previously used `{ block: true }` to ask the user, return `{ decision: "ask" }` instead.
 
 ## Registering shortcuts, providers, and flags
 
 Beyond tools, commands, and hooks, an extension can register a few other surfaces (all optional):
 
-```typescript
+```ts
 // A keyboard shortcut (CLI only). Pick a key that isn't reserved (see below).
 api.registerShortcut?.("ctrl+k", {
   description: "Run my action",
@@ -237,20 +234,20 @@ api.registerMessageRenderer?.("my-custom-type", (entry) => {
 });
 ```
 
-**Reserved shortcuts** — extensions can't override these: `escape`, `ctrl+b`, `ctrl+c`, `ctrl+g`, `ctrl+l`, `ctrl+o`, `ctrl+u`, `ctrl+d`, `ctrl+up`, `ctrl+down`, `ctrl+j`, `ctrl+shift+c`.
+**Reserved shortcuts** — extensions can't override these: `escape`, `ctrl+b`, `ctrl+c`, `ctrl+g`, `ctrl+l`, `ctrl+o`, `ctrl+u`, `ctrl+d`, `ctrl+up`, `ctrl+down`, `ctrl+j`, `ctrl+p`, `ctrl+shift+c`. `Ctrl+Up` / `Ctrl+Down` scroll the transcript; `Ctrl+U` / `Ctrl+D` remain reserved for conventional input behavior rather than scrolling.
 
 ## Loading, testing, and reloading
 
 - **Drop-in load.** Save your `.ts` file under `.coda/extensions/` (project) or `~/.coda/extensions/` (global) and CODA picks it up on the next launch — no registration step.
 - **Verify it loaded.** Run `/extensions list` inside CODA to confirm your extension is active and see the tools and commands it registered; `/extensions guide` prints API help.
-- **Iterate quickly.** If your extension is bundled with plugins, `/reload-plugins` re-reads them after you change the files on disk. Otherwise, relaunch CODA to reload a standalone extension file.
+- **Iterate quickly.** If your extension is bundled with a plugin, `/reload-plugins` starts a fresh session with plugins reloaded. Restart the CLI after changing a standalone extension file.
 - **Try one for a single run.** Pass `-e ./path/to/extension.ts` on the command line to load an extra extension just for that session — useful while developing.
 
 ## Tips for good extensions
 
 - **Write tool descriptions for the model, not the user.** Lead with a CAPS category, say *when* to pick this tool over alternatives, and include a short parameter example. CODA chooses tools from these descriptions.
 - **Respect cancellation.** Honor `context.signal` in long-running tool work so **Esc** can interrupt cleanly.
-- **Ask before doing harm.** Route risky actions through `context.hitl` so they go through the same approval flow as built-in tools.
+- **Let policy own general tool safety.** Extension tools pass through the same authorization engine as built-ins. Use a `tool_call` decision for policy-like `ask` or `deny` behavior. Use `context.hitl.requestAnswer(...)` when the tool genuinely needs a user choice—such as selecting a deployment target—and `context.hitl.requestApproval(...)` only for a separate, tool-specific confirmation that policy cannot express.
 - **Use `context.operations`** for file and shell access instead of importing Node APIs directly — it's the supported, sandbox-aware path.
 
 ## See also