# Hyperchat installation instructions for coding agents

**Existing installation?** Read [UPGRADE_1.5.1.md](/hyperchat/getting-started/upgrade-1.5.1.md) first. Extract this release separately; do not run fresh-install setup or overwrite your customized installation. The read-only planner is `scripts/plan-upgrade.mjs`.

## Scope and entry point

Work from the extracted folder containing `package.json`. Read `START_HERE.md`, `SETUP.md` and `docs/TROUBLESHOOTING.md` before changing configuration. The installed `package.json` and lockfile define the version; do not upgrade dependencies as part of installation. The illustrated human guide is https://devlaunchlearn.com/hyperchat/getting-started.

This is a buyer-owned Next.js frontend with a Convex backend, Better Auth and Zernio. Each customer supplies their own infrastructure. One deployment can contain multiple client workspaces. Do not copy the seller's environment or reuse a different project's database.

## Inputs and boundaries

Establish these values with the operator or their existing configuration:

- Fresh install or existing installation; development or production target.
- Their Convex team/project. Stop on an unexpected project before making changes.
- Exact frontend origin: development defaults to `http://127.0.0.1:3215`; production requires HTTPS.
- Owner email. The owner chooses their password privately in the browser.
- Their Zernio key, entered through the hidden installer prompt or Convex dashboard. This may be skipped to test authentication first.
- Optional Resend key and verified sender for email. Optional OpenRouter/GIPHY keys go in workspace Settings later.

Never request credentials in a chat transcript, print them, commit `.env.local` or `.bootstrap-owner`, or put secrets in `NEXT_PUBLIC_*` variables. Do not silently select another project, reset a database, rotate working secrets or enable unrestricted signup. Do not send social messages, publish posts, launch campaigns or incur AI spend simply to complete installation. Obtain the operator's content/account/budget instructions for live tests.

## Procedure and checkpoints

1. **Preflight.** Run `node --version` (at least 22.13) and `pnpm --version` (10.20.0). Install pnpm if necessary with `npm install --global pnpm@10.20.0`. Preserve the archive's lockfile. If a checksum sidecar came with the download, verify it before extraction.
2. **Dependencies.** Run `pnpm install --frozen-lockfile`. Expected: successful install with no lockfile changes. Investigate errors rather than deleting the lockfile.
3. **Configure development.** Run `pnpm run setup` in an interactive terminal. Plain `pnpm setup` is a different, built-in pnpm command. The Convex CLI authenticates and selects/creates a cloud project. Confirm the selected project, frontend origin and owner email. Enter keys privately; blank optional prompts can be skipped.
4. **Installer completion.** Expected: backend deployed; `.env.local` contains the three frontend URLs; `.bootstrap-owner` contains the one-time owner token. Generated secrets are stored in Convex. `ALLOW_SIGN_UP` stays false. New installs leave required email verification off pending a successful delivery test. Inspect variable names or use diagnostics, never dump values to logs.
5. **Start.** Run `pnpm dev`. Visit `http://127.0.0.1:3215/workspace` (or the configured local origin). Use Owner setup with the configured email and private token. Create a password of at least 12 characters. Delete `.bootstrap-owner` after successful owner creation. Sign out and sign back in; create a clearly named test workspace.
6. **Connections.** Follow SETUP.md: assign the operator's Zernio profile, connect and sync their intended account, configure the signed webhook and verify delivery. The webhook uses the matching public Convex `.convex.site` origin, not localhost. Keep separate client profiles/workspaces.
7. **Email.** Configure the operator's Resend sender. Confirm an actual verification/reset email reaches their inbox before enabling `REQUIRE_EMAIL_VERIFICATION=true`. Then retest sign-in and invitation acceptance. A saved API key or provider acceptance alone does not prove delivery.
8. **Verify.** Run `pnpm run doctor --connected` and `pnpm check`. Doctor checks configuration shape; it does not contact providers or certify credentials. The tests and production build do not prove live channel delivery. Record each live check separately.

## Production is a separate target

Use a separate checkout of this customer's source. Configure their Convex project, then run `pnpm run setup --prod` and supply that project's production URL plus the HTTPS frontend origin. The command updates production backend variables and deploys the backend. Set the frontend's `NEXT_PUBLIC_CONVEX_URL`, matching `NEXT_PUBLIC_CONVEX_SITE_URL`, and `NEXT_PUBLIC_SITE_URL` before building. Backend `SITE_URL` must match the frontend origin. Rebuild after URL changes. See SETUP.md for hosting and production owner creation. Do not switch an existing local workspace to production just to validate a build.

## Recovery

- On Convex login/network/env-read failure, repair access and rerun the same setup. Existing secrets are preserved. Do not delete configuration files as a generic fix.
- If first-owner creation is unfinished and the token is lost, the operator can remove `BOOTSTRAP_TOKEN_HASH` in their Convex dashboard, then rerun setup. Do not do this for an active installation as routine maintenance.
- If port 3215 is occupied, do not stop an unrelated app. Select a free port, enter its exact origin during setup, and run `pnpm exec next dev --hostname 127.0.0.1 --port YOUR_PORT`.
- If a provider send has an uncertain result, inspect its run/provider history; never automatically retry it.

## Completion report

Return the installed version, environment (development/production), local or hosted app link, and which checkpoints actually passed. Separate automated checks from live owner/email/provider acceptance. List skipped integrations and remaining work. Never include credentials or customer conversations.

For a support report, run `node scripts/doctor.mjs --connected --json` and review the output before sharing. It excludes configuration values and does not upload anything. Use Help & feedback in the app or https://devlaunchlearn.com/feedback?product=hyperchat.