diff --git a/apps/website/src/content/blog/tmdb-metadata-guide.mdx b/apps/website/src/content/blog/tmdb-metadata-guide.mdx
new file mode 100644
index 000000000..290dc0cbd
--- /dev/null
+++ b/apps/website/src/content/blog/tmdb-metadata-guide.mdx
@@ -0,0 +1,199 @@
+---
+title: 'Richer Movies & Series: Set Up TMDB Metadata in IPTVnator'
+description: How to get a free TMDB API key, where to paste it in IPTVnator, and every feature it unlocks — posters, cast and clickable actor pages, trailers, episode details, similar recommendations, and a Trending rail on your dashboard.
+pubDate: 2026-07-06
+author: 4gray
+featured: true
+heroImage: /iptvnator/blog/tmdb/hero.jpg
+tags:
+ - tutorial
+ - tmdb
+ - metadata
+draft: true
+---
+
+import Alert from '../../components/blog/Alert.astro';
+import StepRail from '../../components/blog/StepRail.astro';
+import IconFeatureGrid from '../../components/blog/IconFeatureGrid.astro';
+import ImageGallery from '../../components/blog/ImageGallery.astro';
+import PostButton from '../../components/blog/PostButton.astro';
+import LinkCards from '../../components/blog/LinkCards.astro';
+
+Most IPTV providers hand you a stream URL and a title — and not much else. A movie shows up as a bare filename, a series is a wall of episodes with no descriptions, and you have no idea whether the thing you're about to watch is worth two hours of your evening.
+
+IPTVnator can fix that. With a free **TMDB** (The Movie Database) key, your Xtream and Stalker libraries get real posters, plots, cast, trailers, ratings, episode details, "similar" recommendations, clickable actor pages, and a personalized **Trending this week** rail on the dashboard — all layered on top of the data your provider already gives you.
+
+It's **opt-in**, takes about two minutes to set up, and this guide walks through every step.
+
+## What you get
+
+
+
+
+ You only need a free themoviedb.org account and one API key. Everything below is a one-time setup — after that, IPTVnator does the work quietly in the background and caches results so pages stay fast.
+
+
+## Step 1 — Get a free TMDB API key
+
+TMDB is a community movie & TV database with a free API. Getting a key is quick:
+
+
+
+
+
+
+ IPTVnator accepts both the classic **API Key (v3 auth)** and the newer **API Read Access Token (v4)**. If you see both on the page, the shorter v3 key is the simplest choice.
+
+
+## Step 2 — Turn it on in IPTVnator
+
+
+
+
+
+
+ The field is labelled optional, but on public builds you should add your own key — it's free, it's yours, and it means enrichment keeps working no matter what. Your key stays on your device.
+
+
+That's it. Open any movie or series and enrichment starts filling in the details.
+
+## Now explore what it unlocks
+
+### Movie & series pages
+
+Detail pages render your provider's data instantly, then TMDB patches in the rest: a proper **plot**, **poster** and wide **backdrop**, **genres**, a **rating** badge, **director** and **cast**. Your provider stays the source of truth for anything it already supplies — TMDB only fills the gaps.
+
+
+
+
+ Metadata is fetched in your app language. TMDB doesn't translate everything, so for a title that only has text in its original language (say, a Russian film viewed in English), IPTVnator quietly refetches the plot — and the trailer — in the original language and fills only what was missing. No more empty descriptions just because you're not using the app in the film's language.
+
+
+### Trailers
+
+When TMDB has one, the **YouTube trailer** appears right on the detail page — no need to leave the app.
+
+
+
+### Cast & actor pages
+
+The cast list becomes a row of **photo chips**. Click any actor to open a dedicated page with their **photo, bio and full filmography** — pulled straight from TMDB.
+
+
+
+### Find an actor's films in your library
+
+Here's the part that ties it all together. On an actor's filmography, titles you **already have** in your library are marked available and open straight to their detail page. The rest open a search so you can look for them.
+
+On desktop you can even flip the scope to **All portals** — IPTVnator matches the actor's filmography against every Xtream library you've imported, so you can see which of their films are available anywhere in your setup, and jump right in.
+
+
+
+
+ When a filmography title opens the portal search, that search page now has a **Back** button, so you can return to the actor page in one click instead of navigating from scratch.
+
+
+### Seasons & episodes
+
+Open a season and IPTVnator lazily fetches its episode list from TMDB, overlaying **real episode names, overviews and still images** onto your provider's episodes. If the season description or names are missing in your language, the same original-language fallback kicks in.
+
+
+
+### "Similar" recommendations
+
+Every detail page can show a **Similar** rail built from TMDB recommendations — but filtered to titles you can actually watch. On Xtream it matches against your loaded catalog; on desktop it also matches against your **other imported portals**, so a recommendation available in a different library shows up with that library's name. Stalker pages, whose catalogs can't be searched locally, get their Similar rail entirely from these cross-portal matches.
+
+
+
+### Trending this week — on your dashboard
+
+The dashboard gains an opt-in **Trending this week** rail: TMDB's weekly trending movies and series, matched against your imported Xtream libraries. Titles you own open straight to their detail page (with the library name shown); the rest open a search. The dashboard hero also picks up a **backdrop**, **rating** and **genre** badges when available, plus a season/episode badge for series you're mid-watch on.
+
+
+
+
+ The Trending rail is a normal dashboard rail — toggle it (and any other rail) on or off in Settings → Dashboard. It only loads when TMDB is enabled.
+
+
+## Fast by design
+
+The dashboard and detail pages always render your provider's data **first**, then enrichment patches in the extras a moment later. Nothing new blocks the first paint. Results are cached — on desktop in a local database, in the browser in memory — so revisiting a page or reopening the app doesn't re-fetch. Trending is cached for a day; details for a month.
+
+## Privacy & matching
+
+
+ Enrichment is off until you turn it on. When enabled, IPTVnator sends **movie and series titles** (and TMDB IDs when your provider supplies them) to TMDB to look up metadata — nothing else. Matching is conservative: a title is only enriched when there's a confident match on normalized title and year, so you won't get the wrong film's poster.
+
+
+## Desktop vs. browser
+
+Core enrichment — plots, posters, cast, actor pages, trailers, episodes, and the in-catalog Similar rail — works in **both** the desktop app and the PWA. A few features rely on the desktop app's local database for cross-library matching and are **desktop-only**: the Trending rail, cross-portal Similar matches, the actor "All portals" scope, and global search.
+
+## A note on TMDB
+
+This product uses the TMDB API but is not endorsed or certified by TMDB. All the movie and TV metadata, artwork and trailers come from [The Movie Database](https://www.themoviedb.org/) — a huge, community-maintained resource. If you enjoy it, consider contributing data or artwork back to TMDB.
+
+---
+
+That's the whole feature set in one place. Turn it on, add your key, and your libraries stop looking like a list of filenames and start looking like a proper media collection.
+
+