## Summary
- Documentation for the song lookup autocomplete and community version
detection feature shipped in PR #451
## Changes
- **docs/README.md**: Added feature status rows (song lookup
autocomplete, community version detection) and recent changes entry
- **docs/API.md**: New "Catalog (Song Lookup)" section documenting all 3
endpoints (`/api/catalog/artists`, `/api/catalog/tracks`,
`/api/catalog/community-check`) with request/response examples
- **docs/ARCHITECTURE.md**: Added karaoke-decide and KaraokeNerds to
external services table, added `catalog_proxy_service.py` and
`karaokenerds_service.py` to service modules table
- **docs/LESSONS-LEARNED.md**: Added "Autocomplete UX: Less Is More"
pattern (single autocomplete that overwrites both fields > dual
autocompletes)
## Test plan
- Docs-only change, no code modifications
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@coderabbitai ignore
## Summary
- **Cancel → Delete**: The Cancel button now permanently deletes jobs
(Firestore doc + GCS files) via the existing `DELETE /api/jobs/{job_id}`
endpoint. Cancelled jobs no longer exist as a concept in the user-facing
flow.
- **Hide completed fix**: The "Hide completed" toggle now only hides
successful completions (`complete`, `prep_complete`). Failed jobs remain
visible so users always see jobs that need attention.
- **Date-only sorting**: Removed priority-based sorting that buried
failed jobs below completed ones. Jobs now sort purely by `created_at`
descending — newest first, always.
- **Admin controls toggle**: Admins see a Shield toggle in the header
that reveals inline admin action buttons (reset, restart, delete, regen
screens, etc.) on each job card — no need to switch to the admin
dashboard.
## Test plan
- [x] Frontend tests pass (496 tests)
- [x] Backend route tests pass (8 tests)
- [x] `next build` succeeds
- [x] New AdminJobActions component has unit tests
- [x] JobCard admin controls rendering tested
- [x] JobActions cancel→delete behavior tested
- [x] E2E regression test updated for delete flow
- [ ] Visual verification: failed job appears at top of Recent Jobs
- [ ] Visual verification: "Hide completed" keeps failed jobs visible
- [ ] Visual verification: Admin shield toggle shows/hides admin actions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Fixes 4 UX problems caused by the guided wizard creating a backend job
at Step 2 (audio search), before the user has set `is_private`, display
overrides, or confirmed they want a job at all
- Adds `POST /api/audio-search/search-standalone` — runs search
synchronously, stores results in a 30-minute Firestore session, returns
`search_session_id + results` (no job created)
- Adds `POST /api/jobs/create-from-search` — creates job at Step 3 with
all correct values from the start; atomically consumes the session to
prevent duplicate job creation
## Problems Solved
**A) Orphan job records** — abandoned searches left job records in
Firestore; back button `deleteJob` cleanup was best-effort
**B) Wrong field values at creation** — job existed briefly with
`is_private: false` and no display overrides
**C) Jobs in Recent Jobs list** — `AWAITING_AUDIO_SELECTION` jobs
appeared in the list before user confirmed
**D) Notification chime fired** — state transitions on the temporary job
triggered the action-required chime during search
## Changes
- `backend/routers/audio_search.py` — new `POST
/api/audio-search/search-standalone` endpoint (synchronous, no job)
- `backend/routers/jobs.py` — new `POST /api/jobs/create-from-search`
endpoint with validate-then-consume session pattern
- `backend/services/firestore_service.py` — `create_search_session`,
`get_search_session`, `consume_search_session` (atomic transaction),
`delete_search_session`
- `infrastructure/modules/database.py` — Firestore TTL policy for
`search_sessions` collection (30-min auto-expiry)
- `frontend/lib/api.ts` — `searchStandalone`, `createJobFromSearch`
methods
- `frontend/components/job/steps/AudioSourceStep.tsx` — uses standalone
search; no polling; no job state
- `frontend/components/job/GuidedJobFlow.tsx` — defers job creation to
Step 3 confirm; no `deleteJob` on back
**Unchanged:** old `POST /api/audio-search/search` (CLI backward
compat), upload/URL paths, `AWAITING_AUDIO_SELECTION` status.
## Testing
- [x] 26 new backend unit tests
(`backend/tests/test_standalone_search.py`) covering session CRUD, both
new endpoints, ownership/tenant/TTL/index validation, atomic consumption
- [x] 13 new frontend Jest tests
(`frontend/__tests__/guided-flow.test.tsx`) covering API contract,
component exports, behavioral invariants
- [x] Full test suite passes: 2167 backend + 507 frontend
## Review
- [x] CodeRabbit CLI review completed (3 cycles, 0 remaining findings)
- [x] Atomic session consumption via Firestore transaction (prevents
duplicate jobs on concurrent requests)
- [x] Validate-before-consume pattern (4xx errors leave session intact
for user retry)
- [x] Tenant consistency check added
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@coderabbitai ignore
## Summary
- **Better no-results UX**: Replace bare "No audio sources found" text
with a contextual `NoResultsSection` card explaining why results might
be missing (unreleased tracks, independent music, unusual characters)
and what to try
- **Softer timeout styling**: Timeout errors now show amber
(`text-amber-400 bg-amber-500/10`) instead of red — it's a delay, not a
failure. Credit/API errors remain red
- **Larger fallback buttons** when no results: `h-12` height and `w-4
h-4` icons (vs `h-9`/`w-3.5 h-3.5`) since upload/URL are the primary
actions
- **Fix file input text overlap**: Replace `opacity-0` absolute
`<Input>` with `<label>` + `<input className="sr-only">` — eliminates
browser "Browse..." bleed-through, adds "Click to browse or drag a file"
helper text
- **Signed URL upload flow** for large files (≥25MB): Bypasses Cloud
Run's 32MB body limit; files <25MB still use the existing direct upload
- **Upload progress bar**: Phase labels (Preparing / Uploading X/Y MB /
Finalizing) + animated progress bar during signed URL uploads
- **Large file warning** (>100MB): Amber amber notice about expected
upload time
- **GCS CORS config**: Add Pulumi CORS rule for `PUT` from
`gen.nomadkaraoke.com` and `localhost:3000` — required for
browser-to-GCS signed URL uploads to work
⚠️ **Deploy order matters**: The GCS CORS config (infrastructure change)
must be deployed before the signed URL upload path will work in
production. Both changes are in this PR so they deploy together on
merge.
## Test plan
- [x] 492 Jest tests passing (9 new tests for `createJobWithUploadUrls`,
`uploadToSignedUrl`, `completeJobUpload`, `uploadJobSmart`)
- [x] `npx next build` succeeds
- [x] CodeRabbit CLI: no findings
- [ ] **Manual**: Search for a nonexistent track → verify
`NoResultsSection` appears with guidance text and larger buttons
- [ ] **Manual**: Trigger a timeout (slow network) → verify amber banner
(not red)
- [ ] **Manual**: Open upload form → verify no "Browse..." text
bleed-through, see "Click to browse or drag a file"
- [ ] **Manual** (post-deploy): Upload a file ≥25MB → verify progress
bar appears and upload completes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
- E2E happy path test now uses **private mode** (NOMADNP prefix) so test
jobs never consume public NOMAD brand codes or upload to GDrive/YouTube
- `delete-outputs` admin endpoint now **recycles brand codes** after
successful Dropbox + GDrive cleanup
- `DELETE /api/jobs/{id}` endpoint now **recycles brand codes** before
deleting the job record
- Frontend delete-outputs dialog accurately shows brand code recycling
status (recycled/skipped/failed)
## Context
Test jobs ("piri - dog") consumed NOMAD-1275 and NOMAD-1276 brand codes.
When manually deleted via `delete-outputs`, the brand codes were not
recycled back to the counter. This caused the GDrive validator to detect
sequence gaps at 1275/1276 when NOMAD-1277 was later uploaded.
## Test plan
- [x] 7 new unit tests for brand code recycling in both endpoints
- [x] All 490 existing tests pass (483 frontend + backend)
- [x] Frontend builds successfully (TypeScript types updated)
- [ ] Manual: run E2E test, verify job uses NOMADNP prefix
- [ ] Manual: delete-outputs on a test job, verify brand code recycled
in response
<!-- @coderabbitai ignore -->
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Update docs to reflect feedback-for-credits feature (PR #431) and beta
program removal (PR #430)
- Add `user_feedback` Firestore collection to architecture docs
- Mark beta program section as deprecated in API reference
- Add archive entry for the feedback-for-credits feature
## Changes
| File | Update |
|------|--------|
| `docs/README.md` | Replace beta with feedback-for-credits in status
table, add recent changes entries |
| `docs/API.md` | Mark beta section deprecated, document
`feedback_eligible` in `/me`, link from credit enforcement |
| `docs/ARCHITECTURE.md` | Add `user_feedback` collection, mark
`beta_feedback` as deprecated |
| `docs/archive/2026-03-01-feedback-for-credits.md` | New archive entry
|
## Test plan
- [x] Docs-only change, no code modified
- [x] Verified all internal doc links are valid
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Users who complete 2+ karaoke videos can submit product feedback to
earn 2 free credits
- Replaces beta-only feedback flow — available to ALL users
- PR 2 of 2: follows #430 which removed the beta program from homepage
## Changes
**Backend:**
- New `POST /api/users/feedback` endpoint with eligibility checks,
validation (>50 char text), credit granting
- New `GET /api/users/feedback/eligibility` endpoint
- `feedback_eligible` field added to `/api/users/me` response
- `UserFeedback` model + `user_feedback` Firestore collection
- Welcome email updated with prominent credit display and feedback
teaser
**Frontend:**
- `FeedbackDialog` component: 4 star ratings, 3 text fields, 2
checkboxes, submit/success states
- Dismissible banner on dashboard when user is eligible
- "Earn 2 Free Credits" menu item in user dropdown (green Gift icon)
- Auto-refreshes user data after submission to hide prompts
**Docs:**
- API.md updated with new endpoints
## Test plan
- [ ] Backend Python syntax verified (ast.parse)
- [ ] Frontend builds successfully (`npx next build`)
- [ ] Version bumped to 0.121.0
- [ ] Manual flow: sign up → create 2 jobs → see banner → submit
feedback → credits granted → banner disappears
- [ ] Edge cases: duplicate submission blocked, ineligible users don't
see prompts
<!-- @coderabbitai ignore -->
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
Complete UX overhaul of the karaoke video generation review flow,
spanning 4 phases:
- **Phase 1 - Job Creation**: Guided audio source selection with 3-tier
confidence system, responsive stepper, renamed "Find Audio" to "Choose
Audio"
- **Phase 2 - Audio Selection**: Production E2E tests for guided job
creation flow
- **Phase 3 - Lyrics Review**: Guidance panel with workflow steps, gap
navigation scoped to visible lines, simplified review UI with edit
tracking and low-friction feedback
- **Phase 4 - Instrumental Review**: Responsive layout (waveform no
longer disappears on short viewports), canvas-rendered time ruler,
hover-to-highlight waveform regions, dedicated Alternate Instrumental
upload section with duration explanation, dismissable guidance panel
### Key changes
- Root layout switches from viewport-locked (`h-screen overflow-hidden`)
to scrollable (`min-h-screen`) — fixes waveform disappearing on short
viewports
- Bottom section stacks vertically on mobile/tablet, side-by-side on
desktop
- Time ruler rendered directly on canvas with auto-scaling tick
intervals
- Hovering mute region or segment buttons highlights the corresponding
waveform range
- Upload button moved from toolbar to dedicated section with context and
duration requirement
- 21 unit tests added for instrumental review components
- Guidance panels with dismissable tips across lyrics and instrumental
review
## Test plan
- [x] `npx next build` — no errors
- [x] `npx jest --testPathPattern="instrumental-review/__tests__"` —
21/21 pass
- [x] Visual testing at 4 viewports: desktop (1280x800), tablet
(768x1024), mobile (375x667), short (1280x400)
- [x] Hover highlight verified with Playwright MCP
- [x] Time ruler scales correctly at 1x and 2x zoom
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Wire up the existing credits system to actually gate job creation -
previously, credits were tracked but never enforced
- Add credit check before job creation, atomic deduction after, and
auto-refund on job failure
- New users now receive 2 welcome credits (was 1)
- Frontend shows zero-credit warning banner, disables submit, and
handles 402 errors with "Buy Credits" link
- Clean up dead credit deduction code from auth_service
## Changes
**Backend:**
- `InsufficientCreditsError` exception with 402 handler
- Credit check + deduction in `JobManager.create_job()` (admin bypass,
atomic deduction, rollback on failure)
- Auto-refund in `JobManager.fail_job()` (skipped for admins,
error-isolated)
- Welcome credits bumped 1 → 2
- Removed dead credit deduction path from
`auth_service.increment_token_usage()`
**Frontend:**
- Zero-credit warning banner at top of job submission form
- Submit buttons disabled when credits = 0
- 402 error handling with "Buy Credits" link
- Boolean state `isCreditError` (not string matching) for credit error
display
**Tests:**
- 13 new backend unit tests covering enforcement, refunds, admin bypass,
atomicity
- 3 new Playwright E2E tests for frontend credit UX
- Tests for 402 exception handler and auth_service cleanup
## Test plan
- [x] Backend unit tests: `pytest tests/test_credit_enforcement.py -v`
(13 tests)
- [x] 402 handler test in `test_main.py`
- [x] Auth service test in `test_auth_firestore.py`
- [x] Frontend E2E tests: `npx playwright test
e2e/regression/credit-enforcement.spec.ts`
- [x] Full suite: `make test` (1928 tests passed)
- [ ] Manual: Create test user with 0 credits → verify 402
- [ ] Manual: Create test user with 1 credit → verify deduction
- [ ] Manual: Fail a job → verify credit refund
<!-- @coderabbitai ignore -->
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@coderabbitai ignore
## Summary
- Add `is_private` flag to jobs that changes distribution behavior for
non-published tracks
- Private jobs upload to Dropbox `Tracks-NonPublished` folder with
`NOMADNP` brand prefix
- Private jobs skip YouTube and Google Drive uploads entirely
- Completion emails omit YouTube section for private jobs
- Available to all users at job creation; admin can toggle on existing
jobs
- When admin toggles completed job to private, existing outputs are
auto-deleted
## Changes
### Backend
- **Job model**: Added `is_private: bool = False` to `Job` and
`JobCreate`
- **Config**: Added `DEFAULT_PRIVATE_DROPBOX_PATH` and
`DEFAULT_PRIVATE_BRAND_PREFIX` settings
- **Distribution helper**: New `get_effective_distribution_for_job()` in
`job_defaults_service.py` applies private overrides at runtime
- **Orchestrator + native paths**: Both distribution code paths use the
helper (per "Fix Both Sides" lesson)
- **Email template**: YouTube section conditionally removed when
`is_private=True`
- **Credential pre-validation**: Skip YouTube/GDrive credential checks
for private jobs
- **API endpoints**: All 4 job creation endpoints accept `is_private`;
admin can PATCH it
- **Admin auto-delete**: Toggling completed job to private triggers
output deletion
### Frontend
- **Job creation form**: "Private (Non-Published)" checkbox on all 3
tabs (upload, URL, search)
- **Admin dashboard**: Private toggle in job configuration section
- **API interfaces**: Updated TypeScript interfaces and API methods
### Tests
- 23 unit tests covering model, distribution overrides, email template,
notification service, request models, admin toggle, and orchestrator
config
- Fixed MagicMock truthiness issue in existing tests
## Test plan
- [x] All 23 private tracks tests pass
- [x] All 1794 existing backend tests pass (1 flaky unrelated test)
- [x] CodeRabbit review: credential pre-validation issue found and fixed
- [ ] Manual: Create private job end-to-end, verify Dropbox folder
- [ ] Manual: Verify completion email has Dropbox link but no YouTube
section
- [ ] Manual: Admin toggle on completed job deletes outputs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Add missing `POST /api/jobs/{id}/create-custom-instrumental` endpoint
that was lost during the unified review UI migration. The endpoint
creates a custom instrumental by muting selected backing vocal regions
and returns a signed audio URL for playback.
- Strip `reference_lyrics` from corrections data before saving to
Firestore `state_data`, preventing 1MB document size limit errors when
Genius fetches non-lyrics content (e.g. screenplays). Full data is
preserved in GCS.
- Update frontend `InstrumentalSelector` to use the signed audio URL
returned from the create endpoint instead of a non-existent stream
endpoint.
## Test plan
- [x] 11 new backend tests covering both fixes (happy path, auth,
validation, error handling, Firestore stripping, GCS preservation)
- [x] Full test suite passes (1912 backend, 168 frontend)
- [ ] Manual test: create custom instrumental on a job in review
- [ ] Manual test: submit corrections for a job with oversized Genius
lyrics
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Add `AudioTranscodingService` that transcodes FLAC audio to OGG Opus
128kbps (~3 MB vs 35+ MB), cached in GCS at `review-audio/*.ogg`
- Eager transcoding in `screens_worker` before `AWAITING_REVIEW` so
files are cached before the user opens the review UI
- All 3 review audio paths (`_stream_audio`, `get_correction_data`,
`get_instrumental_analysis`) now serve transcoded OGG URLs with FLAC
fallback
- Admin endpoint `POST /admin/jobs/{job_id}/prepare-review-audio` for
backfilling existing jobs
## Test plan
- [x] 21 unit tests at 100% coverage on `AudioTranscodingService`
- [x] 229 existing review tests pass with 0 regressions
- [ ] Deploy and use admin endpoint to backfill job `4bed6f80`
- [ ] Open review UI — verify audio loads fast, Network tab shows ~3 MB
OGG
- [ ] Check GCS for cached files at `jobs/4bed6f80/review-audio/*.ogg`
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
Fixes the override-audio-source endpoint which was transitioning jobs to
`awaiting_audio_selection` without actually performing the search,
leaving jobs stuck with no results to select from.
## Changes
- Now performs actual audio search after clearing state
- Stores search results in state_data before transitioning
- Updated response model to include `search_results_count` and `error`
fields
- Updated API docs to reflect new behavior
## Test plan
- [x] Ran test_admin_job_reset.py - all 39 tests pass
- [x] Manually tested on job 284ed6a6 (populated search results)
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
## Summary
Add three new admin endpoints for better Made-For-You order management,
plus clean up the admin toolbar to remove confusing low-level buttons.
### New Endpoints
1. **`POST /api/admin/jobs/{job_id}/regenerate-screens`**
- Regenerates title/end screens with current artist/title metadata
- Use after editing artist/title to update screens without full
reprocessing
2. **`POST /api/admin/jobs/{job_id}/restart`**
- Full restart that actually triggers workers (fixes the "stuck in
pending" issue)
- Option to preserve audio stems for faster restart
- Handles YouTube, audio search, and file upload jobs appropriately
3. **`POST /api/admin/jobs/{job_id}/override-audio-source`**
- Switch from YouTube URL to audio search mode
- Allows finding higher quality audio for MFY orders
### Frontend Changes
- Add new toolbar buttons: **Regen Screens**, **Full Restart**, **Audio
Search**
- Remove confusing low-level buttons that could leave jobs in broken
states:
- "Reset to Start" (replaced by "Full Restart")
- "Clear Workers" (low-level escape hatch)
- "Trigger" (low-level escape hatch)
- Add confirmation dialogs with clear explanations
### Use Case
When a customer submits a Made-For-You order with:
- Wrong artist/title → Edit fields, click "Regen Screens"
- Low-quality YouTube URL → Click "Audio Search" to switch to audio
search mode
- Job stuck after reset → Click "Full Restart" to actually trigger
workers
## Test plan
- [ ] Verify new endpoints return proper responses
- [ ] Verify "Regen Screens" regenerates screens with updated metadata
- [ ] Verify "Full Restart" with preserve_audio_stems=true triggers
screens worker
- [ ] Verify "Full Restart" with preserve_audio_stems=false re-downloads
YouTube audio
- [ ] Verify "Audio Search" transitions job to awaiting_audio_selection
- [ ] Verify old confusing buttons are removed from toolbar
🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@coderabbitai ignore
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
## Summary
Add flacfetch service health monitoring to the frontend footer,
displaying version and status alongside the existing encoding worker
indicator.
## Changes
- **Backend**: Added `/api/health/flacfetch` endpoint for lightweight
health checks
- **Frontend**: Added flacfetch health display in version footer with
green/red status indicator
- **Tests**: Added 6 comprehensive unit tests for health endpoints
(flacfetch + encoding worker)
- **Docs**: Updated API.md with new endpoint documentation
## Implementation Details
The footer now displays:
```
Frontend: v0.114.8 | Backend: v0.114.8 | ● Encoder: v0.95.1 | ● Flacfetch: v1.2.3
```
Health indicators:
- Green dot (●) = service healthy
- Red dot (○) = service offline
- Hidden if service not configured
## Testing
- [x] All 1749 tests pass (including 6 new health endpoint tests)
- [x] Manual code review completed (CodeRabbit CLI couldn't handle large
diff)
- [x] API endpoint tested for all states (not_configured, offline, ok)
## Review
- [x] Code quality verified - follows existing patterns
- [x] Tests comprehensive - all response states covered
- [x] Documentation updated - API.md includes new endpoint
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
## Summary
Merges the two-step human review process (lyrics review → instrumental
selection) into a single unified flow. Users now review lyrics AND
select instrumental track in one session.
**Benefits:**
- Better UX (one interaction vs two)
- Reduced drop-off between steps
- Single email notification instead of two
- Simpler workflow
## Changes
### Backend
- `complete_review` endpoint now accepts optional
`instrumental_selection` in request body
- Backing vocals analysis moved from `render_video_worker` to
`screens_worker` (runs before review)
- Removed standalone instrumental selection endpoints (now part of
combined review)
- Added `CompleteReviewRequest` model with validation
### Frontend
- New `InstrumentalSelectorEmbedded` component for combined review UI
- `LyricsAnalyzer` updated to proceed to instrumental review
- `ReviewChangesModal` shows "Proceed to Instrumental Review" button
- Mock data updated in E2E tests
### Local CLI
- `gen_cli.py` refactored to use `run_combined_review()` instead of
separate `run_instrumental_review()`
- `ReviewServer` extended with instrumental options and analysis
- Deleted standalone `InstrumentalReviewServer`
### Documentation
- Updated `docs/README.md` with recent changes entry
- Updated `docs/ARCHITECTURE.md` with new pipeline diagram
- Updated `docs/API.md` with endpoint changes
- Added lesson to `docs/LESSONS-LEARNED.md`
## Test plan
- [x] Backend unit tests: 1742 passed
- [x] Frontend unit tests: 234 passed
- [x] New integration tests: 5 tests for combined flow
- [x] New backend tests: 7 tests for CompleteReviewRequest and
state_data
- [x] New frontend E2E tests: 6 tests for combined flow UI
🤖 Generated with [Claude Code](https://claude.com/claude-code)
@coderabbitai ignore
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
## Summary
- Improve admin reset job feedback with transparent worker trigger
status
- Add manual trigger endpoint as fallback when auto-trigger fails
- Enhance frontend UI with detailed result dialogs and loading states
**Problem:** When using the admin "Reprocess" button (reset to
`instrumental_selected`), the job status reset correctly but the video
worker was NOT automatically triggered, leaving jobs stuck. The
auto-trigger could fail silently with no user feedback.
## Changes
### Backend (`backend/api/routes/admin.py`)
- Add `worker_triggered` and `worker_trigger_error` fields to
`JobResetResponse`
- Add try/except error handling around worker trigger in `reset_job()`
- Add new `POST /api/admin/jobs/{job_id}/trigger-worker` endpoint for
manual triggering
### Frontend (`frontend/app/admin/jobs/page.tsx`, `frontend/lib/api.ts`)
- Add "Trigger" button in admin toolbar for manual worker triggering
- Add detailed Reset Result Dialog showing:
- Status change (from → to)
- State data keys that were cleared
- Worker trigger status (for instrumental_selected)
- "What happens next" guidance
- "Trigger Now" button if worker wasn't triggered
- Add loading spinners for all async operations
### Tests (`backend/tests/test_admin_job_reset.py`)
- Add 14 new tests for worker trigger response fields and trigger-worker
endpoint
- All 38 tests pass
### Documentation
- Update `docs/API.md` with new endpoint and response fields
- Update `docs/README.md` recent changes
## Test plan
- [x] Backend tests pass (1756 passed)
- [x] TypeScript compiles without errors
- [ ] Manual: Reset a job to `instrumental_selected` via admin UI
- [ ] Manual: Verify response shows worker trigger status
- [ ] Manual: If trigger fails, verify error shown in UI
- [ ] Manual: Click "Trigger Worker" button and verify job starts
processing
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
## Summary
- **Fix critical bug**: When completed jobs are re-reviewed or reset,
worker progress keys were not cleared, causing workers to skip with
"already complete, skipping"
- **Add Clear Workers button**: Escape hatch in admin UI to manually
clear all worker progress markers
- **Add new API endpoint**: `POST
/api/admin/jobs/{job_id}/clear-workers` for programmatic access
- **Fix E2E test suite**: Update admin-job-detail.spec.ts tests to match
current UI patterns
## Test plan
- [x] Backend unit tests for new `delete_state_data_key(s)` methods pass
- [x] Backend tests for review re-submission and admin reset pass
- [x] Frontend E2E tests for Clear Workers button pass
- [x] All admin-job-detail E2E tests now pass (fixed 9 pre-existing
failures)
## Root cause
Jobs have worker progress keys like `render_progress: {stage:
'complete'}` in `state_data`. Workers check these for idempotency. When
re-reviewing a completed job:
1. Review interface only changed `status` to `in_review`
2. Worker progress keys remained with `stage: 'complete'`
3. Triggered workers saw "complete" and skipped execution
## Solution
- Clear worker progress keys in `review.py` when re-reviewing jobs that
were previously completed
- Add `job_manager.delete_state_data_key(s)` helpers
- Add admin UI button and API endpoint for manual intervention
<!-- @coderabbitai ignore -->
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
## Summary
- Add "Reprocess" button to admin job reset toolbar
- Enables re-encoding and re-distributing jobs with existing settings
after deleting outputs
- Automatically triggers video worker when resetting to
`instrumental_selected` state
## Changes
### Backend (`backend/api/routes/admin.py`)
- Add `instrumental_selected` to allowed reset states
- Configure state data clearing (video_progress, encoding_progress,
distribution, brand_code, etc.)
- Auto-trigger video worker via WorkerService after reset
### Frontend (`frontend/app/admin/jobs/page.tsx`)
- Add "Reprocess" button with RefreshCw icon to reset toolbar
- Add tooltip explaining the action
### Tests (`backend/tests/test_admin_job_reset.py`)
- Test successful reset to instrumental_selected
- Test video worker trigger after reset
- Test message reflects worker trigger success/failure
- Test state data clearing
## Test plan
- [x] Unit tests pass for new reset target
- [x] All existing admin reset tests still pass
- [x] CodeRabbit review completed
## Use case
1. Job completes but has quality issues
2. Admin uses "Delete Outputs" to remove YouTube/Dropbox/GDrive files
3. Admin clicks "Reprocess" button
4. Job re-encodes and re-distributes with same settings
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
## Summary
Add admin functionality to delete all distributed outputs (YouTube,
Dropbox, Google Drive) for a completed job while preserving the job
record. This enables quality issue remediation by deleting outputs,
resetting to review, and re-generating.
## Changes
- Add `outputs_deleted_at` and `outputs_deleted_by` fields to Job model
- Add `POST /api/admin/jobs/{job_id}/delete-outputs` endpoint
- Add auto-clear of outputs_deleted_at flag when outputs are re-uploaded
after re-processing
- Add "Delete All Outputs" button and confirmation dialog in admin job
detail page
- Add "Outputs Deleted" badge when flag is set
- Add 13 unit tests for the new endpoint
## Testing
- [x] Backend unit tests pass (1546 passed)
- [x] Frontend unit tests pass (163 passed)
- [x] Frontend build succeeds
- [x] New endpoint tests pass (13 tests)
## Review
- [x] CodeRabbit CLI review completed locally
- [x] Review feedback addressed (2 issues fixed)
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
## Summary
Refactor made-for-you order processing to pause at audio selection like
regular search jobs, giving admin control over audio source selection
before processing.
- Made-for-you orders now pause at `AWAITING_AUDIO_SELECTION` for admin
review
- Admin receives notification email with link to select audio source
- Customer receives professional order confirmation email
- On completion, ownership transfers from admin to customer for delivery
## Changes
### Backend
- Add model fields: `made_for_you`, `customer_email`, `customer_notes`
to Job and JobCreate
- Add email templates: `send_made_for_you_order_confirmation()` and
`send_made_for_you_admin_notification()`
- Add email suppression for intermediate reminders on made-for-you jobs
(internal.py)
- Add ownership transfer on job completion (video_worker.py - not in
this commit, was in prior session)
### Tests
- Add `backend/tests/test_made_for_you.py` with 50+ test cases
- Add made-for-you email tests to `test_email_service.py`
- Add model field tests to `test_models.py`
### Documentation
- Update `docs/API.md` with full made-for-you order flow
- Add "Admin-Owned Jobs with Ownership Transfer" pattern to
`docs/LESSONS-LEARNED.md`
- Add recent changes entry to `docs/README.md`
## Testing
- [x] All Python files pass syntax validation
- [x] Frontend unit tests pass (150 tests)
- [x] Email methods validated via direct Python script
- [x] Model fields validated via direct Python script
- [ ] Backend pytest has pre-existing environment issue
(lyrics_transcriber import)
## Review
- [x] Local CodeRabbit review completed
- [x] Review feedback addressed (hardcoded URL → self.frontend_url)
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
- Add user impersonation feature for admins to view the app as any user
- Replace "Make Admin" button with "Impersonate" button in admin users
page
- Display amber impersonation banner when viewing as another user
## Changes
- **Backend**: Add `POST /api/admin/users/{email}/impersonate` endpoint
that creates a session token for the target user
- **Frontend Auth**: Add `startImpersonation` / `endImpersonation`
methods to auth store with token rollback on failure and nested
impersonation prevention
- **Admin UI**: Replace role toggle button with impersonate button
(disabled for self)
- **Banner Component**: New `ImpersonationBanner` component showing
"Viewing as {email}" with Stop button
- **Tests**: 7 backend unit tests + 4 E2E tests (2 skipped - require
stateful mocks)
- **Docs**: Updated API.md with new endpoint, added testing lesson to
LESSONS-LEARNED.md
## Testing
- [x] Backend unit tests pass (7/7 impersonation tests)
- [x] Frontend E2E tests pass (4 pass, 2 skipped)
- [x] Manual testing needed for full flow
## Review
- [x] CodeRabbit CLI review completed locally
- [x] Review feedback addressed (token rollback, nested impersonation
guard)
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
## Summary
- Filter out E2E test data from admin dashboard by default (emails
ending in `@inbox.testmail.app`)
- Add "Show test data" toggle in admin header that persists to
localStorage
- Add `exclude_test` query parameter to all admin list/stats endpoints
(defaults to `true`)
- Add streaming limits with warnings to prevent memory issues on large
datasets
## Changes
**Backend:**
- New `backend/utils/test_data.py` with `is_test_email()` utility
- Updated admin stats endpoint with test data filtering
- Updated users list, jobs list, beta stats, and audio searches
endpoints
- Added USERS_STREAM_LIMIT (2000) and JOBS_STREAM_LIMIT (10000) with
warning logs
**Frontend:**
- New `frontend/lib/admin-settings.ts` zustand store for admin
preferences
- Toggle switch in admin layout header
- All admin pages pass `exclude_test: !showTestData` to API calls
**Docs:**
- Updated API.md with exclude_test parameter documentation
## Test Plan
- [x] Backend tests pass (68 passed)
- [x] Frontend tests pass (128 passed)
- [x] Frontend build succeeds
- [x] CodeRabbit review passed
- [ ] Manual: Visit `/admin` - stats should show lower numbers by
default
- [ ] Manual: Toggle "Show test data" ON - counts should increase
- [ ] Manual: Toggle persists across page refreshes
<!-- @coderabbitai ignore -->
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
- Add optional "Display As" fields to audio search, allowing users to
search for audio by one artist/title but display a different
artist/title on title screens and filenames
- Useful for Broadway casts, covers, remixes where tracker metadata
differs from desired display
## Changes
- Add `display_artist`/`display_title` fields to `AudioSearchRequest`
model
- Update job creation to use display values for output (title screens,
filenames, YouTube, distribution)
- Add "Display As" optional fields to frontend search UI
- Update API documentation
## Example Use Case
- **Search For**: Artist = "Jeremy Kushnier", Title = "I Can't Stand
Still"
- **Display As**: Artist = "Footloose (Broadway Cast)"
- **Result**: Audio found using "Jeremy Kushnier", but title screen
shows "Footloose (Broadway Cast) - I Can't Stand Still"
## Test plan
- [ ] Search with display override → verify title screen shows display
values
- [ ] Search without display override → verify search values used
(backwards compatible)
- [ ] Verify filenames use display values
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
- Add admin UI at `/admin/searches` to view and manage cached audio
search results
- Allow admins to clear stale caches when flacfetch is updated with new
providers
- Fixes issue where jobs showed only YouTube results when lossless
sources should be available
## Changes
- **Backend**: New admin endpoints `GET /api/admin/audio-searches` and
`POST /api/admin/audio-searches/{job_id}/clear-cache`
- **Frontend**: New admin page with search results table, status
indicators, and cache clear action
- **Safety**: Status validation prevents clearing cache on
active/complete jobs
- **Docs**: Updated API.md, LESSONS-LEARNED.md, and README.md
## Testing
- [x] Backend module imports successfully
- [x] Frontend TypeScript compiles without errors
- [x] CodeRabbit CLI review completed and issues addressed
## Review
- [x] CodeRabbit CLI review completed locally (3 cycles)
- [x] Fixed: `has_lossless` now computed from ALL results, not just
first 10
- [x] Fixed: Added status validation before cache clear
- [x] Noted (not fixed): Scalability optimization for large-scale -
acceptable for admin tool
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
Add a full admin dashboard at `/admin` for platform management with:
- **Dashboard**: Stats overview showing users, jobs by status, credits
issued
- **User Management**: Search, sort, pagination, add credits, toggle
role, enable/disable
- **Job Browser**: Filter by status/user, view details with timeline and
logs, delete jobs
- **Beta Program**: Stats and feedback list
## Changes
### Backend
- New `/api/admin/stats/overview` endpoint for dashboard metrics
- Enhanced user list with search, pagination, and sorting
- New user detail endpoint with credit history and recent jobs
### Frontend
- Admin layout with responsive sidebar navigation
- Dashboard page with stats cards and job status breakdown
- User management pages (list + detail) with all admin actions
- Job browser pages (list + detail) with filters and log viewer
- Beta program page with stats and feedback
- Query-param based routing (`/admin/users/detail?email=`) for static
export compatibility
### Documentation
- Added Admin Endpoints section to API.md
- Updated README with admin dashboard in What Works and Current State
## Testing
- [x] Backend tests pass (`make test` - 57 passed)
- [x] Frontend tests pass (`npm run test:all` - 64 passed)
- [x] Frontend build passes (`npm run build`)
- [x] Manual testing completed
## Review
- [x] CodeRabbit CLI review completed locally (2 cycles)
- [x] All important feedback addressed
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
- Add is_configured() method to EmailService
- Return 503 error if email service not configured (magic link, beta enrollment)
- Add email/Stripe status to /health/detailed endpoint
- Update docs to reflect merged payment flow (PR #90)
- Add lesson learned about Cloud Run secret mounting
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- README: Update status table with payment flow and beta program
- API.md: Add user auth, credits, and beta tester endpoints
- LESSONS-LEARNED.md: Add gitignore and Firestore transaction insights
- archive: Add session summary for PR #90 work
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Wrap bare URLs in angle brackets in CLAUDE.md (MD034)
- Add language specifiers to fenced code blocks (MD040):
- `text` for directory structures and ASCII diagrams
- `http` for HTTP request examples
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
## Summary
Complete documentation reorganization to make it more effective for AI agents working on this codebase.
## Changes Made
- Consolidated 88 docs into 5 active files + archive
- New structure: README.md, ARCHITECTURE.md, DEVELOPMENT.md, API.md, LESSONS-LEARNED.md
- Added Claude Code slash commands: /docs-review (pre-merge), /docs-maintain (periodic)
- Updated CLAUDE.md with documentation maintenance rules
- Moved all historical docs to docs/archive/ with YYYY-MM-DD prefixes
## New Documentation Structure
```
docs/
├── README.md # Current status + navigation
├── ARCHITECTURE.md # System design
├── DEVELOPMENT.md # Dev setup, testing, deployment
├── API.md # Backend API reference
├── LESSONS-LEARNED.md # Key insights for future agents
└── archive/ # 93 historical docs with date prefixes
```
## Testing
- All 57 backend tests pass
- No code changes, docs-only reorganization
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>