feat: add Flowxtra board-wide jobs provider, debug CLI, and MCP tools

[9mtm]

Adds Flowxtra (https://flowxtra.com) as a job-board provider, built following .agents/skills/integrate-new-provider/SKILL.md end to end (recon → fixtures → ogen client → provider package → debug CLI → MCP surface → docs).

Why dedicated tools, not an ats.Adapter

Flowxtra is a multi-tenant ATS, but its public central endpoint (GET https://app.flowxtra.com/api/central/jobs) is one cross-tenant, board-wide feed — no per-company slug or board to roster, no token, no auth. Per the SKILL.md surface-choice rule that makes it structurally like Indeed/LinkedIn/104, so it ships as flowxtra_search_jobs / flowxtra_get_job_detail dedicated tools rather than an ats.Adapter.

Surface notes (all verified against live captures, 2026-07-26)

• Search narrowing is real and server-side: search-key (title), location (city/state/country), company_name, workplace (exact On-site/Hybrid/Remote) all reduce total. Nullability in openapi.yaml was swept across every row live at capture time (116 jobs), not guessed.
• The upstream employment_type parameter is a live no-op (the backing column stores objects, the filter compares strings — every value returns zero rows), so it is deliberately unmodeled, with the deviation documented in openapi.yaml remotive-style.
• Detail (GET /api/candidate/jobs/{has_id}) 404s cleanly with a JSON envelope for unknown ids; date_share serializes as null on detail (posted-at comes from the list); list rows carry a flowxtra.com/apply/… URL while detail carries the company's own career-page apply URL.

What's included

• internal/provider/flowxtra — minimal openapi.yaml + ogen client, 4 captured hurl fixtures, mock server, client tests
• cmd/flowxtra — ff/v4 debug CLI (search, detail)
• internal/openingsmcp/flowxtra.go — the two tools + E2E tests (mock-backed in-memory MCP sessions), wired into cmd/openings-mcp with serverInstructions mentions
• README job-board list + Makefile OPENAPI_SPECS entry

Verification

• go test ./... — all packages green
• hurlfmt --check clean; hurl --test replays all 4 fixtures against the live API successfully
• Live stdio smoke per SKILL.md step 6: initialize → tools/call flowxtra_search_jobs (query=sales, workplace=Remote → 4 live listings with formatted salaries) → tools/call flowxtra_get_job_detail (full plain-text description + career-page apply URL), both isError: false
• make validate-openapi not run locally (no docker on this machine) — relying on CI

Disclosure: I work at Flowxtra. The endpoint is public and unauthenticated; this integration is read-only search/detail like every other provider, no apply flow.

[amikai]

@9mtm Want to merge this. One thing first, internal/openingsmcp/flowxtra.go:219:

Search live jobs across every company hosted on the Flowxtra ATS platform (board-wide, all narrowing server-side).

That describes the endpoint. A description should tell a client when to pick the tool. The other providers name a market: 104 "Taiwan's largest job board", Jobindex "(Denmark job board)", Mynavi "a major Japanese job board for mid-career hires. Listings are in Japanese."

Flowxtra isn't the largest board in any single market, so a client can't route on the name. It skips the tool, or fires on unrelated queries and burns user tokens on rows that miss. Your server eats the request either way.

Pulling the board today (per_page=200, one page): 116 jobs / 32 companies, US 78, FR 13, NL 7, with one US healthcare staffing agency posting 58 of them. "Europe-leaning" in serverInstructions doesn't hold either.

I'd rather you write that line than me. Name what Flowxtra covers, so a client fires the tool on questions it can answer and skips the rest. If the snapshot above misses where you're headed, write to that instead.

Longer term: a per-company endpoint keyed by slug or career domain would put Flowxtra behind search_jobs_by_company next to Greenhouse and Lever. Then the routing problem above goes away. A user names a company and gets its postings without knowing which ATS hosts it, and no client has to judge whether a question belongs to Flowxtra. Every tenant you host becomes reachable, instead of whoever matches a board-wide query.

[amikai]

Rename this to job_id on the outward-facing MCP schema. Two reasons.

has_* reads as a boolean prefix. A client meeting has_id can parse it as "does this have an id" rather than as a value to carry into the next call.

Eight providers here already use job_id, including mynavi_get_job_detail, whose ids look like 348855-1-29-1. The three that don't (path, job_code, job_key) each carry a term the caller meets elsewhere. This one carries upstream's misspelling of hash_id.

Suggested change

	HasID string `json:"has_id" jsonschema:"Public hashed job id; pass to flowxtra_get_job_detail's has_id param."`
	URL string `json:"url" jsonschema:"Public apply URL for the posting."`
	}
	type flowxtraDetailInput struct {
	HasID string `json:"has_id" jsonschema:"Public hashed job id (has_id from flowxtra_search_jobs results, e.g. M88PB)."`
	JobID string `json:"job_id" jsonschema:"Public job id; pass to flowxtra_get_job_detail's job_id param."`
	URL string `json:"url" jsonschema:"Public apply URL for the posting."`
	}
	type flowxtraDetailInput struct {
	JobID string `json:"job_id" jsonschema:"Public job id (job_id from flowxtra_search_jobs results, e.g. M88PB)."`

Keep has_id in the provider package and openapi.yaml. That layer should stay faithful to the wire. Line 173, the tool description on 236, and the error string on 240 need the same rename.

[9mtm]

Thanks for the review — both make sense. Pushed:

• Removed the server-side / client-side / board-wide mechanism from the tool and parameter descriptions; they now say what to search, not how it runs. Point taken on the linkedin_search_jobs rate-limiting bar — mechanism only when the client must act on it.
• Renamed the outward id has_id → job_id on the MCP schema (search output + detail input, the tool description, and the error string), matching the eight other providers. Kept has_id in the provider package and openapi.yaml so that layer stays faithful to the wire.

go build + go test ./... green.