@globant/coda-windows-x64 1.0.0

package/assets/docs/how-it-works.md

@@ -0,0 +1,73 @@
+# How CODA Works
+
+Understanding what CODA does under the hood helps you use it more effectively — and troubleshoot it when it behaves unexpectedly.
+
+## Tools: what CODA can do
+
+CODA doesn't just generate text. It has tools it can call to actually interact with your system:
+
+| Tool | What it does |
+| --- | --- |
+| File read/write | Read any file in your project; write or patch files to make changes |
+| Shell | Run shell commands — tests, linters, build scripts, git operations |
+| Search | Search for patterns across your codebase, faster than reading every file |
+| MCP tools | Tools exposed by connected MCP servers (GitHub, databases, internal APIs) |
+| Skills | Invoke a skill you or your team has defined |
+| Sub-agents | Delegate a subtask to another CODA instance running in parallel |
+
+CODA picks which tools to use automatically based on the task. You don't need to tell it "use the search tool now" — it figures that out. For the full list of built-in tools and what you can configure about each, see [Tools Reference](#tools-reference).
+
+## The agent loop
+
+Each turn runs a loop: CODA reads your message, decides on the next action, calls one or more tools, observes the results, and repeats — until the task is done or it needs your input. A few properties of this loop are worth knowing:
+
+- **It pauses for approval** before risky actions (shell commands above your level, overwriting an unread file). See [Permissions & Approvals](#permissions).
+- **It has a step budget.** A single turn is capped at a maximum number of loop steps (`maxSteps`, default 300) so a runaway turn can't loop forever. You'll rarely hit this in normal use.
+- **You can interrupt it.** Press **Esc** to stop the loop mid-turn and redirect.
+- **It can delegate.** For big or parallelizable work, the loop can spawn child [agents](#agents) or a [workflow](#workflows) instead of doing everything inline.
+
+## Memory: what CODA knows
+
+CODA draws on a few different kinds of memory:
+
+**In-session context** — everything you've said and everything CODA has read or done in the current session. This builds up as the session progresses, which is why later turns in a session are often better than earlier ones — CODA has more context.
+
+**AGENTS.md (instructions you give)** — project-specific instructions injected at the start of every session. This is how *you* tell CODA about your project's conventions, quality gates, and constraints.
+
+**MEMORY.md (facts CODA learns)** — durable notes the agent keeps across sessions: your preferences, decisions, and project gotchas. Unlike AGENTS.md, CODA writes this one itself as it learns. It even survives checkpoint rollbacks — restoring an earlier point never erases what CODA has remembered.
+
+**The file system** — CODA always reads your actual files live from disk, not from a cached index. So it works with what's currently there, not a stale snapshot.
+
+The two files you control directly play different roles:
+
+| | `AGENTS.md` | `MEMORY.md` |
+| --- | --- | --- |
+| **Who writes it** | You (or `/init`) | CODA, as it learns |
+| **What goes in it** | Project conventions, quality gates, no-go zones | Preferences, decisions, gotchas |
+| **Scope** | The project where it lives | Global (`~/.coda/`) and per-project |
+| **Survives rollback?** | It's your file — yes | Yes, excluded from checkpoints on purpose |
+| **Commit to Git?** | Yes — share with the team | Usually no — it's agent scratch memory |
+
+## Compaction: keeping context fresh
+
+Long sessions accumulate a lot of history. Once the conversation reaches a certain size, CODA automatically condenses older messages into a summary (compaction) while keeping recent messages verbatim. This keeps the session running smoothly without losing important context.
+
+You can also trigger compaction manually before switching topics:
+
+```text
+/compact
+```
+
+If you'd rather control when this happens — for example while debugging a problem where CODA seems to "forget" something — open `/settings` → **Context Compaction** to disable automatic compaction or adjust when it kicks in. See [Configuration](#configuration) for details.
+
+## Error recovery: handling provider hiccups
+
+Model calls don't always succeed — providers rate-limit, time out, or return transient errors. CODA recovers automatically instead of just failing the turn:
+
+- **Classifies the failure** from the provider's signals (rate limit, transient service error, auth, content policy, context-length, quota).
+- **Retries with guidance** when the model can fix it — for example, telling it exactly which tool arguments were wrong — and **backs off with jitter** (honoring any `Retry-After`) within a bounded per-turn budget.
+- **Continues a truncated answer** that hit the output-length cap, resuming where it stopped.
+- **Fails over** to your configured `fallback` model when a provider keeps failing, with a circuit breaker so it stops hammering a service that's down.
+- **Escalates immediately** for problems retrying can't fix — auth failures, content-policy blocks, hard quota/billing limits, and model-unavailable errors (when the model has been removed or renamed on the provider) — surfacing a clear classified message.
+
+In the TUI you'll see a live row like `↻ Backing off… / Failing over… / Continuing…` while this happens. You can tune how aggressively CODA retries with `errorHandling.posture` (`conservative` / `balanced` / `aggressive`) and set `fallback.enabled: true` along with `fallback.provider` (and optionally `fallback.model`) to opt in to failover — see [Configuration Reference](#config-reference).

package/assets/docs/index.md

@@ -0,0 +1,62 @@
+# CODA User Guide
+
+**CODA** (`coda`) is Globant's AI coding agent. You describe what you want in plain language; CODA reads your codebase, plans the work, makes changes, and runs commands — while you stay in control of every step.
+
+This guide is the authoritative reference for using CODA. Every page is a Markdown file under `~/.coda/docs/`, synced from the version of CODA you have installed. Cross-links use `#page-name` anchors that map directly to the file of the same name (for example, `#config-reference` → `config-reference.md`).
+
+## Where to start
+
+If you are brand new, read these in order:
+
+1. [What is CODA?](#overview) — the big picture and what you can do with it.
+2. [Installation](#installation) — get `coda` running on your machine.
+3. [Connect a Provider](#connect-provider) — choose Glob.AI OS (recommended for Globant employees) or a custom OpenAI-compatible / Ollama endpoint, and authenticate.
+4. [Quick Start](#quickstart) — open CODA in a real project and run your first prompt.
+
+## Table of contents
+
+### Getting started
+
+- [What is CODA?](#overview) — overview, the two run modes, and what a session looks like.
+- [Installation](#installation) — requirements, install script vs npm, and upgrading.
+- [Connect a Provider](#connect-provider) — the first-run setup wizard, OAuth vs API key, custom providers.
+- [Quick Start](#quickstart) — your first session in under five minutes.
+- [How CODA Works](#how-it-works) — tools, memory, and compaction under the hood.
+
+### Everyday use
+
+- [Interactive vs Headless](#cli-vs-batch) — when to use the TUI and when to use batch mode.
+- [Commands & Flags](#cli-reference) — every slash command and shell flag.
+- [Keyboard Shortcuts](#shortcuts) — TUI key bindings.
+- [Tools Reference](#tools-reference) — the built-in tools the agent can call.
+- [Permissions & Approvals](#permissions) — the human-in-the-loop model and bash approval levels.
+- [Sessions & Checkpoints](#sessions) — resuming work and undoing changes.
+
+### Task guides
+
+- [Understand a Codebase](#guide-understand) — exploration prompts and tips.
+- [Make Changes Safely](#guide-changes) — checkpoints, approvals, and undo workflows.
+- [Collaborate with Your Team](#guide-collaborate) — `AGENTS.md`, shared skills, and what to commit.
+- [Automate with Batch Mode](#guide-automate) — scripting and CI.
+
+### Extending CODA
+
+- [Extend CODA](#guide-extend) — the high-level map of MCP, skills, extensions, plugins, and workflows.
+- [Agents](#agents) — delegate a task to a child CODA session.
+- [Workflows](#workflows) — orchestrate many agents at once.
+- [Writing Extensions](#extensions) — the extension API reference.
+- [Lifecycle Hooks](#hooks) — shell/HTTP hooks that fire at session, tool, and prompt events.
+
+### Operations & reference
+
+- [Configuration](#configuration) — how settings cascade and where they live.
+- [Configuration Reference](#config-reference) — config keys, defaults, and environment variables.
+- [config.json — A Complete Example](#config-json) — a full, annotated `config.json` you can copy from.
+- [View & Share Logs](#logging) — `coda logs`, redaction, and support bundles.
+- [FAQ](#faq) — short answers to common questions.
+- [Glossary](#glossary) — definitions for the terms used throughout.
+- [Release History](#release-history) — notable changes by version.
+
+## A note on safety
+
+CODA is built to be safe on real codebases. It asks before doing anything risky (see [Permissions & Approvals](#permissions)), snapshots your files before every turn so you can roll back (see [Sessions & Checkpoints](#sessions)), and never touches your project's own Git history. If you only remember one thing: when CODA heads the wrong way, press **Esc** to interrupt, then redirect — that is faster than undoing a pile of changes.

package/assets/docs/installation.md

@@ -0,0 +1,71 @@
+# Installation
+
+## Requirements
+
+- **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.
+- **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
+
+The recommended way to install CODA is the install script — it has **no dependencies** (it just runs the commands below), so everyone can use it.
+
+**macOS & Linux**
+
+```bash
+curl -fsSL https://docs.globant.ai/en/filedownload?4622,12 | bash
+```
+
+**Windows (PowerShell 7)**
+
+```powershell
+irm 'https://docs.globant.ai/en/filedownload?5346,6' | iex
+```
+
+Alternatively, you can install via **npm**. Note this requires Node.js, whereas the install script above does not:
+
+```bash
+npm i -g @globant/coda
+```
+
+Once installed, confirm it's working:
+
+```bash
+coda --version
+```
+
+You should see a version string like `1.2.3`. If you see a "command not found" error, something went wrong with the install path — check the [FAQ](#faq).
+
+## Where CODA installs
+
+Knowing the layout helps when you troubleshoot:
+
+- **The install script** places a native binary under `~/.coda/bin/` and ensures that directory is on your `PATH` (it appends a line to your shell profile, e.g. `~/.zshrc` or `~/.bashrc`).
+- **npm** installs the `coda` command into your global npm bin directory (run `npm prefix -g` and look under the resulting path's `bin/` subdirectory to see where that is).
+- Either way, your config, credentials, sessions, logs, and checkpoints live under `~/.coda/` (override the location with the `CODA_HOME` environment variable or the `--coda-home <path>` CLI flag — see [Configuration Reference](#config-reference)).
+
+## 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:
+
+- **Installed via npm** → it upgrades through npm.
+- **Installed via the script** → it swaps in the latest native binary under `~/.coda/bin`.
+
+You can see what changed between versions in [Release History](#release-history).
+
+## Troubleshooting the install
+
+**`coda: command not found`** — the install directory isn't on your `PATH` yet. Open a new terminal (so it re-reads your shell profile), or add `~/.coda/bin` to your `PATH` manually. For npm installs, confirm your global npm bin directory is on `PATH`.
+
+**The script install fails behind a proxy or strict firewall** — the script downloads a binary over HTTPS. If your network blocks it, use the npm install instead (`npm i -g @globant/coda`), which goes through your configured npm registry. Alternatively, set the `CODA_NPM_REGISTRY` environment variable to point `coda upgrade` at an internal registry mirror — this works with the native binary install and does not require Node.js.
+
+**Permission errors with npm** — a global npm install may need elevated permissions, or a per-user npm prefix. Prefer the install script if you'd rather avoid Node.js and npm entirely.
+
+**Checkpoints say they're disabled at startup** — that's a Git version issue, not an install problem. Checkpoints need **Git 2.5.0+**; see [Sessions & Checkpoints](#sessions).
+
+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.

package/assets/docs/logging.md

@@ -0,0 +1,123 @@
+# View & Share Logs
+
+CODA writes structured logs to disk so you can troubleshoot what happened in a session — and share a safe, redacted bundle with support when you need help. Secrets are scrubbed *before* anything is written, so logs are safe to read and share.
+
+## What you get
+
+- **`coda logs`** — a full-screen log viewer in your terminal, or a plain text / JSON stream when piped.
+- **Filtering** by level, service, and time, plus a live `--follow` tail.
+- **Secret redaction at the source** — tokens, keys, passwords, email addresses, and `Bearer`/`sk-`/`ghp_`-style values never reach disk.
+- **`coda logs export`** — a local, redacted, path-scrubbed bundle for support (nothing is ever uploaded).
+- **Per-service log levels** so you can turn up detail only where you need it.
+- **`coda logs-demo`** — a few-second self-test of the whole logging pipeline.
+
+## Viewing logs
+
+```bash
+coda logs              # interactive viewer (in a terminal)
+coda logs | less       # plain text stream (when piped)
+coda logs --json       # raw JSON lines
+coda logs --follow     # tail new entries live
+```
+
+In an interactive terminal, `coda logs` opens a full-screen viewer with aligned `TIME LEVEL SERVICE MESSAGE` columns. Only `warn` and `error` rows are colored, so problems stand out.
+
+| Key | Action |
+| --- | --- |
+| **↑ / ↓** or **j / k** | Move the selection |
+| **PageUp / PageDown** | Jump by a page |
+| **g / G** | Jump to the oldest / newest entry |
+| **Space / Enter** | Expand the selected row's full record (every field and stack trace) |
+| **c** or **Ctrl+C** | Copy the selected entry's JSON to the clipboard |
+| **q / Esc** | Quit |
+
+When piped or non-interactive, the same window streams as one entry per line (or `--json` for raw lines, `--plain` to disable color), so `grep` and `less` work as usual.
+
+## Filtering
+
+All filters work in both the viewer and the stream:
+
+| Flag | What it does |
+| --- | --- |
+| `--level <name>` | Minimum severity: `trace`, `debug`, `info`, `warn`, `error`, `fatal` |
+| `--service <prefix>` | Only entries whose service starts with the prefix (e.g. `core.agent`, `core.tools`) |
+| `--since <when>` | Only newer than `30s`, `30m`, `2h`, `1d`, or an ISO-8601 timestamp |
+| `--lines <N>` (`-n`) | Window size (default 2000) |
+| `--follow` (`-f`) | Keep streaming new entries (Ctrl-C to stop) |
+
+## Where logs live
+
+Logs are stored under `~/.coda/logs/` (relocatable with `CODA_HOME`). The live file is `coda.log`; on rotation it shifts to a numbered file (`coda.log.1` … `coda.log.7`). Logs rotate **daily and at 50 MB**, keeping the **7 most recent** files. `coda logs` reads across all of them automatically, newest first. Each line is one JSON object: an ISO-8601 `time`, a `level`, the `service` name, the `msg`, and any structured fields.
+
+## Secrets never hit disk
+
+Every entry is scrubbed as it's written:
+
+- **Secret-looking keys** (`authorization`, `token`, `apiKey`, `secret`, `password`, `cookie`, `username`, `email`, …) have their value replaced with `[REDACTED]`.
+- **Secret-looking values** anywhere in a string (`Bearer …`, `sk-…`, `ghp_` / `gho_` / `ghs_` / `ghr_` / `ghu_` / `github_pat_…`, `AKIA…`, JWTs, private-key blocks, and email addresses) are scrubbed — even inside a longer message like a shell command.
+- Counters like token usage are kept; only *string* secrets are masked.
+
+Built-in redaction is always on and can't be disabled. To **add** rules (extra deny-keys, key substrings, or value patterns), set `logging.redact` in your config — they merge on top of the built-ins.
+
+## Log levels
+
+You can control per-service detail two ways. The `LOG_LEVEL` environment variable wins over config for the same service.
+
+- **Persistent** — in your config: `logging.level` (global default) and `logging.levels` (per service).
+- **Ad-hoc** — the `LOG_LEVEL` env var (Rust-style; a bare token sets the global floor):
+
+```bash
+LOG_LEVEL=info,core.agent.step:debug,core.tools:warn coda
+```
+
+By default, `info` carries lifecycle events (a turn starting and finishing); per-operation detail (each agent step, tool call, and file op) is `debug`. A per-service entry always beats the global default.
+
+## The viewer gate
+
+Raw log viewing is controlled by `logging.rawViewer.enabled`. Left unset, it defaults **on during development and off in a shipped release build**. When it's off, `coda logs` declines and points you at the export below (which is never gated). Redaction protects secrets either way — the gate just keeps raw logs from being browsed casually in a release.
+
+## Sharing logs with support
+
+```text
+coda logs export [--since … | --lines … | --keep-paths]
+```
+
+This writes a **local, redacted** bundle to `~/.coda/exports/` and prints the path — **nothing is uploaded**. Each entry is redacted a second time (also catching logs written by an older version), and absolute paths are rewritten so your username and home directory don't leak (`--keep-paths` opts out). The bundle records the CODA version, OS/arch, and session/turn ids — no identity. Review the file, then share it.
+
+## Self-test
+
+```text
+coda logs-demo
+```
+
+Runs the whole pipeline end to end (build redacted entries → read → render → filter → export) against a throwaway directory and prints **PASS** / **FAIL** in a few seconds — a quick way to confirm logging works after an install or upgrade.
+
+## Troubleshooting with logs
+
+A few recipes for common situations:
+
+```bash
+# What just went wrong? Tail errors live while you reproduce it.
+coda logs --level error --follow
+
+# Zoom in on the agent loop for the last 15 minutes.
+coda logs --service core.agent --since 15m
+
+# Turn up detail for one subsystem without flooding everything else.
+LOG_LEVEL=info,core.tools:debug coda
+```
+
+When you can't tell what happened from the rendered view, press **Space**/**Enter** on a row to expand its full JSON record — including any stack trace and structured fields.
+
+## Sending a bundle to support — checklist
+
+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.
+
+## See also
+
+- [Commands & Flags](#cli-reference) — the full command and flag reference.
+- [Configuration](#configuration) — where the `logging.*` settings live.
+- [Configuration Reference](#config-reference) — the `logging.*` keys and `LOG_LEVEL` syntax.

package/assets/docs/overview.md

@@ -0,0 +1,91 @@
+# What is CODA?
+
+**CODA** (`coda`) is Globant's AI coding agent. You describe what you want to accomplish in plain language — CODA reads your codebase, figures out what needs to change, and gets it done, while you stay in control of every step.
+
+Unlike a chat window that only suggests code, CODA is an *agent*: it can read and write files, run shell commands, search your repository, call connected services, and delegate subtasks — all in your actual working directory, with your approval where it matters.
+
+## What you can do with CODA
+
+**Explore an unfamiliar codebase** — ask CODA to explain how authentication works, trace where a bug might be coming from, or map out the dependencies of a module before you touch anything. Because CODA reads your files live from disk, it answers from the real state of the repo, not a stale index. See [Understand a Codebase](#guide-understand).
+
+**Make changes with a safety net** — CODA snapshots your files before every turn (checkpoints). If something goes wrong, you can roll back to any previous state with a single command, and your project's own Git history is never touched. See [Make Changes Safely](#guide-changes) and [Sessions & Checkpoints](#sessions).
+
+**Automate repetitive work** — run CODA headlessly in scripts and CI pipelines. Feed it a prompt, let it work, and check the result — no terminal UI needed. See [Automate with Batch Mode](#guide-automate).
+
+**Extend it for your team** — connect MCP servers, write custom skills, create shared `AGENTS.md` files, package integrations as plugins, and drop TypeScript *extensions* into `.coda/extensions/` to register custom tools, slash commands, and lifecycle hooks — so every developer on the project works with the same conventions baked in. See [Extend CODA](#guide-extend) and [Collaborate with Your Team](#guide-collaborate).
+
+**Scale up with delegation** — when a job is bigger than a single conversation, CODA can spin up [agents](#agents) (child sessions that work in parallel) or run [workflows](#workflows) that orchestrate many agents in fan-out, pipelines, and loops.
+
+## How a session looks
+
+A session is a back-and-forth loop. You set the goal; CODA does the work and checks in with you at the points that matter.
+
+| You | CODA |
+| --- | --- |
+| Describe the goal in plain language | Reads files, plans the approach |
+| 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.
+
+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).
+
+## 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.
+
+**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.
+
+**Editor (ACP)** — start CODA with `--acp` to expose it over stdio as an Agent Communication Protocol server, used by IDE plugins (Zed, JetBrains) to drive CODA from inside your editor.
+
+Both share the same agent, the same configuration, and the same tools — the difference is the interface and a few safety defaults (headless runs are more autonomous because there is no one to answer an approval prompt). See [Interactive vs Headless](#cli-vs-batch) for a side-by-side comparison.
+
+## 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).
+- **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).
+- **Your Git history** — checkpoints use a separate private shadow repository, so `git log`, branches, and commits are entirely yours.
+
+## When to reach for CODA (and when not to)
+
+CODA shines when a task touches **real files in a real repository** and benefits from reading, searching, editing, and running commands in a loop:
+
+- Onboarding to an unfamiliar codebase and asking how things fit together.
+- Implementing a feature or fix that spans several files, with tests run as you go.
+- Reviewing a pull request, diagnosing a bug report, or auditing for code smells.
+- Repetitive, scriptable chores — changelogs, doc generation, batch refactors — run headlessly in CI.
+
+It is *not* the right tool for everything. For a one-line syntax question with no repo context, a plain chat assistant is faster. For changes you are not ready to review, prefer exploration prompts ("explain, don't change") until you trust the plan.
+
+## The agent loop, step by step
+
+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 above your approval level, or overwriting a file it never read). You answer with a single key.
+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.
+
+## What a session accumulates
+
+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.
+- **`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.
+
+## 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.
+3. [Quick Start](#quickstart) — open CODA in a real project and run your first prompt.
+4. [Configuration](#configuration) — connect your provider and tune settings.
+
+New to the terminology? The [Glossary](#glossary) defines every term used across this guide.

package/assets/docs/permissions.md

@@ -0,0 +1,93 @@
+# Permissions & Approvals
+
+CODA can read files, run shell commands, and edit your code — but it asks before doing anything risky. 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.
+
+## 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:
+
+- **Y** — allow this action and continue.
+- **N** — skip 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**.
+
+How often CODA stops to ask depends on your settings. The goal is to auto-approve the safe, routine things (reading files, listing directories) and pause on the things that write, delete, or reach outside your project.
+
+## Bash approval levels
+
+The most common approval control is the **bash approval level** — it decides how many shell commands CODA can run without asking. Set it from `/settings` → **Bash Tool Preferences**:
+
+| Level | What it auto-approves |
+| --- | --- |
+| `safe` | Read-only commands only (`ls`, `cat`, `git status`) |
+| `low` | Safe commands plus low-risk writes — **default** |
+| `medium` | Most file operations and git commits |
+| `high` | Everything except clearly destructive operations (`rm -rf`, disk formatting) |
+
+Even at `high`, commands that match CODA's blocked patterns still require explicit approval. Lowering the level is the safest choice when you're working in an unfamiliar or sensitive repo.
+
+**Which level should I pick?**
+
+- `safe` — auditing or read-only review, or any repo you don't fully trust yet.
+- `low` (default) — everyday development; CODA runs safe reads and low-risk writes (creating files, package installs, `git add`/`commit`) but asks before anything that moves or deletes.
+- `medium` — you're moving fast in a repo you know and are comfortable auto-approving `mv`/`rm`, `git push`/`reset`, and permission changes.
+- `high` — trusted, recoverable environments where you want minimal interruptions; still stops on clearly destructive commands.
+
+**What is never auto-approved.** Regardless of level, commands matching CODA's blocked patterns — things like `rm -rf /`, disk formatting, or piping a remote script straight into a shell — always require an explicit **Y**. The approval level controls the *gray area*; the hard-block list is not negotiable by config.
+
+## Choosing the shell
+
+CODA runs bash commands through a shell you can pick from the same `/settings` → **Bash Tool Preferences** screen. The **shell mode** can be `auto` (let CODA detect the best option), or you can pin it to `bash`, `powershell`, or `wsl` — handy on Windows where the default isn't always what you want.
+
+## Other actions that ask first
+
+Bash isn't the only thing gated by approvals. CODA also pauses before:
+
+- **Overwriting a file it never read this session** — an anti-clobber guard. If CODA didn't read a file before writing to it, it asks first so it can't silently clobber work it hasn't seen.
+- **Consolidating memory** — when CODA rewrites its `MEMORY.md` notes, it asks before replacing them.
+- **MCP and other tools** — external tools you've connected may run their own approval logic; CODA always routes them through your MCP configuration.
+
+## Approvals in headless (batch) mode
+
+Headless runs can't show you a prompt, so the rules are stricter and more autonomous by design:
+
+- The **`ask_user`** tool isn't available — there's no one to answer.
+- Bash defaults to a higher auto-approval tier so scripts don't hang waiting on input.
+
+You control this from the command line when you launch a batch run:
+
+```bash
+# Set the bash approval level for this run
+coda -p "Run the test suite and report failures" --bash-security high
+
+# Auto-approve everything for a fully unattended run (this is the default when --auto-approve is omitted)
+coda -p "Format the codebase" --auto-approve all
+
+# Block all HITL requests — run fails immediately if any approval is needed
+coda -p "Run the test suite and report failures" --auto-approve none
+```
+
+When `--auto-approve` is omitted, headless runs default to `all`, meaning every HITL request is auto-approved. Pass `--auto-approve none` to do the opposite: any pending approval request immediately aborts the run with an error — useful for CI pipelines where silent auto-approval is unacceptable.
+
+Use a high auto-approval tier only when you trust the prompt and the repo — an unattended run with `--auto-approve all` will not stop to ask, even for destructive commands.
+
+## Trust and external code
+
+Approvals protect you from CODA's *own* actions. A separate concern is the **code and instructions you load into CODA**: skills, plugins (including marketplace catalogs), MCP servers, extensions, and agent definitions all load text or executable code from disk or packages — and they are **not sandboxed**. A few rules of thumb:
+
+- **Install and enable only from sources you trust.** MCP servers and some extensions can spawn processes and reach the network or filesystem.
+- **The model can read skill text and call any tool you expose** — treat an installed skill or extension like running someone else's code.
+- **Keep approvals on** (don't blanket `--auto-approve all`) when running with untrusted extensions or MCP servers active.
+- **Don't put secrets into prompts or project files** that an untrusted extension could read.
+
+## Where to set it
+
+- **From inside CODA:** `/settings` → **Bash Tool Preferences** (applies globally or per project).
+- **Per project:** project-level config overrides your personal defaults — see [Configuration](#configuration).
+- **For a single run:** the `--bash-security` and `--auto-approve` flags (see [Commands & Flags](#cli-reference)).
+
+## See also
+
+- [Make Changes Safely](#guide-changes) — staying in control while CODA edits code.
+- [How CODA Works](#how-it-works) — tools, memory, and the agent loop.
+- [Configuration](#configuration) — where settings live and how they cascade.

package/assets/docs/quickstart.md

@@ -0,0 +1,104 @@
+# Quick Start
+
+This guide takes you from a fresh CODA install to a real working session in under five minutes. You'll open CODA in a project, connect a provider, and run prompts that actually do something useful.
+
+## 1. Open CODA in your project
+
+Always launch CODA from your project's root directory. That's how it knows what codebase to work with.
+
+```bash
+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).
+
+## 2. Try these prompts
+
+Here are example prompts that work well for a first session. Start with the ones that feel most relevant to you.
+
+**Understand what you're looking at**
+
+```text
+What is the main entry point of this project and how is it structured?
+```
+
+**Create an implementation plan**
+
+```text
+Create a plan to add the X, Y, and Z capabilities to this feature. Don't change files yet — first explain the affected modules, risks, and test strategy.
+```
+
+> CODA also ships with a built-in **`plan`** skill for this workflow. You can ask naturally as above, or invoke it explicitly with `/plan` when you want CODA to focus on requirements analysis and implementation planning.
+
+**Review a pull request**
+
+```text
+Review this PR and summarize the main risks, missing tests, and any code-quality issues: <pull-request-url>
+```
+
+**Diagnose a reported bug**
+
+```text
+Diagnose this bug report and trace the most likely root cause in the codebase: <github-issue-url>
+```
+
+**Search for code smells**
+
+```text
+Search the codebase for code smells around error handling, duplicated logic, and overly large functions. Report findings first; don't edit anything yet.
+```
+
+## 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:
+
+- Press **Y** to approve and continue
+- Press **N** to skip that step
+- Press **Esc** to interrupt the current turn entirely
+
+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
+
+CODA takes a checkpoint (a file snapshot) **before every turn** — that is, before CODA starts acting on the message you just sent. If something goes wrong, restoring that checkpoint takes your files back to the state they were in **right before that message was processed**:
+
+```text
+/timeline
+```
+
+This opens the timeline picker (you can also type `/rewind`, or press **Esc** twice when the chat input is empty). Select any point to restore your files to that state.
+
+> **Tip — give CODA your project's rules.** Run `/init` to generate an `AGENTS.md`: project-specific instructions for the agent (coding conventions, how to run tests, areas to avoid, etc.). It's optional, but it makes CODA follow your team's conventions. Review the file, edit anything it missed, and commit it to Git so the whole team benefits — or write it by hand at any time.
+
+## 5. Keep the session healthy
+
+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.
+- **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.
+
+## A realistic first session
+
+Putting it together, a typical first session looks like:
+
+```text
+You:  What does this service do and where's the entry point?
+CODA: (reads files, explains the structure)
+
+You:  Add input validation to the /signup endpoint. Explain the plan first, don't edit yet.
+CODA: (lists the files it would touch and why)
+
+You:  Looks good — make the changes and run the tests.
+CODA: (edits files, asks to approve the test command, reports results)
+
+You:  /timeline    ← if anything looks wrong, roll back to before that turn
+```
+
+## What's next
+
+- [Understand a Codebase](#guide-understand) — more prompts for exploring unfamiliar code
+- [Make Changes Safely](#guide-changes) — checkpoints, approvals, and how to undo
+- [Configuration](#configuration) — switch providers, tune settings, manage secrets