Claude Build Instructions

First Run — How Claude Responds

Instructions for Claude: When a user loads this file for the first time, do NOT start building immediately. Follow these steps in order.

• 1 Confirm understanding. Tell the human what you just read and what this file is. Example: "I've read the build guide. I have full context on the tools, build phases, and lessons from the SprintingForLife.com project. This is a reference — not a prescription. Let's figure out what you want to build and which parts of this apply."
• 2 Browse the reference site. Visit sprintingforlife.com to see a live example of what this stack can produce. Note the nav structure, design system (charcoal #2D2D2D, gold #D4A017, Archivo + Source Serif 4 fonts), interactive location map, community forms, and science library pages. Then tell the user: "I've reviewed SprintingForLife.com as a reference. Your site will be designed around your project, not this one."
• 3 Understand the user's project first. Before describing anything you would build, ask: What is your project and who is it for? What do you want visitors to do? Do you have a domain? Which features do you need — content library, community submissions, maps, database, newsletter, analytics, merchandise? What is your budget and timeline? Listen before recommending.
• 4 Recommend tools and phases for their project. Based on their answers, describe what you would build for their specific situation. State which tools apply and which don't. The minimum viable site is a domain (Namecheap) and a web host (Netlify). Everything else is optional.
• 5 Describe the context file system. Explain that before writing any code, you'll build documentation infrastructure — CLAUDE.md (master instructions, your memory across sessions), Action-Items.md (open/closed task tracker), Session-Log.md (running session history), and Decisions.md (permanent decision log, written in real time).
• 6 Ask for questions. "Before I build anything, do you have questions about the approach, the tools, or what applies to your project?"
• 7 Ask for permission to proceed. "When you're ready, I'll start with Phase 0: building the context files for your project. That's about 10 minutes of work and sets the foundation for everything after it. Should I proceed?" Do not build anything without an explicit yes.

Part 1 — What This Guide Is

This guide documents how SprintingForLife.com was built — a science-backed fitness website for a specific niche. The tools, phases, and patterns described here work for a wide range of projects: community sites, resource libraries, local directories, niche content sites, personal brand platforms, and more. Your project may need some or none of what's listed.

What the original site included:

• Static HTML/CSS/JS site (no CMS, no WordPress, no frameworks)
• Homepage with founder story, expert endorsements, email signup
• Science library (peer-reviewed articles, each with its own page)
• Getting Started guide (milestone-based protocol, multiple levels)
• Technique guide (hill sprinting)
• Location Finder (community-submitted locations with Google Maps, photo uploads, ratings)
• Community page (reader story submissions with photo uploads, moderation workflow)
• FAQ, Disclaimer, Terms, Privacy pages
• Merchandise section (Printful QuickStore integration)
• Email newsletter (Beehiiv), Analytics (GA4 consent-gated), Professional email (Google Workspace)

Minimum viable set: A domain (Namecheap, ~$12/yr) and a web host (Netlify, $9/mo). Everything else is optional.

Part 2 — Prerequisites

Only set up what your project needs. These require your identity, credit card, or direct access to third-party consoles — Claude cannot do them for you.

1. Buy your domain — Namecheap.com. Required for any live site. Write down login credentials.
2. Create a Netlify account — netlify.com. Free to start; upgrade when needed.
3. Create a Google account — Foundation for Workspace, Maps API, GA4, Search Console. Only if using those tools.
4. Set up Google Workspace — Only if you want professional email (name@yoursite.com). ~$14/month.
5. Create a Supabase account — Only if your site needs a database. Free tier. Save: project URL, anon key, service role key.
6. Create a Beehiiv account — Only if you want an email newsletter. Free tier.
7. Create a Google Cloud Console project — Only if you need Google Maps. Enable: Maps JavaScript API, Geocoding API, Places API.
8. Create a GA4 property — Only if you want site analytics. Get the Measurement ID (G-XXXXXXXXXX).
9. Printful account — Only if you want merchandise. Set up a QuickStore hosted storefront.

Credentials to share with Claude (never put in public-facing files): Supabase project URL and anon key, Google Maps API key, GA4 Measurement ID, Beehiiv form embed URL.

Content Claude needs from you: Your name, background, and personal story. Your project niche and target audience. Any articles or studies to feature. Expert endorsements. Your brand color. Photos.

Part 3 — The Tool Stack (Detailed)

Namecheap — Domain Registrar

• Register your domain here. Keep Namecheap as registrar only.
• CRITICAL: When you switch DNS to Netlify's nameservers, Namecheap becomes registrar-only. All DNS records (MX, CNAME, TXT) go in Netlify DNS after that point — not Namecheap.

Netlify — Hosting, DNS, SSL

• Serves your static files. Drag-and-drop deployment (drag a zip file into the dashboard).
• SSL is automatic — Let's Encrypt certificate provisions itself when you point your domain.
• When you switch Namecheap DNS to Netlify nameservers, Netlify becomes authoritative DNS. Add all records there.
• Pricing: Free tier is viable for low-traffic launches. Upgrade to paid plan ($9/mo) before hosting large files or seeing real traffic — PDFs burn through free bandwidth quickly.
• Option to consider: GitHub + Netlify auto-deploy. Push to GitHub → Netlify auto-deploys. Eliminates the zip/drag step. Good once the site is stable.

Supabase — Backend Database + Storage (optional)

• PostgreSQL database with REST API, Row Level Security, and file storage. Claude handles all SQL.
• Public INSERT allowed — anyone can submit. Public SELECT only on approved rows. Service role key bypasses RLS — used only in the local admin tool, never deployed.
• Storage: Public bucket for submission photos. Client-side compression before upload (max 1600px, 82% JPEG).
• Admin workflow: Claude builds a local-only HTML admin tool. Open in Chrome, enter service role key, approve/reject submissions. Never deploy this file.

Google Workspace — Professional Email (optional)

• Critical — easy to miss: After creating your account, manually click "Activate Gmail" in the Admin Console. Gmail does not activate automatically.
• Add Google MX records in Netlify DNS (not Namecheap) after switching nameservers.
• Set up DMARC TXT record in Netlify DNS to prevent email spoofing.
• Set up aliases: info@, support@, newsletter@ forwarding to your primary address.

Beehiiv — Email Newsletter (optional)

• Handles subscriber management, welcome email, and broadcast sends.
• Beehiiv provides a CNAME record for your branded sending domain — add in Netlify DNS.
• Welcome email: Configure in Beehiiv → Automations → Welcome Email.
• Font note: Use Arial in Beehiiv email typography. Google Fonts don't render in Outlook.

Google Maps API (optional)

• Enable: Maps JavaScript API, Geocoding API, Places API in Google Cloud Console.
• Restrict your API key to *.yoursite.com/* immediately — takes 30 seconds, prevents unexpected billing.
• Pin-drop submission: user drops a pin, reverse geocoding auto-fills city/state. Claude builds this entirely.
• Free tier: $200/month Google credit — sufficient for most small sites.

Google Analytics 4 (optional)

• Free. Get Measurement ID (G-XXXXXXXXXX) from GA4 console.
• Consent-gated: Claude implements a cookie consent banner. GA4 fires only after visitor clicks Accept.
• One GA4 property per site. Key events to star: email_signup, location_submission, story_submission, first_visit.

Printful — Merchandise (optional)

• Use Printful QuickStore (hosted storefront). Printful is seller of record — handles checkout, fulfillment, shipping, and U.S. sales tax collection. No sales tax permit needed for this channel.
• Design products, order physical samples, approve them, then link the store from your site.
• Don't link the store live until you've approved physical samples. Screen and product can look very different.

Logo Development — AI-Generated Family (optional)

• Use an AI image generator (Midjourney, DALL-E, Adobe Firefly) to develop the initial concept.
• Use Python (Pillow library) to generate color variants — Claude writes all Python scripts.
• Always use transparent PNGs — never JPG for logos. JPG has no alpha channel and renders with a solid white background box.
• Naming convention: bodycolor_swooshcolor_logo_tm.png (e.g., black_gold_logo_tm.png).
• SFL developed 16 color variants across gold, black, white, slate, green, purple.

Part 4 — Build Phases

These are the phases used for SprintingForLife.com. Claude will confirm which phases apply to your project before starting.

yoursite/                ← All files flat at root
  index.html
  [content pages].html
  sitemap.xml / robots.txt / 404.html
  favicon.ico / og-image-v2.png / logo.png

-- Anyone can submit
CREATE POLICY "Public can insert" ON locations
  FOR INSERT WITH CHECK (true);

-- Visitors only see approved content
CREATE POLICY "Public can view approved" ON locations
  FOR SELECT USING (status = 'approved');

Part 5 — File Structure Reference

_YourProject/
  CLAUDE.md                    ← Session instructions
  Action-Items.md              ← Open/closed task tracker
  Session-Log.md               ← Session history
  Decisions.md                 ← Permanent decision log
  Brand/
    Logo Source Files/
      black_gold_logo_tm.png   ← Active web logo
      [color variants]
      archive/                 ← Retired logos (never delete)
  WebsiteDev/
    yoursite/                  ← All HTML, images, PDFs (flat)
      index.html
      [all other HTML files]
      sitemap.xml / robots.txt / 404.html
      favicon.ico / favicon.png
      og-image-v2.png / logo.png
    Deployments/
      yoursite-v1.0.zip        ← Keep all versions

All internal HTML links use bare filenames (faq.html, not /faq.html). All deployment files are at root — no subfolders in the zip.

Part 6 — What Claude Does vs. What You Do

Part 7 — Lessons Learned

• DNS lives in Netlify after you switch nameservers. The moment you change Namecheap DNS to Netlify's nameservers, Namecheap is done. Every DNS record — MX for email, CNAME for Beehiiv, TXT for DMARC — goes in Netlify DNS going forward. Many people keep adding records in Namecheap and wonder why email doesn't work. It won't — Namecheap is no longer authoritative.
• Gmail must be explicitly activated in Google Workspace. There's an "Activate Gmail" banner in the Admin Console. Click it. Gmail does not activate automatically. Easy to skip; leaves you with professional email addresses that silently don't receive mail.
• Chrome print is the right way to make a PDF from your site. Print the web page directly from Chrome (File → Print → Save as PDF). One source of truth — update the page, reprint the PDF. Zero separate content maintenance.
• Netlify free tier hits bandwidth limits faster than you expect. A 2–3MB PDF with real traffic burns through the 100GB free allowance faster than you'd think. Upgrade to Pro ($9/mo) around launch time.
• Supabase service role key is powerful and must stay local. The service role key bypasses all Row Level Security. Never put it in a deployed file. Never commit it to GitHub. The admin tool that uses it lives on your local machine only.
• Logo files must be transparent PNGs, not JPGs. JPG has no alpha channel. A JPG logo renders with a solid white background box that only accidentally matches your page. Use transparent PNGs for all logos on the web.
• Beehiiv typography — use Arial, not Google Fonts. Google Fonts don't render in Outlook. Arial is a native Windows font that works everywhere.
• Restrict your Google Maps API key immediately. Takes 30 seconds in Cloud Console. Prevents unexpected billing if someone scrapes the key from your HTML.
• Document decisions in real time. Write every decision to Decisions.md the moment it's made. Sessions end abruptly. If it isn't written when it happens, it may not survive.
• Ask Claude everything — and push back. No matter what comes up — a technical problem, a tool decision, an unexpected error — the first and best move is to ask Claude. Ask why. Ask how. Ask whether there's a better approach. Don't accept every recommendation without questioning it. Tell Claude the direction you want to go. Claude writes the code; you make the decisions.

Part 8 — Starting a Session With This File

1. Save this file as ClaudeHowToInstructions.md in your connected Cowork workspace folder.
2. At the start of a new session, tell Claude: "I want to build a website. I've read the build guide. Here's my situation: [your project, your niche, which accounts you've already set up]."
3. Claude will follow the First Run protocol: confirm understanding, browse the reference site, ask what you want to build, recommend the right tools, explain context files, ask questions, and request permission before building anything.

Total active build time: A simple content site: 5–10 hours of Claude sessions. A full-featured site like SprintingForLife.com: 15–25 hours of Claude sessions. Your time (decisions, content, account setup): 10–15 hours.