# HyperSEO installation

## Requirements

- Node.js 22.13 or newer with npm. This package was tested on macOS with Node
  22.23.1. Get Node from [the official download page](https://nodejs.org/en/download).
- Internet access for `npm ci`, website crawling, and optional Google connections.
- A writable local folder and an available loopback port (3226 by default).
- Optional: Git for packaging customized releases (its fixture test skips if Git
  is unavailable). PHP 8+ for WordPress connector contract tests; your own WordPress
  staging site and Google OAuth project for live integration validation.

No Docker, Convex, paid AI key, cloud database, or hosting account is required to
try the local fixture. Node's SQLite API may print an experimental warning on Node
22; that warning alone is not an installation failure. Windows/Linux instructions
use platform-neutral Node scripts; this release's full installation was checked
on macOS, not independently on Windows or Linux.

## Download and verify

Keep the `.zip.sha256` sidecar beside the ZIP. Before extraction, compare the
SHA-256 checksum:

```bash
# macOS
shasum -a 256 hyperseo-0.5.0.zip
# Linux
sha256sum hyperseo-0.5.0.zip
```

```powershell
# Windows PowerShell
Get-FileHash .\hyperseo-0.5.0.zip -Algorithm SHA256
Get-Content .\hyperseo-0.5.0.zip.sha256
```

The digest must match the sidecar. This detects an altered/corrupt download; the
sidecar is not a digital signature. Extract into a dedicated folder outside
another application's source. `RELEASE.json` lists the source commit and file
hashes. The archive contains source and fonts, not installed dependencies, builds,
local website captures, configuration, database rows, or credentials.

## Fresh installation

In the extracted folder containing `package.json`:

```bash
npm run setup
npm start
```

`setup` checks the runtime, preserves/creates `.env.local`, installs dependencies
with `npm ci --include=dev`, and runs `npm run check` (types, tests, build).
It does not start a cloud deployment, authorize an integration, or enable monitoring.
Dependencies include `tsx`, which the local worker needs at runtime; do not install
with `--omit=dev`. Keep the supplied lockfile and dependency versions.

Open **http://127.0.0.1:3226**. `npm start` supervises both processes. Keep its
terminal open and the computer awake for background jobs. Ctrl+C stops both.
For source development, use `npm run dev`; restart the runner after worker-code or
`.env.local` changes. There is no automatic OS service.

To prepare configuration without installing dependencies or running checks:

```bash
npm run setup -- --config-only
```

This is preparation only; run normal setup afterward. The equivalent manual path
is `npm ci --include=dev`, `npm run check`, then `npm start`.

## Local configuration

The setup command copies `.env.example` to `.env.local` only when the latter is
absent. Defaults work without integrations. The supervisor loads this file before
starting the web app and worker; `npm run worker` also loads it directly. Existing
process environment variables take precedence. Use literal values, not shell
expressions or variable interpolation.

```dotenv
HYPERSEO_ORIGIN=http://127.0.0.1:3226
# Optional private absolute path, quoted if it contains spaces:
# HYPERSEO_DATA_DIR="/absolute/path/to/private/hyperseo-data"
```

The canonical origin must use HTTP, `127.0.0.1`, a port between 1024 and 65535, and
no path/query. To use an available alternate port, change the single origin value,
restart, and update any Google OAuth redirect URI to the exact address shown in
Connections. The runner derives the port and always binds to `127.0.0.1`.
Never stop an unrelated application just to free port 3226.

Private data defaults to `.data` in the extracted project. Alternate storage must
be an absolute folder outside the source project. Do not point it into `public`,
`src`, docs, or exported packages. Both processes must share the same folder and
credential key. Windows path example: `"C:/Users/You/HyperSEOData"`.

Google OAuth secrets and WordPress application passwords are entered privately in
**Connections** and encrypted server-side. Do not put secrets in chat transcripts,
`NEXT_PUBLIC_*` variables, example files, or source control.

## First-run checks

1. Run `npm run doctor`. Expect runtime/npm/SQLite/dependency checks to pass.
2. Start with `npm start`, then use another terminal:

   ```bash
   npm run doctor -- --running
   ```

   Expect HTTP 200 and a current worker heartbeat.

3. In the app, choose Fieldwork Studio. Queue **Monitoring → Check now** and see
   the completed audit. Track an opportunity on the fix board.
4. Review/apply a metadata change **to the test website**, verify its HTML, and
   restore the original. Real website implementation is a separate live action.
5. Confirm missing Google/analytics metrics remain missing and recurrence is off.

Diagnostics do not inspect saved credential values or authorize providers.
`npm run doctor -- --running --json` produces a local report; review it before
sharing. It is not a Google/WordPress health certificate.

## Optional Google and WordPress connections

See [Connect Google](README.md#connect-google) for your own Google project,
read-only OAuth consent, property selection, and report synchronization.
The callback defaults to `http://127.0.0.1:3226/api/google/callback`; use the exact
configured address and your own test-user/provider permissions.

For WordPress, `extras/hyperseo-connector.zip` is included in the source download.
It is also available from Connections after starting the app. Install/activate it
on your staging site first and create a dedicated application password privately.
See [Connect a WordPress website](README.md#connect-a-wordpress-website). The
connector version is independent of the HyperSEO app version. Contract tests use
WordPress stubs; they do not establish live theme/plugin/cache compatibility.

## Existing installations

1. Stop the web/worker runner. Securely copy the **entire** private data folder,
   including `hyperseo.sqlite`, any SQLite sidecars, and `credential.key`. Keep
   backups private; a database without its original key cannot decrypt credentials.
2. Extract the new release into a separate folder. Compare your source edits;
   never blanket-overwrite a customized installation.
3. Copy your `.env.local` privately. If using default `.data`, copy the entire
   stopped data folder into the new installation, or configure its original
   absolute external storage path. Never mix a database with a different key.
4. Run setup and review the reported checks. Start only the intended new runner;
   use the same canonical origin or update Google redirects if you change it.
5. Check your saved websites, history, connections, and worker status. For rollback,
   stop the new runner and restore the old source **and** its matching data backup.

Fresh-install scripts preserve data; they are not source-merge or migration planners.
Current startup creates missing SQLite tables but does not reset existing records.

## Packaging your own source

With reviewed code committed and the checkout clean:

```bash
npm run release
```

This creates a ZIP, checksum, and manifest in ignored `exports/hyperseo-VERSION/`.
Only allowlisted tracked source is included; private paths, symlinks, unexpected
files, and an uncommitted checkout stop packaging. Verify a fresh extraction before
handing out a customized release. See [release checks](docs/RELEASE_CHECKLIST.md).

## Optional 0.4.0 workflows

Start with `docs/GROWTH_WORKFLOW.md` for action plans, keywords, results and branded
reports. `docs/CONTENT_WORKFLOW.md` covers briefs and internal links;
`docs/CONTENT_POLISH.md` covers your own OpenAI key, Brand Voice and per-generation
consent. Draft review and exact live-publishing approval are separate steps.

For body changes read `docs/WORDPRESS_CONTENT.md` or `docs/CUSTOM_PUBLISHING.md`.
The Vercel connector requires your own Neon PostgreSQL database and a site that
renders registered managed HTML. It does not rewrite arbitrary JSX/MDX source.

`docs/SEARCH_INTELLIGENCE.md`, `docs/AI_VISIBILITY.md` and
`docs/GROWTH_MONITORING.md` explain provider setup, evidence boundaries and costs.
Scheduled paid checks start paused, require explicit opt-in and the running local
worker, and never automatically retry. API samples are not consumer-app exposure;
GA4 source tags are not proof of which prompt generated a visit.

## Keyword, competitor and backlink research

Open any Explorer → Usage & connection and configure your own DataForSEO account.
Review the shared Explorer call cap and planning budget before approving a paid
request. Labs and Backlinks require the corresponding access with your provider.
The local worker must stay running. See `docs/RESEARCH_EXPLORERS.md` for the 14
research modes, filters, exports, shortlist tasks and billing/failure behavior.

## Optional Firecrawl and external agents (0.5.0)

Open **AEO & agents → Usage** to save your own Firecrawl key and review usage limits. In **Agent connections**, choose the sites/captures to share and create a scoped, expiring connection. Copy its one-time generated MCP configuration into private Claude Code or Codex settings. Both the agent bridge and HyperSEO must run on the same computer. No agent configuration is installed automatically. See [Firecrawl and agent setup](docs/FIRECRAWL_AGENTS.md) for capabilities, consent and troubleshooting.

## URL report browser support (0.5.0)

The standard setup now installs Chromium for restricted rendered-page checks. When upgrading an existing installation, run `npm run setup:browser` after installing dependencies. HTML-only reports still work when browser support is unavailable; missing deep checks are labelled. Open **URL report** to paste a domain and generate a report. Google mobile performance is optional and requires URL-sharing approval. See [URL reports](docs/URL_REPORTS.md).