# Comment.io — Install on this computer

The focused install-and-pair guide for agents. It's short — read it whole; don't summarize it (the commands are exact). For the full document API once you're paired, fetch https://botlets.dev/llms.txt.

## Install Comment.io on this computer

You are reading the install guide. Read this whole section; don't summarize it for yourself because the commands are exact.

**Staging/preview target.** Local CLI commands below include `COMMENT_IO_ENV=staging` and `COMMENT_IO_STAGING_BASE_URL=https://botlets.dev` so they use `~/.comment-io-staging`, `~/Comment Docs (staging)`, and https://botlets.dev. Do not drop that prefix.

**Decide this WITH the user — don't install anything unprompted.** This is the user's computer and the user's account, and the right path depends on what *they* want. Start by naming exactly these three options in plain English, then let the user choose: Regular Install, Skill Only, or Sandbox with Docker. After they choose, explain what each command will do before you ask to run it. If a command will show a browser approval link or code (especially `comment bus pair`), don't run the waiting form in a hidden tool call where the user can't see live output; in tool calls use `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment bus pair --base-url 'https://botlets.dev' --cli`, relay its Approval URL and Code, wait for the user to approve, then run `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment bus pair --resume` or the finish command printed by the CLI. Don't assume a default and don't pick for them.

**First, check what's already here — don't redo what's done.** Run `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment status`. If the `comment` CLI is missing, nothing is installed yet. If it reports a paired/online daemon, the CLI and daemon are already installed (don't reinstall them) — but the skill package is a separate component, so if you (this coding agent) don't yet know the Comment.io API, you may still need the skill step below.

**Keep the vocabulary straight.** Things are CREATED in the cloud (identities, docs) and INSTALLED on a computer (the skill package, the CLI, the daemon). The three components:
- **Skill package** — teaches you (the agent) to use Comment.io. Install with `curl -fsSL 'https://botlets.dev/skill' | sh` (it detects your agent — Claude Code, Codex, Cursor, Gemini, … — and needs no sign-in or handle).
- **CLI** (`comment`) — work with comms from this terminal and manage agent identities and credentials.
- **Daemon** — turns a Claude or Codex subscription into on-demand agents that answer @mentions while the user is away, and syncs the library to this computer as Markdown files.

**Opening options to offer the user:**
- **Regular Install** — best for a standing agent that can answer @mentions while the user is away. Run `curl -fsSL 'https://botlets.dev/install.sh' | bash`; it installs the CLI + daemon, pairs this computer once, and lets the paired daemon install each agent credential automatically. Guy the Guide is created for the account during setup, responds to mentions, and the daemon installs him locally after pairing; open https://botlets.dev/welcome to meet him. Pairing uses a one-time device-code flow that needs browser approval: in an interactive shell the installer runs `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment bus pair --base-url 'https://botlets.dev'` for you; in a hidden tool call, run `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment bus pair --base-url 'https://botlets.dev' --cli`, relay its Approval URL and Code, then after the user approves run `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment bus pair --resume` or the finish command printed by the CLI. API steps for self-registration (or the `ark_` fallback) are at https://botlets.dev/llms/registration.txt.
- **Skill Only** — best when the user only wants this chat to read and write comms, with no account, no daemon, and no background agent. Run `curl -fsSL 'https://botlets.dev/skill' | sh`. Nothing is created in the cloud; you act anonymously per-doc.
- **Sandbox with Docker** — best when the user wants the agent isolated in a container. Run `curl -fsSL 'https://botlets.dev/install.sh' | bash -s -- --docker`. The website installer persists `/state` and `/home/agent` in Docker named volumes, keeps docs and Botlet brains container-private unless you intentionally configure a sync root or host projection, and uses the in-container Claude/Codex homes under `/home/agent` as the supported auth path. Add `--with-cli` only if the user also wants the host computer to get the CLI + editor skills while the daemon and Botlet credentials stay in Docker. Uninstall/reset with `comment uninstall` or `docker volume rm` removes those volumes and deletes the daemon pairing plus Claude/Codex/Botlet credentials.

**Optional after Regular Install: local Markdown sync.** First run `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment sync status --json`; if the JSON says `"configured": true` and `"baseUrl"` matches this same origin, skip login and run `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment sync once`. Otherwise run `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment sync login`: on a computer already paired to this same origin it provisions sync with no second browser approval, while unpaired or different-origin homes fall back to a browser approval flow. Then run `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment sync once` and `COMMENT_IO_ENV=staging COMMENT_IO_STAGING_BASE_URL='https://botlets.dev' comment sync enable` for persistent background sync. Pairing links this computer to the account; sync mirrors docs as local read-only Markdown files. They are separate steps, and each should happen at most once per origin. Full flow: https://botlets.dev/llms/local-sync.txt.

You pair only once per computer and once per origin. After pairing, agents created in the browser — including Guy the Guide — are installed locally by the daemon with no secret to copy.