docs: [gacha] add hidden Gacha v2 API docs

[tpompon]

Summary

Adds hidden documentation for the Gacha /v2 API: one normalised surface over Collector Crypt, Phygitals and Beezie (pack catalogue, machines, prize inventory, wallet collectibles, marketplace, buyback, rewards, transaction gateway), consumed by Jupiter mobile and web.

Every page is hidden: true and reachable by direct URL only. Nothing is added to docs.json navigation or llms.txt, following the Portfolio v2 precedent (#949). The product is not public yet; un-hiding at launch is frontmatter plus nav.

Content is source-verified against jup-ag/gacha-api @ ac49b04 (docs/openapi.json, which pnpm openapi:sync keeps in sync with the routes, plus the route code for error codes and cache rules).

Changes

• openapi-spec/gacha/gacha.yaml: OpenAPI 3.1 spec with the 32 /v2 operations across 10 tags. Generated from the API repo's spec: /v2 prefix stripped, unused V1* schemas pruned, server set to https://api.raccoons.dev/gacha/v2, security: [], tag descriptions added, three missing operation descriptions filled in, em dashes and American spelling removed.
• api-reference/gacha/*.mdx: 32 endpoint wrappers (Packs, Machines, Inventory, Collections, Marketplace, Buyback, Transactions, Pulls, Users, Rewards), each with title, description, hand-written llmsDescription and hidden: true. sell-asset.mdx carries deprecated: true and a warning pointing to the buyback endpoints.
• gacha/index.mdx: overview, base URL, quickstart curls, endpoint index grouped by area.
• gacha/conventions.mdx: identifiers, both pagination envelopes, sorting, full error-code table (incl. 451 region_restricted, 413, 414), response headers, geo-blocking, cache tiers and stale-on-error behaviour.
• gacha/packs.mdx: curated catalogue vs raw machines feed, unavailableReason, retired packs, live pricing, filtering, categories, capability-based assets.
• gacha/transactions.mdx: build, sign, submit contract with a complete @solana/web3.js TypeScript example, status polling, batch submit, and the purchase/open two-step.
• gacha/platforms.mdx: capability matrix and per-platform notes.
• .claude/rules/product-learning.md: new # Jupiter Gacha API section (sources, undocumented behaviour, conventions, spec quirks, launch to-do).
• .claude/rules/decisions.md: [2026-09-03] Gacha v2 docs added as hidden pages.

Unchanged: docs.json, llms.txt (regenerated, no diff), every existing page.

Linear Issues

None. Skipped by request.

Checklist

• node generate-llms-from-docs.js run; llms.txt unchanged (hidden pages are excluded)
• mint openapi-check openapi-spec/gacha/gacha.yaml passes
• mint broken-links reports zero broken links
• mint validate passes
• Every new page has title, description, llmsDescription and hidden: true
• No em dashes, British spelling, full URLs in every code example
• docs.json not touched; no redirects needed (nothing moved)
• .claude/rules/ updated (product learnings + IA decision)
• Changelog entry in developer-platform: not applicable while hidden. Do it when Gacha launches publicly.

Notes for reviewer

• Base URL is https://api.raccoons.dev/gacha/v2, not api.jup.ag, per Thomas. The style guide's api.jup.ag rule does not apply to this product.
• /v2 prefix assumption: spec paths are written without /v2 (e.g. /machines) because the server URL already carries it, same as the Portfolio v2 spec. This assumes the gateway maps /gacha/v2/<path> onto the service's /v2/<path>. If the gateway forwards the full path instead, the server URL in the spec needs adjusting.
• No API key. The /v2 surface has no securitySchemes; the spec declares security: [] and the pages say so. Money-moving endpoints are geo-blocked (451 region_restricted).
• POST /marketplace/{asset}/sell is documented as deprecated (badge + warning) in favour of POST /buyback/{asset} and POST /buyback.
• Spec is OpenAPI 3.1.0 (Mintlify supports it; openapi-check passes). The tag list, server, security and three missing descriptions are patched in this copy only. Worth a follow-up in gacha-api so future syncs carry them.
• Suggested review order: gacha/index.mdx, then gacha/conventions.mdx, then spot-check a couple of reference pages (get-packs, purchase-machine, submit-transactions) in mint dev.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ScwwAFeU8LkfoJTPKQ5CeA

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Jupiter	🟢 Ready	View Preview	Sep 3, 2026, 11:46 AM

💡 Tip: Enable Automations to automatically generate PRs for you.