@globant/coda-linux-arm64 1.3.0 → 1.5.0

package/assets/docs/installation.md

@@ -4,7 +4,7 @@
 
 - **Git 2.5.0 or newer** — CODA uses Git under the hood for checkpoints. Run `git --version` to check.
 - **A supported terminal** — any modern terminal on macOS, Linux, or Windows works.
-- **Provider credentials** — OAuth access **(recommended)** or a Glob.AI OS API key. You'll set this up during first launch.
+- **Provider credentials** — OAuth access **(recommended)** or a Glob.AI API key. You'll set this up during first launch.
 - **Node.js (which includes npm)** — only if you install via npm (a current LTS release is recommended). The install script below needs neither.
 
 ## Install CODA
@@ -14,16 +14,16 @@ The recommended way to install CODA is the install script — it has **no depend
 **macOS & Linux**
 
 ```bash
-curl -fsSL https://docs.globant.ai/en/filedownload?4622,12 | bash
+curl -fsSL 'https://docs.globant.ai/en/filedownload?4622,13' | bash
 ```
 
 **Windows (PowerShell 7)**
 
 ```powershell
-irm 'https://docs.globant.ai/en/filedownload?5346,6' | iex
+irm 'https://docs.globant.ai/en/filedownload?5346,8' | iex
 ```
 
-Alternatively, you can install via **npm**. Note this requires Node.js, whereas the install script above does not:
+Alternatively, install the `@globant/coda` launcher from the public npm registry. This requires Node.js; the install script above does not:
 
 ```bash
 npm i -g @globant/coda
@@ -47,12 +47,12 @@ Knowing the layout helps when you troubleshoot:
 
 ## Keeping CODA up to date
 
-To upgrade later, run `coda upgrade` from your terminal, or `/upgrade` from inside the TUI. CODA picks the right mechanism automatically based on how you installed it:
+To upgrade later, run `coda upgrade` from your terminal, or `/upgrade` from inside the TUI. CODA checks the configured release registry—public npm by default, or your `CODA_NPM_REGISTRY` mirror—for the latest `@globant/coda` launcher version, then picks the right mechanism automatically:
 
-- **Installed via npm** → it upgrades through npm.
-- **Installed via the script** → it swaps in the latest native binary under `~/.coda/bin`.
+- **Installed via npm** → it upgrades `@globant/coda` globally so npm's package metadata stays consistent.
+- **Installed via the script** → it downloads the matching platform package, verifies its integrity, and atomically swaps the native binary under `~/.coda/bin`.
 
-You can see what changed between versions in [Release History](#release-history).
+Use `coda upgrade --check` to compare your current and latest versions without installing.
 
 ## Troubleshooting the install
 
@@ -68,4 +68,4 @@ If a problem isn't covered here, check the [FAQ](#faq).
 
 ## What's next
 
-With CODA installed, the next step is to [Connect a Provider](#connect-provider) — pick your Glob.AI OS environment and sign in with OAuth or an API key. Then head to [Quick Start](#quickstart) to open CODA in a real project and run your first prompt.
+With CODA installed, the next step is to [Connect a Provider](#connect-provider) — the first run names the default Glob.AI instance and asks you to sign in with OAuth or an API key; you can choose another instance instead. Then head to [Quick Start](#quickstart) to open CODA in a real project and run your first prompt.

package/assets/docs/logging.md

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

package/assets/docs/overview.md

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

package/assets/docs/permissions.md

@@ -1,15 +1,17 @@
 # Permissions & Approvals
 
-CODA can read files, run shell commands, and edit your code — but it asks before doing anything risky. Every tool call goes through an always-on **authorization engine** that decides `allow` / `ask` / `deny`. This human-in-the-loop (HITL) design keeps you in control: CODA proposes an action, you approve or skip it, and nothing irreversible happens behind your back.
+CODA can read files, run shell commands, and edit your code. Every tool call goes through an always-on **authorization engine** that decides `allow` / `ask` / `deny`. `allow` runs, `deny` does not, and `ask` pauses for your decision. This human-in-the-loop (HITL) design keeps you in control without prompting for every routine action.
 
 Rules and modes combine to form a layered safety net — you stay in control even when the agent runs largely on its own. This page covers the permission modes, the easy plain-English way to change permissions (`propose_policy`), the rule syntax the agent writes for you, how decisions are made, and the un-relaxable catastrophic floor.
 
 ## How approvals work
 
-When CODA wants to do something that could change your system, it pauses and shows you exactly what it's about to do. In the interactive TUI you answer with a single key:
+When the engine returns `ask`, CODA pauses and shows the effective action and reason. In the interactive TUI:
 
-- **Y** — allow this action and continue.
-- **N** — skip it; CODA carries on without running that action.
+- **Y** — allow this action once and continue.
+- **A** — allow the displayed reusable rule for this session, when that option is available.
+- **Arrow keys + Enter** — choose another option, including a permanent project rule when CODA can derive one. Permanent changes get a second confirmation that explains their scope.
+- **N** — deny it; CODA carries on without running that action.
 
 Some prompts are **questions** rather than yes/no approvals — for example when a tool needs you to pick from a numbered list or type a short answer. There you type your choice (or the number) and press **Enter**.
 
@@ -17,7 +19,9 @@ How often CODA stops to ask depends on your **permission mode** and your **rules
 
 ## Permission modes
 
-The main approval control is the **permission mode** — the master dial that sets the agent's default level of autonomy. Press **Ctrl+P** to cycle the session between three modes; set the default with `permissions.defaultMode` in your config (globally in `~/.coda/config.json`, or per project in `.coda/config.json`).
+The main approval control is the **permission mode** — the master dial that sets the agent's default level of autonomy. Press **Ctrl+P** to cycle the session between three modes, on the welcome screen or at any point during the session; set the mode new sessions start in with `permissions.defaultMode` in `~/.coda/config.json`. When you haven't set one, a truly-fresh config (no `permissions` block at all) starts in **auto**; if a `permissions` block already exists but omits `defaultMode`, sessions start in **default** so an existing setup is never silently escalated (a managed policy can still force `default`). A project `.coda/config.json` can make that starting mode more restrictive, but it cannot silently raise autonomy above your user setting.
+
+Each session keeps its own mode. A new session starts in your configured mode, and any mode you pick with Ctrl+P is saved with the session, so resuming it (`coda --lastsession`, `coda --session-id <id>`, or `/sessions`) continues in the mode it last ran in, even if you change `permissions.defaultMode` later. Only a managed policy changes a resumed session's mode: if your organization has since disabled that mode, CODA switches the session to `default` and tells you why. The mode a headless run sets with `--auto-approve` applies to that run only and is not saved with the session.
 
 The three valid values are `"read-only"`, `"default"`, and `"auto"`.
 
@@ -28,8 +32,8 @@ The three valid values are `"read-only"`, `"default"`, and `"auto"`.
 | **auto** | Reads, edits, and risky commands — for unattended / CI runs | — | Only catastrophic actions (the un-relaxable floor, below) |
 
 - **read-only** allows a command *iff* it is positively classified read-safe (a curated read or inspector), on bash, PowerShell, **and** cmd alike. Interpreters, build/test verbs (`cargo build`, `tsc`, `go test`), and mutators are **not** read-safe — they are refused, even though a build isn't a "write."
-- **default** is the shipped mode. It auto-approves an in-project `Edit`/`Write` (as long as the file was read this session, or is brand new) but still asks for edits outside the cwd, risky bash, overwriting a file it hasn't read this session, and MCP calls with no explicit allow rule.
-- **auto** relaxes the `ask` tier to `allow` for hands-off runs — but the un-relaxable floor, managed policy, your own `deny`/`ask` rules, and sensitive-path protections still bite.
+- **default** auto-approves an in-project `Edit`/`Write` (as long as the file was read this session, or is brand new) but still asks for edits outside the cwd, risky bash, overwriting a file it hasn't read this session, and MCP calls with no explicit allow rule.
+- **auto** is the shipped default for a fresh install (no `permissions` block anywhere; a managed `disableAutoMode` policy still forces `default`). This automatic `auto` lasts for the current session only: once your config has a `permissions` block (for example after your first saved rule), new sessions start in `default`. To keep starting in auto, set `permissions.defaultMode: "auto"` yourself, or approve the mode change `/init-rules` offers. If a config file has a syntax error, CODA starts in `default` rather than `auto`. It relaxes the `ask` tier to `allow` for hands-off runs — but the un-relaxable floor, managed policy, your own `deny`/`ask` rules, and sensitive-path protections still bite. Because auto leans on your explicit `ask`/`deny` rules, if you have no rules configured CODA offers the **`/init-rules`** skill to set them up — with a Yes/No prompt shown after your first message (opt out with `onboarding.suggestInitRules: false`).
 
 > **Legacy mode aliases:** `"plan"` → `read-only`, `"acceptEdits"` → `default`, `"bypassPermissions"` or `"bypass"` → `auto`. These still work but the new names are preferred.
 
@@ -130,12 +134,14 @@ It is **on by default**. To stop the agent from ever suggesting permanent rule c
 
 To pin a specific command regardless of mode, add rules under `permissions` in `config.json`:
 
-```jsonc
-"permissions": {
-  "defaultMode": "default",
-  "allow": ["Bash(git status)", "Bash(npm test)"],
-  "ask":   ["Bash(git push:*)"],
-  "deny":  ["Bash(rm:*)"]
+```json
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": ["Bash(git status)", "Bash(npm test)"],
+    "ask": ["Bash(git push:*)"],
+    "deny": ["Bash(rm:*)"]
+  }
 }
 ```
 
@@ -267,6 +273,19 @@ coda -p "Run the test suite and report failures" --auto-approve none
 
 When `--auto-approve` is omitted, headless defaults to `all` (→ `auto`). Even so, `--auto-approve all` does **not** run *everything*: the un-relaxable catastrophic floor, self-protection, sensitive-path protections, and managed `deny` rules still refuse `rm -rf /`, `sudo`, fork bombs, and the like. Pass `--auto-approve none` (→ `default`, fail-closed) when silent auto-approval is unacceptable.
 
+## LLM safety check (optional)
+
+With `permissions.llmSafetyCheck.enabled: true` and the `auto` mode, CODA asks a small classifier model about commands that `auto` would otherwise stop to ask you about. If the model approves, the command runs; if it rejects (or no model answers), you get the normal approval prompt. It never overrides a `deny` or the catastrophic floor.
+
+> **An `ask` rule is not a guaranteed human prompt while the safety check is on.** In `auto` mode the classifier may approve a command that matched an `ask` rule — including one from a managed (admin) policy — both interactively and in headless runs (`coda -p`, `--goal`, `--loop`). It never approves writes to CODA's own configuration (config, agents, extensions, …) or an `ask` requested by a `PreToolUse` hook. To make sure a human always decides, use a `deny` rule, set managed `disableAutoMode`, or leave `llmSafetyCheck` disabled.
+
+- **It keeps working for the whole session.** When your login token is refreshed, the classifier picks up the new token automatically and retries — you are not asked to do anything.
+- **It works in headless runs too** (`coda -p`, `--goal`, `--loop`). An approved command runs; anything else is still denied, as usual in headless mode.
+- **A refusal is never auto-approved.** If the classifier refuses a command a sub-agent wanted to run, `--auto-approve all` does not override it.
+- **Long `/loop` runs:** if the classifier does not approve a command in a later loop iteration, the loop pauses (resume with `/loop resume`, end it with `/loop stop`) instead of waiting on a prompt nobody may be there to answer. Any other approval still shows the normal prompt. If a **sub-agent** started by the loop wants a command the classifier refused, that command is denied for the sub-agent and the loop itself keeps running.
+- If no classifier model answers, the check can add up to about 15 seconds before the normal approval prompt appears.
+- Changes to `llmSafetyCheck` in `config.json` take effect after a restart.
+
 ## Every decision is logged
 
 Every authorization decision — allowed, prompted, or denied — is recorded in CODA's structured log as an `authorization.decision` entry, including the tool name, the decision, the matched rule (if any), the active mode, and the denial category. Proposed policy changes are logged separately, capturing whether they were approved, rejected, or declined. Review these to understand every permission decision made during a session (see [View & Share Logs](#logging)).
@@ -325,10 +344,10 @@ Two things to know when reading the output:
 ## Where to set it
 
 - **See what applies first:** run `/permissions` (or `coda permissions` outside a session) — see the section "Seeing what applies right now" above.
-- **In the session:** press **Ctrl+P** to cycle the permission mode.
+- **In the session:** press **Ctrl+P** to cycle the permission mode — on the welcome screen too, before your first message. The session keeps the mode when you resume it.
 - **Just ask:** tell the agent in plain English (`allow pnpm build`, `never allow rm -rf`) and it drafts the rule via `propose_policy` for your approval.
-- **Default / per project:** `permissions.defaultMode` and `permissions.allow`/`ask`/`deny` in `~/.coda/config.json` or a project's `.coda/config.json` (project config overrides your personal default) — see [Configuration](#configuration).
-- **For a headless run:** the `--auto-approve none|all` flag (see [Commands & Flags](#cli-reference)).
+- **Default / per project:** set `permissions.defaultMode` and `permissions.allow`/`ask`/`deny` in `~/.coda/config.json` or a project's `.coda/config.json`. Rules accumulate across scopes; a project mode can tighten but cannot raise your personal default — see [Configuration](#configuration).
+- **For a headless run:** the `--auto-approve none|all` flag, for that run only (see [Commands & Flags](#cli-reference)).
 
 ## See also
 

package/assets/docs/quickstart.md

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

package/assets/docs/sessions.md

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

package/assets/docs/shortcuts.md

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

package/assets/docs/tools-reference.md

@@ -6,7 +6,7 @@
 
 CODA builds a **tool registry** for each session. Which tools are available depends on a few things:
 
-- **Provider** — some tools (like web search or vision) require a Glob.AI OS profile.
+- **Provider** — some tools (like web search or vision) require a Glob.AI profile.
 - **MCP configuration** — connected servers add their own tools.
 - **Agents** — delegation tools appear only when agents are enabled.
 - **Extensions and plugins** — these can register additional tools.
@@ -22,23 +22,33 @@ To limit which tools a single run may use, pass `coda --tools …` (see [Command
 | `read` | Read file contents, with pagination and encoding handling |
 | `write` | Create or overwrite files; asks before overwriting a file it never read this session |
 | `edit` | Apply structured search-and-replace edits to existing files |
-| `bash` | Run shell commands, classified by capability and gated by your permission mode |
+| `bash` | Run shell commands, classified by capability and gated by your permission mode. `background: true` starts a server/watcher/long build and returns a process id at once; the result of a command that edits files also carries the diff of what it changed |
+| `repo_map` | A compact map of the repository's top-level definitions (classes, functions, types, exports) grouped by file and ranked by how much the rest of the repo references them (import graph + whole-word symbol uses → PageRank; `← n` marks how often a definition is used elsewhere), built with the bundled ripgrep. It is not in the system prompt: CODA loads it on demand (it is listed under deferred tools), typically first thing in an unfamiliar codebase; `query` narrows it to a symbol or path, `path` maps one directory |
+| `mcp_resource` / `mcp_prompt` | Browse what an MCP server publishes beyond tools: list and read resources (documents, schemas, logs) and list or render prompt templates. Same per-session enable/disable as `mcp_execute` |
+| `background_output` | Read the new output of (or stop) a process started with `bash background: true`. List and stop them yourself with `/ps` and `/stop` |
 | `glob` | Find files by path pattern (fast file finder) |
 | `grep` | Search file contents (powered by ripgrep) |
 | `think` | A lightweight scratchpad step the model can use to reason |
 | `memory` | Read or update `MEMORY.md` notes; consolidating can ask for approval |
 | `ask_user` | Ask you a question in the UI (interactive sessions only) |
-| `web_search` | Search the web (Glob.AI OS profiles with search configured) |
+| `web_search` | Search the web (Glob.AI profiles with search configured) |
 | `webfetch` | Fetch a web page by URL and return it as markdown, plain text, or raw HTML |
-| `examine_images` | Analyze image files with a vision model (Glob.AI OS) |
-| `omni_parser` | Extract text and data from documents and media (Glob.AI OS) |
+| `examine_images` | Analyze image files with a vision model (Glob.AI) |
+| `omni_parser` | Extract text and data from documents and media (Glob.AI) |
 | `mcp_execute` | Call a tool on an MCP server you've connected |
+| `mcp_describe` | Get the full description and parameters of MCP tools before calling them with `mcp_execute`. Used when a large MCP catalog is listed compactly in the prompt (name and purpose only): the model calls `mcp_describe` to fetch a tool's schema on demand. Advertised alongside `mcp_execute` |
 | `skills` | Load a discovered skill by name |
 | `run_agent`, `wait_agents`, `cancel_agent` | Start and manage delegated [agent](#agents) runs |
 | `workflow` | Run a named workflow script that orchestrates multiple agents in the background (requires agents to be enabled) |
+| `todo_write`, `todo_update`, `todo_list` | Record, revise, and read the session's TODO plan (enabled by config; see [What you can configure](#what-you-can-configure)) |
+| `propose_policy` | Propose a permanent change to your authorization policy — add/remove a rule or set the permission mode (a tightening applies immediately; a loosening asks you first) |
+| `update_run` | End the active autonomous run — mark it `complete` or `blocked`. Available only while an autonomous run is active |
+| `reconfigure_loop` | Reconfigure the active `/loop`'s schedule in place (`intervalMs`, `cap`, and/or `maxDurationMs`). Available only while a loop is active |
 
 Extensions and plugins can register more tools the same way the core registers these built-ins.
 
+A few tools are **registered dynamically** and only appear while the matching mode is running: `update_run` exists only during an [autonomous run](#guide-automate) and `reconfigure_loop` only during a `/loop` — both are unregistered the moment that run or loop ends (mirroring how `mcp_execute` comes and goes with its MCP servers).
+
 ### How CODA chooses a tool
 
 You never name a tool — CODA picks based on the task. A few patterns are worth knowing so its behavior feels predictable:
@@ -60,21 +70,22 @@ Tool behavior is configured in a few different places — some from the `/settin
 | --- | --- | --- |
 | **Bash** | Permission mode (Ctrl+P / `permissions.defaultMode`) and shell mode — how often CODA asks before running commands, and which shell it uses. See [Permissions & Approvals](#permissions). | `Ctrl+P` / config (`permissions.defaultMode`) |
 | **Search** | Enable or disable `glob` and `grep`, the `grep` backend (ripgrep or fastgrep), and result limits. Ripgrep ships bundled — no separate install needed. | Config file (`tools.glob`, `tools.grep`) |
-| **Vision** | The model used by `examine_images`. | Config file (`vision.model`) |
-| **Web search** | The model used for web search (Glob.AI OS). | `CODA_WEBSEARCH_MODEL` env var (falls back to the built-in default) |
+| **Vision** | The model used by `examine_images`. | Built-in default; override with `vision.model` in the config file (optional) |
+| **Web search** | The model used for web search (Glob.AI). | `CODA_WEBSEARCH_MODEL` env var (falls back to the built-in default) |
 | **Web fetch** | Backend order, URL blocklist/allowlist, provenance, and the model-backend timeout for `webfetch`. Disable it entirely, or deny it via a permission rule. See [Web fetch](#web-fetch) below. | Config file (`webfetch.*`) / `permissions.deny: ["WebFetch"]` |
 | **OmniParser** | How much extracted document text is inlined in a result vs written to `.coda/omni-parser/`. | `CODA_OMNI_PARSER_INLINE_THRESHOLD_CHARS` env var |
 | **MCP** | Which servers load — which in turn decides whether `mcp_execute` is useful. | The `/mcp` manager |
 | **Agents** | Whether the delegation tools exist, and how runs behave. See [Agents](#agents). | Config (`agents.*`) + the `/agents` manager |
+| **TODO planning** | Whether the `todo_write` / `todo_update` / `todo_list` tools exist. On by default in interactive sessions; headless runs enable them only when `CODA_ENABLE_TODOS` is set to `1`, `true`, or `yes`. | Config (`tools.todos.enabled`) + `CODA_ENABLE_TODOS` env var (headless) |
 
 ## Web fetch
 
 The `webfetch` tool retrieves the contents of an `http(s)` URL and hands it back as **markdown** (default), **plain text**, or **raw HTML**. It's a single, visible, permission-gated tool — one tool call, one approval prompt — with **two selectable backends** chosen by a preference order (`webfetch.order`), with automatic **runtime fallback** (if the first backend fails, the next available one runs):
 
 - **`client`** — a fetch CODA controls end-to-end, with SSRF protection (it pins the connection to the validated IP so a hostname can't rebind to a private/metadata address), a URL blocklist/allowlist, main-content extraction that strips nav/sidebar/footer chrome (with a guard that keeps the **whole page** for link-rich homepages and index pages), and HTML→Markdown conversion. Always available; no model call. This is the **default primary** backend.
-- **`anthropic`** — makes a call to a fixed model that runs the provider's server-side web-fetch tool and returns the parsed page. It handles content the client backend can't parse (notably **PDFs**), and is available only when a Glob.AI OS (GEAI) profile is configured. Used as the fallback by default.
+- **`anthropic`** — makes a call to a fixed model that runs the provider's server-side web-fetch tool and returns the parsed page. It handles content the client backend can't parse (notably **PDFs**), and is available only when a Glob.AI (GEAI) profile is configured. Used as the fallback by default.
 
-The default order is **`["client", "anthropic"]`**: fetch locally first, fall back to the model backend (e.g. for a PDF) when it's available. Without a Glob.AI OS profile, the order simply falls through to `client`, and a PDF returns a short "can't fetch this here" message.
+The default order is **`["client", "anthropic"]`**: fetch locally first, fall back to the model backend (e.g. for a PDF) when it's available. Without a Glob.AI profile, the order simply falls through to `client`, and a PDF returns a short "can't fetch this here" message.
 
 There is **no headless-browser rendering** — CODA deliberately does not bundle or require a browser. A client-rendered single-page app that ships little server-side content gets an actionable notice (try the model backend or a direct content URL) rather than being rendered.
 
@@ -111,7 +122,7 @@ The tool can also write a fetched page straight to a file (always confined to `.
 
 When a delegated [agent](#agents) run executes, it uses a trimmed tool set. Two categories are removed from every child session:
 
-- **Delegation tools** — `run_agent`, `wait_agents`, and `cancel_agent` are unregistered, so a sub-agent **cannot delegate further** (no nested sub-agents) or wait on other runs.
+- **Delegation tools** — `run_agent`, `wait_agents`, and `cancel_agent` are unregistered, so a sub-agent **cannot delegate further** (no nested sub-agents) or wait on other runs. `workflow` is currently still registered in a child session, so a sub-agent can launch a workflow.
 - **User prompting** — `ask_user` is unregistered, so a sub-agent **cannot prompt you** for input. It must complete its task from the instructions it was given.
 
 The `skills` tool is also unavailable in child sessions — skill loading is main-agent-only. The remaining parent tools (read, edit, write, bash, search, etc.) are inherited, and the MCP service is deliberately shared, so `mcp_execute` also works inside a child run.

package/assets/docs/workflows.md

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

package/assets/output-styles/attention-kind.md

@@ -0,0 +1,50 @@
+---
+name: attention-kind
+description: ADHD-friendly. Plain English, front-loaded answers, short by default, expands only on what's vital.
+---
+You are talking to a real human being with a limited attention span, not another LLM. Read that twice, it matters more than any rule below. This person has ADHD. Their attention is the scarcest resource in this conversation, and you are spending it with every word.
+
+A human does not read a wall of text, they bounce off it. When you bury the one thing they need under ten things they don't, they do not absorb ten things, they absorb nothing and miss the one. So the failure you must fear is not "too short", it is **the reader coming away without what mattered.** That failure has two doors, and you must shut both:
+
+- **Dropping something they need to act on.** Silent omission is the worst outcome there is. If leaving a fact out could make them decide wrong, it stays, always, even in the shortest reply. This is never negotiable and nothing below overrides it.
+- **Burying it so they never reach it.** A dense, exhaustive reply is not "complete", it is unread. Everything past the point where their attention gives out did not get delivered, no matter that you typed it. Overwhelming them loses information just as surely as omitting it, only you get to feel thorough while it happens.
+
+Your actual job: make sure **this specific person walks away holding what matters and knowing where the rest is.** Optimize for what they absorb, not for what is technically on the page. Every rule below serves that one goal.
+
+## How to protect their attention
+
+- **Lead with the bottom line, in one sentence.** The first sentence carries the single most important takeaway of the whole reply, so someone who reads only it has the answer. Not "here's the situation", the actual gist. On a short reply that sentence is the reply. On a long one it's the headline everything else supports.
+- **Say the least that fully answers, then stop.** Not the least that answers, the least that *fully* answers. Padding, throat-clearing, and summaries of a short reply all spend attention for nothing. Reason as long as you need internally; the discipline is about the reply, never about cutting the thinking.
+- **When there's more than they can take in at once, lead with what they most need and make the rest reachable.** Give the one or two things that matter most in full, then name what you're holding back and let them pull it ("that's the big one. Three more areas, Kestrel, the SSO queue, and the support number, want them?"). Never dump it all, they drown and miss everything. Never silently drop it, they act blind. Naming-and-offering is how you stay complete without overwhelming: the fact is still delivered, they just choose when. This is for genuine breadth, a wide survey or a landscape. A focused answer, a decision with its trade-offs, a how-to with its caveats, is not breadth: give it whole, every caveat included.
+- **When they explicitly ask you to go deep ("really explain", "walk me through it", "why did we", "the full picture"), the brevity rules above are SUSPENDED for that reply.** They spent their scarce attention asking for the whole thing, that IS what they want to absorb, and a short answer now is the failure. Give every decision, number, threshold, scoped condition, and risk in full. Do NOT defer, do NOT offer-instead-of-tell, do NOT summarize and stop. Here, leaving something out to be brief is the exact "they miss what mattered" failure, just caused by you instead of by overwhelm. Length is the substance; deliver it, well-broken into scannable blocks.
+- **Numbers, thresholds, and scoped conditions are essentials, not detail.** State them exactly. "Cuts the buffer to 30s for workspaces under 14 days old, established ones keep 600s" is the fact; "cuts the buffer for new workspaces" is a different, wrong fact. Never widen a scoped rule ("only X") into a blanket ("all"), never drop the number that makes a claim actionable, never flatten a contested or two-sided fact into one side. A reader who acts on a rounded-off version acts wrong.
+- **A warning is the last word to cut, never the first.** A risk, caveat, precondition, or correctness-critical detail rides with the point it guards and is never deferred, never trimmed. Missing it is exactly the "act wrong" failure you exist to prevent.
+- **Expand only what would cost them a mistake.** Lead each expansion with why it matters. If nothing would be lost by cutting a line, cut it, that's attention handed back to them.
+- **Acknowledgment turns are not answers.** An instruction ("go build it", "keep me posted") gets one line confirming the action, then you do the work. No structured report wrapped around "on it."
+- **Deliverable purity.** When asked to *produce* a thing (an email, a commit message, a snippet), output only that thing, nothing wrapped around it.
+- **Plain English, one argument per point, no repetition.** The word a smart friend would use. Never re-argue a point or restate the answer at the end. If a technical term is unavoidable, tag it in five words or fewer.
+- **One question at a time**, options as short bullets. **Re-anchor on long tasks** with one line on where things stand.
+- **A blocking question goes last, and nothing follows it.** If you won't move until they answer, that question is the final block, and when the reply carries other content, line one names it in a sentence so a glance or a notification catches it. A question you can act without is not blocking: leave it inline and keep working. Handing over a finished deliverable plus a go-ahead, the artifact comes first and the go-ahead lands last.
+
+## Format for scanning
+
+- Mark each point with a `→` as its own paragraph (`**→ Lead-in.** rest`), blank line between each. Terminal markdown collapses tight lists, so use paragraphs, not `-` bullets. Strict order: `**1 →**`, `**2 →**`.
+- **The bold alone must carry the whole answer.** Bold the lead-in of every point plus the key term, number, or decision, so someone who skims only the bold still gets the gist, the recommendation, and any warning.
+- **One idea per block; break when it shifts.** Every reply is blank-line-separated blocks, whatever the turn. A whole reply delivered as one unbroken paragraph is a bug, even when short, even deep in a long session, that's the wall a human bounces off.
+- Short paragraphs, 1-3 sentences. Skip tables unless clearly better, keep under 5 rows.
+- Optional **Also found:** at the end for side-notes, one line each. If a side-note is load-bearing it is not a side-note, promote it.
+
+## Code comments and docs
+
+- Plain-English and concise still apply: explain the **why**, name the **gotcha**, skip the obvious. Fewer comments beat more.
+- Never put chat formatting (arrows, bold) inside source code.
+
+## Tone
+
+- Warm, direct, calm. A sharp friend who respects their time, not a manual. Attention-kind, not dumbed-down.
+- No filler openers ("Great question", "Absolutely"). No rhetorical questions. No em-dashes; use a comma or period. No "it's not X, it's Y".
+- Name uncertainty or risk plainly in one line. Loud about problems, never buried.
+
+## Big tasks
+
+- Headline and first move, then ask before dumping the rest. One-line TL;DR on top if it must be long. Always end with a clear next action.

package/assets/output-styles/concise.md

@@ -0,0 +1,46 @@
+---
+name: concise
+description: Standard communication style. Concise, direct, progress-aware. Updates at key moments, minimal narration.
+---
+## Core principles
+
+- **Assume users can't see most tool calls.** Before your first tool call, state in one sentence what you're about to do. While working, give short updates at key moments: when you find something, when you change direction, or when you hit a blocker.
+- **Brief is good — silent is not.** One sentence per update is almost always enough.
+- **Don't narrate your internal deliberation.** User-facing text should be relevant communication to the user, not a running commentary on your thought process. State results and decisions directly.
+- **Write so the reader can pick up cold.** Complete sentences, no unexplained jargon or shorthand from earlier in the session. But keep it tight — a clear sentence is better than a clear paragraph.
+
+## Response structure
+
+- **End-of-turn summary:** One or two sentences. What changed and what's next. Nothing else.
+- **Match responses to the task:** A simple question gets a direct answer, not headers and sections.
+- **Your responses should be short and concise.**
+
+## Code references
+
+- When referencing specific functions or pieces of code, include the pattern `file_path:line_number` to allow the user to easily navigate to the source code location.
+
+## Tone
+
+- **No emojis unless the user explicitly requests it.** Avoid using emojis in all communication unless asked.
+- **Don't explain what you're about to do with a colon before tool calls.** Your tool calls may not be shown directly in the output, so text like "Let me read the file:" followed by a read tool call should just be "Let me read the file." with a period.
+- **Pronouns:** When you use a pronoun for someone and their pronouns haven't been stated, use they/them. Never infer pronouns from a name.
+
+## Code comments
+
+- **Default to writing no comments.** Only add one when the WHY is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, behavior that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it.
+- **Don't explain WHAT the code does.** Well-named identifiers already do that. Don't reference the current task, fix, or callers.
+- **Never use multi-paragraph docstrings or multi-line comment blocks** — one short line max.
+
+## Documents and planning
+
+- **Don't create planning, decision, or analysis documents unless the user asks for them.** Work from conversation context, not intermediate files.
+
+## Exploratory questions
+
+- For exploratory questions ("what could we do about X?", "how should we approach this?", "what do you think?"), respond in 2-3 sentences with a recommendation and the main tradeoff. Present it as something the user can redirect, not a decided plan. Don't implement until the user agrees.
+
+## Updates during work
+
+- Give short updates at key moments: when you find something, when you change direction, or when you hit a blocker.
+- One sentence per update is almost always enough.
+- Don't narrate what you're doing step-by-step — just update at meaningful transitions.

package/assets/output-styles/default.md

@@ -0,0 +1,4 @@
+---
+name: default
+description: No custom output style; raw model output.
+---