[rossrdme]

Summary

• The category-page pass in syncOneOas created <info.title>/<tag>/index.md (plus _order.yaml entries) for every tag in the spec, without checking whether any of that tag's operations would actually live in that folder.
• When a reference has been reorganized, that produced one empty, childless category page per tag on every sync. This covers tag folders moved into hand-made categories (e.g. several specs grouped under Applications/) and folders spelled differently from the CLI's slug (e.g. a platform-created site-api-v10 vs. the CLI's site-api-v1-0 for tag Site API v1.0). Endpoint pages were matched correctly by api.file + operationId, so only these empty parents were added, and lint then flagged each one as Empty page: non-hidden page has no content.
• Reproduced against a real customer docs repo: on a tree lint considered clean (no reference issues), oas:sync reported 29 added, 0 deleted, and every addition was an empty index.md.
• Fix: before the category-page pass, compute which tag folders will hold at least one of the spec's pages this run. That's the case when a new page will be created there, an existing page already lives there (keeps the existing backfill behavior), or apply-tag-changes will move one in. A tag with none of those, and no existing index.md, is skipped entirely: no category page, no category folder, no _order.yaml entries.

Test plan

• npm test: 225/225 passing
• Added regression tests: all of a tag's pages in another category (nothing created, root _order.yaml untouched); pages in a differently spelled folder in the same category (no -v1-0 duplicate); the same "pages elsewhere" case with apply-tag-changes (still nothing created); and a tag with pages elsewhere plus a brand-new operation (folder + index.md still created). The first three fail without the fix.
• Ran the patched CLI against the customer repo: Reference pages are already in sync., no file changes, and lint shows no new warnings
• Ran the patched CLI against a fresh project whose specs were uploaded via the UI: still already in sync, no changes
• Rebuilt dist-gha/ with npm run build:gha

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable new bugs remain.

_{Reviews (2) · Last reviewed commit: "fix(oas:sync): restore a tag landing pag..." · Reviewed by Greptile}

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[rossrdme]

@erunion after some testing, I think your PR changes are good. I think there is a bug with the lint function where it sometimes flags empty index.md files which are valid in the fs, but at least now we're not creating a ton of them incorrectly.