@globant/coda-linux-arm64 1.4.0 → 1.5.0

package/assets/docs/faq.md

@@ -12,7 +12,7 @@ coda --version
 
 ### How do I add or change a provider?
 
-From your terminal (outside a session): `coda --reconfigure`. From inside an active session: `/providers`. Note that `/providers` changes require restarting CODA to take effect.
+From your terminal (outside a session): `coda --reconfigure`. From inside an active session: `/providers`. Both open the same wizard, and the provider you configure there becomes the active one. A `/providers` save that only changes the Glob.AI project applies right away; other changes need a restart of CODA to take effect.
 
 ### How do I set up two projects (e.g. two Clients projects) and switch between them?
 
@@ -20,7 +20,7 @@ Configure each one as its own profile, then switch with `/switch-profile`:
 
 1. Run `/providers` and sign in to the first Clients project (OAuth or API key). CODA saves it as a named profile.
 2. Run `/providers` again and sign in to the **second** Clients project. Because it's a different organization/project, CODA stores it as a **separate** profile rather than overwriting the first.
-3. From then on, flip between them with `/switch-profile` (alias `/sp`) — no argument opens a picker, or pass the profile id directly (`/switch-profile geai-clients`). The switch is saved as `activeProfile` and applies on the next launch.
+3. From then on, flip between them with `/switch-profile` (alias `/sp`) — no argument opens a picker, or pass the profile id directly (`/switch-profile geai-clients`). The switch is saved as `activeProfile` and applies to the session right away when it is idle; while a response is running, it applies on the next launch.
 
 Use `/switch-profile` when you only want to change which configured profile is active; use `/providers` to add, edit, or remove one. See [Connect a Provider](#connect-provider) › "Switch between configured providers".
 
@@ -28,10 +28,10 @@ Use `/switch-profile` when you only want to change which configured profile is a
 
 You have two options:
 
-- **Stay in the session** — run `/project` (Glob.AI OS OAuth only). It lists the organizations and projects your account can access; pick one, or run `/project <id>` directly. This re-targets the active project without a restart. See [Connect a Provider](#connect-provider) › "Switching the active Glob.AI OS project".
-- **Switch profiles** — if you've configured the other project as its own profile (see above), `/switch-profile` selects it instead. That change applies on the next launch.
+- **Stay in the session** — run `/project` (Glob.AI OAuth only). It lists the organizations and projects your account can access; pick one, or run `/project <id>` directly. This re-targets the active project without a restart. See [Connect a Provider](#connect-provider) › "Switching the active Glob.AI project".
+- **Switch profiles** — if you've configured the other project as its own profile (see above), `/switch-profile` selects it instead. That change applies right away when the session is idle, else on the next launch.
 
-Reach for `/project` for a quick in-session project change on the same login; use `/switch-profile` to move between separately configured profiles (which may also differ in environment or auth method).
+Reach for `/project` for a quick in-session project change on the same login; use `/switch-profile` to move between separately configured profiles (which may also differ in instance or auth method).
 
 ### How do I run CODA in batch mode, and how does it authenticate?
 
@@ -45,9 +45,9 @@ By default a batch run uses your **active profile** (`activeProfile` from `~/.co
 
 You can't start an interactive **OAuth browser login** in batch mode — there's no browser to hand off to. For headless OAuth, reuse a profile you already authenticated interactively (`--profile <id>` or the active profile). To provide credentials inline for a one-off run without saving them, use the ephemeral flags — for example `--provider openai-compat --base-url … --api-key …`, or `--provider glob-ai --instance clients --api-key …`. The key is held only in memory and never written to disk. See [Automate with headless mode](#guide-automate) › "Authenticating in batch mode".
 
-### CODA opened and immediately shows a setup wizard. Is that normal?
+### CODA opened and immediately asked me to sign in. Is that normal?
 
-Yes. The wizard appears automatically on first launch if no provider is configured. Follow the prompts to add your credentials. You can also trigger it manually at any time with `coda --reconfigure`.
+Yes. On first launch, with no provider configured, CODA picks the default Glob.AI instance, names it, and asks for its credential — a browser sign-in, or an API key for a key-only instance. That is the whole setup. If your account lives on another instance, run `coda --instance <id>` for one run or `coda configure --instance <id>` to change your default (with `--api-key-stdin` for a key-only instance such as `corp` or `us-v1`). The full setup wizard is still there for other providers: `coda --reconfigure`.
 
 ### How do I get help from inside CODA?
 
@@ -59,6 +59,14 @@ A few ways: type `/help` for the command list, press `?` for the keyboard-shortc
 
 Use `coda --lastsession` to resume the most recent session. For a specific session, use `coda --session-id <id>` — when you exit, CODA prints the exact `coda --session-id <id>` command, ready to copy and paste. From inside CODA, browse sessions with `/sessions`.
 
+### CODA won't start: "its schema differs from what this CODA version needs"
+
+Every time it starts, CODA checks the session database (`~/.coda/coda.db`) and repairs what it safely can on its own. If something can't be repaired — for example the file was changed by a development build, restored from an old backup, or edited by hand — CODA stops before writing anything, lists each problem, and says "Nothing was modified". Either open the database with the CODA version that last used it, or start over with a new session history: close every CODA window, back up the database, and move `coda.db` together with `coda.db-wal` and `coda.db-shm` (if present) out of `~/.coda/`. The next start creates a new database.
+
+### CODA won't start: "it was upgraded by a newer CODA"
+
+Another CODA — a newer CLI, or an app built on a newer CODA SDK — upgraded the session database, which they share, to a version this CODA can't safely use. Nothing was modified. Run `coda upgrade` to bring this installation up to date.
+
 ### What does the context percentage in the status bar mean?
 
 It shows how full the current conversation context is. 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.
@@ -77,11 +85,21 @@ Type `/timeline` (or `/rewind`, or press **Esc** twice) to see all snapshots fro
 
 CODA runs an **authorization engine** that decides `allow` / `ask` / `deny` for every tool call. Two levers control it:
 
-- **Permission mode** — press `Ctrl+P` to cycle the session's mode: **read-only** (only reads run; writes and commands are refused), **default** (reads run, risky actions like `git commit` ask first, destructive ones are denied unless you add an allow rule), and **auto** (risky actions auto-run for unattended/CI use; only catastrophic ones stay blocked). Set your default in `~/.coda/config.json` via `permissions.defaultMode`; a project config can tighten but cannot raise 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). A truly-fresh install (no `permissions` block in any config) starts in **auto**; once any `permissions` block exists without a `defaultMode`, sessions start in **default** — so an upgrade never silently raises autonomy. Saving a rule never changes your mode, so after your first rule new sessions start in `default`; to keep starting in auto, set `permissions.defaultMode: "auto"` yourself or approve the mode change `/init-rules` offers. A config file with a syntax error starts the session in `default`, never `auto`. A managed policy can still force `default`, a project config can tighten but cannot raise the mode, and headless `coda -p` ignores `defaultMode` (it follows `--auto-approve`). A session keeps its mode when you resume it.
 - **Rules** — to always allow or always block a specific command, add `allow` / `ask` / `deny` rules under `permissions` in `config.json` (e.g. `allow Bash(git status)` or `deny Bash(rm:*)`). **Deny always wins**, and a handful of catastrophic actions (`rm -rf /`, `sudo`, a fork bomb) sit behind an un-relaxable floor that no allow rule can override.
 
 The legacy `bash.autoApproveLevel` ("safe"→"high") was replaced by this model; a stored `high` migrates to `auto`.
 
+### CODA asked if I want to set up permission rules — what is that?
+
+If you have **no `allow` rules** in either your project `.coda/config.json` or your global `~/.coda/config.json`, CODA offers to run the **`/init-rules`** skill with a Yes/No prompt. On a fresh install the default permission mode is `auto` — where only your explicit `ask`/`deny` rules and the catastrophic floor stop the agent — so `/init-rules` helps you set up sensible `allow`/`ask`/`deny` rules for how your project actually works.
+
+The prompt appears **after you send your first message** — that message goes through normally and lands you on the usual chat screen, then CODA asks. It never interrupts the home screen. It is offered at most once each time you start CODA (`/new` or `/clear` don't bring it back).
+
+- **Yes** runs the skill.
+- **No** (or Esc) dismisses it and it won't ask again.
+- To turn it off permanently, set `"onboarding": { "suggestInitRules": false }` in your config. You can always run `/init-rules` yourself later.
+
 ### How does CODA decide what's safe to run without asking?
 
 It **parses** each command into a syntax tree (not string-matching) and classifies it by capability — read, write, network, destructive, catastrophic — across bash, PowerShell, and cmd. The decision is **deny-first**: explicit deny rules win, then your permission mode fills the gaps, then the un-relaxable floor plus self-protection clamp the dangerous cases. So `cat file` reads freely, `git commit` asks in `default`, `rm -rf /` is refused in every mode, and piping a remote script into a shell (`curl … | sh`) is denied by default. (`rm` and PowerShell `Remove-Item` deny for out-of-tree, absolute, or non-literal targets; an in-tree delete like `rm ./tmp` is auto-allowed in `default`/`auto` as an easily-reverted change, while recursive/absolute forms stay un-relaxable.)
@@ -112,6 +130,10 @@ Open the `/mcp` manager inside CODA and add the server — paste its JSON or imp
 
 Create a `.md` file with YAML frontmatter (`name` and `description` are required) and place it in `<project>/.coda/skills/` or `~/.coda/skills/`. The slash command `/skill-name` invokes it. See [Extend CODA](#guide-extend) for a complete example.
 
+### Can I use skills from Claude, Codex, or OpenCode?
+
+Yes. CODA can scan those agents' skill folders (`.claude/skills`, `.codex/skills`, `.opencode/skills`) plus the cross-tool `.agents/skills` — without copying anything. Foreign sources are **off by default**; turn one on from `/settings → Skills` or with `coda skills enable <source> --global|--project`. Add extra folders with `coda skills add-path <dir>`. See [Extend CODA](#guide-extend) › § "Import skills from other coding agents".
+
 ### How do I create an extension?
 
 The easiest way is to ask CODA: run `/create-extension` and describe what you want in plain language — the built-in `create-extension` skill scaffolds the TypeScript file and places it in the right folder for you. If you'd rather hand-write or fine-tune one, see [Writing Extensions](#extensions) for the full API reference.
@@ -165,7 +187,7 @@ The TUI status bar shows the context fill percentage and running token/cost figu
 
 ### Where are my config, sessions, and logs stored?
 
-Everything lives under `~/.coda/` — `config.json`, `.secrets`, the session database `coda.db` (with per-session override files under `sessions/<id>/`), `logs/`, `checkpoints/`, and `exports/`. Point `CODA_HOME` at a different directory to relocate all of it — or pass `--coda-home <path>` on the command line (both have the same effect; the flag wins when the env var is not set). See [Configuration Reference](#config-reference).
+Most state lives under `~/.coda/` — `config.json`, `.secrets` (a marker file for generic `${VAR}` values; newly added API keys go through your system keychain instead, though a legacy key may remain here in plaintext on a host without an OS keyring), `.credentials.json` (the encrypted fallback store, only present where there is no OS keyring), the session database `coda.db` (with per-session override files under `sessions/<id>/`), `logs/`, `checkpoints/`, and `exports/`. Your OS keychain entry for provider API keys, when available, is external to this directory. Point `CODA_HOME` at a different directory to relocate all of it — or pass `--coda-home <path>` on the command line (both have the same effect; precedence is `--coda-home` > `CODA_HOME` > the default, so an explicit flag overwrites an inherited env var). See [Configuration Reference](#config-reference).
 
 ### How do I view or share logs safely?
 

package/assets/docs/glossary.md

@@ -12,13 +12,13 @@ Quick definitions for terms used throughout the docs.
 | **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** | 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, 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`. |
+| **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. |

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

@@ -14,7 +14,7 @@ For how checkpoints work in detail — the shadow repo, Git requirements, and ho
 
 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 |
 | --- | --- |

package/assets/docs/guide-collaborate.md

@@ -61,9 +61,9 @@ 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.
+- **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.
@@ -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

@@ -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.

package/assets/docs/hooks.md

@@ -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. |

package/assets/docs/index.md

@@ -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.
 

package/assets/docs/installation.md

@@ -4,7 +4,7 @@
 
 - **Git 2.5.0 or newer** — CODA uses Git under the hood for checkpoints. Run `git --version` to check.
 - **A supported terminal** — any modern terminal on macOS, Linux, or Windows works.
-- **Provider credentials** — OAuth access **(recommended)** or a Glob.AI OS API key. You'll set this up during first launch.
+- **Provider credentials** — OAuth access **(recommended)** or a Glob.AI API key. You'll set this up during first launch.
 - **Node.js (which includes npm)** — only if you install via npm (a current LTS release is recommended). The install script below needs neither.
 
 ## Install CODA
@@ -14,13 +14,13 @@ The recommended way to install CODA is the install script — it has **no depend
 **macOS & Linux**
 
 ```bash
-curl -fsSL https://docs.globant.ai/en/filedownload?4622,12 | bash
+curl -fsSL 'https://docs.globant.ai/en/filedownload?4622,13' | bash
 ```
 
 **Windows (PowerShell 7)**
 
 ```powershell
-irm 'https://docs.globant.ai/en/filedownload?5346,6' | iex
+irm 'https://docs.globant.ai/en/filedownload?5346,8' | iex
 ```
 
 Alternatively, install the `@globant/coda` launcher from the public npm registry. This requires Node.js; the install script above does not:
@@ -68,4 +68,4 @@ If a problem isn't covered here, check the [FAQ](#faq).
 
 ## What's next
 
-With CODA installed, the next step is to [Connect a Provider](#connect-provider) — pick your Glob.AI OS environment and sign in with OAuth or an API key. Then head to [Quick Start](#quickstart) to open CODA in a real project and run your first prompt.
+With CODA installed, the next step is to [Connect a Provider](#connect-provider) — the first run names the default Glob.AI instance and asks you to sign in with OAuth or an API key; you can choose another instance instead. Then head to [Quick Start](#quickstart) to open CODA in a real project and run your first prompt.

package/assets/docs/overview.md

@@ -44,7 +44,7 @@ Both share the same agent, the same configuration, and the same tools — the di
 
 - **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).
+- **Secrets** — API keys entered through `/providers` live in your system keychain (or an encrypted secrets file where there is no keychain); on a host without an OS keyring, a legacy key already on disk is left in place rather than migrated. Nothing is committed to Git, and log redaction scrubs secret-shaped values 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.
 
@@ -85,7 +85,7 @@ See [How CODA Works](#how-it-works) for the mechanics of tools, memory, and comp
 ## Start here
 
 1. [Installation](#installation) — get `coda` running on your machine.
-2. [Connect a Provider](#connect-provider) — pick your Glob.AI OS environment and sign in.
+2. [Connect a Provider](#connect-provider) — sign in to the default Glob.AI instance, or choose another.
 3. [Quick Start](#quickstart) — open CODA in a real project and run your first prompt.
 4. [Configuration](#configuration) — connect your provider and tune settings.
 

package/assets/docs/permissions.md

@@ -19,7 +19,9 @@ 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 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 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, on the welcome screen or at any point during the session; set the mode new sessions start in with `permissions.defaultMode` in `~/.coda/config.json`. When you haven't set one, a truly-fresh config (no `permissions` block at all) starts in **auto**; if a `permissions` block already exists but omits `defaultMode`, sessions start in **default** so an existing setup is never silently escalated (a managed policy can still force `default`). A project `.coda/config.json` can make that starting mode more restrictive, but it cannot silently raise autonomy above your user setting.
+
+Each session keeps its own mode. A new session starts in your configured mode, and any mode you pick with Ctrl+P is saved with the session, so resuming it (`coda --lastsession`, `coda --session-id <id>`, or `/sessions`) continues in the mode it last ran in, even if you change `permissions.defaultMode` later. Only a managed policy changes a resumed session's mode: if your organization has since disabled that mode, CODA switches the session to `default` and tells you why. The mode a headless run sets with `--auto-approve` applies to that run only and is not saved with the session.
 
 The three valid values are `"read-only"`, `"default"`, and `"auto"`.
 
@@ -30,8 +32,8 @@ The three valid values are `"read-only"`, `"default"`, and `"auto"`.
 | **auto** | Reads, edits, and risky commands — for unattended / CI runs | — | Only catastrophic actions (the un-relaxable floor, below) |
 
 - **read-only** allows a command *iff* it is positively classified read-safe (a curated read or inspector), on bash, PowerShell, **and** cmd alike. Interpreters, build/test verbs (`cargo build`, `tsc`, `go test`), and mutators are **not** read-safe — they are refused, even though a build isn't a "write."
-- **default** is the shipped mode. It auto-approves an in-project `Edit`/`Write` (as long as the file was read this session, or is brand new) but still asks for edits outside the cwd, risky bash, overwriting a file it hasn't read this session, and MCP calls with no explicit allow rule.
-- **auto** relaxes the `ask` tier to `allow` for hands-off runs — but the un-relaxable floor, managed policy, your own `deny`/`ask` rules, and sensitive-path protections still bite.
+- **default** auto-approves an in-project `Edit`/`Write` (as long as the file was read this session, or is brand new) but still asks for edits outside the cwd, risky bash, overwriting a file it hasn't read this session, and MCP calls with no explicit allow rule.
+- **auto** is the shipped default for a fresh install (no `permissions` block anywhere; a managed `disableAutoMode` policy still forces `default`). This automatic `auto` lasts for the current session only: once your config has a `permissions` block (for example after your first saved rule), new sessions start in `default`. To keep starting in auto, set `permissions.defaultMode: "auto"` yourself, or approve the mode change `/init-rules` offers. If a config file has a syntax error, CODA starts in `default` rather than `auto`. It relaxes the `ask` tier to `allow` for hands-off runs — but the un-relaxable floor, managed policy, your own `deny`/`ask` rules, and sensitive-path protections still bite. Because auto leans on your explicit `ask`/`deny` rules, if you have no rules configured CODA offers the **`/init-rules`** skill to set them up — with a Yes/No prompt shown after your first message (opt out with `onboarding.suggestInitRules: false`).
 
 > **Legacy mode aliases:** `"plan"` → `read-only`, `"acceptEdits"` → `default`, `"bypassPermissions"` or `"bypass"` → `auto`. These still work but the new names are preferred.
 
@@ -271,6 +273,19 @@ coda -p "Run the test suite and report failures" --auto-approve none
 
 When `--auto-approve` is omitted, headless defaults to `all` (→ `auto`). Even so, `--auto-approve all` does **not** run *everything*: the un-relaxable catastrophic floor, self-protection, sensitive-path protections, and managed `deny` rules still refuse `rm -rf /`, `sudo`, fork bombs, and the like. Pass `--auto-approve none` (→ `default`, fail-closed) when silent auto-approval is unacceptable.
 
+## LLM safety check (optional)
+
+With `permissions.llmSafetyCheck.enabled: true` and the `auto` mode, CODA asks a small classifier model about commands that `auto` would otherwise stop to ask you about. If the model approves, the command runs; if it rejects (or no model answers), you get the normal approval prompt. It never overrides a `deny` or the catastrophic floor.
+
+> **An `ask` rule is not a guaranteed human prompt while the safety check is on.** In `auto` mode the classifier may approve a command that matched an `ask` rule — including one from a managed (admin) policy — both interactively and in headless runs (`coda -p`, `--goal`, `--loop`). It never approves writes to CODA's own configuration (config, agents, extensions, …) or an `ask` requested by a `PreToolUse` hook. To make sure a human always decides, use a `deny` rule, set managed `disableAutoMode`, or leave `llmSafetyCheck` disabled.
+
+- **It keeps working for the whole session.** When your login token is refreshed, the classifier picks up the new token automatically and retries — you are not asked to do anything.
+- **It works in headless runs too** (`coda -p`, `--goal`, `--loop`). An approved command runs; anything else is still denied, as usual in headless mode.
+- **A refusal is never auto-approved.** If the classifier refuses a command a sub-agent wanted to run, `--auto-approve all` does not override it.
+- **Long `/loop` runs:** if the classifier does not approve a command in a later loop iteration, the loop pauses (resume with `/loop resume`, end it with `/loop stop`) instead of waiting on a prompt nobody may be there to answer. Any other approval still shows the normal prompt. If a **sub-agent** started by the loop wants a command the classifier refused, that command is denied for the sub-agent and the loop itself keeps running.
+- If no classifier model answers, the check can add up to about 15 seconds before the normal approval prompt appears.
+- Changes to `llmSafetyCheck` in `config.json` take effect after a restart.
+
 ## Every decision is logged
 
 Every authorization decision — allowed, prompted, or denied — is recorded in CODA's structured log as an `authorization.decision` entry, including the tool name, the decision, the matched rule (if any), the active mode, and the denial category. Proposed policy changes are logged separately, capturing whether they were approved, rejected, or declined. Review these to understand every permission decision made during a session (see [View & Share Logs](#logging)).
@@ -329,10 +344,10 @@ Two things to know when reading the output:
 ## Where to set it
 
 - **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.
+- **In the session:** press **Ctrl+P** to cycle the permission mode — on the welcome screen too, before your first message. The session keeps the mode when you resume it.
 - **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:** 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)).
+- **For a headless run:** the `--auto-approve none|all` flag, for that run only (see [Commands & Flags](#cli-reference)).
 
 ## See also
 

package/assets/docs/quickstart.md

@@ -11,7 +11,7 @@ cd /path/to/your/project
 coda
 ```
 
-The first time you run CODA, if you haven't set up a provider yet, a setup wizard appears automatically. Follow the prompts to pick your Glob.AI OS environment and sign in. For a step-by-step walkthrough of that flow, see [Connect a Provider](#connect-provider).
+The first time you run CODA, if you haven't set up a provider yet, it names the Glob.AI instance it will use and asks you to sign in — nothing else. For what happens, and how to choose another instance, see [Connect a Provider](#connect-provider).
 
 ## 2. Try these prompts
 

package/assets/docs/sessions.md

@@ -23,13 +23,15 @@ When you exit, CODA prints the exact command to resume — `coda --session-id <i
 
 From the `/sessions` manager you can **resume, rename, or delete** any saved session.
 
+A resumed session continues in the permission mode it last ran in — see [Permissions & Approvals](#permissions).
+
 > **Note:** `--lastsession` and `--session-id` / `-s` are mutually exclusive — using them together will produce an error. Sessions are scoped to the project directory you launched from, so `coda --lastsession` resumes the last session *for this project*, not globally.
 
 **Keyboard controls in the `/sessions` overlay:** `↑`/`↓` move, `←`/`→` page, **Enter** resume, **r** rename, **d** delete (asks to confirm), **q** or **Esc** to close.
 
 ### Where sessions are stored
 
-Sessions persist in a global SQLite database at `~/.coda/coda.db` (override the location with `CODA_HOME`). Each session has a stable id — the one printed on exit and shown in `/sessions` — and is scoped to the project directory you launched from. A few per-session override files (such as a session-level `mcp.json`) live under `~/.coda/sessions/<sessionId>/`, but the session record itself is in the database, not in your project's `.coda/` folder. Because it's persisted to disk, a session survives closing your terminal, rebooting, even upgrading CODA. The `/clear` command wipes a session's message history while keeping the session itself; `/sessions` → delete removes it entirely.
+Sessions persist in a global SQLite database at `~/.coda/coda.db` (override the location with `CODA_HOME`). Each session has a stable id — the one printed on exit and shown in `/sessions` — and is scoped to the project directory you launched from. A few per-session override files (such as a session-level `mcp.json`) live under `~/.coda/sessions/<sessionId>/`, but the session record itself is in the database, not in your project's `.coda/` folder. Because it's persisted to disk, a session survives closing your terminal, rebooting, even upgrading CODA: a new version updates the database the first time it starts, and if the database can't be used as-is it stops before changing anything (see the FAQ). The `/clear` command wipes a session's message history while keeping the session itself; `/sessions` → delete removes it entirely.
 
 ## Start fresh without losing the old session
 
@@ -86,6 +88,8 @@ To keep additional project-local paths out of snapshots, add a `.codaignore` fil
 
 Two things to know: `.codaignore` is read **once at session start**, so restart `coda` after editing it. And negations (`!path`) are honored last and apply across every layer — a negation can re-include a path that an earlier pattern *or* the always-on static exclusions (`.git`, `node_modules`, …) would have dropped. That's a deliberate, opt-in escape hatch: writing `!secrets/keep-me.txt` to snapshot an otherwise-excluded path is treated as a conscious choice. (Restoring never overwrites `.coda/MEMORY.md`, so your agent's memory survives a rollback regardless.)
 
+If a restore skips a path your current rules exclude today (for example you added it to `.codaignore` after the checkpoint was taken, or it's a dependency directory that's still live on disk), the picker and the chat-log confirmation both say so — "N file(s) not restored — ignored by your current rules" — instead of silently reporting "already at target". The file isn't lost: it just wasn't part of this restore.
+
 ### Drift detection
 
 If your worktree has uncaptured changes when you try to restore — your own edits, or agent output from the current turn that hasn't been snapshotted yet — CODA **stops the restore** so you don't silently lose work. The drift report groups the affected files into **Modified**, **Added (would be removed by restore)**, and **Deleted (would be restored)**, with a per-file line-count delta.

package/assets/docs/shortcuts.md

@@ -18,9 +18,49 @@ These shortcuts work inside the interactive TUI. Type `?` at any time to open th
 | `Ctrl+J` | Insert a newline without sending |
 | `↑` / `↓` | Navigate input history |
 | `/` | Open the slash command palette |
+| `@` | Attach a file — opens the file-path browser |
 | `?` | Open the keyboard-shortcuts overlay |
-
-> **Tip — attach screenshots.** Paste a path to an image file (or paste the image itself where your terminal supports it) and CODA picks it up as visual context — it shows a short `[Image N]` marker so you know it'll be sent. Useful for sharing a screenshot of an error or a UI mockup.
+| `Ctrl+V` (macOS / Linux) · `Alt+V` (Windows) | Paste an image from the clipboard (see **Pasting images** below) |
+
+> **Tip — attach screenshots.** Copy a screenshot and press `Ctrl+V` (`Alt+V` on Windows), or paste a path to an image file, and CODA picks it up as visual context — it shows a short `[Image N]` marker so you know it'll be sent. Useful for sharing a screenshot of an error or a UI mockup.
+
+### Pasting images
+
+A terminal can only pass text to the programs running in it, so when you
+paste an image CODA reads it straight from your clipboard. Use the key that
+reaches CODA in your terminal:
+
+- **`Ctrl+V`** pastes a clipboard image on macOS and Linux in every common
+  terminal: iTerm2, Terminal.app, Zed (0.219.4 or later), Ghostty, Kitty,
+  WezTerm, Alacritty, GNOME Terminal and VS Code / Cursor.
+- **`Alt+V`** pastes a clipboard image on Windows (Windows Terminal every
+  version, VS Code, WSL) and the classic console window — this is the key to
+  use on Windows. `Ctrl+V` also works where the terminal forwards the paste to
+  CODA (VS Code, the classic console), but Windows Terminal's default `Ctrl+V`
+  binding pastes clipboard *text* and will not attach an image — use `Alt+V`,
+  or unbind `Ctrl+V` in Windows Terminal settings if you prefer it. On Windows
+  and WSL the paste can take a second or two while PowerShell starts; press the
+  key once and wait for the `[Image N]` marker.
+- **`Cmd+V`** pastes images out of the box in **VS Code and Cursor**. Other
+  macOS terminals (iTerm2, Terminal.app, Zed, Ghostty, Kitty, WezTerm) ignore
+  `Cmd+V` when the clipboard holds only an image, so nothing reaches CODA.
+  Use `Ctrl+V` there. If your terminal is set up to pass `Cmd+V` through to
+  the program, CODA attaches the image, or pastes the text when the clipboard
+  holds text.
+- **Warp** does not pass image pastes to programs. Drag the image file into
+  the terminal, or paste its path.
+
+If the image-paste chord (`Alt+V` on Windows, `Ctrl+V` elsewhere) finds no
+image, CODA shows "No image in clipboard". (On Windows, pressing `Ctrl+V` with
+no image does nothing — the toast is tied to the `Alt+V` chord.) Copy a
+screenshot first: `Cmd+Ctrl+Shift+4` on macOS, `Win+Shift+S` on Windows.
+
+Holding the key down does not attach the image again, and the key does
+nothing while a dialog or picker is open.
+
+**Inside `tmux` or `screen`**, `Ctrl+V` may be taken by the multiplexer.
+Remap image paste to another chord with the `imagePaste` action in
+`~/.coda/keybindings.json` (see below), or paste the image's file path.
 
 ## During a turn
 
@@ -63,3 +103,13 @@ If you only remember two, make them these:
 
 - [Commands & Flags](#cli-reference) — the slash commands these shortcuts complement.
 - [Make Changes Safely](#guide-changes) — using **Esc**, the timeline, and message steering to stay in control.
+
+## Remapping shortcuts
+
+Create `~/.coda/keybindings.json` to remap any of the shortcuts above. Keys are the action names, values are chords:
+
+```json
+{ "toggleSidebar": "ctrl+e", "scrollUp": "alt+up", "clearQueue": "ctrl+k" }
+```
+
+Actions: `exit`, `clear`, `toggleCollapsible`, `scrollUp`, `scrollDown`, `scrollPageUp`, `scrollPageDown`, `scrollToTop`, `scrollToBottom`, `copyLastCodeBlock`, `toggleSidebar`, `cycleFavoriteModel`, `cyclePermissionMode`, `clearQueue`, `imagePaste`. Chords combine `ctrl`, `alt`, `shift`, `meta` with a letter or a named key (`up`, `down`, `left`, `right`, `pageup`, `pagedown`, `home`, `end`, `tab`, `escape`, `enter`). Malformed entries are reported at startup and ignored.

package/assets/docs/tools-reference.md

@@ -6,7 +6,7 @@
 
 CODA builds a **tool registry** for each session. Which tools are available depends on a few things:
 
-- **Provider** — some tools (like web search or vision) require a Glob.AI OS profile.
+- **Provider** — some tools (like web search or vision) require a Glob.AI profile.
 - **MCP configuration** — connected servers add their own tools.
 - **Agents** — delegation tools appear only when agents are enabled.
 - **Extensions and plugins** — these can register additional tools.
@@ -22,17 +22,21 @@ To limit which tools a single run may use, pass `coda --tools …` (see [Command
 | `read` | Read file contents, with pagination and encoding handling |
 | `write` | Create or overwrite files; asks before overwriting a file it never read this session |
 | `edit` | Apply structured search-and-replace edits to existing files |
-| `bash` | Run shell commands, classified by capability and gated by your permission mode |
+| `bash` | Run shell commands, classified by capability and gated by your permission mode. `background: true` starts a server/watcher/long build and returns a process id at once; the result of a command that edits files also carries the diff of what it changed |
+| `repo_map` | A compact map of the repository's top-level definitions (classes, functions, types, exports) grouped by file and ranked by how much the rest of the repo references them (import graph + whole-word symbol uses → PageRank; `← n` marks how often a definition is used elsewhere), built with the bundled ripgrep. It is not in the system prompt: CODA loads it on demand (it is listed under deferred tools), typically first thing in an unfamiliar codebase; `query` narrows it to a symbol or path, `path` maps one directory |
+| `mcp_resource` / `mcp_prompt` | Browse what an MCP server publishes beyond tools: list and read resources (documents, schemas, logs) and list or render prompt templates. Same per-session enable/disable as `mcp_execute` |
+| `background_output` | Read the new output of (or stop) a process started with `bash background: true`. List and stop them yourself with `/ps` and `/stop` |
 | `glob` | Find files by path pattern (fast file finder) |
 | `grep` | Search file contents (powered by ripgrep) |
 | `think` | A lightweight scratchpad step the model can use to reason |
 | `memory` | Read or update `MEMORY.md` notes; consolidating can ask for approval |
 | `ask_user` | Ask you a question in the UI (interactive sessions only) |
-| `web_search` | Search the web (Glob.AI OS profiles with search configured) |
+| `web_search` | Search the web (Glob.AI profiles with search configured) |
 | `webfetch` | Fetch a web page by URL and return it as markdown, plain text, or raw HTML |
-| `examine_images` | Analyze image files with a vision model (Glob.AI OS) |
-| `omni_parser` | Extract text and data from documents and media (Glob.AI OS) |
+| `examine_images` | Analyze image files with a vision model (Glob.AI) |
+| `omni_parser` | Extract text and data from documents and media (Glob.AI) |
 | `mcp_execute` | Call a tool on an MCP server you've connected |
+| `mcp_describe` | Get the full description and parameters of MCP tools before calling them with `mcp_execute`. Used when a large MCP catalog is listed compactly in the prompt (name and purpose only): the model calls `mcp_describe` to fetch a tool's schema on demand. Advertised alongside `mcp_execute` |
 | `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) |
@@ -66,8 +70,8 @@ Tool behavior is configured in a few different places — some from the `/settin
 | --- | --- | --- |
 | **Bash** | Permission mode (Ctrl+P / `permissions.defaultMode`) and shell mode — how often CODA asks before running commands, and which shell it uses. See [Permissions & Approvals](#permissions). | `Ctrl+P` / config (`permissions.defaultMode`) |
 | **Search** | Enable or disable `glob` and `grep`, the `grep` backend (ripgrep or fastgrep), and result limits. Ripgrep ships bundled — no separate install needed. | Config file (`tools.glob`, `tools.grep`) |
-| **Vision** | The model used by `examine_images`. | Config file (`vision.model`) |
-| **Web search** | The model used for web search (Glob.AI OS). | `CODA_WEBSEARCH_MODEL` env var (falls back to the built-in default) |
+| **Vision** | The model used by `examine_images`. | Built-in default; override with `vision.model` in the config file (optional) |
+| **Web search** | The model used for web search (Glob.AI). | `CODA_WEBSEARCH_MODEL` env var (falls back to the built-in default) |
 | **Web fetch** | Backend order, URL blocklist/allowlist, provenance, and the model-backend timeout for `webfetch`. Disable it entirely, or deny it via a permission rule. See [Web fetch](#web-fetch) below. | Config file (`webfetch.*`) / `permissions.deny: ["WebFetch"]` |
 | **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 |
@@ -79,9 +83,9 @@ Tool behavior is configured in a few different places — some from the `/settin
 The `webfetch` tool retrieves the contents of an `http(s)` URL and hands it back as **markdown** (default), **plain text**, or **raw HTML**. It's a single, visible, permission-gated tool — one tool call, one approval prompt — with **two selectable backends** chosen by a preference order (`webfetch.order`), with automatic **runtime fallback** (if the first backend fails, the next available one runs):
 
 - **`client`** — a fetch CODA controls end-to-end, with SSRF protection (it pins the connection to the validated IP so a hostname can't rebind to a private/metadata address), a URL blocklist/allowlist, main-content extraction that strips nav/sidebar/footer chrome (with a guard that keeps the **whole page** for link-rich homepages and index pages), and HTML→Markdown conversion. Always available; no model call. This is the **default primary** backend.
-- **`anthropic`** — makes a call to a fixed model that runs the provider's server-side web-fetch tool and returns the parsed page. It handles content the client backend can't parse (notably **PDFs**), and is available only when a Glob.AI OS (GEAI) profile is configured. Used as the fallback by default.
+- **`anthropic`** — makes a call to a fixed model that runs the provider's server-side web-fetch tool and returns the parsed page. It handles content the client backend can't parse (notably **PDFs**), and is available only when a Glob.AI (GEAI) profile is configured. Used as the fallback by default.
 
-The default order is **`["client", "anthropic"]`**: fetch locally first, fall back to the model backend (e.g. for a PDF) when it's available. Without a Glob.AI OS profile, the order simply falls through to `client`, and a PDF returns a short "can't fetch this here" message.
+The default order is **`["client", "anthropic"]`**: fetch locally first, fall back to the model backend (e.g. for a PDF) when it's available. Without a Glob.AI profile, the order simply falls through to `client`, and a PDF returns a short "can't fetch this here" message.
 
 There is **no headless-browser rendering** — CODA deliberately does not bundle or require a browser. A client-rendered single-page app that ships little server-side content gets an actionable notice (try the model backend or a direct content URL) rather than being rendered.