@globant/coda-windows-x64-baseline 1.3.0 → 1.5.0

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,16 +23,19 @@ 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 what you connect to: "glob-ai" (any
+  // Glob.AI instance), "openai-compat" or "ollama". For a Glob.AI instance,
+  // Coda records "glob-ai" or "glob-ai-os" itself, from the instance's preset
+  // or from what the endpoint answers when the profile is created.
   "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").
+    // Glob.AI via OAuth (browser login). Tokens live in the OS keyring, so
+    // 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)",
-      "instance": "saas-europe",
+      "label": "Glob.AI (OAuth)",
+      "instance": "eu-v1",
       "auth": { "method": "oauth" },
       "model": "anthropic/claude-opus-4-8",
       // Optional per-tier models for the agents "fast"/"smart"/"deep" shortcuts:
@@ -40,7 +43,7 @@ Settings cascade in priority order: **CLI flags → project config → global co
       "smartModel": "anthropic/claude-sonnet-4",
       "deepModel": "anthropic/claude-opus-4-8"
     },
-    // Any OpenAI-compatible HTTP API. Key is resolved from ~/.coda/.secrets via secretRef.
+    // Any OpenAI-compatible HTTP API. Key is resolved from the credential store (system keychain, or an encrypted secrets file) via secretRef, falling back to the process environment.
     "my-compat": {
       "provider": "openai-compat",
       "label": "My OpenAI-compat server",
@@ -65,7 +68,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".
@@ -77,7 +81,7 @@ Settings cascade in priority order: **CLI flags → project config → global co
   // don't add them by hand; the profiles above are the source of truth. See
   // "The legacy providers map" below if you're maintaining an old config.
 
-  // ── Authentication preferences (Glob.AI OS) ─────────────────────────────────
+  // ── Authentication preferences (Glob.AI) ─────────────────────────────────
   "auth": {
     // Prefer OAuth access tokens or a static API key.
     "methodPreference": "access_token",
@@ -93,7 +97,10 @@ Settings cascade in priority order: **CLI flags → project config → global co
   },
 
   // ── Permissions (the authorization engine) ────────────────────────────
-  // defaultMode: the session's starting permission mode.
+  // defaultMode: the interactive session's starting permission mode. When
+  //   unset: "auto" only if no `permissions` block exists anywhere, otherwise
+  //   "default" (a managed disableAutoMode policy still forces "default").
+  //   Headless `coda -p` ignores it and follows --auto-approve.
   //   "read-only" (reads only) | "default" (asks for risky) | "auto" (hands-off).
   // allow/ask/deny: rule strings; deny always wins (deny-first).
   // additionalDirectories: extra roots treated as "in project" for edits/writes.
@@ -106,14 +113,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 +169,15 @@ 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.
+  // Optional — omit to use the built-in default vision model. Set it only to
+  // pick a different LiteLLM-style model id. With Ollama and no override,
+  // vision follows the main model unless useMainAgentModel is false.
   "vision": {
-    "model": "openai/gpt-5.4"
+    "model": "google/gemini-3-pro"
   },
 
-  // ── 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-backed web_search tool. Leave it out.
 
   // ── Web fetch tool ────────────────────────────────────────────────────
   // Backend priority: the FIRST entry is the primary, the rest are fallbacks.
@@ -181,10 +196,21 @@ Settings cascade in priority order: **CLI flags → project config → global co
   // Paths to extension modules (in addition to auto-discovered .coda/extensions).
   "extensions": ["./.coda/extensions/my-tool.ts"],
 
-  // ── Skills tuning ─────────────────────────────────────────────────────
+  // ── Skills tuning + discovery sources ─────────────────────────────────
   "skills": {
     "descriptionMaxChars": 200,
-    "warnThreshold": 100
+    "warnThreshold": 100,
+    // Which external-agent skill directories to scan. `.coda/skills` is
+    // native and always on. Foreign sources are off by default.
+    "sources": {
+      "agents": true,    // .agents/skills (cross-tool)
+      "claude": false,   // .claude/skills
+      "codex": false,    // .codex/skills
+      "opencode": false  // .opencode/skills
+    },
+    // Extra skill roots. Absolute paths apply at both scopes; relative
+    // paths resolve under the project. Unioned across global + project.
+    "paths": []
   },
 
   // ── Checkpoints (file snapshots / undo) ───────────────────────────────
@@ -205,23 +231,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 +254,13 @@ Settings cascade in priority order: **CLI flags → project config → global co
     "rawViewer": { "enabled": false }
   },
 
-  // ── Telemetry (OpenTelemetry export) ──────────────────────────────────
+  // ── Telemetry (Glob.AI 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
+    "otlpUseTls": true
   }
 }
 ```
@@ -256,12 +269,11 @@ 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`. Add them through the `/providers` wizard (or `echo "$KEY" | coda configure --provider … --api-key-stdin`) — the key is stored in your system keychain (or an encrypted secrets file where there is no keychain), never in the config. API-key profiles reference the stored secret by **name** via `auth.secretRef`; other compatible string fields use `${VAR}` interpolation, resolved from a project `.coda/.env` or `.env` file, then `~/.coda/.secrets`, then your process environment:
 
 ```bash
-# ~/.coda/.secrets
-MY_API_KEY=sk-...
-BRAVE_API_KEY=...
+# <project>/.coda/.env  (or ~/.coda/.secrets for global values)
+MCP_TOKEN=...
 ```
 
 ```jsonc
@@ -279,23 +291,25 @@ BRAVE_API_KEY=...
 }
 ```
 
-The `.secrets` file is never committed and its values are scrubbed from logs before anything is written to disk.
+Log redaction scrubs secret-shaped values (tokens, keys, credentials) from logs by pattern before anything is written to disk — regardless of where a value is stored.
 
 ## Common edits, by goal
 
 | You want to… | Edit |
 | --- | --- |
 | 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) |
+| Add a provider | A new entry under `profiles` (use `/providers`); API-key ones reference a `secretRef` resolved from the credential store, falling back to a shell-exported environment variable of the same name |
+| 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) |
+| Import skills from another agent (Claude/Codex/OpenCode) | Turn on the matching flag under `skills.sources`, or run `coda skills enable <source> --global\|--project` — see [Extend CODA](#guide-extend) |
+| Scan an extra skills folder | Add it to `skills.paths`, or run `coda skills add-path <dir> --global\|--project` |
 | Quiet or verbose logs | `logging.level` / `logging.levels` |
 | Disable update checks | `autoupdate: false` |
 
@@ -310,7 +324,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

@@ -7,9 +7,9 @@ Reference for the most common configuration options. For how to set these up in
 | File | Purpose |
 | --- | --- |
 | `~/.coda/config.json` | User-global settings |
-| `~/.coda/.secrets` | API keys (dotenv format, never commit) |
+| `~/.coda/.secrets` | Marker file for generic `${VAR}` values (never commit) — API keys entered via `/providers` live in your system keychain (or an encrypted secrets file); on a host without an OS keyring, legacy keys already present here are left in plaintext rather than migrated |
 | `~/.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
@@ -23,7 +23,7 @@ Reference for the most common configuration options. For how to set these up in
 
 Each profile has a `provider` type that determines its shape:
 
-### `glob-ai` profiles (Glob.AI OS / Globant)
+### `glob-ai` profiles (Glob.AI / Globant)
 
 ```jsonc
 {
@@ -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
@@ -44,15 +44,35 @@ Each profile has a `provider` type that determines its shape:
 
 | Field | Description |
 | --- | --- |
-| `provider` | Must be `"glob-ai"` |
+| `provider` | `"glob-ai"`, written by Coda; a platform instance stores `"glob-ai-os"` instead (next section) |
 | `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` | The Glob.AI instance this profile uses, such as `"eu-v1"` or `"clients"`; `coda configure --help` prints the ids on offer. The former ids `"saas-europe"` and `"saas-us"` are still accepted, as aliases of `"eu-v1"` and `"us-v1"`. An instance's id is accepted whichever provider type serves it, in a `glob-ai` or a `glob-ai-os` profile. A custom id needs a `baseUrl`, because it names no endpoint; a profile with neither a known id nor a `baseUrl` is refused when a run uses it. |
 | `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 platform gateway)
+
+A profile for a Glob.AI platform instance stores `"provider": "glob-ai-os"`. You do not choose this value: Coda writes it when it creates the profile, because the instance's preset, or the endpoint itself, tells it how the instance signs in and which API it speaks. For a known instance, name it with `coda configure --instance <id>`; for an endpoint your administrator gives you, run `coda configure --base-url <url>`, and Coda contacts the endpoint to confirm it is a Glob.AI instance and learn how it signs in before anything is written (see [Connect a Provider](#connect-provider)). Such a profile looks like this:
+
+```jsonc
+{
+  "profiles": {
+    "my-os": {
+      "provider": "glob-ai-os",
+      "label": "My Glob.AI",
+      "baseUrl": "https://identity.example.com",
+      "ingestBaseUrl": "https://gateway.example.com",
+      "auth": { "method": "oauth" }
+    }
+  }
+}
+```
+
+The fields are the same as for a `glob-ai` profile. A profile names its instance with `instance`, `baseUrl`, or both; an entry you write by hand for an endpoint no instance id names needs `baseUrl`. `ingestBaseUrl` (the inference host, which must be on the same domain as `baseUrl`), `signInUrl`, organization/project selections, model, favorite models, tier models and `strictPin` are optional. Telemetry is available only on a platform instance.
 
 ### `openai-compat` profiles (any OpenAI-compatible API)
 
@@ -116,7 +136,7 @@ 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 |
+| `geai` | `baseUrl`, `apiKey` (or OAuth) | Glob.AI 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 |
@@ -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}`:
+Keep secrets out of `config.json`. Provider API keys added through `/providers` (or `coda configure --api-key-stdin`) live in your system keychain (or an encrypted secrets file where there is no keychain) — never in the config. For other string fields you can reference generic values with `${VAR}` interpolation, resolved from a project `.coda/.env` or `.env` file, then `~/.coda/.secrets`, then your process environment:
 
-```json
+```jsonc
 {
   "providers": {
     "my-api": {
@@ -149,9 +169,9 @@ Keep secrets out of `config.json` — store them in `~/.coda/.secrets` (dotenv f
 | --- | --- |
 | `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)
+## auth (Glob.AI login preferences)
 
-Applies to Glob.AI OS / Globant OAuth sign-in. The wizard manages these; you rarely edit them by hand.
+Applies to Glob.AI / Globant OAuth sign-in. The wizard manages these; you rarely edit them by hand.
 
 | Field | Default | Description |
 | --- | --- | --- |
@@ -160,13 +180,13 @@ 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`:
+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).
 
-| 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`. |
+**Denying a single MCP tool still allows reading its schema.** A rule naming an inner tool — `deny mcp__hub__delete_all` — blocks *executing* that tool. It does not block `mcp_describe`, which returns the tool's parameters and nothing else; the tool's name is already visible in the prompt listing. To hide a server's tools entirely, deny the server (`deny mcp__hub`), which covers every MCP surface including `mcp_describe`.
+
+**Large catalogs are listed compactly.** A small MCP catalog is listed in the system prompt in full (each tool's description and parameters). Once the combined listing grows large, CODA lists tools by name and the first sentence of their description, and the model calls `mcp_describe` to fetch a tool's full schema on demand before calling it with `mcp_execute`. Compaction is applied **per server, largest first**: only as many servers as needed to fit the budget are compacted, so a small server keeps its full inline parameters even when a large one alongside it is condensed. This keeps the prompt small without losing any tool.
 
 ## bash
 
@@ -182,7 +202,7 @@ The authorization engine's config. Rule strings use the `Tool(specifier)` form (
 
 | Field | Default | Description |
 | --- | --- | --- |
-| `defaultMode` | `"default"` | Starting permission mode: `"read-only"` (reads only), `"default"` (asks for risky actions), `"auto"` (hands-off; only the un-relaxable floor + managed deny refuse) |
+| `defaultMode` | `"auto"` / `"default"` | Starting permission mode: `"read-only"` (reads only), `"default"` (asks for risky actions), `"auto"` (hands-off; only the un-relaxable floor + managed deny refuse). The unset default depends on the config: `"auto"` **only when there is no `permissions` block at all** (a truly-fresh config); if a `permissions` block exists but omits `defaultMode`, the mode is `"default"` (compatibility exception — an existing partially-configured user is not silently escalated). A managed `disableAutoMode` policy still coerces `"auto"` back to `"default"`. |
 | `allow` | `[]` | Rules that always run without asking |
 | `ask` | `[]` | Rules that always prompt |
 | `deny` | `[]` | Rules that are always refused (wins over `allow`) |
@@ -197,20 +217,20 @@ 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
 
 | 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: `"none"`, `"minimal"`, `"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 (support is discovered dynamically for models not in the built-in list). |
+| `reasoning.effort` | `"medium"` | Thinking effort level: `"none"`, `"minimal"`, `"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. On the Glob.AI OS2 gateway the valid levels come live from the model catalog; on OS1 they come from a built-in table. |
 
 ## 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 |
 | --- | --- | --- |
@@ -222,6 +242,8 @@ Controls how CODA heals a configured model that's been retired or renamed on the
 | --- | --- | --- |
 | `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 |
+| `lazyTools` | `true` | On-demand tool loading. When on, only core tools (`bash`, `read`, `write`, `edit`, `grep`, `glob`, `background_output`, `ask_user`) plus the `skills`, `mcp_execute`, `mcp_describe`, and `load_tool` gateways are advertised each turn; other tools are listed by name in the system prompt and their full schema is loaded on demand when the model calls `load_tool`. Shrinks per-turn token use. Set `false` to always advertise every tool. |
+| `costReport` | `false` | When `true`, each session writes a cost/token breakdown to `~/.coda/logs/cost-report-<sessionId>.md`, separating user turns from billed model steps and reporting per-step section estimates, cache usage and USD. Off by default; only writes a report, never changes model behavior. |
 | `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`. |
@@ -229,6 +251,8 @@ Controls how CODA heals a configured model that's been retired or renamed on the
 | `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 |
+| `onboarding.suggestInitRules` | `true` | When `true`, and you have **no `allow` rules in either your project or global config**, CODA offers to run the **`/init-rules`** skill (a Yes/No prompt shown after your first message, on the chat screen). It isn't offered when rule proposals are turned off (`permissions.proposePolicy: false` or a managed policy). Set `false` to never be asked. |
+| `onboarding.initRulesPromptDismissed` | `false` | Set automatically when you answer **No** / dismiss that prompt, so it won't reappear. You normally don't edit this by hand. |
 | `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. |
@@ -245,9 +269,20 @@ Controls how CODA heals a configured model that's been retired or renamed on the
 
 ## vision
 
+Optional. Omit it to use CODA's built-in default vision model, currently
+`openai/gpt-5.4`. The default ships with CODA and may change between
+releases. CODA never writes a `vision` block into your `config.json`: set
+`vision.model` only when you want a different model. A project
+`.coda/config.json` value wins over the global one.
+
+In a project `.coda/config.json`, omitting `vision` or writing `"vision": {}`
+keeps the global value, while `"vision": null` resets it to the built-in
+default even when the global config sets one.
+
 | Field | Description |
 | --- | --- |
-| `vision.model` | Model used by `examine_images` (Glob.AI OS profiles) |
+| `vision.model` | Optional override for the model used by `examine_images` (LiteLLM-style id, e.g. `google/gemini-3-pro`). Omit to use the built-in default. 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
 
@@ -255,7 +290,7 @@ Configures the `webfetch` tool (fetch a web page by URL). See [Tools Reference](
 
 | Field | Default | Description |
 | --- | --- | --- |
-| `webfetch.order` | `["client", "anthropic"]` | Backend preference order (first is primary, rest are fallbacks). `"client"` = the local SSRF-hardened fetch (always available); `"anthropic"` = a fixed-model server-side fetch (parses PDFs; needs a Glob.AI OS profile). Use `["client"]`, `["anthropic"]`, or `[]` to **disable** the tool. |
+| `webfetch.order` | `["client", "anthropic"]` | Backend preference order (first is primary, rest are fallbacks). `"client"` = the local SSRF-hardened fetch (always available); `"anthropic"` = a fixed-model server-side fetch (parses PDFs; needs a Glob.AI profile). Use `["client"]`, `["anthropic"]`, or `[]` to **disable** the tool. |
 | `webfetch.blockedUrls` | — | URLs/hosts/extensions never fetched (client backend). Merged with `CODA_FETCH_BLOCKED_URLS`. |
 | `webfetch.allowedHosts` | — | Strict host allowlist (client backend) — when set, only these hosts and subdomains may be fetched. |
 | `webfetch.requireProvenance` | `true` | Only fetch URLs that already appeared in the conversation (your messages / prior tool results), not model-invented ones. Set `false` to opt out. |
@@ -278,6 +313,13 @@ Disable the tool entirely with `webfetch.order: []`, or via a `permissions.deny:
 | --- | --- | --- |
 | `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 |
+| `skills.sources.agents` | `true` | Scan the cross-tool `.agents/skills` directory (project and `~/.agents/skills`) |
+| `skills.sources.claude` | `false` | Import skills from Claude's `.claude/skills` (project and `$CLAUDE_CONFIG_DIR`/`~/.claude`) — opt-in |
+| `skills.sources.codex` | `false` | Import skills from Codex's `.codex/skills` (project and `$CODEX_HOME`/`~/.codex`) — opt-in |
+| `skills.sources.opencode` | `false` | Import skills from OpenCode's `.opencode/skills` (project and `~/.opencode`) — opt-in |
+| `skills.paths` | `[]` | Extra skill roots to scan. Absolute paths apply at both scopes; relative paths resolve under the project. Unioned across global + project (project-first) |
+
+CODA's own `.coda/skills` (project and `~/.coda/skills`) is native and always scanned — there is no toggle for it. Foreign sources are **off by default**, so upgrading changes nothing until you opt in. Discovery scans project roots before global ones, and dedupes so the same skill file reached from several roots appears once (a name collision across different files is won by the higher-tier source: `coda` > `agents` > `claude` > `codex` > `opencode` > `paths`). Toggle sources from the `/settings → Skills` screen or the headless `coda skills` sub-command; changes apply on the next launch.
 
 ## logging
 
@@ -300,12 +342,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 credentials instead.
 
 **`session`** — session auto-rename behavior:
 
@@ -320,8 +357,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,33 +366,44 @@ 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 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.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.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"` (prints spans, metrics and logs locally) |
+| `telemetry.otlpUseTls` | `true` | Use TLS for OTLP export; credentialed cleartext export is refused |
+| `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` |
+
+The producer identity is not configurable: `service.name` is always `coda`, `service.version` is the CLI version, and the employee id and email come from your login. Older `telemetry.serviceName`, `telemetry.serviceVersion` and `telemetry.employeeId` keys are ignored, as is `telemetry.otlpProtocol` (export is always OTLP over HTTP).
+
+**`sessionActivity`** — lists your CODA sessions on the glob.ai-os **Session Activity** screen. Available only on the platform gateway, set in the **global** config only (a project config cannot change it), and off whenever `telemetry.level` is `"off"`. You can change it under `/settings` → **Session Activity**, which also shows the active session's platform conversation id:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `sessionActivity.enabled` | `true` | Report sessions (metered usage, a conversation per session, and each finished turn). |
+| `sessionActivity.transcript` | `"auto"` | `"auto"` sends prompt/reply text, and a title based on your first prompt, only when `telemetry.level` is `"full"` and your organization allows prompt logging. `"off"` always sends status and tool names only, with a neutral title. |
+| `sessionActivity.mode` | `"report"` | `"report"` records each turn when it finishes, with its status. `"live"` mirrors messages while the turn runs, but the platform then cannot show a turn's failed/cancelled status or count errors. |
+
+Whether Session Activity is on follows the profile CODA was **started** with. After `/switch-profile` to or from the gateway, or into a project whose organization turned telemetry off, restart CODA for the change to apply. Turns not delivered before exit are kept and resent on a later start — only to the same platform instance they were recorded on.
 
-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}`
 
-Keep keys out of `config.json` by storing them in `~/.coda/.secrets` (dotenv format) and referencing them with `${VAR}` interpolation:
+Keep keys out of `config.json`. Provider API keys added through `/providers` (or `coda configure --api-key-stdin`) live in your system keychain (or an encrypted secrets file where there is no keychain) — never in the config. For other string fields, reference generic values with `${VAR}` interpolation:
 
 ```jsonc
-// ~/.coda/.secrets
+// <project>/.coda/.env  (or ~/.coda/.secrets for global values)
 // GEAI_API_KEY=sk-...
 
 // ~/.coda/config.json
@@ -367,9 +415,12 @@ Keep keys out of `config.json` by storing them in `~/.coda/.secrets` (dotenv for
 | 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_CLIENT_VIA` | unset | Set by an app that starts CODA (a launcher) to name itself, such as `stepwise`. Sent to the Glob.AI platform gateway and on telemetry as `globant.client_via`. Read only from the environment CODA was started with, never from `~/.coda/.secrets`. |
+| `OTEL_RESOURCE_ATTRIBUTES` | unset | OpenTelemetry `key=value` labels a launcher adds to CODA's telemetry, such as `stepwise.run_id=r-42`. A key needs a namespace of its own; reserved namespaces (`service`, `globant`, `host`, …) are dropped, and `~/.coda/logs/coda.log` names each dropped key. See the telemetry docs, "Resource attributes". |
 | `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`. |
 | `CODA_WEBFETCH_MODEL` | `anthropic/claude-sonnet-4-6` | Fixed model used by the `webfetch` `anthropic` backend (independent of your session model). |
-| `CODA_WEBFETCH_BASE_URL` / `CODA_WEBFETCH_API_KEY` / `CODA_WEBFETCH_PROJECT_ID` | unset | Explicit Glob.AI OS credentials that enable the `webfetch` `anthropic` backend even in a non-GEAI session (e.g. to fetch PDFs). `PROJECT_ID` is optional; the backend is active only when both base URL and API key are set. |
+| `CODA_WEBFETCH_BASE_URL` / `CODA_WEBFETCH_API_KEY` / `CODA_WEBFETCH_PROJECT_ID` | unset | Explicit Glob.AI credentials that enable the `webfetch` `anthropic` backend even in a non-GEAI session (e.g. to fetch PDFs). `PROJECT_ID` is optional; the backend is active only when both base URL and API key are set. |