Publish Role

Put a role on the board. Requires the company page to be public already.

Why the company has to be public first

A role links back to its company for everything a candidate needs in order to decide whether to apply -- who they are, what they do, where they are, how to reach them. If the company page is private, GET /api/public/companies/{handle} 404s, the board's join excludes the role anyway, and the "role_url" in every payload points at a page nobody can load. Publishing into that state would report success and produce nothing: an opening that is live, unreachable, and invisible.

So it is a 422 with a sentence naming the fix, rather than a silent success or a cascade that publishes the company page on the user's behalf. Publishing a company page is a consent decision (see models.Company.is_public) and it is not this endpoint's to make.

Idempotent, and the timestamp is written once

Publishing an already-open role is a 200 and changes nothing. published_at is stamped only if it is null, so a role that was open, closed, and reopened keeps its ORIGINAL publication date -- which is the fact that matters, both for the board's ordering and for anyone asking how long this opening has been around. closed_at is cleared on the way back to open, because a role that is open now is not closed and leaving a stale timestamp would make the payload say both.