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.
strategy: rewrite section 13 milestones to board-distribution model
2026-07-31 19:34:08 -07:00 · 2026-07-30 03:34:19 -07:00 · 2026-07-29 19:28:03 -07:00
6 changed files with 272 additions and 41 deletions
@@ -6,5 +6,7 @@ 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 |
@@ -0,0 +1,35 @@
 # Self-Service Portal (SSP) — v1 (Archived)
 > **Archived:** 2026-07-30
 > **Superseded by:** [docs/product/ssp-refined.md](../product/ssp-refined.md)
 > **Decision:** The original SSP doc was a thin intent sketch — good for early alignment but insufficient as an operating spec. The refined version adds:
 > - Full conversational activation flow (no form-based fallback)
 > - Two-phase relationship model (First Hour + First Month+)
 > - Detailed UX spec with personality and tone
 > - Integration with UC-04 and UC-05 use cases
 > - Owner MCP tool definitions
 > - Product decision record (five decisions from SSP Refinement channel, 2026-07-29)
 > **Reason for archiving:** Original doc preserved for historical context and traceability. Do not use as reference for implementation.
 ---
 *Original content below (as of archiving):*
 # Self-Service Portal (SSP)
 Activation experience for individual local businesses (Model 1). Important, not the whole company.
 ## Intent
 Owners should feel the value before they pay: genre-aware onboarding, site scrape reflection, a live simulation of an external AI recommending and booking them, pointer install, in-browser preflight against their MCP, optimization guidance, optional partner handoff, and ongoing reports.
 The portal chat UI is a **test harness** for how external assistants will interpret the business — not a customer-facing chatbot product.
 ## Spec source of truth
 - Narrative: [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (product definition + priorities)
 - Operating use case: [UC-01](./use-cases/uc-01-endpoint-auto-repair.md)
 ## Build status
 Not implemented. Engineering Priority 0 includes portal spine after HTTP MCP is real enough to preflight against.
@@ -7,7 +7,7 @@ Product definitions for what we build and sell. Align with [Canonical Strategy](
 1. [overview.md](./overview.md) — platform map and surfaces  
 2. [use-cases/](./use-cases/) — canonical specs (start with UC-01 and UC-02)  
 3. [genre-packs.md](./genre-packs.md) — vertical primitives  
-4. [ssp.md](./ssp.md) — Self-Service Portal as **activation**, not the whole product  
+4. [ssp-refined.md](./ssp-refined.md) — Self-Service Portal, refined spec (conversational, two-phase)  
 5. [intermediate.md](./intermediate.md) — tourism/chamber intermediate surface  
 ## Center of gravity
@@ -1,18 +0,0 @@
 # Self-Service Portal (SSP)
 Activation experience for individual local businesses (Model 1). Important, not the whole company.
 ## Intent
 Owners should feel the value before they pay: genre-aware onboarding, site scrape reflection, a live simulation of an external AI recommending and booking them, pointer install, in-browser preflight against their MCP, optimization guidance, optional partner handoff, and ongoing reports.
 The portal chat UI is a **test harness** for how external assistants will interpret the business — not a customer-facing chatbot product.
 ## Spec source of truth
 - Narrative: [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (product definition + priorities)  
 - Operating use case: [UC-01](./use-cases/uc-01-endpoint-auto-repair.md)
 ## Build status
 Not implemented. Engineering Priority 0 includes portal spine after HTTP MCP is real enough to preflight against.
@@ -1,6 +1,6 @@
 # geolocal.io — Canonical Strategy
-**Status:** Final draft (2026-07-18; revised same day for strategic depth and local-retail scope)  
+**Status:** Final draft (2026-07-18; revised 2026-07-29 for conversational SSP, §13 milestones aligned to board-distribution model)  
 **Role:** The document the team plans, builds, and sells against. When other docs disagree with this one, update them — or update this one deliberately. Do not leave the conflict hanging.
 This is an operating strategy, not a product brochure. The Self-Service Portal matters, but it is one activation surface. The company is the platform underneath.
@@ -352,32 +352,40 @@ Tourism board deals use separate pilot or enterprise pricing. Do not block launc
 ## 13. What success looks like
-### First 90 days
+### First 90 days — prime the pump
- Public multi-tenant MCP over HTTP  
+Distribution before direct sales. Land one Chamber of Commerce or Tourism Board partnership and use their member businesses as our first customer segment. The board is the trust signal; the messages come from us and them:
 - Portal spine good enough to activate real owners (scrape, simulation, pointer, preflight)  
 - About 100 live endpoints  
 - One tourism or destination pilot at LOI or live pilot  
 - One or two genre packs  
 - Booking path via Cal.com (link first is acceptable)  
 - First dollars of ARR  
 - Explicit quality rules written (even if enforcement is still manual)
-### By 180 days
+- **Services:** "Make every AI assistant understand and book your business."
 - **Retail:** "Make sure AI can tell people what you actually carry and why you're worth the stop."
- About 1,000 endpoints  
+**Concrete targets:**
- Three genres  
+- One Chamber or Tourism Board at pilot (LOI signed, member list in hand)
- Related-businesses handshake in production  
+- Conversational SSP live and shippable — the **wow experience** owners feel on first interaction
- Several intermediate dashboards active  
+- First cohort of member businesses activated through the board (not cold outbound)
- Telemetry useful for real owner reports  
+- HTTP MCP transport in production with multi-tenant routing
- First decommission or quarantine decisions made with a documented standard
+- Enough live endpoints to show a working registry, not just a demo
 - First dollars of ARR from the pilot
-### By 360 days
+The SSP is the win moment. Owners arrive from the board, describe their business in a chat, and within one session see a visual simulation of an AI assistant recommending them — services listed, booking path found, details correct. That experience is what makes them stay.
- About 10,000 endpoints  
+### 180 days — prove the loop
- Several major chamber or tourism partnerships  
+
- Early anonymized demand or data product in beta or market  
+- Second Chamber or Tourism Board partnership (different geo or vertical)
- Case studies showing assistants prefer geolocal-backed paths in pilot geos  
+- Self-serve SMB motion running in parallel (not just board-distributed)
 - Telemetry showing agents prefer geolocal-backed paths in pilot geos
 - Owner reports that drive returning visits — "here's what changed, here's what to fix"
 - Quality standards documented and first decommission or quarantine decisions made
 - Genre packs for at least two verticals (services first, retail next)
 - Booking path deeper than redirect (Cal.com or peer integrated)
 ### 360 days — scale the model
 - Several major chamber or tourism partnerships active
 - Service graph effects visible — related businesses, demand patterns, competitive context
 - Telemetry and quality enforcement (including decommissioning) as a trust moat
 - Early anonymized demand or data product in beta
 - Case studies showing assistants prefer geolocal-backed paths  
 ---