> ## Documentation Index
> Fetch the complete documentation index at: https://aiwithapex.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# RELEASING

# Release Checklist (npm)

Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tagging/publishing.

## Operator trigger

When the operator says “release”, immediately do this preflight (no extra questions unless blocked):

* Read this doc and confirm npm auth is available.

1. **Version & metadata**

* [ ] Bump `package.json` version (e.g., `2026.1.26`).
* [ ] Update CLI/version strings: [`src/cli/program.ts`](https://github.com/moshehbenavraham/crocbot/blob/main/src/cli/program.ts) and the Baileys user agent in [`src/provider-web.ts`](https://github.com/moshehbenavraham/crocbot/blob/main/src/provider-web.ts).
* [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to [`dist/entry.js`](https://github.com/moshehbenavraham/crocbot/blob/main/dist/entry.js) for `crocbot`.
* [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.

2. **Build & artifacts**

* [ ] `pnpm run build` (regenerates `dist/`).
* [ ] Verify npm package `files` includes all required `dist/*` folders (notably `dist/node-host/**` and `dist/acp/**` for headless node + ACP CLI).
* [ ] Confirm `dist/build-info.json` exists and includes the expected `commit` hash (CLI banner uses this for npm installs).
* [ ] Optional: `npm pack --pack-destination /tmp` after the build; inspect the tarball contents and keep it handy for the GitHub release (do **not** commit it).

3. **Changelog & docs**

* [ ] Update `CHANGELOG.md` with user-facing highlights (create the file if missing); keep entries strictly descending by version.
* [ ] Ensure README examples/flags match current CLI behavior (notably new commands or options).

4. **Validation**

* [ ] `pnpm lint`
* [ ] `pnpm test` (or `pnpm test:coverage` if you need coverage output)
* [ ] `pnpm run build` (last sanity check after tests)
* [ ] `pnpm release:check` (verifies npm pack contents)
* [ ] `CROCBOT_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke` (Docker install smoke test, fast path; required before release)
  * If the immediate previous npm release is known broken, set `CROCBOT_INSTALL_SMOKE_PREVIOUS=<last-good-version>` or `CROCBOT_INSTALL_SMOKE_SKIP_PREVIOUS=1` for the preinstall step.
* [ ] (Optional) Full installer smoke (adds non-root + CLI coverage): `pnpm test:install:smoke`
* [ ] (Optional) Installer E2E (Docker, runs `curl -fsSL https://github.com/moshehbenavraham/crocbot/install.sh | bash`, onboards, then runs real tool calls):
  * `pnpm test:install:e2e:openai` (requires `OPENAI_API_KEY`)
  * `pnpm test:install:e2e:anthropic` (requires `ANTHROPIC_API_KEY`)
  * `pnpm test:install:e2e` (requires both keys; runs both providers)
* [ ] (Optional) Spot-check the web gateway if your changes affect send/receive paths.

5. **Publish (npm)**

* [ ] Confirm git status is clean; commit and push as needed.
* [ ] `npm login` (verify 2FA) if needed.
* [ ] `npm publish --access public` (use `--tag beta` for pre-releases).
* [ ] Verify the registry: `npm view crocbot version`, `npm view crocbot dist-tags`, and `npx -y crocbot@X.Y.Z --version` (or `--help`).

### Troubleshooting (notes from 2.0.0-beta2 release)

* **npm auth web loop for dist-tags**: use legacy auth to get an OTP prompt:
  * `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add crocbot@X.Y.Z latest`
* **`npx` verification fails with `ECOMPROMISED: Lock compromised`**: retry with a fresh cache:
  * `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y crocbot@X.Y.Z --version`
* **Tag needs repointing after a late fix**: force-update and push the tag, then ensure the GitHub release assets still match:
  * `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`

6. **GitHub release**

* [ ] Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z` (or `git push --tags`).
* [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `crocbot X.Y.Z`** (not just the tag); body should include the **full** changelog section for that version (Highlights + Changes + Fixes), inline (no bare links), and **must not repeat the title inside the body**.
* [ ] Attach artifacts: `npm pack` tarball (optional).
* [ ] From a clean temp directory (no `package.json`), run `npx -y crocbot@X.Y.Z send --help` to confirm install/CLI entrypoints work.
* [ ] Announce/share release notes.

## Plugin publish scope (npm)

We only publish **existing npm plugins** under the `@crocbot/*` scope. The repo
does not ship a bundle of extensions beyond the Telegram channel plugin, so
plugin publishing is opt-in per package.

Process to derive the list:

1. `npm search @crocbot --json` and capture the package names.
2. Confirm each package is still maintained and intended to ship (skip repo-only
   plugins like `extensions/telegram`).

Current npm plugin list: derive it from `npm search @crocbot` and the repo plugin
manifests, then update this doc as needed.

Release notes should call out new optional plugins if any are introduced later.