diff --git a/docs/archive/README.md b/docs/archive/README.md index b836f27..5d74b60 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -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). diff --git a/docs/archive/ssp-form-spec-superseded.md b/docs/archive/ssp-form-spec-superseded.md new file mode 100644 index 0000000..a819b65 --- /dev/null +++ b/docs/archive/ssp-form-spec-superseded.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 |