Resolve open questions; update all core specs

specification/00-overview.md

@@ -1,40 +1,55 @@
 # Diana Website — Specification Overview (v1)
 
+## Brand
+**Home Enhancement and Renovation — HER**
+- Short-form: **HER** (used in logo/header)
+- Full name: "Home Enhancement and Renovation" (footers, About, legal)
+
 ## Purpose
 Build a **mobile-first, SEO-friendly, static website** for Diana (handywoman) that primarily **converts visitors into qualified quote requests**.
 
-This document is the navigation map for the specification set.
-
 ## Goals
 1. **Generate qualified leads** via a lightweight quote/contact form.
-2. Communicate Diana’s differentiation: **trustworthy, easy to work with, female handyman/handywoman**, strong **project coordination/mediation** skills.
+2. Communicate Diana's differentiation: **trustworthy, easy to work with, female handyman/handywoman**, strong **project coordination/mediation** skills.
-3. **SEO-first information architecture**: separate service pages with clear local relevance (San Francisco + 50-mile radius).
+3. **SEO-first information architecture**: separate/grouped service pages with clear local relevance (San Francisco + 50-mile radius).
 4. **Fast, mobile-first UX** (Core Web Vitals friendly, readable, tap-target safe).
 
 ## Non-goals / Out of scope (v1)
 - Blog
 - Booking / calendar scheduling
 - Payments
-- Deployment/infrastructure work beyond “static site served behind Caddy reverse proxy”
+- Analytics / tracking (no cookie consent banner required)
+- Deployment/infrastructure work beyond "static site served behind Caddy reverse proxy"
 
 ## Key constraints
 - Language: **English**.
 - Site type: **static website**.
 - Content updates expected to be infrequent (maintained by owner/you).
 - Form should be **lightweight** (no file uploads in v1).
+- Form backend: **existing AWS service** (details TBD — see OQ-3 / ADR-002).
 
 ## Primary user flows
 1. Visitor lands on Home page → scans credibility/services → taps **Request a Quote** → submits form.
-2. Visitor lands on a Service page (SEO) → sees what’s included + service area + CTA → submits form.
+2. Visitor lands on a Service page (SEO) → sees what's included + service area + CTA → submits form.
 3. Visitor checks About / Testimonials for trust → CTA → submits form.
 
-## Intended information architecture (high level)
+## Intended information architecture
-- Home
+| Page | URL slug | Notes |
-- Services (hub)
+|------|----------|-------|
-- Service detail pages (one per service)
+| Home | `/` | Hero, positioning, services overview, CTA |
-- About Diana
+| Services hub | `/services/` | Links to all service pages |
-- Testimonials
+| Painting | `/services/painting/` | |
-- Contact / Request a Quote
+| Tile Setting | `/services/tile-setting/` | |
+| Drywall & Sheetrocking | `/services/drywall/` | |
+| Minor Plumbing | `/services/plumbing/` | |
+| Minor Electrical | `/services/electrical/` | |
+| Carpentry & Mounting | `/services/carpentry-and-mounting/` | |
+| Flooring & Wood Refinishing | `/services/flooring/` | |
+| Security & Safety Equipment | `/services/security-safety/` | |
+| Boat Work | `/services/boat-work/` | |
+| About Diana | `/about/` | Story, experience, credibility |
+| Testimonials | `/testimonials/` | Customer quotes |
+| Contact / Request a Quote | `/contact/` | Form + secondary contact (email, phone) |
 
 ## Specification documents
 ### Core specs (Phase 2)
@@ -47,5 +62,3 @@ This document is the navigation map for the specification set.
 - `33-frontend-spec.md` — pages, components, UX, mobile-first design, conversion flow
 - `37-seo-content-spec.md` — page structure, metadata, schema.org, sitemap/robots, content requirements per page
 - `38-lead-capture-spec.md` — form fields, validation, spam protection, delivery/routing, confirmation UX
-
-(If a themed spec requires an architectural decision, it will be captured in `02-architecture-decisions.md`. If uncertainty remains, it will be captured in `99-open-questions.md`.)

specification/01-requirements.md

@@ -9,64 +9,84 @@
 
 ### Lead capture (primary)
 - **FR-1**: The site must provide a **Request a Quote / Contact** form accessible within 1–2 taps from any page (persistent CTA).
-- **FR-2**: The form must be **lightweight** (no file upload requirement in v1).
+- **FR-2**: The form must be **lightweight** (no file upload in v1).
-- **FR-3**: The form must collect enough info to support **qualified leads**.
+- **FR-3**: The form must collect the following fields to support **qualified leads**:
-  - Minimum fields TBD in `38-lead-capture-spec.md`.
+  - **Name** (required)
-- **FR-4**: After submission, the user must see a **clear confirmation** (and guidance on next steps).
+  - **Address** (service location, required)
+  - **Phone** (required)
+  - **Email** (required)
+  - **Description** (description of work requested, required)
+- **FR-4**: After submission, the user must see a **clear confirmation** and guidance on next steps (e.g., Diana will follow up within N days).
+- **FR-5**: Form submissions are delivered via an **existing AWS service** (endpoint TBD — see ADR-002, OQ-3).
+
+### Contact channels
+- **FR-6**: The site must prominently expose:
+  - **Primary**: quote request form
+  - **Secondary**: email address
+  - **Secondary**: phone number
+- **FR-7**: Both secondary channels must appear in the site **header/footer** and in the **post-submission confirmation** copy.
 
 ### Content & pages
-- **FR-5**: The site must be **English-only**.
+- **FR-8**: The site must be **English-only**.
-- **FR-6**: The site must clearly state the **service area: San Francisco + 50 mile radius**.
+- **FR-9**: The site must clearly state the **service area: San Francisco + 50 mile radius**.
-- **FR-7**: The site must include a **Services hub page**.
+- **FR-10**: The site must include a **Services hub page** (`/services/`).
-- **FR-8**: The site must include **one page per service** (SEO-driven).
+- **FR-11**: The site must include **service detail pages**, grouped for SEO as follows:
-  - Services list (current):
+
-    - Security & Safety Equipment
+  | Page | URL slug |
-    - Tile Setting
+  |------|----------|
-    - Drywall / Sheetrocking
+  | Painting | `/services/painting/` |
-    - Painting
+  | Tile Setting | `/services/tile-setting/` |
-    - Minor Plumbing
+  | Drywall & Sheetrocking | `/services/drywall/` |
-    - Minor Electrical
+  | Minor Plumbing | `/services/plumbing/` |
-    - Carpentry
+  | Minor Electrical | `/services/electrical/` |
-    - Mounting
+  | Carpentry & Mounting | `/services/carpentry-and-mounting/` |
-    - Flooring touch-ups
+  | Flooring & Wood Refinishing | `/services/flooring/` |
-    - Boat work
+  | Security & Safety Equipment | `/services/security-safety/` |
-- **FR-9**: The site must include an **About Diana** page highlighting credibility, experience, and project coordination.
+  | Boat Work | `/services/boat-work/` |
-- **FR-10**: The site must include a **Testimonials** page using existing testimonial content as a base (source: https://spotlighthis.com/testimonials/).
+
-- **FR-11**: The site must include a **Contact** page (may be the same as Request a Quote).
+- **FR-12**: The site must include an **About Diana** page highlighting credibility, experience, and project coordination background.
+- **FR-13**: The site must include a **Testimonials** page using existing testimonial content (source: https://spotlighthis.com/testimonials/).
+- **FR-14**: The site must include a **Contact / Request a Quote** page (`/contact/`).
 
 ### Differentiation / brand messaging
-- **FR-12**: The site must explicitly lean into “**female handyman/handywoman**” positioning.
+- **FR-15**: Brand name: **"Home Enhancement and Renovation — HER"** (short-form: **HER**).
-- **FR-13**: The site must highlight Diana as **trustworthy, easy to work with**, and skilled at **project coordination/mediation**.
+- **FR-16**: The site must explicitly lean into "**female handyman/handywoman**" positioning.
-- **FR-14**: The site must incorporate proof points (e.g., **years of experience**, project coordination background).
+- **FR-17**: The site must highlight Diana as **trustworthy, easy to work with**, and skilled at **project coordination/mediation** between homeowners and construction crews.
+- **FR-18**: The site must incorporate key proof points: **years of experience** and **project coordination background** (aerospace team lead).
 
 ## Non-functional requirements
 
 ### Mobile-first UX
 - **NFR-1**: The site must be designed **mobile-first**, with readable typography and touch-friendly controls.
-- **NFR-2**: The quote/contact CTA must be prominent and accessible on mobile.
+- **NFR-2**: The quote/contact CTA must be prominent and easily accessible on mobile.
 
 ### SEO
-- **NFR-3**: The site must be **indexable** (server-rendered/static HTML; no content hidden behind client-only rendering).
+- **NFR-3**: The site must be **indexable** (static/server-rendered HTML; no content hidden behind client-only rendering).
-- **NFR-4**: Each service page must have unique, descriptive metadata (title/description) and content targeting that service.
+- **NFR-4**: Each service page must have unique, descriptive metadata (title/description) targeting that service and location.
-- **NFR-5**: The site must have sitemap and robots configuration (details in `37-seo-content-spec.md`).
+- **NFR-5**: The site must include a sitemap and robots.txt (details in `37-seo-content-spec.md`).
 
 ### Performance
 - **NFR-6**: Pages must load quickly on mobile networks; images must be optimized and appropriately sized.
 
+### Privacy / tracking
+- **NFR-7**: **No analytics, tracking scripts, or cookie consent banner** in v1. No privacy policy page required at launch.
+
 ### Maintainability
-- **NFR-7**: The solution should be low-maintenance and suitable for infrequent updates by you.
+- **NFR-8**: The solution should be low-maintenance and suitable for infrequent updates by the owner.
 
 ## Constraints / scope boundaries
 - **C-1**: Site must be a **static website**.
-- **C-2**: Deployment/infrastructure is **out of scope** for v1 beyond the assumption it will be served behind **Caddy reverse proxy**.
+- **C-2**: Deployment/infrastructure is **out of scope** beyond the assumption it will be served behind **Caddy reverse proxy**.
 - **C-3**: No blog, booking/calendar, or payments in v1.
+- **C-4**: No file uploads on the contact form in v1.
 
 ## Acceptance criteria (v1)
-- **AC-1**: A visitor can reach a quote request form from any page in 1–2 taps.
+- **AC-1**: A visitor can reach the quote request form from any page in 1–2 taps.
-- **AC-2**: Service pages exist for each service in FR-8, and each has a clear CTA.
+- **AC-2**: Service pages exist for each group in FR-11, each with a clear CTA and unique content.
-- **AC-3**: The site clearly states service area and core positioning.
+- **AC-3**: The site clearly states service area and core brand positioning (HER).
 - **AC-4**: The site is usable on mobile (no horizontal scroll, readable text, accessible tap targets).
 - **AC-5**: The site is SEO-ready: indexable pages, unique metadata per service page, sitemap/robots present.
+- **AC-6**: Secondary contact channels (email, phone) are visible in header/footer and post-form confirmation.
 
 ## Traceability notes
 - Lead capture specs → `38-lead-capture-spec.md`

specification/02-architecture-decisions.md

@@ -2,53 +2,74 @@
 
 This file records stable architectural decisions and their rationale. Items here should remain valid even as implementation details evolve.
 
-## ADR-001 — Static website (SSG or plain static HTML) as the delivery model
+## ADR-001 — Static website as the delivery model
 - **Status**: Accepted
 - **Context**: Site is primarily informational/lead-capture, needs strong SEO, and is expected to change infrequently.
-- **Decision**: Build as a **static website** (pre-rendered HTML) suitable for hosting behind a reverse proxy.
+- **Decision**: Build as a **static website** (pre-rendered HTML) suitable for hosting behind a Caddy reverse proxy.
 - **Rationale**:
-  - SEO-friendly (indexable content)
+  - SEO-friendly (fully indexable content)
   - Fast and reliable on mobile
   - Low maintenance
 - **Alternatives considered**:
   - WordPress/CMS: easier editing but higher maintenance/security surface
   - SPA-only: SEO/performance risks and complexity
 - **Consequences**:
-  - Contact form delivery must be handled via a static-compatible approach (see ADR-002, TBD)
+  - Contact form delivery must be handled via a static-compatible approach (see ADR-002)
 
-## ADR-002 — Quote request form submission mechanism
+## ADR-002 — Form backend: existing AWS service
-- **Status**: Proposed (blocked)
+- **Status**: Partially accepted (details pending)
-- **Context**: Form is required (FR-1..FR-4), but the mechanism (email service, server endpoint, third-party form backend) is not yet selected.
+- **Context**: The site must collect quote request form submissions (FR-3, FR-5). The site is static, so a backend service is required.
-- **Decision**: TBD.
+- **Decision**: Use an **existing AWS service** owned/operated by the stakeholder.
-- **Options to evaluate** (non-exhaustive):
+- **Rationale**:
-  1. Static form backend service (e.g., Netlify Forms / Formspree / Basin)
+  - Reuses existing infrastructure
-  2. Self-hosted lightweight endpoint behind Caddy (out-of-scope per C-2 unless already existing)
+  - Avoids new third-party service dependencies
-  3. Email link fallback (mailto) — likely insufficient for qualified leads
+- **Remaining open items** (blocking `38-lead-capture-spec.md`):
-- **Drivers**:
+  - Which AWS service is used (e.g. SES, API Gateway + Lambda)?
-  - Qualified lead capture
+  - What is the form submission endpoint URL?
-  - Spam protection
+  - What spam protection is in place or expected (e.g. honeypot, reCAPTCHA, AWS WAF)?
-  - GDPR/cookie implications
+- **See also**: OQ-3
-  - Operational simplicity
-- **Next step**: Resolve in `99-open-questions.md` and specify in `38-lead-capture-spec.md`.
 
 ## ADR-003 — Mobile-first, performance-first design
 - **Status**: Accepted
 - **Context**: Most traffic is expected on mobile; SEO and conversion depend on usability and speed.
-- **Decision**: Adopt a **mobile-first** layout and performance budget mindset.
+- **Decision**: Adopt a **mobile-first** layout and performance budget mindset throughout.
 - **Rationale**:
-  - Improves conversion
+  - Improves conversion on mobile
   - Supports SEO (Core Web Vitals)
 - **Consequences**:
-  - Images must be optimized; avoid heavy JS
+  - Images must be optimized (sized, compressed, lazy-loaded); avoid heavy JavaScript
-  - Ensure accessible typography and tap targets
+  - Ensure accessible typography and touch-friendly tap targets
 
-## ADR-004 — SEO information architecture: one page per service
+## ADR-004 — Service pages: grouped by search intent for SEO
 - **Status**: Accepted
-- **Context**: SEO is important and services are distinct.
+- **Context**: Individual pages per service produce better SEO but only if pages have sufficient unique content. Some services (carpentry/mounting, flooring/wood refinishing) share search intent and image assets.
-- **Decision**: Create **separate service pages** for each service category listed in FR-8.
+- **Decision**: Organize service pages into **9 grouped pages** (down from 10+ individual items), grouped by search intent:
+
+  | Page | Slug | Services grouped |
+  |------|------|-----------------|
+  | Painting | `/services/painting/` | Interior & exterior painting, trim |
+  | Tile Setting | `/services/tile-setting/` | All tile types, all rooms |
+  | Drywall & Sheetrocking | `/services/drywall/` | Drywall, sheetrocking, patching |
+  | Minor Plumbing | `/services/plumbing/` | Sinks, toilets, showers |
+  | Minor Electrical | `/services/electrical/` | Lights, fans, fixtures |
+  | Carpentry & Mounting | `/services/carpentry-and-mounting/` | Carpentry, mounting, assembly |
+  | Flooring & Wood Refinishing | `/services/flooring/` | Flooring, decks, stairs, refinishing |
+  | Security & Safety Equipment | `/services/security-safety/` | Grab bars, locks, cameras |
+  | Boat Work | `/services/boat-work/` | Marine woodwork, paint, hardware |
+
 - **Rationale**:
-  - Supports service-intent keywords
+  - Grouped pages have richer content and avoid thin-page SEO penalties
-  - Improves internal linking and topical relevance
+  - Carpentry + Mounting share the installation/assembly search intent
+  - Flooring touch-ups + Wood Refinishing share the surface/finishing search intent and asset library
 - **Consequences**:
-  - Requires unique content per page (avoid duplicate/thin pages)
+  - Each grouped page must contain enough unique content to serve its target keywords
-  - Requires a services hub and internal navigation
+  - Internal linking from the Services hub must cover all sub-topics
+
+## ADR-005 — No analytics or tracking in v1
+- **Status**: Accepted
+- **Context**: Stakeholder decided against tracking for simplicity.
+- **Decision**: **No analytics scripts, no ad pixels, no cookie consent banner** in v1.
+- **Rationale**: Reduces complexity, avoids consent/privacy obligations at launch.
+- **Consequences**:
+  - No data-driven iteration on traffic or conversions at launch
+  - Adding analytics later will require revisiting privacy policy needs

specification/99-open-questions.md

@@ -3,40 +3,49 @@
 This log tracks uncertainties and deferred decisions. Each item should be resolved before implementation in Phase 4.
 
 ## OQ-1 — Preferred contact method(s) beyond the contact form
-- **Status**: Open
+- **Status**: Resolved
-- **Context**: Contact form is a given, but preferred secondary channel(s) are not finalized.
+- **Resolution**: Secondary contact channels are **email** and **phone**. Both should appear in the site header/footer and in the confirmation copy after form submission.
-- **Why it matters**: Influences CTA design, header/footer, and “next steps” after form submission.
-- **Candidates**: phone, SMS/text, email.
-- **Proposed resolution**: Decide primary + secondary channel(s) and when to encourage each.
 
 ## OQ-2 — GDPR/cookie consent and tracking requirements
-- **Status**: Open
+- **Status**: Resolved
-- **Context**: Need to know whether we will run analytics/ads pixels and whether consent banners are required.
+- **Resolution**: **No analytics, no tracking scripts, no cookie consent banner** for v1. No privacy policy required at launch. Revisit if analytics are added later.
-- **Why it matters**: Affects scripts, cookie banner, privacy policy content, and SEO.
-- **Proposed resolution**:
-  - Decide whether to use analytics (and which)
-  - If analytics, decide consent model and privacy policy needs
 
 ## OQ-3 — Form backend + spam protection approach (ADR-002)
-- **Status**: Open
+- **Status**: Partially resolved
-- **Context**: Static site requires an external or existing backend mechanism.
+- **Resolution**: Form submissions will be handled via an **existing AWS service**. Specific service (e.g. SES, API Gateway + Lambda, or similar) and the endpoint URL/configuration need to be confirmed before `38-lead-capture-spec.md` implementation. See ADR-002.
-- **Why it matters**: Reliability, spam filtering, and operational workflow.
+- **Remaining**: Confirm which AWS service/endpoint and provide connection details.
-- **Proposed resolution**: Choose a form delivery method and specify validation + anti-spam.
 
-## OQ-4 — Minimum quote form fields for “qualified leads”
+## OQ-4 — Minimum quote form fields for "qualified leads"
-- **Status**: Open
+- **Status**: Resolved
-- **Context**: Goal is “more qualified leads”, but minimum qualifying information is not fully specified.
+- **Resolution**: Required form fields are:
-- **Why it matters**: Balances friction vs. lead quality.
+  - **Name** (full name)
-- **Proposed resolution**: Define required vs optional fields in `38-lead-capture-spec.md`.
+  - **Address** (service location)
+  - **Phone**
+  - **Email**
+  - **Description** (description of work requested)
+- All fields are required. Detailed validation rules to be defined in `38-lead-capture-spec.md`.
 
-## OQ-5 — Service taxonomy: separate pages vs grouping for carpentry/mounting/flooring
+## OQ-5 — Service taxonomy: separate pages vs grouping
-- **Status**: Open
+- **Status**: Resolved
-- **Context**: Requirement says separate page per service, but some services overlap.
+- **Resolution**: Services are grouped for best SEO relevance and content depth. Proposed groupings:
-- **Why it matters**: SEO clarity and content uniqueness.
+
-- **Proposed resolution**: Confirm final service list and page slugs.
+  | Page | Slug | Services included |
+  |------|------|-------------------|
+  | Painting | `/services/painting/` | Interior & exterior painting, trim work |
+  | Tile Setting | `/services/tile-setting/` | All tile types, kitchens, bathrooms, entryways, patios |
+  | Drywall & Sheetrocking | `/services/drywall/` | Removing, replacing, patching, sanding |
+  | Minor Plumbing | `/services/plumbing/` | Sinks, toilets, showers |
+  | Minor Electrical | `/services/electrical/` | Lights, fans, fixtures |
+  | Carpentry & Mounting | `/services/carpentry-and-mounting/` | Carpentry, furniture assembly, TV/shelf mounting |
+  | Flooring & Wood Refinishing | `/services/flooring/` | Flooring touch-ups, wood refinishing (floors, decks, stairs, cabinets) |
+  | Security & Safety Equipment | `/services/security-safety/` | Grab bars, lock bars, window mesh, security cameras |
+  | Boat Work | `/services/boat-work/` | Woodwork, spray paint, marine hardware |
+
+- **Rationale**: Carpentry and Mounting share the same installation/assembly search intent. Flooring touch-ups and Wood Refinishing share the same surface/finish search intent and existing image assets.
 
 ## OQ-6 — Brand naming and domain
-- **Status**: Open
+- **Status**: Resolved
-- **Context**: Current site uses “Spotlight Home Improvement Services”; new site may keep or adjust branding.
+- **Resolution**: New public-facing brand name is **"Home Enhancement and Renovation — HER"**.
-- **Why it matters**: Title tags, logo, copy, and SEO continuity.
+  - Use full name in footers, About page, and legal references.
-- **Proposed resolution**: Confirm public-facing brand name for v1.
+  - Use **"HER"** as the short-form logo/header identity.
+  - Update all spec documents and eventually title tags/metadata to reflect the new brand.