Proto Baseline Requirements

Pre-Awareness Client Prototype Baseline Requirements Specification

Source Issue: #576
Status: uningested (Point-in-time write-up pending /docs distill alignment)
Target Canonical Spec: docs/runbooks/PROTO_BASELINE_REQUIREMENTS.md

1. Context & Architectural Mandate

In SiteSwarm, pre-awareness client prospecting hinges on delivering high-fidelity, high-taste, interactive prototypes before a prospective client even initiates a formal discovery conversation. When business owners see their actual business—with their real address, phone number, operating hours, authentic photography, and brand aesthetic—rendered with sub-second edge performance on their own smartphones, the sales conversation shifts from abstract promises to undeniable proof of excellence.

The Negative Constraint: Zero Sibling App Cloning

[!CAUTION] Sibling App Cloning is Strictly Forbidden. Autonomous agents and engineers must NEVER clone, copy-paste, or scaffold new prototypes from existing vertical apps (such as apps/bakery, apps/auto-repair, apps/me-portfolio, or apps/clk-construction).

Why Cloning Existing Client Apps Is Banned:

Domain Cruft & Schema Contamination: Existing client apps carry client-specific component hierarchies, obsolete bespoke CSS variables, and domain-specific schemas that pollute new prospect codebases.
Hidden Platform & Backend Leakage: Cloned apps often retain references to internal platform services, obsolete D1 database bindings, or admin route artifacts that violate the lightweight, zero-leakage prototype contract.
Template Stagnation (“AI Slop” Trap): Copying layouts creates homogenized, repetitive design patterns that degrade the bespoke, handcrafted agency aesthetic required by SiteSwarm.

The Greenfield Rule: Every prototype must begin as a blank directory at apps/proto-<slug>/ and satisfy the 6-Pillar Baseline Requirements Specification codified below.

flowchart TD
    subgraph NegativeConstraint["Strictly Forbidden Workflow"]
        ExistingApp["Existing Client App\n(apps/bakery, apps/auto-repair)"] -- "Clone / Copy-Paste" --> CorruptedProto["Bloated Prototype\n(Legacy cruft, schema leaks, styling bugs)"]
    end

    subgraph StandardWorkflow["The 6-Pillar Greenfield Workflow"]
        EmptyDir["Empty Directory\n(apps/proto-slug/)"] --> Grounding["Fact & Aesthetic Grounding\n(prospect.json + VIBE.md)"]
        Grounding --> Scaffold["Greenfield Astro Edge Scaffold\n(Astro + @astrojs/cloudflare)"]
        Scaffold --> SixPillars["6-Pillar Baseline Compliance\n(100/100 CWV, Zero-CLS, Mobile-First)"]
        SixPillars --> VerifiedProto["Pristine Edge Prototype\n(apps/proto-slug)"]
    end

    style CorruptedProto stroke:#ff0000,stroke-width:2px;
    style VerifiedProto stroke:#00aa00,stroke-width:2px;

2. The 6-Pillar Baseline Requirements Specification

Every prototype authored within SiteSwarm must satisfy all six pillars before being submitted for review, deployed to preview ingress, or presented to a prospect.

apps/proto-<slug>/
├── package.json         # Pillar 1: Valid pnpm workspace manifest
├── astro.config.mjs     # Pillar 1: Astro + Cloudflare adapter, session: false
├── wrangler.jsonc       # Pillar 1 & 6: Worker isolate config with noindex preview headers
├── tsconfig.json        # Pillar 1: Strict monorepo TypeScript setup
├── prospect.json        # Pillar 4: Verified NAP & Prospect Fact Sheet (Zero Hallucination)
├── VIBE.md              # Pillar 5: Aesthetic Direction Contract & Design Tokens
├── public/
│   ├── favicon.svg
│   └── _headers         # Pillar 6: X-Robots-Tag: noindex, nofollow
└── src/
    ├── components/      # Pillar 2 & 3: Mobile-first, zero-CLS components
    │   ├── Header.astro
    │   ├── Hero.astro
    │   ├── Offerings.astro
    │   ├── ProofPoints.astro
    │   ├── LocationHours.astro
    │   └── Footer.astro
    ├── layouts/
    │   └── BaseLayout.astro
    └── pages/
        └── index.astro

Pillar 1: Edge Technical Foundation

Prototypes are first-class citizens in the SiteSwarm monorepo and must seamlessly integrate into the monorepo build, check, and deployment topology.

Package Manifest (package.json):
- Must reside in apps/proto-<slug>/.
- Name format: "@siteswarm/proto-<slug>" or "proto-<slug>".
- Must specify "private": true and "type": "module".
- Scripts must include standard workspace targets:
```
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "wrangler dev",
    "check": "astro check"
  }
}
```
Astro Edge Adapter Configuration (astro.config.mjs):
- Adapter: @astrojs/cloudflare.
- Mode: output: "server" or static edge pre-rendering.
- Session Configuration: Must declare session: false (or explicitly avoid session auto-provisioning) to prevent @astrojs/cloudflare from provisioning orphaned KV namespaces in ephemeral preview environments per architectural decision docs/write-ups/ADR-0003-WORKER-SPLITTING-AND-KV-ELIMINATION.md.
Cloudflare Worker Isolate (wrangler.jsonc):
- Must define valid Worker isolate parameters: name, compatibility_date, and compatibility_flags: ["nodejs_compat"].
- Zero Database Bindings: In Phase 1 static prototypes, direct D1, KV, and R2 bindings are prohibited in Worker A. The visitor frontend remains completely stateless.
Strict TypeScript Setup (tsconfig.json):
- Must extend standard workspace configuration ("extends": "astro/tsconfigs/strict" or monorepo base).
- Strict type-checking enabled ("strict": true).
- Clean path alias mapping (e.g., "@/*": ["./src/*"]).

Pillar 2: 100/100 Core Web Vitals & Zero-CLS Fallbacks

Prospects judge prototype quality instantly based on speed. Every prototype must target a perfect 100/100 Google Lighthouse Core Web Vitals score on mobile edge networks.

Sub-Second Edge Response:
- Edge SSR caching headers configured for instantaneous edge delivery:
```
Cache-Control: public, max-age=0, s-maxage=3600, stale-while-revalidate=86400
```
- Time to First Byte (TTFB) < 150ms globally on Cloudflare edge.
- Largest Contentful Paint (LCP) < 1.2s.
- First Contentful Paint (FCP) < 0.8s.
Zero Cumulative Layout Shift (CLS = 0.000):
- Layout shifts destroy trust. All visual elements must occupy reserved layout dimensions before remote assets finish loading.
- Every <img>, <svg>, and media container must specify explicit HTML width and height attributes or explicit CSS aspect-ratio rules.
Remote CDN Asset Hotlinking with Explicit Aspect-Ratio SVG Fallbacks:
- Prototypes hotlink authentic photography from prospect web presences or curated high-resolution CDNs (Unsplash/Cloudflare Images).
- If an external CDN asset is slow to load or fails, the layout must provide an inlined SVG placeholder fallback matching the exact aspect ratio (e.g., aspect-ratio: 16 / 9 or aspect-ratio: 4 / 3) with muted neutral tones. Remote images must never collapse containers or cause layout pop-in.
Asset & Script Discipline:
- Zero heavyweight client-side JavaScript frameworks in the visitor bundle.
- No jQuery, heavy UI libraries, or extraneous tracking SDKs.
- Total client JS budget < 10KB (vanilla TypeScript or Astro islands only when interactive state is required).
- Critical typography preloaded or inlined via modern system fallbacks (font-display: swap).

Pillar 3: Mobile-First Responsive Hierarchy

Over 80% of local business customers and prospective owners view websites on mobile devices. Prototypes must be designed for a 375px viewport first, expanding gracefully to tablet and desktop.

Semantic HTML Layout Structure:
- Layouts must adhere to a strict top-to-bottom conversion hierarchy:
  1. Sticky Header / Utility Bar: Brand logotype, immediate 1-tap tel: phone trigger, and real-time open/closed operating status indicator.
  2. Hero Section: Unambiguous value proposition, geographic service radius (e.g., “Serving Northwest Houston Since 1998”), primary high-contrast action CTA, and secondary contact CTA.
  3. Core Offerings / Specialty Grid: Concrete services, menu items, or products extracted directly from prospect facts. No generic 3-card placeholders.
  4. Proof Points & Trust Signals: Verified business age, certifications, trade licenses, Google/Yelp star ratings, and real customer quote excerpts.
  5. Location, Operating Hours & Contact: Physical address, 1-tap Google Maps directions link, detailed day-by-day weekly schedule with current day highlighted, and frictionless contact form or tap-to-call action.
  6. Footer: Neutral copyright, verified legal business name, physical NAP data, and privacy link.
Ergonomic Touch Targets:
- All interactive targets (buttons, links, form inputs) must have a minimum physical bounding box of 44px × 44px.
- Spacing between adjacent tap targets must be at least 8px to prevent accidental mis-taps on mobile touchscreens.
Fluid Typography & Overflow Prevention:
- Fluid typography implemented via CSS clamp() to scale cleanly across viewports without breakpoint jumps.
- Zero horizontal scroll (overflow-x: hidden on viewport roots, defensive layout sizing).

Pillar 4: Verified NAP & Prospect Fact Sheet (`prospect.json`)

[!IMPORTANT] Zero Content Hallucination: AI agents and developers must never invent fictitious business hours, phone numbers (e.g., 555-0199), fake street addresses, or imaginary offerings. Every piece of business data displayed on the prototype must trace directly to prospect.json.

Before authoring a single component, the prospect fact sheet must be established at apps/proto-<slug>/prospect.json:

{
  "$schema": "./prospect.schema.json",
  "business": {
    "legalName": "Apex Auto Care LLC",
    "dba": "Apex Auto Service",
    "tagline": "Precision European Automotive Diagnostics & Repair",
    "foundedYear": 2011,
    "licenseNumber": "BAR #281904"
  },
  "contact": {
    "phone": "+1 (555) 382-9102",
    "displayPhone": "(555) 382-9102",
    "email": "service@apexautocare.com",
    "address": {
      "street": "1420 NW Industrial Blvd",
      "suite": "Suite 4B",
      "city": "Portland",
      "state": "OR",
      "postalCode": "97210",
      "country": "US"
    },
    "googleMapsUrl": "https://maps.google.com/?cid=1029384756"
  },
  "hours": {
    "monday": { "open": "07:30", "close": "17:30" },
    "tuesday": { "open": "07:30", "close": "17:30" },
    "wednesday": { "open": "07:30", "close": "17:30" },
    "thursday": { "open": "07:30", "close": "17:30" },
    "friday": { "open": "07:30", "close": "17:00" },
    "saturday": { "closed": true },
    "sunday": { "closed": true }
  },
  "offerings": [
    {
      "id": "factory-diagnostics",
      "name": "OEM Diagnostic Scanning",
      "summary": "Dealer-level computer diagnostics for BMW, Audi, Porsche, and Mercedes.",
      "pricingNote": "Flat-rate $185 diagnostic inspection"
    },
    {
      "id": "brake-service",
      "name": "Brembo & OEM Brake Service",
      "summary": "Precision rotor resurfacing, ceramic pads, and fluid flush."
    }
  ],
  "socialProof": {
    "googleRating": 4.9,
    "reviewCount": 184,
    "highlights": [
      "ASE Master Certified Technicians",
      "3-Year / 36,000-Mile Warranty"
    ]
  }
}

Pillar 5: Aesthetic Direction Contract (`VIBE.md`)

Prototypes must reflect bespoke, brand-faithful visual artistry. Every prototype must include a VIBE.md contract at its root specifying aesthetic tone, typography, and color tokens extracted directly from the prospect’s brand identity.

Structure of `VIBE.md`:

Design Philosophy & Brand Narrative:
- Defines the emotional resonance of the brand (e.g., “Humble, quiet mastery; precision engineering without industrial aggression” or “Warm, dawn-baked artisanal community atmosphere”).
- Aligns directly with the 4-Axis “Red Pen” Editorial Rubric codified in CLIENT_APP_REVIEW.md.
Typography Pairing:
- Primary Display Font: Expresses brand character (e.g., Cormorant Garamond for heirloom bakeries; Syne or Plus Jakarta Sans for precision engineering).
- Secondary Body Font: Clean, neutral reading ergonomics (e.g., Inter, DM Sans).
- Strict type-scale ratios and letter-spacing specifications.
Color Palette Tokens:
- Extracted from real prospect assets (existing website, physical shop signage, or truck livery).
- Semantic token mapping:
  - --bg-canvas: Deep canvas background.
  - --bg-surface: Elevated card surface.
  - --color-accent: High-contrast brand accent for primary conversion actions.
  - --text-primary: High-contrast readable copy (WCAG AAA compliant).
  - --text-muted: Subtle supporting copy.
  - --border-subtle: Restrained dividing borders.
Textures, Radii & Depth Discipline:
- Corner Radii: Strict geometric standard (e.g., 0px sharp for industrial architecture, 4px subtle for engineering, 8px warm for hospitality).
- Shadow Discipline: Ban on heavy drop-shadows; use crisp 1px borders and tonal contrast for elevation.

Pillar 6: Noindex & Zero Platform Leakage Guardrails

Prototypes are confidential prospect assets deployed to publicly accessible edge infrastructure. They must never be indexed by search engines or leak internal platform implementation details.

1. Mandatory Noindex HTTP Headers

Every prototype worker must emit strict noindex HTTP headers on all routes. This is enforced via Cloudflare public/_headers and Astro middleware:

/*
  X-Robots-Tag: noindex, nofollow, noarchive, nosnippet
  Cache-Control: public, max-age=0, s-maxage=3600, stale-while-revalidate=86400

And mirrored in HTML <head>:

<meta name="robots" content="noindex, nofollow" />

2. Zero Platform Leakage Invariant

Public copy, HTML comments, and client-facing error pages must be completely white-labeled.

[!CAUTION] Strictly Forbidden Terms in Public Copy:

SiteSwarm

EmDash

Cloudflare Worker (or Cloudflare Workers)

Worktrunk

Worker A / Worker B

D1 / R2

Automated linting and review gates will reject any prototype exposing these platform terms to prospect visitors.

Footer copyright lines must attribute ownership exclusively to the prospect:

<!-- Correct -->
<p>© 2026 Apex Auto Service. All rights reserved.</p>

<!-- FORBIDDEN (Platform Leakage) -->
<p>Powered by SiteSwarm Edge Engine / Cloudflare Workers</p>

3. Compliance & Verification Checklist

Before advancing a prototype to preview hosting or client presentation, verify compliance against the 6 pillars:

Pillar	Requirement	Verification Method
Pillar 1: Edge Foundation	Greenfield directory (`apps/proto-<slug>`), valid `package.json`, `astro.config.mjs` with `session: false`, `wrangler.jsonc`.	`pnpm --filter proto-<slug> run check`
Pillar 2: 100/100 CWV	Sub-second edge TTFB, CLS = 0.000, explicit image aspect-ratios, SVG fallbacks, total client JS < 10KB.	Lighthouse audit & DevTools Performance trace
Pillar 3: Mobile-First	Bespoke hierarchy (Nav, Hero, Offerings, Proof, Location, Footer), 44px touch targets, fluid typography.	Mobile viewport (375px) visual inspection
Pillar 4: Verified NAP	`prospect.json` present; 100% of copy, hours, phone, and services grounded with zero hallucination.	Content diff against `prospect.json`
Pillar 5: Aesthetic Contract	`VIBE.md` established; typography pairing and brand color tokens implemented; Red Pen rubric compliance.	Visual review against `VIBE.md` tokens
Pillar 6: Zero Leakage	`X-Robots-Tag: noindex, nofollow` header active; zero platform terminology (`SiteSwarm`, `EmDash`, etc.) in copy.	`curl -I <url>` header audit & grep string sweep

🔍 Founder Trimming & Condensation Notes

Items flagged for condensation during Phase 2 /docs distill alignment into docs/runbooks/PROTO_BASELINE_REQUIREMENTS.md:

The detailed prospect.json example can be shortened or referenced via a dedicated schema definition once a shared Zod schema is published in @siteswarm/governance.
The negative constraint explanation regarding sibling app cloning can be distilled into a concise architectural callout box once automated linter rules (arch/no-sibling-clone) are activated.
The 6-pillar table can serve as the primary condensed quick-reference cheat sheet for autonomous agent prompts.

Decisions Intentionally Deferred

Automated Lighthouse CI Gate: While 100/100 Core Web Vitals is a strict standard, automated CI failure on performance variance is deferred until preview ingress infrastructure (#577) is fully deployed.
Dynamic Zod Schema Validation for prospect.json: Runtime schema validation via CLI is planned for Story #444 (feat(prototype): implement multi-agent prototype skill).