@globant/coda-darwin-x64 1.0.0

package/assets/docs/guide-changes.md

@@ -0,0 +1,101 @@
+# Make Changes Safely
+
+CODA is designed for real work on real codebases — which means it needs to be safe to use. This guide explains how CODA protects your work, how to stay in control while it makes changes, and how to undo anything that goes wrong.
+
+## Checkpoints: your undo button
+
+Before each turn, CODA takes a checkpoint — a snapshot of your files **before it acts on your latest message**. Restoring that checkpoint brings the worktree back to the state it had right before that message was processed. To see and restore checkpoints, open the timeline picker with `/timeline` (or its alias `/rewind`, or press **Esc** twice) and select the point to restore to.
+
+In addition to per-turn snapshots, CODA automatically takes an extra snapshot labelled `pre_destructive_bash` immediately before any destructive shell command (`rm`, `mv`, `sed -i`, `git reset`, `git clean`, `git checkout`, and similar). These appear in `/timeline` alongside the regular per-turn snapshots, so you can restore to the state right before a file deletion or rebase even if it happened mid-turn.
+
+For how checkpoints work in detail — the shadow repo, Git requirements, and how restoring rewinds the conversation — see [Sessions & Checkpoints](#sessions).
+
+## Approve commands as they run
+
+When CODA wants to run a shell command, it shows you what it's about to execute and waits for your approval — press **Y** to allow it or **N** to skip it. By default, CODA auto-approves low-risk commands (like `git status` or `cat`) and asks before anything that writes or deletes files.
+
+How much runs without asking depends on your **bash approval level**, which you set 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 — `mkdir`/`touch`/`cp`, package installs/tests, `git add`/`commit`/`checkout`/`stash`/`switch`/`restore` (**default**) |
+| `medium` | Adds riskier operations — `mv`/`rm`, `git push`/`pull`/`merge`/`rebase`/`reset`, `chmod`/`chown` |
+| `high` | Everything except clearly destructive operations (`rm -rf /`, disk format) |
+
+See [Configuration](#configuration) for more on adjusting this per project.
+
+## Interrupt early if something looks wrong
+
+If you see CODA going in the wrong direction, don't wait for it to finish — interrupt as soon as you notice:
+
+- Press **Esc** to stop the current turn
+- Then redirect: "Stop — I didn't mean to change that file. Undo those changes and let's try a different approach."
+
+The earlier you interrupt, the easier it is to recover. Letting CODA run to completion and then asking it to undo everything is much messier than stopping it mid-stream.
+
+## Send a message while CODA is working
+
+You don't have to stop the turn to react. You can type while CODA is busy, and a setting controls what happens when you hit **Enter**. Choose it from `/settings` → **Composer**. This controls the **chat input** behavior while CODA is busy:
+
+- **Queue** (default) — your message waits and is delivered as the next turn once the current one finishes.
+- **Steer** — your message is injected into the run in progress, nudging CODA mid-turn without interrupting it.
+
+If you queued messages and change your mind, press **Ctrl+G** to clear the queue.
+
+## A safe workflow for bigger changes
+
+For anything non-trivial, use this pattern:
+
+1. **Explore first, change later.** Ask CODA to explain what it would do before it does it: *"List the files you'd need to change for X, but don't make any edits yet."*
+2. **Work in small steps.** Instead of "implement the whole feature", break it into "add the model", then "add the controller", then "add the tests". Checkpoint between each.
+3. **Review after each step.** Use `/timeline` to verify what changed before moving to the next step.
+4. **Test often.** Ask CODA to run your test suite after each significant change: *"Run the tests for the billing module now."*
+
+## Common undo scenarios
+
+**CODA edited the wrong file**
+
+```text
+Undo the last change you made to UserService.java — you edited the wrong method.
+```
+
+**A whole batch of changes went wrong**
+
+```text
+/timeline
+```
+
+Select the snapshot from before the bad changes. CODA restores your files to that state.
+
+**You want to start the session over**
+
+```text
+/new
+```
+
+Starts a fresh session. The old session is still saved and resumable — see [Sessions & Checkpoints](#sessions).
+
+## Let CODA verify its own work
+
+The safest changes are the ones CODA checks before handing back. Make verification part of the request:
+
+```text
+Implement the fix, then run `pnpm lint && pnpm type-check && pnpm test` and don't consider it done until they pass.
+```
+
+If your project has an `AGENTS.md` with a "quality gate" section, CODA follows it automatically — see [Collaborate with Your Team](#guide-collaborate). When a check fails, ask CODA to diagnose and fix rather than reverting blindly.
+
+## A quick mental model for staying in control
+
+1. **Checkpoint** — every turn is snapshotted before it runs, so you can always go back.
+2. **Approve** — risky shell commands and unread-file overwrites pause for your **Y**/**N**.
+3. **Interrupt** — **Esc** stops a turn the instant it heads the wrong way.
+4. **Steer or queue** — react without stopping the turn (`/settings` → **Composer**).
+5. **Undo** — `/timeline` (or **Esc Esc**) rewinds files *and* the conversation to a chosen point.
+
+## See also
+
+- [Sessions & Checkpoints](#sessions) — the shadow repo, drift detection, and what a snapshot captures.
+- [Permissions & Approvals](#permissions) — bash approval levels and the anti-clobber guard in depth.
+- [Configuration](#configuration) — set your default approval level and composer behavior.

package/assets/docs/guide-collaborate.md

@@ -0,0 +1,119 @@
+# Collaborate with Your Team
+
+CODA works best when the whole team uses it consistently. This guide covers how to share conventions, skills, and configuration so every developer on the project gets the same quality of assistance.
+
+## Start with AGENTS.md
+
+`AGENTS.md` is the most important file for team collaboration. CODA reads it at the start of every session and uses it to understand your project's conventions — coding style, testing approach, which areas to avoid, how to run the quality checks.
+
+CODA looks for it at your project root (`<project>/AGENTS.md`) first, and falls back to `<project>/.coda/AGENTS.md` if the root file isn't present. Put it at the root for visibility, or under `.coda/` if you prefer to keep it out of the top level.
+
+Create or update it with `/init` and then edit it to add what CODA missed. A typical `AGENTS.md` looks like this:
+
+```text
+# AGENTS.md
+
+## Project conventions
+- Use TypeScript strict mode everywhere
+- All database queries must use parameterized statements
+- New features must include unit tests and at least one integration test
+
+## How to run tests
+  pnpm test              # unit tests
+  pnpm test:integration  # integration tests
+  pnpm lint              # linting
+  pnpm type-check        # TypeScript check
+
+## Quality gate — always run before finishing a task
+  pnpm lint && pnpm type-check && pnpm test
+
+## Do not change
+- The public API in src/api/v1/ without team approval
+- The database schema without a migration
+```
+
+Commit `AGENTS.md` to Git. Every developer who runs CODA in this project gets these conventions automatically.
+
+## Share skills across the team
+
+Skills are per-project when placed in `<project>/.coda/skills/`. Commit them to the repository and everyone can invoke them — or manage them from the `/skills` manager inside CODA.
+
+Good candidates for shared skills:
+
+- PR review checklists specific to your project
+- Debugging workflows for common issues
+- Documentation generation templates
+- Deployment pre-flight checklists
+
+Once committed, any developer on the team can invoke them by name:
+
+```text
+/pr-review
+/debug-api-error
+/generate-docs
+```
+
+## What to commit (and what not to)
+
+The most valuable things to share live in the repo and apply to everyone who clones it:
+
+- **`AGENTS.md`** — your project conventions and quality gates.
+- **Skills** in `<project>/.coda/skills/` — shared workflows the whole team can invoke.
+- **MCP servers** in `<project>/.coda/mcp.json` — the external services this project connects to.
+
+A project-level `<project>/.coda/config.json` is also **safe to commit** — it never holds secrets (those live in `~/.coda/.secrets`, which is never committed). But be selective about what you put there:
+
+- **Don't commit the active provider.** Which provider you use (a specific Glob.AI OS instance, or a local Ollama) is a personal, machine-specific choice, and provider profiles are defined in each developer's own global config. Pinning it in the repo can break teammates who don't have that profile.
+- **Think twice before committing an elevated bash approval level.** Raising `autoApproveLevel` for the whole project means everyone who clones the repo runs more commands without being asked — a safety trade-off your team should agree on first.
+
+In short: share **conventions and workflows**, keep **personal and security preferences** local.
+
+## Working in a monorepo
+
+CODA loads exactly one `AGENTS.md` — the one in the directory where you launch it. **For `AGENTS.md` specifically**, there is no upward directory walk and no merging of parent files. (Agent definitions and workflow modules _do_ walk upward to parent directories, so placing them closer to the repo root makes them available to nested package launches automatically.)
+
+In a monorepo, launch CODA from the package directory you're working in:
+
+```bash
+cd packages/billing
+coda   # loads packages/billing/AGENTS.md
+```
+
+Put conventions that apply everywhere in each package's `AGENTS.md`, or maintain a root-level one and symlink it into each package.
+
+## Share agents and workflows too
+
+Beyond skills, two more team assets live in the repo and ship to everyone who clones it:
+
+- **Agents** in `<project>/.coda/agents/` — reusable specialist profiles (a project-specific reviewer, a migration helper). See [Agents](#agents).
+- **Workflows** in `<project>/.coda/workflows/` — multi-agent orchestrations like a repo-wide audit. See [Workflows](#workflows).
+
+Both are discovered automatically and need no per-developer setup — committing the file is all it takes.
+
+## A suggested `.gitignore` posture
+
+To keep shared assets in and personal/secret state out, a typical project ignores:
+
+```gitignore
+# Personal/local CODA state — do not commit
+.coda/MEMORY.md
+# Generated, project-local caches CODA writes at runtime
+.coda/fgr/
+.coda/omni-parser/
+.coda/workflows-docs/
+.coda/offload/
+.coda/checkpoint-repo/
+
+# Shared CODA assets — DO commit (leave these tracked)
+# .coda/skills/  .coda/agents/  .coda/workflows/  .coda/mcp.json  AGENTS.md
+```
+
+Note that **session records aren't stored in your project** — they live in the global `~/.coda/coda.db` (see [Sessions & Checkpoints](#sessions)), so there's nothing session-related to ignore here. Secrets never live in the repo at all — they're in `~/.coda/.secrets`, outside the project.
+
+> **Watch out for `.env` files.** CODA also loads environment variables from a `.coda/.env` or `.env` file in the project directory. These files may contain API keys or other secrets and should **never** be committed. Add `.coda/.env` and `.env` to your `.gitignore` and use `~/.coda/.secrets` for per-developer secrets instead.
+
+## See also
+
+- [Agents](#agents) and [Workflows](#workflows) — shareable delegation assets.
+- [Extend CODA](#guide-extend) — skills, extensions, plugins, and MCP for the whole team.
+- [Configuration](#configuration) — what a project-level `config.json` can and shouldn't pin.

package/assets/docs/guide-extend.md

@@ -0,0 +1,120 @@
+# Extend CODA
+
+Out of the box, CODA can read files, run shell commands, and use its built-in tools. But you can extend it significantly: connect external services via MCP, teach it reusable workflows via skills, or automate complex integrations with extensions and plugins.
+
+## Which extension mechanism do I want?
+
+These five mechanisms overlap, so start by matching your goal to the simplest option that fits:
+
+| You want to… | Use | Why |
+| --- | --- | --- |
+| Let CODA call an external service (GitHub, a DB, an internal API) | **MCP server** | Speaks a standard protocol; no code to write if the service ships one |
+| Capture a repeatable *process* in plain words (a PR-review checklist, a debug routine) | **Skill** | Just a Markdown file with frontmatter; invoked with `/name` |
+| Add a custom tool, slash command, or hook in code | **Extension** | TypeScript with the full `ExtensionAPI` |
+| Delegate one focused task to a child session | **Agent** | A reusable persona CODA can run on its own |
+| Orchestrate *many* agents (a repo-wide audit, fan-out + verify) | **Workflow** | A deterministic script over multiple agent runs |
+| Bundle and version several of the above to share | **Plugin** | Ships skills, agents, extensions, and MCP fragments together |
+
+Rule of thumb: prefer a **skill** for "how we do X," an **MCP server** for "talk to Y," and an **extension** only when you need real code. Reach for **workflows** when one agent isn't enough.
+
+## Connect external services with MCP
+
+MCP (Model Context Protocol) servers let CODA talk to external services — your issue tracker, CI system, database, or any internal tool that exposes an MCP interface. Once connected, CODA can use these tools automatically when they're relevant to the task.
+
+Everything happens from inside CODA through the `/mcp` manager:
+
+```text
+/mcp
+```
+
+From there you can **add a server** (paste its JSON or import it from a file), edit the global or project `mcp.json`, list configured servers and their connection status, view the tools each one exposes, enable or disable servers for the session, and reload after a change — no need to hand-edit files outside the app.
+
+**Where MCP servers are defined.** Servers live in `mcp.json` files that layer like the rest of your config: `~/.coda/mcp.json` (global) and `<project>/.coda/mcp.json` (project). A third, session-level file at `~/.coda/sessions/<sessionId>/mcp.json` holds per-session overrides — including a disable-only shorthand `{ "disabled": true }` to switch a higher-tier server off for one session. Each server entry is either **stdio** (`command` plus optional `args`/`env`) or **HTTP** (`url`, optional `headers`/token); add `"disabled": true` to any entry to keep it but turn it off. (CODA builds the live server map from `mcp.json` + plugins + `--mcp-config`, so prefer `mcp.json` over the `mcp.servers` block in `config.json`.)
+
+Once a server is connected, CODA can use its tools automatically — you just describe what you want in plain language. For example, with a **GitHub MCP server** connected, you could ask:
+
+```text
+Create a GitHub issue for the bug we just found in the payment flow. Title it "NullPointerException in PaymentProcessor.processRefund".
+```
+
+CODA recognizes that the GitHub server exposes an issue-creating tool and calls it for you. Without that server connected, this prompt has nothing to act on — the tools come from the MCP servers you add.
+
+## Teach CODA repeatable workflows with skills
+
+A skill is a Markdown file that describes a repeatable process — like "how to review a PR" or "how to write tests for this project." Once you create a skill, you can invoke it with a slash command in any session.
+
+Create a skill file:
+
+```markdown
+---
+name: pr-review
+description: Review a pull request for code quality, test coverage, and potential issues.
+---
+
+1. Read the diff carefully.
+2. Check that every changed function has test coverage.
+3. Flag any SQL queries that aren't parameterized.
+4. Note any missing error handling.
+5. Summarize findings in a comment-ready format.
+```
+
+Optional frontmatter flags:
+- `disable-model-invocation: true` — hides this skill from CODA's autonomous tool selection (it won't be suggested automatically; default `false`).
+- `user-invocable: false` — hides this skill from the slash palette and `/skills` list (default `true`).
+
+Save it to `<project>/.coda/skills/pr-review.md` and invoke it:
+
+```text
+/pr-review
+```
+
+Skills in the project's `.coda/skills/` folder are available to everyone on the team. Skills in `~/.coda/skills/` are personal and available in every project.
+
+To browse, enable, disable, or install skills, use the skills manager from inside CODA:
+
+```text
+/skills
+```
+
+The manager lists every skill and its enabled state, and lets you enable or disable individual skills (per-session disables are stored under `~/.coda/sessions/<sessionId>/`). You can also install a skill straight from GitHub with `/skills add <repo-url> [project|global]` — choose `project` to commit it with the repo or `global` for your personal library. For private repos or to avoid rate limits, set `GITHUB_TOKEN` (or `GH_TOKEN`) so the GitHub API fallback can authenticate.
+
+## Automate with extensions
+
+Extensions are TypeScript modules that can register custom **tools**, **slash commands**, **lifecycle hooks** (e.g. `session_start`, `tool_execution_end`), custom model providers, keyboard shortcuts, CLI flags, and custom message renderers — using the full `ExtensionAPI`. Use them when you need CODA to integrate with an internal system that doesn't have an MCP server, or to automate a complex workflow that doesn't fit in a skill.
+
+Extensions are auto-discovered from `~/.coda/extensions/` (user-global) and `<project>/.coda/extensions/` (project-specific). No configuration needed — just drop the file in the folder. To see which extensions are loaded and the commands they add, run `/extensions` inside CODA.
+
+Ready to build one? The easiest way is to ask CODA — its `create-extension` skill scaffolds the extension for you. See [Writing Extensions](#extensions) for that, plus the full API reference if you want to hand-write one.
+
+## Share packaged integrations with plugins
+
+Plugins are versioned, installable packages — like extensions, but with a manifest, version number, and the ability to bundle skills, agents, and MCP fragments together. Use plugins when you want to share a reusable CODA integration across teams or projects.
+
+Manage plugins from inside CODA with the `/plugin` manager — enable, disable, and browse any registered marketplace catalog. The `/plugin install` slash command accepts **only absolute local paths** to a plugin directory; for npm packages, Git URLs, or marketplace-sourced plugins, use `coda plugin install <source>` from the terminal:
+
+```text
+/plugin
+```
+
+You can also install from your terminal:
+
+```bash
+coda plugin install <source> [--name <folder>] [--scope global|project]
+```
+
+`<source>` can be an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. `--name` selects a subdirectory (useful for monorepo git sources); `--scope` chooses `global` (default) or `project` install scope.
+
+### Adding a marketplace
+
+A marketplace is a catalog of plugins. Add one from the terminal with `coda marketplace install <source>`, where `<source>` can be:
+
+- a **Git remote** (`https://…/owner/repo`, an `git@host:owner/repo` SSH URL, or a GitHub `/blob/` link) — CODA shallow-clones it, so enterprise GitHub/GHES works too;
+- a **direct catalog URL** (`https://…/marketplace.json`, including `raw.githubusercontent.com`);
+- a **local folder** containing a `marketplace.json` (Claude-style `.claude-plugin/` or `.coda-plugin/` layouts are recognized);
+- a **local `.zip`** archive — CODA unpacks it and finds the catalog inside, including the single nested top-level folder you get from a GitHub "Download ZIP" / "Source code" archive.
+
+CODA is compatible with the Claude Code plugin and marketplace ecosystem, so catalogs published for Claude Code work here.
+
+## Orchestrate multiple agents with workflows
+
+When a job needs more than a single agent — a repo-wide audit, reviewing every file in a changeset, or any sweep that runs the same treatment over many items — CODA can run a **workflow**: a script that orchestrates multiple agents in parallel, in pipelines, or in loops. Ask CODA to build one (it delegates to the built-in `create-workflow` agent), then run it in the background and watch it from the `/workflows` dashboard. See [Workflows](#workflows) for the full picture.

package/assets/docs/guide-understand.md

@@ -0,0 +1,95 @@
+# Understand a Codebase
+
+Whether you're onboarding to a new repo or diving into a part of your own codebase you haven't touched in months, CODA can get you oriented fast. This guide shows you how to use CODA as an exploration tool — before writing a single line of code.
+
+## Before you start
+
+Launch CODA from the project root and let it explore freely. Don't give it tasks yet — ask it questions. The more context it builds up, the better its answers get.
+
+```bash
+cd /path/to/project
+coda
+```
+
+## Get oriented quickly
+
+Start with the big picture before zooming in on specifics.
+
+**Understand the overall structure**
+
+```text
+What is the main entry point of this project and how is it structured?
+```
+
+**Map the key flows**
+
+```text
+Trace the full request lifecycle from an incoming HTTP request to the database and back. Which files are involved?
+```
+
+**Understand how a specific feature works**
+
+```text
+How does authentication work in this project? Walk me through the full flow.
+```
+
+## Dig into specifics
+
+Once you have the big picture, use CODA to go deeper on the areas you care about.
+
+**Understand a module before changing it**
+
+```text
+Before I touch the billing module, explain how it works. What are its dependencies? What would break if I changed the calculate_invoice function?
+```
+
+**Find where something is implemented**
+
+```text
+Where is the rate limiting logic implemented? Is it in middleware or inside the controllers?
+```
+
+**Understand a bug before fixing it**
+
+```text
+Users are reporting that their session expires too quickly. Without making any changes, trace the session timeout logic and tell me where the problem might be.
+```
+
+## Plan before editing
+
+One of the best uses of CODA's exploration mode is planning a change before you make it. Ask CODA to map the impact of a change so you don't miss anything.
+
+```text
+I want to add soft-delete support to the User model. Without making any changes, list every file I would need to touch and explain why each one is affected.
+```
+
+```text
+What's the minimal set of changes I'd need to make to support multi-tenancy in this project?
+```
+
+## Tips for better exploration
+
+- **Be specific about what you want to know.** "How does auth work?" is fine, but "How does the OAuth refresh token flow work specifically?" gets you a better answer.
+- **Ask follow-up questions.** CODA builds context as the session progresses. If the first answer is too high-level, ask it to go deeper on the part that matters.
+- **Don't let it make changes during exploration.** If CODA offers to fix something while explaining it, say "just explain for now, don't change anything."
+- **Delegate broad exploration on large repos.** Instead of flooding your main session, ask naturally for a broad exploration — for example: *"Map how billing connects to the payment provider and report back a summary; don't edit anything."* CODA can decide to delegate that work to the built-in `explore` agent and bring the summary back to your main session. See [Agents](#agents) for more on delegated work.
+
+## Ask for a diagram or a written map
+
+Exploration output doesn't have to be prose. Ask CODA to render what it finds in a form you can keep:
+
+```text
+Draw a Mermaid sequence diagram of the checkout flow, from "Add to cart" to "Order confirmed".
+```
+
+```text
+Write a short ARCHITECTURE.md describing the top-level modules and how they depend on each other.
+```
+
+Pinning the result to a file (a diagram, a module map, an onboarding note) turns a one-off exploration into something the whole team can reuse.
+
+## See also
+
+- [Make Changes Safely](#guide-changes) — once you understand the code, change it without surprises.
+- [Agents](#agents) — delegate a deep exploration to the built-in `explore` agent.
+- [How CODA Works](#how-it-works) — why live file reads make answers accurate.