@globant/coda-linux-x64-baseline-musl 1.3.0 → 1.5.0

package/assets/agents/coda-help.md

@@ -31,12 +31,12 @@ Notation: every entry points to `file.md › § "Exact Heading"`. All files live
 | --- | --- |
 | How do I install / upgrade Coda? | `installation.md` › § "Install CODA", § "Keeping CODA up to date" |
 | What are the requirements? | `installation.md` › § "Requirements" |
-| How do I connect / set up a provider? | `connect-provider.md` › § "Step 1 — Choose how to connect" → § "Step 3 — Authenticate" |
+| How do I connect / set up a provider? | `connect-provider.md` › § "What the first run does", § "Choosing an instance yourself", § "Custom provider" |
 | Configure a provider non-interactively / from a script / in CI / headless setup (`coda configure`)? | `connect-provider.md` › § "Non-interactive setup (`coda configure`)"; command → `cli-reference.md` › § "Subcommands (run as `coda <command>`)" |
-| OAuth vs API key / switch between them? | `connect-provider.md` › § "Switch a Glob.AI OS provider between OAuth and API key" |
+| OAuth vs API key / switch between them? | `connect-provider.md` › § "Switch a Glob.AI profile between OAuth and API key" |
 | Switch the active provider / profile (`/switch-profile`, `/sp`)? | `connect-provider.md` › § "Switch between configured providers"; command → `cli-reference.md` › § "Configuration" |
-| Add / edit / remove a provider (`/providers`)? | `connect-provider.md` › § "Reconfigure"; wizard steps → § "Step 1 — Choose how to connect" |
-| Switch the active Glob.AI OS project (`/project`)? | `connect-provider.md` › § "Switching the active Glob.AI OS project" |
+| Add / edit / remove a provider (`/providers`)? | `connect-provider.md` › § "Reconfigure"; wizard steps → § "Choosing an instance yourself" |
+| Switch the active Glob.AI project (`/project`)? | `connect-provider.md` › § "Switching the active Glob.AI project" |
 | Set up two projects / accounts and switch between them? | `faq.md` › § "How do I set up two projects (e.g. two Clients projects) and switch between them?" |
 | Change project while logged in with OAuth? | `faq.md` › § "I'm logged in with OAuth. How do I switch to a different project?" |
 | How do I run batch mode / authenticate headlessly / in CI? | `faq.md` › § "How do I run CODA in batch mode, and how does it authenticate?"; details → `guide-automate.md` › § "Authenticating in batch mode", § "Important flags for automation" |
@@ -51,19 +51,30 @@ Notation: every entry points to `file.md › § "Exact Heading"`. All files live
 | Where are config / secrets / sessions / logs stored? | `config-reference.md` › § "Config file locations"; `faq.md` › § "Where are my config, sessions, and logs stored?" |
 | Store API keys safely / `${VAR}` / `secretRef` secrets? | `config-json.md` › § "Secrets: keep keys out of the file"; `config-reference.md` › § "Referencing secrets with `${VAR}`" |
 | How do I switch models? | `cli-reference.md` › § "Configuration" (`/switch-model`); `shortcuts.md` › § "Model switching" |
+| How do I copy CODA's response / a past response / test the `/copy` command? | `cli-reference.md` › § "Session management" (`/copy`); shortcut → `shortcuts.md` › § "Transcript navigation" (`Ctrl+Shift+C`) |
 | How do I let bash run everything / change approval level / permission mode (`read-only`/`default`/`auto`, Ctrl+P)? | `permissions.md` › § "Permission modes", § "Where to set it"; headless: § "Approvals in headless (batch) mode" |
 | How do I allow / always-allow / never-allow a command (`propose_policy`, "allow pnpm build")? | `permissions.md` › § "The easy way to change permissions: just ask the agent", § "How `propose_policy` works", § "What you actually approve" |
 | Stop CODA suggesting rule changes / disable `propose_policy` (`permissions.proposePolicy`, `CODA_PROPOSE_POLICY`, `disableProposePolicy`)? | `permissions.md` › § "Turning `propose_policy` off"; `config-reference.md` › § "permissions" |
+| CODA asked to set up rules / run `/init-rules` after my first message / stop that prompt (`onboarding.suggestInitRules`)? | `faq.md` › § "CODA asked if I want to set up permission rules — what is that?"; key → `config-reference.md` › § "Other common settings" (`onboarding.suggestInitRules`) |
+| What is the default permission mode / does CODA start in `auto`? | `permissions.md` › § "Permission modes"; default value → `config-reference.md` › § "permissions" (`defaultMode`) |
 | Rule syntax / write allow-ask-deny rules by hand / path or command not matching? | `permissions.md` › § "Rule syntax", § "Rules — always-allow / always-ask / always-deny", § "Project-scoped vs. global-scoped rules" |
 | Why was an action denied / precedence / deny-first / order of rules vs mode? | `permissions.md` › § "How decisions are made (precedence)", § "What denial messages look like" |
 | What is the catastrophic floor / what can never be allowed (`rm -rf /`, reading SSH keys, git hooks, `--privileged`)? Answer from the floor sections ONLY — do not describe the retired `bash.autoApproveLevel` as a current control. | `permissions.md` › § "The catastrophic floor — protections that can never be turned off", § "What is never auto-approved" |
 | What permissions do I have right now / what rules apply / where did a rule come from (`/permissions`, `coda permissions`)? | `permissions.md` › § "Seeing what applies right now" |
 | Organization / managed policy / admin lockdown of permissions? | `permissions.md` › § "Managed (organization) policy"; to see what it actually permits on this machine: § "Seeing what applies right now" |
+| LLM safety check (`permissions.llmSafetyCheck`) — what it does, does it work in headless / `/goal` / `/loop`, why did it stop working? | `permissions.md` › § "LLM safety check (optional)" |
 | Where are permission decisions logged (`authorization.decision`)? | `permissions.md` › § "Every decision is logged" |
 | Is it safe to install skills/plugins/MCP? | `permissions.md` › § "Trust and external code" |
-| How do I connect an MCP server? | `guide-extend.md` › § "Connect external services with MCP" |
+| How do I connect an MCP server? | `guide-extend.md` › § "Connect external services with MCP"; step by step with the bundled `configure-mcp` skill → `add-mcp-server-skill.md` › § "Ask in plain language", § "Choose the scope" |
 | Where do MCP servers live / session override / disable one? | `guide-extend.md` › § "Connect external services with MCP" ("Where MCP servers are defined") |
+| Add an MCP server from a package / command / Git repo / local binary / URL? | `add-mcp-server-skill.md` › § "Supported inputs", § "Entry rules"; check it loaded → § "Activate and verify"; problems → § "Troubleshooting" |
+| MCP server needs a token / how do I keep it out of `mcp.json`? | `add-mcp-server-skill.md` › § "Keep secrets out of the file" |
+| What are lifecycle hooks / how do I add one / which events exist? | `hooks.md` › § "Quick start", § "Where hooks are configured", § "Hook events" |
+| Hook config schema / `if` conditions / async hooks / turn all hooks off? | `hooks.md` › § "Configuration schema", § "Conditional execution (`if` field)", § "Async hooks", § "Disabling all hooks" |
+| What does a hook receive and return / how do I block an action from a hook? | `hooks.md` › § "JSON input (what your hook receives)", § "JSON output (what your hook can return)", § "Blocking operations" |
+| Hook env vars / `CODA_ENV_FILE` / hook examples / my hook does not fire? | `hooks.md` › § "Environment variables available to hooks", § "Session environment files (`CODA_ENV_FILE`)", § "Common recipes", § "Troubleshooting" |
 | How do I create / install a skill? | `guide-extend.md` › § "Teach CODA repeatable workflows with skills"; `faq.md` › § "How do I create a skill?" |
+| Import skills from Claude/Codex/OpenCode / cross-tool `.agents` / scan extra skill folders (`skills.sources`, `skills.paths`, `/settings → Skills`, `coda skills`)? | `guide-extend.md` › § "Import skills from other coding agents"; `faq.md` › § "Can I use skills from Claude, Codex, or OpenCode?"; keys → `config-reference.md` › § "skills" |
 | How do I create an extension? | `extensions.md` › § "The easy way: let CODA write it"; API → § "Registering a tool" onward |
 | Extension hooks / registerTool / registerShortcut / context fields? | `extensions.md` › § "Subscribing to lifecycle hooks", § "Registering shortcuts, providers, and flags" |
 | How do I install a plugin / use a marketplace? | `guide-extend.md` › § "Share packaged integrations with plugins", § "Adding a marketplace"; CLI → `cli-reference.md` › § "Subcommands (run as `coda <command>`)" |
@@ -84,7 +95,7 @@ Notation: every entry points to `file.md › § "Exact Heading"`. All files live
 | How do I view / share logs? | `logging.md` › § "Viewing logs", § "Sharing logs with support" |
 | Where do I see token usage / cost? | `faq.md` › § "Where do I see token usage and cost?" |
 | What does <term> mean (HITL, drift, shadow repo, fastModel…)? | `glossary.md` (single table — grep the term) |
-| What changed in this release / my version? | `release-history.md` › § "Checking your version" |
+| Which version am I running / how do I update? | `faq.md` › § "How do I check which version I'm running?"; `installation.md` › § "Keeping CODA up to date" |
 | Team setup / AGENTS.md / what to commit / monorepo? | `guide-collaborate.md` › § "Start with AGENTS.md", § "What to commit (and what not to)", § "Working in a monorepo" |
 
 ## Topic index (file › sections)
@@ -100,7 +111,7 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 **Install, providers, first run**
 
 - Requirements, install (script vs npm), where it installs, upgrading, install troubleshooting → `installation.md` › § "Requirements", § "Install CODA", § "Where CODA installs", § "Keeping CODA up to date", § "Troubleshooting the install"
-- Setup wizard, Glob.AI OS environment, OAuth vs API key, custom/Ollama provider, switch active profile (`/switch-profile`/`/sp`), switch Glob.AI OS project (`/project`), who am I signed in as, reconfigure (`/providers`), OAuth↔API-key switch, OAuth troubleshooting → `connect-provider.md` › § "Step 1 — Choose how to connect", § "Step 2 — Pick a Glob.AI OS environment", § "Step 3 — Authenticate", § "Custom provider", § "Switch between configured providers", § "Switching the active Glob.AI OS project", § "Check who you're signed in as", § "Reconfigure", § "Switch a Glob.AI OS provider between OAuth and API key", § "Troubleshooting"
+- First run, choosing a Glob.AI instance, setup wizard, OAuth vs API key, custom/Ollama provider, switch active profile (`/switch-profile`/`/sp`), switch Glob.AI project (`/project`), who am I signed in as, reconfigure (`/providers`), OAuth↔API-key switch, OAuth troubleshooting → `connect-provider.md` › § "What the first run does", § "Choosing an instance yourself", § "Custom provider", § "Switch between configured providers", § "Switching the active Glob.AI project", § "Check who you're signed in as", § "Non-interactive setup (`coda configure`)", § "Reconfigure", § "Switch a Glob.AI profile between OAuth and API key", § "Troubleshooting"
 - Non-interactive / headless / CI provider setup (`coda configure`), flags, exit codes, key storage → `connect-provider.md` › § "Non-interactive setup (`coda configure`)"; subcommand entry → `cli-reference.md` › § "Subcommands (run as `coda <command>`)"
 - First session in 5 min, starter prompts, `/init`, reviewing/undoing, keeping a session healthy → `quickstart.md` › § "2. Try these prompts", § "3. Review what CODA does", § "4. Undo anything", § "5. Keep the session healthy"
 
@@ -114,13 +125,13 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 
 **Commands, flags, shortcuts**
 
-- Slash commands grouped by purpose, shell flags, `coda` subcommands (`upgrade`, `logs`, `plugin install`, `marketplace install`, demos), worked examples → `cli-reference.md` › § "Session management", § "Files and changes", § "Configuration", § "Tools and extensions", § "Context", § "Shell flags (run before opening CODA)", § "Subcommands (run as `coda <command>`)", § "Notes and examples"
+- Slash commands grouped by purpose, shell flags, `coda` subcommands (`upgrade`, `logs`, `skills`, `plugin install`, `marketplace install`, demos), worked examples → `cli-reference.md` › § "Session management", § "Files and changes", § "Configuration", § "Tools and extensions", § "Context", § "Shell flags (run before opening CODA)", § "Subcommands (run as `coda <command>`)", § "Notes and examples"
 - Keyboard shortcuts by context, `Esc`/`Esc Esc` → `shortcuts.md` › § "Global", § "In the chat input", § "During a turn", § "Transcript navigation", § "Model switching", § "Two shortcuts worth memorizing"
 
 **Tools and safety**
 
 - Built-in tool list, how tools show up, how CODA chooses a tool, what you can configure (incl. env vars), trimmed tools in agent runs → `tools-reference.md` › § "How tools show up", § "Built-in tools", § "How CODA chooses a tool", § "What you can configure", § "Tools inside agent runs"
-- Authorization engine (HITL): approvals, permission modes (`read-only`/`default`/`auto`, Ctrl+P, legacy aliases, sub-agent inheritance), plain-English rule changes via `propose_policy` (add/remove rule, change mode, scopes, turning it off), HITL choices, denial messages, rule syntax + gotchas, project vs global scope, precedence (deny-first), catastrophic floor (self-protection, sensitive-path writes, un-relaxable secret reads, git RCE, container escape, redirects), shell mode, other actions that ask, managed policy, headless approvals, decision logging, `bash.autoApproveLevel` migration, trust of external code, where to set it → `permissions.md` › § "How approvals work", § "Permission modes", § "The easy way to change permissions: just ask the agent", § "How `propose_policy` works", § "What you actually approve", § "Turning `propose_policy` off", § "Rules — always-allow / always-ask / always-deny", § "Rule syntax", § "Project-scoped vs. global-scoped rules", § "How decisions are made (precedence)", § "The catastrophic floor — protections that can never be turned off", § "Choosing the shell", § "Other actions that ask first", § "Managed (organization) policy", § "Approvals in headless (batch) mode", § "Every decision is logged", § "Migrating from `bash.autoApproveLevel`", § "Trust and external code", § "Seeing what applies right now" (the read-only `/permissions` and `coda permissions` views: which rules apply, which scope each came from, session grants), § "Where to set it"
+- Authorization engine (HITL): approvals, permission modes (`read-only`/`default`/`auto`, Ctrl+P, legacy aliases, sub-agent inheritance; the unset default is `auto`, coerced to `default` under managed `disableAutoMode`; with no rules configured, CODA offers `/init-rules` via a Yes/No prompt after your first message, opt out via `onboarding.suggestInitRules`), plain-English rule changes via `propose_policy` (add/remove rule, change mode, scopes, turning it off), HITL choices, denial messages, rule syntax + gotchas, project vs global scope, precedence (deny-first), catastrophic floor (self-protection, sensitive-path writes, un-relaxable secret reads, git RCE, container escape, redirects), shell mode, other actions that ask, managed policy, headless approvals, decision logging, `bash.autoApproveLevel` migration, trust of external code, where to set it → `permissions.md` › § "How approvals work", § "Permission modes", § "The easy way to change permissions: just ask the agent", § "How `propose_policy` works", § "What you actually approve", § "Turning `propose_policy` off", § "Rules — always-allow / always-ask / always-deny", § "Rule syntax", § "Project-scoped vs. global-scoped rules", § "How decisions are made (precedence)", § "The catastrophic floor — protections that can never be turned off", § "Choosing the shell", § "Other actions that ask first", § "Managed (organization) policy", § "Approvals in headless (batch) mode", § "Every decision is logged", § "Migrating from `bash.autoApproveLevel`", § "Trust and external code", § "Seeing what applies right now" (the read-only `/permissions` and `coda permissions` views: which rules apply, which scope each came from, session grants), § "Where to set it"
 
 **Sessions and checkpoints**
 
@@ -129,7 +140,7 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 **Task guides**
 
 - Explore a codebase: orientation, planning before edits, diagrams, delegating to `explore` → `guide-understand.md` › § "Get oriented quickly", § "Plan before editing", § "Ask for a diagram or a written map"
-- Change code safely: checkpoints, approving commands, interrupting, steer vs queue, the safe workflow, undo scenarios, self-verification → `guide-changes.md` › § "Approve commands as they run", § "Interrupt early if something looks wrong", § "Send a message while CODA is working", § "A safe workflow for bigger changes", § "Common undo scenarios", § "Let CODA verify its own work"
+- Change code safely: checkpoints, approving commands, interrupting, steer vs queue, the safe workflow, undo scenarios, self-verification → `guide-changes.md` › § "Checkpoints: your undo button", § "Approve actions when CODA asks", § "Interrupt early if something looks wrong", § "Send a message while CODA is working", § "A safe workflow for bigger changes", § "Common undo scenarios", § "Let CODA verify its own work"
 - Team collaboration: `AGENTS.md`, shared skills/agents/workflows, what to commit, monorepo, `.gitignore` posture → `guide-collaborate.md` › § "Start with AGENTS.md", § "Share skills across the team", § "What to commit (and what not to)", § "Working in a monorepo", § "A suggested `.gitignore` posture"
 - Batch/CI automation: usage, examples, flags, authenticating headlessly (`--profile`/`--provider`/`--instance`/`--api-key`, OAuth reuse), reading `--output json`, scoping with `--tools`/`--timeout`, limits → `guide-automate.md` › § "Basic usage", § "Practical examples", § "Important flags for automation", § "Authenticating in batch mode", § "Reading the output", § "Scope it down for safety"
 - Which mechanism (MCP vs skills vs extensions vs plugins vs workflows) → `guide-extend.md` › § "Which extension mechanism do I want?"
@@ -139,11 +150,13 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 - Agents: just-ask usage, bundled agents (`coda-help`/`explore`), defining one, discovery order, `/agents` manager, foreground vs background, config (`agents.enabled`/`maxConcurrent`/`fastModel`/`defaultModel`), limits → `agents.md` › § "The easiest way to use an agent: just ask", § "Agents that ship with CODA", § "Defining an agent", § "Where CODA looks for definitions", § "Managing runs with `/agents`", § "Foreground vs background", § "Configuration", § "Good to know"
 - Workflows: running by plain language, `/workflows` dashboard + stop, creating via `create-workflow`, where they live, what a run produces, when worth it → `workflows.md` › § "Run a workflow", § "Watch and stop runs with `/workflows`", § "Create a workflow", § "Where workflows live", § "What a run produces", § "When a workflow is worth it"
 - Extensions: scaffold via `create-extension`, anatomy/`activate`, load order, `registerTool`, `registerCommand` + reserved names, lifecycle hooks (+ `input` return values), intercepting tool calls, `registerShortcut`/`registerProvider`/`registerFlag` + reserved shortcuts, loading/reloading → `extensions.md` › § "The easy way: let CODA write it", § "Anatomy of an extension", § "Where extensions load from", § "Registering a tool", § "Registering a slash command", § "Subscribing to lifecycle hooks", § "Intercepting tool calls", § "Registering shortcuts, providers, and flags", § "Loading, testing, and reloading"
+- Lifecycle hooks (shell/HTTP hooks fired at session, tool and prompt events): quick start, where they are configured, the event list, config schema, the JSON input/output contracts, blocking an operation, injecting context into a tool result, rewriting prompts, `if` conditions, plugin hooks, `CODA_ENV_FILE`, async hooks, disabling all hooks, slash commands, env vars, execution model, security, recipes → `hooks.md` › § "Quick start", § "Where hooks are configured", § "Hook events", § "Configuration schema", § "JSON input (what your hook receives)", § "JSON output (what your hook can return)", § "Blocking operations", § "Injecting context into tool results", § "Rewriting prompts", § "Conditional execution (`if` field)", § "Plugin hooks", § "Session environment files (`CODA_ENV_FILE`)", § "Async hooks", § "Disabling all hooks", § "Slash commands", § "Environment variables available to hooks", § "Execution model", § "Security considerations", § "Common recipes", § "Troubleshooting"
+- Configuring an MCP server through the bundled `configure-mcp` skill: asking in plain language, project vs global scope, the accepted input kinds (package, command, Git repository, local binary, remote URL), entry rules, keeping tokens out of `mcp.json`, verifying the server loaded → `add-mcp-server-skill.md` › § "Ask in plain language", § "Choose the scope", § "Supported inputs", § "Entry rules", § "Keep secrets out of the file", § "Activate and verify", § "Troubleshooting"
 
 **Configuration**
 
 - From the UI: `/providers`, `/settings`, where files live, common settings, cascade, what's safe to commit, minimal example → `configuration.md` › § "Where settings live", § "Common settings to change", § "How settings cascade", § "What's safe to commit", § "A minimal `config.json`"
-- Reference (key-by-key, defaults): locations, `activeProfile`/`profiles` (selection layer), legacy `providers` map, top-level `model`, `auth`, inline `mcp`, `bash`, `compaction`, `reasoning`, `tools`, `vision`, `checkpoints`, `skills`, `logging`, advanced, `${VAR}`, env vars → `config-reference.md` › § "Config file locations", § "activeProfile and profiles", § "providers (runtime client map — legacy)", § "model (top-level)", § "auth (Glob.AI OS login preferences)", § "mcp (inline servers)", § "bash", § "compaction", § "reasoning", § "modelResilience", § "Other common settings", § "tools", § "vision", § "checkpoints", § "skills", § "logging", § "Advanced blocks", § "Referencing secrets with `${VAR}`", § "Environment variables"
+- Reference (key-by-key, defaults): locations, `activeProfile`/`profiles` (selection layer), legacy `providers` map, top-level `model`, `auth`, `mcp.json` files, `bash`, `compaction`, `reasoning`, `tools`, `vision`, `checkpoints`, `skills`, `logging`, advanced, `${VAR}`, env vars → `config-reference.md` › § "Config file locations", § "activeProfile and profiles", § "providers (runtime client map — legacy)", § "model (top-level)", § "auth (Glob.AI login preferences)", § "mcp.json files", § "bash", § "compaction", § "reasoning", § "modelResilience", § "Other common settings" (incl. `onboarding.suggestInitRules` / `initRulesPromptDismissed`), § "tools", § "vision", § "checkpoints", § "skills", § "logging", § "Advanced blocks", § "Referencing secrets with `${VAR}`", § "Environment variables"
 - Complete annotated `config.json` (profiles-first) + secrets + legacy providers map + per-goal edits + env vars → `config-json.md` › § "The complete example", § "Secrets: keep keys out of the file", § "Common edits, by goal", § "The legacy `providers` map", § "Environment variables"
 
 **Logging**
@@ -153,7 +166,7 @@ Use this when the Fast-answers table doesn't match. Each line names the **file**
 **FAQ and history**
 
 - Short answers grouped by goal (getting started, sessions, making changes, extensions/tools, models & cost, operations) → `faq.md` (grep the exact `### <question>` heading)
-- Notable features by release, checking/updating your version → `release-history.md` › § "Checking your version"
+- Checking/updating your version → `faq.md` › § "How do I check which version I'm running?"; `installation.md` › § "Keeping CODA up to date"
 
 ## Topics You Cover
 

package/assets/agents/council.md

@@ -0,0 +1,11 @@
+---
+name: council
+description: one council member — a full agent (every tool) answering the same question as the other models, read-only
+permissionMode: read-only
+background: true
+---
+
+You are one member of a council: several models answer the same question independently and the answers are compared side by side.
+
+- Use your tools when they make the answer better — web search for anything current or outside the repository, glob/grep/view for anything about this codebase, read-only commands to check facts. Never modify files or system state.
+- Your final message IS the answer the human will read next to the others: direct, complete, in the language of the question, without mentioning other models. Keep it under ~400 words unless the question needs code.

package/assets/agents/reviewer.md

@@ -0,0 +1,14 @@
+---
+name: reviewer
+description: read-only code reviewer for a side session — reads the diff and the surrounding code, runs tests/lint, never edits
+tools: glob, grep, view, bash, think, examine_images
+background: true
+---
+
+You are a senior engineer reviewing a code change in a side session. The conversation that asked for this review continues without you; your only output is the review.
+
+Rules:
+
+- Read only. Never create, modify or delete files; never commit, stash, checkout or push. `bash` is for reading (`git diff`, `git log`, `git show`), running tests, linters and type checks.
+- Follow the review brief you were given exactly (method, what to look for, what not to report, how to write each finding).
+- Answer for a human: a summary with a `Verdict:` line, then each finding as a short section with file:line, severity, what is wrong, the concrete failure scenario and the fix. When the change is clean, say so.

package/assets/agents/side.md

@@ -0,0 +1,15 @@
+---
+name: side
+description: answer a quick side question with tools (web search, files, read-only commands) without touching the main conversation
+tools: web_search, glob, grep, view, bash, think, examine_images, mcp_execute
+background: true
+---
+
+You answer ONE side question for the user of a coding agent. The main conversation continues separately; nothing you do is part of it.
+
+How to work:
+
+- If the question is about the world outside this repository (news, results, prices, documentation, versions, anything time-sensitive), use `web_search` first — do not answer from memory, and do not say you have no access to real-time information when the tool is available.
+- If the question is about this codebase, use `glob`, `grep` and `view` to look before answering; use `bash` only for read-only inspection (never modify files or system state).
+- Answer directly and concisely in the language of the question: a few sentences, or a short list when the answer is a list. Name the source (URL or file path) when you looked something up.
+- If a tool is not available or the search returns nothing useful, say what you tried and give your best answer with that caveat.

package/assets/docs/add-mcp-server-skill.md

@@ -0,0 +1,137 @@
+# Configure an MCP Server with CODA
+
+When you ask CODA to add, register, install, or configure an MCP server, it can load the bundled **`configure-mcp`** skill. The skill turns a package name, command, Git repository, local binary, or remote HTTP endpoint into a valid MCP configuration without overwriting your other servers.
+
+## Ask in plain language
+
+Examples:
+
+```text
+Add the Playwright MCP server to this project.
+```
+
+```text
+Configure https://api.example.com/mcp globally. Read its token from API_TOKEN.
+```
+
+```text
+Install the MCP server from this repository and show me the available setup choices: <repository-url>
+```
+
+CODA inspects the input, asks which scope or installation method you want when that is unclear, and writes only after it can derive a valid server transport.
+
+## Choose the scope
+
+| Scope | Configuration file | Use it when |
+| --- | --- | --- |
+| **Project** | `<project>/.coda/mcp.json` | The server belongs to this project and the config should be shared with teammates. |
+| **Global** | `~/.coda/mcp.json` | The server is personal and should be available in every project on this machine. |
+
+If you do not specify a scope, CODA asks. When both scopes contain the same server name, the project definition wins.
+
+## Supported inputs
+
+The bundled skill accepts package names, executable commands, local binaries, Git repositories, and remote HTTP endpoints. A `.zip` archive is not a direct skill input; unpack it first, then point CODA at the extracted command or repository instructions.
+
+### Remote HTTP endpoint
+
+An HTTP MCP server uses `url` and may include headers, a bearer-token reference, a timeout, and environment variables:
+
+```jsonc
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "https://api.example.com/mcp",
+      "authorizationToken": "Bearer ${API_TOKEN}",
+      "headers": { "X-Project": "${PROJECT_ID}" },
+      "timeout": 120
+    }
+  }
+}
+```
+
+### Package, command, or local binary
+
+A local stdio server uses `command` with optional arguments, environment variables, and a working directory:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+Common launchers include `npx`, `uvx`, `node`, and a direct executable path.
+
+### Git repository
+
+A repository can document several installation methods. CODA reads its setup instructions, presents the viable choices, and lets you pick—for example a package launcher, a hosted HTTP endpoint, or a local build. A temporary clone is removed when the selected runtime does not need it.
+
+If no command or URL can be derived, CODA writes nothing and asks you for a package name, executable command, repository, or HTTP endpoint.
+
+## Entry rules
+
+Each server entry must have exactly one transport:
+
+- `command` for a local stdio subprocess; or
+- `url` for Streamable HTTP.
+
+Do not set both. Useful optional fields are:
+
+| Field | Applies to | Purpose |
+| --- | --- | --- |
+| `args` | stdio | Command arguments. |
+| `cwd` | stdio | Working directory for the subprocess. |
+| `env` | both | Environment variables passed to the server. |
+| `headers` | HTTP | Extra request headers. |
+| `oauth` | HTTP | `true` for an OAuth 2.1 server; the user signs in with `coda mcp login <name>`. |
+| `oauthClientId` | HTTP | Pre-registered OAuth client id, for servers without dynamic client registration (Glob.AI: `mcp`). Requires `oauth: true`. |
+| `authorizationToken` | HTTP | Shorthand for the Authorization header. |
+| `timeout` | both | Timeout in seconds for each request to the server. Unset: 60 s for MCP requests, 30 s for OAuth sign-in requests. |
+
+Session-level overrides can also use `{ "disabled": true }` to switch off a server inherited from a higher scope. For ordinary project/global entries, enable or disable the server from the `/mcp` manager.
+
+## Keep secrets out of the file
+
+Never put a real token or API key directly in `mcp.json`. Use `${VAR}` or `${VAR:-default}` and define the value in your environment, in `~/.coda/.secrets` or a project environment file (`.coda/.env` or `.env`) that is excluded from version control. A default is literal text up to the first `}`; it cannot contain another `${…}` reference or a line break. Provider API keys are different: add them through `/providers` (or `coda configure --api-key-stdin`) and they live in your system keychain (or an encrypted secrets file where there is no keychain) — never in `mcp.json` or any dotenv file. On a host with no OS keyring, a legacy key entered before the credential store existed may still remain in `~/.coda/.secrets` in plaintext, since migration into the encrypted store is intentionally skipped there — see [Configuration](#configuration).
+
+For example:
+
+```json
+{
+  "authorizationToken": "Bearer ${GITHUB_TOKEN}"
+}
+```
+
+CODA preserves existing server entries. If the chosen name already exists, it shows the current entry and asks before replacing only that key.
+
+## Activate and verify
+
+After the file is written:
+
+1. Open `/mcp`.
+2. Choose **Reload MCP servers**.
+3. Check the server status and view its discovered tools.
+
+Restarting CODA also loads the change. `/skills refresh` reloads skill definitions; it does not reload MCP connections.
+
+Once the server is connected, describe the task normally. CODA can select its MCP tools when they are relevant, subject to the same authorization rules as other tools.
+
+## Troubleshooting
+
+- **Invalid JSON** — fix the existing file first; CODA does not overwrite malformed configuration.
+- **Duplicate server name** — choose a different name or approve replacement of that one entry.
+- **No transport found** — provide the exact executable command, package name, or HTTP endpoint.
+- **Git setup is ambiguous** — choose one of the installation methods found in the repository documentation.
+- **A credential is required** — provide the environment-variable name, never the secret value in the config.
+- **The server does not appear** — reload it from `/mcp`, then inspect its status and error details.
+
+## See also
+
+- [Extend CODA](#guide-extend) — MCP, skills, extensions, plugins, and workflows.
+- [Configuration](#configuration) — where configuration and secrets live.
+- [Permissions & Approvals](#permissions) — authorization for MCP tool calls.

package/assets/docs/agents.md

@@ -128,7 +128,7 @@ Agent behavior is controlled by the `agents` block in your config (global and/or
 | --- | --- |
 | `agents.enabled` | When `false`, agent tools and the run manager aren't wired up. Default **true** |
 | `agents.maxConcurrent` | Cap on parallel runs (valid range **1–10**). Default **6** |
-| `agents.defaultModel` | Override the inherited model for all delegated runs (optional) |
+| `agents.defaultModel` | Legacy configuration field retained for compatibility; delegated runs now inherit the main session model unless a definition or tool call chooses another model |
 | `agents.fastModel` | Model ID used when a run requests the `"fast"` tier at the agents level (overrides provider value) |
 | `agents.smartModel` | Model ID used when a run requests the `"smart"` tier |
 | `agents.deepModel` | Model ID used when a run requests the `"deep"` tier |

package/assets/docs/cli-reference.md

@@ -10,6 +10,7 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `/new` | Start a fresh session (old one is saved) |
 | `/exit` (alias `/quit`) | Exit CODA; prints `coda --session-id <id>` so you can resume later |
 | `/clear` | Permanently wipe the current session's message history (the session itself stays) |
+| `/copy` (or `/copy N`) | Copy CODA's last response to the clipboard; `/copy N` copies the Nth-most-recent response (assistant messages only). Complements the [`Ctrl+Shift+C`](#shortcuts) shortcut, which copies only the last fenced code block |
 
 ## Files and changes
 
@@ -17,7 +18,7 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | --- | --- |
 | `/timeline` (alias `/rewind`) | Open the timeline picker to view and restore checkpoints from this session |
 | `/init` | Analyze the project and generate an `AGENTS.md` file |
-| `/project` | Switch the active Glob.AI OS project (Glob.AI OS OAuth only) |
+| `/project` | Switch the active Glob.AI project (Glob.AI OAuth only) |
 
 ## Configuration
 
@@ -26,9 +27,9 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `/providers` | Connect, add, update, or remove providers (the setup wizard; same as `--reconfigure`; restart required) |
 | `/switch-profile` (alias `/sp`) | Switch the active provider profile among the ones you've already configured. With no argument it opens the profile picker; `/switch-profile <profile-id>` selects one directly. The change is saved as `activeProfile` and applies on the next launch |
 | `/switch-model` (alias `/sm`) | Open the model picker. `/switch-model <provider/model>` applies for this session; `/switch-model save <provider/model>` also saves it as the default for new sessions |
-| `/login` | Authenticate with Glob.AI OS via browser (OAuth PKCE) when `auth` is configured |
+| `/login` | Authenticate with Glob.AI via browser (OAuth PKCE) when `auth` is configured |
 | `/effort [<level>]` | Set the model's thinking (reasoning) effort — `low`, `medium`, `high`, `xhigh`, `max`. With no level, pick from the levels the current model supports; some models don't support effort at all |
-| `/logout` | Sign out of your Glob.AI OS session |
+| `/logout` | Sign out of your Glob.AI session |
 | `/settings` | Open the settings panel: UI theme, permission mode, compaction |
 | `/auth-status` (alias `/whoami`) | Show the current authentication status |
 
@@ -40,6 +41,7 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `/mcp status` | Show each server's connection status |
 | `/mcp list-tools [server]` | List the tools a server exposes |
 | `/mcp enable <server>` / `/mcp disable <server>` | Toggle a server for this session |
+| `/mcp login <server>` | OAuth sign-in for an HTTP server declared with `"oauth": true` in `mcp.json` — opens the browser, receives the code on a loopback redirect, stores tokens in `~/.coda/mcp-oauth/<server>.json`, bound to the authorization server that issued them (a login saved before that binding existed is discarded and needs one new sign-in) |
 | `/skills` | Open the skills manager (no args), or use a subcommand |
 | `/skills list` | List skills and their enabled state |
 | `/skills enable <name>` / `/skills disable <name>` | Toggle a skill |
@@ -61,6 +63,30 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `/workflows` | Open the workflow dashboard (live run → phase → agent tree and history) |
 | `/workflows stop [runId]` | Stop a workflow run; omit the id to stop all in-flight runs |
 
+## Planning, changes and side questions
+
+| Command | What it does |
+| --- | --- |
+| `/plan <goal>` | Switch to `read-only`, research the codebase and write a plan (`Context / Steps / Acceptance / Risks`) to `.coda/plans/<date>-<slug>.md`. The mode stays read-only until you approve |
+| `/plan approve [--auto]` | Switch back to `default` (or `auto`) and implement the latest plan; its `## Acceptance` checklist becomes the objective of a `/goal` run, so completion is judged against the plan |
+| `/plan list` / `/plan status` | List plan files / show the current permission mode and latest plan |
+| `/review [--base <ref>\|--commit <sha>\|--pr <n>\|--branch <name>] [--instructions <focus>]` | Professional code review from inside the session, same reviewer as `coda review`: intent first, verified findings only (correctness, security, concurrency, error handling, API/behaviour changes, tests), no linter nits, every finding with file:line, severity, the failure scenario and a fix. `--pr` checks the PR out in `.coda/worktrees/pr-<n>` and posts the findings on GitHub as a review (inline comments with one-click `suggestion` blocks where the line is in the diff, the rest in the review body; `--no-post` keeps them local). `--branch` reviews a branch vs `--base` (default: the repo's main branch) — a branch has nowhere on GitHub to hold comments, so open a PR (`gh pr create --head <branch>`) and `--post` sends the same review there. Either way the full review document is saved to `.coda/reviews/<target>/review-<n>.md` |
+| `/fix-pr <n\|url> [--max-rounds N]` | Reads the PR's unresolved review threads and failing checks (with their logs), checks the branch out in a worktree and starts a `/goal`: fix, commit, push, reply on each thread with the commit, wait for the checks — until every check is green and no thread is unresolved. `/goal status` / `/goal stop` control it |
+| `/review --by <model> [...]` / `/review followup` | "Review in another session": the same professional review runs as a read-only reviewer sub-session on the model you name, in the side panel, while this conversation keeps going. `/review followup` sends its findings as the next turn ("address each finding") |
+| `/sessions launch [--models a,b,c] <brief>` (alias `/fanout`) | "Launch sessions": the same brief runs on several models at once — one headless session per model, each in its own worktree (`.coda/worktrees/sess-<stamp>-<n>`), its work committed on that branch when it ends. The side panel follows them: model, state, time · cost · tokens · files, first line of the answer. Default models: ★ favorites plus the current one (max 5) |
+| `/sessions compare [--models a,b] <brief>` (alias `/compare-sessions`) | "Compare on two sessions": the same, on exactly two models; `/sessions synthesize` then asks the current model for a comparison table (approach, files, tests, cost, time, risks) and a pick |
+| `/sessions synthesize` / `/sessions pick <n>` / `/sessions status\|show\|close` | `synthesize`: the current model reads every session's answer, files and commit (it can `git -C <worktree> show HEAD`) and merges or picks; `pick <n>`: cherry-picks session n's commit into this working tree, staged and uncommitted, so `/changes` shows it and `/commit` lands it |
+| `/handoff <model>` | "Hand off to…": the conversation continues on another model; before doing anything it says what it understood (goal, state, open points, next step) and asks what to correct |
+| `/second-opinion [--model m] <question>` / `use` | "Second opinion": one other model (default: the first ★ favorite that is not the current one) answers a bounded question with the recent conversation as context, in the side panel, never in the transcript; `/second-opinion use` folds the last answer into the conversation as the next turn |
+| `/changes [n\|close\|before]` | Expand the sidebar into the **changes panel**: the files this session touched with `+added −removed`, the files that were already dirty before the session (collapsible), and the diff of the selected file. The sidebar's `▸ View changes` row opens the same panel; click a file to select it, PgUp/PgDn or the wheel scroll the diff, Esc or × return to the normal sidebar |
+| `/diff` | Show the working-tree diff (bash tool output already appends `[changed files: …]` after each command that changes the repo) |
+| `/commit [message]` | Ask the agent to stage and commit the current changes with a conventional-commit message |
+| `/export [md\|json] [path]` | Export the current session as Markdown or lossless JSON (`coda session import` re-creates it) |
+| `/ps` / `/stop <id>` | List background processes started with `bash … background: true` (read their output with the `background_output` tool) / terminate one |
+| `/trust [status\|revoke]` | Trust the current folder so its `.coda` hooks, extensions, skills roots, plugins and MCP servers load on the next launch (until then an untrusted folder's executable config is ignored and a notice is printed at startup) |
+| `/council [--models a,b,c] <question>` (alias `/compare`) | Opens a live view: one column per model streaming its answer side by side (spinner → ✓ time · tokens · cost, ✗ on failure), the synthesis streaming underneath with the picked column starred, and one key to continue — `1–N` from that answer, `s` from the synthesis, Esc to close. Every member is a full agent of the session on its model — web search, repo reads, read-only commands — so answers are looked up, not recalled (`provider/model` refs of another configured provider answer without tools). Asks 2–5 models the same question in parallel (default: your ★ favorite models topped up with the current model — star models in `/model` with Space; `provider/model` refs reach other configured providers), see the answers side by side with time/tokens/cost, plus a synthesis by the current model that picks or merges. Nothing enters the conversation until `/council use <n\|synthesis>`; `/council show` repeats the last one |
+| `/btw <question>` (alias `/side`) · `/btw show` · `/btw close` | Ask a side question **in a side panel**: the sidebar gives way to a panel where the question and its answer stream (markdown; run by the bundled `side` sub-agent — web search, grep, read-only bash — on your current model, with the recent transcript as context, so "how did X do yesterday" is looked up rather than declined) — nothing is added to the conversation. Earlier questions stay in the panel; Esc or × returns to the sidebar |
+
 ## Context
 
 | Command | What it does |
@@ -86,6 +112,7 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `coda --timeout <ms>` | Abort a headless run after the given time |
 | `coda --checkpoints[=true\|false]` | Force checkpoints on or off for this run |
 | `coda --model <name>` / `-m` | Use a specific model for this run |
+| `coda --reasoning-effort <level>` | Set the thinking effort for THIS run only — `none\|minimal\|low\|medium\|high\|xhigh\|max` (case-insensitive). Applied in memory; never written to config. Overrides a persisted `reasoning.effort` at launch and is inherited by subagents. An invalid value fails fast; a level the model can't honor prints a stderr warning and is not applied (no silent fallback) |
 | `coda -e <path>` | Load an extra extension file for this run |
 | `coda --mcp-config <path>` | Point at a specific `mcp.json` for this run |
 | `coda --system-prompt <text>` | Replace the built-in base system prompt for this run |
@@ -94,7 +121,7 @@ Reference for the slash commands available in the interactive TUI, plus the shel
 | `coda --coda-home <dir>` | Use an alternate config/data home (equivalent to `CODA_HOME` env var) |
 | `coda --profile <id>` | Select a persisted profile for this run (read-only) |
 | `coda --provider <name>` | Ephemeral provider for a headless run (`glob-ai \| openai-compat \| ollama`) |
-| `coda --instance <id>` | Glob.AI OS instance for a headless run (e.g. `saas-europe`) |
+| `coda --instance <id>` | Glob.AI instance for a headless run (e.g. `us-v1`; the former `saas-us` still works, naming it) |
 | `coda --base-url <url>` | Base URL for `openai-compat` / `ollama` runs |
 | `coda --api-key <key>` | Ephemeral API key for this run (never persisted) |
 
@@ -109,8 +136,17 @@ Beyond launching a session, `coda` exposes a few standalone subcommands:
 | `coda upgrade` | Download and install the platform-native CODA binary from the release feed |
 | `coda logs` | Open the log viewer (or stream when piped); supports filters and `--follow` |
 | `coda logs export` | Write a redacted support bundle to `~/.coda/exports/` — see [View & Share Logs](#logging) |
+| `coda skills` | Inspect and configure skill-discovery sources. `list` / `sources` print the resolved merged view; `enable`/`disable <source>`, `add-path`/`remove-path <dir>` require an explicit `--global\|--project` scope. Add `--json` for a machine-readable envelope — see [Extend CODA](#guide-extend) |
 | `coda plugin install <source>` | Install a plugin from npm, a Git URL, or a local path. Flags: `--scope global\|project` (default `global`; `project` also records it in `<project>/.coda/plugins.json`), `--name <folder>` (pick a subfolder in a monorepo repo), `--copy` (copy-based install for local paths). Note: a `plugin-id@marketplace-id` argument is **not** supported |
 | `coda marketplace install <source>` | Register a plugin marketplace catalog. Flags: `--id <id>`, `--display-name <name>`, `--root-path <path>` |
+| `coda review [--base <ref>\|--commit <sha>\|--uncommitted\|--pr <n>\|--branch <name>]` | Governed headless code review — the same professional reviewer as `/review`: reads the diff (never edits; may run tests/lint), applies `.coda/checks/*.md` if present, returns findings validated against a JSON Schema (file, line, severity, category, kind, title, detail, optional `suggestion`). **Every run writes the full review document** to `.coda/reviews/<target>/review-<n>.md` (or `--out <file>`) in the directory you invoked it from: overview, a files-changed table grouped by concern, a feature overview, a high-level conceptual review, the numbered findings and general feedback — the terminal only shows a digest. `--pr <n\|url>` reviews the PR in its own worktree and also posts a GitHub review (inline comments + summary table; `REQUEST_CHANGES` when a finding reaches `--fail-on`; `--no-post` to only write the document). `--branch <name> [--base <ref>]` reviews a branch and, with `--post`, sends the review to its open PR. `--severity low\|medium\|high\|critical` sets the reporting floor (default `low` — the document is meant to be read in full) and `--fail-on` the CI exit code (default `medium`, so a `low` finding never fails a build; `none` never fails), `--json` prints findings as JSON, `--dry-run` shows the assembled prompt. Progress is reported on stderr as a single status line while it runs; `--verbose` logs every tool call instead |
+| `coda fix-pr <n\|url> [--max-rounds N] [--timeout MIN] [--dry-run]` | Headless "make it green" loop: each round gathers the PR's unresolved review threads and failing checks (with `gh run view --log-failed` excerpts), runs `coda -p <brief>` in `.coda/worktrees/pr-<n>` (the agent fixes, commits, pushes and replies on the threads with the commit), then waits for the checks (`gh pr checks --watch`, up to `--timeout` minutes). The agent only inherits trust when the repo is already trusted (`coda trust`) **and** the PR's branch did not modify `.coda/config.json`/`.coda/mcp.json` relative to its base — otherwise that config is ignored (no override). Exit 0 once every check passes and no thread is unresolved, 1 after `--max-rounds` (default 5), 2 on a usage/setup error. Needs `gh` logged in; `CODA_BIN` picks the binary |
+| `coda github install` | Write a GitHub Actions workflow that runs `coda review` on pull requests (the check fails on findings) and answers `/coda <task>` comments on issues and PRs. Credentials come from repository secrets |
+| `coda mcp add <name> --url <URL> [--oauth [--client-id <id>]] [--header K=V] [--scope global\|project]` / `coda mcp add <name> -- <command> [args]` | Add an HTTP or stdio server to `mcp.json` (project scope when `./.coda` exists, else global). `coda mcp remove <name>`, `coda mcp list`, `coda mcp login <name>` (OAuth 2.1 with PKCE, dynamic client registration and refresh handled by the MCP SDK; `--client-id` sets a pre-registered client id for servers without dynamic registration, e.g. Glob.AI's `mcp`), `coda mcp logout <name>` |
+| `coda schedule add --cron "<expr>" [--name N] [--cwd DIR] [--goal] "<prompt>"` | Persistent schedules stored in `~/.coda/schedules.json`: each run executes `coda -p <prompt>` (or `--goal`) in its cwd and appends to `~/.coda/schedules/<id>.log`. `list`, `remove`, `pause`/`resume`, `run <id>` (now), `log <id>`; `tick` runs what is due and exits (what cron/launchd call every minute), `daemon [--interval S]` keeps ticking in the foreground, `install` registers the tick with launchd (macOS) or prints the crontab line |
+| `coda trust [DIR] \| --list` / `coda untrust [DIR]` | Trusted folders: until a project folder is trusted, coda ignores its `.coda/config.json` hooks, extensions, skills roots and plugins and its `.coda/mcp.json` servers (permissions, model and rules still apply). `--trust` trusts the current folder for one run; `CODA_TRUST_FOLDER` is tri-state — `1` trusts (e.g. CI), `0` is an authoritative deny (set by headless child spawns such as `fix-pr`/`schedule`/`sessions`; overrides `--trust` and folder inheritance), unset falls back to the folder check |
+| `coda session list\|show\|export\|import\|delete` | Headless session management: list this project's sessions, export one as lossless JSON or Markdown, import a JSON export as a new session |
+| `coda session import claude-code\|codex [--list\|--pick N\|--last\|--all] [--continue]` | Continue a conversation started in Claude Code (`~/.claude/projects/*/*.jsonl`) or Codex (`~/.codex/sessions/**/rollout-*.jsonl`): lists that tool's conversations for the current project, imports the one(s) you pick with tool calls and results as history, then `coda --lastsession` (or `--continue`) resumes it on your active profile. A `.jsonl` path works too; the format is detected |
 | `coda checkpoints-demo` | Smoke-test the checkpoint subsystem against a throwaway project |
 | `coda logs-demo` | Self-test the logging pipeline end to end |
 

package/assets/docs/cli-vs-batch.md

@@ -47,6 +47,8 @@ Batch runs a **single turn** — one prompt in, one result out — then exits. T
 | `--lastsession` | Resume the most recent session in headless mode |
 | `--checkpoints` | Enable checkpoint creation (no TUI restore, but useful for diff workflows) |
 
+With the LLM safety check enabled, headless runs consult it too: an approved command runs, and a command it refuses is never auto-approved — not even with `--auto-approve all`.
+
 See [Automate with Batch Mode](#guide-automate) for full examples.
 
 ## How to choose