m13v-setup-client-website

# Setup Client Website One-time onboarding flow for a new (or rebuilt) client/consumer site. Produces a modern, SEO-optimized Next.js site with real content, images, video embeds, structured data, and the infrastructure needed for programmatic SEO guide pages. **Scope boundary:** this skill leaves the repo in a state where `/t/<slug>` guide pages can be produced. It does NOT write guide pages. All guide-page content generation is handled by the `gsc-seo-page` skill, which drives `~/social-autoposter/seo/generate_page.py`. After running this skill, register the site in `~/social-autoposter/config.json` and hand off to `gsc-seo-page` for every page. ## Arguments Provide the client name, domain (if any), and existing site URL (if any). Example: `"Paperback Expert at paperbackexpert.com"` ### Optional scope flags These are OFF by default. Only enable them if the invoker mentions the feature explicitly (e.g. "with book-a-call", "add a contact form"). If the scope flag is not mentioned, skip every phase marked `[opt-in: book-a-call]` etc. — do not half-scaffold placeholders. | Flag | Default | Triggers phases | |------|---------|-----------------| | `book-a-call` | off | 3.5d Book-a-Call helpers, 3.5l Cal.com event type creation, 6g Cal.com webhook wiring, Phase 8 booking-verification row, Phase 10a `booking_link` field | **When a flag is off:** do not add `<BookCallLink>`/`<BookCallTracker>`, do not create a Cal.com event type, do not add `booking_link` to `config.json`, and skip the booking-related Phase 8 checklist rows. The DM / dashboard pipeline must fall back to `links.install` (or whatever primary CTA the site has) when `booking_link` is absent. **Rationale:** free OSS tools, install-driven products, and open-source landing pages (ClaudeMeter, appmaker-style utilities) have no "book a call" conversion. Forcing Cal.com wiring on them created dead links + placeholder config that broke the stats pipeline. ## Prerequisites - **Google Cloud** project under the m13v.com org (or create a new one) - **GitHub** org or personal account - **PostHog** account (org: m13v) for analytics - **Resend** account (`you@example.com`) for transactional email - **Neon** account for Postgres (one project per client, pooled connection) - **Google Search Console** access - **Isolated browser MCP** for visual comparison ## Stack - Next.js 16 (App Router) + React 19 + TypeScript - Tailwind CSS 4 (inline theme via `@theme`) - next/image for optimized images - Google Cloud Run for hosting (with HTTPS Load Balancer + Certificate Manager) - PostHog for analytics (pageviews, CTA clicks, newsletter subscribes) - Resend for transactional email (newsletter welcome, contact form, optional inbound webhook) - Neon (`@neondatabase/serverless`) for email + contact logs --- ## Phase 1: Audit and Research Phase 1 runs two tracks concurrently: - **Outward track (1a):** understand the market the client sells into (competitors, search demand, industry developments, ICP). - **Inward track (1b-1e):** audit what the client already has (SEO baseline, content crawl, assets, screenshots). Both tracks feed **1f**, which produces a single `research-brief.md` that every downstream phase (copy, hero, CTAs, FAQ, case studies) is required to consume. Research that does not make it into the brief is decoration. ### 1a. Market Research Fan-Out Launch these agents in parallel. They have no dependencies on each other or on the inward track, so batch them in a single message. ``` Launch 4 agents in parallel: - competitor-analysis: identify top 3-5 rivals by SERP + brand search. Per rival, capture: positioning one-liner, pricing, primary CTAs, hero copy, testimonial themes, messaging pillars, obvious gaps or weaknesses. - keyword-research + serp-analysis (single agent, both skills): head terms, long-tail clusters, search intent (informational / commercial / transactional), SERP feature mix (AI Overviews, PAA, video, local pack), difficulty, monthly volume. - deep-research-pro: industry developments in the last 90 days, regulation, notable launches, funding, M&A, price moves, new entrants, platform / distribution shifts. Cite sources. - general-purpose (ICP pass, with WebFetch): 1-2 primary personas with jobs-to-be-done, top 3 pains, top 3 gains, objections, triggers, and the language they actually use (verbatim pulls from Reddit threads, review sites, forum posts, NOT marketing copy). ``` **Output:** four raw reports in `research/raw/` (`competitors.md`, `keywords.md`, `industry.md`, `icp.md`). Do not edit them down here, **1f** does the compression. **Budget guardrail:** if any single agent returns more than ~15k tokens, ask it to re-emit a tighter version capped at ~8k before moving on. Raw-output bloat is the main failure mode of this step. ### 1b. SEO Audit (if existing site) Run parallel SEO agents to baseline the current site. This runs concurrently with 1a. ``` Launch 5 agents in parallel: - seo-technical: crawlability, indexability, Core Web Vitals, mobile - seo-content: E-E-A-T signals, readability, content depth - seo-schema: existing structured data (JSON-LD, Microdata, RDFa) - seo-performance: Lighthouse scores, LCP, CLS, TBT (desktop + mobile) - seo-geo: AI crawler accessibility, llms.txt, citation readiness ``` Record all scores. These become the "before" baseline and the fix list for the new site. ### 1c. Crawl All Pages Use an agent with WebFetch to discover and extract content from every page on the site: 1. Fetch the homepage, extract all navigation and footer links 2. Try common paths: /about, /services, /contact, /faq, /blog, /pricing, /testimonials, /privacy 3. For each discovered page, extract: - URL and page title - All headings (h1 through h6) with hierarchy - Full body text (quotes, testimonials, stats, descriptions) - CTA text and link targets - Form fields (if any) - Navigation links (to discover more pages) **Output:** Complete content inventory organized by page. ### 1d. Extract Visual Assets (and Brand Identity) Use the isolated browser to catalog images, videos, and embeds **on the original brand domain** (e.g. `piastech.com`, `cyrano.ai`), not on the new generic SEO domain. The brand identity is the property of the brand domain. ```js // In isolated browser, navigate to each page and run: () => { const imgs = Array.from(document.querySelectorAll('img')).map((img, i) => { const rect = img.getBoundingClientRect(); return { idx: i, src: img.src, y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height) }; }).filter(x => x.w > 50); const iframes = Array.from(document.querySelectorAll('iframe')).map(f => f.src); return { imgs, iframes }; } ``` **Key assets to identify and download:** - **Brand wordmark / logo** (header top-left; may be SVG, PNG, or inline text — capture exact spelling, casing, and any logomark character like `π(a|s)`) - **Favicon** (`/favicon.ico`, `/favicon.png`, or any `<link rel="icon">` href) - Hero images or background photos - Client/team headshot photos (circular, 100-200px) - Product images (book covers, screenshots, etc.) - Social proof imagery (awards, certifications, partner logos) - Video embeds (Vimeo, YouTube URLs) - Scheduling widgets (Calendly, Cal.com URLs) - Book cover strips / product galleries **Brand colors and fonts.** Dump the brand site's CSS custom properties and fonts so the new site can match the palette: ```js // Run on the brand domain's homepage: () => { const r = getComputedStyle(document.documentElement); const b = getComputedStyle(document.body); const varNames = ['--background','--foreground','--primary','--primary-foreground','--accent','--card','--secondary','--muted','--border']; const vars = Object.fromEntries(varNames.map(n => [n, r.getPropertyValue(n).trim()])); return { bodyBg: b.backgroundColor, bodyFg: b.color, bodyFont: b.fontFamily, vars, }; } ``` Also pull the brand site's CSS file and grep for hex/hsl color values if CSS vars aren't exposed: ```bash curl -sL <brand-url>/assets/index.css | grep -oE '\-\-[a-z-]+:[^;]+;' | sort -u ``` Save the palette to `research/brand-identity.md` with: brand name exact spelling, logomark character (if any), primary/accent hex codes, body/heading fonts, favicon URL, and the logo image URL. Download all identified images to `public/images/` with descriptive filenames. Copy the favicon to `public/favicon.png` and convert to `src/app/favicon.ico` (multi-size `.ico`) with: ```bash magick <favicon>.png -define icon:auto-resize=16,32,48 src/app/favicon.ico ``` ### 1e. Take Full Page Screenshots Capture full-page screenshots of every key page on the original site for visual reference: ``` For each page: 1. browser_navigate to URL 2. browser_take_screenshot with fullPage: true 3. Save as original-{pagename}-full.png ``` ### 1f. Synthesize Research Brief Once 1a-1e are all complete, run a **single** synthesizer pass (general-purpose agent, no fan-out) that reads every file in `research/raw/` plus the crawl inventory and produces `research/research-brief.md` using exactly this schema: ```markdown # Research Brief: <client> ## Positioning angle (one sentence) <single crisp sentence — what the client uniquely is, for whom, against whom> ## 3 differentiators 1. <differentiator> — proof: <citation / source / datapoint> 2. ... 3. ... ## 5 messaging pillars 1. <pillar headline> — supporting evidence: <...> 2. ... ... ## ICP (1-2 personas) For each persona: - Name + one-line description - Top 3 jobs-to-be-done - Top 3 pains (verbatim language from research) - Top 3 gains - Primary objection + the counter - Trigger event that starts the buying journey ## Proof points Verifiable stats, awards, case-study numbers, named clients, certifications, press mentions. Anything that can appear on the site as evidence — with source. ## Competitor landscape (one paragraph) Who the client is up against, how they're positioned, and the gap the client is walking into. ## Banned clichés Phrases pulled from competitor copy that the new site must NOT reuse (e.g. "cutting-edge", "world-class", "one-stop-shop", plus any industry-specific filler found during 1a). ## Industry signals (last 90 days) 3-5 bullets. Only items that should change hero copy, FAQ, or CTAs. Everything else is cut. ``` **Hard rules for the synthesizer:** - Every claim must trace to a file in `research/raw/` or the crawl inventory. No invented stats. - Hero copy, CTAs, FAQ answers, and case-study selection in Phases 3+ **must** cite lines from this brief. If a later phase wants to say something not in the brief, it returns to 1a instead of making it up. - The brief is the artifact. The raw reports in `research/raw/` are scratch and can be deleted after 1f lands. ### 1g. Visual Reference Brief (required for Phase 3) Phase 3 no longer prescribes how each section looks. It prescribes structure and tokens; visual treatment comes from this brief. Without `research/visual-references.md`, Phase 3 cannot start. **Pick 3-5 reference sites:** - 2 direct category competitors (the best-designed ones from Phase 1a, not the most prominent). - 2-3 design benchmarks from adjacent categories. Rotate so no two client sites share the same benchmark set. Pool: Linear, Raycast, Vercel, Anthropic, PostHog, Stripe, Resend, Rauno, Framer, Arc, Readwise, Granola, NYT Cooking, magazine editorial layouts (Apple newsroom, Stripe Press), brutalist/Swiss sites. **For each reference, capture in `research/visual-references.md`:** - Screenshot at `research/visual-references/<slug>.png` (full page via isolated browser). - Palette (3-5 hex codes; note which is background, ink, accent, signal). - Type stack (display, body, mono families and weights). - 2-3 distinctive motifs (e.g. section numbering with mono chip, live animated product mock in hero, paper grain overlay, hairline grid instead of cards, pull quotes with giant serif marks, floating persistent chip, scroll-reveal stagger, italic serif for emphasis, tilt-on-hover, copy-to-clipboard CTA, kinetic type). - Animation vocabulary (sheen, pulse, parallax, marquee, scroll-driven, spring). - One-line observation: what this reference does well that this client can borrow. **Close with a design thesis** (one paragraph): the visual identity for this client site. Must be specific enough that two agents reading it would produce the same palette family and the same 2-3 signature motifs. Example: *"Editorial, Swiss, on paper-cream `#F4EEE4` with ink `#121110` and signal orange `#E8471C`. Serif display (Instrument Serif, italic for emphasis), sans body (Geist), mono for meta and numbers (Geist Mono). Signature motifs: numbered section eyebrows with hairline rules, live-ticking product mock as the hero anchor, copy-to-clipboard install chip as primary CTA, pull quotes with 90px orange serif mark, floating persistent product chip that follows scroll."* **Exemplar to read first:** `~/.claude/skills/setup-client-website/exemplars/claude-meter-editorial.html`. This is ONE treatment (editorial, Swiss, paper-and-ink, product-first). Do not copy it. Read it as proof that Phase 3 output can be distinctive, product-first, and tactile, rather than the corporate baseline in Appendix A. Add a second and third exemplar to `exemplars/` over time so this skill accumulates visual range. --- ## Phase 1.5: Generic Domain Discovery and Purchase **Goal:** secure a generic, keyword-rich domain that describes the product category rather than the brand (pattern: Cyrano → `apartment-security-cameras.com`). The brand domain (e.g. `cyrano.ai`) still exists; the generic domain is what the new Next.js site ships under for SEO. Skip this phase only if the user explicitly opts out or the brand domain IS already the generic descriptive domain. ### 1.5a. Brainstorm candidates Launch one subagent to generate **two tracks** of candidates, 15-25 per track. Both tracks describe the product category and never include the brand name. **Track A: Short brandable names (priority).** These are the preferred output. - **Length cap: under 8 characters for the stem** (TLD excluded). Total domain with TLD should stay ≤ 11 chars where possible. Examples: `s4l.ai` (stem 3, total 6), `fazm.ai` (stem 4, total 7), `mk0r.com` (stem 4, total 8), `fde10x.com` (stem 6, total 10). Shorter stems are better. - Derive from the product category keyword by vowel drops, consonant clusters, or playful contractions (e.g. `camera` → `cam`, `cmra`, `kmr`; `security` → `sec`, `scrty`). - **Digit substitution for availability.** Swap letters for visually or phonetically similar digits to find available domains: `o` ↔ `0`, `i/l` ↔ `1`, `e` ↔ `3`, `a` ↔ `4`, `s` ↔ `5`, `b` ↔ `6` or `8`, `t` ↔ `7`, `g/q` ↔ `9`. Pattern matches the user's own brands: `s4l.ai`, `mk0r.com`, `cl0ne.ai`, `t8r.tech`, `fde10x.com`. - TLDs ordered by preference: `.ai` (short, premium feel), `.io`, `.com`, `.co`, short-country TLDs like `.bz`, `.me`, `.to`. - Must still phonetically suggest the category (not random letter soup). **Track B: Keyword-rich descriptive names (fallback).** Use when Track A returns nothing available under the price cap. - 3-6 words max; hyphens allowed. - Keyword-front-loaded (e.g. `apartment-security-cameras.com`, not `best.cameras.for.apartments.com`). - Mix TLDs: `.com` (preferred), `.io`, `.ai`, plus any niche TLD that fits the category (e.g. `.cameras`, `.tech`, `.studio`).