fix(cli): detect changelog overview pages beyond reserved filenames

[emjoseph]

Description

Fixes a changelog URL slug divergence between V2 and ledger rendering. Sites with changelog overview pages that use non-standard filenames (anything other than summary.mdx, index.mdx, or overview.mdx) produce incorrect navigation slugs in the V1 tree, which then propagate through the ledger pipeline.

Example: A changelog with an overview file named release-notes.mdx containing frontmatter slug: release-notes renders as /docs/release-notes in V2 but /docs/changelog/connect in the ledger.

Root Cause

ChangelogNodeConverter.toChangelogNode() scans changelog directory files and classifies each as either:

1. Date file (matches YYYY-MM-DD pattern) → changelog entry
2. Reserved-name file (summary, index, overview) → overview page
3. Anything else → silently skipped

When no reserved-name file exists, overviewPageId stays undefined and the node's slug falls through to the raw config slug (opts.slug ?? kebabCase(title)), ignoring any frontmatter slug: override on the non-reserved overview file.

The V2 reader compensates via fullSlugMap applied at read time from page markdown (NavigationConfigConverter → ChangelogNavigationConverter). The ledger pipeline has no equivalent — it trusts the V1 tree's slug as-is. So the V1 tree arriving with the wrong slug produces wrong sectionPath in the ledger segment, wrong nav routes, and the URL divergence.

Changes Made

• Modified ChangelogNodeConverter.toChangelogNode() to track the first non-date, non-reserved file as a fallback overview candidate
• When no reserved-name overview is found, the fallback is promoted to overviewPagePath
• This allows the file's frontmatter slug: override to propagate via markdownToFullSlug → opts.parentSlug.apply({ fullSlug: ... }), and correctly sets overviewPageId on the resulting ChangelogNode
• Reserved-name files still take priority (no behavior change for existing changelogs)

V2 ↔ V1 Tree fullSlugMap Parity Analysis

Traced every place V2 uses fullSlugMap at read time and compared it against how the CLI's V1 tree builder (DocsDefinitionResolver) uses markdownFilesToFullSlugs at build time. The changelog overview was the only gap:

Node type	V2 (read time)	CLI V1 tree (build time)	Parity?
Regular pages	NavigationConfigConverter:330	DocsDefinitionResolver:2033	✅
Sections with overview	NavigationConfigConverter:330	DocsDefinitionResolver:2071-2091	✅
Landing pages	N/A	DocsDefinitionResolver:1078	✅
API reference overview	ApiReferenceNavigationConverter:76	ApiReferenceNodeConverter:94	✅
API subpackages	ApiReferenceNavigationConverter:495	ApiReferenceNodeConverter:321,363,443	✅
Changelog overview	ChangelogConverter:40	ChangelogNodeConverter — only matched reserved filenames	❌ → fixed here

This means the CLI fix fully closes the V2 ↔ ledger slug parity gap. No FDR/docs-server changes are needed — the existing transform and read path work correctly once the V1 tree carries the right overviewPageId and slug.

Testing

• All 44 existing @fern-api/docs-resolver tests pass
• No compile errors in changed file (pre-existing integrations type errors in mapDocsConfigToLedgerConfig.ts / buildLedgerInput.test.ts on base branch are unrelated — the published @fern-api/fdr-sdk doesn't yet include integrations on LedgerConfigSchema)
• Lint and format checks pass

Link to Devin session: https://app.devin.ai/sessions/ec72b39820204a31be764cd3d1e8f654
Requested by: @emjoseph

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.