archive: supersede form-based SSP spec with decision notes

Archive the 5-screen form wizard spec (signup → data entry → scrape → pointer install → live status) as superseded by the conversational flow (UC-04/UC-05). Preserved for structured data field reference and historical traceability.
2026-07-31 19:34:08 -07:00
parent 1e66fe135a
commit 2aa7a2cf97
2 changed files with 205 additions and 0 deletions
@@ -7,5 +7,6 @@ Historical materials kept for context. **Not operating documentation.**
 | [geolocal-copilot-conversation.md](./geolocal-copilot-conversation.md) | Early exploration conversation that informed the strategy |
 | [copilot-activity-history.csv](./copilot-activity-history.csv) | Activity export from that session |
 | [ssp-v1.md](./ssp-v1.md) | Original SSP intent doc — superseded by [ssp-refined.md](../product/ssp-refined.md) (2026-07-30) |
+| [ssp-form-spec-superseded.md](./ssp-form-spec-superseded.md) | Form-based screen spec (5-screen wizard) — superseded by conversational flow (UC-04/UC-05). Decision: chat replaces forms entirely (2026-07-29) |

 Operating truth lives in [../strategy/CANONICAL_STRATEGY.md](../strategy/CANONICAL_STRATEGY.md).
@@ -0,0 +1,204 @@
+# 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 |