fix(pipeline): resolve nav entries to real files before reading or writing them

[shirgoldbird]

Summary

Follow-up to #449, which surfaced this in #447's body:

Generation errors: 1
  - [Errno 21] Is a directory: .../docs/resources/breaking-changes-change-notices

A gap's path is a docs.json nav entry. Nav entries carry no file extension, and a page can share its name with the directory holding its children — docs/resources/breaking-changes-change-notices is both a page (.mdx) and the folder its notices live in. generate.py used those values as filesystem paths.

That one mistake broke every page-editing gap in three ways:

1. The crash. open() got the directory and raised [Errno 21] Is a directory.
2. Silent content loss. Otherwise load_file() swallowed FileNotFoundError and returned "", so the model was told to expand a page whose current content was empty and wrote a replacement from scratch. The real content would have been discarded.
3. The page never shipped. The output path had no extension, so the draft was named docs--a--b and promote.py — which collects only *.mdx — dropped it without a word. This is why docs: pipeline-generated pages (?, Languages, Voice) #447 reports an expanded cookbook/google-sheets that isn't in its diff.

So thin_page, missing_code_examples and missing_description have never produced a shipped page. Symptom 2 is the one worth noting: it never landed only because symptom 3 kept it from shipping.

What changed

• detect_gaps.page_file() is now the single way to turn a nav entry into a file. It uses is_file(), so a directory can never masquerade as the page, and it replaces two copies of the extension-guessing loop.
• generate.load_existing_page() raises rather than returning nothing, so a failed read can't become "write this page from scratch". It also rejects an empty page.
• determine_output_path() and apply_description() resolve through page_file(), so drafts keep their .mdx and promote picks them up. This also fixes open-PR path matching for these gaps, since PR file lists carry extensions.

Hub pages are no longer flagged as thin

breaking-changes-change-notices is short because its content is on its child pages. Padding it out is the wrong fix, so pages with children are exempt from the thin-page check. After this, the only thin_page gap in the repo is the genuine one:

thin_page: docs/learning-how-tos/cookbook/google-sheets has under 100 words
  -> docs/learning-how-tos/cookbook/google-sheets.mdx      # was: ...google-sheets

Lazy SDK import

generate.py imports anthropic at call time instead of at import. Gap detection, --dry-run and the tests no longer need the SDK, so the CI test job installs only pyyaml.

Verification

Against the two real pages, before → after:

	Before	After
breaking-changes-change-notices	[Errno 21] Is a directory	not flagged (it's a hub)
cookbook/google-sheets	empty source, extensionless draft, dropped at promote	reads the real page, writes google-sheets.mdx

New pipeline/test_gap_paths.py — 17 tests against a temp docs tree, including the directory-collision regression and "a name prefix is not a child" (notices-and-more must not count as a child of notices). 41 tests total in pipeline/.

Not addressed: whether a 40-word cookbook page should be expanded by the pipeline at all is a judgment call, and stays with the reviewer.

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated
deepl-c950b784	🟢 Ready	View Preview	Sep 22, 2026, 4:32 PM

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