Initial commit - but way too late.

openspec/specs/seo-content-surface/spec.md

@@ -0,0 +1,57 @@
+## ADDED Requirements
+
+### Requirement: Indexable pages
+The site MUST provide indexable HTML pages for:
+- home (`/`)
+- videos (`/videos`)
+- podcast (`/podcast`)
+- about (`/about`)
+
+These pages MUST be server-rendered or statically generated HTML suitable for search engine crawling (not client-rendered only).
+
+The deployed static server MUST serve these pages successfully for both trailing-slash and non-trailing-slash requests when a directory-based `index.html` exists (for example, `/videos` and `/videos/` MUST both resolve to the videos page).
+
+#### Scenario: Crawling the home page
+- **WHEN** a crawler requests `/`
+- **THEN** the server returns an HTML document containing the homepage content modules and metadata
+
+#### Scenario: Direct request without trailing slash
+- **WHEN** a user requests `/videos` (no trailing slash)
+- **THEN** the server returns the videos page HTML and does not respond with 404
+
+#### Scenario: Direct request with trailing slash
+- **WHEN** a user requests `/videos/` (with trailing slash)
+- **THEN** the server returns the videos page HTML and does not respond with 404
+
+### Requirement: Metadata and canonical URLs
+Each indexable page MUST define:
+- a document title
+- a meta description
+- a canonical URL
+
+#### Scenario: Page metadata is present
+- **WHEN** a crawler requests `/videos`
+- **THEN** the HTML contains a `<title>`, a meta description, and a canonical URL for `/videos`
+
+### Requirement: Social sharing cards
+The site MUST provide Open Graph and Twitter card metadata for indexable pages so shared links render a preview.
+
+#### Scenario: Sharing the home page
+- **WHEN** a social crawler requests `/`
+- **THEN** the response includes Open Graph and Twitter card tags with a title, description, and image when available
+
+### Requirement: Sitemap and robots
+The site MUST provide:
+- `sitemap.xml` enumerating indexable pages
+- `robots.txt` that allows indexing of indexable pages
+
+#### Scenario: Sitemap is available
+- **WHEN** a crawler requests `/sitemap.xml`
+- **THEN** the server returns an XML sitemap listing `/`, `/videos`, `/podcast`, and `/about`
+
+### Requirement: Structured data
+The site MUST support structured data (JSON-LD) for Video and Podcast content when detail pages exist, and MUST ensure the JSON-LD is valid JSON.
+
+#### Scenario: Video structured data present
+- **WHEN** a video detail page exists and is requested
+- **THEN** the HTML includes JSON-LD describing the video using a recognized schema type