Supplemental Insurance Pros Website

Project Identity

This repository contains the L9 Website Factory Bot — a deterministic website generation pipeline powered by @quantum-l9/llm-router. It generates Astro-based lead-generation websites from domain specifications, with AI-powered content generation, design intelligence, competitor research, and visual QA. Currently configured for Supplemental Insurance Pros, prepared for Vercel preview-first deployment.

Verified Repo Facts

Area	Value	Evidence
Runtime	Node.js 20+	REQUIREMENTS.md, npm/Astro project
Package manager	npm	package.json, package-lock.json
Framework	Astro	astro.config.mjs, package.json
Build output	dist/	Astro static build convention and local validation bundle
Deployment target	Vercel	deployment scripts and docs
CRM direction	AccuLynx phase 2	env contract and verification scripts
LLM Router	@quantum-l9/llm-router (GitHub Packages dependency)	src/services/llm.ts
LLM Providers	OpenRouter + Perplexity	contracts/llm_router_integration.yaml

Unsupported values remain Unknown until the operator supplies them. Do not invent contact, license, disclaimer, analytics, CRM, or deployment values.

Domain Spec — input contract (flat, canonical)

The pipeline consumes a flat DomainSpec, validated at stage 1 by src/pipeline/validateDomainSpec.ts. This is the canonical build input — see fixtures/ci-test-spec.yaml for a complete example and src/pipeline/BuildContext.ts for the type. Required shape:

• client_id: string
• business_name: string
• vertical: string
• geography: { states: string[]; primary_state: string }
• routes: Array<{ slug: string; title: string; components: string[] }>
• design: { status: 'resolved' | 'pending'; palette?: Record<string,string>; fonts?: Record<string,string> }
• optional: seo_contract, wom_flags

Run with an explicit spec: npm run pipeline -- --spec=<path> (defaults to domain_spec/domain_spec.normalized.yaml). The rich, deeply-nested authoring format under inputs/ is not consumed directly — it must be converted to this flat schema first; the loader detects the nested format and fails with an actionable message.

Quick Start

npm ci                    # Install dependencies (incl. @quantum-l9/llm-router from GitHub Packages)
npm run build             # Build the Astro site into dist/
npm run preview           # Serve built site locally

Canonical operator commands are available through make:

make help                 # Show all available commands
make install              # Install dependencies
make build                # Build site
make verify               # Run full verification suite
make verify-visual-qa     # Run LLM vision-based layout QA
make generate-domain-spec # Generate domain spec via LLM
make generate-content     # Generate page content via LLM

Developer shortcuts are available through just when installed:

just build
just verify

Environment Setup

Copy the template and fill operator-specific values locally:

cp .env.example .env.local

Never commit .env.local. Required live-launch values include Vercel credentials, form endpoint, analytics provider/id, AccuLynx credentials, business contact values, license number, and approved disclaimer text.

Validation

Run the full local verification suite:

npm run verify:all

Individual checks:

npm run verify:preflight
npm run verify:source
npm run verify:build
npm run verify:smoke
npm run verify:form
npm run verify:analytics
npm run verify:crm
npm run verify:seo
npm run verify:rollback

Validation must produce evidence. A script existing is not proof. A successful launch claim requires logs, URLs, receipts, or blocked checks labeled with exact missing values.

Deployment

Deployment is Vercel preview-first:

npm run deploy:preview

Production deployment requires explicit operator authorization:

npm run deploy:production

See DEPLOYMENT.md for gates and RUNBOOK.md for operational procedures.

Launch Gate

Do not call the site launch-ready until all are true:

1. npm ci passes.
2. npm run build passes.
3. npm run verify:all passes or labels external checks as blocked with evidence.
4. Vercel preview URL is created and verified.
5. Form endpoint receives a synthetic lead.
6. AccuLynx receives a synthetic lead or CRM is formally deferred.
7. Analytics receives page-view and conversion events or analytics is formally deferred.
8. Rollback procedure is verified.
9. No unresolved blocker remains.

File Map

• src/: Astro source files.
• public/: static public assets and runtime SEO files.
• scripts/: verification and deployment automation.
• validation/: validation reports and machine evidence.
• docs/: secondary operational documentation when present.
• Makefile: canonical CI/operator command surface.
• justfile: developer ergonomic wrappers.
• .env.example: environment variable contract without secrets.

AI Agent Use

Read AGENTS.md before modifying the repository. Agents must preserve Astro/Vercel locks, avoid fake claims, avoid invented values, and validate before reporting readiness.

Remaining Unknowns

• business phone
• business email
• business address
• public adjuster license number
• approved disclaimer text
• support/security contact
• license choice
• form endpoint
• Vercel org/project/token
• analytics provider/id
• AccuLynx endpoint/key/account

Launch Configuration Closure

The remaining launch Unknowns are controlled through .env.example, config/launch-env.required.yaml, and scripts/verify-launch-env.mjs. No real-world values are invented in this repository.

Before public launch, provide required support, security, domain, form, Vercel, legal approval, licensing, analytics, and AccuLynx values through .env.local or Vercel Project Settings.

Run:

npm run verify:launch-env

This fails closed until required launch values and approval gates are satisfied. DRAFT_LEGAL_DISCLAIMER.md is draft only until LEGAL_DISCLAIMER_APPROVED=true and LEGAL_DISCLAIMER_VERSION are set.