Attach an uploaded image to a brand kit (ENG-2466).

Multipart-upload flow: the caller first POST /v1/uploads their file and receives a file_* id (the response's id field), then calls this endpoint with that id as file_id to associate the image with the brand kit (logo / reference / asset). A bare UUID is also accepted for back-compat with older integrations.

Returns 404 not_found if the brand kit does not exist, has been deleted, or the caller lacks team access — collapsed like the sibling endpoints so the write path does not leak existence of brand kits in other teams. An unusable file_id (missing, deleted, or outside the kit's team) is a 400.

The attach is idempotent (ENG-3043): re-posting a file_id already on the kit returns 201 with the brand kit unchanged rather than adding a second image, so retries and full re-syncs are safe. Dedupe is per storage bucket, and reference and asset share one bucket — re-attaching a reference image as an asset succeeds without recording the new role. Re-posting the same role with a different label relabels the existing image in place (ENG-5988) and returns 201: the ref keeps its id, notes and position, and no second image is added. The role has to match because the scan is bucket-scoped: re-posting under the other bucket's role finds nothing to relabel and appends instead. role is required here, so a caller always states one — the transports that default it carry a louder warning. It was a 400 until then, on the reasoning that the no-op path could not carry a new label without writing and that returning success over a dropped one would be undetectable — both true, and both answered by writing the label instead of dropping it.

{
  "file_id": "file_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "role": "logo",
  "label": "Dark mode logo"
}