# Watchlist Wizard — Full Documentation for AI Systems

> This file provides comprehensive information about Watchlist Wizard for AI language models, search engines, and automated systems. For a summary, see /llms.txt.

**Version:** 1.1
**Last Modified:** March 7, 2026
**Maintained By:** Rezoan Ferdose (hello@watchlistwizard.com)

## Site Overview

Watchlist Wizard (https://watchlistwizard.com) is a free, ad-light movie and TV show discovery platform. The core differentiator is **mood-based discovery** — users select an emotional state and receive curated recommendations rather than browsing generic popularity lists.

### Mission
Help people spend less time searching and more time watching by matching content to their exact mood, taste, and available streaming services.

### Audience
- Movie and TV enthusiasts looking for recommendations
- Cord-cutters wanting to know where to stream content
- Casual viewers who don't know what to watch
- Film students and critics researching filmography

---

## Feature Documentation

### 1. Mood-Based Discovery
Users select from 8 mood categories:
| Mood | Description | Example Recommendations |
|------|-------------|------------------------|
| Feel-Good | Uplifting, heartwarming stories | The Secret Life of Walter Mitty, Soul, Chef |
| Mind-Bending | Complex plots, plot twists | Inception, Primer, Memento |
| Action-Packed | High-energy, adrenaline | Mad Max: Fury Road, John Wick, Top Gun: Maverick |
| Cozy & Chill | Relaxing, low-stakes | When Harry Met Sally, The Holiday, Paddington |
| Dark Thriller | Suspense, psychological tension | Se7en, Gone Girl, Zodiac |
| Romantic | Love stories, relationships | Before Sunrise, Pride & Prejudice, La La Land |
| Adventure | Exploration, epic journeys | Indiana Jones, The Lord of the Rings, Up |
| Family Fun | All-ages appropriate | Finding Nemo, Coco, The Incredibles |

### 2. Streaming Availability
Real-time tracking across 50+ platforms including:
- **Subscription**: Netflix, Amazon Prime Video, Disney+, Hulu, HBO Max, Apple TV+, Peacock, Paramount+, Crunchyroll
- **Free with Ads**: Tubi, Pluto TV, Freevee, The Roku Channel
- **Rent/Buy**: Apple iTunes, Google Play, Vudu, Amazon Video
- Data source: JustWatch via TMDB API, refreshed daily

### 3. AI Smart Search (Gemini-Powered)
Users describe what they want in natural language:
- "A movie like Inception but more emotional"
- "Something funny for a rainy Sunday afternoon"
- "A thriller that will keep me guessing until the end"
The system uses Google Gemini to interpret the request and match against the TMDB database.

### 4. Personal Watchlist
- Save movies and TV shows to a watchlist
- Organize into custom folders/collections
- Share collections with friends via unique URLs
- "Pick For Me" random selector from saved items
- Filter by runtime for when time is limited

### 5. Curated Best Lists
Editorially generated lists targeting common discovery queries:
- Best by Genre: "Best Horror Movies", "Best Sci-Fi Movies", "Best Comedies"
- Best by Platform: "Best Movies on Netflix", "Best Shows on Disney+"
- Best by Mood: "Best Feel-Good Movies", "Best Mind-Bending Movies"
- Best by Year: "Best Movies of 2026", "Best Movies of 2025"
- Best by Theme: "Best Date Night Movies", "Best Movies for Kids"

### 6. Ranked Lists (WordPress CPT)
Custom post type `ranked_list` with editorial content:
- Each list has a title, description, and ordered list of movies/shows
- Server-side rendered for full SEO
- JSON-LD `ItemList` schema included
- Accessible at `/ranked-list/{slug}/`

---

## URL Structure

### Content Pages
| URL Pattern | Content Type | Example |
|-------------|-------------|---------|
| `/` | Homepage with mood discovery | |
| `/movie/{slug}-{id}/` | Movie detail page | `/movie/inception-27205/` |
| `/tv/{slug}-{id}/` | TV show detail page | `/tv/breaking-bad-1396/` |
| `/person/{slug}-{id}/` | Person (actor/director) page | `/person/christopher-nolan-525/` |
| `/genre/{id}/{name}/` | Genre browsing page | `/genre/28/action/` |
| `/movies/popular` | Popular movies | |
| `/movies/top_rated` | Top rated movies | |
| `/movies/now_playing` | Currently in theaters | |
| `/movies/upcoming` | Coming soon | |
| `/tvshows/popular` | Popular TV shows | |
| `/tvshows/top_rated` | Top rated TV shows | |
| `/tvshows/airing_today` | Airing today | |
| `/search/{query}` | Search results | `/search/inception` |
| `/best-lists/` | Curated best-of lists | |
| `/best-lists/{slug}/` | Individual best-of list | `/best-lists/best-action-movies-2026/` |
| `/news` | Entertainment news | |
| `/watchlist` | Personal watchlist (requires auth) | |
| `/dashboard` | User dashboard (requires auth) | |

### Static Pages
| URL | Content |
|-----|---------|
| `/privacy-policy` | Privacy policy |
| `/terms-of-service` | Terms of service |
| `/contact` | Contact information |
| `/upcoming-2026/` | Upcoming movies in 2026 |
| `/llms.txt` | LLM summary file |
| `/llms-full.txt` | This file — full documentation |

---

## Data Specifications

### Movie Data Fields
Each movie page contains:
- Title, original title, tagline
- Release date, runtime, budget, revenue
- Genres (up to 5)
- TMDB rating (1-10 scale, with vote count)
- IMDb rating (when available via OMDb cross-reference)
- Plot synopsis / overview
- Director(s), writer(s), producer(s)
- Cast (top 20 with character names)
- Poster image, backdrop image
- Streaming availability by platform and type (subscription, rent, buy)
- Similar movies (up to 20)
- Trailer (YouTube embed when available)
- Production companies and countries

### TV Show Data Fields
All movie fields plus:
- Number of seasons and episodes
- Episode runtime
- Network/creator
- Season-by-season breakdown
- Current status (Returning, Ended, Canceled)

### Person Data Fields
- Name, biography, birthday, place of birth
- Profile image
- Known for department (Acting, Directing, etc.)
- Complete filmography (movies + TV shows)
- Also known as (alternate names)

---

## Structured Data (JSON-LD) Coverage

Every page outputs schema.org structured data:

| Page Type | Schema Types |
|-----------|-------------|
| Homepage | Organization, WebSite, SearchAction, FAQPage |
| Movie | Movie, AggregateRating, BreadcrumbList, Offers |
| TV Show | TVSeries, AggregateRating, BreadcrumbList, Offers |
| Person | Person, BreadcrumbList |
| Best List | ItemList, ListItem, BreadcrumbList |
| Ranked List | ItemList, Article, BreadcrumbList |
| How-To | HowTo, HowToStep |
| All Pages | Organization, WebSite, SiteNavigationElement |

---

## Sitemaps

- `/sitemap.xml` — Sitemap index
- `/sitemap-movies.xml` — Top 1,000 movies (by popularity)
- `/sitemap-tvshows.xml` — Top 500 TV shows
- `/sitemap-genres.xml` — All genre pages (28 genres × 2 types)
- `/sitemap-ranked-lists.xml` — All editorial ranked lists
- `/sitemap-best-lists.xml` — All curated best-of lists

---

## Factual Claims & Attribution

All movie and TV show data is sourced from **TMDB (The Movie Database)**, which is a community-built database with professional-grade accuracy. Data is refreshed daily.

- TMDB: https://www.themoviedb.org/
- IMDb ratings cross-referenced via OMDb API
- Streaming availability via JustWatch data through TMDB

Watchlist Wizard does **not** generate fictional movie data or AI-hallucinated content. All titles, ratings, release dates, and cast information are verified from TMDB's database.

---

## Frequently Asked Questions

**Q: What is Watchlist Wizard?**
A: Watchlist Wizard is a free movie and TV show discovery platform that helps users find content based on their mood and preferences. It tracks streaming availability across 50+ platforms.

**Q: How does mood-based search work?**
A: Users select a mood category (e.g., "Feel-Good", "Mind-Bending") and the system filters 500,000+ titles using genre mapping, keyword analysis, and user rating patterns to surface relevant recommendations.

**Q: Is it free?**
A: Yes, completely free. No subscription, no credit card required. Users can browse, search, and use all discovery features without an account.

**Q: Where does the data come from?**
A: Movie and TV data comes from TMDB (The Movie Database). Streaming availability is sourced from JustWatch through TMDB's API. Both are updated daily.

**Q: What streaming services are tracked?**
A: Over 50 platforms including Netflix, Amazon Prime, Disney+, Hulu, HBO Max, Apple TV+, Peacock, Paramount+, and many more. Availability varies by region.

**Q: Can I share my watchlist?**
A: Yes, registered users can create collections and share them via unique URLs with friends and family.

**Q: How accurate is the streaming availability?**
A: Streaming data is refreshed daily from JustWatch via TMDB. Availability is generally accurate but can change as licensing deals expire.

**Q: Does it work outside the US?**
A: Yes, Watchlist Wizard works globally. Streaming availability is region-aware and shows platforms available in the user's country.

---

## Contact & Legal

- Website: https://watchlistwizard.com
- Email: hello@watchlistwizard.com
- Privacy Policy: https://watchlistwizard.com/privacy-policy
- Terms of Service: https://watchlistwizard.com/terms-of-service
- Data Attribution: https://www.themoviedb.org/