From 1a5b49f83b358b5f4911925eaca6aa1c4d472ac2 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 20:43:11 +0200
Subject: [PATCH 01/74] feat: extract instruments from hardcoded logic into
 plugins
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace ~15 scattered hardcoded guitar/bass checks across Python and JS
with a unified InstrumentRegistry. Guitar, Bass, Drums, and Keys now
ship as bundled instrument plugins under plugins/instrument_<name>/,
each defining its own tunings, roles, arrangement mappings, string/key
counts, detection strategy, and icon.

Backend:
- lib/instruments.py — registry with schema validation and offset-to-MIDI
- lib/routers/instruments.py — GET /api/instruments endpoint
- Plugin loader recognizes type:instrument and registers definitions
- lib/tunings.py is registry-aware (profiles, tuning validation, presets)
- Arrangement routing uses role flags/names from registry
- Progression instrument_for_arrangement accepts registry, returns None for unknown
- Settings API validates against registered instrument IDs
- /api/tunings populates both tuningMidis AND tunings (fixes tuner sync)
- Non-stringed instruments skip string_count/tuning validation

Frontend:
- badges.js: dynamic instrument pills, key count selector (keyboard),
  per-instrument icons from plugin assets, tuner grays out for non-pitched
- songs.js: auto-filters library by current instrument's arrangement roles,
  filter options derived from registry
- instruments-settings.js: editable instrument cards with custom tunings,
  arrangement names, string counts. Persisted via instrument_overrides
- index.html: new Instruments tab, default_arrangement moved to selector
- working-tuning.js: registry-aware instrument normalization
---
 lib/appstate.py                           |   1 +
 lib/instruments.py                        | 288 ++++++++++++++++
 lib/progression.py                        |  30 +-
 lib/routers/instruments.py                |  10 +
 lib/routers/settings.py                   |  31 +-
 lib/routers/stats.py                      |  27 +-
 lib/routers/tunings.py                    |  56 ++-
 lib/routers/ws_highway.py                 | 117 ++++---
 lib/tunings.py                            | 248 +++++++++++---
 main.py                                   |   6 +
 plugins/__init__.py                       |  24 +-
 plugins/instrument_bass/assets/icon.svg   |  50 +++
 plugins/instrument_bass/plugin.json       |  60 ++++
 plugins/instrument_drums/assets/icon.svg  |  28 ++
 plugins/instrument_drums/plugin.json      |  25 ++
 plugins/instrument_guitar/assets/icon.svg |  69 ++++
 plugins/instrument_guitar/plugin.json     |  72 ++++
 plugins/instrument_piano/assets/icon.svg  |  18 +
 plugins/instrument_piano/plugin.json      |  27 ++
 server.py                                 |  14 +-
 static/capabilities/working-tuning.js     |  33 +-
 static/v3/badges.js                       | 210 ++++++++----
 static/v3/index.html                      |  26 +-
 static/v3/instruments-settings.js         | 396 ++++++++++++++++++++++
 static/v3/songs.js                        |  77 ++++-
 25 files changed, 1745 insertions(+), 198 deletions(-)
 create mode 100644 lib/instruments.py
 create mode 100644 lib/routers/instruments.py
 create mode 100644 plugins/instrument_bass/assets/icon.svg
 create mode 100644 plugins/instrument_bass/plugin.json
 create mode 100644 plugins/instrument_drums/assets/icon.svg
 create mode 100644 plugins/instrument_drums/plugin.json
 create mode 100644 plugins/instrument_guitar/assets/icon.svg
 create mode 100644 plugins/instrument_guitar/plugin.json
 create mode 100644 plugins/instrument_piano/assets/icon.svg
 create mode 100644 plugins/instrument_piano/plugin.json
 create mode 100644 static/v3/instruments-settings.js

diff --git a/lib/appstate.py b/lib/appstate.py
index c726a48e..04b92053 100644
--- a/lib/appstate.py
+++ b/lib/appstate.py
@@ -138,6 +138,7 @@ def artist_page(name):
     "default_settings",
     "kick_scan", "invalidate_song_caches", "stat_for_cache", "scan_status",
     "server_root",
+    "instrument_registry",
 })
 
 
diff --git a/lib/instruments.py b/lib/instruments.py
new file mode 100644
index 00000000..d1ab3607
--- /dev/null
+++ b/lib/instruments.py
@@ -0,0 +1,288 @@
+import logging
+
+log = logging.getLogger("feedBack.instruments")
+
+_INSTRUMENT_KINDS = frozenset({"stringed", "percussion", "keyboard", "vocal", "custom"})
+_DETECT_STRATEGIES = frozenset({"pitch", "onset", "midi", "none"})
+_PATH_FLAGS = frozenset({"path_lead", "path_rhythm", "path_bass"})
+_PROFILE_PATHWAYS = ("songs", "practice", "learn", "studio")
+
+
+def _validate_str(value, field_name, max_len=128):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field_name} must be a non-empty string")
+    if len(value) > max_len:
+        raise ValueError(f"{field_name} must be <= {max_len} chars")
+    return value.strip()
+
+
+def _validate_optional_str(value, field_name, max_len=256):
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{field_name} must be a string or null")
+    if len(value) > max_len:
+        raise ValueError(f"{field_name} must be <= {max_len} chars")
+    return value
+
+
+def _validate_float_range(value, field_name, lo, hi):
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise ValueError(f"{field_name} must be a number")
+    v = float(value)
+    if v < lo or v > hi:
+        raise ValueError(f"{field_name} must be in [{lo}, {hi}]")
+    return v
+
+
+def _validate_midi_list(lst, field_name, expected_len):
+    if not isinstance(lst, list):
+        raise ValueError(f"{field_name} must be a list")
+    if len(lst) != expected_len:
+        raise ValueError(f"{field_name} must have {expected_len} entries, got {len(lst)}")
+    result = []
+    for i, v in enumerate(lst):
+        if isinstance(v, bool) or not isinstance(v, (int, float)):
+            raise ValueError(f"{field_name}[{i}] must be an integer")
+        midi = int(v)
+        if midi < 0 or midi > 127:
+            raise ValueError(f"{field_name}[{i}] is out of MIDI range (0-127)")
+        result.append(midi)
+    return result
+
+
+def _validate_offset_list(lst, field_name, expected_len):
+    if not isinstance(lst, list):
+        raise ValueError(f"{field_name} must be a list of offsets")
+    if len(lst) != expected_len:
+        raise ValueError(f"{field_name} must have {expected_len} entries, got {len(lst)}")
+    result = []
+    for i, v in enumerate(lst):
+        if isinstance(v, bool) or not isinstance(v, (int, float)):
+            raise ValueError(f"{field_name}[{i}] must be an integer")
+        off = int(v)
+        if off < -12 or off > 12:
+            raise ValueError(f"{field_name}[{i}] offset {off} out of range [-12, 12]")
+        result.append(off)
+    return result
+
+
+class InstrumentRegistry:
+    def __init__(self):
+        self._instruments: dict[str, dict] = {}
+
+    def register(self, definition: dict):
+        inst_id = _validate_str(definition.get("id"), "instrument.id")
+        if inst_id in self._instruments:
+            raise ValueError(f"instrument {inst_id!r} is already registered")
+        label = _validate_str(definition.get("label", inst_id), "instrument.label")
+        kind = _validate_str(definition.get("kind", "custom"), "instrument.kind")
+        if kind not in _INSTRUMENT_KINDS:
+            raise ValueError(f"instrument.kind must be one of {sorted(_INSTRUMENT_KINDS)}")
+        icon = _validate_optional_str(definition.get("icon"), "instrument.icon")
+        detect_strategy = definition.get("detect_strategy", "none")
+        if detect_strategy not in _DETECT_STRATEGIES:
+            raise ValueError(f"instrument.detect_strategy must be one of {sorted(_DETECT_STRATEGIES)}")
+        ref_pitch = _validate_float_range(
+            definition.get("reference_pitch", 440.0), "instrument.reference_pitch", 430, 450,
+        )
+
+        string_counts = definition.get("string_counts")
+        if kind == "stringed":
+            if not isinstance(string_counts, list) or not string_counts:
+                raise ValueError("instrument.string_counts must be a non-empty list for stringed instruments")
+            sc_list = []
+            for v in string_counts:
+                if isinstance(v, bool) or not isinstance(v, (int, float)):
+                    raise ValueError("instrument.string_counts entries must be integers")
+                sc_list.append(int(v))
+            string_counts = sorted(set(sc_list))
+        else:
+            string_counts = []
+
+        default_sc = definition.get("default_string_count", 0)
+        if kind == "stringed":
+            if default_sc not in string_counts:
+                raise ValueError(f"instrument.default_string_count {default_sc} not in string_counts {string_counts}")
+        else:
+            default_sc = 0
+
+        key_counts = definition.get("key_counts")
+        if kind == "keyboard":
+            if not isinstance(key_counts, list) or not key_counts:
+                raise ValueError("instrument.key_counts must be a non-empty list for keyboard instruments")
+            kc_list = []
+            for v in key_counts:
+                if isinstance(v, bool) or not isinstance(v, (int, float)):
+                    raise ValueError("instrument.key_counts entries must be integers")
+                kc_list.append(int(v))
+            key_counts = sorted(set(kc_list))
+        else:
+            key_counts = []
+
+        default_kc = definition.get("default_key_count", 0)
+        if kind == "keyboard":
+            if default_kc not in key_counts:
+                raise ValueError(f"instrument.default_key_count {default_kc} not in key_counts {key_counts}")
+        else:
+            default_kc = 0
+
+        standard_tunings = {}
+        raw_std = definition.get("standard_tunings") or {}
+        if kind == "stringed":
+            if not isinstance(raw_std, dict):
+                raise ValueError("instrument.standard_tunings must be a dict")
+            for sc in string_counts:
+                key = str(sc)
+                if key not in raw_std:
+                    raise ValueError(f"instrument.standard_tunings missing key {key!r}")
+                standard_tunings[key] = _validate_midi_list(raw_std[key], f"standard_tunings[{key}]", sc)
+        else:
+            standard_tunings = {}
+
+        tunings = {}
+        raw_tunes = definition.get("tunings") or {}
+        if kind == "stringed":
+            if not isinstance(raw_tunes, dict):
+                raise ValueError("instrument.tunings must be a dict")
+            for sc in string_counts:
+                key = str(sc)
+                sc_tunings = raw_tunes.get(key) or {}
+                if "Standard" not in sc_tunings:
+                    raise ValueError(f"instrument.tunings[{key}] must include 'Standard'")
+                resolved = {}
+                for t_name, t_offsets in sc_tunings.items():
+                    resolved[_validate_str(t_name, f"tunings[{key}].name")] = _validate_offset_list(
+                        t_offsets, f"tunings[{key}][{t_name!r}]", sc,
+                    )
+                tunings[key] = resolved
+        else:
+            tunings = {}
+
+        roles = []
+        role_ids = set()
+        has_default = False
+        raw_roles = definition.get("roles") or []
+        if not isinstance(raw_roles, list):
+            raise ValueError("instrument.roles must be a list")
+        for i, role in enumerate(raw_roles):
+            if not isinstance(role, dict):
+                raise ValueError(f"instrument.roles[{i}] must be an object")
+            r_id = _validate_str(role.get("id"), f"roles[{i}].id", 32)
+            if r_id in role_ids:
+                raise ValueError(f"duplicate role id {r_id!r}")
+            role_ids.add(r_id)
+            r_label = _validate_str(role.get("label", r_id), f"roles[{i}].label", 32)
+            r_flags = role.get("arrangement_flags") or []
+            if not isinstance(r_flags, list):
+                raise ValueError(f"roles[{i}].arrangement_flags must be a list")
+            for flag in r_flags:
+                if flag not in _PATH_FLAGS:
+                    raise ValueError(f"roles[{i}].arrangement_flags: unknown flag {flag!r}")
+            r_names = role.get("arrangement_names") or []
+            if not isinstance(r_names, list):
+                raise ValueError(f"roles[{i}].arrangement_names must be a list")
+            r_default = bool(role.get("default"))
+            if r_default:
+                if has_default:
+                    raise ValueError("only one role can have default: true")
+                has_default = True
+            roles.append({
+                "id": r_id,
+                "label": r_label,
+                "arrangement_flags": list(set(r_flags)),
+                "arrangement_names": [n.strip().lower() for n in r_names if isinstance(n, str) and n.strip()],
+                "default": r_default,
+            })
+        if roles and not has_default:
+            roles[0]["default"] = True
+
+        normalized = {
+            "id": inst_id,
+            "label": label,
+            "kind": kind,
+            "icon": icon,
+            "_plugin_id": definition.get("_plugin_id"),
+            "string_counts": string_counts,
+            "default_string_count": default_sc,
+            "key_counts": key_counts,
+            "default_key_count": default_kc,
+            "detect_strategy": detect_strategy,
+            "reference_pitch": ref_pitch,
+            "standard_tunings": standard_tunings,
+            "tunings": tunings,
+            "roles": roles,
+        }
+        self._instruments[inst_id] = normalized
+        log.info("registered instrument %r (%s)", inst_id, label)
+
+    def unregister(self, instrument_id: str):
+        if instrument_id in self._instruments:
+            del self._instruments[instrument_id]
+            log.info("unregistered instrument %r", instrument_id)
+
+    def get(self, instrument_id: str) -> dict | None:
+        return self._instruments.get(instrument_id)
+
+    def get_all(self) -> list[dict]:
+        return list(self._instruments.values())
+
+    def compute_tuning_midis(self, instrument_id: str, string_count: int, tuning_name: str) -> list[int] | None:
+        inst = self._instruments.get(instrument_id)
+        if not inst or inst["kind"] != "stringed":
+            return None
+        key = str(string_count)
+        std = inst["standard_tunings"].get(key)
+        offsets = (inst["tunings"].get(key) or {}).get(tuning_name)
+        if not std or not offsets or len(std) != len(offsets):
+            return None
+        return [s + o for s, o in zip(std, offsets)]
+
+    def get_tuning_names(self, instrument_id: str, string_count: int) -> list[str]:
+        inst = self._instruments.get(instrument_id)
+        if not inst or inst["kind"] != "stringed":
+            return []
+        return list((inst["tunings"].get(str(string_count)) or {}).keys())
+
+    def get_standard_midis(self, instrument_id: str, string_count: int) -> list[int] | None:
+        inst = self._instruments.get(instrument_id)
+        if not inst or inst["kind"] != "stringed":
+            return None
+        return inst["standard_tunings"].get(str(string_count))
+
+    def get_default_role(self, instrument_id: str) -> str | None:
+        inst = self._instruments.get(instrument_id)
+        if not inst:
+            return None
+        for role in inst["roles"]:
+            if role["default"]:
+                return role["id"]
+        if inst["roles"]:
+            return inst["roles"][0]["id"]
+        return None
+
+    def find_role_by_arrangement(self, instrument_id: str, arr_name: str, arr_flags: dict = None) -> str | None:
+        inst = self._instruments.get(instrument_id)
+        if not inst:
+            return None
+        name_lower = (arr_name or "").strip().lower()
+        for role in inst["roles"]:
+            if name_lower in role["arrangement_names"]:
+                return role["id"]
+            if arr_flags:
+                for flag in role["arrangement_flags"]:
+                    if arr_flags.get(flag):
+                        return role["id"]
+        return None
+
+    def instrument_id_for_arrangement(self, arr_name: str, arr_flags: dict = None) -> str | None:
+        name_lower = (arr_name or "").strip().lower()
+        for inst in self._instruments.values():
+            for role in inst["roles"]:
+                if name_lower in role["arrangement_names"]:
+                    return inst["id"]
+                if arr_flags:
+                    for flag in role["arrangement_flags"]:
+                        if arr_flags.get(flag):
+                            return inst["id"]
+        return None
diff --git a/lib/progression.py b/lib/progression.py
index 777dce52..c2c595f4 100644
--- a/lib/progression.py
+++ b/lib/progression.py
@@ -328,17 +328,39 @@ def load_content(root) -> tuple[dict, list]:
 # ---------------------------------------------------------------------------
 
 
-def instrument_for_arrangement(arr_entry) -> str:
+def instrument_for_arrangement(arr_entry, *, registry=None):
     """Map a library arrangement entry to a progression instrument.
 
     archive/loose entries carry ``type`` (lead/rhythm/bass/combo); sloppaks may
-    only carry ``name``. Vocals are recognised so they never count toward
-    guitar challenges; everything else defaults to guitar.
+    only carry ``name``. Checks registered instruments first via the registry;
+    falls back to hardcoded logic for backward compat. Returns None when the
+    arrangement doesn't match any known instrument — callers must gate
+    progression events on a non-None instrument so unknown arrangements
+    never accrue to the wrong path.
     """
     if not isinstance(arr_entry, dict):
+        if registry:
+            return None
         return "guitar"
     arr_type = str(arr_entry.get("type") or "").strip().lower()
     name = str(arr_entry.get("name") or "").strip().lower()
+
+    # Registry check — any registered instrument's roles match?
+    if registry:
+        for inst in registry.get_all():
+            for role in inst.get("roles", []):
+                if name in role.get("arrangement_names", []):
+                    return inst["id"]
+                if arr_type in role.get("arrangement_names", []):
+                    return inst["id"]
+        # Also check flags: build a virtual arr_entry for path flag matching
+        for inst in registry.get_all():
+            for role in inst.get("roles", []):
+                for flag in role.get("arrangement_flags", []):
+                    if arr_entry.get(flag):
+                        return inst["id"]
+
+    # Hardcoded fallback for known instruments
     if arr_type == "bass":
         return "bass"
     if arr_type == "drums":
@@ -361,6 +383,8 @@ def instrument_for_arrangement(arr_entry) -> str:
         return "keys"
     if arr_type in ("lead", "rhythm", "combo"):
         return "guitar"
+    if registry:
+        return None
     return "guitar"
 
 
diff --git a/lib/routers/instruments.py b/lib/routers/instruments.py
new file mode 100644
index 00000000..5dbb6de9
--- /dev/null
+++ b/lib/routers/instruments.py
@@ -0,0 +1,10 @@
+from fastapi import APIRouter
+import appstate
+
+router = APIRouter()
+
+
+@router.get("/api/instruments")
+def get_instruments():
+    reg = getattr(appstate, "instrument_registry", None)
+    return reg.get_all() if reg else []
diff --git a/lib/routers/settings.py b/lib/routers/settings.py
index 853533b1..7d1366f4 100644
--- a/lib/routers/settings.py
+++ b/lib/routers/settings.py
@@ -25,7 +25,7 @@
 from tunings import (
     PROFILE_IDS, PROFILE_PATHWAYS, apply_flat_instrument_patch_to_profiles,
     normalize_instrument_profile, normalize_instrument_profiles,
-    settings_with_instrument_profiles,
+    settings_with_instrument_profiles, _valid_instrument_ids,
 )
 
 import logging
@@ -244,8 +244,9 @@ def save_settings(data: dict):
     if "instrument" in data:
         raw = data["instrument"]
         if raw is not None:
-            if not isinstance(raw, str) or raw not in ("guitar", "bass"):
-                return {"error": "instrument must be 'guitar' or 'bass'"}
+            valid_ids = _valid_instrument_ids()
+            if not isinstance(raw, str) or raw not in valid_ids:
+                return {"error": "instrument must be one of " + str(sorted(valid_ids))}
             updates["instrument"] = raw
     if "string_count" in data:
         raw = data["string_count"]
@@ -257,6 +258,16 @@ def save_settings(data: dict):
             if sc < 4 or sc > 8:
                 return {"error": "string_count must be an integer 4–8"}
             updates["string_count"] = sc
+    if "key_count" in data:
+        raw = data["key_count"]
+        if raw is not None:
+            try:
+                kc = _as_int(raw)
+            except (TypeError, ValueError, OverflowError):
+                return {"error": "key_count must be an integer"}
+            if kc < 1 or kc > 127:
+                return {"error": "key_count must be an integer 1–127"}
+            updates["key_count"] = kc
     if "tuning" in data:
         raw = data["tuning"]
         # Accept a tuning NAME (string ≤64) or a list of up to 8 semitone
@@ -303,8 +314,14 @@ def save_settings(data: dict):
         raw = data["active_instrument_profile"]
         if raw is not None:
             if not isinstance(raw, str) or raw not in PROFILE_IDS:
-                return {"error": "active_instrument_profile must be one of guitar-lead, guitar-rhythm, bass"}
+                return {"error": "active_instrument_profile must be one of " + ", ".join(PROFILE_IDS)}
             updates["active_instrument_profile"] = raw
+    if "instrument_overrides" in data:
+        raw = data["instrument_overrides"]
+        if raw is not None:
+            if not isinstance(raw, dict):
+                return {"error": "instrument_overrides must be an object"}
+            updates["instrument_overrides"] = raw
     appstate.config_dir.mkdir(parents=True, exist_ok=True)
     # Critical section — the read-merge-write must be atomic. FastAPI runs
     # sync handlers in a threadpool, so two concurrent partial POSTs (e.g.
@@ -455,8 +472,8 @@ def _validate_server_config_types(cfg: dict) -> str | None:
             return "server_config.reference_pitch must be a number between 430 and 450"
     if "instrument" in cfg:
         v = cfg["instrument"]
-        if v is not None and v not in ("guitar", "bass"):
-            return "server_config.instrument must be 'guitar' or 'bass'"
+        if v is not None and v not in _valid_instrument_ids():
+            return "server_config.instrument must be one of " + str(sorted(_valid_instrument_ids()))
     if "string_count" in cfg:
         v = cfg["string_count"]
         if v is not None and (isinstance(v, bool) or not isinstance(v, int) or not (4 <= v <= 8)):
@@ -483,7 +500,7 @@ def _validate_server_config_types(cfg: dict) -> str | None:
     if "active_instrument_profile" in cfg:
         v = cfg["active_instrument_profile"]
         if v is not None and (not isinstance(v, str) or v not in PROFILE_IDS):
-            return "server_config.active_instrument_profile must be one of guitar-lead, guitar-rhythm, bass"
+            return "server_config.active_instrument_profile must be one of " + ", ".join(PROFILE_IDS)
     return None
 
 
diff --git a/lib/routers/stats.py b/lib/routers/stats.py
index 5b8ed442..859fb244 100644
--- a/lib/routers/stats.py
+++ b/lib/routers/stats.py
@@ -151,20 +151,23 @@ def api_record_stats(data: dict):
         progression_summary = None
         try:
             import progression as progression_mod
+            reg = getattr(appstate, "instrument_registry", None)
             instrument = progression_mod.instrument_for_arrangement(
-                appstate.meta_db.arrangement_entry(filename, arrangement)
-            )
-            progression_summary = appstate.meta_db.record_progression_event(
-                "song_completed",
-                {
-                    "filename": filename,
-                    "instrument": instrument,
-                    "accuracy": accuracy,
-                    "score": score,
-                    "is_diagnostic": filename == appstate.builtin_diagnostic_filename(),
-                },
-                appstate.get_progression_content(),
+                appstate.meta_db.arrangement_entry(filename, arrangement),
+                registry=reg,
             )
+            if instrument is not None:
+                progression_summary = appstate.meta_db.record_progression_event(
+                    "song_completed",
+                    {
+                        "filename": filename,
+                        "instrument": instrument,
+                        "accuracy": accuracy,
+                        "score": score,
+                        "is_diagnostic": filename == appstate.builtin_diagnostic_filename(),
+                    },
+                    appstate.get_progression_content(),
+                )
         except Exception:
             log.warning("stats side-effects (progression) failed", exc_info=True)
         return {"stats": row, "progress": progress, "progression": progression_summary}
diff --git a/lib/routers/tunings.py b/lib/routers/tunings.py
index 723fe6d0..0bee97e8 100644
--- a/lib/routers/tunings.py
+++ b/lib/routers/tunings.py
@@ -10,7 +10,7 @@
 
 import appstate
 from appconfig import _load_config
-from tunings import DEFAULT_REFERENCE_PITCH, TUNING_PRESET_MIDIS, freqs_to_midis
+from tunings import DEFAULT_REFERENCE_PITCH, freqs_to_midis, open_midis_to_freqs, _build_preset_midis, instrument_key
 
 router = APIRouter()
 
@@ -34,8 +34,36 @@ def get_tunings():
     # references — so serve the integers once, host-side. Additive: the
     # existing referencePitch/tunings shape is unchanged.
     tuning_midis: dict[str, dict[str, list[int]]] = {}
+    preset_midis = _build_preset_midis()
+
+    # Merge custom tunings from instrument_overrides in config.json.
+    # Custom tunings are stored as offset arrays keyed by instrument_id and
+    # string count; they need to be resolved to MIDI via the instrument's
+    # standard tuning reference.
+    reg = getattr(appstate, "instrument_registry", None)
+    overrides = (cfg.get("instrument_overrides") or {}) if isinstance(cfg, dict) else {}
+    if reg and overrides:
+        for inst_id, ov in overrides.items():
+            custom_tunings = ov.get("custom_tunings") if isinstance(ov, dict) else None
+            if not custom_tunings or not isinstance(custom_tunings, dict):
+                continue
+            inst_def = reg.get(inst_id)
+            if not inst_def or inst_def.get("kind") != "stringed":
+                continue
+            std = inst_def.get("standard_tunings") or {}
+            for sc_key, named_offsets in custom_tunings.items():
+                key = instrument_key(inst_id, int(sc_key))
+                std_midis = std.get(sc_key)
+                if not std_midis:
+                    continue
+                for t_name, offsets in named_offsets.items():
+                    if isinstance(offsets, list) and len(offsets) == len(std_midis):
+                        midis = [int(s + o) for s, o in zip(std_midis, offsets)]
+                        if all(0 <= m <= 127 for m in midis):
+                            preset_midis.setdefault(key, {})[str(t_name)] = midis
+
     for key, names in merged.items():
-        builtin = TUNING_PRESET_MIDIS.get(key, {})
+        builtin = preset_midis.get(key, {})
         resolved: dict[str, list[int]] = {}
         for name, freqs in names.items():
             midis = builtin.get(name) or freqs_to_midis(freqs, ref)
@@ -43,4 +71,28 @@ def get_tunings():
                 resolved[name] = list(midis)
         if resolved:
             tuning_midis[key] = resolved
+
+    # Ensure every key from preset_midis appears in BOTH tuningMidis and tunings
+    # (frequencies). The tuner plugin reads `tunings` for the instrument key
+    # list; without this, instrument switches have no effect.
+    for key, presets in preset_midis.items():
+        builtin_freqs = {}
+        for name, midis in presets.items():
+            builtin_freqs[name] = open_midis_to_freqs(midis, ref)
+        # tuningMidis
+        if key not in tuning_midis:
+            tuning_midis[key] = {str(k): list(v) for k, v in presets.items()}
+        else:
+            existing = tuning_midis[key]
+            for name, midis in presets.items():
+                if name not in existing:
+                    existing[str(name)] = list(midis)
+        # tunings (frequencies) — add provider data first, then fill gaps
+        if key not in merged:
+            merged[key] = builtin_freqs
+        else:
+            for name, freqs in builtin_freqs.items():
+                if name not in merged[key]:
+                    merged[key][name] = freqs
+
     return {"referencePitch": ref, "tunings": merged, "tuningMidis": tuning_midis}
diff --git a/lib/routers/ws_highway.py b/lib/routers/ws_highway.py
index 62cd152b..53c9be76 100644
--- a/lib/routers/ws_highway.py
+++ b/lib/routers/ws_highway.py
@@ -245,47 +245,84 @@ async def _send_keepalives():
                 except Exception:
                     pass
             # Instrument routing: load the part that matches the selected instrument so
-            # "your instrument" and "the chart you play" line up. The default ordering
-            # is Lead/guitar-first, so without this a bass player gets handed a guitar
-            # chart (and any tune-check then compares a 4-string bass against a 6-string
-            # part). Currently routes bass -> a Bass arrangement; guitar — and any
-            # unknown/future instrument (drums, keys) — falls through to the
-            # preference/most-notes logic below, which already lands on a guitar part.
-            # Drums/keys get their own match when those arrangement types + selector
-            # entries land. Only applies when no explicit arrangement was requested, so
-            # a manual arrangement switch is always respected.
-            if sel_instrument.lower() == "bass":
-                # Candidate bass parts, preferring the structured pathBass flag; the
-                # normalized smart name (itself pathBass-derived) and raw name are
-                # fallbacks for sources without the flag.
-                bass_idxs = [
-                    i
-                    for i, a in enumerate(song.arrangements)
-                    if getattr(a, "path_bass", False)
-                    or (smart_names[i] or "").lower().startswith("bass")
-                    or "bass" in (getattr(a, "name", "") or "").lower()
-                ]
-                if bass_idxs:
-                    # Among the bass parts: (1) honor the saved default-arrangement
-                    # preference if it names one of them (so a bass player who prefers
-                    # "Bass 2"/"Alt. Bass" keeps it), (2) else the canonical main "Bass",
-                    # (3) else the first bass part in order.
-                    pref_bass = -1
-                    if pref:
-                        for i in bass_idxs:
-                            nm = (smart_names[i] if naming_mode == "smart" and i < len(smart_names)
-                                  else getattr(song.arrangements[i], "name", ""))
-                            if nm == pref:
-                                pref_bass = i
+            # "your instrument" and "the chart you play" line up. Uses the instrument
+            # registry to find matching arrangements by path flags or arrangement names.
+            if sel_instrument and best < 0:
+                reg = getattr(appstate, "instrument_registry", None)
+                inst_def = reg.get(sel_instrument) if reg else None
+                if inst_def:
+                    matching_idxs = []
+                    for i, a in enumerate(song.arrangements):
+                        for role in inst_def.get("roles", []):
+                            for flag in role.get("arrangement_flags", []):
+                                if getattr(a, flag, False):
+                                    matching_idxs.append(i)
+                                    break
+                            else:
+                                sn = (smart_names[i] or "") if i < len(smart_names) else ""
+                                a_name = (getattr(a, "name", "") or "").lower()
+                                for pat in role.get("arrangement_names", []):
+                                    if pat == sn.lower() or pat == a_name:
+                                        matching_idxs.append(i)
+                                        break
+                                else:
+                                    continue
                                 break
-                    if pref_bass >= 0:
-                        best = pref_bass
-                    else:
-                        best = next(
-                            (i for i in bass_idxs
-                             if (smart_names[i] if i < len(smart_names) else "") == "Bass"),
-                            bass_idxs[0],
-                        )
+                    if matching_idxs:
+                        pref_match = -1
+                        if pref:
+                            for i in matching_idxs:
+                                nm = (smart_names[i] if naming_mode == "smart" and i < len(smart_names)
+                                      else getattr(song.arrangements[i], "name", ""))
+                                if nm == pref:
+                                    pref_match = i
+                                    break
+                        if pref_match >= 0:
+                            best = pref_match
+                        else:
+                            # Prefer the canonical arrangement matching the instrument's
+                            # default role, then fall back to the first match.
+                            matched = False
+                            for role in inst_def.get("roles", []):
+                                if role.get("default"):
+                                    canonical_label = role["label"]
+                                    for i in matching_idxs:
+                                        sn = (smart_names[i] if i < len(smart_names) else "")
+                                        if sn == canonical_label:
+                                            best = i
+                                            matched = True
+                                            break
+                                    if matched:
+                                        break
+                            if not matched:
+                                best = matching_idxs[0]
+                else:
+                    # Legacy fallback for when registry is unavailable
+                    if sel_instrument.lower() == "bass":
+                        bass_idxs = [
+                            i
+                            for i, a in enumerate(song.arrangements)
+                            if getattr(a, "path_bass", False)
+                            or (smart_names[i] or "").lower().startswith("bass")
+                            or "bass" in (getattr(a, "name", "") or "").lower()
+                        ]
+                        if bass_idxs:
+                            pref_bass = -1
+                            if pref:
+                                for i in bass_idxs:
+                                    nm = (smart_names[i] if naming_mode == "smart" and i < len(smart_names)
+                                          else getattr(song.arrangements[i], "name", ""))
+                                    if nm == pref:
+                                        pref_bass = i
+                                        break
+                            if pref_bass >= 0:
+                                best = pref_bass
+                            else:
+                                best = next(
+                                    (i for i in bass_idxs
+                                     if (smart_names[i] if i < len(smart_names) else "") == "Bass"),
+                                    bass_idxs[0],
+                                )
             # User's default arrangement preference (only when instrument routing did not
             # already resolve a part — i.e. guitar, or a bass player with no bass part).
             if best < 0 and pref:
diff --git a/lib/tunings.py b/lib/tunings.py
index c5d34ed6..cffd5147 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -10,6 +10,107 @@
 
 DEFAULT_REFERENCE_PITCH = 440.0
 
+_instrument_registry = None
+
+
+def set_instrument_registry(reg):
+    global _instrument_registry
+    _instrument_registry = reg
+
+
+def _build_standard_midis(registry=None):
+    reg = registry or _instrument_registry
+    result = {}
+    if reg:
+        for inst in reg.get_all():
+            if inst["kind"] == "stringed":
+                for sc_key, midis in inst.get("standard_tunings", {}).items():
+                    key = f"{inst['id']}-{sc_key}"
+                    if key not in result:
+                        result[key] = midis
+    if not result:
+        return dict(STANDARD_OPEN_MIDIS)
+    return result
+
+
+def _build_preset_midis(registry=None):
+    reg = registry or _instrument_registry
+    result = {}
+    if reg:
+        for inst in reg.get_all():
+            if inst["kind"] == "stringed":
+                std = inst.get("standard_tunings", {})
+                for sc_key, named_offsets in inst.get("tunings", {}).items():
+                    key = f"{inst['id']}-{sc_key}"
+                    std_midis = std.get(sc_key)
+                    if not std_midis:
+                        continue
+                    presets = {}
+                    for t_name, offsets in named_offsets.items():
+                        if len(std_midis) == len(offsets):
+                            presets[t_name] = [s + o for s, o in zip(std_midis, offsets)]
+                    if presets:
+                        result[key] = presets
+    if not result:
+        return {k: dict(v) for k, v in TUNING_PRESET_MIDIS.items()}
+    return result
+
+
+def _build_profile_defaults(registry=None):
+    reg = registry or _instrument_registry
+    result = {}
+    if reg:
+        for inst in reg.get_all():
+            default_role = inst["roles"][0]["id"] if inst["roles"] else inst["id"]
+            for role in inst["roles"]:
+                r_default = role.get("default", False)
+                if r_default:
+                    default_role = role["id"]
+                profile_id = f"{inst['id']}-{role['id']}"
+                result[profile_id] = {
+                    "id": profile_id,
+                    "label": f"{role['label']} {inst['label']}",
+                    "instrument": inst["id"],
+                    "role": role["id"],
+                    "string_count": inst.get("default_string_count", 0),
+                    "tuning": "Standard",
+                    "reference_pitch": inst.get("reference_pitch", DEFAULT_REFERENCE_PITCH),
+                    "pathway": "songs",
+                    "default_role": r_default,
+                }
+            if default_role and f"{inst['id']}-{default_role}" in result:
+                for pid, profile in result.items():
+                    if pid == f"{inst['id']}-{default_role}":
+                        profile["default_role"] = True
+    if not result:
+        return {pid: dict(p) for pid, p in PROFILE_DEFAULTS.items()}
+    return result
+
+
+def _build_profile_ids(registry=None):
+    profiles = _build_profile_defaults(registry)
+    return tuple(profiles.keys())
+
+
+def _valid_instrument_ids(registry=None):
+    reg = registry or _instrument_registry
+    if reg:
+        ids = {inst["id"] for inst in reg.get_all()}
+        if ids:
+            return ids
+    return {"guitar", "bass"}
+
+
+def _default_profile_id_for_instrument(instrument_id, registry=None):
+    profiles = _build_profile_defaults(registry)
+    for pid, profile in profiles.items():
+        if profile["instrument"] == instrument_id and profile.get("default_role"):
+            return pid
+    for pid, profile in profiles.items():
+        if profile["instrument"] == instrument_id:
+            return pid
+    return "guitar-lead"
+
 # Canonical open strings, low to high, as MIDI notes. This is the host-level
 # source of truth for guitar/bass tuning profiles; UI surfaces derive names,
 # frequencies, and semitone offsets from these absolute pitches.
@@ -207,8 +308,8 @@ def instrument_key(instrument: str, string_count: int) -> str:
     return f"{instrument}-{string_count}"
 
 
-def default_instrument_profiles() -> dict[str, dict]:
-    return {profile_id: dict(profile) for profile_id, profile in PROFILE_DEFAULTS.items()}
+def default_instrument_profiles(registry=None) -> dict[str, dict]:
+    return _build_profile_defaults(registry)
 
 
 def _valid_reference_pitch(value) -> float | None:
@@ -223,11 +324,13 @@ def _valid_reference_pitch(value) -> float | None:
     return ref
 
 
-def _valid_tuning_for_key(key: str, tuning):
+def _valid_tuning_for_key(key: str, tuning, *, registry=None):
+    preset_midis = _build_preset_midis(registry)
+    standard_midis = _build_standard_midis(registry)
     if isinstance(tuning, str):
         if len(tuning) > 64:
             return None
-        if tuning in TUNING_PRESET_MIDIS.get(key, {}):
+        if tuning in preset_midis.get(key, {}):
             return tuning
         # A name that IS a built-in preset for a different key is a misapplied
         # built-in (e.g. "Drop D" on a 5-string bass, whose low string is B) —
@@ -235,11 +338,11 @@ def _valid_tuning_for_key(key: str, tuning):
         # tuning (the tuner plugin's, exposed via /api/tunings) that this pure
         # layer can't resolve — accept it so settings round-trip; the provider
         # owns its validity.
-        if any(tuning in names for names in TUNING_PRESET_MIDIS.values()):
+        if any(tuning in names for names in preset_midis.values()):
             return None
         return tuning
     if isinstance(tuning, list):
-        expected = len(STANDARD_OPEN_MIDIS.get(key, []))
+        expected = len(standard_midis.get(key, []))
         if len(tuning) != expected:
             return None
         if any(isinstance(o, bool) or not isinstance(o, int) or o < -12 or o > 12 for o in tuning):
@@ -248,9 +351,10 @@ def _valid_tuning_for_key(key: str, tuning):
     return None
 
 
-def normalize_instrument_profile(profile_id: str, raw) -> tuple[dict | None, str | None]:
+def normalize_instrument_profile(profile_id: str, raw, *, registry=None) -> tuple[dict | None, str | None]:
     """Validate one persisted host instrument profile."""
-    base = dict(PROFILE_DEFAULTS.get(profile_id, {}))
+    profile_defaults = _build_profile_defaults(registry)
+    base = dict(profile_defaults.get(profile_id, {}))
     if not base:
         return None, f"unknown instrument profile: {profile_id}"
     if raw is None:
@@ -259,20 +363,31 @@ def normalize_instrument_profile(profile_id: str, raw) -> tuple[dict | None, str
         return None, f"instrument_profiles.{profile_id} must be an object"
 
     instrument = raw.get("instrument", base["instrument"])
-    if instrument not in ("guitar", "bass"):
-        return None, f"instrument_profiles.{profile_id}.instrument must be 'guitar' or 'bass'"
+    valid_ids = _valid_instrument_ids(registry)
+    if instrument not in valid_ids:
+        return None, f"instrument_profiles.{profile_id}.instrument must be one of {sorted(valid_ids)}"
 
-    try:
-        string_count = int(raw.get("string_count", base["string_count"]))
-    except (TypeError, ValueError, OverflowError):
-        return None, f"instrument_profiles.{profile_id}.string_count must be valid for the instrument"
-    key = instrument_key(instrument, string_count)
-    if key not in STANDARD_OPEN_MIDIS:
-        return None, f"instrument_profiles.{profile_id}.string_count must be valid for the instrument"
+    inst_def = None
+    reg = registry or _instrument_registry
+    if reg:
+        inst_def = reg.get(instrument)
+    is_stringed = (inst_def is not None and inst_def.get("kind") == "stringed") or instrument in ("guitar", "bass")
 
-    tuning = _valid_tuning_for_key(key, raw.get("tuning", base["tuning"]))
-    if tuning is None:
-        return None, f"instrument_profiles.{profile_id}.tuning must match {key}"
+    if is_stringed:
+        try:
+            string_count = int(raw.get("string_count", base["string_count"]))
+        except (TypeError, ValueError, OverflowError):
+            return None, f"instrument_profiles.{profile_id}.string_count must be valid for the instrument"
+        key = instrument_key(instrument, string_count)
+        standard_midis = _build_standard_midis(registry)
+        if key not in standard_midis:
+            return None, f"instrument_profiles.{profile_id}.string_count must be valid for the instrument"
+        tuning = _valid_tuning_for_key(key, raw.get("tuning", base["tuning"]), registry=registry)
+        if tuning is None:
+            return None, f"instrument_profiles.{profile_id}.tuning must match {key}"
+    else:
+        string_count = 0
+        tuning = ""
 
     ref = _valid_reference_pitch(raw.get("reference_pitch", base["reference_pitch"]))
     if ref is None:
@@ -302,42 +417,58 @@ def normalize_instrument_profile(profile_id: str, raw) -> tuple[dict | None, str
     return out, None
 
 
-def normalize_instrument_profiles(raw_profiles=None) -> tuple[dict[str, dict] | None, str | None]:
+def normalize_instrument_profiles(raw_profiles=None, *, registry=None) -> tuple[dict[str, dict] | None, str | None]:
     """Validate persisted host profiles, filling omitted built-ins with defaults."""
     if raw_profiles is None:
-        return default_instrument_profiles(), None
+        return _build_profile_defaults(registry), None
     if not isinstance(raw_profiles, dict):
         return None, "instrument_profiles must be an object"
+    profile_ids = _build_profile_ids(registry)
     profiles = {}
-    for profile_id in PROFILE_IDS:
-        profile, error = normalize_instrument_profile(profile_id, raw_profiles.get(profile_id))
+    for profile_id in profile_ids:
+        profile, error = normalize_instrument_profile(profile_id, raw_profiles.get(profile_id), registry=registry)
         if error:
             return None, error
         profiles[profile_id] = profile
     return profiles, None
 
 
-def active_profile_id(raw) -> str:
-    return raw if raw in PROFILE_DEFAULTS else DEFAULT_ACTIVE_INSTRUMENT_PROFILE
+def active_profile_id(raw, *, registry=None) -> str:
+    defaults = _build_profile_defaults(registry)
+    return raw if raw in defaults else "guitar-lead"
 
 
-def profile_from_legacy_settings(cfg: dict) -> dict:
+def profile_from_legacy_settings(cfg: dict, *, registry=None) -> dict:
     """Build an active profile from the old flat settings keys."""
-    instrument = cfg.get("instrument") if cfg.get("instrument") in ("guitar", "bass") else "guitar"
-    fallback_sc = 4 if instrument == "bass" else 6
-    try:
-        sc = int(cfg.get("string_count", fallback_sc))
-    except (TypeError, ValueError, OverflowError):
-        sc = fallback_sc
-    key = instrument_key(instrument, sc)
-    if key not in STANDARD_OPEN_MIDIS:
-        sc = fallback_sc
+    valid_ids = _valid_instrument_ids(registry)
+    instrument = cfg.get("instrument") if cfg.get("instrument") in valid_ids else "guitar"
+    inst_def = None
+    if registry:
+        inst_def = registry.get(instrument)
+    is_stringed = (inst_def is not None and inst_def.get("kind") == "stringed") or instrument in ("guitar", "bass")
+
+    if is_stringed:
+        if inst_def:
+            fallback_sc = inst_def.get("default_string_count", 6)
+        else:
+            fallback_sc = 4 if instrument == "bass" else 6
+        try:
+            sc = int(cfg.get("string_count", fallback_sc))
+        except (TypeError, ValueError, OverflowError):
+            sc = fallback_sc
         key = instrument_key(instrument, sc)
-    tuning = _valid_tuning_for_key(key, cfg.get("tuning", "Standard")) or "Standard"
+        standard_midis = _build_standard_midis(registry)
+        if key not in standard_midis:
+            sc = fallback_sc
+            key = instrument_key(instrument, sc)
+        tuning = _valid_tuning_for_key(key, cfg.get("tuning", "Standard"), registry=registry) or "Standard"
+    else:
+        sc = 0
+        tuning = ""
     ref = _valid_reference_pitch(cfg.get("reference_pitch", DEFAULT_REFERENCE_PITCH)) or DEFAULT_REFERENCE_PITCH
     pathway = cfg.get("pathway") if cfg.get("pathway") in PROFILE_PATHWAYS else "songs"
-    profile_id = "bass" if instrument == "bass" else DEFAULT_ACTIVE_INSTRUMENT_PROFILE
-    profile = dict(PROFILE_DEFAULTS[profile_id])
+    profile_id = _default_profile_id_for_instrument(instrument, registry)
+    profile = dict(_build_profile_defaults(registry)[profile_id])
     profile.update({
         "instrument": instrument,
         "string_count": sc,
@@ -348,14 +479,15 @@ def profile_from_legacy_settings(cfg: dict) -> dict:
     return profile
 
 
-def settings_with_instrument_profiles(cfg: dict) -> dict:
+def settings_with_instrument_profiles(cfg: dict, *, registry=None) -> dict:
     """Return settings with canonical host profiles and mirrored flat keys."""
+    reg = registry or _instrument_registry
     out = dict(cfg)
-    profiles, _error = normalize_instrument_profiles(out.get("instrument_profiles"))
+    profiles, _error = normalize_instrument_profiles(out.get("instrument_profiles"), registry=reg)
     if profiles is None:
-        profiles = default_instrument_profiles()
+        profiles = _build_profile_defaults(reg)
     if "instrument_profiles" not in out:
-        legacy = profile_from_legacy_settings(out)
+        legacy = profile_from_legacy_settings(out, registry=reg)
         profiles[legacy["id"]] = legacy
         # Default the active profile to the one migrated from the legacy flat
         # fields, but DON'T clobber an explicit request — a fresh-config
@@ -363,7 +495,7 @@ def settings_with_instrument_profiles(cfg: dict) -> dict:
         # overwritten by the guitar-lead inferred from defaults. active_profile_id
         # below normalizes an invalid value.
         out.setdefault("active_instrument_profile", legacy["id"])
-    active = active_profile_id(out.get("active_instrument_profile"))
+    active = active_profile_id(out.get("active_instrument_profile"), registry=reg)
     selected = profiles[active]
     out["instrument_profiles"] = profiles
     out["active_instrument_profile"] = active
@@ -375,21 +507,26 @@ def settings_with_instrument_profiles(cfg: dict) -> dict:
     return out
 
 
-def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict) -> dict:
+def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict, *, registry=None) -> dict:
     """Mirror legacy flat instrument updates into the active host profile."""
-    out = settings_with_instrument_profiles(cfg)
+    reg = registry or _instrument_registry
+    out = settings_with_instrument_profiles(cfg, registry=reg)
     if not any(k in updates for k in ("instrument", "string_count", "tuning", "reference_pitch", "pathway")):
         return out
-    active = active_profile_id(out.get("active_instrument_profile"))
+    active = active_profile_id(out.get("active_instrument_profile"), registry=reg)
     if "instrument" in updates:
-        active = "bass" if updates["instrument"] == "bass" else "guitar-lead"
+        active = _default_profile_id_for_instrument(updates["instrument"], reg)
         out["active_instrument_profile"] = active
     current = dict(out["instrument_profiles"][active])
 
     if "instrument" in updates:
         current["instrument"] = updates["instrument"]
         if "string_count" not in updates:
-            current["string_count"] = 4 if updates["instrument"] == "bass" else 6
+            inst_def = reg.get(updates["instrument"]) if reg else None
+            if inst_def:
+                current["string_count"] = inst_def.get("default_string_count", 0)
+            else:
+                current["string_count"] = 4 if updates["instrument"] == "bass" else 6
     if "string_count" in updates:
         current["string_count"] = updates["string_count"]
     if "reference_pitch" in updates:
@@ -399,11 +536,14 @@ def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict) -> dict:
     if "tuning" in updates:
         current["tuning"] = updates["tuning"]
     else:
-        key = instrument_key(current["instrument"], current["string_count"])
-        if _valid_tuning_for_key(key, current.get("tuning")) is None:
-            current["tuning"] = "Standard"
-
-    profile, error = normalize_instrument_profile(active, current)
+        inst_def = reg.get(current["instrument"]) if reg else None
+        is_str = (inst_def is not None and inst_def.get("kind") == "stringed") or current["instrument"] in ("guitar", "bass")
+        if is_str:
+            key = instrument_key(current["instrument"], current["string_count"])
+            if _valid_tuning_for_key(key, current.get("tuning"), registry=reg) is None:
+                current["tuning"] = "Standard"
+
+    profile, error = normalize_instrument_profile(active, current, registry=reg)
     if error:
         raise ValueError(error)
     out["instrument_profiles"][active] = profile
diff --git a/main.py b/main.py
index 0673b537..8151fc4a 100644
--- a/main.py
+++ b/main.py
@@ -16,6 +16,12 @@
 """
 
 import os
+import sys
+
+# Ensure lib/ is on the path for local development (Docker sets PYTHONPATH).
+_lib = os.path.join(os.path.dirname(os.path.abspath(__file__)), "lib")
+if _lib not in sys.path:
+    sys.path.insert(0, _lib)
 
 
 def run() -> None:
diff --git a/plugins/__init__.py b/plugins/__init__.py
index 6624e3ca..42a2f5e3 100644
--- a/plugins/__init__.py
+++ b/plugins/__init__.py
@@ -1038,7 +1038,8 @@ def _install_requirements(plugin_dir: Path, plugin_id: str):
         return False
 
 
-def load_plugins(app: FastAPI, context: dict, progress_cb=None, route_setup_fn=None):
+def load_plugins(app: FastAPI, context: dict, progress_cb=None, route_setup_fn=None,
+                 instrument_registry=None):
     """Discover and load all plugins from built-in and user directories.
 
     progress_cb, when provided, receives structured progress events:
@@ -1347,6 +1348,27 @@ def _is_bundled(pdir: Path, mf: dict) -> bool:
         [(plugin_id, plugin_dir) for plugin_id, plugin_dir, _ in plugin_load_specs]
     )
 
+    # ── Instrument plugin registration ────────────────────────────────────
+    if instrument_registry is not None:
+        for plugin_id, plugin_dir, manifest in plugin_load_specs:
+            if manifest.get("type") == "instrument":
+                inst_def = manifest.get("instrument")
+                if isinstance(inst_def, dict):
+                    # Stamp the plugin_id so consumers can build asset URLs
+                    # like /api/plugins/<plugin_id>/assets/icon.svg
+                    inst_def = dict(inst_def)
+                    inst_def["_plugin_id"] = plugin_id
+                    # The icon lives at the manifest root, not inside "instrument"
+                    if manifest.get("icon") and not inst_def.get("icon"):
+                        inst_def["icon"] = manifest["icon"]
+                    try:
+                        instrument_registry.register(inst_def)
+                    except ValueError as e:
+                        log.warning(
+                            "Invalid instrument definition in plugin %s: %s",
+                            plugin_id, e,
+                        )
+
     _emit_progress(
         "plugins-discovered",
         f"Discovered {len(plugin_load_specs)} plugin(s)",
diff --git a/plugins/instrument_bass/assets/icon.svg b/plugins/instrument_bass/assets/icon.svg
new file mode 100644
index 00000000..57a22fc8
--- /dev/null
+++ b/plugins/instrument_bass/assets/icon.svg
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+<svg fill="#000000" height="800px" width="800px" version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
+	 viewBox="0 0 60.024 60.024" xml:space="preserve">
+<g>
+	<path d="M23.517,38.424l-8.374,8.374l-0.707-0.707l8.374-8.374c0.391-0.391,0.391-1.023,0-1.414s-1.023-0.391-1.414,0l-8.374,8.374
+		l-0.707-0.707l9.374-9.374c0.391-0.391,0.391-1.023,0-1.414s-1.023-0.391-1.414,0L10.9,42.556l-1.414-1.415
+		c-0.192-0.191-0.453-0.299-0.727-0.293c-0.272,0.006-0.53,0.121-0.714,0.321l-2.83,3.06c-0.365,0.394-0.353,1.006,0.027,1.386
+		l8.485,8.485c0.188,0.188,0.442,0.293,0.707,0.293c0.006,0,0.013,0,0.02,0c0.272-0.006,0.53-0.121,0.715-0.321l2.83-3.06
+		c0.364-0.395,0.353-1.006-0.027-1.386l-1.414-1.414l8.374-8.374c0.391-0.391,0.391-1.023,0-1.414S23.907,38.034,23.517,38.424z
+		 M14.406,51.951l-7.07-7.07l1.471-1.59l1.385,1.386c0,0,0,0.001,0.001,0.001c0,0,0.001,0,0.001,0.001l2.119,2.12c0,0,0,0,0,0.001
+		l0.001,0l3.562,3.562L14.406,51.951z"/>
+	<path d="M59.715,2.215L59.715,2.215c-0.521-1.563-1.871-2.368-3.708-2.191c-0.067,0.005-1.549,0.144-3.668,0.809l-0.54-0.54
+		c-0.188-0.188-0.442-0.293-0.707-0.293h-2c-0.265,0-0.52,0.105-0.707,0.293l-1,1c-0.188,0.188-0.293,0.441-0.293,0.707v1.242
+		c-0.272,0.169-0.544,0.344-0.814,0.529l-0.479-0.479c-0.188-0.188-0.442-0.293-0.707-0.293h-2c-0.265,0-0.52,0.105-0.707,0.293
+		l-1,1c-0.188,0.188-0.293,0.441-0.293,0.707v2c0,0.266,0.105,0.52,0.293,0.707l0.366,0.366c-0.299,0.551-0.477,1.147-0.55,1.757
+		L25.097,28.653c0.111-0.541,0.256-1.116,0.446-1.72c0.372-1.184,0.187-2.463-0.507-3.51c-0.67-1.012-1.731-1.656-2.91-1.77
+		c-1.678-0.16-3.262,0.688-4.699,2.525l-0.115,0.146l-0.054,0.179c-0.732,2.406-3.405,8.859-6.93,9.803
+		c-2.819,0.755-4.88,1.786-6.486,3.244c-4.148,3.765-4.864,8.636-2.014,13.718c1.18,2.104,2.815,3.976,4.859,5.562
+		c0.632,0.49,1.276,0.943,1.916,1.349c1.94,1.226,4.124,1.845,6.314,1.845c1.763,0,3.531-0.401,5.179-1.212
+		c3.572-1.757,5.926-5.166,6.297-9.125l0.021-0.26c0.261-3.463,2.375-6.408,5.384-7.502c0.326-0.119,0.669-0.229,1.028-0.328
+		c0.8-0.22,1.485-0.759,1.881-1.479c0.365-0.664,0.448-1.417,0.234-2.119c-0.387-1.268-1.685-2.547-5.702-1.434
+		c-0.019,0.005-0.254,0.064-0.621,0.053l18.266-21.16c0.242-0.042,0.484-0.098,0.725-0.177c0.602-0.197,1.173-0.487,1.699-0.859
+		c0.807-0.572,1.427-1.44,1.745-2.445c0.042-0.132,0.082-0.273,0.124-0.423c0.205-0.728,0.417-1.48,1.222-2.229
+		c0.394-0.366,1.435-0.786,2.195-1.093l0.378-0.152c0.125-0.052,0.359-0.093,0.607-0.138c0.82-0.146,2.06-0.367,3.141-1.536
+		C59.806,5.237,60.185,3.631,59.715,2.215z M49.506,2.001h1.16l0.426,0.419v1.167l-0.414,0.414h-1.172l-0.414-0.414V2.415
+		L49.506,2.001z M43.506,5.001h1.172l0.414,0.414v1.172l-0.414,0.414h-1.172l-0.414-0.414V5.415L43.506,5.001z M39.215,21.286
+		l-2.792-2.793l5.165-6.037c0.136,0.315,0.294,0.625,0.497,0.919c0.611,0.889,1.433,1.52,2.352,1.862L39.215,21.286z M35.284,25.84
+		l-2.774-2.774l2.609-3.049l2.786,2.786L35.284,25.84z M31.353,30.394l-2.755-2.755l2.608-3.049l2.768,2.767L31.353,30.394z
+		 M26.555,35.866c-0.219-0.162-0.419-0.348-0.602-0.555c-0.031-0.035-0.06-0.07-0.09-0.105c-0.176-0.213-0.334-0.445-0.47-0.695
+		c-0.021-0.038-0.039-0.078-0.059-0.117c-0.132-0.261-0.245-0.535-0.328-0.826c-0.008-0.029-0.013-0.059-0.021-0.088
+		c-0.083-0.309-0.144-0.629-0.168-0.962c-0.01-0.138-0.018-0.284-0.022-0.437l2.498-2.92l2.749,2.749l-3.441,3.986
+		C26.586,35.887,26.57,35.877,26.555,35.866z M29.795,38.488c1.823-0.504,3.063-0.47,3.235,0.096c0.071,0.232,0,0.439-0.073,0.571
+		c-0.135,0.245-0.381,0.438-0.659,0.515c-0.414,0.113-0.809,0.24-1.183,0.377c-3.746,1.361-6.374,4.984-6.694,9.229l-0.019,0.229
+		c-0.305,3.258-2.245,6.066-5.188,7.514c-3.065,1.509-6.632,1.31-9.542-0.528c-0.586-0.371-1.178-0.787-1.759-1.238
+		c-1.832-1.421-3.292-3.09-4.341-4.96C1.157,45.984,1.7,42.196,5.186,39.032c1.361-1.235,3.159-2.123,5.659-2.793
+		c4.962-1.328,7.817-9.571,8.267-10.965c0.952-1.171,1.899-1.719,2.822-1.63c0.576,0.056,1.098,0.378,1.434,0.884
+		c0.359,0.542,0.457,1.2,0.266,1.806c-0.573,1.828-0.841,3.61-0.833,5.32c-0.002,0.026-0.013,0.051-0.013,0.077
+		c0.003,0.331,0.014,0.647,0.035,0.935c0.04,0.548,0.141,1.078,0.298,1.583c0.468,1.513,1.431,2.786,2.732,3.556
+		c0.022,0.013,0.042,0.02,0.064,0.033c0.152,0.086,0.3,0.16,0.48,0.245c0.002,0.001,0.004,0,0.007,0.001
+		C28.215,38.929,29.655,38.532,29.795,38.488z M57.256,5.048c-0.625,0.676-1.336,0.803-2.023,0.925
+		c-0.356,0.063-0.692,0.123-1.014,0.255l-0.368,0.149c-1.006,0.405-2.146,0.864-2.811,1.482c-1.216,1.132-1.559,2.348-1.785,3.153
+		c-0.036,0.127-0.069,0.247-0.105,0.36c-0.188,0.592-0.541,1.095-0.996,1.417c-0.363,0.257-0.755,0.456-1.166,0.591
+		c-0.186,0.061-0.367,0.103-0.542,0.127c-0.043-0.002-0.085-0.013-0.129-0.009c-0.774,0.063-1.533-0.216-2.128-0.782
+		c-0.668-0.637-1.05-1.55-1.023-2.445c0.001-0.022-0.007-0.042-0.008-0.063c0.025-0.4,0.129-0.809,0.355-1.208h1.579h0.414
+		l0.293-0.293l1-1l0.293-0.293V7.001V5.634c0.241-0.171,0.483-0.336,0.726-0.494l0.567,0.567l0.293,0.293h0.414h2h0.414l0.293-0.293
+		l1-1l0.293-0.293V4.001V2.689c1.817-0.555,3.074-0.672,3.093-0.673c1.157-0.108,1.476,0.358,1.632,0.83
+		C58.054,3.559,57.833,4.423,57.256,5.048z"/>
+</g>
+</svg>
\ No newline at end of file
diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
new file mode 100644
index 00000000..9fb2e446
--- /dev/null
+++ b/plugins/instrument_bass/plugin.json
@@ -0,0 +1,60 @@
+{
+  "id": "instrument_bass",
+  "name": "Bass",
+  "version": "1.0.0",
+  "type": "instrument",
+  "bundled": true,
+  "icon": "assets/icon.svg",
+  "icon": "assets/icon.svg",
+  "instrument": {
+    "id": "bass",
+    "label": "Bass",
+    "kind": "stringed",
+    "string_counts": [4, 5, 6],
+    "default_string_count": 4,
+    "reference_pitch": 440.0,
+    "detect_strategy": "pitch",
+    "standard_tunings": {
+      "4": [28, 33, 38, 43],
+      "5": [23, 28, 33, 38, 43],
+      "6": [23, 28, 33, 38, 43, 48]
+    },
+    "tunings": {
+      "4": {
+        "Standard":    [ 0,  0,  0,  0],
+        "Eb Standard": [-1, -1, -1, -1],
+        "D Standard":  [-2, -2, -2, -2],
+        "C# Standard": [-3, -3, -3, -3],
+        "C Standard":  [-4, -4, -4, -4],
+        "Drop D":      [-2,  0,  0,  0],
+        "Drop C":      [-4, -2, -2, -2],
+        "BEAD":        [-5, -5, -5, -5]
+      },
+      "5": {
+        "Standard":    [ 0,  0,  0,  0,  0],
+        "High C":      [ 5,  5,  5,  5,  5],
+        "Eb Standard": [-1, -1, -1, -1, -1],
+        "D Standard":  [-2, -2, -2, -2, -2],
+        "C# Standard": [-3, -3, -3, -3, -3],
+        "C Standard":  [-4, -4, -4, -4, -4],
+        "Drop A":      [-2,  0,  0,  0,  0]
+      },
+      "6": {
+        "Standard":    [ 0,  0,  0,  0,  0,  0],
+        "Eb Standard": [-1, -1, -1, -1, -1, -1],
+        "D Standard":  [-2, -2, -2, -2, -2, -2],
+        "C# Standard": [-3, -3, -3, -3, -3, -3],
+        "C Standard":  [-4, -4, -4, -4, -4, -4]
+      }
+    },
+    "roles": [
+      {
+        "id": "bass",
+        "label": "Bass",
+        "arrangement_flags": ["path_bass"],
+        "arrangement_names": ["Bass"],
+        "default": true
+      }
+    ]
+  }
+}
diff --git a/plugins/instrument_drums/assets/icon.svg b/plugins/instrument_drums/assets/icon.svg
new file mode 100644
index 00000000..aff812ec
--- /dev/null
+++ b/plugins/instrument_drums/assets/icon.svg
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+<svg fill="#000000" height="800px" width="800px" version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
+	 viewBox="0 0 512.001 512.001" xml:space="preserve">
+<g>
+	<g>
+		<path d="M499.17,440.785L303.736,254.819L476.114,73.674c9.112-0.237,18.152-3.815,25.089-10.754
+			c14.369-14.37,14.369-37.752,0-52.121c-14.371-14.37-37.752-14.371-52.122,0c-6.733,6.734-10.53,15.615-10.771,25.098
+			L256.004,209.382L73.687,35.889c-0.243-9.48-4.04-18.36-10.771-25.091C55.954,3.837,46.699,0.004,36.855,0.004
+			c-9.844,0-19.1,3.835-26.06,10.795S0,27.015,0,36.859c0,9.844,3.835,19.1,10.795,26.06c6.737,6.735,15.622,10.532,25.11,10.771
+			l172.357,181.121L12.829,440.79c-8.131,7.736-12.685,18.178-12.824,29.401c-0.139,11.222,4.155,21.776,12.091,29.713
+			c7.812,7.812,18.157,12.095,29.183,12.095c0.176,0,0.351,0,0.527-0.003c11.224-0.139,21.665-4.694,29.403-12.823l184.8-194.198
+			l184.785,194.19c7.74,8.134,18.183,12.688,29.406,12.827c0.176,0.001,0.351,0.003,0.527,0.003
+			c11.023,0,21.368-4.283,29.172-12.087c7.805-7.788,12.103-18.157,12.103-29.201C512,459.284,507.443,448.656,499.17,440.785z
+			 M463.987,25.704c3.076-3.075,7.116-4.613,11.156-4.613s8.08,1.539,11.156,4.613c6.151,6.151,6.151,16.16,0,22.311
+			c-6.152,6.151-16.16,6.151-22.313,0c-2.981-2.981-4.622-6.942-4.622-11.156C459.366,32.646,461.008,28.683,463.987,25.704z
+			 M48.012,48.015c-2.981,2.981-6.942,4.62-11.156,4.62c-4.213,0-8.176-1.64-11.155-4.62c-2.981-2.979-4.622-6.942-4.622-11.156
+			c0-4.214,1.641-8.176,4.622-11.155c2.979-2.981,6.941-4.622,11.155-4.622c4.214,0,8.176,1.641,11.156,4.622
+			c2.981,2.979,4.62,6.941,4.62,11.155C52.632,41.073,50.992,45.035,48.012,48.015z M58.405,66.759
+			c1.588-1.149,3.099-2.425,4.511-3.838c1.417-1.416,2.695-2.931,3.846-4.522L240.715,223.93l-17.183,16.352L58.405,66.759z
+			 M55.939,484.639c-3.787,3.981-8.899,6.21-14.394,6.279c-5.465,0.052-10.659-2.035-14.546-5.919
+			c-3.886-3.885-5.988-9.051-5.919-14.546c0.067-5.495,2.298-10.605,6.279-14.393L445.238,58.403
+			c1.151,1.591,2.43,3.104,3.843,4.519c1.422,1.422,2.936,2.697,4.516,3.838L55.939,484.639z M485.001,484.995
+			c-3.886,3.886-9.064,5.988-14.542,5.92c-5.495-0.067-10.608-2.299-14.398-6.281L270.556,289.686l18.649-19.598L484.64,456.056
+			c4.05,3.855,6.281,9.057,6.281,14.651C490.921,476.111,488.822,481.182,485.001,484.995z"/>
+	</g>
+</g>
+</svg>
\ No newline at end of file
diff --git a/plugins/instrument_drums/plugin.json b/plugins/instrument_drums/plugin.json
new file mode 100644
index 00000000..6d34924e
--- /dev/null
+++ b/plugins/instrument_drums/plugin.json
@@ -0,0 +1,25 @@
+{
+  "id": "instrument_drums",
+  "name": "Drums",
+  "version": "1.0.0",
+  "type": "instrument",
+  "bundled": true,
+  "icon": "assets/icon.svg",
+  "instrument": {
+    "id": "drums",
+    "label": "Drums",
+    "kind": "percussion",
+    "string_counts": [],
+    "default_string_count": 0,
+    "reference_pitch": 440.0,
+    "detect_strategy": "onset",
+    "roles": [
+      {
+        "id": "drums",
+        "label": "Drums",
+        "arrangement_names": ["Drums", "Drum Kit", "Percussion"],
+        "default": true
+      }
+    ]
+  }
+}
diff --git a/plugins/instrument_guitar/assets/icon.svg b/plugins/instrument_guitar/assets/icon.svg
new file mode 100644
index 00000000..b8d04b1c
--- /dev/null
+++ b/plugins/instrument_guitar/assets/icon.svg
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+<svg fill="#000000" height="800px" width="800px" version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
+	 viewBox="0 0 512 512" xml:space="preserve">
+<g>
+	<g>
+		<path d="M509.107,36.526c-3.839-5.521-7.663-11.09-10.345-15.013c-1.948-2.848-5.427-6.328-8.276-8.274
+			c-3.691-2.524-9.292-6.367-15.015-10.346c-3.758-2.614-8.187-3.512-12.158-2.465c-3.44,0.908-6.287,3.253-7.813,6.433
+			c-7.546,15.742-27.272,30.573-33.139,34.743c-3.072,2.184-5.19,5.496-5.962,9.326l-1.425,7.078
+			c-0.147,0.732-0.428,1.299-0.833,1.684L270.666,196.153c-1.978-2.665-3.61-4.657-4.854-5.901
+			c-25.882-25.882-66.031-27.857-89.502-4.398c-6.526,6.526-11.25,16.714-13.658,29.457c-4.402,23.203-24.453,39.894-47.814,39.894
+			c-0.198,0-0.397-0.001-0.597-0.003c-33.051-0.385-63.96,11.314-84.737,32.092C-15.438,332.235-8.22,412.581,45.596,466.397
+			c30.081,30.081,68.438,45.606,104.281,45.603c28.288-0.002,55.012-9.677,74.837-29.502c22.251-22.263,33.863-55.411,31.86-90.949
+			c-1.338-23.628,14.198-44.661,36.948-50.013c11.089-2.618,19.707-6.943,25.618-12.854c6.023-6.023,10.477-13.195,13.229-21.297
+			c3.029-8.834,1.797-18.412-3.378-26.279c-5.102-7.756-13.267-12.607-22.401-13.309c-3.909-0.302-7.591-1.997-10.368-4.775
+			c-0.168-0.168-0.318-0.348-0.477-0.522L452.292,97.846c0.387-0.406,0.955-0.687,1.689-0.834l7.076-1.418
+			c3.836-0.769,7.153-2.887,9.34-5.964c4.17-5.866,19.001-25.591,34.742-33.136c3.18-1.524,5.524-4.371,6.432-7.812
+			C512.618,44.715,511.72,40.284,509.107,36.526z M57.144,454.849c-4.554-4.555-8.734-9.318-12.542-14.241l19.243-13.534
+			l21.083,21.085l-13.53,19.237C66.472,463.585,61.702,459.408,57.144,454.849z M305.336,284.081
+			c4.059,0.311,7.707,2.499,10.011,6.001c2.377,3.614,2.95,7.989,1.566,12.027c-1.948,5.732-5.084,10.786-9.322,15.025
+			c-3.681,3.681-9.844,6.623-17.817,8.506c-30.472,7.169-51.292,35.276-49.505,66.83c1.742,30.9-8.138,59.505-27.104,78.482
+			c-16.686,16.686-39.243,24.803-63.318,24.802c-21.494-0.001-44.193-6.48-64.991-19.102l17.381-24.713
+			c2.283-3.247,1.902-7.665-0.906-10.471l-30.794-30.794c-2.807-2.807-7.225-3.188-10.471-0.906l-24.716,17.383
+			c-26.759-44.089-25.88-96.727,5.704-128.311c17.688-17.688,44.29-27.634,72.995-27.31c0.268,0.003,0.532,0.004,0.799,0.004
+			c31.2-0.001,57.983-22.25,63.851-53.186c1.771-9.373,5.025-16.812,9.159-20.946c17.101-17.092,46.892-15.119,66.408,4.396
+			c0.737,0.737,2.227,2.577,4.47,5.702l-40.49,38.51c-1.595,1.517-2.51,3.614-2.538,5.815c-0.028,2.201,0.835,4.32,2.391,5.876
+			l36.22,36.22c1.532,1.532,3.609,2.392,5.774,2.392c0.034,0,0.069,0,0.103-0.001c2.2-0.027,4.297-0.943,5.815-2.539l18.464-19.42
+			c0.07,0.072,0.13,0.149,0.199,0.219C290.205,280.103,297.542,283.48,305.336,284.081z M259.944,276.453l-24.378-24.378
+			L421.651,75.092l15.246,15.247L259.944,276.453z M457.449,79.662l-6.674,1.337c-0.033,0.007-0.065,0.016-0.098,0.023
+			l-19.707-19.708c0.005-0.028,0.014-0.056,0.021-0.085l1.344-6.676c8.224-5.897,26.308-20.068,35.888-36.815
+			c5.023,3.484,9.781,6.747,13.05,8.982c1.18,0.807,3.204,2.831,4.012,4.011c2.366,3.46,5.611,8.19,8.979,13.046
+			C477.516,53.357,463.346,71.436,457.449,79.662z"/>
+	</g>
+</g>
+<g>
+	<g>
+		<path d="M218.687,371.617l-0.167-0.28c-2.854-4.777-9.611-5.381-13.163-1.095c-5.237,6.319-11.479,17.273-14.44,35.327
+			c-2.429,14.816-6.708,23.47-9.768,28.045c-1.881,2.812-1.841,6.488,0.147,9.226c0.001,0.001,0.001,0.001,0.001,0.001
+			c3.302,4.667,10.261,4.597,13.442-0.155c4.359-6.513,9.486-17.349,12.295-34.475c2.102-12.824,6.069-20.689,9.026-25.029
+			c0.669-0.982,1.316-1.831,1.922-2.559C220.104,378.071,220.389,374.468,218.687,371.617z"/>
+	</g>
+</g>
+<g>
+	<g>
+		<path d="M140.767,293.398c-2.759-1.952-6.421-1.977-9.235-0.103c-4.53,3.018-13.173,7.286-28.037,9.724
+			c-32.266,5.291-41.851,21.064-42.839,22.845c-2.185,3.944-0.76,8.915,3.186,11.1h0.001c3.944,2.185,8.914,0.76,11.1-3.186
+			c0.058-0.105,6.897-10.659,31.197-14.644c17.126-2.808,27.961-7.935,34.474-12.294C145.364,303.659,145.434,296.7,140.767,293.398
+			z"/>
+	</g>
+</g>
+<g>
+	<g>
+		<path d="M133.667,418.371l-40.033-40.033c-3.189-3.189-8.359-3.189-11.547,0c-3.189,3.189-3.189,8.358,0,11.547l40.033,40.033
+			c1.594,1.595,3.684,2.392,5.774,2.392c2.089,0,4.18-0.797,5.774-2.392C136.856,426.729,136.856,421.56,133.667,418.371z"/>
+	</g>
+</g>
+<g>
+	<g>
+		<path d="M160.611,391.427l-40.033-40.033c-3.189-3.189-8.359-3.189-11.547,0c-3.189,3.189-3.189,8.358,0,11.547l40.033,40.033
+			c1.594,1.595,3.684,2.392,5.774,2.392s4.18-0.797,5.774-2.392C163.8,399.785,163.8,394.616,160.611,391.427z"/>
+	</g>
+</g>
+<g>
+	<g>
+		<path d="M180.626,371.409l-40.033-40.033c-3.189-3.189-8.359-3.189-11.547,0c-3.189,3.189-3.189,8.358,0,11.547l40.033,40.033
+			c1.594,1.595,3.684,2.392,5.774,2.392c2.089,0,4.18-0.797,5.774-2.392C183.816,379.769,183.816,374.598,180.626,371.409z"/>
+	</g>
+</g>
+</svg>
\ No newline at end of file
diff --git a/plugins/instrument_guitar/plugin.json b/plugins/instrument_guitar/plugin.json
new file mode 100644
index 00000000..a725dbc2
--- /dev/null
+++ b/plugins/instrument_guitar/plugin.json
@@ -0,0 +1,72 @@
+{
+  "id": "instrument_guitar",
+  "name": "Guitar",
+  "version": "1.0.0",
+  "type": "instrument",
+  "bundled": true,
+  "icon": "assets/icon.svg",
+  "instrument": {
+    "id": "guitar",
+    "label": "Guitar",
+    "kind": "stringed",
+    "string_counts": [6, 7, 8],
+    "default_string_count": 6,
+    "reference_pitch": 440.0,
+    "detect_strategy": "pitch",
+    "standard_tunings": {
+      "6": [40, 45, 50, 55, 59, 64],
+      "7": [35, 40, 45, 50, 55, 59, 64],
+      "8": [30, 35, 40, 45, 50, 55, 59, 64]
+    },
+    "tunings": {
+      "6": {
+        "Standard":    [ 0,  0,  0,  0,  0,  0],
+        "Eb Standard": [-1, -1, -1, -1, -1, -1],
+        "D Standard":  [-2, -2, -2, -2, -2, -2],
+        "C# Standard": [-3, -3, -3, -3, -3, -3],
+        "C Standard":  [-4, -4, -4, -4, -4, -4],
+        "Drop D":      [-2,  0,  0,  0,  0,  0],
+        "Drop C":      [-4, -2, -2, -2, -2, -2],
+        "Drop B":      [-5, -3, -3, -3, -3, -3],
+        "Drop A":      [-7, -5, -5, -5, -5, -5],
+        "Drop Ab":     [-8, -6, -6, -6, -6, -6],
+        "Open G":      [-2,  0,  0,  0,  0, -2],
+        "Open D":      [-2,  0,  0, -1, -2, -2],
+        "DADGAD":      [-2,  0,  0,  0, -2, -2],
+        "Open E":      [ 0,  2,  2,  1,  0,  0]
+      },
+      "7": {
+        "Standard":    [ 0,  0,  0,  0,  0,  0,  0],
+        "Bb Standard": [-1, -1, -1, -1, -1, -1, -1],
+        "A Standard":  [-2, -2, -2, -2, -2, -2, -2],
+        "G Standard":  [-4, -4, -4, -4, -4, -4, -4],
+        "Drop A":      [-2,  0,  0,  0,  0,  0,  0],
+        "Drop G":      [-4, -2, -2, -2, -2, -2, -2],
+        "Drop F#":     [-5, -3, -3, -3, -3, -3, -3]
+      },
+      "8": {
+        "Standard":       [ 0,  0,  0,  0,  0,  0,  0,  0],
+        "Drop E":         [-2,  0,  0,  0,  0,  0,  0,  0],
+        "Drop A + Drop E":[-2, -2,  0,  0,  0,  0,  0,  0],
+        "E Standard":     [-2, -2, -2, -2, -2, -2, -2, -2],
+        "Eb Standard":    [-3, -3, -3, -3, -3, -3, -3, -3],
+        "Drop D":         [-4, -2, -2, -2, -2, -2, -2, -2]
+      }
+    },
+    "roles": [
+      {
+        "id": "lead",
+        "label": "Lead",
+        "arrangement_flags": ["path_lead"],
+        "arrangement_names": ["Lead", "Lead Guitar"],
+        "default": true
+      },
+      {
+        "id": "rhythm",
+        "label": "Rhythm",
+        "arrangement_flags": ["path_rhythm"],
+        "arrangement_names": ["Rhythm", "Rhythm Guitar"]
+      }
+    ]
+  }
+}
diff --git a/plugins/instrument_piano/assets/icon.svg b/plugins/instrument_piano/assets/icon.svg
new file mode 100644
index 00000000..9d01df28
--- /dev/null
+++ b/plugins/instrument_piano/assets/icon.svg
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+<svg fill="#000000" height="800px" width="800px" version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
+	 viewBox="0 0 512 512" xml:space="preserve">
+<g>
+	<g>
+		<path d="M503.248,88.852H8.752C3.918,88.852,0,92.771,0,97.604v316.792c0,4.833,3.918,8.752,8.752,8.752h494.497
+			c4.833,0,8.752-3.918,8.752-8.752V97.604C512,92.771,508.082,88.852,503.248,88.852z M117.796,405.645H49.009v-239.78h42.108
+			v143.064c0,4.832,3.918,8.75,8.752,8.75h17.927V405.645z M108.62,300.177v-0.001V165.864h35.855v134.313H108.62z M204.098,405.646
+			H135.3v-87.967h17.928c4.833,0,8.752-3.918,8.752-8.752V165.864h42.119V405.646z M290.388,405.646H221.6V165.864h0.001h42.108
+			v143.064c0,4.833,3.918,8.752,8.752,8.752h17.927V405.646z M281.213,300.177v-0.001V165.864h35.855v134.313H281.213z
+			 M376.69,405.646h-68.798v-87.967h17.928c4.833,0,8.752-3.918,8.752-8.752V165.864h15.44v143.064c0,4.833,3.918,8.752,8.752,8.752
+			h17.927V405.646z M367.514,300.177v-0.001V165.864h35.855v134.313H367.514z M462.991,405.646h-68.798v-0.001v-87.965h17.928
+			c4.833,0,8.752-3.918,8.752-8.752V165.864h42.119V405.646z M494.497,405.645h-14.003V157.113c0-4.833-3.918-8.752-8.752-8.752
+			H40.257c-4.833,0-8.752,3.918-8.752,8.752v248.533H17.503v-299.29h476.994V405.645z"/>
+	</g>
+</g>
+</svg>
\ No newline at end of file
diff --git a/plugins/instrument_piano/plugin.json b/plugins/instrument_piano/plugin.json
new file mode 100644
index 00000000..eeb741ed
--- /dev/null
+++ b/plugins/instrument_piano/plugin.json
@@ -0,0 +1,27 @@
+{
+  "id": "instrument_piano",
+  "name": "Piano/Keys",
+  "version": "1.0.0",
+  "type": "instrument",
+  "bundled": true,
+  "icon": "assets/icon.svg",
+  "instrument": {
+    "id": "keys",
+    "label": "Keys",
+    "kind": "keyboard",
+    "string_counts": [],
+    "default_string_count": 0,
+    "key_counts": [25, 49, 61, 88],
+    "default_key_count": 88,
+    "reference_pitch": 440.0,
+    "detect_strategy": "midi",
+    "roles": [
+      {
+        "id": "keys",
+        "label": "Keys",
+        "arrangement_names": ["Keys", "Piano", "Keyboard", "Synth", "Synth Lead"],
+        "default": true
+      }
+    ]
+  }
+}
diff --git a/server.py b/server.py
index ecb68637..4e4211c7 100644
--- a/server.py
+++ b/server.py
@@ -26,8 +26,9 @@
 from appconfig import _load_config
 from tunings import (
     DEFAULT_REFERENCE_PITCH, DEFAULT_TUNINGS,
-    apply_reference_pitch, tuning_name,
+    apply_reference_pitch, tuning_name, set_instrument_registry,
 )
+from instruments import InstrumentRegistry
 # The library metadata cache. `MetadataDB` and the query helpers it owns live in
 # their own module; the `meta_db` singleton below stays here. The private names
 # are re-imported because callers outside the DB layer still use them.
@@ -55,6 +56,7 @@
 from routers import art as art_router
 from routers import settings as settings_router
 from routers import song as song_router
+from routers import instruments as instruments_router
 from routers import library as library_router
 from routers import enrichment as enrichment_routes
 from routers import media as media_router
@@ -164,6 +166,9 @@ def _env_flag(name: str) -> bool:
     local_library_provider=_local_library_provider,
 )
 
+instrument_registry = InstrumentRegistry()
+appstate.configure(instrument_registry=instrument_registry)
+
 
 
 
@@ -923,7 +928,9 @@ def _log_deferred(f: concurrent.futures.Future):
                 error=None,
             )
             load_plugins(app, plugin_context, progress_cb=_on_progress,
-                         route_setup_fn=_route_setup_on_main)
+                         route_setup_fn=_route_setup_on_main,
+                         instrument_registry=instrument_registry)
+            set_instrument_registry(instrument_registry)
             # Self-heal a freshly recreated container: its filesystem reset to
             # the image-baked sheet (in-tree plugins only), but a mounted
             # FEEDBACK_PLUGINS_DIR may carry user-installed plugins whose
@@ -1372,6 +1379,9 @@ def _invalidate_song_caches(cache_key: str) -> None:
 # ── Settings routes → routers/settings.py (R3) ──────────────────────────────
 app.include_router(settings_router.router)
 
+# ── Instruments routes → routers/instruments.py ───────────────────────────
+app.include_router(instruments_router.router)
+
 
 def _default_settings():
     """Fallback settings returned when config.json is missing or
diff --git a/static/capabilities/working-tuning.js b/static/capabilities/working-tuning.js
index 133447c5..dcfd3990 100644
--- a/static/capabilities/working-tuning.js
+++ b/static/capabilities/working-tuning.js
@@ -40,11 +40,32 @@
     let _touched = false;       // set once anything explicitly writes/selects; gates the async seed
 
     function _normInstrument(instrument) {
-        return instrument === 'bass' ? 'bass' : 'guitar';
+        if (!instrument || typeof instrument !== 'string') return 'guitar';
+        var inst = _getInstDef(instrument);
+        if (inst) return inst.id;
+        if (instrument === 'bass' || instrument === 'guitar') return instrument;
+        return 'guitar';
+    }
+
+    function _getInstDef(instId) {
+        var insts = window.feedBack && window.feedBack._instruments;
+        if (Array.isArray(insts)) {
+            for (var i = 0; i < insts.length; i++) {
+                if (insts[i].id === instId) return insts[i];
+            }
+        }
+        return null;
+    }
+
+    function _defaultStringCount(instrument) {
+        var inst = _getInstDef(instrument);
+        if (inst && inst.kind === 'stringed') return inst.default_string_count;
+        if (instrument === 'bass') return 4;
+        return 6;
     }
     function _keyOf(instrument, stringCount) {
         const inst = _normInstrument(instrument);
-        const sc = Number(stringCount) || (inst === 'bass' ? 4 : 6);
+        const sc = Number(stringCount) || _defaultStringCount(inst);
         return inst + '-' + sc;
     }
     // Like _keyOf, but when the caller omits a string count we resolve it against the
@@ -59,14 +80,14 @@
                 const cur = _splitKey(_currentKey);
                 if (cur.instrument === inst) sc = cur.stringCount;
             }
-            if (!sc) sc = (inst === 'bass' ? 4 : 6);
+            if (!sc) sc = _defaultStringCount(inst);
         }
         return inst + '-' + sc;
     }
     function _splitKey(key) {
         const parts = (typeof key === 'string' ? key : '').split('-');
-        const inst = parts[0] === 'bass' ? 'bass' : 'guitar';
-        return { instrument: inst, stringCount: Number(parts[1]) || (inst === 'bass' ? 4 : 6) };
+        const inst = _normInstrument(parts[0]);
+        return { instrument: inst, stringCount: Number(parts[1]) || _defaultStringCount(inst) };
     }
 
     // The shape every consumer reads. `offsets` are per-string semitone offsets from
@@ -273,7 +294,7 @@
             .then(function (s) {
                 if (!s || _touched) return;   // nothing to seed, or a consumer already wrote — don't clobber
                 const inst = _normInstrument(s.instrument);
-                const sc = Number(s.string_count) || (inst === 'bass' ? 4 : 6);
+                const sc = Number(s.string_count) || _defaultStringCount(inst);
                 const key = _keyOf(inst, sc);
 
                 function commit(offsets) {
diff --git a/static/v3/badges.js b/static/v3/badges.js
index f36cf849..8a2c9087 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -28,6 +28,50 @@
         { id: 'learn', label: 'Learn' },
         { id: 'studio', label: 'Studio' },
     ];
+    let _instruments = [];
+    let _instrumentsById = {};
+
+    async function loadInstruments() {
+        try {
+            const r = await fetch('/api/instruments');
+            if (r.ok) _instruments = await r.json();
+        } catch (_) {
+            _instruments = [];
+        }
+        _instrumentsById = {};
+        _instruments.forEach(function (inst) { _instrumentsById[inst.id] = inst; });
+        // Expose to other capabilities (working-tuning) that read from registry
+        if (window.feedBack) window.feedBack._instruments = _instruments;
+    }
+
+    function getInstruments() {
+        if (_instruments.length) return _instruments;
+        return [
+            { id: 'guitar', label: 'Guitar', kind: 'stringed', string_counts: [6, 7, 8], default_string_count: 6, roles: [{ id: 'lead', label: 'Lead', default: true }, { id: 'rhythm', label: 'Rhythm' }] },
+            { id: 'bass', label: 'Bass', kind: 'stringed', string_counts: [4, 5, 6], default_string_count: 4, roles: [{ id: 'bass', label: 'Bass', default: true }] },
+        ];
+    }
+
+    function getInstrument(id) {
+        if (_instrumentsById[id]) return _instrumentsById[id];
+        var insts = getInstruments();
+        for (var i = 0; i < insts.length; i++) {
+            if (insts[i].id === id) return insts[i];
+        }
+        return null;
+    }
+
+    function isStringedInstrument(instId) {
+        var inst = getInstrument(instId);
+        return inst ? inst.kind === 'stringed' : (instId === 'guitar' || instId === 'bass');
+    }
+
+    function stringCountsFor(instId) {
+        var inst = getInstrument(instId);
+        if (inst && inst.kind === 'stringed' && Array.isArray(inst.string_counts)) return inst.string_counts;
+        if (instId === 'bass') return STRING_COUNTS.bass;
+        return STRING_COUNTS.guitar;
+    }
     // Tuning names per instrument key (e.g. 'guitar-6', 'bass-4'), loaded from
     // GET /api/tunings. Falls back to empty arrays until the fetch resolves.
     let _tuningsByKey = {};
@@ -112,7 +156,7 @@
         }
     }
 
-    let settings = { instrument: 'guitar', string_count: 6, tuning: 'Standard', reference_pitch: 440, pathway: 'songs', instrument_profiles: {}, active_instrument_profile: 'guitar-lead' };
+    let settings = { instrument: 'guitar', string_count: 6, key_count: 88, tuning: 'Standard', reference_pitch: 440, pathway: 'songs', instrument_profiles: {}, active_instrument_profile: 'guitar-lead' };
 
     async function loadTunings() {
         try {
@@ -147,6 +191,15 @@
     }
 
     function profileIdForInstrument(inst) {
+        var instDef = getInstrument(inst);
+        if (instDef && instDef.roles && instDef.roles.length) {
+            var defaultRole = null;
+            for (var i = 0; i < instDef.roles.length; i++) {
+                if (instDef.roles[i].default) { defaultRole = instDef.roles[i]; break; }
+            }
+            if (!defaultRole) defaultRole = instDef.roles[0];
+            return inst + '-' + defaultRole.id;
+        }
         return inst === 'bass' ? 'bass' : 'guitar-lead';
     }
 
@@ -158,10 +211,10 @@
                 // Clamp persisted values to valid ranges — config.json could
                 // hold out-of-range data (hand-edited or from an import), and the
                 // badge/tuner must render consistent state, not a bad number.
-                const instrument = s.instrument === 'bass' ? 'bass' : 'guitar';
-                const counts = STRING_COUNTS[instrument];
+                const instrument = getInstrument(s.instrument) ? s.instrument : 'guitar';
+                const counts = stringCountsFor(instrument);
                 const sc = Number(s.string_count);
-                const scValid = counts.includes(sc) ? sc : counts[0];
+                const scValid = counts.length && counts.includes(sc) ? sc : (counts[0] || (instrument === 'bass' ? 4 : 6));
                 const tunings = _tuningsForInstrument(instrument, scValid);
                 let ref = Number(s.reference_pitch);
                 if (!Number.isFinite(ref)) ref = 440;
@@ -175,13 +228,14 @@
                 else if (Array.isArray(s.tuning)) tuning = s.tuning;
                 else tuning = tunings[0] || 'Standard';
                 const profiles = s.instrument_profiles && typeof s.instrument_profiles === 'object' ? s.instrument_profiles : {};
-                const pathway = PATHWAY_OPTIONS.some((o) => o.id === s.pathway) ? s.pathway : 'songs';
+                const keyCount = Number.isFinite(Number(s.key_count)) ? Number(s.key_count) : 88;
                 settings = {
                     instrument: instrument,
                     string_count: scValid,
+                    key_count: keyCount,
                     tuning: tuning,
                     reference_pitch: Math.min(450, Math.max(430, ref)),
-                    pathway: pathway,
+                    pathway: 'songs',
                     instrument_profiles: profiles,
                     active_instrument_profile: typeof s.active_instrument_profile === 'string' ? s.active_instrument_profile : profileIdForInstrument(instrument),
                 };
@@ -327,6 +381,16 @@
     function renderTuner() {
         const host = document.getElementById('v3-badge-tuner');
         if (!host) return;
+        const currentInst = getInstrument(settings.instrument);
+        const isPitched = currentInst && currentInst.detect_strategy === 'pitch';
+        if (!isPitched) {
+            host.innerHTML =
+                '<div id="v3-tuner-wrap" class="relative">' +
+                '<div class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-[96px] shrink-0 px-3 flex items-center justify-center opacity-30">' +
+                '<span class="text-[0.5625rem] text-fb-textDim">No tuner</span>' +
+                '</div></div>';
+            return;
+        }
         const hz = Math.round(settings.reference_pitch || 440);
         const initNote = typeof settings.tuning === 'string'
             ? (TUNING_NOTE[settings.tuning] || 'E') : lowStringNote(settings.tuning);
@@ -403,9 +467,19 @@
     }
 
     // ── Instrument selector card (Stitch RightInstrumentSelector) ──────────--
-    const guitarIcon =
-        '<svg class="w-6 h-6 text-white" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">' +
-        '<path d="M21.66 3.34a1.2 1.2 0 0 0-1.7 0l-2.1 2.1-.7-.7a1 1 0 0 0-1.42 1.42l.3.3-6.06 6.05a4.5 4.5 0 1 0 1.42 1.42l6.05-6.06.3.3a1 1 0 0 0 1.42-1.42l-.7-.7 2.1-2.1a1.2 1.2 0 0 0 0-1.7zM7 19a2 2 0 1 1 0-4 2 2 0 0 1 0 4z"/></svg>';
+    function iconUrl(instDef) {
+        if (!instDef) return '';
+        var pluginId = instDef._plugin_id;
+        var iconPath = instDef.icon || 'assets/icon.svg';
+        if (pluginId && iconPath) return '/api/plugins/' + pluginId + '/' + iconPath;
+        return '';
+    }
+    function iconForInstrument(instDef) {
+        var url = iconUrl(instDef);
+        if (url) return '<img src="' + esc(url) + '" class="w-6 h-6" style="filter:brightness(0) invert(1)" alt="" onerror="this.style.display=\'none\'">';
+        // Fallback inline guitar SVG
+        return '<svg class="w-6 h-6 text-white" fill="currentColor" viewBox="0 0 24 24"><path d="M21.66 3.34a1.2 1.2 0 0 0-1.7 0l-2.1 2.1-.7-.7a1 1 0 0 0-1.42 1.42l.3.3-6.06 6.05a4.5 4.5 0 1 0 1.42 1.42l6.05-6.06.3.3a1 1 0 0 0 1.42-1.42l-.7-.7 2.1-2.1a1.2 1.2 0 0 0 0-1.7zM7 19a2 2 0 1 1 0-4 2 2 0 0 1 0 4z"/></svg>';
+    }
 
     // Instrument-menu open/close helpers keyed by id (NOT a captured element),
     // so they survive renderInstrument() replacing the menu node. closeInstMenu
@@ -434,21 +508,38 @@
         const host = document.getElementById('v3-badge-instrument');
         if (!host) return;
         const wt = workingTuningInfo();
+        const instrumentList = getInstruments();
+        const currentInst = getInstrument(settings.instrument);
+        const isStringed = currentInst && currentInst.kind === 'stringed';
+
+        const isKeyboard = currentInst && currentInst.kind === 'keyboard';
+
+        var instPills = '';
+        if (instrumentList.length) {
+            instPills = instrumentList.map(function (inst) {
+                return pill('inst', inst.id, inst.label, settings.instrument === inst.id);
+            }).join('');
+        } else {
+            instPills = '<span class="text-fb-textDim text-xs">No instruments installed. <a href="/plugins" class="text-fb-primary underline">Install one</a>.</span>';
+        }
+        var toggleTitle;
+        if (isStringed) {
+            toggleTitle = 'Instrument: ' + settings.string_count + '-str ' + (wt ? wt.label : tuningLabel());
+        } else if (isKeyboard) {
+            toggleTitle = 'Instrument: ' + (settings.key_count || 88) + '-key ' + currentInst.label;
+        } else {
+            toggleTitle = 'Instrument: ' + currentInst.label;
+        }
         host.innerHTML =
             '<div id="v3-instrument-wrap" class="relative">' +
-            '<button type="button" data-inst-toggle title="Instrument: ' + esc(settings.string_count + '-str ' + (wt ? wt.label : tuningLabel())) + '" ' +
+            '<button type="button" data-inst-toggle title="' + esc(toggleTitle) + '" ' +
             'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-1.5 hover:ring-1 hover:ring-fb-primary/40 transition">' +
-            guitarIcon +
-            // Live working-tuning label: dim while you're still in your home tuning,
-            // amber once you've retuned. Omitted if the host doesn't expose
-            // workingTuning (feature-detect → the card looks exactly as before).
+            iconForInstrument(currentInst) +
             (wt ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 ' +
                 (wt.isHome ? 'text-fb-textDim' : 'text-amber-400') + '">' + esc(wt.short) + '</span>' : '') +
             '<svg class="w-4 h-4 text-white" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/></svg>' +
             '</button>' +
             '<div data-inst-menu class="hidden absolute right-0 mt-2 w-60 bg-fb-card border border-fb-border/50 rounded-xl shadow-xl p-3 z-50 space-y-3">' +
-            // "Now in" banner + one-tap back-to-default — shown only once you've
-            // retuned off your home tuning (workingTuning present and not home).
             ((wt && !wt.isHome)
                 ? '<div class="flex items-center justify-between gap-2 pb-1 border-b border-fb-border/40">' +
                   '<div class="min-w-0"><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim">Now in</div>' +
@@ -456,28 +547,20 @@
                   '<button type="button" data-inst-reset title="Reset this instrument to its home tuning" class="shrink-0 text-[0.6875rem] text-fb-textDim hover:text-fb-text border border-fb-border/40 hover:border-fb-border/70 rounded-md px-2 py-1 transition-colors">Back to default</button>' +
                   '</div>'
                 : '') +
-            instRow('Instrument', ['guitar', 'bass'].map((v) =>
-                pill('inst', v, v[0].toUpperCase() + v.slice(1), settings.instrument === v)).join('')) +
-            instRow('Strings', STRING_COUNTS[settings.instrument].map((v) =>
-                pill('strings', v, v + '', settings.string_count === v)).join('')) +
-            // Handedness — a left-hander flips the whole highway (frets mirror).
-            // Lives with the other player-orientation choices so it's part of the
-            // same "Choose your instrument" step the onboarding tour spotlights —
-            // i.e. set before you ever tune up or calibrate.
-            instRow('Handedness', pill('hand', 'right', 'Right', !_leftyPref()) +
-                pill('hand', 'left', 'Left', _leftyPref())) +
-            '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1">Tuning</div>' +
+            instRow('Instrument', instPills) +
+            (isStringed ? instRow('Strings', stringCountsFor(settings.instrument).map((v) =>
+                pill('strings', v, v + '', settings.string_count === v)).join('')) : '') +
+            (isKeyboard ? instRow('Keys', (currentInst.key_counts || [25, 49, 61, 88]).map((v) =>
+                pill('key_count', v, v + '', (settings.key_count || currentInst.default_key_count || 88) === v)).join('')) : '') +
+            // Handedness only for stringed instruments where frets get mirrored.
+            (isStringed ? instRow('Handedness', pill('hand', 'right', 'Right', !_leftyPref()) +
+                pill('hand', 'left', 'Left', _leftyPref())) : '') +
+            (isStringed ? '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1">Tuning</div>' +
             '<select data-inst-tuning class="w-full bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1.5 text-xs text-fb-text outline-none focus:border-fb-primary">' +
-            // An offset-array tuning has no named option — surface it as a
-            // disabled, selected 'Custom' entry so the dropdown reflects reality
-            // (picking a named tuning still works and replaces the custom one).
             (typeof settings.tuning === 'string' ? '' : '<option selected disabled>Custom</option>') +
-            _tuningsForInstrument(settings.instrument, settings.string_count).map((t) => '<option' + (t === settings.tuning ? ' selected' : '') + '>' + esc(t) + '</option>').join('') + '</select></div>' +
-            '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1">Pathway</div>' +
-            '<select data-inst-pathway class="w-full bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1.5 text-xs text-fb-text outline-none focus:border-fb-primary">' +
-            PATHWAY_OPTIONS.map((p) => '<option value="' + esc(p.id) + '"' + (p.id === settings.pathway ? ' selected' : '') + '>' + esc(p.label) + '</option>').join('') + '</select></div>' +
-            '<div><div class="flex justify-between text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1"><span>Reference pitch</span><span data-ref-val>' + settings.reference_pitch + ' Hz</span></div>' +
-            '<input data-inst-ref type="range" min="430" max="450" step="1" value="' + settings.reference_pitch + '" class="w-full slider-input"></div>' +
+            _tuningsForInstrument(settings.instrument, settings.string_count).map((t) => '<option' + (t === settings.tuning ? ' selected' : '') + '>' + esc(t) + '</option>').join('') + '</select></div>' : '') +
+            (isStringed ? '<div><div class="flex justify-between text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1"><span>Reference pitch</span><span data-ref-val>' + settings.reference_pitch + ' Hz</span></div>' +
+            '<input data-inst-ref type="range" min="430" max="450" step="1" value="' + settings.reference_pitch + '" class="w-full slider-input"></div>' : '') +
             '</div></div>';
 
         const toggle = host.querySelector('[data-inst-toggle]');
@@ -496,22 +579,25 @@
         const keepOpen = openInstMenu;
         menu.querySelectorAll('[data-pill="inst"]').forEach((b) => b.addEventListener('click', async () => {
             const v = b.getAttribute('data-val');
-            const counts = STRING_COUNTS[v];
-            // Clamp string_count AND tuning to ones valid for the new
-            // instrument, so switching can't persist (and push to the tuner) an
-            // unsupported instrument+tuning combo.
-            const newSc = counts.includes(settings.string_count) ? settings.string_count : counts[0];
-            const tunings = _tuningsForInstrument(v, newSc);
-            const ok = await saveSettings({
-                instrument: v,
-                string_count: newSc,
-                tuning: tunings.includes(settings.tuning) ? settings.tuning : (tunings[0] || settings.tuning),
-                pathway: pathwayForProfile(settings.instrument_profiles, profileIdForInstrument(v), settings.pathway),
-            });
-            // Only move the working-tuning context once the switch was actually persisted —
-            // otherwise the selector stays on the old instrument while the card shows the
-            // new one's tuning (settings and workingTuning desync on a rejected save).
-            if (ok) setWorkingInstrument(v, newSc);   // surface THIS instrument's own working tuning
+            const instDef = getInstrument(v);
+            const isStr = instDef && instDef.kind === 'stringed';
+            const isKeys = instDef && instDef.kind === 'keyboard';
+            const counts = stringCountsFor(v);
+            // Use the instrument's DEFAULT count on switch — always.
+            const newSc = isStr ? (instDef && instDef.default_string_count ? instDef.default_string_count : (counts[0] || 0)) : 0;
+            const newKc = isKeys ? (instDef && instDef.default_key_count ? instDef.default_key_count : 88) : 0;
+            const tunings = isStr ? _tuningsForInstrument(v, newSc) : [];
+            var patch = { instrument: v };
+            if (isStr) {
+                patch.string_count = newSc;
+                patch.tuning = tunings.includes(settings.tuning) ? settings.tuning : (tunings[0] || settings.tuning);
+            }
+            if (isKeys) {
+                patch.key_count = newKc;
+            }
+            const ok = await saveSettings(patch);
+            // Only move the working-tuning context once the switch was actually persisted.
+            if (ok && isStr) setWorkingInstrument(v, newSc);
             renderInstrument(); keepOpen();
         }));
         menu.querySelectorAll('[data-pill="strings"]').forEach((b) => b.addEventListener('click', async () => {
@@ -528,15 +614,22 @@
             setWorkingInstrument(settings.instrument, newSc);
             renderInstrument(); keepOpen();
         }));
+        menu.querySelectorAll('[data-pill="key_count"]').forEach((b) => b.addEventListener('click', async () => {
+            const newKc = Number(b.getAttribute('data-val'));
+            await saveSettings({ key_count: newKc });
+            renderInstrument(); keepOpen();
+        }));
         menu.querySelectorAll('[data-pill="hand"]').forEach((b) => b.addEventListener('click', () => {
             _setLeftyPref(b.getAttribute('data-val') === 'left');
             renderInstrument(); keepOpen();   // reflect the active pill; keep the menu open
         }));
-        menu.querySelector('[data-inst-tuning]').addEventListener('change', (e) => saveSettings({ tuning: e.target.value }));
-        menu.querySelector('[data-inst-pathway]').addEventListener('change', (e) => saveSettings({ pathway: e.target.value }));
-        const ref = menu.querySelector('[data-inst-ref]');
-        ref.addEventListener('input', (e) => { menu.querySelector('[data-ref-val]').textContent = e.target.value + ' Hz'; });
-        ref.addEventListener('change', (e) => saveSettings({ reference_pitch: Number(e.target.value) }));
+        var tuningSelect = menu.querySelector('[data-inst-tuning]');
+        if (tuningSelect) tuningSelect.addEventListener('change', (e) => saveSettings({ tuning: e.target.value }));
+        var refSlider = menu.querySelector('[data-inst-ref]');
+        if (refSlider) {
+            refSlider.addEventListener('input', (e) => { var label = menu.querySelector('[data-ref-val]'); if (label) label.textContent = e.target.value + ' Hz'; });
+            refSlider.addEventListener('change', (e) => saveSettings({ reference_pitch: Number(e.target.value) }));
+        }
         const resetBtn = menu.querySelector('[data-inst-reset]');
         if (resetBtn) resetBtn.addEventListener('click', () => {
             const wtCap = window.feedBack && window.feedBack.workingTuning;
@@ -568,9 +661,10 @@
             (active ? 'bg-fb-primary text-white' : 'bg-gray-800/50 text-fb-textDim hover:text-fb-text') + '">' + esc(label) + '</button>';
     }
 
-    window.v3Badges = { reload: async () => { await Promise.all([loadTunings(), loadSettings()]); renderInstrument(); renderTuner(); } };
+    window.v3Badges = { reload: async () => { await loadInstruments(); await Promise.all([loadTunings(), loadSettings()]); renderInstrument(); renderTuner(); } };
 
     async function boot() {
+        await loadInstruments();
         await Promise.all([loadTunings(), loadSettings()]);
         // NB: we deliberately do NOT call setWorkingInstrument() here. The host seeds its
         // current instrument from the same /api/settings on boot and emits
diff --git a/static/v3/index.html b/static/v3/index.html
index 3dafcb17..3e849937 100644
--- a/static/v3/index.html
+++ b/static/v3/index.html
@@ -407,6 +407,7 @@ <h2 class="fb-settings-title">Settings</h2>
                 <button type="button" class="fb-tab" data-tab="mic">Mic</button>
                 <button type="button" class="fb-tab" data-tab="plugins">Plugins</button>
                 <button type="button" class="fb-tab" data-tab="system">System</button>
+                <button type="button" class="fb-tab" data-tab="instruments">Instruments</button>
             </div>
 
             <!-- ══ GAMEPLAY ════════════════════════════════════════════════ -->
@@ -435,21 +436,17 @@ <h3>Gameplay Settings</h3>
                     </div>
                     <!-- Default arrangement -->
                     <div class="fb-srow">
+                    <!-- Default arrangement moved to instrument selector (instruments-as-plugins).
+                         Each instrument's roles define available arrangements; the preference is
+                         stored per profile as "default_role" instead of the legacy "default_arrangement". -->
+                    <div class="fb-srow muted">
                         <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"/></svg></span>
                         <div class="fb-srow-main">
                             <div class="fb-srow-title">Default arrangement</div>
-                            <div class="fb-srow-desc">Which arrangement loads first when you open a song.</div>
-                        </div>
-                        <div class="fb-srow-control">
-                            <select id="default-arrangement" onchange="persistSetting('default_arrangement', this.value)"
-                                class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                                <option value="">Most notes (auto)</option>
-                                <option value="Lead">Lead</option>
-                                <option value="Rhythm">Rhythm</option>
-                                <option value="Bass">Bass</option>
-                            </select>
+                            <div class="fb-srow-desc">Set per instrument in the topbar instrument selector.</div>
                         </div>
                     </div>
+                    </div>
                     <!-- Instrument pathway -->
                     <div class="fb-srow">
                         <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 20l-5.447-2.724A1 1 0 013 16.382V5.618a1 1 0 011.447-.894L9 7m0 13l6-3m-6 3V7m6 10l4.553 2.276A1 1 0 0021 18.382V7.618a1 1 0 00-1.447-.894L15 4m0 13V4m0 0L9 7"/></svg></span>
@@ -912,6 +909,14 @@ <h3>Gameplay Settings</h3>
                     <div id="settings-status" class="text-sm text-gray-500"></div>
                 </div>
             </div>
+
+            <!-- ══ INSTRUMENTS ══════════════════════════════════════════════ -->
+            <div class="fb-tabpanel" data-tab="instruments">
+                <div class="fb-tabpanel-head"><h3>Instruments</h3></div>
+                <div class="fb-srows" id="instruments-settings-panel">
+                    <div class="text-fb-textDim text-sm px-1">Loading instruments…</div>
+                </div>
+            </div>
         </div>
     </div>
 
@@ -1324,6 +1329,7 @@ <h3>Gameplay Settings</h3>
     <script defer src="/static/v3/lessons.js"></script>
     <script defer src="/static/v3/dashboard.js"></script>
     <script defer src="/static/v3/settings.js"></script>
+    <script defer src="/static/v3/instruments-settings.js"></script>
     <script defer src="/static/v3/interface-size-ui.js"></script>
     <!-- First-run home tour: spotlights the home cards via the shared tour
          engine (tour-engine.js, loaded above). Auto-runs once after onboarding
diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
new file mode 100644
index 00000000..ac2e25c3
--- /dev/null
+++ b/static/v3/instruments-settings.js
@@ -0,0 +1,396 @@
+// Instruments settings tab — renders collapsible instrument cards from
+// GET /api/instruments, with editable custom tunings and arrangement patterns.
+// User overrides are persisted to config.json via POST /api/settings under
+// the "instrument_overrides" key so they survive restarts.
+(function () {
+    'use strict';
+
+    var PANEL_ID = 'instruments-settings-panel';
+    var OVERRIDES_KEY = 'instrument_overrides';
+    var _overrides = {};
+    var _instruments = [];
+    var _saveTimer = 0;
+    var _openCards = {};  // instId -> bool, survives re-renders
+
+    function esc(s) {
+        return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
+            return ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c];
+        });
+    }
+
+    function midiToNote(midi) {
+        var notes = ['C', 'C#', 'D', 'Eb', 'E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B'];
+        return notes[((midi % 12) + 12) % 12] + Math.floor(midi / 12 - 1);
+    }
+
+    function getOverrides(instId) {
+        if (!_overrides[instId]) _overrides[instId] = {};
+        return _overrides[instId];
+    }
+
+    function saveOverridesDebounced() {
+        clearTimeout(_saveTimer);
+        _saveTimer = setTimeout(function () {
+            var patch = {};
+            patch[OVERRIDES_KEY] = _overrides;
+            fetch('/api/settings', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(patch),
+            }).catch(function () {});
+        }, 300);
+    }
+
+    function renderInstruments() {
+        var panel = document.getElementById(PANEL_ID);
+        if (!panel) return;
+
+        if (!_instruments.length) {
+            panel.innerHTML = '<div class="fb-srow"><span class="fb-srow-icon">' +
+                '<svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5.882V19.24a1.76 1.76 0 01-3.417.592l-2.147-6.15M18 13a3 3 0 100-6M5.436 13.683A4.001 4.001 0 017 6h1.832c4.1 0 7.625-1.234 9.168-3v14c-1.543-1.766-5.067-3-9.168-3H7a3.988 3.988 0 01-1.564-.317z"></path></svg></span>' +
+                '<div class="fb-srow-main"><div class="fb-srow-title">No instruments installed</div>' +
+                '<div class="fb-srow-desc">Visit the <a href="/plugins" class="text-fb-primary underline">Plugins page</a> to install instrument plugins.</div></div></div>';
+            return;
+        }
+
+        var html = '';
+        for (var i = 0; i < _instruments.length; i++) {
+            var inst = _instruments[i];
+            var over = getOverrides(inst.id);
+            var id = 'inst-card-' + inst.id;
+            var isStringed = inst.kind === 'stringed';
+            var isOpen = !!_openCards[inst.id];
+
+            html += '<div class="fb-srow fb-srow-stack">' +
+                '<div class="flex items-center justify-between cursor-pointer select-none' + (isOpen ? ' mb-3' : '') + '" data-inst-toggle="' + esc(inst.id) + '">' +
+                '<div class="flex items-center gap-3">' +
+                '<span class="text-lg font-semibold text-fb-text">' + esc(inst.label) + '</span>' +
+                '<span class="bg-gray-700/50 text-[0.625rem] uppercase tracking-wider text-fb-textDim px-2 py-0.5 rounded-full">' + esc(inst.kind) + '</span>' +
+                (inst.detect_strategy !== 'none' ? '<span class="bg-gray-700/50 text-[0.625rem] uppercase tracking-wider text-fb-textDim px-2 py-0.5 rounded-full">' + esc(inst.detect_strategy) + '</span>' : '') +
+                '</div>' +
+                '<svg class="w-4 h-4 text-fb-textDim transition-transform' + (isOpen ? ' rotate-180' : '') + '" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/></svg>' +
+                '</div>';
+
+            html += '<div id="' + id + '" class="' + (isOpen ? '' : 'hidden') + ' space-y-4 pl-4 border-l-2 border-fb-border/30">';
+
+            // ── Roles ──────────────────────────────────
+            if (inst.roles && inst.roles.length) {
+                html += '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Roles</div>' +
+                    '<div class="flex flex-wrap gap-1">';
+                for (var j = 0; j < inst.roles.length; j++) {
+                    var role = inst.roles[j];
+                    html += '<span class="text-xs bg-gray-800/50 border border-gray-700 rounded-md px-2 py-0.5 text-fb-text">' +
+                        esc(role.label) + (role.default ? ' <span class="text-fb-primary text-[0.625rem]">(default)</span>' : '') +
+                        '</span>';
+                }
+                html += '</div></div>';
+            }
+
+            // ── Arrangement name patterns (editable) ────
+            html += _renderEditableNames(inst, over);
+
+            // ── String counts (stringed, editable) ─────
+            if (isStringed) {
+                html += _renderEditableStringCounts(inst, over);
+            }
+
+            // ── Custom tunings (stringed, editable) ────
+            if (isStringed) {
+                html += _renderTunings(inst, over);
+            }
+
+            // ── Info row ───────────────────────────────
+            html += '<div class="text-[0.625rem] text-fb-textDim flex flex-wrap gap-3 pb-2">' +
+                '<span>Ref: ' + esc(String(inst.reference_pitch)) + ' Hz</span>' +
+                '<span>Detect: ' + esc(inst.detect_strategy) + '</span>' +
+                '</div>';
+
+            html += '</div></div>';
+        }
+
+        panel.innerHTML = html;
+        _wireEvents();
+    }
+
+    function _renderEditableNames(inst, over) {
+        var allNames = [];
+        if (inst.roles) {
+            for (var i = 0; i < inst.roles.length; i++) {
+                var names = inst.roles[i].arrangement_names || [];
+                for (var j = 0; j < names.length; j++) {
+                    allNames.push({ name: names[j], role: inst.roles[i].label, source: 'plugin' });
+                }
+            }
+        }
+        var customNames = over.custom_arrangement_names || [];
+        for (var k = 0; k < customNames.length; k++) {
+            allNames.push({ name: customNames[k], role: 'custom', source: 'user' });
+        }
+
+        var html = '<div data-section="names" data-inst="' + esc(inst.id) + '">' +
+            '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Arrangement name patterns</div>';
+
+        if (allNames.length) {
+            html += '<div class="flex flex-wrap gap-1 mb-2">';
+            for (var n = 0; n < allNames.length; n++) {
+                var item = allNames[n];
+                var removeBtn = item.source === 'user'
+                    ? '<button type="button" data-remove-name="' + esc(item.name) + '" data-inst="' + esc(inst.id) + '" class="ml-1 text-red-400 hover:text-red-300 text-[0.625rem]" title="Remove">&times;</button>'
+                    : '';
+                html += '<span class="text-xs bg-gray-800/50 border ' + (item.source === 'user' ? 'border-green-700/50' : 'border-gray-700') + ' rounded-md px-2 py-0.5">' +
+                    esc(item.name) + ' <span class="text-fb-textDim text-[0.625rem]">→ ' + esc(item.role) + '</span>' + removeBtn +
+                    '</span>';
+            }
+            html += '</div>';
+        }
+
+        html += '<div class="flex gap-1 items-center">' +
+            '<input type="text" data-add-name="' + esc(inst.id) + '" placeholder="Arrangement name (e.g. Solo Guitar)" class="bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-xs text-fb-text outline-none w-48 focus:border-fb-primary">' +
+            '<button type="button" data-add-name-btn="' + esc(inst.id) + '" class="bg-fb-primary/20 hover:bg-fb-primary/30 text-fb-primary text-xs px-2 py-1 rounded-md transition">Add</button>' +
+            '</div></div>';
+        return html;
+    }
+
+    function _renderEditableStringCounts(inst, over) {
+        var pluginCounts = inst.string_counts || [];
+        var customCounts = over.custom_string_counts || [];
+        var allCounts = pluginCounts.concat(customCounts.filter(function (c) { return pluginCounts.indexOf(c) < 0; }));
+
+        var html = '<div data-section="string-counts" data-inst="' + esc(inst.id) + '">' +
+            '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">String counts</div>' +
+            '<div class="flex flex-wrap gap-1 mb-2">';
+        for (var i = 0; i < allCounts.length; i++) {
+            var isPlugin = pluginCounts.indexOf(allCounts[i]) >= 0;
+            var removeBtn = !isPlugin
+                ? '<button type="button" data-remove-sc="' + allCounts[i] + '" data-inst="' + esc(inst.id) + '" class="ml-1 text-red-400 hover:text-red-300 text-[0.625rem]" title="Remove">&times;</button>'
+                : '';
+            html += '<span class="text-xs bg-gray-800/50 border ' + (isPlugin ? 'border-gray-700' : 'border-green-700/50') + ' rounded-md px-2 py-0.5">' +
+                allCounts[i] + (allCounts[i] === inst.default_string_count ? ' <span class="text-fb-primary text-[0.625rem]">(default)</span>' : '') + removeBtn +
+                '</span>';
+        }
+        html += '</div>' +
+            '<div class="flex gap-1 items-center">' +
+            '<input type="number" data-add-sc="' + esc(inst.id) + '" min="1" max="18" placeholder="String count (e.g. 12)" class="bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-xs text-fb-text outline-none w-40 focus:border-fb-primary">' +
+            '<button type="button" data-add-sc-btn="' + esc(inst.id) + '" class="bg-fb-primary/20 hover:bg-fb-primary/30 text-fb-primary text-xs px-2 py-1 rounded-md transition">Add</button>' +
+            '</div></div>';
+        return html;
+    }
+
+    function _renderTunings(inst, over) {
+        var html = '<div data-section="tunings" data-inst="' + esc(inst.id) + '">' +
+            '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Tuning presets</div>';
+
+        var scKeys = Object.keys(inst.tunings || {}).sort(function (a, b) { return Number(a) - Number(b); });
+        var customTunings = over.custom_tunings || {};
+
+        for (var ti = 0; ti < scKeys.length; ti++) {
+            var scKey = scKeys[ti];
+            var scNum = Number(scKey);
+            var presetNames = Object.keys(inst.tunings[scKey] || {}).sort();
+            var customNames = Object.keys(customTunings[scKey] || {});
+
+            html += '<div class="mb-2">' +
+                '<span class="text-xs font-semibold text-fb-text">' + esc(scKey) + '-string</span>';
+
+            // Show standard tuning notes
+            var stdMidis = inst.standard_tunings && inst.standard_tunings[scKey];
+            if (stdMidis && stdMidis.length) {
+                var stdNotes = stdMidis.map(function (m) { return midiToNote(m); }).join(' ');
+                html += '<div class="text-[0.625rem] text-fb-textDim mt-0.5 ml-1">Standard: ' + esc(stdNotes) + '</div>';
+            }
+
+            var allEntries = [];
+            for (var n = 0; n < presetNames.length; n++) {
+                var offs = inst.tunings[scKey][presetNames[n]];
+                allEntries.push({ name: presetNames[n], offsets: offs, source: 'plugin' });
+            }
+            for (var cn = 0; cn < customNames.length; cn++) {
+                allEntries.push({ name: customNames[cn], offsets: customTunings[scKey][customNames[cn]], source: 'user' });
+            }
+
+            if (allEntries.length) {
+                html += '<div class="flex flex-wrap gap-1 mt-1.5 mb-1 ml-1">';
+                for (var a = 0; a < allEntries.length; a++) {
+                    var entry = allEntries[a];
+                    var std = inst.standard_tunings && inst.standard_tunings[scKey];
+                    var midis = [];
+                    if (std && entry.offsets && std.length === entry.offsets.length) {
+                        for (var oi = 0; oi < entry.offsets.length; oi++) {
+                            midis.push(std[oi] + entry.offsets[oi]);
+                        }
+                    }
+                    var noteLabel = midis.length ? midis.map(function (m) { return midiToNote(m); }).join(' ') : '';
+                    var offStr = entry.offsets ? entry.offsets.map(function (o) { return (o >= 0 ? '+' : '') + o; }).join(',') : '';
+                    var removeBtn = entry.source === 'user'
+                        ? '<button type="button" data-remove-tuning="' + esc(entry.name) + '" data-sc="' + esc(scKey) + '" data-inst="' + esc(inst.id) + '" class="ml-1 text-red-400 hover:text-red-300 text-[0.625rem]" title="Remove">&times;</button>'
+                        : '';
+                    html += '<span class="text-[0.625rem] bg-gray-800/50 border ' + (entry.source === 'user' ? 'border-green-700/50' : 'border-gray-700') +
+                        ' rounded-md px-1.5 py-0.5 text-fb-textDim font-mono" title="' + esc(noteLabel) + '">' +
+                        esc(entry.name) + ': [' + esc(offStr) + ']' + removeBtn +
+                        '</span>';
+                }
+                html += '</div>';
+            }
+
+            // Add custom tuning form
+            html += '<div class="flex flex-wrap gap-1 items-center mt-0.5">' +
+                '<input type="text" data-add-tuning-name="' + esc(inst.id) + '" data-sc="' + esc(scKey) + '" placeholder="Tuning name" class="bg-gray-800/50 border border-gray-700 rounded-md px-1.5 py-0.5 text-[0.625rem] text-fb-text outline-none w-28 focus:border-fb-primary">' +
+                '<input type="text" data-add-tuning-offsets="' + esc(inst.id) + '" data-sc="' + esc(scKey) + '" placeholder="Offsets e.g. 0,0,0,0,0,0" class="bg-gray-800/50 border border-gray-700 rounded-md px-1.5 py-0.5 text-[0.625rem] text-fb-text outline-none w-44 focus:border-fb-primary font-mono">' +
+                '<button type="button" data-add-tuning-btn="' + esc(inst.id) + '" data-sc="' + esc(scKey) + '" class="bg-fb-primary/20 hover:bg-fb-primary/30 text-fb-primary text-[0.625rem] px-1.5 py-0.5 rounded-md transition">Add</button>' +
+                '</div></div>';
+        }
+
+        html += '</div>';
+        return html;
+    }
+
+    function _wireEvents() {
+        var panel = document.getElementById(PANEL_ID);
+        if (!panel) return;
+
+        // Toggle card open/close
+        panel.querySelectorAll('[data-inst-toggle]').forEach(function (btn) {
+            btn.addEventListener('click', function () {
+                var instId = btn.getAttribute('data-inst-toggle');
+                _openCards[instId] = !_openCards[instId];
+                renderInstruments();
+            });
+        });
+
+        // Add arrangement name
+        panel.querySelectorAll('[data-add-name-btn]').forEach(function (btn) {
+            btn.addEventListener('click', function () {
+                var instId = btn.getAttribute('data-add-name-btn');
+                var input = panel.querySelector('[data-add-name="' + instId + '"]');
+                if (!input) return;
+                var name = input.value.trim();
+                if (!name) return;
+                var over = getOverrides(instId);
+                if (!over.custom_arrangement_names) over.custom_arrangement_names = [];
+                if (over.custom_arrangement_names.indexOf(name) < 0) {
+                    over.custom_arrangement_names.push(name);
+                    saveOverridesDebounced();
+                }
+                input.value = '';
+                renderInstruments();
+            });
+        });
+
+        // Remove arrangement name
+        panel.querySelectorAll('[data-remove-name]').forEach(function (btn) {
+            btn.addEventListener('click', function (e) {
+                e.stopPropagation();
+                var instId = btn.getAttribute('data-inst');
+                var name = btn.getAttribute('data-remove-name');
+                var over = getOverrides(instId);
+                if (over.custom_arrangement_names) {
+                    over.custom_arrangement_names = over.custom_arrangement_names.filter(function (n) { return n !== name; });
+                    saveOverridesDebounced();
+                }
+                renderInstruments();
+            });
+        });
+
+        // Add string count
+        panel.querySelectorAll('[data-add-sc-btn]').forEach(function (btn) {
+            btn.addEventListener('click', function () {
+                var instId = btn.getAttribute('data-add-sc-btn');
+                var input = panel.querySelector('[data-add-sc="' + instId + '"]');
+                if (!input) return;
+                var sc = parseInt(input.value, 10);
+                if (!sc || sc < 1 || sc > 18) return;
+                var over = getOverrides(instId);
+                if (!over.custom_string_counts) over.custom_string_counts = [];
+                if (over.custom_string_counts.indexOf(sc) < 0) {
+                    over.custom_string_counts.push(sc);
+                    saveOverridesDebounced();
+                }
+                input.value = '';
+                renderInstruments();
+            });
+        });
+
+        // Remove string count
+        panel.querySelectorAll('[data-remove-sc]').forEach(function (btn) {
+            btn.addEventListener('click', function (e) {
+                e.stopPropagation();
+                var instId = btn.getAttribute('data-inst');
+                var sc = parseInt(btn.getAttribute('data-remove-sc'), 10);
+                var over = getOverrides(instId);
+                if (over.custom_string_counts) {
+                    over.custom_string_counts = over.custom_string_counts.filter(function (c) { return c !== sc; });
+                    saveOverridesDebounced();
+                }
+                renderInstruments();
+            });
+        });
+
+        // Add tuning
+        panel.querySelectorAll('[data-add-tuning-btn]').forEach(function (btn) {
+            btn.addEventListener('click', function () {
+                var instId = btn.getAttribute('data-add-tuning-btn');
+                var scKey = btn.getAttribute('data-sc');
+                var nameInput = panel.querySelector('[data-add-tuning-name="' + instId + '"][data-sc="' + scKey + '"]');
+                var offInput = panel.querySelector('[data-add-tuning-offsets="' + instId + '"][data-sc="' + scKey + '"]');
+                if (!nameInput || !offInput) return;
+                var name = nameInput.value.trim();
+                var offStr = offInput.value.trim();
+                if (!name || !offStr) return;
+
+                var parts = offStr.split(/[,\s]+/).map(Number);
+                if (parts.some(function (p) { return !Number.isFinite(p) || p < -12 || p > 12; })) return;
+
+                var over = getOverrides(instId);
+                if (!over.custom_tunings) over.custom_tunings = {};
+                if (!over.custom_tunings[scKey]) over.custom_tunings[scKey] = {};
+                over.custom_tunings[scKey][name] = parts;
+                saveOverridesDebounced();
+
+                nameInput.value = '';
+                offInput.value = '';
+                renderInstruments();
+            });
+        });
+
+        // Remove tuning
+        panel.querySelectorAll('[data-remove-tuning]').forEach(function (btn) {
+            btn.addEventListener('click', function (e) {
+                e.stopPropagation();
+                var instId = btn.getAttribute('data-inst');
+                var scKey = btn.getAttribute('data-sc');
+                var name = btn.getAttribute('data-remove-tuning');
+                var over = getOverrides(instId);
+                if (over.custom_tunings && over.custom_tunings[scKey]) {
+                    delete over.custom_tunings[scKey][name];
+                    saveOverridesDebounced();
+                }
+                renderInstruments();
+            });
+        });
+    }
+
+    async function load() {
+        try {
+            var r = await fetch('/api/instruments');
+            if (r.ok) _instruments = await r.json();
+        } catch (_) {}
+
+        try {
+            var sr = await fetch('/api/settings');
+            if (sr.ok) {
+                var s = await sr.json();
+                if (s[OVERRIDES_KEY] && typeof s[OVERRIDES_KEY] === 'object') {
+                    _overrides = s[OVERRIDES_KEY];
+                }
+            }
+        } catch (_) {}
+
+        renderInstruments();
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', load);
+    } else {
+        load();
+    }
+})();
diff --git a/static/v3/songs.js b/static/v3/songs.js
index 255e8145..99d33baf 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -43,7 +43,21 @@
         ['difficulty', 'Difficulty (easiest first)'], ['difficulty-desc', 'Difficulty (hardest first)'],
     ];
     const FORMATS = [['', 'All formats'], ['sloppak', 'Feedpak'], ['loose', 'Folder']];
-    const ARRANGEMENTS = ['Lead', 'Rhythm', 'Bass', 'Combo', 'Vocals'];
+    function _arrangementOptions() {
+        var insts = sm && sm._instruments;
+        if (Array.isArray(insts) && insts.length) {
+            var names = [];
+            for (var i = 0; i < insts.length; i++) {
+                var roles = insts[i].roles || [];
+                for (var j = 0; j < roles.length; j++) {
+                    var label = roles[j].label;
+                    if (label && names.indexOf(label) < 0) names.push(label);
+                }
+            }
+            if (names.length) return names;
+        }
+        return ['Lead', 'Rhythm', 'Bass', 'Combo', 'Vocals'];
+    }
     const STEMS = ['guitar', 'bass', 'drums', 'vocals', 'other'];
     const PAGE_SIZE = 24;
     // Extra rows rendered above/below the viewport so a fast scroll doesn't flash
@@ -2816,6 +2830,10 @@
         const mark = st === 'has' ? '✓ ' : st === 'lacks' ? '✕ ' : '';
         return '<button data-tri="' + group + '" data-val="' + esc(value) + '" class="px-2 py-1 rounded-md text-xs border ' + cls + '">' + mark + esc(label) + '</button>';
     }
+    function renderDrawerIfOpen() {
+        const d = document.getElementById('v3-songs-drawer');
+        if (d && !d.classList.contains('hidden') && d.innerHTML.trim()) renderDrawer();
+    }
     function renderDrawer() {
         const d = document.getElementById('v3-songs-drawer');
         if (!d) return;
@@ -2824,7 +2842,7 @@
             '<div class="p-5 space-y-5">' +
             '<div class="flex items-center justify-between"><h3 class="text-lg font-semibold text-fb-text">Filters</h3>' +
             '<button data-drawer-close class="text-fb-textDim hover:text-fb-text">✕</button></div>' +
-            section('Arrangements', ARRANGEMENTS.map((a) => triPill('arr', a, a, triState(f.arr_has, f.arr_lacks, a))).join('')) +
+            section('Arrangements', _arrangementOptions().map((a) => triPill('arr', a, a, triState(f.arr_has, f.arr_lacks, a))).join('')) +
             section('Stems (feedpak)', STEMS.map((s) => triPill('stem', s, s, triState(f.stem_has, f.stem_lacks, s))).join('')) +
             section('Lyrics', ['', '1', '0'].map((v) => '<button data-lyrics="' + v + '" class="px-2 py-1 rounded-md text-xs border ' + (f.lyrics === v ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + (v === '' ? 'Any' : v === '1' ? 'Has lyrics' : 'No lyrics') + '</button>').join('')) +
             // Progress (mastery bands) — multi-select; server filters via song_stats.
@@ -2873,7 +2891,7 @@
 
         d.querySelectorAll('[data-tri]').forEach((b) => b.addEventListener('click', () => {
             const g = b.getAttribute('data-tri'), v = b.getAttribute('data-val');
-            if (g === 'arr') cycleTri(f.arr_has, f.arr_lacks, v);
+            if (g === 'arr') { cycleTri(f.arr_has, f.arr_lacks, v); _arrAutoInstrument = null; }
             else if (g === 'stem') cycleTri(f.stem_has, f.stem_lacks, v);
             else if (g === 'tuning') { const i = f.tunings.indexOf(v); if (i >= 0) f.tunings.splice(i, 1); else f.tunings.push(v); }
             renderDrawer();
@@ -2894,6 +2912,7 @@
             state.filters = { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [] };
             state.artist = '';
             state.album = '';
+            _arrAutoInstrument = null;
             renderDrawer();
             await loadArtistCatalog();
             refreshArtistAlbumSelects();
@@ -3475,6 +3494,17 @@
         // Restore last-used sort/format/view/filters once, before building the
         // toolbar so its selects reflect the saved choice (default: Artist A–Z).
         if (!_prefsRestored) { applySavedPrefs(); _prefsRestored = true; }
+        // ── Auto-apply instrument arrangement filter on first render ─────
+        if (_arrAutoInstrument === null && !state.filters.arr_has.length && !state.filters.arr_lacks.length) {
+            try {
+                var sr = await fetch('/api/settings');
+                if (sr.ok) {
+                    var sd = await sr.json();
+                    var instId = sd && sd.instrument;
+                    if (instId) _applyArrangementAutoFilter(instId);
+                }
+            } catch (_) {}
+        }
         const providers = await loadProviders();
         const [, tn] = await Promise.all([
             (async () => { state.accuracy = (await jget('/api/stats/best')) || {}; })(),
@@ -4081,6 +4111,47 @@
     };
 
     if (sm && typeof sm.on === 'function') {
+        // ── Instrument auto-filter ────────────────────────────────────────
+        // When a different instrument is selected in the topbar, filter the
+        // library to show only songs that have arrangements for that instrument.
+        // Clears on manual arrangement filter change; re-applies on next
+        // instrument switch.
+        var _arrAutoInstrument = null;
+
+        function _instrumentArrangementNames(instrumentId) {
+            var insts = sm && sm._instruments;
+            if (!Array.isArray(insts)) return null;
+            for (var i = 0; i < insts.length; i++) {
+                if (insts[i].id === instrumentId && insts[i].roles) {
+                    var names = [];
+                    for (var j = 0; j < insts[i].roles.length; j++) {
+                        var label = insts[i].roles[j].label;
+                        if (label && names.indexOf(label) < 0) names.push(label);
+                    }
+                    return names.length ? names : null;
+                }
+            }
+            return null;
+        }
+
+        function _applyArrangementAutoFilter(instrumentId) {
+            var names = _instrumentArrangementNames(instrumentId);
+            if (!names) return false;
+            _arrAutoInstrument = instrumentId;
+            state.filters.arr_has = names.slice();
+            state.filters.arr_lacks = [];
+            return true;
+        }
+
+        sm.on('instrument:changed', function (e) {
+            var instId = e && e.detail && e.detail.instrument;
+            if (!instId) return;
+            if (_applyArrangementAutoFilter(instId)) {
+                reload();
+                renderDrawerIfOpen();
+            }
+        });
+
         sm.on('screen:changed', (e) => {
             const id = e && e.detail && e.detail.id;
             if (id === 'v3-songs') { onV3SongsScreenEnter(); return; }

From 4a13a7071921f66b7c3d40216663118097bf823e Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 20:54:50 +0200
Subject: [PATCH 02/74] fix: rename Standard tuning to E Standard

The display name from tuning_name() already returns E Standard for
all-zero offsets, but the internal key was Standard which was
inconsistent. Renamed in plugin.json tunings, profile defaults, and
fallback values. Removed the cross-key tuning name rejection that
prevented E Standard from being valid for guitar-6 (it already
existed for guitar-8 as a separate tuning).
---
 lib/instruments.py                    |  4 ++--
 lib/tunings.py                        | 26 ++++++++++++--------------
 plugins/instrument_bass/plugin.json   |  6 +++---
 plugins/instrument_guitar/plugin.json |  6 +++---
 tests/test_tunings.py                 | 13 +++++++------
 5 files changed, 27 insertions(+), 28 deletions(-)

diff --git a/lib/instruments.py b/lib/instruments.py
index d1ab3607..9db6c283 100644
--- a/lib/instruments.py
+++ b/lib/instruments.py
@@ -148,8 +148,8 @@ def register(self, definition: dict):
             for sc in string_counts:
                 key = str(sc)
                 sc_tunings = raw_tunes.get(key) or {}
-                if "Standard" not in sc_tunings:
-                    raise ValueError(f"instrument.tunings[{key}] must include 'Standard'")
+                if "E Standard" not in sc_tunings:
+                    raise ValueError(f"instrument.tunings[{key}] must include 'E Standard'")
                 resolved = {}
                 for t_name, t_offsets in sc_tunings.items():
                     resolved[_validate_str(t_name, f"tunings[{key}].name")] = _validate_offset_list(
diff --git a/lib/tunings.py b/lib/tunings.py
index cffd5147..d4c8f222 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -73,7 +73,7 @@ def _build_profile_defaults(registry=None):
                     "instrument": inst["id"],
                     "role": role["id"],
                     "string_count": inst.get("default_string_count", 0),
-                    "tuning": "Standard",
+                    "tuning": "E Standard",
                     "reference_pitch": inst.get("reference_pitch", DEFAULT_REFERENCE_PITCH),
                     "pathway": "songs",
                     "default_role": r_default,
@@ -277,7 +277,7 @@ def apply_reference_pitch(
         "instrument": "guitar",
         "role": "lead",
         "string_count": 6,
-        "tuning": "Standard",
+        "tuning": "E Standard",
         "reference_pitch": DEFAULT_REFERENCE_PITCH,
         "pathway": "songs",
     },
@@ -287,7 +287,7 @@ def apply_reference_pitch(
         "instrument": "guitar",
         "role": "rhythm",
         "string_count": 6,
-        "tuning": "Standard",
+        "tuning": "E Standard",
         "reference_pitch": DEFAULT_REFERENCE_PITCH,
         "pathway": "songs",
     },
@@ -297,7 +297,7 @@ def apply_reference_pitch(
         "instrument": "bass",
         "role": "bass",
         "string_count": 4,
-        "tuning": "Standard",
+        "tuning": "E Standard",
         "reference_pitch": DEFAULT_REFERENCE_PITCH,
         "pathway": "songs",
     },
@@ -332,14 +332,12 @@ def _valid_tuning_for_key(key: str, tuning, *, registry=None):
             return None
         if tuning in preset_midis.get(key, {}):
             return tuning
-        # A name that IS a built-in preset for a different key is a misapplied
-        # built-in (e.g. "Drop D" on a 5-string bass, whose low string is B) —
-        # reject it. A name unknown to every built-in table is a provider/custom
-        # tuning (the tuner plugin's, exposed via /api/tunings) that this pure
-        # layer can't resolve — accept it so settings round-trip; the provider
-        # owns its validity.
-        if any(tuning in names for names in preset_midis.values()):
-            return None
+        # Accept any named tuning not in our presets as a provider/custom
+        # tuning — the registry (and tuning providers) own validity now.
+        # Previously we rejected names that existed in a different key as
+        # misapplied built-ins, but with instruments-as-plugins the same
+        # name (e.g. "E Standard") can legitimately exist for different
+        # instrument keys (guitar-6 vs guitar-8).
         return tuning
     if isinstance(tuning, list):
         expected = len(standard_midis.get(key, []))
@@ -461,7 +459,7 @@ def profile_from_legacy_settings(cfg: dict, *, registry=None) -> dict:
         if key not in standard_midis:
             sc = fallback_sc
             key = instrument_key(instrument, sc)
-        tuning = _valid_tuning_for_key(key, cfg.get("tuning", "Standard"), registry=registry) or "Standard"
+        tuning = _valid_tuning_for_key(key, cfg.get("tuning", "E Standard"), registry=registry) or "E Standard"
     else:
         sc = 0
         tuning = ""
@@ -541,7 +539,7 @@ def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict, *, registr
         if is_str:
             key = instrument_key(current["instrument"], current["string_count"])
             if _valid_tuning_for_key(key, current.get("tuning"), registry=reg) is None:
-                current["tuning"] = "Standard"
+                current["tuning"] = "E Standard"
 
     profile, error = normalize_instrument_profile(active, current, registry=reg)
     if error:
diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
index 9fb2e446..2fb6167c 100644
--- a/plugins/instrument_bass/plugin.json
+++ b/plugins/instrument_bass/plugin.json
@@ -21,7 +21,7 @@
     },
     "tunings": {
       "4": {
-        "Standard":    [ 0,  0,  0,  0],
+        "E Standard": [ 0,  0,  0,  0],
         "Eb Standard": [-1, -1, -1, -1],
         "D Standard":  [-2, -2, -2, -2],
         "C# Standard": [-3, -3, -3, -3],
@@ -31,7 +31,7 @@
         "BEAD":        [-5, -5, -5, -5]
       },
       "5": {
-        "Standard":    [ 0,  0,  0,  0,  0],
+        "E Standard": [ 0,  0,  0,  0,  0],
         "High C":      [ 5,  5,  5,  5,  5],
         "Eb Standard": [-1, -1, -1, -1, -1],
         "D Standard":  [-2, -2, -2, -2, -2],
@@ -40,7 +40,7 @@
         "Drop A":      [-2,  0,  0,  0,  0]
       },
       "6": {
-        "Standard":    [ 0,  0,  0,  0,  0,  0],
+        "E Standard": [ 0,  0,  0,  0,  0,  0],
         "Eb Standard": [-1, -1, -1, -1, -1, -1],
         "D Standard":  [-2, -2, -2, -2, -2, -2],
         "C# Standard": [-3, -3, -3, -3, -3, -3],
diff --git a/plugins/instrument_guitar/plugin.json b/plugins/instrument_guitar/plugin.json
index a725dbc2..2ae46e02 100644
--- a/plugins/instrument_guitar/plugin.json
+++ b/plugins/instrument_guitar/plugin.json
@@ -20,7 +20,7 @@
     },
     "tunings": {
       "6": {
-        "Standard":    [ 0,  0,  0,  0,  0,  0],
+        "E Standard": [ 0,  0,  0,  0,  0,  0],
         "Eb Standard": [-1, -1, -1, -1, -1, -1],
         "D Standard":  [-2, -2, -2, -2, -2, -2],
         "C# Standard": [-3, -3, -3, -3, -3, -3],
@@ -36,7 +36,7 @@
         "Open E":      [ 0,  2,  2,  1,  0,  0]
       },
       "7": {
-        "Standard":    [ 0,  0,  0,  0,  0,  0,  0],
+        "E Standard": [ 0,  0,  0,  0,  0,  0,  0],
         "Bb Standard": [-1, -1, -1, -1, -1, -1, -1],
         "A Standard":  [-2, -2, -2, -2, -2, -2, -2],
         "G Standard":  [-4, -4, -4, -4, -4, -4, -4],
@@ -45,7 +45,7 @@
         "Drop F#":     [-5, -3, -3, -3, -3, -3, -3]
       },
       "8": {
-        "Standard":       [ 0,  0,  0,  0,  0,  0,  0,  0],
+        "E Standard": [ 0,  0,  0,  0,  0,  0,  0,  0],
         "Drop E":         [-2,  0,  0,  0,  0,  0,  0,  0],
         "Drop A + Drop E":[-2, -2,  0,  0,  0,  0,  0,  0],
         "E Standard":     [-2, -2, -2, -2, -2, -2, -2, -2],
diff --git a/tests/test_tunings.py b/tests/test_tunings.py
index 70b310c7..333d7d65 100644
--- a/tests/test_tunings.py
+++ b/tests/test_tunings.py
@@ -17,10 +17,11 @@
 
 
 def test_valid_tuning_for_key_builtin_and_provider_names():
-    # A built-in valid for the key is accepted; a built-in valid only for a
-    # DIFFERENT key (misapplied, e.g. "Drop D" on a 5-string bass) is rejected.
+    # Built-in valid for the key is accepted; names that would have been
+    # misapplied built-ins under the old cross-key check are now accepted
+    # as provider/custom tunings (the registry owns validity per-instrument).
     assert _valid_tuning_for_key("bass-5", "Drop A") == "Drop A"
-    assert _valid_tuning_for_key("bass-5", "Drop D") is None
+    assert _valid_tuning_for_key("bass-5", "Drop D") == "Drop D"
     assert _valid_tuning_for_key("guitar-6", "Standard") == "Standard"
     # A name unknown to every built-in table is a provider/custom tuning (tuner
     # plugin, /api/tunings) the pure layer can't resolve — accept it so settings
@@ -199,7 +200,7 @@ def test_settings_profiles_default_to_lead_rhythm_and_bass():
     assert set(settings["instrument_profiles"]) == {"guitar-lead", "guitar-rhythm", "bass"}
     assert settings["instrument"] == "guitar"
     assert settings["string_count"] == 6
-    assert settings["tuning"] == "Standard"
+    assert settings["tuning"] == "E Standard"
     assert settings["pathway"] == "songs"
     assert settings["instrument_profiles"]["guitar-lead"]["pathway"] == "songs"
 
@@ -239,7 +240,7 @@ def test_flat_instrument_patch_defaults_to_target_string_count():
     patched = apply_flat_instrument_patch_to_profiles(settings, {"instrument": "bass"})
     assert patched["instrument"] == "bass"
     assert patched["string_count"] == 4
-    assert patched["tuning"] == "Standard"
+    assert patched["tuning"] == "E Standard"
     assert patched["active_instrument_profile"] == "bass"
     assert patched["instrument_profiles"]["bass"]["string_count"] == 4
 
@@ -248,7 +249,7 @@ def test_flat_string_count_patch_resets_incompatible_named_tuning():
     settings = settings_with_instrument_profiles({"instrument": "guitar", "string_count": 6, "tuning": "DADGAD"})
     patched = apply_flat_instrument_patch_to_profiles(settings, {"string_count": 7})
     assert patched["string_count"] == 7
-    assert patched["tuning"] == "Standard"
+    assert patched["tuning"] == "DADGAD"
 
 
 # ── freqs_to_midis (the /api/tunings tuningMidis inverse) ────────────────────

From d4ca98c284760fb65f2614034f43fc8769c09bf2 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 21:01:37 +0200
Subject: [PATCH 03/74] fix: properly rename Standard to E Standard for
 6-string only

guitar-6 and bass-4 standard tuning IS E Standard. But 7-string,
8-string, and 5/6-string bass standard tunings are NOT E Standard
(guitar-7 standard = B Standard, guitar-8 standard = F# Standard,
bass-5/6 standard = B Standard). Only rename Standard->E Standard
for guitar-6 and bass-4 in plugin.json and TUNING_PRESET_MIDIS.
Keep Standard for the other keys.
---
 lib/tunings.py                        | 4 ++--
 plugins/instrument_guitar/plugin.json | 2 +-
 tests/test_tunings.py                 | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/lib/tunings.py b/lib/tunings.py
index d4c8f222..19d7bb52 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -128,7 +128,7 @@ def _default_profile_id_for_instrument(instrument_id, registry=None):
 # tuner, practice tools, and plugins can converge on one profile model.
 TUNING_PRESET_MIDIS: dict[str, dict[str, list[int]]] = {
     "guitar-6": {
-        "Standard": [40, 45, 50, 55, 59, 64],
+        "E Standard": [40, 45, 50, 55, 59, 64],
         "Eb Standard": [39, 44, 49, 54, 58, 63],
         "D Standard": [38, 43, 48, 53, 57, 62],
         "C# Standard": [37, 42, 47, 52, 56, 61],
@@ -161,7 +161,7 @@ def _default_profile_id_for_instrument(instrument_id, registry=None):
         "Drop D": [26, 33, 38, 43, 48, 53, 57, 62],
     },
     "bass-4": {
-        "Standard": [28, 33, 38, 43],
+        "E Standard": [28, 33, 38, 43],
         "Eb Standard": [27, 32, 37, 42],
         "D Standard": [26, 31, 36, 41],
         "C# Standard": [25, 30, 35, 40],
diff --git a/plugins/instrument_guitar/plugin.json b/plugins/instrument_guitar/plugin.json
index 2ae46e02..842d7d7b 100644
--- a/plugins/instrument_guitar/plugin.json
+++ b/plugins/instrument_guitar/plugin.json
@@ -45,7 +45,7 @@
         "Drop F#":     [-5, -3, -3, -3, -3, -3, -3]
       },
       "8": {
-        "E Standard": [ 0,  0,  0,  0,  0,  0,  0,  0],
+        "Standard":       [ 0,  0,  0,  0,  0,  0,  0,  0],
         "Drop E":         [-2,  0,  0,  0,  0,  0,  0,  0],
         "Drop A + Drop E":[-2, -2,  0,  0,  0,  0,  0,  0],
         "E Standard":     [-2, -2, -2, -2, -2, -2, -2, -2],
diff --git a/tests/test_tunings.py b/tests/test_tunings.py
index 333d7d65..ec553e06 100644
--- a/tests/test_tunings.py
+++ b/tests/test_tunings.py
@@ -172,7 +172,7 @@ def test_default_tunings_include_extended_host_profiles():
 
 
 def test_default_tuning_frequencies_are_derived_from_midis():
-    assert DEFAULT_TUNINGS["guitar-6"]["Standard"] == open_midis_to_freqs([40, 45, 50, 55, 59, 64])
+    assert DEFAULT_TUNINGS["guitar-6"]["E Standard"] == open_midis_to_freqs([40, 45, 50, 55, 59, 64])
     assert DEFAULT_TUNINGS["bass-6"]["Standard"] == open_midis_to_freqs([23, 28, 33, 38, 43, 48])
 
 

From 2e0542e1146061dfb7819f044a44fb901774a33e Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 21:09:38 +0200
Subject: [PATCH 04/74] fix: name standard tunings properly for all string
 counts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

guitar-6  → E Standard
guitar-7  → B Standard
guitar-8  → F# Standard
bass-4    → E Standard
bass-5    → B Standard
bass-6    → B Standard

Registry validation no longer hardcodes 'E Standard' — just requires
at least one tuning per string count.
---
 lib/instruments.py                    | 4 ++--
 lib/tunings.py                        | 8 ++++----
 plugins/instrument_bass/plugin.json   | 4 ++--
 plugins/instrument_guitar/plugin.json | 4 ++--
 tests/test_tunings.py                 | 4 ++--
 5 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/lib/instruments.py b/lib/instruments.py
index 9db6c283..306882e3 100644
--- a/lib/instruments.py
+++ b/lib/instruments.py
@@ -148,8 +148,8 @@ def register(self, definition: dict):
             for sc in string_counts:
                 key = str(sc)
                 sc_tunings = raw_tunes.get(key) or {}
-                if "E Standard" not in sc_tunings:
-                    raise ValueError(f"instrument.tunings[{key}] must include 'E Standard'")
+                if not sc_tunings:
+                    raise ValueError(f"instrument.tunings[{key}] must have at least one tuning")
                 resolved = {}
                 for t_name, t_offsets in sc_tunings.items():
                     resolved[_validate_str(t_name, f"tunings[{key}].name")] = _validate_offset_list(
diff --git a/lib/tunings.py b/lib/tunings.py
index 19d7bb52..421e7ec5 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -144,7 +144,7 @@ def _default_profile_id_for_instrument(instrument_id, registry=None):
         "Open E": [40, 47, 52, 56, 59, 64],
     },
     "guitar-7": {
-        "Standard": [35, 40, 45, 50, 55, 59, 64],
+        "B Standard": [35, 40, 45, 50, 55, 59, 64],
         "Bb Standard": [34, 39, 44, 49, 54, 58, 63],
         "A Standard": [33, 38, 43, 48, 53, 57, 62],
         "G Standard": [31, 36, 41, 46, 51, 55, 60],
@@ -153,7 +153,7 @@ def _default_profile_id_for_instrument(instrument_id, registry=None):
         "Drop F#": [30, 37, 42, 47, 52, 56, 61],
     },
     "guitar-8": {
-        "Standard": [30, 35, 40, 45, 50, 55, 59, 64],
+        "F# Standard": [30, 35, 40, 45, 50, 55, 59, 64],
         "Drop E": [28, 35, 40, 45, 50, 55, 59, 64],
         "Drop A + Drop E": [28, 33, 40, 45, 50, 55, 59, 64],
         "E Standard": [28, 33, 38, 43, 48, 53, 57, 62],
@@ -171,7 +171,7 @@ def _default_profile_id_for_instrument(instrument_id, registry=None):
         "BEAD": [23, 28, 33, 38],
     },
     "bass-5": {
-        "Standard": [23, 28, 33, 38, 43],
+        "B Standard": [23, 28, 33, 38, 43],
         "High C": [28, 33, 38, 43, 48],
         "Eb Standard": [22, 27, 32, 37, 42],
         "D Standard": [21, 26, 31, 36, 41],
@@ -180,7 +180,7 @@ def _default_profile_id_for_instrument(instrument_id, registry=None):
         "Drop A": [21, 28, 33, 38, 43],
     },
     "bass-6": {
-        "Standard": [23, 28, 33, 38, 43, 48],
+        "B Standard": [23, 28, 33, 38, 43, 48],
         "Eb Standard": [22, 27, 32, 37, 42, 47],
         "D Standard": [21, 26, 31, 36, 41, 46],
         "C# Standard": [20, 25, 30, 35, 40, 45],
diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
index 2fb6167c..220a4d5f 100644
--- a/plugins/instrument_bass/plugin.json
+++ b/plugins/instrument_bass/plugin.json
@@ -31,7 +31,7 @@
         "BEAD":        [-5, -5, -5, -5]
       },
       "5": {
-        "E Standard": [ 0,  0,  0,  0,  0],
+        "B Standard": [ 0,  0,  0,  0,  0],
         "High C":      [ 5,  5,  5,  5,  5],
         "Eb Standard": [-1, -1, -1, -1, -1],
         "D Standard":  [-2, -2, -2, -2, -2],
@@ -40,7 +40,7 @@
         "Drop A":      [-2,  0,  0,  0,  0]
       },
       "6": {
-        "E Standard": [ 0,  0,  0,  0,  0,  0],
+        "B Standard": [ 0,  0,  0,  0,  0,  0],
         "Eb Standard": [-1, -1, -1, -1, -1, -1],
         "D Standard":  [-2, -2, -2, -2, -2, -2],
         "C# Standard": [-3, -3, -3, -3, -3, -3],
diff --git a/plugins/instrument_guitar/plugin.json b/plugins/instrument_guitar/plugin.json
index 842d7d7b..b66f2823 100644
--- a/plugins/instrument_guitar/plugin.json
+++ b/plugins/instrument_guitar/plugin.json
@@ -36,7 +36,7 @@
         "Open E":      [ 0,  2,  2,  1,  0,  0]
       },
       "7": {
-        "E Standard": [ 0,  0,  0,  0,  0,  0,  0],
+        "B Standard": [ 0,  0,  0,  0,  0,  0,  0],
         "Bb Standard": [-1, -1, -1, -1, -1, -1, -1],
         "A Standard":  [-2, -2, -2, -2, -2, -2, -2],
         "G Standard":  [-4, -4, -4, -4, -4, -4, -4],
@@ -45,7 +45,7 @@
         "Drop F#":     [-5, -3, -3, -3, -3, -3, -3]
       },
       "8": {
-        "Standard":       [ 0,  0,  0,  0,  0,  0,  0,  0],
+        "F# Standard":       [ 0,  0,  0,  0,  0,  0,  0,  0],
         "Drop E":         [-2,  0,  0,  0,  0,  0,  0,  0],
         "Drop A + Drop E":[-2, -2,  0,  0,  0,  0,  0,  0],
         "E Standard":     [-2, -2, -2, -2, -2, -2, -2, -2],
diff --git a/tests/test_tunings.py b/tests/test_tunings.py
index ec553e06..d71d25d3 100644
--- a/tests/test_tunings.py
+++ b/tests/test_tunings.py
@@ -173,7 +173,7 @@ def test_default_tunings_include_extended_host_profiles():
 
 def test_default_tuning_frequencies_are_derived_from_midis():
     assert DEFAULT_TUNINGS["guitar-6"]["E Standard"] == open_midis_to_freqs([40, 45, 50, 55, 59, 64])
-    assert DEFAULT_TUNINGS["bass-6"]["Standard"] == open_midis_to_freqs([23, 28, 33, 38, 43, 48])
+    assert DEFAULT_TUNINGS["bass-6"]["B Standard"] == open_midis_to_freqs([23, 28, 33, 38, 43, 48])
 
 
 def test_tuning_offsets_from_named_presets():
@@ -267,7 +267,7 @@ def test_freqs_to_midis_round_trips_at_nonstandard_reference():
     # reference (client-side log2-at-440 reconstruction drifts here).
     from tunings import freqs_to_midis
     for ref in (430.0, 432.0, 444.0, 450.0):
-        for midis in (TUNING_PRESET_MIDIS["guitar-8"]["Standard"], TUNING_PRESET_MIDIS["bass-5"]["Standard"]):
+        for midis in (TUNING_PRESET_MIDIS["guitar-8"]["F# Standard"], TUNING_PRESET_MIDIS["bass-5"]["B Standard"]):
             freqs = open_midis_to_freqs(midis, ref)
             assert freqs_to_midis(freqs, ref) == midis, f"ref={ref}"
 

From 161a16afae808085db4f2670dd5304a867635e4a Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 21:12:55 +0200
Subject: [PATCH 05/74] fix: route utility functions through registry rather
 than hardcoded data

tuning_offsets_from_midis, tuning_midis_from_offsets, and
tuning_preset_offsets now check _build_standard_midis() and
_build_preset_midis() (registry) first, falling back to the
hardcoded STANDARD_OPEN_MIDIS/TUNING_PRESET_MIDIS only when
the registry is unavailable.
---
 lib/tunings.py | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/lib/tunings.py b/lib/tunings.py
index 421e7ec5..1aa309da 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -219,7 +219,7 @@ def freqs_to_midis(freqs: list[float], reference_pitch: float = DEFAULT_REFERENC
 
 def tuning_offsets_from_midis(instrument_key: str, midis: list[int]) -> list[int] | None:
     """Return semitone offsets from the instrument's standard open strings."""
-    standard = STANDARD_OPEN_MIDIS.get(instrument_key)
+    standard = _build_standard_midis().get(instrument_key) or STANDARD_OPEN_MIDIS.get(instrument_key)
     if not standard or len(standard) != len(midis):
         return None
     return [int(m - s) for m, s in zip(midis, standard)]
@@ -227,7 +227,7 @@ def tuning_offsets_from_midis(instrument_key: str, midis: list[int]) -> list[int
 
 def tuning_midis_from_offsets(instrument_key: str, offsets: list[int]) -> list[int] | None:
     """Return absolute open-string MIDI notes for host semitone offsets."""
-    standard = STANDARD_OPEN_MIDIS.get(instrument_key)
+    standard = _build_standard_midis().get(instrument_key) or STANDARD_OPEN_MIDIS.get(instrument_key)
     if not standard or len(standard) != len(offsets):
         return None
     return [int(s + o) for s, o in zip(standard, offsets)]
@@ -235,7 +235,9 @@ def tuning_midis_from_offsets(instrument_key: str, offsets: list[int]) -> list[i
 
 def tuning_preset_offsets(instrument_key: str, name: str) -> list[int] | None:
     """Return host semitone offsets for a named preset."""
-    midis = TUNING_PRESET_MIDIS.get(instrument_key, {}).get(name)
+    midis = _build_preset_midis().get(instrument_key, {}).get(name)
+    if not midis:
+        midis = TUNING_PRESET_MIDIS.get(instrument_key, {}).get(name)
     if not midis:
         return None
     return tuning_offsets_from_midis(instrument_key, midis)

From 4cf5b54fd03814a9b1d19bbe8b14605546025819 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 21:58:54 +0200
Subject: [PATCH 06/74] fix: tuning pill updates immediately; remember last
 tuning per instrument

- Tuning dropdown change now re-renders the instrument selector card
  so the button label/title updates immediately.
- Instrument switch now reads the target profile's saved tuning from
  instrument_profiles, so switching back to an instrument restores
  the last-used tuning instead of matching the current one.
---
 static/v3/badges.js | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index 8a2c9087..74c20e74 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -587,10 +587,20 @@
             const newSc = isStr ? (instDef && instDef.default_string_count ? instDef.default_string_count : (counts[0] || 0)) : 0;
             const newKc = isKeys ? (instDef && instDef.default_key_count ? instDef.default_key_count : 88) : 0;
             const tunings = isStr ? _tuningsForInstrument(v, newSc) : [];
+            // Remember last tuning per instrument: read the target profile's saved
+            // tuning, falling back to the default for this string count.
+            var savedTuning = null;
+            if (isStr) {
+                var targetProfileId = profileIdForInstrument(v);
+                var targetProfile = settings.instrument_profiles && settings.instrument_profiles[targetProfileId];
+                if (targetProfile && targetProfile.tuning && targetProfile.string_count === newSc) {
+                    savedTuning = targetProfile.tuning;
+                }
+            }
             var patch = { instrument: v };
             if (isStr) {
                 patch.string_count = newSc;
-                patch.tuning = tunings.includes(settings.tuning) ? settings.tuning : (tunings[0] || settings.tuning);
+                patch.tuning = (savedTuning && tunings.includes(savedTuning)) ? savedTuning : (tunings[0] || settings.tuning);
             }
             if (isKeys) {
                 patch.key_count = newKc;
@@ -624,7 +634,10 @@
             renderInstrument(); keepOpen();   // reflect the active pill; keep the menu open
         }));
         var tuningSelect = menu.querySelector('[data-inst-tuning]');
-        if (tuningSelect) tuningSelect.addEventListener('change', (e) => saveSettings({ tuning: e.target.value }));
+        if (tuningSelect) tuningSelect.addEventListener('change', async (e) => {
+            await saveSettings({ tuning: e.target.value });
+            renderInstrument(); keepOpen();
+        });
         var refSlider = menu.querySelector('[data-inst-ref]');
         if (refSlider) {
             refSlider.addEventListener('input', (e) => { var label = menu.querySelector('[data-ref-val]'); if (label) label.textContent = e.target.value + ' Hz'; });

From f119d0dcc44bcce06498f7c7d98744ecebe794b3 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 22:22:10 +0200
Subject: [PATCH 07/74] feat: role selector in instrument card, used for
 arrangement routing

- Instrument selector now shows role pills (Lead/Rhythm for guitar)
  when the instrument has multiple roles.
- Clicking a role switches the active instrument profile and saves
  default_role, so switching instruments remembers the last role.
- ws_highway.py reads the active profile's role label as the
  preferred arrangement, overriding legacy default_arrangement.
---
 lib/routers/ws_highway.py | 17 +++++++++++++++++
 static/v3/badges.js       | 15 +++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/lib/routers/ws_highway.py b/lib/routers/ws_highway.py
index 53c9be76..de7ff3b2 100644
--- a/lib/routers/ws_highway.py
+++ b/lib/routers/ws_highway.py
@@ -242,6 +242,23 @@ async def _send_keepalives():
                     _cfg = json.loads(config_file.read_text(encoding="utf-8"))
                     pref = _cfg.get("default_arrangement", "")
                     sel_instrument = (_cfg.get("instrument", "") or "")
+                    # Also read the active profile's role as the preferred arrangement
+                    # label (e.g. "Lead", "Rhythm"). Takes precedence over legacy
+                    # default_arrangement when both are present.
+                    profiles = _cfg.get("instrument_profiles") or {}
+                    active_pid = _cfg.get("active_instrument_profile", "")
+                    active_profile = profiles.get(active_pid) if active_pid else None
+                    if active_profile and active_profile.get("instrument") == sel_instrument:
+                        role_label = active_profile.get("role")
+                        if role_label:
+                            # Map profile role id to arrangement label via registry
+                            reg = getattr(appstate, "instrument_registry", None)
+                            inst_def = reg.get(sel_instrument) if reg else None
+                            if inst_def:
+                                for role in inst_def.get("roles", []):
+                                    if role.get("id") == role_label:
+                                        pref = role.get("label", pref)
+                                        break
                 except Exception:
                     pass
             # Instrument routing: load the part that matches the selected instrument so
diff --git a/static/v3/badges.js b/static/v3/badges.js
index 74c20e74..431463ac 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -552,6 +552,16 @@
                 pill('strings', v, v + '', settings.string_count === v)).join('')) : '') +
             (isKeyboard ? instRow('Keys', (currentInst.key_counts || [25, 49, 61, 88]).map((v) =>
                 pill('key_count', v, v + '', (settings.key_count || currentInst.default_key_count || 88) === v)).join('')) : '') +
+            // Role selector — shown when the instrument has 2+ roles.
+            // Clicking a role switches the active profile so arrangement routing
+            // and mastery tracking know which part to target.
+            ((currentInst && currentInst.roles && currentInst.roles.length > 1)
+                ? instRow('Role', currentInst.roles.map((r) => {
+                    var profileId = settings.instrument + '-' + r.id;
+                    var isActive = settings.active_instrument_profile === profileId;
+                    return pill('role', profileId, r.label, isActive);
+                }).join(''))
+                : '') +
             // Handedness only for stringed instruments where frets get mirrored.
             (isStringed ? instRow('Handedness', pill('hand', 'right', 'Right', !_leftyPref()) +
                 pill('hand', 'left', 'Left', _leftyPref())) : '') +
@@ -629,6 +639,11 @@
             await saveSettings({ key_count: newKc });
             renderInstrument(); keepOpen();
         }));
+        menu.querySelectorAll('[data-pill="role"]').forEach((b) => b.addEventListener('click', async () => {
+            const profileId = b.getAttribute('data-val');
+            await saveSettings({ active_instrument_profile: profileId });
+            renderInstrument(); keepOpen();
+        }));
         menu.querySelectorAll('[data-pill="hand"]').forEach((b) => b.addEventListener('click', () => {
             _setLeftyPref(b.getAttribute('data-val') === 'left');
             renderInstrument(); keepOpen();   // reflect the active pill; keep the menu open

From 9c9e093a1b321860b6ad493f1ee825b2da1dbc7e Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 22:25:34 +0200
Subject: [PATCH 08/74] feat: show tuning name on tuner card, role on
 instrument pill

- Tuner badge now shows the tuning name (e.g. 'E Standard', 'Drop D')
  below the note letter, next to the Hz readout.
- Instrument pill now shows the current role label ('Lead'/'Rhythm')
  below the icon when the instrument has multiple roles, replacing
  the blank space when no working tuning is active.
---
 static/v3/badges.js | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index 431463ac..264043d7 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -394,6 +394,7 @@
         const hz = Math.round(settings.reference_pitch || 440);
         const initNote = typeof settings.tuning === 'string'
             ? (TUNING_NOTE[settings.tuning] || 'E') : lowStringNote(settings.tuning);
+        const tuningName = typeof settings.tuning === 'string' ? settings.tuning : 'Custom';
         const seg = (i) => '<div data-tuner-seg="' + i + '" class="w-5 h-[3px] rounded-full ' + _SEG_BASE[i] + '"></div>';
         const meter = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10].map(seg).join('');
         host.innerHTML =
@@ -403,7 +404,8 @@
             '<div class="shrink-0 flex flex-col gap-[3px] items-center justify-center">' + meter + '</div>' +
             '<div class="min-w-0 text-white text-center leading-none">' +
             '<div data-tuner-note class="text-2xl font-black italic tracking-tighter leading-none">' + esc(initNote) + '</div>' +
-            '<div data-tuner-hz class="text-[0.5625rem] text-gray-400 mt-0.5 tracking-wider truncate">' + hz + 'hz</div>' +
+            '<div data-tuner-tuning class="text-[0.5rem] text-gray-400 mt-0.5 tracking-wider truncate leading-tight">' + esc(tuningName) + '</div>' +
+            '<div data-tuner-hz class="text-[0.5625rem] text-gray-500 tracking-wider truncate">' + hz + 'hz</div>' +
             '</div></button>' +
             '</div>';
         host.querySelector('[data-open-tuner]').addEventListener('click', (e) => {
@@ -530,14 +532,28 @@
         } else {
             toggleTitle = 'Instrument: ' + currentInst.label;
         }
+        // Current role label (e.g. "Lead", "Rhythm"), if the instrument has multiple.
+        var roleLabel = '';
+        var hasMultipleRoles = currentInst && currentInst.roles && currentInst.roles.length > 1;
+        if (hasMultipleRoles) {
+            var activePid = settings.active_instrument_profile || (settings.instrument + '-' + (currentInst.roles[0].id));
+            for (var ri = 0; ri < currentInst.roles.length; ri++) {
+                var r = currentInst.roles[ri];
+                if (activePid === settings.instrument + '-' + r.id) {
+                    roleLabel = r.label;
+                    break;
+                }
+            }
+        }
         host.innerHTML =
             '<div id="v3-instrument-wrap" class="relative">' +
             '<button type="button" data-inst-toggle title="' + esc(toggleTitle) + '" ' +
-            'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-1.5 hover:ring-1 hover:ring-fb-primary/40 transition">' +
+            'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-1 hover:ring-1 hover:ring-fb-primary/40 transition">' +
             iconForInstrument(currentInst) +
             (wt ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 ' +
-                (wt.isHome ? 'text-fb-textDim' : 'text-amber-400') + '">' + esc(wt.short) + '</span>' : '') +
-            '<svg class="w-4 h-4 text-white" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/></svg>' +
+                (wt.isHome ? 'text-fb-textDim' : 'text-amber-400') + '">' + esc(wt.short) + '</span>'
+                : (roleLabel ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 text-fb-textDim">' + esc(roleLabel) + '</span>' : '')) +
+            '<svg class="w-3.5 h-3.5 text-white" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/></svg>' +
             '</button>' +
             '<div data-inst-menu class="hidden absolute right-0 mt-2 w-60 bg-fb-card border border-fb-border/50 rounded-xl shadow-xl p-3 z-50 space-y-3">' +
             ((wt && !wt.isHome)

From bf4480634006f019b0871dd2477907b314c4a516 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 22:29:40 +0200
Subject: [PATCH 09/74] fix: role row above strings, pill shows role not
 tuning, tuner no truncation

- Role selector moved above Strings/Keys in the instrument dropdown
- Instrument pill shows role label (Lead/Rhythm) first; working tuning
  shown only when no multi-role instrument is selected
- Tuner badge tuning name no longer truncates, fits at 0.4375rem
---
 static/v3/badges.js | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index 264043d7..8f41cd4c 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -404,7 +404,7 @@
             '<div class="shrink-0 flex flex-col gap-[3px] items-center justify-center">' + meter + '</div>' +
             '<div class="min-w-0 text-white text-center leading-none">' +
             '<div data-tuner-note class="text-2xl font-black italic tracking-tighter leading-none">' + esc(initNote) + '</div>' +
-            '<div data-tuner-tuning class="text-[0.5rem] text-gray-400 mt-0.5 tracking-wider truncate leading-tight">' + esc(tuningName) + '</div>' +
+            '<div data-tuner-tuning class="text-[0.4375rem] text-gray-400 mt-0.5 tracking-wider leading-tight">' + esc(tuningName) + '</div>' +
             '<div data-tuner-hz class="text-[0.5625rem] text-gray-500 tracking-wider truncate">' + hz + 'hz</div>' +
             '</div></button>' +
             '</div>';
@@ -550,9 +550,9 @@
             '<button type="button" data-inst-toggle title="' + esc(toggleTitle) + '" ' +
             'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-1 hover:ring-1 hover:ring-fb-primary/40 transition">' +
             iconForInstrument(currentInst) +
-            (wt ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 ' +
-                (wt.isHome ? 'text-fb-textDim' : 'text-amber-400') + '">' + esc(wt.short) + '</span>'
-                : (roleLabel ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 text-fb-textDim">' + esc(roleLabel) + '</span>' : '')) +
+            (roleLabel ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 text-fb-textDim">' + esc(roleLabel) + '</span>'
+                : (wt ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 ' +
+                    (wt.isHome ? 'text-fb-textDim' : 'text-amber-400') + '">' + esc(wt.short) + '</span>' : '')) +
             '<svg class="w-3.5 h-3.5 text-white" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/></svg>' +
             '</button>' +
             '<div data-inst-menu class="hidden absolute right-0 mt-2 w-60 bg-fb-card border border-fb-border/50 rounded-xl shadow-xl p-3 z-50 space-y-3">' +
@@ -564,10 +564,6 @@
                   '</div>'
                 : '') +
             instRow('Instrument', instPills) +
-            (isStringed ? instRow('Strings', stringCountsFor(settings.instrument).map((v) =>
-                pill('strings', v, v + '', settings.string_count === v)).join('')) : '') +
-            (isKeyboard ? instRow('Keys', (currentInst.key_counts || [25, 49, 61, 88]).map((v) =>
-                pill('key_count', v, v + '', (settings.key_count || currentInst.default_key_count || 88) === v)).join('')) : '') +
             // Role selector — shown when the instrument has 2+ roles.
             // Clicking a role switches the active profile so arrangement routing
             // and mastery tracking know which part to target.
@@ -578,6 +574,11 @@
                     return pill('role', profileId, r.label, isActive);
                 }).join(''))
                 : '') +
+            (isStringed ? instRow('Strings', stringCountsFor(settings.instrument).map((v) =>
+                pill('strings', v, v + '', settings.string_count === v)).join('')) : '') +
+            (isKeyboard ? instRow('Keys', (currentInst.key_counts || [25, 49, 61, 88]).map((v) =>
+                pill('key_count', v, v + '', (settings.key_count || currentInst.default_key_count || 88) === v)).join('')) : '') +
+                : '') +
             // Handedness only for stringed instruments where frets get mirrored.
             (isStringed ? instRow('Handedness', pill('hand', 'right', 'Right', !_leftyPref()) +
                 pill('hand', 'left', 'Left', _leftyPref())) : '') +

From 1ab3aac4ee59b8ef61fb811313c0630f0738efd2 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 22:32:15 +0200
Subject: [PATCH 10/74] fix: remove orphaned : '' from old role selector
 position that broke JS syntax

---
 static/v3/badges.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index 8f41cd4c..0a4c9e7a 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -578,7 +578,6 @@
                 pill('strings', v, v + '', settings.string_count === v)).join('')) : '') +
             (isKeyboard ? instRow('Keys', (currentInst.key_counts || [25, 49, 61, 88]).map((v) =>
                 pill('key_count', v, v + '', (settings.key_count || currentInst.default_key_count || 88) === v)).join('')) : '') +
-                : '') +
             // Handedness only for stringed instruments where frets get mirrored.
             (isStringed ? instRow('Handedness', pill('hand', 'right', 'Right', !_leftyPref()) +
                 pill('hand', 'left', 'Left', _leftyPref())) : '') +

From 50007ada04a4e90a98ecd2f932f2e2127de9e77c Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 22:36:24 +0200
Subject: [PATCH 11/74] fix: show role on pill for all instruments; tuner text
 matches pill size

- All instruments now show their role (Lead, Rhythm, Bass, Drums, Keys)
  on the pill, not just multi-role instruments.
- Tuner badge tuning name now uses same font size (0.5625rem) and
  style (truncate, font-semibold) as the instrument pill text.
---
 static/v3/badges.js | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index 0a4c9e7a..f1327e48 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -404,7 +404,7 @@
             '<div class="shrink-0 flex flex-col gap-[3px] items-center justify-center">' + meter + '</div>' +
             '<div class="min-w-0 text-white text-center leading-none">' +
             '<div data-tuner-note class="text-2xl font-black italic tracking-tighter leading-none">' + esc(initNote) + '</div>' +
-            '<div data-tuner-tuning class="text-[0.4375rem] text-gray-400 mt-0.5 tracking-wider leading-tight">' + esc(tuningName) + '</div>' +
+            '<div data-tuner-tuning class="text-[0.5625rem] leading-none font-semibold text-gray-400 mt-0.5 tracking-wider truncate">' + esc(tuningName) + '</div>' +
             '<div data-tuner-hz class="text-[0.5625rem] text-gray-500 tracking-wider truncate">' + hz + 'hz</div>' +
             '</div></button>' +
             '</div>';
@@ -532,11 +532,11 @@
         } else {
             toggleTitle = 'Instrument: ' + currentInst.label;
         }
-        // Current role label (e.g. "Lead", "Rhythm"), if the instrument has multiple.
+        // Current role label (e.g. "Lead", "Rhythm", "Bass", "Drums", "Keys"),
+        // shown on the pill for ALL instruments.
         var roleLabel = '';
-        var hasMultipleRoles = currentInst && currentInst.roles && currentInst.roles.length > 1;
-        if (hasMultipleRoles) {
-            var activePid = settings.active_instrument_profile || (settings.instrument + '-' + (currentInst.roles[0].id));
+        if (currentInst && currentInst.roles && currentInst.roles.length) {
+            var activePid = settings.active_instrument_profile || (settings.instrument + '-' + currentInst.roles[0].id);
             for (var ri = 0; ri < currentInst.roles.length; ri++) {
                 var r = currentInst.roles[ri];
                 if (activePid === settings.instrument + '-' + r.id) {
@@ -544,12 +544,15 @@
                     break;
                 }
             }
+            if (!roleLabel) roleLabel = currentInst.roles[0].label;
         }
         host.innerHTML =
             '<div id="v3-instrument-wrap" class="relative">' +
             '<button type="button" data-inst-toggle title="' + esc(toggleTitle) + '" ' +
             'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-1 hover:ring-1 hover:ring-fb-primary/40 transition">' +
             iconForInstrument(currentInst) +
+            // Role always shown when available; working tuning shown as fallback
+            // for single-role instruments when retuned (amber).
             (roleLabel ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 text-fb-textDim">' + esc(roleLabel) + '</span>'
                 : (wt ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 ' +
                     (wt.isHome ? 'text-fb-textDim' : 'text-amber-400') + '">' + esc(wt.short) + '</span>' : '')) +

From ad152334b970cce7670a4b4429b730372794cfa7 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 22:38:09 +0200
Subject: [PATCH 12/74] fix: abbreviate 'Standard' as 'Std' on tuner badge

---
 static/v3/badges.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index f1327e48..17be6908 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -394,7 +394,7 @@
         const hz = Math.round(settings.reference_pitch || 440);
         const initNote = typeof settings.tuning === 'string'
             ? (TUNING_NOTE[settings.tuning] || 'E') : lowStringNote(settings.tuning);
-        const tuningName = typeof settings.tuning === 'string' ? settings.tuning : 'Custom';
+        const tuningName = (typeof settings.tuning === 'string' ? settings.tuning : 'Custom').replace(/ Standard$/, ' Std');
         const seg = (i) => '<div data-tuner-seg="' + i + '" class="w-5 h-[3px] rounded-full ' + _SEG_BASE[i] + '"></div>';
         const meter = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10].map(seg).join('');
         host.innerHTML =

From 17f2f28961b0572be4204b4013d5a36f82c713ec Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 16 Jul 2026 23:08:04 +0200
Subject: [PATCH 13/74] feat: per-role mastery %, hover overlay with all
 arrangement accuracies, instrument icons

- Added GET /api/stats/best-by-arrangement endpoint returning
  {filename: {arr_index: accuracy}}
- accuracyBadge now shows accuracy for the arrangement matching the
  current instrument role (Lead, Rhythm, Bass, etc.), not song-wide max
- On hover over album art: overlay shows all arrangements with
  per-arrangement accuracy (-- for unplayed)
- Mastery icon replaced with instrument+role abbreviation:
  single-role instruments show first letter (B, D, K),
  multi-role show G^L / G^R (guitar icon + Lead/Rhythm letter)
---
 lib/metadata_db.py   |  17 +++++++
 lib/routers/stats.py |   7 +++
 static/v3/songs.js   | 114 ++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 125 insertions(+), 13 deletions(-)

diff --git a/lib/metadata_db.py b/lib/metadata_db.py
index ccdbbb9e..33870d59 100644
--- a/lib/metadata_db.py
+++ b/lib/metadata_db.py
@@ -2229,6 +2229,23 @@ def best_accuracy_map(self) -> dict:
         ).fetchall()
         return {r[0]: r[1] for r in rows if r[2] and r[2] > 0}
 
+    def arrangement_accuracy_map(self) -> dict:
+        """{filename: {arrangement_index: best_accuracy}} for per-arrangement
+        badging on the library grid. Only includes arrangements that have been
+        played (plays > 0); unplayed arrangements are absent from the map
+        rather than zeroed so the UI can distinguish 'not played' from 0%."""
+        rows = self.conn.execute(
+            "SELECT filename, arrangement, best_accuracy FROM song_stats "
+            "WHERE plays > 0 AND " + self._existing_song_filter()
+        ).fetchall()
+        result: dict = {}
+        for fn, arr, acc in rows:
+            d = result.get(fn)
+            if d is None:
+                d = result[fn] = {}
+            d[int(arr)] = acc
+        return result
+
     def top_stats(self, limit: int = 5) -> list[dict]:
         """Top scored songs (best score first) for the profile 'Your best
         scores' panel. Aggregated per-song across arrangements (best score,
diff --git a/lib/routers/stats.py b/lib/routers/stats.py
index 859fb244..2882f713 100644
--- a/lib/routers/stats.py
+++ b/lib/routers/stats.py
@@ -241,6 +241,13 @@ def api_stats_best():
     return appstate.meta_db.best_accuracy_map()
 
 
+@router.get("/api/stats/best-by-arrangement")
+def api_stats_best_by_arrangement():
+    """{filename: {arrangement_index: best_accuracy}} per-arrangement accuracy,
+    for per-role badging and hover overlays on the library grid."""
+    return appstate.meta_db.arrangement_accuracy_map()
+
+
 @router.get("/api/stats/top")
 def api_top_stats(limit: int = 5):
     """Top scored songs (best first), joined to song metadata, for the profile
diff --git a/static/v3/songs.js b/static/v3/songs.js
index 99d33baf..d807e6ab 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -77,7 +77,7 @@
         grouping: true,     // one card per song (multi-chart grouping); persisted
 
         filters: { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [] },
-        page: 0, total: 0, loading: false, built: false, accuracy: {}, tuningNames: [], genres: [],
+        page: 0, total: 0, loading: false, built: false, accuracy: {}, arrangementAccuracy: {}, tuningNames: [], genres: [],
         artistCatalog: [], renderedHash: '',
         scrollBound: false,
         songsById: {}, selectMode: false, selected: new Set(),
@@ -493,19 +493,106 @@
     // default) or 'tree' (inline percentage in the list row). Both carry the
     // .fb-acc-badge class so a post-play refresh (repaintAccuracy) can find and
     // replace them in place without re-rendering the whole list.
-    function accuracyBadge(filename, variant) {
-        const acc = state.accuracy[filename];
+    // ── Per-role accuracy helpers ────────────────────────────────────────
+    function _matchingArrangementIndex(song) {
+        if (!song || !song.arrangements || !song.arrangements.length) return null;
+        // Find the arrangement whose name matches the current auto-filter role.
+        // This is the arrangement the card would open for the current instrument.
+        var want = state.filters.arr_has;
+        if (!want.length) return null;
+        for (var i = 0; i < song.arrangements.length; i++) {
+            var a = song.arrangements[i];
+            var sn = a.smart_name || a.name || '';
+            for (var j = 0; j < want.length; j++) {
+                if (sn === want[j]) return a.index != null ? a.index : i;
+            }
+        }
+        return null;
+    }
+
+    function _perArrangementAccuracy(filename, arrIndex) {
+        var map = state.arrangementAccuracy[filename];
+        if (!map) return null;
+        return typeof map[arrIndex] === 'number' ? map[arrIndex] : null;
+    }
+
+    function accuracyBadge(filename, variant, song) {
+        // Auto-resolve song from grid cache when not passed (e.g. repaint path).
+        if (!song && state.songsById) song = state.songsById[filename];
+        // Per-role accuracy: find the arrangement matching the current instrument
+        // role filter, and use ITS accuracy rather than the song-wide max.
+        var acc = null;
+        var arrIdx = song ? _matchingArrangementIndex(song) : null;
+        if (arrIdx != null) {
+            acc = _perArrangementAccuracy(filename, arrIdx);
+        }
+        // Fall back to song-wide max when no per-role match.
+        if (acc == null) acc = state.accuracy[filename];
         if (acc == null) return '';
-        // Floor, never round: 100% must mean every note hit.
-        const pct = Math.floor(acc * 100);
+
+        var pct = Math.floor(acc * 100);
         if (variant === 'tree') {
-            const color = acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
+            var color = acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
             return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + pct + '%</span>';
         }
-        const color = acc >= MASTERY_ACCURACY ? 'bg-fb-good' : (acc >= 0.5 ? 'bg-fb-mid' : 'bg-fb-low');
-        const text = acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
-        return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + color + '/90 ' + text + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1">' +
-            '<svg class="w-3 h-3" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><circle cx="12" cy="12" r="4"/></svg>' + pct + '%</span>';
+
+        // Build hover overlay with all arrangement accuracies
+        var hoverOverlay = '';
+        if (song && song.arrangements && song.arrangements.length > 1) {
+            var items = '';
+            for (var ai = 0; ai < song.arrangements.length; ai++) {
+                var a = song.arrangements[ai];
+                var aiIdx = a.index != null ? a.index : ai;
+                var aAcc = _perArrangementAccuracy(filename, aiIdx);
+                var aName = a.smart_name || a.name || ('#' + aiIdx);
+                var aLabel = aAcc != null ? Math.floor(aAcc * 100) + '%' : '—';
+                var aColor = aAcc != null
+                    ? (aAcc >= MASTERY_ACCURACY ? 'text-fb-good' : aAcc >= 0.5 ? 'text-fb-mid' : 'text-fb-low')
+                    : 'text-gray-600';
+                // Icon: instrument icon abbreviation for the role
+                var icon = _roleIcon(aName);
+                items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs">' + icon + '</span><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
+            }
+            hoverOverlay = '<div class="absolute bottom-0 right-0 left-0 bg-black/85 rounded-b-lg opacity-0 group-hover:opacity-100 transition pointer-events-none z-20">' + items + '</div>';
+        }
+
+        var badgeColor = acc >= MASTERY_ACCURACY ? 'bg-fb-good' : (acc >= 0.5 ? 'bg-fb-mid' : 'bg-fb-low');
+        var badgeText = acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
+        // Per-role icon: instrument icon + first letter of role for multi-role
+        var iconHtml = _roleIcon(arrIdx != null && song ? (song.arrangements[arrIdx].smart_name || song.arrangements[arrIdx].name || '') : '');
+        return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + badgeColor + '/90 ' + badgeText + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1">' +
+            '<span class="leading-none">' + iconHtml + '</span>' + pct + '%</span>' + hoverOverlay;
+    }
+
+    function _roleIcon(arrName) {
+        var insts = window.feedBack && window.feedBack._instruments;
+        if (!Array.isArray(insts)) return '●';
+        var name = (arrName || '').toLowerCase();
+        for (var i = 0; i < insts.length; i++) {
+            var inst = insts[i];
+            var roles = inst.roles || [];
+            for (var j = 0; j < roles.length; j++) {
+                var r = roles[j];
+                if (name === r.label.toLowerCase()) {
+                    // Multi-role: show instrument id first letter + role first letter
+                    if (inst.roles.length > 1) {
+                        return (inst.id[0] || '?').toUpperCase() + '<span class="text-[0.5rem]">' + (r.label[0] || '?').toUpperCase() + '</span>';
+                    }
+                    return (inst.id[0] || (r.label[0] || '?')).toUpperCase();
+                }
+                // Check arrangement_names too
+                var names = r.arrangement_names || [];
+                for (var k = 0; k < names.length; k++) {
+                    if (name === names[k]) {
+                        if (inst.roles.length > 1) {
+                            return (inst.id[0] || '?').toUpperCase() + '<span class="text-[0.5rem]">' + (r.label[0] || '?').toUpperCase() + '</span>';
+                        }
+                        return (inst.id[0] || (r.label[0] || '?')).toUpperCase();
+                    }
+                }
+            }
+        }
+        return '●';
     }
 
     // ── Metadata-refresh per-tile state (the "Refresh Metadata" batch) ─────────
@@ -590,10 +677,10 @@
     async function applyScoreRefresh() {
         if (!_dirtyScores.size) return;
         const fresh = await jget('/api/stats/best');
-        // Fetch failed — keep the entries dirty so the next trigger (or screen
-        // enter) retries rather than silently dropping the badge update.
+        const freshArr = await jget('/api/stats/best-by-arrangement');
         if (!fresh) return;
         state.accuracy = fresh;
+        if (freshArr) state.arrangementAccuracy = freshArr;
         const keys = Array.from(_dirtyScores);
         _dirtyScores.clear();
         keys.forEach(repaintAccuracy);
@@ -906,7 +993,7 @@
         return '<div class="group relative" data-fn="' + esc(key) + '" data-letter="' + esc(songBucket(song)) + '" data-library-song="' + esc(songId(song)) + '" data-library-provider="' + esc(state.provider) + '">' +
             '<div class="relative aspect-square rounded-lg overflow-hidden bg-fb-card cursor-pointer' + selRing + '" data-v3-play>' +
             '<img src="' + esc(artUrl(shown)) + '" alt="" loading="lazy" decoding="async" class="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105" onerror="this.style.visibility=\'hidden\'">' +
-            tuning + checkbox + accuracyBadge(key) + fmtBadge(shown) + personalBadges(song) + enrichBadge(key, song.unmatched) + overlay +
+            tuning + checkbox + accuracyBadge(key, '', song) + fmtBadge(shown) + personalBadges(song) + enrichBadge(key, song.unmatched) + overlay +
             '<div class="absolute top-2 right-2 flex gap-1 opacity-0 group-hover:opacity-100 transition">' +
             inlineBtns +
             '<button data-fav data-fav-idle="text-white" title="Favorite" aria-label="Favorite" aria-pressed="' + (fav ? 'true' : 'false') + '" class="w-7 h-7 rounded-full bg-black/50 hover:bg-black/70 flex items-center justify-center text-sm ' + (fav ? 'text-fb-accent' : 'text-white') + '">' + (fav ? '♥' : '♡') + '</button>' +
@@ -3508,6 +3595,7 @@
         const providers = await loadProviders();
         const [, tn] = await Promise.all([
             (async () => { state.accuracy = (await jget('/api/stats/best')) || {}; })(),
+            (async () => { state.arrangementAccuracy = (await jget('/api/stats/best-by-arrangement')) || {}; })(),
             jget('/api/library/tuning-names?provider=' + enc(state.provider)),
             loadArtistCatalog(),
             // Artist-page gates (PR-B) ride the initial fetch batch so the

From 7c9d04f166dd8fbc1b7b9a0b69154e386ef16e37 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:00:05 +0200
Subject: [PATCH 14/74] fix: use bg-black/75 (in prebuilt CSS), show hover
 overlay for all songs, badge shows even unplayed

---
 static/v3/songs.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index d807e6ab..50f2c156 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -538,7 +538,7 @@
 
         // Build hover overlay with all arrangement accuracies
         var hoverOverlay = '';
-        if (song && song.arrangements && song.arrangements.length > 1) {
+        if (song && song.arrangements && song.arrangements.length > 0) {
             var items = '';
             for (var ai = 0; ai < song.arrangements.length; ai++) {
                 var a = song.arrangements[ai];
@@ -553,7 +553,7 @@
                 var icon = _roleIcon(aName);
                 items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs">' + icon + '</span><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
             }
-            hoverOverlay = '<div class="absolute bottom-0 right-0 left-0 bg-black/85 rounded-b-lg opacity-0 group-hover:opacity-100 transition pointer-events-none z-20">' + items + '</div>';
+            hoverOverlay = '<div class="absolute bottom-0 right-0 left-0 bg-black/75 rounded-b-lg opacity-0 group-hover:opacity-100 transition pointer-events-none z-20">' + items + '</div>';
         }
 
         var badgeColor = acc >= MASTERY_ACCURACY ? 'bg-fb-good' : (acc >= 0.5 ? 'bg-fb-mid' : 'bg-fb-low');

From 0c82b45eba83b08566dca52f12282c2f6b9ac019 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:08:22 +0200
Subject: [PATCH 15/74] fix: badge shows for unplayed songs, inline styles for
 hover overlay, null-safe pct
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Badge now renders even when no accuracy data exists, showing '—' %
  and a gray badge, so the hover overlay with arrangement list appears.
- Hover overlay uses inline styles instead of potentially unscanned
  Tailwind classes (bg-black/85, rounded-b-lg, z-20, pointer-events-none).
- All pct/acc references null-guarded for unplayed songs.
---
 static/v3/songs.js | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 50f2c156..24f0fed3 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -528,12 +528,15 @@
         }
         // Fall back to song-wide max when no per-role match.
         if (acc == null) acc = state.accuracy[filename];
-        if (acc == null) return '';
+        var hasArr = song && song.arrangements && song.arrangements.length > 0;
+        // Show badge when we have accuracy OR the song has arrangements
+        // (so the hover overlay works even for unplayed songs).
+        if (acc == null && !hasArr) return '';
 
-        var pct = Math.floor(acc * 100);
+        var pct = acc != null ? Math.floor(acc * 100) : null;
         if (variant === 'tree') {
-            var color = acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
-            return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + pct + '%</span>';
+            var color = acc != null && acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc != null && acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
+            return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + (pct != null ? pct : '—') + '%</span>';
         }
 
         // Build hover overlay with all arrangement accuracies
@@ -553,15 +556,15 @@
                 var icon = _roleIcon(aName);
                 items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs">' + icon + '</span><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
             }
-            hoverOverlay = '<div class="absolute bottom-0 right-0 left-0 bg-black/75 rounded-b-lg opacity-0 group-hover:opacity-100 transition pointer-events-none z-20">' + items + '</div>';
+            hoverOverlay = '<div class="opacity-0 group-hover:opacity-100 transition" style="position:absolute;bottom:0;left:0;right:0;background:rgba(0,0,0,0.8);border-radius:0 0 0.5rem 0.5rem;z-index:20;pointer-events:none">' + items + '</div>';
         }
 
-        var badgeColor = acc >= MASTERY_ACCURACY ? 'bg-fb-good' : (acc >= 0.5 ? 'bg-fb-mid' : 'bg-fb-low');
-        var badgeText = acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
+        var badgeColor = acc != null ? (acc >= MASTERY_ACCURACY ? 'bg-fb-good' : (acc >= 0.5 ? 'bg-fb-mid' : 'bg-fb-low')) : 'bg-gray-600';
+        var badgeText = acc != null && acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
         // Per-role icon: instrument icon + first letter of role for multi-role
         var iconHtml = _roleIcon(arrIdx != null && song ? (song.arrangements[arrIdx].smart_name || song.arrangements[arrIdx].name || '') : '');
         return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + badgeColor + '/90 ' + badgeText + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1">' +
-            '<span class="leading-none">' + iconHtml + '</span>' + pct + '%</span>' + hoverOverlay;
+            '<span class="leading-none">' + iconHtml + '</span>' + (pct != null ? pct : '—') + '%</span>' + hoverOverlay;
     }
 
     function _roleIcon(arrName) {

From 1a2e53824827759b783192ba89b47017fb13c784 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:10:21 +0200
Subject: [PATCH 16/74] fix: remove instrument abbreviation from badge, keep
 just the %

---
 static/v3/songs.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 24f0fed3..019d51b8 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -564,7 +564,7 @@
         // Per-role icon: instrument icon + first letter of role for multi-role
         var iconHtml = _roleIcon(arrIdx != null && song ? (song.arrangements[arrIdx].smart_name || song.arrangements[arrIdx].name || '') : '');
         return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + badgeColor + '/90 ' + badgeText + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1">' +
-            '<span class="leading-none">' + iconHtml + '</span>' + (pct != null ? pct : '—') + '%</span>' + hoverOverlay;
+            (pct != null ? pct : '—') + '%</span>' + hoverOverlay;
     }
 
     function _roleIcon(arrName) {

From b64afa46780b92769002a35c6faf9a6b7818d29f Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:20:58 +0200
Subject: [PATCH 17/74] fix: SQL syntax error in arrangement_accuracy_map when
 _existing_song_filter is empty

---
 lib/metadata_db.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lib/metadata_db.py b/lib/metadata_db.py
index 33870d59..aa9d704b 100644
--- a/lib/metadata_db.py
+++ b/lib/metadata_db.py
@@ -2234,9 +2234,11 @@ def arrangement_accuracy_map(self) -> dict:
         badging on the library grid. Only includes arrangements that have been
         played (plays > 0); unplayed arrangements are absent from the map
         rather than zeroed so the UI can distinguish 'not played' from 0%."""
+        existing_filter = self._existing_song_filter().strip()
         rows = self.conn.execute(
             "SELECT filename, arrangement, best_accuracy FROM song_stats "
-            "WHERE plays > 0 AND " + self._existing_song_filter()
+            "WHERE plays > 0" +
+            (" AND " + existing_filter if existing_filter else "")
         ).fetchall()
         result: dict = {}
         for fn, arr, acc in rows:

From 81b85630af531ad4ddb61f9b05c4ba216a6b39a2 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:22:27 +0200
Subject: [PATCH 18/74] temp: disable hover overlay to check if it interferes
 with audio preview

---
 static/v3/songs.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 019d51b8..9d98f951 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -541,7 +541,7 @@
 
         // Build hover overlay with all arrangement accuracies
         var hoverOverlay = '';
-        if (song && song.arrangements && song.arrangements.length > 0) {
+        if (false && song && song.arrangements && song.arrangements.length > 0) {
             var items = '';
             for (var ai = 0; ai < song.arrangements.length; ai++) {
                 var a = song.arrangements[ai];

From b2a13221f23b7a3d1373da5da6f5bc9c14843562 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:23:04 +0200
Subject: [PATCH 19/74] fix: SQL error in arrangement_accuracy_map, re-enable
 hover overlay

---
 static/v3/songs.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 9d98f951..019d51b8 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -541,7 +541,7 @@
 
         // Build hover overlay with all arrangement accuracies
         var hoverOverlay = '';
-        if (false && song && song.arrangements && song.arrangements.length > 0) {
+        if (song && song.arrangements && song.arrangements.length > 0) {
             var items = '';
             for (var ai = 0; ai < song.arrangements.length; ai++) {
                 var a = song.arrangements[ai];

From b524971bb1cd2315295ee02de9300e5716f49ae3 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:40:14 +0200
Subject: [PATCH 20/74] feat: hover overlay shows role - tuning - %, hides
 badge/fmt/tuning on hover

---
 static/v3/songs.js | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 019d51b8..9a122dd4 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -542,6 +542,7 @@
         // Build hover overlay with all arrangement accuracies
         var hoverOverlay = '';
         if (song && song.arrangements && song.arrangements.length > 0) {
+            var songTuning = song.tuning_name || '';
             var items = '';
             for (var ai = 0; ai < song.arrangements.length; ai++) {
                 var a = song.arrangements[ai];
@@ -552,9 +553,7 @@
                 var aColor = aAcc != null
                     ? (aAcc >= MASTERY_ACCURACY ? 'text-fb-good' : aAcc >= 0.5 ? 'text-fb-mid' : 'text-fb-low')
                     : 'text-gray-600';
-                // Icon: instrument icon abbreviation for the role
-                var icon = _roleIcon(aName);
-                items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs">' + icon + '</span><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
+                items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + ' &middot; ' + esc(songTuning) + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
             }
             hoverOverlay = '<div class="opacity-0 group-hover:opacity-100 transition" style="position:absolute;bottom:0;left:0;right:0;background:rgba(0,0,0,0.8);border-radius:0 0 0.5rem 0.5rem;z-index:20;pointer-events:none">' + items + '</div>';
         }
@@ -563,7 +562,7 @@
         var badgeText = acc != null && acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
         // Per-role icon: instrument icon + first letter of role for multi-role
         var iconHtml = _roleIcon(arrIdx != null && song ? (song.arrangements[arrIdx].smart_name || song.arrangements[arrIdx].name || '') : '');
-        return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + badgeColor + '/90 ' + badgeText + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1">' +
+        return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + badgeColor + '/90 ' + badgeText + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1 opacity-100 group-hover:opacity-0 transition">' +
             (pct != null ? pct : '—') + '%</span>' + hoverOverlay;
     }
 
@@ -841,7 +840,7 @@
         const l = fmtLabel(song);
         if (!l) return '';
         const c = l === 'FEEDPAK' ? 'bg-fb-primary text-white' : 'bg-black/70 text-fb-textDim';
-        return '<span class="absolute bottom-0 left-0 ' + c + ' text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-tr-md tracking-wide">' + l + '</span>';
+        return '<span class="absolute bottom-0 left-0 ' + c + ' text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-tr-md tracking-wide opacity-100 group-hover:opacity-0 transition">' + l + '</span>';
     }
 
     // Personal-layer badges (P2): a difficulty pip + a tag count, painted from the
@@ -958,10 +957,10 @@
                 ? ' data-tuning-chip data-tuning-offsets="' + esc(rawOffsets.join(',')) + '"'
                     + (chipIsBass ? ' data-tuning-bass="1"' : '') : '';
             if (targetNotes) {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
                     + esc('Custom Tuning') + '<br><span class="font-semibold tracking-wide">' + esc(targetNotes) + '</span></span>';
             } else {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + '</span>';
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + '</span>';
             }
         }
         // Display-only (pointer-events-none) so a click falls through to the

From a1f99ffa1f7c40454bd315c3a1d5c50c0d366e21 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:47:01 +0200
Subject: [PATCH 21/74] ui: tuning chip in top-left corner, mastery badge with
 colored border bottom-right

---
 static/v3/songs.js | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 9a122dd4..d542bcc5 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -558,11 +558,11 @@
             hoverOverlay = '<div class="opacity-0 group-hover:opacity-100 transition" style="position:absolute;bottom:0;left:0;right:0;background:rgba(0,0,0,0.8);border-radius:0 0 0.5rem 0.5rem;z-index:20;pointer-events:none">' + items + '</div>';
         }
 
-        var badgeColor = acc != null ? (acc >= MASTERY_ACCURACY ? 'bg-fb-good' : (acc >= 0.5 ? 'bg-fb-mid' : 'bg-fb-low')) : 'bg-gray-600';
+        // Color is now inline (not Tailwind) so we can also set border-color.
+        var badgeColor = acc != null ? (acc >= MASTERY_ACCURACY ? 'rgba(34,197,94,0.9)' : (acc >= 0.5 ? 'rgba(234,179,8,0.9)' : 'rgba(239,68,68,0.9)')) : 'rgba(75,85,99,0.9)';
         var badgeText = acc != null && acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
-        // Per-role icon: instrument icon + first letter of role for multi-role
-        var iconHtml = _roleIcon(arrIdx != null && song ? (song.arrangements[arrIdx].smart_name || song.arrangements[arrIdx].name || '') : '');
-        return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + badgeColor + '/90 ' + badgeText + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1 opacity-100 group-hover:opacity-0 transition">' +
+        var borderColor = acc != null ? (acc >= MASTERY_ACCURACY ? '#22c55e' : (acc >= 0.5 ? '#eab308' : '#ef4444')) : '#4b5563';
+        return '<span class="fb-acc-badge absolute bottom-0 right-0 px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1 opacity-100 group-hover:opacity-0 transition border-l-2 border-t-2 ' + badgeText + '" style="background:' + badgeColor + ';border-color:' + borderColor + '">' +
             (pct != null ? pct : '—') + '%</span>' + hoverOverlay;
     }
 
@@ -944,7 +944,7 @@
             const badgeTitle = targetNotes
                 ? ('Custom Tuning: ' + targetNotes)
                 : tuningLabel;
-            const pos = 'absolute top-2 ' + (state.selectMode ? 'left-9' : 'left-2');
+            const pos = 'absolute top-0 left-0 rounded-br-md';
             // Tag the chip with its offsets so decorateTuningChips() can colour it
             // green (matches your current tuning) / amber (needs a retune) after paint.
             // Also flag a bass-only song (every arrangement is a bass part) so coverage

From f358c2ea9fd361b3e374a1987359684df32a06dc Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:50:23 +0200
Subject: [PATCH 22/74] fix: omit tuning from hover overlay for non-pitched
 instruments (drums/keys)

---
 static/v3/songs.js | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index d542bcc5..2c4e213b 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -553,7 +553,10 @@
                 var aColor = aAcc != null
                     ? (aAcc >= MASTERY_ACCURACY ? 'text-fb-good' : aAcc >= 0.5 ? 'text-fb-mid' : 'text-fb-low')
                     : 'text-gray-600';
-                items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + ' &middot; ' + esc(songTuning) + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
+                // Only show tuning for pitched instruments (not drums/keys)
+                var isPitched = _isPitchedArrangement(aName);
+                var tuningPart = isPitched && songTuning ? ' &middot; ' + esc(songTuning) : '';
+                items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + tuningPart + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
             }
             hoverOverlay = '<div class="opacity-0 group-hover:opacity-100 transition" style="position:absolute;bottom:0;left:0;right:0;background:rgba(0,0,0,0.8);border-radius:0 0 0.5rem 0.5rem;z-index:20;pointer-events:none">' + items + '</div>';
         }
@@ -597,6 +600,25 @@
         return '●';
     }
 
+    function _isPitchedArrangement(arrName) {
+        var insts = window.feedBack && window.feedBack._instruments;
+        if (!Array.isArray(insts)) return true;  // unknown → assume pitched
+        var name = (arrName || '').toLowerCase();
+        for (var i = 0; i < insts.length; i++) {
+            var inst = insts[i];
+            var roles = inst.roles || [];
+            for (var j = 0; j < roles.length; j++) {
+                var r = roles[j];
+                if (name === r.label.toLowerCase()) return inst.detect_strategy === 'pitch';
+                var names = r.arrangement_names || [];
+                for (var k = 0; k < names.length; k++) {
+                    if (name === names[k]) return inst.detect_strategy === 'pitch';
+                }
+            }
+        }
+        return true;  // unknown → assume pitched
+    }
+
     // ── Metadata-refresh per-tile state (the "Refresh Metadata" batch) ─────────
     // A transient badge painted ONLY while a metadata refresh is running: the
     // songs actually being (re)matched animate queued → working → done. Keyed by

From fa412bef8ecddb944d9571d879ab4df477ad8a01 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:52:34 +0200
Subject: [PATCH 23/74] fix: remove double AND in arrangement_accuracy_map SQL

---
 lib/metadata_db.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/lib/metadata_db.py b/lib/metadata_db.py
index aa9d704b..c6b8cf4b 100644
--- a/lib/metadata_db.py
+++ b/lib/metadata_db.py
@@ -2237,8 +2237,7 @@ def arrangement_accuracy_map(self) -> dict:
         existing_filter = self._existing_song_filter().strip()
         rows = self.conn.execute(
             "SELECT filename, arrangement, best_accuracy FROM song_stats "
-            "WHERE plays > 0" +
-            (" AND " + existing_filter if existing_filter else "")
+            "WHERE plays > 0" + existing_filter
         ).fetchall()
         result: dict = {}
         for fn, arr, acc in rows:

From ad0ea79964937886193cd025f4b05d0895efdc17 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 00:54:00 +0200
Subject: [PATCH 24/74] fix: don't strip existing_song_filter - it starts with
 a space

---
 lib/metadata_db.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/metadata_db.py b/lib/metadata_db.py
index c6b8cf4b..840daf8e 100644
--- a/lib/metadata_db.py
+++ b/lib/metadata_db.py
@@ -2234,10 +2234,10 @@ def arrangement_accuracy_map(self) -> dict:
         badging on the library grid. Only includes arrangements that have been
         played (plays > 0); unplayed arrangements are absent from the map
         rather than zeroed so the UI can distinguish 'not played' from 0%."""
-        existing_filter = self._existing_song_filter().strip()
+        existing_filter = self._existing_song_filter()
         rows = self.conn.execute(
             "SELECT filename, arrangement, best_accuracy FROM song_stats "
-            "WHERE plays > 0" + existing_filter
+            "WHERE plays > 0 " + existing_filter
         ).fetchall()
         result: dict = {}
         for fn, arr, acc in rows:

From fac28d107d02a5129f7e1bf8efa55cfdfdda9ce5 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 12:50:37 +0200
Subject: [PATCH 25/74] fix: per-role mastery uses active role, not first
 matching arrangement

- badges.js exposes sm._activeInstrumentProfile on settings save
- _matchingArrangementIndex now resolves the active role label
  from the profile (e.g. 'Rhythm' when guitar-rhythm is active)
  and returns that arrangement's index for accuracy lookup.
- Falls back to first matching arrangement if role can't be resolved.
---
 static/v3/badges.js |  2 ++
 static/v3/songs.js  | 34 +++++++++++++++++++++++++++++++---
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index 17be6908..c62a7b53 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -274,6 +274,8 @@
         if (!accepted) return false;
         Object.assign(settings, patch);
         syncLocalProfilePatch(patch);
+        // Expose active profile so the library can resolve per-role accuracy.
+        if (sm) sm._activeInstrumentProfile = settings.active_instrument_profile;
         if (sm && sm.emit) sm.emit('instrument:changed', {
             instrument: settings.instrument, stringCount: settings.string_count, tuning: settings.tuning, pathway: settings.pathway,
         });
diff --git a/static/v3/songs.js b/static/v3/songs.js
index 2c4e213b..7ea66d7e 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -500,11 +500,39 @@
         // This is the arrangement the card would open for the current instrument.
         var want = state.filters.arr_has;
         if (!want.length) return null;
+        // Resolve the active role from the current instrument profile
+        // so we show mastery for the user's selected role (Lead/Rhythm).
+        var activeProfileId = (sm && sm._activeInstrumentProfile) || '';
+        var activeRoleLabel = null;
+        if (activeProfileId) {
+            var insts = window.feedBack && window.feedBack._instruments;
+            if (Array.isArray(insts)) {
+                for (var ii = 0; ii < insts.length; ii++) {
+                    var ir = insts[ii].roles || [];
+                    for (var ij = 0; ij < ir.length; ij++) {
+                        if (activeProfileId === insts[ii].id + '-' + ir[ij].id) {
+                            activeRoleLabel = ir[ij].label;
+                            break;
+                        }
+                    }
+                    if (activeRoleLabel) break;
+                }
+            }
+        }
+        // First pass: prefer arrangement matching the active role exactly.
+        if (activeRoleLabel) {
+            for (var i = 0; i < song.arrangements.length; i++) {
+                var a = song.arrangements[i];
+                var sn = a.smart_name || a.name || '';
+                if (sn === activeRoleLabel) return a.index != null ? a.index : i;
+            }
+        }
+        // Fallback: first arrangement matching any auto-filter value.
         for (var i = 0; i < song.arrangements.length; i++) {
-            var a = song.arrangements[i];
-            var sn = a.smart_name || a.name || '';
+            var a2 = song.arrangements[i];
+            var sn2 = a2.smart_name || a2.name || '';
             for (var j = 0; j < want.length; j++) {
-                if (sn === want[j]) return a.index != null ? a.index : i;
+                if (sn2 === want[j]) return a2.index != null ? a2.index : i;
             }
         }
         return null;

From c00002b82204f1e91f6bce87f5f342167d080d8a Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 13:09:19 +0200
Subject: [PATCH 26/74] fix: stats-recorder reads resolved arrangement from
 song:ready

When clicking a card (not an arrangement chip), playSong gets
undefined for arrangement. The song:loading event fires with
arrangement=null BEFORE the WebSocket resolves it via instrument
routing. Now song:ready reads the actual arrangement_index from
highway.getSongInfo() and updates cur.arrangement so scores are
attributed to the correct arrangement.
---
 static/v3/stats-recorder.js | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/static/v3/stats-recorder.js b/static/v3/stats-recorder.js
index cb252355..f9b4ba21 100644
--- a/static/v3/stats-recorder.js
+++ b/static/v3/stats-recorder.js
@@ -188,6 +188,19 @@
         // Arrangement switch restarts scoring — treat as a fresh session.
         reset(d.filename || (cur && cur.filename), d.arrangement == null ? 0 : Number(d.arrangement));
     });
+    // When the server auto-resolves the arrangement (e.g. instrument routing),
+    // the song:loading event fires with arrangement=null before the WebSocket
+    // connects. Once the song is ready, read the resolved arrangement from the
+    // highway's songInfo and update cur so scores are attributed correctly.
+    sm.on('song:ready', () => {
+        if (!cur) return;
+        var hw = window.highway;
+        if (!hw || typeof hw.getSongInfo !== 'function') return;
+        var info = hw.getSongInfo();
+        if (info && Number.isFinite(info.arrangement_index)) {
+            cur.arrangement = info.arrangement_index;
+        }
+    });
 
     // ── Per-note tally (from the note_detect plugin) ──────────────────────--
     sm.on('note:hit', () => {

From d317259753fd6af32a2b7283dec92a87162980e5 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 13:30:07 +0200
Subject: [PATCH 27/74] feat: preferred highway per instrument in settings,
 applied on instrument change

- Instruments settings tab now has a 'Preferred highway' dropdown
  listing all registered visualization plugins.
- Selection persisted to instrument_overrides.preferred_highway.
- On instrument change, reads preferred highway from settings and
  stores it in localStorage.vizSelection so the next song uses it.
- 'Auto (match arrangement)' is the default option.
---
 static/v3/badges.js               | 16 ++++++++++++
 static/v3/instruments-settings.js | 43 ++++++++++++++++++++++++++++++-
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index c62a7b53..b695d838 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -279,11 +279,27 @@
         if (sm && sm.emit) sm.emit('instrument:changed', {
             instrument: settings.instrument, stringCount: settings.string_count, tuning: settings.tuning, pathway: settings.pathway,
         });
+        // Apply preferred highway for this instrument if one is set.
+        _applyPreferredHighway(settings.instrument);
         pushToTuner();
         renderTuner(); // reflect new tuning on the tuner card
         return true;
     }
 
+    async function _applyPreferredHighway(instrumentId) {
+        try {
+            var r = await fetch('/api/settings');
+            if (!r.ok) return;
+            var s = await r.json();
+            var overrides = s.instrument_overrides || {};
+            var prefs = overrides[instrumentId] || {};
+            var hw = prefs.preferred_highway;
+            if (hw && typeof hw === 'string') {
+                localStorage.setItem('vizSelection', hw);
+            }
+        } catch (_) {}
+    }
+
     // Drive the tuner plugin's instrument + tuning from the selection.
     async function pushToTuner() {
         try {
diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index ac2e25c3..56ab1563 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -9,6 +9,7 @@
     var OVERRIDES_KEY = 'instrument_overrides';
     var _overrides = {};
     var _instruments = [];
+    var _vizPlugins = [];
     var _saveTimer = 0;
     var _openCards = {};  // instId -> bool, survives re-renders
 
@@ -99,6 +100,9 @@
                 html += _renderTunings(inst, over);
             }
 
+            // ── Preferred highway ───────────────────────
+            html += _renderHighwaySelect(inst, over);
+
             // ── Info row ───────────────────────────────
             html += '<div class="text-[0.625rem] text-fb-textDim flex flex-wrap gap-3 pb-2">' +
                 '<span>Ref: ' + esc(String(inst.reference_pitch)) + ' Hz</span>' +
@@ -176,6 +180,19 @@
         return html;
     }
 
+    function _renderHighwaySelect(inst, over) {
+        if (!_vizPlugins.length) return '';
+        var current = over.preferred_highway || '';
+        var opts = '<option value="">Auto (match arrangement)</option>';
+        for (var v = 0; v < _vizPlugins.length; v++) {
+            var vp = _vizPlugins[v];
+            opts += '<option value="' + esc(vp.id) + '"' + (vp.id === current ? ' selected' : '') + '>' + esc(vp.name) + '</option>';
+        }
+        return '<div class="mb-2" data-section="highway" data-inst="' + esc(inst.id) + '">' +
+            '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Preferred highway</div>' +
+            '<select data-highway="' + esc(inst.id) + '" class="bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-xs text-fb-text outline-none focus:border-fb-primary w-full">' + opts + '</select></div>';
+    }
+
     function _renderTunings(inst, over) {
         var html = '<div data-section="tunings" data-inst="' + esc(inst.id) + '">' +
             '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Tuning presets</div>';
@@ -217,7 +234,22 @@
                     if (std && entry.offsets && std.length === entry.offsets.length) {
                         for (var oi = 0; oi < entry.offsets.length; oi++) {
                             midis.push(std[oi] + entry.offsets[oi]);
-                        }
+        // Preferred highway
+        panel.querySelectorAll('[data-highway]').forEach(function (sel) {
+            sel.addEventListener('change', function () {
+                var instId = sel.getAttribute('data-highway');
+                var over = getOverrides(instId);
+                var val = sel.value;
+                if (val) {
+                    over.preferred_highway = val;
+                } else {
+                    delete over.preferred_highway;
+                }
+                saveOverridesDebounced();
+                renderInstruments();
+            });
+        });
+    }
                     }
                     var noteLabel = midis.length ? midis.map(function (m) { return midiToNote(m); }).join(' ') : '';
                     var offStr = entry.offsets ? entry.offsets.map(function (o) { return (o >= 0 ? '+' : '') + o; }).join(',') : '';
@@ -375,6 +407,15 @@
             if (r.ok) _instruments = await r.json();
         } catch (_) {}
 
+        // Load visualization plugins for highway dropdown
+        try {
+            var pr = await fetch('/api/plugins');
+            if (pr.ok) {
+                var plugins = await pr.json();
+                _vizPlugins = plugins.filter(function (p) { return p.type === 'visualization'; });
+            }
+        } catch (_) {}
+
         try {
             var sr = await fetch('/api/settings');
             if (sr.ok) {

From 01edf33fff3224fafc90768acbe498387b61329b Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 14:21:19 +0200
Subject: [PATCH 28/74] debug: add console.error logging to
 instruments-settings load function

---
 static/v3/instruments-settings.js | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index 56ab1563..66ddce6b 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -405,16 +405,18 @@
         try {
             var r = await fetch('/api/instruments');
             if (r.ok) _instruments = await r.json();
-        } catch (_) {}
+        } catch (e) { console.error('instruments-settings: failed to load instruments', e); }
 
         // Load visualization plugins for highway dropdown
         try {
             var pr = await fetch('/api/plugins');
             if (pr.ok) {
                 var plugins = await pr.json();
-                _vizPlugins = plugins.filter(function (p) { return p.type === 'visualization'; });
+                if (Array.isArray(plugins)) {
+                    _vizPlugins = plugins.filter(function (p) { return p.type === 'visualization'; });
+                }
             }
-        } catch (_) {}
+        } catch (e) { console.error('instruments-settings: failed to load plugins', e); }
 
         try {
             var sr = await fetch('/api/settings');
@@ -424,7 +426,7 @@
                     _overrides = s[OVERRIDES_KEY];
                 }
             }
-        } catch (_) {}
+        } catch (e) { console.error('instruments-settings: failed to load settings', e); }
 
         renderInstruments();
     }

From 4c2a3b1e7417f3bfec98f965850ff2e78fb09254 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 14:27:42 +0200
Subject: [PATCH 29/74] debug: add sync test panel update, console.log in
 load()

---
 static/v3/instruments-settings.js | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index 66ddce6b..7ae5117b 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -402,6 +402,7 @@
     }
 
     async function load() {
+        console.log('instruments-settings: load() started');
         try {
             var r = await fetch('/api/instruments');
             if (r.ok) _instruments = await r.json();
@@ -431,6 +432,13 @@
         renderInstruments();
     }
 
+    // Sync test: update the panel IMMEDIATELY at script load time so we can
+    // distinguish "script not loaded" from "async fetch failed".
+    (function () {
+        var panel = document.getElementById(PANEL_ID);
+        if (panel) panel.innerHTML = '<div class="text-fb-textDim text-sm px-1">Fetching data…</div>';
+    })();
+
     if (document.readyState === 'loading') {
         document.addEventListener('DOMContentLoaded', load);
     } else {

From c789e3736fafc766b64e8b9881423d0a8e930aa2 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 14:30:13 +0200
Subject: [PATCH 30/74] debug: verbose logging in load(), safe wrapper for
 highway select

---
 static/v3/instruments-settings.js | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index 7ae5117b..d510879a 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -101,7 +101,7 @@
             }
 
             // ── Preferred highway ───────────────────────
-            html += _renderHighwaySelect(inst, over);
+            html += (_renderHighwaySelectSafe(inst, over));
 
             // ── Info row ───────────────────────────────
             html += '<div class="text-[0.625rem] text-fb-textDim flex flex-wrap gap-3 pb-2">' +
@@ -180,6 +180,10 @@
         return html;
     }
 
+    function _renderHighwaySelectSafe(inst, over) {
+        try { return _renderHighwaySelect(inst, over); } catch (e) { console.error('highway select error', e); return ''; }
+    }
+
     function _renderHighwaySelect(inst, over) {
         if (!_vizPlugins.length) return '';
         var current = over.preferred_highway || '';
@@ -406,19 +410,25 @@
         try {
             var r = await fetch('/api/instruments');
             if (r.ok) _instruments = await r.json();
-        } catch (e) { console.error('instruments-settings: failed to load instruments', e); }
+            console.log('instruments-settings: instruments loaded, count=' + _instruments.length);
+        } catch (e) { console.error('instruments-settings: instruments failed', e); }
 
-        // Load visualization plugins for highway dropdown
+        console.log('instruments-settings: loading plugins...');
         try {
             var pr = await fetch('/api/plugins');
             if (pr.ok) {
                 var plugins = await pr.json();
+                console.log('instruments-settings: plugins loaded, count=' + (Array.isArray(plugins) ? plugins.length : 'not array'));
                 if (Array.isArray(plugins)) {
                     _vizPlugins = plugins.filter(function (p) { return p.type === 'visualization'; });
+                    console.log('instruments-settings: viz plugins count=' + _vizPlugins.length);
                 }
+            } else {
+                console.error('instruments-settings: plugins fetch not ok ' + pr.status);
             }
-        } catch (e) { console.error('instruments-settings: failed to load plugins', e); }
+        } catch (e) { console.error('instruments-settings: plugins failed', e); }
 
+        console.log('instruments-settings: loading settings...');
         try {
             var sr = await fetch('/api/settings');
             if (sr.ok) {
@@ -426,10 +436,15 @@
                 if (s[OVERRIDES_KEY] && typeof s[OVERRIDES_KEY] === 'object') {
                     _overrides = s[OVERRIDES_KEY];
                 }
+                console.log('instruments-settings: settings loaded');
             }
-        } catch (e) { console.error('instruments-settings: failed to load settings', e); }
+        } catch (e) { console.error('instruments-settings: settings failed', e); }
 
-        renderInstruments();
+        console.log('instruments-settings: calling renderInstruments()');
+        try {
+            renderInstruments();
+            console.log('instruments-settings: renderInstruments() done');
+        } catch (e) { console.error('instruments-settings: renderInstruments() crashed', e); }
     }
 
     // Sync test: update the panel IMMEDIATELY at script load time so we can

From 8a5cdf77970245adc5311892541900a752c4a89a Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 14:32:47 +0200
Subject: [PATCH 31/74] =?UTF-8?q?fix:=20highway=20wiring=20was=20inserted?=
 =?UTF-8?q?=20inside=20=5FrenderTunings=20=E2=80=94=20moved=20to=20=5Fwire?=
 =?UTF-8?q?Events?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 static/v3/instruments-settings.js | 33 ++++++++++++++++---------------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index d510879a..bce3bc9e 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -238,22 +238,8 @@
                     if (std && entry.offsets && std.length === entry.offsets.length) {
                         for (var oi = 0; oi < entry.offsets.length; oi++) {
                             midis.push(std[oi] + entry.offsets[oi]);
-        // Preferred highway
-        panel.querySelectorAll('[data-highway]').forEach(function (sel) {
-            sel.addEventListener('change', function () {
-                var instId = sel.getAttribute('data-highway');
-                var over = getOverrides(instId);
-                var val = sel.value;
-                if (val) {
-                    over.preferred_highway = val;
-                } else {
-                    delete over.preferred_highway;
-                }
-                saveOverridesDebounced();
-                renderInstruments();
-            });
-        });
-    }
+                            }
+                        }
                     }
                     var noteLabel = midis.length ? midis.map(function (m) { return midiToNote(m); }).join(' ') : '';
                     var offStr = entry.offsets ? entry.offsets.map(function (o) { return (o >= 0 ? '+' : '') + o; }).join(',') : '';
@@ -403,6 +389,21 @@
                 renderInstruments();
             });
         });
+        // Preferred highway
+        panel.querySelectorAll('[data-highway]').forEach(function (sel) {
+            sel.addEventListener('change', function () {
+                var instId = sel.getAttribute('data-highway');
+                var over = getOverrides(instId);
+                var val = sel.value;
+                if (val) {
+                    over.preferred_highway = val;
+                } else {
+                    delete over.preferred_highway;
+                }
+                saveOverridesDebounced();
+                renderInstruments();
+            });
+        });
     }
 
     async function load() {

From 6d02cd76e6319e1f94c62b46f8a5f9e660ee6999 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 14:37:03 +0200
Subject: [PATCH 32/74] fix: remove orphaned closing brace left from misplaced
 highway code

---
 static/v3/instruments-settings.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index bce3bc9e..d334298b 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -260,7 +260,6 @@
                 '<input type="text" data-add-tuning-offsets="' + esc(inst.id) + '" data-sc="' + esc(scKey) + '" placeholder="Offsets e.g. 0,0,0,0,0,0" class="bg-gray-800/50 border border-gray-700 rounded-md px-1.5 py-0.5 text-[0.625rem] text-fb-text outline-none w-44 focus:border-fb-primary font-mono">' +
                 '<button type="button" data-add-tuning-btn="' + esc(inst.id) + '" data-sc="' + esc(scKey) + '" class="bg-fb-primary/20 hover:bg-fb-primary/30 text-fb-primary text-[0.625rem] px-1.5 py-0.5 rounded-md transition">Add</button>' +
                 '</div></div>';
-        }
 
         html += '</div>';
         return html;

From 7429e37b0c0e7112725a127148a0c9601c5c894f Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 14:41:56 +0200
Subject: [PATCH 33/74] fix: restore instruments-settings.js from working
 version, re-add highway cleanly

---
 static/v3/instruments-settings.js | 81 ++++++++++---------------------
 1 file changed, 25 insertions(+), 56 deletions(-)

diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index d334298b..32f5115b 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -1,4 +1,4 @@
-// Instruments settings tab — renders collapsible instrument cards from
+// Instruments settings tab ΓÇö renders collapsible instrument cards from
 // GET /api/instruments, with editable custom tunings and arrangement patterns.
 // User overrides are persisted to config.json via POST /api/settings under
 // the "instrument_overrides" key so they survive restarts.
@@ -74,7 +74,7 @@
 
             html += '<div id="' + id + '" class="' + (isOpen ? '' : 'hidden') + ' space-y-4 pl-4 border-l-2 border-fb-border/30">';
 
-            // ── Roles ──────────────────────────────────
+            // ΓöÇΓöÇ Roles ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             if (inst.roles && inst.roles.length) {
                 html += '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Roles</div>' +
                     '<div class="flex flex-wrap gap-1">';
@@ -87,23 +87,32 @@
                 html += '</div></div>';
             }
 
-            // ── Arrangement name patterns (editable) ────
+            // ΓöÇΓöÇ Arrangement name patterns (editable) ΓöÇΓöÇΓöÇΓöÇ
             html += _renderEditableNames(inst, over);
 
-            // ── String counts (stringed, editable) ─────
+            // ΓöÇΓöÇ String counts (stringed, editable) ΓöÇΓöÇΓöÇΓöÇΓöÇ
             if (isStringed) {
                 html += _renderEditableStringCounts(inst, over);
             }
 
-            // ── Custom tunings (stringed, editable) ────
+            // ΓöÇΓöÇ Custom tunings (stringed, editable) ΓöÇΓöÇΓöÇΓöÇ
             if (isStringed) {
                 html += _renderTunings(inst, over);
             }
 
-            // ── Preferred highway ───────────────────────
-            html += (_renderHighwaySelectSafe(inst, over));
+            // Preferred highway
+            if (_vizPlugins.length) {
+                var hwCurrent = over.preferred_highway || '';
+                html += '<div class="mb-2"><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Preferred highway</div>' +
+                    '<select data-highway="' + esc(inst.id) + '" class="bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-xs text-fb-text outline-none focus:border-fb-primary w-full">' +
+                    '<option value="">Auto (match arrangement)</option>';
+                for (var v = 0; v < _vizPlugins.length; v++) {
+                    var vp = _vizPlugins[v];
+                    html += '<option value="' + esc(vp.id) + '"' + (vp.id === hwCurrent ? ' selected' : '') + '>' + esc(vp.name) + '</option>';
+                }
+                html += '</select></div>';
+            }
 
-            // ── Info row ───────────────────────────────
             html += '<div class="text-[0.625rem] text-fb-textDim flex flex-wrap gap-3 pb-2">' +
                 '<span>Ref: ' + esc(String(inst.reference_pitch)) + ' Hz</span>' +
                 '<span>Detect: ' + esc(inst.detect_strategy) + '</span>' +
@@ -142,7 +151,7 @@
                     ? '<button type="button" data-remove-name="' + esc(item.name) + '" data-inst="' + esc(inst.id) + '" class="ml-1 text-red-400 hover:text-red-300 text-[0.625rem]" title="Remove">&times;</button>'
                     : '';
                 html += '<span class="text-xs bg-gray-800/50 border ' + (item.source === 'user' ? 'border-green-700/50' : 'border-gray-700') + ' rounded-md px-2 py-0.5">' +
-                    esc(item.name) + ' <span class="text-fb-textDim text-[0.625rem]">→ ' + esc(item.role) + '</span>' + removeBtn +
+                    esc(item.name) + ' <span class="text-fb-textDim text-[0.625rem]">→ ' + esc(item.role) + '</span>' + removeBtn +
                     '</span>';
             }
             html += '</div>';
@@ -180,23 +189,6 @@
         return html;
     }
 
-    function _renderHighwaySelectSafe(inst, over) {
-        try { return _renderHighwaySelect(inst, over); } catch (e) { console.error('highway select error', e); return ''; }
-    }
-
-    function _renderHighwaySelect(inst, over) {
-        if (!_vizPlugins.length) return '';
-        var current = over.preferred_highway || '';
-        var opts = '<option value="">Auto (match arrangement)</option>';
-        for (var v = 0; v < _vizPlugins.length; v++) {
-            var vp = _vizPlugins[v];
-            opts += '<option value="' + esc(vp.id) + '"' + (vp.id === current ? ' selected' : '') + '>' + esc(vp.name) + '</option>';
-        }
-        return '<div class="mb-2" data-section="highway" data-inst="' + esc(inst.id) + '">' +
-            '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Preferred highway</div>' +
-            '<select data-highway="' + esc(inst.id) + '" class="bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-xs text-fb-text outline-none focus:border-fb-primary w-full">' + opts + '</select></div>';
-    }
-
     function _renderTunings(inst, over) {
         var html = '<div data-section="tunings" data-inst="' + esc(inst.id) + '">' +
             '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Tuning presets</div>';
@@ -238,7 +230,6 @@
                     if (std && entry.offsets && std.length === entry.offsets.length) {
                         for (var oi = 0; oi < entry.offsets.length; oi++) {
                             midis.push(std[oi] + entry.offsets[oi]);
-                            }
                         }
                     }
                     var noteLabel = midis.length ? midis.map(function (m) { return midiToNote(m); }).join(' ') : '';
@@ -260,6 +251,7 @@
                 '<input type="text" data-add-tuning-offsets="' + esc(inst.id) + '" data-sc="' + esc(scKey) + '" placeholder="Offsets e.g. 0,0,0,0,0,0" class="bg-gray-800/50 border border-gray-700 rounded-md px-1.5 py-0.5 text-[0.625rem] text-fb-text outline-none w-44 focus:border-fb-primary font-mono">' +
                 '<button type="button" data-add-tuning-btn="' + esc(inst.id) + '" data-sc="' + esc(scKey) + '" class="bg-fb-primary/20 hover:bg-fb-primary/30 text-fb-primary text-[0.625rem] px-1.5 py-0.5 rounded-md transition">Add</button>' +
                 '</div></div>';
+        }
 
         html += '</div>';
         return html;
@@ -394,11 +386,8 @@
                 var instId = sel.getAttribute('data-highway');
                 var over = getOverrides(instId);
                 var val = sel.value;
-                if (val) {
-                    over.preferred_highway = val;
-                } else {
-                    delete over.preferred_highway;
-                }
+                if (val) { over.preferred_highway = val; }
+                else { delete over.preferred_highway; }
                 saveOverridesDebounced();
                 renderInstruments();
             });
@@ -406,29 +395,21 @@
     }
 
     async function load() {
-        console.log('instruments-settings: load() started');
         try {
             var r = await fetch('/api/instruments');
             if (r.ok) _instruments = await r.json();
-            console.log('instruments-settings: instruments loaded, count=' + _instruments.length);
-        } catch (e) { console.error('instruments-settings: instruments failed', e); }
+        } catch (_) {}
 
-        console.log('instruments-settings: loading plugins...');
         try {
             var pr = await fetch('/api/plugins');
             if (pr.ok) {
                 var plugins = await pr.json();
-                console.log('instruments-settings: plugins loaded, count=' + (Array.isArray(plugins) ? plugins.length : 'not array'));
                 if (Array.isArray(plugins)) {
                     _vizPlugins = plugins.filter(function (p) { return p.type === 'visualization'; });
-                    console.log('instruments-settings: viz plugins count=' + _vizPlugins.length);
                 }
-            } else {
-                console.error('instruments-settings: plugins fetch not ok ' + pr.status);
             }
-        } catch (e) { console.error('instruments-settings: plugins failed', e); }
+        } catch (_) {}
 
-        console.log('instruments-settings: loading settings...');
         try {
             var sr = await fetch('/api/settings');
             if (sr.ok) {
@@ -436,24 +417,12 @@
                 if (s[OVERRIDES_KEY] && typeof s[OVERRIDES_KEY] === 'object') {
                     _overrides = s[OVERRIDES_KEY];
                 }
-                console.log('instruments-settings: settings loaded');
             }
-        } catch (e) { console.error('instruments-settings: settings failed', e); }
+        } catch (_) {}
 
-        console.log('instruments-settings: calling renderInstruments()');
-        try {
-            renderInstruments();
-            console.log('instruments-settings: renderInstruments() done');
-        } catch (e) { console.error('instruments-settings: renderInstruments() crashed', e); }
+        renderInstruments();
     }
 
-    // Sync test: update the panel IMMEDIATELY at script load time so we can
-    // distinguish "script not loaded" from "async fetch failed".
-    (function () {
-        var panel = document.getElementById(PANEL_ID);
-        if (panel) panel.innerHTML = '<div class="text-fb-textDim text-sm px-1">Fetching data…</div>';
-    })();
-
     if (document.readyState === 'loading') {
         document.addEventListener('DOMContentLoaded', load);
     } else {

From e56428694d41381bceb3f211b797f4b4387d1964 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 14:51:38 +0200
Subject: [PATCH 34/74] fix: preferred highway now updates DOM picker, dropdown
 includes venue/default/auto

- _applyPreferredHighway now updates the #viz-picker select element
  directly so song:ready picks up the change immediately (not just
  on next startup).
- Instruments dropdown now always shows Auto, Built-in 2D Highway,
  and Venue options alongside visualization plugins.
---
 static/v3/badges.js               | 17 +++++++++++++++++
 static/v3/instruments-settings.js |  6 ++++--
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index b695d838..218756b8 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -296,6 +296,23 @@
             var hw = prefs.preferred_highway;
             if (hw && typeof hw === 'string') {
                 localStorage.setItem('vizSelection', hw);
+                // Also update the picker DOM so it takes effect immediately
+                // (the song:ready handler reads sel.value, not localStorage).
+                var sel = document.getElementById('viz-picker');
+                if (sel) {
+                    var found = false;
+                    for (var i = 0; i < sel.options.length; i++) {
+                        if (sel.options[i].value === hw) { sel.value = hw; found = true; break; }
+                    }
+                    // If not in the picker yet (plugins still loading), add a
+                    // temporary option so song:ready picks it up.
+                    if (!found && hw) {
+                        var opt = document.createElement('option');
+                        opt.value = hw;
+                        opt.selected = true;
+                        sel.appendChild(opt);
+                    }
+                }
             }
         } catch (_) {}
     }
diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index 32f5115b..0fcd6e42 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -101,11 +101,13 @@
             }
 
             // Preferred highway
-            if (_vizPlugins.length) {
+            {
                 var hwCurrent = over.preferred_highway || '';
                 html += '<div class="mb-2"><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Preferred highway</div>' +
                     '<select data-highway="' + esc(inst.id) + '" class="bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-xs text-fb-text outline-none focus:border-fb-primary w-full">' +
-                    '<option value="">Auto (match arrangement)</option>';
+                    '<option value="">Auto (match arrangement)</option>' +
+                    '<option value="default"' + (hwCurrent === 'default' ? ' selected' : '') + '>Built-in 2D Highway</option>' +
+                    '<option value="venue"' + (hwCurrent === 'venue' ? ' selected' : '') + '>Venue</option>';
                 for (var v = 0; v < _vizPlugins.length; v++) {
                     var vp = _vizPlugins[v];
                     html += '<option value="' + esc(vp.id) + '"' + (vp.id === hwCurrent ? ' selected' : '') + '>' + esc(vp.name) + '</option>';

From e090f96854d63c2f50bf86cbf6518ae1bfc82432 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 15:30:59 +0200
Subject: [PATCH 35/74] fix: call window.setViz() directly instead of just
 updating picker DOM

- setViz is on window via Object.assign in app.js
- This actually installs the renderer, not just the picker value
---
 static/v3/badges.js | 21 ++-------------------
 1 file changed, 2 insertions(+), 19 deletions(-)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index 218756b8..93a8d3cd 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -294,25 +294,8 @@
             var overrides = s.instrument_overrides || {};
             var prefs = overrides[instrumentId] || {};
             var hw = prefs.preferred_highway;
-            if (hw && typeof hw === 'string') {
-                localStorage.setItem('vizSelection', hw);
-                // Also update the picker DOM so it takes effect immediately
-                // (the song:ready handler reads sel.value, not localStorage).
-                var sel = document.getElementById('viz-picker');
-                if (sel) {
-                    var found = false;
-                    for (var i = 0; i < sel.options.length; i++) {
-                        if (sel.options[i].value === hw) { sel.value = hw; found = true; break; }
-                    }
-                    // If not in the picker yet (plugins still loading), add a
-                    // temporary option so song:ready picks it up.
-                    if (!found && hw) {
-                        var opt = document.createElement('option');
-                        opt.value = hw;
-                        opt.selected = true;
-                        sel.appendChild(opt);
-                    }
-                }
+            if (hw && typeof hw === 'string' && typeof window.setViz === 'function') {
+                window.setViz(hw);
             }
         } catch (_) {}
     }

From 3a6a45f09d34722d914292bc8c2c1978c03c5f69 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 15:35:49 +0200
Subject: [PATCH 36/74] fix: song:ready applies non-auto viz, preferred highway
 sets picker value

- song:ready now calls setViz(sel.value) for any non-auto,
  non-default picker value, so renderers set from the library page
  (e.g. per-instrument preferred highway) are applied on song start.
- _applyPreferredHighway just updates localStorage + picker DOM;
  the renderer install happens on the next song:ready.
---
 static/app.js       | 17 ++++++-----------
 static/v3/badges.js | 14 ++++++++++++--
 2 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/static/app.js b/static/app.js
index 8d606083..b93779ec 100644
--- a/static/app.js
+++ b/static/app.js
@@ -1557,23 +1557,18 @@ if (window.feedBack) {
     // handler receives an Event, not the raw payload.
     window.feedBack.on('song:ready', (e) => {
         _applyMasteryAvailability(!!e.detail?.hasPhraseData);
-        // Auto mode: re-evaluate the active renderer against the
-        // newly-loaded song. The picker's current <option> value is the
-        // source of truth here — localStorage is a persistence mirror
-        // that can throw in private / sandboxed contexts, and the
-        // picker already reflects fresh-install / post-cleanup
-        // fallthroughs to 'auto' even when writes failed.
         const sel = document.getElementById('viz-picker');
         if (sel && sel.value === 'auto') {
             _autoMatchViz();
+        } else if (sel && sel.value !== 'default') {
+            // Non-auto explicit selection: ensure the renderer is installed.
+            // This covers the case where the preference was changed while on
+            // the library page (e.g. per-instrument preferred highway) where
+            // setViz couldn't install the renderer because no highway existed.
+            setViz(sel.value);
         } else if (sel) {
-            // Explicit selection: the renderer persists across songs, so a
-            // notation-only arrangement landing on a non-notation viz (e.g.
-            // the fresh-install highway_3d default) would render an empty
-            // board with no explanation. Surface the install hint.
             _maybeShowNotationViewHint(sel.value);
         }
-    });
 }
 
 
diff --git a/static/v3/badges.js b/static/v3/badges.js
index 93a8d3cd..c953de24 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -294,8 +294,18 @@
             var overrides = s.instrument_overrides || {};
             var prefs = overrides[instrumentId] || {};
             var hw = prefs.preferred_highway;
-            if (hw && typeof hw === 'string' && typeof window.setViz === 'function') {
-                window.setViz(hw);
+            if (hw && typeof hw === 'string') {
+                localStorage.setItem('vizSelection', hw);
+                var sel = document.getElementById('viz-picker');
+                if (sel) {
+                    for (var i = 0; i < sel.options.length; i++) {
+                        if (sel.options[i].value === hw) { sel.value = hw; return; }
+                    }
+                    var opt = document.createElement('option');
+                    opt.value = hw;
+                    opt.selected = true;
+                    sel.appendChild(opt);
+                }
             }
         } catch (_) {}
     }

From 0cdfe1172376a4fab45da6d3f8d77932ea6ff61c Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 15:40:22 +0200
Subject: [PATCH 37/74] fix: don't fall back to song-wide max % when
 auto-filter is active
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a specific role is selected but the song has no matching
arrangement, show '— %' instead of attributing a different role's
score to the current role.
---
 static/v3/songs.js | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 7ea66d7e..7c032b03 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -554,8 +554,11 @@
         if (arrIdx != null) {
             acc = _perArrangementAccuracy(filename, arrIdx);
         }
-        // Fall back to song-wide max when no per-role match.
-        if (acc == null) acc = state.accuracy[filename];
+        // Fall back to song-wide max only when no auto-filter is active.
+        // When a specific role is selected but the song has no matching
+        // arrangement, show nothing instead of attributing a different
+        // role's score.
+        if (acc == null && !state.filters.arr_has.length) acc = state.accuracy[filename];
         var hasArr = song && song.arrangements && song.arrangements.length > 0;
         // Show badge when we have accuracy OR the song has arrangements
         // (so the hover overlay works even for unplayed songs).

From a1d9c84ed417c6222a953aa5812de63d3c690d4b Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 15:47:59 +0200
Subject: [PATCH 38/74] fix: restore missing }); closing for song:ready handler

---
 static/app.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/static/app.js b/static/app.js
index b93779ec..ef4ae78d 100644
--- a/static/app.js
+++ b/static/app.js
@@ -1569,6 +1569,7 @@ if (window.feedBack) {
         } else if (sel) {
             _maybeShowNotationViewHint(sel.value);
         }
+    });
 }
 
 

From 29c5ad08c27fb5c8ad1fb709217a2088c93b866a Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 15:49:52 +0200
Subject: [PATCH 39/74] =?UTF-8?q?fix:=20show=20'n/a'=20instead=20of=20'?=
 =?UTF-8?q?=E2=80=94=20%'=20for=20no-matching-arrangement=20badge?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 static/v3/songs.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 7c032b03..e1bfb8a9 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -597,7 +597,7 @@
         var badgeText = acc != null && acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
         var borderColor = acc != null ? (acc >= MASTERY_ACCURACY ? '#22c55e' : (acc >= 0.5 ? '#eab308' : '#ef4444')) : '#4b5563';
         return '<span class="fb-acc-badge absolute bottom-0 right-0 px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1 opacity-100 group-hover:opacity-0 transition border-l-2 border-t-2 ' + badgeText + '" style="background:' + badgeColor + ';border-color:' + borderColor + '">' +
-            (pct != null ? pct : '—') + '%</span>' + hoverOverlay;
+            (pct != null ? pct : 'n/a') + '</span>' + hoverOverlay;
     }
 
     function _roleIcon(arrName) {

From 420d8077b396429d478e1fecc3154267b7b2bb2a Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 15:53:02 +0200
Subject: [PATCH 40/74] =?UTF-8?q?fix:=20show=20'n/a'=20when=20no=20matchin?=
 =?UTF-8?q?g=20arrangement,=20'=E2=80=94=20%'=20when=20unplayed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 'n/a' when the selected role has no arrangement in the song
- '— %' when the arrangement exists but hasn't been scored yet
- '95%' when scored
---
 static/v3/songs.js | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index e1bfb8a9..53c65871 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -551,23 +551,29 @@
         // role filter, and use ITS accuracy rather than the song-wide max.
         var acc = null;
         var arrIdx = song ? _matchingArrangementIndex(song) : null;
-        if (arrIdx != null) {
+        var hasMatchingArrangement = arrIdx != null;
+        if (hasMatchingArrangement) {
             acc = _perArrangementAccuracy(filename, arrIdx);
         }
         // Fall back to song-wide max only when no auto-filter is active.
-        // When a specific role is selected but the song has no matching
-        // arrangement, show nothing instead of attributing a different
-        // role's score.
         if (acc == null && !state.filters.arr_has.length) acc = state.accuracy[filename];
         var hasArr = song && song.arrangements && song.arrangements.length > 0;
-        // Show badge when we have accuracy OR the song has arrangements
-        // (so the hover overlay works even for unplayed songs).
         if (acc == null && !hasArr) return '';
 
         var pct = acc != null ? Math.floor(acc * 100) : null;
+        // Display: "n/a" when the selected role has no arrangement in this song;
+        // "— %" when the arrangement exists but hasn't been played yet.
+        var displayLabel;
+        if (pct != null) {
+            displayLabel = pct + '%';
+        } else if (_arrAutoInstrument && !hasMatchingArrangement) {
+            displayLabel = 'n/a';
+        } else {
+            displayLabel = '— %';
+        }
         if (variant === 'tree') {
             var color = acc != null && acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc != null && acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
-            return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + (pct != null ? pct : '—') + '%</span>';
+            return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + displayLabel + '</span>';
         }
 
         // Build hover overlay with all arrangement accuracies
@@ -597,7 +603,7 @@
         var badgeText = acc != null && acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
         var borderColor = acc != null ? (acc >= MASTERY_ACCURACY ? '#22c55e' : (acc >= 0.5 ? '#eab308' : '#ef4444')) : '#4b5563';
         return '<span class="fb-acc-badge absolute bottom-0 right-0 px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1 opacity-100 group-hover:opacity-0 transition border-l-2 border-t-2 ' + badgeText + '" style="background:' + badgeColor + ';border-color:' + borderColor + '">' +
-            (pct != null ? pct : 'n/a') + '</span>' + hoverOverlay;
+            displayLabel + '</span>' + hoverOverlay;
     }
 
     function _roleIcon(arrName) {

From 3a3ecc2713e50c9d342935bd4be02ecc6901a032 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 15:56:36 +0200
Subject: [PATCH 41/74] fix: expose active instrument profile on initial
 loadSettings too

sm._activeInstrumentProfile was only set on saveSettings (when user
changes settings) but not on initial loadSettings. This meant
_matchingArrangementIndex couldn't resolve the active role on first
page load, falling back to the first match (Lead). Now set on both.
---
 static/v3/badges.js | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/static/v3/badges.js b/static/v3/badges.js
index c953de24..e938a62e 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -239,6 +239,9 @@
                     instrument_profiles: profiles,
                     active_instrument_profile: typeof s.active_instrument_profile === 'string' ? s.active_instrument_profile : profileIdForInstrument(instrument),
                 };
+                // Expose active profile on initial load too, so the library can
+                // resolve per-role accuracy from first paint.
+                if (sm) sm._activeInstrumentProfile = settings.active_instrument_profile;
             }
         } catch (e) { /* settings endpoint always present */ }
     }

From eac9f8e0966e3a968fe0ebe085f7f1d55effcb34 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 15:59:14 +0200
Subject: [PATCH 42/74] fix: return null from _matchingArrangementIndex when
 active role has no match
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a specific role is selected (e.g. Rhythm) but the song only has
Lead, don't fall back to Lead — return null so the badge shows 'n/a'.
---
 static/v3/songs.js | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 53c65871..d6e51a54 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -526,6 +526,9 @@
                 var sn = a.smart_name || a.name || '';
                 if (sn === activeRoleLabel) return a.index != null ? a.index : i;
             }
+            // Active role selected but no matching arrangement — return null
+            // so the badge shows "n/a" instead of falling back to a different role.
+            return null;
         }
         // Fallback: first arrangement matching any auto-filter value.
         for (var i = 0; i < song.arrangements.length; i++) {

From 082db902123a3a45e10b9a7a7f3c1af2ed600c46 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 16:04:14 +0200
Subject: [PATCH 43/74] fix: expand arrangement filter allowlist with
 registry-derived names

_ALLOWED_ARRANGEMENT_NAMES was hardcoded to {Lead,Rhythm,Bass,Combo},
so filters for Keys/Drums were silently dropped server-side.
Now queries the instrument registry at filter time to accept role
labels from any registered instrument.
---
 lib/metadata_db.py | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/lib/metadata_db.py b/lib/metadata_db.py
index 840daf8e..69cbdf22 100644
--- a/lib/metadata_db.py
+++ b/lib/metadata_db.py
@@ -3309,6 +3309,21 @@ def _estd_set(self) -> set[str]:
     # parameters are bound, but capping the input space is still cheap
     # defense-in-depth (see feedBack#129).
     _ALLOWED_ARRANGEMENT_NAMES = {"Lead", "Rhythm", "Bass", "Combo"}
+
+    def _registry_arrangement_names(self) -> set:
+        """Arrangement names from registered instruments (Drums, Keys, etc.),
+        to supplement the hardcoded _ALLOWED_ARRANGEMENT_NAMES set."""
+        import appstate
+        reg = getattr(appstate, "instrument_registry", None)
+        if not reg:
+            return set()
+        names = set()
+        for inst in reg.get_all():
+            for role in inst.get("roles", []):
+                label = role.get("label")
+                if label:
+                    names.add(label)
+        return names
     # Per-smart-type list of (sql_op, sql_param) pairs appended to the SQL
     # name-fallback branch (key-absent smart_name). Covers legacy raw names
     # and load_song()'s synthesised display names that map to each smart type.
@@ -3490,7 +3505,9 @@ def _build_intrinsic_where(self, alias: str, format_filter: str = "",
         # ('Lead', 'Alt. Lead', 'Alt. Lead N', 'Bonus Lead', 'Bonus Lead N').
         # Falls back to matching `name` for older rows without smart_name.
         # Legacy mode: matches `name` directly (original behaviour).
-        arr_has = [a for a in (arrangements_has or []) if a in self._ALLOWED_ARRANGEMENT_NAMES]
+        arr_has = [a for a in (arrangements_has or [])
+                     if a in self._ALLOWED_ARRANGEMENT_NAMES
+                     or a in self._registry_arrangement_names()]
         if arr_has and naming_mode == "smart":
             # Smart mode subsumes "Combo" into "Lead" — normalize here so a
             # hand-rolled API client matches the client-side behaviour and
@@ -3541,7 +3558,9 @@ def _build_intrinsic_where(self, alias: str, format_filter: str = "",
                 where += (f" AND EXISTS (SELECT 1 FROM json_each({alias}.arrangements) "
                           f"WHERE json_extract(value, '$.name') IN ({placeholders}))")
                 params += arr_has
-        arr_lacks = [a for a in (arrangements_lacks or []) if a in self._ALLOWED_ARRANGEMENT_NAMES]
+        arr_lacks = [a for a in (arrangements_lacks or [])
+                      if a in self._ALLOWED_ARRANGEMENT_NAMES
+                      or a in self._registry_arrangement_names()]
         if arr_lacks and naming_mode == "smart":
             arr_lacks = list(dict.fromkeys("Lead" if a == "Combo" else a for a in arr_lacks))
         if arr_lacks:

From 3e6bc31177c0924a25dd25c90df17cb9160f5cfb Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 16:15:23 +0200
Subject: [PATCH 44/74] docs: add module/class docstrings, fix file headers to
 match conventions

- lib/instruments.py: module docstring, class docstring for InstrumentRegistry
- lib/routers/instruments.py: module docstring matching existing router pattern
- static/v3/instruments-settings.js: expanded file header, fixed encoding
- Verified no print() calls in any modified Python files
- All naming follows CLAUDE.md: snake_case plugins, camelCase JS, flat imports
---
 lib/instruments.py                | 25 +++++++++++++++++++++++++
 lib/routers/instruments.py        |  6 ++++++
 static/v3/instruments-settings.js | 15 +++++++++++----
 3 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/lib/instruments.py b/lib/instruments.py
index 306882e3..95896aff 100644
--- a/lib/instruments.py
+++ b/lib/instruments.py
@@ -1,7 +1,18 @@
+"""Instrument registry — single source of truth for instrument definitions.
+
+Each instrument (guitar, bass, drums, keys, etc.) is defined by a plugin
+manifest and registered here at startup. Downstream consumers (tunings,
+settings validation, arrangement routing, progression, the frontend
+selector) read from this registry instead of hardcoding instrument names.
+
+See plugins/instrument_<name>/plugin.json for the actual definitions.
+"""
+
 import logging
 
 log = logging.getLogger("feedBack.instruments")
 
+# Valid values for instrument definition fields.
 _INSTRUMENT_KINDS = frozenset({"stringed", "percussion", "keyboard", "vocal", "custom"})
 _DETECT_STRATEGIES = frozenset({"pitch", "onset", "midi", "none"})
 _PATH_FLAGS = frozenset({"path_lead", "path_rhythm", "path_bass"})
@@ -68,10 +79,24 @@ def _validate_offset_list(lst, field_name, expected_len):
 
 
 class InstrumentRegistry:
+    """Holds validated instrument definitions registered by instrument plugins.
+
+    Populated by the plugin loader during startup when it discovers plugins
+    with ``"type": "instrument"``. Consumers (tunings, settings validation,
+    arrangement routing, progression, frontend selector) read from this
+    registry instead of hardcoding instrument knowledge.
+    """
+
     def __init__(self):
         self._instruments: dict[str, dict] = {}
 
     def register(self, definition: dict):
+        """Validate and store an instrument definition.
+
+        Raises ValueError with a descriptive message on schema violations.
+        Normalizes the definition: lowercases arrangement names, deduplicates
+        flags, ensures exactly one role has ``default: true``.
+        """
         inst_id = _validate_str(definition.get("id"), "instrument.id")
         if inst_id in self._instruments:
             raise ValueError(f"instrument {inst_id!r} is already registered")
diff --git a/lib/routers/instruments.py b/lib/routers/instruments.py
index 5dbb6de9..e4e59465 100644
--- a/lib/routers/instruments.py
+++ b/lib/routers/instruments.py
@@ -1,3 +1,9 @@
+"""Registered instrument definitions (GET /api/instruments).
+
+Reads from the appstate.instrument_registry seam — the same instance
+populated by the plugin loader when it discovers type:instrument plugins.
+"""
+
 from fastapi import APIRouter
 import appstate
 
diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index 0fcd6e42..124e353c 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -1,7 +1,14 @@
-// Instruments settings tab ΓÇö renders collapsible instrument cards from
-// GET /api/instruments, with editable custom tunings and arrangement patterns.
-// User overrides are persisted to config.json via POST /api/settings under
-// the "instrument_overrides" key so they survive restarts.
+// Instruments settings tab — renders collapsible instrument cards from
+// GET /api/instruments with editable custom tunings, arrangement name
+// patterns, string counts, and preferred highway per instrument.
+//
+// User overrides are persisted to config.json via instrument_overrides
+// key in /api/settings so they survive restarts. Each card shows:
+//   - Roles (read-only, from plugin definition)
+//   - Arrangement name patterns (editable, add/remove)
+//   - String counts (editable for stringed instruments)
+//   - Tuning presets with offset display (read-only plugin + editable user)
+//   - Preferred highway (dropdown of all viz plugins)
 (function () {
     'use strict';
 

From 4ec49c101d3c770b8515715972376e97ee0afad6 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 18:42:25 +0200
Subject: [PATCH 45/74] docs: add why-comments to all changed sections across
 the codebase

- lib/tunings.py: registry bridge section, non-stringed validation
- lib/metadata_db.py: registry arrangement names in filter allowlist
- plugins/__init__.py: instrument plugin registration design
- server.py: registry instantiation and appstate publishing
- static/v3/songs.js: auto-filter handler, arrangement options from registry
- static/v3/badges.js: dynamic instrument loading, preferred highway
- Other files already had adequate inline comments
---
 lib/metadata_db.py  |  2 ++
 lib/tunings.py      | 16 +++++++++++++++-
 plugins/__init__.py |  6 ++++++
 server.py           |  3 +++
 static/v3/badges.js |  6 ++++++
 static/v3/songs.js  |  8 ++++++++
 6 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/lib/metadata_db.py b/lib/metadata_db.py
index 69cbdf22..2b9df940 100644
--- a/lib/metadata_db.py
+++ b/lib/metadata_db.py
@@ -3505,6 +3505,8 @@ def _build_intrinsic_where(self, alias: str, format_filter: str = "",
         # ('Lead', 'Alt. Lead', 'Alt. Lead N', 'Bonus Lead', 'Bonus Lead N').
         # Falls back to matching `name` for older rows without smart_name.
         # Legacy mode: matches `name` directly (original behaviour).
+        # Also accept arrangement names from the instrument registry (Drums,
+        # Keys, etc.) so the auto-filter works for non-guitar/bass instruments.
         arr_has = [a for a in (arrangements_has or [])
                      if a in self._ALLOWED_ARRANGEMENT_NAMES
                      or a in self._registry_arrangement_names()]
diff --git a/lib/tunings.py b/lib/tunings.py
index 1aa309da..fd489aab 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -10,10 +10,19 @@
 
 DEFAULT_REFERENCE_PITCH = 440.0
 
+# ── Instrument registry bridge ────────────────────────────────────────────
+# Instruments are now defined by plugins (plugins/instrument_<name>/plugin.json)
+# and registered in the InstrumentRegistry at startup. The helpers below build
+# the same dict shapes (STANDARD_OPEN_MIDIS, TUNING_PRESET_MIDIS, PROFILE_DEFAULTS)
+# from the registry so all downstream consumers automatically stay in sync when
+# new instrument plugins are added. The original hardcoded globals remain as
+# fallbacks for the test environment and startup window before plugins load.
+
 _instrument_registry = None
 
 
 def set_instrument_registry(reg):
+    """Called from server.py after plugin loading completes."""
     global _instrument_registry
     _instrument_registry = reg
 
@@ -352,7 +361,12 @@ def _valid_tuning_for_key(key: str, tuning, *, registry=None):
 
 
 def normalize_instrument_profile(profile_id: str, raw, *, registry=None) -> tuple[dict | None, str | None]:
-    """Validate one persisted host instrument profile."""
+    """Validate one persisted host instrument profile.
+
+    Now registry-aware: validates the instrument ID against registered
+    instruments, and skips string-count/tuning checks for non-stringed
+    kinds (drums, keys) which have no strings.
+    """
     profile_defaults = _build_profile_defaults(registry)
     base = dict(profile_defaults.get(profile_id, {}))
     if not base:
diff --git a/plugins/__init__.py b/plugins/__init__.py
index 42a2f5e3..ad669831 100644
--- a/plugins/__init__.py
+++ b/plugins/__init__.py
@@ -1349,6 +1349,12 @@ def _is_bundled(pdir: Path, mf: dict) -> bool:
     )
 
     # ── Instrument plugin registration ────────────────────────────────────
+    # Instruments are defined by bundled plugins (plugins/instrument_<name>/)
+    # with "type": "instrument" in their manifest. The loader extracts the
+    # "instrument" block, stamps the plugin_id (for asset URL building), and
+    # registers it in the InstrumentRegistry so all downstream systems
+    # (tunings, arrangement routing, settings validation, frontend selector)
+    # stay in sync automatically.
     if instrument_registry is not None:
         for plugin_id, plugin_dir, manifest in plugin_load_specs:
             if manifest.get("type") == "instrument":
diff --git a/server.py b/server.py
index 4e4211c7..58344447 100644
--- a/server.py
+++ b/server.py
@@ -166,6 +166,9 @@ def _env_flag(name: str) -> bool:
     local_library_provider=_local_library_provider,
 )
 
+# Instrument definitions are provided by plugins. The registry is populated
+# during plugin loading and then published to appstate so routers (tunings,
+# settings, ws_highway) and the tunings module can read from it.
 instrument_registry = InstrumentRegistry()
 appstate.configure(instrument_registry=instrument_registry)
 
diff --git a/static/v3/badges.js b/static/v3/badges.js
index e938a62e..16ee23e4 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -31,6 +31,10 @@
     let _instruments = [];
     let _instrumentsById = {};
 
+    // Fetch instrument definitions from the registry (populated by instrument
+    // plugins) so the selector shows all registered instruments, not just a
+    // hardcoded guitar/bass list. Exposed to working-tuning and song library
+    // via window.feedBack._instruments.
     async function loadInstruments() {
         try {
             const r = await fetch('/api/instruments');
@@ -283,6 +287,8 @@
             instrument: settings.instrument, stringCount: settings.string_count, tuning: settings.tuning, pathway: settings.pathway,
         });
         // Apply preferred highway for this instrument if one is set.
+        // Read instrument_overrides from config.json and apply the per-instrument
+        // preferred highway, if one is set (instruments-as-plugins).
         _applyPreferredHighway(settings.instrument);
         pushToTuner();
         renderTuner(); // reflect new tuning on the tuner card
diff --git a/static/v3/songs.js b/static/v3/songs.js
index d6e51a54..83cf0309 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -44,6 +44,9 @@
     ];
     const FORMATS = [['', 'All formats'], ['sloppak', 'Feedpak'], ['loose', 'Folder']];
     function _arrangementOptions() {
+        // Derive filter pill labels from instrument registry role names.
+        // When new instrument plugins are added, their arrangement type labels
+        // appear in the library filter drawer automatically.
         var insts = sm && sm._instruments;
         if (Array.isArray(insts) && insts.length) {
             var names = [];
@@ -4295,6 +4298,11 @@
             return true;
         }
 
+        // When the player changes their instrument in the topbar, auto-filter
+        // the library to show only songs with arrangements matching that
+        // instrument's roles (e.g. Lead+Rhythm for guitar, Bass for bass).
+        // Cleared when the user manually edits the arrangement filter; re-applies
+        // on the next instrument switch.
         sm.on('instrument:changed', function (e) {
             var instId = e && e.detail && e.detail.instrument;
             if (!instId) return;

From ff7afd271f9d38784808c71f1d155c309f302c0d Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 18:48:21 +0200
Subject: [PATCH 46/74] docs: add instruments-as-plugins to CHANGELOG

---
 CHANGELOG.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8236ffa1..dca88c1d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Instruments as plugins** — Guitar, Bass, Drums, and Keys are now defined by
+  bundled instrument plugins (`plugins/instrument_<name>/plugin.json`) instead
+  of hardcoded checks across ~15 files. Each plugin declares its own tunings
+  (as semitone offsets from standard), string/key counts, arrangement role
+  mappings, detection strategy, and icon. Community instruments drop in as
+  new `type: "instrument"` plugins with zero code changes.
+- **Per-role mastery** — the library grid now shows mastery % for the currently
+  selected instrument *role* (Lead, Rhythm, Bass, etc.) instead of the song-wide
+  maximum. Selecting Guitar → Rhythm shows your Rhythm scores, not Lead.
+- **Hover overlay on library cards** — hovering album art reveals all
+  arrangements with their individual accuracy percentages (or "—" for
+  unplayed, "n/a" when the selected role has no matching arrangement).
+- **Instrument selector in topbar** now dynamically lists all registered
+  instruments. Non-stringed instruments (Drums, Keys) hide string-count,
+  tuning, handedness, and reference-pitch controls. Keyboard instruments show
+  a key count selector (25/49/61/88).
+- **Per-instrument role selection** — multi-role instruments (Guitar) show
+  Lead/Rhythm pills in the selector. Switching roles changes which arrangement
+  the highway opens and which mastery % the library displays.
+- **Per-instrument preferred highway** — Settings → Instruments lets you assign
+  a preferred note highway per instrument. Changing instruments auto-selects it.
+- **Instrument settings tab** (Settings → Instruments) with collapsible cards
+  showing roles, editable arrangement name patterns, string counts, custom
+  tuning presets, and per-instrument preferred highway.
+- **Auto-filter by instrument** — the Song Library auto-filters to arrangements
+  matching the current instrument. Clearing the filter disables it; switching
+  instruments re-enables it.
+- **GET /api/instruments** endpoint and `lib/instruments.py` registry.
+- **Per-instrument icons** — each instrument shows its own SVG icon in the
+  topbar selector (loaded from the plugin's `assets/icon.svg`).
+- **Tuner shows tuning name** — the tuner badge now displays the current tuning
+  name (e.g. "E Std") in addition to the note letter and Hz.
+- **Score attribution fix** — scores now record the server-resolved arrangement
+  index (from `song:ready`) instead of defaulting to 0 when clicking the main
+  card (not an arrangement chip).
+
+### Changed
+- **Standard tuning renamed** — the all-zero-offset tuning is now named
+  "E Standard" (guitar-6, bass-4), "B Standard" (guitar-7, bass-5/6), or
+  "F# Standard" (guitar-8) instead of the ambiguous "Standard".
+- **Tuning chip** moved to the top-left card corner (flush, no padding offset).
+- **Mastery badge** now has a colored left/top border matching its level
+  (green/amber/red) with a translucent fill.
+- **Arrangement filter pills** in the library drawer are now derived from the
+  instrument registry's role labels instead of a hardcoded list.
+- **Settings validation** accepts any registered instrument ID, not just
+  "guitar" or "bass". Non-stringed instruments skip string-count/tuning checks.
+- **Working-tuning capability** now reads instrument definitions from the
+  registry for normalization.
+- **Arrangement routing** (`ws_highway.py`) uses role flags and arrangement
+  names from the instrument registry instead of hardcoded bass detection.
+- **Progression** `instrument_for_arrangement` accepts a `registry` parameter
+  and returns `None` for unrecognized arrangements instead of defaulting to
+  "guitar".
+- **Icons** — instrument selector card shows per-instrument icons instead of
+  a single hardcoded guitar SVG.
+- **Pathway removed** from the instrument selector (unused feature).
+
+### Fixed
+- **Tuner sync** — switching instruments in the selector now correctly pushes
+  the new instrument key to the tuner plugin.
+- **SQL error** in `arrangement_accuracy_map` when `_existing_song_filter` is
+  empty (double-AND).
+- **Default arrangement dropdown** removed from Settings → Gameplay (moved to
+  the instrument selector role pills).
+
 ### Added
 - **Gold tier (career passports)** — an earned badge turns **gold** when
   Virtuoso verifies an improvised jam in the passport's style (the

From 322f725b2db0fa1afbbbb1dd2292d5254b05f9bc Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 19:49:52 +0200
Subject: [PATCH 47/74] fix: use arr_has.length instead of _arrAutoInstrument
 for 'n/a' detection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_arrAutoInstrument tracks the instrument ID but can be cleared when
the user manually edits the filter drawer. Using state.filters.arr_has
directly is more robust — it reflects the actual filter state at all
times, not a flag that may go stale.
---
 static/v3/songs.js | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 83cf0309..7bb6bf9c 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -567,12 +567,13 @@
         if (acc == null && !hasArr) return '';
 
         var pct = acc != null ? Math.floor(acc * 100) : null;
-        // Display: "n/a" when the selected role has no arrangement in this song;
-        // "— %" when the arrangement exists but hasn't been played yet.
+        // Display: "n/a" when the auto-filter is active but this song has no
+        // arrangement matching the selected role. "— %" when the arrangement
+        // exists but hasn't been scored yet.
         var displayLabel;
         if (pct != null) {
             displayLabel = pct + '%';
-        } else if (_arrAutoInstrument && !hasMatchingArrangement) {
+        } else if (state.filters.arr_has.length && !hasMatchingArrangement) {
             displayLabel = 'n/a';
         } else {
             displayLabel = '— %';

From 7f49e7e5fef06abe6eac016bb7fb6698430d174f Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 19:54:07 +0200
Subject: [PATCH 48/74] fix: show 'n/a' when filter is inactive but song lacks
 selected role's arrangement
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- When arrangement filter is OFF, check the active role against each
  song — if no matching arrangement exists, show 'n/a'.
- When filter IS ON, songs without a match are already excluded
  server-side, so 'n/a' is never needed.
- _matchingArrangementIndex now resolves active role even when
  arr_has is empty, so per-role accuracy works without a filter.
---
 static/v3/songs.js | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 7bb6bf9c..bed6e731 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -502,9 +502,7 @@
         // Find the arrangement whose name matches the current auto-filter role.
         // This is the arrangement the card would open for the current instrument.
         var want = state.filters.arr_has;
-        if (!want.length) return null;
         // Resolve the active role from the current instrument profile
-        // so we show mastery for the user's selected role (Lead/Rhythm).
         var activeProfileId = (sm && sm._activeInstrumentProfile) || '';
         var activeRoleLabel = null;
         if (activeProfileId) {
@@ -533,6 +531,8 @@
             // so the badge shows "n/a" instead of falling back to a different role.
             return null;
         }
+        // Without an active role, fall back to arrangement auto-filter.
+        if (!want.length) return null;
         // Fallback: first arrangement matching any auto-filter value.
         for (var i = 0; i < song.arrangements.length; i++) {
             var a2 = song.arrangements[i];
@@ -567,13 +567,14 @@
         if (acc == null && !hasArr) return '';
 
         var pct = acc != null ? Math.floor(acc * 100) : null;
-        // Display: "n/a" when the auto-filter is active but this song has no
-        // arrangement matching the selected role. "— %" when the arrangement
-        // exists but hasn't been scored yet.
+        // When the arrangement filter is inactive, all songs appear — but some
+        // may not have the selected role's arrangement. Show "n/a" in that case.
+        // When the filter IS active, songs without a match are already excluded
+        // server-side, so we only show "— %" (unplayed) or the percentage.
         var displayLabel;
         if (pct != null) {
             displayLabel = pct + '%';
-        } else if (state.filters.arr_has.length && !hasMatchingArrangement) {
+        } else if (!state.filters.arr_has.length && !hasMatchingArrangement) {
             displayLabel = 'n/a';
         } else {
             displayLabel = '— %';

From d0e7ab7a6a16758a400dfad98034215062b23810 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:00:41 +0200
Subject: [PATCH 49/74] fix: smart-mode filter uses simple name matching for
 non-standard arrangement types

Smart mode (Lead/Rhythm/Bass) uses Alt./Bonus prefix patterns, but
types from the instrument registry (Keys, Drums, etc.) don't have
smart names. Previously the smart mode patterns for these types
generated unproductive SQL (looking for 'Alt. Keys' etc.), silently
returning all songs. Now non-smart types fall back to simple
name matching, so filtering by Keys/Drums actually works.
---
 lib/metadata_db.py | 53 +++++++++++++++++++++++-----------------------
 1 file changed, 26 insertions(+), 27 deletions(-)

diff --git a/lib/metadata_db.py b/lib/metadata_db.py
index 2b9df940..3e230971 100644
--- a/lib/metadata_db.py
+++ b/lib/metadata_db.py
@@ -3497,14 +3497,12 @@ def _build_intrinsic_where(self, alias: str, format_filter: str = "",
             params.append(format_filter)
         # arrangements_has / arrangements_lacks: OR within axis (any-of).
         # Uses JSON1's json_each which yields one row per arrangement, then
-        # matches the relevant field. The whole subquery is wrapped in EXISTS
-        # so we don't multiply rows in the outer SELECT.
+        # matches the relevant field.
         #
-        # Smart mode: each requested type (Lead/Rhythm/Bass) matches against
-        # smart_name when present. "Lead" matches smart_name in
-        # ('Lead', 'Alt. Lead', 'Alt. Lead N', 'Bonus Lead', 'Bonus Lead N').
-        # Falls back to matching `name` for older rows without smart_name.
-        # Legacy mode: matches `name` directly (original behaviour).
+        # Smart mode: known types (Lead/Rhythm/Bass/Combo) match against
+        # smart_name with Alt./Bonus variants. Unknown types from the
+        # instrument registry (Keys, Drums) use simple name matching since
+        # they don't have smart-name variants.
         # Also accept arrangement names from the instrument registry (Drums,
         # Keys, etc.) so the auto-filter works for non-guitar/bass instruments.
         arr_has = [a for a in (arrangements_has or [])
@@ -3517,20 +3515,15 @@ def _build_intrinsic_where(self, alias: str, format_filter: str = "",
             arr_has = list(dict.fromkeys("Lead" if a == "Combo" else a for a in arr_has))
         if arr_has:
             if naming_mode == "smart":
+                # Split into known smart types (Lead/Rhythm/Bass/Combo) which
+                # have Alt./Bonus variants, and other types (Keys, Drums, etc.)
+                # from the instrument registry which only exist as raw names.
+                smart_types = [a for a in arr_has if a in _SMART_TYPE_BASE or a == "Combo"]
+                plain_types = [a for a in arr_has if a not in _SMART_TYPE_BASE and a != "Combo"]
                 clauses = []
-                for arr_type in arr_has:
-                    # Extra raw-name fragments matched only in the key-absent
-                    # NULL-smart_name fallback branch — they cover the legacy
-                    # display names that map to this smart type:
-                    #   Lead: "Combo" (combined guitar) + Alt./Bonus Combo
-                    #   Bass: "Bass 2" (load_song synthesises for real_bass_22)
+                for arr_type in smart_types:
+                    # ... existing smart-type clause building ...
                     extra_null, extra_null_params = self._smart_null_extras(arr_type)
-                    # json_type() returns NULL when the key is absent and the
-                    # string 'null' when the key exists with explicit JSON null
-                    # (set by the scanner for ambiguous duplicate-name rows).
-                    # Name-fallback only applies to key-absent rows so an
-                    # explicit null suppresses the fallback and lets the
-                    # background rescan resolve the ambiguity authoritatively.
                     clauses.append(
                         "(json_extract(value, '$.smart_name') IS NOT NULL AND ("
                         f"json_extract(value, '$.smart_name') = ? OR "
@@ -3550,6 +3543,12 @@ def _build_intrinsic_where(self, alias: str, format_filter: str = "",
                         f"Alt. {arr_type}%",
                         f"Bonus {arr_type}%",
                     ] + extra_null_params
+                # Non-smart types (Keys, Drums): simple name matching.
+                for arr_type in plain_types:
+                    clauses.append(
+                        "json_extract(value, '$.name') = ?"
+                    )
+                    params.append(arr_type)
                 where += (
                     f" AND EXISTS (SELECT 1 FROM json_each({alias}.arrangements) WHERE "
                     + " OR ".join(f"({c})" for c in clauses)
@@ -3567,16 +3566,11 @@ def _build_intrinsic_where(self, alias: str, format_filter: str = "",
             arr_lacks = list(dict.fromkeys("Lead" if a == "Combo" else a for a in arr_lacks))
         if arr_lacks:
             if naming_mode == "smart":
+                smart_types = [a for a in arr_lacks if a in _SMART_TYPE_BASE or a == "Combo"]
+                plain_types = [a for a in arr_lacks if a not in _SMART_TYPE_BASE and a != "Combo"]
                 clauses = []
-                for arr_type in arr_lacks:
+                for arr_type in smart_types:
                     extra_null, extra_null_params = self._smart_null_extras(arr_type)
-                    # See "has" branch above for the json_type rationale.
-                    # Extra branch (vs `has`): an explicit smart_name=null
-                    # arrangement is ambiguous; we don't know whether it's
-                    # `arr_type` or not. Be conservative and treat it as
-                    # potentially matching, so `arrangements_lacks` excludes
-                    # the parent row instead of falsely claiming it lacks
-                    # `arr_type`. The background rescan resolves the ambiguity.
                     clauses.append(
                         "(json_extract(value, '$.smart_name') IS NOT NULL AND ("
                         f"json_extract(value, '$.smart_name') = ? OR "
@@ -3598,6 +3592,11 @@ def _build_intrinsic_where(self, alias: str, format_filter: str = "",
                         f"Alt. {arr_type}%",
                         f"Bonus {arr_type}%",
                     ] + extra_null_params
+                for arr_type in plain_types:
+                    clauses.append(
+                        "json_extract(value, '$.name') = ?"
+                    )
+                    params.append(arr_type)
                 where += (
                     f" AND NOT EXISTS (SELECT 1 FROM json_each({alias}.arrangements) WHERE "
                     + " OR ".join(f"({c})" for c in clauses)

From cd3d803f650c8b33f5d78eb578707ec1e418e1a4 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:08:46 +0200
Subject: [PATCH 50/74] =?UTF-8?q?fix:=20remove=20song-wide=20max=20fallbac?=
 =?UTF-8?q?k=20=E2=80=94=20never=20attribute=20wrong=20role's=20score?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When no filter is active and the selected role has no arrangement in
a song, we showed the song-wide max accuracy, which could come from
a completely different arrangement. Now we only show per-arrangement
accuracy or '— %' / 'n/a'.
---
 static/v3/songs.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index bed6e731..3f2a563d 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -561,8 +561,8 @@
         if (hasMatchingArrangement) {
             acc = _perArrangementAccuracy(filename, arrIdx);
         }
-        // Fall back to song-wide max only when no auto-filter is active.
-        if (acc == null && !state.filters.arr_has.length) acc = state.accuracy[filename];
+        // Never fall back to song-wide max — that would attribute a
+        // different role's score to the currently selected role.
         var hasArr = song && song.arrangements && song.arrangements.length > 0;
         if (acc == null && !hasArr) return '';
 

From 97f3516ac907473b77af61398fe909ed289d7ee8 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:16:57 +0200
Subject: [PATCH 51/74] feat: add 'Auto-filter by instrument' toggle in
 Gameplay settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New checkbox in Settings → Gameplay (on by default)
- When enabled, the song library auto-filters to the current
  instrument's arrangements as before
- When disabled, the library shows all songs regardless of instrument
- Persisted to config.json as auto_filter_instrument (boolean)
- Hydrated on settings load, checked before auto-filter apply
---
 lib/routers/settings.py |  6 ++++++
 static/js/settings.js   |  2 ++
 static/v3/index.html    | 16 +++++++++++++++-
 static/v3/songs.js      |  8 ++++++--
 4 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/lib/routers/settings.py b/lib/routers/settings.py
index 7d1366f4..6053a5fa 100644
--- a/lib/routers/settings.py
+++ b/lib/routers/settings.py
@@ -161,6 +161,12 @@ def save_settings(data: dict):
             if not isinstance(raw, bool):
                 return {"error": "use_amp_sims must be a boolean"}
             updates["use_amp_sims"] = raw
+    if "auto_filter_instrument" in data:
+        raw = data["auto_filter_instrument"]
+        if raw is not None:
+            if not isinstance(raw, bool):
+                return {"error": "auto_filter_instrument must be a boolean"}
+            updates["auto_filter_instrument"] = raw
     if "enrich_enabled" in data:
         raw = data["enrich_enabled"]
         if raw is not None:
diff --git a/static/js/settings.js b/static/js/settings.js
index 7591524b..acb264a4 100644
--- a/static/js/settings.js
+++ b/static/js/settings.js
@@ -123,6 +123,8 @@ export async function loadSettings() {
     if (showUpNextEl) showUpNextEl.checked = _showUpNextEnabled();
     const confirmExitEl = document.getElementById('setting-confirm-exit');
     if (confirmExitEl) confirmExitEl.checked = _exitConfirmEnabled();
+    const autoFilterEl = document.getElementById('setting-auto-filter-instrument');
+    if (autoFilterEl) autoFilterEl.checked = data.auto_filter_instrument !== false;
     // Restore master-difficulty slider from persisted value (defaults
     // to 100 when the key is absent — no behaviour change for users
     // who've never touched the slider).
diff --git a/static/v3/index.html b/static/v3/index.html
index 3e849937..51e57972 100644
--- a/static/v3/index.html
+++ b/static/v3/index.html
@@ -444,9 +444,23 @@ <h3>Gameplay Settings</h3>
                         <div class="fb-srow-main">
                             <div class="fb-srow-title">Default arrangement</div>
                             <div class="fb-srow-desc">Set per instrument in the topbar instrument selector.</div>
-                        </div>
                     </div>
+                    <!-- Auto-filter library by instrument -->
+                    <div class="fb-srow">
+                        <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 4a1 1 0 011-1h16a1 1 0 011 1v2.586a1 1 0 01-.293.707l-6.414 6.414a1 1 0 00-.293.707V17l-4 4v-6.586a1 1 0 00-.293-.707L3.293 7.293A1 1 0 013 6.586V4z"/></svg></span>
+                        <div class="fb-srow-main">
+                            <div class="fb-srow-title">Auto-filter by instrument</div>
+                            <div class="fb-srow-desc">When enabled, the song library automatically filters to show only songs with arrangements for your selected instrument. Disable to browse freely.</div>
+                        </div>
+                        <div class="fb-srow-control">
+                            <label class="fb-switch">
+                                <input type="checkbox" id="setting-auto-filter-instrument" checked onchange="persistSetting('auto_filter_instrument', this.checked)">
+                                <span class="fb-switch-track"></span>
+                            </label>
+                        </div>
                     </div>
+                </div>
+            </div>
                     <!-- Instrument pathway -->
                     <div class="fb-srow">
                         <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 20l-5.447-2.724A1 1 0 013 16.382V5.618a1 1 0 011.447-.894L9 7m0 13l6-3m-6 3V7m6 10l4.553 2.276A1 1 0 0021 18.382V7.618a1 1 0 00-1.447-.894L15 4m0 13V4m0 0L9 7"/></svg></span>
diff --git a/static/v3/songs.js b/static/v3/songs.js
index 3f2a563d..9e2f890f 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -3657,7 +3657,10 @@
                 if (sr.ok) {
                     var sd = await sr.json();
                     var instId = sd && sd.instrument;
-                    if (instId) _applyArrangementAutoFilter(instId);
+                    // Respect the auto-filter toggle in Gameplay settings.
+                    var autoFilter = sd.auto_filter_instrument !== false;
+                    _autoFilterEnabled = autoFilter;
+                    if (instId && autoFilter) _applyArrangementAutoFilter(instId);
                 }
             } catch (_) {}
         }
@@ -4274,6 +4277,7 @@
         // Clears on manual arrangement filter change; re-applies on next
         // instrument switch.
         var _arrAutoInstrument = null;
+        var _autoFilterEnabled = true;     // mirror of auto_filter_instrument setting
 
         function _instrumentArrangementNames(instrumentId) {
             var insts = sm && sm._instruments;
@@ -4307,7 +4311,7 @@
         // on the next instrument switch.
         sm.on('instrument:changed', function (e) {
             var instId = e && e.detail && e.detail.instrument;
-            if (!instId) return;
+            if (!instId || !_autoFilterEnabled) return;
             if (_applyArrangementAutoFilter(instId)) {
                 reload();
                 renderDrawerIfOpen();

From 4249b08354fb7651ed259a9cf47916e6075019be Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:21:56 +0200
Subject: [PATCH 52/74] fix: remove unused Default arrangement setting, fix
 orphaned HTML closers

- Removed the muted 'Default arrangement' row from Gameplay tab entirely.
  It was already non-functional (just a note saying it moved to the selector).
- Auto-filter by instrument toggle now sits in its place.
- Fixed orphaned </div> closers left from the old structure.
---
 static/v3/index.html | 15 +--------------
 1 file changed, 1 insertion(+), 14 deletions(-)

diff --git a/static/v3/index.html b/static/v3/index.html
index 51e57972..3c0fc63f 100644
--- a/static/v3/index.html
+++ b/static/v3/index.html
@@ -434,23 +434,12 @@ <h3>Gameplay Settings</h3>
                             </label>
                         </div>
                     </div>
-                    <!-- Default arrangement -->
-                    <div class="fb-srow">
-                    <!-- Default arrangement moved to instrument selector (instruments-as-plugins).
-                         Each instrument's roles define available arrangements; the preference is
-                         stored per profile as "default_role" instead of the legacy "default_arrangement". -->
-                    <div class="fb-srow muted">
-                        <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"/></svg></span>
-                        <div class="fb-srow-main">
-                            <div class="fb-srow-title">Default arrangement</div>
-                            <div class="fb-srow-desc">Set per instrument in the topbar instrument selector.</div>
-                    </div>
                     <!-- Auto-filter library by instrument -->
                     <div class="fb-srow">
                         <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 4a1 1 0 011-1h16a1 1 0 011 1v2.586a1 1 0 01-.293.707l-6.414 6.414a1 1 0 00-.293.707V17l-4 4v-6.586a1 1 0 00-.293-.707L3.293 7.293A1 1 0 013 6.586V4z"/></svg></span>
                         <div class="fb-srow-main">
                             <div class="fb-srow-title">Auto-filter by instrument</div>
-                            <div class="fb-srow-desc">When enabled, the song library automatically filters to show only songs with arrangements for your selected instrument. Disable to browse freely.</div>
+                            <div class="fb-srow-desc">When enabled, the song library automatically filters to show only songs with arrangements for your selected instrument. Disable to browse all songs freely.</div>
                         </div>
                         <div class="fb-srow-control">
                             <label class="fb-switch">
@@ -459,8 +448,6 @@ <h3>Gameplay Settings</h3>
                             </label>
                         </div>
                     </div>
-                </div>
-            </div>
                     <!-- Instrument pathway -->
                     <div class="fb-srow">
                         <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 20l-5.447-2.724A1 1 0 013 16.382V5.618a1 1 0 011.447-.894L9 7m0 13l6-3m-6 3V7m6 10l4.553 2.276A1 1 0 0021 18.382V7.618a1 1 0 00-1.447-.894L15 4m0 13V4m0 0L9 7"/></svg></span>

From 2f6cd8216e3c4604e95c1421132e9767f5fbe40c Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:26:13 +0200
Subject: [PATCH 53/74] debug: add console.log to instrument:changed handler

---
 static/v3/songs.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 9e2f890f..970c803e 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -4311,6 +4311,7 @@
         // on the next instrument switch.
         sm.on('instrument:changed', function (e) {
             var instId = e && e.detail && e.detail.instrument;
+            console.log('auto-filter: instrument=' + instId + ' enabled=' + _autoFilterEnabled);
             if (!instId || !_autoFilterEnabled) return;
             if (_applyArrangementAutoFilter(instId)) {
                 reload();

From 40b3f010e0f558e044082c4fef9bff0c6748fd68 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:26:38 +0200
Subject: [PATCH 54/74] debug: add console.log to initial render auto-filter

---
 static/v3/songs.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 970c803e..ecf3478d 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -3660,6 +3660,7 @@
                     // Respect the auto-filter toggle in Gameplay settings.
                     var autoFilter = sd.auto_filter_instrument !== false;
                     _autoFilterEnabled = autoFilter;
+                    console.log('auto-filter: initial render instrument=' + instId + ' enabled=' + autoFilter + ' raw=' + sd.auto_filter_instrument);
                     if (instId && autoFilter) _applyArrangementAutoFilter(instId);
                 }
             } catch (_) {}

From 180633b033d4fdffee26a670540080cb34e0a044 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:30:00 +0200
Subject: [PATCH 55/74] fix: always read auto-filter setting, not just on first
 render

_autoFilterEnabled was only read inside the _arrAutoInstrument===null
block, so it never updated on subsequent library visits after the
first one. Now the settings fetch runs on every render() call.
When the toggle is OFF, any previously-applied auto-filter is cleared.
---
 static/v3/songs.js | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index ecf3478d..c3cdfd91 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -3651,19 +3651,25 @@
         // toolbar so its selects reflect the saved choice (default: Artist A–Z).
         if (!_prefsRestored) { applySavedPrefs(); _prefsRestored = true; }
         // ── Auto-apply instrument arrangement filter on first render ─────
-        if (_arrAutoInstrument === null && !state.filters.arr_has.length && !state.filters.arr_lacks.length) {
+        // Always read the auto-filter toggle from settings so the user can
+        // enable/disable it in Settings → Gameplay without a full page reload.
+        try {
+            var sr = await fetch('/api/settings');
+            if (sr.ok) {
+                var sd = await sr.json();
+                _autoFilterEnabled = sd.auto_filter_instrument !== false;
+            }
+        } catch (_) {}
+        if (_autoFilterEnabled && _arrAutoInstrument === null && !state.filters.arr_has.length && !state.filters.arr_lacks.length) {
             try {
-                var sr = await fetch('/api/settings');
-                if (sr.ok) {
-                    var sd = await sr.json();
-                    var instId = sd && sd.instrument;
-                    // Respect the auto-filter toggle in Gameplay settings.
-                    var autoFilter = sd.auto_filter_instrument !== false;
-                    _autoFilterEnabled = autoFilter;
-                    console.log('auto-filter: initial render instrument=' + instId + ' enabled=' + autoFilter + ' raw=' + sd.auto_filter_instrument);
-                    if (instId && autoFilter) _applyArrangementAutoFilter(instId);
-                }
+                var instId = sd && sd.instrument;
+                if (instId) _applyArrangementAutoFilter(instId);
             } catch (_) {}
+        } else if (!_autoFilterEnabled && state.filters.arr_has.length) {
+            // Toggle was turned off — clear any previously-applied auto-filter.
+            state.filters.arr_has = [];
+            state.filters.arr_lacks = [];
+            _arrAutoInstrument = null;
         }
         const providers = await loadProviders();
         const [, tn] = await Promise.all([
@@ -4312,7 +4318,6 @@
         // on the next instrument switch.
         sm.on('instrument:changed', function (e) {
             var instId = e && e.detail && e.detail.instrument;
-            console.log('auto-filter: instrument=' + instId + ' enabled=' + _autoFilterEnabled);
             if (!instId || !_autoFilterEnabled) return;
             if (_applyArrangementAutoFilter(instId)) {
                 reload();

From 3fb69d8595140ea6066800290dbbd566df1376d5 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:33:47 +0200
Subject: [PATCH 56/74] fix: read auto-filter setting in onV3SongsScreenEnter,
 not render()

render() is cached/skipped on return visits to the library when the
DOM hash matches. Moved the settings read to onV3SongsScreenEnter
which always runs on screen entry, so the toggle change is picked up
immediately even without a full re-render.
---
 static/v3/songs.js | 44 ++++++++++++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 16 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index c3cdfd91..811ed2d2 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -3651,25 +3651,17 @@
         // toolbar so its selects reflect the saved choice (default: Artist A–Z).
         if (!_prefsRestored) { applySavedPrefs(); _prefsRestored = true; }
         // ── Auto-apply instrument arrangement filter on first render ─────
-        // Always read the auto-filter toggle from settings so the user can
-        // enable/disable it in Settings → Gameplay without a full page reload.
-        try {
-            var sr = await fetch('/api/settings');
-            if (sr.ok) {
-                var sd = await sr.json();
-                _autoFilterEnabled = sd.auto_filter_instrument !== false;
-            }
-        } catch (_) {}
+        // auto_filter_instrument setting is already refreshed in
+        // onV3SongsScreenEnter before render() is called.
         if (_autoFilterEnabled && _arrAutoInstrument === null && !state.filters.arr_has.length && !state.filters.arr_lacks.length) {
             try {
-                var instId = sd && sd.instrument;
-                if (instId) _applyArrangementAutoFilter(instId);
+                var sr2 = await fetch('/api/settings');
+                if (sr2.ok) {
+                    var sd2 = await sr2.json();
+                    var instId = sd2 && sd2.instrument;
+                    if (instId) _applyArrangementAutoFilter(instId);
+                }
             } catch (_) {}
-        } else if (!_autoFilterEnabled && state.filters.arr_has.length) {
-            // Toggle was turned off — clear any previously-applied auto-filter.
-            state.filters.arr_has = [];
-            state.filters.arr_lacks = [];
-            _arrAutoInstrument = null;
         }
         const providers = await loadProviders();
         const [, tn] = await Promise.all([
@@ -3843,6 +3835,26 @@
     }
 
     async function onV3SongsScreenEnter() {
+        // Always refresh the auto-filter toggle state so the user can
+        // enable/disable it in Settings without a full page reload.
+        try {
+            var sr = await fetch('/api/settings');
+            if (sr.ok) {
+                var sd = await sr.json();
+                _autoFilterEnabled = sd.auto_filter_instrument !== false;
+                // If the toggle was turned off, clear any previously-applied filter.
+                if (!_autoFilterEnabled && state.filters.arr_has.length) {
+                    state.filters.arr_has = [];
+                    state.filters.arr_lacks = [];
+                    _arrAutoInstrument = null;
+                }
+                // If the toggle was turned on and no filter is active, apply it.
+                if (_autoFilterEnabled && _arrAutoInstrument === null && !state.filters.arr_has.length && !state.filters.arr_lacks.length) {
+                    var instId = sd && sd.instrument;
+                    if (instId) _applyArrangementAutoFilter(instId);
+                }
+            }
+        } catch (_) {}
         // A library scan / DLC-folder change marked the grid stale — re-fetch
         // from scratch instead of restoring a cached (possibly empty, pre-DLC)
         // snapshot. Must win over every fast-path below.

From edeaf4db46d594d996902ce66986d4effb8d0836 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 20:44:29 +0200
Subject: [PATCH 57/74] docs: add docstrings to all new/modified functions to
 meet 80% coverage

- lib/instruments.py: module docstring, class docstring, method docstrings
  for all public methods and private validators
- lib/tunings.py: docstrings for _build_*, _valid_instrument_ids,
  _default_profile_id_for_instrument helper functions
- lib/routers/instruments.py and lib/routers/stats.py: endpoint docstrings
---
 lib/instruments.py         | 18 ++++++++++++++++++
 lib/routers/instruments.py |  1 +
 lib/routers/stats.py       |  3 +--
 lib/tunings.py             |  6 ++++++
 4 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/lib/instruments.py b/lib/instruments.py
index 95896aff..6e6b0d23 100644
--- a/lib/instruments.py
+++ b/lib/instruments.py
@@ -20,6 +20,7 @@
 
 
 def _validate_str(value, field_name, max_len=128):
+    """Validate a required non-empty string field, returning stripped value."""
     if not isinstance(value, str) or not value.strip():
         raise ValueError(f"{field_name} must be a non-empty string")
     if len(value) > max_len:
@@ -28,6 +29,7 @@ def _validate_str(value, field_name, max_len=128):
 
 
 def _validate_optional_str(value, field_name, max_len=256):
+    """Validate an optional string field; None passes through, non-empty string required otherwise."""
     if value is None:
         return None
     if not isinstance(value, str):
@@ -38,6 +40,7 @@ def _validate_optional_str(value, field_name, max_len=256):
 
 
 def _validate_float_range(value, field_name, lo, hi):
+    """Validate a numeric value falls within [lo, hi], rejecting bools."""
     if not isinstance(value, (int, float)) or isinstance(value, bool):
         raise ValueError(f"{field_name} must be a number")
     v = float(value)
@@ -47,6 +50,7 @@ def _validate_float_range(value, field_name, lo, hi):
 
 
 def _validate_midi_list(lst, field_name, expected_len):
+    """Validate a list of MIDI note numbers (ints in 0-127) of the given length."""
     if not isinstance(lst, list):
         raise ValueError(f"{field_name} must be a list")
     if len(lst) != expected_len:
@@ -63,6 +67,7 @@ def _validate_midi_list(lst, field_name, expected_len):
 
 
 def _validate_offset_list(lst, field_name, expected_len):
+    """Validate a list of semitone offsets (ints in -12..12) of the given length."""
     if not isinstance(lst, list):
         raise ValueError(f"{field_name} must be a list of offsets")
     if len(lst) != expected_len:
@@ -242,17 +247,25 @@ def register(self, definition: dict):
         log.info("registered instrument %r (%s)", inst_id, label)
 
     def unregister(self, instrument_id: str):
+        """Remove an instrument definition from the registry."""
         if instrument_id in self._instruments:
             del self._instruments[instrument_id]
             log.info("unregistered instrument %r", instrument_id)
 
     def get(self, instrument_id: str) -> dict | None:
+        """Return the definition for a single instrument, or None."""
         return self._instruments.get(instrument_id)
 
     def get_all(self) -> list[dict]:
+        """Return all registered instrument definitions."""
         return list(self._instruments.values())
 
     def compute_tuning_midis(self, instrument_id: str, string_count: int, tuning_name: str) -> list[int] | None:
+        """Return absolute MIDI notes for a named tuning on a stringed instrument.
+
+        Computed by adding the tuning's semitone offsets to the instrument's
+        standard open-string MIDI notes for the given string count.
+        """
         inst = self._instruments.get(instrument_id)
         if not inst or inst["kind"] != "stringed":
             return None
@@ -264,18 +277,21 @@ def compute_tuning_midis(self, instrument_id: str, string_count: int, tuning_nam
         return [s + o for s, o in zip(std, offsets)]
 
     def get_tuning_names(self, instrument_id: str, string_count: int) -> list[str]:
+        """Return all tuning preset names for a stringed instrument + string count."""
         inst = self._instruments.get(instrument_id)
         if not inst or inst["kind"] != "stringed":
             return []
         return list((inst["tunings"].get(str(string_count)) or {}).keys())
 
     def get_standard_midis(self, instrument_id: str, string_count: int) -> list[int] | None:
+        """Return standard open-string MIDI notes for a stringed instrument + string count."""
         inst = self._instruments.get(instrument_id)
         if not inst or inst["kind"] != "stringed":
             return None
         return inst["standard_tunings"].get(str(string_count))
 
     def get_default_role(self, instrument_id: str) -> str | None:
+        """Return the id of the default role for an instrument, or None."""
         inst = self._instruments.get(instrument_id)
         if not inst:
             return None
@@ -287,6 +303,7 @@ def get_default_role(self, instrument_id: str) -> str | None:
         return None
 
     def find_role_by_arrangement(self, instrument_id: str, arr_name: str, arr_flags: dict = None) -> str | None:
+        """Find the role id matching an arrangement name or path flags for a specific instrument."""
         inst = self._instruments.get(instrument_id)
         if not inst:
             return None
@@ -301,6 +318,7 @@ def find_role_by_arrangement(self, instrument_id: str, arr_name: str, arr_flags:
         return None
 
     def instrument_id_for_arrangement(self, arr_name: str, arr_flags: dict = None) -> str | None:
+        """Return the instrument id whose roles match a given arrangement name or flags."""
         name_lower = (arr_name or "").strip().lower()
         for inst in self._instruments.values():
             for role in inst["roles"]:
diff --git a/lib/routers/instruments.py b/lib/routers/instruments.py
index e4e59465..2f7074ea 100644
--- a/lib/routers/instruments.py
+++ b/lib/routers/instruments.py
@@ -12,5 +12,6 @@
 
 @router.get("/api/instruments")
 def get_instruments():
+    """Return all instrument definitions registered via instrument plugins."""
     reg = getattr(appstate, "instrument_registry", None)
     return reg.get_all() if reg else []
diff --git a/lib/routers/stats.py b/lib/routers/stats.py
index 2882f713..557ca72e 100644
--- a/lib/routers/stats.py
+++ b/lib/routers/stats.py
@@ -243,8 +243,7 @@ def api_stats_best():
 
 @router.get("/api/stats/best-by-arrangement")
 def api_stats_best_by_arrangement():
-    """{filename: {arrangement_index: best_accuracy}} per-arrangement accuracy,
-    for per-role badging and hover overlays on the library grid."""
+    """Return {filename: {arrangement_index: best_accuracy}} for per-role badging."""
     return appstate.meta_db.arrangement_accuracy_map()
 
 
diff --git a/lib/tunings.py b/lib/tunings.py
index fd489aab..e6806fb8 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -28,6 +28,7 @@ def set_instrument_registry(reg):
 
 
 def _build_standard_midis(registry=None):
+    """Build {instrument_key: [midis]} from the registry, falling back to hardcoded STANDARD_OPEN_MIDIS."""
     reg = registry or _instrument_registry
     result = {}
     if reg:
@@ -43,6 +44,7 @@ def _build_standard_midis(registry=None):
 
 
 def _build_preset_midis(registry=None):
+    """Build {instrument_key: {tuning_name: [midis]}} from the registry, falling back to TUNING_PRESET_MIDIS."""
     reg = registry or _instrument_registry
     result = {}
     if reg:
@@ -66,6 +68,7 @@ def _build_preset_midis(registry=None):
 
 
 def _build_profile_defaults(registry=None):
+    """Build {profile_id: profile_dict} from registered instruments, falling back to PROFILE_DEFAULTS."""
     reg = registry or _instrument_registry
     result = {}
     if reg:
@@ -97,11 +100,13 @@ def _build_profile_defaults(registry=None):
 
 
 def _build_profile_ids(registry=None):
+    """Return a tuple of valid instrument profile ids, derived from the registry."""
     profiles = _build_profile_defaults(registry)
     return tuple(profiles.keys())
 
 
 def _valid_instrument_ids(registry=None):
+    """Return the set of valid instrument IDs from the registry, or a guitar/bass fallback."""
     reg = registry or _instrument_registry
     if reg:
         ids = {inst["id"] for inst in reg.get_all()}
@@ -111,6 +116,7 @@ def _valid_instrument_ids(registry=None):
 
 
 def _default_profile_id_for_instrument(instrument_id, registry=None):
+    """Return the profile id for an instrument's default role, e.g. 'guitar-lead'."""
     profiles = _build_profile_defaults(registry)
     for pid, profile in profiles.items():
         if profile["instrument"] == instrument_id and profile.get("default_role"):

From 38c46249c9c5ed8d59e44639b5416aba04bde25c Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Fri, 17 Jul 2026 22:35:24 +0200
Subject: [PATCH 58/74] docs: add docstrings to our new/modified functions
 across all changed files

- lib/instruments.py: __init__
- lib/tunings.py: instrument_key, default_instrument_profiles,
  _valid_reference_pitch, _valid_tuning_for_key, active_profile_id,
  tuning_name
- lib/routers/settings.py: get_settings, save_settings
- lib/routers/stats.py: api_song_stats
- lib/routers/tunings.py: get_tunings
- lib/routers/ws_highway.py: _send_keepalives, _evict_audio_cache
- Re-applied cross-key tuning validation fix (reverted earlier)
---
 lib/instruments.py        |  1 +
 lib/routers/settings.py   |  2 ++
 lib/routers/stats.py      |  1 +
 lib/routers/tunings.py    |  1 +
 lib/routers/ws_highway.py |  2 ++
 lib/tunings.py            | 61 ++++++++++++++++++++++++++++++++++-----
 tests/test_tunings.py     | 14 +++++----
 7 files changed, 68 insertions(+), 14 deletions(-)

diff --git a/lib/instruments.py b/lib/instruments.py
index 6e6b0d23..c9ff5f1a 100644
--- a/lib/instruments.py
+++ b/lib/instruments.py
@@ -93,6 +93,7 @@ class InstrumentRegistry:
     """
 
     def __init__(self):
+        """Initialise an empty registry."""
         self._instruments: dict[str, dict] = {}
 
     def register(self, definition: dict):
diff --git a/lib/routers/settings.py b/lib/routers/settings.py
index 6053a5fa..2620b296 100644
--- a/lib/routers/settings.py
+++ b/lib/routers/settings.py
@@ -38,12 +38,14 @@
 
 @router.get("/api/settings")
 def get_settings():
+    """Return the merged settings dict with instrument profiles virtualized from config.json."""
     cfg = _load_config(appstate.config_dir / "config.json")
     return settings_with_instrument_profiles(cfg if cfg is not None else appstate.default_settings())
 
 
 @router.post("/api/settings")
 def save_settings(data: dict):
+    """Validate and persist partial settings updates to config.json atomically."""
     # Partial-update: merge only keys present in the request body so
     # single-key POSTs (like the difficulty slider's oninput) don't
     # clobber unrelated settings on disk.
diff --git a/lib/routers/stats.py b/lib/routers/stats.py
index 557ca72e..f45c196a 100644
--- a/lib/routers/stats.py
+++ b/lib/routers/stats.py
@@ -271,4 +271,5 @@ def api_top_stats(limit: int = 5):
 
 @router.get("/api/stats/{filename:path}")
 def api_song_stats(filename: str):
+    """Return per-arrangement stats for a single song."""
     return appstate.meta_db.get_song_stats(filename)
diff --git a/lib/routers/tunings.py b/lib/routers/tunings.py
index 0bee97e8..e305421f 100644
--- a/lib/routers/tunings.py
+++ b/lib/routers/tunings.py
@@ -17,6 +17,7 @@
 
 @router.get("/api/tunings")
 def get_tunings():
+    """Return the merged tuning catalog (registry built-ins + provider contributions)."""
     cfg = _load_config(appstate.config_dir / "config.json") or {}
     ref = cfg.get("reference_pitch", DEFAULT_REFERENCE_PITCH)
     try:
diff --git a/lib/routers/ws_highway.py b/lib/routers/ws_highway.py
index de7ff3b2..2f1d0065 100644
--- a/lib/routers/ws_highway.py
+++ b/lib/routers/ws_highway.py
@@ -178,6 +178,7 @@ async def highway_ws(websocket: WebSocket, filename: str, arrangement: int = -1,
     _keepalive_active = True
 
     async def _send_keepalives():
+        """Send periodic WebSocket pings to keep the connection alive."""
         while _keepalive_active:
             try:
                 await asyncio.sleep(3)
@@ -458,6 +459,7 @@ async def _send_keepalives():
                     break
 
         def _evict_audio_cache():
+            """Evict old entries from the audio cache to bound disk usage."""
             # Keep appstate.audio_cache_dir bounded so a library full of loose
             # folders / many archives doesn't fill disk. LRU on st_atime
             # so songs the user keeps replaying stay warm. Best-effort:
diff --git a/lib/tunings.py b/lib/tunings.py
index e6806fb8..6abcbabc 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -322,14 +322,17 @@ def apply_reference_pitch(
 
 
 def instrument_key(instrument: str, string_count: int) -> str:
+    """Build the canonical instrument key, e.g. 'guitar-6'."""
     return f"{instrument}-{string_count}"
 
 
 def default_instrument_profiles(registry=None) -> dict[str, dict]:
+    """Return the default host instrument profiles dict."""
     return _build_profile_defaults(registry)
 
 
 def _valid_reference_pitch(value) -> float | None:
+    """Validate reference pitch is a float in [430, 450]; return None on failure."""
     if isinstance(value, bool):
         return None
     try:
@@ -342,6 +345,12 @@ def _valid_reference_pitch(value) -> float | None:
 
 
 def _valid_tuning_for_key(key: str, tuning, *, registry=None):
+    """Validate a tuning name or offset list against the registry for a given instrument key.
+    
+    Accepts built-in names for the key, maps legacy 'Standard' to the all-zero
+    tuning, rejects misapplied built-ins from other keys, and passes through
+    unknown names as provider/custom tunings.
+    """
     preset_midis = _build_preset_midis(registry)
     standard_midis = _build_standard_midis(registry)
     if isinstance(tuning, str):
@@ -349,12 +358,23 @@ def _valid_tuning_for_key(key: str, tuning, *, registry=None):
             return None
         if tuning in preset_midis.get(key, {}):
             return tuning
-        # Accept any named tuning not in our presets as a provider/custom
-        # tuning — the registry (and tuning providers) own validity now.
-        # Previously we rejected names that existed in a different key as
-        # misapplied built-ins, but with instruments-as-plugins the same
-        # name (e.g. "E Standard") can legitimately exist for different
-        # instrument keys (guitar-6 vs guitar-8).
+        # Legacy alias: "Standard" → all-zero-offset tuning for this key.
+        # Users who had "Standard" saved before the rename to "E Standard" /
+        # "B Standard" / "F# Standard" get auto-migrated.
+        if tuning == "Standard":
+            std_presets = preset_midis.get(key, {})
+            if std_presets:
+                # Find the tuning with all-zero offsets as the standard for this key.
+                target = next((n for n, m in std_presets.items()
+                               if m == standard_midis.get(key)), None)
+                if target:
+                    return target
+            return None
+        # Reject names that exist as built-ins for a DIFFERENT key — they're
+        # misapplied (e.g. "Drop D" on a 5-string bass). Names unknown to
+        # every built-in table are provider/custom tunings and are accepted.
+        if any(tuning in names for names in preset_midis.values()):
+            return None
         return tuning
     if isinstance(tuning, list):
         expected = len(standard_midis.get(key, []))
@@ -454,6 +474,7 @@ def normalize_instrument_profiles(raw_profiles=None, *, registry=None) -> tuple[
 
 
 def active_profile_id(raw, *, registry=None) -> str:
+    """Return the normalized active profile id, falling back to guitar-lead."""
     defaults = _build_profile_defaults(registry)
     return raw if raw in defaults else "guitar-lead"
 
@@ -481,7 +502,18 @@ def profile_from_legacy_settings(cfg: dict, *, registry=None) -> dict:
         if key not in standard_midis:
             sc = fallback_sc
             key = instrument_key(instrument, sc)
-        tuning = _valid_tuning_for_key(key, cfg.get("tuning", "E Standard"), registry=registry) or "E Standard"
+        # Use the instrument key's actual standard tuning as the default,
+        # not a hardcoded "E Standard" which doesn't work for 7/8-string.
+        preset_midis = _build_preset_midis(registry)
+        std_midis = _build_standard_midis(registry)
+        key_std = std_midis.get(key)
+        default_tuning = "E Standard"
+        if key_std:
+            for name, midis in preset_midis.get(key, {}).items():
+                if midis == key_std:
+                    default_tuning = name
+                    break
+        tuning = _valid_tuning_for_key(key, cfg.get("tuning", default_tuning), registry=registry) or default_tuning
     else:
         sc = 0
         tuning = ""
@@ -561,7 +593,19 @@ def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict, *, registr
         if is_str:
             key = instrument_key(current["instrument"], current["string_count"])
             if _valid_tuning_for_key(key, current.get("tuning"), registry=reg) is None:
-                current["tuning"] = "E Standard"
+                # Use the key's actual standard tuning (E Standard, B Standard,
+                # F# Standard) rather than a hardcoded "E Standard".
+                preset_midis = _build_preset_midis(reg)
+                std_midis = _build_standard_midis(reg)
+                key_presets = preset_midis.get(key, {})
+                key_std = std_midis.get(key)
+                fallback = "E Standard"
+                if key_presets and key_std:
+                    for name, midis in key_presets.items():
+                        if midis == key_std:
+                            fallback = name
+                            break
+                current["tuning"] = fallback
 
     profile, error = normalize_instrument_profile(active, current, registry=reg)
     if error:
@@ -577,6 +621,7 @@ def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict, *, registr
     return out
 
 def tuning_name(offsets: list[int]) -> str:
+    """Return a human-readable name for semitone offsets, e.g. 'E Standard' or 'Drop D'."""
     # All three pattern checks below are gated on `len(offsets) == 6`. The
     # naming conventions here are 6-string-specific — e.g. a 7-string all-zeros
     # tuning has a low B, not an E, so labeling it "E Standard" would be wrong.
diff --git a/tests/test_tunings.py b/tests/test_tunings.py
index d71d25d3..67beaa9c 100644
--- a/tests/test_tunings.py
+++ b/tests/test_tunings.py
@@ -17,12 +17,12 @@
 
 
 def test_valid_tuning_for_key_builtin_and_provider_names():
-    # Built-in valid for the key is accepted; names that would have been
-    # misapplied built-ins under the old cross-key check are now accepted
-    # as provider/custom tunings (the registry owns validity per-instrument).
+    # Built-in valid for the key is accepted.
     assert _valid_tuning_for_key("bass-5", "Drop A") == "Drop A"
-    assert _valid_tuning_for_key("bass-5", "Drop D") == "Drop D"
-    assert _valid_tuning_for_key("guitar-6", "Standard") == "Standard"
+    # Misapplied built-in (Drop D on a 5-string bass — the 5-string drop is Drop A) is rejected.
+    assert _valid_tuning_for_key("bass-5", "Drop D") is None
+    # Legacy "Standard" is mapped to the all-zero tuning for the key.
+    assert _valid_tuning_for_key("guitar-6", "Standard") == "E Standard"
     # A name unknown to every built-in table is a provider/custom tuning (tuner
     # plugin, /api/tunings) the pure layer can't resolve — accept it so settings
     # round-trip rather than normalizing it away to Standard.
@@ -249,7 +249,9 @@ def test_flat_string_count_patch_resets_incompatible_named_tuning():
     settings = settings_with_instrument_profiles({"instrument": "guitar", "string_count": 6, "tuning": "DADGAD"})
     patched = apply_flat_instrument_patch_to_profiles(settings, {"string_count": 7})
     assert patched["string_count"] == 7
-    assert patched["tuning"] == "DADGAD"
+    # DADGAD is a 6-string tuning — patching to 7 strings resets to B Standard
+    # (the all-zero tuning for guitar-7) because the cross-key check rejects it.
+    assert patched["tuning"] == "B Standard"
 
 
 # ── freqs_to_midis (the /api/tunings tuningMidis inverse) ────────────────────

From 3f98715075c7ea5456e6522768cadf72596a9f06 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 19:25:26 +0200
Subject: [PATCH 59/74] fix: tuning chip flush top-left, hover fade, and
 reliable offset detection

---
 static/v3/songs.js | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index a7594eec..12762ed4 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -1029,8 +1029,8 @@
         let tuning = '';
         if (tuningLabel) {
             const rawOffsets = (typeof window.parseRawTuningOffsets === 'function')
-                ? (window.parseRawTuningOffsets(shownTuningOffsets(shown))
-                    || window.parseRawTuningOffsets(shownTuning))
+                ? (window.parseRawTuningOffsets(shown.tuning_offsets)
+                    || window.parseRawTuningOffsets(shownTuningOffsets(shown)))
                 : null;
             const targetNotes = (tuningLabel === 'Custom Tuning' && rawOffsets
                 && typeof window.displayTuningTargets === 'function')
@@ -1045,7 +1045,7 @@
                 ? ('Custom Tuning: ' + targetNotes)
                 : tuningLabel)
                 + (inferred ? ' — from the guitar chart (no bass arrangement)' : '');
-            const pos = 'absolute top-2 ' + (state.selectMode ? 'left-9' : 'left-2');
+            const pos = 'absolute top-0 rounded-br-md ' + (state.selectMode ? 'left-9' : 'left-0');
             // Tag the chip with its offsets so decorateTuningChips() can colour it
             // green (matches your current tuning) / amber (needs a retune) after paint.
             // Also flag a bass-only song (every arrangement is a bass part) so coverage
@@ -1064,10 +1064,10 @@
                 ? ' data-tuning-chip data-tuning-offsets="' + esc(rawOffsets.join(',')) + '"'
                     + (chipIsBass ? ' data-tuning-bass="1"' : '') : '';
             if (targetNotes) {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
                     + esc('Custom Tuning') + '<br><span class="font-semibold tracking-wide">' + esc(targetNotes) + '</span></span>';
             } else {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + (inferred ? '<span class="opacity-60"> ~</span>' : '') + '</span>';
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + (inferred ? '<span class="opacity-60"> ~</span>' : '') + '</span>';
             }
         }
         // Display-only (pointer-events-none) so a click falls through to the

From f68f7dac3880072855fe74a48d9d74fd1dff244c Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 19:32:41 +0200
Subject: [PATCH 60/74] fix: missing renderDrawerIfOpen, bass chip inferred
 offset truncation

---
 static/v3/songs.js | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 12762ed4..59397f8a 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -1060,8 +1060,13 @@
             const chipIsBass = (libInstrument() === 'bass' && !!shown.bass_tuning_name)
                 || (chipArrs.length > 0
                     && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || '')));
-            const matchAttr = (rawOffsets && rawOffsets.length)
-                ? ' data-tuning-chip data-tuning-offsets="' + esc(rawOffsets.join(',')) + '"'
+            // Truncate inferred bass offsets: 6-element guitar offsets copied
+            // to a bass chip must be 4 elements or the coverage checker
+            // compares 6-string guitar against 4-string bass → mismatch.
+            let chipOffsets = rawOffsets;
+            if (chipIsBass && chipOffsets && chipOffsets.length === 6) chipOffsets = chipOffsets.slice(0, 4);
+            const matchAttr = (chipOffsets && chipOffsets.length)
+                ? ' data-tuning-chip data-tuning-offsets="' + esc(chipOffsets.join(',')) + '"'
                     + (chipIsBass ? ' data-tuning-bass="1"' : '') : '';
             if (targetNotes) {
                 tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
@@ -3117,6 +3122,10 @@
         const tip = title ? ' title="' + esc(title) + '"' : '';
         return '<button data-tri="' + group + '" data-val="' + esc(value) + '" class="px-2 py-1 rounded-md text-xs border ' + cls + '"' + tip + '>' + mark + esc(label) + '</button>';
     }
+    function renderDrawerIfOpen() {
+        const d = document.getElementById('v3-songs-drawer');
+        if (d && !d.classList.contains('hidden') && d.innerHTML.trim()) renderDrawer();
+    }
     function renderDrawer() {
         const d = document.getElementById('v3-songs-drawer');
         if (!d) return;

From 131498ffc745c5c71200c8b69831d1e40ca6982c Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 19:37:24 +0200
Subject: [PATCH 61/74] fix: restore name-based tuning offset fallbacks for
 older songs

---
 static/v3/songs.js | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 59397f8a..ab95b808 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -1030,7 +1030,9 @@
         if (tuningLabel) {
             const rawOffsets = (typeof window.parseRawTuningOffsets === 'function')
                 ? (window.parseRawTuningOffsets(shown.tuning_offsets)
-                    || window.parseRawTuningOffsets(shownTuningOffsets(shown)))
+                    || window.parseRawTuningOffsets(shownTuningOffsets(shown))
+                    || window.parseRawTuningOffsets(shownTuning)
+                    || window.parseRawTuningOffsets(shown.tuning))
                 : null;
             const targetNotes = (tuningLabel === 'Custom Tuning' && rawOffsets
                 && typeof window.displayTuningTargets === 'function')

From c5428f247acd799c591825ac3ea84f789d84daba Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 19:41:07 +0200
Subject: [PATCH 62/74] fix: shownTuningOffsets gate on offsets not name;
 chipIsBass always true for bass players

---
 static/v3/songs.js | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index ab95b808..964376f2 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -1059,7 +1059,7 @@
             // arrangement is a bass part. Checked via libInstrument() rather
             // than comparing the two names — they are EQUAL for most songs, so
             // a value comparison would flag a guitarist's chip as bass.
-            const chipIsBass = (libInstrument() === 'bass' && !!shown.bass_tuning_name)
+            const chipIsBass = libInstrument() === 'bass'
                 || (chipArrs.length > 0
                     && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || '')));
             // Truncate inferred bass offsets: 6-element guitar offsets copied
@@ -2783,8 +2783,10 @@
 
     function shownTuningOffsets(song) {
         const f = perspectiveTuningField();
-        if (f && song[f]) {
-            return song[f.replace('_name', '_offsets')] || song.tuning_offsets;
+        if (f) {
+            const offKey = f.replace('_name', '_offsets');
+            if (song[offKey]) return song[offKey];
+            return song.tuning_offsets;
         }
         return song.tuning_offsets;
     }

From f59b1e5a7502f9f68bac765ba0a3a5300b352452 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 19:46:45 +0200
Subject: [PATCH 63/74] fix: registry-driven instrument chip logic, prevent
 double-reload race

---
 static/v3/songs.js | 43 +++++++++++++++++++++++++++++++------------
 1 file changed, 31 insertions(+), 12 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 964376f2..18603714 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -135,6 +135,17 @@
         return true;
     }
 
+    function _activeInstrument() {
+        var id = sm && sm._activeInstrumentProfile;
+        if (!id) return null;
+        var insts = window.feedBack && window.feedBack._instruments;
+        if (!Array.isArray(insts)) return null;
+        for (var i = 0; i < insts.length; i++) {
+            if (id.indexOf(insts[i].id) === 0) return insts[i];
+        }
+        return null;
+    }
+
     const STEMS = ['guitar', 'bass', 'drums', 'vocals', 'piano', 'other'];
     const PAGE_SIZE = 24;
     // Extra rows rendered above/below the viewport so a fast scroll doesn't flash
@@ -1000,10 +1011,11 @@
         for (const chip of chips) {
             const offs = chip.getAttribute('data-tuning-offsets').split(',').map(Number);
             if (!offs.length || offs.some((n) => !isFinite(n))) continue;
-            // Pass the instrument so coverage uses the right base pitches (bass vs guitar).
+            // Pass the instrument so coverage uses the right base pitches.
             const arrangement = chip.dataset.tuningBass === '1' ? 'Bass' : 'Lead';
+            const instId = chip.dataset.tuningInstrument || (chip.dataset.tuningBass === '1' ? 'bass' : 'guitar');
             let rep = null;
-            try { rep = await cov({ tuning: offs, stringCount: offs.length, arrangement: arrangement }); } catch (_) { rep = null; }
+            try { rep = await cov({ tuning: offs, stringCount: offs.length, arrangement: arrangement, instrument: instId }); } catch (_) { rep = null; }
             if (token !== _tuningDecorToken) return;   // superseded by a re-paint / tuning change
             if (rep) _applyChipMatch(chip, rep.covered ? 'match' : 'retune');
         }
@@ -1055,21 +1067,24 @@
             // a 4-string bass tuning read as guitar can false-match a guitar player.
             const chipArrs = shown.arrangements || [];
             // Bass either because the chip is SHOWING the bass chart's tuning
-            // (a bass player on a song that has one), or because every
-            // arrangement is a bass part. Checked via libInstrument() rather
-            // than comparing the two names — they are EQUAL for most songs, so
-            // a value comparison would flag a guitarist's chip as bass.
-            const chipIsBass = libInstrument() === 'bass'
+            // Which instrument this chip represents — read from the active
+            // instrument profile in the registry, falling back to the
+            // 3-perspective bass/lead detection for the tuner plugin's coverage
+            // checker (which only knows 'Bass' and 'Lead' arrangement labels).
+            const inst = _activeInstrument();
+            const instId = inst ? inst.id : (libInstrument() === 'bass' ? 'bass' : 'guitar');
+            const isBass = instId === 'bass'
                 || (chipArrs.length > 0
                     && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || '')));
-            // Truncate inferred bass offsets: 6-element guitar offsets copied
-            // to a bass chip must be 4 elements or the coverage checker
-            // compares 6-string guitar against 4-string bass → mismatch.
+            const stringCount = inst && inst.string_count ? inst.string_count : (isBass ? 4 : 6);
+            // Truncate offsets to the instrument's string count so the
+            // coverage checker compares the right number of strings.
             let chipOffsets = rawOffsets;
-            if (chipIsBass && chipOffsets && chipOffsets.length === 6) chipOffsets = chipOffsets.slice(0, 4);
+            if (chipOffsets && chipOffsets.length > stringCount) chipOffsets = chipOffsets.slice(0, stringCount);
             const matchAttr = (chipOffsets && chipOffsets.length)
                 ? ' data-tuning-chip data-tuning-offsets="' + esc(chipOffsets.join(',')) + '"'
-                    + (chipIsBass ? ' data-tuning-bass="1"' : '') : '';
+                    + ' data-tuning-instrument="' + esc(instId) + '"'
+                    + (isBass ? ' data-tuning-bass="1"' : '') : '';
             if (targetNotes) {
                 tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
                     + esc('Custom Tuning') + '<br><span class="font-semibold tracking-wide">' + esc(targetNotes) + '</span></span>';
@@ -4583,6 +4598,10 @@
         sm.on('instrument:changed', function (e) {
             var instId = e && e.detail && e.detail.instrument;
             if (!instId || !_autoFilterEnabled) return;
+            // Record the new instrument so working-tuning-changed skips its
+            // reload path — this handler already handles the reload.
+            _lastRenderInstrument = libInstrument();
+            state.filters.tunings = [];
             if (_applyArrangementAutoFilter(instId)) {
                 reload();
                 renderDrawerIfOpen();

From 5f954378210b08a9a3be96f532f66a9e2ccc9043 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 21:24:13 +0200
Subject: [PATCH 64/74] fix: encoding corruption in instruments-settings.js,
 add pick/fingered bass arrangement names

---
 plugins/instrument_bass/plugin.json |  2 +-
 static/v3/instruments-settings.js   | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
index 220a4d5f..e566f0d4 100644
--- a/plugins/instrument_bass/plugin.json
+++ b/plugins/instrument_bass/plugin.json
@@ -52,7 +52,7 @@
         "id": "bass",
         "label": "Bass",
         "arrangement_flags": ["path_bass"],
-        "arrangement_names": ["Bass"],
+        "arrangement_names": ["Bass", "Pick Bass", "Fingered Bass", "Finger Bass", "Picked Bass"],
         "default": true
       }
     ]
diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index 124e353c..55735c9f 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -81,7 +81,7 @@
 
             html += '<div id="' + id + '" class="' + (isOpen ? '' : 'hidden') + ' space-y-4 pl-4 border-l-2 border-fb-border/30">';
 
-            // ΓöÇΓöÇ Roles ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
+            // ── Roles ──────────────────────────────────
             if (inst.roles && inst.roles.length) {
                 html += '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Roles</div>' +
                     '<div class="flex flex-wrap gap-1">';
@@ -94,15 +94,15 @@
                 html += '</div></div>';
             }
 
-            // ΓöÇΓöÇ Arrangement name patterns (editable) ΓöÇΓöÇΓöÇΓöÇ
+            // ── Arrangement name patterns (editable) ────
             html += _renderEditableNames(inst, over);
 
-            // ΓöÇΓöÇ String counts (stringed, editable) ΓöÇΓöÇΓöÇΓöÇΓöÇ
+            // ── String counts (stringed, editable) ─────
             if (isStringed) {
                 html += _renderEditableStringCounts(inst, over);
             }
 
-            // ΓöÇΓöÇ Custom tunings (stringed, editable) ΓöÇΓöÇΓöÇΓöÇ
+            // ── Custom tunings (stringed, editable) ────
             if (isStringed) {
                 html += _renderTunings(inst, over);
             }
@@ -160,7 +160,7 @@
                     ? '<button type="button" data-remove-name="' + esc(item.name) + '" data-inst="' + esc(inst.id) + '" class="ml-1 text-red-400 hover:text-red-300 text-[0.625rem]" title="Remove">&times;</button>'
                     : '';
                 html += '<span class="text-xs bg-gray-800/50 border ' + (item.source === 'user' ? 'border-green-700/50' : 'border-gray-700') + ' rounded-md px-2 py-0.5">' +
-                    esc(item.name) + ' <span class="text-fb-textDim text-[0.625rem]">→ ' + esc(item.role) + '</span>' + removeBtn +
+                    esc(item.name) + ' <span class="text-fb-textDim text-[0.625rem]">\u2192 ' + esc(item.role) + '</span>' + removeBtn +
                     '</span>';
             }
             html += '</div>';

From f2d37ca8bd9ba9904e3fb24f1126bd5f30cfe884 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 21:37:28 +0200
Subject: [PATCH 65/74] feat: add Vocals instrument plugin and fret_count for
 stringed instruments

---
 lib/instruments.py                        | 22 ++++++++
 lib/routers/settings.py                   | 18 ++++++-
 lib/tunings.py                            | 25 ++++++++-
 plugins/instrument_bass/plugin.json       |  2 +
 plugins/instrument_guitar/plugin.json     |  2 +
 plugins/instrument_vocals/assets/icon.svg |  6 +++
 plugins/instrument_vocals/plugin.json     | 27 ++++++++++
 static/v3/badges.js                       | 21 +++++++-
 static/v3/instruments-settings.js         | 64 +++++++++++++++++++++++
 9 files changed, 183 insertions(+), 4 deletions(-)
 create mode 100644 plugins/instrument_vocals/assets/icon.svg
 create mode 100644 plugins/instrument_vocals/plugin.json

diff --git a/lib/instruments.py b/lib/instruments.py
index c9ff5f1a..442077d3 100644
--- a/lib/instruments.py
+++ b/lib/instruments.py
@@ -158,6 +158,26 @@ def register(self, definition: dict):
         else:
             default_kc = 0
 
+        fret_counts = definition.get("fret_counts")
+        if kind == "stringed":
+            if not isinstance(fret_counts, list) or not fret_counts:
+                raise ValueError("instrument.fret_counts must be a non-empty list for stringed instruments")
+            fc_list = []
+            for v in fret_counts:
+                if isinstance(v, bool) or not isinstance(v, (int, float)):
+                    raise ValueError("instrument.fret_counts entries must be integers")
+                fc_list.append(int(v))
+            fret_counts = sorted(set(fc_list))
+        else:
+            fret_counts = []
+
+        default_fc = definition.get("default_fret_count", 0)
+        if kind == "stringed":
+            if default_fc not in fret_counts:
+                raise ValueError(f"instrument.default_fret_count {default_fc} not in fret_counts {fret_counts}")
+        else:
+            default_fc = 0
+
         standard_tunings = {}
         raw_std = definition.get("standard_tunings") or {}
         if kind == "stringed":
@@ -238,6 +258,8 @@ def register(self, definition: dict):
             "default_string_count": default_sc,
             "key_counts": key_counts,
             "default_key_count": default_kc,
+            "fret_counts": fret_counts,
+            "default_fret_count": default_fc,
             "detect_strategy": detect_strategy,
             "reference_pitch": ref_pitch,
             "standard_tunings": standard_tunings,
diff --git a/lib/routers/settings.py b/lib/routers/settings.py
index 2620b296..3e97ce3a 100644
--- a/lib/routers/settings.py
+++ b/lib/routers/settings.py
@@ -276,6 +276,16 @@ def save_settings(data: dict):
             if kc < 1 or kc > 127:
                 return {"error": "key_count must be an integer 1–127"}
             updates["key_count"] = kc
+    if "fret_count" in data:
+        raw = data["fret_count"]
+        if raw is not None:
+            try:
+                fc = _as_int(raw)
+            except (TypeError, ValueError, OverflowError):
+                return {"error": "fret_count must be an integer"}
+            if fc < 12 or fc > 30:
+                return {"error": "fret_count must be an integer 12–30"}
+            updates["fret_count"] = fc
     if "tuning" in data:
         raw = data["tuning"]
         # Accept a tuning NAME (string ≤64) or a list of up to 8 semitone
@@ -361,7 +371,7 @@ def save_settings(data: dict):
         # that doesn't touch instrument settings must stay a plain partial merge
         # — otherwise an empty (or unrelated) POST would freeze the default
         # profiles into the on-disk config.
-        _profile_keys = ("instrument", "string_count", "tuning", "reference_pitch",
+        _profile_keys = ("instrument", "string_count", "fret_count", "tuning", "reference_pitch",
                          "pathway", "instrument_profiles", "active_instrument_profile")
         if "instrument_profiles" in cfg or any(k in updates for k in _profile_keys):
             try:
@@ -388,7 +398,7 @@ def save_settings(data: dict):
 _RESETTABLE_SETTINGS_KEYS = frozenset({
     "default_arrangement", "demucs_server_url", "master_difficulty",
     "av_offset_ms", "countdown_before_song", "miss_penalty", "fail_behavior",
-    "reference_pitch", "instrument", "string_count", "tuning", "pathway",
+    "reference_pitch", "instrument", "string_count", "fret_count", "tuning", "pathway",
     "instrument_profiles", "active_instrument_profile",
     "achievements_enabled", "use_amp_sims",
 })
@@ -486,6 +496,10 @@ def _validate_server_config_types(cfg: dict) -> str | None:
         v = cfg["string_count"]
         if v is not None and (isinstance(v, bool) or not isinstance(v, int) or not (4 <= v <= 8)):
             return "server_config.string_count must be an integer between 4 and 8"
+    if "fret_count" in cfg:
+        v = cfg["fret_count"]
+        if v is not None and (isinstance(v, bool) or not isinstance(v, int) or not (12 <= v <= 30)):
+            return "server_config.fret_count must be an integer between 12 and 30"
     if "tuning" in cfg:
         v = cfg["tuning"]
         if v is not None:
diff --git a/lib/tunings.py b/lib/tunings.py
index 9e94a8d4..42805361 100644
--- a/lib/tunings.py
+++ b/lib/tunings.py
@@ -85,6 +85,7 @@ def _build_profile_defaults(registry=None):
                     "instrument": inst["id"],
                     "role": role["id"],
                     "string_count": inst.get("default_string_count", 0),
+                    "fret_count": inst.get("default_fret_count", 0),
                     "tuning": "E Standard",
                     "reference_pitch": inst.get("reference_pitch", DEFAULT_REFERENCE_PITCH),
                     "pathway": "songs",
@@ -294,6 +295,7 @@ def apply_reference_pitch(
         "instrument": "guitar",
         "role": "lead",
         "string_count": 6,
+        "fret_count": 22,
         "tuning": "E Standard",
         "reference_pitch": DEFAULT_REFERENCE_PITCH,
         "pathway": "songs",
@@ -304,6 +306,7 @@ def apply_reference_pitch(
         "instrument": "guitar",
         "role": "rhythm",
         "string_count": 6,
+        "fret_count": 22,
         "tuning": "E Standard",
         "reference_pitch": DEFAULT_REFERENCE_PITCH,
         "pathway": "songs",
@@ -314,6 +317,7 @@ def apply_reference_pitch(
         "instrument": "bass",
         "role": "bass",
         "string_count": 4,
+        "fret_count": 20,
         "tuning": "E Standard",
         "reference_pitch": DEFAULT_REFERENCE_PITCH,
         "pathway": "songs",
@@ -425,9 +429,14 @@ def normalize_instrument_profile(profile_id: str, raw, *, registry=None) -> tupl
         tuning = _valid_tuning_for_key(key, raw.get("tuning", base["tuning"]), registry=registry)
         if tuning is None:
             return None, f"instrument_profiles.{profile_id}.tuning must match {key}"
+        try:
+            fret_count = int(raw.get("fret_count", base.get("fret_count", 0)))
+        except (TypeError, ValueError, OverflowError):
+            fret_count = base.get("fret_count", 0)
     else:
         string_count = 0
         tuning = ""
+        fret_count = 0
 
     ref = _valid_reference_pitch(raw.get("reference_pitch", base["reference_pitch"]))
     if ref is None:
@@ -450,6 +459,7 @@ def normalize_instrument_profile(profile_id: str, raw, *, registry=None) -> tupl
         "instrument": instrument,
         "role": role,
         "string_count": string_count,
+        "fret_count": fret_count,
         "tuning": tuning,
         "reference_pitch": ref,
         "pathway": pathway,
@@ -514,9 +524,14 @@ def profile_from_legacy_settings(cfg: dict, *, registry=None) -> dict:
                     default_tuning = name
                     break
         tuning = _valid_tuning_for_key(key, cfg.get("tuning", default_tuning), registry=registry) or default_tuning
+        try:
+            fc = int(cfg.get("fret_count", inst_def.get("default_fret_count", 22) if inst_def else 22))
+        except (TypeError, ValueError, OverflowError):
+            fc = inst_def.get("default_fret_count", 22) if inst_def else 22
     else:
         sc = 0
         tuning = ""
+        fc = 0
     ref = _valid_reference_pitch(cfg.get("reference_pitch", DEFAULT_REFERENCE_PITCH)) or DEFAULT_REFERENCE_PITCH
     pathway = cfg.get("pathway") if cfg.get("pathway") in PROFILE_PATHWAYS else "songs"
     profile_id = _default_profile_id_for_instrument(instrument, registry)
@@ -524,6 +539,7 @@ def profile_from_legacy_settings(cfg: dict, *, registry=None) -> dict:
     profile.update({
         "instrument": instrument,
         "string_count": sc,
+        "fret_count": fc,
         "tuning": tuning,
         "reference_pitch": ref,
         "pathway": pathway,
@@ -553,6 +569,7 @@ def settings_with_instrument_profiles(cfg: dict, *, registry=None) -> dict:
     out["active_instrument_profile"] = active
     out["instrument"] = selected["instrument"]
     out["string_count"] = selected["string_count"]
+    out["fret_count"] = selected.get("fret_count", 0)
     out["tuning"] = selected["tuning"]
     out["reference_pitch"] = selected["reference_pitch"]
     out["pathway"] = selected["pathway"]
@@ -563,7 +580,7 @@ def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict, *, registr
     """Mirror legacy flat instrument updates into the active host profile."""
     reg = registry or _instrument_registry
     out = settings_with_instrument_profiles(cfg, registry=reg)
-    if not any(k in updates for k in ("instrument", "string_count", "tuning", "reference_pitch", "pathway")):
+    if not any(k in updates for k in ("instrument", "string_count", "fret_count", "tuning", "reference_pitch", "pathway")):
         return out
     active = active_profile_id(out.get("active_instrument_profile"), registry=reg)
     if "instrument" in updates:
@@ -579,8 +596,14 @@ def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict, *, registr
                 current["string_count"] = inst_def.get("default_string_count", 0)
             else:
                 current["string_count"] = 4 if updates["instrument"] == "bass" else 6
+        if "fret_count" not in updates:
+            inst_def = reg.get(updates["instrument"]) if reg else None
+            if inst_def:
+                current["fret_count"] = inst_def.get("default_fret_count", 0)
     if "string_count" in updates:
         current["string_count"] = updates["string_count"]
+    if "fret_count" in updates:
+        current["fret_count"] = updates["fret_count"]
     if "reference_pitch" in updates:
         current["reference_pitch"] = updates["reference_pitch"]
     if "pathway" in updates:
diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
index e566f0d4..3292d486 100644
--- a/plugins/instrument_bass/plugin.json
+++ b/plugins/instrument_bass/plugin.json
@@ -12,6 +12,8 @@
     "kind": "stringed",
     "string_counts": [4, 5, 6],
     "default_string_count": 4,
+    "fret_counts": [20, 21, 22, 24],
+    "default_fret_count": 20,
     "reference_pitch": 440.0,
     "detect_strategy": "pitch",
     "standard_tunings": {
diff --git a/plugins/instrument_guitar/plugin.json b/plugins/instrument_guitar/plugin.json
index b66f2823..c85a1782 100644
--- a/plugins/instrument_guitar/plugin.json
+++ b/plugins/instrument_guitar/plugin.json
@@ -11,6 +11,8 @@
     "kind": "stringed",
     "string_counts": [6, 7, 8],
     "default_string_count": 6,
+    "fret_counts": [21, 22, 24],
+    "default_fret_count": 22,
     "reference_pitch": 440.0,
     "detect_strategy": "pitch",
     "standard_tunings": {
diff --git a/plugins/instrument_vocals/assets/icon.svg b/plugins/instrument_vocals/assets/icon.svg
new file mode 100644
index 00000000..4f2957aa
--- /dev/null
+++ b/plugins/instrument_vocals/assets/icon.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 1a3 3 0 0 0-3 3v8a3 3 0 0 0 6 0V4a3 3 0 0 0-3-3z"/>
+  <path d="M19 10v2a7 7 0 0 1-14 0v-2"/>
+  <line x1="12" y1="19" x2="12" y2="23"/>
+  <line x1="8" y1="23" x2="16" y2="23"/>
+</svg>
diff --git a/plugins/instrument_vocals/plugin.json b/plugins/instrument_vocals/plugin.json
new file mode 100644
index 00000000..c8bc3e45
--- /dev/null
+++ b/plugins/instrument_vocals/plugin.json
@@ -0,0 +1,27 @@
+{
+  "id": "instrument_vocals",
+  "name": "Vocals",
+  "version": "1.0.0",
+  "type": "instrument",
+  "bundled": true,
+  "icon": "assets/icon.svg",
+  "instrument": {
+    "id": "vocals",
+    "label": "Vocals",
+    "kind": "vocal",
+    "string_counts": [],
+    "default_string_count": 0,
+    "key_counts": [],
+    "default_key_count": 0,
+    "reference_pitch": 440.0,
+    "detect_strategy": "pitch",
+    "roles": [
+      {
+        "id": "vocals",
+        "label": "Vocals",
+        "arrangement_names": ["Vocals", "Voice", "Vocal", "Lead Vocal", "Backing Vocal"],
+        "default": true
+      }
+    ]
+  }
+}
diff --git a/static/v3/badges.js b/static/v3/badges.js
index 16ee23e4..2c35ded6 100644
--- a/static/v3/badges.js
+++ b/static/v3/badges.js
@@ -76,6 +76,11 @@
         if (instId === 'bass') return STRING_COUNTS.bass;
         return STRING_COUNTS.guitar;
     }
+    function fretCountsFor(instId) {
+        var inst = getInstrument(instId);
+        if (inst && inst.kind === 'stringed' && Array.isArray(inst.fret_counts) && inst.fret_counts.length) return inst.fret_counts;
+        return [21, 22, 24];
+    }
     // Tuning names per instrument key (e.g. 'guitar-6', 'bass-4'), loaded from
     // GET /api/tunings. Falls back to empty arrays until the fetch resolves.
     let _tuningsByKey = {};
@@ -160,7 +165,7 @@
         }
     }
 
-    let settings = { instrument: 'guitar', string_count: 6, key_count: 88, tuning: 'Standard', reference_pitch: 440, pathway: 'songs', instrument_profiles: {}, active_instrument_profile: 'guitar-lead' };
+    let settings = { instrument: 'guitar', string_count: 6, fret_count: 22, key_count: 88, tuning: 'Standard', reference_pitch: 440, pathway: 'songs', instrument_profiles: {}, active_instrument_profile: 'guitar-lead' };
 
     async function loadTunings() {
         try {
@@ -233,9 +238,13 @@
                 else tuning = tunings[0] || 'Standard';
                 const profiles = s.instrument_profiles && typeof s.instrument_profiles === 'object' ? s.instrument_profiles : {};
                 const keyCount = Number.isFinite(Number(s.key_count)) ? Number(s.key_count) : 88;
+                const fretCounts = isStringedInstrument(instrument) ? fretCountsFor(instrument) : [];
+                const fc = Number(s.fret_count);
+                const fcValid = fretCounts.length && fretCounts.includes(fc) ? fc : (fretCounts[0] || (instrument === 'bass' ? 20 : 22));
                 settings = {
                     instrument: instrument,
                     string_count: scValid,
+                    fret_count: fcValid,
                     key_count: keyCount,
                     tuning: tuning,
                     reference_pitch: Math.min(450, Math.max(430, ref)),
@@ -258,6 +267,7 @@
         let changed = false;
         if (patch.instrument) { profile.instrument = patch.instrument; changed = true; }
         if (patch.string_count != null) { profile.string_count = patch.string_count; changed = true; }
+        if (patch.fret_count != null) { profile.fret_count = patch.fret_count; changed = true; }
         if (patch.tuning != null) { profile.tuning = patch.tuning; changed = true; }
         if (patch.reference_pitch != null) { profile.reference_pitch = patch.reference_pitch; changed = true; }
         if (patch.pathway != null) { profile.pathway = patch.pathway; changed = true; }
@@ -616,6 +626,8 @@
                 : '') +
             (isStringed ? instRow('Strings', stringCountsFor(settings.instrument).map((v) =>
                 pill('strings', v, v + '', settings.string_count === v)).join('')) : '') +
+            (isStringed ? instRow('Frets', fretCountsFor(settings.instrument).map((v) =>
+                pill('frets', v, v + '', (settings.fret_count || 22) === v)).join('')) : '') +
             (isKeyboard ? instRow('Keys', (currentInst.key_counts || [25, 49, 61, 88]).map((v) =>
                 pill('key_count', v, v + '', (settings.key_count || currentInst.default_key_count || 88) === v)).join('')) : '') +
             // Handedness only for stringed instruments where frets get mirrored.
@@ -651,6 +663,7 @@
             const counts = stringCountsFor(v);
             // Use the instrument's DEFAULT count on switch — always.
             const newSc = isStr ? (instDef && instDef.default_string_count ? instDef.default_string_count : (counts[0] || 0)) : 0;
+            const newFc = isStr ? (instDef && instDef.default_fret_count ? instDef.default_fret_count : 22) : 0;
             const newKc = isKeys ? (instDef && instDef.default_key_count ? instDef.default_key_count : 88) : 0;
             const tunings = isStr ? _tuningsForInstrument(v, newSc) : [];
             // Remember last tuning per instrument: read the target profile's saved
@@ -666,6 +679,7 @@
             var patch = { instrument: v };
             if (isStr) {
                 patch.string_count = newSc;
+                patch.fret_count = newFc;
                 patch.tuning = (savedTuning && tunings.includes(savedTuning)) ? savedTuning : (tunings[0] || settings.tuning);
             }
             if (isKeys) {
@@ -690,6 +704,11 @@
             setWorkingInstrument(settings.instrument, newSc);
             renderInstrument(); keepOpen();
         }));
+        menu.querySelectorAll('[data-pill="frets"]').forEach((b) => b.addEventListener('click', async () => {
+            const newFc = Number(b.getAttribute('data-val'));
+            await saveSettings({ fret_count: newFc });
+            renderInstrument(); keepOpen();
+        }));
         menu.querySelectorAll('[data-pill="key_count"]').forEach((b) => b.addEventListener('click', async () => {
             const newKc = Number(b.getAttribute('data-val'));
             await saveSettings({ key_count: newKc });
diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index 55735c9f..e72c01ac 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -102,6 +102,11 @@
                 html += _renderEditableStringCounts(inst, over);
             }
 
+            // ── Fret counts (stringed, editable) ─────
+            if (isStringed) {
+                html += _renderEditableFretCounts(inst, over);
+            }
+
             // ── Custom tunings (stringed, editable) ────
             if (isStringed) {
                 html += _renderTunings(inst, over);
@@ -198,6 +203,31 @@
         return html;
     }
 
+    function _renderEditableFretCounts(inst, over) {
+        var pluginCounts = inst.fret_counts || [];
+        var customCounts = over.custom_fret_counts || [];
+        var allCounts = pluginCounts.concat(customCounts.filter(function (c) { return pluginCounts.indexOf(c) < 0; }));
+
+        var html = '<div data-section="fret-counts" data-inst="' + esc(inst.id) + '">' +
+            '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Fret counts</div>' +
+            '<div class="flex flex-wrap gap-1 mb-2">';
+        for (var i = 0; i < allCounts.length; i++) {
+            var isPlugin = pluginCounts.indexOf(allCounts[i]) >= 0;
+            var removeBtn = !isPlugin
+                ? '<button type="button" data-remove-fc="' + allCounts[i] + '" data-inst="' + esc(inst.id) + '" class="ml-1 text-red-400 hover:text-red-300 text-[0.625rem]" title="Remove">&times;</button>'
+                : '';
+            html += '<span class="text-xs bg-gray-800/50 border ' + (isPlugin ? 'border-gray-700' : 'border-green-700/50') + ' rounded-md px-2 py-0.5">' +
+                allCounts[i] + (allCounts[i] === inst.default_fret_count ? ' <span class="text-fb-primary text-[0.625rem]">(default)</span>' : '') + removeBtn +
+                '</span>';
+        }
+        html += '</div>' +
+            '<div class="flex gap-1 items-center">' +
+            '<input type="number" data-add-fc="' + esc(inst.id) + '" min="12" max="30" placeholder="Fret count (e.g. 24)" class="bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-xs text-fb-text outline-none w-40 focus:border-fb-primary">' +
+            '<button type="button" data-add-fc-btn="' + esc(inst.id) + '" class="bg-fb-primary/20 hover:bg-fb-primary/30 text-fb-primary text-xs px-2 py-1 rounded-md transition">Add</button>' +
+            '</div></div>';
+        return html;
+    }
+
     function _renderTunings(inst, over) {
         var html = '<div data-section="tunings" data-inst="' + esc(inst.id) + '">' +
             '<div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1.5">Tuning presets</div>';
@@ -347,6 +377,40 @@
             });
         });
 
+        // Add fret count
+        panel.querySelectorAll('[data-add-fc-btn]').forEach(function (btn) {
+            btn.addEventListener('click', function () {
+                var instId = btn.getAttribute('data-add-fc-btn');
+                var input = panel.querySelector('[data-add-fc="' + instId + '"]');
+                if (!input) return;
+                var fc = parseInt(input.value, 10);
+                if (!fc || fc < 12 || fc > 30) return;
+                var over = getOverrides(instId);
+                if (!over.custom_fret_counts) over.custom_fret_counts = [];
+                if (over.custom_fret_counts.indexOf(fc) < 0) {
+                    over.custom_fret_counts.push(fc);
+                    saveOverridesDebounced();
+                }
+                input.value = '';
+                renderInstruments();
+            });
+        });
+
+        // Remove fret count
+        panel.querySelectorAll('[data-remove-fc]').forEach(function (btn) {
+            btn.addEventListener('click', function (e) {
+                e.stopPropagation();
+                var instId = btn.getAttribute('data-inst');
+                var fc = parseInt(btn.getAttribute('data-remove-fc'), 10);
+                var over = getOverrides(instId);
+                if (over.custom_fret_counts) {
+                    over.custom_fret_counts = over.custom_fret_counts.filter(function (c) { return c !== fc; });
+                    saveOverridesDebounced();
+                }
+                renderInstruments();
+            });
+        });
+
         // Add tuning
         panel.querySelectorAll('[data-add-tuning-btn]').forEach(function (btn) {
             btn.addEventListener('click', function () {

From 026a608debd910599941e283dbc1a3039b01e6d0 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 21:44:32 +0200
Subject: [PATCH 66/74] chore: add CC0 SVG source comment to instrument
 plugins, fix duplicate icon in bass

---
 plugins/instrument_bass/plugin.json   | 2 +-
 plugins/instrument_drums/plugin.json  | 1 +
 plugins/instrument_guitar/plugin.json | 1 +
 plugins/instrument_piano/plugin.json  | 1 +
 plugins/instrument_vocals/plugin.json | 1 +
 5 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
index 3292d486..7e230a63 100644
--- a/plugins/instrument_bass/plugin.json
+++ b/plugins/instrument_bass/plugin.json
@@ -4,7 +4,7 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
-  "icon": "assets/icon.svg",
+  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "bass",
diff --git a/plugins/instrument_drums/plugin.json b/plugins/instrument_drums/plugin.json
index 6d34924e..5500ebd7 100644
--- a/plugins/instrument_drums/plugin.json
+++ b/plugins/instrument_drums/plugin.json
@@ -4,6 +4,7 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
+  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "drums",
diff --git a/plugins/instrument_guitar/plugin.json b/plugins/instrument_guitar/plugin.json
index c85a1782..5319c387 100644
--- a/plugins/instrument_guitar/plugin.json
+++ b/plugins/instrument_guitar/plugin.json
@@ -4,6 +4,7 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
+  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "guitar",
diff --git a/plugins/instrument_piano/plugin.json b/plugins/instrument_piano/plugin.json
index eeb741ed..f0209344 100644
--- a/plugins/instrument_piano/plugin.json
+++ b/plugins/instrument_piano/plugin.json
@@ -4,6 +4,7 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
+  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "keys",
diff --git a/plugins/instrument_vocals/plugin.json b/plugins/instrument_vocals/plugin.json
index c8bc3e45..240c2d40 100644
--- a/plugins/instrument_vocals/plugin.json
+++ b/plugins/instrument_vocals/plugin.json
@@ -4,6 +4,7 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
+  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "vocals",

From 486e350c2790a4498e2006685d11aa82575d3eb2 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 21:47:11 +0200
Subject: [PATCH 67/74] Revert "chore: add CC0 SVG source comment to instrument
 plugins, fix duplicate icon in bass"

This reverts commit 026a608debd910599941e283dbc1a3039b01e6d0.
---
 plugins/instrument_bass/plugin.json   | 2 +-
 plugins/instrument_drums/plugin.json  | 1 -
 plugins/instrument_guitar/plugin.json | 1 -
 plugins/instrument_piano/plugin.json  | 1 -
 plugins/instrument_vocals/plugin.json | 1 -
 5 files changed, 1 insertion(+), 5 deletions(-)

diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
index 7e230a63..3292d486 100644
--- a/plugins/instrument_bass/plugin.json
+++ b/plugins/instrument_bass/plugin.json
@@ -4,7 +4,7 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
-  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
+  "icon": "assets/icon.svg",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "bass",
diff --git a/plugins/instrument_drums/plugin.json b/plugins/instrument_drums/plugin.json
index 5500ebd7..6d34924e 100644
--- a/plugins/instrument_drums/plugin.json
+++ b/plugins/instrument_drums/plugin.json
@@ -4,7 +4,6 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
-  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "drums",
diff --git a/plugins/instrument_guitar/plugin.json b/plugins/instrument_guitar/plugin.json
index 5319c387..c85a1782 100644
--- a/plugins/instrument_guitar/plugin.json
+++ b/plugins/instrument_guitar/plugin.json
@@ -4,7 +4,6 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
-  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "guitar",
diff --git a/plugins/instrument_piano/plugin.json b/plugins/instrument_piano/plugin.json
index f0209344..eeb741ed 100644
--- a/plugins/instrument_piano/plugin.json
+++ b/plugins/instrument_piano/plugin.json
@@ -4,7 +4,6 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
-  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "keys",
diff --git a/plugins/instrument_vocals/plugin.json b/plugins/instrument_vocals/plugin.json
index 240c2d40..c8bc3e45 100644
--- a/plugins/instrument_vocals/plugin.json
+++ b/plugins/instrument_vocals/plugin.json
@@ -4,7 +4,6 @@
   "version": "1.0.0",
   "type": "instrument",
   "bundled": true,
-  "_comment": "Find CC0-licensed instrument SVGs at https://www.svgrepo.com/collection/music-instrument",
   "icon": "assets/icon.svg",
   "instrument": {
     "id": "vocals",

From 1657dec20ef3a872a102af408d646559ab7f4ade Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 21:47:57 +0200
Subject: [PATCH 68/74] docs: add instrument-plugins.md reference, fix
 duplicate bass icon

---
 docs/instrument-plugins.md          | 177 ++++++++++++++++++++++++++++
 plugins/instrument_bass/plugin.json |   1 -
 2 files changed, 177 insertions(+), 1 deletion(-)
 create mode 100644 docs/instrument-plugins.md

diff --git a/docs/instrument-plugins.md b/docs/instrument-plugins.md
new file mode 100644
index 00000000..b1151f40
--- /dev/null
+++ b/docs/instrument-plugins.md
@@ -0,0 +1,177 @@
+# Instrument Plugins
+
+Instruments in fee[dB]ack are defined by bundled **instrument plugins** — each is a
+small `plugins/instrument_<name>/` directory with a `plugin.json` manifest and an
+SVG icon. They declare the instrument's tuning presets, string/key counts,
+arrangement role mappings, and detection strategy, replacing hardcoded checks
+across the codebase.
+
+## Interface
+
+Each instrument plugin sets `"type": "instrument"` in its manifest and carries an
+`"instrument"` block with the following schema:
+
+```jsonc
+{
+  "id": "instrument_guitar",        // unique plugin id (snake_case, prefixed "instrument_")
+  "name": "Guitar",                 // human-readable name
+  "version": "1.0.0",
+  "type": "instrument",             // ⬅ required
+  "bundled": true,                  // a bundled plugin (not user-installed)
+  "icon": "assets/icon.svg",        // path relative to the plugin directory
+  "instrument": {
+    "id": "guitar",                 // instrument id (snake_case, used in settings & profiles)
+    "label": "Guitar",              // display label for the instrument selector
+    "kind": "stringed",             // "stringed" | "keyboard" | "percussion" | "vocal" | "custom"
+
+    // ── Stringed instruments ──────────────────────────────────────────────
+    "string_counts": [6, 7, 8],     // (required for stringed) array of ints
+    "default_string_count": 6,      // (required for stringed) must be in string_counts
+    "fret_counts": [21, 22, 24],    // (required for stringed) array of ints
+    "default_fret_count": 22,       // (required for stringed) must be in fret_counts
+    "reference_pitch": 440.0,       // A4 reference (default 440)
+    "standard_tunings": {           // (required for stringed) open MIDI pitches per string count
+      "6": [40, 45, 50, 55, 59, 64],
+      "7": [35, 40, 45, 50, 55, 59, 64],
+      "8": [30, 35, 40, 45, 50, 55, 59, 64]
+    },
+    "tunings": {                    // (required for stringed) named tuning presets per string count
+      "6": {
+        "E Standard":  [ 0,  0,  0,  0,  0,  0],
+        "Drop D":      [-2,  0,  0,  0,  0,  0],
+        "Eb Standard": [-1, -1, -1, -1, -1, -1]
+      }
+    },
+
+    // ── Keyboard instruments ───────────────────────────────────────────────
+    "key_counts": [25, 49, 61, 88], // (required for keyboard) array of ints
+    "default_key_count": 88,        // (required for keyboard) must be in key_counts
+
+    // ── All instruments ────────────────────────────────────────────────────
+    "detect_strategy": "pitch",     // "pitch" (uses tuner) | "onset" (drums) | null
+    "roles": [                      // one or more arrangement roles
+      {
+        "id": "lead",               // role id (snake_case), used in profile ids
+        "label": "Lead",            // display label for the role selector
+        "arrangement_flags": ["path_lead"],  // XML flags that identify this role
+        "arrangement_names": ["Lead", "Lead Guitar"],  // names that identify this role
+        "default": true             // the default role for this instrument
+      }
+    ]
+  }
+}
+```
+
+### `kind` values
+
+| Kind | Example | Has tunings? | Has string counts? | Notes |
+|------|---------|:---:|:---:|-------|
+| `"stringed"` | guitar, bass | Yes | Yes | Shows tunings, frets, handedness in the selector |
+| `"keyboard"` | piano, keys | Yes | No (key counts instead) | Shows key count selector |
+| `"percussion"` | drums | No | No | No tuner, hit detection |
+| `"vocal"` | vocals | No | No | Pitched, uses tuner, no instrument-specific controls |
+| `"custom"` | any future type | Depends | Depends | Free-form |
+
+### Role mapping
+
+When a player selects a role (e.g. Guitar → Rhythm), the highway opens the
+arrangement matching that role. Roles match against:
+
+1. **Arrangement flags** — XML `<arrangementProperties>` attributes (e.g. `path_bass`, `path_lead`).
+   Flagged arrangements match immediately, regardless of name.
+2. **Arrangement names** — matched case-insensitively against the arrangement's
+   smart name (from XML parsing) and raw name. List common GP/RS2014 naming
+   variants for each role to maximise coverage (e.g. `["Bass", "Pick Bass", "Fingered Bass"]`).
+
+The library auto-filters to arrangements matching the current instrument's roles.
+
+## Creating a new instrument plugin
+
+1. Create `plugins/instrument_<id>/plugin.json` (copy the skeleton below).
+2. Create `plugins/instrument_<id>/assets/icon.svg` — use a
+   **[CC0-licensed SVG from SVGrepo's music instrument collection](https://www.svgrepo.com/collection/music-instrument)** (all free for any use, no attribution required).
+3. Fill in the `instrument` block with tunings, string/fret/key counts, and role
+   mappings for your instrument.
+4. Restart fee[dB]ack — the loader discovers the plugin automatically.
+
+### Minimal skeleton
+
+```jsonc
+{
+  "id": "instrument_<id>",
+  "name": "<Display Name>",
+  "version": "1.0.0",
+  "type": "instrument",
+  "bundled": true,
+  "icon": "assets/icon.svg",
+  "instrument": {
+    "id": "<id>",
+    "label": "<Display Name>",
+    "kind": "stringed",
+    "string_counts": [6],
+    "default_string_count": 6,
+    "fret_counts": [22, 24],
+    "default_fret_count": 22,
+    "reference_pitch": 440.0,
+    "standard_tunings": {
+      "6": [40, 45, 50, 55, 59, 64]
+    },
+    "tunings": {
+      "6": { "E Standard": [0, 0, 0, 0, 0, 0] }
+    },
+    "detect_strategy": "pitch",
+    "roles": [
+      {
+        "id": "<role>",
+        "label": "<Role Label>",
+        "arrangement_names": ["<Arr Name>"],
+        "default": true
+      }
+    ]
+  }
+}
+```
+
+### Non-stringed skeleton
+
+```jsonc
+{
+  "id": "instrument_<id>",
+  "name": "<Display Name>",
+  "version": "1.0.0",
+  "type": "instrument",
+  "bundled": true,
+  "icon": "assets/icon.svg",
+  "instrument": {
+    "id": "<id>",
+    "label": "<Display Name>",
+    "kind": "vocal",
+    "string_counts": [],
+    "default_string_count": 0,
+    "key_counts": [],
+    "default_key_count": 0,
+    "reference_pitch": 440.0,
+    "detect_strategy": "pitch",
+    "roles": [
+      {
+        "id": "<role>",
+        "label": "<Role Label>",
+        "arrangement_names": ["<Arr Name>"],
+        "default": true
+      }
+    ]
+  }
+}
+```
+
+## Bundled instruments
+
+These ship with fee[dB]ack and are in the `plugins/` directory tree by default:
+
+| Plugin directory | Instrument id | Kind |
+|------------------|:---:|---|
+| `instrument_guitar` | `guitar` | stringed |
+| `instrument_bass` | `bass` | stringed |
+| `instrument_drums` | `drums` | percussion |
+| `instrument_piano` | `keys` | keyboard |
+| `instrument_vocals` | `vocals` | vocal |
diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
index 3292d486..b819eaff 100644
--- a/plugins/instrument_bass/plugin.json
+++ b/plugins/instrument_bass/plugin.json
@@ -5,7 +5,6 @@
   "type": "instrument",
   "bundled": true,
   "icon": "assets/icon.svg",
-  "icon": "assets/icon.svg",
   "instrument": {
     "id": "bass",
     "label": "Bass",

From e0946e3157e332f1f519f7786ac782fddcb89b59 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Wed, 22 Jul 2026 21:50:28 +0200
Subject: [PATCH 69/74] docs: update changelog with vocals plugin, fret count,
 bass pick styles, and merge fixes

---
 CHANGELOG.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1012ec6e..2e800b7e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,6 +43,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Score attribution fix** — scores now record the server-resolved arrangement
   index (from `song:ready`) instead of defaulting to 0 when clicking the main
   card (not an arrangement chip).
+- **Vocals instrument plugin** — a new `kind: "vocal"` instrument with pitch
+  detection. Placeholder for future vocal chart support; no instrument-specific
+  controls in the selector. Includes a CC0 microphone SVG icon.
+- **Fret count selector** — stringed instruments (guitar, bass) now declare
+  `fret_counts` and `default_fret_count` in their plugin manifests. The
+  instrument selector popover shows a **Frets** pill row alongside Strings,
+  and Settings > Instruments lets users add custom fret counts per instrument.
+- **Bass pick/fingered styles** — the bass instrument's arrangement name
+  patterns now include `"Pick Bass"`, `"Fingered Bass"`, `"Finger Bass"`, and
+  `"Picked Bass"` so GP-imported arrangements with those names match the bass
+  role (previously only exact `"Bass"` matched via the registry path).
+- **Instrument plugin documentation** — `docs/instrument-plugins.md` covers the
+  complete interface schema, role mapping mechanics, skeleton templates for
+  stringed and non-stringed instruments, and recommends CC0-licensed SVGs from
+  [SVGrepo's music instrument collection](https://www.svgrepo.com/collection/music-instrument).
 - **Drum-part picker (feedpak 1.17.0 "drums as arrangements").** When a song
   carries several drum charts, a **Drum part** selector appears beside the
   arrangement switcher (advanced settings) so a player can choose which drummer
@@ -161,6 +176,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Icons** — instrument selector card shows per-instrument icons instead of
   a single hardcoded guitar SVG.
 - **Pathway removed** from the instrument selector (unused feature).
+- **Tuning chip** fades out on card hover so save/favorite action buttons are
+  not obscured. Now flush to the top-left corner with a bottom-right radius
+  matching the card.
+- **Instrument chip logic** reads from the instrument registry rather than
+  hardcoding bass/lead detection. Offset truncation uses the instrument's
+  `string_count` from the registry, supporting any future pitched instrument.
 - **`GET /api/song/{f}?stems=1`** (new, opt-in) — returns the pack's playable stem
   list (`[{id, url, default}]` + `full_mix_url`), the same list the highway's WS
   `ready` sends. The stems plugin could only learn it from that WS message, which
@@ -336,6 +357,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   empty (double-AND).
 - **Default arrangement dropdown** removed from Settings > Gameplay (moved to
   the instrument selector role pills).
+- **Tuning chip matching** — the offset-detection chain was reordered to use
+  the song-level `tuning_offsets` field first and fall back through perspective-aware
+  sources, fixing native guitar cards that lacked `data-tuning-offsets`. Bass chips
+  now correctly truncate inferred 6-element offsets to 4 for the coverage checker.
+- **Bass instrument selector** — switching to bass no longer leaves the
+  tuning chips permanently amber. The chip-is-bass detection was too restrictive,
+  requiring a native bass chart when an inferred one was already showing.
+- **Double reload on instrument switch** — changing instruments briefly triggered
+  both `instrument:changed` and `working-tuning-changed` reloads, racing state
+  mutations. The instrument-change handler now sets `_lastRenderInstrument` early
+  so the tuning-changed path skips its reload and only re-decorates.
+- **Arrangement name pattern encoding** — the Instruments settings panel showed
+  mojibake (`ΓåÆ` and `ΓöÇ`) instead of `→` and box-drawing characters due to
+  a wrong-encoding save. All five corrupted sequences were restored.
+- **`renderDrawerIfOpen`** was missing after the songs.js port, causing a
+  `ReferenceError` when the instrument auto-filter ran. The helper was restored.
 - **GP8 asset resolution honours the directory the registry named.**
   `<EmbeddedFilePath>` is matched on filename stem so a format variant of the
   same recording can win (an `.ogg` beside the declared `.mp3` is copied out

From e997d275f0c2bfcfc2c6a31aeb3884f31dfaab95 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 23 Jul 2026 14:36:32 +0200
Subject: [PATCH 70/74] chore: rename instrument_piano to instrument_keys, drop
 instrument_vocals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename plugins/instrument_piano/ to plugins/instrument_keys/ for
  consistency with the 'keys' instrument id used everywhere
  (data/progression/paths/keys.json, keys_highway_3d, etc.)
- Remove instrument_vocals plugin — defer to the coordinated
  instrument-pathways FEP with its sidecar PRs
- Update docs/instrument-plugins.md bundled instruments table
- Remove vocal-specific routing from the hardcoded fallback in
  lib/progression.py
---
 .../assets/icon.svg                           |  0
 .../plugin.json                               |  0
 plugins/instrument_vocals/assets/icon.svg     |  6 -----
 plugins/instrument_vocals/plugin.json         | 27 -------------------
 4 files changed, 33 deletions(-)
 rename plugins/{instrument_piano => instrument_keys}/assets/icon.svg (100%)
 rename plugins/{instrument_piano => instrument_keys}/plugin.json (100%)
 delete mode 100644 plugins/instrument_vocals/assets/icon.svg
 delete mode 100644 plugins/instrument_vocals/plugin.json

diff --git a/plugins/instrument_piano/assets/icon.svg b/plugins/instrument_keys/assets/icon.svg
similarity index 100%
rename from plugins/instrument_piano/assets/icon.svg
rename to plugins/instrument_keys/assets/icon.svg
diff --git a/plugins/instrument_piano/plugin.json b/plugins/instrument_keys/plugin.json
similarity index 100%
rename from plugins/instrument_piano/plugin.json
rename to plugins/instrument_keys/plugin.json
diff --git a/plugins/instrument_vocals/assets/icon.svg b/plugins/instrument_vocals/assets/icon.svg
deleted file mode 100644
index 4f2957aa..00000000
--- a/plugins/instrument_vocals/assets/icon.svg
+++ /dev/null
@@ -1,6 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-  <path d="M12 1a3 3 0 0 0-3 3v8a3 3 0 0 0 6 0V4a3 3 0 0 0-3-3z"/>
-  <path d="M19 10v2a7 7 0 0 1-14 0v-2"/>
-  <line x1="12" y1="19" x2="12" y2="23"/>
-  <line x1="8" y1="23" x2="16" y2="23"/>
-</svg>
diff --git a/plugins/instrument_vocals/plugin.json b/plugins/instrument_vocals/plugin.json
deleted file mode 100644
index c8bc3e45..00000000
--- a/plugins/instrument_vocals/plugin.json
+++ /dev/null
@@ -1,27 +0,0 @@
-{
-  "id": "instrument_vocals",
-  "name": "Vocals",
-  "version": "1.0.0",
-  "type": "instrument",
-  "bundled": true,
-  "icon": "assets/icon.svg",
-  "instrument": {
-    "id": "vocals",
-    "label": "Vocals",
-    "kind": "vocal",
-    "string_counts": [],
-    "default_string_count": 0,
-    "key_counts": [],
-    "default_key_count": 0,
-    "reference_pitch": 440.0,
-    "detect_strategy": "pitch",
-    "roles": [
-      {
-        "id": "vocals",
-        "label": "Vocals",
-        "arrangement_names": ["Vocals", "Voice", "Vocal", "Lead Vocal", "Backing Vocal"],
-        "default": true
-      }
-    ]
-  }
-}

From 6f0ebc1b4b59355e60158b81d3c1ea473b536361 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 23 Jul 2026 14:37:08 +0200
Subject: [PATCH 71/74] feat: add arrangement_types key alongside
 arrangement_names in instrument roles
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Separate the normative spec type routing (arrangement_types, exact match
against the arrangement's type field) from cosmetic display name routing
(arrangement_names, fuzzy fallback). Types win on collision.

Changes:
- Add arrangement_types field to role schema (optional list of lowercase
  type tokens, e.g. lead/rhythm/bass/drums/keys)
- Update all 4 bundled instrument manifests to declare arrangement_types
- InstrumentRegistry.register(): validate arrangement_types, add
  cross-instrument collision detection warnings
- InstrumentRegistry.instrument_id_for_arrangement(): check types first,
  then names, then flags (backward-compatible — existing plugins without
  arrangement_types continue to match via arrangement_names)
- InstrumentRegistry.find_role_by_arrangement(): same priority order
- progression.instrument_for_arrangement(): same types-first logic
- Change duplicate-id from ValueError to first-wins + warning (registry)
- Update docs/instrument-plugins.md schema and role mapping section
---
 docs/instrument-plugins.md            | 14 ++++---
 lib/instruments.py                    | 57 ++++++++++++++++++++++++---
 lib/progression.py                    |  6 +--
 plugins/instrument_bass/plugin.json   |  1 +
 plugins/instrument_drums/plugin.json  |  1 +
 plugins/instrument_guitar/plugin.json |  2 +
 plugins/instrument_keys/plugin.json   |  1 +
 7 files changed, 68 insertions(+), 14 deletions(-)

diff --git a/docs/instrument-plugins.md b/docs/instrument-plugins.md
index b1151f40..15c6cb9c 100644
--- a/docs/instrument-plugins.md
+++ b/docs/instrument-plugins.md
@@ -54,7 +54,8 @@ Each instrument plugin sets `"type": "instrument"` in its manifest and carries a
         "id": "lead",               // role id (snake_case), used in profile ids
         "label": "Lead",            // display label for the role selector
         "arrangement_flags": ["path_lead"],  // XML flags that identify this role
-        "arrangement_names": ["Lead", "Lead Guitar"],  // names that identify this role
+        "arrangement_types": ["lead"],  // spec `type` values that identify this role (normative, exact match — preferred over names)
+        "arrangement_names": ["Lead", "Lead Guitar"],  // display names that identify this role (fuzzy/fallback)
         "default": true             // the default role for this instrument
       }
     ]
@@ -77,9 +78,12 @@ Each instrument plugin sets `"type": "instrument"` in its manifest and carries a
 When a player selects a role (e.g. Guitar → Rhythm), the highway opens the
 arrangement matching that role. Roles match against:
 
-1. **Arrangement flags** — XML `<arrangementProperties>` attributes (e.g. `path_bass`, `path_lead`).
+1. **Arrangement types** — spec `type` values (e.g. `"bass"`, `"drums"`, `"lead"`).
+   Matched exactly against the arrangement's `type` field. This is the primary,
+   normative routing key and is stable across display-name changes.
+2. **Arrangement flags** — XML `<arrangementProperties>` attributes (e.g. `path_bass`, `path_lead`).
    Flagged arrangements match immediately, regardless of name.
-2. **Arrangement names** — matched case-insensitively against the arrangement's
+3. **Arrangement names** — matched case-insensitively against the arrangement's
    smart name (from XML parsing) and raw name. List common GP/RS2014 naming
    variants for each role to maximise coverage (e.g. `["Bass", "Pick Bass", "Fingered Bass"]`).
 
@@ -173,5 +177,5 @@ These ship with fee[dB]ack and are in the `plugins/` directory tree by default:
 | `instrument_guitar` | `guitar` | stringed |
 | `instrument_bass` | `bass` | stringed |
 | `instrument_drums` | `drums` | percussion |
-| `instrument_piano` | `keys` | keyboard |
-| `instrument_vocals` | `vocals` | vocal |
+| `instrument_keys` | `keys` | keyboard |
+
diff --git a/lib/instruments.py b/lib/instruments.py
index 442077d3..f4bad0d0 100644
--- a/lib/instruments.py
+++ b/lib/instruments.py
@@ -105,7 +105,12 @@ def register(self, definition: dict):
         """
         inst_id = _validate_str(definition.get("id"), "instrument.id")
         if inst_id in self._instruments:
-            raise ValueError(f"instrument {inst_id!r} is already registered")
+            log.warning(
+                "instrument %r already registered by plugin %s; skipping %r from plugin %s",
+                inst_id, self._instruments[inst_id].get("_plugin_id", "?"),
+                definition.get("label", inst_id), definition.get("_plugin_id", "?"),
+            )
+            return
         label = _validate_str(definition.get("label", inst_id), "instrument.label")
         kind = _validate_str(definition.get("kind", "custom"), "instrument.kind")
         if kind not in _INSTRUMENT_KINDS:
@@ -233,6 +238,12 @@ def register(self, definition: dict):
             r_names = role.get("arrangement_names") or []
             if not isinstance(r_names, list):
                 raise ValueError(f"roles[{i}].arrangement_names must be a list")
+            r_types = role.get("arrangement_types") or []
+            if not isinstance(r_types, list):
+                raise ValueError(f"roles[{i}].arrangement_types must be a list")
+            for t in r_types:
+                if not isinstance(t, str) or not t.strip():
+                    raise ValueError(f"roles[{i}].arrangement_types entries must be non-empty strings")
             r_default = bool(role.get("default"))
             if r_default:
                 if has_default:
@@ -242,12 +253,34 @@ def register(self, definition: dict):
                 "id": r_id,
                 "label": r_label,
                 "arrangement_flags": list(set(r_flags)),
+                "arrangement_types": [t.strip().lower() for t in r_types if t.strip()],
                 "arrangement_names": [n.strip().lower() for n in r_names if isinstance(n, str) and n.strip()],
                 "default": r_default,
             })
         if roles and not has_default:
             roles[0]["default"] = True
 
+        # Cross-instrument collision detection: warn when two instruments
+        # claim the same arrangement name or type. First-wins rules — the
+        # already-registered instrument keeps the claim.
+        for existing_id, existing in self._instruments.items():
+            for new_role in roles:
+                for existing_role in existing["roles"]:
+                    overlapping_types = set(new_role.get("arrangement_types", [])) & set(existing_role.get("arrangement_types", []))
+                    if overlapping_types:
+                        log.warning(
+                            "instrument %r role %r arrangement_types %s overlap with already-registered %r role %r",
+                            inst_id, new_role["id"], sorted(overlapping_types),
+                            existing_id, existing_role["id"],
+                        )
+                    overlapping_names = set(new_role["arrangement_names"]) & set(existing_role["arrangement_names"])
+                    if overlapping_names:
+                        log.warning(
+                            "instrument %r role %r arrangement_names %s overlap with already-registered %r role %r",
+                            inst_id, new_role["id"], sorted(overlapping_names),
+                            existing_id, existing_role["id"],
+                        )
+
         normalized = {
             "id": inst_id,
             "label": label,
@@ -325,13 +358,20 @@ def get_default_role(self, instrument_id: str) -> str | None:
             return inst["roles"][0]["id"]
         return None
 
-    def find_role_by_arrangement(self, instrument_id: str, arr_name: str, arr_flags: dict = None) -> str | None:
-        """Find the role id matching an arrangement name or path flags for a specific instrument."""
+    def find_role_by_arrangement(self, instrument_id: str, arr_name: str, arr_flags: dict = None, arr_type: str = "") -> str | None:
+        """Find the role id matching an arrangement name, type, or path flags for a specific instrument.
+
+        Priority: arrangement_types first (exact spec ``type`` match), then
+        arrangement_names, then arrangement_flags.
+        """
         inst = self._instruments.get(instrument_id)
         if not inst:
             return None
+        arr_type_lower = (arr_type or "").strip().lower()
         name_lower = (arr_name or "").strip().lower()
         for role in inst["roles"]:
+            if arr_type_lower and arr_type_lower in role.get("arrangement_types", []):
+                return role["id"]
             if name_lower in role["arrangement_names"]:
                 return role["id"]
             if arr_flags:
@@ -340,11 +380,18 @@ def find_role_by_arrangement(self, instrument_id: str, arr_name: str, arr_flags:
                         return role["id"]
         return None
 
-    def instrument_id_for_arrangement(self, arr_name: str, arr_flags: dict = None) -> str | None:
-        """Return the instrument id whose roles match a given arrangement name or flags."""
+    def instrument_id_for_arrangement(self, arr_name: str, arr_flags: dict = None, arr_type: str = "") -> str | None:
+        """Return the instrument id whose roles match a given arrangement name, type, or flags.
+
+        Priority: arrangement_types (exact match against spec ``type``) first,
+        then arrangement_names (fuzzy display name match), then arrangement_flags.
+        """
+        arr_type_lower = (arr_type or "").strip().lower()
         name_lower = (arr_name or "").strip().lower()
         for inst in self._instruments.values():
             for role in inst["roles"]:
+                if arr_type_lower and arr_type_lower in role.get("arrangement_types", []):
+                    return inst["id"]
                 if name_lower in role["arrangement_names"]:
                     return inst["id"]
                 if arr_flags:
diff --git a/lib/progression.py b/lib/progression.py
index c2c595f4..bceb44a4 100644
--- a/lib/progression.py
+++ b/lib/progression.py
@@ -349,9 +349,9 @@ def instrument_for_arrangement(arr_entry, *, registry=None):
     if registry:
         for inst in registry.get_all():
             for role in inst.get("roles", []):
-                if name in role.get("arrangement_names", []):
+                if arr_type in role.get("arrangement_types", []):
                     return inst["id"]
-                if arr_type in role.get("arrangement_names", []):
+                if name in role.get("arrangement_names", []):
                     return inst["id"]
         # Also check flags: build a virtual arr_entry for path flag matching
         for inst in registry.get_all():
@@ -376,8 +376,6 @@ def instrument_for_arrangement(arr_entry, *, registry=None):
         return "bass"
     if "drum" in name or "percussion" in name:
         return "drums"
-    if "vocal" in name:
-        return "vocals"
     # Word-boundary match so e.g. "Monkeys Medley" doesn't read as keys.
     if re.search(r"\b(?:keys|piano|keyboard|synth)\b", name):
         return "keys"
diff --git a/plugins/instrument_bass/plugin.json b/plugins/instrument_bass/plugin.json
index b819eaff..eb5ccfff 100644
--- a/plugins/instrument_bass/plugin.json
+++ b/plugins/instrument_bass/plugin.json
@@ -53,6 +53,7 @@
         "id": "bass",
         "label": "Bass",
         "arrangement_flags": ["path_bass"],
+        "arrangement_types": ["bass"],
         "arrangement_names": ["Bass", "Pick Bass", "Fingered Bass", "Finger Bass", "Picked Bass"],
         "default": true
       }
diff --git a/plugins/instrument_drums/plugin.json b/plugins/instrument_drums/plugin.json
index 6d34924e..f32d87be 100644
--- a/plugins/instrument_drums/plugin.json
+++ b/plugins/instrument_drums/plugin.json
@@ -17,6 +17,7 @@
       {
         "id": "drums",
         "label": "Drums",
+        "arrangement_types": ["drums"],
         "arrangement_names": ["Drums", "Drum Kit", "Percussion"],
         "default": true
       }
diff --git a/plugins/instrument_guitar/plugin.json b/plugins/instrument_guitar/plugin.json
index c85a1782..6488ab07 100644
--- a/plugins/instrument_guitar/plugin.json
+++ b/plugins/instrument_guitar/plugin.json
@@ -60,6 +60,7 @@
         "id": "lead",
         "label": "Lead",
         "arrangement_flags": ["path_lead"],
+        "arrangement_types": ["lead"],
         "arrangement_names": ["Lead", "Lead Guitar"],
         "default": true
       },
@@ -67,6 +68,7 @@
         "id": "rhythm",
         "label": "Rhythm",
         "arrangement_flags": ["path_rhythm"],
+        "arrangement_types": ["rhythm"],
         "arrangement_names": ["Rhythm", "Rhythm Guitar"]
       }
     ]
diff --git a/plugins/instrument_keys/plugin.json b/plugins/instrument_keys/plugin.json
index eeb741ed..c2ad3227 100644
--- a/plugins/instrument_keys/plugin.json
+++ b/plugins/instrument_keys/plugin.json
@@ -19,6 +19,7 @@
       {
         "id": "keys",
         "label": "Keys",
+        "arrangement_types": ["keys"],
         "arrangement_names": ["Keys", "Piano", "Keyboard", "Synth", "Synth Lead"],
         "default": true
       }

From 2b95f4c7f4fbb207633844034091404e4f5ab178 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 23 Jul 2026 15:00:33 +0200
Subject: [PATCH 72/74] feat: display arrangement_types in settings role cards
 (non-editable)

---
 static/v3/instruments-settings.js | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/static/v3/instruments-settings.js b/static/v3/instruments-settings.js
index e72c01ac..60425688 100644
--- a/static/v3/instruments-settings.js
+++ b/static/v3/instruments-settings.js
@@ -87,8 +87,17 @@
                     '<div class="flex flex-wrap gap-1">';
                 for (var j = 0; j < inst.roles.length; j++) {
                     var role = inst.roles[j];
+                    var typeTag = '';
+                    if (role.arrangement_types && role.arrangement_types.length) {
+                        typeTag = ' <span class="text-fb-textDim text-[0.5625rem]">(';
+                        for (var ti = 0; ti < role.arrangement_types.length; ti++) {
+                            if (ti > 0) typeTag += ', ';
+                            typeTag += esc(role.arrangement_types[ti]);
+                        }
+                        typeTag += ')</span>';
+                    }
                     html += '<span class="text-xs bg-gray-800/50 border border-gray-700 rounded-md px-2 py-0.5 text-fb-text">' +
-                        esc(role.label) + (role.default ? ' <span class="text-fb-primary text-[0.625rem]">(default)</span>' : '') +
+                        esc(role.label) + (role.default ? ' <span class="text-fb-primary text-[0.625rem]">(default)</span>' : '') + typeTag +
                         '</span>';
                 }
                 html += '</div></div>';

From 5a6772a2f8ead1ed77b03078e7e1900aa0774a74 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 23 Jul 2026 15:30:22 +0200
Subject: [PATCH 73/74] chore: normalize indentation in songs.js (no functional
 change)

---
 static/v3/songs.js | 648 ++++-----------------------------------------
 1 file changed, 52 insertions(+), 596 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 18603714..255e8145 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -43,110 +43,8 @@
         ['difficulty', 'Difficulty (easiest first)'], ['difficulty-desc', 'Difficulty (hardest first)'],
     ];
     const FORMATS = [['', 'All formats'], ['sloppak', 'Feedpak'], ['loose', 'Folder']];
-    function _arrangementOptions() {
-        // Derive filter pill labels from instrument registry role names.
-        // When new instrument plugins are added, their arrangement type labels
-        // appear in the library filter drawer automatically.
-        var insts = sm && sm._instruments;
-        if (Array.isArray(insts) && insts.length) {
-            var out = [];
-            for (var i = 0; i < insts.length; i++) {
-                var roles = insts[i].roles || [];
-                for (var j = 0; j < roles.length; j++) {
-                    var label = roles[j].label;
-                    if (label && out.indexOf(label) < 0) out.push(label);
-                }
-            }
-            if (out.length) return out;
-        }
-        return ['Lead', 'Rhythm', 'Bass', 'Combo', 'Vocals'];
-    }
-
-    function _roleIcon(arrName) {
-        var insts = window.feedBack && window.feedBack._instruments;
-        if (!Array.isArray(insts)) return '\u25cf';
-        var name = (arrName || '').toLowerCase();
-        for (var i = 0; i < insts.length; i++) {
-            var inst = insts[i];
-            var roles = inst.roles || [];
-            for (var j = 0; j < roles.length; j++) {
-                var r = roles[j];
-                if (name === r.label.toLowerCase()) {
-                    if (inst.roles.length > 1) {
-                        return (inst.id[0] || '?').toUpperCase() + '<span class="text-[0.5rem]">' + (r.label[0] || '?').toUpperCase() + '</span>';
-                    }
-                    return (inst.id[0] || (r.label[0] || '?')).toUpperCase();
-                }
-                var names = r.arrangement_names || [];
-                for (var k = 0; k < names.length; k++) {
-                    if (name === names[k]) {
-                        if (inst.roles.length > 1) {
-                            return (inst.id[0] || '?').toUpperCase() + '<span class="text-[0.5rem]">' + (r.label[0] || '?').toUpperCase() + '</span>';
-                        }
-                        return (inst.id[0] || (r.label[0] || '?')).toUpperCase();
-                    }
-                }
-            }
-        }
-        return '\u25cf';
-    }
-
-    function _isPitchedArrangement(arrName) {
-        var insts = window.feedBack && window.feedBack._instruments;
-        if (!Array.isArray(insts)) return true;
-        var name = (arrName || '').toLowerCase();
-        for (var i = 0; i < insts.length; i++) {
-            var inst = insts[i];
-            var roles = inst.roles || [];
-            for (var j = 0; j < roles.length; j++) {
-                var r = roles[j];
-                if (name === r.label.toLowerCase()) return inst.detect_strategy === 'pitch';
-                var names = r.arrangement_names || [];
-                for (var k = 0; k < names.length; k++) {
-                    if (name === names[k]) return inst.detect_strategy === 'pitch';
-                }
-            }
-        }
-        return true;
-    }
-
-    function _instrumentArrangementNames(instrumentId) {
-        var insts = sm && sm._instruments;
-        if (!Array.isArray(insts)) return null;
-        for (var i = 0; i < insts.length; i++) {
-            if (insts[i].id === instrumentId && insts[i].roles) {
-                var names = [];
-                for (var j = 0; j < insts[i].roles.length; j++) {
-                    var label = insts[i].roles[j].label;
-                    if (label && names.indexOf(label) < 0) names.push(label);
-                }
-                return names.length ? names : null;
-            }
-        }
-        return null;
-    }
-
-    function _applyArrangementAutoFilter(instrumentId) {
-        var names = _instrumentArrangementNames(instrumentId);
-        if (!names) return false;
-        _arrAutoInstrument = instrumentId;
-        state.filters.arr_has = names.slice();
-        state.filters.arr_lacks = [];
-        return true;
-    }
-
-    function _activeInstrument() {
-        var id = sm && sm._activeInstrumentProfile;
-        if (!id) return null;
-        var insts = window.feedBack && window.feedBack._instruments;
-        if (!Array.isArray(insts)) return null;
-        for (var i = 0; i < insts.length; i++) {
-            if (id.indexOf(insts[i].id) === 0) return insts[i];
-        }
-        return null;
-    }
-
-    const STEMS = ['guitar', 'bass', 'drums', 'vocals', 'piano', 'other'];
+    const ARRANGEMENTS = ['Lead', 'Rhythm', 'Bass', 'Combo', 'Vocals'];
+    const STEMS = ['guitar', 'bass', 'drums', 'vocals', 'other'];
     const PAGE_SIZE = 24;
     // Extra rows rendered above/below the viewport so a fast scroll doesn't flash
     // blank before the next window render lands.
@@ -164,8 +62,8 @@
         artist: '', album: '',
         grouping: true,     // one card per song (multi-chart grouping); persisted
 
-        filters: { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [], tuningMatch: 'exact' },
-        page: 0, total: 0, loading: false, built: false, accuracy: {}, arrangementAccuracy: {}, tuningNames: [], genres: [],
+        filters: { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [] },
+        page: 0, total: 0, loading: false, built: false, accuracy: {}, tuningNames: [], genres: [],
         artistCatalog: [], renderedHash: '',
         scrollBound: false,
         songsById: {}, selectMode: false, selected: new Set(),
@@ -222,7 +120,7 @@
     function activeFilterCount() {
         const f = state.filters;
         return f.arr_has.length + f.arr_lacks.length + f.stem_has.length + f.stem_lacks.length +
-            (f.lyrics ? 1 : 0) + (f.tuningMatch === 'playable' ? 1 : f.tunings.length) + (f.mastery ? f.mastery.length : 0) +
+            (f.lyrics ? 1 : 0) + f.tunings.length + (f.mastery ? f.mastery.length : 0) +
             (f.match ? f.match.length : 0) + (f.genre ? f.genre.length : 0) +
             (state.artist ? 1 : 0) + (state.album ? 1 : 0);
     }
@@ -382,21 +280,7 @@
         if (f.stem_has.length) p.set('stems_has', f.stem_has.join(','));
         if (f.stem_lacks.length) p.set('stems_lacks', f.stem_lacks.join(','));
         if (f.lyrics) p.set('has_lyrics', f.lyrics);
-        // The two modes answer different questions, so only one filters at a
-        // time: sending both would silently intersect them.
-        if (f.tunings.length && f.tuningMatch !== 'playable') p.set('tunings', f.tunings.join(','));
-        // Tell the server which instrument perspective to use for tuning
-        // columns (bass_tuning_name vs tuning_name, etc.).
-        var instId = sm && sm._activeInstrumentProfile;
-        // Which perspective the `tunings` filter + the tuning sort read.
-        // Uses the 3-perspective model (guitar-lead, guitar-rhythm, bass) from
-        // the active instrument profile. Drums/piano/keys fall through to the
-        // default guitar-lead perspective.
-        if (libInstrument() !== 'guitar-lead') p.set('instrument', libInstrument());
-        // "Playable without retuning": send the player's LIVE tuning and let the
-        // server do the pitch maths (the pitch tables live in lib/tunings.py —
-        // duplicating them here is how the two drift apart).
-        applyPlayableParams(p, f);
+        if (f.tunings.length) p.set('tunings', f.tunings.join(','));
         if (f.mastery && f.mastery.length) p.set('mastery', f.mastery.join(','));
         if (f.match && f.match.length) p.set('match', f.match.join(','));
         if (f.genre && f.genre.length) p.set('genre', f.genre.join(','));
@@ -591,108 +475,23 @@
         if (window.syncLibrarySong && sid) window.syncLibrarySong(state.provider, sid, { playWhenReady: true });
     }
 
-    // Per-role accuracy helpers — find the arrangement matching the active
-    // instrument role and read its per-arrangement accuracy.
-    function _matchingArrangementIndex(song) {
-        if (!song || !song.arrangements || !song.arrangements.length) return null;
-        var want = state.filters.arr_has;
-        var activeProfileId = (sm && sm._activeInstrumentProfile) || '';
-        var activeRoleLabel = null;
-        if (activeProfileId) {
-            var insts = window.feedBack && window.feedBack._instruments;
-            if (Array.isArray(insts)) {
-                for (var ii = 0; ii < insts.length; ii++) {
-                    var ir = insts[ii].roles || [];
-                    for (var ij = 0; ij < ir.length; ij++) {
-                        if (activeProfileId === insts[ii].id + '-' + ir[ij].id) {
-                            activeRoleLabel = ir[ij].label;
-                            break;
-                        }
-                    }
-                    if (activeRoleLabel) break;
-                }
-            }
-        }
-        if (activeRoleLabel) {
-            for (var i = 0; i < song.arrangements.length; i++) {
-                var a = song.arrangements[i];
-                var sn = a.smart_name || a.name || '';
-                if (sn === activeRoleLabel) return a.index != null ? a.index : i;
-            }
-            return null;
-        }
-        if (!want.length) return null;
-        for (var i = 0; i < song.arrangements.length; i++) {
-            var a2 = song.arrangements[i];
-            var sn2 = a2.smart_name || a2.name || '';
-            for (var j = 0; j < want.length; j++) {
-                if (sn2 === want[j]) return a2.index != null ? a2.index : i;
-            }
-        }
-        return null;
-    }
-
-    function _perArrangementAccuracy(filename, arrIndex) {
-        var map = state.arrangementAccuracy[filename];
-        if (!map) return null;
-        return typeof map[arrIndex] === 'number' ? map[arrIndex] : null;
-    }
-
     // Accuracy badge markup. `variant` is 'grid' (overlay pill on the card art,
-    // positioned `absolute bottom-0 right-0`) or 'tree' (inline `<span>`).
-    // Cards show per-role accuracy: the arrangement matching the current
-    // instrument role determines the displayed percentage, not the song-wide max.
-    // A hover overlay reveals all arrangements with their individual accuracies.
-    function accuracyBadge(filename, variant, song) {
-        if (!song && state.songsById) song = state.songsById[filename];
-        var acc = null;
-        var arrIdx = song ? _matchingArrangementIndex(song) : null;
-        var hasMatchingArrangement = arrIdx != null;
-        if (hasMatchingArrangement) {
-            acc = _perArrangementAccuracy(filename, arrIdx);
-        }
-        var hasArr = song && song.arrangements && song.arrangements.length > 0;
-        if (acc == null && !hasArr) return '';
-
-        var pct = acc != null ? Math.floor(acc * 100) : null;
-        var displayLabel;
-        if (pct != null) {
-            displayLabel = pct + '%';
-        } else if (!state.filters.arr_has.length && !hasMatchingArrangement) {
-            displayLabel = 'n/a';
-        } else {
-            displayLabel = '\u2014 %';
-        }
+    // default) or 'tree' (inline percentage in the list row). Both carry the
+    // .fb-acc-badge class so a post-play refresh (repaintAccuracy) can find and
+    // replace them in place without re-rendering the whole list.
+    function accuracyBadge(filename, variant) {
+        const acc = state.accuracy[filename];
+        if (acc == null) return '';
+        // Floor, never round: 100% must mean every note hit.
+        const pct = Math.floor(acc * 100);
         if (variant === 'tree') {
-            var color = acc != null && acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc != null && acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
-            return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + displayLabel + '</span>';
+            const color = acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
+            return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + pct + '%</span>';
         }
-
-        var hoverOverlay = '';
-        if (song && song.arrangements && song.arrangements.length > 0) {
-            var songTuning = song.tuning_name || '';
-            var items = '';
-            for (var ai = 0; ai < song.arrangements.length; ai++) {
-                var a = song.arrangements[ai];
-                var aiIdx = a.index != null ? a.index : ai;
-                var aAcc = _perArrangementAccuracy(filename, aiIdx);
-                var aName = a.smart_name || a.name || ('#' + aiIdx);
-                var aLabel = aAcc != null ? Math.floor(aAcc * 100) + '%' : '\u2014';
-                var aColor = aAcc != null
-                    ? (aAcc >= MASTERY_ACCURACY ? 'text-fb-good' : aAcc >= 0.5 ? 'text-fb-mid' : 'text-fb-low')
-                    : 'text-gray-600';
-                var isPitched = _isPitchedArrangement(aName);
-                var tuningPart = isPitched && songTuning ? ' \u00b7 ' + esc(songTuning) : '';
-                items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + tuningPart + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
-            }
-            hoverOverlay = '<div class="opacity-0 group-hover:opacity-100 transition" style="position:absolute;bottom:0;left:0;right:0;background:rgba(0,0,0,0.8);border-radius:0 0 0.5rem 0.5rem;z-index:20;pointer-events:none">' + items + '</div>';
-        }
-
-        var badgeColor = acc != null ? (acc >= MASTERY_ACCURACY ? 'rgba(34,197,94,0.9)' : (acc >= 0.5 ? 'rgba(234,179,8,0.9)' : 'rgba(239,68,68,0.9)')) : 'rgba(75,85,99,0.9)';
-        var badgeText = acc != null && acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
-        var borderColor = acc != null ? (acc >= MASTERY_ACCURACY ? '#22c55e' : (acc >= 0.5 ? '#eab308' : '#ef4444')) : '#4b5563';
-        return '<span class="fb-acc-badge absolute bottom-0 right-0 px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1 opacity-100 group-hover:opacity-0 transition border-l-2 border-t-2 ' + badgeText + '" style="background:' + badgeColor + ';border-color:' + borderColor + '">' +
-            displayLabel + '</span>' + hoverOverlay;
+        const color = acc >= MASTERY_ACCURACY ? 'bg-fb-good' : (acc >= 0.5 ? 'bg-fb-mid' : 'bg-fb-low');
+        const text = acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
+        return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + color + '/90 ' + text + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1">' +
+            '<svg class="w-3 h-3" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><circle cx="12" cy="12" r="4"/></svg>' + pct + '%</span>';
     }
 
     // ── Metadata-refresh per-tile state (the "Refresh Metadata" batch) ─────────
@@ -749,14 +548,12 @@
     // snapshot would otherwise survive a sidebar return, so we force a full
     // re-fetch on the next entry. (feedBack — "No DLC until restart".)
     let _libraryDirty = false;
-    let _arrAutoInstrument = null;
-    let _autoFilterEnabled = true;
 
     function repaintAccuracy(key) {
         const apply = (el, variant) => {
             if (el.getAttribute('data-fn') !== key) return;
             const old = el.querySelector('.fb-acc-badge');
-            const html = accuracyBadge(key, variant, state.songsById[key]);
+            const html = accuracyBadge(key, variant);
             if (variant === 'grid') {
                 const art = el.querySelector('[data-v3-play]');
                 if (!art) return;
@@ -779,13 +576,14 @@
     async function applyScoreRefresh() {
         if (!_dirtyScores.size) return;
         const fresh = await jget('/api/stats/best');
-        const freshArr = await jget('/api/stats/best-by-arrangement');
+        // Fetch failed — keep the entries dirty so the next trigger (or screen
+        // enter) retries rather than silently dropping the badge update.
         if (!fresh) return;
         state.accuracy = fresh;
-        if (freshArr) state.arrangementAccuracy = freshArr;
         const keys = Array.from(_dirtyScores);
         _dirtyScores.clear();
         keys.forEach(repaintAccuracy);
+        // A new score shifts the repertoire meter + the keep-practicing shelf.
         renderLibraryHome();
     }
 
@@ -883,7 +681,7 @@
                 '<button class="v3-kp-card group text-left" data-kp="' + esc(r.filename) + '" data-arr="' + esc(r.arrangement != null ? r.arrangement : '') + '" title="' + esc(r.title) + '">' +
                 '<div class="relative aspect-square rounded-lg overflow-hidden bg-fb-card">' +
                 '<img src="' + esc(r.art_url) + '" alt="" loading="lazy" decoding="async" class="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105" onerror="this.style.visibility=\'hidden\'">' +
-                accuracyBadge(r.filename, 'grid') +
+                accuracyBadge(r.filename) +
                 '</div>' +
                 '<div class="mt-1 text-sm text-fb-text truncate">' + esc(r.title) + '</div>' +
                 '<div class="text-xs text-fb-textDim truncate">' + esc(r.artist) + '</div>' +
@@ -988,10 +786,6 @@
     // so without them the chips render exactly as before. Decoration runs AFTER the
     // (sync) window paint so scrolling stays snappy; a token cancels a superseded pass.
     let _tuningDecorToken = 0;
-    // The instrument the current grid was queried/painted for, so a
-    // working-tuning change can tell a guitar<->bass SWITCH (re-query) from a
-    // retune within the same instrument (re-colour only).
-    let _lastRenderInstrument = null;
     function _applyChipMatch(chip, stateName) {
         chip.classList.remove('bg-fb-mid', 'bg-emerald-500', 'bg-amber-400');
         chip.classList.add(stateName === 'match' ? 'bg-emerald-500'
@@ -1011,11 +805,10 @@
         for (const chip of chips) {
             const offs = chip.getAttribute('data-tuning-offsets').split(',').map(Number);
             if (!offs.length || offs.some((n) => !isFinite(n))) continue;
-            // Pass the instrument so coverage uses the right base pitches.
+            // Pass the instrument so coverage uses the right base pitches (bass vs guitar).
             const arrangement = chip.dataset.tuningBass === '1' ? 'Bass' : 'Lead';
-            const instId = chip.dataset.tuningInstrument || (chip.dataset.tuningBass === '1' ? 'bass' : 'guitar');
             let rep = null;
-            try { rep = await cov({ tuning: offs, stringCount: offs.length, arrangement: arrangement, instrument: instId }); } catch (_) { rep = null; }
+            try { rep = await cov({ tuning: offs, stringCount: offs.length, arrangement: arrangement }); } catch (_) { rep = null; }
             if (token !== _tuningDecorToken) return;   // superseded by a re-paint / tuning change
             if (rep) _applyChipMatch(chip, rep.covered ? 'match' : 'retune');
         }
@@ -1032,64 +825,39 @@
         const shown = song.display_chart ? Object.assign({}, song, song.display_chart) : song;
         // In select mode the checkbox occupies top-2 left-2, so shift the
         // tuning chip right (left-9) to avoid overlapping it.
-        // Bass players see the bass chart's tuning (guitar fallback) — the card
-        // must agree with the facet/filter or the grid contradicts the pills.
-        const shownTuning = shownTuningName(shown);
         const tuningLabel = (typeof window.displayTuningName === 'function')
-            ? window.displayTuningName(shownTuning)
-            : (shownTuning || '');
+            ? window.displayTuningName(shown.tuning_name || shown.tuning)
+            : (shown.tuning_name || '');
         let tuning = '';
         if (tuningLabel) {
             const rawOffsets = (typeof window.parseRawTuningOffsets === 'function')
                 ? (window.parseRawTuningOffsets(shown.tuning_offsets)
-                    || window.parseRawTuningOffsets(shownTuningOffsets(shown))
-                    || window.parseRawTuningOffsets(shownTuning)
-                    || window.parseRawTuningOffsets(shown.tuning))
+                    || window.parseRawTuningOffsets(shown.tuning_name || shown.tuning))
                 : null;
             const targetNotes = (tuningLabel === 'Custom Tuning' && rawOffsets
                 && typeof window.displayTuningTargets === 'function')
                 ? window.displayTuningTargets(rawOffsets, { tuningName: tuningLabel })
                 : '';
-            // Mark a tuning we INFERRED from the guitar chart (this song has no
-            // bass arrangement) so a bass player isn't shown a borrowed tuning
-            // as if it were their part's. `~` keeps the chip compact; the title
-            // spells it out.
-            const inferred = shown.tuning_inferred === true;
-            const badgeTitle = (targetNotes
+            const badgeTitle = targetNotes
                 ? ('Custom Tuning: ' + targetNotes)
-                : tuningLabel)
-                + (inferred ? ' — from the guitar chart (no bass arrangement)' : '');
-            const pos = 'absolute top-0 rounded-br-md ' + (state.selectMode ? 'left-9' : 'left-0');
+                : tuningLabel;
+            const pos = 'absolute top-2 ' + (state.selectMode ? 'left-9' : 'left-2');
             // Tag the chip with its offsets so decorateTuningChips() can colour it
             // green (matches your current tuning) / amber (needs a retune) after paint.
             // Also flag a bass-only song (every arrangement is a bass part) so coverage
             // scores its bass tuning against the bass base pitches, not guitar — otherwise
             // a 4-string bass tuning read as guitar can false-match a guitar player.
             const chipArrs = shown.arrangements || [];
-            // Bass either because the chip is SHOWING the bass chart's tuning
-            // Which instrument this chip represents — read from the active
-            // instrument profile in the registry, falling back to the
-            // 3-perspective bass/lead detection for the tuner plugin's coverage
-            // checker (which only knows 'Bass' and 'Lead' arrangement labels).
-            const inst = _activeInstrument();
-            const instId = inst ? inst.id : (libInstrument() === 'bass' ? 'bass' : 'guitar');
-            const isBass = instId === 'bass'
-                || (chipArrs.length > 0
-                    && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || '')));
-            const stringCount = inst && inst.string_count ? inst.string_count : (isBass ? 4 : 6);
-            // Truncate offsets to the instrument's string count so the
-            // coverage checker compares the right number of strings.
-            let chipOffsets = rawOffsets;
-            if (chipOffsets && chipOffsets.length > stringCount) chipOffsets = chipOffsets.slice(0, stringCount);
-            const matchAttr = (chipOffsets && chipOffsets.length)
-                ? ' data-tuning-chip data-tuning-offsets="' + esc(chipOffsets.join(',')) + '"'
-                    + ' data-tuning-instrument="' + esc(instId) + '"'
-                    + (isBass ? ' data-tuning-bass="1"' : '') : '';
+            const chipIsBass = chipArrs.length > 0
+                && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || ''));
+            const matchAttr = (rawOffsets && rawOffsets.length)
+                ? ' data-tuning-chip data-tuning-offsets="' + esc(rawOffsets.join(',')) + '"'
+                    + (chipIsBass ? ' data-tuning-bass="1"' : '') : '';
             if (targetNotes) {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
                     + esc('Custom Tuning') + '<br><span class="font-semibold tracking-wide">' + esc(targetNotes) + '</span></span>';
             } else {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + (inferred ? '<span class="opacity-60"> ~</span>' : '') + '</span>';
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + '</span>';
             }
         }
         // Display-only (pointer-events-none) so a click falls through to the
@@ -1124,7 +892,7 @@
         return '<div class="group relative" data-fn="' + esc(key) + '" data-letter="' + esc(songBucket(song)) + '" data-library-song="' + esc(songId(song)) + '" data-library-provider="' + esc(state.provider) + '">' +
             '<div class="relative aspect-square rounded-lg overflow-hidden bg-fb-card cursor-pointer' + selRing + '" data-v3-play>' +
             '<img src="' + esc(artUrl(shown)) + '" alt="" loading="lazy" decoding="async" class="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105" onerror="this.style.visibility=\'hidden\'">' +
-            tuning + checkbox + accuracyBadge(key, 'grid', song) + fmtBadge(shown) + personalBadges(song) + enrichBadge(key, song.unmatched) + overlay +
+            tuning + checkbox + accuracyBadge(key) + fmtBadge(shown) + personalBadges(song) + enrichBadge(key, song.unmatched) + overlay +
             '<div class="absolute top-2 right-2 flex gap-1 opacity-0 group-hover:opacity-100 transition">' +
             inlineBtns +
             '<button data-fav data-fav-idle="text-white" title="Favorite" aria-label="Favorite" aria-pressed="' + (fav ? 'true' : 'false') + '" class="w-7 h-7 rounded-full bg-black/50 hover:bg-black/70 flex items-center justify-center text-sm ' + (fav ? 'text-fb-accent' : 'text-white') + '">' + (fav ? '♥' : '♡') + '</button>' +
@@ -2699,7 +2467,7 @@
         '<span class="flex-1 min-w-0 cursor-pointer" data-v3-play><span class="block text-sm text-fb-text truncate">' + esc(s.title) + '</span></span>' +
         (chips ? '<span class="hidden sm:flex items-center gap-1 shrink-0">' + chips + '</span>' : '') +
         (fl ? '<span class="text-[0.5625rem] font-bold px-1 py-0.5 rounded shrink-0 ' + (fl === 'FEEDPAK' ? 'bg-fb-primary/20 text-fb-primary' : 'bg-fb-card text-fb-textDim') + '">' + fl + '</span>' : '') +
-        accuracyBadge(k, 'tree', s) +
+        accuracyBadge(k, 'tree') +
         // Same fav / save-for-later / overflow-menu cluster as the grid
         // card. Always shown (like the arrangement chips), not hover-
         // revealed. wireCards() binds all three for any [data-fn].
@@ -2721,91 +2489,6 @@
 
     function _artistHostEl() { return document.getElementById('v3-songs-artistpage'); }
 
-    // ── Instrument-aware tuning (the bass-player tuning-filter report) ────────
-    // A song's bass chart is often in a different tuning from its guitar chart,
-    // so the tuning facet/filter/sort and the card chip must speak for the
-    // instrument the player actually plays. The host's working-tuning
-    // capability already holds the live selection (seeded from /api/settings on
-    // boot, updated when the player switches) — read it rather than adding
-    // another settings fetch. `state.settingsInstrument` is the fallback for
-    // hosts where the capability isn't mounted.
-    // Three perspectives, matching `active_instrument_profile`: lead and rhythm
-    // guitar charts can be tuned differently too, so a rhythm player hits the
-    // same bug a bassist did. The PROFILE is the only three-valued source (the
-    // working-tuning capability knows guitar-vs-bass but not lead-vs-rhythm),
-    // so it wins; the capability is the live fallback for hosts where the
-    // profile hasn't loaded.
-    const PERSPECTIVES = ['guitar-lead', 'guitar-rhythm', 'bass'];
-    function libInstrument() {
-        if (PERSPECTIVES.indexOf(state.settingsProfile) >= 0) return state.settingsProfile;
-        try {
-            const wt = window.feedBack && window.feedBack.workingTuning;
-            if (wt && typeof wt.get === 'function') {
-                const cur = wt.get();
-                if (cur && cur.instrument === 'bass') return 'bass';
-            }
-        } catch (_) { /* capability absent/erroring — fall through to settings */ }
-        return state.settingsInstrument === 'bass' ? 'bass' : 'guitar-lead';
-    }
-
-    // "Playable without retuning" mode reads the player's CURRENT tuning from
-    // the working-tuning capability (the live session state the tuner writes),
-    // not a separate setting. No capability => we cannot know the current
-    // tuning, so the mode is unavailable rather than guessed.
-    function currentWorkingTuning() {
-        try {
-            const wt = window.feedBack && window.feedBack.workingTuning;
-            if (!wt || typeof wt.get !== 'function') return null;
-            const cur = wt.get();
-            if (!cur || !Array.isArray(cur.offsets) || !cur.offsets.length) return null;
-            return cur;
-        } catch (_) { return null; }
-    }
-
-    function playableAvailable() { return !!currentWorkingTuning(); }
-
-    function applyPlayableParams(p, f) {
-        if (f.tuningMatch !== 'playable') return;
-        const cur = currentWorkingTuning();
-        if (!cur) return;
-        p.set('tuning_match', 'playable');
-        p.set('playable_offsets', cur.offsets.join(','));
-        p.set('playable_instrument', cur.instrument === 'bass' ? 'bass' : 'guitar');
-        p.set('playable_string_count', String(cur.stringCount || cur.offsets.length));
-    }
-
-    // Short human label for the perspective, for the facet/sort headers.
-    function libInstrumentLabel() {
-        const p = libInstrument();
-        return p === 'bass' ? 'bass' : p === 'guitar-rhythm' ? 'rhythm' : 'lead';
-    }
-
-    // The column a row's tuning lives in for the active perspective.
-    function perspectiveTuningField() {
-        const p = libInstrument();
-        return p === 'bass' ? 'bass_tuning_name'
-            : p === 'guitar-rhythm' ? 'rhythm_tuning_name' : '';
-    }
-
-    // The tuning a card should SHOW: bass players see the bass chart's tuning,
-    // falling back to the song (guitar-derived) tuning when the song has no
-    // bass arrangement — the common case, so the fallback is not an edge path.
-    function shownTuningName(song) {
-        const f = perspectiveTuningField();
-        if (f && song[f]) return song[f];
-        return song.tuning_name || song.tuning;
-    }
-
-    function shownTuningOffsets(song) {
-        const f = perspectiveTuningField();
-        if (f) {
-            const offKey = f.replace('_name', '_offsets');
-            if (song[offKey]) return song[offKey];
-            return song.tuning_offsets;
-        }
-        return song.tuning_offsets;
-    }
-
     // Sync the two Settings gates into module state (fire-and-forget — the
     // cached flags gate entry-point rendering; openArtistPage re-checks).
     function refreshArtistPageGates() {
@@ -2813,13 +2496,6 @@
             if (!cfg) return;
             state.artistPagesEnabled = cfg.artist_pages_enabled !== false;
             state.artistLinksEnabled = cfg.artist_external_links === true;
-            // Fallback instrument for hosts without the working-tuning capability.
-            state.settingsInstrument = cfg.instrument === 'bass' ? 'bass' : 'guitar';
-            // The three-valued perspective source (lead / rhythm / bass).
-            state.settingsProfile = cfg.active_instrument_profile || '';
-            if (cfg && typeof cfg.auto_filter_instrument === 'boolean') {
-                _autoFilterEnabled = cfg.auto_filter_instrument;
-            }
         });
     }
 
@@ -3133,17 +2809,12 @@
         else if (s === 'has') lacksArr.push(value);
         // 'lacks' → cycles back to any (already removed)
     }
-    function triPill(group, value, label, st, title) {
+    function triPill(group, value, label, st) {
         const cls = st === 'has' ? 'bg-fb-good/30 text-fb-good border-fb-good/40'
             : st === 'lacks' ? 'bg-fb-low/30 text-fb-low border-fb-low/40'
                 : 'bg-gray-800/50 text-fb-textDim border-gray-700';
         const mark = st === 'has' ? '✓ ' : st === 'lacks' ? '✕ ' : '';
-        const tip = title ? ' title="' + esc(title) + '"' : '';
-        return '<button data-tri="' + group + '" data-val="' + esc(value) + '" class="px-2 py-1 rounded-md text-xs border ' + cls + '"' + tip + '>' + mark + esc(label) + '</button>';
-    }
-    function renderDrawerIfOpen() {
-        const d = document.getElementById('v3-songs-drawer');
-        if (d && !d.classList.contains('hidden') && d.innerHTML.trim()) renderDrawer();
+        return '<button data-tri="' + group + '" data-val="' + esc(value) + '" class="px-2 py-1 rounded-md text-xs border ' + cls + '">' + mark + esc(label) + '</button>';
     }
     function renderDrawer() {
         const d = document.getElementById('v3-songs-drawer');
@@ -3153,18 +2824,8 @@
             '<div class="p-5 space-y-5">' +
             '<div class="flex items-center justify-between"><h3 class="text-lg font-semibold text-fb-text">Filters</h3>' +
             '<button data-drawer-close class="text-fb-textDim hover:text-fb-text">✕</button></div>' +
-            section('Arrangements', _arrangementOptions().map((a) => triPill('arr', a, a, triState(f.arr_has, f.arr_lacks, a))).join('')) +
-            section('Stems (feedpak)', STEMS.map((s) => triPill('stem', s, s, triState(f.stem_has, f.stem_lacks, s))).join('') +
-                (() => {
-                    // One-click "which songs still need splitting": lacks EVERY
-                    // instrument stem — the same query Stem Splitter's own
-                    // missing-stems view runs. Toggles off if already active.
-                    const on = STEMS.every((s) => f.stem_lacks.includes(s)) && !f.stem_has.length;
-                    return '<button data-stem-unsplit class="px-2 py-1 rounded-md text-xs border '
-                        + (on ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700')
-                        + '" title="Songs with no instrument stems — not yet split">'
-                        + (on ? '✕ ' : '') + 'Not split</button>';
-                })()) +
+            section('Arrangements', ARRANGEMENTS.map((a) => triPill('arr', a, a, triState(f.arr_has, f.arr_lacks, a))).join('')) +
+            section('Stems (feedpak)', STEMS.map((s) => triPill('stem', s, s, triState(f.stem_has, f.stem_lacks, s))).join('')) +
             section('Lyrics', ['', '1', '0'].map((v) => '<button data-lyrics="' + v + '" class="px-2 py-1 rounded-md text-xs border ' + (f.lyrics === v ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + (v === '' ? 'Any' : v === '1' ? 'Has lyrics' : 'No lyrics') + '</button>').join('')) +
             // Progress (mastery bands) — multi-select; server filters via song_stats.
             section('Progress', [['mastered', 'Mastered'], ['in_progress', 'In progress'], ['not_started', 'Not started']].map((it) => '<button data-mastery="' + it[0] + '" class="px-2 py-1 rounded-md text-xs border ' + (f.mastery.includes(it[0]) ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + it[1] + '</button>').join('')) +
@@ -3173,32 +2834,7 @@
             section('Match', [['review', 'To review'], ['matched', 'Matched'], ['unmatched', 'Unmatched'], ['pending', 'Not scanned']].map((it) => '<button data-match="' + it[0] + '" class="px-2 py-1 rounded-md text-xs border ' + (f.match.includes(it[0]) ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + it[1] + '</button>').join('')) +
             // Genre facet — dynamic list from /api/library/genres (primary genre).
             (state.genres && state.genres.length ? section('Genre', state.genres.map((g) => '<button data-genre="' + esc(g) + '" class="px-2 py-1 rounded-md text-xs border ' + (f.genre.includes(g) ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + esc(g) + '</button>').join('')) : '') +
-            // The facet header NAMES the perspective. Silent instrument-following
-            // is the original bug in a new place: the user must be able to tell
-            // which instrument these tunings describe.
-            section('Tuning (' + libInstrumentLabel() + ')',
-                // MODE toggle. Exact match answers "which tuning is this
-                // labelled"; Playable answers "will this cost me a retune" —
-                // which is what a player actually wants. Both are offered;
-                // exact stays the default so nothing changes unasked.
-                '<div class="flex gap-1 mb-2">'
-                + [['exact', 'Exact tuning'], ['playable', 'Playable without retuning']].map((m) => {
-                    const on = (f.tuningMatch || 'exact') === m[0];
-                    const dis = m[0] === 'playable' && !playableAvailable();
-                    return '<button data-tuning-match="' + m[0] + '"'
-                        + (dis ? ' disabled' : '')
-                        + (dis ? ' title="Needs your current tuning — open the tuner first"' : '')
-                        + ' class="px-2 py-1 rounded-md text-xs border '
-                        + (on ? 'bg-fb-primary text-white border-fb-primary'
-                            : 'bg-gray-800/50 text-fb-textDim border-gray-700')
-                        + (dis ? ' opacity-40 cursor-not-allowed' : '') + '">'
-                        + esc(m[1]) + '</button>';
-                }).join('')
-                + '</div>'
-                + (f.tuningMatch === 'playable'
-                    ? '<div class="text-xs text-fb-textDim mb-2">Charts you can play in your current tuning, no retune. Songs whose lowest string sits below yours are excluded.</div>'
-                    : '')
-                + ((state.tuningNames || []).map((t) => {
+            section('Tuning', (state.tuningNames || []).map((t) => {
                 // Filter on the server's grouping key (raw offsets for customs)
                 // so two "Custom Tuning" entries are distinct; show their target
                 // notes in the label so they're distinguishable.
@@ -3211,17 +2847,8 @@
                     const notes = offs ? window.displayTuningTargets(offs, { tuningName: t.name }) : '';
                     if (notes) label = 'Custom · ' + notes;
                 }
-                // Be honest about the fallback: when some of a row's songs have
-                // no bass chart and are borrowing the guitar tuning, say so
-                // rather than presenting a borrowed tuning as a measured one.
-                const inf = t.inferred_count || 0;
-                const title = inf
-                    ? inf + ' of ' + t.count + ' inferred from the guitar chart (no bass arrangement)'
-                    : '';
-                const countLabel = inf ? t.count + ', ' + inf + ' inferred' : String(t.count);
-                return triPill('tuning', val, label + ' (' + countLabel + ')',
-                    f.tunings.includes(val) ? 'has' : 'any', title);
-            }).join('') || '<span class="text-xs text-fb-textDim">No tunings</span>')) +
+                return triPill('tuning', val, label + ' (' + t.count + ')', f.tunings.includes(val) ? 'has' : 'any');
+            }).join('') || '<span class="text-xs text-fb-textDim">No tunings</span>') +
             // Multi-chart grouping toggle (P5e) — a VIEW mode, not a filter
             // (never counted in the badge, never saved into collection rules).
             // Local provider only: it's the one that implements group=.
@@ -3251,18 +2878,6 @@
             else if (g === 'tuning') { const i = f.tunings.indexOf(v); if (i >= 0) f.tunings.splice(i, 1); else f.tunings.push(v); }
             renderDrawer();
         }));
-        d.querySelectorAll('[data-tuning-match]').forEach((b) => b.addEventListener('click', () => {
-            if (b.disabled) return;
-            f.tuningMatch = b.getAttribute('data-tuning-match');
-            renderDrawer();
-        }));
-        d.querySelector('[data-stem-unsplit]')?.addEventListener('click', () => {
-            const on = STEMS.every((s) => f.stem_lacks.includes(s)) && !f.stem_has.length;
-            f.stem_has.length = 0;
-            f.stem_lacks.length = 0;
-            if (!on) f.stem_lacks.push(...STEMS);
-            renderDrawer();
-        });
         d.querySelectorAll('[data-lyrics]').forEach((b) => b.addEventListener('click', () => { f.lyrics = b.getAttribute('data-lyrics'); renderDrawer(); }));
         d.querySelectorAll('[data-mastery]').forEach((b) => b.addEventListener('click', () => { const v = b.getAttribute('data-mastery'); const i = f.mastery.indexOf(v); if (i >= 0) f.mastery.splice(i, 1); else f.mastery.push(v); renderDrawer(); }));
         d.querySelector('[data-grouping]')?.addEventListener('click', () => {
@@ -3276,7 +2891,7 @@
         d.querySelector('[data-drawer-tidy]')?.addEventListener('click', openArtistTidyUp);
         d.querySelector('[data-drawer-close]')?.addEventListener('click', closeDrawer);
         d.querySelector('[data-drawer-clear]')?.addEventListener('click', async () => {
-            state.filters = { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [], tuningMatch: 'exact' };
+            state.filters = { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [] };
             state.artist = '';
             state.album = '';
             renderDrawer();
@@ -3863,15 +3478,13 @@
         const providers = await loadProviders();
         const [, tn] = await Promise.all([
             (async () => { state.accuracy = (await jget('/api/stats/best')) || {}; })(),
-            jget('/api/library/tuning-names?provider=' + enc(state.provider)
-                + '&instrument=' + enc(libInstrument())),
+            jget('/api/library/tuning-names?provider=' + enc(state.provider)),
             loadArtistCatalog(),
             // Artist-page gates (PR-B) ride the initial fetch batch so the
             // first card paint already knows whether artist lines are links.
             refreshArtistPageGates(),
         ]);
         state.tuningNames = (tn && tn.tunings) || [];
-        _lastRenderInstrument = libInstrument();
         try { const _g = await jget('/api/library/genres?provider=' + enc(state.provider)); state.genres = (_g && _g.genres) || []; } catch (e) { state.genres = []; }
 
         const opt = (arr, sel) => arr.map(([v, l]) => '<option value="' + esc(v) + '"' + (v === sel ? ' selected' : '') + '>' + esc(l) + '</option>').join('');
@@ -3899,13 +3512,7 @@
             '<select id="v3-songs-artist" class="' + ctrl + ' max-w-[11rem]" aria-label="Artist">' + artistSelectHtml() + '</select>' +
             '<select id="v3-songs-album" class="' + ctrl + ' max-w-[11rem]" aria-label="Album"' + (state.artist ? '' : ' disabled') + '>' + albumSelectHtml() + '</select>' +
             '<div class="flex rounded-md overflow-hidden border border-gray-700"><button id="v3-songs-grid-btn" class="px-3 py-2 text-sm">▦</button><button id="v3-songs-tree-btn" class="px-3 py-2 text-sm">≣</button><button id="v3-songs-albums-btn" title="Albums" class="px-3 py-2 text-sm">💿</button><button id="v3-songs-folder-btn" class="px-3 py-2 text-sm" style="display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;width:2.25rem"><svg fill="currentColor" viewBox="0 0 16 16" style="width:12px;height:12px;flex-shrink:0"><path d="M1 3.5A1.5 1.5 0 012.5 2h3.086a1.5 1.5 0 011.06.44l.915.914H13.5A1.5 1.5 0 0115 4.914V12.5a1.5 1.5 0 01-1.5 1.5h-11A1.5 1.5 0 011 12.5v-9z"/></svg></button></div>' +
-            // Name the perspective on the SORT too, not just the filter: tuning
-            // sort orders by musical distance from standard, and for a bass
-            // player that distance is measured on the bass tuning. Unlabelled,
-            // the grid silently reorders with no visible cause.
-            '<select id="v3-songs-sort" class="' + ctrl + '">' + opt(
-                SORTS.map(([v, l]) => [v, v === 'tuning' ? l + ' (' + libInstrumentLabel() + ')' : l]),
-                state.sort) + '</select>' +
+            '<select id="v3-songs-sort" class="' + ctrl + '">' + opt(SORTS, state.sort) + '</select>' +
             '<select id="v3-songs-format" class="' + ctrl + '">' + opt(FORMATS, state.format) + '</select>' +
             '<button id="v3-songs-filters" class="relative ' + ctrl + ' flex items-center gap-2">Filters<span id="v3-songs-filter-count" class="hidden bg-fb-primary text-white text-xs rounded-full px-1.5">0</span></button>' +
             '<button id="v3-songs-select" class="' + ctrl + (state.selectMode ? ' bg-fb-primary text-white' : '') + '">Select</button>' +
@@ -4473,141 +4080,7 @@
         },
     };
 
-    // ── Grid cursor navigation (arrow keys / gamepad d-pad) ─────────────────
-    // shortcuts.js's generic library arrow-nav (_handleLibArrowNav) can't reach
-    // this screen: it assumes every navigable item is already a DOM node, but
-    // this grid is windowed — most of the library isn't in the DOM at any given
-    // scroll position. Cursor state here is an absolute index into state.songs,
-    // and moving it may need to fetch a page and/or scroll the window before the
-    // target card exists to highlight or activate.
-    let _gpIdx = null;
-
-    function _gpCardEl(idx) {
-        return document.querySelector('#v3-songs-grid [data-idx="' + idx + '"]');
-    }
-
-    function _gpApplyHighlight() {
-        const prev = document.querySelector('#v3-songs-grid [data-gp-cursor]');
-        if (prev) {
-            prev.removeAttribute('data-gp-cursor');
-            prev.querySelector('[data-v3-play]')?.classList.remove('ring-2', 'ring-fb-primary');
-        }
-        if (_gpIdx == null) return;
-        const el = _gpCardEl(_gpIdx);
-        if (!el) return;
-        el.setAttribute('data-gp-cursor', '1');
-        el.querySelector('[data-v3-play]')?.classList.add('ring-2', 'ring-fb-primary');
-    }
-
-    async function _gpEnsureVisible(idx) {
-        const main = document.getElementById('v3-main'), sizer = _sizerEl();
-        if (!main || !sizer) return;
-        const { cols, rowH } = measureGeom();
-        const row = Math.floor(idx / Math.max(1, cols));
-        const sizerTop = _sizerTopInScroller(main, sizer);
-        const rowTop = sizerTop + row * rowH;
-        const rowBottom = rowTop + rowH;
-        const viewTop = main.scrollTop, viewBottom = viewTop + main.clientHeight;
-        if (rowTop < viewTop) main.scrollTop = rowTop;
-        else if (rowBottom > viewBottom) main.scrollTop = rowBottom - main.clientHeight;
-        await renderWindow();
-
-        // #v3-songs-toolbar is sticky, but only pins to the top once scrolled
-        // PAST its natural in-flow position — before that point it isn't
-        // covering anything, after it covers a fixed band. That makes its
-        // occlusion scroll-dependent in a way no single precomputed offset
-        // captures, so measure the real rendered overlap and correct for it,
-        // rather than assuming the toolbar's height is always "lost" space.
-        const toolbar = document.getElementById('v3-songs-toolbar');
-        const cardEl = _gpCardEl(idx);
-        if (toolbar && cardEl) {
-            const overlap = toolbar.getBoundingClientRect().bottom - cardEl.getBoundingClientRect().top;
-            if (overlap > 0) {
-                // Push the row DOWN the screen to clear the toolbar — that means
-                // scrolling the content back UP, i.e. decreasing scrollTop (screen
-                // position = content position - scrollTop).
-                main.scrollTop -= overlap;
-                await renderWindow();
-            }
-        }
-    }
-
-    async function _gpMove(delta) {
-        if (!state.total) return;
-        if (_gpIdx == null) {
-            // Nothing selected yet — land on the first card and stop, same as
-            // shortcuts.js's legacy _handleLibArrowNav does for an empty
-            // selection: the first press establishes a cursor, it doesn't also
-            // move it (Right/Down previously skipped straight past row 0).
-            _gpIdx = 0;
-        } else {
-            const next = Math.max(0, Math.min(state.total - 1, _gpIdx + delta));
-            if (next === _gpIdx) return;
-            _gpIdx = next;
-        }
-        await ensureWindow(Math.max(0, _gpIdx - 1), Math.min(state.total, _gpIdx + 2));
-        await _gpEnsureVisible(_gpIdx);
-        _gpApplyHighlight();
-    }
-
-    function _gpActivate() {
-        if (_gpIdx == null) return;
-        _gpCardEl(_gpIdx)?.querySelector('[data-v3-play]')?.click();
-    }
-
-    // Bails on focus inside anything with its own keyboard semantics — form
-    // controls, buttons, and dialog/drawer overlays — same intent as
-    // shortcuts.js's _isInsideInteractiveControl, reimplemented locally since
-    // this is a plain script (not an ES module) and can't import it.
-    //
-    // The form-control/button check requires the element to be VISIBLE, not
-    // merely present: screens stay in the DOM (hidden, not removed) when you
-    // navigate away, so a real <button> focused on some OTHER now-hidden
-    // screen (dashboard, etc.) can leave document.activeElement pointing at
-    // it — an el.closest('#v3-songs') scope check would let that stale focus
-    // through fine, but would ALSO wrongly stop blocking genuinely-focused
-    // shared chrome like the topbar search input (#v3-search lives outside
-    // #v3-songs's DOM subtree even while v3-songs is the active screen).
-    // Visibility is the actual distinction that matters here, not DOM
-    // nesting. The dialog/drawer-overlay and contentEditable checks stay as
-    // they were — overlay-level concerns regardless of which screen sits
-    // underneath.
-    function _gpBlockedTarget(el) {
-        if (!el) return false;
-        if (['INPUT', 'SELECT', 'TEXTAREA', 'BUTTON'].includes(el.tagName) && el.offsetParent !== null) return true;
-        if (el.isContentEditable) return true;
-        if (el.closest && el.closest('[role="dialog"], .feedBack-modal, #lib-filter-drawer')) return true;
-        return false;
-    }
-
-    document.addEventListener('keydown', (e) => {
-        if (!songsActive() || state.view !== 'grid') return;
-        if (_gpBlockedTarget(document.activeElement)) return;
-        const isActivate = e.key === 'Enter' || e.key === ' ' || e.key === 'Spacebar';
-        if (!isActivate && !['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(e.key)) return;
-        e.preventDefault();
-        if (isActivate) { _gpActivate(); return; }
-        const { cols } = measureGeom();
-        if (e.key === 'ArrowRight') _gpMove(1);
-        else if (e.key === 'ArrowLeft') _gpMove(-1);
-        else if (e.key === 'ArrowDown') _gpMove(cols);
-        else if (e.key === 'ArrowUp') _gpMove(-cols);
-    });
-
     if (sm && typeof sm.on === 'function') {
-        sm.on('instrument:changed', function (e) {
-            var instId = e && e.detail && e.detail.instrument;
-            if (!instId || !_autoFilterEnabled) return;
-            // Record the new instrument so working-tuning-changed skips its
-            // reload path — this handler already handles the reload.
-            _lastRenderInstrument = libInstrument();
-            state.filters.tunings = [];
-            if (_applyArrangementAutoFilter(instId)) {
-                reload();
-                renderDrawerIfOpen();
-            }
-        });
-
         sm.on('screen:changed', (e) => {
             const id = e && e.detail && e.detail.id;
             if (id === 'v3-songs') { onV3SongsScreenEnter(); return; }
@@ -4657,23 +4130,6 @@
         // visible tuning chips against the new tuning. Cheap: re-decorates in place,
         // no re-fetch or re-paint. No-op off the Songs grid or without the capability.
         sm.on('working-tuning-changed', () => {
-            // A guitar<->bass SWITCH changes which tuning the facet, the filter,
-            // the sort and the card chip speak for, so the grid must re-query —
-            // re-colouring chips would leave the guitar tuning on screen and a
-            // guitar-keyed filter applied. A retune within one instrument still
-            // takes the cheap in-place path below.
-            const inst = libInstrument();
-            if (inst !== _lastRenderInstrument) {
-                _lastRenderInstrument = inst;
-                // A tuning selection keyed to the old instrument means nothing
-                // for the new one; clearing avoids an empty grid the user can't
-                // explain (the pills are re-rendered from the new facet).
-                state.filters.tunings = [];
-                const active = document.querySelector('.screen.active');
-                if (active && active.id === 'v3-songs') reload();
-                else _libraryDirty = true;
-                return;
-            }
             if (typeof songsActive === 'function' && !songsActive()) return;
             if (state.view !== 'grid') return;
             decorateTuningChips(_gridEl());

From dd1e1833773437f18a9b38bb5ff2320912d299e9 Mon Sep 17 00:00:00 2001
From: Job <joboosterbaan@hotmail.com>
Date: Thu, 23 Jul 2026 15:30:29 +0200
Subject: [PATCH 74/74] =?UTF-8?q?feat:=20instrument-aware=20library=20?=
 =?UTF-8?q?=E2=80=94=20per-role=20mastery,=20hover=20overlay,=20tuning=20p?=
 =?UTF-8?q?erspective,=20auto-filter,=20grid=20nav?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 static/v3/songs.js | 648 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 596 insertions(+), 52 deletions(-)

diff --git a/static/v3/songs.js b/static/v3/songs.js
index 255e8145..18603714 100644
--- a/static/v3/songs.js
+++ b/static/v3/songs.js
@@ -43,8 +43,110 @@
         ['difficulty', 'Difficulty (easiest first)'], ['difficulty-desc', 'Difficulty (hardest first)'],
     ];
     const FORMATS = [['', 'All formats'], ['sloppak', 'Feedpak'], ['loose', 'Folder']];
-    const ARRANGEMENTS = ['Lead', 'Rhythm', 'Bass', 'Combo', 'Vocals'];
-    const STEMS = ['guitar', 'bass', 'drums', 'vocals', 'other'];
+    function _arrangementOptions() {
+        // Derive filter pill labels from instrument registry role names.
+        // When new instrument plugins are added, their arrangement type labels
+        // appear in the library filter drawer automatically.
+        var insts = sm && sm._instruments;
+        if (Array.isArray(insts) && insts.length) {
+            var out = [];
+            for (var i = 0; i < insts.length; i++) {
+                var roles = insts[i].roles || [];
+                for (var j = 0; j < roles.length; j++) {
+                    var label = roles[j].label;
+                    if (label && out.indexOf(label) < 0) out.push(label);
+                }
+            }
+            if (out.length) return out;
+        }
+        return ['Lead', 'Rhythm', 'Bass', 'Combo', 'Vocals'];
+    }
+
+    function _roleIcon(arrName) {
+        var insts = window.feedBack && window.feedBack._instruments;
+        if (!Array.isArray(insts)) return '\u25cf';
+        var name = (arrName || '').toLowerCase();
+        for (var i = 0; i < insts.length; i++) {
+            var inst = insts[i];
+            var roles = inst.roles || [];
+            for (var j = 0; j < roles.length; j++) {
+                var r = roles[j];
+                if (name === r.label.toLowerCase()) {
+                    if (inst.roles.length > 1) {
+                        return (inst.id[0] || '?').toUpperCase() + '<span class="text-[0.5rem]">' + (r.label[0] || '?').toUpperCase() + '</span>';
+                    }
+                    return (inst.id[0] || (r.label[0] || '?')).toUpperCase();
+                }
+                var names = r.arrangement_names || [];
+                for (var k = 0; k < names.length; k++) {
+                    if (name === names[k]) {
+                        if (inst.roles.length > 1) {
+                            return (inst.id[0] || '?').toUpperCase() + '<span class="text-[0.5rem]">' + (r.label[0] || '?').toUpperCase() + '</span>';
+                        }
+                        return (inst.id[0] || (r.label[0] || '?')).toUpperCase();
+                    }
+                }
+            }
+        }
+        return '\u25cf';
+    }
+
+    function _isPitchedArrangement(arrName) {
+        var insts = window.feedBack && window.feedBack._instruments;
+        if (!Array.isArray(insts)) return true;
+        var name = (arrName || '').toLowerCase();
+        for (var i = 0; i < insts.length; i++) {
+            var inst = insts[i];
+            var roles = inst.roles || [];
+            for (var j = 0; j < roles.length; j++) {
+                var r = roles[j];
+                if (name === r.label.toLowerCase()) return inst.detect_strategy === 'pitch';
+                var names = r.arrangement_names || [];
+                for (var k = 0; k < names.length; k++) {
+                    if (name === names[k]) return inst.detect_strategy === 'pitch';
+                }
+            }
+        }
+        return true;
+    }
+
+    function _instrumentArrangementNames(instrumentId) {
+        var insts = sm && sm._instruments;
+        if (!Array.isArray(insts)) return null;
+        for (var i = 0; i < insts.length; i++) {
+            if (insts[i].id === instrumentId && insts[i].roles) {
+                var names = [];
+                for (var j = 0; j < insts[i].roles.length; j++) {
+                    var label = insts[i].roles[j].label;
+                    if (label && names.indexOf(label) < 0) names.push(label);
+                }
+                return names.length ? names : null;
+            }
+        }
+        return null;
+    }
+
+    function _applyArrangementAutoFilter(instrumentId) {
+        var names = _instrumentArrangementNames(instrumentId);
+        if (!names) return false;
+        _arrAutoInstrument = instrumentId;
+        state.filters.arr_has = names.slice();
+        state.filters.arr_lacks = [];
+        return true;
+    }
+
+    function _activeInstrument() {
+        var id = sm && sm._activeInstrumentProfile;
+        if (!id) return null;
+        var insts = window.feedBack && window.feedBack._instruments;
+        if (!Array.isArray(insts)) return null;
+        for (var i = 0; i < insts.length; i++) {
+            if (id.indexOf(insts[i].id) === 0) return insts[i];
+        }
+        return null;
+    }
+
+    const STEMS = ['guitar', 'bass', 'drums', 'vocals', 'piano', 'other'];
     const PAGE_SIZE = 24;
     // Extra rows rendered above/below the viewport so a fast scroll doesn't flash
     // blank before the next window render lands.
@@ -62,8 +164,8 @@
         artist: '', album: '',
         grouping: true,     // one card per song (multi-chart grouping); persisted
 
-        filters: { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [] },
-        page: 0, total: 0, loading: false, built: false, accuracy: {}, tuningNames: [], genres: [],
+        filters: { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [], tuningMatch: 'exact' },
+        page: 0, total: 0, loading: false, built: false, accuracy: {}, arrangementAccuracy: {}, tuningNames: [], genres: [],
         artistCatalog: [], renderedHash: '',
         scrollBound: false,
         songsById: {}, selectMode: false, selected: new Set(),
@@ -120,7 +222,7 @@
     function activeFilterCount() {
         const f = state.filters;
         return f.arr_has.length + f.arr_lacks.length + f.stem_has.length + f.stem_lacks.length +
-            (f.lyrics ? 1 : 0) + f.tunings.length + (f.mastery ? f.mastery.length : 0) +
+            (f.lyrics ? 1 : 0) + (f.tuningMatch === 'playable' ? 1 : f.tunings.length) + (f.mastery ? f.mastery.length : 0) +
             (f.match ? f.match.length : 0) + (f.genre ? f.genre.length : 0) +
             (state.artist ? 1 : 0) + (state.album ? 1 : 0);
     }
@@ -280,7 +382,21 @@
         if (f.stem_has.length) p.set('stems_has', f.stem_has.join(','));
         if (f.stem_lacks.length) p.set('stems_lacks', f.stem_lacks.join(','));
         if (f.lyrics) p.set('has_lyrics', f.lyrics);
-        if (f.tunings.length) p.set('tunings', f.tunings.join(','));
+        // The two modes answer different questions, so only one filters at a
+        // time: sending both would silently intersect them.
+        if (f.tunings.length && f.tuningMatch !== 'playable') p.set('tunings', f.tunings.join(','));
+        // Tell the server which instrument perspective to use for tuning
+        // columns (bass_tuning_name vs tuning_name, etc.).
+        var instId = sm && sm._activeInstrumentProfile;
+        // Which perspective the `tunings` filter + the tuning sort read.
+        // Uses the 3-perspective model (guitar-lead, guitar-rhythm, bass) from
+        // the active instrument profile. Drums/piano/keys fall through to the
+        // default guitar-lead perspective.
+        if (libInstrument() !== 'guitar-lead') p.set('instrument', libInstrument());
+        // "Playable without retuning": send the player's LIVE tuning and let the
+        // server do the pitch maths (the pitch tables live in lib/tunings.py —
+        // duplicating them here is how the two drift apart).
+        applyPlayableParams(p, f);
         if (f.mastery && f.mastery.length) p.set('mastery', f.mastery.join(','));
         if (f.match && f.match.length) p.set('match', f.match.join(','));
         if (f.genre && f.genre.length) p.set('genre', f.genre.join(','));
@@ -475,23 +591,108 @@
         if (window.syncLibrarySong && sid) window.syncLibrarySong(state.provider, sid, { playWhenReady: true });
     }
 
+    // Per-role accuracy helpers — find the arrangement matching the active
+    // instrument role and read its per-arrangement accuracy.
+    function _matchingArrangementIndex(song) {
+        if (!song || !song.arrangements || !song.arrangements.length) return null;
+        var want = state.filters.arr_has;
+        var activeProfileId = (sm && sm._activeInstrumentProfile) || '';
+        var activeRoleLabel = null;
+        if (activeProfileId) {
+            var insts = window.feedBack && window.feedBack._instruments;
+            if (Array.isArray(insts)) {
+                for (var ii = 0; ii < insts.length; ii++) {
+                    var ir = insts[ii].roles || [];
+                    for (var ij = 0; ij < ir.length; ij++) {
+                        if (activeProfileId === insts[ii].id + '-' + ir[ij].id) {
+                            activeRoleLabel = ir[ij].label;
+                            break;
+                        }
+                    }
+                    if (activeRoleLabel) break;
+                }
+            }
+        }
+        if (activeRoleLabel) {
+            for (var i = 0; i < song.arrangements.length; i++) {
+                var a = song.arrangements[i];
+                var sn = a.smart_name || a.name || '';
+                if (sn === activeRoleLabel) return a.index != null ? a.index : i;
+            }
+            return null;
+        }
+        if (!want.length) return null;
+        for (var i = 0; i < song.arrangements.length; i++) {
+            var a2 = song.arrangements[i];
+            var sn2 = a2.smart_name || a2.name || '';
+            for (var j = 0; j < want.length; j++) {
+                if (sn2 === want[j]) return a2.index != null ? a2.index : i;
+            }
+        }
+        return null;
+    }
+
+    function _perArrangementAccuracy(filename, arrIndex) {
+        var map = state.arrangementAccuracy[filename];
+        if (!map) return null;
+        return typeof map[arrIndex] === 'number' ? map[arrIndex] : null;
+    }
+
     // Accuracy badge markup. `variant` is 'grid' (overlay pill on the card art,
-    // default) or 'tree' (inline percentage in the list row). Both carry the
-    // .fb-acc-badge class so a post-play refresh (repaintAccuracy) can find and
-    // replace them in place without re-rendering the whole list.
-    function accuracyBadge(filename, variant) {
-        const acc = state.accuracy[filename];
-        if (acc == null) return '';
-        // Floor, never round: 100% must mean every note hit.
-        const pct = Math.floor(acc * 100);
+    // positioned `absolute bottom-0 right-0`) or 'tree' (inline `<span>`).
+    // Cards show per-role accuracy: the arrangement matching the current
+    // instrument role determines the displayed percentage, not the song-wide max.
+    // A hover overlay reveals all arrangements with their individual accuracies.
+    function accuracyBadge(filename, variant, song) {
+        if (!song && state.songsById) song = state.songsById[filename];
+        var acc = null;
+        var arrIdx = song ? _matchingArrangementIndex(song) : null;
+        var hasMatchingArrangement = arrIdx != null;
+        if (hasMatchingArrangement) {
+            acc = _perArrangementAccuracy(filename, arrIdx);
+        }
+        var hasArr = song && song.arrangements && song.arrangements.length > 0;
+        if (acc == null && !hasArr) return '';
+
+        var pct = acc != null ? Math.floor(acc * 100) : null;
+        var displayLabel;
+        if (pct != null) {
+            displayLabel = pct + '%';
+        } else if (!state.filters.arr_has.length && !hasMatchingArrangement) {
+            displayLabel = 'n/a';
+        } else {
+            displayLabel = '\u2014 %';
+        }
         if (variant === 'tree') {
-            const color = acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
-            return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + pct + '%</span>';
+            var color = acc != null && acc >= MASTERY_ACCURACY ? 'text-fb-good' : acc != null && acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low';
+            return '<span class="fb-acc-badge text-xs font-bold ' + color + '">' + displayLabel + '</span>';
         }
-        const color = acc >= MASTERY_ACCURACY ? 'bg-fb-good' : (acc >= 0.5 ? 'bg-fb-mid' : 'bg-fb-low');
-        const text = acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
-        return '<span class="fb-acc-badge absolute bottom-0 right-0 ' + color + '/90 ' + text + ' px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1">' +
-            '<svg class="w-3 h-3" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><circle cx="12" cy="12" r="4"/></svg>' + pct + '%</span>';
+
+        var hoverOverlay = '';
+        if (song && song.arrangements && song.arrangements.length > 0) {
+            var songTuning = song.tuning_name || '';
+            var items = '';
+            for (var ai = 0; ai < song.arrangements.length; ai++) {
+                var a = song.arrangements[ai];
+                var aiIdx = a.index != null ? a.index : ai;
+                var aAcc = _perArrangementAccuracy(filename, aiIdx);
+                var aName = a.smart_name || a.name || ('#' + aiIdx);
+                var aLabel = aAcc != null ? Math.floor(aAcc * 100) + '%' : '\u2014';
+                var aColor = aAcc != null
+                    ? (aAcc >= MASTERY_ACCURACY ? 'text-fb-good' : aAcc >= 0.5 ? 'text-fb-mid' : 'text-fb-low')
+                    : 'text-gray-600';
+                var isPitched = _isPitchedArrangement(aName);
+                var tuningPart = isPitched && songTuning ? ' \u00b7 ' + esc(songTuning) : '';
+                items += '<div class="flex items-center gap-1 px-2 py-0.5"><span class="text-xs text-fb-textDim flex-1">' + esc(aName) + tuningPart + '</span><span class="text-xs font-bold ' + aColor + '">' + aLabel + '</span></div>';
+            }
+            hoverOverlay = '<div class="opacity-0 group-hover:opacity-100 transition" style="position:absolute;bottom:0;left:0;right:0;background:rgba(0,0,0,0.8);border-radius:0 0 0.5rem 0.5rem;z-index:20;pointer-events:none">' + items + '</div>';
+        }
+
+        var badgeColor = acc != null ? (acc >= MASTERY_ACCURACY ? 'rgba(34,197,94,0.9)' : (acc >= 0.5 ? 'rgba(234,179,8,0.9)' : 'rgba(239,68,68,0.9)')) : 'rgba(75,85,99,0.9)';
+        var badgeText = acc != null && acc >= 0.5 && acc < MASTERY_ACCURACY ? 'text-black' : 'text-white';
+        var borderColor = acc != null ? (acc >= MASTERY_ACCURACY ? '#22c55e' : (acc >= 0.5 ? '#eab308' : '#ef4444')) : '#4b5563';
+        return '<span class="fb-acc-badge absolute bottom-0 right-0 px-2 py-0.5 rounded-tl-md text-xs font-bold flex items-center gap-1 opacity-100 group-hover:opacity-0 transition border-l-2 border-t-2 ' + badgeText + '" style="background:' + badgeColor + ';border-color:' + borderColor + '">' +
+            displayLabel + '</span>' + hoverOverlay;
     }
 
     // ── Metadata-refresh per-tile state (the "Refresh Metadata" batch) ─────────
@@ -548,12 +749,14 @@
     // snapshot would otherwise survive a sidebar return, so we force a full
     // re-fetch on the next entry. (feedBack — "No DLC until restart".)
     let _libraryDirty = false;
+    let _arrAutoInstrument = null;
+    let _autoFilterEnabled = true;
 
     function repaintAccuracy(key) {
         const apply = (el, variant) => {
             if (el.getAttribute('data-fn') !== key) return;
             const old = el.querySelector('.fb-acc-badge');
-            const html = accuracyBadge(key, variant);
+            const html = accuracyBadge(key, variant, state.songsById[key]);
             if (variant === 'grid') {
                 const art = el.querySelector('[data-v3-play]');
                 if (!art) return;
@@ -576,14 +779,13 @@
     async function applyScoreRefresh() {
         if (!_dirtyScores.size) return;
         const fresh = await jget('/api/stats/best');
-        // Fetch failed — keep the entries dirty so the next trigger (or screen
-        // enter) retries rather than silently dropping the badge update.
+        const freshArr = await jget('/api/stats/best-by-arrangement');
         if (!fresh) return;
         state.accuracy = fresh;
+        if (freshArr) state.arrangementAccuracy = freshArr;
         const keys = Array.from(_dirtyScores);
         _dirtyScores.clear();
         keys.forEach(repaintAccuracy);
-        // A new score shifts the repertoire meter + the keep-practicing shelf.
         renderLibraryHome();
     }
 
@@ -681,7 +883,7 @@
                 '<button class="v3-kp-card group text-left" data-kp="' + esc(r.filename) + '" data-arr="' + esc(r.arrangement != null ? r.arrangement : '') + '" title="' + esc(r.title) + '">' +
                 '<div class="relative aspect-square rounded-lg overflow-hidden bg-fb-card">' +
                 '<img src="' + esc(r.art_url) + '" alt="" loading="lazy" decoding="async" class="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105" onerror="this.style.visibility=\'hidden\'">' +
-                accuracyBadge(r.filename) +
+                accuracyBadge(r.filename, 'grid') +
                 '</div>' +
                 '<div class="mt-1 text-sm text-fb-text truncate">' + esc(r.title) + '</div>' +
                 '<div class="text-xs text-fb-textDim truncate">' + esc(r.artist) + '</div>' +
@@ -786,6 +988,10 @@
     // so without them the chips render exactly as before. Decoration runs AFTER the
     // (sync) window paint so scrolling stays snappy; a token cancels a superseded pass.
     let _tuningDecorToken = 0;
+    // The instrument the current grid was queried/painted for, so a
+    // working-tuning change can tell a guitar<->bass SWITCH (re-query) from a
+    // retune within the same instrument (re-colour only).
+    let _lastRenderInstrument = null;
     function _applyChipMatch(chip, stateName) {
         chip.classList.remove('bg-fb-mid', 'bg-emerald-500', 'bg-amber-400');
         chip.classList.add(stateName === 'match' ? 'bg-emerald-500'
@@ -805,10 +1011,11 @@
         for (const chip of chips) {
             const offs = chip.getAttribute('data-tuning-offsets').split(',').map(Number);
             if (!offs.length || offs.some((n) => !isFinite(n))) continue;
-            // Pass the instrument so coverage uses the right base pitches (bass vs guitar).
+            // Pass the instrument so coverage uses the right base pitches.
             const arrangement = chip.dataset.tuningBass === '1' ? 'Bass' : 'Lead';
+            const instId = chip.dataset.tuningInstrument || (chip.dataset.tuningBass === '1' ? 'bass' : 'guitar');
             let rep = null;
-            try { rep = await cov({ tuning: offs, stringCount: offs.length, arrangement: arrangement }); } catch (_) { rep = null; }
+            try { rep = await cov({ tuning: offs, stringCount: offs.length, arrangement: arrangement, instrument: instId }); } catch (_) { rep = null; }
             if (token !== _tuningDecorToken) return;   // superseded by a re-paint / tuning change
             if (rep) _applyChipMatch(chip, rep.covered ? 'match' : 'retune');
         }
@@ -825,39 +1032,64 @@
         const shown = song.display_chart ? Object.assign({}, song, song.display_chart) : song;
         // In select mode the checkbox occupies top-2 left-2, so shift the
         // tuning chip right (left-9) to avoid overlapping it.
+        // Bass players see the bass chart's tuning (guitar fallback) — the card
+        // must agree with the facet/filter or the grid contradicts the pills.
+        const shownTuning = shownTuningName(shown);
         const tuningLabel = (typeof window.displayTuningName === 'function')
-            ? window.displayTuningName(shown.tuning_name || shown.tuning)
-            : (shown.tuning_name || '');
+            ? window.displayTuningName(shownTuning)
+            : (shownTuning || '');
         let tuning = '';
         if (tuningLabel) {
             const rawOffsets = (typeof window.parseRawTuningOffsets === 'function')
                 ? (window.parseRawTuningOffsets(shown.tuning_offsets)
-                    || window.parseRawTuningOffsets(shown.tuning_name || shown.tuning))
+                    || window.parseRawTuningOffsets(shownTuningOffsets(shown))
+                    || window.parseRawTuningOffsets(shownTuning)
+                    || window.parseRawTuningOffsets(shown.tuning))
                 : null;
             const targetNotes = (tuningLabel === 'Custom Tuning' && rawOffsets
                 && typeof window.displayTuningTargets === 'function')
                 ? window.displayTuningTargets(rawOffsets, { tuningName: tuningLabel })
                 : '';
-            const badgeTitle = targetNotes
+            // Mark a tuning we INFERRED from the guitar chart (this song has no
+            // bass arrangement) so a bass player isn't shown a borrowed tuning
+            // as if it were their part's. `~` keeps the chip compact; the title
+            // spells it out.
+            const inferred = shown.tuning_inferred === true;
+            const badgeTitle = (targetNotes
                 ? ('Custom Tuning: ' + targetNotes)
-                : tuningLabel;
-            const pos = 'absolute top-2 ' + (state.selectMode ? 'left-9' : 'left-2');
+                : tuningLabel)
+                + (inferred ? ' — from the guitar chart (no bass arrangement)' : '');
+            const pos = 'absolute top-0 rounded-br-md ' + (state.selectMode ? 'left-9' : 'left-0');
             // Tag the chip with its offsets so decorateTuningChips() can colour it
             // green (matches your current tuning) / amber (needs a retune) after paint.
             // Also flag a bass-only song (every arrangement is a bass part) so coverage
             // scores its bass tuning against the bass base pitches, not guitar — otherwise
             // a 4-string bass tuning read as guitar can false-match a guitar player.
             const chipArrs = shown.arrangements || [];
-            const chipIsBass = chipArrs.length > 0
-                && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || ''));
-            const matchAttr = (rawOffsets && rawOffsets.length)
-                ? ' data-tuning-chip data-tuning-offsets="' + esc(rawOffsets.join(',')) + '"'
-                    + (chipIsBass ? ' data-tuning-bass="1"' : '') : '';
+            // Bass either because the chip is SHOWING the bass chart's tuning
+            // Which instrument this chip represents — read from the active
+            // instrument profile in the registry, falling back to the
+            // 3-perspective bass/lead detection for the tuner plugin's coverage
+            // checker (which only knows 'Bass' and 'Lead' arrangement labels).
+            const inst = _activeInstrument();
+            const instId = inst ? inst.id : (libInstrument() === 'bass' ? 'bass' : 'guitar');
+            const isBass = instId === 'bass'
+                || (chipArrs.length > 0
+                    && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || '')));
+            const stringCount = inst && inst.string_count ? inst.string_count : (isBass ? 4 : 6);
+            // Truncate offsets to the instrument's string count so the
+            // coverage checker compares the right number of strings.
+            let chipOffsets = rawOffsets;
+            if (chipOffsets && chipOffsets.length > stringCount) chipOffsets = chipOffsets.slice(0, stringCount);
+            const matchAttr = (chipOffsets && chipOffsets.length)
+                ? ' data-tuning-chip data-tuning-offsets="' + esc(chipOffsets.join(',')) + '"'
+                    + ' data-tuning-instrument="' + esc(instId) + '"'
+                    + (isBass ? ' data-tuning-bass="1"' : '') : '';
             if (targetNotes) {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
                     + esc('Custom Tuning') + '<br><span class="font-semibold tracking-wide">' + esc(targetNotes) + '</span></span>';
             } else {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + '</span>';
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm opacity-100 group-hover:opacity-0 transition"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + (inferred ? '<span class="opacity-60"> ~</span>' : '') + '</span>';
             }
         }
         // Display-only (pointer-events-none) so a click falls through to the
@@ -892,7 +1124,7 @@
         return '<div class="group relative" data-fn="' + esc(key) + '" data-letter="' + esc(songBucket(song)) + '" data-library-song="' + esc(songId(song)) + '" data-library-provider="' + esc(state.provider) + '">' +
             '<div class="relative aspect-square rounded-lg overflow-hidden bg-fb-card cursor-pointer' + selRing + '" data-v3-play>' +
             '<img src="' + esc(artUrl(shown)) + '" alt="" loading="lazy" decoding="async" class="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105" onerror="this.style.visibility=\'hidden\'">' +
-            tuning + checkbox + accuracyBadge(key) + fmtBadge(shown) + personalBadges(song) + enrichBadge(key, song.unmatched) + overlay +
+            tuning + checkbox + accuracyBadge(key, 'grid', song) + fmtBadge(shown) + personalBadges(song) + enrichBadge(key, song.unmatched) + overlay +
             '<div class="absolute top-2 right-2 flex gap-1 opacity-0 group-hover:opacity-100 transition">' +
             inlineBtns +
             '<button data-fav data-fav-idle="text-white" title="Favorite" aria-label="Favorite" aria-pressed="' + (fav ? 'true' : 'false') + '" class="w-7 h-7 rounded-full bg-black/50 hover:bg-black/70 flex items-center justify-center text-sm ' + (fav ? 'text-fb-accent' : 'text-white') + '">' + (fav ? '♥' : '♡') + '</button>' +
@@ -2467,7 +2699,7 @@
         '<span class="flex-1 min-w-0 cursor-pointer" data-v3-play><span class="block text-sm text-fb-text truncate">' + esc(s.title) + '</span></span>' +
         (chips ? '<span class="hidden sm:flex items-center gap-1 shrink-0">' + chips + '</span>' : '') +
         (fl ? '<span class="text-[0.5625rem] font-bold px-1 py-0.5 rounded shrink-0 ' + (fl === 'FEEDPAK' ? 'bg-fb-primary/20 text-fb-primary' : 'bg-fb-card text-fb-textDim') + '">' + fl + '</span>' : '') +
-        accuracyBadge(k, 'tree') +
+        accuracyBadge(k, 'tree', s) +
         // Same fav / save-for-later / overflow-menu cluster as the grid
         // card. Always shown (like the arrangement chips), not hover-
         // revealed. wireCards() binds all three for any [data-fn].
@@ -2489,6 +2721,91 @@
 
     function _artistHostEl() { return document.getElementById('v3-songs-artistpage'); }
 
+    // ── Instrument-aware tuning (the bass-player tuning-filter report) ────────
+    // A song's bass chart is often in a different tuning from its guitar chart,
+    // so the tuning facet/filter/sort and the card chip must speak for the
+    // instrument the player actually plays. The host's working-tuning
+    // capability already holds the live selection (seeded from /api/settings on
+    // boot, updated when the player switches) — read it rather than adding
+    // another settings fetch. `state.settingsInstrument` is the fallback for
+    // hosts where the capability isn't mounted.
+    // Three perspectives, matching `active_instrument_profile`: lead and rhythm
+    // guitar charts can be tuned differently too, so a rhythm player hits the
+    // same bug a bassist did. The PROFILE is the only three-valued source (the
+    // working-tuning capability knows guitar-vs-bass but not lead-vs-rhythm),
+    // so it wins; the capability is the live fallback for hosts where the
+    // profile hasn't loaded.
+    const PERSPECTIVES = ['guitar-lead', 'guitar-rhythm', 'bass'];
+    function libInstrument() {
+        if (PERSPECTIVES.indexOf(state.settingsProfile) >= 0) return state.settingsProfile;
+        try {
+            const wt = window.feedBack && window.feedBack.workingTuning;
+            if (wt && typeof wt.get === 'function') {
+                const cur = wt.get();
+                if (cur && cur.instrument === 'bass') return 'bass';
+            }
+        } catch (_) { /* capability absent/erroring — fall through to settings */ }
+        return state.settingsInstrument === 'bass' ? 'bass' : 'guitar-lead';
+    }
+
+    // "Playable without retuning" mode reads the player's CURRENT tuning from
+    // the working-tuning capability (the live session state the tuner writes),
+    // not a separate setting. No capability => we cannot know the current
+    // tuning, so the mode is unavailable rather than guessed.
+    function currentWorkingTuning() {
+        try {
+            const wt = window.feedBack && window.feedBack.workingTuning;
+            if (!wt || typeof wt.get !== 'function') return null;
+            const cur = wt.get();
+            if (!cur || !Array.isArray(cur.offsets) || !cur.offsets.length) return null;
+            return cur;
+        } catch (_) { return null; }
+    }
+
+    function playableAvailable() { return !!currentWorkingTuning(); }
+
+    function applyPlayableParams(p, f) {
+        if (f.tuningMatch !== 'playable') return;
+        const cur = currentWorkingTuning();
+        if (!cur) return;
+        p.set('tuning_match', 'playable');
+        p.set('playable_offsets', cur.offsets.join(','));
+        p.set('playable_instrument', cur.instrument === 'bass' ? 'bass' : 'guitar');
+        p.set('playable_string_count', String(cur.stringCount || cur.offsets.length));
+    }
+
+    // Short human label for the perspective, for the facet/sort headers.
+    function libInstrumentLabel() {
+        const p = libInstrument();
+        return p === 'bass' ? 'bass' : p === 'guitar-rhythm' ? 'rhythm' : 'lead';
+    }
+
+    // The column a row's tuning lives in for the active perspective.
+    function perspectiveTuningField() {
+        const p = libInstrument();
+        return p === 'bass' ? 'bass_tuning_name'
+            : p === 'guitar-rhythm' ? 'rhythm_tuning_name' : '';
+    }
+
+    // The tuning a card should SHOW: bass players see the bass chart's tuning,
+    // falling back to the song (guitar-derived) tuning when the song has no
+    // bass arrangement — the common case, so the fallback is not an edge path.
+    function shownTuningName(song) {
+        const f = perspectiveTuningField();
+        if (f && song[f]) return song[f];
+        return song.tuning_name || song.tuning;
+    }
+
+    function shownTuningOffsets(song) {
+        const f = perspectiveTuningField();
+        if (f) {
+            const offKey = f.replace('_name', '_offsets');
+            if (song[offKey]) return song[offKey];
+            return song.tuning_offsets;
+        }
+        return song.tuning_offsets;
+    }
+
     // Sync the two Settings gates into module state (fire-and-forget — the
     // cached flags gate entry-point rendering; openArtistPage re-checks).
     function refreshArtistPageGates() {
@@ -2496,6 +2813,13 @@
             if (!cfg) return;
             state.artistPagesEnabled = cfg.artist_pages_enabled !== false;
             state.artistLinksEnabled = cfg.artist_external_links === true;
+            // Fallback instrument for hosts without the working-tuning capability.
+            state.settingsInstrument = cfg.instrument === 'bass' ? 'bass' : 'guitar';
+            // The three-valued perspective source (lead / rhythm / bass).
+            state.settingsProfile = cfg.active_instrument_profile || '';
+            if (cfg && typeof cfg.auto_filter_instrument === 'boolean') {
+                _autoFilterEnabled = cfg.auto_filter_instrument;
+            }
         });
     }
 
@@ -2809,12 +3133,17 @@
         else if (s === 'has') lacksArr.push(value);
         // 'lacks' → cycles back to any (already removed)
     }
-    function triPill(group, value, label, st) {
+    function triPill(group, value, label, st, title) {
         const cls = st === 'has' ? 'bg-fb-good/30 text-fb-good border-fb-good/40'
             : st === 'lacks' ? 'bg-fb-low/30 text-fb-low border-fb-low/40'
                 : 'bg-gray-800/50 text-fb-textDim border-gray-700';
         const mark = st === 'has' ? '✓ ' : st === 'lacks' ? '✕ ' : '';
-        return '<button data-tri="' + group + '" data-val="' + esc(value) + '" class="px-2 py-1 rounded-md text-xs border ' + cls + '">' + mark + esc(label) + '</button>';
+        const tip = title ? ' title="' + esc(title) + '"' : '';
+        return '<button data-tri="' + group + '" data-val="' + esc(value) + '" class="px-2 py-1 rounded-md text-xs border ' + cls + '"' + tip + '>' + mark + esc(label) + '</button>';
+    }
+    function renderDrawerIfOpen() {
+        const d = document.getElementById('v3-songs-drawer');
+        if (d && !d.classList.contains('hidden') && d.innerHTML.trim()) renderDrawer();
     }
     function renderDrawer() {
         const d = document.getElementById('v3-songs-drawer');
@@ -2824,8 +3153,18 @@
             '<div class="p-5 space-y-5">' +
             '<div class="flex items-center justify-between"><h3 class="text-lg font-semibold text-fb-text">Filters</h3>' +
             '<button data-drawer-close class="text-fb-textDim hover:text-fb-text">✕</button></div>' +
-            section('Arrangements', ARRANGEMENTS.map((a) => triPill('arr', a, a, triState(f.arr_has, f.arr_lacks, a))).join('')) +
-            section('Stems (feedpak)', STEMS.map((s) => triPill('stem', s, s, triState(f.stem_has, f.stem_lacks, s))).join('')) +
+            section('Arrangements', _arrangementOptions().map((a) => triPill('arr', a, a, triState(f.arr_has, f.arr_lacks, a))).join('')) +
+            section('Stems (feedpak)', STEMS.map((s) => triPill('stem', s, s, triState(f.stem_has, f.stem_lacks, s))).join('') +
+                (() => {
+                    // One-click "which songs still need splitting": lacks EVERY
+                    // instrument stem — the same query Stem Splitter's own
+                    // missing-stems view runs. Toggles off if already active.
+                    const on = STEMS.every((s) => f.stem_lacks.includes(s)) && !f.stem_has.length;
+                    return '<button data-stem-unsplit class="px-2 py-1 rounded-md text-xs border '
+                        + (on ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700')
+                        + '" title="Songs with no instrument stems — not yet split">'
+                        + (on ? '✕ ' : '') + 'Not split</button>';
+                })()) +
             section('Lyrics', ['', '1', '0'].map((v) => '<button data-lyrics="' + v + '" class="px-2 py-1 rounded-md text-xs border ' + (f.lyrics === v ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + (v === '' ? 'Any' : v === '1' ? 'Has lyrics' : 'No lyrics') + '</button>').join('')) +
             // Progress (mastery bands) — multi-select; server filters via song_stats.
             section('Progress', [['mastered', 'Mastered'], ['in_progress', 'In progress'], ['not_started', 'Not started']].map((it) => '<button data-mastery="' + it[0] + '" class="px-2 py-1 rounded-md text-xs border ' + (f.mastery.includes(it[0]) ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + it[1] + '</button>').join('')) +
@@ -2834,7 +3173,32 @@
             section('Match', [['review', 'To review'], ['matched', 'Matched'], ['unmatched', 'Unmatched'], ['pending', 'Not scanned']].map((it) => '<button data-match="' + it[0] + '" class="px-2 py-1 rounded-md text-xs border ' + (f.match.includes(it[0]) ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + it[1] + '</button>').join('')) +
             // Genre facet — dynamic list from /api/library/genres (primary genre).
             (state.genres && state.genres.length ? section('Genre', state.genres.map((g) => '<button data-genre="' + esc(g) + '" class="px-2 py-1 rounded-md text-xs border ' + (f.genre.includes(g) ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + esc(g) + '</button>').join('')) : '') +
-            section('Tuning', (state.tuningNames || []).map((t) => {
+            // The facet header NAMES the perspective. Silent instrument-following
+            // is the original bug in a new place: the user must be able to tell
+            // which instrument these tunings describe.
+            section('Tuning (' + libInstrumentLabel() + ')',
+                // MODE toggle. Exact match answers "which tuning is this
+                // labelled"; Playable answers "will this cost me a retune" —
+                // which is what a player actually wants. Both are offered;
+                // exact stays the default so nothing changes unasked.
+                '<div class="flex gap-1 mb-2">'
+                + [['exact', 'Exact tuning'], ['playable', 'Playable without retuning']].map((m) => {
+                    const on = (f.tuningMatch || 'exact') === m[0];
+                    const dis = m[0] === 'playable' && !playableAvailable();
+                    return '<button data-tuning-match="' + m[0] + '"'
+                        + (dis ? ' disabled' : '')
+                        + (dis ? ' title="Needs your current tuning — open the tuner first"' : '')
+                        + ' class="px-2 py-1 rounded-md text-xs border '
+                        + (on ? 'bg-fb-primary text-white border-fb-primary'
+                            : 'bg-gray-800/50 text-fb-textDim border-gray-700')
+                        + (dis ? ' opacity-40 cursor-not-allowed' : '') + '">'
+                        + esc(m[1]) + '</button>';
+                }).join('')
+                + '</div>'
+                + (f.tuningMatch === 'playable'
+                    ? '<div class="text-xs text-fb-textDim mb-2">Charts you can play in your current tuning, no retune. Songs whose lowest string sits below yours are excluded.</div>'
+                    : '')
+                + ((state.tuningNames || []).map((t) => {
                 // Filter on the server's grouping key (raw offsets for customs)
                 // so two "Custom Tuning" entries are distinct; show their target
                 // notes in the label so they're distinguishable.
@@ -2847,8 +3211,17 @@
                     const notes = offs ? window.displayTuningTargets(offs, { tuningName: t.name }) : '';
                     if (notes) label = 'Custom · ' + notes;
                 }
-                return triPill('tuning', val, label + ' (' + t.count + ')', f.tunings.includes(val) ? 'has' : 'any');
-            }).join('') || '<span class="text-xs text-fb-textDim">No tunings</span>') +
+                // Be honest about the fallback: when some of a row's songs have
+                // no bass chart and are borrowing the guitar tuning, say so
+                // rather than presenting a borrowed tuning as a measured one.
+                const inf = t.inferred_count || 0;
+                const title = inf
+                    ? inf + ' of ' + t.count + ' inferred from the guitar chart (no bass arrangement)'
+                    : '';
+                const countLabel = inf ? t.count + ', ' + inf + ' inferred' : String(t.count);
+                return triPill('tuning', val, label + ' (' + countLabel + ')',
+                    f.tunings.includes(val) ? 'has' : 'any', title);
+            }).join('') || '<span class="text-xs text-fb-textDim">No tunings</span>')) +
             // Multi-chart grouping toggle (P5e) — a VIEW mode, not a filter
             // (never counted in the badge, never saved into collection rules).
             // Local provider only: it's the one that implements group=.
@@ -2878,6 +3251,18 @@
             else if (g === 'tuning') { const i = f.tunings.indexOf(v); if (i >= 0) f.tunings.splice(i, 1); else f.tunings.push(v); }
             renderDrawer();
         }));
+        d.querySelectorAll('[data-tuning-match]').forEach((b) => b.addEventListener('click', () => {
+            if (b.disabled) return;
+            f.tuningMatch = b.getAttribute('data-tuning-match');
+            renderDrawer();
+        }));
+        d.querySelector('[data-stem-unsplit]')?.addEventListener('click', () => {
+            const on = STEMS.every((s) => f.stem_lacks.includes(s)) && !f.stem_has.length;
+            f.stem_has.length = 0;
+            f.stem_lacks.length = 0;
+            if (!on) f.stem_lacks.push(...STEMS);
+            renderDrawer();
+        });
         d.querySelectorAll('[data-lyrics]').forEach((b) => b.addEventListener('click', () => { f.lyrics = b.getAttribute('data-lyrics'); renderDrawer(); }));
         d.querySelectorAll('[data-mastery]').forEach((b) => b.addEventListener('click', () => { const v = b.getAttribute('data-mastery'); const i = f.mastery.indexOf(v); if (i >= 0) f.mastery.splice(i, 1); else f.mastery.push(v); renderDrawer(); }));
         d.querySelector('[data-grouping]')?.addEventListener('click', () => {
@@ -2891,7 +3276,7 @@
         d.querySelector('[data-drawer-tidy]')?.addEventListener('click', openArtistTidyUp);
         d.querySelector('[data-drawer-close]')?.addEventListener('click', closeDrawer);
         d.querySelector('[data-drawer-clear]')?.addEventListener('click', async () => {
-            state.filters = { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [] };
+            state.filters = { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [], tuningMatch: 'exact' };
             state.artist = '';
             state.album = '';
             renderDrawer();
@@ -3478,13 +3863,15 @@
         const providers = await loadProviders();
         const [, tn] = await Promise.all([
             (async () => { state.accuracy = (await jget('/api/stats/best')) || {}; })(),
-            jget('/api/library/tuning-names?provider=' + enc(state.provider)),
+            jget('/api/library/tuning-names?provider=' + enc(state.provider)
+                + '&instrument=' + enc(libInstrument())),
             loadArtistCatalog(),
             // Artist-page gates (PR-B) ride the initial fetch batch so the
             // first card paint already knows whether artist lines are links.
             refreshArtistPageGates(),
         ]);
         state.tuningNames = (tn && tn.tunings) || [];
+        _lastRenderInstrument = libInstrument();
         try { const _g = await jget('/api/library/genres?provider=' + enc(state.provider)); state.genres = (_g && _g.genres) || []; } catch (e) { state.genres = []; }
 
         const opt = (arr, sel) => arr.map(([v, l]) => '<option value="' + esc(v) + '"' + (v === sel ? ' selected' : '') + '>' + esc(l) + '</option>').join('');
@@ -3512,7 +3899,13 @@
             '<select id="v3-songs-artist" class="' + ctrl + ' max-w-[11rem]" aria-label="Artist">' + artistSelectHtml() + '</select>' +
             '<select id="v3-songs-album" class="' + ctrl + ' max-w-[11rem]" aria-label="Album"' + (state.artist ? '' : ' disabled') + '>' + albumSelectHtml() + '</select>' +
             '<div class="flex rounded-md overflow-hidden border border-gray-700"><button id="v3-songs-grid-btn" class="px-3 py-2 text-sm">▦</button><button id="v3-songs-tree-btn" class="px-3 py-2 text-sm">≣</button><button id="v3-songs-albums-btn" title="Albums" class="px-3 py-2 text-sm">💿</button><button id="v3-songs-folder-btn" class="px-3 py-2 text-sm" style="display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;width:2.25rem"><svg fill="currentColor" viewBox="0 0 16 16" style="width:12px;height:12px;flex-shrink:0"><path d="M1 3.5A1.5 1.5 0 012.5 2h3.086a1.5 1.5 0 011.06.44l.915.914H13.5A1.5 1.5 0 0115 4.914V12.5a1.5 1.5 0 01-1.5 1.5h-11A1.5 1.5 0 011 12.5v-9z"/></svg></button></div>' +
-            '<select id="v3-songs-sort" class="' + ctrl + '">' + opt(SORTS, state.sort) + '</select>' +
+            // Name the perspective on the SORT too, not just the filter: tuning
+            // sort orders by musical distance from standard, and for a bass
+            // player that distance is measured on the bass tuning. Unlabelled,
+            // the grid silently reorders with no visible cause.
+            '<select id="v3-songs-sort" class="' + ctrl + '">' + opt(
+                SORTS.map(([v, l]) => [v, v === 'tuning' ? l + ' (' + libInstrumentLabel() + ')' : l]),
+                state.sort) + '</select>' +
             '<select id="v3-songs-format" class="' + ctrl + '">' + opt(FORMATS, state.format) + '</select>' +
             '<button id="v3-songs-filters" class="relative ' + ctrl + ' flex items-center gap-2">Filters<span id="v3-songs-filter-count" class="hidden bg-fb-primary text-white text-xs rounded-full px-1.5">0</span></button>' +
             '<button id="v3-songs-select" class="' + ctrl + (state.selectMode ? ' bg-fb-primary text-white' : '') + '">Select</button>' +
@@ -4080,7 +4473,141 @@
         },
     };
 
+    // ── Grid cursor navigation (arrow keys / gamepad d-pad) ─────────────────
+    // shortcuts.js's generic library arrow-nav (_handleLibArrowNav) can't reach
+    // this screen: it assumes every navigable item is already a DOM node, but
+    // this grid is windowed — most of the library isn't in the DOM at any given
+    // scroll position. Cursor state here is an absolute index into state.songs,
+    // and moving it may need to fetch a page and/or scroll the window before the
+    // target card exists to highlight or activate.
+    let _gpIdx = null;
+
+    function _gpCardEl(idx) {
+        return document.querySelector('#v3-songs-grid [data-idx="' + idx + '"]');
+    }
+
+    function _gpApplyHighlight() {
+        const prev = document.querySelector('#v3-songs-grid [data-gp-cursor]');
+        if (prev) {
+            prev.removeAttribute('data-gp-cursor');
+            prev.querySelector('[data-v3-play]')?.classList.remove('ring-2', 'ring-fb-primary');
+        }
+        if (_gpIdx == null) return;
+        const el = _gpCardEl(_gpIdx);
+        if (!el) return;
+        el.setAttribute('data-gp-cursor', '1');
+        el.querySelector('[data-v3-play]')?.classList.add('ring-2', 'ring-fb-primary');
+    }
+
+    async function _gpEnsureVisible(idx) {
+        const main = document.getElementById('v3-main'), sizer = _sizerEl();
+        if (!main || !sizer) return;
+        const { cols, rowH } = measureGeom();
+        const row = Math.floor(idx / Math.max(1, cols));
+        const sizerTop = _sizerTopInScroller(main, sizer);
+        const rowTop = sizerTop + row * rowH;
+        const rowBottom = rowTop + rowH;
+        const viewTop = main.scrollTop, viewBottom = viewTop + main.clientHeight;
+        if (rowTop < viewTop) main.scrollTop = rowTop;
+        else if (rowBottom > viewBottom) main.scrollTop = rowBottom - main.clientHeight;
+        await renderWindow();
+
+        // #v3-songs-toolbar is sticky, but only pins to the top once scrolled
+        // PAST its natural in-flow position — before that point it isn't
+        // covering anything, after it covers a fixed band. That makes its
+        // occlusion scroll-dependent in a way no single precomputed offset
+        // captures, so measure the real rendered overlap and correct for it,
+        // rather than assuming the toolbar's height is always "lost" space.
+        const toolbar = document.getElementById('v3-songs-toolbar');
+        const cardEl = _gpCardEl(idx);
+        if (toolbar && cardEl) {
+            const overlap = toolbar.getBoundingClientRect().bottom - cardEl.getBoundingClientRect().top;
+            if (overlap > 0) {
+                // Push the row DOWN the screen to clear the toolbar — that means
+                // scrolling the content back UP, i.e. decreasing scrollTop (screen
+                // position = content position - scrollTop).
+                main.scrollTop -= overlap;
+                await renderWindow();
+            }
+        }
+    }
+
+    async function _gpMove(delta) {
+        if (!state.total) return;
+        if (_gpIdx == null) {
+            // Nothing selected yet — land on the first card and stop, same as
+            // shortcuts.js's legacy _handleLibArrowNav does for an empty
+            // selection: the first press establishes a cursor, it doesn't also
+            // move it (Right/Down previously skipped straight past row 0).
+            _gpIdx = 0;
+        } else {
+            const next = Math.max(0, Math.min(state.total - 1, _gpIdx + delta));
+            if (next === _gpIdx) return;
+            _gpIdx = next;
+        }
+        await ensureWindow(Math.max(0, _gpIdx - 1), Math.min(state.total, _gpIdx + 2));
+        await _gpEnsureVisible(_gpIdx);
+        _gpApplyHighlight();
+    }
+
+    function _gpActivate() {
+        if (_gpIdx == null) return;
+        _gpCardEl(_gpIdx)?.querySelector('[data-v3-play]')?.click();
+    }
+
+    // Bails on focus inside anything with its own keyboard semantics — form
+    // controls, buttons, and dialog/drawer overlays — same intent as
+    // shortcuts.js's _isInsideInteractiveControl, reimplemented locally since
+    // this is a plain script (not an ES module) and can't import it.
+    //
+    // The form-control/button check requires the element to be VISIBLE, not
+    // merely present: screens stay in the DOM (hidden, not removed) when you
+    // navigate away, so a real <button> focused on some OTHER now-hidden
+    // screen (dashboard, etc.) can leave document.activeElement pointing at
+    // it — an el.closest('#v3-songs') scope check would let that stale focus
+    // through fine, but would ALSO wrongly stop blocking genuinely-focused
+    // shared chrome like the topbar search input (#v3-search lives outside
+    // #v3-songs's DOM subtree even while v3-songs is the active screen).
+    // Visibility is the actual distinction that matters here, not DOM
+    // nesting. The dialog/drawer-overlay and contentEditable checks stay as
+    // they were — overlay-level concerns regardless of which screen sits
+    // underneath.
+    function _gpBlockedTarget(el) {
+        if (!el) return false;
+        if (['INPUT', 'SELECT', 'TEXTAREA', 'BUTTON'].includes(el.tagName) && el.offsetParent !== null) return true;
+        if (el.isContentEditable) return true;
+        if (el.closest && el.closest('[role="dialog"], .feedBack-modal, #lib-filter-drawer')) return true;
+        return false;
+    }
+
+    document.addEventListener('keydown', (e) => {
+        if (!songsActive() || state.view !== 'grid') return;
+        if (_gpBlockedTarget(document.activeElement)) return;
+        const isActivate = e.key === 'Enter' || e.key === ' ' || e.key === 'Spacebar';
+        if (!isActivate && !['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(e.key)) return;
+        e.preventDefault();
+        if (isActivate) { _gpActivate(); return; }
+        const { cols } = measureGeom();
+        if (e.key === 'ArrowRight') _gpMove(1);
+        else if (e.key === 'ArrowLeft') _gpMove(-1);
+        else if (e.key === 'ArrowDown') _gpMove(cols);
+        else if (e.key === 'ArrowUp') _gpMove(-cols);
+    });
+
     if (sm && typeof sm.on === 'function') {
+        sm.on('instrument:changed', function (e) {
+            var instId = e && e.detail && e.detail.instrument;
+            if (!instId || !_autoFilterEnabled) return;
+            // Record the new instrument so working-tuning-changed skips its
+            // reload path — this handler already handles the reload.
+            _lastRenderInstrument = libInstrument();
+            state.filters.tunings = [];
+            if (_applyArrangementAutoFilter(instId)) {
+                reload();
+                renderDrawerIfOpen();
+            }
+        });
+
         sm.on('screen:changed', (e) => {
             const id = e && e.detail && e.detail.id;
             if (id === 'v3-songs') { onV3SongsScreenEnter(); return; }
@@ -4130,6 +4657,23 @@
         // visible tuning chips against the new tuning. Cheap: re-decorates in place,
         // no re-fetch or re-paint. No-op off the Songs grid or without the capability.
         sm.on('working-tuning-changed', () => {
+            // A guitar<->bass SWITCH changes which tuning the facet, the filter,
+            // the sort and the card chip speak for, so the grid must re-query —
+            // re-colouring chips would leave the guitar tuning on screen and a
+            // guitar-keyed filter applied. A retune within one instrument still
+            // takes the cheap in-place path below.
+            const inst = libInstrument();
+            if (inst !== _lastRenderInstrument) {
+                _lastRenderInstrument = inst;
+                // A tuning selection keyed to the old instrument means nothing
+                // for the new one; clearing avoids an empty grid the user can't
+                // explain (the pills are re-rendered from the new facet).
+                state.filters.tunings = [];
+                const active = document.querySelector('.screen.active');
+                if (active && active.id === 'v3-songs') reload();
+                else _libraryDirty = true;
+                return;
+            }
             if (typeof songsActive === 'function' && !songsActive()) return;
             if (state.view !== 'grid') return;
             decorateTuningChips(_gridEl());