docs(openapi): document contributor watches GET/POST/DELETE routes (#9306)

[RealDiligent]

Problem

Closes #9306.

/v1/contributors/:login/watches is live across all three verbs (GET=list, POST=watch, DELETE=unwatch) as the REST mirror of the loopover_watch_issues MCP tool — whose action enum splits across the verbs — but no verb appears in src/openapi/spec.ts.

Fix

Mirrors the neighboring /v1/contributors/{login}/notifications routes:

1. src/openapi/schemas.ts: ContributorWatchesResponseSchema (field-level parity with watchIssuesOutputSchema) + ContributorWatchRequestSchema (the POST/DELETE body, mirroring watchSubscriptionBodySchema: repoFullName + optional labels).
2. src/openapi/spec.ts: registry.register both, then registerPath all three verbs (GET / POST / DELETE) for the path (login param; POST/DELETE carry the body + 400).
3. Regenerated + committed apps/loopover-ui/public/openapi.json; npm run ui:openapi:check enforces it.

test/unit/openapi.test.ts passes; 100% patch coverage on the new schemas.ts/spec.ts lines.

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-27 19:38:04 UTC}

3 files · 1 AI reviewer · no blockers · CI green · dirty

⏸️ Suggested Action - Manual Review

Review summary
This is a straightforward, mechanical OpenAPI documentation PR that adds `ContributorWatchesResponseSchema`/`ContributorWatchRequestSchema` and registers GET/POST/DELETE paths for the already-live `/v1/contributors/{login}/watches` route, closing #9306. The change follows the exact same registration pattern used for the neighboring `/notifications` routes in the same file, and the regenerated `openapi.json` diff is consistent with the new `spec.ts`/`schemas.ts` additions. It's a pure documentation/schema-registration change with no runtime route logic touched, so risk is low.

Nits — 6 non-blocking

• The actual route handler (src/api/routes.ts) implementing `/v1/contributors/{login}/watches` isn't part of this diff, so field-level parity between `ContributorWatchesResponseSchema`/`ContributorWatchRequestSchema` and the real runtime response/request shapes can't be verified from what's shown here — worth a maintainer spot-check against `watchIssuesOutputSchema`/`watchSubscriptionBodySchema` before merge.
• No new test-path changes accompany the two new source files (src/openapi/schemas.ts, src/openapi/spec.ts), relying entirely on the existing `test/unit/openapi.test.ts` + `ui:openapi:check` snapshot mechanism to catch drift, consistent with how the sibling `/notifications` routes were documented.
• spec.ts:1392+/1409+/1427+ repeat the same `200`/`400` response-status literals used throughout the file for every other route — consistent with existing convention, not worth changing.
• Confirm `ContributorWatchRequestSchema`'s `labels` field being marked optional matches the DELETE handler actually ignoring/accepting it, per the PR description's own claim.
• If a future PR adds more contributor self-service verbs, consider extracting a shared `login` path-param schema (`z.object({ login: z.string() })`) since it's now duplicated three times in spec.ts for this one path.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#9306
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 267 registered-repo PR(s), 113 merged, 36 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 267 PR(s), 36 issue(s).
Improvement	ℹ️ None detected	risk: low · value: none · LLM: minor

Linked issue satisfaction

Partially addressed
The PR adds ContributorWatchesResponseSchema/ContributorWatchRequestSchema, registers all three verbs for /v1/contributors/{login}/watches in spec.ts, and regenerates openapi.json, closely mirroring the notifications pattern as required. However, the issue explicitly requires a new regression test asserting all three verbs appear in buildOpenApiSpec()'s output with response schema keys matching wa

Review context

• Author: RealDiligent
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, Ruby, TypeScript, Svelte, Cuda, JavaScript, Markdown, MDX
• Official Gittensor activity: 267 PR(s), 36 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop	before /	after /	—
/	mobile	before / (mobile)	after / (mobile)	—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

Scroll preview

Route	Before (production)	After (this PR's preview)
/	before / (scroll)	after / (scroll)

A short scroll-through clip (desktop) — click either thumbnail to open the full animation. Evidence for scroll-linked behavior a single screenshot can't show.

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

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[superagent-security]

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

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9453      +/-   ##
==========================================
+ Coverage   75.51%   75.69%   +0.18%     
==========================================
  Files         275      277       +2     
  Lines       58032    58479     +447     
  Branches     6209     6216       +7     
==========================================
+ Hits        43820    44266     +446     
  Misses      13942    13942              
- Partials      270      271       +1     

Flag	Coverage Δ
backend	99.77% <100.00%> (?)

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.63% <100.00%> (ø)

[loopover-orb]

LoopOver is closing this pull request on the maintainer's behalf (conflicts with the base branch — resolve and open a fresh PR). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.