#258 docs(social): optional `posts` depth param on both social scrape endpoints

Summary

Contract PR for recoupable/chat#1836 — merge before the api implementation PR (docs → api).

• POST /api/socials/{id}/scrape: new optional posts query param (integer, 1–100, default 1).
• POST /api/artist/socials/scrape: new optional posts body field (same shape) on ArtistSocialsScrapeRequest.
• Scraper Results (GET /api/apify/runs/{runId}): data example now shows an X tweet item (with likeCount/retweetCount/replyCount/quoteCount/bookmarkCount/viewCount) and a YouTube video item (viewCount/likes/commentsCount) alongside the Instagram profile item, and the description explains the per-platform item shapes.

Semantics documented: posts applies to X/Twitter and YouTube; other platforms ignore it; omitted → legacy single-item profile snapshot (existing behavior unchanged).

Verification

• Both OpenAPI files re-parse (json.load) after the edit; diff is additive (59 insertions / 4 deletions across the two files).
• Field semantics match the planned api implementation exactly (Twitter maxItems, YouTube maxResults/maxResultsShorts).

🤖 Generated with Claude Code

---

Summary by cubic

Adds an optional posts depth to both social scrape endpoints to include recent posts with engagement metrics. X/Twitter returns the latest N timeline items (incl. retweets/replies) and YouTube returns up to N videos + N Shorts; omit to get the legacy single-item profile snapshot; other platforms ignore it.

• New Features

  • POST /api/socials/{id}/scrape: posts query param (integer 1–100).
  • POST /api/artist/socials/scrape: posts body field on ArtistSocialsScrapeRequest (same shape).

• Refactors

  • Removed schema default for posts (use example: 10) and tightened endpoint copy; responses now point to the Scraper Results API and the artist scrape notes a runId per social profile.
  • Expanded examples to include Instagram latestPosts plus X and YouTube items; moved api-reference/artist/socials-scrape into the Social group.

Summary by CodeRabbit

• New Features
  • Added an optional posts setting to social scraping APIs (min: 1, max: 100) to return recent post/video data with engagement metrics on supported platforms.
• Documentation
  • Updated artist socials scrape documentation to clarify scrape-job triggering and per-social runId results behavior.
  • Expanded per-platform posts behavior (X/Twitter, YouTube, Instagram) and documented legacy snapshot behavior when posts is omitted.
  • Refreshed scrape completion response examples and guidance for scraper-type-specific dataset shapes.
  • Moved the artist socials scrape API reference entry in the docs navigation.