# CCLI SongSelect Import — Issues

## [2026-05-10] Known Issues / Gotchas

### T1: Fixture corpus requires structurally accurate CCLI format
- Plan originally asked for "real CCLI text pastes" but since we can't access SongSelect, agent creates synthetic fixtures.
- Synthetic fixtures MUST match exact CCLI format: title line, blank, section label, lyrics, blank, footer with © and CCLI #.
- The parser tests depend on these fixtures — structural accuracy is critical.

### T7: ProImportService method name
- Plan was corrected: the public method is `ProImportService::import(UploadedFile $file)`, not `upsertSong()`.
- When mirroring the pattern, READ app/Services/ProImportService.php before implementing.

### No Admin Role
- No `admin` role or Policy exists in the codebase.
- CCLI Settings section is visible to ALL authenticated users.
- Document this decision, don't create a policy gate.

### AGENDA_KEYS whitelist
- SettingsController has a `const AGENDA_KEYS` array.
- T4 MUST add `'default_translation_language'` to this array OR update the validation to include it.
- Failure to update AGENDA_KEYS = PATCH /settings will silently ignore the new key.

### Translation Pairing Label Direction
- CCLI paste can have English labels; local songs may have German labels (Strophe, Refrain).
- CcliLabels::normalizeLabelName() normalizes BOTH directions to canonical English before pairing.
- Do NOT assume same language on both sides.

### T7: Global Label Slide Replacement Caveat
- The requested CCLI import pattern deletes `songSlides()` on the resolved global `Label` before recreating slides.
- Because labels are shared globally, a later import using the same canonical label name replaces that label's slide text globally; this intentionally matches the task spec and existing `ProImportService` pattern, but remains a design caveat for future per-song slide ownership work.

### T8: Translation Pairing Leaves Missing Sections Non-Fatal
- `CcliTranslationPairingService` intentionally does not throw when a local arrangement label is absent from the CCLI paste.
- Missing labels are returned in `unmatched_labels`, and their mapping entries keep empty slide placeholders so `distributed_text` still aligns with the local arrangement shape.