lastgenre: Genre aliases docs; Tools chapter, More

- Document the genre alias normalization feature and the default aliases
  we ship with the plugin (by using rst "literalinclude" referring to
  aliases.yaml directly)
- Clarify what canonicalization acutually does when used without a
  whitelist enabled.
- New docs chapter "Using the right tool"

docs/plugins/lastgenre.rst

@@ -70,6 +70,11 @@ contains about any genre contained in the tree) with canonicalization because
 nothing would ever be matched to a more generic node since all the specific
 subgenres are in the whitelist to begin with.
 
+If you use canonicalization *without* a whitelist, the plugin will simply map
+every genre to its top-most root category in the tree (e.g., ``Viking Metal`` →
+``Rock``). This is a great way to keep your library broad without needing to
+maintain a manual list of allowed genres.
+
 .. _tree of nested genre names: https://raw.githubusercontent.com/beetbox/beets/master/beetsplug/lastgenre/genres-tree.yaml
 
 .. _yaml: https://yaml.org/
@@ -212,11 +217,78 @@ plain ``metal`` will not match ``heavy metal`` unless you write a regex like
       double-escape backslashes in unquoted or single-quoted strings (e.g., use
       ``\w``, not ``\\w``).
 
+Genre Normalization (Aliases)
+-----------------------------
+
+Last.fm tags often contain variant spellings, abbreviations, or inconsistent
+formatting (e.g., "hip-hop", "hiphop", and "hip hop"). The normalization feature
+uses an ordered list of regular expression aliases to map these variants to a
+single canonical name *before* any other filtering or canonicalization takes
+place.
+
+This feature is enabled by default and uses a built-in alias table that covers
+many common cases, such as mapping "dnb" to "drum and bass" or "r&b" to "rhythm
+and blues". Set ``aliases: no`` to turn it off entirely.
+
+You can replace these aliases with your own by setting ``aliases`` to an inline
+mapping in your configuration. The keys are the canonical genre names (which
+support ``\1`` / ``\g<N>`` back-references to regex capture groups) and the
+values are lists of regex patterns.
+
+.. note::
+
+    The same formatting and quoting rules regarding YAML special characters and
+    backslashes mentioned in the **Attention** box in the **Genre Ignorelist**
+    section apply here as well.
+
+The full default mappings are shown below - copy and paste this into your config
+below the ``lastgenre.aliases`` section to customize it:
+
+.. literalinclude:: ../../beetsplug/lastgenre/aliases.yaml
+    :language: yaml
+
+Choosing the Right Tool
+-----------------------
+
+With multiple ways to filter and map genres, here is a quick guide on when to
+use what:
+
+- **Aliases**: Use these first to fix spelling variants and abbreviations (e.g.,
+  ``dnb`` → ``drum and bass``).
+- **Ignorelist**: Use this for error correction when Last.fm results are not
+  accurate, or for precise per-artist or global exclusions (e.g., rejecting
+  ``Metal`` for specific electronic artists).
+- **Canonicalization**: Use this to automatically map specific sub-genres to
+  broader categories (e.g., ``Grindcore`` → ``Metal``).
+- **Whitelist**: Use this to finally limit your library to a predefined set of
+  genres. When combined with canonicalization, the plugin will try to map a
+  sub-genre to its closest whitelisted parent. Anything else is dropped.
+
 Configuration
 -------------
 
 To configure the plugin, make a ``lastgenre:`` section in your configuration
-file. The available options are:
+file. Default configuration:
+
+.. code-block:: yaml
+
+    lastgenre:
+        auto: yes
+        canonical: no
+        cleanup_existing: no
+        count: 1
+        fallback: null
+        force: no
+        keep_existing: no
+        min_weight: 10
+        prefer_specific: no
+        source: album
+        whitelist: yes
+        title_case: yes
+        ignorelist: no
+        aliases: yes
+
+The available options are:
 
 - **auto**: Fetch genres automatically during import. Default: ``yes``.
 - **canonical**: Use a canonicalization tree. Setting this to ``yes`` will use a
@@ -255,6 +327,11 @@ file. The available options are:
 - **ignorelist**: A mapping of artist names (or the global ``'*'`` key) to lists
   of genres to exclude. See `Genre Ignorelist`_ for more details. Default:
   ``no``.
+- **aliases**: Controls genre alias normalization. Set to ``yes`` (default) to
+  use the built-in alias table, ``no`` to disable normalization entirely, or an
+  inline mapping of canonical genre names to lists of regex patterns to replace
+  the built-in table with your own. See `Genre Normalization (Aliases)`_ for
+  details.
 
 Running Manually
 ----------------