# 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. Audit findings, briefs and link proposals are deterministic drafts. Content Polish is an explicitly requested AI feature: use only the operator’s own encrypted provider key and explicit per-generation sharing consent. Treat provider output as untrusted draft text. Retain exact sources and brand voice snapshots, require editorial review, and require a separate exact publishing preview/apply approval. Never promise detector evasion, factual correctness or ranking gains. AI Visibility may use explicitly approved OpenAI API samples with optional web search. Send only the selected prompt/persona, not tracked brands or private notes. Keep API samples separate from operator-captured consumer-app answers; retain exact text/citations and never imply measured consumer exposure, rank or causal uplift. Growth Monitoring adds explicitly approved recurring API samples and SERP reads in a separate paid-check queue. Reserve allowances before requests, enforce call limits, preserve uncertain charges, never auto-retry paid calls, and fence results after pause/cancel/provider or input changes. Planning allowances are not provider invoice guarantees. See docs/GROWTH_MONITORING.md. ## 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. Explorer research uses fixed DataForSEO Labs/Backlinks endpoints and an independent paid queue/allowance ledger. Never infer measured traffic from competitor estimates or Google judgments from backlink scores. Preserve zero versus missing metrics, explicit per-request approval, source scope, no-retry behavior and credential/lease fencing. See docs/RESEARCH_EXPLORERS.md. ## 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. - `custom-connector.ts`, `content-publisher.ts`, `connectors/nextjs/`: approved custom-site body publishing. The shipped SQLite adapter requires persistent storage; connectors/nextjs-vercel uses Neon Postgres for Vercel. Both require registered HTML rendering. JSX/MDX use reviewed packages; never imply arbitrary code is edited automatically. - `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. ## 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. Firecrawl and agent access: use only scoped, expiring hashed agent tokens over the local stdio MCP bridge. Never expose provider credentials or unshared evidence. Agent research stays pending until human paid approval; AEO drafts require cited frozen evidence and human editorial review. No agent publish/apply/settings tools. Keep fixed provider endpoints, bounded plain-text captures, no paid retries and lease/credential/cancellation fences. See docs/FIRECRAWL_AGENTS.md. URL reports preserve HTML and rendered DOM as separate evidence. Never use a restricted render as proof of publication or Google indexing. Chromium must use the dead-end proxy, blocked service workers/WebSockets, and intercepted same-origin GETs fulfilled through the DNS-pinned fetcher; do not give page scripts direct network access. Keep response, request and time limits. Google mobile Lighthouse requires per-report sharing approval, has a daily cap and never auto-retries. Label unavailable checks and lab versus field data. See docs/URL_REPORTS.md.