feat: support markdown file as category cover

[julia-rabello]

EDU-17534

Adds support for using a markdown file as the cover of a category in the navigation, instead of generating a generic index.

Behavior

Category cover logic is structure-driven and applies automatically based on folder contents:

Folder contents	categoryCover frontmatter	Result
Single .md + subfolders	any	Cover applied automatically
Single .md, no subfolders	any	Flattened to plain markdown node (no category wrapper)
Multiple .md + subfolders	none	Regular type: "category" (no change)
Multiple .md + subfolders	true on one file	That file becomes the cover
Multiple .md + subfolders	true on more than one file	Warning logged, falls back to regular category

When a cover is applied, the category node gets type: "markdown" and its name/slug are taken from the cover file. Subcategories remain in children.

Changes

• transformer.ts: cover and degenerate-category logic in buildNavigationNode; markdown nodes preserved through mergeCategoryNodeLists
• types.ts: categoryCover?: boolean added to FrontMatter
• navigation.schema.json: markdown nodes can now have non-empty children (cover-backed categories)
• readme.md: new "Category cover pages" section

[julia-rabello]

Test results

Added run-cover-tests.mjs to the branch. To run: node run-cover-tests.mjs

Results: 7/7 passed

#	Scenario	Result
1	Single .md + subfolders → auto cover	✅
2	Single .md, no subfolders → flattened to plain markdown	✅
3	Multiple .md + subfolders, no categoryCover → regular category	✅
4	Multiple .md + subfolders, one categoryCover: true → that file becomes cover	✅
5	Multiple categoryCover: true → warning logged, fallback to regular category	✅
6	EN/PT/ES variants of same slugEN count as one file	✅
7	Cover-backed node with children survives pruning	✅

What the tests check

Each test calls buildNavigationNode directly with minimal fake inputs and inspects the output node. Key things verified per case:

• Case 1: type === "markdown", slug.en matches the cover file, children is non-empty
• Case 2: type === "markdown", no children (no category wrapper)
• Case 3: type === "category" (folder-derived name/slug unchanged)
• Case 4: type === "markdown", slug.en === "overview", "getting-started" still in children
• Case 5: type === "category", warning includes "Multiple files with categoryCover: true" and lists both conflicting slugs
• Case 6: Three locale variants of the same slugEN dedup to one logical file → auto cover fires
• Case 7: Node is not dropped by the empty-children cleanup step

Subcategories must contain at least one file, the tool prunes empty folders before the cover logic runs. Empty subcategory stubs silently make hasSubcats = false and send the function down the wrong path. The test helpers account for this via makeSubcat(), which always includes a file.