feat: include templates by file path and bind them to a profile name

docs/docs/configuration/_include/config-file-sample.yml

@@ -241,6 +241,14 @@ radarr:
       - template: radarr-quality-definition-movie
       - template: radarr-quality-profile-hd-bluray-web
       - template: radarr-custom-formats-hd-bluray-web
+      # Include a template by path. Relative paths resolve against this config's folder.
+      # - template: ./profiles/radarr/extra.yml
+
+    # Reusable, name-independent profiles: the included file carries no profile name,
+    # so the same file can be bound to a different name per instance.
+    # profiles:
+    #   - name: UHD
+    #     includes: ./profiles/radarr/quality.yml
 
     custom_formats: # Custom format assignments
       - trash_ids:

docs/docs/configuration/config-file.md

@@ -96,6 +96,34 @@ sonarr:
 - When loading TRaSH-Guides templates from URLs, specify `source: TRASH` in the include entry
 - Network requests have a 30-second timeout
 
+4. **File Templates** <span className="badge badge--warning">Experimental</span>: Include a template by its path on disk
+
+   - Lets you organise templates in subfolders instead of the single flat `localConfigTemplatesPath` directory
+   - The same file can be included from several instances, so a profile lives in exactly one place
+   - Any `include` entry whose `template` contains a `/` or `\`, or ends in `.yml` / `.yaml` / `.json`, is treated as a path
+
+```yaml title="config.yml"
+radarr:
+  movies:
+    # ...
+    include:
+      # Relative paths resolve against the folder containing your config.yml
+      - template: ./profiles/radarr/uhd.yml
+      # Absolute paths are used as-is
+      - template: /data/profiles/shared/audio.yml
+      # TRaSH-Guides JSON is detected automatically from its trash_id
+      - template: ./profiles/radarr/trash-profile.json
+```
+
+**Notes:**
+
+- Relative paths are resolved against the **directory holding `config.yml`** (see `CONFIG_LOCATION`), never the working directory, so the same config behaves identically however configarr is started
+- Both Recyclarr-format YAML and TRaSH-Guides-format JSON are accepted. A file containing a `trash_id` is treated as TRaSH automatically, so `source: TRASH` is optional
+- A template _name_ always wins: if the value also matches a known Recyclarr, local or TRaSH template, that template is used and the file is never read
+- File templates are processed **last**, so they take precedence over the name-resolved sources
+- A missing or malformed file is logged and skipped - it never aborts the run
+- Nested `include:` inside a file template is **not** supported (it logs a warning and is ignored)
+
 ### Repository URL Configuration
 
 You can override the default repository URLs for TRaSH-Guides and Recyclarr templates:
@@ -583,6 +611,79 @@ Notes:
 - clone order will be displayed in `DEBUG` log
 - **experimental**, available since `v1.10.0`
 
+### Reusable Profiles {#profiles}
+
+<span className="badge badge--warning">Experimental</span>
+
+`profiles:` lets a template file stay free of any profile name, and binds it to one in the config.
+That makes the file reusable: the same file can be shared by several instances, each under a
+different name, without editing it.
+
+```yaml title="config.yml"
+radarr:
+  movies:
+    base_url: !secret RADARR_URL
+    api_key: !secret RADARR_API_KEY
+    profiles:
+      - name: UHD
+        includes: ./profiles/radarr/quality.yml
+      - name: HD
+        # The very same file, bound to a second name
+        includes: ./profiles/radarr/quality.yml
+```
+
+```yaml title="profiles/radarr/quality.yml"
+# Note there is no profile name anywhere in this file.
+custom_formats:
+  - trash_ids:
+      - 496f355514737f7d83bf7aa4d24f8169 # TrueHD Atmos
+    assign_scores_to:
+      - score: 5000
+  - trash_ids:
+      - 2f22d89048b01681dde8afe203bf2e95 # DTS X
+    assign_scores_to:
+      - score: 4500
+```
+
+`includes` accepts a single entry, a list, or full include items - so a profile can be built from
+any template source, not just files:
+
+```yaml
+profiles:
+  - name: UHD
+    includes: ./profiles/uhd.yml # a single path
+  - name: HD
+    includes: # a list
+      - ./profiles/hd.yml
+      - radarr-custom-formats-hd-bluray-web # a Recyclarr template
+  - name: Trash
+    includes:
+      - template: ./profiles/trash-profile.json # a full include item
+        source: TRASH
+```
+
+**How the name is bound:**
+
+| In the included template                   | Result                                                            |
+| ------------------------------------------ | ----------------------------------------------------------------- |
+| No quality profile                         | Only custom format scores are bound to `name`                     |
+| Exactly one quality profile                | It is renamed to `name`, whatever it was called                   |
+| More than one quality profile              | The entry is **skipped** with a warning - use `include:` instead  |
+| A custom format with no `assign_scores_to` | An assignment to `name` is created                                |
+| Any `assign_scores_to` entry               | Its name is set to `name`; `score` / `use_default_score` are kept |
+
+Notes:
+
+- Every score assignment is redirected to `name`, including ones that already name a profile. That
+  is what lets an unmodified upstream template be reused under a name of your choosing.
+- Because only one quality profile may be bound per entry, there is never any ambiguity about
+  which profile those scores belong to.
+- `profiles:` is processed **after** `include:` and **before** the instance's own `custom_formats`
+  and `quality_profiles`, so your instance-level config still wins.
+- [`renameQualityProfiles`](#quality-profile-rename) and [`cloneQualityProfiles`](#quality-profile-clone)
+  run afterwards, so a bound profile can still be renamed or cloned.
+- Binding two entries to the same name is allowed - they merge like any other same-named profiles.
+
 ## Custom Formats Definitions {#custom-format-definitions}
 
 Custom formats can be defined in two ways:

docs/docs/configuration/general.md

@@ -27,6 +27,8 @@ At the moment we have the following order:
 - TRaSH
 - Recyclarr templates
 - Local Files
+- File templates (`include:` with a path)
+- Profiles (`profiles:`)
 - Config file (global level)
 - Config file (instance level)
 

examples/full/config/config.yml

@@ -250,6 +250,12 @@ radarr:
         trash_cfgroup_exclude_cfs:
           - id: dc98083864ea246d05a42df0d05f81cc # remove x265 (HD)
 
+    # (experimental) Reusable profiles: the included file carries no profile name, so the same
+    # file can be bound to a different name here and in any other instance.
+    profiles:
+      - name: ExampleBoundProfile
+        includes: ./profiles/radarr-audio.yml
+
     # Experimental defaults for all TRaSH profile includes in this instance (since v1.28.0)
     trash_cfgroup_config:
       include_optional: true

examples/full/config/profiles/radarr-audio.yml

@@ -0,0 +1,39 @@
+# Reusable profile definition (experimental).
+#
+# Note that no profile name appears anywhere in this file. It is supplied by the `profiles:`
+# entry in config.yml that includes it, so the same file can be bound to several names, in
+# several instances, without being edited.
+#
+# Included from config.yml as:
+#   profiles:
+#     - name: ExampleBoundProfile
+#       includes: ./profiles/radarr-audio.yml
+
+quality_profiles:
+  - upgrade:
+      allowed: true
+      until_quality: WEB 2160p
+      until_score: 1000
+      min_format_score: 5
+    min_format_score: 0
+    quality_sort: top
+    qualities:
+      - name: Remux-2160p
+      - name: WEB 2160p
+        qualities:
+          - WEBDL-2160p
+          - WEBRip-2160p
+
+custom_formats:
+  - trash_ids:
+      - 496f355514737f7d83bf7aa4d24f8169 # TrueHD Atmos
+    assign_scores_to:
+      - score: 5000
+  - trash_ids:
+      - 2f22d89048b01681dde8afe203bf2e95 # DTS X
+    assign_scores_to:
+      - score: 4500
+  - trash_ids:
+      - 417804f7f2c4308c1f4c5d380d4c4475 # ATMOS (undefined)
+    assign_scores_to:
+      - score: 3000