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

package/assets/docs/config-reference.md

@@ -7,7 +7,7 @@ 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 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 |
@@ -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
 {
@@ -44,9 +44,9 @@ 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` | 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. |
+| `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) |
@@ -54,16 +54,16 @@ Each profile has a `provider` type that determines its shape:
 | `fastModel` / `smartModel` / `deepModel` | Model IDs for the `"fast"`, `"smart"`, and `"deep"` agent shortcut tiers |
 | `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)
+### `glob-ai-os` profiles (custom Glob.AI platform gateway)
 
-Use `glob-ai-os` when your administrator gives you a platform-gateway URL rather than one of the `glob-ai` presets:
+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 OS",
+      "label": "My Glob.AI",
       "baseUrl": "https://identity.example.com",
       "ingestBaseUrl": "https://gateway.example.com",
       "auth": { "method": "oauth" }
@@ -72,7 +72,7 @@ Use `glob-ai-os` when your administrator gives you a platform-gateway URL rather
 }
 ```
 
-`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.
+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)
 
@@ -136,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 |
@@ -149,7 +149,7 @@ Each entry maps a key (referenced by `provider`) to a typed config block:
 
 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:
 
 ```jsonc
 {
@@ -169,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 |
 | --- | --- | --- |
@@ -184,6 +184,10 @@ Applies to Glob.AI OS / Globant OAuth sign-in. The wizard manages these; you rar
 
 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).
 
+**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
 
 | Field | Default | Description |
@@ -198,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`) |
@@ -222,7 +226,7 @@ Admin-only managed-policy lockdown keys (set in a managed policy, not personal c
 | 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
 
@@ -238,6 +242,8 @@ Controls recommendations when a configured model has been retired or renamed (se
 | --- | --- | --- |
 | `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`. |
@@ -245,6 +251,8 @@ Controls recommendations when a configured model has been retired or renamed (se
 | `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. |
@@ -261,9 +269,19 @@ Controls recommendations when a configured model has been retired or renamed (se
 
 ## 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` for Glob.AI OS; Ollama can use this value or follow the main model according to `vision.useMainAgentModel` |
+| `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
@@ -272,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. |
@@ -295,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
 
@@ -317,7 +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`** — 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.
+**`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:
 
@@ -347,28 +372,38 @@ These exist for power users and rarely need hand-editing. Most can be reached th
 
 **`reasoning`** — effort/thinking controls for reasoning-capable models.
 
-**`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`:
+**`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.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.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.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` |
 
+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 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
@@ -380,10 +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. |

package/assets/docs/configuration.md

@@ -4,12 +4,9 @@ CODA is configured from within the tool itself — you normally don't edit files
 
 ## Connect a provider
 
-You don't need to run any command to get your first provider. The very first time you launch CODA, a setup wizard appears automatically and walks you through it:
+You don't need to run any command to get your first provider. The very first time you launch CODA, it creates a profile for the default Glob.AI instance (SaaS Europe, unless your install command chose another), names it, and asks you for one credential — a browser sign-in, or an API key for a key-only instance. No setup screen comes before it.
 
-- **Pick a Glob.AI OS environment** — Clients, Corp, SaaS Europe, and so on.
-- **Choose how to authenticate** — **OAuth (recommended)**, which signs you in through your browser, or an **API key**.
-
-For a step-by-step walkthrough of that flow — including OAuth vs API key and custom providers — see [Connect a Provider](#connect-provider). API keys are stored in `~/.coda/.secrets`, separate from config and never committed to Git.
+For what that first run does, how to pick another instance, and how custom providers are set up — see [Connect a Provider](#connect-provider). API keys are stored in your system keychain (or an encrypted secrets file), separate from config and never committed to Git.
 
 To **add another provider or edit an existing one** later, open the wizard again from inside CODA:
 
@@ -21,7 +18,7 @@ The same wizard is available from your terminal with `coda --reconfigure`.
 
 ## Switch between providers
 
-If you've set up more than one provider (say, two Glob.AI OS instances, or a local Ollama for testing), switch between them right from the UI with `/providers` — no config files to edit.
+If you've set up more than one provider (say, two Glob.AI instances, or a local Ollama for testing), switch between them right from the UI with `/providers` — no config files to edit.
 
 ## Where settings live
 
@@ -30,12 +27,12 @@ Most settings cascade in priority order — project settings override user setti
 | File | What it's for |
 | --- | --- |
 | `~/.coda/config.json` | Your personal defaults — provider, model, theme |
-| `~/.coda/.secrets` | API keys and credentials (never commit this) |
+| `~/.coda/.secrets` | Marker file for generic `${VAR}` values (never commit this) — 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 |
 | `<project>/.coda/config.json` | Project-level overrides (safe to commit if no secrets) |
 | `~/.coda/mcp.json` | MCP servers available in all your projects |
 | `<project>/.coda/mcp.json` | MCP servers for this project only |
 | `~/.coda/sessions/<id>/mcp.json` | Per-session MCP overrides (written by `/mcp` commands within a session) |
-| `<project>/.coda/.env` or `<project>/.env` | Project-level secrets for `${VAR}` interpolation (merged with `~/.coda/.secrets`) |
+| `<project>/.coda/.env` or `<project>/.env` | Project-level values for `${VAR}` interpolation (merged with `~/.coda/.secrets`). Only the first of the two is read; `.env.local`, `.env.development` and similar files are not loaded, so export those variables in your shell instead |
 
 ## Common settings to change
 
@@ -45,7 +42,9 @@ 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 user default with `permissions.defaultMode` in `~/.coda/config.json`. 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). A truly-fresh config (no `permissions` block at all) starts in **auto**; if a `permissions` block already exists but sets no `defaultMode`, sessions start in **default** instead, so an existing partially-configured setup is never silently escalated. A managed policy can still force **default**. Cycle it with **Ctrl+P**, or set the user default with `permissions.defaultMode` in `~/.coda/config.json`. See [Permissions & Approvals](#permissions).
+
+> If you have **no allow rules configured** in either your project or global config, CODA offers to run the **`/init-rules`** skill to set up `allow`/`ask`/`deny` rules for auto mode. The Yes/No prompt appears **after your first message** (on the chat screen), not on the home screen. Answer **No** to dismiss it, or set `onboarding.suggestInitRules: false` to never be asked.
 
 **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.
 
@@ -58,11 +57,23 @@ Some settings can be adjusted from the settings panel. Open it from inside CODA:
 
 **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**.
+**Theme** — switch the look of the UI under **UI Theme**: `classic` and `modern` (dark), `light`, `solarized`, `nord` and `high-contrast` (black/white with saturated accents, for low-vision setups). Also settable with `"theme": "<name>"` in `config.json`.
+
+**Autonomy** — tune `/goal` and `/loop`, including goal judging and loop duration limits. Both commands are **on by default**: rather than making you enable them, CODA warns you before each autonomous run that unattended turns can consume tokens quickly, and every warning lets you choose "don't show this again" (saved per command — silencing `/goal` leaves `/loop`'s warning on). Set `"autonomy": { "enabled": false }` to turn the commands off entirely.
+
+**Format after every edit** — run `coda hooks install-format` in a project to add a `PostToolUse` hook that formats/lints each file CODA writes or edits with the project's own formatter (biome, prettier, ruff, gofmt, rustfmt — detected from the config files) and feeds any problems back to the model, which fixes them before moving on. It is a plain hook entry in `.coda/config.json`, so you can edit or remove it like any other.
+
+**Git auto-commit** — with `"git": { "autoCommit": true }` every completed turn that changed files ends with a commit of exactly those files, titled `coda: <your prompt>` (`autoCommitPrefix` changes the prefix). Step-by-step history on top of checkpoints; use `/commit` for an on-demand Conventional Commits message instead.
+
+**Notifications** — get a system notification (OSC 9, works in iTerm2, WezTerm, Ghostty, Kitty and Windows Terminal) plus a terminal bell when CODA needs an approval or an answer, or when a long turn finishes. Off by default; enable it in `~/.coda/config.json`:
+
+```json
+{ "notifications": { "enabled": true, "bell": true, "onComplete": true, "command": "apprise -b" } }
+```
 
-**Autonomy** — enable or tune `/goal` and `/loop`, including goal judging and loop duration limits.
+`command` is optional: it runs for every notification with a JSON payload (`kind`, `title`, `message`, `sessionId`) on stdin, so routing to Slack, Apprise or `say` is one line.
 
-**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.
+**Telemetry** — on an authenticated Glob.AI 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
 
@@ -99,6 +110,6 @@ You rarely write this by hand, but it helps to know the shape:
 
 > **Note:** The older `"provider"` key is still accepted for backward compatibility but `activeProfile` + `profiles` is the current mechanism used by the wizard and `/switch-profile`.
 
-API keys are *not* in here — they live in `~/.coda/.secrets` in dotenv format and can be referenced from config with `${VAR}` interpolation.
+API keys are *not* in here — they live in your system keychain (or an encrypted secrets file where there is no keychain), separate from config and never committed to Git. `~/.coda/.secrets` is primarily a marker file and a home for generic `${VAR}` values: any plaintext `CODA_*_API_KEY` lines found in it are moved into the credential store at launch **when a real OS keyring is available**. On keychain-less hosts (headless Linux, CI, Docker, WSL, macOS-over-SSH) migration is skipped and legacy keys stay in `.secrets`, kept at `0600` permissions.
 
 See the full [Configuration Reference](#config-reference) for every available option, or [config.json — A Complete Example](#config-json) for one annotated file showing every block in context.

package/assets/docs/connect-provider.md

@@ -1,35 +1,37 @@
 # Connect a Provider
 
-The first time you launch CODA — before you can run a prompt — a setup wizard (titled **CODA setup**) walks you through connecting a **provider**: the AI backend CODA talks to. This page explains each choice so you land on the right one. You can reopen the wizard later — see **Reconfigure** below.
+The first time you launch CODA it asks you for one thing: a credential. It names the Glob.AI instance it will use — **Glob.AI (Europe)** (`eu-v1`) unless an instance was chosen for you at install time — opens your browser to sign in there, and stores the session for you. There is no configuration screen to get through. To use another instance, or a custom, OpenAI-compatible or Ollama **provider** (the AI backend CODA talks to), see below.
 
-## Step 1 — Choose how to connect
+## What the first run does
 
-- **Glob.AI OS (Globant environments)** — what most people at Globant want.
-- **Custom provider** — an OpenAI-compatible endpoint, or a local [Ollama](https://ollama.com) server.
+1. **Names the instance.** With no profile on the machine, CODA creates one for the default instance and shows its name on the sign-in dialog. If the install command carried an instance, that is the one it names.
+2. **Asks for the credential.** For an instance with browser login (`eu-v1`, `clients`) it opens your browser; sign in with your account, and if you have more than one project assigned you'll be asked to **select your organization and project**. For a key-only instance (`corp`, `us-v1`) it shows a single **API key** prompt naming the instance and where to get a key — paste or type the key (the input is hidden) and press **Enter**.
+3. **That's it.** The profile is written to `~/.coda/config.json` and made active; the session or key lives in your system keychain (or an encrypted secrets file where there is no keychain), never in the config.
 
-## Step 2 — Pick a Glob.AI OS environment
+If your account lives on a different instance, the sign-in fails there. Run `coda --instance <id>` to use another instance for one run, or `coda configure --instance <id>` to make it your default — CODA names the new profile after the instance, or the next free name (`<id>-2`) when that one is taken. For an instance without browser login (`corp`, `us-v1`) the key comes with the command, because there is no sign-in step to ask for it later: `echo "$KEY" | coda configure --instance us-v1 --api-key-stdin`. `coda --help` lists the accepted ids.
 
-> **Note:** The environment picker (this step) only appears when you launch `coda --globant`. Running plain `coda` skips the picker and defaults directly to **SaaS Europe**.
+## Choosing an instance yourself
 
-Pick your environment: **Clients**, **Corp** (API key only — no browser OAuth), or **SaaS Europe**.
+- `coda --instance us-v1` runs against the US instance for that run only — nothing on disk changes.
+- `coda configure --instance <id>` creates a profile for that instance and makes it active; for an instance with browser login, the next run asks for its credential there. For a key-only instance the key comes with the command: `echo "$KEY" | coda configure --instance us-v1 --api-key-stdin`.
+- `coda --reconfigure` opens the setup wizard (titled **CODA setup**): pick **Glob.AI (Globant environments)**, then an instance — **Glob.AI (Europe)** (`eu-v1`), **Glob.AI (US)** (`us-v1`, API key only) — then how to authenticate: **Login (OAuth browser)** or **API Key**. The wizard also sets up a custom provider (next section).
 
-## Step 3 — Authenticate
+The ids earlier releases used, `saas-us` and `saas-europe`, still resolve, to `us-v1` and `eu-v1` respectively. Globant-internal runs (`coda --globant`) are also offered **Glob.AI (Clients)** (`clients`) and **Glob.AI (Corp)** (`corp`, API key only).
 
-- **OAuth (recommended)** — CODA opens your browser, you sign in with your Globant account, and the session is stored for you. No keys to copy or rotate. Back in CODA, if you have more than one project assigned in that environment, you'll be asked to **select your organization and project** so CODA knows which workspace to use.
-- **API Key** — paste or type your key (the input is hidden), then press **Enter**. Key-only environments skip straight here.
-
-API keys are stored in `~/.coda/.secrets`, separate from your config and never committed to Git.
+API keys are stored in your system keychain (or an encrypted secrets file on systems without one), separate from your config and never committed to Git.
 
 ## Custom provider
 
 If you picked **Custom provider**, choose the type:
 
 - **OpenAI-compatible** — enter a profile name, the base URL, and an API key.
-- **Ollama** — point CODA at your local server (no API key needed). The default endpoint is `http://127.0.0.1:11434/v1`. For a copy-paste `config.json` example, see [Configuration Reference](#config-reference).
+- **Ollama** — point CODA at your local server (no API key needed). Leave the URL empty for the default, `http://127.0.0.1:11434/v1`; CODA adds the `/v1` path when you leave it out, so `http://127.0.0.1:11434` works too. For a copy-paste `config.json` example, see [Configuration Reference](#config-reference).
+
+Custom providers are set up through the wizard (`coda --reconfigure`, or `/providers` inside a session) or with `coda configure` (below); the first run never asks about them.
 
 ## Switch between configured providers
 
-Each provider you set up is stored as a named **profile** (in the `profiles` map of `~/.coda/config.json`), and one of them is marked **active** via the top-level `activeProfile` key. The active profile decides which backend — and, for Glob.AI OS, which environment, organization, and project — CODA talks to.
+Each provider you set up is stored as a named **profile** (in the `profiles` map of `~/.coda/config.json`), and one of them is marked **active** via the top-level `activeProfile` key. The active profile decides which backend — and, for Glob.AI, which instance, organization, and project — CODA talks to.
 
 Once you have more than one profile configured, switch between them quickly with **`/switch-profile`** (alias **`/sp`**):
 
@@ -37,13 +39,13 @@ Once you have more than one profile configured, switch between them quickly with
 /switch-profile              # opens the profile picker
 ```
 
-`/switch-profile` only chooses among profiles you've **already configured** — it doesn't add or edit them. It saves your choice as `activeProfile` and reports `Active profile "…" set — applies on next launch`; the switch takes effect the next time you start CODA (there's no live re-target of the current session).
+`/switch-profile` only chooses among profiles you've **already configured** — it doesn't add or edit them. It saves your choice as `activeProfile`. When the session is idle, the switch applies to it right away and CODA reports `Switched to profile "…"`. While a response is still running, CODA leaves the current session alone, because the switch would change the backend under that response, and reports `Active profile "…" set — applies on next launch`.
 
 To **add, edit, or remove** a profile instead of just selecting one, use `/providers` (see [Reconfigure](#reconfigure)).
 
-## Switching the active Glob.AI OS project
+## Switching the active Glob.AI project
 
-If you authenticated with OAuth and your account has more than one project in the chosen environment, CODA asks you to select an **organization and project** during setup. To change that selection later without re-running the whole wizard, use `/project` inside a session — it switches the active Glob.AI OS project (OAuth only).
+If you authenticated with OAuth and your account has more than one project on the chosen instance, CODA asks you to select an **organization and project** during setup. To change that selection later without re-running the whole wizard, use `/project` inside a session — it switches the active Glob.AI project (OAuth only).
 
 ## Check who you're signed in as
 
@@ -53,7 +55,7 @@ To confirm the current authentication state from inside a session:
 /auth-status     (alias /whoami)
 ```
 
-It shows the active provider, environment, and — for OAuth — the signed-in identity and selected project. To sign out of a Glob.AI OS session, run `/logout`.
+It shows the active profile and — for OAuth — the signed-in identity and selected project. To sign out of a Glob.AI session, run `/logout`.
 
 ## Non-interactive setup (`coda configure`)
 
@@ -72,7 +74,7 @@ echo "$API_KEY" | coda configure \
 
 # Local Ollama (no API key needed)
 coda configure \
-  --provider ollama --base-url http://localhost:11434 \
+  --provider ollama --base-url http://127.0.0.1:11434 \
   --profile-name local
 ```
 
@@ -80,33 +82,34 @@ coda configure \
 
 | Flag | Purpose |
 | --- | --- |
-| `--profile-name NAME` | Profile ID in `~/.coda/config.json` (required) |
-| `--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` |
+| `--profile-name NAME` | Profile ID in `~/.coda/config.json`. Omitted: named after the instance, the endpoint's host, or the provider; when that name is taken, the next free one (`eu-2`). A name you pass that is already taken is refused unless you add `--force`. Required with `--force` |
+| `--provider PROVIDER` | `glob-ai` (the default: any Glob.AI instance) \| `openai-compat` \| `ollama`. Omitted with `--force`: the provider of the profile it overwrites |
+| `--instance INSTANCE` | Any instance `coda configure --help` lists, or a custom name with `--base-url`. Omitted: the active profile's instance, else the declared default |
+| `--base-url URL` | Required for `openai-compat`. For a Glob.AI instance, CODA contacts an endpoint no instance declares to confirm it is a Glob.AI instance before writing anything; if it cannot, nothing is written and the message says what to do next (check the URL, or use `--provider openai-compat` for an endpoint that is not a Glob.AI instance). With a known `--instance` it pins that instance to the endpoint; with `--force` it moves the profile there. An endpoint without browser login, or a known instance pinned to another URL, needs `--api-key` or `--api-key-stdin`, because browser login applies only to an instance's own endpoint. Optional for `ollama`, which defaults to the local server |
 | `--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 |
+| `--force` | Overwrite an existing profile and rotate its API key. Without `--provider`, the profile keeps its provider and endpoint unless `--base-url` replaces it |
 | `--no-activate` | Write the profile without changing `activeProfile` |
 
 API keys are stored in the system keychain (or an encrypted secrets file on systems without a keychain). They are never written in plain text to `config.json`. Run `coda configure --help` for the full reference and exit codes.
 
 ## Reconfigure
 
-To re-authenticate within an active session (e.g. after an OAuth session expires), run `/login` — it re-initiates browser OAuth without reopening the full wizard. For first-time provider setup or editing an existing provider, use `/providers` inside a session (changes take effect after a restart) or `coda --reconfigure` from your terminal. Use `/providers` to switch between configured providers anytime — the provider you configure or select there becomes the **active** one. `coda --reconfigure` edits a provider's settings *without* changing which provider is active.
+To re-authenticate within an active session (e.g. after an OAuth session expires), run `/login` — it re-initiates browser OAuth without reopening the full wizard. To add a provider or edit an existing one, use `/providers` inside a session or `coda --reconfigure` from your terminal. Both open the same wizard, and the provider you configure or select there becomes the **active** one. Inside a session, a save that only changes the Glob.AI project of the active profile applies right away; any other change applies after a restart, and CODA says so (`Restart CODA to load it`). `coda --reconfigure` exits when the wizard closes, so the next launch uses the change.
 
-You can configure **more than one provider** and keep them side by side — for example a Glob.AI OS environment for day-to-day work and a local Ollama for offline testing. `/providers` lets you add, edit, remove, and switch between them. If you only want to *change which configured profile is active* (not add or edit one), `/switch-profile` (alias `/sp`) is the quicker path — see [Switch between configured providers](#switch-between-configured-providers). Either way, the change applies after a restart.
+You can configure **more than one provider** and keep them side by side — for example a Glob.AI instance for day-to-day work and a local Ollama for offline testing. `/providers` lets you add, edit, remove, and switch between them. If you only want to *change which configured profile is active* (not add or edit one), `/switch-profile` (alias `/sp`) is the quicker path, and it applies to an idle session right away — see [Switch between configured providers](#switch-between-configured-providers).
 
-### Switch a Glob.AI OS provider between OAuth and API key
+### Switch a Glob.AI profile between OAuth and API key
 
-To change *how* you authenticate to the same environment — say, move from a pasted API key to browser OAuth, or the reverse — reopen the wizard with `/providers` (or `coda --reconfigure`), select that environment again, and pick the other authentication method. CODA replaces the stored credential: an OAuth session is captured for you, or a new key is written to `~/.coda/.secrets`. The change takes effect after a restart. To drop the current credential entirely, `/logout` signs out of the active Glob.AI OS session.
+To change *how* you authenticate to the same instance — say, move from a pasted API key to browser OAuth, or the reverse — reopen the wizard with `/providers` (or `coda --reconfigure`), select that instance again, and pick the other authentication method. CODA replaces the stored credential: an OAuth session is captured for you, or a new key is stored in your system keychain (or the encrypted secrets file where there is no keychain). The change takes effect after a restart. To drop the current credential entirely, `/logout` signs out of the active Glob.AI session.
 
 ## Troubleshooting
 
 - **The browser didn't open during OAuth** — copy the URL CODA prints and open it manually. Once you finish signing in, the session is captured automatically.
-- **"No project found" after OAuth** — your account may not be assigned to a project in that environment. Pick a different environment, or use `/project` after sign-in to select one.
-- **A key stopped working** — re-run `/providers` (or `coda --reconfigure`) and paste a fresh key. Keys live in `~/.coda/.secrets`; rotating one there is enough.
-- **Changes to `/providers` didn't take effect** — provider changes apply after a restart. Exit and relaunch CODA.
+- **"No project found" after OAuth** — your account may not be assigned to a project on that instance. Pick a different instance, or use `/project` after sign-in to select one.
+- **A key was never entered** — CODA shows the API-key prompt on the next launch.
+- **A key stopped working** — re-run `/providers` (or `coda --reconfigure`) and paste a fresh key. Keys live in your system keychain (or the encrypted secrets file); rotating one there is enough.
+- **Changes to `/providers` didn't take effect** — only a change of Glob.AI project applies in the session; other provider changes apply after a restart. Exit and relaunch CODA.
 
 ## What's next
 

package/assets/docs/extensions.md

@@ -160,8 +160,8 @@ api.on("context", async (context) => {
 | `session_start` / `session_end` | `{ sessionId }` | After session creation / when it ends |
 | `session_shutdown` | `{}` | Process exit — flush buffers |
 | `before_agent_start` | `{ text, sessionId }` | Before the agent loop |
-| `agent_start` / `agent_end` | `{ turnId }` | Agent loop boundaries |
-| `turn_start` / `turn_end` | `{ turnId }` | Per-LLM-turn boundaries |
+| `agent_start` / `agent_end` | `{ turnId }`; `agent_end` also carries `breakReason?` and `finalReply?` | Agent loop boundaries. `finalReply` is the loop's committed final answer (absent when there is none) |
+| `turn_start` / `turn_end` | `{ turnId }`; `turn_end` also carries `outcome?` | Per-LLM-turn boundaries. `outcome` is `committed` or `discarded` — a discarded turn (for example, one an automatic retry replaced) should be dropped by an extension that assembles text from `message_update` |
 | `context` | `{ systemPrompt, messages, tools }` | Mutate before each LLM call |
 | `input` | `InputEvent` | Transform user input before send |
 | `model_select` | `{ model }` | After `setModel()` switches the active model |