# SSP Form-Based Screen Spec — Superseded

**Archived:** 2026-07-29
**Superseded by:** UC-04 (Conversational SSP — First Hour), UC-05 (Conversational SSP — Ongoing)
**Source:** `docs/product/ssp-refined.md` §3, §6 (legacy flow), §7, §9

---

## Decision Note

> **Why cut:** Ty decided "chat replaces forms entirely" (Decision #4, SSP Refinement channel, 2026-07-29). The entire form-based activation path — 5-screen wizard with signup, manual data entry, scrape reflection, pointer install, and live status — is replaced by a single conversational flow. The form screens are retained here for historical traceability and as a reference for the structured data fields that the conversational flow must still capture.

---

## Screen 1: Signup

**Purpose:** Create an account tied to one business. No OAuth — email + password only for MVP.

**Fields:**
- Email (required, validated format)
- Password (required, min 8 chars)
- Password confirm (required, must match)

**Behavior:**
- Creates a `tenants` row (email, password hash, status = 'active')
- Creates a `businesses` row with status = 'draft'
- Associates tenant with business via FK
- Redirects to Screen 2 (Business Info)
- No email verification for MVP (defer)

**Errors:**
- Email already registered → "Account exists. Try signing in." (add signin link)
- Password mismatch → "Passwords don't match"
- Empty required field → inline validation

---

## Screen 2: Business Info Capture

**Purpose:** Collect the structured data that becomes the MCP payload.

**Fields (organized in sections):**

**Identity:**
- Business name (required)
- Business slug (auto-generated from name, editable, unique)
- Category (required, select from predefined list)
- Description / story (optional, textarea)

**Location:**
- Street address (optional but encouraged)
- City, State, ZIP (optional)
- Phone (optional)
- Website URL (optional — used for scrape reflection)

**Operations:**
- Hours (JSON structure: Mon-Sun open/close, plus holiday override flag)
- Services (array of name/description pairs)
- Booking link (optional, URL — Cal.com or equivalent)

**Schema mapping:**

| Field | businesses column |
|-------|-------------------|
| Business name | `name` |
| Slug | `slug` |
| Category | `category` |
| Description | `story` |
| Address fields | `address`, `city`, `state`, `zip` |
| Phone | `phone` |
| Website | `website` |
| Hours | `hours` (JSONB) |
| Services | `services` (JSONB) |
| Booking link | `calcom_link` |

---

## Screen 3: Scrape Reflection

**Purpose:** Show the owner what the platform already sees on their website — and where there are gaps.

**Input:** Website URL from Screen 2.

**Behavior:**
- One-time scrape triggered when user clicks "Analyze my site"
- Parse public HTML for: business name, hours, services, phone, address, booking links
- Display side-by-side comparison (green check / yellow warning / red X)
- "Use what we found" button to auto-populate gaps from scrape
- "Skip" button to proceed without scrape

**Technical notes:**
- Scrape runs server-side (not client-side — CORS)
- Timeout: 10 seconds per page
- No JS rendering for MVP (static HTML only)
- Rate limit: one scrape per signup session

---

## Screen 4: Pointer Install

**Purpose:** Give the owner concrete instructions to attach a discovery pointer on their website.

**Options:**
- A: `.well-known/mcp-server` (preferred)
- B: DNS CNAME (for static sites / hosted platforms)
- C: Link tag (quick test)

**Verification:**
- "Verify" button triggers a server-side fetch of the pointer location
- Proceed without verification allowed (unverified badge)

---

## Screen 5: Live Status

**Purpose:** Confirm the endpoint is live and show what an AI agent sees.

**Content:**
- Status banner: Green (discoverable) / Yellow (almost live) / Red (not ready)
- MCP Preview: actual JSON response for `get_business_info`
- Preflight Checklist: required fields verified
- Actions: edit, re-verify, share endpoint URL

---

## Legacy Form Flow Diagram

```
Owner arrives at geolocal.io
  |
  v
[Screen 1] Signup (email + password)
  | creates tenant + business(draft)
  v
[Screen 2] Business Info Capture (manual entry)
  | populates businesses row
  v
[Screen 3] Scrape Reflection (one-time, optional)
  | compares site content vs entered data
  | owner confirms or edits
  v
[Screen 4] Pointer Install (instructions + verify)
  | owner installs .well-known/mcp-server or CNAME
  | platform verifies pointer
  v
[Screen 5] Live Status
  | status = 'active'
  | preflight passes
  | MCP endpoint live at /mcp/{slug}
```

---

## Screen-Based Acceptance Criteria (Superseded)

### Screen 1: Signup
- [ ] User can create an account with email + password
- [ ] Duplicate email is rejected
- [ ] Tenant row created with correct business_id FK
- [ ] Business row created with status = 'draft'

### Screen 2: Business Info
- [ ] All fields save to businesses row
- [ ] Slug is auto-generated, editable, unique
- [ ] Category is required (from predefined list)
- [ ] Services can be added/removed (min 1)
- [ ] Hours captured as JSONB

### Screen 3: Scrape Reflection
- [ ] Server-side scrape of provided URL (10s timeout)
- [ ] Side-by-side comparison displayed
- [ ] "Use what we found" populates gaps
- [ ] Skippable (proceed without scrape)

### Screen 4: Pointer Install
- [ ] Three pointer options presented (well-known, CNAME, link tag)
- [ ] Verification fetches and validates pointer
- [ ] Proceed without verification allowed (unverified badge)

### Screen 5: Live Status
- [ ] Status banner reflects endpoint state
- [ ] MCP preview shows actual JSON response
- [ ] Preflight checklist is accurate
- [ ] Setting status = 'active' makes endpoint queryable

### Cross-cutting
- [ ] HTTP transport replaces stdio for `/mcp/{slug}`
- [ ] Slug-based routing returns correct business data
- [ ] Done-when criteria 1-4 are all satisfied

---

## What Changed from Original SSP Spec (Historical)

| Area | Before | After |
|------|--------|-------|
| Length | 14 lines | Implementation-ready |
| Screens | Named but not described | 5 screens with fields, behavior, errors |
| Data model | Not specified | Schema with status column, tenants table |
| Scrape | Mentioned | One-time on signup, side-by-side comparison |
| Pointer | Mentioned | 3 options with verification flow |
| Transport | Not decided | Streamable-HTTP with decision record |
| Quality flags | Separate table | Status column on businesses |
| Acceptance criteria | None | Per-screen + cross-cutting |