@globant/coda-linux-x64-baseline-musl 1.4.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" |
@@ -55,16 +55,26 @@ Notation: every entry points to `file.md › § "Exact Heading"`. All files live
 | 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>`)" |
@@ -85,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)
@@ -101,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"
 
@@ -115,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**
 
@@ -130,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?"
@@ -140,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**
@@ -154,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

@@ -44,7 +44,7 @@ An HTTP MCP server uses `url` and may include headers, a bearer-token reference,
       "url": "https://api.example.com/mcp",
       "authorizationToken": "Bearer ${API_TOKEN}",
       "headers": { "X-Project": "${PROJECT_ID}" },
-      "timeout": 30
+      "timeout": 120
     }
   }
 }
@@ -88,14 +88,16 @@ Do not set both. Useful optional fields are:
 | `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` | HTTP | Request timeout in seconds. |
+| `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, `~/.coda/.secrets`, or a project environment file that is excluded from version control.
+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:
 

package/assets/docs/cli-reference.md

@@ -18,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
 
@@ -27,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 |
 
@@ -41,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 |
@@ -62,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 |
@@ -96,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) |
 
@@ -111,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

package/assets/docs/config-json.md

@@ -23,17 +23,19 @@ Most settings cascade in priority order: **CLI flags → project config → glob
   // This is the ONLY provider config CODA writes to disk. "activeProfile" names
   // the profile currently in use; "profiles" is the map of switchable targets.
   // Both are managed by /providers and /switch-profile — you rarely hand-edit
-  // them. Each profile's "provider" is one of:
-  // "glob-ai" | "glob-ai-os" | "openai-compat" | "ollama".
+  // them. Each profile's "provider" is what you connect to: "glob-ai" (any
+  // Glob.AI instance), "openai-compat" or "ollama". For a Glob.AI instance,
+  // Coda records "glob-ai" or "glob-ai-os" itself, from the instance's preset
+  // or from what the endpoint answers when the profile is created.
   "activeProfile": "geai-oauth",
   "profiles": {
-    // Glob.AI OS via OAuth (browser login). Tokens live in the OS keyring, so
+    // Glob.AI via OAuth (browser login). Tokens live in the OS keyring, so
     // no key is stored here. "instance" is a known preset or a custom id;
     // a custom id also needs its own "baseUrl".
     "geai-oauth": {
       "provider": "glob-ai",
-      "label": "Glob.AI OS (OAuth)",
-      "instance": "saas-europe",
+      "label": "Glob.AI (OAuth)",
+      "instance": "eu-v1",
       "auth": { "method": "oauth" },
       "model": "anthropic/claude-opus-4-8",
       // Optional per-tier models for the agents "fast"/"smart"/"deep" shortcuts:
@@ -41,7 +43,7 @@ Most settings cascade in priority order: **CLI flags → project config → glob
       "smartModel": "anthropic/claude-sonnet-4",
       "deepModel": "anthropic/claude-opus-4-8"
     },
-    // Any OpenAI-compatible HTTP API. Key is resolved from ~/.coda/.secrets via secretRef.
+    // Any OpenAI-compatible HTTP API. Key is resolved from the credential store (system keychain, or an encrypted secrets file) via secretRef, falling back to the process environment.
     "my-compat": {
       "provider": "openai-compat",
       "label": "My OpenAI-compat server",
@@ -79,7 +81,7 @@ Most settings cascade in priority order: **CLI flags → project config → glob
   // don't add them by hand; the profiles above are the source of truth. See
   // "The legacy providers map" below if you're maintaining an old config.
 
-  // ── Authentication preferences (Glob.AI OS) ─────────────────────────────────
+  // ── Authentication preferences (Glob.AI) ─────────────────────────────────
   "auth": {
     // Prefer OAuth access tokens or a static API key.
     "methodPreference": "access_token",
@@ -95,7 +97,10 @@ Most settings cascade in priority order: **CLI flags → project config → glob
   },
 
   // ── Permissions (the authorization engine) ────────────────────────────
-  // defaultMode: the session's starting permission mode.
+  // defaultMode: the interactive session's starting permission mode. When
+  //   unset: "auto" only if no `permissions` block exists anywhere, otherwise
+  //   "default" (a managed disableAutoMode policy still forces "default").
+  //   Headless `coda -p` ignores it and follows --auto-approve.
   //   "read-only" (reads only) | "default" (asks for risky) | "auto" (hands-off).
   // allow/ask/deny: rule strings; deny always wins (deny-first).
   // additionalDirectories: extra roots treated as "in project" for edits/writes.
@@ -164,14 +169,15 @@ Most settings cascade in priority order: **CLI flags → project config → glob
   },
 
   // ── Vision (examine_images) ───────────────────────────────────────────
-  // A LiteLLM-style model id. With Ollama, the product-default vision model
-  // follows the main model unless useMainAgentModel is explicitly false.
+  // Optional — omit to use the built-in default vision model. Set it only to
+  // pick a different LiteLLM-style model id. With Ollama and no override,
+  // vision follows the main model unless useMainAgentModel is false.
   "vision": {
-    "model": "openai/gpt-5.4"
+    "model": "google/gemini-3-pro"
   },
 
   // The legacy webSearch block is accepted for compatibility but is not used
-  // by the current Glob.AI OS-backed web_search tool. Leave it out.
+  // by the current Glob.AI-backed web_search tool. Leave it out.
 
   // ── Web fetch tool ────────────────────────────────────────────────────
   // Backend priority: the FIRST entry is the primary, the rest are fallbacks.
@@ -190,10 +196,21 @@ Most settings cascade in priority order: **CLI flags → project config → glob
   // Paths to extension modules (in addition to auto-discovered .coda/extensions).
   "extensions": ["./.coda/extensions/my-tool.ts"],
 
-  // ── Skills tuning ─────────────────────────────────────────────────────
+  // ── Skills tuning + discovery sources ─────────────────────────────────
   "skills": {
     "descriptionMaxChars": 200,
-    "warnThreshold": 100
+    "warnThreshold": 100,
+    // Which external-agent skill directories to scan. `.coda/skills` is
+    // native and always on. Foreign sources are off by default.
+    "sources": {
+      "agents": true,    // .agents/skills (cross-tool)
+      "claude": false,   // .claude/skills
+      "codex": false,    // .codex/skills
+      "opencode": false  // .opencode/skills
+    },
+    // Extra skill roots. Absolute paths apply at both scopes; relative
+    // paths resolve under the project. Unioned across global + project.
+    "paths": []
   },
 
   // ── Checkpoints (file snapshots / undo) ───────────────────────────────
@@ -237,15 +254,13 @@ Most settings cascade in priority order: **CLI flags → project config → glob
     "rawViewer": { "enabled": false }
   },
 
-  // ── Telemetry (Glob.AI OS platform gateway only) ──────────────────────
+  // ── Telemetry (Glob.AI platform gateway only) ──────────────────────
   // The destination is derived from the authenticated provider and cannot be
   // set here. Use /settings → Telemetry for the normal off/basic/full control.
   "telemetry": {
     "level": "basic",              // "off" | "basic" | "full"
     "exporter": "otlp",            // or "console" for local diagnostics
-    "otlpProtocol": "http",
-    "otlpUseTls": true,
-    "serviceName": "coda"
+    "otlpUseTls": true
   }
 }
 ```
@@ -254,11 +269,10 @@ Most settings cascade in priority order: **CLI flags → project config → glob
 
 ## Secrets: keep keys out of the file
 
-Never paste raw API keys into `config.json`. Store them in `~/.coda/.secrets` (dotenv format). API-key profiles reference a secret by **name** via `auth.secretRef`; other compatible string fields use `${VAR}` interpolation:
+Never paste raw API keys into `config.json`. Add them through the `/providers` wizard (or `echo "$KEY" | coda configure --provider … --api-key-stdin`) — the key is stored in your system keychain (or an encrypted secrets file where there is no keychain), never in the config. API-key profiles reference the stored secret by **name** via `auth.secretRef`; other compatible string fields use `${VAR}` interpolation, resolved from a project `.coda/.env` or `.env` file, then `~/.coda/.secrets`, then your process environment:
 
 ```bash
-# ~/.coda/.secrets
-MY_API_KEY=sk-...
+# <project>/.coda/.env  (or ~/.coda/.secrets for global values)
 MCP_TOKEN=...
 ```
 
@@ -277,14 +291,14 @@ MCP_TOKEN=...
 }
 ```
 
-The `.secrets` file is never committed and its values are scrubbed from logs before anything is written to disk.
+Log redaction scrubs secret-shaped values (tokens, keys, credentials) from logs by pattern before anything is written to disk — regardless of where a value is stored.
 
 ## Common edits, by goal
 
 | You want to… | Edit |
 | --- | --- |
 | Switch the active model | `profiles.<id>.model` (or `/model` live) |
-| Add a provider | A new entry under `profiles` (use `/providers`); API-key ones reference a `secretRef` in `.secrets` |
+| Add a provider | A new entry under `profiles` (use `/providers`); API-key ones reference a `secretRef` resolved from the credential store, falling back to a shell-exported environment variable of the same name |
 | Switch which provider is active | `activeProfile`, or `/switch-profile` / `/sp` for the next launch |
 | Switch OAuth ↔ API key | the profile's `auth` block (`{ "method": "oauth" }` vs `{ "method": "apikey", "secretRef": "VAR" }`) |
 | Let commands run more without asking | Set your user-level `permissions.defaultMode` to `"auto"`, or add narrow `permissions.allow` rules — see [Permissions & Approvals](#permissions) |
@@ -294,6 +308,8 @@ The `.secrets` file is never committed and its values are scrubbed from logs bef
 | Use the faster search engine | `tools.grep.backend: "fastgrep"` |
 | Set the web-fetch backend priority | `webfetch.order` — e.g. `["client","anthropic"]` (default) or `["anthropic","client"]`; `[]` disables the tool |
 | Add an MCP server | `~/.coda/mcp.json` or `<project>/.coda/mcp.json` — see [Configure an MCP Server](#add-mcp-server-skill) |
+| Import skills from another agent (Claude/Codex/OpenCode) | Turn on the matching flag under `skills.sources`, or run `coda skills enable <source> --global\|--project` — see [Extend CODA](#guide-extend) |
+| Scan an extra skills folder | Add it to `skills.paths`, or run `coda skills add-path <dir> --global\|--project` |
 | Quiet or verbose logs | `logging.level` / `logging.levels` |
 | Disable update checks | `autoupdate: false` |