# HyperSEO installation instructions for coding agents

## Entry point and scope

Work in the extracted HyperSEO folder containing `package.json`. Read
START_HERE.md, SETUP.md, AGENTS.md, and docs/TROUBLESHOOTING.md first. The installed
package.json/lockfile define the version; do not upgrade dependencies as an install
step. This is a standalone local Next.js app with SQLite, not Hyperchat's Convex
architecture. Use no DevLaunch/Hyperchat cloud projects, credentials, or databases.

Infer fresh/existing installation from files and the operator's request. Do useful
local setup without repeatedly asking for permission. When configuration/data
already exists, preserve it. If ownership/target is ambiguous, establish the intended
folder before changing an external connection; do not pick another site's account.

## Procedure

1. Verify the ZIP checksum if supplied. Read `RELEASE.json` for version/source identity.
   Inspect the actual `package.json`; a source checkout may not have a release manifest.
2. Check Node (`node --version`, minimum 22.13) and npm (`npm --version`). Use the
   bundled version-manager files if the operator already uses a version manager.
   Do not replace their system-wide runtime automatically.
3. Inspect whether `.env.local` and private data already exist, without printing
   their contents. Existing installations use SETUP.md's stopped backup/compare
   procedure. Preserve the database and its matching encryption key together.
4. Run `npm run setup` from the package root. It creates `.env.local` only when
   missing, uses locked `npm ci --include=dev`, then runs types/tests/build.
   `--config-only` does not constitute a finished installation.
5. Run `npm run doctor`. Investigate failed checks; never delete the lockfile,
   database, or key as a generic repair. PHP connector contract checks are optional
   unless you changed connector code: `npm run test:wordpress`.
6. Start `npm start` in a persistent local terminal. Open the configured loopback
   address. Run `npm run doctor -- --running` from another terminal and confirm
   the web response and local worker heartbeat.
7. Use **Fieldwork Studio** for writes. Queue an audit, track a finding, review/apply
   test metadata, verify actual HTML, and restore the original. Keep dated evidence
   and implementation records; never fabricate traffic/SEO gains for acceptance.
8. If optional integrations are requested, follow README.md. The owner enters
   credentials privately in Connections and completes Google consent themselves
   when interactive authorization is required. Use their own staging WordPress
   site. A passing local build is not live provider acceptance.
9. Report version, local URL, automated checks, web/worker results, and integration
   steps actually completed. List skipped optional checks without credentials.

## Boundaries

- Local origin is `http://127.0.0.1:PORT` (1024–65535). The runner binds loopback
  and derives its port from `.env.local`; the worker shares this configuration.
  If the port is occupied, preserve the unrelated process. Use a user-selected
  free port and update the exact Google redirect URI when applicable.
- Private data belongs in `.data` or an absolute external folder. Never put it in
  `public`, source, documentation, exports, or another customer's installation.
- Never request passwords/keys in chat, dump environment values, or print database
  connection rows. Diagnostics report local status without credential values.
- Live website writes require the explicit in-app review/apply flow. Do not queue,
  silently apply, or retry an ambiguous write to “finish setup.” Monitoring is
  read-only and begins off; setup does not authorize recurring client work.
- No public deployment: this edition has no hosted workspace authentication or
  tenant authorization. Public hosting is separate development, not an install flag.
- Do not send emails, post social content, publish reports, or make purchases to
  validate an installation. None is required for the local workflow.

## Useful follow-up prompts

**Continue development:** “Read AGENTS.md and docs/BUILD_PLAN.md. Inspect the current
code/status, implement the requested change, run appropriate checks, and preserve
existing data and explicit live-implementation review.”

**Diagnose installation:** “Read docs/TROUBLESHOOTING.md. Run local diagnostics and
repair the actual failing step without exposing credentials or resetting history.”

**Prepare a release:** “Read docs/RELEASE_CHECKLIST.md. Validate and commit the source,
package only its clean tracked allowlist, and verify the ZIP in a fresh private
installation before handing it off.”