Skip to content
SiteSwarm Platform Documentation

Client Intake And Onboarding

Client Intake & Onboarding Runbook

1. Purpose & Lifecycle Overview

This runbook defines the operational workflow for onboarding a new client business into SiteSwarm.

Client onboarding follows three sequential phases:

  1. Phase 1 — Discovery Conversation: Unstructured or semi-structured conversation with the business owner to understand their business model, customer base, physical locations, pain points, and existing digital assets.
  2. Phase 2 — Post-Discovery KYC & Scope Synthesis: Translating raw discovery notes into the structured post-call intake checklist (CLIENT_INTAKE_CHECKLIST.md) to capture Know-Your-Customer (KYC) records, the full scope of work (locations, number of web properties/sites, and business-specific operational workflows), and open escalation questions.
  3. Phase 3 — Workspace Initialization & Vibe Definition: Creating or promoting the client workspace(s) using client-prefixed naming (apps/<client-prefix>-<site-slug>/ so clients with multiple locations or sister sites coexist cleanly), connecting capabilities in the client manifest (CAPABILITY_MANAGEMENT.md, CLIENT_INQUIRY_INTAKE_ONBOARDING.md), and authoring or ratifying the client’s VIBE.md voice and aesthetic direction contract.
    • Supported Phase 3 Entry Points:
      • Greenfield Scaffolding: Standard entry point for direct inbound clients onboarded without a prior prototype.
      • Prototype-to-Client Promotion: Fast-track entry point for signed prospects who already have an active pre-awareness edge prototype (apps/proto-<slug>/). Rather than re-scaffolding from scratch, Phase 3 executes the in-place promotion procedure (preserving Git commit pedigree via git mv, synchronizing monorepo package manifests, provisioning dedicated Cloudflare D1/R2 infrastructure, ingesting remote CDN assets, and wiring custom domain ingress per CLOUDFLARE_FOR_PLATFORMS_AND_DOMAIN_INGRESS.md).

2. Resolving Ambiguities: Builder Liberties vs. Client Escalation

Discovery conversations rarely answer every implementation detail upfront. To maintain delivery velocity without making unauthorized business or legal commitments, intake staff and agents resolve ambiguities using strict domain separation:

Domain Category Resolution Path Operational Policy
Creative & Aesthetic Layout Builder Liberties Layout composition, typography pairings matching the client’s vibe, spacing rhythms, and responsive breakpoints are executed with high-taste defaults and logged for review.
Micro-Copy & UX Polish Builder Liberties Section headlines, call-to-action phrasing, and toggleable preview variations (?variant=...) are prototyped directly.
Commercial & Pricing Models Client Escalation Gate Never assumed. Service rates, fee tiers, discounts, or deposit terms require explicit client verification.
Legal & Regulatory Compliance Client Escalation Gate Never assumed. Disclaimers, warranties, privacy policies, trade licenses, and certifications require explicit client sign-off.
Domain, DNS & Identity Routing Client Escalation Gate Never assumed. Production DNS cutover (CLOUDFLARE_FOR_PLATFORMS_AND_DOMAIN_INGRESS.md), live inquiry forwarding email addresses, and SMS alert phone numbers require explicit verification.

3. Phase 3 Detail: Prototype-to-Client Promotion Lifecycle

When onboarding a signed client whose engagement originated as an interactive pre-awareness edge prototype (under Epic #575 and the prototype promotion procedure codified in #578 / candidate runbook PROTOTYPE_TO_CLIENT_PROMOTION.md), Phase 3 executes an auditable in-place promotion workflow rather than a blank scaffold:

flowchart LR
    Proto["apps/proto-<slug>\n(Pre-Awareness Prototype)"] --> GitMv["In-Place Rename\n(git mv apps/proto-<slug> apps/<client-prefix>-<site-slug>)"]
    GitMv --> Sync["Workspace Sync\n(package.json, swarm.config.ts, wrangler.jsonc)"]
    Sync --> Infra["Dedicated Cloudflare Infra\n(Dedicated D1 SQLite & Dedicated R2 Bucket)"]
    Infra --> AssetMigrate["Asset Ingestion\n(Audit CDN Hotlinks -> Ingest to R2)"]
    AssetMigrate --> Ingress["Platforms Ingress\n(Dual Route Binding: Custom + CNAME Target)"]
    Ingress --> ProductionTenant["Production Tenant\n(apps/<client-prefix>-<site-slug>)"]

3.1 Promotion Execution Checklist

  1. Lineage Pre-Flight & Working Tree Audit:
    • Confirm commercial contract execution and onboarding deposit receipt.
    • Cross-reference CLIENT_INTAKE_CHECKLIST.md §2.1 (Prototype Lineage) and §5.3 (Ratified Builder Liberties).
    • Ensure the source prototype directory (apps/proto-<slug>/) has 0 uncommitted changes.
  2. In-Place Directory Rename (git mv):
    • Run git mv apps/proto-<slug> apps/<client-prefix>-<site-slug>.
    • Never duplicate or copy-paste directories (cp -r is forbidden) to preserve 100% of commit history, blame, and author attribution.
  3. Workspace Manifest & Configuration Synchronization:
    • Update apps/<client-prefix>-<site-slug>/package.json package name to @siteswarm/app-<client-prefix>-<site-slug>.
    • Run pnpm install to update the monorepo workspace dependency graph.
    • Register root scripts (dev:<client-prefix>-<site-slug>, build:<client-prefix>-<site-slug>) in root package.json.
    • Author or update swarm.config.ts using @siteswarm/governance to register tenant metadata, brand tokens, and capabilities.
    • Update wrangler.jsonc with the new Worker isolate name, APP_ID, and environment blocks (staging, production). Ensure session: false is configured in Astro to prevent orphaned preview KV namespaces.
  4. Dedicated Cloudflare Tenant Infrastructure:
    • Provision dedicated Cloudflare D1 SQLite database(s) (wrangler d1 create <client-prefix>-<site-slug>-prod-d1 and -staging-d1).
    • If the prototype was escalated to Phase 3 with local SQLite schemas, execute remote schema and seed migrations (schema.sql / seed.sql).
    • Provision dedicated Cloudflare R2 media bucket(s) (wrangler r2 bucket create <client-prefix>-<site-slug>-media-prod and -staging).
    • Register the D1 and R2 bindings in wrangler.jsonc (or Worker B CMS for split architectures).
  5. Remote Asset Migration & R2 Ingestion:
    • Audit external media hotlinks in src/ (e.g. Unsplash, external prospect sites).
    • Ingest all remote assets into the client’s dedicated R2 bucket using Wrangler.
    • Refactor image references to tenant-hosted paths and verify 0 unmanaged external CDN hotlinks remain in production markup.
  6. Cloudflare for Platforms Domain Ingress:
    • Create the client’s dedicated CNAME target (<client-prefix>-<site-slug>-ingress.<platform-domain>) pointing to fallback.<platform-domain> on the platform zone.
    • Register the custom hostname (www.<client-domain>.com) with DCV TXT pre-validation for zero-downtime SSL issuance.
    • Configure Dual Worker Route Bindings in wrangler.jsonc (www.<client-domain>.com/* and <client-prefix>-<site-slug>-ingress.<platform-domain>/*) per CLOUDFLARE_FOR_PLATFORMS_AND_DOMAIN_INGRESS.md to guarantee resilience across Grey Cloud and Orange Cloud (O2O) DNS modes.
    • Guide client through updating their www CNAME and root @ forwarding without modifying authoritative nameservers or touching MX email records.
  7. Zero-Lockout Data Portability Verification:
    • Promoted tenants must maintain 100% data portability guaranteed by CLIENT_OFFBOARDING.md and Issue #207.
    • Verify that the client’s dedicated D1 database can be atomically exported (wrangler d1 export <client-db> --remote --output=<client>-export.sql or pnpm swarm export-client <client-slug>).
    • Verify that all media assets in R2 can be cleanly extracted into a portable archive bundle in under 5 minutes.