docs: add comprehensive documentation for archive_name dict format

- Document both string pattern and dict format in manifest reference
- Add real-world examples (NATS Exporter) in adding-exporters guide
- Document all available template variables ({upstream_linux_arch}, etc.)
- Add detailed use cases for when to use dict format
- Update CHANGELOG.md with new feature entry

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: SckyzO

CHANGELOG.md

@@ -33,6 +33,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 *   **Enhanced Cards:** Build dates displayed below "Updated" badges with short date format.
 *   **Build Status:** Real-time availability tracking with "success", "pending", and "failed" states.
 
+### ✨ Enhanced Features
+
+*   **Flexible Archive Naming:** Added dict format support for `archive_name` field to handle per-architecture patterns.
+    *   **String Pattern:** Original template variable format (e.g., `{name}-{clean_version}-{arch}.tar.gz`).
+    *   **Dict Format:** New per-architecture mapping for inconsistent upstream naming.
+    *   **New Variables:** Added `{upstream_linux_arch}` variable for mixed conventions (x86_64, arm64).
+    *   **Schema Validation:** Marshmallow validation ensures correct format usage.
+    *   **Use Case:** Handles upstreams with completely different naming per architecture (e.g., NATS Exporter).
+
 ### 🐛 Bug Fixes
 
 *   **DEB Template Issues:** Fixed `debian/rules` template to use correct `build_source` field for extra files.

docs/user-guide/adding-exporters.md

@@ -67,8 +67,43 @@ upstream:
   type: github
   repo: owner/my_exporter
   strategy: latest_release
-  # Optional: custom archive naming pattern
-  archive_name: "{name}-{clean_version}-linux-{arch}.tar.gz"
+```
+
+#### Custom Archive Naming
+
+If the upstream release artifacts don't follow standard naming conventions, you can define custom patterns:
+
+**Option 1: String Pattern (Most Common)**
+```yaml
+upstream:
+  archive_name: "{name}-{clean_version}-linux-{upstream_linux_arch}.tar.gz"
+```
+
+Available variables:
+- `{name}`, `{version}`, `{clean_version}`: Project identifiers
+- `{arch}`: Standard (amd64, arm64)
+- `{rpm_arch}`: RPM convention (x86_64, aarch64)
+- `{deb_arch}`: DEB convention (amd64, arm64)
+- `{upstream_linux_arch}`: Mixed convention (x86_64, arm64)
+
+**Option 2: Dict Format (Per-Architecture Patterns)**
+```yaml
+upstream:
+  archive_name:
+    amd64: "my_exporter-v{clean_version}-x86_64-special.tar.gz"
+    arm64: "my_exporter-v{clean_version}-arm64-custom.tar.gz"
+```
+
+Use the dict format when upstream uses completely different naming per architecture.
+
+**Real-World Example: NATS Exporter**
+```yaml
+# NATS uses mixed convention: x86_64 for amd64, arm64 for arm64
+upstream:
+  archive_name: "prometheus-nats-exporter-v{clean_version}-linux-{upstream_linux_arch}.tar.gz"
+  # Resolves to:
+  # - amd64: prometheus-nats-exporter-v0.19.1-linux-x86_64.tar.gz
+  # - arm64: prometheus-nats-exporter-v0.19.1-linux-arm64.tar.gz
 ```
 
 ### Build Configuration

docs/user-guide/manifest-reference.md

@@ -52,6 +52,42 @@ For the full manifest schema with all available options, see the [manifest.refer
 - `strategy`: `latest_release` (default) or `pinned`
 - `archive_name`: Custom archive name pattern (optional)
 
+#### Archive Name Patterns
+
+The `archive_name` field supports two formats for handling non-standard upstream naming:
+
+**1. String Pattern (Most Common)**
+
+Use template variables for simple patterns:
+
+```yaml
+archive_name: "{name}-{clean_version}.linux-{arch}.tar.gz"
+```
+
+Available variables:
+- `{name}`: Exporter name
+- `{version}`: Raw version (e.g., v1.0.0)
+- `{clean_version}`: Version without 'v' prefix (e.g., 1.0.0)
+- `{arch}`: Standard arch (amd64, arm64)
+- `{rpm_arch}`: RPM convention (x86_64, aarch64)
+- `{deb_arch}`: DEB convention (amd64, arm64)
+- `{upstream_linux_arch}`: Mixed convention (x86_64, arm64)
+
+**2. Dict Format (Per-Architecture Patterns)**
+
+Use when upstream has completely different naming per architecture:
+
+```yaml
+archive_name:
+  amd64: "project-v{clean_version}-x86_64-special.tar.gz"
+  arm64: "project-v{clean_version}-arm64-custom.tar.gz"
+```
+
+This is useful when:
+- Upstream uses inconsistent naming across architectures
+- Each architecture has a unique file structure
+- Standard variables don't provide enough flexibility
+
 ### Build
 
 - `method`: `binary_repack` or `source_build`