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

package/assets/docs/glossary.md

@@ -4,21 +4,21 @@ Quick definitions for terms used throughout the docs.
 
 | Term | Definition |
 | --- | --- |
-| **AGENTS.md** | A Markdown file at your project root that CODA reads at the start of every session. Use it to document your project's conventions, quality gates, and constraints for the agent. |
+| **AGENTS.md** | The preferred instruction filename for project conventions, quality gates, and constraints. CODA loads it from the launch directory at startup and can attach more-specific instruction files when reading deeper paths. `AGENT.md` and `CLAUDE.md` are fallback names. |
 | **Agent** | In CODA, an agent is a Markdown-defined profile that describes a specialist persona. CODA can delegate subtasks to agents, running them in parallel for complex work. |
 | **Batch mode** | Headless, non-interactive mode. Run with `coda -p "prompt"`. No TUI, no multi-turn conversation — use in scripts and CI. |
 | **Checkpoint** | A file snapshot taken before each turn — the state from before CODA acts on the message you just sent. Restored via `/timeline` or `/rewind`; your project's Git history is untouched. |
 | **CLI** | The `coda` command-line tool. It runs in two modes: interactive (the TUI) and headless (batch). |
 | **coda-help** | A built-in agent that answers questions about how to use CODA by searching the local user guide. CODA delegates to it automatically when you ask about itself. |
-| **Compaction** | Automatic condensing of older conversation history to free up context window space. Triggered at a configurable fill threshold. |
+| **Compaction** | Context reduction for long sessions. CODA either stores the current context directly or reduces it by moving stale tool output aside and, at the configured threshold, condensing older messages into a summary. |
 | **Extension** | A TypeScript module that registers custom tools, slash commands, or lifecycle hooks into CODA. |
-| **Glob.AI OS** | Globant's internal AI gateway — the primary provider for CODA at Globant. |
+| **Glob.AI** | Globant's internal AI gateway — the primary provider for CODA at Globant. |
 | **MCP** | Model Context Protocol. A standard for connecting AI models to external tools and services. CODA uses MCP servers to talk to GitHub, databases, CI systems, and other integrations. |
 | **MEMORY.md** | Durable notes the agent keeps across sessions — preferences, decisions, and gotchas it learns. Unlike AGENTS.md (which you write), CODA maintains this itself, and it survives checkpoint rollbacks. |
-| **Plugin** | A versioned, installable package that can bundle skills, agents, extensions, and MCP fragments. More structured than an extension; installable via `coda plugin install`. |
-| **Provider** | The AI backend CODA sends prompts to — for example a Glob.AI OS instance, a local Ollama server, or any OpenAI-compatible endpoint. Managed with `/providers`. |
+| **Plugin** | A versioned, installable package that can bundle skills, agents, extensions, MCP fragments, and lifecycle hooks. More structured than an extension; installable via `coda plugin install`. |
+| **Provider** | The AI backend CODA sends prompts to — for example a Glob.AI instance, a local Ollama server, or any OpenAI-compatible endpoint. Managed with `/providers`. |
 | **Session** | A persistent CODA conversation. Stored on disk; resumable at any time. |
-| **Skill** | A Markdown file that encodes a repeatable workflow. Invoked with a slash command like `/skill-name`. |
+| **Skill** | A Markdown file that encodes a repeatable workflow. Invoked with a slash command like `/skill-name`. CODA discovers skills from its own `.coda/skills` and, when enabled, from other agents' folders (`.agents`, `.claude`, `.codex`, `.opencode`) — see `skills.sources`. |
 | **TUI** | Terminal User Interface — the full-screen interface you see when you run `coda` interactively. |
 | **Workflow** | A deterministic script that orchestrates multiple agents — parallel fan-out, multi-stage pipelines, and loops. Authored by the built-in `create-workflow` agent, stored in `.coda/workflows/`, run in the background, and monitored with `/workflows`. |
 | **ACP** | Agent Client Protocol — the integration that lets editors like Zed and JetBrains drive CODA. |
@@ -27,7 +27,7 @@ Quick definitions for terms used throughout the docs.
 | **`.codaignore`** | A gitignore-syntax file at your project root with glob patterns (and optional `!negation` lines) to exclude from — or forcibly include in — checkpoints. Shares `.gitignore` semantics, so patterns, directory globs, and negations all work. |
 | **Context window** | The amount of conversation CODA can hold at once. The status-bar percentage shows how full it is; compaction frees room as it fills. |
 | **Drift** | Uncaptured changes in your worktree at restore time. CODA stops the restore so you don't lose work; press **F** to force it. |
-| **`fastModel`** | The model the literal `model: "fast"` shortcut resolves to, used for cheap, high-volume agent runs. Can be configured per-provider (`providers.<key>.fastModel`) or globally under `agents.fastModel`; CODA also supplies a built-in Glob.AI OS fallback when neither is set. |
+| **`fastModel`** | The model the literal `model: "fast"` shortcut resolves to, used for cheap, high-volume agent runs. Can be configured per-provider (`providers.<key>.fastModel`) or globally under `agents.fastModel`; CODA also supplies a built-in Glob.AI fallback when neither is set. |
 | **`smartModel`** | The model the literal `model: "smart"` shortcut resolves to — the balanced mid-tier for agent runs. Configured under `agents.smartModel` or per-provider. |
 | **`deepModel`** | The model the literal `model: "deep"` shortcut resolves to — the highest-capability, most expensive tier. Configured under `agents.deepModel` or per-provider. |
 | **HITL** | Human-in-the-loop — the approval model where CODA pauses to ask before risky actions. |
@@ -37,7 +37,7 @@ Quick definitions for terms used throughout the docs.
 | **`propose_policy`** | The built-in tool CODA uses to suggest a permanent permission change (add rule, remove rule, or change mode) for you to approve. Triggered when you ask in plain English (e.g. "allow pnpm build") or after a denial. On by default; a *widening* change always needs your explicit approval. Disable with `permissions.proposePolicy: false`, `CODA_PROPOSE_POLICY`, or the admin `disableProposePolicy`. |
 | **Managed policy** | An organization-level policy set by an administrator that overrides and locks certain permission settings in your personal and project configs (e.g. forbidding `auto` mode, restricting MCP servers). A managed `deny` is final. |
 | **Headless mode** | See *Batch mode*. |
-| **Marketplace** | The catalog of installable plugins, reachable from the `/plugin` manager; Claude Code-ecosystem compatible. |
+| **Marketplace** | A catalog of installable plugins, reachable from the `/plugin` manager. CODA recognizes native, Claude Code, Cursor, and portable Agent Plugins layouts. |
 | **Redaction** | The always-on scrubbing of secret-looking keys and values from logs before they're written to disk. |
 | **ripgrep / fastgrep** | The two content-search backends behind the `grep` tool. ripgrep ships bundled and is the default. |
 | **Shadow repository** | The private Git repo where checkpoints are stored, separate from your project's own `.git`. Located at `~/.coda/checkpoints/<hash>/` by default (one per project, keyed by a SHA-256 of the project path). The base directory can be relocated via `CODA_HOME`. |

package/assets/docs/guide-automate.md

@@ -76,7 +76,7 @@ fi
 | `--checkpoints=true` | Enable file snapshots (off by default in headless runs) |
 | `--profile id` | Use a specific persisted profile for this run (read-only; doesn't change your saved `activeProfile`) |
 | `--provider name` | Ephemeral run provider: `glob-ai`, `openai-compat`, or `ollama` (default `glob-ai`) |
-| `--instance id` | Glob.AI OS instance for an ephemeral run (`clients`, `corp`, `saas-europe`; default `saas-europe`) |
+| `--instance id` | Glob.AI instance for an ephemeral run (`eu-v1`, `us-v1`, `clients`, `corp`; the former `saas-us` / `saas-europe` still resolve, to `us-v1` and `eu-v1`). Omitted: the declared default — see `coda --help` |
 | `--base-url url` | Base URL for an ephemeral `openai-compat` / `ollama` run |
 | `--api-key key` | Ephemeral, run-only API key — held in memory, never persisted, redacted in logs |
 
@@ -95,7 +95,7 @@ A batch run needs credentials just like an interactive one, but there's no wizar
    coda -p "Review this diff" --provider openai-compat \
      --base-url https://api.example.com/v1 --api-key "$MY_API_KEY"
 
-   # Glob.AI OS Clients instance with an API key
+   # Glob.AI Clients instance with an API key
    coda -p "Summarize the changes" --provider glob-ai \
      --instance clients --api-key "$CODA_GEAI_CLIENTS_API_KEY"
    ```
@@ -115,6 +115,10 @@ coda -p "Summarize the open TODOs in this repo" --output json \
   | jq -r 'select(.type=="agent_response") | .payload.response'
 ```
 
+**What the result contains.** `response` is the run's **final reply** — the answer the agent ended on. Text the agent wrote along the way (for example "Let me look at the tests first" before a tool call) is progress, not part of the result; it stays visible in the event stream. `--output-last-message FILE` writes exactly that final reply, `--output-schema` validates it, and `--silent` prints only it. If the run ends without a final reply (for example, it hit its step limit while still working), `response` is empty and a warning is added to the result.
+
+**Retried responses are never printed.** When a provider connection drops mid-answer, CODA retries automatically. The interrupted partial answer is dropped: it doesn't appear in stdout, in the JSON stream, or in `response`. In `--output json`, each model attempt ends with a `turn_end` event whose `outcome` is `committed` or `discarded`, so a consumer that tracks attempts can tell them apart.
+
 Always check the **exit code**: a non-zero status means the run failed (an error, a timeout, or — with `--auto-approve none` — a denied approval), so your CI step can fail fast.
 
 ## Scope it down for safety

package/assets/docs/guide-changes.md

@@ -10,11 +10,11 @@ In addition to per-turn snapshots, CODA automatically takes an extra snapshot la
 
 For how checkpoints work in detail — the shadow repo, Git requirements, and how restoring rewinds the conversation — see [Sessions & Checkpoints](#sessions).
 
-## Approve commands as they run
+## Approve actions when CODA asks
 
-When CODA wants to run a shell command, it shows you what it's about to execute and waits for your approval — press **Y** to allow it or **N** to skip it. By default, CODA auto-approves low-risk commands (like `git status` or `cat`) and asks before anything that writes or deletes files.
+Every tool call goes through the authorization engine. It combines your **permission mode** with `allow` / `ask` / `deny` rules and the built-in safety floor. An `allow` decision runs immediately, `deny` does not run, and `ask` opens the approval prompt — press **Y** for this action, **A** for the displayed reusable session rule when offered, or **N** to deny it. Use **Arrow keys + Enter** to select another offered option; a permanent project rule always gets a second confirmation.
 
-How much runs without asking depends on your **permission mode**, which you cycle with **Ctrl+P** or set via `permissions.defaultMode`:
+How much runs without asking depends on the session's permission mode. Cycle it with **Ctrl+P** (the session keeps it when you resume it); `permissions.defaultMode` sets the mode new sessions start in:
 
 | Mode | What it allows |
 | --- | --- |
@@ -88,7 +88,7 @@ If your project has an `AGENTS.md` with a "quality gate" section, CODA follows i
 ## A quick mental model for staying in control
 
 1. **Checkpoint** — every turn is snapshotted before it runs, so you can always go back.
-2. **Approve** — risky shell commands and unread-file overwrites pause for your **Y**/**N**.
+2. **Authorize** — rules and the current mode decide each tool call; only `ask` decisions pause for you.
 3. **Interrupt** — **Esc** stops a turn the instant it heads the wrong way.
 4. **Steer or queue** — react without stopping the turn (`/settings` → **Composer**).
 5. **Undo** — `/timeline` (or **Esc Esc**) rewinds files *and* the conversation to a chosen point.

package/assets/docs/guide-collaborate.md

@@ -6,7 +6,7 @@ CODA works best when the whole team uses it consistently. This guide covers how
 
 `AGENTS.md` is the most important file for team collaboration. CODA reads it at the start of every session and uses it to understand your project's conventions — coding style, testing approach, which areas to avoid, how to run the quality checks.
 
-CODA looks for it at your project root (`<project>/AGENTS.md`) first, and falls back to `<project>/.coda/AGENTS.md` if the root file isn't present. Put it at the root for visibility, or under `.coda/` if you prefer to keep it out of the top level.
+CODA looks for an instruction file in the directory where you launch it, preferring `AGENTS.md`, then `AGENT.md`, then `CLAUDE.md`. Put project instructions at that root for visibility. A legacy `<project>/.coda/AGENTS.md` is no longer loaded; move it to the project root.
 
 Create or update it with `/init` and then edit it to add what CODA missed. A typical `AGENTS.md` looks like this:
 
@@ -61,16 +61,16 @@ The most valuable things to share live in the repo and apply to everyone who clo
 - **Skills** in `<project>/.coda/skills/` — shared workflows the whole team can invoke.
 - **MCP servers** in `<project>/.coda/mcp.json` — the external services this project connects to.
 
-A project-level `<project>/.coda/config.json` is also **safe to commit** — it never holds secrets (those live in `~/.coda/.secrets`, which is never committed). But be selective about what you put there:
+A project-level `<project>/.coda/config.json` is also **safe to commit** as long as no one hand-edits a literal secret into it — provider API keys go through your system keychain (or an encrypted secrets file) outside the repo, so they have no reason to end up here. But be selective about what you put there:
 
-- **Don't commit the active provider.** Which provider you use (a specific Glob.AI OS instance, or a local Ollama) is a personal, machine-specific choice, and provider profiles are defined in each developer's own global config. Pinning it in the repo can break teammates who don't have that profile.
-- **Think twice before committing an elevated permission mode.** Setting `permissions.defaultMode: "auto"` in the project's `.coda/config.json` means everyone who clones the repo runs more commands without being asked — a safety trade-off your team should agree on first.
+- **Don't commit the active provider.** Which provider you use (a specific Glob.AI instance, or a local Ollama) is a personal, machine-specific choice, and provider profiles are defined in each developer's own global config. Pinning it in the repo can break teammates who don't have that profile.
+- **Use project permission modes to tighten, not widen.** A project `.coda/config.json` can start sessions in a more restrictive mode, but CODA ignores attempts to raise autonomy above each developer's user-level default. Share explicit rules only when the team agrees on them.
 
 In short: share **conventions and workflows**, keep **personal and security preferences** local.
 
 ## Working in a monorepo
 
-CODA loads exactly one `AGENTS.md` — the one in the directory where you launch it. **For `AGENTS.md` specifically**, there is no upward directory walk and no merging of parent files. (Agent definitions and workflow modules _do_ walk upward to parent directories, so placing them closer to the repo root makes them available to nested package launches automatically.)
+At startup, CODA loads your optional global instruction file from `~/.coda/` and one instruction file from the directory where you launch it, using the `AGENTS.md` → `AGENT.md` → `CLAUDE.md` fallback order. It does not merge instruction files from parent directories at startup. When CODA later reads a file below that root, it can attach more-specific instruction files found between that file and the launch directory. Agent definitions and workflow modules use their own upward discovery rules.
 
 In a monorepo, launch CODA from the package directory you're working in:
 
@@ -79,7 +79,7 @@ cd packages/billing
 coda   # loads packages/billing/AGENTS.md
 ```
 
-Put conventions that apply everywhere in each package's `AGENTS.md`, or maintain a root-level one and symlink it into each package.
+Put package-specific conventions in each package's `AGENTS.md`. For repository-wide conventions, launch from the repository root or make the shared rules available from the package launch directory; CODA does not automatically inherit a parent root file at startup.
 
 ## Share agents and workflows too
 
@@ -108,9 +108,9 @@ To keep shared assets in and personal/secret state out, a typical project ignore
 # .coda/skills/  .coda/agents/  .coda/workflows/  .coda/mcp.json  AGENTS.md
 ```
 
-Note that **session records aren't stored in your project** — they live in the global `~/.coda/coda.db` (see [Sessions & Checkpoints](#sessions)), so there's nothing session-related to ignore here. Secrets never live in the repo at all — they're in `~/.coda/.secrets`, outside the project.
+Note that **session records aren't stored in your project** — they live in the global `~/.coda/coda.db` (see [Sessions & Checkpoints](#sessions)), so there's nothing session-related to ignore here. Provider API keys never live in tracked repo content — they're in your system keychain (or an encrypted secrets file), outside the project.
 
-> **Watch out for `.env` files.** CODA also loads environment variables from a `.coda/.env` or `.env` file in the project directory. These files may contain API keys or other secrets and should **never** be committed. Add `.coda/.env` and `.env` to your `.gitignore` and use `~/.coda/.secrets` for per-developer secrets instead.
+> **Watch out for `.env` files.** CODA also reads a `.coda/.env` or `.env` file in the project directory as values for `${VAR}` in its config. It does not export them: the bash tool, hooks and MCP servers see a variable only when it is exported in your shell or kept in `~/.coda/.secrets`, or when an MCP server's `env` or `headers` passes it with `${VAR}`. These files may contain API keys or other secrets and should **never** be committed. Add `.coda/.env` and `.env` to your `.gitignore`. For per-developer values, use a project `.coda/.env` (kept out of Git) for generic `${VAR}` values — provider API keys belong in the keychain via `/providers` (or an encrypted store file when no keychain is available), never in a dotenv file.
 
 ## See also
 

package/assets/docs/guide-extend.md

@@ -27,9 +27,9 @@ Everything happens from inside CODA through the `/mcp` manager:
 /mcp
 ```
 
-From there you can **add a server** (paste its JSON or import it from a file), edit the global or project `mcp.json`, list configured servers and their connection status, view the tools each one exposes, enable or disable servers for the session, and reload after a change — no need to hand-edit files outside the app.
+From there you can **add a server** (paste its JSON or import it from a file), edit the global or project `mcp.json`, list configured servers and their connection status, view the tools each one exposes, enable or disable servers for the session, and reload after a change — no need to hand-edit files outside the app. You can also ask CODA to configure one from a package, command, repository, or URL; see [Configure an MCP Server](#add-mcp-server-skill).
 
-**Where MCP servers are defined.** Servers live in `mcp.json` files that layer like the rest of your config: `~/.coda/mcp.json` (global) and `<project>/.coda/mcp.json` (project). A third, session-level file at `~/.coda/sessions/<sessionId>/mcp.json` holds per-session overrides — including a disable-only shorthand `{ "disabled": true }` to switch a higher-tier server off for one session. Each server entry is either **stdio** (`command` plus optional `args`/`env`) or **HTTP** (`url`, optional `headers`/token); add `"disabled": true` to any entry to keep it but turn it off. (CODA builds the live server map from `mcp.json` + plugins + `--mcp-config`, so prefer `mcp.json` over the `mcp.servers` block in `config.json`.)
+**Where MCP servers are defined.** Servers live in `mcp.json` files that layer like the rest of your config: `~/.coda/mcp.json` (global) and `<project>/.coda/mcp.json` (project). A third, session-level file at `~/.coda/sessions/<sessionId>/mcp.json` holds per-session overrides — including a disable-only shorthand `{ "disabled": true }` to switch a higher-tier server off for one session. Each project/global server entry is either **stdio** (`command` plus optional `args`/`env`) or **HTTP** (`url`, optional `headers`/token). Use the `/mcp` manager to enable or disable it for the current session. CODA builds the live server map from `mcp.json` + plugins + `--mcp-config`, so prefer `mcp.json` over the `mcp.servers` block in `config.json`.
 
 Once a server is connected, CODA can use its tools automatically — you just describe what you want in plain language. For example, with a **GitHub MCP server** connected, you could ask:
 
@@ -78,6 +78,33 @@ To browse, enable, disable, or install skills, use the skills manager from insid
 
 The manager lists every skill and its enabled state, and lets you enable or disable individual skills (per-session disables are stored under `~/.coda/sessions/<sessionId>/`). You can also install a skill straight from GitHub with `/skills add <repo-url> [project|global]` — choose `project` to commit it with the repo or `global` for your personal library. For private repos or to avoid rate limits, set `GITHUB_TOKEN` (or `GH_TOKEN`) so the GitHub API fallback can authenticate.
 
+### Import skills from other coding agents
+
+CODA can also discover skills that already live in *other* agents' directories, so you don't have to copy them. Alongside its own `.coda/skills`, it can scan the cross-tool `.agents/skills` folder and — once you opt in — the skill folders of Claude, Codex, and OpenCode:
+
+| Source | Scanned directories | Default |
+| --- | --- | --- |
+| `coda` | `<project>/.coda/skills`, `~/.coda/skills` | Always on (native) |
+| `agents` | `<project>/.agents/skills`, `~/.agents/skills` | On |
+| `claude` | `<project>/.claude/skills`, `$CLAUDE_CONFIG_DIR`/`~/.claude/skills` | Off |
+| `codex` | `<project>/.codex/skills`, `$CODEX_HOME`/`~/.codex/skills` | Off |
+| `opencode` | `<project>/.opencode/skills`, `~/.opencode/skills` | Off |
+
+Foreign sources are **off by default**, so upgrading changes nothing until you turn one on. Project directories are scanned before global ones, and CODA dedupes: the same skill file reached from several roots shows up once, and if two *different* files share a name, the higher-tier source wins (`coda` > `agents` > `claude` > `codex` > `opencode` > your extra paths).
+
+Turn sources on or off from the **`/settings → Skills`** screen (a per-source toggle, at global or project scope), or from the terminal with the **`coda skills`** sub-command:
+
+```text
+coda skills sources                      # show each source and whether it's enabled
+coda skills list                         # list every discovered skill and its source
+coda skills enable claude --global       # opt a source in (needs --global or --project)
+coda skills disable codex --project
+coda skills add-path ~/shared/skills --global   # scan an extra folder (must exist)
+coda skills remove-path ~/shared/skills --global
+```
+
+Reads (`sources`, `list`) show the resolved, merged view (project overrides global). Writes require an explicit `--global` or `--project` scope, and add `--json` for a machine-readable envelope. Extra folders can also be listed directly under `skills.paths` in `config.json`. Source and path changes apply on the next launch.
+
 ## Automate with extensions
 
 Extensions are TypeScript modules that can register custom **tools**, **slash commands**, **lifecycle hooks** (e.g. `session_start`, `tool_execution_end`), custom model providers, keyboard shortcuts, CLI flags, and custom message renderers — using the full `ExtensionAPI`. Use them when you need CODA to integrate with an internal system that doesn't have an MCP server, or to automate a complex workflow that doesn't fit in a skill.
@@ -88,7 +115,7 @@ Ready to build one? The easiest way is to ask CODA — its `create-extension` sk
 
 ## Share packaged integrations with plugins
 
-Plugins are versioned, installable packages — like extensions, but with a manifest, version number, and the ability to bundle skills, agents, and MCP fragments together. Use plugins when you want to share a reusable CODA integration across teams or projects.
+Plugins are versioned, installable packages — like extensions, but with a manifest, version number, and the ability to bundle skills, agents, extensions, MCP fragments, and lifecycle hooks together. Use plugins when you want to share a reusable CODA integration across teams or projects.
 
 Manage plugins from inside CODA with the `/plugin` manager — enable, disable, and browse any registered marketplace catalog. The `/plugin install` slash command accepts **only absolute local paths** to a plugin directory; for npm packages, Git URLs, or marketplace-sourced plugins, use `coda plugin install <source>` from the terminal:
 
@@ -102,7 +129,7 @@ You can also install from your terminal:
 coda plugin install <source> [--name <folder>] [--scope global|project]
 ```
 
-`<source>` can be an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. `--name` selects a subdirectory (useful for monorepo git sources); `--scope` chooses `global` (default) or `project` install scope.
+`<source>` can be an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. `--name` selects a subdirectory (useful for monorepo git sources); `--scope` chooses `global` (default) or `project` install scope. After installing, enabling, or disabling a plugin, run `/reload-plugins`. It starts a fresh session with plugins reloaded.
 
 ### Adding a marketplace
 
@@ -113,7 +140,7 @@ A marketplace is a catalog of plugins. Add one from the terminal with `coda mark
 - a **local folder** containing a `marketplace.json` (Claude-style `.claude-plugin/` or `.coda-plugin/` layouts are recognized);
 - a **local `.zip`** archive — CODA unpacks it and finds the catalog inside, including the single nested top-level folder you get from a GitHub "Download ZIP" / "Source code" archive.
 
-CODA is compatible with the Claude Code plugin and marketplace ecosystem, so catalogs published for Claude Code work here.
+CODA recognizes native CODA plugins plus Claude Code, Cursor, and portable Agent Plugins layouts. Features outside CODA's supported component set may be ignored, so review the detected plugin details before enabling it.
 
 ## Orchestrate multiple agents with workflows
 

package/assets/docs/hooks.md

@@ -10,7 +10,7 @@ The hook system is **compatible with Claude Code hooks**: the same JSON input/ou
 
 Add a `hooks` key to `~/.coda/config.json` (global) or `.coda/config.json` (project):
 
-```jsonc
+```json
 {
   "hooks": {
     "PreToolUse": [
@@ -160,7 +160,7 @@ The `matcher` field filters which tool names (or session sources) trigger the ho
 | `type` | ✅ | `"command"` |
 | `command` | ✅ | The command to run. In **shell form** (no `args`) it is the command string passed to a shell. In **exec form** (`args` present) it is the executable to spawn directly. Receives JSON on stdin. |
 | `args` | — | Argument vector. When present (even `[]`), the hook runs in **exec form**: `command` is spawned directly with `args` as its arguments and **no shell** — each element is passed verbatim (no quoting/globbing). `shell` is ignored. Path placeholders are substituted in each element. |
-| `shell` | — | Shell for **shell form** only (ignored when `args` is set): `"bash"` (→ `bash -c`) or `"powershell"` (→ `powershell -NoProfile -Command`). Defaults to `sh -c`. |
+| `shell` | — | Shell for **shell form** only (ignored when `args` is set): `"bash"` (→ `bash -c`), `"powershell"` (→ `powershell -NoProfile -Command`), or `"sh"` (→ `sh -c`). Omitted or `"auto"` is **POSIX-first** (#909/#921): `sh -c` on macOS/Linux; on Windows, Git Bash when present, else `powershell -NoProfile -Command` as a last resort. It never inherits the session's `bash.shellMode` — that is the model/user's shell choice, not the hook author's, and pinning is the way to opt into PowerShell/bash explicitly. |
 | `timeout` | — | Seconds before the hook is killed (default: 600). |
 | `if` | — | Permission rule — conditionally skip the hook (see [Conditional execution](#conditional-execution-if-field)). |
 | `statusMessage` | — | Custom spinner label shown while the hook runs. |
@@ -186,15 +186,18 @@ The `matcher` field filters which tool names (or session sources) trigger the ho
 
 Coda sends a JSON object on **stdin** (command hooks) or as the **POST body** (HTTP hooks). All events include these base fields:
 
-```jsonc
+```json
 {
   "session_id": "abc123",
   "transcript_path": "",
   "cwd": "/home/user/my-project",
-  "hook_event_name": "PreToolUse"
+  "hook_event_name": "PreToolUse",
+  "cli_version": "0.4.2"
 }
 ```
 
+`cli_version` is the running Coda version — the value `coda --version` prints — so a hook can attribute what it observes to the exact version that produced it. Command hooks also receive it as the `CODA_VERSION` environment variable (see [Environment variables available to hooks](#environment-variables-available-to-hooks)), which is cheaper than parsing stdin in hot-path hooks.
+
 ### Tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`)
 
 ```jsonc
@@ -203,7 +206,8 @@ Coda sends a JSON object on **stdin** (command hooks) or as the **POST body** (H
   "transcript_path": "",
   "cwd": "/home/user/my-project",
   "hook_event_name": "PreToolUse",
-  "tool_name": "Bash",
+  "cli_version": "0.4.2",
+  "tool_name": "bash",
   "tool_input": { "command": "git status", "description": "Check git status" },
   "tool_use_id": "toolu_01XYZ",
   // PostToolUse only:
@@ -215,36 +219,39 @@ Coda sends a JSON object on **stdin** (command hooks) or as the **POST body** (H
 
 ### `UserPromptSubmit`
 
-```jsonc
+```json
 {
   "session_id": "abc123",
   "transcript_path": "",
   "cwd": "/home/user/my-project",
   "hook_event_name": "UserPromptSubmit",
+  "cli_version": "0.4.2",
   "prompt": "Refactor the auth module"
 }
 ```
 
 ### `SessionStart`
 
-```jsonc
+```json
 {
   "session_id": "abc123",
   "transcript_path": "",
   "cwd": "/home/user/my-project",
   "hook_event_name": "SessionStart",
+  "cli_version": "0.4.2",
   "source": "startup"
 }
 ```
 
 ### `Stop`
 
-```jsonc
+```json
 {
   "session_id": "abc123",
   "transcript_path": "",
   "cwd": "/home/user/my-project",
   "hook_event_name": "Stop",
+  "cli_version": "0.4.2",
   "stop_reason": "turn_complete"
 }
 ```
@@ -385,7 +392,7 @@ rule ::= toolName | toolName(content)
 | File glob | `"Edit(src/*.ts)"` | TypeScript files under `src/` |
 | Prefix (legacy) | `"Bash(npm:*)"` | `npm`, `npm install`, `npm run …` |
 
-```jsonc
+```json
 {
   "hooks": {
     "PreToolUse": [
@@ -444,29 +451,17 @@ Plugins can ship a `hooks/hooks.json` file at the plugin root. The format is ide
 
 ## Session environment files (`CODA_ENV_FILE`)
 
-Hooks can export environment variables that persist across all subsequent Bash tool commands in the session.
-
-### Mode 1 — External env file (process-level)
-
-Set `CODA_ENV_FILE` in your shell before launching Coda. Its contents are prepended to every Bash command:
-
-```bash
-export CODA_ENV_FILE=~/.coda/my-env.sh
-coda
-```
-
-### Mode 2 — Hook-writable env file (hook-level)
+The hook runtime can give `SessionStart` hooks a writable `CODA_ENV_FILE`, and embedders can use the session-environment API to prepend those exports to later Bash commands. The current CODA CLI does **not** connect that optional callback to its Bash tool, so these files do not currently change later CLI commands. Treat this as an embedding API rather than a CLI feature.
 
-For `SessionStart` hooks (bash/wsl only), Coda sets `CODA_ENV_FILE` to a writable path before spawning your hook. Write `export` statements to that file; they are sourced before every subsequent Bash command in the session:
+A `SessionStart` hook may still write the file for a host that supports it:
 
 ```bash
 #!/bin/bash
-# SessionStart hook — activate a Python venv for the whole session
-source .venv/bin/activate
-echo "export VIRTUAL_ENV=$VIRTUAL_ENV" >> "$CODA_ENV_FILE"
-echo "export PATH=$PATH" >> "$CODA_ENV_FILE"
+echo "export VIRTUAL_ENV=$PWD/.venv" >> "$CODA_ENV_FILE"
 ```
 
+Do not rely on this for the standard CLI today; configure the environment before launching CODA instead.
+
 ---
 
 ## Async hooks
@@ -475,9 +470,9 @@ By default hooks run **synchronously** — the lifecycle event waits for every m
 
 ### `async: true` — tracked background
 
-The hook runs in the background. Results are polled at the start of each turn and applied (e.g. `additionalContext` is injected into the next tool result).
+The hook runs in the background. Results are polled at the start of each turn. Completed `additionalContext` is injected into the conversation as an `[Async hook]` user message before that turn proceeds.
 
-```jsonc
+```json
 {
   "type": "command",
   "command": ".coda/hooks/slow-analysis.sh",
@@ -490,7 +485,7 @@ The hook runs in the background. Results are polled at the start of each turn an
 
 The hook runs fully detached. If it exits with code 2, its stderr/stdout is injected as a system message that re-engages the model. Useful for background file watchers or integrity checkers.
 
-```jsonc
+```json
 {
   "type": "command",
   "command": ".coda/hooks/file-integrity-watcher.sh",
@@ -508,7 +503,7 @@ A hook can decide at runtime to go async by printing `{"async": true}` as its fi
 
 Set `disableAllHooks: true` in `config.json` to disable all hooks globally. Useful in CI environments or when debugging unexpected behavior:
 
-```jsonc
+```json
 {
   "disableAllHooks": true
 }
@@ -531,8 +526,9 @@ Set `disableAllHooks: true` in `config.json` to disable all hooks globally. Usef
 | Variable | Value |
 | --- | --- |
 | `CODA_PROJECT_DIR` | Current project directory |
+| `CODA_VERSION` | The running Coda version (what `coda --version` prints) — same value as the `cli_version` payload field. Set by Coda and authoritative: it overrides any `CODA_VERSION` you exported, and is absent (not empty) when the running version is unknown |
 | `CODA_PLUGIN_ROOT` | Plugin installation directory (plugin hooks only) |
-| `CODA_ENV_FILE` | Writable env file path (SessionStart hooks only, bash/wsl) |
+| `CODA_ENV_FILE` | Writable env file path for `SessionStart` hooks. It affects later Bash calls only in an embedding that wires session-environment support; the standard CLI currently does not. |
 
 All other environment variables from the Coda process are also inherited.
 
@@ -561,7 +557,7 @@ All other environment variables from the Coda process are also inherited.
 
 ### Block `git push` in a project
 
-```jsonc
+```json
 {
   "hooks": {
     "PreToolUse": [
@@ -602,7 +598,7 @@ All other environment variables from the Coda process are also inherited.
 
 ### Log every session to a file
 
-```jsonc
+```json
 {
   "hooks": {
     "SessionStart": [
@@ -642,38 +638,6 @@ All other environment variables from the Coda process are also inherited.
 }
 ```
 
-### Activate a Python venv for the whole session
-
-```bash
-#!/bin/bash
-# .coda/hooks/activate-venv.sh
-# Used as a SessionStart hook
-if [ -f ".venv/bin/activate" ]; then
-  source .venv/bin/activate
-  echo "export VIRTUAL_ENV=\"$VIRTUAL_ENV\"" >> "$CODA_ENV_FILE"
-  echo "export PATH=\"$PATH\"" >> "$CODA_ENV_FILE"
-fi
-```
-
-```jsonc
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".coda/hooks/activate-venv.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
----
-
 ## Troubleshooting
 
 **Hooks are not running**
@@ -698,7 +662,7 @@ fi
 
 ## See also
 
-- [Configuration](configuration.md) — where `config.json` files live and how they merge
-- [Features](features.md) — plugins, extensions, agents, skills
-- [How to create a Coda extension](create-extension.md) — programmatic hooks via the extension API
-- [Coda tools overview](tools.md) — tool names to use in `matcher` patterns
+- [Configuration](#configuration) — where `config.json` files live and how they merge.
+- [Extend CODA](#guide-extend) — plugins, extensions, agents, skills, and MCP.
+- [Writing Extensions](#extensions) — programmatic lifecycle hooks and tool interception.
+- [Tools Reference](#tools-reference) — built-in tool names used in matcher patterns.

package/assets/docs/how-it-works.md

@@ -32,7 +32,7 @@ CODA draws on a few different kinds of memory:
 
 **In-session context** — everything you've said and everything CODA has read or done in the current session. This builds up as the session progresses, which is why later turns in a session are often better than earlier ones — CODA has more context.
 
-**AGENTS.md (instructions you give)** — project-specific instructions injected at the start of every session. This is how *you* tell CODA about your project's conventions, quality gates, and constraints.
+**Project instructions (instructions you give)** — `AGENTS.md` is the preferred filename; `AGENT.md` and `CLAUDE.md` are fallbacks. CODA loads instructions from the launch directory at startup and can attach more-specific files as it reads deeper paths. This is how *you* describe conventions, quality gates, and constraints.
 
 **MEMORY.md (facts CODA learns)** — durable notes the agent keeps across sessions: your preferences, decisions, and project gotchas. Unlike AGENTS.md, CODA writes this one itself as it learns. It even survives checkpoint rollbacks — restoring an earlier point never erases what CODA has remembered.
 
@@ -44,13 +44,13 @@ The two files you control directly play different roles:
 | --- | --- | --- |
 | **Who writes it** | You (or `/init`) | CODA, as it learns |
 | **What goes in it** | Project conventions, quality gates, no-go zones | Preferences, decisions, gotchas |
-| **Scope** | The project where it lives | Global (`~/.coda/`) and per-project |
+| **Scope** | Launch-directory root, with more-specific on-read files below it | Global (`~/.coda/`) and per-project |
 | **Survives rollback?** | It's your file — yes | Yes, excluded from checkpoints on purpose |
 | **Commit to Git?** | Yes — share with the team | Usually no — it's agent scratch memory |
 
 ## Compaction: keeping context fresh
 
-Long sessions accumulate a lot of history. Once the conversation reaches a certain size, CODA automatically condenses older messages into a summary (compaction) while keeping recent messages verbatim. This keeps the session running smoothly without losing important context.
+Long sessions accumulate a lot of history. Before each model call, CODA makes a simple two-way choice: **store directly** when the context fits, or **reduce** it when it does not. Reduction first moves stale, large tool results out of the active context and then, when the configured threshold is reached, condenses older messages into a summary while keeping recent messages verbatim. Original transcript rows remain stored, even though the model sees the reduced view.
 
 You can also trigger compaction manually before switching topics:
 

package/assets/docs/index.md

@@ -2,7 +2,7 @@
 
 **CODA** (`coda`) is Globant's AI coding agent. You describe what you want in plain language; CODA reads your codebase, plans the work, makes changes, and runs commands — while you stay in control of every step.
 
-This guide is the authoritative reference for using CODA. Every page is a Markdown file under `~/.coda/docs/`, synced from the version of CODA you have installed. Cross-links use `#page-name` anchors that map directly to the file of the same name (for example, `#config-reference` → `config-reference.md`).
+This guide is the authoritative reference for using CODA. It is synced to the active CODA home under `docs/` (normally `~/.coda/docs/`) from the version you have installed. Cross-links use `#page-name` anchors that map directly to the file of the same name (for example, `#config-reference` → `config-reference.md`).
 
 ## Where to start
 
@@ -10,7 +10,7 @@ If you are brand new, read these in order:
 
 1. [What is CODA?](#overview) — the big picture and what you can do with it.
 2. [Installation](#installation) — get `coda` running on your machine.
-3. [Connect a Provider](#connect-provider) — choose Glob.AI OS (recommended for Globant employees) or a custom OpenAI-compatible / Ollama endpoint, and authenticate.
+3. [Connect a Provider](#connect-provider) — choose Glob.AI (recommended for Globant employees) or a custom OpenAI-compatible / Ollama endpoint, and authenticate.
 4. [Quick Start](#quickstart) — open CODA in a real project and run your first prompt.
 
 ## Table of contents
@@ -19,7 +19,7 @@ If you are brand new, read these in order:
 
 - [What is CODA?](#overview) — overview, the two run modes, and what a session looks like.
 - [Installation](#installation) — requirements, install script vs npm, and upgrading.
-- [Connect a Provider](#connect-provider) — the first-run setup wizard, OAuth vs API key, custom providers.
+- [Connect a Provider](#connect-provider) — the first run's single sign-in, choosing an instance, OAuth vs API key, custom providers.
 - [Quick Start](#quickstart) — your first session in under five minutes.
 - [How CODA Works](#how-it-works) — tools, memory, and compaction under the hood.
 
@@ -46,17 +46,18 @@ If you are brand new, read these in order:
 - [Workflows](#workflows) — orchestrate many agents at once.
 - [Writing Extensions](#extensions) — the extension API reference.
 - [Lifecycle Hooks](#hooks) — shell/HTTP hooks that fire at session, tool, and prompt events.
+- [Configure an MCP Server](#add-mcp-server-skill) — let CODA safely turn a package, command, repository, or URL into MCP configuration.
 
 ### Operations & reference
 
 - [Configuration](#configuration) — how settings cascade and where they live.
 - [Configuration Reference](#config-reference) — config keys, defaults, and environment variables.
 - [config.json — A Complete Example](#config-json) — a full, annotated `config.json` you can copy from.
-- [View & Share Logs](#logging) — `coda logs`, redaction, and support bundles.
-- [FAQ](#faq) — short answers to common questions.
+- [View & Share Logs](#logging) — `coda logs`, redaction, support bundles, and the support contact.
+- [FAQ](#faq) — short answers to common questions, including how to check your installed version.
+- **What changed?** Run `coda upgrade --check` to compare your installed version with the current release, then check the release notes published with that version.
 - [Glossary](#glossary) — definitions for the terms used throughout.
-- [Release History](#release-history) — notable changes by version.
 
 ## A note on safety
 
-CODA is built to be safe on real codebases. It asks before doing anything risky (see [Permissions & Approvals](#permissions)), snapshots your files before every turn so you can roll back (see [Sessions & Checkpoints](#sessions)), and never touches your project's own Git history. If you only remember one thing: when CODA heads the wrong way, press **Esc** to interrupt, then redirect — that is faster than undoing a pile of changes.
+CODA is built to be safe on real codebases. Every tool call goes through an authorization decision, with `ask` actions sent to you for approval (see [Permissions & Approvals](#permissions)). CODA snapshots your files before every turn so you can roll back (see [Sessions & Checkpoints](#sessions)), and it never touches your project's own Git history. If you only remember one thing: when CODA heads the wrong way, press **Esc** to interrupt, then redirect — that is faster than undoing a pile of changes.