@globant/coda-windows-x64 1.0.0

package/assets/docs/extensions.md

@@ -0,0 +1,260 @@
+# Writing Extensions
+
+Extensions are TypeScript modules that plug into CODA. Use them when you want CODA to integrate with an internal system that has no MCP server, or to automate a workflow that's too complex for a skill. An extension can register custom **tools**, **slash commands**, and **lifecycle hooks** — and even intercept tool calls.
+
+> Looking for the high-level overview of skills, extensions, and plugins? See [Extend CODA](#guide-extend).
+
+## The easy way: let CODA write it
+
+You don't have to learn the API to build an extension. CODA ships with a **`create-extension`** skill that scaffolds one for you — just describe what you want in plain language:
+
+```text
+/create-extension
+
+I want an extension that adds a /deploy slash command which deploys
+the app to staging or production.
+```
+
+CODA generates the extension file, places it in the right folder, and explains how to use it. This is the recommended path for most people.
+
+The rest of this page is a **reference** for when you want to understand what CODA generated, or hand-write and fine-tune an extension yourself — you don't need to read it to get started.
+
+## Anatomy of an extension
+
+An extension is a TypeScript file that exports an `activate` (or `default`) function receiving the `ExtensionAPI`. It lives in `.coda/extensions/` (project) or `~/.coda/extensions/` (global) — no configuration needed.
+
+```typescript
+import { z, type ExtensionAPI, type AgentTool, type ToolContext } from "@globant/coda-core";
+
+export default function activate(api: ExtensionAPI): void {
+  // Register tools, commands, hooks
+}
+```
+
+`@globant/coda-core` re-exports `z` (Zod) so your extension needs only one import source.
+
+## Where extensions load from
+
+Extensions are auto-discovered, highest priority first:
+
+| Priority | Source | Scope |
+| --- | --- | --- |
+| 1 | `.coda/extensions/*.ts` | Project-level (highest) |
+| 2 | `~/.coda/extensions/*.ts` | User-global |
+| 3 | `config.json` → `extensions[]` | Configured paths |
+| 4 | `-e ./path.ts` | CLI flag |
+
+Subdirectory extensions are also discovered. For a folder, CODA resolves the entry file in this order: `package.json` `coda.extensions` → `package.json` `main` → `main.ts` → `<folder-name>.ts` → `index.ts` / `index.js`. To see what's loaded, run `/extensions` inside CODA.
+
+## Registering a tool
+
+Tools are functions the agent can call. Use Zod for the parameter schema.
+
+```typescript
+const myTool: AgentTool<MyParams, string> = {
+  name: "my_tool",
+  description: "Clear description of what the tool does and when to use it",
+  parameters: z.object({
+    query: z.string().describe("What to search for"),
+    limit: z.number().int().positive().optional().describe("Max results"),
+  }),
+  label: "My Tool",
+  execute: async (toolCallId, params, context: ToolContext) => {
+    const cwd = context.cwd ?? process.cwd();
+    // ... do the work ...
+    return "result string returned to the agent";
+  },
+};
+
+api.registerTool(myTool);
+```
+
+Inside `execute`, the `ToolContext` gives you what you need:
+
+| Field | Purpose |
+| --- | --- |
+| `cwd` | Project directory |
+| `signal` | Cancellation signal (`AbortSignal`) |
+| `hitl` | Human-in-the-loop prompts (ask for approval) |
+| `operations` | File and shell helpers: `readFile`, `writeFile`, `glob`, `stat`, `exists`, `exec`, … |
+| `sessionId` | Current session ID |
+| `mcp` | MCP server access |
+| `onUpdate` | Stream progress updates back to the UI |
+| `model` | Current model info |
+
+**Description tips:** lead with the category in CAPS, explain when the agent should pick this tool over alternatives, and include short parameter examples in the description.
+
+## Registering a slash command
+
+Commands are invoked by the user as `/name args`.
+
+```typescript
+api.registerCommand("deploy", {
+  description: "Deploy the application to staging or production",
+  getArgumentCompletions: (prefix) => {
+    const options = [
+      { value: "staging", label: "staging — deploy to staging" },
+      { value: "production", label: "production — deploy to production" },
+    ];
+    const p = prefix.trim().toLowerCase();
+    return p ? options.filter((o) => o.value.startsWith(p)) : options;
+  },
+  handler: async (args, ctx) => {
+    if (!args.trim()) {
+      ctx.addMessage?.("system", "Usage: /deploy [staging|production]");
+      return;
+    }
+    await ctx.sendMessage?.(`Deploy to ${args.trim()}`);
+  },
+});
+```
+
+The handler context (`ExtensionCommandContext`) lets you drive the session:
+
+| Field | Purpose |
+| --- | --- |
+| `addMessage(role, content)` | Add a system/error/user message to chat |
+| `sendMessage(text)` | Send as a user message (triggers an agent response) |
+| `clearMessages()` | Clear the conversation |
+| `setModel(id)` | Switch the model |
+| `session` | The AgentSession (read-only) |
+| `ui` | `select`, `confirm`, `input`, `notify`, `setStatus` |
+| `showModelPicker()` / `showSettings()` / `showMcpManager()` | Open overlays |
+| `showProvidersManager?()` | Open the providers manager overlay |
+| `newSession?(options?)` | Start a new session (optionally parented) |
+| `fork?(entryId)` | Fork the session from a given timeline entry |
+| `navigateTree?(targetId, options?)` | Navigate to a specific node in the session tree |
+| `switchSession?(sessionPath)` | Switch to an existing session by path |
+| `reload?()` | Trigger a session reload |
+| `waitForIdle()` | Wait until the agent finishes the current turn |
+| `exit()` | Close the CLI |
+| `cwd` | The current working directory |
+| `sessionId` | The active session id |
+| `mcp` | Reference to the MCP service (for inspecting connected servers) |
+
+**Reserved command names** — extensions can't override these built-ins:
+
+```text
+model, models, clear, compact, exit, help, mcp, providers, settings,
+skills, agents, extensions, plugin, plugins, reload-plugins,
+init, timeline, rewind, checkpoint-status
+```
+
+## Subscribing to lifecycle hooks
+
+Hooks let you react to (or modify) what CODA does at key moments.
+
+```typescript
+api.on("session_start", async ({ sessionId }) => {
+  console.error("Session started:", sessionId);
+});
+
+api.on("context", async (context) => {
+  // Mutate in place before each LLM call
+  context.systemPrompt += "\n\n## My custom instructions\n...";
+});
+```
+
+| Hook | Payload | When it fires |
+| --- | --- | --- |
+| `session_start` / `session_end` | `{ sessionId }` | After session creation / when it ends |
+| `session_shutdown` | `{}` | Process exit — flush buffers |
+| `before_agent_start` | `{ text, sessionId }` | Before the agent loop |
+| `agent_start` / `agent_end` | `{ turnId }` | Agent loop boundaries |
+| `turn_start` / `turn_end` | `{ turnId }` | Per-LLM-turn boundaries |
+| `context` | `{ systemPrompt, messages, tools }` | Mutate before each LLM call |
+| `input` | `InputEvent` | Transform user input before send |
+| `model_select` | `{ model }` | After `setModel()` switches the active model |
+| `tool_call` | `ToolCallEvent` | Intercept or deny a tool call |
+| `tool_result` | `ToolResultEvent` | Modify a tool result |
+| `session_before_compact` | — | Before compaction (return `{ cancel: true }` to cancel) |
+| `session_compact` | — | After compaction completes |
+| `session_before_switch` | `{ sessionId }` | Before switching to a different session |
+| `session_switch` | `{ sessionId }` | After a session switch completes |
+| `session_before_fork` | `{ entryId }` | Before forking from a timeline entry |
+| `session_fork` | `{ sessionId }` | After a fork completes |
+| `session_before_tree` | — | Before the session tree is traversed |
+| `session_tree` | — | After the session tree traversal |
+| `message_start` | `MessageEvent` | When a new message begins streaming |
+| `message_update` | `MessageEvent` | On each incremental message update |
+| `message_end` | `MessageEvent` | When a message finishes streaming |
+| `tool_execution_start` | `ToolExecutionEvent` | When a tool starts executing |
+| `tool_execution_update` | `ToolExecutionEvent` | On tool execution progress update |
+| `tool_execution_end` | `ToolExecutionEvent` | When a tool finishes executing |
+| `resources_discover` | — | When CODA discovers extension resources |
+| `user_bash` | `UserBashEvent` | When the user runs a shell command via the bash tool |
+
+> **`context` hook — important invariant:** The `context` payload also contains a `messageIds` field — a parallel array to `messages` where `messageIds[i]` is the DB row id for `messages[i]` (or `null` for synthetic messages). The invariant `messages.length === messageIds.length` is load-bearing. If your hook appends, inserts, or reorders `payload.messages`, you **must** apply the same operation to `payload.messageIds`, pushing `null` for synthetic entries.
+
+The `input` hook returns one of three actions to control the message: `{ action: "continue" }` passes it through unchanged, `{ action: "transform", text }` replaces the text, and `{ action: "handled" }` swallows the message entirely (CODA does nothing further with it).
+
+## Intercepting tool calls
+
+Use the `tool_call` hook to block dangerous commands or rewrite inputs before they run:
+
+```typescript
+api.on("tool_call", async ({ toolName, input }) => {
+  if (toolName === "bash" && input.command?.includes("rm -rf /")) {
+    return { deny: true, reason: "Blocked destructive command" };
+  }
+});
+```
+
+The hook can return `{ deny: true, reason }` to cancel the call with an error, or `{ block: true, reason }` to pause it and wait for explicit user approval before proceeding. Returning nothing (or `undefined`) lets the call proceed normally.
+
+## Registering shortcuts, providers, and flags
+
+Beyond tools, commands, and hooks, an extension can register a few other surfaces (all optional):
+
+```typescript
+// A keyboard shortcut (CLI only). Pick a key that isn't reserved (see below).
+api.registerShortcut?.("ctrl+k", {
+  description: "Run my action",
+  handler: (ctx) => ctx.addMessage("system", "Triggered!"),
+});
+
+// A custom model provider.
+api.registerProvider?.("my-provider", {
+  baseUrl: "https://api.example.com/v1",
+  apiKey: process.env.MY_KEY,
+  models: [{ id: "my-model", name: "My Model", contextWindow: 128000 }],
+});
+
+// A CLI flag parsed from process.argv. `type` is required ("boolean" or "string";
+// a string flag reads --name=value).
+api.registerFlag?.("my-flag", { type: "boolean", description: "Enable my feature" });
+
+// Read a flag value registered above.
+const isEnabled = api.getFlag?.("my-flag");
+
+// Dynamically unregister a tool previously added with registerTool.
+api.removeTool("my_tool");
+
+// Register a custom renderer for a custom message type.
+api.registerMessageRenderer?.("my-custom-type", (entry) => {
+  // Return a React node or string representation for the custom message.
+  return entry.content;
+});
+```
+
+**Reserved shortcuts** — extensions can't override these: `escape`, `ctrl+b`, `ctrl+c`, `ctrl+g`, `ctrl+l`, `ctrl+o`, `ctrl+u`, `ctrl+d`, `ctrl+up`, `ctrl+down`, `ctrl+j`, `ctrl+shift+c`.
+
+## Loading, testing, and reloading
+
+- **Drop-in load.** Save your `.ts` file under `.coda/extensions/` (project) or `~/.coda/extensions/` (global) and CODA picks it up on the next launch — no registration step.
+- **Verify it loaded.** Run `/extensions list` inside CODA to confirm your extension is active and see the tools and commands it registered; `/extensions guide` prints API help.
+- **Iterate quickly.** If your extension is bundled with plugins, `/reload-plugins` re-reads them after you change the files on disk. Otherwise, relaunch CODA to reload a standalone extension file.
+- **Try one for a single run.** Pass `-e ./path/to/extension.ts` on the command line to load an extra extension just for that session — useful while developing.
+
+## Tips for good extensions
+
+- **Write tool descriptions for the model, not the user.** Lead with a CAPS category, say *when* to pick this tool over alternatives, and include a short parameter example. CODA chooses tools from these descriptions.
+- **Respect cancellation.** Honor `context.signal` in long-running tool work so **Esc** can interrupt cleanly.
+- **Ask before doing harm.** Route risky actions through `context.hitl` so they go through the same approval flow as built-in tools.
+- **Use `context.operations`** for file and shell access instead of importing Node APIs directly — it's the supported, sandbox-aware path.
+
+## See also
+
+- [Extend CODA](#guide-extend) — when to use skills vs extensions vs plugins.
+- [Tools Reference](#tools-reference) — the built-in tools your extension sits alongside.
+- [Permissions & Approvals](#permissions) — the HITL flow your tools should hook into.

package/assets/docs/faq.md

@@ -0,0 +1,152 @@
+# FAQ
+
+Common questions, organized by what you're trying to do.
+
+## Getting started
+
+### How do I check which version I'm running?
+
+```bash
+coda --version
+```
+
+### How do I add or change a provider?
+
+From your terminal (outside a session): `coda --reconfigure`. From inside an active session: `/providers`. Note that `/providers` changes require restarting CODA to take effect.
+
+### How do I set up two projects (e.g. two Clients projects) and switch between them?
+
+Configure each one as its own profile, then switch with `/switch-profile`:
+
+1. Run `/providers` and sign in to the first Clients project (OAuth or API key). CODA saves it as a named profile.
+2. Run `/providers` again and sign in to the **second** Clients project. Because it's a different organization/project, CODA stores it as a **separate** profile rather than overwriting the first.
+3. From then on, flip between them with `/switch-profile` (alias `/sp`) — no argument opens a picker, or pass the profile id directly (`/switch-profile geai-clients`). The switch is saved as `activeProfile` and applies on the next launch.
+
+Use `/switch-profile` when you only want to change which configured profile is active; use `/providers` to add, edit, or remove one. See [Connect a Provider](#connect-provider) › "Switch between configured providers".
+
+### I'm logged in with OAuth. How do I switch to a different project?
+
+You have two options:
+
+- **Stay in the session** — run `/project` (Glob.AI OS OAuth only). It lists the organizations and projects your account can access; pick one, or run `/project <id>` directly. This re-targets the active project without a restart. See [Connect a Provider](#connect-provider) › "Switching the active Glob.AI OS project".
+- **Switch profiles** — if you've configured the other project as its own profile (see above), `/switch-profile` selects it instead. That change applies on the next launch.
+
+Reach for `/project` for a quick in-session project change on the same login; use `/switch-profile` to move between separately configured profiles (which may also differ in environment or auth method).
+
+### How do I run CODA in batch mode, and how does it authenticate?
+
+Run a single prompt headlessly with `-p` (or `--prompt`):
+
+```bash
+coda -p "Summarize the open TODOs in this repo"
+```
+
+By default a batch run uses your **active profile** (`activeProfile` from `~/.coda/config.json`) — the same credentials you set up interactively, including a stored OAuth session. So the usual flow is: log in once with `/providers` in the TUI, then run `coda -p …` in CI. To target a specific saved profile instead of the active one, pass `--profile <id>`.
+
+You can't start an interactive **OAuth browser login** in batch mode — there's no browser to hand off to. For headless OAuth, reuse a profile you already authenticated interactively (`--profile <id>` or the active profile). To provide credentials inline for a one-off run without saving them, use the ephemeral flags — for example `--provider openai-compat --base-url … --api-key …`, or `--provider glob-ai --instance clients --api-key …`. The key is held only in memory and never written to disk. See [Automate with headless mode](#guide-automate) › "Authenticating in batch mode".
+
+### CODA opened and immediately shows a setup wizard. Is that normal?
+
+Yes. The wizard appears automatically on first launch if no provider is configured. Follow the prompts to add your credentials. You can also trigger it manually at any time with `coda --reconfigure`.
+
+### How do I get help from inside CODA?
+
+A few ways: type `/help` for the command list, press `?` for the keyboard-shortcuts overlay, or just **ask CODA in plain language** ("how do I undo a change?"). When you ask about CODA itself, it delegates to the built-in **`coda-help`** agent, which answers from the local user guide. You can also call it directly with `/agents run coda-help "<your question>"`. See [Agents](#agents) for more.
+
+## Working with sessions
+
+### How do I pick up where I left off?
+
+Use `coda --lastsession` to resume the most recent session. For a specific session, use `coda --session-id <id>` — when you exit, CODA prints the exact `coda --session-id <id>` command, ready to copy and paste. From inside CODA, browse sessions with `/sessions`.
+
+### What does the context percentage in the status bar mean?
+
+It shows how full the current conversation context is. When it approaches 100%, CODA automatically compacts the session history. If you're seeing degraded quality near 100%, run `/compact` manually or start a `/new` session.
+
+### CODA seems to have "forgotten" something from earlier in the session. Why?
+
+Automatic compaction condenses older messages into a summary to keep the session running. If you need full history for debugging, open `/settings` → **Context Compaction** to disable it or adjust when it kicks in.
+
+## Making changes
+
+### How do I undo what CODA just did?
+
+Type `/timeline` (or `/rewind`, or press **Esc** twice) to see all snapshots from this session. Pick the checkpoint from before the message that caused the bad change: CODA restores your files to the state they had right before that message was processed. Requires Git 2.5.0+.
+
+### How do I stop CODA from asking me to approve every command?
+
+Raise the bash approval level from `/settings` → **Bash Tool Preferences**. Levels are:
+- `safe` — only truly read-only commands; everything else asks.
+- `low` — the default; a conservative set of safe commands and low-risk writes auto-approve.
+- `medium` — more destructive operations auto-approve.
+- `high` — everything auto-approves except the most destructive operations.
+
+For a single headless run, pass `--bash-security <level>` (e.g. `--bash-security high`) to override the approval level without changing your saved config. See [Configuration](#configuration) for details.
+
+### What is AGENTS.md and should I have one?
+
+It's optional, but recommended — especially for shared projects. It's a Markdown file at your project root that CODA reads at the start of every session, where you document your coding conventions, how to run tests, what files not to touch, etc. Generate one with `/init` (or write it by hand), customize it, and commit it to Git so the whole team benefits.
+
+## Extensions and tools
+
+### How do I connect an MCP server?
+
+Open the `/mcp` manager inside CODA and add the server — paste its JSON or import it from a file. From the same place you can check its status, view its tools, and enable or disable it. See [Extend CODA](#guide-extend) for details.
+
+### How do I create a skill?
+
+Create a `.md` file with YAML frontmatter (`name` and `description` are required) and place it in `<project>/.coda/skills/` or `~/.coda/skills/`. The slash command `/skill-name` invokes it. See [Extend CODA](#guide-extend) for a complete example.
+
+### How do I create an extension?
+
+The easiest way is to ask CODA: run `/create-extension` and describe what you want in plain language — the built-in `create-extension` skill scaffolds the TypeScript file and places it in the right folder for you. If you'd rather hand-write or fine-tune one, see [Writing Extensions](#extensions) for the full API reference.
+
+### What are agents?
+
+Agents are Markdown-defined profiles that CODA can use to delegate subtasks — like spawning a second CODA instance to explore one area of the codebase while the main session works on another. CODA picks when to use them automatically, or you can trigger them explicitly with `/agents run <profile> <task>`.
+
+### What's the difference between an agent and a workflow?
+
+An **agent** handles one delegated task. A **workflow** orchestrates **many** agents — running them in parallel, in pipelines, or in loops — for jobs too big for a single agent, like a repo-wide audit. Ask CODA to build one (it uses the built-in `create-workflow` agent), run it by name in plain language, and monitor it with `/workflows`. See [Workflows](#workflows).
+
+### How do I stop a running workflow?
+
+Open `/workflows` and press **`c`** on a running entry, or run `/workflows stop <runId>`. Omitting the id (`/workflows stop`) stops **all** in-flight runs for the session. See [Workflows](#workflows).
+
+### How do I install a plugin or browse the marketplace?
+
+From inside CODA, open the `/plugin` manager to install, enable, disable, and browse the marketplace. From your terminal, `coda plugin install <source>` works too, where `<source>` is an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. CODA is compatible with the Claude Code plugin ecosystem. To browse a marketplace catalog, first register one with `coda marketplace install <source>`; then `/plugin` lists available plugins from that catalog. See [Extend CODA](#guide-extend).
+
+## Models and cost
+
+### How do I switch models?
+
+Press `Shift+Tab` to cycle your favorite models, or run `/switch-model` (alias `/sm`) to open the picker — apply it to just this session or save it as your new default. For a single headless run, pass `--model <name>`.
+
+### Where do I see token usage and cost?
+
+The TUI status bar shows the context fill percentage and running token/cost figures for the session, so you can keep an eye on how much a long session is consuming.
+
+## Operations
+
+### Where are my config, sessions, and logs stored?
+
+Everything lives under `~/.coda/` — `config.json`, `.secrets`, the session database `coda.db` (with per-session override files under `sessions/<id>/`), `logs/`, `checkpoints/`, and `exports/`. Point `CODA_HOME` at a different directory to relocate all of it — or pass `--coda-home <path>` on the command line (both have the same effect; the flag wins when the env var is not set). See [Configuration Reference](#config-reference).
+
+### How do I view or share logs safely?
+
+Run `coda logs` for the viewer (filter by `--level`, `--service`, `--since`, or `--follow`). To share with support, `coda logs export` writes a redacted, path-scrubbed bundle to `~/.coda/exports/` — nothing is ever uploaded. Secrets are scrubbed before anything hits disk. See [View & Share Logs](#logging).
+
+### Can I use checkpoints in CI?
+
+Not for rollback — the `/timeline` picker is a TUI feature. In headless mode checkpoints are off by default; you can pass `--checkpoints=true` to record snapshots as an audit trail, but you can't restore from them without the interactive UI. See [Sessions & Checkpoints](#sessions).
+
+### How does CODA behave in a monorepo?
+
+It loads exactly one `AGENTS.md` — the one in the directory you launch it from. There's no upward walk or merging. Launch from the package you're working in (`cd packages/billing && coda`). See [Collaborate with Your Team](#guide-collaborate).
+
+## See also
+
+- [Glossary](#glossary) — definitions for every term used in these answers.
+- [Commands & Flags](#cli-reference) — the complete command and flag reference.
+- [Configuration](#configuration) — where settings live and how they cascade.

package/assets/docs/glossary.md

@@ -0,0 +1,41 @@
+# Glossary
+
+Quick definitions for terms used throughout the docs.
+
+| Term | Definition |
+| --- | --- |
+| **AGENTS.md** | A Markdown file at your project root that CODA reads at the start of every session. Use it to document your project's conventions, quality gates, and constraints for the agent. |
+| **Agent** | In CODA, an agent is a Markdown-defined profile that describes a specialist persona. CODA can delegate subtasks to agents, running them in parallel for complex work. |
+| **Batch mode** | Headless, non-interactive mode. Run with `coda -p "prompt"`. No TUI, no multi-turn conversation — use in scripts and CI. |
+| **Checkpoint** | A file snapshot taken before each turn — the state from before CODA acts on the message you just sent. Restored via `/timeline` or `/rewind`; your project's Git history is untouched. |
+| **CLI** | The `coda` command-line tool. It runs in two modes: interactive (the TUI) and headless (batch). |
+| **coda-help** | A built-in agent that answers questions about how to use CODA by searching the local user guide. CODA delegates to it automatically when you ask about itself. |
+| **Compaction** | Automatic condensing of older conversation history to free up context window space. Triggered at a configurable fill threshold. |
+| **Extension** | A TypeScript module that registers custom tools, slash commands, or lifecycle hooks into CODA. |
+| **Glob.AI OS** | Globant's internal AI gateway — the primary provider for CODA at Globant. |
+| **MCP** | Model Context Protocol. A standard for connecting AI models to external tools and services. CODA uses MCP servers to talk to GitHub, databases, CI systems, and other integrations. |
+| **MEMORY.md** | Durable notes the agent keeps across sessions — preferences, decisions, and gotchas it learns. Unlike AGENTS.md (which you write), CODA maintains this itself, and it survives checkpoint rollbacks. |
+| **Plugin** | A versioned, installable package that can bundle skills, agents, extensions, and MCP fragments. More structured than an extension; installable via `coda plugin install`. |
+| **Provider** | The AI backend CODA sends prompts to — for example a Glob.AI OS instance, a local Ollama server, or any OpenAI-compatible endpoint. Managed with `/providers`. |
+| **Session** | A persistent CODA conversation. Stored on disk; resumable at any time. |
+| **Skill** | A Markdown file that encodes a repeatable workflow. Invoked with a slash command like `/skill-name`. |
+| **TUI** | Terminal User Interface — the full-screen interface you see when you run `coda` interactively. |
+| **Workflow** | A deterministic script that orchestrates multiple agents — parallel fan-out, multi-stage pipelines, and loops. Authored by the built-in `create-workflow` agent, stored in `.coda/workflows/`, run in the background, and monitored with `/workflows`. |
+| **ACP** | Agent Client Protocol — the integration that lets editors like Zed and JetBrains drive CODA. |
+| **Anti-clobber guard** | The safety check that makes CODA ask before overwriting a file it never read during the current session. |
+| **Approval level** | See *Bash approval level*. The tier (`safe`/`low`/`medium`/`high`) that decides which shell commands run without asking. |
+| **Bash approval level** | The setting (`safe`, `low`, `medium`, `high`) controlling how many shell commands CODA auto-approves. Set from `/settings` → Bash Tool Preferences. |
+| **`.codaignore`** | A gitignore-syntax file at your project root with glob patterns (and optional `!negation` lines) to exclude from — or forcibly include in — checkpoints. Shares `.gitignore` semantics, so patterns, directory globs, and negations all work. |
+| **Context window** | The amount of conversation CODA can hold at once. The status-bar percentage shows how full it is; compaction frees room as it fills. |
+| **Drift** | Uncaptured changes in your worktree at restore time. CODA stops the restore so you don't lose work; press **F** to force it. |
+| **`fastModel`** | The model the literal `model: "fast"` shortcut resolves to, used for cheap, high-volume agent runs. Can be configured per-provider (`providers.<key>.fastModel`) or globally under `agents.fastModel`; CODA also supplies a built-in Glob.AI OS fallback when neither is set. |
+| **`smartModel`** | The model the literal `model: "smart"` shortcut resolves to — the balanced mid-tier for agent runs. Configured under `agents.smartModel` or per-provider. |
+| **`deepModel`** | The model the literal `model: "deep"` shortcut resolves to — the highest-capability, most expensive tier. Configured under `agents.deepModel` or per-provider. |
+| **HITL** | Human-in-the-loop — the approval model where CODA pauses to ask before risky actions. |
+| **Headless mode** | See *Batch mode*. |
+| **Marketplace** | The catalog of installable plugins, reachable from the `/plugin` manager; Claude Code-ecosystem compatible. |
+| **Redaction** | The always-on scrubbing of secret-looking keys and values from logs before they're written to disk. |
+| **ripgrep / fastgrep** | The two content-search backends behind the `grep` tool. ripgrep ships bundled and is the default. |
+| **Shadow repository** | The private Git repo where checkpoints are stored, separate from your project's own `.git`. Located at `~/.coda/checkpoints/<hash>/` by default (one per project, keyed by a SHA-256 of the project path). The base directory can be relocated via `CODA_HOME`. |
+| **Steering / Queuing** | What happens when you send a message mid-turn: *queue* delivers it as the next turn (default); *steer* injects it into the run in progress. Set under `/settings` → Composer. |
+| **Timeline** | The `/timeline` (alias `/rewind`) picker for viewing and restoring checkpoints. |

package/assets/docs/guide-automate.md

@@ -0,0 +1,135 @@
+# Automate with Batch Mode
+
+Batch mode (also called headless mode) lets you run CODA from a shell script or CI pipeline — no terminal UI, no interaction. You give it a prompt, it runs, and it exits. This is how you integrate CODA into automated workflows.
+
+## When to use batch mode
+
+- Running CODA as a step in a CI pipeline (generate docs, run a code review, apply a linting fix)
+- Scripting repetitive tasks across multiple repos
+- Triggering CODA from a webhook or external event
+- Running a long analysis job and checking the result later
+
+For day-to-day coding where you want to review changes as they happen, use the [interactive TUI](#cli-vs-batch) instead.
+
+## Basic usage
+
+The simplest batch run: pass a prompt with `-p`.
+
+```bash
+cd /path/to/project
+coda -p "Summarize what this repo does in five bullet points"
+```
+
+CODA runs, prints the result, and exits. No UI, no interaction.
+
+## Practical examples
+
+**Generate a changelog from recent commits**
+
+```bash
+coda -p "Look at the last 20 git commits and write a CHANGELOG entry for this week's changes."
+```
+
+**Check for security issues before merging**
+
+```bash
+coda -p "Review the changes in this PR for potential security issues. Focus on input validation, SQL queries, and authentication checks."
+```
+
+**Run from a prompt file**
+
+For longer or more structured prompts, put the prompt in a file:
+
+```bash
+coda --prompt-file ./scripts/review-prompt.txt
+```
+
+**Use in a CI pipeline**
+
+```bash
+#!/bin/bash
+coda -p "Run the test suite and report any failures" \
+     --auto-approve all \
+     --output json \
+     --timeout 600000
+
+EXIT=$?
+if [ $EXIT -ne 0 ]; then
+  echo "CODA run failed with exit code $EXIT"
+  exit $EXIT
+fi
+```
+
+## Important flags for automation
+
+| Flag | What it does |
+| --- | --- |
+| `-p` / `--prompt "…"` | The prompt to run |
+| `--prompt-file` / `-pf path` | Read the prompt from a file |
+| `--output text\|json` | Output format. `json` emits newline-delimited events — ideal for parsing in a pipeline |
+| `--auto-approve all\|none` | How to handle approval prompts headlessly. `all` approves everything (needed in CI); `none` denies and aborts on the first request |
+| `--timeout ms` | Abort after N milliseconds. Default `0` = no limit. |
+| `--bash-security lvl` | Override the bash auto-approve level for this run (`safe`, `low`, `medium`, `high`). Affects which shell commands auto-run without a prompt. |
+| `--lastsession` | Resume the most recent session for this project (mutually exclusive with `--session-id`). |
+| `--tools default\|all\|*list*` | Limit available tools, e.g. `read,glob,grep` for a read-only run |
+| `--model` / `-m id` | Override the model for this run |
+| `--session-id` / `-s id` | Resume or create a session with a specific id |
+| `--checkpoints=true` | Enable file snapshots (off by default in headless runs) |
+| `--profile id` | Use a specific persisted profile for this run (read-only; doesn't change your saved `activeProfile`) |
+| `--provider name` | Ephemeral run provider: `glob-ai`, `openai-compat`, or `ollama` (default `glob-ai`) |
+| `--instance id` | Glob.AI OS instance for an ephemeral run (`clients`, `corp`, `saas-europe`; default `saas-europe`) |
+| `--base-url url` | Base URL for an ephemeral `openai-compat` / `ollama` run |
+| `--api-key key` | Ephemeral, run-only API key — held in memory, never persisted, redacted in logs |
+
+> **Approvals in CI.** In headless mode `--auto-approve` defaults to `all`, so CODA runs without stopping for prompts. Pass `--auto-approve none` if you instead want it to refuse anything that would need approval and abort on the first such request. For finer control over which shell commands run, also set `bash.autoApproveLevel` in `config.json` (it defaults to `high` in headless mode).
+
+## Authenticating in batch mode
+
+A batch run needs credentials just like an interactive one, but there's no wizard and no browser. There are three ways it finds them, in order of precedence:
+
+1. **Ephemeral flags (one-off)** — pass credentials inline for a single run: `--provider`, `--instance`, `--base-url`, `--api-key`. CODA builds a run-only profile; the key is kept in memory and never written to disk. Examples:
+
+   ```bash
+   # OpenAI-compatible endpoint, key from an environment variable
+   coda -p "Review this diff" --provider openai-compat \
+     --base-url https://api.example.com/v1 --api-key "$MY_API_KEY"
+
+   # Glob.AI OS Clients instance with an API key
+   coda -p "Summarize the changes" --provider glob-ai \
+     --instance clients --api-key "$CODA_GEAI_CLIENTS_API_KEY"
+   ```
+
+2. **A named profile** — `--profile <id>` reuses a profile you already configured in the TUI, **including its stored OAuth session**. This is the recommended way to use OAuth in CI: sign in once interactively with `/providers`, then reference that profile from your pipeline.
+
+3. **The active profile** — with no provider flags at all, the run uses `activeProfile` from `~/.coda/config.json` (the same profile the TUI would open with).
+
+> **OAuth can't be *started* headlessly.** The interactive browser sign-in only works in the TUI. For OAuth in batch mode, authenticate once interactively and then reuse that profile (`--profile <id>` or the active profile). Passing `--api-key` to a `glob-ai` run uses key-based auth instead, which needs no browser.
+
+## Reading the output
+
+With `--output text` (the default), CODA prints its final answer to stdout. With `--output json`, it emits **newline-delimited JSON events** — one object per line — so a pipeline can parse progress and the final result. Successful runs emit a `{ type: "agent_response", payload: { status: "ok", response: "..." } }` event; failures emit `{ type: "headless_error", payload: { ... } }`. Pair it with `jq` in a script:
+
+```bash
+coda -p "Summarize the open TODOs in this repo" --output json \
+  | jq -r 'select(.type=="agent_response") | .payload.response'
+```
+
+Always check the **exit code**: a non-zero status means the run failed (an error, a timeout, or — with `--auto-approve none` — a denied approval), so your CI step can fail fast.
+
+## Scope it down for safety
+
+Unattended runs are safest when you limit what the agent can touch:
+
+- **Restrict tools** with `--tools` — e.g. `--tools read,glob,grep` for a read-only review that can't edit or run commands.
+- **Tune bash** with `--bash-security` (or `bash.autoApproveLevel` in config) so even an auto-approved run won't run beyond the tier you set.
+- **Cap runtime** with `--timeout` so a stuck run can't hang the pipeline.
+
+## What batch mode can't do
+
+Batch mode runs a single turn — one prompt, one response. It doesn't support multi-turn conversation or interactive review. The `ask_user` tool isn't available (there's no one to answer), and there's no `/timeline` to roll back from — pass `--checkpoints=true` only if you want snapshots recorded for an audit trail. For tasks that require back-and-forth, use the [interactive TUI](#cli-vs-batch).
+
+## See also
+
+- [Interactive vs Headless](#cli-vs-batch) — choosing between the two modes.
+- [Commands & Flags](#cli-reference) — the complete flag and subcommand reference.
+- [Permissions & Approvals](#permissions) — how approvals behave when no one is watching.