# ADR 002: Versioned Filenames + Stable `latest.html` Alias **Status:** Accepted **Date:** 2026-04-26 **Decision-makers:** Sam, Claude Code (during repo provisioning) --- ## Context Equipment service guides are versioned HTML files (`lt180-service-guide-v3.html`). The version is part of the filename, not just git history, because: - Guides cite their own prior versions by name (the v3 errata block calls out what v1 and v2 got wrong; that reference would be unresolvable if old versions were overwritten) - A field user reading a guide may want to consult an earlier version to understand what they may have already done based on the prior info - The errata format from METHODOLOGY.md depends on prior versions remaining retrievable as standalone documents But: external systems (the /manage app's eventual Equipment tab, links in chat sessions, QR codes on equipment) need *one* stable URL per equipment that resolves to whatever the current guide is, without manual link-rot maintenance every time a new version ships. --- ## Decision Each equipment folder under `guides//` contains: 1. **One file per version**: `-service-guide-v.html` — never deleted, never overwritten. These are the canonical artifacts. 2. **One stable alias**: `latest.html` — an HTML meta-refresh redirect pointing to the current version's filename. Updated each time a new version is added. External systems link to `latest.html`. Browsing the folder shows the version history. --- ## Why meta-refresh, not symlink or `_redirects` - **Symlinks** behave inconsistently across Windows / git / Cloudflare Pages. - **Cloudflare `_redirects`** at the deploy root would work for the deployed site but breaks when Sam opens the file directly from a local clone (file://) — and offline access from the local clone is a primary use case (field service notes on a phone with no signal). - **Meta-refresh HTML** works in both contexts: served by Pages, opened locally, opened from a USB stick. The trade-off is a tiny visible flash on redirect, which is acceptable for a once-per-equipment lookup. --- ## Update procedure on version bump When promoting a new version to current: 1. Drop the new versioned file into `guides//` (do not delete prior versions). 2. Edit `latest.html` to point at the new filename — change the `meta refresh` `url=` attribute and the `` link in the body. 3. Commit both the new versioned file and the updated `latest.html` together so git history shows the promotion. A future automation could derive `latest.html` from the highest-numbered versioned file in the folder. Don't build that until there are enough equipment items to make manual updates annoying. --- ## What NOT to do - Do not delete or rename old versioned files — they are referenced by later versions' errata blocks and by external systems that may have bookmarked specific versions. - Do not version `latest.html` itself — it is, by design, a moving alias. - Do not commit `latest.html` as a copy of the current version's full content. The redirect form is intentional: it makes promotion a one-line edit and prevents the guide content from drifting between two files. --- ## Revision history | Date | Change | Author | |---|---|---| | 2026-04-26 | Initial decision during repo provisioning | Sam + Claude Code |