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

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,21 +18,21 @@ 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
 
-Settings cascade in priority order — project settings override user settings, and CLI flags override everything:
+Most settings cascade in priority order — project settings override user settings, and CLI flags override everything. Permission rules accumulate across scopes, and project config cannot raise the starting permission mode:
 
 | File | What it's for |
 | --- | --- |
 | `~/.coda/config.json` | Your personal defaults — provider, model, theme |
-| `~/.coda/.secrets` | API keys and credentials (never commit this) |
+| `~/.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,20 +42,38 @@ Some settings can be adjusted from the settings panel. Open it from inside CODA:
 /settings
 ```
 
-**Permission mode** — how much CODA runs without asking is set by the session's permission mode: **read-only** (reads only), **default** (asks before risky actions), or **auto** (hands-off). Cycle it with **Ctrl+P**, or set the default with `permissions.defaultMode`. See [Permissions & Approvals](#permissions).
+**Permission mode** — how much CODA runs without asking is set by the session's permission mode: **read-only** (reads only), **default** (asks before risky actions), or **auto** (hands-off). 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.
 
-**Compaction** — to keep context fresh, CODA can automatically condense older conversation before it runs out of room. Tune it under **Context Compaction**:
+**Compaction** — to keep context fresh, CODA checks before each model call whether the conversation still fits. When reduction is needed, it can first move stale tool output aside and later condense older conversation at the configured threshold. Tune it under **Context Compaction**:
 
 - **Scope** — apply your changes globally or to the current project (project overrides global).
-- **Enable / disable** — turn automatic compaction on or off. With it off, you can still compact on demand with `/compact`.
-- **Threshold** — how full the context can get (as a percentage) before CODA condenses.
+- **Enable / disable** — turn automatic reduction on or off. With it off, you can still compact on demand with `/compact`.
+- **Threshold** — how full the context can get before summary condensation begins. Large, stale tool output can start moving aside at **65%** of the conversation budget (or at your lower condensation threshold).
 - **Retain fraction** — how much of the most recent conversation is kept intact when condensing; older messages are summarized.
 
 **Chat input** — choose what happens when you send a message while CODA is already working: **Queue message** waits until the current turn finishes (default), while **Steer message** sends your message as the next input to guide the active flow. In `/settings`, this appears under **Composer**. See [Make Changes Safely](#guide-changes) for details.
 
-**Theme** — switch the look of the UI between `classic` and `modern` under **UI Theme**.
+**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" } }
+```
+
+`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 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
 
@@ -66,16 +81,16 @@ When the same key is set in more than one place, the most specific wins. From lo
 
 1. **Built-in defaults** — what CODA ships with.
 2. **`~/.coda/config.json`** — your personal, machine-wide settings.
-3. **`<project>/.coda/config.json`** — project overrides.
+3. **`<project>/.coda/config.json`** — project overrides, except that a project cannot raise the starting permission mode above your user-level default.
 4. **CLI flags** — `--model`, `--profile`, `--auto-approve` (headless), and friends, for a single run.
 
-So a project can set the permission mode (`permissions.defaultMode`) for everyone who clones it, and a headless run can override the approval posture with `--auto-approve none|all` — without editing any file.
+A project can make the starting permission mode more restrictive for everyone who clones it, but it cannot silently raise autonomy. For a one-off headless run, `--auto-approve none|all` chooses fail-closed default mode or unattended auto mode without editing a file.
 
 ## What's safe to commit
 
 - **Commit:** `<project>/.coda/config.json` (no secrets), `<project>/.coda/mcp.json`, `AGENTS.md`, shared skills/agents/workflows.
 - **Never commit:** `~/.coda/.secrets` (it lives in your home directory, not the repo) and your personal `~/.coda/config.json`.
-- **Think twice:** pinning the active `provider` or an elevated `permissions.defaultMode` (e.g. `"auto"`) in a project config affects every teammate — see [Collaborate with Your Team](#guide-collaborate).
+- **Think twice:** pinning the active `provider` or shared permission rules affects teammates. A project `permissions.defaultMode` can tighten their starting mode, but it cannot raise autonomy above their user-level default — see [Collaborate with Your Team](#guide-collaborate).
 
 ## A minimal `config.json`
 
@@ -95,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` \| `openai-compat` \| `ollama` (required) |
-| `--instance INSTANCE` | glob-ai only: `clients` \| `corp` \| `saas-europe` (default: `clients`) |
-| `--base-url URL` | Required for `openai-compat`; optional for `ollama` |
+| `--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

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

package/assets/docs/faq.md

@@ -12,7 +12,7 @@ coda --version
 
 ### How do I add or change a provider?
 
-From your terminal (outside a session): `coda --reconfigure`. From inside an active session: `/providers`. Note that `/providers` changes require restarting CODA to take effect.
+From your terminal (outside a session): `coda --reconfigure`. From inside an active session: `/providers`. Both open the same wizard, and the provider you configure there becomes the active one. A `/providers` save that only changes the Glob.AI project applies right away; other changes need a restart of CODA to take effect.
 
 ### How do I set up two projects (e.g. two Clients projects) and switch between them?
 
@@ -20,7 +20,7 @@ Configure each one as its own profile, then switch with `/switch-profile`:
 
 1. Run `/providers` and sign in to the first Clients project (OAuth or API key). CODA saves it as a named profile.
 2. Run `/providers` again and sign in to the **second** Clients project. Because it's a different organization/project, CODA stores it as a **separate** profile rather than overwriting the first.
-3. From then on, flip between them with `/switch-profile` (alias `/sp`) — no argument opens a picker, or pass the profile id directly (`/switch-profile geai-clients`). The switch is saved as `activeProfile` and applies on the next launch.
+3. From then on, flip between them with `/switch-profile` (alias `/sp`) — no argument opens a picker, or pass the profile id directly (`/switch-profile geai-clients`). The switch is saved as `activeProfile` and applies to the session right away when it is idle; while a response is running, it applies on the next launch.
 
 Use `/switch-profile` when you only want to change which configured profile is active; use `/providers` to add, edit, or remove one. See [Connect a Provider](#connect-provider) › "Switch between configured providers".
 
@@ -28,10 +28,10 @@ Use `/switch-profile` when you only want to change which configured profile is a
 
 You have two options:
 
-- **Stay in the session** — run `/project` (Glob.AI OS OAuth only). It lists the organizations and projects your account can access; pick one, or run `/project <id>` directly. This re-targets the active project without a restart. See [Connect a Provider](#connect-provider) › "Switching the active Glob.AI OS project".
-- **Switch profiles** — if you've configured the other project as its own profile (see above), `/switch-profile` selects it instead. That change applies on the next launch.
+- **Stay in the session** — run `/project` (Glob.AI OAuth only). It lists the organizations and projects your account can access; pick one, or run `/project <id>` directly. This re-targets the active project without a restart. See [Connect a Provider](#connect-provider) › "Switching the active Glob.AI project".
+- **Switch profiles** — if you've configured the other project as its own profile (see above), `/switch-profile` selects it instead. That change applies right away when the session is idle, else on the next launch.
 
-Reach for `/project` for a quick in-session project change on the same login; use `/switch-profile` to move between separately configured profiles (which may also differ in environment or auth method).
+Reach for `/project` for a quick in-session project change on the same login; use `/switch-profile` to move between separately configured profiles (which may also differ in instance or auth method).
 
 ### How do I run CODA in batch mode, and how does it authenticate?
 
@@ -45,9 +45,9 @@ By default a batch run uses your **active profile** (`activeProfile` from `~/.co
 
 You can't start an interactive **OAuth browser login** in batch mode — there's no browser to hand off to. For headless OAuth, reuse a profile you already authenticated interactively (`--profile <id>` or the active profile). To provide credentials inline for a one-off run without saving them, use the ephemeral flags — for example `--provider openai-compat --base-url … --api-key …`, or `--provider glob-ai --instance clients --api-key …`. The key is held only in memory and never written to disk. See [Automate with headless mode](#guide-automate) › "Authenticating in batch mode".
 
-### CODA opened and immediately shows a setup wizard. Is that normal?
+### CODA opened and immediately asked me to sign in. Is that normal?
 
-Yes. The wizard appears automatically on first launch if no provider is configured. Follow the prompts to add your credentials. You can also trigger it manually at any time with `coda --reconfigure`.
+Yes. On first launch, with no provider configured, CODA picks the default Glob.AI instance, names it, and asks for its credential — a browser sign-in, or an API key for a key-only instance. That is the whole setup. If your account lives on another instance, run `coda --instance <id>` for one run or `coda configure --instance <id>` to change your default (with `--api-key-stdin` for a key-only instance such as `corp` or `us-v1`). The full setup wizard is still there for other providers: `coda --reconfigure`.
 
 ### How do I get help from inside CODA?
 
@@ -59,13 +59,21 @@ A few ways: type `/help` for the command list, press `?` for the keyboard-shortc
 
 Use `coda --lastsession` to resume the most recent session. For a specific session, use `coda --session-id <id>` — when you exit, CODA prints the exact `coda --session-id <id>` command, ready to copy and paste. From inside CODA, browse sessions with `/sessions`.
 
+### CODA won't start: "its schema differs from what this CODA version needs"
+
+Every time it starts, CODA checks the session database (`~/.coda/coda.db`) and repairs what it safely can on its own. If something can't be repaired — for example the file was changed by a development build, restored from an old backup, or edited by hand — CODA stops before writing anything, lists each problem, and says "Nothing was modified". Either open the database with the CODA version that last used it, or start over with a new session history: close every CODA window, back up the database, and move `coda.db` together with `coda.db-wal` and `coda.db-shm` (if present) out of `~/.coda/`. The next start creates a new database.
+
+### CODA won't start: "it was upgraded by a newer CODA"
+
+Another CODA — a newer CLI, or an app built on a newer CODA SDK — upgraded the session database, which they share, to a version this CODA can't safely use. Nothing was modified. Run `coda upgrade` to bring this installation up to date.
+
 ### What does the context percentage in the status bar mean?
 
-It shows how full the current conversation context is. When it approaches 100%, CODA automatically compacts the session history. If you're seeing degraded quality near 100%, run `/compact` manually or start a `/new` session.
+It shows how full the current conversation context is. CODA starts automatic reduction before the window is exhausted: stale tool output can move aside first, and older history is summarized at the configured threshold. If quality feels degraded, run `/compact` manually or start a `/new` session.
 
 ### CODA seems to have "forgotten" something from earlier in the session. Why?
 
-Automatic compaction condenses older messages into a summary to keep the session running. If you need full history for debugging, open `/settings` → **Context Compaction** to disable it or adjust when it kicks in.
+Automatic reduction may move stale tool output out of the active context and condense older messages into a summary. The original transcript remains stored, but the model works from the reduced view. If you need a less aggressive model-visible context while debugging, open `/settings` → **Context Compaction** to disable automatic reduction or adjust the threshold.
 
 ## Making changes
 
@@ -77,11 +85,21 @@ Type `/timeline` (or `/rewind`, or press **Esc** twice) to see all snapshots fro
 
 CODA runs an **authorization engine** that decides `allow` / `ask` / `deny` for every tool call. Two levers control it:
 
-- **Permission mode** — press `Ctrl+P` to cycle the session's mode: **read-only** (only reads run; writes and commands are refused), **default** (reads run, risky actions like `git commit` ask first, destructive ones are denied unless you add an allow rule), and **auto** (risky actions auto-run for unattended/CI use; only catastrophic ones stay blocked). Set the default in `/settings` or per project in `.coda/config.json` via `permissions.defaultMode`.
+- **Permission mode** — press `Ctrl+P` to cycle the session's mode: **read-only** (only reads run; writes and commands are refused), **default** (reads run, risky actions like `git commit` ask first, destructive ones are denied unless you add an allow rule), and **auto** (risky actions auto-run for unattended/CI use; only catastrophic ones stay blocked). A truly-fresh install (no `permissions` block in any config) starts in **auto**; once any `permissions` block exists without a `defaultMode`, sessions start in **default** — so an upgrade never silently raises autonomy. Saving a rule never changes your mode, so after your first rule new sessions start in `default`; to keep starting in auto, set `permissions.defaultMode: "auto"` yourself or approve the mode change `/init-rules` offers. A config file with a syntax error starts the session in `default`, never `auto`. A managed policy can still force `default`, a project config can tighten but cannot raise the mode, and headless `coda -p` ignores `defaultMode` (it follows `--auto-approve`). A session keeps its mode when you resume it.
 - **Rules** — to always allow or always block a specific command, add `allow` / `ask` / `deny` rules under `permissions` in `config.json` (e.g. `allow Bash(git status)` or `deny Bash(rm:*)`). **Deny always wins**, and a handful of catastrophic actions (`rm -rf /`, `sudo`, a fork bomb) sit behind an un-relaxable floor that no allow rule can override.
 
 The legacy `bash.autoApproveLevel` ("safe"→"high") was replaced by this model; a stored `high` migrates to `auto`.
 
+### CODA asked if I want to set up permission rules — what is that?
+
+If you have **no `allow` rules** in either your project `.coda/config.json` or your global `~/.coda/config.json`, CODA offers to run the **`/init-rules`** skill with a Yes/No prompt. On a fresh install the default permission mode is `auto` — where only your explicit `ask`/`deny` rules and the catastrophic floor stop the agent — so `/init-rules` helps you set up sensible `allow`/`ask`/`deny` rules for how your project actually works.
+
+The prompt appears **after you send your first message** — that message goes through normally and lands you on the usual chat screen, then CODA asks. It never interrupts the home screen. It is offered at most once each time you start CODA (`/new` or `/clear` don't bring it back).
+
+- **Yes** runs the skill.
+- **No** (or Esc) dismisses it and it won't ask again.
+- To turn it off permanently, set `"onboarding": { "suggestInitRules": false }` in your config. You can always run `/init-rules` yourself later.
+
 ### How does CODA decide what's safe to run without asking?
 
 It **parses** each command into a syntax tree (not string-matching) and classifies it by capability — read, write, network, destructive, catastrophic — across bash, PowerShell, and cmd. The decision is **deny-first**: explicit deny rules win, then your permission mode fills the gaps, then the un-relaxable floor plus self-protection clamp the dangerous cases. So `cat file` reads freely, `git commit` asks in `default`, `rm -rf /` is refused in every mode, and piping a remote script into a shell (`curl … | sh`) is denied by default. (`rm` and PowerShell `Remove-Item` deny for out-of-tree, absolute, or non-literal targets; an in-tree delete like `rm ./tmp` is auto-allowed in `default`/`auto` as an easily-reverted change, while recursive/absolute forms stay un-relaxable.)
@@ -100,7 +118,7 @@ Some editors capture `Ctrl+P` before CODA sees it. On **Windows/Linux**, VS Code
 
 ### What is AGENTS.md and should I have one?
 
-It's optional, but recommended — especially for shared projects. It's a Markdown file at your project root that CODA reads at the start of every session, where you document your coding conventions, how to run tests, what files not to touch, etc. Generate one with `/init` (or write it by hand), customize it, and commit it to Git so the whole team benefits.
+It's optional, but recommended — especially for shared projects. Put `AGENTS.md` in the directory where you launch CODA to document coding conventions, test commands, and files not to touch. CODA also accepts `AGENT.md` or `CLAUDE.md` as fallback names. Generate `AGENTS.md` with `/init` (or write it by hand), customize it, and commit it so the whole team benefits.
 
 ## Extensions and tools
 
@@ -112,6 +130,10 @@ Open the `/mcp` manager inside CODA and add the server — paste its JSON or imp
 
 Create a `.md` file with YAML frontmatter (`name` and `description` are required) and place it in `<project>/.coda/skills/` or `~/.coda/skills/`. The slash command `/skill-name` invokes it. See [Extend CODA](#guide-extend) for a complete example.
 
+### Can I use skills from Claude, Codex, or OpenCode?
+
+Yes. CODA can scan those agents' skill folders (`.claude/skills`, `.codex/skills`, `.opencode/skills`) plus the cross-tool `.agents/skills` — without copying anything. Foreign sources are **off by default**; turn one on from `/settings → Skills` or with `coda skills enable <source> --global|--project`. Add extra folders with `coda skills add-path <dir>`. See [Extend CODA](#guide-extend) › § "Import skills from other coding agents".
+
 ### How do I create an extension?
 
 The easiest way is to ask CODA: run `/create-extension` and describe what you want in plain language — the built-in `create-extension` skill scaffolds the TypeScript file and places it in the right folder for you. If you'd rather hand-write or fine-tune one, see [Writing Extensions](#extensions) for the full API reference.
@@ -130,7 +152,7 @@ Open `/workflows` and press **`c`** on a running entry, or run `/workflows stop
 
 ### How do I install a plugin or browse the marketplace?
 
-From inside CODA, open the `/plugin` manager to install, enable, disable, and browse the marketplace. From your terminal, `coda plugin install <source>` works too, where `<source>` is an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. CODA is compatible with the Claude Code plugin ecosystem. To browse a marketplace catalog, first register one with `coda marketplace install <source>`; then `/plugin` lists available plugins from that catalog. See [Extend CODA](#guide-extend).
+From inside CODA, open the `/plugin` manager to install, enable, disable, and browse the marketplace. From your terminal, `coda plugin install <source>` works too, where `<source>` is an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. CODA recognizes native CODA plugins plus Claude Code, Cursor, and portable Agent Plugins layouts. To browse a marketplace catalog, first register one with `coda marketplace install <source>`; then `/plugin` lists available plugins from that catalog. See [Extend CODA](#guide-extend).
 
 ## Models and cost
 
@@ -147,6 +169,16 @@ CODA re-checks your configured model against the provider's live catalog at star
 
 To opt out and always be asked, set `"strictPin": true` on the profile (see [Configuration Reference](#config-reference) › "activeProfile and profiles" and "modelResilience"). On a provider without a live catalog (e.g. local Ollama), CODA trusts your id and shows a clear switch-model message if it turns out to be unavailable.
 
+### How do I set the reasoning (thinking) effort for a single headless run?
+
+Pass `coda --reasoning-effort <level>` (`none|minimal|low|medium|high|xhigh|max`, case-insensitive) alongside your headless prompt:
+
+```bash
+coda -p "explain this repo" --reasoning-effort high
+```
+
+The level is applied **in memory for that run only** — it is never written to `~/.coda/config.json`, and it overrides any persisted `reasoning.effort` just for that invocation. Because nothing is written to disk, you can launch several headless runs **concurrently with different efforts** and they won't race on a shared config file (the reason the flag exists). Subagents spawned during the run inherit the same effort. An invalid value fails fast; a level the active model can't honor prints a stderr warning and runs without applying it (no silent fallback). Interactively, use `/effort` instead. See [Configuration Reference](#config-reference) for the persisted reasoning settings and supported levels.
+
 ### Where do I see token usage and cost?
 
 The TUI status bar shows the context fill percentage and running token/cost figures for the session, so you can keep an eye on how much a long session is consuming.
@@ -155,11 +187,11 @@ The TUI status bar shows the context fill percentage and running token/cost figu
 
 ### Where are my config, sessions, and logs stored?
 
-Everything lives under `~/.coda/` — `config.json`, `.secrets`, the session database `coda.db` (with per-session override files under `sessions/<id>/`), `logs/`, `checkpoints/`, and `exports/`. Point `CODA_HOME` at a different directory to relocate all of it — or pass `--coda-home <path>` on the command line (both have the same effect; the flag wins when the env var is not set). See [Configuration Reference](#config-reference).
+Most state lives under `~/.coda/` — `config.json`, `.secrets` (a marker file for generic `${VAR}` values; newly added API keys go through your system keychain instead, though a legacy key may remain here in plaintext on a host without an OS keyring), `.credentials.json` (the encrypted fallback store, only present where there is no OS keyring), the session database `coda.db` (with per-session override files under `sessions/<id>/`), `logs/`, `checkpoints/`, and `exports/`. Your OS keychain entry for provider API keys, when available, is external to this directory. Point `CODA_HOME` at a different directory to relocate all of it — or pass `--coda-home <path>` on the command line (both have the same effect; precedence is `--coda-home` > `CODA_HOME` > the default, so an explicit flag overwrites an inherited env var). See [Configuration Reference](#config-reference).
 
 ### How do I view or share logs safely?
 
-Run `coda logs` for the viewer (filter by `--level`, `--service`, `--since`, or `--follow`). To share with support, `coda logs export` writes a redacted, path-scrubbed bundle to `~/.coda/exports/` — nothing is ever uploaded. Secrets are scrubbed before anything hits disk. See [View & Share Logs](#logging).
+Run `coda logs` for the viewer (filter by `--level`, `--service`, `--since`, or `--follow`). To share with support, `coda logs export` writes a redacted, path-scrubbed bundle to `~/.coda/exports/` — nothing is ever uploaded. Review it, then attach it to your request or email **coda-tech-support@globant.com**. Secrets are scrubbed before anything hits disk. See [View & Share Logs](#logging).
 
 ### Can I use checkpoints in CI?
 
@@ -167,7 +199,7 @@ Not for rollback — the `/timeline` picker is a TUI feature. In headless mode c
 
 ### How does CODA behave in a monorepo?
 
-It loads exactly one `AGENTS.md` — the one in the directory you launch it from. There's no upward walk or merging. Launch from the package you're working in (`cd packages/billing && coda`). See [Collaborate with Your Team](#guide-collaborate).
+At startup, CODA loads an optional global instruction file plus one instruction file from the directory where you launch it (`AGENTS.md`, then `AGENT.md`, then `CLAUDE.md`). It does not inherit parent-directory instructions at startup. When it reads files deeper in the tree, it can attach more-specific instructions from those subdirectories. Launch from the package you're working in (`cd packages/billing && coda`) when that package's rules should be the root conventions. See [Collaborate with Your Team](#guide-collaborate).
 
 ## See also