# MD vs HTML Audit — 2026-05-12

## Question
Sam reported "kept clicking to MD files instead of the HTML visit doc" when looking for Peter Scott prep. Investigate whether duplicate `.md` and `.html` files for the same content cause navigation confusion.

## Findings

### Basename-collision audit
Cross-checked `customer-jobs/` and `personal/` for files where the same basename exists as both `.md` and `.html`:

**Result: ZERO actual duplicates.** No file like `intake.md` and `intake.html` in the same folder.

### What Sam actually experienced

The "clicking to MD files first" issue is NOT duplication — it's **discovery order**. When Sam landed in `/customer-jobs/peter-scott-shed-2026-05/` (the folder root, before today's index.html existed), Cloudflare Pages showed a directory listing alphabetically:

```
2026-05-12-visit.html  ← the one he wanted (the HTML visit sheet)
appointment-prep.md
intake.md
```

The `.html` was first alphabetically, but Sam may have clicked into other files looking for the right one because there was no "this is the canonical doc" signal.

### Fix shipped today

1. **Customer folder index.html** added for each customer with active jobs:
   - `/customer-jobs/peter-scott-shed-2026-05/index.html`
   - `/customer-jobs/aceves-home-fence-2026-04/index.html`
2. **Each customer index lists docs with pill labels**:
   - 🟢 CANONICAL — the mobile-friendly HTML view
   - 🔵 NOTES — markdown working notes (intake, research, prep)
3. **Master customer directory** at `/customer-jobs/index.html` lists all customers with linked active jobs.

### Conventions going forward

| File type | Purpose | When to create |
|---|---|---|
| `index.html` in customer folder | Job hub / mobile entry point | Always (canonical) |
| `intake.md` | Initial customer notes | Customer onboarding |
| `appointment-prep.md` | Pre-visit prep | Before visit |
| `{date}-visit.html` | Mobile-friendly post-visit doc | After each visit |
| `condition-assessment.md` | Site survey notes | If detailed assessment needed |
| `quote-draft.md` | Quote working text | Before formal quote in manage app |
| `materials-research.md` | Product research | If complex materials decision |

**Rule:** When in doubt between `.md` and `.html`, prefer:
- `.html` for anything Sam will view on his phone in the field
- `.md` for working notes during research / planning sessions

If a `.md` doc becomes the operational doc (e.g., Sam refers to it on his phone), promote it to `.html` with breadcrumb nav.

### MD files SAFE to stay as .md

After today's hub additions, these MD files still exist but are now linked from their customer's index.html with clear "NOTES" labeling — no navigation friction:

- `customer-jobs/aceves-home-fence-2026-04/intake.md`, `condition-assessment.md`, `materials-research.md`, `quote-draft.md`, `tools-inventory.md`
- `customer-jobs/peter-scott-shed-2026-05/intake.md`, `appointment-prep.md`
- `handoff-blocks/*.md` (system files, not customer-facing)

### Recommended actions
- ✅ Fix shipped — customer indexes + breadcrumb nav
- 🟡 Consider: promote `aceves-home-fence-2026-04/quote-draft.md` to `.html` if Sam still actively references it (currently superseded by the Aceves paint handoff)
- 🟡 Consider: tools-inventory.md duplicates `/personal/tools/inventory.md` — could be deleted or cross-linked

## Net result

Navigation friction fixed without deletions. All previous MD files preserved as searchable notes; HTML files clearly labeled as canonical entry points.