Client Business Intake & Technical Scaffolding Blueprint Specification

Document Status: 🟢 Active True Specification (Medium-Level Design)
Authority: Canonical architectural standard for client onboarding, discovery intake contracts, technical workspace scaffolding, and agent context briefing.
Primary Maintainer: SiteSwarm Architecture Council
Related Documents: HIGH_LEVEL_DESIGN.md, docs/PRD.md, docs/specs/CLIENT_APPLICATION_ANATOMY.md, docs/specs/CAPABILITY_PACKAGE_ANATOMY.md, docs/specs/LOCAL_DEV_AND_EMULATION_RUNTIME.md, docs/CAPABILITY_MANAGEMENT.md
Governing Epic: #37 (epic(dx): client business intake schema and technical scaffolding blueprint)
Companion Epics: #34 (Client App Anatomy), #35 (Headless Capability Anatomy), #36 (Local Dev Runtime), #38 (Cache Invalidation & Freshness), #104 (Strategic Roadmap Initiative)

1. Executive Summary & Design Rationale

SiteSwarm accelerates agency web development for local businesses by marrying a high-velocity monorepo infrastructure with 100% bespoke, unrestrained visual presentation.

1.1 The AI-Amplified Agency Operating Model & Human-in-the-Loop Reality

SiteSwarm is not an imaginary “100% autonomous magic box” where clients appear out of thin air and websites build themselves in a vacuum. In the real world, human relationships are the lifeblood of web agencies and local business partnerships:

The Human Touch & Agency Reality: Humans make the sale, conduct in-person and phone discovery, build client trust, and navigate interpersonal nuances. Local business owners (bakers, mechanics, clinic directors) do not simply discover self-service websites—they partner with trusted agency operators who understand their community and livelihood.
AI-Amplified Human Leverage (10x–50x Force Multiplier): SiteSwarm uses autonomous AI coding agents and edge monorepo infrastructure as a radical force multiplier. A single agency operator commands the output of an entire engineering squad, achieving hyper-scale velocity, low overhead, and ultra-competitive pricing (near-$0/mo hosting, same-day iterations) that traditional agencies cannot match.
The Human Operator as the ‘Client Mirror’: In internal development and planning loops, the human operator acts as the Agency Principal and Technical Lead, directly mirroring the client’s interests, brand standards, and expectations.
Builder Liberties over Micro-Interrogation: When specifications or brand inputs are ambiguous, AI agents must not stall or interrogate the agency operator over every minor aesthetic detail; instead, agents rapidly execute on high-taste, plausible interpretations, maintain an explicit audit trail of liberties taken, build toggleable prototypes, and promote unresolved commercial or legal questions to the human operator.

1.2 The Agency Trade-Off Dilemma

In conventional web development agencies or CMS ecosystems, onboarding a new client traditionally forces a painful trade-off:

The Rigid UI Theme Trap: The agency buys or builds a rigid “restaurant theme” or “auto repair template.” The new client is shoehorned into pre-baked CSS design tokens, hardcoded layouts, and opinionated styling hierarchies. Customizing anything beyond a few color variables requires bloated CSS overrides, #important hacks, and constant fighting against the template. Every client website looks identikit and generic.
The Fragile Blank Canvas Trap: The developer starts completely from scratch with a blank directory. They must repeatedly reinvent routing, TypeScript configurations, Cloudflare edge deployment scripts, contact form honeypots, Turnstile verification, and SEO schemas. Velocity collapses, and maintenance burdens compound.

SiteSwarm solves this dichotomy through three core operational and architectural pillars:

The Living Blueprint Scaffolding Model: Sibling peer applications (apps/bakery, apps/auto-repair, apps/software-agency) serve as living, verified blueprints for foundational technical plumbing. Rather than relying on rigid, brittle code generators or static cookie-cutter CLI templates, AI coding agents and developers dynamically spin up minimal, fully wired Astro edge workspaces on the fly by referencing sibling configurations.
The Open-Ended Client Discovery Intake: A structured yet flexible checklist capturing essential real-world business facts, raw brand assets, aesthetic vibe context, and platform capability needs—while leaving ample, unconstrained room for bespoke client workflows, unique domain logic, and unstructured discovery notes.
The 3-Pillar Ambiguity Resolution & Builder Liberties Protocol: Empowers agents to move fast with high-taste defaults, prototype interactive variations, and log questions for client review without halting execution.

flowchart TD
    subgraph DiscoveryPhase["1. Discovery & Intake Phase"]
        DiscoveryNotes["Client Discovery Interview\n(Owner Conversation, Photos, Signage)"]
        IntakeEpic["GitHub Issue Epic\nepic(client-<prefix>): client intake & onboarding\n(Filled from docs/templates/CLIENT_INTAKE_CHECKLIST.md)"]
        DiscoveryNotes --> IntakeEpic
    end

    subgraph LivingBlueprintPhase["2. Technical Scaffolding Phase"]
        IntakeEpic --> Scaffolding["Dynamic Workspace Scaffolding\n(apps/<client-prefix>-<app-slug>/)"]
        PeerApps["Living Sibling Blueprints\n• apps/bakery/\n• apps/auto-repair/\n• apps/software-agency/"] -.->|Structural Reference| Scaffolding

        Scaffolding --> Plumbing["Foundational Technical Plumbing\n• package.json (@siteswarm/app-<prefix>-<app>)\n• astro.config.mjs (output: 'static')\n• wrangler.jsonc (zero-KV, service bindings)\n• swarm.config.ts (defineAppConfig)"]
    end

    subgraph AgentBriefingPhase["3. Bespoke Authoring Phase"]
        Plumbing --> AgentPrompt["Conversational Agent Briefing\n(Intake Epic Issue #N + Living Blueprints)"]
        AgentPrompt --> BespokeUI["100% Bespoke Client Website\n• Tailored Astro Markup & Vanilla CSS\n• Unique Typography & Aesthetic Vibes\n• Zero Shared UI Theme Tokens"]
        CapabilityPackages["Headless Capability Packages\n(@siteswarm/lead-capture, @siteswarm/seo)"] -.->|Headless Logic| BespokeUI
    end

2. Core Architectural Invariants

2.1 The Anti-Theming & Zero Visual Templating Invariant

The Anti-Theming Invariant: The client business intake contract and scaffolding blueprint must NEVER define a CSS design token schema, theme adapter, or shared component styling hierarchy. We strictly do not feed color variables into a global theme generator.

Instead, the intake captures raw business facts and brand reference materials (e.g. logo, signage color palette, aesthetic vibe notes). AI coding agents and developers consume these notes as creative context to author 100% bespoke markup and styling from scratch for each client, preserving complete visual freedom.

No Global Component Libraries: Client apps under apps/* never import shared visual components (e.g. @siteswarm/ui, buttons, navbars, cards).
Headless-Only Platform Sharing: Shared packages under packages/capabilities/* provide headless logic, state controllers, calculation engines, and server endpoints. They never output HTML markup or CSS classes (as codified in docs/specs/CAPABILITY_PACKAGE_ANATOMY.md).
Visual Individuality: Every client site has its own distinct layout structure, typography pairings, color usage, micro-animations, and visual personality reflecting the authentic brick-and-mortar storefront.

2.2 The Living Blueprint Invariant

The Living Blueprint Invariant: Foundational technical plumbing is defined by canonical documentation and demonstrated by real, working sibling applications in the monorepo (apps/*).

The platform strictly rejects brittle static code generators (pnpm generate-app or rigid CLI templates) that quickly drift from monorepo dependencies. Modern AI agents and engineers generate minimal, compliant application skeletons on the fly by inspecting living peer projects.

Self-Healing Evolution: When monorepo-wide standards evolve (such as transitioning from wrangler.toml to wrangler.jsonc, or updating Astro major versions), updating the sibling applications automatically updates the living blueprint for future client scaffolding.
Context-Aware Scaffolding: An agent scaffolding a specialized automotive service client can inspect apps/auto-repair/ for relevant service layouts, while an agent scaffolding an artisan bakery can inspect apps/bakery/ for menu catalog patterns.

3. The Client Discovery Intake Framework

Client onboarding in the real world is inherently fluid. A local bakery owner might have a vector logo, professional food photography, and an existing square terminal. A local mechanic might only have a photo of their physical storefront sign, a handwritten list of services, and a personal cell phone number.

Attempting to enforce a rigid, machine-validated JSON schema during early client discovery creates friction and breaks down when non-standard requirements emerge.

3.1 Two-Tier Intake Architecture & GitHub Issue Tracking

The intake model operates in two distinct tiers:

Client Intake Epic on GitHub (epic(client-<client-prefix>): client intake & onboarding - <Client Name>): Rather than committing static markdown files to the git repository (which creates commit clutter and separate tracking disconnects), client discovery facts are tracked directly as a GitHub Issue Epic. The checklist template (docs/templates/CLIENT_INTAKE_CHECKLIST.md) is copied into the Epic issue body. Linked child issues track the complete client onboarding lifecycle.
Technical Governance Manifest (apps/<client-prefix>-<app-slug>/swarm.config.ts): Once the technical workspace is scaffolded, verified capabilities and deployment endpoints are formalized in TypeScript using defineAppConfig from @siteswarm/governance.

flowchart LR
    Discovery["Discovery Meeting /\nStorefront Visit"] --> IntakeEpic["GitHub Issue Epic\nepic(client-<prefix>): client intake & onboarding\n(Filled from docs/templates/CLIENT_INTAKE_CHECKLIST.md)"]
    IntakeEpic --> ChildIssues["Lifecycle Child Issues\n• Scaffolding (#A)\n• Bespoke UI (#B)\n• CMS & Content (#C)\n• Routing (#D)\n• Launch (#E)"]
    ChildIssues --> Agent["AI Coding Agent /\nEngineer"]
    Agent --> AppManifest["apps/<client-prefix>-<app-slug>/swarm.config.ts\n(Strict TypeScript Manifest)"]
    Agent --> BespokePages["apps/<client-prefix>-<app-slug>/src/pages/*.astro\n(Bespoke Implementation)"]

3.2 Standard Client Onboarding Lifecycle (Child Issues)

When a Client Intake Epic is opened, it orchestrates standard child issues tracking the client onboarding milestones:

Workspace Scaffolding & Edge Plumbing: Scaffolds apps/<client-prefix>-<app-slug>/ using the living blueprint, allocates ports, configures astro.config.mjs and wrangler.jsonc.
Bespoke Design System & Typography: Implements the client’s unique aesthetic vibe, responsive layout, and typography hierarchy without shared UI tokens.
CMS Content Collections & Data: Configures dynamic content collections, item menus, product catalogs, or portfolio case studies.
Domain Content & Case Studies: Authors domain-specific marketing copy, menus, services, or sanitized enterprise case studies.
Platform Capability Integration: Wires @siteswarm/lead-capture, @siteswarm/quote-estimator, or custom booking forms.
SEO, OpenGraph, Health & Launch: Integrates @siteswarm/seo JSON-LD schemas, dynamic social sharing cards, /api/health probes, and domain bindings.

3.3 Canonical Intake Checklist Taxonomy

The intake document captures six core dimensions of a client’s business:

1. Business Identity & Operating Facts

Official Trade & Legal Name: (e.g., “Green Leaf Bakery LLC”, dba “Green Leaf Artisan Bread & Pastry”).
Physical Street Address & Service Radius: Exact street address, suite, city, state, postal code, and whether the business serves on-site customers or delivers within a specific radius.
Direct Contact Channels: Primary public telephone number, emergency contact phone, customer inquiry email address, and notification preferences (SMS vs. email).
Weekly Operating Hours: Standard hours per day of the week, special weekend hours, and holiday closure policies.
Local Business Classification: Primary Schema.org entity type (e.g. Bakery, AutoRepair, ProfessionalService, Restaurant).

2. Raw Brand Assets & Aesthetic Vibe Context

Brand Identity Assets: Paths or links to primary logo (SVG preferred, high-res PNG accepted), favicon, and secondary icon marks.
Physical Signage & Palette References: Real-world brand hex colors observed on store signage, packaging, or vehicles (e.g. Primary: #2D5A27, Accent: #D4A373).
Aesthetic Vibe Notes: Qualitative brand personality directives authoring the visual atmosphere.
- Example: “Warm, rustic artisan bakery with natural parchment paper textures, handcrafted wood tones, elegant serif headings, and cozy neighborhood bakery ambiance.”
- Example: “High-precision, industrial-grade European automotive specialist with clean dark-mode aesthetics, aggressive neon-amber accents, and sleek performance iconography.”
Raw Photography & Media: Hero storefront photos, team headshots, work-in-progress action shots, or client-provided galleries.

3. Platform Capability Requirements (Wishlist)

Customer Lead & Inquiry Capture: Turnstile spam defense, contact forms, notification channels (SMS via Twilio / email via Resend).
Interactive Estimators & Calculators: Instant quote generators (e.g., custom catering cake pricing, brake pad replacement estimates).
Catalog & Menu Displays: Dynamic item menus, dietary filters (vegan, gluten-free), product pricing tiers.
Local SEO & Schema.org: Automated JSON-LD structured data, OpenGraph cards, breadcrumbs.
Mobile BAU CMS: Rapid phone-based emergency alerts and business hours overrides via EmDash.

4. Bespoke Client Workflows & Domain Nuances (Unstructured)

Unique business rules that do not fit into standard horizontal capabilities (e.g. forwarding high-value catering inquiries to a legacy Square POS terminal, or handling custom vehicle VIN lookups).
Special customer instructions, local community awards, or regulatory disclosures.

5. Raw Discovery Transcript & Notes

Free-form interview transcripts, owner audio notes, handwritten meeting bullet points, or unstructured WhatsApp/email threads.

4. Technical Plumbing Scaffolding Blueprint

When an engineer or AI agent spins up a new client workspace, it must follow the Client-Prefixed Workspace Naming Convention: apps/<client-prefix>-<app-slug>/ (e.g., apps/me-portfolio/, apps/apex-auto/, apps/greenleaf-bakery/).

The Client-Prefixed Naming Invariant: Client applications MUST be slugged or prefixed with the client identifier (<client-prefix>-<app-slug>). If a client later commissions additional web properties (e.g., me-dashboard, me-docs), they live cleanly under the client’s namespace without collision or ambiguity.

4.1 Minimal Workspace Topology

apps/<client-prefix>-<app-slug>/
├── package.json               # Monorepo workspace package manifest
├── tsconfig.json              # TypeScript configuration extending monorepo root
├── astro.config.mjs           # Astro configuration (output: 'static')
├── wrangler.jsonc             # Cloudflare edge runtime config (zero-KV sessions)
├── swarm.config.ts            # Type-safe capability governance manifest
├── tailwind.config.mjs        # (Optional) Client-specific styling setup
├── public/
│   ├── favicon.svg            # Client favicon
│   ├── robots.txt             # Search crawler directives
│   └── assets/                # Self-contained client images and brand media
└── src/
    ├── layouts/
    │   └── BaseLayout.astro   # Minimal HTML document envelope (SEO, meta tags, fonts)
    ├── pages/
    │   ├── index.astro        # Bespoke homepage (prerender = true)
    │   └── api/
    │       └── health.ts      # Edge synthetic health probe (prerender = false)
    ├── components/            # Bespoke client-specific components (no shared UI)
    └── styles/
        └── global.css         # Client-specific typography & base CSS

4.2 Standard Configuration Blueprints

1. `package.json`

Every client app defines a private workspace package importing required headless capability packages and shared governance contracts:

{
  "name": "@siteswarm/app-<client-prefix>-<app-slug>",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "check": "astro check"
  },
  "dependencies": {
    "@astrojs/check": "^0.9.4",
    "@astrojs/cloudflare": "^12.2.0",
    "@siteswarm/governance": "workspace:*",
    "@siteswarm/lead-capture": "workspace:*",
    "@siteswarm/seo": "workspace:*",
    "astro": "^5.4.2",
    "typescript": "^5.8.2"
  },
  "devDependencies": {
    "@types/node": "^26.6.3"
  }
}

2. `astro.config.mjs`

Enforces the Static-First Invariant (output: "static") and configures @astrojs/cloudflare with the passthrough image service:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
  output: "static",
  adapter: cloudflare({
    imageService: "passthrough",
  }),
});

3. `wrangler.jsonc`

Enforces the Zero-Session-KV Guarantee (ADR-0003) and configures service bindings to platform services:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "<client-prefix>-<app-slug>",
  "main": "./dist/_worker.js/index.js",
  "compatibility_date": "2024-12-01",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "binding": "ASSETS",
    "directory": "./dist"
  },
  "services": [
    {
      "binding": "LEADS_SERVICE",
      "service": "siteswarm-leads-service"
    }
  ]
}

4. `swarm.config.ts`

Formalizes the client’s declared capabilities in the type-safe governance engine:

import { defineAppConfig } from "@siteswarm/governance";

export default defineAppConfig({
  appId: "<client-slug>",
  name: "Client Business Name",
  brand: {
    primaryColor: "#HEXCODE",
    accentColor: "#HEXCODE",
    fontFamilyHeading: "'Serif or Sans Name', serif",
    fontFamilyBody: "'Body Font Name', sans-serif",
    logoAssetPath: "public/assets/logo.svg",
  },
  deployment: {
    productionDomain: "clientdomain.com",
    stagingDomain: "staging.clientdomain.siteswarm.dev",
    cloudPlatform: "cloudflare",
  },
  capabilities: {
    "lead-capture": {
      type: "horizontal",
      version: "1.2.0",
      targets: [
        "src/components/ContactForm.astro",
        "src/pages/api/submit-inquiry.ts",
      ],
      options: {
        provider: "turnstile",
        notifyChannel: "sms",
        storeSubmissions: true,
      },
      storage: {
        mode: "platform-shared",
        serviceBindingName: "LEADS_SERVICE",
      },
    },
    "dynamic-seo": {
      type: "horizontal",
      version: "1.4.0",
      targets: ["src/layouts/BaseLayout.astro"],
      options: {
        schemaType: "LocalBusiness",
        enableBreadcrumbs: true,
        generateOpenGraphImages: true,
      },
      storage: {
        mode: "static-only",
      },
    },
    health: {
      type: "horizontal",
      version: "1.0.0",
      targets: ["src/pages/api/health.ts"],
      options: {
        endpoint: "/api/health",
      },
      storage: {
        mode: "static-only",
      },
    },
  },
});

4.3 Client Vibe, Tone & Aesthetic Taste Vectors (`VIBE.md`)

While swarm.config.ts formalizes machine-readable capability targets and deployment bindings, client personality, voice, and design restraint cannot be reduced to rigid TypeScript tokens.

To bridge human taste and autonomous AI agent execution, every client application in apps/<client-prefix>-<app-slug>/ MUST contain an authoritative, human-first Markdown document: VIBE.md.

The `VIBE.md` Standard Contract

A valid VIBE.md document MUST include the following core sections:

## Voice & Persona: Identifies the client’s archetype (e.g. Understated Systems Craftsman, Warm Neighborhood Baker, Straightforward Local Mechanic), authentic emotional register, and conversational posture.
## Posture & Aesthetic Restraint: Defines typographic discipline, whitespace ratio, copy density (concise-factual vs. narrative), visual hierarchy, and contrast boundaries.
## Badge Tolerance: Specifies explicit numeric and stylistic caps on visual noise, badges, and pill tags (e.g., hard cap of 1 badge per visual card, prohibition of stacked colored status pills).
## Banned Patterns & AI Slop Registry: Documents negative constraints and explicit forbidden phrases (e.g., corporate parody buzzwords like “Flagship Architecture”, “Master Engineer”, “Initiate Direct Dialogue”, faux-terminal diagrams, accordion drawers hiding core case studies).
## Good vs. Bad Examples: Provides concrete, side-by-side phrasing and layout calibrations (pass vs. fail) to ground AI agents before generating first drafts.

5. Conversational Agent Briefing Protocol

Because SiteSwarm relies on autonomous AI coding agents to author client implementations, context injection must be clear, complete, and grounded in ground-truth repository assets.

5.1 The Conversational Briefing Pattern

When assigning a coding agent to build or refine a client application:

Provide the Client Intake Epic: Direct the agent to read the parent GitHub Issue Epic (epic(client-<client-prefix>): client intake & onboarding - <Client Name>) for exact business facts, hours, phone numbers, brand colors, and aesthetic vibe notes.
Mandate Ingesting VIBE.md: Explicitly instruct the agent to read apps/<app>/VIBE.md before generating any copy, layout, or styling. The agent MUST adhere to the client’s declared archetype, posture, badge limits, and banned phrases.
Point to Living Blueprints: Point the agent to sibling applications (apps/bakery/, apps/auto-repair/, apps/software-agency/) for verified plumbing patterns, Astro page structure, and headless capability mounting.
Reiterate the Anti-Theming Invariant: Explicitly instruct the agent to write bespoke markup and CSS matching the client’s distinct aesthetic. Forbid the creation of generic UI token abstractions or shared styling components.
Mandate Verification Commands: Instruct the agent to run pnpm swarm audit --app <client-prefix>-<app-slug> and project verification tests before concluding.
Enforce the Builder Liberties Protocol: Instruct the agent to exercise high-taste creative liberties rather than stalling on open-ended specifications, build interactive variations via dev query param switchers (?variant=...), document all liberties in PRs, and promote unresolved commercial, legal, and domain questions to the human operator.

5.2 Conversational Prompt Example

You are building the client application for **Jacob Miller** in `apps/me-portfolio/`.

1. **Client Context**: Read GitHub Issue Epic #119 for all factual discovery details (professional profile, contact routing, brand colors). Do not fabricate facts or invent contact info.
2. **Client Vibe & Taste Vectors**: Read `apps/me-portfolio/VIBE.md` thoroughly. Strictly embody the *Understated Systems Craftsman* persona. Enforce zero corporate PR buzzwords, limit badges to a maximum of 1 per card, and avoid faux-terminal ASCII boxes.
3. **Living Blueprints**: Reference `apps/software-agency/` for architectural plumbing conventions and headless capability mounting.
4. **Bespoke UI Mandate**: Author 100% bespoke Astro markup and styling in `src/pages/` reflecting the client's Clean Warm Editorial aesthetic (`#FAF7F2` canvas, high-character serif headings, hairline borders). Do NOT create shared theme tokens or generic UI adapters.
5. **Capability Wiring**: Mount headless capability engines from `@siteswarm/lead-capture` and `@siteswarm/seo`.
6. **Builder Liberties Protocol**: When micro-copy, typography pairing nuances, or layout compositions are unspecified, take opinionated, high-taste defaults. Do not stall on minor questions. Maintain an explicit audit trail of liberties taken in your PR description using standard callout blocks, build toggleable options for alternative hero layouts (`?variant=grid`), and flag any open domain/legal questions for client review.
7. **Verification**: Verify that `pnpm swarm audit --app me-portfolio` and `pnpm run check` pass cleanly with zero errors.

6. The 3-Pillar Ambiguity Resolution & Builder Liberties Protocol

In high-velocity AI-amplified agency workflows, the primary operational bottleneck is not code generation—it is indecision and micro-stalls. Traditional agency projects stall when engineers or junior staff stop work to ask the client dozens of trivial questions (e.g., “What font weight should the subtitle be?”, “Should the button be 4px or 8px rounded?”, “What shade of cream should the paper background use?”).

SiteSwarm eliminates micro-stalls through an explicit operational compact: The 3-Pillar Ambiguity Resolution & Builder Liberties Protocol.

flowchart TD
    subgraph AmbiguityDetection["Client Intake / Discovery Ambiguity"]
        Ambiguity["Unspecified Detail or Open-Ended Requirement"]
    end

    Ambiguity --> Check{"Domain Gatekeeper:\nCommercial / Legal / Identity?"}

    Check -- "YES (High Risk)" --> P1["Pillar 1: Explicit Ambiguity Log\n(Questions for Client Review)\nEscalate to Human Operator & Section 8.1"]

    Check -- "NO (Creative / UX / Plumbing)" --> P2["Pillar 2: Builder Liberties Taken\n(High-Taste Plausible Defaults)\nExecute immediately & log in Section 8.2"]

    P2 --> MultiOption{"Multiple Plausible\nAesthetic / Layout Options?"}
    MultiOption -- "YES" --> P3["Pillar 3: Multi-Option Prototypes\n(Interactive Options Explored)\nClient-side dev toggle / ?variant=... switcher"]
    MultiOption -- "NO" --> Forward["Direct High-Velocity Implementation"]

    P1 --> Promotion["Two-Tier Promotion Model\nPR Descriptions & Milestone Comments ➔ Epic Section 8"]
    P2 --> Promotion
    P3 --> Promotion

6.1 Pillar 1: Explicit Ambiguity Log (“Questions for Client Review”)

When an ambiguity directly impacts client legal liability, real-world finance, DNS authority, or critical identity routing, autonomous guessing is strictly forbidden. The agent immediately records the item in the Explicit Ambiguity Log:

Scope: Production DNS cutover permissions, third-party payment gateway credentials, formal terms of service / privacy policies, official state licensing numbers, and verified owner notification endpoints.
Action: Formulate a crisp, decision-ready question with recommended options, documented in milestone comments and logged in Section 8.1 of the parent GitHub Intake Epic for human operator resolution.

6.2 Pillar 2: Documented Builder Liberties (“Liberties & Defaults Taken”)

When an ambiguity concerns creative styling, visual composition, micro-copy, typography pairing, or non-commercial component plumbing, the agent is mandated to exercise builder liberties:

Philosophy: Forward momentum over micro-interrogation. Stalling to ask trivial questions degrades velocity. The agent acts with high agency, selecting an authoritative, high-taste, plausible default that harmonizes with the client’s brand vibe and industry conventions.
Audit Invariant: Every liberty taken must be documented. The agent records the context, the decision made, and the architectural or aesthetic rationale in issue comments, PR bodies, and Section 8.2 of the Client Intake Epic. This ensures full transparency for the human operator (the Client Mirror) prior to client review.

6.3 Pillar 3: Multi-Option Prototypes (“Interactive Options Explored”)

When an ambiguity presents two or three equally strong, distinct creative or architectural directions (e.g., a split-screen editorial hero vs. a centered minimalist hero; or a 2x2 grid vs. a stacked timeline showcase), agents do not engage in abstract conceptual debate.

Pattern: Client-Side Dev/Preview Toggle & Query Parameter Switcher: Agents build both working options into the component, governed by a lightweight client-side preview switcher. In development and PR preview builds, visitors can toggle options via URL query parameters (e.g., ?variant=split vs. ?variant=grid) or an unobtrusive preview bar. In production static builds, the switcher compiles away or defaults cleanly to the primary chosen variant.
Client Leverage: The human operator and client evaluate living, tactile UI variations in their actual browser on mobile and desktop, making decisions in seconds based on concrete software rather than mockups or theories.

6.4 Strict Domain Separation Guardrails

To prevent both stagnation and catastrophic assumptions, SiteSwarm enforces strict domain separation:

Category	Protocol Treatment	Permitted Autonomous Liberties
Creative & Aesthetic Design	Pillar 2 (Builder Liberties)	Layout grid composition, typography font pairing matching brand vibe, exact spacing and whitespace rhythms, accent color highlights, micro-animations, hairline borders, and responsive breakpoints.
Micro-Copy & Narrative Polish	Pillar 2 (Builder Liberties)	Section headlines, button CTA copy, subtitle polish, placeholder project descriptions, and industry-standard boilerplate (e.g. copyright notices).
Component Plumbing & Architecture	Pillar 2 (Builder Liberties)	Component decomposition, Astro island boundaries, static collection schemas, zero-KV edge configuration, and build optimizations.
Commercial & Pricing Models	Pillar 1 (Escalation Gate)	Strictly Forbidden. Base rates, hourly pricing, service fee tiers, discounts, or deposit percentages require direct client verification.
Legal & Regulatory Compliance	Pillar 1 (Escalation Gate)	Strictly Forbidden. Disclaimers, warranties, liability terms, privacy policy specifics, state trade licenses, and health certifications.
Domain, DNS & Identity Routing	Pillar 1 (Escalation Gate)	Strictly Forbidden. Production domain delegation, nameserver cutover, live customer inquiry forwarding emails, and SMS alert destination numbers.

6.5 Two-Tier Promotion Protocol & Comment Standards

To ensure liberties and open questions seamlessly reach the human operator without getting lost in closed PRs, SiteSwarm defines a Two-Tier Promotion Model:

Tier 1: PR Description & Milestone Comment Callouts: Every PR modifying client applications must include standardized GitHub-flavored Markdown callout blocks:

> [!NOTE]
> ### 🎨 Builder Liberties & High-Taste Defaults Taken
> - **Hero Typography**: Selected 'Newsreader' serif paired with 'Plus Jakarta Sans' to satisfy the Clean Warm Editorial vibe.
> - **Color Hierarchy**: Applied #0F766E (Deep Teal) to interactive anchors and #B45309 (Amber) to flagship badges.

> [!IMPORTANT]
> ### 🔍 Open Questions for Client Review
> - [ ] **Domain DNS Delegation**: Confirm whether jacobmiller22.com DNS is hosted in Cloudflare or requires external A-record mapping.
> - [ ] **Resume Asset**: Verify final resume.pdf path and ensure sanitized public availability.

> [!TIP]
> ### 🔀 Interactive Variations Explored
> - **Hero Showcase Variant**: Implemented toggleable grid view via `?variant=grid` alongside default single-flagship showcase (`?variant=flagship`).

Tier 2: Living Promotion into Parent Intake Epic: Prior to closing the task or handing off to the human operator, the agent or engineer promotes the consolidated items directly into Section 8 (Ambiguity Resolution & Builder Liberties Log) of the parent GitHub Issue Epic (epic(client-<prefix>): ...). The Intake Epic remains the authoritative, permanent living source of truth for all client-facing reviews and sign-offs.

7. Monorepo File Taxonomy & Governance Boundaries

To preserve developer velocity while preventing clutter and false CI failures, SiteSwarm strictly delineates governance boundaries:

File Location	Purpose & Format	Governance / CI Check Behavior
`docs/templates/CLIENT_INTAKE_CHECKLIST.md`	Canonical discovery questionnaire and checklist template.	Documented in Living Specs; reviewed during PRs.
GitHub Issue Epics (`epic(client-<prefix>): ...`)	Live tracker of raw client discovery facts, owner interviews, and aesthetic context.	Completely outside git repository. Zero repo commit clutter, native async review comments, milestone checkboxes.
`apps/<client-prefix>-<app-slug>/`	Standalone client application workspace.	Strictly governed. Verified by `pnpm swarm audit`, AST linters (`pnpm swarm lint`), TypeScript typechecks, and e2e test suites.
`packages/capabilities/*`	Headless platform capability engines.	Verified by AST linters for Headless Invariants (no JSX/Astro/CSS).

8. Multi-Client Validation Matrix

The intake checklist and living blueprint model have been ground-truthed across both prototype and production client applications:

Client Application	Business Vertical	Living Reference / Intake Source	Unique Aesthetic & Capability Footprint
Jacob Miller (`apps/me-portfolio`)	Personal & Software Engineering Practice	Epic #119	Clean Warm Editorial (`#FAF7F2` canvas, serif typography), dynamic CMS project showcase, sanitized enterprise case studies, Turnstile lead capture.
Green Leaf Bakery (`apps/bakery`)	Food & Beverage / Artisan Bakery	Prototype Client Blueprint	Warm wood tones, serif typography (`Fraunces`), pastry menu catalog, catering quote estimator, legacy POS sync vertical.
Apex Auto Care (`apps/auto-repair`)	Automotive Repair & Fleet Maintenance	Prototype Client Blueprint	High-contrast industrial dark mode, bold sans typography, instant brake/oil service estimator, urgent phone call-to-actions.
Apex Labs (`apps/software-agency`)	Professional Tech & Software Services	Prototype Client Blueprint	Clean minimalist modernism, monochrome palette with electric cyan accents, client intake inquiries, dynamic SEO.

9. Summary & Downstream Milestones

By establishing the Living Blueprint Scaffolding Model, Open-Ended Client Discovery Intake, and Builder Liberties Protocol, Epic #37 and Issue #128 complete Wave 2B of Phase 2 under Initiative #104.

Immediate Downstream Unblocks:
- Portfolio Onboarding (Epic #119): First production client execution using the Builder Liberties Protocol.
- Wave 2C (Epic #38): Content Invalidation, Edge Caching, and Data Freshness Model.
- Phase 3 (Epic #5): SiteSwarm Marketing Website (apps/marketing) which will incorporate a public client intake submission flow based on this discovery taxonomy.

Client Business Intake & Technical Scaffolding Blueprint Specification

Client Business Intake & Technical Scaffolding Blueprint Specification

1. Executive Summary & Design Rationale

1.1 The AI-Amplified Agency Operating Model & Human-in-the-Loop Reality

1.2 The Agency Trade-Off Dilemma

2. Core Architectural Invariants

2.1 The Anti-Theming & Zero Visual Templating Invariant

2.2 The Living Blueprint Invariant

3. The Client Discovery Intake Framework

3.1 Two-Tier Intake Architecture & GitHub Issue Tracking

3.2 Standard Client Onboarding Lifecycle (Child Issues)

3.3 Canonical Intake Checklist Taxonomy

1. Business Identity & Operating Facts

2. Raw Brand Assets & Aesthetic Vibe Context

3. Platform Capability Requirements (Wishlist)

4. Bespoke Client Workflows & Domain Nuances (Unstructured)

5. Raw Discovery Transcript & Notes

4. Technical Plumbing Scaffolding Blueprint

4.1 Minimal Workspace Topology

4.2 Standard Configuration Blueprints

1. package.json

2. astro.config.mjs

3. wrangler.jsonc

4. swarm.config.ts

4.3 Client Vibe, Tone & Aesthetic Taste Vectors (VIBE.md)

The VIBE.md Standard Contract

5. Conversational Agent Briefing Protocol

5.1 The Conversational Briefing Pattern

5.2 Conversational Prompt Example

6. The 3-Pillar Ambiguity Resolution & Builder Liberties Protocol

6.1 Pillar 1: Explicit Ambiguity Log (“Questions for Client Review”)

6.2 Pillar 2: Documented Builder Liberties (“Liberties & Defaults Taken”)

6.3 Pillar 3: Multi-Option Prototypes (“Interactive Options Explored”)

6.4 Strict Domain Separation Guardrails

6.5 Two-Tier Promotion Protocol & Comment Standards

7. Monorepo File Taxonomy & Governance Boundaries

8. Multi-Client Validation Matrix

9. Summary & Downstream Milestones

1. `package.json`

2. `astro.config.mjs`

3. `wrangler.jsonc`

4. `swarm.config.ts`

4.3 Client Vibe, Tone & Aesthetic Taste Vectors (`VIBE.md`)

The `VIBE.md` Standard Contract