docs: images methods documentation

apps/docs/content/docs/getting-started/features.mdx

@@ -121,15 +121,74 @@ See the [Options guide](/docs/getting-started/options) for the full reference.
 `tmdb.images` is a pure URL builder — no HTTP request, no async. Pass a file path returned by any
 API response and get back a ready-to-use image URL.
 
+The builder exposes five methods, one per TMDB image category:
+
+| Method       | Input path field | Default size | Size type                                                 |
+| ------------ | ---------------- | ------------ | --------------------------------------------------------- |
+| `poster()`   | `poster_path`    | `w500`       | [`PosterSize`](/docs/types/options/images#postersize)     |
+| `backdrop()` | `backdrop_path`  | `w780`       | [`BackdropSize`](/docs/types/options/images#backdropsize) |
+| `logo()`     | `logo_path`      | `w185`       | [`LogoSize`](/docs/types/options/images#logosize)         |
+| `profile()`  | `profile_path`   | `w185`       | [`ProfileSize`](/docs/types/options/images#profilesize)   |
+| `still()`    | `still_path`     | `w300`       | [`StillSize`](/docs/types/options/images#stillsize)       |
+
+<Callout type="warn">
+	Path fields such as `poster_path`, `backdrop_path`, `profile_path`, and `still_path` are optional on most TMDB response types. Always
+	guard against `undefined` before building a URL.
+</Callout>
+
 ```ts
 const movie = await tmdb.movies.details({ movie_id: 550 });
+const tv = await tmdb.tv_series.details({ series_id: 1396 });
+const person = await tmdb.people.details({ person_id: 31 });
+const episode = await tmdb.tv_episodes.details({
+	series_id: 1396,
+	season_number: 1,
+	episode_number: 1,
+});
+
+// Poster — movies, TV series, collections
+if (movie.poster_path) {
+	const posterUrl = tmdb.images.poster(movie.poster_path, "w500");
+	// → "https://image.tmdb.org/t/p/w500/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg"
+}
+
+// Backdrop — movies, TV series
+if (movie.backdrop_path) {
+	const backdropUrl = tmdb.images.backdrop(movie.backdrop_path, "w1280");
+	// → "https://image.tmdb.org/t/p/w1280/rr7E0NoGKxvbkb89eR1GwfoYjpA.jpg"
+}
+
+// Logo — companies, networks (logo_path is always present on NetworkDetails)
+const network = await tmdb.networks.details({ network_id: 213 });
+const logoUrl = tmdb.images.logo(network.logo_path, "w185");
+// → "https://image.tmdb.org/t/p/w185/alqLicR1ZMHMaZGP3xRQxn9sq7p.png"
 
-const posterUrl = tmdb.images.poster(movie.poster_path, "w500");
-// → "https://image.tmdb.org/t/p/w500/e1mjopzAS2KNsvpbpahQ1a6SkSn.jpg"
+// Profile — people (actors, directors, crew)
+if (person.profile_path) {
+	const profileUrl = tmdb.images.profile(person.profile_path, "w185");
+	// → "https://image.tmdb.org/t/p/w185/r7WLn4Kbnqb6oJ8TmSI0e3GKEAO.jpg"
+}
+
+// Still — TV episode thumbnails
+if (episode.still_path) {
+	const stillUrl = tmdb.images.still(episode.still_path, "w300");
+	// → "https://image.tmdb.org/t/p/w300/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg"
+}
+```
+
+Each method's second argument is optional. When omitted, the built-in default size for that
+category is used (`w500` for posters, `w780` for backdrops, `w185` for logos and profiles, `w300`
+for stills).
+
+```ts
+// Uses default size — equivalent to poster(path, "w500")
+if (movie.poster_path) {
+	const posterUrl = tmdb.images.poster(movie.poster_path);
+}
 ```
 
-Default sizes can be configured once in `TMDBOptions.images` and are applied automatically when no
-size is specified at call time. See the [Images option](/docs/getting-started/options/images) for the full reference.
+Default sizes can be overridden globally once in `TMDBOptions.images` and are applied automatically
+across all calls. See the [Images option](/docs/getting-started/options/images) for the full reference.
 
 ---
 

apps/docs/content/docs/getting-started/options/images.mdx

@@ -7,6 +7,115 @@ The `images` option controls how the client builds image URLs.
 You can toggle HTTPS and set default sizes for each image category so they are applied
 automatically across all responses without needing to specify a size on every call.
 
+## Using `tmdb.images`
+
+`tmdb.images` is a synchronous URL builder — no HTTP request, no async. It exposes one method per
+TMDB image category. Each method accepts a file path (returned by any API response) and an optional
+size. When the size is omitted the configured default for that category is used.
+
+### `poster(path, size?)`
+
+Builds a URL for a poster image (`poster_path` field on movies, TV series, collections, and seasons).
+
+`poster_path` is optional on most response types — guard before calling.
+
+```ts
+const movie = await tmdb.movies.details({ movie_id: 550 });
+
+if (movie.poster_path) {
+	const posterUrl = tmdb.images.poster(movie.poster_path, "w500");
+	// → "https://image.tmdb.org/t/p/w500/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg"
+
+	// Omit size to use the configured default (w500)
+	const posterUrlDefault = tmdb.images.poster(movie.poster_path);
+}
+```
+
+**Size options (`PosterSize`):** `w92` · `w154` · `w185` · `w342` · `w500` · `w780` · `original`
+
+---
+
+### `backdrop(path, size?)`
+
+Builds a URL for a backdrop image (`backdrop_path` field on movies and TV series).
+
+`backdrop_path` is optional — guard before calling.
+
+```ts
+const tv = await tmdb.tv_series.details({ series_id: 1396 });
+
+if (tv.backdrop_path) {
+	const backdropUrl = tmdb.images.backdrop(tv.backdrop_path, "w1280");
+	// → "https://image.tmdb.org/t/p/w1280/tsRy63Mu5cu8etL1X7ZLyf7UP1M.jpg"
+}
+```
+
+**Size options (`BackdropSize`):** `w300` · `w780` · `w1280` · `original`
+
+---
+
+### `logo(path, size?)`
+
+Builds a URL for a logo image (`logo_path` field on companies and networks).
+
+```ts
+const network = await tmdb.networks.details({ network_id: 213 });
+
+const logoUrl = tmdb.images.logo(network.logo_path, "w185");
+// → "https://image.tmdb.org/t/p/w185/alqLicR1ZMHMaZGP3xRQxn9sq7p.png"
+```
+
+**Size options (`LogoSize`):** `w45` · `w92` · `w154` · `w185` · `w300` · `w500` · `original`
+
+---
+
+### `profile(path, size?)`
+
+Builds a URL for a profile image (`profile_path` field on people).
+
+`profile_path` is optional — guard before calling.
+
+```ts
+const person = await tmdb.people.details({ person_id: 31 });
+
+if (person.profile_path) {
+	const profileUrl = tmdb.images.profile(person.profile_path, "w185");
+	// → "https://image.tmdb.org/t/p/w185/r7WLn4Kbnqb6oJ8TmSI0e3GKEAO.jpg"
+}
+```
+
+**Size options (`ProfileSize`):** `w45` · `w185` · `h632` · `original`
+
+---
+
+### `still(path, size?)`
+
+Builds a URL for a TV episode still image (`still_path` field on TV episodes).
+
+`still_path` is optional — guard before calling.
+
+```ts
+const episode = await tmdb.tv_episodes.details({
+	series_id: 1396,
+	season_number: 1,
+	episode_number: 1,
+});
+
+if (episode.still_path) {
+	const stillUrl = tmdb.images.still(episode.still_path, "w300");
+	// → "https://image.tmdb.org/t/p/w300/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg"
+}
+```
+
+**Size options (`StillSize`):** `w92` · `w185` · `w300` · `original`
+
+---
+
+## Configuring Default Sizes
+
+Pass the `images` option to the `TMDB` constructor to configure HTTPS mode and set per-category
+default sizes. These defaults apply whenever a size is not passed explicitly at call time.
+
 ```ts
 const tmdb = new TMDB(apiKey, {
 	images: {