fix(core): remove implicit file-promotion + clean dev output + full rebuild on watch

[sinsombat]

Background

This PR follows #131 which fixed a silent 404 caused by a trailing-slash mismatch in generator.ts. While investigating that bug, three related issues were found.

---

Fix 1 — Remove implicit file-promotion in auto-router.ts

Problem

When a folder contains .md files but no index.md, buildAutoNav silently "promotes" the first file (alphabetically by title) to use the folder URL:

// current behaviour
if (!indexExists && nav.length > 0) {
  const firstFile = fileItems[0];
  firstFile._sourceFile = firstFile.path;  // save original
  firstFile.path = basePath;               // overwrite with folder URL
}

This causes two problems:

Silent 404 (root cause of #131): nav link → folder URL, file output → own path, no index.html at folder URL → 404 on click. Fixed in #131, but the root cause was here.

Filename silently dropped from URL (still present after #131 if promotion is kept):

docs/SA/feature-discovery/my-doc.md  →  URL: /SA/feature-discovery/

Instead of the intuitive:

docs/SA/feature-discovery/my-doc.md  →  URL: /SA/feature-discovery/my-doc/

This creates inconsistent URL behaviour:

• Files in folders with index.md → URL includes filename ✓
• Files in folders without index.md → URL drops filename ✗

It also makes same-named files in sibling folders indistinguishable by URL.

Fix

Remove the promotion block. Every .md file always keeps its own filename in the URL.

Before:

nav link → /SA/feature-discovery
output   → site/SA/feature-discovery/index.html

After:

nav link → /SA/feature-discovery/my-doc/
output   → site/SA/feature-discovery/my-doc/index.html

Folders without index.md become collapsible section headers (no link) rather than having the first child silently represent the section.

Migration: add an index.md to any folder that should have its own landing page.

---

Fix 2 — Clean output dir before initial dev build

Problem

buildSite used fs.ensureDir (mkdir -p) which never removes existing files. After any change to auto-router behaviour (e.g. applying this PR), old HTML files built under the previous URL structure remain in site/. The new nav links point to the new URLs but the old files still exist at old paths — and the new files may not yet — causing 404 on nav click.

Fix

Call fs.remove(rootOutputDir) before the initial dev build so every docmd dev session starts from a clean slate.

---

Fix 3 — Full rebuild on file watch (nav goes stale with targeted rebuild)

Problem

The file watcher called buildSite with targetFiles: [filePath], regenerating only the modified page. Every other page kept its old nav HTML. Adding a new .md file while the dev server is running means the link to that new file never appears in the sidebar of existing pages — the new page is accessible by direct URL but invisible in navigation.

Fix

Remove targetFiles from the watcher rebuild so every watched change triggers a full rebuild. For typical documentation projects (~20–50 pages) a full rebuild takes ~200–300 ms — imperceptible in practice.

---

Note on _sourceFile / navDesignatedIndexFiles

With Fix 1, _sourceFile is never set on nav items, so the navDesignatedIndexFiles logic in generator.ts becomes a no-op. The code is left in place (harmless) as it may be useful for future features.

[mgks]

Tested with new workspace changes and playground. Everything works smoothly and feels robust. Great job!

Thank you for the contribution.