How to organize a large OpenAPI spec: multi-file structure, $ref rules, and CI checks

Every OpenAPI document starts as one clean file. Then it reaches forty operations and the file is 2,000 lines, then a hundred operations and pull requests conflict on every merge, then nobody edits it without a full afternoon of context. The standard advice is "split it with $ref," which is true and unhelpful — split how, along which boundaries, and what breaks in tooling when you do? This is the layout and rule set that survives 200+ operation APIs. Organize by artifact kind first, domain second.