astro-website/openspec/changes/archive/2026-02-10-dynamic-homepage-social-acquisition/tasks.md

1. Repo And Tooling Setup

• 1.1 Choose the site framework and initialize the project skeleton (Astro preferred) with TypeScript support
• 1.2 Add a consistent config approach for secrets and runtime settings (env vars for API keys, Umami settings, base URL)
• 1.3 Add basic quality gates (lint/format, typecheck) and a minimal CI workflow
• 1.4 Add Docker build/run for deployment to the Linode instance (multi-stage build, static output served by nginx or equivalent)

2. Content Model And Cache

• 2.1 Define the normalized content item schema (id, source, url, title, publishedAt, thumbnailUrl, optional metrics/views)
• 2.2 Implement a content cache file format and location (e.g., content/cache/*.json) plus a "last updated" timestamp
• 2.3 Implement cache read utilities used by page rendering, including source filtering and limit controls
• 2.4 Implement "serve last good cache on failure" behavior in the ingestion workflow (write temp then swap)

3. YouTube Ingestion

• 3.1 Implement YouTube ingestion via RSS as the baseline (latest videos, no metrics)
• 3.2 Implement optional YouTube Data API ingestion when YOUTUBE_API_KEY is configured (include metrics.views)
• 3.3 Implement configurable channel identifier for youtube.com/santhoshj (document required values)
• 3.4 Add a small set of local fixtures/tests for parsing and normalization (RSS and API response samples)

4. Podcast Ingestion

• 4.1 Add configuration for the Irregular Mind podcast RSS URL
• 4.2 Implement podcast RSS fetch + parse to normalized items (one item per episode)
• 4.3 Ensure episode URLs and publish dates normalize correctly across common RSS date formats
• 4.4 Add fixtures/tests for RSS parsing and normalization

5. Instagram Support (Embed-First)

• 5.1 Define the minimal normalized representation for Instagram items in embed-first mode (post URL + optional thumbnail)
• 5.2 Implement a configuration-driven list of Instagram post URLs (or a simple feed source) for v1
• 5.3 Implement the renderer for Instagram embeds with a graceful empty state when no items exist
• 5.4 Document a Phase 2 path for API-based ingestion (constraints, account/app requirements, token refresh)

6. Build-Time Refresh And Scheduling

• 6.1 Implement a fetch-content script/command that ingests all sources and writes the cache
• 6.2 Add a manual refresh mechanism for ops (document how to run on the Linode host)
• 6.3 Add a scheduled refresh plan (cron on Linode or CI scheduler) and document frequency (daily minimum)
• 6.4 Add logging for ingestion runs (success/failure per source, cache write result)

7. Pages And SEO Surface

• 7.1 Implement / home page scaffold with deterministic module order
• 7.2 Implement /videos, /podcast, and /about indexable pages (static/SSR HTML, not client-only)
• 7.3 Add per-page metadata: title, description, canonical URL
• 7.4 Add Open Graph + Twitter card tags for indexable pages
• 7.5 Implement sitemap.xml and robots.txt (include /, /videos, /podcast, /about)
• 7.6 Add structured data (JSON-LD) scaffolding for Video/Podcast where detail pages exist (ensure valid JSON)

8. Homepage Modules

• 8.1 Implement "newest content" feed (sort by publishedAt desc across sources, configurable limits)
• 8.2 Implement "high-performing videos" module using metrics.views when present
• 8.3 Implement a manual override/curation list for featured/high-performing videos
• 8.4 Implement graceful empty/error states for each module (page never breaks if a module has no data)

9. CTAs And Outbound Tracking

• 9.1 Implement a reusable CTA component with platform, placement, and destination url
• 9.2 Add default destinations for YouTube channel, Instagram profile, and podcast listen target(s)
• 9.3 Add UTM parameter support for CTA outbound links
• 9.4 Define CTA placements on homepage (hero + at least one additional placement) and ensure they are visually prominent

10. Umami Analytics

• 10.1 Add Umami configuration (website ID + script URL) via environment/config without code changes per environment
• 10.2 Load Umami on all indexable pages when enabled; ensure site works when disabled
• 10.3 Implement cta_click event emission with platform, placement, and target
• 10.4 Implement outbound_click event emission with destination domain/identifier

11. Verification And Launch

• 11.1 Validate SEO basics locally (view-source contains metadata; sitemap/robots served correctly)
• 11.2 Validate performance basics (no blocking API calls at runtime; pages render from cache)
• 11.3 Validate analytics in a staging environment (events show up in Umami; disabled mode has no errors)
• 11.4 Document deployment steps for the Linode Docker setup (build, run, refresh schedule, rollback)