# HyperSEO

Separate, buyer-owned website growth app inspired by Hyperchat. Working name.
Use Next.js, TypeScript, Figtree, white surfaces, cobalt accents, and UI text at
least 14px. Keep changes here, separate from the DevLaunch website and Hyperchat.

This edition is a local, single-operator application with persistent SQLite
storage. Bind to 127.0.0.1. Do not publicly deploy before workspace authentication,
tenant authorization, hosted persistence, and credential management are added.
Never use DevLaunch or Hyperchat credentials, Convex deployments, or provider keys.

Local test-site data must be clearly labeled. Real crawls and connected metrics
must never be mixed with test data. Never invent traffic or uplift. Deployment
verification and measured business impact are distinct. Live website changes
require an explicit in-app review and apply action. Never automatically retry an
ambiguous live mutation. Preserve originals; verify current values before undo.

Keep credentials encrypted server-side. Crawl only public HTTP(S) targets with
DNS-pinned connections, bounded responses, redirects, timeouts, and robots rules.
Do not follow cross-origin crawl links. Use deterministic proposals in the current local edition;
label them as drafts, not AI recommendations.

## Entry points and commands

- Installation: START_HERE.md → AGENT_SETUP.md → SETUP.md. The setup command is
  `npm run setup`; keep the lockfile and install dev dependencies for `tsx`.
- Diagnosis: `npm run doctor`, or `npm run doctor -- --running` for the web/worker.
  Diagnostics are local; provider authorization/rendering still needs live checks.
- Development: `npm run dev`; built local run: `npm start`; both supervise the web
  app and worker. Restart after worker or configuration edits. `npm run worker`
  uses the same environment loader when run separately.
- Configuration: `.env.local`; process environment takes precedence. The origin
  is `http://127.0.0.1:PORT`, with no path/query. The runner derives its port.
  Keep storage in private `.data` or an absolute folder outside the source tree.
- Validation: `npm run check`; PHP connector edits also require
  `npm run test:wordpress`. Record meaningful live checks separately from fixtures.
- Packaging: read docs/RELEASE_CHECKLIST.md; `npm run release` requires a clean,
  committed checkout. Never package local environment, database/key, captures,
  installed dependencies, build output, or private customer material.

## Architecture map

- `src/lib/database.ts`, `store.ts`: SQLite state and encrypted credentials.
- `network.ts`, `crawler.ts`, `analyzer.ts`: DNS-pinned public fetches, bounded
  robots-aware crawling, and deterministic HTML findings.
- `actions.ts`, `wordpress.ts`, `wordpress/`: review/apply/verify/restore workflow
  and the external metadata connector. Keep originals and expected-value guards.
- `google.ts`, `analytics.ts`, `page-evidence.ts`: read-only Google grants/reports,
  source-specific imports, page evidence, and scoped heuristics.
- `jobs.ts`, `job-runner.ts`, `work-items.ts`: durable read-only jobs, recurrence,
  ownership/lease fencing, fix tracking, and fresh evidence verification.
- `src/app/api/`: loopback, Origin, body-size, and schema boundaries.
- `src/components/`: page evidence, monitoring, fix board, and implementation UI.

## Work and evidence rules

Queued work is read-only: audit, Google sync, or fix verification. Keep publication
and successful completion atomic in SQLite. Lost/expired ownership or cancellation
must block publication; do not revive disconnected Google grants. Interrupted
reads have at most two attempts. Ordinary provider failures need a manual retry.
Never put apply/restore into automatic retries.

Only freshly inspected original/required related pages can establish an HTML fix.
Redirected, missing, robots-blocked, failed, or unvisited required evidence remains
inconclusive. Operator closure is distinct from verified HTML; analytics findings
need a documented report/tracking review. Keep reporting scopes and samples clear.
Monitoring begins off and requires the local computer/worker to stay available.

Preserve existing installations and source customizations. Back up stopped private
data and its matching key together before moving or upgrading an installation.
Do not erase history or replace secrets as a generic repair. Update relevant setup,
status, and operations documentation when behavior changes.

<!-- BEGIN:nextjs-agent-rules -->

## This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

<!-- END:nextjs-agent-rules -->