@globant/coda-darwin-x64 1.3.0 → 1.4.0

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.

package/assets/docs/permissions.md

@@ -1,15 +1,17 @@
 # Permissions & Approvals
 
-CODA can read files, run shell commands, and edit your code — but it asks before doing anything risky. Every tool call goes through an always-on **authorization engine** that decides `allow` / `ask` / `deny`. This human-in-the-loop (HITL) design keeps you in control: CODA proposes an action, you approve or skip it, and nothing irreversible happens behind your back.
+CODA can read files, run shell commands, and edit your code. Every tool call goes through an always-on **authorization engine** that decides `allow` / `ask` / `deny`. `allow` runs, `deny` does not, and `ask` pauses for your decision. This human-in-the-loop (HITL) design keeps you in control without prompting for every routine action.
 
 Rules and modes combine to form a layered safety net — you stay in control even when the agent runs largely on its own. This page covers the permission modes, the easy plain-English way to change permissions (`propose_policy`), the rule syntax the agent writes for you, how decisions are made, and the un-relaxable catastrophic floor.
 
 ## How approvals work
 
-When CODA wants to do something that could change your system, it pauses and shows you exactly what it's about to do. In the interactive TUI you answer with a single key:
+When the engine returns `ask`, CODA pauses and shows the effective action and reason. In the interactive TUI:
 
-- **Y** — allow this action and continue.
-- **N** — skip it; CODA carries on without running that action.
+- **Y** — allow this action once and continue.
+- **A** — allow the displayed reusable rule for this session, when that option is available.
+- **Arrow keys + Enter** — choose another option, including a permanent project rule when CODA can derive one. Permanent changes get a second confirmation that explains their scope.
+- **N** — deny it; CODA carries on without running that action.
 
 Some prompts are **questions** rather than yes/no approvals — for example when a tool needs you to pick from a numbered list or type a short answer. There you type your choice (or the number) and press **Enter**.
 
@@ -17,7 +19,7 @@ How often CODA stops to ask depends on your **permission mode** and your **rules
 
 ## Permission modes
 
-The main approval control is the **permission mode** — the master dial that sets the agent's default level of autonomy. Press **Ctrl+P** to cycle the session between three modes; set the default with `permissions.defaultMode` in your config (globally in `~/.coda/config.json`, or per project in `.coda/config.json`).
+The main approval control is the **permission mode** — the master dial that sets the agent's default level of autonomy. Press **Ctrl+P** to cycle the session between three modes; set the default in `~/.coda/config.json`. A project `.coda/config.json` can make that starting mode more restrictive, but it cannot silently raise autonomy above your user setting.
 
 The three valid values are `"read-only"`, `"default"`, and `"auto"`.
 
@@ -130,12 +132,14 @@ It is **on by default**. To stop the agent from ever suggesting permanent rule c
 
 To pin a specific command regardless of mode, add rules under `permissions` in `config.json`:
 
-```jsonc
-"permissions": {
-  "defaultMode": "default",
-  "allow": ["Bash(git status)", "Bash(npm test)"],
-  "ask":   ["Bash(git push:*)"],
-  "deny":  ["Bash(rm:*)"]
+```json
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": ["Bash(git status)", "Bash(npm test)"],
+    "ask": ["Bash(git push:*)"],
+    "deny": ["Bash(rm:*)"]
+  }
 }
 ```
 
@@ -327,7 +331,7 @@ Two things to know when reading the output:
 - **See what applies first:** run `/permissions` (or `coda permissions` outside a session) — see the section "Seeing what applies right now" above.
 - **In the session:** press **Ctrl+P** to cycle the permission mode.
 - **Just ask:** tell the agent in plain English (`allow pnpm build`, `never allow rm -rf`) and it drafts the rule via `propose_policy` for your approval.
-- **Default / per project:** `permissions.defaultMode` and `permissions.allow`/`ask`/`deny` in `~/.coda/config.json` or a project's `.coda/config.json` (project config overrides your personal default) — see [Configuration](#configuration).
+- **Default / per project:** set `permissions.defaultMode` and `permissions.allow`/`ask`/`deny` in `~/.coda/config.json` or a project's `.coda/config.json`. Rules accumulate across scopes; a project mode can tighten but cannot raise your personal default — see [Configuration](#configuration).
 - **For a headless run:** the `--auto-approve none|all` flag (see [Commands & Flags](#cli-reference)).
 
 ## See also

package/assets/docs/quickstart.md

@@ -51,12 +51,16 @@ Search the codebase for code smells around error handling, duplicated logic, and
 
 ## 3. Review what CODA does
 
-When CODA wants to run a shell command or write to a file, it shows you what it's about to do and asks for approval (depending on your [bash approval settings](#config-reference)). You can:
+Every tool call passes through CODA's authorization engine. Safe actions can run immediately, denied actions do not run, and actions classified as `ask` open an approval prompt. When a prompt appears, you can:
 
-- Press **Y** to approve and continue
-- Press **N** to skip that step
+- Press **Y** to approve this action
+- Press **A** to approve the displayed reusable rule for this session, when offered
+- Use **Arrow keys + Enter** to choose another offered option, including a permanent project rule (which gets a second confirmation)
+- Press **N** to deny this action
 - Press **Esc** to interrupt the current turn entirely
 
+How often you see a prompt depends on the current permission mode and your `allow` / `ask` / `deny` rules. See [Permissions & Approvals](#permissions).
+
 If CODA goes in the wrong direction, interrupt early — don't let it keep going. Interrupting and redirecting is faster than undoing a lot of changes.
 
 ## 4. Undo anything
@@ -75,7 +79,7 @@ This opens the timeline picker (you can also type `/rewind`, or press **Esc** tw
 
 A few small habits make long sessions much better:
 
-- **Watch the context meter.** The status bar shows how full the conversation context is. As it nears 100%, CODA compacts automatically — or you can run `/compact` before switching to a new topic.
+- **Watch the context meter.** The status bar shows how full the conversation context is. CODA reduces context automatically before it fills the window — or you can run `/compact` before switching to a new topic.
 - **Start fresh for unrelated work.** `/new` opens a clean session (the old one is saved and resumable) so unrelated context doesn't bleed into the next task.
 - **Switch models when it helps.** Press `Shift+Tab` to cycle favorite models, or run `/switch-model` to pick one — use a stronger model for hard reasoning, a cheaper one for routine edits.
 - **Resume later.** When you exit (`Ctrl+C` twice or `/exit`), CODA prints a `coda --session-id <id>` command you can paste to pick up exactly where you left off. You can also run `/sessions` from within any active session to open the session browser and switch directly. For an even quicker pick-up, run `coda --lastsession` from your project root to resume the most recent session automatically.

package/assets/docs/sessions.md

@@ -130,7 +130,7 @@ It prints a health summary: current **State**, the **project** + **workspace id*
 
 ## Watch the context fill level
 
-The status bar at the bottom of the TUI shows a context fill percentage. When it approaches 100%, CODA will automatically compact the session history. If you're deep in a long session and things start feeling off, try:
+The status bar at the bottom of the TUI shows a context fill percentage. CODA begins automatic reduction before the window is exhausted: it can move stale tool output aside first and summarize older history at the configured threshold. If you're deep in a long session and things start feeling off, try:
 
 ```text
 /compact

package/assets/docs/shortcuts.md

@@ -36,7 +36,7 @@ These shortcuts work inside the interactive TUI. Type `?` at any time to open th
 | --- | --- |
 | `Ctrl+↑` | Scroll up in the transcript |
 | `Ctrl+↓` | Scroll down in the transcript |
-| `Ctrl+Shift+C` | Copy the last code block to clipboard |
+| `Ctrl+Shift+C` | Copy the last code block to clipboard (use [`/copy`](#cli-reference) to copy a full response instead) |
 | `Esc Esc` | Open the timeline picker (double-press within ~750 ms when the chat input is empty and no turn is running) |
 
 ## Model switching

package/assets/docs/tools-reference.md

@@ -36,9 +36,15 @@ To limit which tools a single run may use, pass `coda --tools …` (see [Command
 | `skills` | Load a discovered skill by name |
 | `run_agent`, `wait_agents`, `cancel_agent` | Start and manage delegated [agent](#agents) runs |
 | `workflow` | Run a named workflow script that orchestrates multiple agents in the background (requires agents to be enabled) |
+| `todo_write`, `todo_update`, `todo_list` | Record, revise, and read the session's TODO plan (enabled by config; see [What you can configure](#what-you-can-configure)) |
+| `propose_policy` | Propose a permanent change to your authorization policy — add/remove a rule or set the permission mode (a tightening applies immediately; a loosening asks you first) |
+| `update_run` | End the active autonomous run — mark it `complete` or `blocked`. Available only while an autonomous run is active |
+| `reconfigure_loop` | Reconfigure the active `/loop`'s schedule in place (`intervalMs`, `cap`, and/or `maxDurationMs`). Available only while a loop is active |
 
 Extensions and plugins can register more tools the same way the core registers these built-ins.
 
+A few tools are **registered dynamically** and only appear while the matching mode is running: `update_run` exists only during an [autonomous run](#guide-automate) and `reconfigure_loop` only during a `/loop` — both are unregistered the moment that run or loop ends (mirroring how `mcp_execute` comes and goes with its MCP servers).
+
 ### How CODA chooses a tool
 
 You never name a tool — CODA picks based on the task. A few patterns are worth knowing so its behavior feels predictable:
@@ -66,6 +72,7 @@ Tool behavior is configured in a few different places — some from the `/settin
 | **OmniParser** | How much extracted document text is inlined in a result vs written to `.coda/omni-parser/`. | `CODA_OMNI_PARSER_INLINE_THRESHOLD_CHARS` env var |
 | **MCP** | Which servers load — which in turn decides whether `mcp_execute` is useful. | The `/mcp` manager |
 | **Agents** | Whether the delegation tools exist, and how runs behave. See [Agents](#agents). | Config (`agents.*`) + the `/agents` manager |
+| **TODO planning** | Whether the `todo_write` / `todo_update` / `todo_list` tools exist. On by default in interactive sessions; headless runs enable them only when `CODA_ENABLE_TODOS` is set to `1`, `true`, or `yes`. | Config (`tools.todos.enabled`) + `CODA_ENABLE_TODOS` env var (headless) |
 
 ## Web fetch
 
@@ -111,7 +118,7 @@ The tool can also write a fetched page straight to a file (always confined to `.
 
 When a delegated [agent](#agents) run executes, it uses a trimmed tool set. Two categories are removed from every child session:
 
-- **Delegation tools** — `run_agent`, `wait_agents`, and `cancel_agent` are unregistered, so a sub-agent **cannot delegate further** (no nested sub-agents) or wait on other runs.
+- **Delegation tools** — `run_agent`, `wait_agents`, and `cancel_agent` are unregistered, so a sub-agent **cannot delegate further** (no nested sub-agents) or wait on other runs. `workflow` is currently still registered in a child session, so a sub-agent can launch a workflow.
 - **User prompting** — `ask_user` is unregistered, so a sub-agent **cannot prompt you** for input. It must complete its task from the instructions it was given.
 
 The `skills` tool is also unavailable in child sessions — skill loading is main-agent-only. The remaining parent tools (read, edit, write, bash, search, etc.) are inherited, and the MCP service is deliberately shared, so `mcp_execute` also works inside a child run.

package/assets/docs/workflows.md

@@ -76,7 +76,7 @@ Create a workflow that keeps generating test ideas until it finds no new ones or
 
 > **Tip — name the inputs.** Mentioning the folder, the diff, or the output location in your request helps `create-workflow` set up the workflow's arguments, so later runs can infer them from a one-line prompt.
 
-The `create-workflow` agent **writes the file but doesn't run it**. The **first** time you run a freshly authored workflow, CODA asks you to confirm — you can approve it, view the generated script, or decline. After that first confirmation, running it again goes straight to the background.
+The `create-workflow` agent **writes the file but doesn't run it**. A freshly authored workflow gets a first-run confirmation where you can run it, view the generated script, request amendments, or decline. Workflows already committed under the current project's `.coda/workflows/` can run directly. Workflows discovered from parent/user directories or plugins ask for approval the first time; editing one changes its content and asks again.
 
 ## Workflow authoring conventions
 
@@ -118,6 +118,7 @@ A workflow doesn't just print a wall of text. As it runs it typically:
 - **Fans out** the work across agents (one per file, module, or ticket) and runs them up to a concurrency cap derived from available CPU cores (capped at 16).
 - **Synthesizes** their results — often into one or more **artifacts** written to disk (a report, a JSON summary, a translated doc).
 - **Reports back** on a later turn with a short overview and links to any artifacts it wrote, so you can open them when you're ready.
+- **Tracks usage** across its agent runs, including the agent count, output tokens, and USD cost when the provider reports it.
 
 Because each step is a real agent run, you can watch the individual agents in the `/workflows` dashboard and open their transcripts, exactly like standalone [agents](#agents).
 

package/assets/skills/configure-mcp/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: configure-mcp
+description: Configure g-coda's MCP client to connect to an MCP server from a Git URL, remote HTTP endpoint, or npm/pip package, at project or global scope. Use when the user asks to add, register, configure, install, or set up an MCP server or MCP client. e.g. "add the playwright MCP server", "configure an MCP server from this URL", "install this MCP tool globally".
+---
+
+# Configure MCP
+
+Configure g-coda's MCP client to connect to an MCP server by registering the server entry in the correct config file at the user-chosen scope. The input can be a Git URL, remote HTTP endpoint, or npm/pip package. Reject inputs from which no valid transport (`command` or `url`) can be derived — write nothing in that case.
+
+---
+
+## Golden Rule
+
+**Never overwrite existing server entries.** Always merge your new entry into the existing `mcpServers` object. If a server with the same name already exists, confirm with the user before replacing it.
+
+**Never hardcode secrets.** Tokens, API keys, and credentials must use `${VAR}` or `${VAR:-default}` interpolation — never inline values.
+
+---
+
+## Step 1: Determine Scope
+
+Ask the user which scope they want if not specified:
+
+| Scope | Write to | When to use |
+|---|---|---|
+| **Project** | `<cwd>/.coda/mcp.json` | Only this repo; shared via version control |
+| **Global** | `~/.coda/mcp.json` | All projects on this machine; personal |
+
+- `<cwd>` = `process.cwd()` where g-coda is running, not the nearest `.git` root.
+- If unsure, **default to project scope**.
+- A project entry always wins over a global entry with the same server name.
+
+**Target file:** always write to `mcp.json` (top-level `mcpServers` key).
+
+---
+
+## Step 2: Detect Input Type and Validate
+
+### 2a. Remote HTTP endpoint
+
+Input is `https://…` or `http://…` pointing to a live MCP endpoint (Streamable HTTP transport).
+
+Example entry — replace the URL, token variable name, and header values with the real ones:
+
+```jsonc
+{
+  "url": "https://api.example.com/mcp",
+  "authorizationToken": "Bearer ${API_TOKEN}",
+  "headers": { "X-Custom": "${CUSTOM_HEADER}" },
+  "timeout": 30
+}
+```
+
+> ⚠️ Make sure no tokens or secrets are exposed — always use `${VAR}` interpolation for credentials.
+
+Transport: `url` → HTTP. Do **not** set `command`.
+
+### 2b. npm/pip package or CLI tool
+
+Input is a package name, `npx`/`uvx` invocation, or local binary path (stdio transport).
+
+Example entry — replace the package name and env var names with the real ones:
+
+```jsonc
+{
+  "command": "npx",
+  "args": ["-y", "@scope/mcp-package@latest"],
+  "env": { "API_KEY": "${MY_API_KEY}" }
+}
+```
+
+> ⚠️ Make sure no tokens or secrets are exposed — always use `${VAR}` interpolation for credentials.
+
+Common patterns: `npx -y <pkg>`, `uvx <pkg>`, `node /path/to/server.js`, `/path/to/binary`.
+
+Transport: `command` → stdio. Do **not** set `url`.
+
+### 2c. Git URL
+
+Most MCP server repositories support **multiple installation methods** (e.g. `npx`, `uvx`, Docker, a remote HTTP endpoint, or a local build). Do not assume — read the repo's documentation first, then ask the user which method they prefer.
+
+Steps:
+
+1. **Clone temporarily** to read the docs:
+   - Project scope: `<cwd>/.coda/tmp/<name>/`
+   - Global scope: `~/.coda/tmp/<name>/`
+   - Command: `git clone --depth 1 <url> <tmp-dir>`
+2. **Read the README and any MCP-specific docs** to identify all available installation methods.
+3. **Ask the user** which method they prefer — present the options you found. Common options:
+   - `npx -y <pkg>` or `uvx <pkg>` (no local build needed — preferred when available)
+   - Remote HTTP endpoint (if the project exposes one)
+   - Local build (`npm install && npm run build`, entry via `node dist/index.js`)
+4. **Derive the entry** using the chosen method (see sections 2a and 2b for the corresponding entry shape).
+5. **Write the config entry** to `mcp.json`.
+6. **Delete the temporary clone** (`<tmp-dir>`) — it is no longer needed once the config entry is written.
+
+> If the chosen method does not require the cloned directory at runtime (e.g. `npx`/`uvx`/HTTP), the tmp directory is always safe to remove. If the user explicitly chooses a local-build method and the runtime depends on the clone, move the directory to its final location (`<cwd>/.coda/mcp-servers/<name>/` or `~/.coda/mcp-servers/<name>/`) instead of deleting it, and tell the user.
+
+### 2d. Rejection — no derivable transport
+
+If you **cannot** determine either a `command` or a `url` from the input, **do not write anything**. Respond:
+
+> "I couldn't determine a valid MCP server transport from what you provided. An MCP server needs either a runnable command (for stdio transport) or an HTTP URL (for Streamable HTTP transport). Please share the server's npm package name, a Git URL, a binary path, or its HTTP endpoint."
+
+---
+
+## Step 3: Build the Server Entry
+
+A valid entry has **exactly one** of `command` (stdio) or `url` (http) — never both, never neither.
+
+| Field | Transport | Description |
+|---|---|---|
+| `command` | stdio | Executable to run as a subprocess |
+| `args` | stdio | Arguments for the subprocess |
+| `cwd` | stdio | Working directory for the subprocess |
+| `url` | http | MCP server HTTP endpoint |
+| `authorizationToken` | http | Shorthand `Authorization` header; supports `${VAR}` |
+| `headers` | http | Extra request headers; string values support `${VAR}` |
+| `timeout` | http | Request timeout in seconds |
+| `env` | both | Environment variables; supports `${VAR}` and `${VAR:-default}` |
+| `disabled` | both | `true` to skip at load time (default: `false`) |
+
+Secrets in `env`, `headers`, and `authorizationToken` are resolved from `~/.coda/.secrets`, project `.env`, and `process.env` at load time. Never put raw credentials in the config.
+
+Choose a descriptive, kebab-case server name (e.g., `playwright`, `github`, `my-internal-api`).
+
+---
+
+## Step 4: Non-Destructive Merge into Config
+
+### Writing to `mcp.json` (preferred)
+
+```jsonc
+// <cwd>/.coda/mcp.json  (project)  or  ~/.coda/mcp.json  (global)
+{
+  "mcpServers": {
+    "<server-name>": { /* entry fields */ }
+  }
+}
+```
+
+Merge steps:
+1. Read the existing file, or start with `{ "mcpServers": {} }` if absent.
+2. Check whether `mcpServers["<server-name>"]` exists — confirm with the user before replacing.
+3. Add or replace only the target key; preserve all other entries.
+4. Write the file back.
+
+---
+
+## Step 5: Verify and Notify
+
+After writing:
+
+1. Show the user exactly what was written (entry + file path).
+2. Confirm the file is valid JSON (no trailing commas, balanced braces).
+3. Remind the user how to activate the change:
+
+> **MCP changes are not picked up by `/skills refresh`.** To activate:
+> - Run `/mcp` → select **Reload MCP servers**, or
+> - Restart g-coda.
+
+4. For cloned Git repos, delete the temporary directory (`<cwd>/.coda/tmp/<name>/` or `~/.coda/tmp/<name>/`) once the config entry has been written — unless the user chose a local-build method that requires the directory at runtime, in which case it was already moved to its final location as part of step 2c.
+
+---
+
+## Examples
+
+### Example 1 — npm package, project scope
+
+**User:** "Add the Playwright MCP server to this project."
+
+Written to `<cwd>/.coda/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+**Response:** Added `playwright` to `.coda/mcp.json`. Run `/mcp` → Reload MCP servers to activate it.
+
+---
+
+### Example 2 — HTTP endpoint, global scope, with auth
+
+**User:** "Set up the GitHub MCP server globally. My token is in `GITHUB_TOKEN`."
+
+Written to `~/.coda/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "authorizationToken": "Bearer ${GITHUB_TOKEN}",
+      "timeout": 30
+    }
+  }
+}
+```
+
+**Response:** Added `github` to `~/.coda/mcp.json`. Make sure `GITHUB_TOKEN` is set in your environment or `~/.coda/.secrets`. Run `/mcp` → Reload MCP servers to activate it.
+
+---
+
+### Example 3 — Git URL, project scope
+
+**User:** "Install from https://github.com/example/my-mcp-server into this project."
+
+Steps:
+1. Clone to `<cwd>/.coda/tmp/my-mcp-server/` with `git clone --depth 1 <url> <tmp-dir>`.
+2. Read `README.md` — it documents two options: `npx -y @example/my-mcp-server` or a local build.
+3. Ask the user: *"The repository supports `npx` (no local build needed) or a local build. Which do you prefer?"*
+4. User chooses `npx`. Derive the entry (section 2b).
+5. Write config, then delete `<cwd>/.coda/tmp/my-mcp-server/`.
+
+Written to `<cwd>/.coda/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "my-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@example/my-mcp-server@latest"]
+    }
+  }
+}
+```
+
+**Response:** Added `my-mcp-server` to `.coda/mcp.json` and removed the temporary clone. Run `/mcp` → Reload MCP servers to activate it.
+
+---
+
+### Example 4 — Rejection
+
+**User:** "Add `my-special-tool` as an MCP server."
+
+No URL or command is derivable from the name alone.
+
+**Response:** I couldn't determine a valid MCP server transport for `my-special-tool`. Please share the npm package name, a Git URL, a binary path, or the HTTP endpoint.
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|---|---|
+| File exists but is invalid JSON | Report the parse error and path; do not overwrite. Ask user to fix manually. |
+| Server name already exists | Show the existing entry; ask user to confirm replacement. |
+| No transport derivable | Reject with a clear explanation (Step 2d). Do not write anything. |
+| Git clone fails | Report the error and path; do not write a config entry. Clean up any partial tmp directory. |
+| No installation method found in repo docs | Tell the user no clear method was found; ask them to provide the command or URL directly. |
+| Secret value unclear | Ask which env var name to use; never guess a value. |
+
+---
+
+## Instructions for the Agent
+
+1. **Clarify scope first** — ask project vs global if not stated. Default to project.
+2. **Derive the entry** — HTTP URL → `url` field; package/git/binary → `command` field. For Git URLs, clone to a tmp dir, read the docs, ask the user which method to use, then delete the tmp dir. If no transport is derivable, reject immediately (do not write).
+3. **Choose the config file** — always use `mcp.json` (top-level `mcpServers` key).
+4. **Merge non-destructively** — read the existing file first; preserve all other entries.
+5. **No inline secrets** — always use `${VAR}` notation; tell the user which env var to set.
+6. **Validate JSON** — ensure the written file is syntactically valid.
+7. **Remind about reload** — MCP changes need `/mcp` → Reload MCP servers or a restart. `/skills refresh` does NOT reload MCP.
+8. **Show the result** — always display the final entry and the full path of the file written.
+
+---
+
+## Deliverables
+
+When done, provide:
+
+1. The exact file path written (e.g., `<cwd>/.coda/mcp.json` or `~/.coda/mcp.json`).
+2. The server entry that was added (JSON block).
+3. Any env vars the user needs to set (if secrets are involved).
+4. The activation command: `/mcp` → Reload MCP servers (or restart g-coda).

package/assets/skills/create-hook/SKILL.md

@@ -154,15 +154,15 @@ Every hook receives a JSON object on stdin. All events include these base fields
 ```json
 {
   "session_id": "abc123",
-  "transcript_path": "/path/to/transcript.json",
+  "transcript_path": "",
   "cwd": "/path/to/project",
   "hook_event_name": "PreToolUse",
-  "permission_mode": "default",
-  "agent_id": "...",
-  "agent_type": "main"
+  "cli_version": "0.4.2"
 }
 ```
 
+`transcript_path` is always an empty string (Coda persists conversations to a database, not a transcript file; the field exists for wire-compatibility). `cli_version` is the running Coda version — also available to command hooks as the `CODA_VERSION` env var, which is cheaper than parsing stdin in hot-path hooks. `permission_mode`, `agent_id`, and `agent_type` are reserved fields that are currently never populated — do not depend on them.
+
 Additional fields by event:
 
 **Tool events** (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`):