ARRFLIX/docs/07-pre-import-cleanup.md

# 07 — Pre-Import Cleanup Ruleset (tv.s8n.ru)

Last updated: 2026-05-08
Server: Jellyfin 10.10.3 on nullstone, container `jellyfin`
Library root inside container: `/media`
Library root on host: `/home/user/media`

This document defines the **normative pre-import cleanup ruleset** for the
personal Jellyfin deploy. The owner downloads scene/group releases (e.g.
`Futurama Season 1  [1080p AI x265 10bit FS99 Joy]/`) which contain a mixture
of media files and non-media junk (codec readmes, release-group brags, Windows
installer shortcuts, comparison images, OS thumbnail caches, etc.). This junk
must NOT land in `/home/user/media/` because:

1. It clutters the library and confuses scrapers.
2. Promo PNGs may be mis-identified as artwork.
3. Release-group `.nfo` files break the NFO-override flow (doc 02 § 11).
4. **Windows executables and installer shortcuts (`.exe`, `.msi`, `.website`,
   `.url`, `.lnk`, `.scr`, `.bat`, `.ps1`) are a real security vector.** Even
   though the Linux server cannot execute them, friends with a Jellyfin
   account can download them through the web UI and run them on their PC.

Cross-linked to:

- [`01-artwork-and-images.md`](01-artwork-and-images.md) — what counts as a
  recognised poster / backdrop on disk.
- [`02-metadata-and-titles.md`](02-metadata-and-titles.md) — NFO sidecar
  override flow; what a "real" Jellyfin NFO looks like.
- [`03-subtitles.md`](03-subtitles.md) — which subtitle files to keep.
- [`05-file-structure-rules.md`](05-file-structure-rules.md) — canonical
  folder layout. § 8 of doc 05 defines the recognised extras subfolders;
  this doc enforces them at import time.
- [`08-filename-normalization.md`](08-filename-normalization.md) — the
  **next** stage of the pipeline (sibling agent), called after this doc's
  `cleanup-import.sh` has produced a clean staging tree.

Sources of truth:

- <https://jellyfin.org/docs/general/server/media/movies/> — extras subfolders
  and artwork filename patterns.
- <https://jellyfin.org/docs/general/server/media/shows/> — same for series.
- <https://jellyfin.org/docs/general/server/metadata/nfo/> — NFO XML schema;
  used here to distinguish a real metadata NFO from a release-group brag.

---

## 0. Top-level cleanup rules

These are non-negotiable. They wrap the doc 05 top-level rules with one
guarantee: **nothing leaves staging until cleanup has run and been
confirmed.**

1. **Never clean in-place on the source download.** The download directory
   (`/home/admin/Downloads/...`) is treated as a read-only artefact until
   the user explicitly approves deletion. The cleanup script copies into a
   staging area and operates there.
2. **Quarantine first, delete later.** First run of the cleanup script on a
   release moves junk to `~/.jellyfin-quarantine/<YYYY-MM-DD>/<release-name>/`
   instead of deleting. The user reviews, then a second pass empties the
   quarantine after sign-off. Subsequent runs on the same release are
   idempotent.
3. **Two-list policy.** Every file is matched against an `ALLOW` list (KEEP)
   or a `DENY` list (DELETE). Anything not on either list is **flagged** and
   surfaced in the audit report — a human decides. Never auto-delete on
   "unknown".
4. **Never run cleanup as root.** All operations are as the unprivileged
   `admin` (onyx) or `user` (nullstone) account. The live `/home/user/media/`
   tree is touched only by the rename step in doc 08, after cleanup has
   produced an intermediate staging copy.
5. **Idempotent.** Running cleanup twice on the same source must produce the
   same staging tree byte-for-byte (same `find -printf '%p %s\n' | sort`
   output, modulo timestamps).
6. **Dry-run is the default.** The cleanup script with no flags lists what it
   *would* do and exits without writing. `--apply` is required to actually
   move/quarantine files.

---

## 1. Categorical taxonomy of non-media files in scene/group releases

Scene and group ("p2p") releases follow loose conventions. The following
categories cover everything observed in the wild plus everything in the
Futurama download set:

### 1.1 Codec / player promotion

Text files and Windows shortcut files steering the user toward a specific
codec pack or media player (often K-Lite + MPC-HC). Frequently the file is
an `.url` or `.website` (Internet Shortcut) pointing to a third-party
installer. **Always DELETE.**

Real-world examples (`/home/admin/Downloads/futrama/`):

- `How to play HEVC (THIS FILE).txt` — 65 lines of MPC-HC marketing.
- `Ninite K-Lite Codecs Unattended Silent Installer and Updater.website`
  — `URL=https://ninite.com/klitecodecs/` Internet Shortcut.

Patterns:

- `How to play *.txt`, `Read*Me*.txt`, `INSTALL*.txt`, `PLAY*.txt`
- `*.website`, `*.url`, `*.lnk`
- `K-Lite*`, `MPC-HC*`, `VLC*`, `MX Player*`, `LAV*`

### 1.2 Release-group brag

Plain-text or `.nfo` files where the release group identifies itself,
documents encoder settings, or pumps its tracker URL. Distinguishable from a
**Jellyfin-compatible metadata NFO** (XML, root `<movie>` / `<tvshow>` /
`<episodedetails>`) by content — see § 3.

Real-world examples:

- `Encoded by JoyBell (UTR).txt` — 41-line manifesto from "Unity Team
  Release group" pointing to `UNITEAM.CO`.
- `RARBG.txt`, `WWW.YIFY-TORRENTS.COM.url`, `<group>.nfo` with ASCII art.

Patterns:

- `Encoded by *.txt`, `Ripped by *.txt`, `<GROUP>.txt`
- `RARBG.txt`, `RARBG_DO_NOT_MIRROR.exe` (yes, those exist; § 1.10)
- `*-readme.txt`, `release notes.txt`
- `*.nfo` containing only ASCII art (no `<movie>` / `<tvshow>` /
  `<episodedetails>` root element)
- `*.diz`, `file_id.diz` — old "BBS description" file, scene leftover

### 1.3 Promo images that are NOT poster artwork

Images that LOOK like artwork to a naive globber but are actually before/after
comparisons, group banners, or screenshot proofs. **Delete unless they live
inside a recognised extras folder (§ 4) or match the strict allow-list of
poster/backdrop names from doc 01.**

Real-world example:

- `Futurama Compare.png` (1.05 MB) — encoder before/after comparison.

Patterns to delete:

- `*Compare*.{png,jpg,jpeg,webp}`
- `*Sample*.{png,jpg,jpeg}` (when not in a `samples/` extras folder)
- `*Screen*.{png,jpg}`, `*Screens/*`, `*Proof/*`, `*Preview/*`
- `*-banner.png` from a group (NOT the same as Jellyfin's `banner.jpg`;
  group banners typically have the group name in the filename — heuristic
  match `*JoyBell*`, `*UTR*`, `*JoY*`, etc.)
- Stray `*.gif` files (animated previews); Jellyfin doesn't use GIF.

### 1.4 OS-generated thumbnail caches

Per-OS file managers (Windows Explorer, macOS Finder, GNOME Files) leave
turds in every directory they browse. **Always DELETE — never useful, never
metadata.**

Patterns:

- `Thumbs.db`, `ehthumbs.db`, `ehthumbs_vista.db`
- `.DS_Store`, `._*` (macOS resource forks)
- `Desktop.ini`, `desktop.ini`
- `.directory` (KDE)
- `.fseventsd/`, `.Spotlight-V100/`, `.Trashes/` (macOS)
- `$RECYCLE.BIN/`, `System Volume Information/` (Windows mount)

### 1.5 Sample files (lower-quality previews)

Scene releases sometimes ship a 30-second sample file at lower bitrate.
Jellyfin treats a `samples/` subfolder as extras (doc 05 § 8.2), but a stray
`Movie.sample.mkv` next to the main file would scrape as "another version".

**Default: DELETE.** Reasoning: we have the full file; the sample is dead
weight. If the user genuinely wants samples, drop them into a `samples/`
subfolder before running cleanup and the script will preserve the folder.

Patterns to delete (when at the top level of a release):

- `sample.{mkv,mp4,avi,m4v}`
- `*-sample.{mkv,mp4,avi,m4v}`, `*.sample.{mkv,mp4,avi,m4v}`
- `*_sample.{mkv,mp4,avi,m4v}`
- `Sample/` directory (rename to `samples/` to preserve as extras, OR delete)

### 1.6 Subtitle leftovers

VobSub (DVD/Blu-ray bitmap subs) are shipped as a pair: `en.idx` (index) +
`en.sub` (bitmap stream). Jellyfin can render them, but if a `.srt` exists
with the same language tag the bitmap pair is redundant and slow.

**Default: KEEP all `.srt` and `.ass`. KEEP `.idx`/`.sub` only if no `.srt`
of the same language exists.** This is a per-file decision — surface to the
user in the audit report rather than auto-pruning.

Patterns:

- `*.srt`, `*.ass`, `*.ssa`, `*.vtt` — KEEP (per doc 03).
- `*.sup` (PGS bitmap, Blu-ray) — KEEP (Jellyfin renders).
- `*.idx` + `*.sub` (VobSub) — KEEP if no `.srt` with same lang code; else
  flag for human review.
- `*.smi`, `*.rt` — DELETE (obsolete formats Jellyfin doesn't support).

### 1.7 Torrent residue

Files left by the torrent client itself. None are useful to Jellyfin.

Patterns to delete:

- `*.torrent`, `*.magnet`
- `*.parts`, `*.!ut`, `*.!qB`, `*.bc!` (in-progress fragments)
- `*.meta`, `*.aria2`
- `*.pad`, `padding/`, `__padding_file_*` (mktorrent padding)
- `*.sfv` (checksum manifest; harmless but useless after download)
- `*.md5`, `*.sha1`, `*.sha256` (release-checksum sidecars)

### 1.8 Test / proof images and folders

Some groups ship a `Proof/` or `Screens/` folder with screenshots to "prove"
the rip's quality. Useless inside a Jellyfin library.

Patterns to delete (whole folders):

- `Proof/`, `proof/`, `PROOF/`
- `Screens/`, `screens/`, `Screenshots/`, `Caps/`
- `Preview/`, `Previews/`
- `_screens/`, `screenshots-only/`

### 1.9 Multi-disc DVD/Blu-ray cruft

When a release is a straight ISO rip the `VIDEO_TS/` or `BDMV/` directory
sometimes survives next to the encoded file. Jellyfin can play
`VIDEO_TS.IFO` directly, but a partial DVD structure left over from the
encode is just clutter.

Patterns:

- `VIDEO_TS/` — KEEP if it contains a complete `VIDEO_TS.VOB` set;
  otherwise flag.
- `*.IFO`, `*.BUP`, `*.VOB` — KEEP if inside a complete `VIDEO_TS/`;
  DELETE if loose.
- `BDMV/`, `CERTIFICATE/`, `AACS/` — KEEP if complete BD structure;
  flag if partial.
- `*.iso` inside a media folder — flag for human review (could be the
  intentional rip OR a Windows malware vector — see § 8).

### 1.10 Outright malicious / suspicious

Some releases historically shipped Windows executables disguised as
"DO NOT MIRROR" anti-leech files. Even on a Linux server these must be
deleted because the friend with a Jellyfin account can download them via
the web UI ("Download original file" button) and run them locally.

**Always DELETE, never quarantine, never preserve, no exceptions.**

Patterns:

- `*.exe`, `*.msi`, `*.bat`, `*.cmd`, `*.com`, `*.scr`, `*.ps1`, `*.vbs`,
  `*.wsf`, `*.hta`, `*.jar`
- `*.app/` (macOS bundle dropped by macOS-using uploader)
- `*.dll`, `*.sys` (rare, but seen)
- Anything with a double extension like `Movie.mkv.exe`

---

## 2. KEEP vs DELETE — exhaustive table

This table is the **canonical decision matrix** for `cleanup-import.sh`.
Patterns are case-insensitive on `ext4`+Jellyfin. `KEEP` means it goes to the
staging tree; `DELETE` means it goes to quarantine on first run, then
recycle-bin on confirm.

| Pattern | Action | Why |
|---|---|---|
| `*.mkv`, `*.mp4`, `*.avi`, `*.m4v`, `*.ts`, `*.mov`, `*.webm`, `*.wmv`, `*.flv`, `*.mpg`, `*.mpeg` | **KEEP** | Media — the entire point. |
| `*.srt`, `*.ass`, `*.ssa`, `*.vtt`, `*.sup` | **KEEP** | Subtitles (doc 03). |
| `*.idx` + `*.sub` (VobSub pair) | **KEEP** if no `.srt` of same lang exists; else **FLAG** | Bitmap subs; redundant with SRT. |
| `*.smi`, `*.rt` | **DELETE** | Obsolete subtitle formats; Jellyfin can't render. |
| `folder.{jpg,png}`, `poster.{jpg,png}`, `cover.{jpg,png}`, `default.{jpg,png}`, `show.{jpg,png}`, `jacket.{jpg,png}`, `movie.{jpg,png}` | **KEEP** | Jellyfin-recognised primary artwork (doc 01). |
| `backdrop.{jpg,png}`, `fanart.{jpg,png}`, `background.{jpg,png}`, `art.{jpg,png}`, `backdrop[0-9]*.{jpg,png}`, `backdrop-[0-9]*.{jpg,png}` | **KEEP** | Jellyfin-recognised backdrops (doc 01). |
| `logo.{png,jpg}`, `clearlogo.{png,jpg}`, `banner.{jpg,png}`, `landscape.{jpg,png}`, `thumb.{jpg,png}`, `disc.{png,jpg}`, `clearart.{png,jpg}` | **KEEP** | Jellyfin-recognised auxiliary artwork. |
| `season[0-9]*-poster.{jpg,png}`, `season[0-9]*.{jpg,png}`, `season-specials-poster.{jpg,png}` | **KEEP** | Per-season artwork (doc 01 / TV layout). |
| `extrafanart/*.{jpg,png}`, `backdrops/*.{jpg,png,mp4}` | **KEEP** | Multi-backdrop folders (doc 05 § 8). |
| `*.nfo` with XML root `<movie>` / `<tvshow>` / `<episodedetails>` / `<artist>` / `<album>` / `<musicvideo>` | **KEEP** | Jellyfin-compatible metadata sidecar (doc 02 § 11). |
| `*.nfo` without one of the above XML roots | **DELETE** | Release-group ASCII-art brag — pretends to be metadata, isn't. |
| `*Compare*.{png,jpg,jpeg,webp,gif}` | **DELETE** | Encoder before/after — group promo. |
| `*Sample*.{png,jpg,jpeg}` (image, top level) | **DELETE** | Group promo (NOT a Jellyfin sample folder). |
| `*Screen*.{png,jpg}`, `Screens/`, `Screenshots/`, `Caps/` | **DELETE** | Proof shots. |
| `Proof/`, `proof/`, `PROOF/` | **DELETE** (whole folder) | Quality-proof shots. |
| `Preview/`, `Previews/` | **DELETE** (whole folder) | Lower-quality teaser. |
| `*.txt` (any) | **DELETE** | Readme / group brag — Jellyfin doesn't read TXT. |
| `*.diz`, `file_id.diz` | **DELETE** | Scene description file — obsolete. |
| `*.website`, `*.url`, `*.lnk` | **DELETE** | Windows Internet Shortcut — points at codec/installer pages. **Security: § 8.** |
| `*.exe`, `*.msi`, `*.bat`, `*.cmd`, `*.com`, `*.scr`, `*.ps1`, `*.vbs`, `*.wsf`, `*.hta`, `*.jar`, `*.dll`, `*.sys` | **DELETE** | Windows executable. **Security: § 8.** |
| `*.app/` | **DELETE** (whole folder) | macOS bundle. |
| `Thumbs.db`, `ehthumbs.db`, `ehthumbs_vista.db` | **DELETE** | Windows Explorer thumbnail cache. |
| `.DS_Store`, `._*` | **DELETE** | macOS Finder. |
| `Desktop.ini`, `desktop.ini` | **DELETE** | Windows folder customisation. |
| `.directory` | **DELETE** | KDE Dolphin. |
| `.fseventsd/`, `.Spotlight-V100/`, `.Trashes/`, `$RECYCLE.BIN/`, `System Volume Information/` | **DELETE** (whole folder) | OS metadata directories. |
| `sample.{mkv,mp4,avi,m4v}` (top level) | **DELETE** | Lower-quality preview (doc 05 § 8.1: full file already present). |
| `*-sample.{mkv,mp4,avi,m4v}`, `*_sample.{mkv,mp4,avi,m4v}`, `*.sample.{mkv,mp4,avi,m4v}` | **DELETE** | Same. |
| `Sample/` (directory, top level) | **DELETE** | Lower-quality preview folder. |
| `samples/` (directory, recognised name) | **KEEP** | Jellyfin extras folder (doc 05 § 8.2). |
| `featurettes/`, `behind the scenes/`, `deleted scenes/`, `interviews/`, `scenes/`, `shorts/`, `clips/`, `trailers/`, `extras/`, `other/`, `theme-music/`, `backdrops/` | **KEEP** (whole folder) | Jellyfin extras (doc 05 § 8.2). |
| `Featurettes/`, `Behind The Scenes/`, etc. (capitalised) | **KEEP** but **rename to lowercase** | Jellyfin matches case-insensitive but lowercase is the documented form. |
| Any other folder name | **FLAG** | Surface to human; might be a typo of an extras folder. |
| `*.torrent`, `*.magnet` | **DELETE** | Torrent client residue. |
| `*.parts`, `*.!ut`, `*.!qB`, `*.bc!`, `*.aria2` | **DELETE** | In-progress download fragments (shouldn't be here, but defensive). |
| `*.meta` | **DELETE** | aria2/torrent metadata. |
| `*.pad`, `padding/`, `__padding_file_*`, `_____padding_file_*` | **DELETE** | mktorrent padding files. |
| `*.sfv`, `*.md5`, `*.sha1`, `*.sha256` | **DELETE** | Checksum manifests; harmless but useless after download. |
| `*.rar`, `*.r[0-9][0-9]`, `*.zip`, `*.7z`, `*.tar`, `*.tar.gz` | **FLAG** | Compressed archive in a media folder is suspicious — release should have been extracted before download. |
| `*.iso` inside a media folder | **FLAG** | Could be intentional DVD/BD rip OR Windows-installer disguise. Human review. |
| `VIDEO_TS/` (complete) | **KEEP** | Jellyfin plays DVD structure directly. |
| `*.IFO`, `*.BUP`, `*.VOB` (loose, no `VIDEO_TS/`) | **DELETE** | Orphan DVD remnants. |
| `BDMV/` (complete) | **KEEP** | Jellyfin plays BD structure. |
| `CERTIFICATE/`, `AACS/` (without `BDMV/`) | **DELETE** | Orphan BD remnants. |
| `RARBG*.{txt,exe}`, `WWW.*.url`, `*.YIFY*.url` | **DELETE** | Tracker promo. |
| `RARBG_DO_NOT_MIRROR.exe` and similar | **DELETE** (security: § 8) | Historic anti-leech file; sometimes weaponised. |
| Anything else | **FLAG** | Two-list policy: never auto-delete on "unknown". |

---

## 3. NFO handling — the nuanced case

`.nfo` is overloaded. Two completely different file kinds share the
extension:

- **Scene release `.nfo`** — plain text, ASCII art, encoder credits, tracker
  URL. Useless to Jellyfin (and at worst gets scraped as garbage metadata
  if NFO Saver is enabled).
- **Jellyfin/Kodi/Emby metadata NFO** — XML, root element is one of
  `<movie>`, `<tvshow>`, `<episodedetails>`, `<artist>`, `<album>`,
  `<musicvideo>`. Documented in doc 02 § 11.

### 3.1 The discriminator one-liner

```bash
is_jellyfin_nfo() {
  # Returns 0 (KEEP) if the file looks like a Jellyfin/Kodi NFO,
  # 1 (DELETE) if it looks like scene-group ASCII-art brag.
  head -c 4096 "$1" | tr -d '[:space:]' \
    | grep -qE '<(movie|tvshow|episodedetails|artist|album|musicvideo|season)\b'
}

# Usage:
if is_jellyfin_nfo "$f"; then echo "KEEP $f"; else echo "DELETE $f"; fi
```

The first 4096 bytes are enough — a real Jellyfin NFO declares its root
within the first kilobyte. `tr -d '[:space:]'` is needed because some
encoders pretty-print the XML and put `<movie` on a different line from `<`.

### 3.2 Edge cases

- An NFO with both ASCII art **and** an XML root: KEEP. Jellyfin's parser
  ignores leading non-XML noise as long as the XML element parses.
- An NFO with a different XML root (e.g. `<root>`, `<info>`): DELETE.
  Jellyfin won't read it; nothing to preserve.
- An NFO with valid XML but **stale TMDB/IMDB IDs** that conflict with a
  newer scrape: KEEP, but flag for the user — doc 02 § 11.5 explains how
  the NFO Saver overwrites these on next scrape.
- Multiple NFOs in one folder (e.g. `release.nfo` from the group AND
  `tvshow.nfo` from a previous Jellyfin write): KEEP `tvshow.nfo`,
  DELETE `release.nfo`. Use the discriminator above on each.

### 3.3 First-100-bytes shortcut

The task brief proposes this:

```bash
if head -c 100 file.nfo | grep -qE '<(movie|tvshow|episodedetails)\b'; then echo KEEP; else echo DELETE; fi
```

This works for the common case but misses NFOs that start with an XML
declaration (`<?xml version="1.0"?>` plus possibly a comment) before the
root element — that prologue alone can be > 100 bytes. The 4096-byte
version above is safer; we use that in `cleanup-import.sh`.

---

## 4. Featurettes / Extras / Bonus folders — the canonical list

Per the Jellyfin docs (movies and shows pages), these subfolder names are
recognised and the contained files are tagged with the matching extra
type. **Folder name match is case-insensitive but lowercase is the
documented canonical form** — `cleanup-import.sh` lowercases on copy to
staging.

| Folder name | Extra type | Notes |
|---|---|---|
| `behind the scenes` | Behind The Scenes | spaces, not dashes |
| `deleted scenes` | Deleted Scene | |
| `interviews` | Interview | |
| `scenes` | Scene | |
| `samples` | Sample | distinct from a top-level `Sample/` (§ 1.5) |
| `shorts` | Short | |
| `featurettes` | Featurette | |
| `clips` | Clip | |
| `other` | Other | catch-all |
| `extras` | Extra | generic catch-all |
| `trailers` | Trailer | |
| `theme-music` | Theme music | `.mp3` files; doc 05 § 8.3 |
| `backdrops` | Backdrop video | rotating video backgrounds |

Anything else (e.g. `Bonus Features/`, `BTS/`, `Special Features/`,
`Featurette/` singular, `behind-the-scenes/` with dashes) is **NOT** matched
by Jellyfin and the contents won't surface as extras. Cleanup either
renames to the canonical name (when the mapping is unambiguous) or flags
for human review.

### 4.1 Canonical-name mapping (auto-rename)

| Found | Renamed to |
|---|---|
| `Featurettes/`, `Featurette/`, `FEATURETTES/` | `featurettes/` |
| `Behind The Scenes/`, `BTS/`, `behind-the-scenes/` | `behind the scenes/` |
| `Deleted Scenes/`, `Deleted_Scenes/`, `deleted-scenes/` | `deleted scenes/` |
| `Interviews/`, `Interview/` | `interviews/` |
| `Trailers/`, `Trailer/` | `trailers/` |
| `Bonus/`, `Bonus Features/`, `Bonus Material/`, `Special Features/`, `Specials/` | `extras/` (generic catch-all) |
| `Outtakes/`, `Bloopers/`, `Gag Reel/` | `extras/` (no dedicated folder) |

The `Specials/` rename to `extras/` is **important** — for a TV series,
`Specials/` looks like a season folder (Season 0 specials), but if the
files inside are featurettes rather than aired specials, putting them in
the wrong folder mis-scrapes them as episodes. When in doubt, flag.

### 4.2 Real-world example: Futurama download

The four Futurama season folders all contain a `Featurettes/` subfolder:

```
Futurama Season 1  [1080p AI x265 10bit FS99 Joy]/Featurettes/
├── Episode One Animatic.mkv
└── Welcome to the World of Tomorrow.mkv

Futurama Season 2 .../Featurettes/
├── Animatic -Why Must I be a Crustacean in Love.mkv
└── Futurama Game Trailer.mkv

Futurama Season 3 .../Featurettes/
├── An X-Mas Message From David X. Cohen.mkv
└── Deleted Scenes.mkv

Futurama Season 4 .../Featurettes/
├── Futurama Welcome to the World of Tomorrow (x265 Joy).mkv
├── Outtakes - Kif Gets Knocked Up a Notch  [1080p x265 10bit Joy].mkv
└── Panel on Voice Actors   [1080p x265 10bit Joy].mkv
```

After cleanup these become `featurettes/` (lowercase) inside the season
folder. Doc 08 (filename normalization) then renames the season folder
itself to `Season 01/` and may relocate the season-level featurettes to a
**series-level** `featurettes/` folder if the user prefers extras at the
series root (this is a doc 05 § 8 / doc 08 decision, not this doc's).

> Note: `Season 3 / Deleted Scenes.mkv` is a single file and should arguably
> be moved into a `deleted scenes/` subfolder rather than left in
> `featurettes/`. That's a manual disambiguation — flagged, not auto-moved.

---

## 5. Audit-then-clean workflow

Three-stage pipeline. Stage 1 is mandatory; stage 2 runs on user approval;
stage 3 is reversible until the quarantine retention window expires.

### 5.1 Stage 1 — Dry-run audit

Lists every file in the source release classified as KEEP / DELETE / FLAG.
Writes nothing.

```bash
# Dry-run audit on a single release dir.
cleanup-import.sh "/home/admin/Downloads/futrama/Futurama Season 1  [1080p AI x265 10bit FS99 Joy]"
```

Output (one line per file):

```
KEEP    Futurama S01E01 Space Pilot 3000  [1080p x265 10bit Joy].mkv
KEEP    folder.jpg
KEEP    Featurettes/Episode One Animatic.mkv  -> featurettes/Episode One Animatic.mkv
DELETE  Encoded by JoyBell (UTR).txt                    [release-group brag]
DELETE  How to play HEVC (THIS FILE).txt                [codec promo .txt]
DELETE  Ninite K-Lite Codecs Unattended Silent ....website   [windows .website -- SECURITY]
DELETE  Futurama Compare.png                            [encoder compare image]
FLAG    SomeUnknownFile.bin                             [unknown extension]
```

A **summary** at the bottom:

```
KEEP   16 files (5.92 GiB)
DELETE 4 files  (1.08 MiB)
FLAG   0 files
Run with --apply to quarantine the DELETE set.
```

Quick one-liner equivalents (for ad-hoc spot checks; the script § 9 is
preferred):

```bash
# What would I delete?
find "$SRC" \( \
     -iname '*.txt' -o -iname '*.nfo' -o -iname '*.url' -o -iname '*.website' \
  -o -iname '*.lnk' -o -iname '*.exe' -o -iname '*.msi' -o -iname '*.bat' \
  -o -iname '*.scr' -o -iname '*.ps1' -o -iname '*.cmd' -o -iname '*.com' \
  -o -iname 'Thumbs.db' -o -iname '.DS_Store' -o -iname 'Desktop.ini' \
  -o -iname '*Compare*.png' -o -iname '*Compare*.jpg' \
  -o -iname 'sample.mkv' -o -iname '*.sample.mkv' -o -iname '*-sample.mkv' \
  -o -iname '*.torrent' -o -iname '*.sfv' -o -iname '*.md5' \
\) -print

# What looks like a real Jellyfin NFO vs a release-group brag?
find "$SRC" -iname '*.nfo' -print0 | while IFS= read -r -d '' f; do
  if head -c 4096 "$f" | tr -d '[:space:]' \
       | grep -qE '<(movie|tvshow|episodedetails|artist|album|musicvideo|season)\b'; then
    printf 'KEEP   %s\n' "$f"
  else
    printf 'DELETE %s\n' "$f"
  fi
done
```

### 5.2 Stage 2 — Quarantine apply

```bash
cleanup-import.sh --apply "/home/admin/Downloads/futrama/Futurama Season 1  [...]"
```

What it does:

1. **Copies** the source directory tree to
   `/home/admin/.jellyfin-staging/<release-name>/`. The source is never
   modified.
2. Inside the staging copy, **moves** every DELETE-classified file to
   `/home/admin/.jellyfin-quarantine/<YYYY-MM-DD>/<release-name>/`,
   preserving relative paths so a user can `diff -r` to confirm.
3. **Renames** non-canonical extras subfolders to canonical lowercase
   (§ 4.1).
4. Writes a manifest at
   `/home/admin/.jellyfin-staging/<release-name>/.cleanup-manifest.json`
   listing every file action with sha256, source path, action, target
   path. This is what stage 3 reads.
5. Returns the staging path on stdout — that's the input to doc 08's
   filename normalizer.

### 5.3 Stage 3 — Confirm and recycle

After the user reviews the quarantine directory and approves:

```bash
cleanup-import.sh --confirm-quarantine 2026-05-08
```

Moves `/home/admin/.jellyfin-quarantine/2026-05-08/` to the system trash
(via `gio trash`) — still recoverable, but no longer cluttering the
quarantine root. After 30 days a cron sweep empties trash older than that.

### 5.4 Never delete from source

The source download (`/home/admin/Downloads/futrama/...`) is **never**
modified by `cleanup-import.sh`. Reasons:

- The user may want to re-seed the torrent.
- The user may want to re-run cleanup with different rules later.
- Bugs in the cleanup script must never destroy original artefacts.

Source deletion is a separate manual step the user does AFTER the
import is verified in Jellyfin and the library is happy. There is no
script for it on purpose.

---

## 6. Idempotency, edge cases, and "unknown" handling

- **Idempotent.** `cleanup-import.sh --apply` on an already-cleaned staging
  directory is a no-op (nothing matches DELETE). The script detects this
  and exits 0 with `nothing to do`.
- **Re-runnable on source.** Re-running the script on the same source
  produces a fresh staging copy, overwriting (after backup) the previous
  staging directory. Quarantine is dated, so two runs on the same day for
  the same release append rather than overwrite (`<release-name>.2/`,
  `.3/`, etc.).
- **Unknown extension** (e.g. `.dat`, `.bin`, `.iso`, `.bin.txt`) — never
  auto-deleted. FLAGGED in the audit output, surfaced to the user. The
  user adds it to the local override file
  `~/.config/jellyfin-cleanup/local-rules.conf` if they want it
  classified next time.
- **Hidden dotfiles** (anything starting with `.` other than known OS
  caches like `.DS_Store`) — FLAGGED. Don't auto-delete; could be a
  legitimate `.subliminal.cache` (subtitles plugin) or similar.
- **Symlinks** — never followed. A symlink in a release directory is
  always FLAGGED; the script refuses to copy or quarantine it.
- **Permission denied** — script bails with non-zero exit. Never
  partially applies.

---

## 7. The `Futurama Compare.png` problem (artwork false-positive)

`Futurama Compare.png` is a 1.05 MB PNG sitting next to the season's MKV
files. To a naive image-globber it looks like artwork — same extension as
`folder.jpg`, larger than the typical poster, sitting in the right
location. It's actually an encoder comparison shot.

The rule from doc 01 (artwork) and enforced here:

> **An image file in the release root is KEPT only if its name is on the
> exact recognised-artwork allow-list.** Anything else is DELETED.

Recognised artwork allow-list (top-level of an item folder):

- `folder.{jpg,jpeg,png,webp}`
- `poster.{jpg,jpeg,png,webp}`
- `cover.{jpg,jpeg,png,webp}`
- `default.{jpg,jpeg,png,webp}`
- `show.{jpg,jpeg,png,webp}` (series only)
- `jacket.{jpg,jpeg,png,webp}` (series only)
- `movie.{jpg,jpeg,png,webp}` (movies only)
- `backdrop.{jpg,jpeg,png,webp}` and `backdrop[0-9]*.{jpg,jpeg,png,webp}`
- `fanart.{jpg,jpeg,png,webp}`, `background.{jpg,jpeg,png,webp}`,
  `art.{jpg,jpeg,png,webp}`
- `logo.{png,jpg}`, `clearlogo.{png,jpg}`
- `banner.{jpg,png}`, `landscape.{jpg,png}`, `thumb.{jpg,png}`,
  `disc.{png,jpg}`, `clearart.{png,jpg}`
- `season[0-9]*-poster.{jpg,png}`, `season[0-9]*.{jpg,png}`,
  `season-specials-poster.{jpg,png}`
- `extrafanart/` and `backdrops/` directories (any contents OK)

Exception: images **inside** a recognised extras folder (`extras/`,
`featurettes/`, etc.) are KEPT regardless of name — they're presumed to be
intentional content of that extra.

`Futurama Compare.png` matches none of these allow-list patterns and is
not inside an extras folder, so it's DELETED.

---

## 8. Security rules

The single most important rule in this document:

> **Windows-executable extensions and Internet Shortcut formats are
> auto-deleted, never quarantined for "review", because the threat model
> isn't the Linux server, it's the Jellyfin user who downloads them.**

Jellyfin has a "Download original file" button for every item. If a
release contains `Codec Installer.exe`, Jellyfin will happily serve it to
any user with library access — including the friend on Windows who might
not understand that downloading and running an `.exe` from a media library
is a terrible idea. We don't trust the upload chain (the release group),
so we strip these on the server side.

Exhaustive auto-delete list (security override — these bypass the
"FLAG unknown" rule):

| Pattern | Risk |
|---|---|
| `*.exe` | Windows executable. Direct code execution on download+run. |
| `*.msi` | Windows Installer package. Silent install possible. |
| `*.bat`, `*.cmd` | Windows batch script. Runs in `cmd.exe`. |
| `*.com` | Old DOS-style executable. Still runs on modern Windows. |
| `*.scr` | Windows screensaver = .exe in disguise. Classic malware vector. |
| `*.ps1` | PowerShell script. Common modern malware delivery. |
| `*.vbs`, `*.wsf`, `*.hta`, `*.js` (Windows Script Host) | Active scripting. |
| `*.jar` | Java archive — runs as `java -jar` on systems with JRE. |
| `*.dll`, `*.sys` | Windows libraries / drivers. Side-load attacks. |
| `*.url`, `*.website`, `*.lnk` | Internet Shortcut / Windows Shortcut. Points at attacker-controlled URL. |
| `*.iso`, `*.img` (in a media folder, not at the library root) | Mountable disk image. Can carry Windows installers. **FLAG, not auto-delete** — could legitimately be a DVD rip. |
| `*.app/` | macOS application bundle. Auto-deleted. |
| `Autorun.inf` | Windows autorun config. **AUTO-DELETE.** |

Total auto-delete categories that are **purely** security-driven (not
Jellyfin-irrelevance-driven): **15** — `.exe`, `.msi`, `.bat`, `.cmd`,
`.com`, `.scr`, `.ps1`, `.vbs`, `.wsf`, `.hta`, `.jar`, `.dll`, `.sys`,
`.url`/`.website`/`.lnk`, `Autorun.inf`. Plus 1 flagged for human review:
`.iso`/`.img`.

### 8.1 Why `.url` is in the security list

`.url` is a plain-text Internet Shortcut. On Windows, double-clicking it
opens the target in the default browser. The "target" is whatever the
release group put in the `URL=` line. Historically this was used to push
codec-pack download pages with bundled adware. There is no benign reason
for a `.url` to ship in a media release.

The Futurama release contains exactly this pattern:

```
[InternetShortcut]
URL=https://ninite.com/klitecodecs/
```

Ninite itself is reputable — but the principle is "do not ship clickable
URLs to third-party installers in a media library, ever".

### 8.2 The `RARBG_DO_NOT_MIRROR.exe` historic case

Some releases historically contained a file named
`RARBG_DO_NOT_MIRROR.exe`, ostensibly to discourage mirror sites from
re-uploading. In several documented cases this file was actually adware
or a cryptominer. Auto-delete, no questions asked.

---

## 9. Prepared cleanup script — `cleanup-import.sh`

Idempotent. Dry-run by default. Quarantine-first. Source-immutable.
Returns the staging path on stdout for piping to doc 08's normalizer.

Save to `bin/cleanup-import.sh` in the `jellyfin-stack` repo.

```bash
#!/usr/bin/env bash
# cleanup-import.sh — Pre-import cleanup for tv.s8n.ru
# Version 1.0 (2026-05-08) — see docs/07-pre-import-cleanup.md
#
# Usage:
#   cleanup-import.sh                              SRC          # dry-run
#   cleanup-import.sh --apply                      SRC          # quarantine
#   cleanup-import.sh --confirm-quarantine YYYY-MM-DD           # recycle
#
# Exit codes:
#   0 success / nothing to do
#   1 user error (bad args, source not found)
#   2 internal error (permission, partial state)
#   3 flagged files present — user must review before --apply
set -euo pipefail

STAGING_ROOT="${JELLYFIN_STAGING_ROOT:-$HOME/.jellyfin-staging}"
QUARANTINE_ROOT="${JELLYFIN_QUARANTINE_ROOT:-$HOME/.jellyfin-quarantine}"
TODAY="$(date +%Y-%m-%d)"

# ----- classification -----
# Returns one of: KEEP DELETE FLAG
classify() {
  local path="$1"
  local base
  base="$(basename "$path")"
  local lower
  lower="$(printf '%s' "$base" | tr '[:upper:]' '[:lower:]')"

  # Security overrides — bypass everything else
  case "$lower" in
    *.exe|*.msi|*.bat|*.cmd|*.com|*.scr|*.ps1|*.vbs|*.wsf|*.hta|*.jar|*.dll|*.sys) echo DELETE; return ;;
    *.url|*.website|*.lnk) echo DELETE; return ;;
    autorun.inf) echo DELETE; return ;;
  esac

  # OS junk
  case "$lower" in
    thumbs.db|ehthumbs.db|ehthumbs_vista.db|.ds_store|desktop.ini|.directory) echo DELETE; return ;;
    ._*) echo DELETE; return ;;
  esac

  # Media — KEEP
  case "$lower" in
    *.mkv|*.mp4|*.avi|*.m4v|*.ts|*.mov|*.webm|*.wmv|*.flv|*.mpg|*.mpeg) echo KEEP; return ;;
    *.srt|*.ass|*.ssa|*.vtt|*.sup|*.idx|*.sub) echo KEEP; return ;;
    *.mp3|*.flac|*.ogg|*.opus|*.m4a|*.wav) echo KEEP; return ;;
  esac

  # Recognised artwork at item root
  case "$lower" in
    folder.jpg|folder.jpeg|folder.png|folder.webp) echo KEEP; return ;;
    poster.jpg|poster.jpeg|poster.png|poster.webp) echo KEEP; return ;;
    cover.jpg|cover.jpeg|cover.png|cover.webp) echo KEEP; return ;;
    default.jpg|default.png|show.jpg|show.png|jacket.jpg|jacket.png|movie.jpg|movie.png) echo KEEP; return ;;
    backdrop.jpg|backdrop.png|backdrop[0-9]*.jpg|backdrop[0-9]*.png) echo KEEP; return ;;
    fanart.jpg|fanart.png|background.jpg|background.png|art.jpg|art.png) echo KEEP; return ;;
    logo.png|logo.jpg|clearlogo.png|clearlogo.jpg|banner.jpg|banner.png) echo KEEP; return ;;
    landscape.jpg|landscape.png|thumb.jpg|thumb.png|disc.png|disc.jpg|clearart.png|clearart.jpg) echo KEEP; return ;;
    season[0-9]*-poster.jpg|season[0-9]*-poster.png|season[0-9]*.jpg|season[0-9]*.png) echo KEEP; return ;;
    season-specials-poster.jpg|season-specials-poster.png) echo KEEP; return ;;
  esac

  # Promo images masquerading as art
  case "$lower" in
    *compare*.png|*compare*.jpg|*compare*.jpeg|*compare*.webp|*compare*.gif) echo DELETE; return ;;
    *sample*.png|*sample*.jpg|*sample*.jpeg) echo DELETE; return ;;
    *screen*.png|*screen*.jpg|*preview*.png|*preview*.jpg) echo DELETE; return ;;
  esac

  # Text-flavoured junk
  case "$lower" in
    *.txt|*.diz|file_id.diz) echo DELETE; return ;;
  esac

  # Sample files
  case "$lower" in
    sample.mkv|sample.mp4|sample.avi|sample.m4v) echo DELETE; return ;;
    *-sample.mkv|*-sample.mp4|*.sample.mkv|*.sample.mp4|*_sample.mkv|*_sample.mp4) echo DELETE; return ;;
  esac

  # Torrent residue
  case "$lower" in
    *.torrent|*.magnet|*.parts|*.aria2|*.meta) echo DELETE; return ;;
    *.pad|__padding_file_*|_____padding_file_*) echo DELETE; return ;;
    *.sfv|*.md5|*.sha1|*.sha256) echo DELETE; return ;;
  esac

  # NFO discriminator — KEEP if Jellyfin-compatible XML, else DELETE
  case "$lower" in
    *.nfo)
      if head -c 4096 "$path" | tr -d '[:space:]' \
           | grep -qE '<(movie|tvshow|episodedetails|artist|album|musicvideo|season)\b'; then
        echo KEEP
      else
        echo DELETE
      fi
      return
      ;;
  esac

  # Suspicious archives in a media folder
  case "$lower" in
    *.rar|*.r[0-9][0-9]|*.zip|*.7z|*.tar|*.tar.gz|*.iso|*.img) echo FLAG; return ;;
  esac

  echo FLAG
}

# ----- folder classification -----
# Returns one of: KEEP_AS-IS RENAME:<target> DELETE FLAG
classify_dir() {
  local d="$1"
  local lower
  lower="$(basename "$d" | tr '[:upper:]' '[:lower:]')"
  case "$lower" in
    behind\ the\ scenes|deleted\ scenes|interviews|scenes|samples|shorts|featurettes|clips|other|extras|trailers|theme-music|backdrops)
      echo "RENAME:$lower"; return ;;
    bts|behind-the-scenes) echo "RENAME:behind the scenes"; return ;;
    deleted-scenes|deleted_scenes) echo "RENAME:deleted scenes"; return ;;
    bonus|bonus\ features|bonus\ material|special\ features|outtakes|bloopers|gag\ reel) echo "RENAME:extras"; return ;;
    proof|screens|screenshots|caps|preview|previews) echo DELETE; return ;;
    sample) echo DELETE; return ;;
    .fseventsd|.spotlight-v100|.trashes|\$recycle.bin|system\ volume\ information) echo DELETE; return ;;
    extrafanart) echo "RENAME:extrafanart"; return ;;  # case stays, recognised
    *) echo FLAG; return ;;
  esac
}

# ----- main -----
APPLY=0
CONFIRM_DATE=""
SRC=""

while [[ $# -gt 0 ]]; do
  case "$1" in
    --apply) APPLY=1; shift ;;
    --confirm-quarantine) CONFIRM_DATE="$2"; shift 2 ;;
    -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
    -*) echo "unknown flag: $1" >&2; exit 1 ;;
    *) SRC="$1"; shift ;;
  esac
done

if [[ -n "$CONFIRM_DATE" ]]; then
  if [[ -d "$QUARANTINE_ROOT/$CONFIRM_DATE" ]]; then
    gio trash "$QUARANTINE_ROOT/$CONFIRM_DATE"
    echo "Recycled $QUARANTINE_ROOT/$CONFIRM_DATE"
  else
    echo "No quarantine for $CONFIRM_DATE" >&2; exit 1
  fi
  exit 0
fi

[[ -n "$SRC" && -d "$SRC" ]] || { echo "usage: $0 [--apply] SRC" >&2; exit 1; }

RELEASE="$(basename "$SRC")"
STAGE="$STAGING_ROOT/$RELEASE"
QUAR="$QUARANTINE_ROOT/$TODAY/$RELEASE"

declare -i KEEP_N=0 DEL_N=0 FLAG_N=0

# Walk source, classify each entry
while IFS= read -r -d '' f; do
  rel="${f#$SRC/}"
  if [[ -d "$f" ]]; then
    case "$(classify_dir "$f")" in
      KEEP_AS-IS|RENAME:*) ;;
      DELETE) printf 'DELETE  %s/  [junk dir]\n' "$rel"; DEL_N+=1 ;;
      FLAG)   printf 'FLAG    %s/  [unknown dir name]\n' "$rel"; FLAG_N+=1 ;;
    esac
    continue
  fi
  case "$(classify "$f")" in
    KEEP)   printf 'KEEP    %s\n' "$rel"; KEEP_N+=1 ;;
    DELETE) printf 'DELETE  %s\n' "$rel"; DEL_N+=1 ;;
    FLAG)   printf 'FLAG    %s\n' "$rel"; FLAG_N+=1 ;;
  esac
done < <(find "$SRC" -mindepth 1 -print0)

echo "---"
echo "KEEP   $KEEP_N"
echo "DELETE $DEL_N"
echo "FLAG   $FLAG_N"

if (( FLAG_N > 0 )); then
  echo "FLAG count > 0; review before re-running with --apply." >&2
  (( APPLY == 0 )) || exit 3
fi

if (( APPLY == 0 )); then
  echo "Dry run only. Re-run with --apply to quarantine."
  exit 0
fi

# --- APPLY path: copy to staging, move DELETE to quarantine ---
mkdir -p "$STAGE" "$QUAR"
# rsync -a preserves perms and is idempotent
rsync -a --delete "$SRC/" "$STAGE/"

while IFS= read -r -d '' f; do
  rel="${f#$STAGE/}"
  if [[ -d "$f" ]]; then
    res="$(classify_dir "$f")"
    case "$res" in
      RENAME:*)
        target="${res#RENAME:}"
        parent="$(dirname "$f")"
        [[ "$(basename "$f")" == "$target" ]] || mv "$f" "$parent/$target"
        ;;
      DELETE)
        mkdir -p "$QUAR/$(dirname "$rel")"
        mv "$f" "$QUAR/$rel"
        ;;
    esac
    continue
  fi
  case "$(classify "$f")" in
    DELETE)
      mkdir -p "$QUAR/$(dirname "$rel")"
      mv "$f" "$QUAR/$rel"
      ;;
  esac
done < <(find "$STAGE" -mindepth 1 -print0)

# Manifest
{
  echo "{"
  echo "  \"release\": \"$RELEASE\","
  echo "  \"date\":    \"$TODAY\","
  echo "  \"source\":  \"$SRC\","
  echo "  \"staging\": \"$STAGE\","
  echo "  \"quarantine\": \"$QUAR\""
  echo "}"
} > "$STAGE/.cleanup-manifest.json"

# Stdout: the staging path, for piping to doc 08's normalizer
echo "$STAGE"
```

### 9.1 Pipeline integration

```bash
# Full pre-import flow:
SRC="/home/admin/Downloads/futrama/Futurama Season 1  [1080p AI x265 10bit FS99 Joy]"
STAGING="$(cleanup-import.sh --apply "$SRC")"
# STAGING is now ~/.jellyfin-staging/Futurama Season 1.../ with junk gone.
# Hand off to doc 08:
normalize-filenames.sh "$STAGING"
# Then move to live media tree (manual; doc 05 confirms layout):
mv "$STAGING" "/home/user/media/tv/Futurama (1999)/Season 01"
```

The `mv` to the live tree is **deliberately manual**. Cleanup and rename
are reproducible from source; the move into `/home/user/media/` is the
point of no return and the user runs it consciously.

---

## 10. What this doc explicitly does NOT do

- **Filename normalization** — that's doc 08. This doc only deletes; doc 08
  renames `Futurama S01E01 Space Pilot 3000  [1080p x265 10bit Joy].mkv`
  into the canonical `Futurama (1999) - S01E01 - Space Pilot 3000.mkv`.
- **Subtitle reconciliation** — doc 03 covers per-language naming; this
  doc only deletes obsolete formats (`.smi`, `.rt`).
- **Library refresh** — after files land in `/home/user/media/`, run
  `POST /Library/Refresh` on the Jellyfin API (doc 02 § 2). Cleanup never
  touches the running container.
- **NFO writing** — doc 02 § 11 covers writing override NFOs. This doc
  only filters incoming NFOs.
- **Source deletion** — never. The source download is read-only to this
  pipeline; the user removes it manually post-import.

---

## 11. TL;DR

| Step | What | Where |
|---|---|---|
| 1 | Audit (dry-run) | `cleanup-import.sh "$SRC"` |
| 2 | Apply (quarantine) | `cleanup-import.sh --apply "$SRC"` → prints staging path |
| 3 | Review quarantine | `ls ~/.jellyfin-quarantine/$(date +%F)/` |
| 4 | Normalize filenames | doc 08, takes staging path as input |
| 5 | Move to live tree | manual `mv "$STAGING" /home/user/media/...` |
| 6 | Refresh library | `POST /Library/Refresh` (doc 02) |
| 7 | Confirm quarantine | `cleanup-import.sh --confirm-quarantine YYYY-MM-DD` |
| 8 | Delete source | manual, only after Jellyfin shows the item correctly |

The hard rule, repeated: **the source download is never modified, the live
media tree is never written by cleanup, and Windows executables never
reach a Jellyfin user's browser.**