fix(openapi): document /v1/opportunities/find + /v1/issue-rag/retrieve

[hurryup52]

Closes #9310

(Fourth attempt — #9423, #9428, and #9439 were each auto-closed by the gate for a base-branch conflict in the generated apps/loopover-ui/public/openapi.json / test/unit/openapi.test.ts. This part of the spec is being actively documented by several parallel PRs for other issues landing in quick succession, each touching the same generated file and shared test assertions. This PR is rebased onto the current main tip with all conflicts resolved; no content changes from the prior attempts.)

What

/v1/opportunities/find (OPPORTUNITIES_FIND_PATH, backing the loopover_find_opportunities MCP tool) and /v1/issue-rag/retrieve (ISSUE_RAG_RETRIEVE_PATH, backing loopover_retrieve_issue_context) are fully implemented and access-gated in src/api/routes.ts, but were never registered with the OpenAPI generator — grep for opportunities/find/issue-rag in src/openapi/spec.ts previously returned nothing, so neither route appeared in GET /openapi.json or the committed apps/loopover-ui/public/openapi.json.

Changes

• src/openapi/schemas.ts: added FindOpportunitiesRequestSchema/FindOpportunitiesResponseSchema and IssueRagRetrieveRequestSchema/IssueRagRetrieveResponseSchema. Field shapes mirror the MCP tools' own Zod shapes verbatim (findOpportunitiesShape/findOpportunitiesOutputSchema and issueRagShape/issueRagOutputSchema in src/mcp/server.ts) so the contract can't silently drift from what the tools actually validate — reused the same MAX_FIND_OPPORTUNITIES_*/MAX_ISSUE_RAG_*/PREFLIGHT_LIMITS constants those shapes already use.
• src/openapi/spec.ts: registered both response schemas as named components (FindOpportunitiesResponse, IssueRagRetrieveResponse) and added two registerPath POST entries, following the same pattern used for GET /v1/repos/{owner}/{repo}/gate-config/effective (OpenAPI spec is missing GET /v1/repos/{owner}/{repo}/gate-config/effective (documented sibling: live-gate-thresholds) #6611) and the existing POST-with-body routes (e.g. the incident-reports pair). Response codes (400/401/403) are matched to each route handler's actual behavior in routes.ts.
• apps/loopover-ui/public/openapi.json: regenerated via npm run ui:openapi and committed. npm run ui:openapi:check passes.
• test/unit/openapi.test.ts: added assertions that both paths are defined, that both response schema components are registered, and that their fields (aiPolicyAllowed, retrievedPathCount) match the MCP output shapes — a regression guard against future drift between the two.

Verification

• npx vitest run test/unit/openapi.test.ts — 8/8 pass (merges cleanly alongside the other recently-landed OpenAPI-documentation tests in this file).
• npm run ui:openapi:check — passes.
• npm run typecheck — clean.
• Rebased directly onto current main tip immediately before opening this PR.

[loopover-orb]

Important

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏳ LoopOver is waiting…

LoopOver has seen this pull request and is waiting on CI checks to finish before reviewing it. This comment will update once the review runs.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed · 🟨 Waiting}

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.

[JSONbored]

Merge conflicts, closing.

This branch has conflicts that must be resolved
Use the [web editor](https://github.com/JSONbored/loopover/pull/9444/conflicts) or the command line to resolve conflicts before continuing.

apps/loopover-ui/public/openapi.json

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.69%. Comparing base (2e4388d) to head (d09ab64).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #9444       +/-   ##
===========================================
- Coverage   89.54%   75.69%   -13.86%     
===========================================
  Files         843      277      -566     
  Lines      110017    58470    -51547     
  Branches    26184     8206    -17978     
===========================================
- Hits        98517    44257    -54260     
- Misses      10238    13942     +3704     
+ Partials     1262      271      -991     

Flag	Coverage Δ
backend	99.77% <100.00%> (+4.51%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/openapi/schemas.ts	100.00% <100.00%> (ø)
src/openapi/spec.ts	99.62% <100.00%> (+<0.01%)	⬆️

... and 704 files with indirect coverage changes