@globant/coda-windows-x64 1.0.0

package/assets/docs/sessions.md

@@ -0,0 +1,139 @@
+# Sessions & Checkpoints
+
+Every time you run CODA, it creates a session — a persistent record of everything that happened: your prompts, CODA's responses, every file it read, every command it ran. Sessions let you pick up where you left off, and checkpoints let you undo what went wrong.
+
+## Resume where you left off
+
+When you exit CODA (`Ctrl+C` twice or `/exit`), the session is saved. To continue it later:
+
+```bash
+# Resume the last session
+coda --lastsession
+
+# Resume a specific session by ID (-s is a short alias)
+coda --session-id <id>
+coda -s <id>
+```
+
+When you exit, CODA prints the exact command to resume — `coda --session-id <id>` — ready to copy and paste. You can also browse and switch sessions from inside the TUI:
+
+```text
+/sessions
+```
+
+From the `/sessions` manager you can **resume, rename, or delete** any saved session.
+
+> **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.
+
+## Start fresh without losing the old session
+
+To start a new conversation without exiting CODA:
+
+```text
+/new
+```
+
+This opens a new session. The previous session is saved and can be resumed later — nothing is lost.
+
+## Checkpoints: undo at any point
+
+CODA takes a checkpoint (a file snapshot) before each turn — before it acts on the message you just sent. Snapshots are stored in a private shadow repository under `~/.coda/checkpoints/<project-hash>/` (one subdirectory per project, named by a hash of the project directory's absolute path), so your project's own Git history and commits are never touched.
+
+Think of a checkpoint as **"the state from before this message ran."** If a prompt leads CODA in the wrong direction, restore the checkpoint for that turn to return your files to the exact state they had before CODA processed it.
+
+CODA snapshots at a few different moments, and the `/timeline` picker labels each row so you can tell them apart:
+
+| Trigger | When it fires | Picker badge |
+| --- | --- | --- |
+| Per-turn | Before CODA acts on a prompt you sent | `turn` |
+| Pre-destructive-bash | Before a risky shell command (`rm`, `mv`, `sed -i`, `>`, `>>`, `git reset`/`clean`/`checkout`) | `bash` |
+| Pre-restore | Right before a restore — this is what powers the undo stack | `↩ undo` |
+
+A `turn` row rewinds to the state **before** the agent acted on that message. Turns that don't touch any files still get a row (so the conversation has a restore anchor) but reuse the previous snapshot, so they cost no extra disk.
+
+To view and restore checkpoints, open the timeline picker:
+
+```text
+/timeline
+```
+
+You can also type `/rewind` or press **Esc** twice when the chat input is empty. Select any checkpoint to restore your files to that exact state — this is your undo button for anything CODA does to your codebase. Restoring also rewinds the conversation back to that point. (Your chat history isn't altered by editing files; only a restore rewinds it.)
+
+> **Checkpoints require Git 2.5.0+.** If Git is unavailable or too old, checkpoints are disabled automatically and CODA tells you at startup. Checkpoints are a TUI feature: the `/timeline` picker doesn't exist in headless (batch) mode, so there's no way to restore there. They're off by default in batch; you can force snapshots on with `--checkpoints=true` for an audit trail, but you won't be able to roll back without the interactive UI.
+
+### What a snapshot captures (and what it skips)
+
+A checkpoint records your **project worktree files** at that moment — but not everything. CODA always skips build artifacts, caches, and a few protected paths so snapshots stay fast and safe:
+
+`.git`, `.coda/sessions`, `.coda/MEMORY.md`, `.coda/agents`, `.coda/offload`, `.coda/checkpoint-repo`, `node_modules`, `.venv`, `venv`, `dist`, `build`, `.next`, `.turbo`, `__pycache__`, `.pytest_cache`, `.cache`, `target`, `.gradle`, `.mypy_cache`, `.tox`, and similar. On Windows, filesystem-reserved device names (`nul`, `con`, `prn`, `aux`, `com1`–`com9`, `lpt1`–`lpt9`) are also excluded.
+
+Very large directories (more than ~200 files) are skipped too, to keep snapshots fast; `/checkpoint-status` lists any it dropped this way under **Skipped dirs**.
+
+Two things are deliberately protected:
+
+- **`.coda/MEMORY.md`** is excluded at both capture and restore time, so your agent's memory **survives every rollback** intact.
+- **`.git/`** is never touched — your project's own Git history is completely separate.
+
+### Exclude your own paths with `.codaignore`
+
+To keep additional project-local paths out of snapshots, add a `.codaignore` file at your project root. It uses gitignore syntax (including negations), so you can exclude large data folders, generated output, or anything you don't want captured.
+
+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.)
+
+### 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.
+
+You have three ways forward:
+
+- **Esc** — cancel the restore and keep your current files.
+- **F** — force the restore through, discarding the drifted changes (only if you're sure). You can also press `F` directly in the picker list (before drift is detected) to initiate a force-restore immediately without a drift check.
+- **Send a new prompt** — this snapshots the current state as a normal turn, which clears the drift, after which you can restore cleanly.
+
+The top of the picker also has an **Undo your last restore** entry, in case a restore itself went the wrong way. Each restore creates its own pre-restore snapshot, so you can undo an undo repeatedly.
+
+### Verify checkpoints work
+
+After an install or upgrade, you can smoke-test the whole subsystem against a throwaway project:
+
+```bash
+coda checkpoints-demo
+```
+
+It runs through snapshot, restore, undo, drift handling, and memory preservation, then exits in a few seconds — no real session needed.
+
+### When checkpoints turn themselves off
+
+Checkpoints disable **gracefully** for the rest of a session (no crash, just no more snapshots) when any of these happen:
+
+- **Git is missing or older than 2.5.0.**
+- **The worktree exceeds `checkpoints.maxWorktreeFiles`** (default 100,000) — add big folders to `.codaignore` and restart, or raise the cap.
+- **Snapshot disk usage passes the hard cap** (`checkpoints.diskHardCapMb`, default 5 GiB) — wait for background cleanup, raise the cap, or clear `~/.coda/checkpoints/`.
+
+If snapshots fail three times in a row, CODA auto-recovers by re-initializing the shadow repo and warns you in chat — earlier history for that session is no longer reachable, and a fresh history starts from the next snapshot.
+
+### Diagnose with `/checkpoint-status`
+
+When the `/timeline` picker is empty or a session reports checkpoints disabled, run:
+
+```text
+/checkpoint-status
+```
+
+It prints a health summary: current **State**, the **project** + **workspace id**, the **shadow repo** path, **disk usage** against the soft/hard caps, the **checkpoint count** (for this session and across sessions sharing the project), and any **Skipped dirs**. Multiple `coda` instances in the same project directory share one shadow repo safely; each session only sees its own rows in `/timeline`, while cross-session totals show up here.
+
+## 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:
+
+```text
+/compact
+```
+
+Or start a `/new` session and bring in just the relevant context for your next task.

package/assets/docs/shortcuts.md

@@ -0,0 +1,61 @@
+# Keyboard Shortcuts
+
+These shortcuts work inside the interactive TUI. Type `?` at any time to open the shortcuts overlay, or `/help` for the full command list (extensions may add more).
+
+## Global
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl+C` × 2 | Exit CODA (double-press within ~1500 ms; a single press never exits) |
+| `Ctrl+L` | Clear the conversation (same as `/clear`) |
+| `Ctrl+B` | Toggle the sidebar |
+
+## In the chat input
+
+| Shortcut | Action |
+| --- | --- |
+| `Enter` | Send your message |
+| `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.
+
+## During a turn
+
+| Shortcut | Action |
+| --- | --- |
+| `Esc` | Interrupt the current turn (once the agent has started) |
+| `Ctrl+O` | Toggle "thinking" visibility |
+| `Ctrl+G` | Clear any messages queued while the agent is busy |
+
+## Transcript navigation
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl+↑` | Scroll up in the transcript |
+| `Ctrl+↓` | Scroll down in the transcript |
+| `Ctrl+Shift+C` | Copy the last code block to clipboard |
+| `Esc Esc` | Open the timeline picker (double-press within ~750 ms when the chat input is empty and no turn is running) |
+
+## Model switching
+
+| Shortcut | Action |
+| --- | --- |
+| `Shift+Tab` | Cycle through favorite models |
+
+Mark models as favorites from the `/switch-model` picker; `Shift+Tab` then rotates through just that shortlist, so you can flip between (say) a strong reasoning model and a cheaper everyday one without opening a menu.
+
+## Two shortcuts worth memorizing
+
+If you only remember two, make them these:
+
+- **`Esc`** — interrupt the current turn the moment CODA heads the wrong way. Interrupting and redirecting is faster than undoing.
+- **`Esc Esc`** (when the input is empty) — open the timeline picker to roll your files back to before any earlier turn.
+
+## See also
+
+- [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.

package/assets/docs/tools-reference.md

@@ -0,0 +1,81 @@
+# Tools Reference
+
+**Tools** are the capabilities CODA's agent can use to actually do work: read a file, run a shell command, search the codebase, call an MCP server, load a skill, or delegate to a sub-agent. You don't type tool names yourself — CODA picks the right tool for each task. This page maps the built-in tools and what you can configure about them.
+
+## How tools show up
+
+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.
+- **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.
+
+Some tools pause for **approval** before doing something risky — see [Permissions & Approvals](#permissions). Headless runs use a stricter set: the `ask_user` tool isn't available, and bash defaults to a higher auto-approval tier.
+
+To limit which tools a single run may use, pass `coda --tools …` (see [Commands & Flags](#cli-reference)).
+
+## Built-in tools
+
+| Tool | What it does |
+| --- | --- |
+| `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, gated by risk tiers and approval prompts |
+| `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) |
+| `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) |
+| `mcp_execute` | Call a tool on an MCP server you've connected |
+| `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) |
+
+Extensions and plugins can register more tools the same way the core registers these built-ins.
+
+### 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:
+
+- **To find files**, it uses `glob` (path patterns) before reading anything.
+- **To find text inside files**, it uses `grep` (ripgrep) rather than reading file after file.
+- **To read a known file**, it uses `read`, often with an offset/limit on large files.
+- **To change a file**, it prefers `edit` (surgical search-and-replace) over `write` (whole-file overwrite), and `write` asks before clobbering a file it never read this session.
+- **To run anything in your shell** — tests, linters, git — it uses `bash`, gated by your approval level.
+- **For big or parallel work**, it may delegate with `run_agent` (see [Agents](#agents)) instead of doing it all inline.
+
+The search tools deserve special mention because they're the backbone of fast, accurate work: `glob` and `grep` let CODA locate the right code without loading the whole repo into context.
+
+## What you can configure
+
+Tool behavior is configured in a few different places — some from the `/settings` panel, some from your config files, and some from dedicated managers. The highlights:
+
+| Area | What you control | Where |
+| --- | --- | --- |
+| **Bash** | Approval level and shell mode — how often CODA asks before running commands, and which shell it uses. See [Permissions & Approvals](#permissions). | `/settings` → Bash Tool Preferences |
+| **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) |
+| **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 |
+
+## Tools inside agent runs
+
+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.
+- **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.
+
+## See also
+
+- [How CODA Works](#how-it-works) — tools, memory, and the agent loop in context.
+- [Permissions & Approvals](#permissions) — when and why tools pause to ask.
+- [Extend CODA](#guide-extend) — adding tools via MCP, extensions, and plugins.

package/assets/docs/workflows.md

@@ -0,0 +1,146 @@
+# Workflows
+
+A **workflow** is a deterministic script that orchestrates **multiple agents** for you — fanning work out in parallel, running multi-stage pipelines, looping until a budget or count is reached, and synthesizing the results. Where a single [agent](#agents) handles one task, a workflow coordinates many, with the shape of the work decided at runtime.
+
+Use a workflow when one agent (or a few inline steps) won't cover the job well — for example a repo-wide audit, reviewing every file in a changeset, or any sweep where coverage and confidence matter more than speed.
+
+> Workflows are **opt-in and token-expensive** — they can spin up many agent runs. Reach for one when the scale clearly warrants orchestration or when you've asked for thoroughness; otherwise a single agent is cheaper and faster.
+
+## Run a workflow
+
+You don't need a special command. Just ask in plain language — if a matching workflow exists, CODA runs it. You can name the workflow explicitly, or just describe what you want and let CODA match it:
+
+
+```text
+Create a workflow to do an independent per-principle SOLID audit — one reviewer per principle (SRP/OCP/LSP/ISP/DIP), each finding adversarially verified, synthesized into per-principle verdicts + a prioritized fix list. Write an artifact with your findings.
+```
+
+```text
+Kick off the security-audit workflow across the whole repo, use multiple subagents. Write an artifact when finished. 
+```
+
+CODA reads the arguments each workflow needs straight from your request (the diff to review, the folder to scan, the output location) and only asks when something required can't be inferred.
+
+A few things to know about how runs behave:
+
+- **They run in the background.** CODA shows a "running" notice and keeps the session responsive. You get the outcome on a later turn, when CODA posts a short overview of what the workflow produced (including links to any artifacts it wrote).
+- **CODA infers the inputs.** It reads the arguments a workflow needs from your request, and only asks you when something required can't be determined.
+- **Track progress anytime** from the dashboard (below).
+
+## Watch and stop runs with `/workflows`
+
+Open the workflow dashboard to see live progress as a tree of phases and agent cards, plus the history of past runs:
+
+```text
+/workflows
+```
+
+To stop a run:
+
+- **Command:** `/workflows stop <runId>` stops that run; `/workflows stop` (no id) stops **all** in-flight runs for the session.
+- **Dashboard:** press **`c`** on a running entry to cancel it.
+
+## Create a workflow
+
+You don't write the script by hand. Ask CODA to build one and it delegates to the built-in **`create-workflow`** agent, which authors the workflow module and saves it for you:
+
+```text
+Create a workflow to do an independent per-principle SOLID audit — one reviewer per principle (SRP/OCP/LSP/ISP/DIP), each finding adversarially verified, synthesized into per-principle verdicts + a prioritized fix list. Write an artifact with your findings.
+```
+
+The same plain-language request works for any of the shapes a workflow is good at — describe the goal and let `create-workflow` design the phases:
+
+```text
+Create a workflow that translates every Markdown doc under content/ to Spanish and reports a summary
+```
+
+```text
+Create a workflow that reviews every file in my staged diff and cross-checks the findings into one report
+```
+
+```text
+Create a workflow that audits each package for missing error handling and writes one findings report
+```
+
+```text
+Create a workflow that researches a question from several angles in parallel, then synthesizes one answer
+```
+
+```text
+Create a workflow that runs each file in a folder through a lint → fix → verify pipeline
+```
+
+```text
+Create a workflow that keeps generating test ideas until it finds no new ones or hits a budget
+```
+
+> **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.
+
+## Workflow authoring conventions
+
+Workflow scripts support two conventions:
+
+- **Coda-native:** export a `run(ctx: WorkflowContext)` function. All primitives are accessed via the `ctx` parameter.
+- **Bare-globals:** top-level body with ambient primitives — the Claude Code-compatible style. CODA loads these through a compatibility layer that injects `agent`, `parallel`, `pipeline`, `phase`, `log`, `workflow`, `args`, `budget`, `writeArtifact`, `copyArtifactTo`, `now`, `random`, and `signal` as globals.
+
+**Key context primitives:**
+
+| Primitive | What it does |
+| --- | --- |
+| `ctx.agent(task, options?)` | Run an agent task and return its result |
+| `ctx.parallel(tasks)` | Fan out tasks concurrently |
+| `ctx.pipeline(stages)` | Run agents in serial stages |
+| `ctx.phase(title)` | Group agents under a named phase in the dashboard |
+| `ctx.log(message)` | Emit a progress message visible in the dashboard |
+| `ctx.workflow(nameOrRef, args?)` | Invoke another workflow by name or path |
+| `ctx.writeArtifact(name, content)` | Persist a deliverable to disk as a named artifact |
+| `ctx.copyArtifactTo(artifactPath, destDir)` | Copy a written artifact to a user-specified directory |
+| `ctx.budget` | Token-budget object with `.spent()` and `.remaining()` methods |
+| `ctx.signal` | `AbortSignal` for cooperative cancellation |
+
+## Where workflows live
+
+Workflows are discovered automatically from your project and your user-global config, so anything committed to the repo is available to the whole team:
+
+- `<project>/.coda/workflows/` — project-specific (commit these to share them).
+- `<project>/.claude/workflows/` — Claude Code-compatible project location, also discovered.
+- `~/.coda/workflows/` and `~/.claude/workflows/` — personal, available in every project.
+- Plugins may also bundle their own workflows.
+
+CODA discovers `.ts`, `.mts`, `.js`, and `.mjs` files in these directories (`.d.ts` declaration files are ignored).
+
+## What a run produces
+
+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.
+
+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).
+
+## When a workflow is worth it
+
+Workflows pay off when **coverage and confidence** matter more than latency:
+
+- A **repo-wide audit** — check every package for a class of bug.
+- **Review every file** in a large changeset, then cross-check the findings.
+- A **sweep** that applies the same treatment to many items (translate every doc, add a header to every file).
+- A **loop** that keeps going until a budget, a count, or "no new results" is reached.
+
+For a single fact, a one-file edit, or a few tightly-coupled steps, skip the workflow — a single [agent](#agents) or inline work is cheaper and faster.
+
+## Good to know
+
+- **No enable/disable setting.** Unlike skills or MCP servers, there's no toggle — a workflow is available as soon as its file is discovered.
+- **Background by design.** Because runs are non-blocking and report back on a later turn, you can keep working (or start another run) while one is in flight.
+- **Built on agents.** Every step a workflow runs is a normal agent run, so the same model, concurrency, and approval rules apply.
+- **Token-aware.** A wide fan-out can spin up many agent runs at once — keep an eye on scale for large sweeps.
+
+## See also
+
+- [Agents](#agents) — the single-task delegation that workflows orchestrate.
+- [Extend CODA](#guide-extend) — skills, extensions, plugins, and MCP.
+- [Tools Reference](#tools-reference) — the `run_agent` family and the rest of CODA's tools.