Turn vibe code into a clean PR

Prompt body

I have working-but-messy code from an AI chat. Convert it into a clean PR:

- Keep behavior the same unless I say otherwise
- Split into logical commits if needed (describe them)
- Add/adjust minimal tests for the happy path
- Write a PR title + summary (why / what / how to test)
- Flag any security or secret risks

Here is the code and context:
{{paste}}