geolocal-io/docs/archive/ssp-form-spec-superseded.md

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