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 · 2026-07-29 19:16:49 -07:00
9 changed files with 1287 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
@@ -0,0 +1,529 @@
 # Self-Service Portal (SSP) — Refined Spec
 **Status:** Draft (ssp-refinement branch)
 **Author:** Bumble (research), Buzz SouthPaw (engineering review)
 **Date:** 2026-07-29
 **Supersedes:** `docs/product/ssp.md` (thin intent doc)
 **Source documents:**
 - [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) — product definition, priorities, scope
 - [UC-01: Endpoint Activation](./use-cases/uc-01-endpoint-auto-repair.md) — operating use case
 - [UC-04: Conversational SSP — First Hour](./use-cases/uc-04-conversational-ssp-first-hour.md) — conversational onboarding
 - [UC-05: Conversational SSP — Ongoing](./use-cases/uc-05-conversational-ssp-ongoing.md) — ongoing relationship
 - [Owner MCP](../owner-mcp.md) — MCP tool definitions
 - MVP scope (Idea research channel, 2026-07-29) — in/out decisions
 - Product decisions (SSP Refinement channel, 2026-07-29) — five decision record (below)
 ---
 ## 1. Intent
 The SSP is the activation experience for Model 1 (individual local businesses). It turns a business owner's raw info into a live, AI-discoverable MCP endpoint through a **conversational interface** — no forms, no wizards.
 The owner describes their business in natural language, verifies ownership, receives a presence audit, and gets actionable recommendations — all through a ChatGPT-like experience at GeoLocal.io.
 **Two phases, one relationship:**
 - **The First Hour** (UC-04): Verification, presence audit, initial recommendations, guided setup
 - **The First Month+** (UC-05): Ongoing monitoring, data updates, periodic reports, seasonal guidance
 **One line we will not blur:** the conversational SSP is the **only activation path** — no form-based fallback. Chat replaces forms entirely.
 ---
 ## 2. Scope (MVP)
 One conversational flow, zero forms. The goal is the smallest shippable thing that lets one real business owner go from "tell me about my business" to "discoverable by AI" — all through chat.
 ### In (MVP)
 - Conversational welcome and discovery (natural language input)
 - Ownership verification (OTP via email)
 - Presence audit (automated, multi-platform)
 - Actionable recommendations (ranked, platform-specific)
 - Guided setup (conversational data capture, pointer install, preflight)
 - Session persistence (resume later)
 - Landing page with animated demo + "Get Started" CTA
 ### Out (deferred)
 - OAuth / SSO
 - Ingestion pipeline (continuous sync)
 - Genre packs beyond basic category
 - Telemetry dashboard
 - Partner handoff flow
 - Voice input
 - Multi-language support
 - Multi-business accounts
 - Form-based fallback (chat is the only path — see decision record)
 ---
 ## 2.5 Product Decision Record
 **Date:** 2026-07-29
 **Source:** SSP Refinement channel — five decisions from Ty
 | # | Decision | Rationale |
 |---|----------|-----------|
 | 1 | **Landing page with entry point** — GeoLocal.io showcases the experience (animated demo of what the chat feels like) with a clear "Get Started" CTA that launches the conversational flow. Not buried behind a separate URL. | Lower friction; demonstrate value before asking for commitment. |
 | 2 | **LLM: TBD, hosted 8–12B model** — Workflow scripts drive the conversation structure; model selection defers to implementation. The model handles natural language within the workflow-driven flow. | Requirements phase, not design phase. Defer provider choice; lock the structure now. |
 | 3 | **Requirements phase for OTP/email** — OTP-by-email is a verification requirement without implementation detail. No email provider selected yet. | Focus on use cases first; implementation details come later. |
 | 4 | **Chat replaces forms entirely** — No form-based fallback. The conversational SSP is the only activation path. | Clean break; forms are the problem we're solving away. |
 | 5 | **Onboarding becomes ongoing** — Two phases: "The First Hour" (verification + audit + first recommendations) and "The First Month+" (presence updates, new audits, monitoring, ongoing guidance). | One-time activation degrades over time. Ongoing relationship maintains data quality and platform value. |
 ---
 ## 3. Screen-by-Screen Spec (Superseded)
 > ⚠️ **This section is superseded by UC-04 and UC-05.** The screen-by-screen form wizard is replaced by the conversational flow. Retained for reference during transition; remove when conversational implementation is complete.
 ### 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
 **Notes:**
 - One tenant = one business for MVP (multi-business deferred)
 - Password hashing: bcrypt or argon2 (whatever the framework provides)
 ---
 ### Screen 2: Business Info Capture
 **Purpose:** Collect the structured data that becomes the MCP payload. This is the core data entry screen.
 **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 (optional)
 - State (optional)
 - ZIP (optional)
 - Phone (optional)
 - Website URL (optional — used for scrape reflection)
 **Operations:**
 - Hours (JSON structure: Mon-Sun open/close, plus holiday override flag)
  - MVP: simple time picker per day + "closed" toggle
  - Holiday overrides deferred to post-MVP
 - Services (array of name/description pairs)
  - MVP: add/remove rows, no sub-categories
 - Booking link (optional, URL — Cal.com or equivalent)
 **Behavior:**
 - Slug validation: lowercase, hyphenated, unique (check against existing businesses)
 - Save drafts as user types (auto-save to `businesses` row, status = 'draft')
 - "Next: See what we found" button → Screen 3 (Scrape Reflection)
 - Back to signup not needed (one-way flow; edit later from dashboard — deferred)
 **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. This is the "aha" moment.
 **Input:** Website URL from Screen 2.
 **Behavior:**
 - One-time scrape triggered when user clicks "Analyze my site" (or auto-triggers if URL provided)
 - Parse public HTML for: business name, hours, services, phone, address, booking links
 - Display side-by-side comparison:
 ```
 +---------------------+---------------------+
 | What you entered    | What we found       |
 +---------------------+---------------------+
 | Name: Bob's Garage  | Name: Bob's Garage  | (match)
 | Hours: M-F 8-5      | Hours: not found    | (gap)
 | Services: [3 items] | Services: [5 items] | (partial match)
 | Booking: Cal.com    | Booking: not found  | (gap)
 +---------------------+---------------------+
 ```
 **Output:**
 - Green check: field found on site and matches entry
 - Yellow warning: field found but differs from entry (show both values)
 - Red X: field not found on site at all
 - "Use what we found" button to auto-populate gaps from scrape
 - "Skip" button to proceed without scrape (site may not exist yet)
 **Technical notes:**
 - Scrape runs server-side (not client-side — CORS)
 - Timeout: 10 seconds per page
 - No JS rendering for MVP (static HTML only — defer puppeteer/playwright)
 - Store scrape result in a temporary field or session (not persisted to `businesses` until user confirms)
 - Rate limit: one scrape per signup session
 **Deferred:**
 - Continuous sync (ingestion pipeline)
 - JS-rendered page support
 - Image/logo extraction
 ---
 ### Screen 4: Pointer Install
 **Purpose:** Give the owner concrete instructions to attach a discovery pointer on their website so AI agents can find the hosted MCP.
 **Content:**
 **What this does (plain language):**
 > "This installs a tiny marker on your website that tells AI assistants where to find your business data. It takes 2 minutes."
 **Option A: `.well-known/mcp-server` (preferred)**
 Instructions:
 1. Create a file: `yourdomain.com/.well-known/mcp-server`
 2. Contents: `{"mcp": "https://geolocal.io/mcp/{slug}"}`
 3. Upload to your website root (or ask your web host)
 4. Click "Verify" below
 **Option B: DNS CNAME (for static sites / hosted platforms)**
 Instructions:
 1. Add a CNAME record: `mcp.yourdomain.com` → `geolocal.io`
 2. Path: `/mcp/{slug}` will be routed by hostname
 3. DNS propagation: up to 24 hours
 4. Click "Verify" below
 **Option C: Link tag (quick test)**
 Instructions:
 1. Add to your site's `<head>`:
   ```html
   <link rel="mcp" href="https://geolocal.io/mcp/{slug}" />
   ```
 2. Click "Verify" below
 **Verification:**
 - "Verify" button triggers a server-side fetch of the pointer location
 - Success: green check + "Pointer verified" message
 - Failure: plain-language error ("We couldn't find the file at that URL — check the path and try again")
 - DNS CNAME verification: check CNAME record + follow to MCP endpoint
 **Behavior:**
 - Owner can proceed to Screen 5 without verified pointer (endpoint goes live as "unverified")
 - Unverified endpoints show a warning badge in Screen 5
 - No blocking — we want them live even if pointer install takes time
 **Notes:**
 - Multi-path discovery is the strategy (not a single fragile convention)
 - The pointer URL uses the HTTP transport endpoint (see decision record)
 - For MVP, Option A is the primary path; B and C are fallbacks
 ---
 ### Screen 5: Live Status
 **Purpose:** Confirm the endpoint is live and show what an AI agent sees.
 **Content:**
 **Status banner:**
 - Green: "You are discoverable" — MCP endpoint is live and responding
 - Yellow: "Almost live" — MCP is live but pointer not verified
 - Red: "Not ready" — preflight failed (missing required fields)
 **MCP Preview:**
 - Show the actual JSON response an agent would get for `get_business_info` with their slug
 - Collapsible sections for each tool: `get_hours`, `get_services`, `get_booking_link`, `get_related_businesses`
 **Preflight Checklist:**
 - [ ] Business name set
 - [ ] Category set
 - [ ] At least one service entered
 - [ ] Hours entered (at least one day)
 - [ ] Phone or booking link set
 - [ ] Pointer verified (optional but recommended)
 **Actions:**
 - "Edit business info" → back to Screen 2 (post-MVP: needs a dashboard)
 - "Re-verify pointer" → back to Screen 4
 - "Share endpoint URL" → copy `https://geolocal.io/mcp/{slug}`
 **Done-when criteria met:**
 1. ✅ One business owner completed signup through SSP
 2. ✅ Their data is queryable via HTTP MCP endpoint
 3. ✅ An AI agent can discover and call the MCP (pointer verified)
 4. ✅ The agent returns a useful answer (preflight passes)
 ---
 ## 4. Data Model
 ### Businesses table (expanded)
 ```sql
 CREATE TABLE businesses (
  id SERIAL PRIMARY KEY,
  slug VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(500) NOT NULL,
  category VARCHAR(100),
  address TEXT,
  city VARCHAR(200),
  state VARCHAR(50),
  zip VARCHAR(20),
  phone VARCHAR(50),
  website VARCHAR(500),
  hours JSONB DEFAULT '{}',
  services JSONB DEFAULT '[]',
  story TEXT,
  owner_bio TEXT,
  photos JSONB DEFAULT '[]',
  calcom_link VARCHAR(500),
  mcp_endpoint VARCHAR(500),
  related_business_ids INTEGER[] DEFAULT '{}',
  status VARCHAR(50) DEFAULT 'draft',  -- NEW: draft | active | inactive | quarantine
  pointer_verified BOOLEAN DEFAULT FALSE,  -- NEW
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
 );
 ```
 **Status values:**
 - `draft` — owner in progress, not queryable
 - `active` — live, queryable by agents
 - `inactive` — owner requested pause or business closed
 - `quarantine` — quality loop flagged, manually reviewed
 **Decision:** Use a `status` column on `businesses` instead of a separate `quality_flags` table. Rationale: MVP has four states that are mutually exclusive per business. A separate table adds join complexity for a single-row-per-business relationship. Revisit if quality flags become multi-dimensional (e.g., separate flags for data freshness, booking health, pointer validity).
 ### Tenants table (new)
 ```sql
 CREATE TABLE tenants (
  id SERIAL PRIMARY KEY,
  email VARCHAR(500) UNIQUE NOT NULL,
  password_hash VARCHAR(500) NOT NULL,
  business_id INTEGER REFERENCES businesses(id) ON DELETE CASCADE,
  status VARCHAR(50) DEFAULT 'active',  -- active | suspended
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
 );
 CREATE INDEX idx_tenants_business ON tenants(business_id);
 ```
 **MVP constraints:**
 - One tenant per business (enforced by application logic, not schema)
 - No role system (owner is the only role)
 - No multi-business support
 ---
 ## 5. HTTP Transport Decision Record
 **Date:** 2026-07-29
 **Status:** Accepted
 **Decision:** Use streamable-HTTP transport for the public MCP gateway, not stdio.
 **Context:**
 - Stdio transport works for local development and single-process agents but cannot serve internet-discoverable endpoints.
 - The MCP spec defines streamable-HTTP as the transport for remote server access (SSE-based, with POST for tool calls).
 - Our gateway must be discoverable via a URL that any AI assistant can reach — stdio cannot satisfy this.
 **Consequences:**
 - Replace `StdioServerTransport` with `StreamableHTTPTransport` (or equivalent) in `mcp-server.ts`.
 - The Fastify/Express server will expose `/mcp/{slug}` as the streamable-HTTP endpoint.
 - Each slug routes to the correct business's tool set (multi-tenant via slug lookup).
 - No JWT auth on MVP endpoints (defer OAuth; open access is acceptable for read-only business data).
 - Rate limiting will be added post-MVP.
 **Alternatives considered:**
 - WebSocket: heavier client requirement, no MCP spec support yet.
 - gRPC: overkill for JSON tool calls, poor browser compatibility.
 - REST API without MCP framing: loses MCP compatibility, reinvents the protocol.
 ---
 ## 6. Flow Diagram
 ### Conversational Flow (Primary — UC-04)
 ```
 Owner arrives at geolocal.io
  | sees animated demo + "Get Started" CTA
  |
  v
 [Chat Opens] "Welcome to GeoLocal! Tell me about your business."
  | owner describes business in natural language
  | AI extracts: business type, location, goal
  v
 [Verification] "Let me verify you're the owner. Emailing OTP to your website's contact."
  | owner enters OTP code
  | ownership confirmed
  v
 [Audit] "I'll review your online presence — one moment."
  | scans: Google, Apple, Bing, Yelp, website
  | gap analysis: what's missing, inconsistent, outdated
  v
 [Results] "This looks like a terrific salon! Here's what I found..."
  | specific findings per platform
  | ranked recommendations
  v
 [Guided Setup] "Want me to help you set things up?"
  | conversational data capture (no forms)
  | pointer install guidance
  | preflight verification
  v
 [First Session Complete]
  | endpoint live (or in progress)
  | action list for ongoing optimization
  | session saved for resume
  |
  v
 [Ongoing — UC-05] Owner returns for updates, monitoring, reports
  | presence monitoring
  | data updates (hours, services, specials)
  | periodic health reports
  | seasonal guidance
 ```
 ### Legacy Form Flow (Superseded — retained for reference)
 ```
 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}
  |
  v
 AI agent discovers pointer -> calls /mcp/{slug} -> gets structured data
 ```
 ---
 ## 7. Acceptance Criteria
 ### 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
 ---
 ## 8. Open Questions
 1. **Minimum content bar:** What fields are required before status = 'active'? Proposal: name, category, at least one service, at least one day of hours.
 2. **Category list:** What categories ship in MVP? Proposal: auto repair, beauty/salon, home services, restaurant, retail/general store, tourism/activity.
 3. **Scrape depth:** Single page only, or follow links? Proposal: single page (homepage) for MVP.
 4. **Edit after live:** Do we need a dashboard screen for post-live edits? Proposal: yes, but defer to post-MVP; allow re-running the flow for now.
 5. **Booking link validation:** Do we verify the Cal.com link actually works? Proposal: URL format check only for MVP.
 ---
 ## 9. What Changed from Original SSP Spec
 | Area | Before | After |
 |------|--------|-------|
 | Length | 14 lines | Implementation-ready |
 | Screens | Named but not described | 5 screens with fields, behavior, errors (superseded by conversational flow) |
 | 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 |
 ## 10. Conversational SSP Revision (2026-07-29)
 This revision incorporates five product decisions from the SSP Refinement channel:
 | Area | Before (Form SSP) | After (Conversational SSP) |
 |------|-------------------|----------------------------|
 | Activation path | 5-screen form wizard | Conversational chat (ChatGPT-like) |
 | Fallback | N/A | No form fallback — chat only |
 | Landing page | Not specified | Animated demo + "Get Started" CTA |
 | Verification | Email + password signup | OTP to website contact email |
 | Data capture | Manual form entry | Conversational (AI asks, owner answers) |
 | Audit timing | Not in original | After verification, before setup |
 | Scope | One-time activation | Ongoing relationship (First Hour + First Month+) |
 | LLM | Not in original | Hosted 8–12B model, workflow-driven (TBD provider) |
 | Use cases | UC-01, UC-02, UC-03 | UC-04 (First Hour), UC-05 (Ongoing) added |
 **Status of form-based screens (§3):** Superseded by UC-04 and UC-05. Retained for reference during transition. Remove when conversational implementation is complete.
@@ -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.
@@ -0,0 +1,254 @@
 # UC-04 — Conversational SSP: The First Hour
 **Status:** Spec
 **Business model:** Model 1 — Endpoint enablement (conversational activation)
 **Primary surface:** GeoLocal.io landing page with embedded chat interface
 **Priority:** P0 (replaces form-based SSP as primary activation path)
 **Supersedes:** form-based SSP screens in `ssp-refined.md` §3 (Screens 1–5)
 ---
 ## 1. Problem
 The form-based SSP requires a business owner to fill out structured fields across five screens — a friction-heavy process that assumes technical comfort and patience. Many small business owners will abandon before completing it, even when they want to be discoverable by AI assistants. The experience also fails to demonstrate *why* this matters until late in the flow.
 A conversational interface lowers the barrier dramatically: the owner tells the system what they do in natural language, and the AI guides them through verification, discovery, and activation — proving value along the way rather than asking for trust upfront.
 ---
 ## 2. Desired Outcome
 Within one conversational session (target: 15–30 minutes), a business owner can:
 1. Arrive at GeoLocal.io and immediately understand the value through an animated demo
 2. Start a chat and describe their business in plain language
 3. Verify ownership via one-time pass code delivered to their website's contact email
 4. Receive an automated audit of their current online presence across major platforms
 5. Get specific, actionable recommendations to improve discoverability on Google, Apple, Bing, Yelp, and their own website
 6. Complete initial setup with the AI's guidance — no forms to fill out manually
 The owner leaves the first session with a clear picture of where they stand and a ranked list of steps to become AI-discoverable.
 ---
 ## 3. Actors
 | Actor | Role |
 |-------|------|
 | **Business owner** | Primary user; may not be technical; wants more customers |
 | **GeoLocal AI** | Conversational interface; guides owner through verification, audit, and recommendations |
 | **Verification system** | Delivers OTP to the email address found on the owner's website |
 | **Presence audit engine** | Scans the business's footprint across Google, Apple, Bing, Yelp, and the core website |
 | **geolocal platform** | Hosted MCP, data persistence, recommendation engine |
 ---
 ## 4. Preconditions
 - Owner can access GeoLocal.io from any browser (desktop or mobile)
 - Owner has a website with a publicly listed contact email (for OTP delivery)
  - **Alternate path:** If no website exists, the owner provides an email directly (see A2)
 - Owner is the legitimate business operator (or authorized representative)
 - Business has a physical presence or service area (local business)
 ---
 ## 5. Main Success Scenario
 ### Phase 1: Welcome and Discovery
 1. **Arrive** — Owner opens GeoLocal.io. The landing page shows:
   - Animated demo of a conversation between an AI and a business owner (visual, not interactive — shows what the experience feels like)
   - Prominent "Get Started" CTA that launches the live chat
   - Brief value statement: "We help local businesses succeed in the AI age"
 2. **Start Chat** — Owner clicks "Get Started." The chat opens with:
   - Welcome message: *"Welcome to GeoLocal! We help local businesses succeed in the AI age. Tell me about your business."*
   - The AI waits for the owner's response
 3. **Describe Business** — Owner describes their business in natural language (e.g., *"I have a salon in Cameron Park, CA. I want to improve our traffic — can you help?"*)
   - The AI extracts key entities: business type, location, goal
   - The AI confirms understanding: *"Got it — a salon in Cameron Park, CA, and you want more customers. Let's make sure AI assistants can find you and recommend you."*
 ### Phase 2: Verification
 4. **Ownership Verification** — The AI initiates verification:
   - *"Sure, I can help with that! First, let me verify you're the legitimate owner. I'm sending a one-time pass code to the contact email on your website."*
   - The system identifies the website from the owner's description (or asks for it)
   - The system scrapes the website for a contact email address
   - An OTP is sent to that email address
   - The AI prompts: *"Check your email and enter the code here."*
 5. **Owner Enters OTP** — Owner types the pass code into the chat
   - The AI validates the code
   - *"Your business affiliation is now verified! I'll review your business's online presence — one moment."*
 ### Phase 3: Presence Audit
 6. **Audit Execution** — The system runs a presence audit (background task, ~30–90 seconds):
   - Scans the business's website for structured data (hours, services, contact info)
   - Checks Google Business Profile status and completeness
   - Checks Apple Maps listing
   - Checks Bing Places listing
   - Checks Yelp listing
   - Evaluates overall data consistency across platforms
 7. **Audit Results** — The AI presents findings conversationally:
   - *"This looks like a terrific salon! I found your listing on Google and Yelp, but there are a few gaps. If we optimized a few things, AI assistants would find you and recommend you to their users much more often."*
   - Specific findings (not generic): *"Your Google listing doesn't include your services. Your website doesn't have structured hours. Yelp has your old phone number."*
 ### Phase 4: Recommendations and Setup
 8. **Actionable Steps** — The AI presents a ranked list of specific actions:
   - *"Here's what I recommend, in order of impact:"*
   - Each item is concrete and platform-specific:
     - *"Add your services to your Google Business Profile (takes 5 minutes)"*
     - *"Update your hours on your website so AI can read them"*
     - *"Install a discovery pointer so assistants can find your structured data"*
   - The AI explains the "why" for each recommendation
 9. **Guided Completion** — The AI offers to help complete items:
   - *"Want me to help you set up your GeoLocal endpoint? I'll walk you through it."*
   - The AI guides the owner through the remaining setup steps (data capture, pointer install, preflight) — all through conversation
   - No forms: the AI asks questions conversationally and populates the data
 10. **First Session Complete** — Owner has:
    - Verified ownership
    - Received a presence audit
    - Started (or completed) initial setup
    - A ranked action list for ongoing optimization
    - Understanding of what's next
 ---
 ## 6. Alternate Paths
 | ID | Trigger | Behavior |
 |----|---------|----------|
 | A1 | Owner has no website | AI asks for email directly: *"I don't see a website for your business yet — that's actually one of the things we can help with. What's the best email to reach you?"* OTP sent to provided email |
 | A2 | Owner wants to skip verification | AI explains why: *"Verification helps me access your existing listings so I can give you accurate recommendations. Want to skip and do a quick overview instead?"* Limited audit available without verification |
 | A3 | Website has no contact email | AI falls back: *"I couldn't find a contact email on your site. Can you tell me the best email for you?"* OTP sent to provided email |
 | A4 | Owner is not the actual owner | OTP fails to validate (code not received). AI handles gracefully: *"No problem — the code wasn't accepted. Are you the right person to talk to?"* Soft reject after multiple failures |
 | A5 | Owner wants to see the demo first | Landing page animated demo is always visible before clicking "Get Started." Owner can also ask the AI *"Show me what this looks like"* during chat |
 | A6 | Multiple locations | AI detects multi-location during discovery. Defers to single-location flow for MVP: *"Let's start with your main location. We can add others later."* |
 ---
 ## 7. Exception Paths
 | ID | Trigger | Behavior |
 |----|---------|----------|
 | E1 | OTP delivery fails | Retry up to 3 times with exponential backoff. After 3 failures: *"I'm having trouble reaching that email. Can you try a different one?"* |
 | E2 | OTP expires | *"That code has expired. Want me to send a new one?"* |
 | E3 | Audit finds no online presence | *"I couldn't find your business listed anywhere online yet. That's actually great news — we're going to set that up from scratch. Let's start with your basic info."* |
 | E4 | Owner abandons mid-conversation | Session state is preserved. Owner can return later and resume: *"Welcome back! We were working on your salon's setup. Want to pick up where we left off?"* |
 | E5 | Business not in ICP | AI detects non-local or non-service business during discovery. Soft redirect: *"We specialize in helping local service businesses right now. Here's what we can do for you…"* |
 | E6 | Audit takes too long | *"This is taking longer than expected — your business has a lot of listings to check. I'll have results in about a minute."* |
 ---
 ## 8. Functional Requirements (Product)
 ### Landing Page
 - Animated demo showing a sample conversation (visual, non-interactive)
 - "Get Started" CTA — single click to launch chat
 - Value proposition: clear, one-line statement
 - Mobile-responsive
 ### Conversational Interface
 - ChatGPT-like experience in the browser (full-width chat UI)
 - Natural language input (text; voice deferred)
 - AI responds in conversational tone (warm, helpful, expert)
 - Session persistence (resume after interruption)
 - Typing indicators during audit/processing
 ### Verification
 - OTP generation and delivery via email
 - Website scraping for contact email extraction
 - OTP validation (time-limited, single-use)
 - Graceful fallback when website email unavailable
 ### Presence Audit
 - Automated scanning of business presence across platforms:
  - Google Business Profile
  - Apple Maps / Apple Business Connect
  - Bing Places
  - Yelp
  - Business website (structured data, contact info, hours, services)
 - Gap analysis: what's missing, what's inconsistent, what's outdated
 - Conversational results delivery (not a report PDF)
 ### Recommendations
 - Ranked, platform-specific action items
 - "Why it matters" explanation for each item
 - Guided completion: AI helps owner execute steps
 - Progress tracking within the session
 ### Data Capture (Conversational)
 - AI asks questions conversationally to populate business data
 - No forms: data enters through natural dialogue
 - AI confirms understanding before saving
 - Editable: owner can correct or update at any time
 ---
 ## 9. Conversation Flow Requirements
 The AI conversation is driven by **workflow scripts** that structure the flow, with a hosted LLM (8–12B parameter model, TBD) handling natural language within that structure. Key constraints:
 - **Workflow-driven, not free-form:** The AI follows a defined state machine (welcome → discovery → verification → audit → recommendations → setup). It does not wander off-topic.
 - **Natural language within structure:** The AI translates structured steps into warm, conversational responses. It asks one question at a time, doesn't overwhelm.
 - **Tone:** Helpful expert — not salesy, not robotic. The AI is a guide, not a form with a chat skin.
 - **Pacing:** One topic per turn. Don't ask for address, hours, and services in the same message.
 - **Confirmation:** After extracting data, the AI confirms: *"So you're Maria's Hair Salon in Cameron Park, open Monday through Saturday. Did I get that right?"*
 ---
 ## 10. Success Metrics
 | Metric | Definition | Early Target |
 |--------|------------|--------------|
 | Chat start rate | Visitors who click "Get Started" | Track; optimize landing page |
 | Verification completion | Owners who complete OTP | >70% of started sessions |
 | Audit-to-action conversion | Owners who start implementing recommendations | Track per session |
 | First session duration | Time from "Get Started" to session end | 15–30 minutes target |
 | Abandonment rate | Sessions abandoned before verification | <30% |
 | Owner satisfaction | "I understand what to do next" after session | Qualitative; interview first 20 |
 ---
 ## 11. Out of Scope for UC-04
 - Voice input (deferred)
 - Multi-language support beyond English (deferred)
 - Multi-business accounts (deferred)
 - Real-time co-browsing or screen-sharing
 - Automated fixes applied by the AI (owner executes; AI guides)
 - Ongoing relationship features (see UC-05)
 - Form-based fallback (chat is the only path — see decision record)
 ---
 ## 12. Dependencies
 - Landing page with animated demo
 - Chat UI component (in-browser, full-width)
 - Hosted LLM (8–12B model, TBD provider)
 - Workflow script engine
 - Email delivery service (OTP)
 - Website scraper (contact email extraction)
 - Presence audit engine (Google, Apple, Bing, Yelp)
 - Data persistence (session state, business data)
 - MCP endpoint (for post-setup activation — reuses UC-01 mechanics)
 ---
 ## 13. Open Questions
 1. What is the minimum viable presence audit? Do we check all five platforms in MVP, or start with Google + website?
 2. How long should OTP codes be valid? (Proposal: 10 minutes)
 3. How many OTP retries before hard block? (Proposal: 3)
 4. Should the animated demo be video or CSS animation?
 5. Do we save partial sessions indefinitely or set a TTL?
 6. What happens when the audit finds the business is already well-optimized? (Happy path conversation)
 7. Should the AI offer to book a follow-up call for complex cases?
@@ -0,0 +1,232 @@
 # UC-05 — Conversational SSP: Ongoing Relationship
 **Status:** Spec
 **Business model:** Model 1 — Endpoint enablement (ongoing optimization and monitoring)
 **Primary surface:** GeoLocal.io chat interface (returning user)
 **Priority:** P1 (follows UC-04; defines the first-month and beyond relationship)
 **Prerequisite:** UC-04 completed (owner verified, initial audit done, setup started or complete)
 ---
 ## 1. Problem
 After the first session, a business owner has a GeoLocal endpoint and a list of recommended improvements — but most won't complete them without ongoing guidance. Their online presence changes over time (hours change, services change, listings get outdated), and AI assistants need current data to make accurate recommendations. A one-time activation is not enough: the platform needs to maintain the quality of the data it surfaces to AI assistants.
 Without an ongoing relationship, the owner's endpoint degrades, recommendations become stale, and the platform loses credibility with both the owner and the AI assistants that depend on it.
 ---
 ## 2. Desired Outcome
 The business owner returns to GeoLocal.io regularly (target: weekly or bi-weekly initially) to:
 1. Resume their conversation where they left off
 2. Get notified about presence changes or issues
 3. Complete recommended improvements with AI guidance
 4. Update their business data (hours, services, specials)
 5. Receive periodic presence health reports
 6. Access new features as the platform evolves
 The relationship evolves from "setup helper" to "ongoing AI presence partner" — the owner trusts GeoLocal to keep them discoverable and well-represented.
 ---
 ## 3. Actors
 | Actor | Role |
 |-------|------|
 | **Business owner** | Returning user; has completed initial verification |
 | **GeoLocal AI** | Conversational interface; remembers context, tracks progress, proactively alerts |
 | **Presence monitoring engine** | Periodic scanning of business listings across platforms |
 | **Notification system** | Email or in-app alerts for issues, changes, and recommendations |
 | **geolocal platform** | Data persistence, MCP endpoint, monitoring, reporting |
 ---
 ## 4. Preconditions
 - Owner has completed UC-04 (verified, audited, setup in progress or complete)
 - Owner has a GeoLocal account (created during verification)
 - Business data is persisted in the platform
 - MCP endpoint is live (or in progress)
 ---
 ## 5. Main Success Scenario
 ### Return and Resume
 1. **Owner Returns** — Owner visits GeoLocal.io again (days, weeks, or months after first session)
   - The landing page recognizes returning users (via cookie, email, or login)
   - The chat opens with context: *"Welcome back! Last time we talked, we were working on getting Maria's Hair Salon set up for AI discovery. Let me catch you up on where things stand."*
 2. **Status Update** — The AI summarizes current state:
   - *"Your GeoLocal endpoint is live and responding to AI assistants."*
   - *"We've completed 3 of 7 recommended improvements. Here's what's left…"*
   - *"I noticed your Google listing was updated — looks like someone added your holiday hours. Good catch."*
 ### Ongoing Guidance
 3. **Continue Recommendations** — The AI picks up where the conversation left off:
   - *"Last time, we finished your Google Business Profile. Want to tackle your Bing listing today? It'll take about 10 minutes."*
   - The AI guides the owner through the next steps conversationally
 4. **Data Updates** — Owner communicates changes naturally:
   - *"We're now open on Sundays from 10 to 4."*
   - *"We added a new service — balaycol."*
   - *"We moved to a new location."*
   - The AI updates the data, confirms the change, and checks if the MCP endpoint needs updating
 5. **Presence Monitoring** — The AI reports on ongoing presence health:
   - *"I checked your listings this week. Everything looks good on Google and Apple. Yelp still has your old phone number — want to fix that?"*
   - The AI can trigger a fresh audit on request: *"Want me to run a full check of all your listings?"*
 ### Proactive Alerts
 6. **Issue Detection** — The system detects problems and alerts the owner:
   - *"Heads up — your Google Business Profile was flagged for review. You may need to respond within 7 days."*
   - *"Your website's contact page returns a 404. AI assistants can't reach you through your site right now."*
   - *"Your MCP endpoint hasn't responded in 24 hours. Let me check what's going on."*
 7. **Opportunity Detection** — The AI identifies improvement opportunities:
   - *"Google just added a new feature for salons — they can now show available appointment slots directly in search. Want me to help you set that up?"*
   - *"I noticed a competitor in Cameron Park just updated their listing with services you also offer. You should make sure yours are listed too."*
 ### Periodic Reports
 8. **Health Reports** — The AI delivers periodic summaries (weekly or monthly):
   - *"Here's your monthly presence report: Your Google listing is at 92% completeness. Yelp is at 67%. Your website could use structured data for hours. Overall health: 81/100 — up from 64 last month."*
   - The report is conversational, not a PDF: the AI walks through the key points and offers to help with anything that needs attention
 ### Special Events and Seasonal
 9. **Seasonal Guidance** — The AI anticipates seasonal needs:
   - *"Holiday season is coming. Want to make sure your holiday hours are updated everywhere? I can help you set them on Google, Apple, and Bing."*
   - *"Summer tourism is picking up in Cameron Park. Let's make sure your listing is optimized for visitors searching from outside the area."*
 ---
 ## 6. Alternate Paths
 | ID | Trigger | Behavior |
 |----|---------|----------|
 | A1 | Owner returns after long absence | AI catches up: *"Welcome back! It's been a few months. Let me give you a full update on your presence and what's changed."* |
 | A2 | Owner wants full re-audit | *"Sure — I'll run a fresh audit of all your listings. This might take a minute."* Full audit re-execution |
 | A3 | Owner has multiple locations | AI manages each location separately: *"Which location do you want to work on today — Cameron Park or Rocklin?"* (post-MVP) |
 | A4 | Owner wants to add services | Conversational data update: *"What new services do you offer? Tell me about them and I'll add them to your profile."* |
 | A5 | Owner wants to pause | *"No problem — I'll pause monitoring. When you're ready to pick back up, just come back and we'll resume."* |
 | A6 | Owner is a delegate (not owner) | AI handles delegate context: *"You're managing this for Maria, right? Let me show you what needs attention."* |
 ---
 ## 7. Exception Paths
 | ID | Trigger | Behavior |
 |----|---------|----------|
 | E1 | MCP endpoint goes down | Alert owner immediately: *"Your MCP endpoint stopped responding. I'm checking now… [diagnosis]. Here's what to do."* |
 | E2 | Business closes permanently | AI detects closure signals (website gone, listings removed). Offers graceful decommission: *"It looks like you may have closed. Want me to update your listings or pause your endpoint?"* |
 | E3 | Owner disputes audit finding | AI explains methodology: *"I found your Yelp listing has the old number because [source]. Want me to help you update it, or did I get it wrong?"* |
 | E4 | Platform changes break listings | AI detects upstream changes (Google changes their API, Yelp changes their format). Adapts and notifies: *"Google updated their listing format. I've adjusted — your data still looks good."* |
 | E5 | Owner abandons ongoing relationship | Session persists. Owner can return anytime. After extended absence, AI offers full catch-up rather than incremental updates |
 ---
 ## 8. Functional Requirements (Product)
 ### Return User Experience
 - Recognize returning users (cookie, email, or login)
 - Resume conversation with full context
 - Summarize what happened since last visit
 - Show progress toward goals
 ### Presence Monitoring
 - Periodic scanning of business listings (cadence TBD — daily, weekly)
 - Change detection: hours, services, contact info, reviews
 - Issue detection: broken links, removed listings, flagged profiles
 - Health scoring: per-platform and aggregate
 ### Conversational Data Management
 - Owner communicates changes in natural language
 - AI parses and updates structured data
 - Confirmation before saving: *"So you're now open Sundays 10–4. Save that?"*
 - Edit history: owner can see what changed and when
 ### Proactive Alerts
 - Issue alerts: endpoint down, listing flagged, website broken
 - Opportunity alerts: new platform features, seasonal optimization
 - Digest option: bundle alerts into a weekly summary instead of real-time
 ### Periodic Reports
 - Conversational health reports (weekly or monthly)
 - Trend data: completeness scores over time
 - Action items derived from report findings
 - Comparison to previous periods
 ### Seasonal and Event Guidance
 - Calendar-aware suggestions (holidays, local events, tourism seasons)
 - Proactive hour updates for holidays
 - Special promotion support
 ---
 ## 9. Conversation Flow Requirements
 The ongoing relationship conversation differs from the first-hour flow in key ways:
 - **Context-aware:** The AI remembers everything from previous sessions — what's been done, what's pending, what the owner cares about
 - **Proactive:** The AI initiates topics (alerts, opportunities) rather than only responding to owner input
 - **Efficient:** Returning users don't re-explain their business. The AI leads with what's new or needs attention
 - **Flexible:** The owner can jump to any topic: *"Update my hours," "Run an audit," "What's my health score?"* — the AI handles it without requiring a specific flow
 ---
 ## 10. Success Metrics
 | Metric | Definition | Early Target |
 |--------|------------|--------------|
 | Return rate | Owners who return within 30 days of first session | >50% |
 | Session frequency | Average sessions per owner per month | 2+ in first month |
 | Recommendation completion | % of recommended actions completed within 30 days | Track; improve |
 | Data freshness | % of endpoints with data <30 days old | >80% |
 | Endpoint uptime | % of endpoints responding to AI assistants | >99% |
 | Owner retention | Owners active after 90 days | Track; improve |
 | Health score improvement | Average health score delta (first session vs. 30 days) | +20 points target |
 ---
 ## 11. Out of Scope for UC-05
 - Multi-business accounts (deferred)
 - Voice input (deferred)
 - Multi-language support (deferred)
 - Automated fixes applied by the AI (owner executes; AI guides)
 - Partner referral workflow (deferred)
 - Revenue/usage-based billing (deferred)
 - White-label or reseller features (deferred)
 - Model 2 intermediate features (see UC-02)
 ---
 ## 12. Dependencies
 - UC-04 (first-hour onboarding complete)
 - User authentication (login for returning users)
 - Session persistence and history
 - Presence monitoring engine (periodic)
 - Notification delivery (email or in-app)
 - Business data management (CRUD via conversation)
 - MCP endpoint health monitoring
 - Calendar integration (seasonal awareness)
 ---
 ## 13. Open Questions
 1. What is the monitoring cadence? Daily, weekly, or event-triggered?
 2. Do we email the owner proactively, or only alert in-app when they return?
 3. How do we handle owners who have multiple businesses? (post-MVP)
 4. Should we offer a "set it and forget it" mode where the AI auto-updates listings?
 5. What's the escalation path when the AI can't resolve an issue?
 6. Do we charge for ongoing monitoring, or is it included in the base service?
 7. How do we balance proactive alerts with notification fatigue?
 8. Should the AI suggest a follow-up cadence to the owner? ("Check in weekly for best results")
@@ -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  
 ---
Author	SHA1	Message	Date
Ty	2aa7a2cf97	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
Ty	1e66fe135a	strategy: rewrite section 13 milestones to board-distribution model Replace stale timeline targets with Ty's direction: prime the pump through a Chamber of Commerce or Tourism Board partnership, use member businesses as the first customer segment, and make the conversational SSP the compelling wow experience that wins returning customers. Old milestones assumed a form-wizard portal and endpoint counts (100, 1000, 10000) that predated the conversational SSP pivot and the refined MVP scope. New milestones track distribution-first activation through board trust, then prove the loop, then scale. Signed-off-by: Ty <tybala@outlook.com> Co-authored-by: Ty <tybala@outlook.com>	2026-07-30 03:34:19 -07:00
Ty	15cc3898cc	archive superseded SSP v1 with decision notes Move docs/product/ssp.md to docs/archive/ssp-v1.md. The original thin intent doc is superseded by ssp-refined.md which adds the full conversational activation spec, two-phase relationship model, and integration with UC-04/UC-05 use cases. Update product README to reference ssp-refined.md as the operating spec. Archive README updated to catalog the archived file. Decision: original preserved for historical traceability; do not use as implementation reference. Co-authored-by: Ty <tybala@outlook.com> Signed-off-by: Ty <tybala@outlook.com>	2026-07-29 19:28:03 -07:00
Ty	a4cc4cdb0f	docs: add conversational SSP use cases and update spec Add UC-04 (conversational SSP first hour) and UC-05 (ongoing relationship) structured as use cases per Ty's direction. Update ssp-refined.md with decision record, revised intent/scope, conversational flow diagram, and revision history. Co-authored-by: Ty <tybala@outlook.com> Signed-off-by: Ty <tybala@outlook.com>	2026-07-29 19:16:49 -07:00