@globant/coda-darwin-x64 1.2.0 → 1.4.0

package/assets/docs/faq.md

@@ -61,11 +61,11 @@ Use `coda --lastsession` to resume the most recent session. For a specific sessi
 
 ### 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,7 +77,7 @@ 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). Set your default in `~/.coda/config.json` via `permissions.defaultMode`; a project config can tighten but cannot raise 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`.
@@ -100,7 +100,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
 
@@ -130,7 +130,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 +147,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.
@@ -159,7 +169,7 @@ Everything lives under `~/.coda/` — `config.json`, `.secrets`, the session dat
 
 ### 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 +177,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
 

package/assets/docs/glossary.md

@@ -4,18 +4,18 @@ 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. |
 | **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`. |
+| **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 OS 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`. |
@@ -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-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 your permission mode, which you cycle with **Ctrl+P** or set via `permissions.defaultMode`:
 
 | 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:
 
@@ -64,13 +64,13 @@ The most valuable things to share live in the repo and apply to everyone who clo
 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:
 
 - **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.
+- **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
 

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:
 
@@ -88,7 +88,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 +102,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 +113,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": [
@@ -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
 
@@ -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.

package/assets/docs/installation.md

@@ -23,7 +23,7 @@ curl -fsSL https://docs.globant.ai/en/filedownload?4622,12 | bash
 irm 'https://docs.globant.ai/en/filedownload?5346,6' | iex
 ```
 
-Alternatively, you can install via **npm**. Note this requires Node.js, whereas the install script above does not:
+Alternatively, install the `@globant/coda` launcher from the public npm registry. This requires Node.js; the install script above does not:
 
 ```bash
 npm i -g @globant/coda
@@ -47,12 +47,12 @@ Knowing the layout helps when you troubleshoot:
 
 ## Keeping CODA up to date
 
-To upgrade later, run `coda upgrade` from your terminal, or `/upgrade` from inside the TUI. CODA picks the right mechanism automatically based on how you installed it:
+To upgrade later, run `coda upgrade` from your terminal, or `/upgrade` from inside the TUI. CODA checks the configured release registry—public npm by default, or your `CODA_NPM_REGISTRY` mirror—for the latest `@globant/coda` launcher version, then picks the right mechanism automatically:
 
-- **Installed via npm** → it upgrades through npm.
-- **Installed via the script** → it swaps in the latest native binary under `~/.coda/bin`.
+- **Installed via npm** → it upgrades `@globant/coda` globally so npm's package metadata stays consistent.
+- **Installed via the script** → it downloads the matching platform package, verifies its integrity, and atomically swaps the native binary under `~/.coda/bin`.
 
-You can see what changed between versions in [Release History](#release-history).
+Use `coda upgrade --check` to compare your current and latest versions without installing.
 
 ## Troubleshooting the install
 

package/assets/docs/logging.md

@@ -114,7 +114,7 @@ When you can't tell what happened from the rendered view, press **Space**/**Ente
 1. Reproduce the issue so it's fresh in the logs.
 2. Run `coda logs export` (optionally `--since 30m` to scope it).
 3. Open the printed file from `~/.coda/exports/` and skim it — redaction is automatic, but a glance confirms it.
-4. Attach it. Nothing was uploaded; the bundle only contains what you choose to share.
+4. Attach it to your support request, or email it to **coda-tech-support@globant.com**. Nothing was uploaded; the bundle only contains what you choose to share.
 
 ## See also
 

package/assets/docs/overview.md

@@ -26,13 +26,13 @@ A session is a back-and-forth loop. You set the goal; CODA does the work and che
 | Review what it's about to do | Edits files, runs shell commands |
 | Approve, adjust, or undo | Saves checkpoints so nothing is permanently lost |
 
-In practice, a turn looks like this: you send a message, CODA snapshots your files, then it reasons, calls tools (reading, searching, editing, running commands), pausing to ask for approval before anything risky, and finally summarizes what it did. You can interrupt at any time with **Esc** and redirect.
+In practice, a turn looks like this: you send a message, CODA snapshots your files, then it reasons and calls tools (reading, searching, editing, running commands). Every tool call passes through the authorization engine; only an `ask` decision pauses for your approval. CODA finally summarizes what it did. You can interrupt at any time with **Esc** and redirect.
 
-The longer a session runs, the more context CODA accumulates — which is why later turns are often sharper than the first. When the conversation grows large, CODA condenses older history automatically (compaction) so it keeps running smoothly. See [How CODA Works](#how-it-works).
+The longer a session runs, the more context CODA accumulates — which is why later turns are often sharper than the first. When the conversation grows large, CODA reduces the active context automatically: stale tool output moves aside first, and older history is summarized when needed. See [How CODA Works](#how-it-works).
 
 ## Two ways to run it
 
-**Interactive (TUI)** — a full-screen terminal UI. Type prompts, review tool output, approve commands, switch models, and navigate your session history in real time. This is how you'll use CODA day-to-day.
+**Interactive (TUI)** — a full-screen terminal UI. Type prompts, review tool output, approve actions, switch models, and navigate your session history in real time. This is how you'll use CODA day-to-day.
 
 **Headless (Batch)** — a single command, no UI. Give CODA a prompt from the shell, it runs, and exits with a status code. Use this in scripts, CI pipelines, and automation.
 
@@ -42,10 +42,11 @@ Both share the same agent, the same configuration, and the same tools — the di
 
 ## What stays in your control
 
-- **Approvals** — CODA asks before running risky shell commands or overwriting files it hasn't read. You tune how often it asks. See [Permissions & Approvals](#permissions).
+- **Authorization** — every tool call is allowed, denied, or sent to you for approval according to the current mode and rules. See [Permissions & Approvals](#permissions).
 - **Undo** — every turn is checkpointed; restore any point from the `/timeline` picker.
 - **Secrets** — API keys live in `~/.coda/.secrets`, never committed to Git, and are scrubbed from logs before they hit disk. See [Configuration](#configuration) and [View & Share Logs](#logging).
 - **Your Git history** — checkpoints use a separate private shadow repository, so `git log`, branches, and commits are entirely yours.
+- **Transcript controls** — drag across rendered text to copy the selection, press **Ctrl+Shift+C** to copy the latest complete fenced code block, and use **Ctrl+Up** / **Ctrl+Down** to scroll.
 
 ## When to reach for CODA (and when not to)
 
@@ -65,7 +66,7 @@ Every turn follows the same shape. Understanding it makes CODA predictable:
 1. **You send a message.** CODA snapshots your files (a checkpoint) before doing anything.
 2. **It reasons and plans.** For non-trivial work it sketches the steps first.
 3. **It calls tools.** Reading files, searching, editing, running shell commands — one or more at a time.
-4. **It pauses for approval** before anything risky (a shell command your permission mode or rules gate to `ask`, or overwriting a file it never read). You answer with a single key.
+4. **It authorizes each tool call.** `allow` runs, `deny` returns a refusal, and `ask` pauses for your decision.
 5. **It summarizes** what changed and why, then hands the turn back to you.
 
 At any point you can press **Esc** to interrupt and redirect — that is almost always faster than letting it finish and undoing the result.
@@ -76,7 +77,7 @@ A session is more than a chat log. As it runs, CODA builds up:
 
 - **Conversation context** — your prompts and its work so far. This is why later turns are often sharper than the first.
 - **What it read from disk** — always the live file, never a stale cache.
-- **`AGENTS.md` instructions** — your project's conventions, injected at the start of every session.
+- **Project instructions** — `AGENTS.md` (or the `AGENT.md` / `CLAUDE.md` fallback) from the launch directory, plus more-specific instructions attached when CODA reads deeper files.
 - **`MEMORY.md` facts** — durable notes CODA writes for itself and carries across sessions.
 
 See [How CODA Works](#how-it-works) for the mechanics of tools, memory, and compaction.