[davior]

Summary

GAM's half of M3a (gecko-suite#5 is the suite's): SA-3 in the suite's plan. Depends on that PR being merged and deployed first. Merging this changes nothing until AI_BACKEND=suite, which is already how enrichment and the assistant are switched.

With AI_BACKEND=suite, a generation's fal.ai requests go to the suite's media jobs instead of to fal with a key from Settings.

• generation/backend.py is the seam. run.py needs submit, status, result and cancel of fal, and the bill; it now gets them from fal directly (local, as always) or from the suite. The job itself (request body, downloads, saving, provenance, resumption) is unchanged.
• The job persists the suite's job id, never fal's URLs, so a restart resumes by id and this app never holds an address the key is sent to. A restart under either mode follows a job by whichever kind of handle it wrote.
• GAM writes no usage row for a suite generation: the suite recorded the cost (fal's billed quantity times fal's own price) under GAM and the asset, and a second row would count it twice.
• A suite that is briefly down doesn't abandon a running generation. A failed status check is asked again until GAM's own deadline, as a fal 5xx already was. A suite that is down at submit fails the job with a sentence and nothing is billed.
• The model catalogue and request builder stay here. Each endpoint's request format is GAM's until the suite takes the catalogue over.
• Settings points at the suite's providers instead of asking for a fal key that nothing would read. The key precheck on /api/generate is skipped in suite mode: the suite says so in the activity feed if it has no fal key.
• requirements.txt pins gecko-suite-client to the suite PR's commit (the one with SuiteMedia). I'll re-pin to main once that merges.

Test plan

• cd backend && pytest -q: 1528 passed (9 new for suite mode: a generation end to end with no GAM key and no GAM usage row, the queue and the suite blinking, a failed run, the suite's own sentence reaching the activity feed, the suite down at submit, resuming by job id without submitting again, cancelling at the suite, handle round trips, and local mode unchanged).
• cd frontend && npm run format:check && npm run lint && npm test && npm run build: 472 tests passed.
• CI green, including the Docker image build.
• A real generation against a real suite and fal. Not run here: everything is against fakes.

Deployment

Merging and redeploying changes nothing for users until AI_BACKEND=suite.

1. Before pulling: gecko-suite#5 must be merged and deployed (its frontend is rebuilt too: it raises the upload limit for media jobs), and the suite needs a fal.ai provider with a key (check Providers; the importer brought across any fal key from GAM or Notes settings).
2. Configuration: nothing new. AI_BACKEND=suite and SUITE_APP_SECRET are already set if enrichment is on the suite.
3. Deploy: rebuilds the backend and the frontend; the server needs outbound access to github.com for the client:

   git pull origin main

   docker compose up --build -d

   docker compose ps

   curl -f http://localhost:${APP_PORT}/api/health

4. Migrations: none.
5. Other apps: GVC generates through GAM, so nothing changes there.
6. Verify: with AI_BACKEND=suite, Settings shows "uses the fal.ai key kept in Gecko Suite". Generate an image: it appears in the library, and the suite's Usage has an image row under GAM with the asset as its subject. GAM's own Usage panel will not show it, because the suite counts it.
7. Roll back: set AI_BACKEND=local and docker compose up -d; the fal key in Settings is still there. A generation running at that moment fails and can be retried.

---

---

Generated by Claude Code